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/torakiki/pdfsam 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.

WAIT — Mixed signals — read the receipts

• Last commit 1w ago
• 4 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{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 torakiki/pdfsam repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/torakiki/pdfsam.

What it runs against: a local clone of torakiki/pdfsam — 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 torakiki/pdfsam | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of torakiki/pdfsam. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/torakiki/pdfsam.git
#   cd pdfsam
#
# 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 torakiki/pdfsam and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.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"

# 4. Critical files exist
test -f "pdfsam-basic/src/main/java/org/pdfsam/basic/App.java" \\
  && ok "pdfsam-basic/src/main/java/org/pdfsam/basic/App.java" \\
  || miss "missing critical file: pdfsam-basic/src/main/java/org/pdfsam/basic/App.java"
test -f "pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasic.java" \\
  && ok "pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasic.java" \\
  || miss "missing critical file: pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasic.java"
test -f "pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java" \\
  && ok "pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java" \\
  || miss "missing critical file: pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java"
test -f "pdfsam-basic/pom.xml" \\
  && ok "pdfsam-basic/pom.xml" \\
  || miss "missing critical file: pdfsam-basic/pom.xml"
test -f "pdfsam-basic/src/main/java/module-info.java" \\
  && ok "pdfsam-basic/src/main/java/module-info.java" \\
  || miss "missing critical file: pdfsam-basic/src/main/java/module-info.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 38 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~8d)"
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/torakiki/pdfsam"
  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).

PDFsam is a free, open-source desktop application built with JavaFX that splits, merges, mixes, rotates, and extracts pages from PDF files. It uses Apache PDFBox (via sambox), Sejda libraries, and RxJava for reactive PDF manipulation, providing a multi-platform GUI tool for batch PDF operations without command-line complexity. Maven multi-module monorepo: pdfsam-basic/ is the main application module containing UI logic and task definitions. Separated doc/third-party/ directories catalog all transitive dependencies and licenses. Modules inherit from pdfsam-parent pom.xml. UI built with JavaFX; PDF operations delegated to Sejda/sambox abstractions; event handling via EventStudio library.

End-users and professionals who need to manipulate PDF files visually (split/merge/rotate/extract) without paying for Adobe Acrobat or mastering command-line tools. Contributors are primarily Java/JavaFX developers maintaining a mature open-source document processing desktop app.

Production-ready and actively maintained. Version 6.0.2-SNAPSHOT in development with established CI/CD via GitHub Actions (build.yml, release.yml), comprehensive third-party license documentation, and AGPLv3 licensing since v3. Regular releases and a stable codebase indicate ongoing community use and support.

Low risk for stable features but moderate dependency surface: bundles sambox (PDFBox fork), Sejda libraries, Hibernate Validator, Jackson, and RxJava. Single primary maintainer (torakiki) visible in org structure. License change from GPLv2→AGPLv3 at v3 means older forks may have compliance gaps. Deployment as self-contained jlinked JDK (since v4) reduces runtime environment risk.

Active snapshot development at v6.0.2-SNAPSHOT. GitHub Actions workflows automate builds and releases. Dependabot enabled for automated dependency updates. No specific PR/issue data in file list, but release profile in pom.xml and build-helper-maven-plugin usage suggest active versioning and release management.

Clone the repo: git clone https://github.com/torakiki/pdfsam.git && cd pdfsam. Build with Maven: mvn clean install. The wiki link in README points to detailed build instructions at https://github.com/torakiki/pdfsam/wiki/Build-and-run. Requires JDK 11+ (bundled in releases for end-users).

Daily commands: From repository root: mvn clean install to build all modules, then execute the pdfsam-basic jar. For development, IDEs like IntelliJ or Eclipse can import the Maven project directly. Self-contained releases bundle a jlinked JDK, so end-users run the packaged executable without installing Java separately.

• pdfsam-basic/src/main/java/org/pdfsam/basic/App.java — Main application entry point and JavaFX initialization—every contributor must understand how the app boots and initializes the UI framework.
• pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasic.java — Core PDFsam Basic application class orchestrating module lifecycle and feature composition—essential to understand the top-level architecture.
• pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java — Spring/Sejda dependency injection configuration for the Basic edition—critical for adding new services or modules.
• pdfsam-basic/pom.xml — Maven POM defining all dependencies including Sejda (PDF processing), JavaFX, and validation frameworks—governs what libraries are available to use.
• pdfsam-basic/src/main/java/module-info.java — Java module descriptor declaring exported packages and required modules—required reading for understanding the modular architecture and cross-module communication.
• .github/workflows/build.yml — CI/CD pipeline defining build, test, and packaging steps—contributors must understand the automated quality gates and release process.
• LICENSE — GNU Affero General Public License v3—legal boundary for contributions and derivative use.

