@backburner/cli 0.1.0

package/dist/src/capabilities/validator.js

@@ -0,0 +1,87 @@
+/**
+ * Validates requested capabilities against declared MCP dependencies and their current status.
+ *
+ * This implementation takes a normalized capabilities object as returned
+ * by loadCapabilitiesConfig() or loadConfig().
+ */
+export function validateCapabilities(capabilities, declaredMcps, mcpStatuses) {
+    const { sensors, controllers } = capabilities;
+    const declaredHandles = new Set(declaredMcps.map((d) => d.handle));
+    const statusByHandle = new Map(mcpStatuses.map((s) => [s.handle, s]));
+    const valid = [];
+    const blocked = [];
+    const processCapability = (name, uses, kind) => {
+        if (!declaredHandles.has(uses)) {
+            blocked.push({ name, kind, uses, reason: "missing_mcp_handle" });
+            return;
+        }
+        const statusRecord = statusByHandle.get(uses);
+        if (!statusRecord) {
+            blocked.push({
+                name,
+                kind,
+                uses,
+                reason: "mcp_not_connection_ready",
+                message: "MCP has not been checked yet — no status record available.",
+            });
+            return;
+        }
+        const message = statusRecord.actionRequired?.message ?? statusRecord.message;
+        switch (statusRecord.status) {
+            case "ready":
+                valid.push({ name, kind, uses, mcpStatus: "ready" });
+                break;
+            case "action_required":
+                blocked.push({
+                    name,
+                    kind,
+                    uses,
+                    reason: "mcp_action_required",
+                    mcpStatus: "action_required",
+                    ...(message ? { message } : {}),
+                });
+                break;
+            case "resolved":
+                blocked.push({
+                    name,
+                    kind,
+                    uses,
+                    reason: "mcp_not_connection_ready",
+                    mcpStatus: "resolved",
+                    ...(message ? { message } : {}),
+                });
+                break;
+            case "resolution_failed":
+                blocked.push({
+                    name,
+                    kind,
+                    uses,
+                    reason: "mcp_resolution_failed",
+                    mcpStatus: "resolution_failed",
+                    ...(message ? { message } : {}),
+                });
+                break;
+            case "error":
+                blocked.push({
+                    name,
+                    kind,
+                    uses,
+                    reason: "mcp_error",
+                    mcpStatus: "error",
+                    ...(message ? { message } : {}),
+                });
+                break;
+            default: {
+                const _exhaustive = statusRecord.status;
+                throw new Error(`Unexpected MCP status: ${_exhaustive}`);
+            }
+        }
+    };
+    for (const sensor of sensors) {
+        processCapability(sensor.name, sensor.uses, "sensor");
+    }
+    for (const controller of controllers) {
+        processCapability(controller.name, controller.uses, "controller");
+    }
+    return { valid, blocked };
+}

package/dist/src/cli/commands/broker-smoke.js

@@ -0,0 +1,96 @@
+import * as path from "node:path";
+import { ExecFileCommandRunner } from "../../utils/command-runner.js";
+import { loadConfig } from "../../config/loader.js";
+import { GhCliGitHubGateway } from "../../github/gateway.js";
+import { GitHubBrokerService } from "../../github/broker.js";
+import { startGitHubBrokerServer } from "../../github/broker-server.js";
+import { ComposedBrokerService } from "../../github/composed.js";
+import { PlanBreakdownSessionStore } from "../../workstreams/plan-breakdown-generator/store.js";
+import { PlanBreakdownToolService } from "../../workstreams/plan-breakdown-generator/tools.js";
+import { WaveAssessmentSessionStore } from "../../workstreams/wave-assessment/store.js";
+import { WaveAssessmentToolService } from "../../workstreams/wave-assessment/tools.js";
+import { defaultBackburnerManagementRoot } from "../../utils/paths.js";
+import { defaultStderrLogger } from "../../utils/logger.js";
+import { DEFAULT_GITHUB_BROKER_PORT, readOptionalNumberFlag, readOptionalStringFlag, readStringFlag } from "../options.js";
+export async function runBrokerSmokeCli(argv, logger = defaultStderrLogger) {
+    const managementDir = path.resolve(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
+    const host = "127.0.0.1";
+    const config = await loadConfig(managementDir);
+    const commandRunner = new ExecFileCommandRunner();
+    const gitHubGateway = new GhCliGitHubGateway(commandRunner, config.allowedUsers);
+    const githubBrokerService = new GitHubBrokerService(gitHubGateway, config.repos, logger);
+    const planBreakdownSessionStore = new PlanBreakdownSessionStore();
+    const planBreakdownToolService = new PlanBreakdownToolService(planBreakdownSessionStore, logger);
+    const waveAssessmentSessionStore = new WaveAssessmentSessionStore();
+    const waveAssessmentToolService = new WaveAssessmentToolService(waveAssessmentSessionStore, logger);
+    const brokerService = new ComposedBrokerService([
+        githubBrokerService,
+        planBreakdownToolService,
+        waveAssessmentToolService
+    ]);
+    const server = await startGitHubBrokerServer({
+        brokerService,
+        host,
+        port: DEFAULT_GITHUB_BROKER_PORT,
+        logger
+    });
+    try {
+        const initializeResponse = await postJson(server.url, {
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: {
+                    name: "backburner-smoke",
+                    version: "0.1.0"
+                }
+            }
+        });
+        const toolsResponse = await postJson(server.url, {
+            jsonrpc: "2.0",
+            id: 2,
+            method: "tools/list",
+            params: {}
+        });
+        process.stdout.write(JSON.stringify({
+            serverUrl: server.url,
+            initialize: initializeResponse.result,
+            tools: toolsResponse.result?.tools ?? []
+        }, null, 2) + "\n");
+        const repo = readOptionalStringFlag(argv, "--repo");
+        const issueNumber = readOptionalNumberFlag(argv, "--issue-number");
+        if (repo && issueNumber) {
+            const issueResponse = await postJson(server.url, {
+                jsonrpc: "2.0",
+                id: 3,
+                method: "tools/call",
+                params: {
+                    name: "get_issue",
+                    arguments: {
+                        repo,
+                        issueNumber
+                    }
+                }
+            });
+            process.stdout.write(`${JSON.stringify(issueResponse.result, null, 2)}\n`);
+        }
+    }
+    finally {
+        await server.close();
+    }
+}
+async function postJson(url, payload) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json"
+        },
+        body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+        throw new Error(`Broker smoke request failed with HTTP ${response.status}`);
+    }
+    return (await response.json());
+}

