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/wmjordan/PDFPatcher 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 — Missing license — unclear to depend on

• Last commit 2mo ago
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

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

What it runs against: a local clone of wmjordan/PDFPatcher — 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 wmjordan/PDFPatcher | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 104 days ago | Catches sudden abandonment since generation |

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

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

# 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 "App/AppContext.cs" \\
  && ok "App/AppContext.cs" \\
  || miss "missing critical file: App/AppContext.cs"
test -f "App/Commands.cs" \\
  && ok "App/Commands.cs" \\
  || miss "missing critical file: App/Commands.cs"
test -f "App/Common/FileHelper.cs" \\
  && ok "App/Common/FileHelper.cs" \\
  || miss "missing critical file: App/Common/FileHelper.cs"
test -f "App/Functions/BookmarkControl.cs" \\
  && ok "App/Functions/BookmarkControl.cs" \\
  || miss "missing critical file: App/Functions/BookmarkControl.cs"
test -f "App/Functions/DocumentInspectorControl.cs" \\
  && ok "App/Functions/DocumentInspectorControl.cs" \\
  || miss "missing critical file: App/Functions/DocumentInspectorControl.cs"

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

PDFPatcher is a comprehensive Windows desktop PDF toolkit built in C# that enables editing bookmarks, cropping/rotating pages, removing DRM restrictions, extracting/merging documents, analyzing document structure, and converting pages to images. It wraps two core open-source engines: iText (for PDF parsing, generation, and modification) and MuPDF (for rendering PDFs to bitmaps via P/Invoke), providing a feature-complete PDF manipulation suite with a native WinForms UI. Single-tier monolithic architecture: App/ folder contains the entire WinForms application. App/Common/ houses cross-cutting utilities (FileHelper, FontUtility, ImageBox rendering). App/Functions/ organizes UI modules by feature (AboutControl, AutoBookmark/, AppOptionForm). Core PDF engine logic is abstracted behind iText/MuPDF P/Invoke wrappers; configuration serialization happens via ConfigurationSerialization.cs and Configuration.Designer.cs (WinForms code generation). No separate business logic layer.

Chinese-speaking PDF power users (docs in Chinese), document managers, archivists, and publishers who need batch PDF editing with granular bookmark control, font replacement, OCR integration with Microsoft Office, and file merging while preserving metadata—without subscription fees or cloud dependencies.

