{ "markdown": "# BugProof\n\n
\n\n\"BugProof\n\n**Executable bugs, not bug reports.**\n\nCapture a failing command into a portable `.bug` artifact that anyone can replay on their machine — same code, same env, same failure. Cryptographically signable. Cross-platform. Zero containers required.\n\n[![npm version](https://img.shields.io/npm/v/bugproof.svg)](https://www.npmjs.com/package/bugproof)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-blue)](https://nodejs.org/)\n[![Cross-Platform](https://img.shields.io/badge/Cross--Platform-Windows%20%7C%20Linux%20%7C%20macOS-blueviolet)]()\n\n
\n\nhttps://github.com/user-attachments/assets/2315cfee-3ccf-40d7-830e-3a3d23731ab8\n\n---\n\n---\n\n## Why BugProof\n\n> \"Works on my machine\" is not a bug report.\n\nFiling a backend or CLI bug today usually looks like this:\n- A screenshot of a terminal\n- A copy-pasted stack trace\n- A list of *probably* relevant files\n- A best-guess description of how the reporter ran the thing\n\nThen the maintainer spends hours reconstructing the failure: matching versions, replicating the env, finding the right command, guessing at config. Most of that time is wasted.\n\n**BugProof captures the bug — not the description of it.** One command produces a single `.bug` file containing the source snapshot, the exact command, the environment schema, the failure fingerprint, and replay metadata. Another developer runs `bugproof replay bug.bug` and reproduces the failure deterministically.\n\nThink of it as **Git for bugs**: a portable, content-addressable, verifiable artifact that turns \"can you reproduce?\" into a one-liner.\n\n---\n\n## Highlights\n\n- **One-command capture.** Wrap any failing command with `bugproof capture --` and ship the result.\n- **Deterministic replay.** Source, env, command, and fingerprint travel together. Verdict is automatic.\n- **No Docker. No daemon.** Uses native OS primitives — Linux namespaces, Windows Job Objects, macOS Seatbelt.\n- **Cryptographic signatures.** Ed25519 sign/verify built in. Tamper-evident artifacts via `bugproof keygen` / `--sign` / `verify`.\n- **Self-healing replay.** `--self-heal` auto-installs missing npm/pip deps in the sandbox and retries.\n- **Best-effort credential redaction.** Env vars are scanned via pattern-matching + Shannon entropy. Known secret shapes (API keys, tokens, JWTs) are caught; low-entropy passwords and binary credentials may still leak.\n- **Multi-language.** Detects Node.js, Python, Ruby, Go, Rust, Java, C/C++, .NET, Kotlin build context automatically.\n- **Cross-platform.** Win ↔ Linux ↔ macOS replay, with command/env translation and architecture-mismatch guardrails.\n\n---\n\n## Install\n\n```bash\nnpm install -g bugproof\n```\n\n**Requirements:** Node.js 18+ and Git. Optional language toolchains (Python, Java, Go, Rust, …) are only needed if your captured command uses them.\n\nRun a one-off health check after install:\n\n```bash\nbugproof doctor\n```\n\n---\n\n## GitHub Action — Capture CI Failures Automatically\n\nAdd a single step to any GitHub Actions workflow to auto-capture flaky/failing commands as `.bug` artifacts.\n\n```yaml\n- name: Capture flaky test\n uses: sidinsearch/BugProof/.github/actions/bugproof-action@main\n with:\n command: 'npm test -- --run flaky-suite'\n name: flaky-test-failure\n timeout: 300000\n```\n\n**How it works**: The action installs `bugproof` from **npmjs.org** (`npm install -g bugproof`) → wraps your command with `bugproof capture` → on failure, the `.bug` artifact is uploaded to the Actions run. Developers download and repro locally with `bugproof replay`.\n\n**Use cases**:\n- **Flaky CI tests**: Capture the exact failure for local debugging\n- **Cross-platform failures**: A test passes on Linux CI but fails on macOS — capture the failure on both and diff\n- **Intermittent crashes**: `bugproof capture -- node app.js` bundles the crash state, env, and source\n\n**All inputs**:\n\n| Input | Required | Default | Description |\n|---|---|---|---|\n| `command` | ✅ | — | Command to capture (e.g. `npm test`) |\n| `name` | — | `bug_` | Artifact name |\n| `timeout` | — | `300000` | Command timeout in ms |\n| `skip-secrets` | — | `false` | Skip env secret scanning |\n| `upload-artifact` | — | `true` | Upload .bug file as Actions artifact |\n| `node-version` | — | `24` | Node.js version for bugproof |\n\nThe action lives at `.github/actions/bugproof-action/action.yml` in this repo. Reference it via `uses: sidinsearch/BugProof/.github/actions/bugproof-action@main`. BugProof is always installed from npmjs.org — no GitHub Packages token needed.\n\n---\n\n## MCP Server — AI-Agent Integration\n\nBugProof ships a built-in **MCP (Model Context Protocol) server** that exposes 10 tools plus Resources and Prompts for AI agents. Listed on the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.sidinsearch/bugproof`.\n\n### Setup\n\n#### Claude Code\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"bugproof\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bugproof\", \"mcp\"]\n }\n }\n}\n```\n\n#### Cursor\n\nAdd to Cursor MCP config (Settings → Features → MCP):\n\n```json\n{\n \"mcpServers\": {\n \"bugproof\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bugproof\", \"mcp\"]\n }\n }\n}\n```\n\n#### Continue.dev\n\nAdd to `~/.continue/config.json`:\n\n```json\n{\n \"experimental\": {\n \"mcpServers\": {\n \"bugproof\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"bugproof\", \"mcp\"]\n }\n }\n }\n}\n```\n\n#### With bugproof installed globally\n\nIf you already have bugproof globally (`npm install -g bugproof`), omit `npx -y`:\n\n```json\n{\n \"mcpServers\": {\n \"bugproof\": {\n \"command\": \"bugproof\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n**No separate MCP install needed.** `npx -y bugproof mcp` auto-downloads from npmjs.org and starts the server over stdio.\n\n### Tools\n\n| Tool | Description | When an AI agent would use it |\n|---|---|---|\n| `capture` | Run a command, capture as .bug artifact | \"Capture this failing test and tell me what changed\" |\n| `replay` | Replay a .bug file, return verdict | \"Replay the artifact from CI and confirm it still fails\" |\n| `inspect` | Show artifact metadata | \"What's in this .bug file without running it?\" |\n| `diff` | Compare two artifacts | \"Compare the CI capture with my local capture — what's different?\" |\n| `doctor` | Check sandbox capabilities | \"Does this machine support full sandbox isolation?\" |\n| `share` | Share artifact via GitHub Gist | \"Share this bug with my team\" |\n| `pull` | Download artifact from Gist | \"Pull the bug artifact from this URL\" |\n| `watch` | Auto-capture on command failure | \"Watch npm test and capture if it fails\" |\n| `list` | List .bug artifacts in directory | \"Show me all bug artifacts in this project\" |\n| `clean` | Remove .bug artifacts | \"Clean up old bug artifacts from this directory\" |\n\n### Resources\n\nAI agents can read .bug artifact contents directly via resource URIs:\n\n- `bugproof://artifact/{path}` — Read the raw .bug artifact (base64-encoded ZIP)\n\n### Prompts\n\nPre-built workflows for common AI agent tasks:\n\n| Prompt | Description |\n|---|---|\n| `capture-failure` | Guide to capture a failing command as a .bug artifact |\n| `replay-and-analyze` | Replay an artifact and analyze the root cause |\n| `compare-bugs` | Compare two artifacts to find differences |\n\n### Example AI session\n\n```\nUser: Capture the failing test and tell me what went wrong\nAgent: [calls bugproof capture -- npm test -- --run flaky-suite]\n [calls bugproof inspect on the result]\n \"The test failed with a timeout. Fingerprint matches a known\n Redis-unreachable pattern. Here's the captured stderr...\"\n```\n\nThe MCP server communicates over **stdio** (JSON-RPC 2.0). It shells out to the local `bugproof` CLI with `--json` output and returns structured results with both human-readable summaries and raw data. If bugproof isn't installed, `npx -y` fetches it from npmjs.org — no global install required.\n\n---\n\n## AI Agent Skill\n\nBugProof ships a **distributable AI Agent Skill** that teaches AI coding agents (Claude Code, Cursor, OpenCode, OpenClaw, Gemini CLI, GitHub Copilot, and others) how to use BugProof effectively. The skill follows the open [Agent Skills](https://agentskills.io) standard — build once, use across any compatible agent.\n\n### What the Skill Does\n\nWhen loaded, the skill gives AI agents complete knowledge of:\n- All 14 BugProof commands with flags and examples\n- Capture, replay, diff, and inspection workflows\n- Cross-platform replay patterns\n- MCP server configuration\n- Best practices for naming, security, and artifact management\n- 8 real-world examples (Node.js, Python, Go, Java, CI/CD, cross-platform, flaky tests)\n\n### How AI Agents Use It\n\nAgents auto-load the skill when users mention:\n- \"capture this bug\"\n- \"replay the bug\"\n- \"reproduce this failure\"\n- \"share this bug\"\n- \".bug file\"\n- \"works on my machine\"\n- \"executable bug\"\n\nOr invoke directly: `/bugproof`\n\n### Install the Skill\n\n#### Option 1: Clone This Repository\n\n```bash\n# Clone the BugProof repository\ngit clone https://github.com/sidinsearch/BugProof.git\n\n# Copy the skill to your agent's skills directory\n# Claude Code:\ncp -r BugProof/skills/bugproof ~/.claude/skills/\n\n# OpenCode:\ncp -r BugProof/skills/bugproof ~/.config/opencode/skills/\n\n# OpenClaw:\ncp -r BugProof/skills/bugproof ~/.agents/skills/\n\n# Cursor:\ncp -r BugProof/skills/bugproof ~/.cursor/skills/\n```\n\n#### Option 2: Download the Skill Directly\n\n```bash\n# Download just the skill\ncurl -L https://github.com/sidinsearch/BugProof/archive/refs/heads/main.tar.gz | tar xz\ncp -r BugProof-main/skills/bugproof ~/.claude/skills/\n```\n\n### Skill Structure\n\n```\nskills/bugproof/\n├── SKILL.md # Main instructions (required)\n├── reference/\n│ └── commands.md # Full command reference\n└── examples/\n └── usage-examples.md # Real-world usage examples\n```\n\n### Supported AI Agents\n\n| Agent | Skill Directory |\n|-------|----------------|\n| Claude Code | `~/.claude/skills/bugproof/` |\n| OpenCode | `~/.config/opencode/skills/bugproof/` |\n| OpenClaw | `~/.agents/skills/bugproof/` |\n| Cursor | `~/.cursor/skills/bugproof/` |\n| Gemini CLI | `~/.gemini/skills/bugproof/` |\n| GitHub Copilot | `.github/skills/bugproof/` |\n\nThe skill follows the open [Agent Skills specification](https://agentskills.io) — any agent that supports the standard can use it.\n\n---\n\n## 60-Second Quick Start\n\n```bash\n# 1. Reproduce a failure\n$ npm test\nFAIL Tests failed because Redis was unreachable.\n\n# 2. Capture it\n$ bugproof capture -- npm test\n ✔ Artifact captured!\n Path ./bug_1778049738215.bug\n Files 42 files (28.4 KB)\n Fingerprint sha256:c8b3...\n\n# 3. Share the file (Slack, email, gist, attachment...)\n\n# 4. Anyone replays it on their machine\n$ bugproof replay bug_1778049738215.bug\n ✔ REPRODUCTION CONFIRMED\n Exit code exit 1 (match)\n Verdict Reproduction confirmed (exact fingerprint match)\n```\n\nOptional flow:\n\n```bash\n$ bugproof inspect bug.bug # peek at the contents\n$ bugproof diff old.bug new.bug # what changed between two captures\n$ bugproof share bug.bug # publish as a GitHub Gist\n```\n \n\n## Commands\n\nBugProof ships **14 commands**. Every command supports `--help` and `--json` for machine-readable output.\n\n| Command | Purpose |\n|---|---|\n| `bugproof capture` | Run a command, record everything, produce a `.bug` artifact |\n| `bugproof replay` | Re-execute an artifact, compare against expected fingerprint |\n| `bugproof watch` | Transparently wrap a command — capture *only* if it fails |\n| `bugproof inspect` | Show artifact contents (manifest, command, fingerprint, files) |\n| `bugproof diff` | Side-by-side comparison of two artifacts |\n| `bugproof verify` | Validate the Ed25519 signature on a `.bug` (standalone) |\n| `bugproof keygen` | Generate an Ed25519 keypair for signing artifacts |\n| `bugproof share` | Publish an artifact as a GitHub Gist |\n| `bugproof mcp` | Start the MCP server for AI-agent integration |\n| `bugproof init` | Scaffold a `.bugproofrc` config file |\n| `bugproof prune` | Garbage-collect orphan sandbox temp directories |\n| `bugproof clean` | Remove all `.bug` artifacts from the current directory |\n| `bugproof pull` | Download a shared `.bug` artifact from a GitHub Gist |\n| `bugproof doctor` | Verify OS support for sandbox isolation features |\n| `bugproof help` | Help for any command |\n\n---\n\n### `bugproof capture [command...]`\n\nRun a command end-to-end and bundle the failure as `.bug`.\n\n```bash\nbugproof capture -- npm test\nbugproof capture -n auth-crash -d \"Login fails on expired session\" -- node server.js\nbugproof capture -o ./bugs/ -- npm test\nbugproof capture --include-untracked -- python app.py\nbugproof capture -x \"*.log\" -x \"node_modules/**\" -- go test ./...\nbugproof capture --timeout 600000 -- java -cp . Main\nbugproof capture --include-compiled -- mvn test # force include .class/.jar files\nbugproof capture --sign --signer \"alice@example.com\" -- ./run.sh\nbugproof capture --json -- node script.js\n```\n\n| Flag | Description |\n|---|---|\n| `-n, --name ` | Artifact name (becomes `.bug`) |\n| `-d, --description ` | Human-readable description embedded in the manifest |\n| `-o, --output ` | Output directory (default: current directory; respects `.bugproofrc` `outputDir`) |\n| `-x, --exclude ` | Exclude files by glob (repeatable) |\n| `--include-untracked` | Bundle untracked files too (`git ls-files -o`) |\n| `--include-compiled` | Force include compiled artifacts (`.class`, `.jar`, `.pyc`, etc.) — auto-detected by default |\n| `--timeout ` | Kill the command after N ms (default 300000) |\n| `--skip-secrets` | Don't scan env for secrets (skip the confirm prompt) |\n| `--sign [key]` | Sign with the default key, or a named key / path to a `.key` file |\n| `--signer ` | Embed a signer identity (email, gist URL, etc.) |\n| `--json` | Structured JSON output |\n\n**Default behavior:** Without `-n`, artifacts are named `bug_.bug`. With `.bugproofrc` `nameTemplate` configured, the template is used instead. Without `-o`, artifacts are saved in the current directory.\n\n---\n\n### `bugproof replay `\n\nRe-execute the captured artifact and compare results.\n\n```bash\nbugproof replay bug.bug\nbugproof replay bug.bug --sandbox isolated\nbugproof replay bug.bug --self-heal\nbugproof replay bug.bug --verify-signature\nbugproof replay bug.bug --source-dir .\nbugproof replay bug.bug --json\n```\n\n| Flag | Description |\n|---|---|\n| `--sandbox ` | `workspace` (default), `isolated`, or `full` |\n| `--self-heal` | Auto-install missing npm/pip deps and retry (up to 3 rounds) |\n| `--verify-signature` | Require a valid Ed25519 signature; exit 2 if missing or invalid |\n| `--source-dir ` | Override source directory for git operations (use current dir's repo instead of captured path) |\n| `--json` | Structured JSON output |\n\n**Replay isolation:** Replay always runs in an isolated temp directory. Files come from either: (1) git worktree/clone at the captured commit, (2) current directory's git repo (if original path is inaccessible), or (3) the artifact's bundled `files/` snapshot. The current directory is never read for source files.\n\n---\n\n### `bugproof keygen` / `verify` — Cryptographic Provenance\n\nSign artifacts with **Ed25519** (RFC 8032). Built on Node's native `crypto` — no external deps.\n\n```bash\n# One-time: create your signing key\nbugproof keygen\n# → writes default.pub / default.key to ~/.bugproof/keys/\n\n# Capture with a signature\nbugproof capture --sign --signer \"alice@example.com\" -- npm test\n\n# Verify a received artifact\nbugproof verify bug.bug\n ✔ SIGNATURE VALID\n Algorithm ed25519\n Fingerprint 179721ef7e63f6b3\n Signed at 2026-05-10T22:09:30Z\n Signer alice@example.com\n\n# Enforce signatures at replay time\nbugproof replay --verify-signature bug.bug\n```\n\nThe signature covers a canonical hash of the manifest, the failure fingerprint, and the SHA-256 of every file in the bundle. Tampering with source, output, exit code, or metadata invalidates the signature.\n\n> **Note:** identity/PKI is intentionally out of scope. Trust is established by comparing the embedded public-key fingerprint against one you know (gist pinning, team wiki, key server, etc.).\n\n---\n\n### `bugproof watch [command...]`\n\nTransparent wrapper. Runs the command normally; only captures if it fails. Drop-in replacement for any command you'd otherwise hand-run.\n\n```bash\nbugproof watch -- npm test\nbugproof watch -o ./bugs -- python app.py\nbugproof watch --always -- node script.js # capture even on success\n```\n\n---\n\n### `bugproof inspect ` / `diff `\n\n```bash\nbugproof inspect bug.bug # manifest, fingerprint, file list, env schema\nbugproof diff captured-v1.bug captured-v2.bug # what changed between two captures\n```\n\n---\n\n### `bugproof share `\n\nPublish an artifact as a GitHub Gist. Respects `HTTPS_PROXY` / `HTTP_PROXY` for corporate networks.\n\n```bash\nbugproof share bug.bug\nbugproof share --public bug.bug\n```\n\nRequires `GITHUB_TOKEN` (or `BUGPROOF_GITHUB_TOKEN`) with `gist` scope.\n\n---\n\n### `bugproof init` / `prune` / `doctor`\n\n```bash\nbugproof init # scaffold .bugproofrc in the current directory\nbugproof prune # garbage-collect orphan BugBox temp directories\nbugproof doctor # check OS support for sandbox isolation (namespaces, Job Objects, Seatbelt)\n```\n\n---\n\n## Configuration (`.bugproofrc`)\n\nGenerated by `bugproof init`. All fields are optional.\n\n```json\n{\n \"exclude\": [\"node_modules/**\", \"dist/**\", \"*.bug\"],\n \"outputDir\": \".\",\n \"timeout\": 300000,\n \"skipSecrets\": false,\n \"includeUntracked\": false\n}\n```\n\n---\n\n## Smart Source Strategy\n\nBugProof keeps artifacts small even on heavy codebases:\n\n| Strategy | When | What ships | Typical size |\n|---|---|---|---|\n| `git-full` | Clean git repo | Commit ref only | ~2 KB |\n| `git-patch` | Dirty git repo | Commit ref + diff patch | ~5 KB |\n| `git-files` | Force mode / untracked | All tracked + untracked files | varies |\n| `full-copy` | No git repo | Full codebase (excl. node_modules, etc.) | ~10–100 MB |\n\nGit is **strongly encouraged** but not required.\n\n### Compiled Language Support\n\nBugProof **auto-detects** compiled languages and bundles build artifacts automatically:\n\n| Language | Source Files | Compiled Artifacts | Auto-Included? |\n|---|---|---|---|\n| **Java** | `.java` | `.class`, `.jar`, `.war`, `.ear` | ✅ Yes (from `target/`, `build/`, `out/`) |\n| **Python** | `.py` | `.pyc`, `.pyo` | ✅ Yes (from `__pycache__/`) |\n| **Go** | `.go` | `bin/`, compiled binaries | ✅ Yes (from `bin/`, `dist/`) |\n| **Rust** | `.rs` | `target/` binaries | ✅ Yes (from `target/`) |\n| **.NET/C#** | `.cs`, `.csproj` | `.dll`, `.exe` | ✅ Yes (from `bin/`, `obj/`) |\n| **WebAssembly** | — | `.wasm` | ✅ Yes (from any build dir) |\n| **Node native** | — | `.node` | ✅ Yes (from `build/`, `dist/`) |\n| **C/C++** | `.c`, `.cpp` | `.o`, `.obj`, `.exe` | ❌ No (platform-specific, source-only) |\n\n**How it works:** When BugProof detects a compiled language project (via `pom.xml`, `go.mod`, `Cargo.toml`, etc.) and finds compiled artifacts in standard build directories, it automatically includes them. No flag needed.\n\nUse `--include-compiled` to force inclusion even when auto-detection misses something, or for edge cases.\n\n---\n\n## Sandbox & Isolation Model\n\nBugProof runs replayed commands in a layered sandbox — Docker-like isolation built on native OS primitives.\n\n| Layer | Linux | Windows | macOS |\n|---|---|---|---|\n| Process | PID namespace (`unshare --pid`) | Job Objects | sandbox-exec |\n| Network | Network namespace (`unshare --net`) | `netsh advfirewall` rules | `(deny network*)` |\n| Filesystem | fuse-overlayfs (RO source + writable overlay) | Isolated temp directory | Restricted write paths |\n| Resource limits | cgroups v2 (memory, CPU, PIDs) | Job Object limits | — |\n| Env sanitization | Strip `LD_PRELOAD`, `NODE_OPTIONS`, … | Same | Same |\n| Temp | Private `/tmp` | Private `%TEMP%` | Private `/tmp` |\n\nThree sandbox levels are exposed via `--sandbox`:\n\n- `workspace` *(default)* — minimal isolation, fast. Good for trusted artifacts.\n- `isolated` — namespace + temp isolation. Recommended for untrusted artifacts.\n- `full` — all layers including network deny + resource limits.\n\n> **Caveat:** On Windows, `isolated` and `full` are best-effort hardening, not VM-grade containment. For artifacts from fully untrusted sources, replay inside a dedicated VM.\n\n---\n\n## Environment Snapshot\n\nCapture-time runtime versions are recorded and diffed on replay:\n\n```\n Environment Mismatches\n • node version mismatch: captured 18.0.0, current 22.1.0\n ✘ python 3.11.0 was available at capture but is not installed now.\n```\n\nTracked: Node.js, Python, Ruby, Go, Rust, Java, npm, pip, OS platform, architecture.\n\n---\n\n## Cross-Platform Replay\n\n| Capture ↘ / Replay ↗ | Windows | Linux | macOS |\n|---|---|---|---|\n| **Windows** | ✅ | ✅ | ✅ |\n| **Linux** | ✅ | ✅ | ✅ |\n| **macOS** | ✅ | ✅ | ✅ |\n\nThe translation layer normalizes commands (`python3 ↔ python`, `gradlew ↔ gradlew.bat`, `make ↔ mingw32-make`, shell paths). Architecture mismatches (`x64 ↔ arm64`) trigger explicit warnings with Rosetta/translation advice.\n\n---\n\n## Security Model\n\n| Area | Mechanism |\n|---|---|\n| **Secrets — known patterns** | Env vars matching `*_TOKEN`, `*_KEY`, `*_SECRET`, AWS/GCP/Stripe shapes are redacted at capture |\n| **Secrets — unknown values** | Shannon entropy analysis flags high-entropy values (≥4.5 bits/char) even with innocuous key names |\n| **stdout/stderr scrubbing** | Active regex stream-scrubber strips emails, IPs, credit cards, GitHub tokens, Stripe keys from captured output |\n| **Path traversal** | Every file copy is validated to stay within artifact and project boundaries |\n| **Script injection** | Sandbox commands are spawned with argument arrays — never via shell strings |\n| **Provenance** | Ed25519 signatures cover manifest + fingerprint + per-file SHA-256s. Verification is local, no network calls |\n| **Sandbox env sanitization** | `LD_PRELOAD`, `NODE_OPTIONS`, `DYLD_*`, and similar runtime-hijack vectors are stripped before replay |\n| **Cryptography** | Node native `crypto` only — no external crypto deps. No telemetry. No phone-home |\n\nUse `--skip-secrets` only when you've audited the environment yourself.\n\n---\n\n## File Association\n\n### Windows\nRegistered under `HKCU\\Software\\Classes\\.bug` → `BugProof.Artifact` with open command `node /dist/cli.js replay \"%1\"`.\n\n### Linux\nRegisters MIME `application/x-bugproof`, a `bugproof.desktop` handler, and a user-level icon entry in `~/.local/share/icons/hicolor/`.\n\n### macOS\nBest-effort via the bundled script. Re-run manually if Finder association doesn't take:\n\n```bash\nbash scripts/bugproof-file-association-macos.sh\n```\n\n---\n\n## Architecture\n\n```\nbugproof/\n├── src/\n│ ├── capture/ # Execution + env snapshot + language detection + packaging\n│ ├── replay/ # Restore + sandbox orchestration + verdict + self-heal\n│ ├── sandbox/ # OS-specific isolation (filesystem, network, process)\n│ ├── share/ # Gist publisher\n│ ├── diff/ # Two-artifact diff engine\n│ ├── config/ # .bugproofrc loader and validation\n│ ├── utils/ # signing, secrets, fingerprint, dependencies, security, …\n│ └── cli.ts # Commander entrypoint (14 commands)\n├── tests/ # 40 suites / 502 tests (Jest)\n├── scripts/ # Postinstall, e2e matrix, file-association helpers\n└── .github/workflows/ # CI/CD (tri-platform matrix, signed npm publish)\n```\n\n| Module | Responsibility |\n|---|---|\n| `capture/engine.ts` | Execute the user's command, stream output to temp files, record stdout/stderr/exit |\n| `capture/packager.ts` | Bundle into `.bug` zip; optionally sign with Ed25519 |\n| `capture/language-support.ts` | Detect Node/Python/Java/Go/Rust/.NET/C++/Kotlin + compiled artifact auto-detection |\n| `capture/env-snapshot.ts` | Record runtime versions for environment diff on replay |\n| `capture/source-strategy.ts` | Smart source selection: git-full, git-patch, stacktrace, minimal |\n| `replay/engine.ts` | Reproduce the command in a sandbox |\n| `replay/self-heal.ts` | Detect missing deps, install in sandbox, retry |\n| `replay/verdict.ts` | Compare fingerprint + normalized error patterns |\n| `replay/hints.ts` | Generate actionable debugging hints from captured output |\n| `sandbox/bugbox.ts` | Orchestrate per-OS isolation layers |\n| `sandbox/cross-platform.ts` | Command translation across Windows/Linux/macOS |\n| `utils/signing.ts` | Ed25519 sign / verify / canonical-payload builder |\n| `utils/secrets.ts` | Pattern + entropy-based env scanning, PII stream scrubber |\n| `utils/fingerprint.ts` | Deterministic failure fingerprinting, path normalization |\n| `utils/dependencies.ts` | Detect missing npm/pip/system deps from stderr |\n| `utils/ui.ts` | Terminal UI: colors, spinners, progress bars, summary boxes |\n| `diff/engine.ts` | Side-by-side artifact comparison |\n| `share/gist.ts` | GitHub Gist publisher with proxy support |\n| `config/loader.ts` | Load and validate `.bugproofrc` configuration |\n\n---\n\n\n\n## Contributing\n\nPRs welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for guidelines, dev setup, and the test matrix expectations. Every PR runs the full tri-platform CI; please add tests for new behavior.\n\n---\n\n## License\n\nThis project is licensed under the **[GNU Affero General Public License v3.0](LICENSE)** (AGPL-3.0).\n\n| Use Case | Allowed? |\n|---|---|\n| Personal & non-commercial use | ✅ Free, no restrictions |\n| Forking & modifications | ✅ Must release under AGPL-3.0 with source code |\n| Running as a network service (SaaS) | ✅ Must publish your modified source code |\n| Commercial / proprietary use | ❌ Requires a separate commercial license |\n\n\n---\n\n

\n Made with ❤️ by sidinsearch\n  · \n Copyright © 2026 sidinsearch\n  · \n AGPL-3.0 License\n

\n", "bytes": 26351, "sha": "374d2c8c58d7911e56c7ce7c9f7f29a566b201de245ff3ab6d8177b6b62fd397", "repo_slug": "sidinsearch/bugproof", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_sidinsearch_bugproof_aebed9de/readme" }