@cruxy/cli 0.9.0 → 0.11.0

package/dist/approval/classify.js

@@ -16,6 +16,8 @@ export function classify(action, cwd) {
             return fileRequest(action, patchHasDelete(action) ? "destructive" : "mutate", root);
         case "shell":
             return shellRequest(action, root);
+        case "test":
+            return testRequest(action, root);
         case "vcs":
             return vcsRequest(action, root);
         case "rollback":
@@ -69,6 +71,25 @@ function shellRequest(action, root) {
         cwd: root,
     };
 }
+// ── test (run the project's test suite, C.13) ──────────────────────────────────
+/**
+ * A test-suite execution. Destructive tier — a test script is arbitrary code
+ * from package.json — but grantable at the tightest possible scope: the exact
+ * command string. That is precisely what an edit→re-run iteration needs
+ * (approve once, re-run the same suite freely) without widening to a program
+ * prefix the way a shell grant would.
+ */
+function testRequest(action, root) {
+    const command = (action.command ?? "").trim();
+    return {
+        action,
+        tier: "destructive",
+        scope: command === "" ? { kind: "none" } : { kind: "shell-exact", command },
+        summary: `run tests: ${command}`,
+        targets: [],
+        cwd: root,
+    };
+}
 // ── vcs (open pull request) ─────────────────────────────────────────────────────
 /**
  * A pull-request publish (C.15): branch → commit → push → open PR. Always

package/dist/approval/policy.js

@@ -38,6 +38,12 @@ export function scopeCovers(scope, request) {
         const tokens = commandTokens(request.action.command ?? "");
         return tokens !== null && tokens[0] === scope.token;
     }
+    if (scope.kind === "shell-exact") {
+        // Test grants (C.13): the exact command string, test actions only — a
+        // grant for `pnpm test` can never cover run_command or any other command.
+        return (request.action.kind === "test" &&
+            (request.action.command ?? "").trim() === scope.command);
+    }
     // file-subtree
     return (request.targets.length > 0 &&
         request.targets.every((t) => isInside(scope.root, t)));

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`
@@ -44,9 +45,9 @@ export function render(request, color) {
     lines.push(choices(request.scope, c));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
-/** The action detail: a diff for file actions, the command + cwd for shell. */
+/** The action detail: a diff for file actions, the command + cwd for shell/test. */
 function detail(request, c) {
-    if (request.action.kind === "shell") {
+    if (request.action.kind === "shell" || request.action.kind === "test") {
         return [
             `  ${c.dim("$")} ${request.action.command ?? ""}`,
             `  ${c.dim(`in ${request.cwd}`)}`,
@@ -66,6 +67,8 @@ function choices(scope, c) {
 function scopeLabel(scope) {
     if (scope.kind === "shell-prefix")
         return `${scope.token} commands`;
+    if (scope.kind === "shell-exact")
+        return `re-runs of \`${scope.command}\``;
     if (scope.kind === "file-subtree")
         return `changes under ${path.basename(scope.root)}/`;
     return null;
@@ -75,37 +78,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/approval/types.d.ts

@@ -17,6 +17,8 @@ export type RiskTier = "read" | "mutate" | "destructive";
  * The tight scope a session grant is keyed by. Never blanket.
  * - `shell-prefix` — a command's leading program token (e.g. `git`); only ever
  *   matches commands we can *positively* prove are simple (no shell features).
+ * - `shell-exact` — one exact command string, for `test` actions only (C.13):
+ *   a grant covers re-runs of precisely that test command, nothing else.
  * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
  *   file path); matches targets that resolve inside it.
  * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
@@ -24,6 +26,9 @@ export type RiskTier = "read" | "mutate" | "destructive";
 export type Scope = {
     readonly kind: "shell-prefix";
     readonly token: string;
+} | {
+    readonly kind: "shell-exact";
+    readonly command: string;
 } | {
     readonly kind: "file-subtree";
     readonly root: string;

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/commands/test.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `cruxy test` (C.13) — run the project's detected/configured test command
+ * once and print the structured result the agent would see. Directly
+ * user-invoked, so there is no approval gate (typing the command IS the
+ * consent — same as running the suite by hand); the process exit code mirrors
+ * the suite's pass/fail so scripts and CI can branch on it.
+ */
+export declare function testCommand(): Command;

package/dist/cli/commands/test.js

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { testCommandNotFound } from "../../errors/index.js";
+import { CommandTestRunner, detectTestCommand } from "../../testing/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy test` (C.13) — run the project's detected/configured test command
+ * once and print the structured result the agent would see. Directly
+ * user-invoked, so there is no approval gate (typing the command IS the
+ * consent — same as running the suite by hand); the process exit code mirrors
+ * the suite's pass/fail so scripts and CI can branch on it.
+ */
+export function testCommand() {
+    return new Command("test")
+        .description("run the project's test suite once and show the parsed result")
+        .action(async () => {
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        const detected = detectTestCommand(cwd, config);
+        if (detected === null)
+            throw testCommandNotFound();
+        logger.print(pc.dim(`running: ${detected.command}  [${detected.source}]`));
+        const result = await new CommandTestRunner().run(detected.command, {
+            cwd,
+            timeoutMs: config.shell.timeoutMs,
+            captureBytes: config.test.captureBytes,
+        });
+        const seconds = (result.durationMs / 1000).toFixed(1);
+        if (result.passed) {
+            logger.print(`${pc.green("✓")} tests passed${result.total !== undefined ? ` (${result.total})` : ""} in ${seconds}s`);
+            return;
+        }
+        logger.print(`${pc.red("✗")} tests failed (exit ${result.exitCode ?? "signal"}) in ${seconds}s`);
+        for (const failure of result.failures) {
+            const where = failure.file !== undefined
+                ? pc.dim(`  ${failure.file}${failure.line !== undefined ? `:${failure.line}` : ""}`)
+                : "";
+            logger.print(`  ${pc.red("✗")} ${failure.name}${where}`);
+        }
+        if (result.failures.length === 0) {
+            // Nothing parseable — show the honest tail instead of fake structure.
+            logger.print(pc.dim(result.output.trimEnd()));
+        }
+        process.exitCode = 1;
+    });
+}

package/dist/cli/program.js

@@ -12,6 +12,7 @@ import { loginCommand } from "./commands/login.js";
 import { initCommand } from "./commands/init.js";
 import { checkpointCommand } from "./commands/checkpoint.js";
 import { rollbackCommand } from "./commands/rollback.js";
+import { testCommand } from "./commands/test.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -40,6 +41,7 @@ export function buildProgram() {
     program.addCommand(initCommand());
     program.addCommand(checkpointCommand());
     program.addCommand(rollbackCommand());
+    program.addCommand(testCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

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/cli/session-factory.js

@@ -67,10 +67,14 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
         if (request.tier === "read")
             return decision;
         await checkpoints.ensureCheckpoint();
-        if (action.kind === "shell")
+        // Shell AND test executions (C.13) can mutate files we can't attribute
+        // (scripts, snapshot writers) — record the lost attribution the same way.
+        if (action.kind === "shell" || action.kind === "test") {
             await checkpoints.recordShellMutation();
-        else
+        }
+        else {
             await checkpoints.recordTouched([...request.targets]);
+        }
         return decision;
     };
 }

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>>;