@fusionkit/cli 0.1.0 → 0.1.1

package/dist/gateway.js

@@ -10,6 +10,14 @@ import { join, resolve } from "node:path";
 import { runFusionPanels, runUnifiedHarnessE2E } from "@fusionkit/ensemble";
 import { emitTrace, newSpanId, newTraceId } from "@fusionkit/protocol";
 import { FusionBackend, installAcpAdapters, runAcpAgent, runFrontDoorAcceptance, startFusionGateway, startGateway } from "@fusionkit/model-gateway";
+// Once an interactive coding agent owns the terminal, the per-turn panel chatter
+// would corrupt its full-screen TUI. The launcher flips this off before handing
+// over; trace events (for --observe) keep flowing regardless.
+let gatewayChatter = true;
+/** Enable/disable the gateway's per-turn stderr chatter (default on). */
+export function setGatewayChatter(enabled) {
+    gatewayChatter = enabled;
+}
 function mapStatus(status) {
     if (status === "succeeded")
         return "succeeded";
@@ -224,7 +232,9 @@ export async function startFusionStepGateway(input) {
                 }
             }
         });
-        console.error(`fusion: running panel (${config.models.map((m) => m.id).join(", ")}) for session ${sessionKey}...`);
+        if (gatewayChatter) {
+            console.error(`fusion: running panel (${config.models.map((m) => m.id).join(", ")}) for session ${sessionKey}...`);
+        }
         try {
             const wire = await runFusionPanels({
                 id: `panels_${sessionKey}_t${turn}`,
@@ -241,12 +251,14 @@ export async function startFusionStepGateway(input) {
                 ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {})
             });
             const trajectories = normalizeWireTrajectories(wire);
-            console.error(`fusion: panel produced ${trajectories.length} candidate trajectories ` +
-                `(${trajectories.map((t) => `${t.model_id}:${t.status}`).join(", ")})`);
+            if (gatewayChatter) {
+                console.error(`fusion: panel produced ${trajectories.length} candidate trajectories ` +
+                    `(${trajectories.map((t) => `${t.model_id}:${t.status}`).join(", ")})`);
+            }
             return trajectories;
         }
         catch (error) {
-            console.error(`fusion: panel run failed: ${error instanceof Error ? error.stack : String(error)}`);
+            console.error(`fusion: panel run failed: ${error instanceof Error ? error.message : String(error)}`);
             throw error;
         }
     };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import "./quiet-warnings.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import "./quiet-warnings.js";
 import { PolicyDeniedError } from "@fusionkit/protocol";
 import { buildProgram } from "./cli.js";
 import { PreflightError } from "./shared/preflight.js";

package/dist/quiet-warnings.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/quiet-warnings.js

@@ -0,0 +1,24 @@
+const original = process.emitWarning.bind(process);
+function isExperimental(warning, typeOrOptions) {
+    if (warning instanceof Error && warning.name === "ExperimentalWarning")
+        return true;
+    if (typeof typeOrOptions === "string")
+        return typeOrOptions === "ExperimentalWarning";
+    if (typeOrOptions !== null && typeof typeOrOptions === "object" && "type" in typeOrOptions) {
+        return typeOrOptions.type === "ExperimentalWarning";
+    }
+    return false;
+}
+process.emitWarning = function patchedEmitWarning(warning, typeOrOptions, ...rest) {
+    if (isExperimental(warning, typeOrOptions))
+        return;
+    original(warning, typeOrOptions, ...rest);
+};
+// Children inherit process.env, so make Node subprocesses (the launched coding
+// agent, the cursor bridge, the dashboard) start with experimental warnings
+// disabled too. Non-Node children (python via uv/uvx) ignore NODE_OPTIONS.
+const DISABLE_EXPERIMENTAL = "--disable-warning=ExperimentalWarning";
+if (!(process.env.NODE_OPTIONS ?? "").includes(DISABLE_EXPERIMENTAL)) {
+    process.env.NODE_OPTIONS = [process.env.NODE_OPTIONS, DISABLE_EXPERIMENTAL].filter(Boolean).join(" ");
+}
+export {};

