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/cyanfish/naps2 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 — Slowing — last commit 7mo ago

• Last commit 7mo ago
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms

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

What it runs against: a local clone of cyanfish/naps2 — 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 cyanfish/naps2 | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 233 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "NAPS2.App.Console/Program.cs" \\
  && ok "NAPS2.App.Console/Program.cs" \\
  || miss "missing critical file: NAPS2.App.Console/Program.cs"
test -f "NAPS2.App.WinForms/Program.cs" \\
  && ok "NAPS2.App.WinForms/Program.cs" \\
  || miss "missing critical file: NAPS2.App.WinForms/Program.cs"
test -f "NAPS2.Escl/Client/EsclClient.cs" \\
  && ok "NAPS2.Escl/Client/EsclClient.cs" \\
  || miss "missing critical file: NAPS2.Escl/Client/EsclClient.cs"
test -f "NAPS2.Escl.Server/EsclServer.cs" \\
  && ok "NAPS2.Escl.Server/EsclServer.cs" \\
  || miss "missing critical file: NAPS2.Escl.Server/EsclServer.cs"
test -f "NAPS2.App.Worker/Program.cs" \\
  && ok "NAPS2.App.Worker/Program.cs" \\
  || miss "missing critical file: NAPS2.App.Worker/Program.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 233 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~203d)"
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/cyanfish/naps2"
  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).

NAPS2 is a cross-platform document scanning application (Windows/macOS/Linux) that acquires images from WIA, TWAIN, SANE, and ESCL scanners, then organizes and exports them to PDF, TIFF, JPEG, or PNG with optional OCR via Tesseract. The core problem it solves is providing a simple, unified scanning interface across multiple operating systems and scanner protocols without vendor lock-in. Monorepo with platform-specific app projects: NAPS2.App.WinForms (Windows), NAPS2.App.Gtk (Linux), NAPS2.App.Mac (macOS), NAPS2.App.Console (CLI), plus NAPS2.App.PortableLauncher for distribution. Core scanning logic is abstracted into NAPS2.Sdk (published as NuGet package). Testing is centralized in NAPS2.App.Tests with Appium-based UI automation (ImportAndSaveTests.cs, ScanAndSaveTests.cs) and per-target implementations (LinuxAppTestTarget.cs, MacAppTestTarget.cs, WindowsAppTestTarget.cs).

End users who need to digitize paper documents across Windows, macOS, or Linux without complexity; also developers integrating scanning into their own applications via the NAPS2.Sdk NuGet package (distributed as GNU LGPL library).

Production-ready and actively maintained. The codebase shows maturity with comprehensive test coverage (NAPS2.App.Tests folder with Appium UI automation, console/GUI/server/worker tests), GitHub Actions CI/CD pipeline (.github/workflows/dotnet.yml), and a CHANGELOG documenting releases. Last evidence of activity is the structured test suite and multi-platform build targets.

Low to moderate risk. Single maintainer (cyanfish) visible in repo structure is a concentration point, but the project has clear licensing (GPL 2.0 + LGPL variants for libraries), established download/docs infrastructure at naps2.com, and active translation community. The complexity of supporting four scanner protocols (WIA/TWAIN/SANE/ESCL) across three OSes means platform-specific bugs are possible; however, the test matrix (Windows/Linux/Mac targets) mitigates this.

Active development visible in structured test suite additions (Appium tests for UI automation, language selection tests) and platform-specific improvements. The presence of LanguageSelectionTests.cs and translation infrastructure (translate.naps2.com link) suggests ongoing i18n work. Recent focus appears to be on test coverage expansion and cross-platform reliability.

.NET-based project; requires .NET SDK. Clone and build: git clone https://github.com/cyanfish/naps2.git && cd naps2 && dotnet build. Run console app: dotnet run --project NAPS2.App.Console. For UI, run platform-specific project (e.g., dotnet run --project NAPS2.App.WinForms on Windows). Check wiki at github.com/cyanfish/naps2/wiki for detailed build environment setup.

Daily commands: Console: dotnet run --project NAPS2.App.Console -- [options]. WinForms (Windows): dotnet run --project NAPS2.App.WinForms. GTK (Linux): dotnet run --project NAPS2.App.Gtk. macOS: dotnet run --project NAPS2.App.Mac. Tests: dotnet test NAPS2.App.Tests (requires test data and platform-specific runner setup per Targets/).

