@cruxy/cli 0.9.0 → 0.10.0

package/dist/approval/prompt.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import pc from "picocolors";
+import { readSingleKey } from "../components/input.js";
 import { renderActionPreview } from "../render/diff.js";
 /**
  * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
@@ -75,37 +76,13 @@ function scopeLabel(scope) {
 export function defaultPromptIO(color) {
     return {
         write: (text) => void process.stderr.write(text),
-        readKey: readKeyFromStdin,
+        // The shared U.7 raw-mode reader: one keypress, cooked mode always
+        // restored. Ctrl-C / EOF / escape resolve "" → the default-deny path.
+        readKey: () => readSingleKey(),
         readLine: readLineFromStdin,
         color,
     };
 }
-/** Read a single keypress in raw mode; "" on EOF. Always restores cooked mode. */
-function readKeyFromStdin() {
-    const stdin = process.stdin;
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onData = (buf) => {
-            cleanup();
-            resolve(buf.toString("utf8").slice(0, 1));
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve("");
-        };
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.once("data", onData);
-        stdin.once("end", onEnd);
-    });
-}
 /** Read one line in cooked mode; "" on EOF. */
 function readLineFromStdin() {
     const stdin = process.stdin;

package/dist/cli/commands/rollback.js

@@ -3,8 +3,43 @@ import pc from "picocolors";
 import { loadConfig } from "../../config/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
 import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
+import { fuzzyFind, selectList } from "../../components/index.js";
 import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
 import { logger } from "../../utils/logger.js";
+/** One picker row: id, age, and what the run was about. */
+function checkpointLabel(c) {
+    return `${c.id}  ${c.createdAt}  ${c.runSummary}`;
+}
+/**
+ * Choose which checkpoint to restore when the user gave no id (U.7 dogfood).
+ * One checkpoint → it, no ceremony. A short list → arrow-key SelectList with
+ * the newest preselected, so Enter-once matches the old "defaults to the
+ * most recent" behavior. A long list → type-to-filter FuzzyFinder. Returns
+ * `null` on cancel (nothing restored) — cancellation is a result, not an
+ * error.
+ */
+async function pickCheckpoint(service) {
+    const checkpoints = await service.list(); // newest first
+    if (checkpoints.length === 0)
+        return undefined; // let rollback() fail loud
+    if (checkpoints.length === 1)
+        return checkpoints[0];
+    const common = {
+        title: "pick a checkpoint to roll back to (newest first)",
+        nonInteractiveHint: ["or pass the id directly: `cruxy rollback <id>`"],
+        // Non-TTY can't reach here (refused above), but the components' own
+        // fallback still names the flag if that ever changes.
+        defaultValue: checkpoints[0],
+    };
+    const result = checkpoints.length > 10
+        ? await fuzzyFind(checkpoints, { ...common, toLabel: checkpointLabel })
+        : await selectList(checkpoints, {
+            ...common,
+            toLabel: checkpointLabel,
+            initialIndex: 0,
+        });
+    return result.kind === "selected" ? result.value : null;
+}
 /**
  * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
  * undoing everything an agent run changed (creates, edits, deletes) in one
@@ -31,6 +66,16 @@ export function rollbackCommand() {
             interactive,
             io: defaultPromptIO(shouldUseColor()),
         });
+        // No id given → pick one interactively (U.7). Enter-once still restores
+        // the newest, exactly as before the picker existed.
+        if (id === undefined) {
+            const picked = await pickCheckpoint(service);
+            if (picked === null) {
+                logger.print(pc.dim("rollback cancelled — nothing was changed"));
+                return;
+            }
+            id = picked?.id;
+        }
         const result = await service.rollback(id, {
             requestApproval: (action) => approval.requestApproval(action),
             interactive,

package/dist/cli/repl.d.ts

@@ -2,6 +2,11 @@ import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
 import { type StreamRenderer } from "../render/index.js";
+/**
+ * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
+ * sync with the dispatch below and the HELP text.
+ */
+export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/exit", "/quit"];
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;

package/dist/cli/repl.js

@@ -1,9 +1,23 @@
 import readline from "node:readline";
 import pc from "picocolors";
+import { makeReplCompleter } from "../components/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { createRenderer } from "../render/index.js";
 import { logger } from "../utils/logger.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
+/**
+ * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
+ * sync with the dispatch below and the HELP text.
+ */
+export const REPL_COMMANDS = [
+    "/help",
+    "/clear",
+    "/compact",
+    "/reload",
+    "/plan",
+    "/exit",
+    "/quit",
+];
 const HELP = `Commands:
   /help          show this help
   /clear         clear the conversation history (keep the session)
@@ -35,6 +49,9 @@ function readLine(io, prompt) {
     const rl = readline.createInterface({
         input: io.input,
         output: io.output,
+        // Tab-completion for slash commands (U.7): readline rewrites the edit
+        // buffer only — completing never submits, Enter remains the sole trigger.
+        completer: makeReplCompleter(() => REPL_COMMANDS),
     });
     return new Promise((resolve) => {
         let answered = false;

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;

package/dist/components/input.js

@@ -0,0 +1,111 @@
+import { interactiveRequired } from "../errors/index.js";
+import { detectCapabilities } from "../render/index.js";
+import { decodeKeys } from "./keys.js";
+/** Build the real reader over `stdin` (or an injected fake in tests). */
+export function createKeyReader(stdin = process.stdin) {
+    const queue = [];
+    const waiters = [];
+    let active = false;
+    let ended = false;
+    const push = (key) => {
+        const waiter = waiters.shift();
+        if (waiter)
+            waiter(key);
+        else
+            queue.push(key);
+    };
+    const onData = (chunk) => {
+        for (const key of decodeKeys(chunk))
+            push(key);
+    };
+    const onEnd = () => {
+        ended = true;
+        // Wake every waiter: EOF is a key, not an error.
+        while (waiters.length > 0)
+            push({ kind: "eof" });
+    };
+    return {
+        begin() {
+            if (active)
+                return;
+            active = true;
+            if (stdin.isTTY)
+                stdin.setRawMode?.(true);
+            stdin.resume();
+            stdin.on("data", onData);
+            stdin.on("end", onEnd);
+        },
+        read() {
+            const next = queue.shift();
+            if (next)
+                return Promise.resolve(next);
+            if (ended || !active)
+                return Promise.resolve({ kind: "eof" });
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+        restore() {
+            if (!active)
+                return;
+            active = false;
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            if (stdin.isTTY)
+                stdin.setRawMode?.(false);
+            stdin.pause();
+            // Unblock anything still awaiting a key — restore means the interaction
+            // is over, and a hung promise would leak the caller.
+            while (waiters.length > 0)
+                waiters.shift()({ kind: "eof" });
+        },
+    };
+}
+/**
+ * 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 async function readSingleKey(stdin = process.stdin) {
+    const keys = createKeyReader(stdin);
+    keys.begin();
+    try {
+        const key = await keys.read();
+        switch (key.kind) {
+            case "char":
+                return key.char;
+            case "enter":
+                return "\n";
+            default:
+                return "";
+        }
+    }
+    finally {
+        keys.restore();
+    }
+}
+/** The real environment: frames to stderr, keys from stdin, caps from stderr. */
+export function defaultComponentIO() {
+    const caps = detectCapabilities(process.stderr);
+    return {
+        caps,
+        interactive: Boolean(process.stdin.isTTY) && caps.cursor,
+        write: (text) => void process.stderr.write(text),
+        keys: createKeyReader(process.stdin),
+    };
+}
+/**
+ * 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 function resolveNonInteractive(io, what, defaultValue, alternatives = []) {
+    if (io.interactive)
+        return null;
+    if (defaultValue !== undefined) {
+        return { kind: "selected", value: defaultValue };
+    }
+    throw interactiveRequired(what, alternatives);
+}

package/dist/components/keys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Byte → key decoding for the interactive components (U.7). Pure data
+ * transformation — no terminal, no state — so every mapping row is directly
+ * unit-testable. The stateful raw-mode plumbing lives in `input.ts`.
+ */
+/** One decoded keypress. The full vocabulary the U.7 components consume. */
+export type Key = 
+/** A printable character (UTF-8; may be multi-byte, never a control char). */
+{
+    kind: "char";
+    char: string;
+} | {
+    kind: "enter";
+} | {
+    kind: "backspace";
+} | {
+    kind: "tab";
+} | {
+    kind: "escape";
+} | {
+    kind: "up";
+} | {
+    kind: "down";
+} | {
+    kind: "left";
+} | {
+    kind: "right";
+}
+/** Ctrl-C in raw mode (no SIGINT is delivered) — components must cancel. */
+ | {
+    kind: "ctrl-c";
+}
+/** Ctrl-D or stream end — components must cancel. */
+ | {
+    kind: "eof";
+};
+/**
+ * Decode one raw-mode chunk into keys. A paste or fast typing delivers many
+ * keys per chunk; all are returned in order.
+ *
+ * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
+ * any other CSI sequence (`ESC [ …final`) is swallowed whole (unmapped keys
+ * must not leak garbage chars into a query), and a lone ESC decodes to
+ * `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * split across chunks degrades to `escape` + literal chars, which is safe
+ * (escape cancels).
+ */
+export declare function decodeKeys(chunk: Buffer | string): Key[];

package/dist/components/keys.js

@@ -0,0 +1,105 @@
+/**
+ * Byte → key decoding for the interactive components (U.7). Pure data
+ * transformation — no terminal, no state — so every mapping row is directly
+ * unit-testable. The stateful raw-mode plumbing lives in `input.ts`.
+ */
+const CTRL_C = 0x03;
+const CTRL_D = 0x04;
+const BACKSPACE = 0x08;
+const TAB = 0x09;
+const LF = 0x0a;
+const CR = 0x0d;
+const ESC = 0x1b;
+const DELETE = 0x7f;
+/** CSI final byte → arrow key, for `ESC [ <final>` sequences. */
+const ARROWS = {
+    0x41: "up", // A
+    0x42: "down", // B
+    0x43: "right", // C
+    0x44: "left", // D
+};
+/**
+ * Decode one raw-mode chunk into keys. A paste or fast typing delivers many
+ * keys per chunk; all are returned in order.
+ *
+ * Escape handling is deliberately simple: `ESC [ A..D` decodes to an arrow,
+ * any other CSI sequence (`ESC [ …final`) is swallowed whole (unmapped keys
+ * must not leak garbage chars into a query), and a lone ESC decodes to
+ * `escape`. Terminals send arrow sequences atomically in practice; a sequence
+ * split across chunks degrades to `escape` + literal chars, which is safe
+ * (escape cancels).
+ */
+export function decodeKeys(chunk) {
+    const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+    const keys = [];
+    for (let i = 0; i < buf.length;) {
+        const byte = buf[i];
+        if (byte === ESC) {
+            if (buf[i + 1] === 0x5b /* [ */) {
+                // CSI: consume parameter/intermediate bytes (0x20–0x3f) up to the
+                // final byte (0x40–0x7e); map arrows, swallow everything else.
+                let j = i + 2;
+                while (j < buf.length && buf[j] >= 0x20 && buf[j] <= 0x3f)
+                    j++;
+                if (j < buf.length) {
+                    // Only a bare `ESC [ <final>` maps to an arrow; parameterized
+                    // sequences (modifier arrows, Home/End variants) are swallowed —
+                    // an unmapped combo must do nothing, not act as a plain arrow.
+                    const arrow = j === i + 2 ? ARROWS[buf[j]] : undefined;
+                    if (arrow)
+                        keys.push({ kind: arrow });
+                    i = j + 1;
+                    continue;
+                }
+                // Truncated CSI at chunk end: treat as escape, drop the partial tail.
+                keys.push({ kind: "escape" });
+                i = buf.length;
+                continue;
+            }
+            keys.push({ kind: "escape" });
+            i++;
+            continue;
+        }
+        if (byte === CTRL_C) {
+            keys.push({ kind: "ctrl-c" });
+            i++;
+            continue;
+        }
+        if (byte === CTRL_D) {
+            keys.push({ kind: "eof" });
+            i++;
+            continue;
+        }
+        if (byte === CR || byte === LF) {
+            keys.push({ kind: "enter" });
+            // Swallow a CRLF pair as one enter.
+            if (byte === CR && buf[i + 1] === LF)
+                i++;
+            i++;
+            continue;
+        }
+        if (byte === BACKSPACE || byte === DELETE) {
+            keys.push({ kind: "backspace" });
+            i++;
+            continue;
+        }
+        if (byte === TAB) {
+            keys.push({ kind: "tab" });
+            i++;
+            continue;
+        }
+        if (byte < 0x20) {
+            // Other control chars: ignore (same rule as the secret reader).
+            i++;
+            continue;
+        }
+        // Printable: consume one UTF-8 code point (1–4 bytes by lead byte).
+        const len = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+        keys.push({
+            kind: "char",
+            char: buf.subarray(i, Math.min(i + len, buf.length)).toString("utf8"),
+        });
+        i += len;
+    }
+    return keys;
+}

package/dist/components/select.d.ts

@@ -0,0 +1,28 @@
+import { type ComponentIO, type InteractiveResult } from "./input.js";
+/**
+ * SelectList (U.7): arrow-key pick from a short list of options. Single-select
+ * only — multi-select is a deliberate seam for a later build (the result type
+ * and key loop extend without breaking callers).
+ */
+export interface SelectOptions<T> {
+    /** Label an item renders under. Defaults to `String(item)`. */
+    toLabel?: (item: T) => string;
+    /** Header row above the options. */
+    title?: string;
+    /** Index highlighted first (so Enter-once picks a sensible default). */
+    initialIndex?: number;
+    /** Non-TTY fallback: resolve to this instead of failing loud. */
+    defaultValue?: T;
+    /** `--flag` alternatives listed in the non-TTY error. */
+    nonInteractiveHint?: string[];
+    /** Visible rows before the list scrolls (default 10). */
+    maxVisible?: number;
+}
+/**
+ * Pick one item: ↑/↓ move (wrapping past either end), Enter selects the
+ * highlighted item, Esc / Ctrl-C / EOF cancel. Renders a transient frame via
+ * the shared U.7 frame (width-truncated rows, no soft-wrap) and erases it
+ * completely before resolving. Empty `items` resolves cancelled — there is
+ * nothing to select.
+ */
+export declare function selectList<T>(items: readonly T[], opts?: SelectOptions<T>, io?: ComponentIO): Promise<InteractiveResult<T>>;

package/dist/components/select.js

@@ -0,0 +1,69 @@
+import pc from "picocolors";
+import { createFrame } from "./frame.js";
+import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
+/**
+ * Pick one item: ↑/↓ move (wrapping past either end), Enter selects the
+ * highlighted item, Esc / Ctrl-C / EOF cancel. Renders a transient frame via
+ * the shared U.7 frame (width-truncated rows, no soft-wrap) and erases it
+ * completely before resolving. Empty `items` resolves cancelled — there is
+ * nothing to select.
+ */
+export async function selectList(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 toLabel = opts.toLabel ?? ((item) => String(item));
+    const colors = pc.createColors(io.caps.color);
+    const maxVisible = opts.maxVisible ?? 10;
+    const frame = createFrame(io.write, io.caps);
+    let cursor = Math.min(Math.max(opts.initialIndex ?? 0, 0), items.length - 1);
+    const paint = () => {
+        const lines = [];
+        if (opts.title)
+            lines.push(colors.bold(opts.title));
+        const top = Math.min(Math.max(0, cursor - maxVisible + 1), Math.max(0, items.length - maxVisible));
+        const visible = items.slice(top, top + maxVisible);
+        for (const [i, item] of visible.entries()) {
+            const selected = top + i === cursor;
+            const marker = selected ? colors.cyan("❯") : " ";
+            const label = toLabel(item);
+            lines.push(`${marker} ${selected ? label : colors.dim(label)}`);
+        }
+        const hidden = items.length - visible.length;
+        if (hidden > 0)
+            lines.push(colors.dim(`  … ${hidden} more`));
+        lines.push(colors.dim("  ↑/↓ move · enter select · esc cancel"));
+        frame.render(lines);
+    };
+    io.keys.begin();
+    try {
+        paint();
+        for (;;) {
+            const key = await io.keys.read();
+            switch (key.kind) {
+                case "ctrl-c":
+                case "eof":
+                case "escape":
+                    return { kind: "cancelled" };
+                case "enter":
+                    return { kind: "selected", value: items[cursor] };
+                case "up":
+                    cursor = (cursor - 1 + items.length) % items.length;
+                    break;
+                case "down":
+                    cursor = (cursor + 1) % items.length;
+                    break;
+                default:
+                    break; // chars/tab have no meaning in a plain select
+            }
+            paint();
+        }
+    }
+    finally {
+        // Selection or cancel alike: no leftover frame bytes, raw mode released.
+        frame.clear();
+        io.keys.restore();
+    }
+}

package/dist/errors/constructors.d.ts

@@ -2,6 +2,13 @@ import { CruxyError } from "./types.js";
 /** Best-effort human message for an arbitrary thrown value. */
 export declare function messageOf(underlying: unknown): string | undefined;
 export declare function usageError(title: string, nextSteps?: string[]): CruxyError;
+/**
+ * An interactive component (picker, fuzzy finder) was needed but stdin is not
+ * an interactive terminal and the caller supplied no default (U.7). Never
+ * silently picks an option, never blocks on a pipe — same discipline as the
+ * approval/onboarding layers.
+ */
+export declare function interactiveRequired(what: string, alternatives?: string[]): CruxyError;
 export declare function configKeyUnknown(key: string): CruxyError;
 export declare function providerUnsupported(provider: string): CruxyError;
 export declare function configParse(path: string, underlying?: unknown): CruxyError;

package/dist/errors/constructors.js

@@ -23,6 +23,21 @@ export function usageError(title, nextSteps) {
         nextSteps: nextSteps ?? ["run `cruxy --help` for usage"],
     });
 }
