@mafdet/cli 0.3.0 → 0.4.0

package/dist/tui/picker.js

@@ -0,0 +1,146 @@
+// CLI-020 · Choosing a model.
+//
+// A list that narrows as you type. It shows only what this key can call, and
+// it marks - rather than hides - the models the agent may not drive, so the
+// difference between "you cannot use this" and "the agent cannot drive this"
+// stays visible instead of looking like a missing model.
+import { describeModel, filterModels } from "./adapters/models.js";
+import { palette } from "./theme.js";
+const ESC = String.fromCharCode(27);
+const CSI = `${ESC}[`;
+const CLEAR_LINE = `${CSI}2K`;
+const TO_COL_0 = `${CSI}G`;
+const up = (n) => (n > 0 ? `${CSI}${n}A` : "");
+/** How many models to show at once, before the list starts scrolling. */
+const WINDOW = 8;
+export async function pickModel(io, options) {
+    const { bold, dim, accent } = palette(io.capabilities);
+    const pool = options.agentOnly
+        ? options.models.filter((m) => m.agentEligible)
+        : options.models;
+    let query = "";
+    let index = startIndex(pool, options.current);
+    let painted = 0;
+    const paint = (lines) => {
+        io.write(up(painted) +
+            TO_COL_0 +
+            lines.map((line) => CLEAR_LINE + line).join("\n") +
+            "\n");
+        painted = lines.length;
+    };
+    const draw = (matches) => {
+        const lines = [
+            bold(options.agentOnly ? "Select a model for the agent" : "Select a model"),
+            dim(`  filter: ${query.length > 0 ? query : "(type to narrow)"}`),
+            "",
+        ];
+        if (matches.length === 0) {
+            lines.push(dim("  no model matches that filter"));
+        }
+        else {
+            for (const { model, i } of windowOf(matches, index)) {
+                const selected = i === index;
+                const name = model.displayName ?? model.modelId;
+                const head = `${model.modelId}${name !== model.modelId ? ` (${name})` : ""}`;
+                lines.push(selected ? accent(`  > ${head}`) : `    ${head}`);
+                lines.push(dim(`      ${describeModel(model)}`));
+            }
+            if (matches.length > WINDOW) {
+                lines.push(dim(`  ${index + 1} of ${matches.length}`));
+            }
+        }
+        lines.push("");
+        // The catalogue does not publish a per-route RPM. Saying so once is
+        // honest; repeating "unknown" on every row would be noise, and inventing
+        // a number from the model id is what plan 19.5 forbids outright.
+        lines.push(dim("  route RPM is not published by the catalogue"));
+        lines.push(dim("  type to filter, up/down to move, Enter to select, Ctrl+C to cancel"));
+        paint(lines);
+    };
+    draw(filterModels(pool, query));
+    for (;;) {
+        const keys = await io.nextKeys();
+        if (keys === undefined)
+            return settle(cancelled());
+        for (const key of keys) {
+            const matches = filterModels(pool, query);
+            if (key.kind === "up") {
+                index = index === 0 ? Math.max(matches.length - 1, 0) : index - 1;
+            }
+            else if (key.kind === "down") {
+                index = index >= matches.length - 1 ? 0 : index + 1;
+            }
+            else if (key.kind === "backspace") {
+                query = query.slice(0, -1);
+                index = 0;
+            }
+            else if (key.kind === "char") {
+                // Every printable character types into the filter. There is no
+                // j/k navigation here: it would make "kimi" unsearchable.
+                query += key.value;
+                index = 0;
+            }
+            else if (key.kind === "enter") {
+                const chosen = filterModels(pool, query)[index];
+                if (chosen === undefined)
+                    continue;
+                return settle({ kind: "picked", model: chosen });
+            }
+            else if (key.kind === "interrupt" ||
+                key.kind === "escape" ||
+                key.kind === "eof") {
+                return settle(cancelled());
+            }
+        }
+        draw(filterModels(pool, query));
+    }
+    function cancelled() {
+        return { kind: "cancelled" };
+    }
+    function settle(result) {
+        const line = result.kind === "picked" && result.model !== undefined
+            ? `${dim("Model")} ${bold(result.model.modelId)}`
+            : dim("Model selection cancelled");
+        io.write(up(painted) + TO_COL_0);
+        if (painted > 0) {
+            io.write(Array.from({ length: painted }, () => CLEAR_LINE).join("\n") +
+                up(painted - 1) +
+                TO_COL_0);
+        }
+        io.write(CLEAR_LINE + line + "\n");
+        painted = 0;
+        return result;
+    }
+}
+function startIndex(models, current) {
+    if (current === undefined)
+        return 0;
+    const found = models.findIndex((model) => model.modelId === current);
+    return found >= 0 ? found : 0;
+}
+/** A scrolling window that keeps the selection visible. */
+function windowOf(models, index) {
+    if (models.length <= WINDOW) {
+        return models.map((model, i) => ({ model, i }));
+    }
+    const half = Math.floor(WINDOW / 2);
+    const start = Math.min(Math.max(index - half, 0), Math.max(models.length - WINDOW, 0));
+    return models
+        .slice(start, start + WINDOW)
+        .map((model, offset) => ({ model, i: start + offset }));
+}
+/**
+ * What to say when this key can call chat models but the agent may drive none
+ * of them. Not an error: chat still works, and the reason is checkable.
+ */
+export function noAgentModelsNotice(chatCount, capabilities) {
+    const { dim, bold } = palette(capabilities);
+    return ([
+        "",
+        bold("  No model on this key has verified tool calling."),
+        dim(`  ${chatCount} chat model(s) are available, so chat still works.`),
+        dim("  Run 'mafdet models list --agent' to see which models qualify,"),
+        dim("  or check the key's model permissions in the console."),
+        "",
+    ].join("\n") + "\n");
+}