package/dist/src/cli/commands/broker.js

@@ -0,0 +1,56 @@
+import * as path from "node:path";
+import { ExecFileCommandRunner } from "../../utils/command-runner.js";
+import { loadConfig } from "../../config/loader.js";
+import { GhCliGitHubGateway } from "../../github/gateway.js";
+import { GitHubBrokerService } from "../../github/broker.js";
+import { startGitHubBrokerServer } from "../../github/broker-server.js";
+import { ComposedBrokerService } from "../../github/composed.js";
+import { PlanBreakdownSessionStore } from "../../workstreams/plan-breakdown-generator/store.js";
+import { PlanBreakdownToolService } from "../../workstreams/plan-breakdown-generator/tools.js";
+import { WaveAssessmentSessionStore } from "../../workstreams/wave-assessment/store.js";
+import { WaveAssessmentToolService } from "../../workstreams/wave-assessment/tools.js";
+import { defaultBackburnerManagementRoot } from "../../utils/paths.js";
+import { defaultStderrLogger } from "../../utils/logger.js";
+import { DEFAULT_GITHUB_BROKER_PORT, readNumberFlag, readStringFlag } from "../options.js";
+export async function runBrokerCli(argv, logger = defaultStderrLogger) {
+    const managementDir = path.resolve(readStringFlag(argv, "--management-dir", defaultBackburnerManagementRoot()));
+    const port = readNumberFlag(argv, "--port", DEFAULT_GITHUB_BROKER_PORT);
+    const host = readStringFlag(argv, "--host", "127.0.0.1");
+    const config = await loadConfig(managementDir);
+    const commandRunner = new ExecFileCommandRunner();
+    const gitHubGateway = new GhCliGitHubGateway(commandRunner, config.allowedUsers);
+    const githubBrokerService = new GitHubBrokerService(gitHubGateway, config.repos, logger);
+    const planBreakdownSessionStore = new PlanBreakdownSessionStore();
+    const planBreakdownToolService = new PlanBreakdownToolService(planBreakdownSessionStore, logger);
+    const waveAssessmentSessionStore = new WaveAssessmentSessionStore();
+    const waveAssessmentToolService = new WaveAssessmentToolService(waveAssessmentSessionStore, logger);
+    const brokerService = new ComposedBrokerService([
+        githubBrokerService,
+        planBreakdownToolService,
+        waveAssessmentToolService
+    ]);
+    const server = await startGitHubBrokerServer({
+        brokerService,
+        host,
+        port,
+        logger
+    });
+    process.stdout.write(`${server.url}\n`);
+    await new Promise((resolve, reject) => {
+        const shutdown = async () => {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            try {
+                await server.close();
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            }
+        };
+        const onSigint = () => void shutdown();
+        const onSigterm = () => void shutdown();
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+    });
+}

package/dist/src/cli/commands/init.js

@@ -0,0 +1,4 @@
+import { runInitCli } from "../init.js";
+export async function runInitCommand(argv) {
+    await runInitCli(argv);
+}

package/dist/src/cli/commands/journal.js