• NAPS2.App.Console/Program.cs — Entry point for CLI application; demonstrates how NAPS2 initialization and command-line argument parsing work across all app variants.
• NAPS2.App.WinForms/Program.cs — Primary GUI entry point for Windows; sets up the WinForms UI framework and initializes platform-specific scanning capabilities.
• NAPS2.Escl/Client/EsclClient.cs — Core ESCL (eSCL) scanner protocol client implementation; critical for network scanner discovery and communication.
• NAPS2.Escl.Server/EsclServer.cs — Server-side ESCL implementation that exposes local scanners to network clients; foundational for cross-platform scanner sharing.
• NAPS2.App.Worker/Program.cs — Background worker process for scanning operations; handles platform-specific scanner access (WIA/TWAIN/SANE) in isolation from UI.
• NAPS2.Escl/EsclCapabilities.cs — Data model for scanner capabilities negotiation; defines the contract between client and server for feature discovery.
• NAPS2.App.Tests/NAPS2.App.Tests.csproj — Test infrastructure project; shows testing patterns and verification strategy across platform-specific implementations.

Add Support for a New Network Scanner via ESCL

1. Define scanner capabilities model in NAPS2.Escl/EsclCapabilities.cs with new resolution or color mode enums (NAPS2.Escl/EsclCapabilities.cs)
2. Update NAPS2.Escl/Client/CapabilitiesParser.cs to parse XML response from scanner's GET /eSCL/ScannerCapabilities endpoint (NAPS2.Escl/Client/CapabilitiesParser.cs)
3. Extend NAPS2.Escl/Client/EsclClient.cs to handle scanner-specific quirks in API behavior (NAPS2.Escl/Client/EsclClient.cs)
4. Add integration test in NAPS2.Escl.Tests/ClientServerTests.cs to verify capability parsing and scan workflow (NAPS2.Escl.Tests/ClientServerTests.cs)

Add a New Output Format (PDF, TIFF, JPEG, PNG)

1. Create new format exporter class following existing export service patterns (NAPS2.App.Console/Program.cs)
2. Register exporter in application initialization code (NAPS2.App.WinForms/Program.cs)
3. Add CLI argument handling for new format in console app (NAPS2.App.Console/Program.cs)
4. Write format-specific tests in NAPS2.App.Tests/ConsoleAppTests.cs (NAPS2.App.Tests/ConsoleAppTests.cs)

Add a New Platform-Specific Scanner Backend (WIA/TWAIN/SANE alternative)

1. Create scanner backend abstraction in core library (not shown in file list, but would be referenced by NAPS2.App.Worker) (NAPS2.App.Worker/Program.cs)
2. Implement backend for Windows in NAPS2.App.WinForms via worker process (NAPS2.App.WinForms/Program.cs)
3. Implement backend for Linux/GTK via worker process (NAPS2.App.Gtk/Program.cs)
4. Add platform-specific test target in NAPS2.App.Tests/Targets/ directory (NAPS2.App.Tests/Targets/WindowsAppTestTarget.cs)

Add mDNS Advertisement for Scanner Sharing

1. Configure mDNS service name and port in NAPS2.Escl.Server/MdnsAdvertiser.cs (NAPS2.Escl.Server/MdnsAdvertiser.cs)
2. Register ESCL server instance in EsclServer initialization (NAPS2.Escl.Server/EsclServer.cs)
3. Add integration test for mDNS discovery in NAPS2.Escl.Tests/AdvertiseTests.cs (NAPS2.Escl.Tests/AdvertiseTests.cs)

• C# / .NET — Cross-platform runtime enabling single codebase for Windows, macOS, Linux with platform-specific UI frameworks.
• WinForms (Windows), GTK+ (Linux), Cocoa (macOS) — Native UI frameworks per platform for optimal user experience and platform integration.
• WIA, TWAIN, SANE — Ubiquitous scanner driver standards across Windows, macOS, and Linux hardware ecosystems.
• eSCL (eScan Certified Linux) Protocol — Vendor-neutral HTTP-based scanner protocol enabling network scanner discovery and control without proprietary drivers.
• mDNS (Bonjour) — Zero-configuration service discovery for finding ESCL scanners on local network without manual IP configuration.
• ASP.NET Core — Lightweight embedded web server

Platform-specific scanner protocol availability: WIA only on Windows, TWAIN requires external library on macOS, SANE/ESCL require system libraries on Linux (libsane package). Test suite requires Appium + platform-specific WebDriver setup (see Appium/AppiumTests.cs) and test data fixtures. PortableLauncher (.NET Framework) has separate build requirements from SDK/.NET Core projects. GTK version constraint (3.20+) and glibc 2.27+ on Linux are strict; mismatches cause silent failures. OCR depends on Tesseract binary in PATH; missing it degrades functionality gracefully but isn't obvious in logs.