package/dist/tui/resize.d.ts

@@ -0,0 +1,22 @@
+import type { TerminalCapabilities } from "./theme.js";
+export interface ResizeSource {
+    on(event: "resize", listener: () => void): unknown;
+    off?(event: "resize", listener: () => void): unknown;
+    readonly columns?: number | undefined;
+}
+export interface LiveCapabilities {
+    /** The same object every reader holds; its `columns` is kept up to date. */
+    readonly capabilities: TerminalCapabilities;
+    /** Re-read the width now. Returns true if it changed. */
+    refresh(): boolean;
+    stop(): void;
+}
+/**
+ * Keep `capabilities.columns` following the terminal.
+ *
+ * The object is mutated rather than replaced because it is already shared by
+ * every component; handing out a new object would leave the old one in place
+ * wherever it had been captured.
+ */
+export declare function followResize(base: TerminalCapabilities, source: ResizeSource): LiveCapabilities;
+//# sourceMappingURL=resize.d.ts.map

package/dist/tui/resize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resize.d.ts","sourceRoot":"","sources":["../../src/tui/resize.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACnD,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,yDAAyD;IACzD,OAAO,IAAI,OAAO,CAAC;IACnB,IAAI,IAAI,IAAI,CAAC;CACd;AAKD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,YAAY,GACnB,gBAAgB,CAuBlB"}

package/dist/tui/resize.js

@@ -0,0 +1,37 @@
+// CLI-022 · Following the terminal's width.
+//
+// Capabilities were read once at startup, so a window resized mid-session kept
+// laying out for the old width - lines wrapping or being clipped to a size the
+// terminal no longer is. Everything already reads `capabilities.columns` at
+// draw time, so the fix is for that number to stay current rather than for
+// every component to learn about resizing.
+/** Used when the terminal stops reporting a width mid-session. */
+const FALLBACK_COLUMNS = 80;
+/**
+ * Keep `capabilities.columns` following the terminal.
+ *
+ * The object is mutated rather than replaced because it is already shared by
+ * every component; handing out a new object would leave the old one in place
+ * wherever it had been captured.
+ */
+export function followResize(base, source) {
+    const live = { ...base };
+    const refresh = () => {
+        const next = source.columns !== undefined && source.columns > 0
+            ? source.columns
+            : FALLBACK_COLUMNS;
+        if (next === live.columns)
+            return false;
+        live.columns = next;
+        return true;
+    };
+    const listener = () => void refresh();
+    source.on("resize", listener);
+    return {
+        capabilities: live,
+        refresh,
+        stop() {
+            source.off?.("resize", listener);
+        },
+    };
+}

package/dist/tui/route.d.ts

