bugzero 0.0.32 → 0.0.33

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.
Files changed (3) hide show
  1. package/.turbo/turbo-build.log +3 -3
  2. package/README.md +136 -71
  3. package/package.json +1 -1
package/.turbo/turbo-build.log CHANGED
@@ -1,5 +1,5 @@
1
1
 
2
- > bugzero@0.0.32 build /home/runner/work/Bugzero/Bugzero/apps/bugzero
2
+ > bugzero@0.0.33 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 33ms
12
12
  DTS Build start
13
- DTS ⚡️ Build success in 1160ms
13
+ DTS ⚡️ Build success in 784ms
14
14
  DTS dist/index.d.ts 20.00 B
package/README.md CHANGED
@@ -1,14 +1,31 @@
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.
10
15
 
11
- Built for developers who want zero-downtime repair cycles, automated CI/CD recovery, and production-grade error resolution without manual debugging.
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## ⚡ Quick Start
21
+
22
+ ```bash
23
+ npm install -g bugzero
24
+ export OPENROUTER_API_KEY="your_openrouter_api_key_here"
25
+ bugzero rescue --path /path/to/your/project
26
+ ```
27
+
28
+ 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
29
 
13
30
  ---
14
31
 
@@ -16,76 +33,117 @@ Built for developers who want zero-downtime repair cycles, automated CI/CD recov
16
33
 
17
34
  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
35
 
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.
36
+ - 🔁 **No more debugging the same TypeScript error twice.** The agent reads the error, finds the file, generates the fix, and verifies it.
37
+ - 🛡️ **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.
38
+ - 🎯 **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.
39
+ - 🧠 **Model agnostic.** DeepSeek, Claude, Gemini, GPT-4o, Llama, or any model on OpenRouter.
40
+ - 🤖 **CI-native.** Run it as a GitHub Action instead of a local CLI, and let it open the fix as a PR.
23
41
 
24
42
  ---
25
43
 
26
- ## How it Works
44
+ ## How It Works
27
45
 
28
46
  ```
29
47
  bugzero rescue
30
- |
31
- v
48
+ │
49
+ ▼
32
50
  Run Build + Lint + Tests
33
- |
34
- v
35
- Any failures? ---- No ---> Build already passing. Exit cleanly.
36
- |
51
+ │
52
+ ▼
53
+ Any failures? ── No ──▶ Build already passing. Exit cleanly.
54
+ │
37
55
  Yes
38
- |
39
- v
56
+ │
57
+ ▼
40
58
  Capture and parse error logs
41
- |
42
- v
59
+ │
60
+ ▼
43
61
  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
62
+ │
63
+ ▼
64
+ Parse structured fix suggestion (one or more file patches)
65
+ │
66
+ ▼
67
+ Apply patches atomically (exact → whitespace → similarity match, with .bak backups)
68
+ │
69
+ ▼
52
70
  Re-run build to verify the fix
53
- |
54
- v
55
- Build fixed? --- Yes ---> Print fix details. Exit success.
56
- |
71
+ │
72
+ ▼
73
+ Build fixed? ── Yes ──▶ Print fix details. Exit success.
74
+ │
57
75
  No
58
- |
59
- v
60
- Max attempts reached? -- Yes ---> Exit with failure logs.
61
- |
76
+ │
77
+ ▼
78
+ Max attempts reached? ── Yes ──▶ Exit with failure logs.
79
+ │
62
80
  No
63
- |
64
- +-------------------> Prompt LLM again (next attempt)
81
+ │
82
+ └──────────────────▶ Prompt LLM again (next attempt)
65
83
  ```
66
84
 
67
85
  ---
68
86
 
69
- ## Key Features
87
+ ## ✨ Key Features
70
88
 
71
89
  | Feature | Description |
72
90
  |---|---|
73
91
  | Autonomous repair loop | Runs analyze, patch, verify in a stateful LangGraph graph |
74
92
  | Multi-model support | DeepSeek, Claude, GPT-4o, Gemini, Llama via OpenRouter |
75
93
  | Framework detection | Automatically identifies your project's tooling setup |
94
+ | **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 |
95
+ | **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
96
  | 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
97
  | Error type parsing | Parses TypeScript, ESLint, and Jest error formats |
80
98
  | Dry-run mode | Analyze and report without writing any files |
81
99
  | 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. |
100
+ | 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 |
101
+ | **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 |
102
+
103
+ ---
104
+
105
+ ## 🤖 GitHub Action Mode
106
+
107
+ 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.
108
+
109
+ ```yaml
110
+ name: BugZero Auto-Fix
111
+
112
+ on:
113
+ workflow_run:
114
+ workflows: ["CI"]
115
+ types: [completed]
116
+
117
+ jobs:
118
+ fix:
119
+ if: github.event.workflow_run.conclusion == 'failure'
120
+ runs-on: ubuntu-latest
121
+ permissions:
122
+ contents: write
123
+ pull-requests: write
124
+ steps:
125
+ - uses: actions/checkout@v4
126
+ with:
127
+ ref: ${{ github.event.workflow_run.head_branch }}
128
+
129
+ - uses: pnpm/action-setup@v4 # or npm/yarn — whatever installs your project's deps
130
+ - run: pnpm install
131
+
132
+ - uses: Saksham1800t/Bugzero@v1
133
+ with:
134
+ github-token: ${{ secrets.GITHUB_TOKEN }}
135
+ base-branch: ${{ github.event.workflow_run.head_branch }}
136
+ env:
137
+ OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
138
+ ```
139
+
140
+ 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
141
 
