@fusionkit/cli 0.1.0

package/dist/render.js

@@ -0,0 +1,131 @@
+import { buildReceiptStory } from "@fusionkit/protocol";
+/** One screen, five questions. This is the product. */
+export function renderReceipt(bundle) {
+    const { contract, receipt } = bundle;
+    const story = buildReceiptStory(bundle);
+    const lines = [];
+    const changed = bundle.events.filter((e) => e.event.type === "file.changed");
+    const approvers = contract.approvedBy?.map((a) => a.id).join(", ");
+    lines.push(`warrant receipt ${story.runId} [${story.status}]`);
+    lines.push("");
+    lines.push("1. What moved?");
+    lines.push(`   in:  workspace @ ${story.workspace.baseRef.slice(0, 12)} (manifest ${story.workspace.manifestHash.slice(0, 12)})`);
+    if (contract.continuation) {
+        lines.push(`   in:  continuation of checkpoint ${contract.continuation.checkpointId} (envelope ${contract.continuation.envelopeHash.slice(0, 12)}, tier ${contract.continuation.tier})`);
+    }
+    lines.push(`   out: ${changed.length} file(s) changed, diff ${receipt.workspaceOut.diffHash ? receipt.workspaceOut.diffHash.slice(0, 12) : "none"}, ${receipt.workspaceOut.artifactHashes.length} artifact(s)`);
+    for (const disclosure of receipt.boundaryDisclosures) {
+        lines.push(`   boundary ${disclosure.direction}: ${disclosure.dataClass} ${disclosure.contentHash.slice(0, 12)}`);
+    }
+    lines.push("");
+    lines.push("2. Why did it move?");
+    lines.push(`   task: ${contract.task.prompt}`);
+    lines.push(`   requested by: ${contract.requestedBy.id}`);
+    lines.push("");
+    lines.push("3. Who or what approved it?");
+    lines.push(approvers
+        ? `   approved by: ${approvers}`
+        : "   policy: auto-allowed (no consent rule matched)");
+    lines.push(`   policy snapshot: ${story.policyHash.slice(0, 12)}`);
+    lines.push("");
+    lines.push("4. Which runtime, model, tools, data, and secrets saw it?");
+    lines.push(`   runner: ${receipt.runner.runnerId} (pool ${receipt.runner.pool}, attestation: ${receipt.runner.attestationTier}, isolation: ${story.isolation})`);
+    lines.push(`   agent: ${story.agent}${contract.agent.version ? `@${contract.agent.version}` : ""}`);
+    lines.push(`   secrets released: ${story.secrets.length > 0
+        ? story.secrets.join(", ")
+        : "none"}`);
+    lines.push(`   network: ${story.network.length > 0
+        ? story.network.join(", ")
+        : "no egress attempted"}`);
+    lines.push(`   models: ${receipt.modelsUsed.length > 0
+        ? receipt.modelsUsed.map((m) => `${m.provider}/${m.model}`).join(", ")
+        : "not observable at session boundary (vendor harness)"}`);
+    lines.push("");
+    lines.push("5. How can you resume, inspect, revoke, or reproduce it?");
+    lines.push(`   contract: ${receipt.contractHash.slice(0, 16)} (signed, expires ${contract.expiresAt})`);
+    lines.push(`   events: ${story.eventCount} hash-chained, head ${story.eventsHead.slice(0, 12)}`);
+    lines.push(`   pull results: warrant pull ${receipt.runId}`);
+    lines.push(`   verify offline: ${story.verificationCommand}`);
+    return lines.join("\n");
+}
+export function renderDisclosure(report) {
+    const lines = [];
+    lines.push("warrant dry run: nothing moved. This is what would:");
+    lines.push("");
+    lines.push(`agent: ${report.agent.kind} on pool "${report.pool}"`);
+    lines.push(`workspace: base ${report.workspace.baseRef.slice(0, 12)}`);
+    lines.push(`  bundle ${report.workspace.bundleHash.slice(0, 12)}`);
+    if (report.workspace.dirtyDiffHash) {
+        lines.push(`  uncommitted diff ${report.workspace.dirtyDiffHash.slice(0, 12)}`);
+    }
+    lines.push(`  untracked included: ${report.workspace.untrackedPaths.length > 0
+        ? report.workspace.untrackedPaths.join(", ")
+        : "none"}`);
+    lines.push(`  denied capture: ${report.workspace.deniedPaths.length > 0
+        ? report.workspace.deniedPaths.join(", ")
+        : "none"}`);
+    if (report.continuation) {
+        lines.push(`continuation: checkpoint ${report.continuation.checkpointId} (envelope ${report.continuation.envelopeHash.slice(0, 12)}, tier ${report.continuation.tier})`);
+    }
+    lines.push(`secrets that would be released: ${report.secrets.length > 0
+        ? report.secrets.map((s) => `${s.name} (${s.scope})`).join(", ")
+        : "none"}`);
+    lines.push(`network egress: ${report.network.defaultDeny
+        ? `deny-by-default, allowlist [${report.network.allowHosts.join(", ")}]`
+        : "allow-all (policy permits)"}`);
+    lines.push(`budget: $${report.budget.maxSpendUsd ?? "policy-default"} / ${report.budget.maxDurationMin ?? "policy-default"}m`);
+    lines.push(`disclosure mode: ${report.disclosure}`);
+    lines.push(`policy decision: ${report.policyDecision.decision} (${report.policyDecision.reason})`);
+    return lines.join("\n");
+}
+export function renderRunList(runs) {
+    if (runs.length === 0)
+        return "no runs yet";
+    const lines = [];
+    for (const run of runs) {
+        const continuation = run.continuation ? " ↩ continuation" : "";
+        const prompt = run.prompt.length > 56 ? `${run.prompt.slice(0, 53)}...` : run.prompt;
+        lines.push(`${run.runId}  [${run.status}]  ${run.agentKind} @ ${run.pool}${continuation}`);
+        lines.push(`  "${prompt}" — ${run.requestedBy.id}, ${run.createdAt}`);
+    }
+    return lines.join("\n");
+}
+export function renderTrace(events) {
+    const lines = ["handoff trace:"];
+    for (const event of events) {
+        switch (event.type) {
+            case "checkpoint.created":
+                lines.push(`  ${event.ts}  checkpoint.created      ${event.checkpointId} (tier ${event.tier})`);
+                break;
+            case "continuation.planned":
+                lines.push(`  ${event.ts}  continuation.planned    ${event.decision} → ${event.target}: ${event.reasons.join("; ")}`);
+                break;
+            case "envelope.created":
+                lines.push(`  ${event.ts}  envelope.created        ${event.envelopeId} (${event.envelopeHash.slice(0, 12)}) → ${event.target}`);
+                break;
+            case "run.requested":
+                lines.push(`  ${event.ts}  run.requested           ${event.runId} [${event.status}]`);
+                break;
+            case "run.terminal":
+                lines.push(`  ${event.ts}  run.terminal            ${event.runId} [${event.status}]`);
+                break;
+            case "results.pulled":
+                lines.push(`  ${event.ts}  results.pulled          ${event.runId} (${event.mode})`);
+                break;
+            case "tool.called":
+                lines.push(`  ${event.ts}  tool.called             ${event.toolName} [${event.ok ? "ok" : "error"}] input ${event.inputHash.slice(0, 12)}${event.outputHash ? ` → ${event.outputHash.slice(0, 12)}` : ""} (${event.durationMs}ms)`);
+                break;
+            case "continuation.requested":
+                lines.push(`  ${event.ts}  continuation.requested  ${event.reason ?? "(no reason given)"}`);
+                break;
+            case "model.routed":
+                lines.push(`  ${event.ts}  model.routed            ${event.route}:${event.model}${event.escalated ? " (escalated)" : ""} — ${event.reason}`);
+                break;
+            default: {
+                const exhausted = event;
+                throw new Error(`unreachable trace event: ${String(exhausted)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/shared/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared CLI failure helper: print a one-line `error: ...` to stderr and exit
+ * non-zero. Used for validation that commander does not express directly, so
+ * the wording (which tests assert) stays under our control.
+ */
+export declare function fail(message: string): never;

package/dist/shared/errors.js

@@ -0,0 +1,9 @@
+/**
+ * Shared CLI failure helper: print a one-line `error: ...` to stderr and exit
+ * non-zero. Used for validation that commander does not express directly, so
+ * the wording (which tests assert) stays under our control.
+ */
+export function fail(message) {
+    console.error(`error: ${message}`);
+    process.exit(1);
+}

package/dist/shared/options.d.ts

@@ -0,0 +1,24 @@
+import type { EnsembleModel, HarnessLiveSmokeTarget, UnifiedHarnessKind } from "@fusionkit/ensemble";
+import type { SessionIsolation } from "@fusionkit/protocol";
+import type { FusionTool, PanelModelSpec, PanelProvider } from "../fusion-quickstart.js";
+/** Commander reducer for repeatable string options (`--flag a --flag b`). */
+export declare function collect(value: string, previous?: string[]): string[];
+/** Parse `ID=VALUE`, failing with a flag-specific message on malformed input. */
+export declare function parseIdValue(flag: string, spec: string): {
+    id: string;
+    value: string;
+};
+/**
+ * Map `--model ID=MODEL` specs to ensemble models, falling back to harness-aware
+ * defaults when none are given.
+ */
+export declare function ensembleModels(model: string[] | undefined, harness?: string): EnsembleModel[];
+export declare function liveSmokeTargets(targets: string[] | undefined): HarnessLiveSmokeTarget[];
+export declare function unifiedHarnessKinds(targets: string[] | undefined): UnifiedHarnessKind[];
+export declare function parseTimeoutMs(raw: string | undefined, fallback: number): number;
+export declare function parsePort(raw: string | undefined, fallback: number): number;
+export declare function isolationFlag(value: string | undefined): SessionIsolation | undefined;
+export declare const PANEL_PROVIDERS: readonly PanelProvider[];
+export declare function parseFusionTool(value: string | undefined): FusionTool;
+/** Parse `id=provider:model` (or `id=model`, defaulting to the local mlx provider). */
+export declare function parsePanelModelSpec(spec: string, keyEnvs: Record<string, string>): PanelModelSpec;

package/dist/shared/options.js

@@ -0,0 +1,106 @@
+import { SESSION_ISOLATIONS } from "@fusionkit/protocol";
+import { FUSION_TOOLS } from "../fusion-quickstart.js";
+import { fail } from "./errors.js";
+/** Commander reducer for repeatable string options (`--flag a --flag b`). */
+export function collect(value, previous) {
+    return [...(previous ?? []), value];
+}
+/** Parse `ID=VALUE`, failing with a flag-specific message on malformed input. */
+export function parseIdValue(flag, spec) {
+    const separator = spec.indexOf("=");
+    if (separator <= 0 || separator === spec.length - 1) {
+        fail(`${flag} must be ID=VALUE, got "${spec}"`);
+    }
+    return { id: spec.slice(0, separator), value: spec.slice(separator + 1) };
+}
+/**
+ * Map `--model ID=MODEL` specs to ensemble models, falling back to harness-aware
+ * defaults when none are given.
+ */
+export function ensembleModels(model, harness) {
+    const specs = model ?? (harness === "command" ? ["command=local-shell"] : ["fast=fake-fast", "writer=fake-writer"]);
+    return specs.map((spec) => {
+        const separator = spec.indexOf("=");
+        if (separator <= 0 || separator === spec.length - 1) {
+            fail(`--model must be ID=MODEL, got "${spec}"`);
+        }
+        return { id: spec.slice(0, separator), model: spec.slice(separator + 1) };
+    });
+}
+export function liveSmokeTargets(targets) {
+    return (targets ?? []).map((target) => {
+        switch (target) {
+            case "claude-code":
+            case "codex":
+                return target;
+            default:
+                fail('--live-smoke must be "claude-code" or "codex"');
+        }
+    });
+}
+export function unifiedHarnessKinds(targets) {
+    return (targets ?? ["mock", "command"])
+        .flatMap((target) => target.split(","))
+        .map((target) => {
+        switch (target) {
+            case "mock":
+            case "command":
+            case "agent":
+            case "codex":
+            case "claude-code":
+            case "cursor-acp":
+            case "cursor-desktop":
+                return target;
+            default:
+                fail(`--harness must be mock, command, agent, codex, claude-code, cursor-acp, or cursor-desktop; got "${target}"`);
+        }
+    });
+}
+export function parseTimeoutMs(raw, fallback) {
+    const timeoutMs = Number(raw ?? String(fallback));
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        fail("--timeout-ms must be positive");
+    return timeoutMs;
+}
+export function parsePort(raw, fallback) {
+    const port = Number(raw ?? String(fallback));
+    if (!Number.isInteger(port) || port < 0)
+        fail("--port must be a non-negative integer");
+    return port;
+}
+export function isolationFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (!SESSION_ISOLATIONS.includes(value)) {
+        fail(`--isolation must be one of ${SESSION_ISOLATIONS.join(" | ")}`);
+    }
+    return value;
+}
+export const PANEL_PROVIDERS = [
+    "mlx",
+    "openai",
+    "anthropic",
+    "google",
+    "openai-compatible"
+];
+export function parseFusionTool(value) {
+    if (value === undefined || !FUSION_TOOLS.includes(value)) {
+        fail(`--tool must be one of ${FUSION_TOOLS.join(" | ")}`);
+    }
+    return value;
+}
+/** Parse `id=provider:model` (or `id=model`, defaulting to the local mlx provider). */
+export function parsePanelModelSpec(spec, keyEnvs) {
+    const { id, value } = parseIdValue("--model", spec);
+    const colon = value.indexOf(":");
+    let provider = "mlx";
+    let model = value;
+    if (colon > 0) {
+        const maybe = value.slice(0, colon);
+        if (PANEL_PROVIDERS.includes(maybe)) {
+            provider = maybe;
+            model = value.slice(colon + 1);
+        }
+    }
+    return { id, model, provider, ...(keyEnvs[id] !== undefined ? { keyEnv: keyEnvs[id] } : {}) };
+}

package/dist/shared/plane.d.ts

@@ -0,0 +1,13 @@
+import { PlaneClient } from "@fusionkit/sdk";
+/** Poll interval while watching a run from the terminal. */
+export declare const WATCH_POLL_MS = 500;
+/** How long `warrant continue` waits for the run before returning. */
+export declare const CONTINUE_WAIT_TIMEOUT_MS: number;
+/**
+ * Resolve the fusionkit home directory: the `--dir` flag wins, then
+ * `FUSIONKIT_HOME` (legacy `WARRANT_HOME`), then `./.fusionkit` (falling back to
+ * a pre-existing `./.warrant` so older checkouts keep working).
+ */
+export declare function resolveDir(dirFlag: string | undefined): string;
+export declare function clientFor(dir: string): PlaneClient;
+export declare function waitForTerminal(client: PlaneClient, runId: string, onStatus: (status: string) => void): Promise<string>;

package/dist/shared/plane.js

@@ -0,0 +1,46 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { isTerminalStatus } from "@fusionkit/protocol";
+import { PlaneClient } from "@fusionkit/sdk";
+import { loadHome } from "../config.js";
+/** Poll interval while watching a run from the terminal. */
+export const WATCH_POLL_MS = 500;
+/** How long `warrant continue` waits for the run before returning. */
+export const CONTINUE_WAIT_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Resolve the fusionkit home directory: the `--dir` flag wins, then
+ * `FUSIONKIT_HOME` (legacy `WARRANT_HOME`), then `./.fusionkit` (falling back to
+ * a pre-existing `./.warrant` so older checkouts keep working).
+ */
+export function resolveDir(dirFlag) {
+    const fromEnv = process.env.FUSIONKIT_HOME ?? process.env.WARRANT_HOME;
+    if (dirFlag !== undefined)
+        return resolve(dirFlag);
+    if (fromEnv !== undefined)
+        return resolve(fromEnv);
+    if (existsSync(".warrant") && !existsSync(".fusionkit"))
+        return resolve(".warrant");
+    return resolve(".fusionkit");
+}
+export function clientFor(dir) {
+    const home = loadHome(dir);
+    return new PlaneClient(home.config.planeUrl, home.config.adminToken);
+}
+export async function waitForTerminal(client, runId, onStatus) {
+    let last = "";
+    for (;;) {
+        const view = await client.getRun(runId);
+        if (view.status !== last) {
+            last = view.status;
+            onStatus(view.status);
+        }
+        if (isTerminalStatus(view.status)) {
+            return view.status;
+        }
+        if (view.status === "awaiting_approval") {
+            onStatus(`awaiting approval (${view.consentRequirements.join("; ")}) — run: warrant approve ${runId}`);
+            return view.status;
+        }
+        await new Promise((resolveSleep) => setTimeout(resolveSleep, WATCH_POLL_MS));
+    }
+}

package/dist/shared/preflight.d.ts

@@ -0,0 +1,15 @@
+/** Thrown when the environment is missing a binary or credential fusion needs. */
+export declare class PreflightError extends Error {
+    constructor(message: string);
+}
+/** True when `bin` resolves on PATH. */
+export declare function hasBinary(bin: string): boolean;
+/**
+ * Fail fast with actionable guidance when a required binary or API key is
+ * missing. Keeps "minimal setup" honest: clear errors instead of deep stack
+ * traces from a half-started stack.
+ */
+export declare function runPreflight(input: {
+    requiredBins: string[];
+    requiredEnv: string[];
+}): void;

package/dist/shared/preflight.js

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+/** Thrown when the environment is missing a binary or credential fusion needs. */
+export class PreflightError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PreflightError";
+    }
+}
+/** True when `bin` resolves on PATH. */
+export function hasBinary(bin) {
+    const finder = process.platform === "win32" ? "where" : "which";
+    try {
+        execFileSync(finder, [bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+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",
+    claude: "install Claude Code: https://docs.anthropic.com/en/docs/claude-code/overview",
+    "cursor-agent": "install the Cursor CLI: https://cursor.com/cli"
+};
+/**
+ * Fail fast with actionable guidance when a required binary or API key is
+ * missing. Keeps "minimal setup" honest: clear errors instead of deep stack
+ * traces from a half-started stack.
+ */
+export function runPreflight(input) {
+    const problems = [];
+    for (const bin of input.requiredBins) {
+        if (!hasBinary(bin)) {
+            problems.push(`  - "${bin}" was not found on PATH — ${INSTALL_HINTS[bin] ?? `install ${bin}`}`);
+        }
+    }
+    for (const env of [...new Set(input.requiredEnv)]) {
+        const value = process.env[env];
+        if (value === undefined || value.length === 0) {
+            problems.push(`  - ${env} is not set — required by the selected panel (export it, or pass --model/--key-env)`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new PreflightError(`fusionkit preflight failed:\n${problems.join("\n")}`);
+    }
+}

package/dist/shared/proc.d.ts

@@ -0,0 +1,41 @@
+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). */
+export declare function freePort(): Promise<number>;
+/**
+ * Spawn a foreground tool with inherited stdio and resolve with its exit code.
+ * A spawn failure (e.g. binary not on PATH) rejects rather than emitting an
+ * unhandled `error` event.
+ */
+export declare function spawnTool(command: string, args: string[], env: Record<string, string>, cwd?: string): Promise<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.
+ */
+export type LoggedChild = {
+    child: ChildProcess;
+    /** The combined stdout+stderr captured so far. */
+    log: () => string;
+    /** The spawn `'error'` (e.g. ENOENT), if one was emitted. */
+    spawnError: () => Error | undefined;
+};
+export declare function spawnLogged(command: string, args: string[], options?: SpawnOptions): LoggedChild;
+/**
+ * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
+ * to spawn, the child exits, or the timeout elapses. Distinguishes a failed
+ * spawn ("uv: not found") from a slow start.
+ */
+export declare function waitForHttp(probeUrl: string, proc: LoggedChild, options: {
+    timeoutMs: number;
+    label: string;
+    requireOk?: boolean;
+}): Promise<void>;
+/** Resolve once `pattern` is seen on the child's output, or reject on exit/timeout. */
+export declare function waitForOutput(proc: LoggedChild, pattern: RegExp, options: {
+    timeoutMs: number;
+    label: string;
+}): Promise<void>;
+/** SIGTERM a child, escalating to SIGKILL if it ignores the grace period. */
+export declare function terminate(child: ChildProcess, graceMs?: number): void;

package/dist/shared/proc.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+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() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * Spawn a foreground tool with inherited stdio and resolve with its exit code.
+ * A spawn failure (e.g. binary not on PATH) rejects rather than emitting an
+ * unhandled `error` event.
+ */
+export function spawnTool(command, args, env, cwd) {
+    return new Promise((resolveExit, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+            ...(cwd !== undefined ? { cwd } : {})
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => resolveExit(code ?? 0));
+    });
+}
+export function spawnLogged(command, args, options = {}) {
+    const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+    let log = "";
+    let spawnError;
+    child.stdout?.on("data", (chunk) => (log += chunk.toString("utf8")));
+    child.stderr?.on("data", (chunk) => (log += chunk.toString("utf8")));
+    child.on("error", (error) => (spawnError = error));
+    return { child, log: () => log, spawnError: () => spawnError };
+}
+/**
+ * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
+ * to spawn, the child exits, or the timeout elapses. Distinguishes a failed
+ * spawn ("uv: not found") from a slow start.
+ */
+export async function waitForHttp(probeUrl, proc, options) {
+    const deadline = Date.now() + options.timeoutMs;
+    let lastError = "";
+    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)}`);
+        }
+        if (proc.child.exitCode !== null) {
+            throw new Error(`${options.label} exited (code ${proc.child.exitCode}) before becoming ready\n${proc.log().slice(-500)}`);
+        }
+        try {
+            const response = await fetch(probeUrl);
+            if (options.requireOk !== true || response.ok)
+                return;
+            lastError = `status ${response.status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(400);
+    }
+    throw new Error(`${options.label} did not become ready within ${options.timeoutMs}ms (${lastError})\n${proc.log().slice(-500)}`);
+}
+/** 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)}`));
+        }, 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)}`));
+            }
+            else if (pattern.test(proc.log())) {
+                cleanup();
+                resolve();
+            }
+        }, 100);
+        const onExit = () => {
+            cleanup();
+            reject(new Error(`${options.label} exited before becoming ready:\n${proc.log().slice(-500)}`));
+        };
+        proc.child.once("exit", onExit);
+        function cleanup() {
+            clearTimeout(deadline);
+            clearInterval(poll);
+            proc.child.off("exit", onExit);
+        }
+    });
+}
+/** SIGTERM a child, escalating to SIGKILL if it ignores the grace period. */
+export function terminate(child, graceMs = 5000) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        child.kill("SIGTERM");
+    }
+    catch {
+        return;
+    }
+    const timer = setTimeout(() => {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // already gone
+        }
+    }, graceMs);
+    timer.unref();
+    child.once("exit", () => clearTimeout(timer));
+}

package/dist/test/cli.test.d.ts

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