@@ -0,0 +1,26 @@
+/** Why a bare `mafdet` did not open the TUI. Shown when the user asks. */
+export type TuiRefusal = "machine-output-flag" | "no-tui-flag" | "stdin-not-tty" | "stdout-not-tty" | "term-dumb" | "ci";
+export type EntryDecision = 
+/** Bare `mafdet` on an interactive terminal. */
+{
+    readonly kind: "tui";
+}
+/** `mafdet <command> ...` — the 0.3 command surface, contract unchanged. */
+ | {
+    readonly kind: "command";
+}
+/** Bare `mafdet` where a TUI would be unsafe: help on stderr, exit 2. */
+ | {
+    readonly kind: "usage";
+    readonly refusedBecause: TuiRefusal;
+};
+export interface EntryEnvironment {
+    readonly argv: readonly string[];
+    readonly stdinIsTTY: boolean;
+    readonly stdoutIsTTY: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export declare function decideEntry(input: EntryEnvironment): EntryDecision;
+/** A sentence for the user, not a code. Printed under the usage text. */
+export declare function explainRefusal(reason: TuiRefusal): string;
+//# sourceMappingURL=route.d.ts.map

package/dist/tui/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/tui/route.ts"],"names":[],"mappings":"AAOA,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAClB,qBAAqB,GACrB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,MAAM,aAAa;AACvB,gDAAgD;AAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1B,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,yEAAyE;GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5D;AAyBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAoBlE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAezD"}

package/dist/tui/route.js

@@ -0,0 +1,68 @@
+// CLI-018 · Where a bare `mafdet` goes.
+//
+// This is a pure function on purpose. Whether the TUI starts decides whether
+// we put the terminal into raw mode and start drawing over it, and getting
+// that wrong in a pipeline or in CI corrupts someone's output. A pure decision
+// can be tested across every combination without a terminal.
+/**
+ * Flags that mean "a machine is reading this". They are checked even on a bare
+ * `mafdet` so that `mafdet --json` can never be answered with a drawing.
+ */
+const MACHINE_FLAGS = new Set(["--json", "--quiet", "-q"]);
+/** Treated as a command rather than a bare invocation. */
+function hasCommand(argv) {
+    return argv.some((arg) => !arg.startsWith("-"));
+}
+/**
+ * CI systems attach a pipe often enough that the TTY checks usually catch them,
+ * but not always — some allocate a pty. An explicit check keeps the promise
+ * that CI behaviour does not depend on that detail.
+ */
+function isCi(env) {
+    const value = env.CI;
+    if (value === undefined)
+        return false;
+    // "false" and "0" are how several providers spell "not CI".
+    return value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+export function decideEntry(input) {
+    if (hasCommand(input.argv))
+        return { kind: "command" };
+    // Order matters only for which reason the user is told; every branch below
+    // refuses. The most specific and most actionable reasons come first.
+    const refuse = (refusedBecause) => ({
+        kind: "usage",
+        refusedBecause,
+    });
+    if (input.argv.includes("--no-tui"))
+        return refuse("no-tui-flag");
+    if (input.argv.some((arg) => MACHINE_FLAGS.has(arg))) {
+        return refuse("machine-output-flag");
+    }
+    if (!input.stdoutIsTTY)
+        return refuse("stdout-not-tty");
+    if (!input.stdinIsTTY)
+        return refuse("stdin-not-tty");
+    if (input.env.TERM === "dumb")
+        return refuse("term-dumb");
+    if (isCi(input.env))
+        return refuse("ci");
+    return { kind: "tui" };
+}
+/** A sentence for the user, not a code. Printed under the usage text. */
+export function explainRefusal(reason) {
+    switch (reason) {
+        case "machine-output-flag":
+            return "not starting the interactive UI because output was requested in a machine-readable form";
+        case "no-tui-flag":
+            return "not starting the interactive UI because --no-tui was given";
+        case "stdin-not-tty":
+            return "not starting the interactive UI because input is not a terminal";
+        case "stdout-not-tty":
+            return "not starting the interactive UI because output is not a terminal";
+        case "term-dumb":
+            return "not starting the interactive UI because TERM=dumb";
+        case "ci":
+            return "not starting the interactive UI because CI is set";
+    }
+}

package/dist/tui/start-agent.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedModel } from "../api/models.js";
+import { type CommandIo } from "../commands/runtime.js";
+import { ExitCode } from "../output/exit-codes.js";
+import { type TerminalCapabilities } from "./theme.js";
+import type { WidgetIo } from "./widgets.js";
+export interface AgentPermissions {
+    readonly allowWrite: boolean;
+    readonly allowedCommands: readonly string[];
+}
+/**
+ * Read the permission flags off a bare `mafdet` invocation.
+ *
+ * The same spellings the agent command uses, so there is one grammar for
+ * granting these and no second one to keep in step.
+ */
+export declare function parsePermissions(argv: readonly string[]): AgentPermissions;
+export interface StartAgentOptions {
+    readonly io: WidgetIo;
+    readonly capabilities: TerminalCapabilities;
+    readonly stdout: {
+        write(text: string): unknown;
+    };
+    readonly commandIo: CommandIo;
+    readonly apiKey: string;
+    readonly model: ResolvedModel;
+    readonly workspace: string;
+    readonly permissions: AgentPermissions;
+    readonly signal?: AbortSignal;
+}
+export declare function startAgent(options: StartAgentOptions): Promise<ExitCode>;
+//# sourceMappingURL=start-agent.d.ts.map

package/dist/tui/start-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-agent.d.ts","sourceRoot":"","sources":["../../src/tui/start-agent.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAe1E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAwDnB"}

package/dist/tui/start-agent.js

@@ -0,0 +1,82 @@
+// CLI-021 · Assembling the agent session for the TUI.
+//
+// Every permission decision reuses the command surface's own pieces:
+// `buildToolset`, the same prompts, and the same flags. The TUI adds no way to
+// grant anything - `mafdet --allow-write` is the same grant `mafdet agent
+// --allow-write` is, and a run given neither flag has no write or command tool
+// loaded at all, which is what makes "read-only" mean something.
+import { buildToolset, READ_ONLY_PROMPT, WRITE_PROMPT, } from "../commands/agent.js";
+import { buildRuntime } from "../commands/runtime.js";
+import { Workspace } from "../filesystem/workspace.js";
+import { ExitCode } from "../output/exit-codes.js";
+import { runAgentSurface } from "./agent-surface.js";
+import { palette } from "./theme.js";
+/**
+ * Read the permission flags off a bare `mafdet` invocation.
+ *
+ * The same spellings the agent command uses, so there is one grammar for
+ * granting these and no second one to keep in step.
+ */
+export function parsePermissions(argv) {
+    let allowWrite = false;
+    const allowedCommands = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--allow-write")
+            allowWrite = true;
+        else if (arg === "--allow-command") {
+            const value = argv[i + 1];
+            if (value !== undefined && !value.startsWith("-")) {
+                allowedCommands.push(value);
+                i += 1;
+            }
+        }
+    }
+    return { allowWrite, allowedCommands };
+}
+export async function startAgent(options) {
+    const { dim, bold } = palette(options.capabilities);
+    let workspace;
+    try {
+        workspace = Workspace.open(options.workspace);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        options.stdout.write(`\n  ${bold("cannot use this directory")}: ${message}\n`);
+        return ExitCode.General;
+    }
+    // The TUI is interactive by construction, so `--allow-write` can be honoured
+    // here without the non-interactive downgrade the command surface applies.
+    const mode = options.permissions.allowWrite ? "suggest" : "read-only";
+    const hasCommands = options.permissions.allowedCommands.length > 0;
+    const runtime = buildRuntime({
+        ...options.commandIo,
+        env: { ...options.commandIo.env, MAFDET_API_KEY: options.apiKey },
+    });
+    options.stdout.write(dim(`\n  ${options.model.modelId} - ${mode}` +
+        (hasCommands
+            ? ` - commands: ${options.permissions.allowedCommands.join(", ")}`
+            : "") +
+        "\n  type a goal, or /help for the session commands\n\n"));
+    await runAgentSurface({
+        io: options.io,
+        capabilities: options.capabilities,
+        stdout: options.stdout,
+        session: {
+            client: runtime.dataPlane,
+            model: options.model.modelId,
+            pricing: options.model,
+            catalog: [options.model],
+            systemPrompt: mode === "read-only" ? READ_ONLY_PROMPT : WRITE_PROMPT,
+            tools: buildToolset(mode, hasCommands),
+            toolContext: {
+                workspace,
+                allowedCommands: options.permissions.allowedCommands,
+            },
+            mode,
+            allowedCommands: options.permissions.allowedCommands,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        },
+    });
+    return ExitCode.Ok;
+}

