ReproProof

ReproProof creates safe, verifiable reproduction receipts for open-source bug reports.

It runs a command, records the important project context, removes common secrets and local paths, and writes both a machine-readable JSON receipt and a Markdown report that can be pasted into a GitHub issue.

Quick start

npx reproproof capture --expect-exit 1 --expect-match "TypeError" -- npm test

The expectation flags describe the failure you are reporting; replace the exit code and output pattern with the ones from your reproducer. Omit them when the captured command is expected to succeed:

npx reproproof capture -- npm test

This creates reproproof.json and reproproof.md in the project directory.

To check the same scenario from another checkout or after changing dependencies:

npx reproproof verify reproproof.json

When the receipt came from an untrusted source, check the copied checkout without executing the recorded command:

npx reproproof verify /path/to/reproproof.json --cwd /path/to/checkout --no-replay

This reports context-matched when the package, dependency files, runtime and Git metadata match. The default verify mode still replays the command and reports reproduced only when its expectations also pass.

See docs/verifying.md for the verification workflow and status meanings.

See docs/consumer-validation.md for a small consumer trial checklist.

After trying ReproProof in a real consumer repository, use the Consumer validation feedback issue form. If you want to join the current independent trial, see the consumer validation call. Share sanitized observations or reviewed Markdown sections only; never attach the raw JSON receipt, an environment dump, credentials or private source.

After the npm package is published, check the installed CLI version with:

npx reproproof --version

Verification compares the package identity, package manager, dependency-file hashes, Node major version, platform, architecture, Git commit when available, exit code and optional output pattern.

What is captured

• Node.js version and detected package manager;
• hashes of common dependency lockfiles and manifests, never their contents;
• Git commit, branch and dirty state;
• a bounded stdout/stderr transcript;
• the command, exit code, signal, timeout state and duration.

The receipt does not include the full environment, source files or dependency contents.

Safety model

ReproProof is local-first. It does not upload receipts, call an AI service or contact GitHub. Common token prefixes, bearer credentials, named secrets, credential URLs, the project path and the home path are redacted before writing the receipt. Treat command output as potentially sensitive and review the Markdown report before publishing it.

If a command argument itself contains a secret, ReproProof redacts that argument and records that automatic replay is disabled for safety. Supply the value again manually when reproducing the scenario.

The first release supports Node.js projects and direct commands. Shell pipelines and automatic execution of code received from an issue are intentionally outside the MVP.

ReproProof also detects common Python project files and package managers (uv, Poetry, Pipenv and pip). For a Python project, pass the explicit test command, for example pytest -q.

GitHub Action

The repository also ships a Node 24 GitHub Action. It accepts the command as a JSON array, writes a receipt to .reproproof/, adds a job summary and uploads the JSON/Markdown files as an artifact by default.

- uses: shleder/reproproof@385a5c4713e580cb0ddd437f42db251c6a4f379f # v0.4.1; pin to a full commit SHA
  id: reproproof
  with:
    command: '["npm", "test"]'
    expect-exit: "1"
    expect-match: "TypeError"
    fail-on-mismatch: "true"
    upload-artifact: "false"

For the least-privilege setup above, set the job permissions to contents: read. If artifact upload is needed, keep contents: read and add only actions: write at that job's scope; do not grant contents: write or pull-requests: write just for ReproProof. Pin both ReproProof and checkout to reviewed immutable commit SHAs instead of @main or a moving tag.

The Action executes the declared command in the checked-out workspace. Do not run it with secrets on untrusted fork code or from pull_request_target. Receipts from issues and pull requests are untrusted input; inspect them with verify --no-replay before any manual replay. See docs/github-action.md for the complete permissions and pull-request security guidance.

The released Action is also exercised in the external dogfood repository.

npm publishing

The package is published from release tags with GitHub Actions and npm Trusted Publishing. The one-time first-release bootstrap and the exact workflow configuration are documented in docs/npm-publishing.md.

Development

npm install
npm run check
npm start -- capture -- node -e "console.log('hello')"

The project is intentionally a small single-package TypeScript CLI. Future adapters can add additional language ecosystems without putting network access or model calls into the deterministic core.

License

MIT