{"_id":"buggy-debugger","_rev":"2-6a38147f0fcb2bf852495f0386ff8619","name":"buggy-debugger","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.0-stage":{"name":"buggy-debugger","version":"0.0.0-stage","_id":"buggy-debugger@0.0.0-stage","stub":true,"maintainers":[{"name":"himanshu_saini_1999","email":"sainihimanshu.1999@gmail.com"}],"dist":{"shasum":"443f980b65a42595a716cba2c0d4d9df85d42b02","tarball":"https://registry.npmjs.org/buggy-debugger/-/buggy-debugger-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-qYYNbvpGHyL0dA8tjcHBZ86Q+GPcJPodMZzzFv4CRc5rlPUkoerR+Vr1nIyQzYhGO92sgWRtyLkNg4xz7FFI2A==","signatures":[{"sig":"MEYCIQCTUF+cesbJo0GtpD1yOB0Vv9wSZs2NHe30IGQMIWHNIQIhANuKlAADLwcsWEKc/zi0gTAcz3ETTXIpSMkpFRD1Ra24","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":336},"_npmUser":{"name":"himanshu_saini_1999","email":"sainihimanshu.1999@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"_id":"buggy-debugger@0.1.0","bin":{"buggy":"dist/cli.js","buggy-mcp":"dist/mcp-server.js"},"bugs":{"url":"https://github.com/himanshusaini-afk/buggy/issues"},"dist":{"shasum":"b83203092ee118d5a8f5ff18b151a25135dbe077","tarball":"https://registry.npmjs.org/buggy-debugger/-/buggy-debugger-0.1.0.tgz","fileCount":248,"integrity":"sha512-oGjwtTTGbJqkGpx+JLGY7tuDdy87/o9TOgq38iURguYuyCb4hbeBOD85QxXncNN0MC0jevigJUwF8Ebq2lbudg==","signatures":[{"sig":"MEUCIQDEfW2X3/k3k1FngDPiAFschZ2yr2njTf7Aid+Lx7wQ3gIgHtnH/y4aDbm/4HizhE/a4PZkpy+4mcRnp2modzUTqFU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCHmU4kcSJ9y1ubIRo9kSvQelzItysAWEvVzAQN7X6iEwIhANiSmMTi/IuftF7geISwTHhDuHrLebh1eXj9O2tapOFG"}],"unpackedSize":1258711},"main":"dist/index.js","name":"buggy-debugger","type":"module","types":"dist/index.d.ts","author":{"name":"himanshusaini-afk"},"engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"dfb6d738ada1a0f30dc8eb77453ab0abeae53780","license":"MIT","scripts":{"test":"vitest run","build":"tsc","smoke":"node scripts/smoke-test.mjs","start":"node dist/cli.js","prepare":"npm run build","test:unit":"vitest run tests/unit","test:watch":"vitest","prepublishOnly":"node scripts/smoke-test.mjs","test:properties":"vitest run tests/properties","test:integration":"vitest run tests/integration"},"version":"0.1.0","_npmUser":{"name":"himanshu_saini_1999","email":"sainihimanshu.1999@gmail.com"},"homepage":"https://himanshusaini-afk.github.io/buggy/","keywords":["debugger","bug-detection","proof-carrying","automated-repair","mcp","mcp-server","model-context-protocol","static-analysis","fuzzing","property-based-testing","ai-coding","developer-tools"],"repository":{"url":"git+https://github.com/himanshusaini-afk/buggy.git","type":"git"},"_npmVersion":"10.9.2","description":"Proof-carrying debugger. Executes your code to find a real failing input, verifies the failure three ways before reporting it, generates candidate repairs, and rejects patches that only fit the example that caught them. CLI, MCP server, or programmatic AP","directories":{},"maintainers":[{"name":"himanshu_saini_1999","email":"sainihimanshu.1999@gmail.com"}],"_nodeVersion":"22.13.1","dependencies":{"zod":"3.24.4","yaml":"2.7.1","tree-sitter":"0.22.4","better-sqlite3":"11.7.0","tree-sitter-python":"0.23.6","tree-sitter-typescript":"0.23.2","@modelcontextprotocol/sdk":"1.12.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"3.1.3","fast-check":"3.23.2","typescript":"5.8.3","@types/node":"22.15.17","@types/better-sqlite3":"7.6.13"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/buggy-debugger_0.1.0_1791456782177_0.37110588035549763"}}},"time":{"created":"2026-10-08T10:50:24.726Z","modified":"2026-10-08T10:53:02.442Z","0.0.0-stage":"2026-10-08T10:50:24.726Z","0.1.0":"2026-10-08T10:53:02.295Z"},"description":"Proof-carrying debugger. Executes your code to find a real failing input, verifies the failure three ways before reporting it, generates candidate repairs, and rejects patches that only fit the example that caught them. CLI, MCP server, or programmatic AP","maintainers":[{"name":"himanshu_saini_1999","email":"sainihimanshu.1999@gmail.com"}],"readme":"# Buggy\r\n\r\nA multi-agent system that autonomously analyzes code, proves bugs exist with formal certificates, generates repairs, and validates patches against overfitting — all coordinated over the Model Context Protocol (MCP). Unlike traditional debuggers that rely on breakpoints and manual inspection, this system produces cryptographically-verifiable proof-of-failure certificates before attempting any repair.\r\n\r\n**[→ buggy on the web](https://himanshusaini-afk.github.io/buggy/)** — what it does, how the pipeline works, and what currently runs. Source in [`site/`](site/).\r\n\r\n**[→ Features](docs/FEATURES.md)** — the full inventory, including a\r\nmodule-by-module split of what is wired into the live pipeline and what is\r\nlibrary code only.\r\n\r\n## Quick Start\r\n\r\n```bash\r\n# From npm. NOTE the name is `buggy-debugger` — plain `buggy` on npm is an\r\n# unrelated issue tracker.\r\nnpm install -g buggy-debugger\r\n\r\n# Initialize in your project — detects your language and asks a few questions\r\ncd /path/to/your/project\r\nbuggy init            # or: buggy init --yes  (accept detected defaults)\r\n\r\n# Ready to use — no config editing needed\r\nbuggy analyze src/payments.ts\r\nbuggy investigate processPayment --file src/payments.ts\r\n```\r\n\r\n## Kiro Integration\r\n\r\nBuggy now works automatically inside Kiro — your team doesn't need to run commands manually. Once configured, every file save, every AI-generated edit, and every spec task is automatically analyzed for bugs with zero developer effort.\r\n\r\n### How It Works\r\n\r\nBuggy ships with 7 Kiro hooks that fire on IDE events. When a hook triggers, Kiro's agent calls Buggy's MCP tools behind the scenes, interprets the results, and either reports findings or applies fixes automatically.\r\n\r\n### Hooks (Automatic Bug Detection)\r\n\r\n| Hook | Trigger | What It Does |\r\n|------|---------|--------------|\r\n| `buggy-on-save` | File saved | Analyzes the saved file for bugs immediately |\r\n| `buggy-post-write` | Kiro writes code | Verifies AI-generated code for correctness |\r\n| `buggy-pre-task` | Before spec task execution | Scans relevant files before changes are made |\r\n| `buggy-auto-fix` | Agent completes work | Self-healing loop — re-checks and fixes (max 3 iterations) |\r\n| `buggy-deep-scan` | User-triggered | Full project scan across all source files |\r\n| `buggy-spec-evolution` | After task completion | Verifies new implementations match specifications |\r\n| `buggy-recall-first` | Code-change request submitted | Consults the Watchlist memory (`buggy_recall`) before editing so proven lessons guide the fix |\r\n\r\n### What Developers Experience\r\n\r\n- Ask Kiro to fix something → it first recalls what worked and what failed on that code before\r\n- Save a file → bugs are surfaced in seconds, no command needed\r\n- Kiro writes code → Buggy verifies it before you even review\r\n- Start a spec task → risky files are pre-scanned for existing issues\r\n- Complete a task → implementation is verified against the spec\r\n\r\n### Deploying to Your Team\r\n\r\nCommit the `.kiro/` folder to your repository. Every team member who opens the project in Kiro gets automatic bug detection with no setup:\r\n\r\n```bash\r\ngit add .kiro/\r\ngit commit -m \"Add Buggy hooks and steering files for automatic bug detection\"\r\n```\r\n\r\n### Steering Files (Advanced Workflows)\r\n\r\nBuggy includes 9 steering files that guide Kiro's behavior during debugging workflows. Five are always active (cross-file impact analysis, bug trend tracking, onboarding warnings, core debugging workflow, and the watchlist experience memory), and four activate on demand for PR reviews, git-diff analysis, spec inference, and TypeScript type narrowing suggestions.\r\n\r\nSee the [Usage Guide](docs/USAGE-GUIDE.md) for the full list and customization options.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n> **Note on the name:** this package is published as **`buggy-debugger`**. The\r\n> bare name `buggy` on npm is an unrelated issue tracker, and `buggy-mcp` is\r\n> also taken by an unrelated project — so install `buggy-debugger`. The binaries\r\n> it installs are still called `buggy` and `buggy-mcp`.\r\n\r\n```bash\r\n# Global — gives you the `buggy` (CLI) and `buggy-mcp` (MCP server) commands\r\nnpm install -g buggy-debugger\r\nbuggy --help\r\n\r\n# Or as a project dependency\r\nnpm install buggy-debugger\r\n```\r\n\r\nInstalling straight from the repository also works, and builds itself via the\r\n`prepare` script:\r\n\r\n```bash\r\nnpm install -g github:himanshusaini-afk/buggy\r\n```\r\n\r\nOr clone and build from source:\r\n\r\n```bash\r\ngit clone https://github.com/himanshusaini-afk/buggy.git\r\ncd buggy\r\nnpm install      # installs deps and builds dist/ (prepare script)\r\nnpm link         # optional: expose `buggy` / `buggy-mcp` globally\r\n```\r\n\r\n### Requirements\r\n\r\n- Node.js >= 18.0.0\r\n- Tree-sitter grammars for TypeScript/JavaScript and Python are **bundled** — no separate grammar install needed\r\n- An LSP server for symbol resolution (optional but recommended)\r\n- For Python bug proving: a `python` interpreter on `PATH` (functions are executed in a real Python process)\r\n\r\n## Integration Guide\r\n\r\n### 1. Run the setup wizard\r\n\r\nRun `buggy init` in your project root. It detects your language, asks a few\r\nquestions, and creates:\r\n\r\n- `.debugger.yaml` — configuration tailored to your answers\r\n- `.debugger/` — working directory for the graph database (added to `.gitignore` for you)\r\n\r\nThat's the whole setup. The generated config picks the right grammar, LSP command,\r\nand sandbox runtime for the language you chose, for example:\r\n\r\n```yaml\r\nlanguage: python\r\nparser:\r\n  command: tree-sitter-python\r\nlsp:\r\n  command: pylsp\r\nsandbox:\r\n  runtime: python\r\n  memory_limit_mb: 512\r\n  timeout_seconds: 60\r\n```\r\n\r\n### 2. Adjust later if you want\r\n\r\nEverything remains a plain YAML file you can tune (see the Configuration Reference\r\nbelow), or just re-run `buggy init --force` to regenerate it.\r\n\r\n## Programmatic API\r\n\r\n```typescript\r\nimport { ProofDebugger } from 'buggy-debugger';\r\n\r\nconst debugger_ = new ProofDebugger({\r\n  projectRoot: '/path/to/your/project',\r\n  language: 'typescript', // optional override\r\n  sandbox: { memory_limit_mb: 1024 }, // optional override\r\n});\r\n\r\nawait debugger_.initialize();\r\n\r\n// What do we already know about this code? (what the buggy-recall-first hook uses)\r\nconst prior = debugger_.recall({\r\n  functionId: 'processPayment',\r\n  filePath: 'src/payments.ts',\r\n});\r\nconsole.log(prior.seen_before); // has this exact target burned us before?\r\nconsole.log(prior.lessons);     // ranked lessons — what worked, what was rejected\r\n\r\n// How much experience has accumulated?\r\nconsole.log(debugger_.watchlistStats()); // episodes, distinct lessons, global coverage\r\n\r\n// Investigate a specific function\r\nconst report = await debugger_.investigate({\r\n  functionId: 'processPayment',\r\n  filePath: 'src/payments.ts',\r\n  specification: {\r\n    preconditions: ['amount > 0'],\r\n    postconditions: ['result.status === \"success\" || result.status === \"failed\"'],\r\n    parameters: [{ name: 'amount', type: 'number' }],\r\n    return_type: 'PaymentResult',\r\n  },\r\n});\r\n\r\n// Access results\r\nconsole.log(report.status);\r\n// → 'confirmed_and_repaired' | 'confirmed_no_repair' | 'unconfirmed' | 'halted'\r\n\r\nconsole.log(report.proof);           // The proof-of-failure certificate\r\nconsole.log(report.approved_patches); // Patches that passed overfitting check\r\n\r\n// Run a single parse\r\nconst parseResult = await debugger_.parse('src/payments.ts');\r\nconsole.log(parseResult.cst);    // Full concrete syntax tree\r\nconsole.log(parseResult.errors); // Syntax errors with locations\r\n\r\n// Query the semantic graph\r\nconst { callees, edges } = await debugger_.queryCallees('processPayment');\r\n\r\n// Query a specific node\r\nconst node = debugger_.queryNode('node_42');\r\n\r\n// Get file subgraph\r\nconst { nodes, edges: fileEdges } = debugger_.queryFileGraph('src/payments.ts');\r\n\r\n// Did past fixes actually hold?\r\nconst retro = debugger_.retrospect();\r\nconsole.log(retro.improvement_score);  // share of fixed lessons that held, or null\r\nconsole.log(retro.regressions);        // defects proven again AFTER being repaired\r\nconsole.log(retro.dead_ends);          // approaches that keep getting rejected\r\n\r\n// What guardrails is this project missing?\r\nconst advice = debugger_.suggestCapabilities();\r\nfor (const s of advice.suggestions) {\r\n  console.log(s.priority, s.kind, s.title, '→', s.target_path);\r\n  console.log(s.rationale);            // grounded in observed episodes\r\n}\r\ndebugger_.applyCapability('steering-dead-ends');  // writes the file; never clobbers\r\n\r\n// Check investigation status\r\nconst status = debugger_.getStatus(report.id);\r\n\r\n// Halt a running investigation\r\ndebugger_.halt(report.id);\r\n\r\n// Shutdown (closes DB, LSP connections)\r\nawait debugger_.shutdown();\r\n```\r\n\r\n### ProofDebugger Options\r\n\r\n```typescript\r\ninterface ProofDebuggerOptions {\r\n  projectRoot: string;        // Required: path to your project\r\n  language?: string;          // Override auto-detected language\r\n  configPath?: string;        // Custom .debugger.yaml path\r\n  dbPath?: string;            // Custom database path\r\n  sandbox?: {\r\n    memory_limit_mb?: number;\r\n    timeout_seconds?: number;\r\n    egress_policy?: 'deny' | 'allow_host_only';\r\n  };\r\n  probe?: {\r\n    search_budget?: number;\r\n    max_refinement_iterations?: number;\r\n  };\r\n}\r\n```\r\n\r\n## CLI Reference\r\n\r\n### `buggy init`\r\n\r\nSets up Buggy for the current project. Detects the primary language from your\r\nsource files, then asks a few questions (language, search effort, per-function\r\ntimeout, memory scope, gitignore) — each with a default, so pressing Enter through\r\nthem is fine. Writes a tailored `.debugger.yaml` plus the `.debugger/` directory.\r\n\r\n```bash\r\nbuggy init                          # interactive\r\nbuggy init --yes                    # accept detected defaults, no prompts\r\nbuggy init --language python --yes  # force the language (typescript|javascript|python)\r\nbuggy init --force                  # regenerate over an existing config\r\nbuggy init --json                   # machine-readable; never prompts\r\n```\r\n\r\nPrompts are skipped automatically when stdin is not a terminal, so this is safe in\r\nCI.\r\n\r\n### `buggy analyze <file>`\r\n\r\nParses a file using Tree-sitter and displays the semantic graph summary.\r\n\r\n```bash\r\nbuggy analyze src/payments.ts\r\nbuggy analyze src/payments.ts --verbose   # Show CST depth-2 summary\r\nbuggy analyze src/payments.ts --json      # Full JSON output\r\n```\r\n\r\n### `buggy investigate <function> --file <path>`\r\n\r\nRuns the full investigation pipeline (Parse → Prove → Repair → Classify) on a function.\r\n\r\n```bash\r\nbuggy investigate processPayment --file src/payments.ts\r\nbuggy investigate processPayment -f src/payments.ts --verbose\r\nbuggy investigate processPayment -f src/payments.ts --json\r\n```\r\n\r\n### `buggy status <id>`\r\n\r\nShows the current status of a running or completed investigation.\r\n\r\n```bash\r\nbuggy status inv_1234567890_abc1234\r\nbuggy status inv_1234567890_abc1234 --json\r\n```\r\n\r\n### `buggy halt <id>`\r\n\r\nHalts a running investigation, preserving intermediate results.\r\n\r\n```bash\r\nbuggy halt inv_1234567890_abc1234\r\n```\r\n\r\n### `buggy retrospect`\r\n\r\nReports whether the experience memory is actually working. Reads each lesson's\r\nepisodes as a timeline and tells you which fixes **held**, which **regressed**\r\n(the defect was proven again after being repaired), which defects never got an\r\naccepted fix, which approaches are repeated dead ends, and which files are\r\nhotspots.\r\n\r\n```bash\r\nbuggy retrospect\r\nbuggy retrospect --verbose   # also list every dead end\r\nbuggy retrospect --json\r\n```\r\n\r\nA regression is the highest-value signal here: the memory existed, the agent had\r\naccess to it, and the defect still came back. That usually means the patch\r\naddressed the triggering input rather than the cause.\r\n\r\n### `buggy suggest`\r\n\r\nProposes new hooks, steering rules and skills derived from this project's own\r\ndefect history. Each proposal carries the evidence that motivated it and the\r\nfinished file content, so accepting one is a write rather than a design exercise.\r\n\r\n```bash\r\nbuggy suggest                                  # list proposals\r\nbuggy suggest --verbose                         # include the full file each would write\r\nbuggy suggest --apply steering-dead-ends        # write one\r\nbuggy suggest --apply steering-dead-ends --force  # overwrite an existing file\r\n```\r\n\r\nNothing is written without `--apply`, and an existing file is never overwritten\r\nwithout `--force` — these artefacts are meant to be hand-edited afterwards.\r\n\r\n### Global Options\r\n\r\n| Flag | Description |\r\n|------|-------------|\r\n| `--json` | Output results as JSON (machine-readable) |\r\n| `--verbose` | Enable detailed logging and extended output |\r\n| `--help`, `-h` | Show help message |\r\n\r\n## Configuration Reference\r\n\r\nThe `.debugger.yaml` file controls all aspects of the debugger. Here's the full schema:\r\n\r\n```yaml\r\n# Required — selects the Tree-sitter grammar AND the execution runtime\r\nlanguage: typescript    # typescript | javascript | python\r\n\r\n# Parser configuration\r\nparser:\r\n  command: tree-sitter-typescript  # Tree-sitter grammar to use\r\n  grammar_path: ./custom.wasm     # Optional: path to custom grammar\r\n\r\n# Language Server Protocol\r\nlsp:\r\n  command: typescript-language-server\r\n  initialization_options:          # Optional: passed to LSP on init\r\n    preferences:\r\n      includeInlayParameterNameHints: \"all\"\r\n\r\n# Sandbox execution environment\r\nsandbox:\r\n  runtime: node                    # Execution runtime (node, python, deno, bun)\r\n  memory_limit_mb: 512             # 64-8192 MB\r\n  timeout_seconds: 60              # 1-300 seconds\r\n  egress_policy: deny              # deny | allow_host_only\r\n\r\n# Oracle violation detectors\r\noracles:\r\n  timeout_threshold_seconds: 10    # 1-300 seconds\r\n  crash_detection: true\r\n  overflow_detection: true\r\n  determinism_check_count: 5       # 1-100 runs\r\n\r\n# PROBE loop configuration\r\nprobe:\r\n  search_budget: 100               # Max property candidates\r\n  max_refinement_iterations: 10    # Max iterations per property\r\n\r\n# Experience memory — see \"Learning Across Runs\"\r\nwatchlist:\r\n  enabled: true                    # Set false to record nothing\r\n  scope: layered                   # local | team | global | layered\r\n\r\n# Optional: custom plug-ins (parsed and validated, but not yet loaded)\r\nplugs:\r\n  parsing: ./plugs/parser\r\n  oracles:\r\n    - ./plugs/memory-oracle\r\n  repair: ./plugs/repair-strategy\r\n  sandbox_executor: ./plugs/sandbox\r\n```\r\n\r\n### Defaults\r\n\r\nOnly these have schema defaults. Everything else above is required — and `buggy\r\ninit` writes all of it for you, so hand-editing is optional.\r\n\r\n| Field | Default |\r\n|-------|---------|\r\n| `lsp.initialization_options` | `{}` |\r\n| `sandbox.egress_policy` | `deny` |\r\n| `plugs` | `undefined` (no custom plugs) |\r\n| `watchlist.enabled` | `true` |\r\n| `watchlist.scope` | `layered` |\r\n\r\n`sandbox.memory_limit_mb` is validated and recorded but **not enforced** —\r\nOS-level memory capping needs the Firecracker executor, which is not wired.\r\n\r\n## Architecture Overview\r\n\r\nThe system consists of five specialized agents coordinated by an orchestrator:\r\n\r\n```\r\n┌──────────────────────────────────────────────────────────────┐\r\n│                     Agent Orchestrator                        │\r\n│  (Coordinates sequential pipeline + sandbox concurrency)     │\r\n└─────────┬──────────┬──────────────┬──────────────┬───────────┘\r\n          │          │              │              │\r\n    ┌─────▼─────┐ ┌─▼──────────┐ ┌▼──────────┐ ┌─▼───────────┐\r\n    │  Parser   │ │ Bug-Proving │ │  Repair   │ │ Classifier  │\r\n    │  Agent    │ │   Agent     │ │  Agent    │ │   Agent     │\r\n    └───────────┘ └─────────────┘ └───────────┘ └─────────────┘\r\n          │              │              │              │\r\n          └──────────────┴──────────────┴──────────────┘\r\n                              │\r\n                    ┌─────────▼─────────┐\r\n                    │   Sandbox Agent   │\r\n                    │  (up to 4 conc.)  │\r\n                    └───────────────────┘\r\n```\r\n\r\n**Pipeline flow:**\r\n1. **Parser Agent** — Tree-sitter CST parsing, symbol resolution via LSP\r\n2. **Bug-Proving Agent** — Edge-case-first execution fuzzing + five oracles → proof-of-failure certificate certified on admissibility, soundness and reproducibility\r\n3. **Repair Agent** — Trigger-derived patch generation with TypeScript and Python dialects\r\n4. **Classifier Agent** — PRISM-APCC overfitting detection using 66-dimensional AST difference vectors\r\n5. **Sandbox Agent** — Firecracker-backed isolated execution, available on-demand. **Wired as a stub today** — the live execution boundary is an OS child process\r\n\r\nPhase 2 is a gate: with no certificate the run ends as `unconfirmed`, and no\r\nrepair is attempted. For what each phase does and does not include, see\r\n[Features → What runs today](docs/FEATURES.md#what-runs-today).\r\n\r\n**Data layer:**\r\n- SQLite graph database (WAL mode) stores CST nodes, edges, symbol resolutions, proofs, and patches\r\n- All inter-agent data flows through typed MCP tool calls\r\n\r\n## Learning Across Runs\r\n\r\nBuggy keeps a record of its own history and acts on it.\r\n\r\n**The Watchlist** records one episode per investigation: the triggering input,\r\nevery patch that was rejected and *how* it failed, and the one that worked.\r\nVerified episodes become lessons, promoted through three tiers — private to you,\r\ncommitted for the repo, and (once corroborated across two projects, sanitized of\r\nall code and values) reused across everything you work on. `buggy_recall` and the\r\n`buggy-recall-first` hook feed those lessons back before code gets edited.\r\n\r\n**The Retrospective** (`buggy retrospect`) asks whether any of that helped. It\r\nreads each lesson as a timeline and separates fixes that held from fixes that\r\n**regressed** — proven again after being repaired. It also collapses repeated\r\nrejection reasons into named dead ends, so the same rejected approach is not\r\nretried indefinitely.\r\n\r\n**The Advisor** (`buggy suggest`) closes the loop. When a defect class keeps\r\nrecurring, the useful response is usually not another patch but a new guardrail,\r\nso the advisor proposes hooks, steering rules and skills derived from the\r\nproject's own evidence — a regression guard scoped to the files where fixes did\r\nnot stick, a dead-ends steering file, a language-specific defect guide rendered\r\nin the right syntax, a triage skill for defects where every patch was rejected,\r\nand a skill for converting proof certificates into regression tests. Every\r\nproposal names the episodes that motivated it. Nothing is written until you\r\naccept it.\r\n\r\n## Extending with Custom Plugs\r\n\r\nThe plug system lets you override default agent behavior without modifying core code.\r\n\r\n### Creating a Parser Plug\r\n\r\n```typescript\r\nimport type { ParsingPlug } from 'buggy-debugger';\r\n\r\nexport const myParser: ParsingPlug = {\r\n  name: 'my-custom-parser',\r\n  parse(source: string, filePath: string) {\r\n    // Your custom parsing logic\r\n    return { cst, errors, duration_ms, file_path: filePath };\r\n  },\r\n};\r\n```\r\n\r\n### Creating an Oracle Plug\r\n\r\n```typescript\r\nimport type { OraclePlug } from 'buggy-debugger';\r\n\r\nexport const memoryOracle: OraclePlug = {\r\n  name: 'memory-leak-detector',\r\n  detect(executionResult) {\r\n    // Analyze execution for memory leaks\r\n    return violations;\r\n  },\r\n};\r\n```\r\n\r\n### Creating a Repair Plug\r\n\r\n```typescript\r\nimport type { RepairPlug } from 'buggy-debugger';\r\n\r\nexport const mlRepair: RepairPlug = {\r\n  name: 'ml-based-repair',\r\n  generatePatches(proof, target) {\r\n    // ML-based patch generation\r\n    return patches;\r\n  },\r\n};\r\n```\r\n\r\n### Registering Plugs\r\n\r\nAdd plug paths to `.debugger.yaml`:\r\n\r\n```yaml\r\nplugs:\r\n  parsing: ./plugs/my-custom-parser\r\n  oracles:\r\n    - ./plugs/memory-leak-detector\r\n  repair: ./plugs/ml-based-repair\r\n```\r\n\r\n> **Not yet wired.** The plug types are exported and the registry is implemented\r\n> and tested, but nothing in the live pipeline loads it — the `plugs:` key is\r\n> parsed and validated, then ignored. The interfaces are stable enough to write\r\n> against; they just are not called yet.\r\n\r\n## Development\r\n\r\n```bash\r\n# Build\r\nnpm run build\r\n\r\n# Run tests\r\nnpm test\r\n\r\n# Run specific test suites\r\nnpm run test:unit\r\nnpm run test:properties\r\nnpm run test:integration\r\n\r\n# Run the CLI locally\r\nnode dist/cli.js --help\r\n\r\n# Smoke test the published artefact (packs, installs into a clean\r\n# project, exercises every entry point). Runs automatically on publish.\r\nnpm run smoke\r\n```\r\n\r\n### The smoke test\r\n\r\n`npm run smoke` is the gate that the unit suite cannot be. The suite runs against\r\n`src/` with this repo's own `.npmrc` and `tsconfig`, so it passes happily while\r\nthe *published* artefact is broken. The smoke test packs the tarball exactly as\r\n`npm publish` would, installs it into a throwaway project with **default** npm\r\nsettings, and checks 15 things from the consumer's side:\r\n\r\n- the tarball builds, and leaks no `.env` / `.npmrc` / `.kiro` / credentials\r\n- it installs with strict peer resolution (the repo's `legacy-peer-deps` is not published)\r\n- both `buggy` and `buggy-mcp` bin shims link\r\n- every CLI command appears in `--help`; `init`, `analyze` and `investigate` work\r\n- `--json` stdout is parseable — a regression guard, since config diagnostics once went to stdout and corrupted it\r\n- `retrospect` and `suggest` read back the history the investigation just recorded\r\n- the MCP server answers `initialize` + `tools/list` over stdio with all 10 tools\r\n- `import { ProofDebugger } from 'buggy-debugger'` works end to end\r\n- `dist/index.d.ts` ships\r\n\r\nIt is wired to `prepublishOnly`, so `npm publish` cannot proceed unless it is\r\ngreen. Use `--keep` to leave the temp project behind for inspection.\r\n\r\n### Shipping a change\r\n\r\nEvery change ships as a complete unit: code, README, and the public site in\r\n`site/`. The full checklist lives in\r\n[`.kiro/steering/release-checklist.md`](.kiro/steering/release-checklist.md)\r\nand is loaded automatically when working in Kiro.\r\n\r\nThe short version:\r\n\r\n1. Update this README if the change is user-visible — CLI, API, MCP tools, config, or the \"what runs today\" split.\r\n2. Update `site/` to match. It has no build step; the stat counters and the MCP tool list go stale silently.\r\n3. `npm run build && npx vitest run`, then commit specific files and push to the current branch.\r\n4. Confirm the [Pages deploy](https://github.com/himanshusaini-afk/buggy/actions) went green. Only pushes touching `site/**` trigger it.\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","homepage":"https://himanshusaini-afk.github.io/buggy/","keywords":["debugger","bug-detection","proof-carrying","automated-repair","mcp","mcp-server","model-context-protocol","static-analysis","fuzzing","property-based-testing","ai-coding","developer-tools"],"repository":{"url":"git+https://github.com/himanshusaini-afk/buggy.git","type":"git"},"author":{"name":"himanshusaini-afk"},"bugs":{"url":"https://github.com/himanshusaini-afk/buggy/issues"},"license":"MIT"}