package/dist/shared/preflight.d.ts

@@ -4,6 +4,7 @@ export declare class PreflightError extends Error {
 }
 /** True when `bin` resolves on PATH. */
 export declare function hasBinary(bin: string): boolean;
+export declare const INSTALL_HINTS: Record<string, string>;
 /**
  * Fail fast with actionable guidance when a required binary or API key is
  * missing. Keeps "minimal setup" honest: clear errors instead of deep stack

package/dist/shared/preflight.js

@@ -17,7 +17,7 @@ export function hasBinary(bin) {
         return false;
     }
 }
-const INSTALL_HINTS = {
+export const INSTALL_HINTS = {
     uv: "install uv: https://docs.astral.sh/uv/getting-started/installation/",
     uvx: "install uv (ships uvx): https://docs.astral.sh/uv/getting-started/installation/",
     codex: "install the Codex CLI: https://github.com/openai/codex",

package/dist/shared/proc.d.ts

@@ -1,7 +1,12 @@
 import type { ChildProcess, SpawnOptions } from "node:child_process";
 /** Shared process helpers for the CLI's launcher/gateway flows. */
 export declare function sleep(ms: number): Promise<void>;
-/** Reserve an ephemeral loopback port and return it (closed before returning). */
+/**
+ * Reserve an ephemeral loopback port and return it. The probe socket is closed
+ * before returning (children bind it themselves), but the number is held out of
+ * circulation briefly so concurrent callers do not collide. Retries a bounded
+ * number of times if the OS hands back a number we just reserved.
+ */
 export declare function freePort(): Promise<number>;
 /**
  * Spawn a foreground tool with inherited stdio and resolve with its exit code.
@@ -9,19 +14,40 @@ export declare function freePort(): Promise<number>;
  * unhandled `error` event.
  */
 export declare function spawnTool(command: string, args: string[], env: Record<string, string>, cwd?: string): Promise<number>;
+export type LoggedSpawnOptions = SpawnOptions & {
+    /** Tee the child's full stdout+stderr to this path for post-mortem. */
+    logFile?: string;
+    /** Cap the in-memory ring buffer (default 256 KiB). */
+    maxLogBytes?: number;
+};
 /**
  * A spawned background child with captured output and a recorded spawn error.
  * Always attaches an `'error'` listener so a missing binary surfaces as a clear
- * message via {@link waitForHttp} instead of crashing the process.
+ * message via {@link waitForHttp} instead of crashing the process. The captured
+ * log is a bounded ring buffer (so long sessions cannot leak memory); the full,
+ * untruncated output is written to `logFile` when one is provided.
  */
 export type LoggedChild = {
     child: ChildProcess;
-    /** The combined stdout+stderr captured so far. */
+    /** The most recent captured stdout+stderr, up to the ring-buffer cap. */
     log: () => string;
     /** The spawn `'error'` (e.g. ENOENT), if one was emitted. */
     spawnError: () => Error | undefined;
+    /** The full log file path, when teeing was requested. */
+    logFile: () => string | undefined;
+    /** Flush and close the log file stream (best-effort). */
+    closeLog: () => void;
 };
-export declare function spawnLogged(command: string, args: string[], options?: SpawnOptions): LoggedChild;
+export declare function spawnLogged(command: string, args: string[], options?: LoggedSpawnOptions): LoggedChild;
+/**
+ * Distill the most useful slice of captured output for an error message. Prefers
+ * lines that look like errors (so the root cause is not buried under `uvx`
+ * resolve/build noise), then falls back to the head and tail of the log. The
+ * full log lives in the child's `logFile` when one was provided.
+ */
+export declare function distillLog(raw: string, options?: {
+    maxLines?: number;
+}): string;
 /**
  * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
  * to spawn, the child exits, or the timeout elapses. Distinguishes a failed
@@ -37,5 +63,10 @@ export declare function waitForOutput(proc: LoggedChild, pattern: RegExp, option
     timeoutMs: number;
     label: string;
 }): Promise<void>;
-/** SIGTERM a child, escalating to SIGKILL if it ignores the grace period. */
+/**
+ * SIGTERM a child's whole process group, escalating to SIGKILL if it ignores the
+ * grace period. Killing the group (`process.kill(-pid, ...)`) tears down wrapper
+ * trees like `uvx -> uv -> python`; if the child was not spawned detached (no
+ * group), it falls back to signalling the child directly.
+ */
 export declare function terminate(child: ChildProcess, graceMs?: number): void;

