@prads01/blackbox 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# BlackBox CLI
+
+Developer CLI for running BlackBox analysis against a local web app.
+
+## Install (local dev)
+
+```bash
+cd cli
+npm install
+npm run build
+npm link
+```
+
+Then run:
+
+```bash
+blackbox --help
+```
+
+## Commands
+
+- `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
+
+## TUI shortcuts
+
+- `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
+
+## Publish to npm later
+
+```bash
+cd cli
+npm run build
+npm login
+npm publish --access public
+```

package/dist/api.js

@@ -0,0 +1,65 @@
+function isSeverity(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "critical";
+}
+function isAnalysisResult(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const result = value;
+    if (typeof result.incidentTitle !== "string")
+        return false;
+    if (typeof result.impact !== "string")
+        return false;
+    if (!Array.isArray(result.brokenAssumptions))
+        return false;
+    if (!result.rootCause || typeof result.rootCause !== "object")
+        return false;
+    if (!result.recommendedNextAction || typeof result.recommendedNextAction !== "object") {
+        return false;
+    }
+    const assumptions = result.brokenAssumptions;
+    const topAssumption = assumptions[0];
+    if (topAssumption && !isSeverity(topAssumption.severity))
+        return false;
+    return true;
+}
+function isAnalyzeApiResponse(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const payload = value;
+    return isAnalysisResult(payload.result);
+}
+export async function callAnalyzeApi(config, requestPayload) {
+    const response = await fetch(`${config.api_base_url}/api/analyze`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(requestPayload),
+    });
+    if (!response.ok) {
+        throw new Error(`API request failed with status ${response.status}`);
+    }
+    const payload = (await response.json());
+    if (!isAnalyzeApiResponse(payload)) {
+        throw new Error("Invalid API response shape");
+    }
+    return payload.result;
+}
+export async function isApiReachable(config) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 4000);
+        const response = await fetch(`${config.api_base_url}/api/health`, {
+            method: "GET",
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok)
+            return false;
+        const payload = (await response.json());
+        return !!payload && typeof payload === "object" && payload.ok === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/analyze.js

@@ -0,0 +1,30 @@
+import { callAnalyzeApi } from "../api.js";
+import { readConfig } from "../config.js";
+import { loadEvidenceFromConfig } from "../files.js";
+import { printTruthReport } from "../report.js";
+import { colors, section } from "../utils/format.js";
+export async function runAnalyzeOnce() {
+    const config = await readConfig();
+    const evidence = await loadEvidenceFromConfig(config);
+    const payload = {
+        project: {
+            name: config.project_name,
+            environment: config.environment,
+        },
+        evidence,
+    };
+    const result = await callAnalyzeApi(config, payload);
+    printTruthReport(result);
+    return result;
+}
+export async function runAnalyze() {
+    section("Running analysis");
+    try {
+        await runAnalyzeOnce();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(colors.bad(`Analyze failed: ${message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,11 @@
+import { createDefaultConfig, writeConfig } from "../config.js";
+import { colors, row, section } from "../utils/format.js";
+export async function runInit() {
+    const config = createDefaultConfig();
+    const configPath = await writeConfig(config);
+    section("Initialized BlackBox");
+    row("Config file:", configPath);
+    row("Project:", config.project_name);
+    row("Environment:", config.environment);
+    console.log(colors.muted("Edit .blackbox.yaml to match your local project paths."));
+}

package/dist/commands/setup.js

@@ -0,0 +1,148 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { cancel, intro, isCancel, note, outro, select, text, } from "@clack/prompts";
+import boxen from "boxen";
+import chalk from "chalk";
+import ora from "ora";
+import { createDefaultConfig, readConfig, writeConfig } from "../config.js";
+async function promptText(message, initialValue, validate) {
+    const value = await text({
+        message,
+        initialValue,
+        validate,
+    });
+    if (isCancel(value)) {
+        cancel("Setup canceled.");
+        process.exit(0);
+    }
+    return (value ?? "").trim();
+}
+async function detectExistingConfig() {
+    try {
+        return await readConfig();
+    }
+    catch {
+        return null;
+    }
+}
+async function validateOptionalPath(filePath) {
+    if (!filePath.trim())
+        return "Path cannot be empty.";
+    const absolute = path.resolve(process.cwd(), filePath);
+    try {
+        await fs.access(absolute);
+        return null;
+    }
+    catch {
+        return `File not found: ${filePath}`;
+    }
+}
+async function checkApiReachability(apiBaseUrl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 4000);
+    try {
+        const response = await fetch(`${apiBaseUrl}/api/health`, {
+            method: "GET",
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return false;
+        const payload = (await response.json());
+        return !!payload && typeof payload === "object" && payload.ok === true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function runSetup() {
+    intro(boxen(`${chalk.bold.cyan("BLACKBOX CLI SETUP")}\n${chalk.gray("Initialize local forensic analysis configuration")}`, {
+        borderColor: "cyan",
+        borderStyle: "round",
+        padding: 1,
+    }));
+    const defaults = createDefaultConfig();
+    const existing = await detectExistingConfig();
+    const base = existing ?? defaults;
+    const projectName = await promptText("Project name", base.project_name, (value) => (value ?? "").trim().length > 0 ? undefined : "Project name is required.");
+    const envSelection = await select({
+        message: "Environment",
+        options: [
+            { value: "local", label: "local" },
+            { value: "staging", label: "staging" },
+            { value: "production", label: "production" },
+            { value: "custom", label: "custom" },
+        ],
+        initialValue: base.environment === "local" ||
+            base.environment === "staging" ||
+            base.environment === "production"
+            ? base.environment
+            : "custom",
+    });
+    if (isCancel(envSelection)) {
+        cancel("Setup canceled.");
+        process.exit(0);
+    }
+    const environment = envSelection === "custom"
+        ? await promptText("Custom environment name", base.environment, (value) => (value ?? "").trim().length > 0 ? undefined : "Environment is required.")
+        : envSelection;
+    const apiBaseUrl = await promptText("API base URL", base.api_base_url, (value) => {
+        const normalized = (value ?? "").trim();
+        if (!normalized)
+            return "API base URL is required.";
+        try {
+            const parsed = new URL(normalized);
+            return parsed.protocol === "http:" || parsed.protocol === "https:"
+                ? undefined
+                : "URL must start with http:// or https://";
+        }
+        catch {
+            return "Enter a valid URL.";
+        }
+    });
+    const logFile = await promptText("Log file path", base.log_file, (value) => (value ?? "").trim().length > 0 ? undefined : "Log file path is required.");
+    const expectedFile = await promptText("Expected behavior file path", base.expected_file, (value) => ((value ?? "").trim().length > 0 ? undefined : "Expected file path is required."));
+    const configFile = await promptText("Config snapshot file path", base.config_file, (value) => (value ?? "").trim().length > 0 ? undefined : "Config file path is required.");
+    const validationSpinner = ora("Validating local file paths").start();
+    const pathErrors = [];
+    const validations = await Promise.all([
+        validateOptionalPath(logFile),
+        validateOptionalPath(expectedFile),
+        validateOptionalPath(configFile),
+    ]);
+    for (const maybeError of validations) {
+        if (maybeError)
+            pathErrors.push(maybeError);
+    }
+    if (pathErrors.length > 0) {
+        validationSpinner.warn("Some files were not found");
+        note(pathErrors.join("\n"), "Path Validation");
+    }
+    else {
+        validationSpinner.succeed("Local file paths look good");
+    }
+    const apiSpinner = ora("Checking API reachability").start();
+    const reachable = await checkApiReachability(apiBaseUrl);
+    if (reachable) {
+        apiSpinner.succeed("BlackBox API is reachable");
+    }
+    else {
+        apiSpinner.warn("Could not reach API at /api/health (continuing)");
+    }
+    const configToWrite = {
+        project_name: projectName,
+        environment,
+        api_base_url: apiBaseUrl,
+        log_file: logFile,
+        expected_file: expectedFile,
+        config_file: configFile,
+        commit_file: base.commit_file || defaults.commit_file,
+    };
+    const writeSpinner = ora("Writing .blackbox.yaml").start();
+    const configPath = await writeConfig(configToWrite);
+    writeSpinner.succeed(`Config saved: ${configPath}`);
+    note(`${chalk.cyan("blackbox watch")}\n${chalk.cyan("blackbox analyze")}\n${chalk.cyan("blackbox status")}`, "Next Steps");
+    outro(chalk.green("BlackBox setup complete."));
+}

package/dist/commands/status.js

@@ -0,0 +1,23 @@
+import { isApiReachable } from "../api.js";
+import { readConfig } from "../config.js";
+import { colors, row, section } from "../utils/format.js";
+export async function runStatus() {
+    try {
+        const config = await readConfig();
+        section("BlackBox Status");
+        row("Project:", config.project_name);
+        row("Environment:", config.environment);
+        row("API base URL:", config.api_base_url);
+        row("Log file:", config.log_file);
+        row("Expected file:", config.expected_file);
+        row("Config file:", config.config_file);
+        row("Commit file:", config.commit_file);
+        const reachable = await isApiReachable(config);
+        row("API reachable:", reachable ? colors.ok("yes") : colors.bad("no"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(colors.bad(`Status failed: ${message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/watch.js

@@ -0,0 +1,64 @@
+import chokidar from "chokidar";
+import path from "node:path";
+import { readConfig } from "../config.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 absoluteLogPath = path.resolve(process.cwd(), config.log_file);
+        let isAnalyzing = false;
+        let debounceTimer = null;
+        let lastRunAt = 0;
+        section("BlackBox Watch");
+        row("Monitoring:", absoluteLogPath);
+        row("API endpoint:", `${config.api_base_url}/api/analyze`);
+        console.log(colors.muted("Waiting for log changes...\n"));
+        const runAnalysis = async () => {
+            const now = Date.now();
+            if (isAnalyzing)
+                return;
+            if (now - lastRunAt < WATCH_COOLDOWN_MS)
+                return;
+            isAnalyzing = true;
+            console.log(colors.title("[DETECTED] Log change detected. Re-running analysis..."));
+            try {
+                await runAnalyzeOnce();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(colors.bad(`Analyze failed: ${message}`));
+            }
+            finally {
+                isAnalyzing = false;
+                lastRunAt = Date.now();
+            }
+        };
+        const watcher = chokidar.watch(absoluteLogPath, {
+            awaitWriteFinish: {
+                stabilityThreshold: 1500,
+                pollInterval: 100,
+            },
+        });
+        watcher.on("change", () => {
+            if (isAnalyzing)
+                return;
+            if (Date.now() - lastRunAt < WATCH_COOLDOWN_MS)
+                return;
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+            }
+            debounceTimer = setTimeout(() => {
+                debounceTimer = null;
+                void runAnalysis();
+            }, WATCH_DEBOUNCE_MS);
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(colors.bad(`Watch failed: ${message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/config.js

@@ -0,0 +1,51 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+const CONFIG_FILENAME = ".blackbox.yaml";
+export function getConfigPath(cwd = process.cwd()) {
+    return path.join(cwd, CONFIG_FILENAME);
+}
+export function createDefaultConfig(cwd = process.cwd()) {
+    return {
+        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",
+    };
+}
+function assertConfigShape(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Invalid .blackbox.yaml: expected object");
+    }
+    const requiredKeys = [
+        "project_name",
+        "environment",
+        "api_base_url",
+        "log_file",
+        "expected_file",
+        "config_file",
+        "commit_file",
+    ];
+    for (const key of requiredKeys) {
+        const field = value[key];
+        if (typeof field !== "string" || field.trim() === "") {
+            throw new Error(`Invalid .blackbox.yaml: missing or invalid "${key}"`);
+        }
+    }
+}
+export async function readConfig(cwd = process.cwd()) {
+    const configPath = getConfigPath(cwd);
+    const raw = await fs.readFile(configPath, "utf8");
+    const parsed = yaml.load(raw);
+    assertConfigShape(parsed);
+    return parsed;
+}
+export async function writeConfig(config, cwd = process.cwd()) {
+    const configPath = getConfigPath(cwd);
+    const serialized = yaml.dump(config);
+    await fs.writeFile(configPath, serialized, "utf8");
+    return configPath;
+}

package/dist/files.js

@@ -0,0 +1,20 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+async function readLocalFile(cwd, filePath) {
+    const resolvedPath = path.resolve(cwd, filePath);
+    return fs.readFile(resolvedPath, "utf8");
+}
+export async function loadEvidenceFromConfig(config, cwd = process.cwd()) {
+    const [logs, expected, configData, commit] = await Promise.all([
+        readLocalFile(cwd, config.log_file),
+        readLocalFile(cwd, config.expected_file),
+        readLocalFile(cwd, config.config_file),
+        readLocalFile(cwd, config.commit_file),
+    ]);
+    return {
+        logs,
+        expected,
+        config: configData,
+        commit,
+    };
+}

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runAnalyze } from "./commands/analyze.js";
+import { runInit } from "./commands/init.js";
+import { runSetup } from "./commands/setup.js";
+import { runStatus } from "./commands/status.js";
+import { runWatch } from "./commands/watch.js";
+import { runTui } from "./tui/app.js";
+if (process.argv.length <= 2) {
+    try {
+        await runTui();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Unable to launch TUI: ${message}`);
+        console.error("Run `blackbox setup` first to create .blackbox.yaml.");
+        process.exit(1);
+    }
+}
+else {
+    const program = new Command();
+    program
+        .name("blackbox")
+        .description("BlackBox local developer CLI")
+        .version("0.1.0");
+    program
+        .command("init")
+        .description("Create a .blackbox.yaml file in the current directory")
+        .action(async () => {
+        await runInit();
+    });
+    program
+        .command("setup")
+        .description("Interactive setup for .blackbox.yaml with validation")
+        .action(async () => {
+        await runSetup();
+    });
+    program
+        .command("ui")
+        .description("Launch full-screen BlackBox terminal UI")
+        .action(async () => {
+        try {
+            await runTui();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Unable to launch TUI: ${message}`);
+            console.error("Run `blackbox setup` first to create .blackbox.yaml.");
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command("analyze")
+        .description("Send configured evidence to the local BlackBox analysis API")
+        .action(async () => {
+        await runAnalyze();
+    });
+    program
+        .command("watch")
+        .description("Watch the configured log file and re-run analysis on changes")
+        .action(async () => {
+        await runWatch();
+    });
+    program
+        .command("status")
+        .description("Show active config and API reachability")
+        .action(async () => {
+        await runStatus();
+    });
+    await program.parseAsync(process.argv);
+}

package/dist/report.js

@@ -0,0 +1,36 @@
+import { colors, line, row, section } from "./utils/format.js";
+const SEVERITY_ORDER = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+function getHighestSeverity(result) {
+    const assumptions = result.brokenAssumptions;
+    if (assumptions.length === 0)
+        return "low";
+    return assumptions.reduce((top, item) => {
+        return SEVERITY_ORDER[item.severity] > SEVERITY_ORDER[top] ? item.severity : top;
+    }, "low");
+}
+function formatSeverity(value) {
+    if (value === "critical")
+        return colors.bad(value.toUpperCase());
+    if (value === "high")
+        return colors.warn(value.toUpperCase());
+    return colors.muted(value.toUpperCase());
+}
+export function printTruthReport(result) {
+    const topAssumption = result.brokenAssumptions[0];
+    const severity = getHighestSeverity(result);
+    section("BlackBox Truth Report");
+    row("Incident:", result.incidentTitle);
+    row("Severity:", formatSeverity(severity));
+    row("Top contradiction:", topAssumption ? topAssumption.statement : result.summary);
+    row("Likely root cause:", result.rootCause.title);
+    row("Impact:", result.impact);
+    row("Next action:", result.recommendedNextAction.summary);
+    line();
+    row("Owner:", `${result.recommendedNextAction.owner} (${result.recommendedNextAction.priority})`);
+    row("Success criteria:", result.recommendedNextAction.successCriteria);
+}