• TWAIN Protocol — NAPS2 uses TWAIN to communicate with scanner hardware on Windows/macOS; understanding its state machine and capabilities negotiation is critical for scanner integration bugs.
• SANE (Scanner Access Now Easy) — Linux scanning backend that NAPS2 wraps via native bindings; SANE daemon management and device enumeration are unique to Linux support.
• ESCL (eSCL) — HTTP-based scanning protocol NAPS2 uses for network scanners; understanding REST semantics and device discovery over mDNS is needed for network scanner support.
• WIA (Windows Image Acquisition) — Windows COM-based scanner API that NAPS2 uses exclusively on Windows; COM marshaling and device enumeration via WIA properties are Windows-specific complexities.
• Platform-Specific UI Abstraction — NAPS2 maintains separate UI codebases (WinForms/GTK#/native macOS) instead of unified toolkit; understanding this multi-target strategy is essential for contributing UI features.
• Appium Test Automation — NAPS2.App.Tests uses Appium for cross-platform UI automation; understanding Appium's element inspection and interaction model is needed to write or debug UI tests.
• NuGet SDK Distribution — NAPS2.Sdk is published as a NuGet package with LGPL licensing; understanding NuGet versioning, strong naming, and license metadata is critical for SDK consumers and maintainers.

• tessnet2/tessnet2 — C# wrapper for Tesseract OCR; NAPS2 integrates this for document text extraction.
• jsprintsetup/jsprintsetup — Similar cross-platform document handling via scripting; alternative approach to NAPS2's native UI strategy.
• tesseract-ocr/tesseract — Upstream OCR engine that NAPS2 delegates to for character recognition; understanding Tesseract config is essential for OCR troubleshooting.
• sane-project/sane-backends — SANE backend library that NAPS2 uses for Linux scanner access; protocol details matter for Linux debugging.
• cyanfish/naps2.sdk-samples — Official SDK usage examples; reference implementation for developers building on top of NAPS2.Sdk.

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 platform-specific integration tests for ESCL server scanning

The repo has NAPS2.Escl.Server with EsclServer.cs, EsclApiController.cs, and test infrastructure in NAPS2.App.Tests/Appium, but there are no dedicated integration tests for the ESCL server functionality. ESCL (eSCL) is a critical protocol for network scanning. Adding comprehensive tests for server initialization, certificate handling (CertificateHelper.cs), mDNS advertising (MdnsAdvertiser.cs), and job management (JobInfo.cs, FakeEsclScanJob.cs) would ensure reliability across Windows/Mac/Linux platforms.

• [ ] Create NAPS2.Escl.Server.Tests project alongside existing test structure
• [ ] Add tests for EsclServer startup with various port configurations (PortFinder.cs)
• [ ] Add tests for CertificateHelper certificate generation and validation
• [ ] Add tests for MdnsAdvertiser registration/deregistration across platforms
• [ ] Add tests for EsclApiController endpoints (GET /Status, /ScannerCapabilities, POST /ScanJobs)
• [ ] Integrate tests into .github/workflows/dotnet.yml to run on Windows, macOS, and Linux

Add missing platform-specific app launcher tests for NAPS2.App.PortableLauncher

The NAPS2.App.PortableLauncher exists as a wrapper (with App.config and Program.cs) to launch the portable version, but there are no dedicated tests for it in NAPS2.App.Tests. The test infrastructure has platform-specific targets (WindowsAppTestTarget.cs, MacAppTestTarget.cs, LinuxAppTestTarget.cs) but PortableLauncher isn't covered. This is critical for ensuring users can successfully launch the portable edition on all platforms.

• [ ] Add PortableLauncher-specific test class in NAPS2.App.Tests (e.g., PortableLauncherTests.cs)
• [ ] Test successful bootstrap and delegation to main application on Windows
• [ ] Test runtime configuration loading from App.config
• [ ] Add Mac-specific test for codesign verification and launch behavior
• [ ] Add Linux-specific test for launcher execution and environment setup
• [ ] Document launcher behavior and configuration in README or CONTRIBUTORS

Refactor and add unit tests for scanning pipeline (WIA/TWAIN/SANE/ESCL abstraction)

The repo supports four different scanner backends (WIA, TWAIN, SANE, ESCL) but there are no visible unit tests for the scanner interface abstraction or backend switching logic. The file structure shows multiple app flavors but scanner backend tests are missing. This is core functionality that would benefit from comprehensive unit tests to prevent regressions when adding new backends or modifying scanner behavior.

• [ ] Identify and map scanner abstraction interfaces (likely in a NAPS2.Scanning or similar namespace not shown in file list)
• [ ] Create NAPS2.Scanning.Tests project with unit tests for scanner provider selection logic
• [ ] Add tests for WIA scanner device enumeration (Windows-specific mocking)
• [ ] Add tests for SANE backend initialization and device discovery (Linux-specific mocking)
• [ ] Add tests for ESCL scanner detection and connection handling
• [ ] Add tests for scanner capability detection and format negotiation across all backends
• [ ] Integrate tests into CI pipeline to run platform-appropriate tests on each OS

• Add unit tests for NAPS2.App.PortableLauncher: PortableLauncher project exists (NAPS2.App.PortableLauncher/.gitignore, .csproj) but no corresponding tests in NAPS2.App.Tests/; a new contributor could add PortableLauncherTests.cs with coverage for launcher argument parsing and app startup.
• Document scanner protocol support matrix in README: README.md mentions WIA/TWAIN/SANE/ESCL but doesn't clarify which OS supports which protocol; adding a compatibility table would help users and reduce support tickets.
• Expand language selection test coverage: LanguageSelectionTests.cs exists in Appium tests but only covers basic selection; add tests for persistence, fallback behavior, and non-Latin scripts (relevant to translate.naps2.com contributor base).

NAPS2 demonstrates a reasonable security posture as a document scanning application. The codebase is well-structured with separation of concerns across multiple modules. Key areas of concern are: (1) ESCL Server implementation which exposes network-facing APIs and requires careful certificate/TLS handling and input validation; (2) Lack of visible dependency management information preventing vulnerability assessment; (3) Potential test data exposure; (4) Configuration file handling. The application handles sensitive document data and network communication, requiring careful attention to cryptography, authentication, authorization, and data validation. No critical vulnerabilities are apparent from the file structure alone, but security depends heavily on implementation details in the actual code.

• Medium · ESCL Server Certificate Management — NAPS2.Escl.Server/CertificateHelper.cs. The NAPS2.Escl.Server module includes CertificateHelper.cs which handles certificate generation for HTTPS/TLS. Without reviewing the actual implementation, certificate handling in custom applications can lead to weak cipher suites, self-signed certificate acceptance, or improper validation. Fix: Ensure certificates use strong algorithms (TLS 1.2+), implement proper certificate validation, avoid hardcoded certificate paths, and use OS certificate stores where possible. Implement certificate pinning if applicable.
• Medium · Web Server Configuration — NAPS2.Escl.Server/WebServerExtensions.cs. The ESCL Server includes WebServerExtensions.cs which configures the web server. Without visibility into the implementation, potential issues could include missing security headers (HSTS, CSP, X-Frame-Options), inadequate CORS configuration, or improper input validation. Fix: Implement comprehensive security headers, configure CORS restrictively, validate all user inputs, sanitize outputs, and implement rate limiting. Ensure the server runs with minimal privileges.
• Medium · API Endpoint Input Validation — NAPS2.Escl.Server/EsclApiController.cs. EsclApiController.cs exposes API endpoints for the ESCL server. Without code review, there's risk of insufficient input validation leading to injection attacks or unexpected behavior. Fix: Implement strict input validation for all API parameters, use parameterized queries/commands, validate data types and ranges, and implement proper error handling without exposing sensitive information.
• Low · Potential Information Disclosure in Test Data — NAPS2.App.Tests/AppTestData.cs, NAPS2.App.Tests/Appium/AppiumTestData.cs. The test project includes AppTestData.cs and test files that may contain hardcoded test credentials, file paths, or system configuration that could be accidentally exposed. Fix: Ensure test data does not contain real credentials or sensitive paths. Use environment variables or secure secret management for test data. Never commit test data with actual credentials to version control.
• Low · Portable Launcher Configuration — NAPS2.App.PortableLauncher/App.config. NAPS2.App.PortableLauncher includes an App.config file which may contain sensitive configuration data or connection strings. Fix: Review App.config for any hardcoded credentials, connection strings, or API keys. Use encryption for sensitive configuration data or environment variables instead.
• Low · Missing Dependency Visibility — Dependencies/Package files. No package dependency file (packages.config, .csproj NuGet references, or similar) was provided for analysis. This prevents assessment of third-party library vulnerabilities. Fix: Provide and regularly review all NuGet package dependencies. Use tools like OWASP Dependency-Check or GitHub Dependabot to identify vulnerable packages. Keep dependencies updated to latest secure versions.

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.