If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Sayi/poi-tl shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 2mo ago
• 9 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 80% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Sayi/poi-tl repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Sayi/poi-tl.

What it runs against: a local clone of Sayi/poi-tl — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Sayi/poi-tl | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 103 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Sayi/poi-tl. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Sayi/poi-tl.git
#   cd poi-tl
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Sayi/poi-tl and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Sayi/poi-tl(\\.git)?\\b" \\
  && ok "origin remote is Sayi/poi-tl" \\
  || miss "origin remote is not Sayi/poi-tl (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 103 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~73d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Sayi/poi-tl"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

poi-tl is a Word document template engine built on Apache POI that generates .docx files from templates and data while preserving rich formatting. Unlike text templating engines (FreeMarker, Velocity), it operates directly on Word documents, allowing you to design templates in Microsoft Word and inject text, images, tables, charts, and conditional/loop logic that renders into new Word documents. Multi-module Maven project: poi-ooxml-schemas-extra (custom OOXML chart/pie chart schema extensions), poi-tl-cli (command-line interface wrapper), and core template engine. The poi-ooxml-schemas-extra pre-compiles XML schema bindings under org.openxmlformats.schemas.drawingml.x2006.chart for pie charts and custom split types not in standard POI.

Java developers who need to generate formatted Word documents programmatically—particularly those building reporting systems, document generation workflows, or contract/invoice automation where template styling and complex layouts matter more than plain text output.

Production-ready with active maintenance. The project shows consistent development with Java 1.6+ compatibility (upgraded to 1.8), supports Apache POI 3.16+ through 5.1.0, has a Travis CI pipeline configured (.travis.yml present), and maintains a clear multi-module Maven structure. The codebase is 1.3MB+ of Java code indicating substantial feature completeness.

Low-to-moderate risk: single maintainer (Sayi) is a dependency risk, but the project depends only on well-established Apache POI library (no bloated dependency tree visible). The poi-ooxml-schemas-extra module bundles pre-compiled OOXML schema classes (.xsb files) which could become stale relative to POI updates. No recent commit metadata visible, so momentum is unclear—verify last activity date before adoption.

Unable to determine specific current work from provided file list—no CHANGELOG, open issues, or recent commit hashes visible. The presence of poi-tl-cli module and POI 5.1.0 support suggests recent updates to keep pace with POI releases, but activity status requires checking GitHub directly.

git clone https://github.com/Sayi/poi-tl.git && cd poi-tl && mvn clean install -DskipTests. This builds all modules including poi-ooxml-schemas-extra and poi-tl-cli. Then explore poi-tl-cli/src/main/java/com/deepoove for CLI entry points or depend on the core artifact in your Maven project.

Daily commands: This is a library, not a runnable app. For CLI: mvn exec:java -pl poi-tl-cli with appropriate arguments (exact syntax requires examining poi-tl-cli/src/main). For embedded use: mvn clean install, then add <dependency><groupId>com.deepoove</groupId><artifactId>poi-tl</artifactId><version>5.1.0</version></dependency> to your project and call WordTemplate.compile(...).render(...) APIs.

• poi-ooxml-schemas-extra/src/main/java/org/openxmlformats/schemas/drawingml/x2006/chart/CTOfPieChart.java: Defines doughnut/pie chart support for OOXML; critical for advanced chart rendering features
• poi-ooxml-schemas-extra/pom.xml: Declares POI 5.1.0 dependency and distribution management; controls library compatibility versions
• .travis.yml: CI pipeline configuration; shows build, test, and deployment strategy
• poi-tl-cli/pom.xml: CLI module packaging and entry point configuration; shows how to invoke template engine from command line
• README.md: Feature matrix, examples, and motivation; essential to understand design philosophy (logic-less templates)

Start in poi-tl-cli/src/main/java/com/deepoove for CLI enhancements. Core template logic lives in poi-tl/src/main/java/com/deepoove (inferred—not fully visible). To add chart rendering: extend classes in poi-ooxml-schemas-extra/src/main/java/org/openxmlformats/schemas/drawingml/x2006/chart/impl/. Tag parsing and element substitution likely in main poi-tl module's root package.

