ReproProof

Give maintainers the context behind “works on my machine.”

Problem

A Node.js bug report can be impossible to reproduce when it only says “run npm test.” The reporter may have a different Node runtime, dependency tree, package manager, platform or Git commit. Asking for a full environment dump is noisy and can expose private data.

Product

ReproProof is a local CLI that captures a sanitized, bounded receipt of a command’s runtime, dependency and Git context. It gives maintainers reviewable evidence to compare before replaying a report; it does not guarantee full reproducibility.

15-second example

npx reproproof capture -- npm test
# writes reproproof.json and reproproof.md

npx reproproof verify reproproof.json --no-replay

Value

Review the Markdown report before sharing it. verify --no-replay checks the package, dependency, runtime and Git context without executing the recorded command, giving a maintainer a safe first check before spending time replaying the bug.

Trust

The local CLI is local-first: it does not upload receipts to a server, call AI or other network services, or contact GitHub. Common secrets and local paths are redacted before writing; review the Markdown report before publishing it.

Try it in a consumer project

ReproProof requires Node.js 20 or newer. Before a ten-minute consumer trial, run the preflight checks so an engine mismatch is caught before capture or verification.

The npx --package examples below assume a consumer project with a different package name. If the checkout itself is named reproproof, use the same-name checkout workaround instead.

Check the pinned CLI first:

npx --yes --package [email protected] reproproof --version

Capture the failing command and its expected outcome:

npx --yes --package [email protected] 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 --yes --package [email protected] 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 --yes --package [email protected] reproproof verify reproproof.json

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

npx --yes --package [email protected] 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.

For CI wrappers that need a machine-readable capture status, see the CI JSON summary.

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, or ask a question in the trial discussion. Share sanitized observations or reviewed Markdown sections only; never attach the raw JSON receipt, an environment dump, credentials or private source.

If ReproProof saves time in a real bug report, star the repository so other maintainers can find it.

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.

ReproProof never creates issues, comments or pull requests, and it does not send automated outreach; publishing feedback is always an explicit user action.

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.

ReproProof supports Node.js projects and direct commands. It detects npm, pnpm, yarn and Bun lockfiles; for a Bun project, pass the explicit command, for example bun test. When Bun is available, its version is included in the receipt. 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@f1282ca412566ff5ff15a6e958a5b15e484aeb53 # v0.4.8; pin to a full commit SHA
  id: reproproof
  with:
    command: '["npm", "test"]'
    expect-exit: "1"
    expect-match: "TypeError"
    fail-on-mismatch: "true"
    upload-artifact: "true"

For the least-privilege setup above, set the job permissions to contents: read. ReproProof's artifact upload works with contents: read; no actions: write permission is required. 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