+/**
+ * An interactive component (picker, fuzzy finder) was needed but stdin is not
+ * an interactive terminal and the caller supplied no default (U.7). Never
+ * silently picks an option, never blocks on a pipe — same discipline as the
+ * approval/onboarding layers.
+ */
+export function interactiveRequired(what, alternatives = []) {
+    return new CruxyError({
+        code: ErrorCode.InteractiveRequired,
+        title: `${what} needs an interactive terminal`,
+        cause: "stdin is not a TTY (or the terminal cannot render an interactive picker)",
+        nextSteps: ["run cruxy in an interactive terminal", ...alternatives],
+        meta: { what },
+    });
+}
 export function configKeyUnknown(key) {
     return new CruxyError({
         code: ErrorCode.ConfigKeyUnknown,

package/dist/errors/types.d.ts

@@ -14,6 +14,7 @@
 export declare const ErrorCode: {
     readonly Internal: "CRUXY_E_INTERNAL";
     readonly Usage: "CRUXY_E_USAGE";
+    readonly InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED";
     readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
     readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
     readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";

package/dist/errors/types.js

@@ -16,6 +16,7 @@ export const ErrorCode = {
     Internal: "CRUXY_E_INTERNAL",
     // usage (exit 2)
     Usage: "CRUXY_E_USAGE",
+    InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED",
     ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
     ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
     GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
@@ -67,6 +68,7 @@ export const ErrorCode = {
 const EXIT_CODES = {
     [ErrorCode.Internal]: 1,
     [ErrorCode.Usage]: 2,
+    [ErrorCode.InteractiveRequired]: 2,
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
     [ErrorCode.GitProtectedBranch]: 2,

package/dist/onboarding/io.d.ts

@@ -2,7 +2,8 @@ import type { OnboardingIO } from "./types.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export declare function defaultOnboardingIO(color?: boolean): OnboardingIO;

package/dist/onboarding/io.js

@@ -1,54 +1,21 @@
+import { createKeyReader, readSingleKey } from "../components/input.js";
 import { shouldUseColor } from "../errors/index.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export function defaultOnboardingIO(color = shouldUseColor()) {
     return {
         write: (text) => void process.stderr.write(text),
         readLine: readLineFromStdin,
-        readKey: readKeyFromStdin,
+        readKey: () => readSingleKey(),
         readSecret: readSecretFromStdin,
         color,
     };
 }
-const CTRL_C = 0x03;
-const CTRL_D = 0x04;
-const BACKSPACE = 0x08;
-const DELETE = 0x7f;
-const LF = 0x0a;
-const CR = 0x0d;
-/** Read one keypress in raw mode; "" on EOF / Ctrl-C / Ctrl-D. Restores cooked mode. */
-function readKeyFromStdin() {
-    const stdin = process.stdin;
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onData = (buf) => {
-            cleanup();
-            const code = buf[0];
-            resolve(code === CTRL_C || code === CTRL_D
-                ? ""
-                : buf.toString("utf8").slice(0, 1));
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve("");
-        };
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.once("data", onData);
-        stdin.once("end", onEnd);
-    });
-}
 /** Read one line in cooked mode; "" on EOF. */
 function readLineFromStdin() {
     const stdin = process.stdin;
@@ -80,54 +47,41 @@ function readLineFromStdin() {
 }
 /**
  * Read a secret with no echo: each printable keystroke shows a `*`, backspace
- * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The real
- * characters are never written anywhere.
+ * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The
+ * real characters are never written anywhere. Built on the shared key reader,
+ * which also keeps arrow/escape sequences from leaking into the secret.
  */
-function readSecretFromStdin() {
-    const stdin = process.stdin;
+async function readSecretFromStdin() {
     const out = process.stderr;
-    return new Promise((resolve) => {
-        let buf = "";
-        let done = false;
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            cleanup();
-            out.write("\n");
-            resolve(value);
-        };
-        const onData = (chunk) => {
-            for (const byte of chunk) {
-                if (byte === CR || byte === LF)
-                    return finish(buf); // Enter → submit
-                if (byte === CTRL_C || byte === CTRL_D)
-                    return finish(""); // abort
-                if (byte === DELETE || byte === BACKSPACE) {
+    const keys = createKeyReader(process.stdin);
+    keys.begin();
+    let buf = "";
+    try {
+        for (;;) {
+            const key = await keys.read();
+            switch (key.kind) {
+                case "enter":
+                    return buf;
+                case "ctrl-c":
+                case "eof":
+                    return "";
+                case "backspace":
                     if (buf.length > 0) {
                         buf = buf.slice(0, -1);
                         out.write("\b \b"); // erase one star
                     }
-                    continue;
-                }
-                if (byte < 0x20)
-                    continue; // ignore other control chars
-                buf += String.fromCharCode(byte);
-                out.write("*");
+                    break;
+                case "char":
+                    buf += key.char;
+                    out.write("*");
+                    break;
+                default:
+                    break; // arrows / tab / escape: ignored, never echoed
             }
-        };
-        const onEnd = () => finish("");
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.on("data", onData);
-        stdin.once("end", onEnd);
-    });
+        }
+    }
+    finally {
+        keys.restore();
+        out.write("\n");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {