@cruxy/cli 0.8.0 → 0.10.0

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/config/schema.d.ts

@@ -203,6 +203,65 @@ export declare const IndexConfigSchema: z.ZodObject<{
         overlapLines?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export declare const CheckpointConfigSchema: z.ZodObject<{
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    retention: number;
+}, {
+    enabled?: boolean | undefined;
+    retention?: number | undefined;
+}>;
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export declare const SubagentConfigSchema: z.ZodObject<{
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z.ZodDefault<z.ZodObject<{
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    }, {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    maxDepth: number;
+    defaultBudget: {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    };
+}, {
+    maxDepth?: number | undefined;
+    defaultBudget?: {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
+}>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -405,6 +464,56 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     }>>;
+    checkpoint: z.ZodDefault<z.ZodObject<{
+        /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** How many checkpoints to keep; older ones are pruned oldest-first. */
+        retention: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        retention: number;
+    }, {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    }>>;
+    subagent: z.ZodDefault<z.ZodObject<{
+        /**
+         * Maximum subagent nesting depth. The main agent is depth 0; the default of
+         * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+         */
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+        defaultBudget: z.ZodDefault<z.ZodObject<{
+            /** Hard cap on the subagent's model turns. */
+            maxIterations: z.ZodDefault<z.ZodNumber>;
+            /** Hard cap on the subagent's combined input+output tokens. */
+            maxTokens: z.ZodDefault<z.ZodNumber>;
+            /** Optional wall-clock cap; unset means no time limit. */
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        }, {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    }, {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -471,6 +580,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
+    checkpoint: {
+        enabled: boolean;
+        retention: number;
+    };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -529,6 +650,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
+    checkpoint?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    } | undefined;
+    subagent?: {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -137,6 +137,44 @@ export const IndexConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export const CheckpointConfigSchema = z
+    .object({
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.boolean().default(true),
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.number().int().positive().default(10),
+})
+    .strict();
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export const SubagentConfigSchema = z
+    .object({
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.number().int().nonnegative().default(1),
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z
+        .object({
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.number().int().positive().default(10),
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.number().int().positive().default(32000),
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.number().int().positive().optional(),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -156,6 +194,8 @@ export const CruxyConfigSchema = z
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
     index: IndexConfigSchema.default({}),
+    checkpoint: CheckpointConfigSchema.default({}),
+    subagent: SubagentConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

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;
@@ -53,6 +60,31 @@ export declare function planRevisionLimit(limit: number): CruxyError;
  * tell it apart from a per-action approval requirement.
  */
 export declare function planApprovalRequired(): CruxyError;
+/**
+ * Creating, reading, or restoring a working-tree checkpoint failed (C.32).
+ * Fail-loud by design: an agent run never mutates files without its undo
+ * protection unless the user explicitly disables it.
+ */
+export declare function checkpointFailed(reason: string, underlying?: unknown): CruxyError;
+/** The requested checkpoint id doesn't exist (or no checkpoints exist at all). */
+export declare function checkpointNotFound(id?: string): CruxyError;
+/**
+ * Rollback needs interactive approval but cruxy is running non-interactively.
+ * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
+ */
+export declare function rollbackApprovalRequired(): CruxyError;
+/**
+ * A subagent spawn was attempted past the configured nesting cap (C.14). The
+ * spawn tool is structurally withheld at the cap, so reaching this means the
+ * orchestrator seam was driven directly — fail loud, never spawn.
+ */
+export declare function subagentDepthExceeded(depth: number, maxDepth: number): CruxyError;
+/**
+ * A subagent run failed outright (provider error, tool crash) before producing
+ * a result. Normally folded into the structured `SubagentResult` the parent
+ * reasons over; thrown only when the orchestrator itself cannot proceed.
+ */
+export declare function subagentFailed(underlying?: unknown): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed