bugzero 0.0.42 → 0.0.44

package/README.md

@@ -114,6 +114,7 @@ bugzero rescue
 ### Integrations and output
 
 - **Markdown reports.** Every `hunt` and `rescue` run writes `bugzero-report.md` to the target project: a pass/fail summary of build, lint, and tests, the full error logs, the model used, token usage, and before/after diffs for every file patched. The terminal prints a clickable link straight to it.
+- **JSON output.** Add `--json` to `hunt` or `rescue` to print the result as a single JSON document on stdout, with all human-readable logs moved to stderr and the exit code unchanged (0 on success, 1 otherwise), so scripts and CI can parse it. See [Scripting and CI](#scripting-and-ci).
 - **GitHub Action mode.** Run the same repair loop in CI. Instead of patching a local checkout, the Action commits every changed file in one atomic commit through the GitHub API and opens a pull request — see [GitHub Action Mode](#github-action-mode) below.
 
 ---
@@ -191,7 +192,7 @@ OPENROUTER_API_KEY=your_openrouter_api_key_here
 ## Commands
 
 ### `bugzero hunt`
-Run build, lint, and test checks. Reports all failures without modifying any files. Accepts `--timeout <seconds>`, like `rescue`.
+Run build, lint, and test checks. Reports all failures without modifying any files. Accepts `--timeout <seconds>` and `--json`, like `rescue`.
 
 ```bash
 bugzero hunt --path /path/to/your/project
@@ -213,6 +214,7 @@ bugzero rescue --path /path/to/your/project
 | `--max-attempts <n>` | `-n` | `3` | Maximum AI fix iterations before giving up |
 | `--timeout <seconds>` | `-t` | none | Stop any build, lint, or test command that runs longer than this many seconds |
 | `--dry-run` | | `false` | Analyze only — no files will be written |
+| `--json` | | `false` | Print the result as one JSON document on stdout (logs go to stderr) |
 
 </details>
 
@@ -236,6 +238,19 @@ bugzero vibe
 
 ---
 
+## Scripting and CI
+
+`hunt` and `rescue` accept `--json`. Stdout then contains exactly one JSON document and every human-readable log line goes to stderr, so the output is safe to pipe. Exit codes don't change: `0` when everything passes or is fixed, `1` otherwise.
+
+```bash
+bugzero hunt --json | jq '.steps'
+bugzero rescue --json --dry-run | jq -r '.outcome'
+```
+
+`hunt` reports each step (`build`, `lint`, `test`) as `passed`, `failed`, or `skipped`; failed steps include the command's output and whether it timed out. `rescue` reports an `outcome` of `already-passing`, `fixed`, `failed`, or `dry-run`, along with the model, token usage, and the files and root cause of any fix. Both include the path to the generated report. If a run can't start at all (for example, because of an invalid option), stdout is `{ "success": false, "error": "..." }`.
+
+---
+
 ## Configuration
 
 BugZero reads a `.bugzerorc` JSON file in your target project directory to pick up model preferences:
@@ -269,8 +284,10 @@ BugZero provides clear, actionable output for common failure modes:
 | Error | Message |
 |---|---|
 | Invalid API key (401) | Prompts you to check your `OPENROUTER_API_KEY` |
-| Rate limit exceeded (429) | Prompts you to check your OpenRouter credit balance |
-| Model not found | Displays the invalid model ID and suggests running `bugzero vibe` |
+| Insufficient credits (402) | Says your OpenRouter balance is too low, links to the credits page, and suggests switching to a cheaper or free model with `bugzero vibe` |
+| Rate limit exceeded (429) | Says OpenRouter is rate limiting and suggests waiting, switching models, or adding credits |
+| Prompt too large for the model | Says the prompt exceeded the model's context window and suggests a larger-context model with `bugzero vibe` |
+| Model not found | Names the unavailable model ID and suggests running `bugzero vibe` |
 | Patch not applied | Reports exact mismatch between AI suggestion and file content, after exhausting exact, whitespace, and fuzzy matching |
 | Max attempts reached | Exits cleanly with the last error log for manual review |
 

package/dist/index.js

@@ -393,7 +393,7 @@ var require_dist = __commonJS({
       while (true) {
         const envPath = import_path2.default.join(dir, ".env");
         if (import_fs2.default.existsSync(envPath)) {
-          import_dotenv.default.config({ path: envPath });
+          import_dotenv.default.config({ path: envPath, quiet: true });
           return;
         }
         const parent = import_path2.default.dirname(dir);
@@ -402,7 +402,7 @@ var require_dist = __commonJS({
         }
         dir = parent;
       }
-      import_dotenv.default.config();
+      import_dotenv.default.config({ quiet: true });
     }
     loadEnv();
     var env = {
@@ -704,12 +704,47 @@ var require_dist3 = __commonJS({
     var __toCommonJS = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
     var index_exports = {};
     __export(index_exports, {
-      OpenRouterProvider: () => OpenRouterProvider
+      OpenRouterProvider: () => OpenRouterProvider,
+      getErrorHints: () => getErrorHints
     });
     module2.exports = __toCommonJS(index_exports);
     var import_axios = __toESM2(require("axios"));
     var import_fs2 = __toESM2(require("fs"));
     var import_path2 = __toESM2(require("path"));
+    var CREDITS_PATTERN = /insufficient credits|credit balance|add more credits|requires more credits|token_limit_exceeded/i;
+    var CONTEXT_PATTERN = /context length|context window|maximum context|context_length_exceeded|string_too_long|too many tokens|reduce the length/i;
+    var MODEL_PATTERN = /not a valid model|no endpoints found|model.{0,40}(not found|does not exist|unavailable)/i;
+    function getErrorHints({ status, message, model }) {
+      if (status === 401) {
+        return ["\u{1F449} Please check if your OPENROUTER_API_KEY is correct and active."];
+      }
+      if (status === 402 || CREDITS_PATTERN.test(message)) {
+        return [
+          "\u{1F449} Your OpenRouter credit balance is too low for this request.",
+          "   Add credits at https://openrouter.ai/settings/credits, or run 'bugzero vibe' to switch to a cheaper model",
+          "   (models that cost nothing are listed at https://openrouter.ai/models?max_price=0)."
+        ];
+      }
+      if (status === 429) {
+        return [
+          "\u{1F449} OpenRouter is rate limiting these requests. Wait a moment and try again.",
+          "   Free models have stricter limits; run 'bugzero vibe' to switch models, or add credits to raise them."
+        ];
+      }
+      if (CONTEXT_PATTERN.test(message)) {
+        return [
+          `\u{1F449} The prompt was too large for the context window of "${model}".`,
+          "   Run 'bugzero vibe' to pick a model with a larger context window, or try again on a smaller failing scope."
+        ];
+      }
+      if (status === 404 || MODEL_PATTERN.test(message)) {
+        return [
+          `\u{1F449} The model "${model}" isn't available on OpenRouter (it wasn't found, or no provider currently serves it).`,
+          "   Run 'bugzero vibe' to choose a different model."
+        ];
+      }
+      return [];
+    }
     function resolveModel(cwd) {
       try {
         const configPath = import_path2.default.resolve(cwd ?? process.cwd(), ".bugzerorc");
@@ -772,21 +807,9 @@ var require_dist3 = __commonJS({
           }
           console.error(`
 \u274C [BugZero] OpenRouter API Error: ${msg}`);
-          if (error.response?.status === 401) {
-            console.error(`\u{1F449} Please check if your OPENROUTER_API_KEY is correct and active.`);
-          } else if (error.response?.status === 429 || error.response?.status === 402 || /credit/i.test(msg) || /token/i.test(msg)) {
-            console.error(`
-\u{1F449} You have insufficient OpenRouter credits (or too low balance) for the selected model.`);
-            console.error(`\u{1F449} We suggest using the 'bugzero vibe' command to change to a FREE model:`);
-            console.error(`   1. Run the command: npx bugzero@latest vibe (or bugzero vibe)`);
-            console.error(`   2. Select "Custom Model" and enter one of these free model IDs:`);
-            console.error(`      - google/gemma-2-9b-it:free`);
-            console.error(`      - meta-llama/llama-3-8b-instruct:free`);
-            console.error(`      - mistralai/mistral-7b-instruct:free`);
-            console.error(`      - microsoft/phi-3-medium-128k-instruct:free`);
-            console.error(`      - nvidia/llama-3.1-nemotron-70b-instruct:free
-`);
-          }
+          const hints = getErrorHints({ status: error.response?.status, message: msg, model });
+          for (const line of hints) console.error(line);
+          if (hints.length > 0) console.error();
           throw new Error(`OpenRouter API failed: ${msg}`);
         }
       }
@@ -1494,6 +1517,7 @@ var require_dist7 = __commonJS({
     var index_exports = {};
     __export(index_exports, {
       DEFAULT_MAX_ATTEMPTS: () => DEFAULT_MAX_ATTEMPTS,
+      REPORT_FILENAME: () => REPORT_FILENAME2,
       detectFramework: () => detectFramework2,
       detectPackageManager: () => import_analyzers2.detectPackageManager,
       orchestrate: () => orchestrate2,
@@ -1602,6 +1626,7 @@ Re-run without \`--dry-run\` to let BugZero attempt a fix.
       }
     }
     var import_ai_provider = require_dist3();
+    var REPORT_FILENAME2 = "bugzero-report.md";
     function statusLabel(result) {
       if (result.skipped) return "\u23ED\uFE0F Skipped (no script defined)";
       return result.success ? "\u2705 Passed" : "\u274C Failed";
@@ -1900,7 +1925,7 @@ ${rawOutput}
 
 ---
 *Report generated by **BugZero** on ${(/* @__PURE__ */ new Date()).toLocaleString()}*`;
-      const reportPath = import_path3.default.resolve(cwd, "bugzero-report.md");
+      const reportPath = import_path3.default.resolve(cwd, REPORT_FILENAME2);
       try {
         import_fs3.default.writeFileSync(reportPath, content, "utf-8");
         const clickableUrl = (0, import_url.pathToFileURL)(reportPath).toString();
@@ -1929,6 +1954,62 @@ var import_fs = __toESM(require("fs"));
 var import_path = __toESM(require("path"));
 var import_core = __toESM(require_dist7());
 
+// src/json-output.ts
+function stepStatus(step) {
+  if (step.skipped) return "skipped";
+  return step.success ? "passed" : "failed";
+}
+function stepJson(step) {
+  const status = stepStatus(step);
+  if (status !== "failed") return { status };
+  return { status, timedOut: step.timedOut === true, output: step.output ?? "" };
+}
+function buildHuntJson(info, steps) {
+  return {
+    command: "hunt",
+    success: steps.build.success && steps.lint.success && steps.test.success,
+    path: info.path,
+    framework: info.framework,
+    packageManager: info.packageManager,
+    steps: { build: stepJson(steps.build), lint: stepJson(steps.lint), test: stepJson(steps.test) },
+    reportPath: info.reportPath
+  };
+}
+function buildRescueJson(result, info) {
+  let outcome;
+  if (result.success && result.attempts === 0) outcome = "already-passing";
+  else if (result.success) outcome = "fixed";
+  else if (info.dryRun) outcome = "dry-run";
+  else outcome = "failed";
+  const tokens = result.promptTokens !== void 0 && result.completionTokens !== void 0 ? {
+    prompt: result.promptTokens,
+    completion: result.completionTokens,
+    total: result.promptTokens + result.completionTokens
+  } : null;
+  return {
+    command: "rescue",
+    outcome,
+    success: result.success,
+    dryRun: info.dryRun,
+    path: info.path,
+    framework: info.framework,
+    packageManager: info.packageManager,
+    attempts: result.attempts,
+    model: result.modelUsed || null,
+    tokens,
+    fix: result.appliedFix ? {
+      rootCause: result.appliedFix.rootCause,
+      explanation: result.appliedFix.explanation,
+      files: result.appliedFix.patches.map((p) => p.filePath)
+    } : null,
+    error: result.error ?? null,
+    reportPath: info.reportPath
+  };
+}
+function buildErrorJson(message) {
+  return { success: false, error: message };
+}
+
 // src/summary.ts
 function tokenLines(result) {
   if (result.promptTokens === void 0 || result.completionTokens === void 0) return [];
@@ -1988,9 +2069,23 @@ function parseTimeout(raw) {
   (0, import_core.resolveTimeoutMs)(seconds);
   return seconds;
 }
+var JSON_DESCRIPTION = "Print the result as one JSON document on stdout (human-readable logs go to stderr)";
+function routeLogsToStderr() {
+  const toStderr = (...args) => console.error(...args);
+  console.log = toStderr;
+  console.info = toStderr;
+  console.debug = toStderr;
+}
+function finish(exitCode, json) {
+  if (json === void 0) process.exit(exitCode);
+  process.stdout.write(`${JSON.stringify(json, null, 2)}
+`, () => process.exit(exitCode));
+}
 var program = new import_commander.Command();
 program.name("bugzero").description("AI-powered build issue fixer \u2014 detects and repairs build errors automatically").version(version);
-program.command("hunt").description("Run build, lint, and tests \u2014 report issues without modifying files").option("-p, --path <dir>", "Path to the target project", ".").option("-t, --timeout <seconds>", TIMEOUT_DESCRIPTION).action(async (opts) => {
+program.command("hunt").description("Run build, lint, and tests \u2014 report issues without modifying files").option("-p, --path <dir>", "Path to the target project", ".").option("-t, --timeout <seconds>", TIMEOUT_DESCRIPTION).option("--json", JSON_DESCRIPTION).action(async (opts) => {
+  const json = opts.json === true;
+  if (json) routeLogsToStderr();
   try {
     const cwd = import_path.default.resolve(opts.path);
     const timeoutSeconds = parseTimeout(opts.timeout);
@@ -2014,14 +2109,22 @@ program.command("hunt").description("Run build, lint, and tests \u2014 report is
     console.log(`
 ${allPassed ? "\u2705 All checks passed" : "\u274C Issues found \u2014 run 'bugzero rescue' to repair"}
 `);
-    process.exit(allPassed ? 0 : 1);
+    finish(
+      allPassed ? 0 : 1,
+      json ? buildHuntJson(
+        { path: cwd, framework, packageManager, reportPath: import_path.default.resolve(cwd, import_core.REPORT_FILENAME) },
+        { build, lint, test }
+      ) : void 0
+    );
   } catch (error) {
     console.error(`
 \u274C [BugZero] Execution failed: ${error.message || error}`);
-    process.exit(1);
+    finish(1, json ? buildErrorJson(String(error.message || error)) : void 0);
   }
 });
-program.command("rescue").description("Detect build failures and automatically apply AI-generated fixes").option("-p, --path <dir>", "Path to the target project", ".").option("-n, --max-attempts <number>", "Maximum AI fix attempts", "3").option("-t, --timeout <seconds>", TIMEOUT_DESCRIPTION).option("--dry-run", "Analyse only \u2014 print what would be fixed without writing files", false).action(async (opts) => {
+program.command("rescue").description("Detect build failures and automatically apply AI-generated fixes").option("-p, --path <dir>", "Path to the target project", ".").option("-n, --max-attempts <number>", "Maximum AI fix attempts", "3").option("-t, --timeout <seconds>", TIMEOUT_DESCRIPTION).option("--dry-run", "Analyse only \u2014 print what would be fixed without writing files", false).option("--json", JSON_DESCRIPTION).action(async (opts) => {
+  const json = opts.json === true;
+  if (json) routeLogsToStderr();
   try {
     const cwd = import_path.default.resolve(opts.path);
     const maxAttempts = (0, import_core.resolveMaxAttempts)(Number(opts.maxAttempts));
@@ -2043,11 +2146,20 @@ program.command("rescue").description("Detect build failures and automatically a
     const summary = buildRescueSummary(result, { dryRun });
     for (const line of summary.lines) console.log(line);
     console.log();
-    process.exit(summary.exitCode);
+    finish(
+      summary.exitCode,
+      json ? buildRescueJson(result, {
+        path: cwd,
+        framework,
+        packageManager,
+        dryRun,
+        reportPath: import_path.default.resolve(cwd, import_core.REPORT_FILENAME)
+      }) : void 0
+    );
   } catch (error) {
     console.error(`
 \u274C [BugZero] Execution failed: ${error.message || error}`);
-    process.exit(1);
+    finish(1, json ? buildErrorJson(String(error.message || error)) : void 0);
   }
 });
 program.command("protect").description("[Deprecated] Use 'hunt' instead").action(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bugzero",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "description": "Autonomous AI-powered CLI and GitHub Action that detects build, lint, and test failures, generates multi-file patches, applies them atomically with fuzzy matching, and re-verifies until your project is green.",
   "license": "MIT",
   "author": "Saksham Agarwal (https://github.com/Saksham1800t)",