bugzero 0.0.32 → 0.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
 
2
- > bugzero@0.0.32 build /home/runner/work/Bugzero/Bugzero/apps/bugzero
2
+ > bugzero@0.0.34 build /home/runner/work/Bugzero/Bugzero/apps/bugzero
3
3
  > tsup src/index.ts --format cjs --dts
4
4
 
5
5
  CLI Building entry: src/index.ts
@@ -8,7 +8,7 @@
8
8
  CLI Target: es2022
9
9
  CJS Build start
10
10
  CJS dist/index.js 77.80 KB
11
- CJS ⚡️ Build success in 32ms
11
+ CJS ⚡️ Build success in 57ms
12
12
  DTS Build start
13
- DTS ⚡️ Build success in 1160ms
13
+ DTS ⚡️ Build success in 1273ms
14
14
  DTS dist/index.d.ts 20.00 B
package/README.md CHANGED
@@ -1,14 +1,35 @@
1
- # BugZero
1
+ <div align="center">
2
+
3
+ # 🐛 BugZero
4
+
5
+ ### Your build breaks. BugZero fixes it. Automatically.
2
6
 
3
7
  [![npm version](https://img.shields.io/npm/v/bugzero.svg?style=flat-square)](https://www.npmjs.com/package/bugzero)
8
+ [![npm downloads](https://img.shields.io/npm/dm/bugzero.svg?style=flat-square)](https://www.npmjs.com/package/bugzero)
9
+ [![CI](https://img.shields.io/github/actions/workflow/status/Saksham1800t/Bugzero/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/Saksham1800t/Bugzero/actions/workflows/ci.yml)
4
10
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
5
11
  [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?style=flat-square)](https://nodejs.org)
6
12
  [![pnpm](https://img.shields.io/badge/maintained%20with-pnpm-cc00ff.svg?style=flat-square)](https://pnpm.io/)
7
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/Saksham1800t)
8
13
 
9
- **BugZero** is an autonomous, AI-powered CLI tool for automatic build error detection and repair. It runs your build pipeline, parses compiler and linter output, invokes an LLM to generate a surgical code fix, applies it safely with a backup, and re-runs validation — looping until your project builds successfully or the attempt limit is reached.
14
+ **BugZero** is an autonomous, AI-powered CLI that detects and repairs build, lint, and test failures — locally or as a GitHub Action that opens the fix as a pull request.
15
+
16
+ <img src="https://raw.githubusercontent.com/Saksham1800t/Bugzero/main/apps/bugzero/demo.svg" alt="Animated terminal demo of bugzero rescue detecting and fixing a TypeScript build error" width="700" />
17
+
18
+ <sub>Illustrative animation of a <code>bugzero rescue</code> run using the tool's real log output format.</sub>
19
+
20
+ </div>
21
+
22
+ ---
23
+
24
+ ## Quick Start
25
+
26
+ ```bash
27
+ npm install -g bugzero
28
+ export OPENROUTER_API_KEY="your_openrouter_api_key_here"
29
+ bugzero rescue --path /path/to/your/project
30
+ ```
10
31
 
11
- Built for developers who want zero-downtime repair cycles, automated CI/CD recovery, and production-grade error resolution without manual debugging.
32
+ That's it — BugZero runs your build, diagnoses the failure, generates a patch, applies it, and re-verifies, looping until it's green or it runs out of attempts.
12
33
 
13
34
  ---
14
35
 
@@ -16,52 +37,53 @@ Built for developers who want zero-downtime repair cycles, automated CI/CD recov
16
37
 
17
38
  Modern applications fail at build and deployment time for reasons that are repetitive, predictable, and ultimately fixable by a knowledgeable agent. BugZero bridges the gap between raw compiler output and working code — automatically.
18
39
 
19
- - **No more debugging the same TypeScript error twice.** The agent reads the stack trace, finds the file, generates the fix, and verifies it.
20
- - **Safe by design.** Every file modified gets a `.opspilot.bak` backup before any change is applied.
21
- - **Model agnostic.** Works with DeepSeek, Claude, Gemini, GPT-4o, Llama, or any model available on OpenRouter.
22
- - **Feedback loop included.** The LangGraph state machine retries intelligently until the build passes or the max attempts threshold is hit.
40
+ - **No more debugging the same TypeScript error twice.** The agent reads the error, finds the file, generates the fix, and verifies it.
41
+ - **Safe by design.** Every modified file gets a `.opspilot.bak` backup, and a multi-file fix is applied and rolled back as one atomic unit.
42
+ - **Forgiving, not brittle.** If the AI's suggested patch doesn't match the file byte-for-byte, BugZero falls back to whitespace-normalized and similarity-scored matching before giving up.
43
+ - **Model agnostic.** DeepSeek, Claude, Gemini, GPT-4o, Llama, or any model on OpenRouter.
44
+ - **CI-native.** Run it as a GitHub Action instead of a local CLI, and let it open the fix as a PR.
23
45
 
24
46
  ---
25
47
 
26
- ## How it Works
48
+ ## How It Works
27
49
 
28
50
  ```
29
51
  bugzero rescue
30
- |
31
- v
52
+ │
53
+ ▼
32
54
  Run Build + Lint + Tests
33
- |
34
- v
35
- Any failures? ---- No ---> Build already passing. Exit cleanly.
36
- |
55
+ │
56
+ ▼
57
+ Any failures? ── No ──▶ Build already passing. Exit cleanly.
58
+ │
37
59
  Yes
38
- |
39
- v
60
+ │
61
+ ▼
40
62
  Capture and parse error logs
41
- |
42
- v
63
+ │
64
+ ▼
43
65
  Prompt selected LLM via LangGraph Agent
44
- |
45
- v
46
- Parse structured fix suggestion (JSON)
47
- |
48
- v
49
- Apply search-and-replace patch (with .bak backup)
50
- |
51
- v
66
+ │
67
+ ▼
68
+ Parse structured fix suggestion (one or more file patches)
69
+ │
70
+ ▼
71
+ Apply patches atomically (exact → whitespace → similarity match, with .bak backups)
72
+ │
73
+ ▼
52
74
  Re-run build to verify the fix
53
- |
54
- v
55
- Build fixed? --- Yes ---> Print fix details. Exit success.
56
- |
75
+ │
76
+ ▼
77
+ Build fixed? ── Yes ──▶ Print fix details. Exit success.
78
+ │
57
79
  No
58
- |
59
- v
60
- Max attempts reached? -- Yes ---> Exit with failure logs.
61
- |
80
+ │
81
+ ▼
82
+ Max attempts reached? ── Yes ──▶ Exit with failure logs.
83
+ │
62
84
  No
63
- |
64
- +-------------------> Prompt LLM again (next attempt)
85
+ │
86
+ └──────────────────▶ Prompt LLM again (next attempt)
65
87
  ```
66
88
 
67
89
  ---
@@ -73,19 +95,59 @@ bugzero rescue
73
95
  | Autonomous repair loop | Runs analyze, patch, verify in a stateful LangGraph graph |
74
96
  | Multi-model support | DeepSeek, Claude, GPT-4o, Gemini, Llama via OpenRouter |
75
97
  | Framework detection | Automatically identifies your project's tooling setup |
98
+ | **Multi-file patches** | A single fix attempt can edit several files at once, applied atomically — if any file's patch fails, every file touched in that attempt is rolled back |
99
+ | **Fuzzy patch matching** | Falls back from exact match to whitespace-normalized and similarity-scored matching when the AI's snippet doesn't match the file verbatim |
76
100
  | Safe file patching | Every modified file receives a `.opspilot.bak` backup |
77
- | Fuzzy patch matching | Falls back from exact match to whitespace-normalized and similarity-scored matching when the AI's snippet doesn't match the file verbatim |
78
- | Multi-file patches | A single fix attempt can edit several files at once, applied atomically — if any file's patch fails, every file touched in that attempt is rolled back |
79
101
  | Error type parsing | Parses TypeScript, ESLint, and Jest error formats |
80
102
  | Dry-run mode | Analyze and report without writing any files |
81
103
  | Local model config | Save preferred model to `.bugzerorc` per project |
82
- | Markdown Reports | Automatically generates a detailed Markdown report at `bugzero-report.md` in the target project path and outputs clickable file URLs in the terminal to open them instantly. |
104
+ | Markdown Reports | Auto-generates a detailed `bugzero-report.md` with error logs, model name, token usage, and code diffs — plus a clickable link straight to your terminal |
105
+ | **GitHub Action mode** | Run the same repair loop in CI and open a pull request with the fix instead of patching a local checkout — see below |
106
+
107
+ ---
108
+
109
+ ## GitHub Action Mode
110
+
111
+ Instead of running BugZero on your machine, run it in CI: when a check fails, it opens a pull request with the fix instead of patching your local checkout.
112
+
113
+ ```yaml
114
+ name: BugZero Auto-Fix
115
+
116
+ on:
117
+ workflow_run:
118
+ workflows: ["CI"]
119
+ types: [completed]
120
+
121
+ jobs:
122
+ fix:
123
+ if: github.event.workflow_run.conclusion == 'failure'
124
+ runs-on: ubuntu-latest
125
+ permissions:
126
+ contents: write
127
+ pull-requests: write
128
+ steps:
129
+ - uses: actions/checkout@v4
130
+ with:
131
+ ref: ${{ github.event.workflow_run.head_branch }}
132
+
133
+ - uses: pnpm/action-setup@v4 # or npm/yarn — whatever installs your project's deps
134
+ - run: pnpm install
135
+
136
+ - uses: Saksham1800t/Bugzero@v1
137
+ with:
138
+ github-token: ${{ secrets.GITHUB_TOKEN }}
139
+ base-branch: ${{ github.event.workflow_run.head_branch }}
140
+ env:
141
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
142
+ ```
143
+
144
+ It commits every changed file as a single atomic commit via the GitHub API — no local git push needed — then opens the PR. Full input/output reference: [`apps/github-action`](https://github.com/Saksham1800t/Bugzero/tree/main/apps/github-action).
83
145
 
84
146
  ---
85
147
 
86
148
  ## Installation
87
149
 
88
- Install globally from the NPM registry:
150
+ Install globally from the npm registry:
89
151
 
90
152
  ```bash
91
153
  npm install -g bugzero
@@ -130,7 +192,8 @@ Run the full AI-powered repair loop. Detects build failures, generates precise c
130
192
  bugzero rescue --path /path/to/your/project
131
193
  ```
132
194
 
133
- Options:
195
+ <details>
196
+ <summary><strong>Options for <code>rescue</code></strong></summary>
134
197
 
135
198
  | Flag | Short | Default | Description |
136
199
  |---|---|---|---|
@@ -138,6 +201,8 @@ Options:
138
201
  | `--max-attempts <n>` | `-n` | `3` | Maximum AI fix iterations before giving up |
139
202
  | `--dry-run` | | `false` | Analyze only — no files will be written |
140
203
 
204
+ </details>
205
+
141
206
  ### `bugzero vibe`
142
207
  Interactively select which AI model to use. Fetches the current model list from OpenRouter, lets you pick one, and saves the selection to a local `.bugzerorc` config file.
143
208
 
@@ -145,13 +210,17 @@ Interactively select which AI model to use. Fetches the current model list from
145
210
  bugzero vibe
146
211
  ```
147
212
 
148
- Supported models (curated list, plus custom entry):
213
+ <details>
214
+ <summary><strong>Supported models</strong> (curated list, plus custom entry)</summary>
215
+
149
216
  - DeepSeek V3 / DeepSeek R1
150
217
  - Anthropic Claude 3.5 Sonnet
151
218
  - Google Gemini 2.5 Pro / Flash
152
219
  - OpenAI GPT-4o
153
220
  - Meta Llama 3.3 Instruct
154
221
 
222
+ </details>
223
+
155
224
  ---
156
225
 
157
226
  ## Configuration
@@ -170,33 +239,45 @@ This file is created automatically when you run `bugzero vibe`.
170
239
 
171
240
  ## Reports
172
241
 
173
- Every time you run `bugzero hunt` or `bugzero rescue`, a detailed Markdown report is generated at `bugzero-report.md` in the target project directory. The tool prints a clickable absolute file URL and path directly to your terminal. Clicking the link instantly opens the report inside your active IDE editor with full syntax styling and Markdown Preview. The report includes:
242
+ Every time you run `bugzero hunt` or `bugzero rescue`, a detailed Markdown report is generated at `bugzero-report.md` in the target project directory. The tool prints a clickable absolute file URL and path directly to your terminal.
243
+
174
244
  - **Pipeline Summary:** Clear status checklist of your project's Build, Lint, and Test suites.
175
245
  - **Detailed Error Outputs:** Full error logs from any failing checks.
176
246
  - **AI Brain Details:** The exact OpenRouter model used.
177
247
  - **Token Usage:** Accumulated prompt and completion tokens used for the run.
178
- - **Applied Fixes (for rescue):** The root cause, explanation, and before/after search-replace code diffs of any patches applied.
248
+ - **Applied Fixes (for rescue):** The root cause, explanation, and before/after diffs for every file patched.
179
249
 
180
250
  ---
181
251
 
182
- ## Development Setup
252
+ ## Error Handling
183
253
 
184
- Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo.
254
+ BugZero provides clear, actionable output for common failure modes:
255
+
256
+ | Error | Message |
257
+ |---|---|
258
+ | Invalid API key (401) | Prompts you to check your `OPENROUTER_API_KEY` |
259
+ | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance |
260
+ | Model not found | Displays the invalid model ID and suggests running `bugzero vibe` |
261
+ | Patch not applied | Reports exact mismatch between AI suggestion and file content, after exhausting exact, whitespace, and fuzzy matching |
262
+ | Max attempts reached | Exits cleanly with the last error log for manual review |
263
+
264
+ ---
265
+
266
+ <details>
267
+ <summary><strong>Development Setup</strong> (contributing to BugZero itself)</summary>
268
+
269
+ Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo, with a Vitest test suite and GitHub Actions CI.
185
270
 
186
271
  ### Prerequisites
187
272
  - Node.js 18 or later
188
273
  - pnpm
189
274
 
190
- ### Install
275
+ ### Install & build
191
276
 
192
277
  ```bash
193
278
  pnpm install
194
- ```
195
-
196
- ### Build all packages
197
-
198
- ```bash
199
279
  pnpm build
280
+ pnpm test
200
281
  ```
201
282
 
202
283
  ### Run commands locally without installing globally
@@ -207,33 +288,22 @@ pnpm rescue --path ./demo-project
207
288
  pnpm vibe
208
289
  ```
209
290
 
210
- ### Monorepo package structure
291
+ ### Monorepo structure
211
292
 
212
293
  | Package | Role |
213
294
  |---|---|
214
- | `packages/cli` | CLI entrypoint (Commander) |
295
+ | `apps/bugzero` | CLI entrypoint (Commander) — the package published to npm |
296
+ | `apps/github-action` | GitHub Action wrapper — runs the repair loop in CI and opens a fix PR |
215
297
  | `packages/core` | Orchestrates build and fix flow |
216
298
  | `packages/agents` | LangGraph state machine (analyze, patch, verify) |
217
299
  | `packages/ai-provider` | OpenRouter HTTP client |
218
300
  | `packages/analyzers` | Runs build/lint/test and parses output |
219
- | `packages/patcher` | Applies search-and-replace patches with backup |
301
+ | `packages/patcher` | Applies search-and-replace patches — with atomic multi-file support and fuzzy-match fallback |
220
302
  | `packages/prompts` | LLM prompt templates |
221
303
  | `packages/config` | Env loading and local `.bugzerorc` config store |
222
304
  | `packages/shared` | Shared TypeScript types |
223
305
 
224
- ---
225
-
226
- ## Error Handling
227
-
228
- BugZero provides clear, actionable output for common failure modes:
229
-
230
- | Error | Message |
231
- |---|---|
232
- | Invalid API key (401) | Prompts you to check your `OPENROUTER_API_KEY` |
233
- | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance |
234
- | Model not found | Displays the invalid model ID and suggests running `bugzero vibe` |
235
- | Patch not applied | Reports exact mismatch between AI suggestion and file content |
236
- | Max attempts reached | Exits cleanly with the last error log for manual review |
306
+ </details>
237
307
 
238
308
  ---
239
309
 
@@ -252,4 +322,3 @@ BugZero provides clear, actionable output for common failure modes:
252
322
  If BugZero saved you debugging hours in production or deployment pipelines, consider buying the author a coffee.
253
323
 
254
324
  [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/saksham_)
255
-
package/demo.svg ADDED
@@ -0,0 +1,81 @@
1
+ <svg viewBox="0 0 700 520" xmlns="http://www.w3.org/2000/svg" font-family="SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace">
2
+ <title>bugzero rescue demo</title>
3
+ <desc>Illustrative animation of "bugzero rescue" fixing a small TypeScript error. Log lines are the tool's real output format; the example error is a stand-in, not a captured recording.</desc>
4
+
5
+ <style>
6
+ text { font-size: 13px; }
7
+ .prompt { fill: #58a6ff; }
8
+ .out { fill: #c9d1d9; }
9
+ .ok { fill: #3fb950; }
10
+ .dim { fill: #8b949e; }
11
+ .dot { }
12
+ .titlebar-label { fill: #8b949e; font-size: 12px; }
13
+
14
+ @keyframes gA { 0% { opacity: 0; } 2% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
15
+ @keyframes gB { 0%, 6% { opacity: 0; } 9% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
16
+ @keyframes gC { 0%, 16% { opacity: 0; } 19% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
17
+ @keyframes gD { 0%, 26% { opacity: 0; } 29% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
18
+ @keyframes gE { 0%, 38% { opacity: 0; } 41% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
19
+ @keyframes gF { 0%, 48% { opacity: 0; } 50% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
20
+ @keyframes gG { 0%, 56% { opacity: 0; } 59% { opacity: 1; } 90% { opacity: 1; } 97% { opacity: 0; } 100% { opacity: 0; } }
21
+
22
+ .groupA { animation: gA 14s ease-in-out infinite; }
23
+ .groupB { animation: gB 14s ease-in-out infinite; }
24
+ .groupC { animation: gC 14s ease-in-out infinite; }
25
+ .groupD { animation: gD 14s ease-in-out infinite; }
26
+ .groupE { animation: gE 14s ease-in-out infinite; }
27
+ .groupF { animation: gF 14s ease-in-out infinite; }
28
+ .groupG { animation: gG 14s ease-in-out infinite; }
29
+ </style>
30
+
31
+ <rect x="0" y="0" width="700" height="520" rx="10" fill="#0d1117" />
32
+ <rect x="0" y="0" width="700" height="34" rx="10" fill="#161b22" />
33
+ <rect x="0" y="24" width="700" height="10" fill="#161b22" />
34
+
35
+ <circle class="dot" cx="20" cy="17" r="6" fill="#ff5f56" />
36
+ <circle class="dot" cx="40" cy="17" r="6" fill="#ffbd2e" />
37
+ <circle class="dot" cx="60" cy="17" r="6" fill="#27c93f" />
38
+ <text class="titlebar-label" x="350" y="21" text-anchor="middle">bugzero rescue</text>
39
+
40
+ <g class="groupA">
41
+ <text class="prompt" x="18" y="54">$ bugzero rescue --path ./demo-project</text>
42
+ </g>
43
+
44
+ <g class="groupB">
45
+ <text class="out" x="18" y="83">🤖 BugZero Fix</text>
46
+ <text class="out" x="18" y="102"> Path: ./demo-project</text>
47
+ <text class="out" x="18" y="121"> Framework: typescript</text>
48
+ <text class="out" x="18" y="140"> Max attempts: 3</text>
49
+ </g>
50
+
51
+ <g class="groupC">
52
+ <text class="out" x="18" y="169">[BugZero] Running validation pipeline in: ./demo-project</text>
53
+ <text class="out" x="18" y="188">[BugZero] Running build...</text>
54
+ <text class="out" x="18" y="207">[BugZero] Detected 1 error(s) (type: typescript)</text>
55
+ </g>
56
+
57
+ <g class="groupD">
58
+ <text class="out" x="18" y="236">[BugZero] Attempt 1/3 — asking AI…</text>
59
+ </g>
60
+
61
+ <g class="groupE">
62
+ <text class="out" x="18" y="265">[BugZero] Patching 1 file: src/sum.ts</text>
63
+ <text class="out" x="18" y="284">[BugZero] Reason: Fixed subtraction typo in the sum() function</text>
64
+ <text class="out" x="18" y="303">[BugZero] Backup saved to: src/sum.ts.opspilot.bak</text>
65
+ <text class="out" x="18" y="322">[BugZero] Re-running validation pipeline to verify fix…</text>
66
+ </g>
67
+
68
+ <g class="groupF">
69
+ <text class="ok" x="18" y="351">[BugZero] ✅ Validation succeeded!</text>
70
+ </g>
71
+
72
+ <g class="groupG">
73
+ <text class="dim" x="18" y="380">──────────────────────────────────────────────</text>
74
+ <text class="ok" x="18" y="399">✅ Build fixed after 1 attempt(s)!</text>
75
+ <text class="out" x="18" y="418"> Model: deepseek/deepseek-chat</text>
76
+ <text class="out" x="18" y="437"> Tokens: Prompt: 812 | Completion: 96 | Total: 908</text>
77
+ <text class="out" x="18" y="456"> File: src/sum.ts</text>
78
+ <text class="out" x="18" y="475"> Reason: Fixed subtraction typo in the sum() function</text>
79
+ <text class="out" x="18" y="494"> Root cause: sum() used the - operator instead of +</text>
80
+ </g>
81
+ </svg>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bugzero",
3
- "version": "0.0.32",
3
+ "version": "0.0.34",
4
4
  "description": "An autonomous, AI-powered CLI tool for automatic build error detection and repair.",
5
5
  "license": "MIT",
6
6
  "bin": {