patchsvc

Git-native patch service and CLI that forks disposable worktrees, runs bounded commands, and extracts validated patch artifacts with manifests, checksums, and apply-check guarantees. JSON-first by default, dependency-light (Node 18+, git).

Why and what

• Safe worktrees: per-run branches under patchsvc/<prefix>/<id> with TTL, reuse, and cleanup sweeps.
• Bounded execution: time/output caps, optional read-only/network-off modes, strict path resolution (blocks .git and symlink escapes).
• Trustable artifacts: staged diff + manifest with checksums, apply-check results, hook outputs, limits/scope, and validator outcomes.
• Scriptable surfaces: CLI, library API, and optional HTTP wrapper with auth + allowedCommands.

Quick start

npm install
npm run build

# Fork → exec → extract → cleanup (JSON output)
patchsvc fork --base HEAD
patchsvc exec --id <id> -- sh -c "echo 'hi' >> readme.md"
patchsvc extract --id <id>
patchsvc cleanup --id <id> --force

• Default apply-check: git apply --check --cached (1MB/10k-line cap; “already exists in index” is treated as OK and preserved in stderr).
• Worktrees live under <repo>/.patchsvc/worktrees; patch + manifest are written there and kept after cleanup.

Key concepts

• Worktree sessions: id/path/branchName/baseRef/baseCommit/expiresAt; reuse policy (never | preferExistingSameBase | requireFresh); default TTL 24h; cleanup-orphans sweeps expired/unregistered sessions.
• Validators (short-circuit order): nonEmptyDiff → filesMatchDiff → baseMatch → scopeAllowlist → sizeGuard → extensionGate → applyCheck → hooks → hygiene. Defaults enforce size caps, a binary denylist, and simple secret regexes; hooks can be lint/test/custom.
• Apply-check: two-way (git apply --check --cached) by default; three-way or worktree-dry-run optional. Oversize diffs mark the check as skipped: size_limit.
• Manifests: JSON next to the .patch capturing schemaVersion, base ref/commit, branch name, worktreePath, limits/scope, hookResults, metadata, diffPath, checksums, applyCheck, validators, filesModified.

Interfaces

• CLI (JSON-first; --human for text): fork, exec, stage, extract, validate, describe, cleanup, cleanup-orphans, serve. Common flags: --config, --base, --prefix, --temp-root, --ttl, --scope, --max-*, --apply-check, --validators, --metadata-provider, --hook/--lint/--test, --read-only, --network-off.
• Library API (import { PatchService } from "patchsvc"): create a service with repo root, limits, validators, metadata provider, hooks, modes; call createSession → exec/stage/extract/validate/cleanup; run cleanupOrphans; start HTTP server via startHttpServer.
• HTTP mode: PATCHSVC serve --port ... --auth <token> exposes /fork, /exec, /extract, /cleanup-orphans, /health. Responses are JSON with {code,message,details?} and status mappings (e.g., E_AUTH→401, E_APPLY_CHECK_FAILED→409, validation→422).

Config & extensibility

• Auto-discovers patchsvc.config.{json,js,cjs} (override with --config). Fields: repoRoot/tempRoot/prefix/ttlMs/reusePolicy, scope, size limits, readOnly, networkOff, hooks, defaultValidators (module paths), metadataProvider.
• Custom validators/metadata providers resolve relative to the config file. Validators can export a function, validator, or { validators: [...] }; metadata providers export a function.

Documentation

• Quick start: docs/quick-start.md
• Concepts: docs/core-concepts.md
• CLI: docs/cli-reference.md
• Config/extensibility: docs/config-extensibility.md
• HTTP: docs/http-mode.md
• Safety/limits: docs/safety-limits.md
• Examples/recipes: docs/examples-recipes.md
• Troubleshooting: docs/troubleshooting.md

Development

• Build: npm run build
• Lint typechecks: npm run lint
• Tests: npm test (builds, compiles tests, runs node --test dist-tests/tests/*.js)