package/dist/shared/proc.js

@@ -1,11 +1,44 @@
 import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
 import { createServer } from "node:net";
 /** Shared process helpers for the CLI's launcher/gateway flows. */
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/** Reserve an ephemeral loopback port and return it (closed before returning). */
-export function freePort() {
+// Ports we have handed out very recently but whose child may not have bound
+// yet. Holding them out of circulation for a short window closes the race where
+// two concurrent `freePort()` callers (parallel server startup) receive the
+// same number between the probe socket closing and the child binding.
+const recentlyReserved = new Map();
+const RESERVATION_MS = 5000;
+function reserve(port) {
+    const existing = recentlyReserved.get(port);
+    if (existing !== undefined)
+        clearTimeout(existing);
+    const timer = setTimeout(() => recentlyReserved.delete(port), RESERVATION_MS);
+    timer.unref();
+    recentlyReserved.set(port, timer);
+}
+/**
+ * Reserve an ephemeral loopback port and return it. The probe socket is closed
+ * before returning (children bind it themselves), but the number is held out of
+ * circulation briefly so concurrent callers do not collide. Retries a bounded
+ * number of times if the OS hands back a number we just reserved.
+ */
+export async function freePort() {
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const port = await probeEphemeralPort();
+        if (!recentlyReserved.has(port)) {
+            reserve(port);
+            return port;
+        }
+    }
+    // Extremely unlikely; fall back to whatever the OS last offered.
+    const port = await probeEphemeralPort();
+    reserve(port);
+    return port;
+}
+function probeEphemeralPort() {
     return new Promise((resolve, reject) => {
         const server = createServer();
         server.on("error", reject);
@@ -32,14 +65,82 @@ export function spawnTool(command, args, env, cwd) {
         child.on("exit", (code) => resolveExit(code ?? 0));
     });
 }
+/** Keep at most this many bytes of a child's captured output in memory. */
+const DEFAULT_MAX_LOG_BYTES = 256 * 1024;
 export function spawnLogged(command, args, options = {}) {
-    const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
-    let log = "";
+    const { logFile, maxLogBytes, ...spawnOptions } = options;
+    const cap = maxLogBytes ?? DEFAULT_MAX_LOG_BYTES;
+    // `detached: true` makes the child its own process-group leader so that
+    // `terminate()` can signal the whole tree. This matters for wrappers like
+    // `uvx` (uvx -> uv -> python): signalling only the immediate child would
+    // orphan the grandchildren. Output is still piped; we never `unref()`, so the
+    // parent keeps managing the child's lifecycle.
+    const child = spawn(command, args, { ...spawnOptions, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    let buffer = "";
     let spawnError;
-    child.stdout?.on("data", (chunk) => (log += chunk.toString("utf8")));
-    child.stderr?.on("data", (chunk) => (log += chunk.toString("utf8")));
+    let file;
+    if (logFile !== undefined) {
+        try {
+            file = createWriteStream(logFile, { flags: "a" });
+            // A broken log sink must never crash the run.
+            file.on("error", () => { });
+        }
+        catch {
+            file = undefined;
+        }
+    }
+    const onChunk = (chunk) => {
+        const text = chunk.toString("utf8");
+        file?.write(text);
+        buffer += text;
+        if (buffer.length > cap)
+            buffer = buffer.slice(buffer.length - cap);
+    };
+    child.stdout?.on("data", onChunk);
+    child.stderr?.on("data", onChunk);
     child.on("error", (error) => (spawnError = error));
-    return { child, log: () => log, spawnError: () => spawnError };
+    return {
+        child,
+        log: () => buffer,
+        spawnError: () => spawnError,
+        logFile: () => logFile,
+        closeLog: () => {
+            try {
+                file?.end();
+            }
+            catch {
+                // already closed
+            }
+        }
+    };
+}
+/**
+ * Distill the most useful slice of captured output for an error message. Prefers
+ * lines that look like errors (so the root cause is not buried under `uvx`
+ * resolve/build noise), then falls back to the head and tail of the log. The
+ * full log lives in the child's `logFile` when one was provided.
+ */
+export function distillLog(raw, options = {}) {
+    const maxLines = options.maxLines ?? 16;
+    const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0)
+        return "";
+    const errorPattern = /error|exception|traceback|fatal|denied|unauthorized|forbidden|invalid|not found|refused|timed? ?out|missing|failed|panic|429|401|403|500/i;
+    const errorLines = lines.filter((line) => errorPattern.test(line));
+    if (errorLines.length > 0) {
+        return errorLines.slice(-maxLines).join("\n");
+    }
+    if (lines.length <= maxLines)
+        return lines.join("\n");
+    const head = lines.slice(0, Math.ceil(maxLines / 2));
+    const tail = lines.slice(-Math.floor(maxLines / 2));
+    return [...head, "...", ...tail].join("\n");
+}
+function failureDetail(proc) {
+    const distilled = distillLog(proc.log());
+    const logPath = proc.logFile();
+    const pathNote = logPath !== undefined ? `\n(full log: ${logPath})` : "";
+    return `${distilled}${pathNote}`;
 }
 /**
  * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
@@ -52,10 +153,10 @@ export async function waitForHttp(probeUrl, proc, options) {
     while (Date.now() < deadline) {
         const spawnError = proc.spawnError();
         if (spawnError !== undefined) {
-            throw new Error(`${options.label} failed to start: ${spawnError.message}\n${proc.log().slice(-500)}`);
+            throw new Error(`${options.label} failed to start: ${spawnError.message}\n${failureDetail(proc)}`);
         }
         if (proc.child.exitCode !== null) {
-            throw new Error(`${options.label} exited (code ${proc.child.exitCode}) before becoming ready\n${proc.log().slice(-500)}`);
+            throw new Error(`${options.label} exited (code ${proc.child.exitCode}) before becoming ready\n${failureDetail(proc)}`);
         }
         try {
             const response = await fetch(probeUrl);
@@ -68,19 +169,19 @@ export async function waitForHttp(probeUrl, proc, options) {
         }
         await sleep(400);
     }
-    throw new Error(`${options.label} did not become ready within ${options.timeoutMs}ms (${lastError})\n${proc.log().slice(-500)}`);
+    throw new Error(`${options.label} did not become ready within ${options.timeoutMs}ms (${lastError})\n${failureDetail(proc)}`);
 }
 /** Resolve once `pattern` is seen on the child's output, or reject on exit/timeout. */
 export function waitForOutput(proc, pattern, options) {
     return new Promise((resolve, reject) => {
         const deadline = setTimeout(() => {
             cleanup();
-            reject(new Error(`${options.label} did not start within ${options.timeoutMs}ms:\n${proc.log().slice(-500)}`));
+            reject(new Error(`${options.label} did not start within ${options.timeoutMs}ms:\n${failureDetail(proc)}`));
         }, options.timeoutMs);
         const poll = setInterval(() => {
             if (proc.spawnError() !== undefined) {
                 cleanup();
-                reject(new Error(`${options.label} failed to start: ${proc.spawnError()?.message}\n${proc.log().slice(-500)}`));
+                reject(new Error(`${options.label} failed to start: ${proc.spawnError()?.message}\n${failureDetail(proc)}`));
             }
             else if (pattern.test(proc.log())) {
                 cleanup();
@@ -89,7 +190,7 @@ export function waitForOutput(proc, pattern, options) {
         }, 100);
         const onExit = () => {
             cleanup();
-            reject(new Error(`${options.label} exited before becoming ready:\n${proc.log().slice(-500)}`));
+            reject(new Error(`${options.label} exited before becoming ready:\n${failureDetail(proc)}`));
         };
         proc.child.once("exit", onExit);
         function cleanup() {
@@ -99,24 +200,31 @@ export function waitForOutput(proc, pattern, options) {
         }
     });
 }
-/** SIGTERM a child, escalating to SIGKILL if it ignores the grace period. */
+/**
+ * SIGTERM a child's whole process group, escalating to SIGKILL if it ignores the
+ * grace period. Killing the group (`process.kill(-pid, ...)`) tears down wrapper
+ * trees like `uvx -> uv -> python`; if the child was not spawned detached (no
+ * group), it falls back to signalling the child directly.
+ */
 export function terminate(child, graceMs = 5000) {
-    if (child.exitCode !== null || child.signalCode !== null)
-        return;
-    try {
-        child.kill("SIGTERM");
-    }
-    catch {
+    if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null)
         return;
-    }
-    const timer = setTimeout(() => {
+    const pid = child.pid;
+    const signal = (sig) => {
         try {
-            child.kill("SIGKILL");
+            process.kill(-pid, sig);
         }
         catch {
-            // already gone
+            try {
+                child.kill(sig);
+            }
+            catch {
+                // already gone
+            }
         }
-    }, graceMs);
+    };
+    signal("SIGTERM");
+    const timer = setTimeout(() => signal("SIGKILL"), graceMs);
     timer.unref();
     child.once("exit", () => clearTimeout(timer));
 }

package/dist/test/fusion-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/fusion-config.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, test } from "node:test";
+import { FUSION_CONFIG_VERSION, FusionConfigError, fusionConfigPath, loadFusionConfig, parseFusionConfig, writeFusionConfig } from "../fusion-config.js";
+const tmpRoots = [];
+function freshDir() {
+    const dir = mkdtempSync(join(tmpdir(), "fusion-config-"));
+    tmpRoots.push(dir);
+    return dir;
+}
+after(() => {
+    for (const dir of tmpRoots)
+        rmSync(dir, { recursive: true, force: true });
+});
+test("parseFusionConfig accepts a valid config", () => {
+    const raw = {
+        version: FUSION_CONFIG_VERSION,
+        tool: "codex",
+        panel: [{ id: "gpt", model: "gpt-5.5", provider: "openai", keyEnv: "OPENAI_API_KEY" }],
+        judgeModel: "gpt-5.5",
+        local: false,
+        observe: true,
+        port: 1234
+    };
+    const config = parseFusionConfig(raw, "test");
+    assert.equal(config.tool, "codex");
+    assert.equal(config.panel?.length, 1);
+    assert.equal(config.panel?.[0]?.provider, "openai");
+    assert.equal(config.observe, true);
+    assert.equal(config.port, 1234);
+});
+test("parseFusionConfig rejects an unsupported version", () => {
+    assert.throws(() => parseFusionConfig({ version: "nope" }, "test"), FusionConfigError);
+});
+test("parseFusionConfig rejects an unknown panel provider", () => {
+    assert.throws(() => parseFusionConfig({ version: FUSION_CONFIG_VERSION, panel: [{ id: "x", model: "m", provider: "bogus" }] }, "test"), /panel\[0\]\.provider/);
+});
+test("parseFusionConfig rejects a panel entry missing model", () => {
+    assert.throws(() => parseFusionConfig({ version: FUSION_CONFIG_VERSION, panel: [{ id: "x" }] }, "test"), /panel\[0\]\.model/);
+});
+test("parseFusionConfig rejects a non-object", () => {
+    assert.throws(() => parseFusionConfig(["not", "an", "object"], "test"), FusionConfigError);
+});
+test("loadFusionConfig returns undefined when the file is absent", () => {
+    assert.equal(loadFusionConfig(freshDir()), undefined);
+});
+test("write then load round-trips the config", () => {
+    const dir = freshDir();
+    const config = {
+        version: FUSION_CONFIG_VERSION,
+        tool: "claude",
+        panel: [
+            { id: "gpt", model: "gpt-5.5", provider: "openai", keyEnv: "OPENAI_API_KEY" },
+            { id: "sonnet", model: "claude-sonnet-4-6", provider: "anthropic", keyEnv: "ANTHROPIC_API_KEY" }
+        ],
+        judgeModel: "gpt-5.5",
+        local: false,
+        observe: false
+    };
+    const path = writeFusionConfig(dir, config);
+    assert.equal(path, fusionConfigPath(dir));
+    const loaded = loadFusionConfig(dir);
+    assert.deepEqual(loaded, config);
+});
+test("writeFusionConfig refuses to clobber without force, overwrites with it", () => {
+    const dir = freshDir();
+    const base = { version: FUSION_CONFIG_VERSION, tool: "codex" };
+    writeFusionConfig(dir, base);
+    assert.throws(() => writeFusionConfig(dir, { version: FUSION_CONFIG_VERSION, tool: "claude" }), FusionConfigError);
+    writeFusionConfig(dir, { version: FUSION_CONFIG_VERSION, tool: "claude" }, { force: true });
+    const reloaded = loadFusionConfig(dir);
+    assert.equal(reloaded?.tool, "claude");
+});
+test("loadFusionConfig surfaces invalid JSON as a FusionConfigError", () => {
+    const dir = freshDir();
+    writeFileSync(fusionConfigPath(dir), "{ this is not json");
+    assert.throws(() => loadFusionConfig(dir), FusionConfigError);
+});

package/dist/test/proc.test.js

@@ -1,11 +1,33 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { freePort, spawnLogged, spawnTool, waitForHttp } from "../shared/proc.js";
+import { distillLog, freePort, spawnLogged, spawnTool, waitForHttp } from "../shared/proc.js";
 const MISSING_BINARY = "warrant-definitely-not-a-real-binary-xyz";
 test("freePort returns a usable ephemeral port", async () => {
     const port = await freePort();
     assert.ok(Number.isInteger(port) && port > 0);
 });
+test("freePort does not hand the same number to concurrent callers", async () => {
+    const ports = await Promise.all(Array.from({ length: 8 }, () => freePort()));
+    assert.equal(new Set(ports).size, ports.length, "all concurrently reserved ports must be distinct");
+});
+test("distillLog prefers error-looking lines over surrounding noise", () => {
+    const log = [
+        "resolving fusionkit@0.1.0",
+        "building wheels...",
+        "downloading numpy",
+        "Error: invalid API key for provider openai",
+        "extra trailing noise line"
+    ].join("\n");
+    const distilled = distillLog(log);
+    assert.match(distilled, /invalid API key/);
+});
+test("distillLog falls back to head and tail when no errors are present", () => {
+    const lines = Array.from({ length: 40 }, (_, i) => `line ${i}`);
+    const distilled = distillLog(lines.join("\n"), { maxLines: 6 });
+    assert.match(distilled, /line 0/);
+    assert.match(distilled, /line 39/);
+    assert.match(distilled, /\.\.\./);
+});
 test("spawnTool resolves with the child's exit code", async () => {
     assert.equal(await spawnTool(process.execPath, ["-e", "process.exit(3)"], {}), 3);
 });

package/dist/test/ui.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/ui.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { isInteractive } from "../ui/runtime.js";
+import { bold, cyan, glyph, supportsColor } from "../ui/theme.js";
+test("color helpers no-op and glyphs use ASCII when color is disabled", () => {
+    const prev = process.env.NO_COLOR;
+    process.env.NO_COLOR = "1";
+    try {
+        assert.equal(supportsColor(), false);
+        assert.equal(bold("hi"), "hi");
+        assert.equal(cyan("hi"), "hi");
+        assert.equal(glyph.tick(), "[ok]");
+        assert.equal(glyph.cross(), "[x]");
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.NO_COLOR;
+        else
+            process.env.NO_COLOR = prev;
+    }
+});
+test("isInteractive is false under the test runner (no TTY)", () => {
+    assert.equal(isInteractive(), false);
+});

package/dist/ui/boot.d.ts

@@ -0,0 +1,23 @@
+import type { StackReporter } from "../fusion-quickstart.js";
+export type BootView = {
+    /** Feed this to `startFusionStack({ report })` to drive the live checklist. */
+    report: StackReporter;
+    /** Settle the checklist and leave the final frame in place. */
+    stop: () => void;
+};
+export type BootServer = {
+    id: string;
+    label: string;
+};
+/**
+ * A live boot checklist: one row per panel server, an optional synthesizer row,
+ * and the gateway row. Maps {@link StackEvent}s onto a {@link StepList} so the
+ * user watches the real stack come up (spinners, elapsed time, check marks)
+ * instead of staring at a silent pause.
+ */
+export declare function createBootView(input: {
+    servers: readonly BootServer[];
+    includeSynth: boolean;
+    includeDashboard?: boolean;
+    title?: string;
+}): BootView;

package/dist/ui/boot.js

@@ -0,0 +1,56 @@
+import { StepList } from "./steps.js";
+/**
+ * A live boot checklist: one row per panel server, an optional synthesizer row,
+ * and the gateway row. Maps {@link StackEvent}s onto a {@link StepList} so the
+ * user watches the real stack come up (spinners, elapsed time, check marks)
+ * instead of staring at a silent pause.
+ */
+export function createBootView(input) {
+    const steps = [
+        ...(input.includeDashboard === true ? [{ id: "dashboard", label: "observability dashboard" }] : []),
+        ...input.servers.map((server) => ({ id: `srv:${server.id}`, label: `panel · ${server.label}` })),
+        ...(input.includeSynth ? [{ id: "synth", label: "synthesizer (fusionkit serve)" }] : []),
+        { id: "gw", label: "fusion gateway" }
+    ];
+    const list = new StepList(steps, input.title !== undefined ? { title: input.title } : {});
+    list.start();
+    const report = (event) => {
+        switch (event.kind) {
+            case "dashboard.start":
+                list.setActive("dashboard");
+                break;
+            case "dashboard.ready":
+                list.setDone("dashboard", event.detail);
+                break;
+            case "dashboard.fail":
+                list.setFailed("dashboard", event.detail);
+                break;
+            case "server.start":
+                list.setActive(`srv:${event.id}`);
+                break;
+            case "server.ready":
+                list.setDone(`srv:${event.id}`, event.detail);
+                break;
+            case "server.fail":
+                list.setFailed(`srv:${event.id}`, event.detail);
+                break;
+            case "synth.start":
+                list.setActive("synth");
+                break;
+            case "synth.ready":
+                list.setDone("synth", event.detail);
+                break;
+            case "gateway.start":
+                list.setActive("gw");
+                break;
+            case "gateway.ready":
+                list.setDone("gw", event.detail);
+                break;
+            default: {
+                const exhaustive = event;
+                throw new Error(`unknown stack event: ${String(exhaustive)}`);
+            }
+        }
+    };
+    return { report, stop: () => list.stop() };
+}

package/dist/ui/index.d.ts

@@ -0,0 +1,8 @@
+/** The fusionkit CLI's zero-dependency terminal UI layer. */
+export * from "./theme.js";
+export * from "./runtime.js";
+export { Spinner, withSpinner } from "./spinner.js";
+export { StepList } from "./steps.js";
+export type { StepInput, StepStatus } from "./steps.js";
+export { select, confirm, text, done, note } from "./prompt.js";
+export type { SelectOption } from "./prompt.js";

package/dist/ui/index.js

@@ -0,0 +1,6 @@
+/** The fusionkit CLI's zero-dependency terminal UI layer. */
+export * from "./theme.js";
+export * from "./runtime.js";
+export { Spinner, withSpinner } from "./spinner.js";
+export { StepList } from "./steps.js";
+export { select, confirm, text, done, note } from "./prompt.js";