@@ -0,0 +1,43 @@
+import * as path from "node:path";
+import { JournalReader } from "../../journal/index.js";
+import { renderJournalEntries } from "../../journal/renderer.js";
+import { defaultBackburnerOutputsRoot, resolveOutputsJournalRoot } from "../../utils/paths.js";
+import { CliUsageError } from "../errors.js";
+import { readOptionalStringFlag, readStringFlag } from "../options.js";
+export async function runJournalCli(argv, injectedJournal) {
+    const outputsDir = path.resolve(readStringFlag(argv, "--outputs-dir", defaultBackburnerOutputsRoot()));
+    const journalDir = resolveOutputsJournalRoot(outputsDir);
+    const reader = injectedJournal ? injectedJournal.reader : new JournalReader(journalDir);
+    const repoId = readOptionalStringFlag(argv, "--repo");
+    const workstreamId = readOptionalStringFlag(argv, "--workstream");
+    const issueRaw = readOptionalStringFlag(argv, "--issue");
+    const prRaw = readOptionalStringFlag(argv, "--pr");
+    const since = readOptionalStringFlag(argv, "--since");
+    const lastRaw = readOptionalStringFlag(argv, "--last");
+    const isJson = argv.includes("--json");
+    const isVerbose = argv.includes("--verbose");
+    const issueNumber = issueRaw !== undefined ? Number(issueRaw) : undefined;
+    const prNumber = prRaw !== undefined ? Number(prRaw) : undefined;
+    const limit = lastRaw !== undefined ? Number(lastRaw) : 50;
+    if (issueRaw !== undefined && (!Number.isInteger(issueNumber) || issueNumber <= 0)) {
+        throw new CliUsageError(`--issue must be a positive integer, got: ${issueRaw}`);
+    }
+    if (prRaw !== undefined && (!Number.isInteger(prNumber) || prNumber <= 0)) {
+        throw new CliUsageError(`--pr must be a positive integer, got: ${prRaw}`);
+    }
+    if (lastRaw !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+        throw new CliUsageError(`--last must be a positive integer, got: ${lastRaw}`);
+    }
+    if (since !== undefined && isNaN(new Date(since).getTime())) {
+        throw new CliUsageError(`--since must be a valid ISO date, got: ${since}`);
+    }
+    const entries = await reader.query({
+        ...(repoId !== undefined ? { repoId } : {}),
+        ...(workstreamId !== undefined ? { workstreamId } : {}),
+        ...(issueNumber !== undefined ? { issueNumber } : {}),
+        ...(prNumber !== undefined ? { prNumber } : {}),
+        ...(since !== undefined ? { since } : {}),
+        limit
+    });
+    process.stdout.write(renderJournalEntries(entries, { json: isJson, verbose: isVerbose }));
+}

package/dist/src/cli/commands/run-loop.js

@@ -0,0 +1,56 @@
+import { formatRunSummary } from "../output.js";
+import { defaultStderrLogger } from "../../utils/logger.js";
+import { CliUsageError } from "../errors.js";
+import { delayWithAbort, isAbortError, readIntervalMs } from "../options.js";
+import { runCli } from "./run.js";
+import { runInteractiveTui, shouldUseRuntimeStatusScreen, SerializedCycleRunner } from "./tui.js";
+export { SerializedCycleRunner };
+export async function runLoopCli(argv, options = {}) {
+    const [command, ...rest] = argv;
+    if (command !== "run-loop") {
+        throw new CliUsageError('Expected command: backburner run-loop [--code-root <path>] [--management-dir <path>] [--outputs-dir <path>] [--log-dir <path>] [--broker-port <port>] [--interval-seconds <seconds> | --interval-minutes <minutes>] [--headless]');
+    }
+    if (shouldUseRuntimeStatusScreen(rest)) {
+        await runInteractiveTui(["run", ...rest]);
+        return;
+    }
+    const intervalMs = readIntervalMs(rest);
+    const logger = options.logger ?? defaultStderrLogger;
+    const delay = options.delay ?? delayWithAbort;
+    const signalRegistrar = options.signalRegistrar ?? process;
+    const abortController = new AbortController();
+    let stopRequested = false;
+    const requestStop = () => {
+        stopRequested = true;
+        abortController.abort();
+    };
+    signalRegistrar.on("SIGINT", requestStop);
+    signalRegistrar.on("SIGTERM", requestStop);
+    try {
+        logger.info(`Starting orchestrator run loop with interval ${Math.floor(intervalMs / 1000)}s`);
+        while (!stopRequested) {
+            const summary = await runCli(["run", ...rest], options);
+            process.stdout.write(formatRunSummary(summary));
+            if (stopRequested) {
+                break;
+            }
+            logger.info(`Waiting ${Math.floor(intervalMs / 1000)}s before the next orchestration cycle`);
+            try {
+                await delay(intervalMs, abortController.signal);
+            }
+            catch (error) {
+                if (!isAbortError(error)) {
+                    throw error;
+                }
+            }
+            if (stopRequested) {
+                break;
+            }
+        }
+        logger.info("Run loop stopped after the current orchestration cycle completed.");
+    }
+    finally {
+        signalRegistrar.off("SIGINT", requestStop);
+        signalRegistrar.off("SIGTERM", requestStop);
+    }
+}