@cruxy/cli 0.8.0 → 0.10.0

package/dist/cli/session-factory.js

@@ -2,16 +2,19 @@ import { createProvider } from "@cruxy/sdk";
 import { loadProjectInstructions } from "../config/index.js";
 import { logger } from "../utils/logger.js";
 import { getGitInfo } from "../utils/git.js";
-import { ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, } from "../approval/index.js";
+import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
 import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
 import { Session } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
- * Wrap a PromptIO so the renderer's transient status line is erased before any
- * prompt text lands (U.2): the approval prompt writes to stderr while the
- * spinner owns the last stdout row of the same terminal — clearing first keeps
- * the prompt from tearing through the live region.
+ * Wrap a PromptIO so the live region yields before any prompt text lands
+ * (U.2/U.4): the prompt writes to stderr while the status line owns the last
+ * stdout row of the same terminal. Entering the `awaiting-approval` phase
+ * hides the live line (the prompt IS the visible state) while keeping the
+ * step-progress register intact, so the line comes back with full context on
+ * the next transition after the user decides.
  */
 function suspendStatusOnPrompt(io, renderer) {
     if (!renderer)
@@ -19,11 +22,58 @@ function suspendStatusOnPrompt(io, renderer) {
     return {
         ...io,
         write: (text) => {
-            renderer.status(null);
+            renderer.setPhase({ kind: "awaiting-approval" });
             io.write(text);
         },
     };
 }
+/**
+ * Restore the live line once an approval request fully settles (U.4). The
+ * settle point must be the service call, not the prompt's key read: the
+ * prompt writes a trailing newline AFTER the read, which re-enters
+ * `awaiting-approval` — resolving here is the first moment no more prompt
+ * bytes can follow. Fires on every decision (prompted or not); the renderer
+ * treats it as a no-op unless a prompt actually displaced the line.
+ */
+function resumeLineAfterApproval(requestApproval, renderer) {
+    if (!renderer)
+        return requestApproval;
+    return async (action) => {
+        try {
+            return await requestApproval(action);
+        }
+        finally {
+            renderer.promptResolved();
+        }
+    };
+}
+/**
+ * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
+ * whole point: a tool mutates only *after* `requestApproval` resolves, so
+ * snapshotting after an `allow` decision but before returning it means the
+ * checkpoint always lands before the run's first mutation — and a denied
+ * action never creates one. The same seam records which paths the run touched
+ * (file actions) or that attribution is lost (shell), for rollback's
+ * external-change detection.
+ */
+export function withCheckpointGate(requestApproval, checkpoints, cwd) {
+    if (!checkpoints)
+        return requestApproval;
+    return async (action) => {
+        const decision = await requestApproval(action);
+        if (!decision.allow)
+            return decision;
+        const request = classify(action, cwd);
+        if (request.tier === "read")
+            return decision;
+        await checkpoints.ensureCheckpoint();
+        if (action.kind === "shell")
+            await checkpoints.recordShellMutation();
+        else
+            await checkpoints.recordTouched([...request.targets]);
+        return decision;
+    };
+}
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -33,7 +83,7 @@ function suspendStatusOnPrompt(io, renderer) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -45,10 +95,35 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
+    // One io shared by every prompt in the session (plan approval, the U.3 gate,
+    // and any gate inside a subagent), so they all coordinate with the same live
+    // region. The full wrapper stack around an ApprovalService is factored here
+    // because subagents must get the *identical* stack over a FRESH service: same
+    // prompt + same checkpoint hook, but a new (empty) session allowlist — a
+    // grant in the parent never silently widens a child's authority.
+    const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
+    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, cwd);
+    // Subagent orchestration (C.14): spawn_subagent goes on the main registry
+    // only when depth allows (maxDepth 0 disables the feature structurally).
+    // Registered before the plan wiring so plan-mode execution steps can
+    // dispatch subagents too; the propose phase filters it out (read-only).
+    const orchestrator = new SubagentOrchestrator({
+        provider,
+        config,
+        parentRegistry: execRegistry,
+        cwd,
+        logger,
+        git,
+        projectInstructions,
+        renderer,
+        makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
+    });
+    if (config.subagent.maxDepth > 0) {
+        execRegistry.register(makeSpawnSubagentTool(orchestrator, 0));
+    }
     if (planMode) {
-        // One io + allowlist shared by the plan-approval prompt and the per-action
+        // One allowlist shared by the plan-approval prompt and the per-action
         // gate, so a grant recorded during execution is honored by U.3's own check.
-        const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
         const allowlist = new SessionAllowlist();
         const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io));
         const approval = new ApprovalService({
@@ -57,12 +132,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             policy: planPolicy,
             io,
         });