84
142
  ---
85
143
 
86
144
  ## Installation
87
145
 
88
- Install globally from the NPM registry:
146
+ Install globally from the npm registry:
89
147
 
90
148
  ```bash
91
149
  npm install -g bugzero
@@ -130,7 +188,8 @@ Run the full AI-powered repair loop. Detects build failures, generates precise c
130
188
  bugzero rescue --path /path/to/your/project
131
189
  ```
132
190
 
133
- Options:
191
+ <details>
192
+ <summary><strong>Options for <code>rescue</code></strong></summary>
134
193
 
135
194
  | Flag | Short | Default | Description |
136
195
  |---|---|---|---|
@@ -138,6 +197,8 @@ Options:
138
197
  | `--max-attempts <n>` | `-n` | `3` | Maximum AI fix iterations before giving up |
139
198
  | `--dry-run` | | `false` | Analyze only — no files will be written |
140
199
 
200
+ </details>
201
+
141
202
  ### `bugzero vibe`
142
203
  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
204
 
@@ -145,13 +206,17 @@ Interactively select which AI model to use. Fetches the current model list from
145
206
  bugzero vibe
146
207
  ```
147
208
 
148
- Supported models (curated list, plus custom entry):
209
+ <details>
210
+ <summary><strong>Supported models</strong> (curated list, plus custom entry)</summary>
211
+
149
212
  - DeepSeek V3 / DeepSeek R1
150
213
  - Anthropic Claude 3.5 Sonnet
151
214
  - Google Gemini 2.5 Pro / Flash
152
215
  - OpenAI GPT-4o
153
216
  - Meta Llama 3.3 Instruct
154
217
 
218
+ </details>
219
+
155
220
  ---
156
221
 
157
222
  ## Configuration
@@ -170,33 +235,45 @@ This file is created automatically when you run `bugzero vibe`.
170
235
 
171
236
  ## Reports
172
237
 
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:
238
+ 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.
239
+
174
240
  - **Pipeline Summary:** Clear status checklist of your project's Build, Lint, and Test suites.
175
241
  - **Detailed Error Outputs:** Full error logs from any failing checks.
176
242
  - **AI Brain Details:** The exact OpenRouter model used.
177
243
  - **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.
244
+ - **Applied Fixes (for rescue):** The root cause, explanation, and before/after diffs for every file patched.
179
245
 
180
246
  ---
181
247
 
182
- ## Development Setup
248
+ ## Error Handling
183
249
 
184
- Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo.
250
+ BugZero provides clear, actionable output for common failure modes:
251
+
252
+ | Error | Message |
253
+ |---|---|
254
+ | Invalid API key (401) | Prompts you to check your `OPENROUTER_API_KEY` |
255
+ | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance |
256
+ | Model not found | Displays the invalid model ID and suggests running `bugzero vibe` |
257
+ | Patch not applied | Reports exact mismatch between AI suggestion and file content, after exhausting exact, whitespace, and fuzzy matching |
258
+ | Max attempts reached | Exits cleanly with the last error log for manual review |
259
+
260
+ ---
261
+
262
+ <details>
263
+ <summary><strong>🛠️ Development Setup</strong> (contributing to BugZero itself)</summary>
264
+
265
+ 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
266
 
186
267
  ### Prerequisites
187
268
  - Node.js 18 or later
188
269
  - pnpm
189
270
 
190
- ### Install
271
+ ### Install & build
191
272
 
192
273
  ```bash
193
274
  pnpm install
194
- ```
195
-
196
- ### Build all packages
197
-
198
- ```bash
199
275
  pnpm build
276
+ pnpm test
200
277
  ```
201
278
 
202
279
  ### Run commands locally without installing globally
@@ -207,33 +284,22 @@ pnpm rescue --path ./demo-project
207
284
  pnpm vibe
208
285
  ```
209
286
 
210
- ### Monorepo package structure
287
+ ### Monorepo structure
211
288
 
212
289
  | Package | Role |
213
290
  |---|---|
214
- | `packages/cli` | CLI entrypoint (Commander) |
291
+ | `apps/bugzero` | CLI entrypoint (Commander) — the package published to npm |
292
+ | `apps/github-action` | GitHub Action wrapper — runs the repair loop in CI and opens a fix PR |
215
293
  | `packages/core` | Orchestrates build and fix flow |
216
294
  | `packages/agents` | LangGraph state machine (analyze, patch, verify) |
217
295
  | `packages/ai-provider` | OpenRouter HTTP client |
218
296
  | `packages/analyzers` | Runs build/lint/test and parses output |
219
- | `packages/patcher` | Applies search-and-replace patches with backup |
297
+ | `packages/patcher` | Applies search-and-replace patches — with atomic multi-file support and fuzzy-match fallback |
220
298
  | `packages/prompts` | LLM prompt templates |
221
299
  | `packages/config` | Env loading and local `.bugzerorc` config store |
222
300
  | `packages/shared` | Shared TypeScript types |
223
301
 
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 |
302
+ </details>
237
303
 
238
304
  ---
239
305
 
@@ -252,4 +318,3 @@ BugZero provides clear, actionable output for common failure modes:
252
318
  If BugZero saved you debugging hours in production or deployment pipelines, consider buying the author a coffee.
253
319
 
254
320
  [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/saksham_)
255
-
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bugzero",
3
- "version": "0.0.32",
3
+ "version": "0.0.33",
4
4
  "description": "An autonomous, AI-powered CLI tool for automatic build error detection and repair.",
5
5
  "license": "MIT",
6
6
  "bin": {