Add a New PDF Processing Module

1. Create a new module JAR (e.g., pdfsam-rotate) with a module-info.java exporting org.pdfsam.rotate.service (pdfsam-basic/src/main/java/module-info.java)
2. Implement a Spring @Configuration class in the new module that registers Sejda task processors (e.g., RotateTask) as beans (pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java)
3. Create a JavaFX @Controller class extending PDFsam UI base classes to expose a user-facing pane for the module (pdfsam-basic/src/main/java/org/pdfsam/basic/App.java)
4. Add the new module as a Maven dependency in pdfsam-basic/pom.xml using the parent's <dependencyManagement> version (pdfsam-basic/pom.xml)
5. Import the module in PdfsamBasicConfig so Spring discovers and wires its bean definitions at application startup (pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java)

Add Platform-Specific Distribution (e.g., MSI for Windows)

1. Create a new assembly descriptor at pdfsam-basic/src/assembly/msi-win.xml following the structure of portable-win.xml, specifying the .msi packaging format (pdfsam-basic/src/assembly/portable-win.xml)
2. Add a new <execution> block in pdfsam-basic/pom.xml under the maven-assembly-plugin binding the new descriptor to the package phase (pdfsam-basic/pom.xml)
3. Create MSI-specific resource files (e.g., WiX .wxs template) in pdfsam-basic/src/msi/resources/ (pdfsam-basic/src/assembly/resources/bin/pdfsam.bat)
4. Update .github/workflows/build.yml to run MSI build steps on the windows-latest runner and upload .msi artifacts (.github/workflows/build.yml)

Add a New Input Validation Rule

1. Create a custom Hibernate Validator @Constraint annotation (e.g., @ValidPdfPath) in a new validator package (pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java)
2. Implement the corresponding ConstraintValidator<ValidPdfPath, String> that checks file extension and existence using Java NIO (pdfsam-basic/pom.xml)
3. Register the validator as a Spring bean in PdfsamBasicConfig so Hibernate Validator discovers it via the injector (pdfsam-basic/src/main/java/org/pdfsam/basic/PdfsamBasicConfig.java)
4. Apply the annotation to input model fields (e.g., @ValidPdfPath private String inputFile) in module DTOs (pdfsam-basic/src/main/java/org/pdfsam/basic/App.java)

• JavaFX — Cross-platform desktop UI framework that is bundled in the JDK (jlinked since v4), eliminating separate JavaFX runtime requirements and enabling self-contained distribution.
• Sejda — Pure Java PDF manipulation library providing low-level PDF splitting, merging, rotation, and extraction without external binaries, enabling portable cross-platform operation.
• Spring/Sejda Injector — Lightweight dependency injection for wiring PDF processors, validators, and UI controllers, reducing boilerplate and enabling modular plugin-like architecture.
• Hibernate Validator — JSR-380 bean validation framework for declaratively enforcing input constraints (file existence, format, permissions) before Sejda execution.
• Maven — Multi-module build orchestration enabling separate module JARs (split, merge, rotate, etc.), cross-platform assembly packaging (ZIP, DEB, DMG), and reproducible builds.
• GitHub Actions — Native CI/CD enabling automated builds on Windows, macOS, and Linux with artifact signing, code-signing for notarization, and release publishing.

• Bundled JDK (jlinked) vs. separate Java runtime requirement

  • Why: Self-contained distribution eliminates end-user JDK installation complexity and version mismatches, but increases app size (~150–200 MB) and build complexity.
  • Consequence: Users can run the app immediately without prerequisites; build pipeline must cross-compile JDK for each platform (Windows, macOS Intel/ARM, Linux).

• Sejda (pure Java) vs. external PDF tools (Ghostscript, PyPDF2)

  • Why: Pure Java ensures portability and no system dependencies; external tools would be faster for very large PDFs but complicate distribution and platform compatibility.
  • Consequence: undefined