-        const ctx = {
-            cwd,
-            config,
-            logger,
-            requestApproval: (action) => approval.requestApproval(action),
-        };
+        const ctx = { cwd, config, logger, requestApproval: gate(approval) };
         const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
@@ -90,14 +160,9 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     const approval = new ApprovalService({
         cwd,
         interactive: ttyInteractive,
-        io: suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer),
+        io,
     });
-    const ctx = {
-        cwd,
-        config,
-        logger,
-        requestApproval: (action) => approval.requestApproval(action),
-    };
+    const ctx = { cwd, config, logger, requestApproval: gate(approval) };
     return new Session({
         provider,
         registry: execRegistry,

package/dist/components/autocomplete.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Autocomplete (U.7): pure completion over an injectable candidate list, plus
+ * the readline adapter the REPL uses for Tab-completion. Non-destructive by
+ * construction — this module transforms strings and returns suggestions; it
+ * has no access to the session, so completing can never execute anything.
+ * Enter (the existing REPL path) remains the only way to act.
+ */
+/** The outcome of one completion attempt. */
+export interface Completion {
+    /** The (possibly extended) input line. Unchanged when nothing matches. */
+    line: string;
+    /** Every candidate the input currently prefixes (shown on ambiguity). */
+    suggestions: string[];
+}
+/**
+ * Complete `line` against `candidates` (exact-prefix filter):
+ * - no match → line unchanged, no suggestions;
+ * - one match → completed fully to it;
+ * - several → extended to their longest common prefix, all listed.
+ * Pure data in, data out — deterministic and order-preserving.
+ */
+export declare function completeLine(line: string, candidates: readonly string[]): Completion;
+/**
+ * A Node-readline `completer` over a live candidate source. Only the leading
+ * word of a line starting with `/` completes (slash commands); everything
+ * else — prompts to the model — is left alone, so Tab never mangles prose.
+ *
+ * readline's contract: return `[hits, prefixBeingReplaced]`; readline itself
+ * extends to the common prefix and lists hits on a second Tab. It rewrites
+ * only the edit buffer — submission stays on Enter.
+ */
+export declare function makeReplCompleter(candidates: () => readonly string[]): (line: string) => [string[], string];

package/dist/components/autocomplete.js

@@ -0,0 +1,50 @@
+/**
+ * Autocomplete (U.7): pure completion over an injectable candidate list, plus
+ * the readline adapter the REPL uses for Tab-completion. Non-destructive by
+ * construction — this module transforms strings and returns suggestions; it
+ * has no access to the session, so completing can never execute anything.
+ * Enter (the existing REPL path) remains the only way to act.
+ */
+/** The longest common prefix of a non-empty candidate list. */
+function commonPrefix(candidates) {
+    let prefix = candidates[0];
+    for (const candidate of candidates.slice(1)) {
+        let i = 0;
+        while (i < prefix.length && prefix[i] === candidate[i])
+            i++;
+        prefix = prefix.slice(0, i);
+    }
+    return prefix;
+}
+/**
+ * Complete `line` against `candidates` (exact-prefix filter):
+ * - no match → line unchanged, no suggestions;
+ * - one match → completed fully to it;
+ * - several → extended to their longest common prefix, all listed.
+ * Pure data in, data out — deterministic and order-preserving.
+ */
+export function completeLine(line, candidates) {
+    const matches = candidates.filter((c) => c.startsWith(line));
+    if (matches.length === 0)
+        return { line, suggestions: [] };
+    if (matches.length === 1)
+        return { line: matches[0], suggestions: matches };
+    return { line: commonPrefix(matches), suggestions: matches };
+}
+/**
+ * A Node-readline `completer` over a live candidate source. Only the leading
+ * word of a line starting with `/` completes (slash commands); everything
+ * else — prompts to the model — is left alone, so Tab never mangles prose.
+ *
+ * readline's contract: return `[hits, prefixBeingReplaced]`; readline itself
+ * extends to the common prefix and lists hits on a second Tab. It rewrites
+ * only the edit buffer — submission stays on Enter.
+ */
+export function makeReplCompleter(candidates) {
+    return (line) => {
+        if (!line.startsWith("/") || /\s/.test(line))
+            return [[], line];
+        const { suggestions } = completeLine(line, candidates());
+        return [suggestions, line];
+    };
+}

package/dist/components/frame.d.ts

@@ -0,0 +1,25 @@
+import type { RenderCapabilities } from "../render/index.js";
+/** The visible text of a possibly-styled row. */
+export declare function stripAnsi(text: string): string;
+/**
+ * The transient multi-line region interactive components draw into (U.7) —
+ * the multi-row analog of the TTY renderer's single managed status line, with
+ * the same discipline:
+ *
+ * - Only the frame is ever rewritten (erase + redraw in place) — committed
+ *   output above it is never touched.
+ * - Every line is hard-truncated to the terminal width so a row can never
+ *   soft-wrap; wrapped rows would break erasure and leave artifacts.
+ * - `clear()` removes the frame entirely — after a component resolves, the
+ *   screen holds zero leftover bytes from the interaction.
+ *
+ * Requires cursor control (`caps.cursor`); components guard on that before
+ * constructing one.
+ */
+export interface Frame {
+    /** Repaint the frame with these rows (erases the previous paint first). */
+    render(lines: string[]): void;
+    /** Erase the frame completely. Idempotent. */
+    clear(): void;
+}
+export declare function createFrame(write: (text: string) => void, caps: RenderCapabilities): Frame;

package/dist/components/frame.js

@@ -0,0 +1,49 @@
+/** Erase the current line and return the cursor to column 0 (same as U.2). */
+const CLEAR_LINE = "\r\x1b[2K";
+/** Move the cursor up one row. */
+const CURSOR_UP = "\x1b[1A";
+/** SGR escape sequences (the only ANSI the components emit — via picocolors). */
+// eslint-disable-next-line no-control-regex
+const SGR = /\x1b\[[0-9;]*m/g;
+/** The visible text of a possibly-styled row. */
+export function stripAnsi(text) {
+    return text.replace(SGR, "");
+}
+export function createFrame(write, caps) {
+    let drawn = 0;
+    /**
+     * Truncate to width-1 (cursor rests after the last cell; a full-width row
+     * would auto-wrap on some terminals). Width is measured on VISIBLE
+     * characters — rows may carry ANSI color. A row that fits passes through
+     * styled; an overflowing row is truncated on its stripped text (style is
+     * dropped rather than risking a cut escape sequence).
+     */
+    const fit = (line) => {
+        const room = Math.max(1, caps.width - 1);
+        const plain = stripAnsi(line);
+        if (plain.length <= room)
+            return line;
+        return plain.slice(0, room - 1) + "…";
+    };
+    const erase = () => {
+        if (drawn === 0)
+            return;
+        // Cursor sits at the end of the last drawn row: clear it, then walk up
+        // clearing each prior row, ending at column 0 of the first frame row.
+        let out = CLEAR_LINE;
+        for (let i = 1; i < drawn; i++)
+            out += CURSOR_UP + CLEAR_LINE;
+        write(out);
+        drawn = 0;
+    };
+    return {
+        render(lines) {
+            erase();
+            if (lines.length === 0)
+                return;
+            write(lines.map(fit).join("\n"));
+            drawn = lines.length;
+        },
+        clear: erase,
+    };
+}

package/dist/components/fuzzy.d.ts

@@ -0,0 +1,61 @@
+import pc from "picocolors";
+import { type ComponentIO, type InteractiveResult } from "./input.js";
+/**
+ * Fuzzy finding (U.7): a deterministic, honest subsequence scorer (pure,
+ * headless-tested) plus the interactive type-to-filter component built on it.
+ * No fabricated relevance — a label either contains the query as a
+ * subsequence or it does not, and the score is three documented bonuses.
+ */
+/** A successful match: its rank score and the label indices that matched. */
+export interface FuzzyMatch {
+    score: number;
+    /** Indices into the label of the matched characters (for highlighting). */
+    positions: number[];
+}
+/**
+ * Case-insensitive greedy-leftmost subsequence match.
+ * - Empty query matches everything: score 0, no positions (nothing to
+ *   highlight, nothing to fabricate).
+ * - Not a subsequence → `null`.
+ * - Score = Σ per matched char: {@link BASE} + {@link CONSECUTIVE} when the
+ *   match continues a run + {@link BOUNDARY} when it starts a word.
+ * Deterministic by construction — same inputs, same output, no randomness,
+ * no length normalization (ties break in {@link rankItems}).
+ */
+export declare function fuzzyScore(query: string, label: string): FuzzyMatch | null;
+/** An item that survived filtering, with everything the finder renders. */
+export interface RankedItem<T> {
+    item: T;
+    label: string;
+    match: FuzzyMatch;
+}
+/**
+ * Filter + rank a list against a query. Ordering is fully stable and
+ * deterministic: score descending, then shorter label, then original index.
+ * An empty query returns every item in original order.
+ */
+export declare function rankItems<T>(items: readonly T[], toLabel: (item: T) => string, query: string): RankedItem<T>[];
+/**
+ * Bold the matched characters of a label. With color off (NO_COLOR, pipe)
+ * picocolors' disabled palette is the identity — plain text, zero ANSI.
+ */
+export declare function highlightMatch(label: string, positions: readonly number[], colors: ReturnType<typeof pc.createColors>): string;
+export interface FuzzyFindOptions<T> {
+    /** Label an item filters/renders under. Required — items are opaque. */
+    toLabel: (item: T) => string;
+    /** Header above the query line (e.g. "pick a checkpoint"). */
+    title?: string;
+    /** Non-TTY fallback: resolve to this instead of failing loud. */
+    defaultValue?: T;
+    /** `--flag` alternatives listed in the non-TTY error. */
+    nonInteractiveHint?: string[];
+    /** Visible result rows before the list scrolls (default 10). */
+    maxVisible?: number;
+}
+/**
+ * Interactive fuzzy finder: type to filter, ↑/↓ to move through the ranked
+ * results, Enter to select the highlighted item (inert while there are no
+ * matches), Esc / Ctrl-C / EOF to cancel. The transient frame is fully erased
+ * before resolving — the screen keeps no trace of the interaction.
+ */
+export declare function fuzzyFind<T>(items: readonly T[], opts: FuzzyFindOptions<T>, io?: ComponentIO): Promise<InteractiveResult<T>>;

package/dist/components/fuzzy.js

@@ -0,0 +1,174 @@
+import pc from "picocolors";
+import { createFrame } from "./frame.js";
+import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
+/** Word-boundary characters that earn the boundary bonus for the NEXT char. */
+const SEPARATORS = new Set(["/", "-", "_", ".", " "]);
+/** Per-character score weights — the entire ranking formula. */
+const BASE = 1; // every matched character
+const CONSECUTIVE = 2; // extra when adjacent to the previous match
+const BOUNDARY = 2; // extra at label start or right after a separator
+/**
+ * Case-insensitive greedy-leftmost subsequence match.
+ * - Empty query matches everything: score 0, no positions (nothing to
+ *   highlight, nothing to fabricate).
+ * - Not a subsequence → `null`.
+ * - Score = Σ per matched char: {@link BASE} + {@link CONSECUTIVE} when the
+ *   match continues a run + {@link BOUNDARY} when it starts a word.
+ * Deterministic by construction — same inputs, same output, no randomness,
+ * no length normalization (ties break in {@link rankItems}).
+ */
+export function fuzzyScore(query, label) {
+    if (query === "")
+        return { score: 0, positions: [] };
+    const q = query.toLowerCase();
+    const l = label.toLowerCase();
+    const positions = [];
+    let score = 0;
+    let li = 0;
+    for (let qi = 0; qi < q.length; qi++) {
+        const idx = l.indexOf(q[qi], li);
+        if (idx === -1)
+            return null;
+        score += BASE;
+        if (positions.length > 0 && idx === positions[positions.length - 1] + 1) {
+            score += CONSECUTIVE;
+        }
+        if (idx === 0 || SEPARATORS.has(label[idx - 1])) {
+            score += BOUNDARY;
+        }
+        positions.push(idx);
+        li = idx + 1;
+    }
+    return { score, positions };
+}
+/**
+ * Filter + rank a list against a query. Ordering is fully stable and
+ * deterministic: score descending, then shorter label, then original index.
+ * An empty query returns every item in original order.
+ */
+export function rankItems(items, toLabel, query) {
+    // Empty query: everything matches with score 0 — original order IS the
+    // ranking (the length tie-break must not silently reorder the full list).
+    if (query === "") {
+        return items.map((item) => ({
+            item,
+            label: toLabel(item),
+            match: { score: 0, positions: [] },
+        }));
+    }
+    const ranked = [];
+    for (const [index, item] of items.entries()) {
+        const label = toLabel(item);
+        const match = fuzzyScore(query, label);
+        if (match)
+            ranked.push({ item, label, match, index });
+    }
+    ranked.sort((a, b) => b.match.score - a.match.score ||
+        a.label.length - b.label.length ||
+        a.index - b.index);
+    return ranked.map(({ item, label, match }) => ({ item, label, match }));
+}
+/**
+ * Bold the matched characters of a label. With color off (NO_COLOR, pipe)
+ * picocolors' disabled palette is the identity — plain text, zero ANSI.
+ */
+export function highlightMatch(label, positions, colors) {
+    if (positions.length === 0)
+        return label;
+    const matched = new Set(positions);
+    let out = "";
+    for (let i = 0; i < label.length; i++) {
+        out += matched.has(i) ? colors.bold(colors.cyan(label[i])) : label[i];
+    }
+    return out;
+}
+/**
+ * Interactive fuzzy finder: type to filter, ↑/↓ to move through the ranked
+ * results, Enter to select the highlighted item (inert while there are no
+ * matches), Esc / Ctrl-C / EOF to cancel. The transient frame is fully erased
+ * before resolving — the screen keeps no trace of the interaction.
+ */
+export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
+    const fallback = resolveNonInteractive(io, opts.title ?? "this picker", opts.defaultValue, opts.nonInteractiveHint);
+    if (fallback)
+        return fallback;
+    if (items.length === 0)
+        return { kind: "cancelled" };
+    const colors = pc.createColors(io.caps.color);
+    const maxVisible = opts.maxVisible ?? 10;
+    const frame = createFrame(io.write, io.caps);
+    let query = "";
+    let cursor = 0; // index into the ranked results
+    const paint = (ranked) => {
+        const lines = [];
+        if (opts.title)
+            lines.push(colors.bold(opts.title));
+        lines.push(`${colors.cyan("›")} ${query}${colors.dim("▏")}`);
+        if (ranked.length === 0) {
+            lines.push(colors.dim("  no results — backspace to widen"));
+        }
+        else {
+            // Keep the highlighted row inside the viewport.
+            const top = Math.min(Math.max(0, cursor - maxVisible + 1), Math.max(0, ranked.length - maxVisible));
+            const visible = ranked.slice(top, top + maxVisible);
+            for (const [i, row] of visible.entries()) {
+                const selected = top + i === cursor;
+                const marker = selected ? colors.cyan("❯") : " ";
+                const label = highlightMatch(row.label, row.match.positions, colors);
+                lines.push(`${marker} ${selected ? label : colors.dim(label)}`);
+            }
+            const hidden = ranked.length - visible.length;
+            if (hidden > 0)
+                lines.push(colors.dim(`  … ${hidden} more`));
+        }
+        frame.render(lines);
+    };
+    io.keys.begin();
+    try {
+        let ranked = rankItems(items, opts.toLabel, query);
+        paint(ranked);
+        for (;;) {
+            const key = await io.keys.read();
+            switch (key.kind) {
+                case "ctrl-c":
+                case "eof":
+                case "escape":
+                    return { kind: "cancelled" };
+                case "enter":
+                    if (ranked.length === 0)
+                        break; // inert in the no-results state
+                    return { kind: "selected", value: ranked[cursor].item };
+                case "up":
+                    if (ranked.length > 0) {
+                        cursor = (cursor - 1 + ranked.length) % ranked.length;
+                    }
+                    break;
+                case "down":
+                    if (ranked.length > 0)
+                        cursor = (cursor + 1) % ranked.length;
+                    break;
+                case "backspace":
+                    if (query.length > 0) {
+                        query = query.slice(0, -1);
+                        ranked = rankItems(items, opts.toLabel, query);
+                        cursor = 0;
+                    }
+                    break;
+                case "char":
+                    query += key.char;
+                    ranked = rankItems(items, opts.toLabel, query);
+                    cursor = 0;
+                    break;
+                default:
+                    break; // tab / left / right: no meaning here
+            }
+            paint(ranked);
+        }
+    }
+    finally {
+        // Both on selection and on cancel: erase the frame and leave raw mode —
+        // no leftover artifact bytes, terminal always restored.
+        frame.clear();
+        io.keys.restore();
+    }
+}

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./keys.js";
+export * from "./input.js";
+export * from "./frame.js";
+export * from "./select.js";
+export * from "./fuzzy.js";
+export * from "./autocomplete.js";

package/dist/components/index.js

@@ -0,0 +1,6 @@
+export * from "./keys.js";
+export * from "./input.js";
+export * from "./frame.js";
+export * from "./select.js";
+export * from "./fuzzy.js";
+export * from "./autocomplete.js";

package/dist/components/input.d.ts

@@ -0,0 +1,78 @@
+import type { RenderCapabilities } from "../render/index.js";
+import { type Key } from "./keys.js";
+/**
+ * The one raw-mode input reader (U.7). Every interactive component — and the
+ * refactored approval/onboarding key readers — reads keys through this seam;
+ * nothing else in the CLI touches `setRawMode`. The lifecycle is strict:
+ * `begin()` → `read()` loop → `restore()` in a `finally`, so the terminal is
+ * never left in raw mode on any exit path (selection, cancel, throw).
+ */
+/** The minimal stdin surface the reader needs. Injectable for tests. */
+export interface RawInput {
+    isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: "data" | "end", listener: (chunk: Buffer) => void): unknown;
+    removeListener(event: "data" | "end", listener: (chunk: Buffer) => void): unknown;
+}
+/** Raw-mode key source with an explicit begin/read/restore lifecycle. */
+export interface KeyReader {
+    /** Enter raw mode and start decoding. Safe to call once per interaction. */
+    begin(): void;
+    /**
+     * The next decoded key. After stream end (or `restore()`), resolves
+     * `{kind:"eof"}` forever — a component's read loop can never hang or reject.
+     */
+    read(): Promise<Key>;
+    /** Leave raw mode, detach, pause. Idempotent; call in `finally`, always. */
+    restore(): void;
+}
+/** Build the real reader over `stdin` (or an injected fake in tests). */
+export declare function createKeyReader(stdin?: RawInput): KeyReader;
+/**
+ * Read exactly one key with the full begin/restore lifecycle — the shared
+ * backend for the approval prompt's single-key read and the onboarding
+ * `readKey`. Resolves the printable character, `"\n"` for enter, and `""` for
+ * anything that means "no answer" (Ctrl-C, EOF, escape, arrows) — preserving
+ * the callers' default-deny mapping.
+ */
+export declare function readSingleKey(stdin?: RawInput): Promise<string>;
+/**
+ * Every component resolves to a selection or a clean, typed cancellation
+ * (Ctrl-C / EOF / escape). Cancellation is data for the caller to interpret —
+ * never a thrown error, never a partial value.
+ */
+export type InteractiveResult<T> = {
+    kind: "selected";
+    value: T;
+} | {
+    kind: "cancelled";
+};
+/**
+ * What a component needs from the environment, bundled so tests can script
+ * all of it. `caps` is the existing U.2 capability detection — components
+ * never re-probe NO_COLOR / width / TTY themselves.
+ */
+export interface ComponentIO {
+    caps: RenderCapabilities;
+    /**
+     * The whole interactive contract in one flag: stdin is a TTY *and* the
+     * output supports cursor control (`TERM=dumb` fails this). When false, no
+     * frame is drawn and no key is read — ever.
+     */
+    interactive: boolean;
+    /** Transient frame bytes. Defaults to stderr so stdout stays pipe-clean. */
+    write(text: string): void;
+    keys: KeyReader;
+}
+/** The real environment: frames to stderr, keys from stdin, caps from stderr. */
+export declare function defaultComponentIO(): ComponentIO;
+/**
+ * The shared non-TTY gate, run before any frame byte or key read:
+ * - interactive → proceed;
+ * - not interactive + a default was supplied → resolve to it immediately;
+ * - otherwise → throw `CRUXY_E_INTERACTIVE_REQUIRED` (usage, exit 2).
+ * Never blocks on a pipe, never silently picks an option.
+ */
+export declare function resolveNonInteractive<T>(io: ComponentIO, what: string, defaultValue: T | undefined, alternatives?: string[]): InteractiveResult<T> | null;