Build PatchProof from an authorized source checkout.

Step 0

Prerequisites

• Node.js 22 or newer and npm.
• Git and an authorized checkout of the PatchProof source.
• An authorized checkout of the project you want to verify.
• The runtimes and tools required by that project’s checks.

node --version
npm --version
git --version

Use a Node.js version that reports v22 or newer. The checked-in lockfile makes npm ci the reproducible install path.

Step 1

Build the CLI from PatchProof source

Run these commands at the root of your authorized PatchProof source checkout. They install the locked workspace dependencies and compile the shared packages and runner CLI.

cd /path/to/authorized/patchproof-source
npm ci
npm run build

node apps/runner/dist/cli/index.js --help

Keep the absolute source path available. The remaining commands invoke that compiled CLI directly from your project checkout.

Step 2

Initialize the project policy

Move to the project you are authorized to verify. init detects common stacks and writes a starter .patchproof.yml. Review that file before running project commands.

cd /path/to/your-authorized-project

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js init

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js \
  config validate

The starter may propose reproducible install, test, build, typecheck, lint, health, or browser checks based on project files. Confirm every generated command is appropriate for this repository and environment.

Step 3

Inspect command readiness

doctor compares the declared policy with the current host. It reports detected runtime and package-manager capabilities without executing the verification plan.

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js \
  doctor \
  --config .patchproof.yml

Resolve missing runtimes or incompatible labels before continuing. Verification commands execute with the authority of the current machine, so review environment access and secrets first.

Step 4

Create a local proof

Run from the project checkout. With HEAD as the comparison head, PatchProof includes committed diff, staged changes, unstaged tracked changes, and untracked files.

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js run \
  --base origin/main \
  --head HEAD

PatchProof loads .patchproof.yml, scans the changed files, executes required commands, then runs configured health checks, browser checks, and optional commands. The exact sequence comes from your repository policy.

By default, the run prints confidence, evidence counts, a merge recommendation, and top concerns, then writes a redacted JSON proof to .patchproof/reports/run-*.json.

Step 5

Interpret and retain the result

run exits nonzero for risky, blocked, and unknown verdicts. Treat that exit as a stopping condition for scripts and coding agents.

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js \
  report --latest

node /path/to/authorized/patchproof-source/apps/runner/dist/cli/index.js \
  report --list --limit 5

Optional next step

Move from a local proof to a manual shared run

The cloud workflow adds workspace access, project and runner coordination, a step timeline, centralized redacted logs, artifacts, and a durable proof page. You create a project, register a self-hosted runner, and explicitly queue each run.

Repository execution still happens on your runner. GitHub/Gitea event integrations and hosted runners are not available in 0.1.