badgr-ci-triage 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# badgr-ci-triage
+
+Paste a failing CI log and get a plain-English diagnosis — dependency conflict, flaky test, build error, race condition, or environment issue.
+
+```bash
+npx badgr-ci-triage --log "npm ERR ERESOLVE unable to resolve dependency tree"
+```
+
+**Free. No signup required.** Runs entirely on your machine.
+
+---
+
+## The problem it solves
+
+CI failures produce walls of text. Finding the root cause means scanning hundreds of log lines to spot the one error that matters. `badgr-ci-triage` classifies the failure instantly and tells you exactly what to do — no log reading required.
+
+---
+
+## Quick start
+
+```bash
+# Pass log text directly
+npx badgr-ci-triage --log "npm ERR ERESOLVE unable to resolve dependency tree"
+
+# Pipe from a file or command
+cat ci-output.txt | npx badgr-ci-triage
+
+# Machine-readable JSON (for CI dashboards or scripts)
+npx badgr-ci-triage --log "TypeError: Cannot read properties of undefined" --json
+```
+
+---
+
+## CLI flags
+
+| Flag | Description |
+|------|-------------|
+| `--log <text>` | CI log text to triage (alternatively, pipe via stdin) |
+| `--json` | Output machine-readable JSON |
+
+**Exit codes:** `0` = failure categorized with a recommended action, `1` = unknown or empty log
+
+---
+
+## Failure categories
+
+| Category | Detected from |
+|---|---|
+| `dependency` | `ERESOLVE`, lockfile errors, `package not found` |
+| `build` | TypeScript errors (`tsc`), `SyntaxError`, webpack/vite failures |
+| `test` | `assert`, snapshot mismatches, `test failed` |
+| `deployment` | Deploy/release failures, health check timeouts |
+| `race` | Flaky failures, timeouts, deadlocks |
+| `environment` | Missing env vars, `permission denied`, secret references |
+
+---
+
+## Example output
+
+```
+badgr-ci-triage — dependency failure
+
+  ✗  ERESOLVE: unable to resolve dependency tree
+
+  Recommended action: Delete node_modules and package-lock.json, then reinstall from scratch.
+    rm -rf node_modules package-lock.json && npm install
+```
+
+```
+badgr-ci-triage — environment failure
+
+  ✗  Missing environment variable: DATABASE_URL
+
+  Recommended action: Add DATABASE_URL to your CI environment secrets.
+  Check your CI settings or .env.example for required variables.
+```
+
+---
+
+## TypeScript API
+
+```ts
+import { triageCiLog } from "badgr-ci-triage";
+
+const result = triageCiLog(`
+  npm ERR code ERESOLVE
+  npm ERR ERESOLVE unable to resolve dependency tree
+`);
+
+console.log(result.category);  // "dependency"
+console.log(result.checks);    // [{ status: "fail", label: "ERESOLVE", detail: "..." }]
+```
+
+**Types:**
+
+```ts
+interface CiTriageResult {
+  category:
+    | "dependency"
+    | "build"
+    | "test"
+    | "deployment"
+    | "race"
+    | "environment"
+    | "unknown";
+  checks: DiagnosticCheck[];
+  report: JsonReport;
+}
+
+function triageCiLog(log: string): CiTriageResult
+```
+
+---
+
+## Use in CI
+
+Triage your own CI logs as part of the pipeline to get structured failure data:
+
+```yaml
+# GitHub Actions example
+- name: Triage CI failure
+  if: failure()
+  run: echo "${{ steps.build.outputs.stderr }}" | npx badgr-ci-triage --json
+```
+
+---
+
+## Requirements
+
+- Node.js 18+

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { createLogger, fireTelemetry } from "badgr-shared";
+import { triageCiLog } from "./index.js";
+fireTelemetry({ package: "badgr-ci-triage" });
+function readArg(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    console.log(`badgr-ci-triage — local CI log triage
+
+Usage:
+  npx badgr-ci-triage --log "npm ERR ERESOLVE unable to resolve dependency tree"
+  npx badgr-ci-triage --log "<log text>" --json
+  echo "<log>" | npx badgr-ci-triage
+
+Flags:
+  --log <text>           First failing CI log section to triage
+  --json                 Output machine-readable JSON
+
+Categories detected:
+  dependency   ERESOLVE, lockfile, package not found
+  build        tsc, SyntaxError, webpack, vite
+  test         assert, snapshot, test failed
+  deployment   deploy, release, health check
+  race         flaky, timeout, deadlock
+  environment  env, secret, permission denied
+
+Exit codes:
+  0  Log present and categorised
+  1  Log empty or uncategorised
+
+No signup required. Hosted execution receipts are optional.
+
+Environment:
+  BADGR_TELEMETRY=0      Disable anonymous usage telemetry`);
+    process.exit(0);
+}
+const logArg = readArg("--log");
+// Accept piped stdin or positional args when --log is not provided.
+const logText = logArg ?? process.argv.slice(2).filter((a) => a !== "--json").join(" ");
+const json = process.argv.includes("--json");
+const result = triageCiLog(logText);
+const logger = createLogger(json);
+if (json) {
+    logger.report(result.report);
+}
+else {
+    logger.line(`Likely CI failure: ${result.category}`);
+    logger.line("");
+    for (const action of result.report.recommendedActions)
+        logger.line(`  - ${action}`);
+    logger.line("");
+    logger.line("Optional: use AI Badgr for execution receipts and failure history.");
+}
+process.exitCode = result.report.status === "failed" ? 1 : 0;
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,aAAa,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC,CAAC;AAE9C,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACnE,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;2DA0B6C,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAChC,oEAAoE;AACpE,MAAM,OAAO,GAAG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAExF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AACpC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;AAClC,IAAI,IAAI,EAAE,CAAC;IACT,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;KAAM,CAAC;IACN,MAAM,CAAC,IAAI,CAAC,sBAAsB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,kBAAkB;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC;IACpF,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,MAAM,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;AACpF,CAAC;AACD,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type DiagnosticCheck, type JsonReport } from "badgr-shared";
+export interface CiTriageResult {
+    category: "dependency" | "build" | "test" | "deployment" | "race" | "environment" | "unknown";
+    checks: DiagnosticCheck[];
+    report: JsonReport;
+}
+export declare function triageCiLog(log: string): CiTriageResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0D,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE7H,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC9F,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAsBvD"}