package/dist/tui/terminal.d.ts

@@ -0,0 +1,41 @@
+/** The bits of a stream the guard touches, so tests can pass a fake. */
+export interface GuardedStdout {
+    write(text: string): unknown;
+}
+export interface GuardedStdin {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode?(mode: boolean): unknown;
+}
+export interface GuardHost {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    removeListener(event: string, listener: (...args: unknown[]) => void): unknown;
+    removeAllListeners(event: string): unknown;
+    kill(pid: number, signal: string): unknown;
+    exit(code: number): unknown;
+    readonly pid: number;
+}
+export interface TerminalGuard {
+    /** Undo everything, at most once. Safe to call from anywhere. */
+    restore(): void;
+    /** Stop listening. For a TUI that ended normally and wants its signals back. */
+    release(): void;
+    hideCursor(): void;
+}
+export interface GuardOptions {
+    readonly stdout: GuardedStdout;
+    readonly stdin: GuardedStdin;
+    readonly host: GuardHost;
+    /** Called before the process dies, for a last summary. Must not throw. */
+    readonly onFatal?: (error: unknown) => void;
+}
+/**
+ * Installs handlers that restore the terminal on every exit path: a normal
+ * return, SIGINT, SIGTERM, and an uncaught exception or rejection.
+ *
+ * Signals are re-raised with the default disposition rather than turned into
+ * `exit(0)`, so a process killed by SIGINT still reports 130. Claiming success
+ * after being interrupted would be a lie a script could act on.
+ */
+export declare function installTerminalGuard(options: GuardOptions): TerminalGuard;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/tui/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/tui/terminal.ts"],"names":[],"mappings":"AAYA,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IACnE,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GACrC,OAAO,CAAC;IACX,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC;IAChB,gFAAgF;IAChF,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CA2DzE"}