Production-ready and actively maintained. The codebase is substantial (~1.56M LOC C#, ~622K LOC C library code) with a long feature set implying years of development. The license model (AGPL + 'good conscience license') and detailed Chinese documentation suggest established user base. Commit recency and issue triage are not visible in provided data, but the breadth of UI polish (AppOptionForm, ImageBoxEx, AutoBookmark subsystem) indicates maturity.

Single-maintainer risk (wmjordan as sole visible maintainer). Tight coupling to Windows/.NET Framework (WinForms, PInvoke to Windows APIs via PInvokeHelper.cs) makes cross-platform adoption unlikely. Dependency on MuPDF C bindings (separate repo: wmjordan/SharpMuPDF) adds indirect maintenance burden. No visible unit test directory in file listing, raising regression risk for complex PDF manipulation logic.

Not visible from provided data (no recent commits, PRs, or GitHub Actions workflows shown). The file structure suggests active subsystems: AutoBookmark feature (with FontFilterForm, PageRangeConditionEditor) is complex and likely under refinement, and ImageBox drag-handle controls hint at UI interaction improvements.

git clone https://github.com/wmjordan/PDFPatcher.git
cd PDFPatcher
# Open in Visual Studio 2019+ or Visual Studio Code with C# DevKit
# The project is a WinForms app targeting .NET Framework; open App/App.csproj
# Build via: dotnet build App/App.csproj
# Run: dotnet run --project App/App.csproj (or launch via Visual Studio)```

**Daily commands:**
Exact dev startup unclear from provided data. Likely: `dotnet build App/App.csproj && dotnet run --project App/App.csproj`. For release build, check .github workflows (not shown in data). The manifest file (app.manifest) suggests admin elevation may be required for some features.

• App/AppContext.cs — Application context and initialization entry point; all contributors must understand the lifecycle and state management of the PDF processing engine.
• App/Commands.cs — Command registry and dispatcher for all PDF operations; core abstraction that routes user actions to handlers.
• App/Common/FileHelper.cs — File I/O and path utilities used throughout the codebase for PDF document access and validation.
• App/Functions/BookmarkControl.cs — Central UI control for PDF bookmark editing; the most complex user-facing feature in the application.
• App/Functions/DocumentInspectorControl.cs — PDF structure inspection and manipulation interface; critical for document parsing and analysis workflows.
• App/Configuration.cs — Application-wide configuration and settings serialization; all feature flags and user preferences routed through here.
• App/Constants.cs — Application constants and magic numbers; essential reference for PDF format compliance and UI behavior.

Add a new PDF document property editor

1. Create a new form class inheriting from System.Windows.Forms.Form in App/Functions/DocumentOption/ (App/Functions/DocumentOption/NewPropertyEditor.Designer.cs)
2. Implement property binding logic to read/write PDF document metadata (App/Functions/DocumentOption/NewPropertyEditor.cs)
3. Register the new editor in the DocumentOption section via Commands registry (App/Commands.cs)
4. Add configuration persistence in Configuration.cs for user-saved values (App/Configuration.cs)

Add a new AutoBookmark condition type

1. Create condition editor form in App/Functions/AutoBookmark/ (App/Functions/AutoBookmark/NewConditionEditor.cs)
2. Implement the matching logic that evaluates PDF content against the condition (App/Functions/AutoBookmark/NewConditionEditor.cs)
3. Wire the new condition into AutoBookmarkControl.cs condition list (App/Functions/AutoBookmarkControl.cs)
4. Serialize/deserialize condition settings in Configuration.cs (App/Configuration.cs)

Add a new document extraction or transformation tool

1. Create a new Control-derived UI class in App/Functions/ for the tool interface (App/Functions/NewToolControl.Designer.cs)
2. Implement tool logic and PDF processing in the code-behind (App/Functions/NewToolControl.cs)
3. Register the command handler in Commands.cs with appropriate menu/toolbar placement (App/Commands.cs)
4. Add configuration options to AppOptionForm.cs if the tool has user-adjustable settings (App/Functions/AppOptionForm.cs)

Add document structure inspection capability

1. Create a new viewer form in App/Functions/DocumentInspector/ (App/Functions/DocumentInspector/NewStructureViewerForm.cs)
2. Implement PDF object parsing and tree node construction logic (App/Functions/DocumentInspector/NewStructureViewerForm.cs)
3. Integrate the viewer into DocumentInspectorControl.cs tab interface (App/Functions/DocumentInspectorControl.cs)
4. Export/serialization support in the viewer if needed for analysis (App/Functions/DocumentInspector/NewStructureViewerForm.cs)

• WinForms (System.Windows.Forms) — Desktop UI framework for cross-platform Windows PDF editing with rich controls (TreeView, PropertyGrid, custom ImageBox); native interop with Win32 for file dialogs and system fonts.
• C# .NET Framework — Type-safe language with strong ecosystem support for PDF processing; COM interop capability for Office image recognition; cross-version compatibility for Windows systems.
• AGPL-licensed PDF library (implied by README) — Core PDF manipulation (bookmarks, metadata, page operations, compression); structured document access for inspection and modification.
• XML serialization (XmlHelper, Configuration.cs) — Configuration persistence and document export format; enables batch processing and human-readable settings management.
• Office COM interop (implied by OCR features in README) — Access to Microsoft Office image recognition engine for OCR and text extraction from scanned PDFs.

• WinForms instead of WPF

  • Why: Broader Windows version support, simpler custom control integration (ImageBox), lower memory footprint for batch operations.
  • Consequence: Limited modern UI paradigms; requires manual threading for long-running PDF operations to avoid UI freezing.

• Single-threaded command dispatch (Commands.cs registry)

  • Why: Simplifies state management and UI updates; deterministic operation ordering for complex bookmark edits.
  • Consequence: Long-running operations (large PDF parsing, OCR) block UI; must implement explicit async wrappers or background workers.

• In-memory document representation

  • Why: Fast bookmark editing, rapid tree navigation, instant property updates without re-parsing.
  • Consequence: Large PDFs (>500MB) consume significant RAM; no streaming support for ultra-large documents.

• Conditional rule engine for AutoBookmark (text, font, position, size conditions)

  • Why: Flexible, user-configurable extraction without hard-coded heuristics; supports diverse document structures.
  • Consequence: Rule composition complexity grows; users must understand condition precedence and interaction.

• Real-time collaborative PDF editing
• Cloud synchronization or online storage integration
• Embedded PDF rendering (uses OS/external viewers)

WinForms code generation: Configuration.Designer.cs and AppOptionForm.Designer.cs are auto-generated by Visual Studio; hand-editing will be overwritten on next designer save—modify only the .cs partial classes. P/Invoke safety: PInvokeHelper.cs bridges to unmanaged MuPDF; memory leaks or marshaling errors can crash the app silently—test thoroughly after changes. Chinese UI strings: Much UI text is hardcoded in Chinese (visible in .resx files); internationalization is minimal. Manifest elevation: app.manifest likely requires Windows admin rights for some PDF restriction-removal features; test with UAC on. .NET Framework lock-in: No modern .NET 6+ support visible; migration would require substantial refactoring. No async/await: WinForms code appears synchronous; long PDF operations may freeze UI.

• PDF bookmark tree structure — Bookmarks are hierarchical outlines in PDFs; understanding their tree representation is essential for the AutoBookmark feature and batch editing in App/Functions/AutoBookmark/
• P/Invoke and marshaling (C#/.NET to C interop) — PDFPatcher calls MuPDF (C library) from C# via P/Invoke; understanding marshaling rules prevents crashes in PInvokeHelper.cs when passing pointers and structs across managed/unmanaged boundaries
• PDF embedded fonts and subsetting — The font replacement and embedding features (visible in Common/FontHelper.cs, Common/FontUtility.cs) rely on TrueType font subset extraction; critical for making PDFs readable on devices without full font libraries
• PDF content streams and operators — Page rotation, cropping, and image extraction manipulate PDF content streams (sequences of drawing commands); iText abstraction hides this but understanding it helps debug rendering issues
• DRM/PDF permissions and encryption — Core feature is removing copy/print restrictions; understanding PDF encryption dictionary and user/owner password hash algorithms explains how the 'restriction removal' works
• WinForms data binding and designer code generation — Configuration.Designer.cs and form files are auto-generated by Visual Studio; understanding the split between designer-controlled and hand-written code is vital to avoid losing changes
• OCR integration with Microsoft Office imaging — The document mentions calling 'Microsoft Office's image recognition engine' for OCR; this likely uses WIA (Windows Image Acquisition) or MODI (Microsoft Office Document Imaging) COM interfaces

• wmjordan/SharpMuPDF — Official companion C# binding layer for MuPDF; required dependency for PDFPatcher's rendering pipeline
• itext/itext7-dotnet — Core iText library for PDF manipulation in .NET; PDFPatcher's primary engine for bookmark, page, and metadata editing
• ArtifexSoftware/mupdf — Original MuPDF C library source; upstream for the rendering engine PDFPatcher uses via P/Invoke
• pdfrw/pdfrw — Pure-Python PDF library; alternative approach to PDF manipulation (different ecosystem, but solves same problem differently for comparison)
• pikepdf/pikepdf — Modern Python PDF tool wrapping C++ qpdf; demonstrates state-of-art PDF manipulation outside .NET, useful for understanding alternative architectures

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 PDF processing utilities in Common folder

The App/Common folder contains many utility classes (StringHelper.cs, ValueHelper.cs, FileHelper.cs, FontHelper.cs, XmlHelper.cs) that are core to PDF manipulation but lack visible test coverage. These utilities handle critical operations like string manipulation, font processing, and file operations. Adding unit tests would improve code reliability and make refactoring safer for future contributors.

• [ ] Create Tests/Common/StringHelperTests.cs for string manipulation methods
• [ ] Create Tests/Common/ValueHelperTests.cs for type conversion and validation
• [ ] Create Tests/Common/FileHelperTests.cs for file path and I/O operations
• [ ] Create Tests/Common/FontHelperTests.cs for font detection and processing
• [ ] Create Tests/Common/XmlHelperTests.cs for XML parsing and serialization
• [ ] Ensure tests cover edge cases relevant to PDF processing (special characters, encoding, malformed data)

Add GitHub Actions CI workflow for building and testing on multiple .NET versions

The repo contains a complete C#/.NET WinForms application but lacks a visible CI pipeline (.github/workflows is present but empty). This makes it difficult for contributors to verify their changes work across different environments. A CI workflow would catch build failures, test regressions, and version compatibility issues before merge.

• [ ] Create .github/workflows/build-and-test.yml with steps to build on .NET Framework 4.x and .NET 5+
• [ ] Configure the workflow to run MSBuild on the solution file
• [ ] Add test execution step for any test projects created
• [ ] Configure the workflow to run on pull requests and pushes to main branches
• [ ] Add a status badge to README.md referencing the workflow

Refactor AutoBookmark folder into a separate module with abstracted interfaces

The App/Functions/AutoBookmark folder contains 7 specialized condition editors (TextConditionEditor, FontNameConditionEditor, PageRangeConditionEditor, etc.) that share similar patterns but lack a common interface. This creates code duplication and makes it hard to extend with new condition types. Extracting a base interface IBookmarkConditionEditor and shared logic would improve maintainability and enable easier feature additions.

• [ ] Create App/Functions/AutoBookmark/IBookmarkConditionEditor.cs with common interface for all editors
• [ ] Create App/Functions/AutoBookmark/BookmarkConditionEditorBase.cs for shared logic (validation, serialization)
• [ ] Refactor TextConditionEditor.cs, FontNameConditionEditor.cs, PageRangeConditionEditor.cs, TextPositionConditionEditor.cs, and TextSizeConditionEditor.cs to inherit from the base class
• [ ] Update AutoBookmarkControl.cs to use the interface for polymorphic handling of editors
• [ ] Add inline documentation explaining the condition editor pattern for future contributors

• Add unit tests for App/Common/FileHelper.cs and App/Common/StringHelper.cs utility functions—currently untested and critical for path/string manipulation in batch operations.
• Document the iText vs. MuPDF responsibility boundary in code comments: which operations use which library and why? Add examples in App/Functions/ showing common patterns (e.g., bookmark modification uses iText, page rendering uses MuPDF).
• Implement async/await wrappers for long-running PDF operations in Commands.cs (e.g., large file merges, image extraction) to prevent UI freezing—start with a single command and generalize.

• Medium · Potential Insecure Deserialization in Configuration — App/ConfigurationSerialization.cs. The codebase contains ConfigurationSerialization.cs which suggests serialization/deserialization of configuration data. Without examining the actual implementation, there's a risk of insecure deserialization vulnerabilities if untrusted configuration files are processed using .NET binary formatters or similar unsafe methods. Fix: Use safe serialization formats (JSON, XML) with strict schema validation. Avoid BinaryFormatter and unsafe deserialization. Implement input validation for all configuration files.
• Medium · Potential Path Traversal in File Operations — App/Common/FileHelper.cs, App/Common/FilePath.cs. The codebase includes FileHelper.cs and FilePath.cs which handle file operations. PDF processing tools are commonly targets for path traversal attacks when handling user-provided file paths or extracting embedded resources. Fix: Validate and sanitize all file paths. Use Path.GetFullPath() and ensure paths remain within expected directories. Implement whitelist-based path validation. Avoid directly concatenating user input with file paths.
• Medium · Potential XML External Entity (XXE) Injection — App/Common/XmlHelper.cs. The codebase contains XmlHelper.cs and XML processing capabilities. XXE vulnerabilities can occur when parsing untrusted XML documents (e.g., from PDF metadata or imported configurations) without proper DTD restrictions. Fix: Disable XML external entity processing. Set XmlReaderSettings with DTD processing disabled: ProhibitDtd = true and XmlResolver = null. Use safe XML parsing methods.
• Medium · PInvoke Security Risks — App/Common/PInvokeHelper.cs. The presence of PInvokeHelper.cs indicates direct P/Invoke calls to native Windows APIs. Improper usage of P/Invoke can lead to buffer overflows, privilege escalation, or other low-level security issues. Fix: Audit all P/Invoke declarations for proper marshaling. Use safe parameter types and validate all native API call results. Avoid passing untrusted data to native APIs. Consider using safer managed alternatives where possible.
• Low · Potential Information Disclosure through PDF Analysis — App/Functions/DocumentInspector/DocumentInspectorControl.cs. Document Inspector functionality (DocumentInspectorControl.cs) exposes internal PDF structure and metadata. This could inadvertently expose sensitive information embedded in PDFs (author metadata, creation dates, embedded scripts). Fix: Document security implications for users. Add warnings when displaying sensitive PDF metadata. Provide sanitization options for metadata removal. Educate users about PDF structure vulnerabilities.
• Low · Potential Regex Denial of Service (ReDoS) — App/Functions/AutoBookmark/TextConditionEditor.cs, bookmark search/replace functionality. The codebase mentions regular expression usage in bookmark search/replace functionality (TextConditionEditor.cs indicates XPath and regex matching). Complex regex patterns without input limits could cause ReDoS attacks. Fix: Implement regex pattern validation with timeout mechanisms. Use regex libraries with built-in ReDoS protection. Add length limits to user-provided patterns. Consider limiting regex complexity.
• Low · Missing Dependency File Analysis — Dependencies/Package files (not provided). The dependencies/package file content was not provided, preventing assessment of known CVEs in third-party libraries used by the application. Fix: Maintain an up-to-date dependency manifest (packages.config, .csproj, or similar). Regularly scan dependencies using tools like OWASP Dependency-Check or NuGet vulnerability scanner. Keep all dependencies updated to latest patched versions.
• Low · Potential Untrusted PDF Processing — Core PDF processing logic (not fully visible in file structure). As a PDF manipulation tool, the application processes untrusted PDF files from users. Malformed or malicious PDFs could trigger vulnerabilities in the underlying PDF processing library (likely iTextSharp or similar). Fix: Implement file type validation beyond extension checks. Use sandboxed processing for untrusted PDFs. Keep PDF libraries updated. Implement resource limits (memory, processing time) for PDF operations. Add error handling for malformed PDFs.

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.