package/dist/index.js

@@ -0,0 +1,52 @@
+import { checkToFinding, createReport, reportStatusFromFindings } from "badgr-shared";
+export function triageCiLog(log) {
+    const lower = log.toLowerCase();
+    const category = classify(lower);
+    const checks = [
+        { name: "log-present", status: log.trim() ? "pass" : "fail", message: log.trim() ? "CI log provided" : "CI log is empty" },
+        { name: "failure-category", status: category === "unknown" ? "warn" : "fail", message: category === "unknown" ? "No known CI failure pattern matched" : `Likely ${category} failure detected`, details: { category } },
+    ];
+    const findings = checks.map((check) => checkToFinding(check, "CI_TRIAGE"));
+    const status = reportStatusFromFindings(findings);
+    return {
+        category,
+        checks,
+        report: createReport({
+            tool: "ci-triage",
+            status,
+            summary: category === "unknown" ? "CI failure needs manual review" : `Likely ${category} CI failure`,
+            findings,
+            recommendedActions: [nextStep(category), "Attach the triage report to the failing automation issue"],
+            nextCommand: "npx @aibadgr/ci-triage --json",
+            actionUrl: "https://aibadgr.com/agents/connect",
+        }),
+    };
+}
+function classify(log) {
+    if (/module not found|eresolve|dependency|lockfile|package not found/.test(log))
+        return "dependency";
+    if (/tsc|syntaxerror|compile|build failed|webpack|vite/.test(log))
+        return "build";
+    if (/flaky|timed out|timeout|race condition|deadlock/.test(log))
+        return "race";
+    if (/assert|expected|test failed|snapshot/.test(log))
+        return "test";
+    if (/deploy|release|rollout|health check/.test(log))
+        return "deployment";
+    if (/env|secret|permission denied|not configured/.test(log))
+        return "environment";
+    return "unknown";
+}
+function nextStep(category) {
+    const steps = {
+        dependency: "Reinstall dependencies from a clean lockfile and verify package versions",
+        build: "Run the build locally with the same runtime and inspect the first compiler error",
+        test: "Rerun the failing test with focused logging and isolate the assertion mismatch",
+        deployment: "Check deployment health checks, environment variables, and release logs",
+        race: "Rerun with serial execution or increased timeout to confirm race/flake behavior",
+        environment: "Verify required secrets, permissions, paths, and runtime config",
+        unknown: "Collect the first failing log section and rerun with verbose output",
+    };
+    return steps[category];
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,wBAAwB,EAAyC,MAAM,cAAc,CAAC;AAQ7H,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,MAAM,GAAsB;QAChC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,EAAE;QAC1H,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,qCAAqC,CAAC,CAAC,CAAC,UAAU,QAAQ,mBAAmB,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE;KACvN,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAClD,OAAO;QACL,QAAQ;QACR,MAAM;QACN,MAAM,EAAE,YAAY,CAAC;YACnB,IAAI,EAAE,WAAW;YACjB,MAAM;YACN,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,UAAU,QAAQ,aAAa;YACpG,QAAQ;YACR,kBAAkB,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,0DAA0D,CAAC;YACpG,WAAW,EAAE,+BAA+B;YAC5C,SAAS,EAAE,oCAAoC;SAChD,CAAC;KACH,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,iEAAiE,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACrG,IAAI,mDAAmD,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAClF,IAAI,iDAAiD,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAC/E,IAAI,sCAAsC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IACpE,IAAI,qCAAqC,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IACzE,IAAI,6CAA6C,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC;IAClF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,QAAQ,CAAC,QAAoC;IACpD,MAAM,KAAK,GAA+C;QACxD,UAAU,EAAE,0EAA0E;QACtF,KAAK,EAAE,kFAAkF;QACzF,IAAI,EAAE,gFAAgF;QACtF,UAAU,EAAE,yEAAyE;QACrF,IAAI,EAAE,iFAAiF;QACvF,WAAW,EAAE,iEAAiE;QAC9E,OAAO,EAAE,qEAAqE;KAC/E,CAAC;IACF,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC"}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "badgr-ci-triage",
+  "version": "0.1.0",
+  "description": "Local-first CI log triage for flaky tests, dependency failures, build errors, and race conditions.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": { "badgr-ci-triage": "dist/cli.js" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "tsc -b", "typecheck": "tsc -b --pretty false", "test": "vitest run" },
+  "dependencies": { "badgr-shared": "0.1.1" },
+  "engines": { "node": ">=18.0.0" },
+  "keywords": ["ci", "triage", "github-actions", "flaky", "build-failure"],
+  "license": "MIT"
+}