package/dist/tui/terminal.js

@@ -0,0 +1,78 @@
+// CLI-018 · Putting the terminal back.
+//
+// The spike (cli-018-tui-renderer-adr) found that Ink hooks only
+// `process.once('beforeExit')`, which does not fire on SIGINT, on
+// process.exit(), or on an uncaught throw — so a component library would not
+// have given us this for free either. It is written here, once, and covers
+// every exit path the plan names.
+const ESC = String.fromCharCode(27);
+const SHOW_CURSOR = `${ESC}[?25h`;
+const HIDE_CURSOR = `${ESC}[?25l`;
+/**
+ * Installs handlers that restore the terminal on every exit path: a normal
+ * return, SIGINT, SIGTERM, and an uncaught exception or rejection.
+ *
+ * Signals are re-raised with the default disposition rather than turned into
+ * `exit(0)`, so a process killed by SIGINT still reports 130. Claiming success
+ * after being interrupted would be a lie a script could act on.
+ */
+export function installTerminalGuard(options) {
+    const { stdout, stdin, host } = options;
+    let restored = false;
+    let cursorHidden = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            if (stdin.isTTY === true && stdin.isRaw === true)
+                stdin.setRawMode?.(false);
+        }
+        catch {
+            // A closed or detached stdin is not a reason to skip the rest.
+        }
+        if (cursorHidden) {
+            try {
+                stdout.write(SHOW_CURSOR);
+            }
+            catch {
+                // Nothing more we can do; the process is going away regardless.
+            }
+        }
+    };
+    const onSignal = (signal) => () => {
+        restore();
+        // Remove our own handler so the re-raise is handled by the default
+        // disposition and the exit status is the real one.
+        host.removeAllListeners(signal);
+        host.kill(host.pid, signal);
+    };
+    const onFatal = (error) => {
+        restore();
+        options.onFatal?.(error);
+        host.exit(1);
+    };
+    const listeners = [
+        ["SIGINT", onSignal("SIGINT")],
+        ["SIGTERM", onSignal("SIGTERM")],
+        ["exit", restore],
+        ["uncaughtException", onFatal],
+        ["unhandledRejection", onFatal],
+    ];
+    for (const [event, listener] of listeners)
+        host.on(event, listener);
+    return {
+        restore,
+        release() {
+            for (const [event, listener] of listeners) {
+                host.removeListener(event, listener);
+            }
+        },
+        hideCursor() {
+            if (cursorHidden)
+                return;
+            cursorHidden = true;
+            stdout.write(HIDE_CURSOR);
+        },
+    };
+}

