bugzero 0.0.4 → 0.0.5

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 (2) hide show
  1. package/README.md +182 -89
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,165 +1,258 @@
1
- # 🚀 BugZero
1
+ # BugZero
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/bugzero.svg?style=flat-square&color=FF69B4)](https://www.npmjs.com/package/bugzero)
3
+ [![npm version](https://img.shields.io/npm/v/bugzero.svg?style=flat-square)](https://www.npmjs.com/package/bugzero)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
5
+ [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green?style=flat-square)](https://nodejs.org)
5
6
  [![pnpm](https://img.shields.io/badge/maintained%20with-pnpm-cc00ff.svg?style=flat-square)](https://pnpm.io/)
6
7
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/Saksham1800t)
7
8
 
8
- **BugZero** is an autonomous, AI-powered self-healing command-line tool. It monitors build, lint, and test errors in your project, analyzes them using an LLM, generates precise surgical code patches, applies them safely, and runs validation loops recursively until your build is completely green.
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.
9
10
 
10
- Designed for modern developer loops, CI/CD pipelines, and automated hotfixes.
11
+ Built for developers who want zero-downtime repair cycles, automated CI/CD recovery, and production-grade error resolution without manual debugging.
11
12
 
12
13
  ---
13
14
 
14
- ## 🛠️ How it Works
15
+ ## Why BugZero?
16
+
17
+ 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
+
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.
23
+
24
+ ---
25
+
26
+ ## How it Works
15
27
 
16
28
  ```
17
29
  bugzero rescue
18
- │
19
- ▼
30
+ |
31
+ v
20
32
  Run Build + Lint + Tests
21
- │
22
- ▼
23
- Any failures? ──── No ──▶ ✅ Exit cleanly
24
- │
33
+ |
34
+ v
35
+ Any failures? ---- No ---> Build already passing. Exit cleanly.
36
+ |
25
37
  Yes
26
- │
27
- ▼
28
- Capture error logs
29
- │
30
- ▼
31
- Prompt LLM via LangGraph
32
- │
33
- ▼
34
- Parse fix suggestion (JSON)
35
- │
36
- ▼
37
- Apply search-and-replace patch
38
- │
39
- ▼
40
- Re-run build to verify
41
- │
42
- ▼
43
- Build fixed? ─── Yes ──▶ ✅ Print fix details & Exit
44
- │
38
+ |
39
+ v
40
+ Capture and parse error logs
41
+ |
42
+ v
43
+ 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
52
+ Re-run build to verify the fix
53
+ |
54
+ v
55
+ Build fixed? --- Yes ---> Print fix details. Exit success.
56
+ |
45
57
  No
46
- │
47
- ▼
48
- Max attempts reached? ── Yes ──▶ ❌ Exit with logs
49
- │
58
+ |
59
+ v
60
+ Max attempts reached? -- Yes ---> Exit with failure logs.
61
+ |
50
62
  No
51
- │
52
- └──────────────────▶ Prompt LLM again (loop)
63
+ |
64
+ +-------------------> Prompt LLM again (next attempt)
53
65
  ```
54
66
 
55
67
  ---
56
68
 
57
- ## 🌟 Key Features
69
+ ## Key Features
58
70
 
59
- * **🔍 Automatic Framework Detection**: Detects common web frameworks and tooling setups inside your target directories.
60
- * **🤖 LangGraph-Based Feedback Loop**: Employs stateful graphs to analyze compiler/test outputs, write minimal patches, and re-run compilation checks recursively.
61
- * **⚡ Surgical Search-and-Replace**: Avoids corrupting files by using highly specific search-and-replace strings generated directly from the abstract syntax context.
62
- * **📦 Safe Backups**: Creates a backup `.bugzero.bak` for every modified file so you can revert modifications easily.
63
- * **📈 Multiple Checkups**: Validates builds, style guidelines (ESLint), and testing frameworks (Jest) automatically.
71
+ | Feature | Description |
72
+ |---|---|
73
+ | Autonomous repair loop | Runs analyze, patch, verify in a stateful LangGraph graph |
74
+ | Multi-model support | DeepSeek, Claude, GPT-4o, Gemini, Llama via OpenRouter |
75
+ | Framework detection | Automatically identifies your project's tooling setup |
76
+ | Safe file patching | Every modified file receives a `.opspilot.bak` backup |
77
+ | Error type parsing | Parses TypeScript, ESLint, and Jest error formats |
78
+ | Dry-run mode | Analyze and report without writing any files |
79
+ | Local model config | Save preferred model to `.bugzerorc` per project |
64
80
 
65
81
  ---
66
82
 
67
- ## 🚀 Getting Started
83
+ ## Installation
84
+
85
+ Install globally from the NPM registry:
68
86
 
69
- ### 1. Global Installation
70
- Install `bugzero` globally from NPM:
71
87
  ```bash
72
88
  npm install -g bugzero
73
89
  ```
74
90
 
75
- ### 2. Configure Environment Variables
76
- BugZero relies on OpenRouter to access AI models (such as DeepSeek, Claude, Gemini, or GPT-4o). Configure your environment variable in your terminal session or add it to a `.env` file at the root of the project you are fixing:
91
+ ---
92
+
93
+ ## Setup
94
+
95
+ BugZero requires an [OpenRouter](https://openrouter.ai) API key to call AI models. Set it as an environment variable before running any command.
77
96
 
78
- **On macOS/Linux:**
97
+ **Linux / macOS:**
79
98
  ```bash
80
99
  export OPENROUTER_API_KEY="your_openrouter_api_key_here"
81
100
  ```
82
101
 
83
- **On Windows (PowerShell):**
102
+ **Windows (PowerShell):**
84
103
  ```powershell
85
104
  $env:OPENROUTER_API_KEY="your_openrouter_api_key_here"
86
105
  ```
87
106
 
107
+ **Or** create a `.env` file in the project root you are targeting:
108
+ ```env
109
+ OPENROUTER_API_KEY=your_openrouter_api_key_here
110
+ ```
111
+
88
112
  ---
89
113
 
90
- ## 💻 Usage & Commands
114
+ ## Commands
91
115
 
92
- Run `bugzero` from any terminal directory.
116
+ ### `bugzero hunt`
117
+ Run build, lint, and test checks. Reports all failures without modifying any files.
93
118
 
94
- ### 1. Hunt for Bugs (Dry-Run / Safe Check)
95
- Run build, lint, and test checks to report error diagnostics without modifying any files.
96
119
  ```bash
97
120
  bugzero hunt --path /path/to/your/project
98
121
  ```
99
122
 
100
- ### 2. Rescue Your Project (Autonomous Mode)
101
- Run the AI repair loop to automatically detect compilation errors, generate code patches, apply them, and verify the build.
123
+ ### `bugzero rescue`
124
+ Run the full AI-powered repair loop. Detects build failures, generates precise code patches, applies them, and verifies the result.
125
+
102
126
  ```bash
103
127
  bugzero rescue --path /path/to/your/project
104
128
  ```
105
129
 
106
- ### 3. Vibe With a Brain (Change AI Model)
107
- List and select which LLM model you want to use. This fetches the latest available models from OpenRouter, lets you pick one, and saves it inside `.bugzerorc`.
130
+ Options:
131
+
132
+ | Flag | Short | Default | Description |
133
+ |---|---|---|---|
134
+ | `--path <dir>` | `-p` | `.` | Path to the target project |
135
+ | `--max-attempts <n>` | `-n` | `3` | Maximum AI fix iterations before giving up |
136
+ | `--dry-run` | | `false` | Analyze only — no files will be written |
137
+
138
+ ### `bugzero vibe`
139
+ 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.
140
+
108
141
  ```bash
109
142
  bugzero vibe
110
143
  ```
111
144
 
112
- ### CLI Command Options
145
+ Supported models (curated list, plus custom entry):
146
+ - DeepSeek V3 / DeepSeek R1
147
+ - Anthropic Claude 3.5 Sonnet
148
+ - Google Gemini 2.5 Pro / Flash
149
+ - OpenAI GPT-4o
150
+ - Meta Llama 3.3 Instruct
151
+
152
+ ---
153
+
154
+ ## Configuration
113
155
 
114
- | Option | Shorthand | Description | Default |
115
- | :--- | :--- | :--- | :--- |
116
- | `--path <dir>` | `-p <dir>` | The path to the target project you want to check/fix | `.` (Current directory) |
117
- | `--max-attempts <num>` | `-n <num>` | Maximum AI fix loops/attempts before giving up | `3` |
118
- | `--dry-run` | | Print the recommended fixes without saving changes to files | `false` |
156
+ BugZero reads a `.bugzerorc` JSON file in your target project directory to pick up model preferences:
157
+
158
+ ```json
159
+ {
160
+ "model": "deepseek/deepseek-chat"
161
+ }
162
+ ```
163
+
164
+ This file is created automatically when you run `bugzero vibe`.
119
165
 
120
166
  ---
121
167
 
122
- ## 🧱 Monorepo Development & Local Setup
168
+ ## Development Setup
123
169
 
124
- If you want to contribute to the BugZero engine:
170
+ Clone the repository and install dependencies. This project uses a pnpm monorepo managed by Turborepo.
125
171
 
126
172
  ### Prerequisites
127
- * Node.js (LTS version recommended)
128
- * `pnpm` (workspace manager)
173
+ - Node.js 18 or later
174
+ - pnpm
175
+
176
+ ### Install
129
177
 
130
- ### Installation
131
- Clone the repository, go into the workspace root, and run:
132
178
  ```bash
133
179
  pnpm install
134
180
  ```
135
181
 
136
- ### Local Commands
137
- * **Build all monorepo packages**:
138
- ```bash
139
- pnpm build
140
- ```
141
- * **Run CLI locally in development mode (shortcuts)**:
142
- ```bash
143
- pnpm hunt --path ./demo-project
144
- pnpm rescue --path ./demo-project
145
- pnpm vibe
146
- ```
182
+ ### Build all packages
183
+
184
+ ```bash
185
+ pnpm build
186
+ ```
187
+
188
+ ### Run commands locally without installing globally
189
+
190
+ ```bash
191
+ pnpm hunt --path ./demo-project
192
+ pnpm rescue --path ./demo-project
193
+ pnpm vibe
194
+ ```
195
+
196
+ ### Monorepo package structure
197
+
198
+ | Package | Role |
199
+ |---|---|
200
+ | `packages/cli` | CLI entrypoint (Commander) |
201
+ | `packages/core` | Orchestrates build and fix flow |
202
+ | `packages/agents` | LangGraph state machine (analyze, patch, verify) |
203
+ | `packages/ai-provider` | OpenRouter HTTP client |
204
+ | `packages/analyzers` | Runs build/lint/test and parses output |
205
+ | `packages/patcher` | Applies search-and-replace patches with backup |
206
+ | `packages/prompts` | LLM prompt templates |
207
+ | `packages/config` | Env loading and local `.bugzerorc` config store |
208
+ | `packages/shared` | Shared TypeScript types |
209
+
210
+ ---
211
+
212
+ ## Error Handling
213
+
214
+ BugZero provides clear, actionable output for common failure modes:
215
+
216
+ | Error | Message |
217
+ |---|---|
218
+ | Invalid API key (401) | Prompts you to check your `OPENROUTER_API_KEY` |
219
+ | Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance |
220
+ | Model not found | Displays the invalid model ID and suggests running `bugzero vibe` |
221
+ | Patch not applied | Reports exact mismatch between AI suggestion and file content |
222
+ | Max attempts reached | Exits cleanly with the last error log for manual review |
147
223
 
148
224
  ---
149
225
 
150
- ## 👥 Author
226
+ ## Contributing
151
227
 
152
- Made with ❤️ and 😎 by:
228
+ Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
153
229
 
154
- * **Name**: Saksham Agarwal
155
- * **Email**: [sakshamagarwal0507@gmail.com](mailto:sakshamagarwal0507@gmail.com)
156
- * **GitHub**: [@Saksham1800t](https://github.com/Saksham1800t)
157
- * **LinkedIn**: [Saksham Agarwal](https://www.linkedin.com/in/saksham-agarwal-/)
230
+ 1. Fork the repository
231
+ 2. Create your feature branch (`git checkout -b feature/my-feature`)
232
+ 3. Commit your changes (`git commit -m 'Add my feature'`)
233
+ 4. Push to the branch (`git push origin feature/my-feature`)
234
+ 5. Open a Pull Request
158
235
 
159
236
  ---
160
237
 
161
- ## ☕ Support My Work
238
+ ## Author
239
+
240
+ **Saksham Agarwal**
241
+
242
+ - GitHub: [@Saksham1800t](https://github.com/Saksham1800t)
243
+ - LinkedIn: [Saksham Agarwal](https://www.linkedin.com/in/saksham-agarwal-/)
244
+ - Email: [sakshamagarwal0507@gmail.com](mailto:sakshamagarwal0507@gmail.com)
245
+
246
+ ---
247
+
248
+ ## Support
249
+
250
+ If BugZero saved you debugging hours in production or deployment pipelines, consider buying the author a coffee.
251
+
252
+ [![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/saksham_)
253
+
254
+ ---
162
255
 
163
- If BugZero saved you debugging hours in production or deployment pipelines, support the project!
256
+ ## License
164
257
 
165
- [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/saksham_)
258
+ MIT — see [LICENSE](LICENSE) for details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bugzero",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "bin": {
5
5
  "bugzero": "dist/index.js"
6
6
  },
@@ -12,9 +12,9 @@
12
12
  "execa": "^7.2.0"
13
13
  },
14
14
  "devDependencies": {
15
+ "@opspilot/agents": "0.0.1",
15
16
  "@opspilot/config": "0.0.1",
16
- "@opspilot/core": "0.0.1",
17
- "@opspilot/agents": "0.0.1"
17
+ "@opspilot/core": "0.0.1"
18
18
  },
19
19
  "main": "./dist/index.js",
20
20
  "types": "./dist/index.d.ts",