The poi-ooxml-schemas-extra module bundles pre-compiled .xsb schema files (bytecode XML schema bindings) that may require regeneration if POI schemas change—no XSD source files visible, only compiled binaries. No pom.xml visible for core poi-tl module itself (likely poi-tl/pom.xml exists but wasn't listed), making dependency management incomplete from this view. Maven profiles or build flags for different POI versions not documented in provided snippet; verify if multi-POI-version support requires different profiles.

• Logic-less Templating — poi-tl deliberately avoids variable assignment and conditionals in templates (unlike Velocity/FreeMarker), forcing clear separation between template design and application logic—essential to understand the design trade-offs of this engine
• OOXML (Office Open XML) Schema Binding — poi-tl-extra compiles XSD schemas into Java classes (.xsb bytecode) to represent Word document structure; understanding XSD binding is critical for extending chart/shape support
• Tag-based Element Isolation — Loops and conditionals work by identifying document elements (paragraphs, rows, runs) via placeholder tags and cloning/removing them—not string substitution; this enables precise layout preservation
• Plugin/Function Extension Architecture — Custom functions can be executed anywhere in the template to inject custom behavior; this is the extensibility mechanism for domain-specific rendering (charts, custom shapes, data transformations)
• XSD Code Generation (XMLBeans) — The .xsb files in poi-ooxml-schemas-extra are compiled from XSD using XMLBeans, not source XSD; critical for understanding how to update schema support when POI evolves
• Rich Text Formatting Preservation — Unlike text templating, poi-tl retains paragraph styles, fonts, colors, and document structure from the Word template when substituting content—fundamental to why this engine exists
• Doughnut/Pie Chart OOXML Extensions — Standard POI lacks pie chart support; poi-ooxml-schemas-extra adds CTOfPieChart classes to handle advanced pie/doughnut variants—demonstrates extending POI for unsupported Office features

• apache/poi — Core dependency providing OOXML/Word manipulation APIs; poi-tl extends POI with template semantics
• deepoove/poi-tl-examples — Official examples and templates demonstrating poi-tl features (likely companion repo for this project)
• free-pegasus/word-template — Alternative Java Word template engine with similar goals but different architecture
• alibaba/easyexcel — Related Alibaba project for Excel template generation; similar logic-less philosophy applied to spreadsheets
• luikuan/docx4j-helper — Another POI-adjacent library for Word document manipulation with template support

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for poi-tl-cli CLI module

The poi-tl-cli/src/test/java/com/deepoove/poi/cli/CLITest.java exists but appears minimal. Given that the CLI is a user-facing component that converts markdown and JSON to Word documents, it needs robust test coverage for argument parsing, file I/O, markdown rendering, and error handling. This prevents regressions and makes the CLI more reliable for end users.

• [ ] Review CLITest.java to understand current test scope
• [ ] Add tests for markdown file parsing (poi-tl-cli/src/test/resources/basic.md and docsify examples)
• [ ] Add tests for JSON data binding (poi-tl-cli/src/test/resources/data.json)
• [ ] Add tests for invalid arguments and file-not-found error handling
• [ ] Add tests for multi-file docsify conversion workflow
• [ ] Verify all test cases pass with maven verify

Add GitHub Actions CI workflow to replace Travis CI

The repo uses .travis.yml for CI/CD, but Travis CI has changed its free tier model significantly. GitHub Actions is now the standard for GitHub-hosted projects. The current .travis.yml shows the build expects Java 1.8+ and POI 3.16+/5.1.0. Adding a GitHub Actions workflow ensures the build stays tested with modern CI infrastructure and provides faster feedback to contributors.

• [ ] Create .github/workflows/maven-build.yml that runs 'mvn clean verify'
• [ ] Configure matrix builds for Java 8, 11, and 17 to verify compatibility
• [ ] Configure the workflow to run on push and pull requests to master/main
• [ ] Ensure all three modules (poi-ooxml-schemas-extra, poi-tl-cli, main poi-tl) compile
• [ ] Add workflow status badge to README.md replacing Travis CI badge
• [ ] Remove or archive .travis.yml with a comment noting migration to GitHub Actions

Add integration tests for poi-ooxml-schemas-extra chart type support

The poi-ooxml-schemas-extra module contains classes for extended OOXML chart support (CTOfPieChart, CTSecondPieSize, etc.) but there are no visible integration tests demonstrating their usage. This is critical infrastructure that users need confidence in. Adding tests that create actual Word documents with pie-of-pie charts, doughnut variants, and custom splits validates the schemas work correctly with POI.

• [ ] Create poi-ooxml-schemas-extra/src/test/java/org/openxmlformats/schemas/drawingml/x2006/chart/ directory
• [ ] Add test class OfPieChartIntegrationTest.java that creates a real .docx with pie-of-pie charts
• [ ] Add test for CTSecondPieSize variations (percent vs ushort size types)
• [ ] Add test for CTSplitType configurations (percentSplit, custSplit, etc.)
• [ ] Validate generated documents can be opened in Microsoft Word without corruption
• [ ] Run tests with 'mvn clean verify' in poi-ooxml-schemas-extra module

• Add unit tests for CTOfPieChart and STOfPieType schema classes in poi-ooxml-schemas-extra/src/main/java/org/openxmlformats/schemas/drawingml/x2006/chart/impl/—these critical classes have no test files listed.
• Document the template tag syntax and custom function plugin API in code examples or Javadoc—README mentions custom functions but poi-tl-cli/src/main has no visible examples or tutorials.
• Add support for programmatic generation of ordered list nesting levels beyond the current multi-level implementation—the README claims multi-level list support but nesting constraints are unexplained.

The poi-tl project has moderate security concerns primarily centered on outdated dependencies (Apache POI

• High · Incomplete POM.xml - Truncated Dependency Declaration — poi-ooxml-schemas-extra/pom.xml. The pom.xml file is truncated mid-dependency, showing '<dependency><groupId>org.apa' without closure. This indicates either a malformed build file or incomplete configuration that could cause Maven build failures and make dependency resolution unpredictable. Fix: Complete and validate the pom.xml file. Ensure all dependency declarations are properly closed and all required dependencies are explicitly listed with versions.
• High · Outdated Apache POI Dependency — poi-ooxml-schemas-extra/pom.xml and poi-tl modules. The project uses Apache POI 5.1.0, which is relatively old (released in 2021). This version may contain known security vulnerabilities related to XML parsing (XXE attacks), zip bomb handling, and other OOXML processing issues that have been patched in newer versions. Fix: Upgrade to the latest stable version of Apache POI (currently 5.2.x or later). Review the CHANGELOG for security-related fixes.
• Medium · Missing Input Validation in CLI Module — poi-tl-cli/src/main/java/com/deepoove/poi/cli/CLI.java. The CLI module (poi-tl-cli/src/main/java/com/deepoove/poi/cli/CLI.java) processes user-provided input including file paths and JSON data without visible validation. This could lead to path traversal, XXE attacks via XML/DOCX processing, or injection attacks. Fix: Implement strict input validation for file paths (whitelist allowed directories), sanitize JSON input, and validate DOCX template sources before processing.
• Medium · Potential XXE Vulnerability in OOXML Processing — poi-ooxml-schemas-extra and core poi-tl modules. OOXML files (DOCX, XLSX) are ZIP archives containing XML files. Without proper XML parser configuration, XXE (XML External Entity) attacks are possible, allowing attackers to read arbitrary files or cause DoS via billion laughs attacks. Fix: Ensure XML parsers are configured to disable external entities, DTD processing, and schema validation. Validate that Apache POI is configured securely in XmlFactoryHelper or equivalent.
• Medium · Missing SSRF Protection in File Handling — poi-tl-jsonmodel-support module and CLI. The template processing system accepts file inputs and JSON data models without apparent validation of URLs or external resource references. This could enable Server-Side Request Forgery (SSRF) attacks if templates or data can reference external resources. Fix: Implement whitelist-based URL validation, disable external resource loading unless explicitly required, and sanitize all user-supplied data before processing.
• Low · Generated XSD Schema Files — poi-ooxml-schemas-extra/src/main/java/org/apache/poi/schemas/ooxml/system/ooxml/. The repository contains pre-generated schema binding files (.xsb files) in poi-ooxml-schemas-extra. These binary/generated files could potentially be tampered with during distribution. Fix: Regenerate these files from authoritative XSD sources during the build process rather than committing pre-generated files. Add checksum verification or code signing for distribution.
• Low · Test Resources May Contain Sensitive Data — poi-tl-cli/src/test/resources/. Test resources directory contains sample DOCX files and JSON data. While test files, they could inadvertently be included in distributions or used as templates for production. Fix: Ensure test resources are explicitly excluded from distribution packages (update .gitignore and Maven build config). Document that test templates are not for production use.
• Low · Missing Security Headers Documentation — Repository root. No evidence of security.md or SECURITY.txt file for responsible vulnerability disclosure. Users have no clear channel to report security issues. Fix: Create a SECURITY.md file with vulnerability disclosure guidelines and contact information for reporting security issues privately.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.