Release profile requires build-helper-maven-plugin for version parsing; activate with -Drelease flag. Self-contained packaging via jlink requires JDK module system configuration (likely in parent pom.xml, not shown). JavaFX requires platform-specific natives (bundled in releases but must be on module-path for development). AGPLv3 license imposes source-code-available requirement on deployments/forks—derivatives must release source. Third-party licenses must be included in distribution (pre-organized in doc/third-party/).

• Reactive Streams / RxJava — PDFsam uses RxJava Observables to handle asynchronous PDF task execution without blocking the UI—essential for processing large files without freezing the desktop app
• Dependency Injection (via Sejda-injector) — The codebase uses constructor-based DI to decouple PDF task implementations from UI controllers, enabling testability and plugin-like task registration
• PDF AcroForm and XMP Metadata — Third-party dependencies (adobe-xmp, sambox) handle PDF forms and metadata; understanding these is necessary when debugging merge/extract operations that preserve document properties
• JavaFX Scene Graph and FXML — UI is built with JavaFX's retained-mode graphics model and declarative FXML layout; CSS styling in pdfsam-basic/ customizes the scene tree
• Self-contained JDK distribution (jlink) — Since v4, pdfsam bundles a minimal jlinked JDK via Maven assembly plugin, eliminating end-user Java installation burden while reducing attack surface
• Multi-module Maven reactor build — pdfsam-basic inherits from pdfsam-parent pom.xml (not shown but referenced); understanding reactor order and version management is critical for contributions
• AGPLv3 copyleft and license compliance — License changed from GPLv2→AGPLv3 at v3; anyone modifying or deploying pdfsam must release derived source code, unlike permissive licenses—critical for contributors to understand

• apache/pdfbox — Original PDF manipulation library; pdfsam-basic uses sambox fork but inherits core architecture and features from PDFBox
• torakiki/sejda — Companion library providing high-level PDF task abstractions (split, merge, extract) that pdfsam-basic wraps in UI
• LibreOffice/core — Alternative open-source document processing suite; users may choose between pdfsam (PDF-focused) and LibreOffice (multi-format) depending on use case
• qpdf/qpdf — Command-line PDF manipulation tool solving same problem space; pdfsam users often compare against or migrate from qpdf for GUI alternative
• openpdf/OpenPDF — Fork of iText library providing PDF generation/manipulation; represents competing ecosystem for Java-based PDF work

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 automated integration tests for PDF operations in GitHub Actions workflow

The repo has build.yml and release.yml workflows but no visible integration tests that validate the core PDF operations (split, merge, mix, rotate, extract). Adding tests would catch regressions early, especially since the project manipulates binary PDF files which are error-prone. This is critical for a PDF manipulation tool.

• [ ] Create pdfsam-basic/src/test/resources/ with sample PDF files for testing
• [ ] Add integration test class in pdfsam-basic/src/test/java/ covering split, merge, rotate operations
• [ ] Update .github/workflows/build.yml to run integration tests as a separate step after compilation
• [ ] Verify tests work with the pom.xml configuration in pdfsam-basic/

Create CHANGELOG.md and automate version tracking between releases

The repo has version 6.0.2-SNAPSHOT in pom.xml and release.yml workflow, but no CHANGELOG.md file. Contributors and users cannot easily track what changed between versions. This is especially important given the AGPLv3 license requiring transparency. A structured changelog linked to git tags would help.

• [ ] Create CHANGELOG.md in repo root following Keep a Changelog format
• [ ] Add section for each version found in git tags (v3, v4, v5, v6.0.x)
• [ ] Update release.yml workflow to generate changelog entries from git commits before release
• [ ] Add CHANGELOG.md reference to README.md in the Documentation section

Add code coverage reporting and enforce minimum coverage thresholds in CI

The build.yml workflow runs tests but provides no visibility into code coverage. For a desktop application handling user files (PDFs), coverage metrics are valuable to identify untested critical paths. JaCoCo is a standard Maven plugin for Java projects.

• [ ] Add JaCoCo Maven plugin configuration to pdfsam-basic/pom.xml with coverage goals
• [ ] Configure exclusions in pom.xml for JavaFX UI classes that are hard to unit test
• [ ] Update .github/workflows/build.yml to run 'mvn verify' and upload coverage reports to Codecov or similar
• [ ] Set minimum coverage threshold (e.g., 70%) and fail build if unmet in CI step

