@cruxy/cli 0.9.0 → 0.11.0

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();
+    }
+}