@prads01/blackbox 0.1.0 → 0.1.2

package/README.md

@@ -1,48 +1,90 @@
 # BlackBox CLI
 
-Developer CLI for running BlackBox analysis against a local web app.
+A CLI for real-time incident analysis, sandboxed fixes, and automated PR generation.
 
-## Install (local dev)
+## What is BlackBox?
+BlackBox is a local incident operations tool for engineering teams. It reads runtime evidence, identifies contradictions between expected and actual behavior, and produces structured analysis that can be verified in a safe sandbox. It is designed to shorten the path from detection to validated fix.
 
+## Overview
+- Analyze local web apps via `/api/analyze`
+- Detect and track incidents
+- Generate sandboxed fixes
+- Verify fixes before applying
+- Create GitHub PRs directly
+- Full TUI + CLI support
+
+## Features
+- Detect runtime contradictions from logs
+- AI-powered root cause analysis
+- Sandbox fix verification (safe, isolated)
+- One-click GitHub PR creation
+- Interactive terminal UI (TUI)
+
+## Installation
 ```bash
-cd cli
-npm install
-npm run build
-npm link
+npm install -g @prads01/blackbox
+```
+
+## Quick Start
+```bash
+blackbox setup
+blackbox
 ```
 
-Then run:
+`blackbox setup` initializes and validates `.blackbox.yaml`.  
+`blackbox` launches the interactive TUI.
 
+## Usage
+
+Run analysis:
 ```bash
-blackbox --help
+blackbox analyze
 ```
 
-## Commands
+Watch logs:
+```bash
+blackbox watch
+```
 
-- `blackbox` - launch full-screen BlackBox TUI mode
-- `blackbox ui` - launch full-screen BlackBox TUI mode
-- `blackbox setup` - interactive onboarding and `.blackbox.yaml` generation
-- `blackbox init` - quick default config file creation
-- `blackbox analyze` - run one analysis against `/api/analyze`
-- `blackbox watch` - monitor log file and re-run analysis on changes
-- `blackbox status` - show config and API reachability
+Open TUI:
+```bash
+blackbox
+```
 
-## TUI shortcuts
+TUI navigation basics:
+- Arrow keys to move
+- Enter to open/execute
+- Backspace to return from detail views
 
-- `a` run analyze
-- `w` start/stop watch mode
-- `i` incidents view
-- `d` dashboard view
-- `s` sandbox view
-- `x` run sandbox fix for latest incident
-- `r` refresh status/incidents
-- `q` quit
+Key shortcuts:
+- `a` → analyze
+- `i` → incidents
+- `s` → sandbox
+- `x` → run fix
+- `c` → create PR
+- `q` → quit
 
-## Publish to npm later
+## Workflow
+1. BlackBox detects an incident.
+2. AI analyzes likely root cause.
+3. Sandbox verifies a fix safely.
+4. User creates a GitHub PR.
+5. Incident is marked resolved.
 
+## Configuration
+BlackBox uses `.blackbox.yaml` for local runtime configuration. Core fields:
+- project name
+- API base URL
+- log path
+
+## Development
 ```bash
+git clone <repo>
 cd cli
+npm install
 npm run build
-npm login
-npm publish --access public
+npm link
 ```
+
+## License
+MIT

package/dist/commands/analyze.js

@@ -1,10 +1,10 @@
 import { callAnalyzeApi } from "../api.js";
-import { readConfig } from "../config.js";
 import { loadEvidenceFromConfig } from "../files.js";
+import { ensureRepoLinkedForCli } from "../linking.js";
 import { printTruthReport } from "../report.js";
 import { colors, section } from "../utils/format.js";
 export async function runAnalyzeOnce() {
-    const config = await readConfig();
+    const config = await ensureRepoLinkedForCli();
     const evidence = await loadEvidenceFromConfig(config);
     const payload = {
         project: {

package/dist/commands/setup.js

@@ -139,6 +139,7 @@ export async function runSetup() {
         expected_file: expectedFile,
         config_file: configFile,
         commit_file: base.commit_file || defaults.commit_file,
+        linked_repo: base.linked_repo,
     };
     const writeSpinner = ora("Writing .blackbox.yaml").start();
     const configPath = await writeConfig(configToWrite);

package/dist/commands/status.js

@@ -1,9 +1,9 @@
 import { isApiReachable } from "../api.js";
-import { readConfig } from "../config.js";
+import { ensureRepoLinkedForCli } from "../linking.js";
 import { colors, row, section } from "../utils/format.js";
 export async function runStatus() {
     try {
-        const config = await readConfig();
+        const config = await ensureRepoLinkedForCli();
         section("BlackBox Status");
         row("Project:", config.project_name);
         row("Environment:", config.environment);
@@ -12,6 +12,7 @@ export async function runStatus() {
         row("Expected file:", config.expected_file);
         row("Config file:", config.config_file);
         row("Commit file:", config.commit_file);
+        row("Linked repo:", config.linked_repo ?? colors.warn("not linked"));
         const reachable = await isApiReachable(config);
         row("API reachable:", reachable ? colors.ok("yes") : colors.bad("no"));
     }

package/dist/commands/watch.js

@@ -1,13 +1,13 @@
 import chokidar from "chokidar";
 import path from "node:path";
-import { readConfig } from "../config.js";
+import { ensureRepoLinkedForCli } from "../linking.js";
 import { runAnalyzeOnce } from "./analyze.js";
 import { colors, row, section } from "../utils/format.js";
 const WATCH_DEBOUNCE_MS = 1200;
 const WATCH_COOLDOWN_MS = 2000;
 export async function runWatch() {
     try {
-        const config = await readConfig();
+        const config = await ensureRepoLinkedForCli();
         const absoluteLogPath = path.resolve(process.cwd(), config.log_file);
         let isAnalyzing = false;
         let debounceTimer = null;

package/dist/config.js

@@ -10,10 +10,10 @@ export function createDefaultConfig(cwd = process.cwd()) {
         project_name: path.basename(cwd),
         environment: "local",
         api_base_url: "http://localhost:3000",
-        log_file: "src/demo/cache-mismatch/logs.txt",
-        expected_file: "src/demo/cache-mismatch/expected.md",
-        config_file: "src/demo/cache-mismatch/config.json",
-        commit_file: "src/demo/cache-mismatch/commit.diff",
+        log_file: "demo-system/logs/app.log",
+        expected_file: "demo-system/config/service-config.json",
+        config_file: "demo-system/state/system-state.json",
+        commit_file: "demo-system/config/recent-change.json",
     };
 }
 function assertConfigShape(value) {

package/dist/linking.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import { readConfig, writeConfig } from "./config.js";
+import { colors } from "./utils/format.js";
+function openBrowser(url) {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        const child = spawn("open", [url], { detached: true, stdio: "ignore" });
+        child.unref();
+        return;
+    }
+    if (platform === "win32") {
+        const child = spawn("cmd", ["/c", "start", "", url], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        return;
+    }
+    const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    child.unref();
+}
+async function startLinkFlow(config) {
+    const response = await fetch(`${config.api_base_url}/api/cli/link/start`, {
+        method: "POST",
+    });
+    if (!response.ok) {
+        throw new Error(`Unable to start CLI link flow (${response.status}).`);
+    }
+    return (await response.json());
+}
+async function getLinkStatus(config, token) {
+    const response = await fetch(`${config.api_base_url}/api/cli/link/${token}`, {
+        method: "GET",
+    });
+    if (!response.ok) {
+        throw new Error(`Unable to fetch CLI link status (${response.status}).`);
+    }
+    return (await response.json());
+}
+export async function ensureRepoLinkedForCli() {
+    const config = await readConfig();
+    if (config.linked_repo && config.linked_repo.trim().length > 0) {
+        return config;
+    }
+    console.log(colors.warn("No linked GitHub repo found for this CLI config."));
+    console.log(colors.muted("Starting browser-based auth and repo linking flow..."));
+    const start = await startLinkFlow(config);
+    console.log(colors.title(`Open this URL if browser does not open:\n${start.linkUrl}`));
+    try {
+        openBrowser(start.linkUrl);
+    }
+    catch {
+        // no-op, URL is already printed
+    }
+    const maxAttempts = 120;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+        const status = await getLinkStatus(config, start.token);
+        if (status.status !== "completed" || !status.repo)
+            continue;
+        const linkedRepo = status.repo.fullName;
+        const nextConfig = {
+            ...config,
+            linked_repo: linkedRepo,
+        };
+        await writeConfig(nextConfig);
+        console.log(colors.ok(`Linked repository: ${linkedRepo}`));
+        return nextConfig;
+    }
+    throw new Error("CLI link timed out. Complete browser auth and retry.");
+}

package/dist/tui/app.js

@@ -1,5 +1,5 @@
 import blessed from "blessed";
-import { fetchApiReachability, fetchIncidents, loadTuiConfig, triggerCreatePr, triggerAnalysis, triggerSandboxFix, updateIncidentStatus, } from "./data.js";
+import { fetchAnalysisRun, fetchApiReachability, fetchIncidents, loadTuiConfig, startAnalysisRun, triggerCreatePr, triggerSandboxFix, updateIncidentStatus, } from "./data.js";
 import { attachKeybindings } from "./keybindings.js";
 import { indexToView, palette, renderFooter, renderMain, renderSidebar, viewToIndex, } from "./render.js";
 import { TuiWatchService } from "./watch-service.js";
@@ -27,6 +27,7 @@ function createInitialState(config) {
         incidents: [],
         selectedIncidentIndex: 0,
         incidentsMode: "list",
+        contextSourceView: "logs",
         sandboxMode: "list",
         selectedSandboxIndex: 0,
         lastSandboxIncidentId: null,
@@ -39,6 +40,7 @@ function createInitialState(config) {
         sandboxPrError: null,
         sandboxPrInFlight: false,
         analyzeInFlight: false,
+        currentAnalysisRun: null,
         busyMessage: null,
         statusMessage: null,
         errorMessage: null,
@@ -220,12 +222,29 @@ export async function runTui() {
         state.analyzeInFlight = true;
         let didSucceed = false;
         await withBusy("Analyzing...", async () => {
-            await triggerAnalysis(config);
-            state.lastAnalysisAt = new Date().toISOString();
-            await refreshData();
-            state.view = "dashboard";
-            state.selectedNavIndex = viewToIndex("dashboard");
-            didSucceed = true;
+            const run = await startAnalysisRun(config);
+            state.currentAnalysisRun = run;
+            state.view = "analyze";
+            state.selectedNavIndex = viewToIndex("analyze");
+            render();
+            while (true) {
+                await new Promise((resolve) => setTimeout(resolve, 700));
+                const next = await fetchAnalysisRun(config, run.id);
+                state.currentAnalysisRun = next;
+                render();
+                if (next.status === "running")
+                    continue;
+                if (next.status === "failed") {
+                    state.errorMessage = next.error ?? "Analysis run failed.";
+                    break;
+                }
+                didSucceed = true;
+                state.lastAnalysisAt = new Date().toISOString();
+                await refreshData();
+                state.view = "dashboard";
+                state.selectedNavIndex = viewToIndex("dashboard");
+                break;
+            }
         });
         state.analyzeInFlight = false;
         if (didSucceed) {

package/dist/tui/data.js

@@ -1,6 +1,6 @@
 import { isApiReachable } from "../api.js";
-import { readConfig } from "../config.js";
 import { loadEvidenceFromConfig } from "../files.js";
+import { ensureRepoLinkedForCli } from "../linking.js";
 function assertIncidentsResponse(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -25,11 +25,21 @@ function assertIncidentsResponse(value) {
             typeof i.impact === "string" &&
             typeof i.nextAction === "string" &&
             (i.evidencePoints === undefined || Array.isArray(i.evidencePoints)) &&
+            (i.investigation === undefined ||
+                (typeof i.investigation === "object" &&
+                    i.investigation !== null &&
+                    typeof i.investigation.investigationSummary ===
+                        "string" &&
+                    Array.isArray(i.investigation.evidence) &&
+                    typeof i.investigation.confidence === "number")) &&
+            (i.investigationTimeline === undefined || Array.isArray(i.investigationTimeline)) &&
+            (i.investigationTools === undefined || Array.isArray(i.investigationTools)) &&
+            (i.toolOutputsSummary === undefined || Array.isArray(i.toolOutputsSummary)) &&
             typeof i.timestamp === "string");
     });
 }
 export async function loadTuiConfig() {
-    return readConfig();
+    return ensureRepoLinkedForCli();
 }
 export async function fetchApiReachability(config) {
     return isApiReachable(config);
@@ -80,6 +90,69 @@ export async function triggerAnalysis(config) {
     }
     return result;
 }
+function assertAnalysisRun(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (typeof candidate.id !== "string" ||
+        (candidate.status !== "running" &&
+            candidate.status !== "completed" &&
+            candidate.status !== "failed") ||
+        typeof candidate.startedAt !== "string" ||
+        !Array.isArray(candidate.steps)) {
+        return false;
+    }
+    return candidate.steps.every((step) => {
+        if (!step || typeof step !== "object")
+            return false;
+        const s = step;
+        return (typeof s.id === "string" &&
+            typeof s.label === "string" &&
+            (s.status === "pending" || s.status === "running" || s.status === "completed"));
+    });
+}
+export async function startAnalysisRun(config) {
+    const evidence = await loadEvidenceFromConfig(config);
+    const payload = {
+        project: {
+            name: config.project_name,
+            environment: config.environment,
+        },
+        evidence,
+    };
+    const response = await fetch(`${config.api_base_url}/api/analyze/run`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Analyze run start failed (${response.status}): ${body}`);
+    }
+    const payloadJson = (await response.json());
+    const run = payloadJson.run;
+    if (!assertAnalysisRun(run)) {
+        throw new Error("Analyze run start returned invalid payload.");
+    }
+    return run;
+}
+export async function fetchAnalysisRun(config, runId) {
+    const response = await fetch(`${config.api_base_url}/api/analyze/run/${runId}`, {
+        method: "GET",
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Analyze run fetch failed (${response.status}): ${body}`);
+    }
+    const payload = (await response.json());
+    const run = payload.run;
+    if (!assertAnalysisRun(run)) {
+        throw new Error("Analyze run status payload invalid.");
+    }
+    return run;
+}
 function assertSandboxResult(value) {
     if (!value || typeof value !== "object")
         return false;

package/dist/tui/keybindings.js

@@ -56,6 +56,7 @@ export function attachKeybindings(screen, state, actions) {
         }
         if (state.view === "incidents" && state.incidentsMode === "list" && state.incidents.length > 0) {
             state.incidentsMode = "detail";
+            state.contextSourceView = "logs";
             actions.render();
             return;
         }
@@ -82,9 +83,34 @@ export function attachKeybindings(screen, state, actions) {
     screen.key(["i"], () => {
         state.view = "incidents";
         state.incidentsMode = "list";
+        state.contextSourceView = "logs";
         state.selectedNavIndex = 1;
         actions.render();
     });
+    screen.key(["1"], () => {
+        if (state.view === "incidents" && state.incidentsMode === "detail") {
+            state.contextSourceView = "logs";
+            actions.render();
+        }
+    });
+    screen.key(["2"], () => {
+        if (state.view === "incidents" && state.incidentsMode === "detail") {
+            state.contextSourceView = "config";
+            actions.render();
+        }
+    });
+    screen.key(["3"], () => {
+        if (state.view === "incidents" && state.incidentsMode === "detail") {
+            state.contextSourceView = "commits";
+            actions.render();
+        }
+    });
+    screen.key(["4"], () => {
+        if (state.view === "incidents" && state.incidentsMode === "detail") {
+            state.contextSourceView = "system_state";
+            actions.render();
+        }
+    });
     screen.key(["s"], () => {
         state.view = "sandbox";
         state.sandboxMode = "list";

package/dist/tui/render.js

@@ -108,6 +108,48 @@ function renderIncidentDetail(state) {
     if (!incident) {
         return "Incident not found.";
     }
+    const investigation = incident.investigation;
+    const evidence = investigation?.evidence && investigation.evidence.length > 0
+        ? investigation.evidence
+        : incident.evidencePoints ?? [];
+    const timeline = incident.investigationTimeline ?? [];
+    const investigationTools = incident.investigationTools ?? [];
+    const context = incident.context;
+    const contextHeader = [
+        "{bold}{white-fg}CONTEXT SOURCES{/white-fg}{/bold}",
+        `[1] Logs  [2] Config  [3] Commits  [4] System State  (active: ${state.contextSourceView})`,
+    ];
+    const contextBody = (() => {
+        if (!context)
+            return ["No context data available for this incident."];
+        if (state.contextSourceView === "logs") {
+            const logs = context.logs?.slice(-12) ?? [];
+            return logs.length > 0 ? logs : ["No log lines available."];
+        }
+        if (state.contextSourceView === "config") {
+            return [
+                `Service: ${context.systemState.service || "N/A"}`,
+                `Environment: ${context.systemState.environment || "N/A"}`,
+                `Expected Topic: ${context.systemState.invalidationTopicExpected || "N/A"}`,
+            ];
+        }
+        if (state.contextSourceView === "commits") {
+            const commits = context.recentCommits ?? [];
+            if (commits.length === 0)
+                return ["No commit context available."];
+            return commits.slice(0, 5).flatMap((commit) => [
+                `${commit.sha.slice(0, 7)} ${commit.message}`,
+                `  ${commit.summary}`,
+            ]);
+        }
+        return [
+            `Cache Version: ${context.systemState.cacheVersion || "N/A"}`,
+            `DB Version: ${context.systemState.dbVersion || "N/A"}`,
+            `Observed Topic: ${context.systemState.invalidationTopicObserved || "N/A"}`,
+            `Expected Topic: ${context.systemState.invalidationTopicExpected || "N/A"}`,
+            `Error Rate: ${context.systemState.recentErrorRate || "N/A"}`,
+        ];
+    })();
     return [
         "{bold}{white-fg}Incident Report{/white-fg}{/bold}",
         "{gray-fg}Backspace to return to incidents list.{/gray-fg}",
@@ -123,6 +165,10 @@ function renderIncidentDetail(state) {
         "{bold}{white-fg}Root Cause{/white-fg}{/bold}",
         incident.rootCause,
         "",
+        "{bold}{white-fg}Investigation Summary{/white-fg}{/bold}",
+        investigation?.investigationSummary ?? "No synthesized investigation summary available.",
+        `{bold}Confidence{/bold}: ${investigation ? `${Math.round(investigation.confidence * 100)}%` : "N/A"}`,
+        "",
         "{bold}{white-fg}Impact{/white-fg}{/bold}",
         incident.impact,
         "",
@@ -130,15 +176,37 @@ function renderIncidentDetail(state) {
         incident.fixSuggestion?.trim() || "No fix suggestion available.",
         "",
         "{bold}{white-fg}Evidence Points{/white-fg}{/bold}",
-        ...(incident.evidencePoints?.length
-            ? incident.evidencePoints.slice(0, 5).map((point) => `- ${point}`)
+        ...(evidence.length
+            ? evidence.slice(0, 5).map((point) => `- ${point}`)
             : ["- No evidence points available."]),
+        "",
+        "{bold}{white-fg}Investigation Timeline{/white-fg}{/bold}",
+        ...(timeline.length
+            ? timeline.slice(0, 8).map((entry) => {
+                const source = entry.source ? ` [${entry.source}]` : "";
+                return `${entry.step}. ${entry.title}${source}\n   ${entry.detail}`;
+            })
+            : ["No timeline steps available."]),
+        "",
+        "{bold}{white-fg}Investigation Tools{/white-fg}{/bold}",
+        ...(investigationTools.length
+            ? investigationTools.map((tool) => {
+                const status = tool.status === "completed"
+                    ? "{green-fg}completed{/green-fg}"
+                    : "{red-fg}failed{/red-fg}";
+                return `- ${tool.name} [${status}]\n   ${tool.summary}`;
+            })
+            : ["No tool execution records available."]),
+        "",
+        ...contextHeader,
+        ...contextBody,
     ].join("\n");
 }
 function renderIncidents(state) {
     return state.incidentsMode === "detail" ? renderIncidentDetail(state) : renderIncidentList(state);
 }
 function renderAnalyze(state) {
+    const run = state.currentAnalysisRun;
     return [
         "{bold}{white-fg}Analyze{/white-fg}{/bold}",
         "",
@@ -147,6 +215,29 @@ function renderAnalyze(state) {
         "",
         "Press {bold}a{/bold} to trigger analysis once.",
         "Repeated keypresses are ignored while analysis is running.",
+        "",
+        "{bold}{white-fg}Investigation Activity{/white-fg}{/bold}",
+        ...(run
+            ? [
+                `Run ID: ${run.id}`,
+                `Run Status: ${run.status === "completed"
+                    ? "{green-fg}COMPLETED{/green-fg}"
+                    : run.status === "failed"
+                        ? "{red-fg}FAILED{/red-fg}"
+                        : "{yellow-fg}RUNNING{/yellow-fg}"}`,
+                ...(run.incidentId ? [`Incident: ${run.incidentId}`] : []),
+                "",
+                ...run.steps.map((step, index) => {
+                    const status = step.status === "completed"
+                        ? "{green-fg}completed{/green-fg}"
+                        : step.status === "running"
+                            ? "{yellow-fg}running{/yellow-fg}"
+                            : "{gray-fg}pending{/gray-fg}";
+                    const detail = step.detail ? `\n   ${step.detail}` : "";
+                    return `${index + 1}. ${step.label} [${status}]${detail}`;
+                }),
+            ]
+            : ["No active investigation run."]),
     ].join("\n");
 }
 function renderWatch(state) {
@@ -269,9 +360,12 @@ export function renderMain(main, state) {
 }
 export function renderFooter(footer, state) {
     const hotkeysBase = "a analyze | w watch | i incidents | d dashboard | s sandbox | x sandbox-fix | f mark-fixed | v mark-investigating";
+    const contextHotkeys = state.view === "incidents" && state.incidentsMode === "detail"
+        ? " | 1 logs | 2 config | 3 commits | 4 system"
+        : "";
     const hotkeys = canCreatePrFromSandbox(state)
-        ? `${hotkeysBase} | c create-pr | r refresh | q quit`
-        : `${hotkeysBase} | r refresh | q quit`;
+        ? `${hotkeysBase}${contextHotkeys} | c create-pr | r refresh | q quit`
+        : `${hotkeysBase}${contextHotkeys} | r refresh | q quit`;
     const status = [
         `focus:${state.focusZone.toUpperCase()}`,
         `api:${state.apiReachable ? "up" : "down"}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prads01/blackbox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "BlackBox CLI for local incident analysis and sandboxed fixes",
   "license": "MIT",
   "type": "module",