• Add missing unit tests for Sejda task wrappers in pdfsam-basic/src/test/java/—many task implementations lack test coverage, making refactoring risky
• Expand UI translations by submitting missing locale strings to https://translations.launchpad.net/pdfsam/pdfsam-v3—many languages have partial translation coverage
• Document command-line argument behavior mentioned in wiki (Properties-and-arguments) by adding examples to README.md and creating arg parser tests—currently only wiki-documented, not in-code

PDFsam is an open-source PDF manipulation tool with a reasonable security baseline. The codebase appears well-structured with proper licensing and third-party documentation. However, several areas require improvement: (1) The provided pom.xml is incomplete, preventing full dependency analysis

• High · Incomplete POM File Analysis — pdfsam-basic/pom.xml. The provided pom.xml file is truncated and incomplete, preventing full dependency analysis. The Maven plugin configuration for 'org.apache.maven.plugi' is cut off, making it impossible to verify all build-time security configurations and plugin versions. Fix: Provide the complete pom.xml file for comprehensive analysis. Verify all Maven plugins are using the latest secure versions and that no vulnerable plugins are included.
• High · Potential Dependency Vulnerabilities in PDF Processing Libraries — pdfsam-basic/doc/third-party/ and dependencies. The application uses multiple PDF processing and cryptographic libraries (Bouncy Castle, FontBox, SamBox, Sejda) that require regular security updates. No explicit dependency version constraints or vulnerability scanning tools (e.g., OWASP Dependency-Check) were found in the visible build configuration. Fix: Implement automated dependency vulnerability scanning in CI/CD pipeline using tools like OWASP Dependency-Check, Snyk, or similar. Regularly audit and update dependencies to patch known CVEs. Pin dependency versions explicitly in pom.xml.
• Medium · Missing Security Headers and Configuration Documentation — pdfsam-basic/src/main/. No explicit security configuration files (security.xml, application.yml with security settings) are visible in the provided structure. The application handles PDF files which may contain sensitive data, but no apparent input validation or output encoding mechanisms are documented. Fix: Implement comprehensive input validation for PDF file uploads and processing. Document security configurations including file size limits, supported PDF versions, and data handling procedures. Implement proper error handling without exposing system details.
• Medium · Release Build Artifacts and Signing Concerns — pdfsam-basic/src/detached-sign.sh, pdfsam-basic/src/dmg/notarize_dmg.sh. The presence of 'src/detached-sign.sh' and 'src/dmg/notarize_dmg.sh' suggests release artifact signing processes. However, no visible security practices for key management, code signing verification, or artifact integrity validation are documented. Fix: Document and implement secure key management practices for code signing. Ensure all release artifacts are cryptographically signed and their integrity can be verified. Use secure key storage solutions and implement rotation policies.
• Medium · No Visible Security Testing Integration — .github/workflows/. The .github/workflows directory shows build and release workflows, but no evidence of security scanning (SAST, DAST, or dependency checking) is visible in the CI/CD pipeline configuration. Fix: Integrate security scanning tools into GitHub Actions workflows. Add SAST scanning (e.g., SonarQube, Checkmarx), DAST testing, and dependency vulnerability scanning. Include security checks as blocking gates in the CI/CD pipeline.
• Low · Third-Party License Documentation — pdfsam-basic/doc/third-party/. While comprehensive third-party license documentation exists, the lack of a Software Bill of Materials (SBOM) in machine-readable format (CycloneDX or SPDX) may complicate security audits and vulnerability tracking. Fix: Generate and maintain an SBOM in CycloneDX or SPDX format. Automate SBOM generation as part of the build process. Make SBOM available for security audits and vulnerability correlation.
• Low · Shell Script Security in Build Process — pdfsam-basic/src/assembly/resources/bin/ and pdfsam-basic/src/dmg/. Build scripts (pdfsam.sh, pdfsam.bat, detached-sign.sh, notarize_dmg.sh) are visible but their security practices cannot be fully verified without content review. Shell scripts may contain hardcoded paths or credentials. Fix: Review and harden all shell scripts. Avoid hardcoding credentials or sensitive paths. Use environment variables for configuration. Implement proper error handling and input validation in scripts. Consider signing scripts for integrity verification.

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.