package/dist/tui/theme.d.ts

@@ -0,0 +1,22 @@
+export interface TerminalCapabilities {
+    readonly colour: boolean;
+    readonly unicode: boolean;
+    /** Columns to lay out for. Narrow terminals collapse rather than wrap badly. */
+    readonly columns: number;
+}
+export interface CapabilityInput {
+    readonly stdoutIsTTY: boolean;
+    readonly columns: number | undefined;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/** Below this, the wide banner is replaced by a single line. */
+export declare const NARROW_COLUMNS = 60;
+export declare function detectCapabilities(input: CapabilityInput): TerminalCapabilities;
+/** The subset of SGR we use, resolved once so no component branches on colour. */
+export interface Palette {
+    readonly bold: (text: string) => string;
+    readonly dim: (text: string) => string;
+    readonly accent: (text: string) => string;
+}
+export declare function palette(capabilities: TerminalCapabilities): Palette;
+//# sourceMappingURL=theme.d.ts.map

package/dist/tui/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/tui/theme.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5D;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,KAAK,CAAC;AA0BjC,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,GACrB,oBAAoB,CAatB;AAED,kFAAkF;AAClF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAUD,wBAAgB,OAAO,CAAC,YAAY,EAAE,oBAAoB,GAAG,OAAO,CASnE"}

package/dist/tui/theme.js

@@ -0,0 +1,59 @@
+// CLI-018 · What this terminal can be trusted to render.
+//
+// Pure, because the answer decides which bytes we write. CLI-016 established
+// that every user-visible byte stays inside ASCII: a Windows console on a
+// non-UTF-8 code page (cp936 is the PowerShell 5.1 default on a Chinese
+// install) turns anything else into mojibake, and the CLI cannot set the code
+// page. So Unicode is opt-in on evidence, never assumed.
+/** Below this, the wide banner is replaced by a single line. */
+export const NARROW_COLUMNS = 60;
+/** Used when the terminal does not report a width. */
+const ASSUMED_COLUMNS = 80;
+function wantsNoColour(env) {
+    // https://no-color.org: any value, including empty, means disable.
+    return env.NO_COLOR !== undefined;
+}
+/**
+ * Unicode is allowed only where the encoding is known to be UTF-8.
+ *
+ * On POSIX that is the locale. On Windows there is no reliable way to read the
+ * console code page from Node, so the only accepted evidence is Windows
+ * Terminal, which is UTF-8 throughout. Everything else — including
+ * conhost/PowerShell 5.1 — gets ASCII.
+ */
+function unicodeIsSafe(env) {
+    if (env.MAFDET_ASCII === "1")
+        return false;
+    if (env.WT_SESSION !== undefined && env.WT_SESSION !== "")
+        return true;
+    const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG ?? "";
+    return /utf-?8/i.test(locale);
+}
+export function detectCapabilities(input) {
+    const dumb = input.env.TERM === "dumb";
+    const colour = input.stdoutIsTTY && !dumb && !wantsNoColour(input.env);
+    return {
+        colour,
+        // A non-TTY still gets ASCII rather than Unicode: the bytes may end up in
+        // a log or a Windows console either way.
+        unicode: input.stdoutIsTTY && !dumb && unicodeIsSafe(input.env),
+        columns: input.columns !== undefined && input.columns > 0
+            ? input.columns
+            : ASSUMED_COLUMNS,
+    };
+}
+const ESC = String.fromCharCode(27);
+function sgr(open, close) {
+    return (text) => `${ESC}[${open}m${text}${ESC}[${close}m`;
+}
+const PLAIN = (text) => text;
+export function palette(capabilities) {
+    if (!capabilities.colour) {
+        return { bold: PLAIN, dim: PLAIN, accent: PLAIN };
+    }
+    return {
+        bold: sgr("1", "22"),
+        dim: sgr("2", "22"),
+        accent: sgr("36", "39"),
+    };
+}