@cruxy/cli 0.10.0 → 0.12.0

package/dist/testing/runner.js

@@ -0,0 +1,124 @@
+import { spawn } from "node:child_process";
+import { parseFailures } from "./parse.js";
+/**
+ * The shipped {@link TestRunner}: spawn the command via the system shell (the
+ * same detached-group + kill-tree discipline as `run_command`), capture a
+ * TAIL-biased, byte-capped transcript (failures live at the end of test
+ * output), and derive `passed` from the exit code — the only source of truth.
+ * A timeout, a signal kill, or a spawn error is a *failed result*, never a
+ * thrown exception and never a fabricated success.
+ */
+export class CommandTestRunner {
+    run(command, opts) {
+        const startedAt = Date.now();
+        return new Promise((resolve) => {
+            const capture = new TailCapture(opts.captureBytes);
+            let child;
+            try {
+                child = spawn(command, {
+                    shell: true,
+                    cwd: opts.cwd,
+                    detached: true,
+                });
+            }
+            catch (err) {
+                resolve(failed(null, err.message, startedAt));
+                return;
+            }
+            child.stdout?.on("data", (buf) => capture.push(buf));
+            child.stderr?.on("data", (buf) => capture.push(buf));
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                killTree(child.pid);
+                resolve(failed(null, capture.text() +
+                    `\n… [test run timed out after ${opts.timeoutMs}ms and was killed]`, startedAt, capture.truncated));
+            }, opts.timeoutMs);
+            child.on("error", (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(failed(null, err.message, startedAt));
+            });
+            child.on("close", (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const output = capture.text();
+                // THE honest-green rule: exit code 0 and nothing else means passed.
+                // `code` is null on a signal kill — a failure, whatever the output says.
+                const passed = code === 0;
+                const parsed = passed ? { failures: [] } : parseFailures(output);
+                resolve({
+                    passed,
+                    exitCode: code,
+                    durationMs: Date.now() - startedAt,
+                    ...(parsed.total !== undefined ? { total: parsed.total } : {}),
+                    failures: parsed.failures,
+                    output,
+                    outputTruncated: capture.truncated,
+                });
+            });
+        });
+    }
+}
+/** Shape a non-execution failure (spawn error, timeout) as a failed result. */
+function failed(exitCode, output, startedAt, truncated = false) {
+    return {
+        passed: false,
+        exitCode,
+        durationMs: Date.now() - startedAt,
+        failures: [],
+        output,
+        outputTruncated: truncated,
+    };
+}
+/**
+ * A rolling, tail-biased capture: whole chunks are dropped from the FRONT
+ * once the byte cap is exceeded, so the end of the output — where test
+ * runners print their failure summaries — always survives.
+ */
+export class TailCapture {
+    cap;
+    chunks = [];
+    bytes = 0;
+    truncated = false;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    push(buf) {
+        this.chunks.push(buf);
+        this.bytes += buf.length;
+        // Drop head chunks while the REMAINDER still meets the cap.
+        while (this.chunks.length > 1 &&
+            this.bytes - this.chunks[0].length >= this.cap) {
+            this.bytes -= this.chunks[0].length;
+            this.chunks.shift();
+            this.truncated = true;
+        }
+    }
+    text() {
+        let all = Buffer.concat(this.chunks);
+        if (all.length > this.cap) {
+            all = all.subarray(all.length - this.cap);
+            this.truncated = true;
+        }
+        const body = all.toString("utf8");
+        return this.truncated ? `… [earlier output truncated]\n${body}` : body;
+    }
+}
+/** Kill the whole process group (POSIX; matches run_command's behavior). */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+/** A resolved test command and where it came from — shown, never guessed. */
+export interface TestCommand {
+    command: string;
+    source: "config" | "package-json";
+}
+/** One extracted failure. Every field beyond `name`/`message` is best-effort. */
+export interface TestFailure {
+    name: string;
+    message: string;
+    file?: string;
+    line?: number;
+}
+/** The structured outcome of one test-suite execution. */
+export interface TestRunResult {
+    /** `exitCode === 0`, full stop — never inferred from output text. */
+    passed: boolean;
+    /** The command's exit code; `null` when killed by signal or never spawned. */
+    exitCode: number | null;
+    /** Measured wall time of the execution. */
+    durationMs: number;
+    /** Total tests, only when a parser confidently extracted it. */
+    total?: number;
+    /** Best-effort extracted failures; may be empty even when `passed` is false. */
+    failures: TestFailure[];
+    /** Tail-biased captured stdout+stderr, capped at `test.captureBytes`. */
+    output: string;
+    /** Whether the head of the output was dropped to honor the byte cap. */
+    outputTruncated: boolean;
+}
+/** Execution bounds handed to a runner per run. */
+export interface TestRunOptions {
+    cwd: string;
+    /** Kill the run (and its process tree) after this many ms. */
+    timeoutMs: number;
+    /** Cap on captured output bytes (tail-biased). */
+    captureBytes: number;
+}
+/**
+ * The swappable execution seam (same discipline as VectorStore/ForgeProvider):
+ * the shipped {@link CommandTestRunner} spawns the command via the system
+ * shell; tests inject fakes, and a future framework-native runner (e.g. a
+ * vitest API runner) slots in without touching the tool.
+ */
+export interface TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * A pluggable best-effort failure extractor: given the captured output,
+ * return whatever structure it can positively recognize — and nothing it
+ * can't. Parsers never touch `passed` and never fabricate counts.
+ */
+export type FailureParser = (output: string) => {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the test-execution loop (C.13): run the project's test suite,
+ * parse what's honestly parseable, and let the agent iterate on failures
+ * under a hard cap. The cardinal rule lives in `runner.ts`: **passed is
+ * derived from the exit code and nothing else.**
+ */
+export {};

package/dist/theme/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./tokens.js";
+export * from "./resolve.js";

package/dist/theme/index.js

@@ -0,0 +1,2 @@
+export * from "./tokens.js";
+export * from "./resolve.js";

package/dist/theme/resolve.d.ts

@@ -0,0 +1,32 @@
+import { type Theme, type ThemeCapabilities } from "./tokens.js";
+/**
+ * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * fully independent by construction:
+ *
+ * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
+ *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
+ *   tests.
+ * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
+ *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
+ *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ */
+export declare function resolveTheme(caps: ThemeCapabilities): Theme;
+/**
+ * Whether the terminal can render unicode glyphs. `TERM=dumb` and an explicit
+ * `CRUXY_ASCII` opt-in fall back to the ASCII table; everything else (real
+ * terminals AND pipes) keeps unicode — piping ✓/✗ to a file is fine, and this
+ * preserves pre-U.1 behavior for non-TTY output.
+ *
+ * The single source of the rule: `render/capabilities.ts` calls this to fill
+ * `RenderCapabilities.unicode`, and the boolean-seam surfaces (errors,
+ * approval, plan, onboarding, CLI commands) call it to build a theme without a
+ * signature change.
+ */
+export declare function detectUnicode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Build a theme for a surface that only knows a `color` boolean (the U.3
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
+ * from the environment so these surfaces still degrade on dumb terminals,
+ * with no change to their public boolean signatures.
+ */
+export declare function themeForColor(color: boolean, env?: NodeJS.ProcessEnv): Theme;

package/dist/theme/resolve.js

@@ -0,0 +1,73 @@
+import pc from "picocolors";
+import { ASCII_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
+/**
+ * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * fully independent by construction:
+ *
+ * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
+ *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
+ *   tests.
+ * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
+ *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
+ *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ */
+export function resolveTheme(caps) {
+    const c = pc.createColors(caps.color);
+    const glyph = caps.unicode ? UNICODE_GLYPHS : ASCII_GLYPHS;
+    const strong = c.bold;
+    const indent = (text, level = 1) => {
+        const pad = "  ".repeat(Math.max(0, level));
+        return text
+            .split("\n")
+            .map((line) => (line === "" ? line : pad + line))
+            .join("\n");
+    };
+    return {
+        danger: c.red,
+        warning: c.yellow,
+        success: c.green,
+        accent: c.cyan,
+        muted: c.dim,
+        strong,
+        syntax: {
+            keyword: c.magenta,
+            string: c.green,
+            number: c.yellow,
+            comment: c.dim,
+        },
+        glyph,
+        heading: strong,
+        indent,
+        kv: (key, value, keyWidth) => `${strong(keyWidth ? key.padEnd(keyWidth) : key)}  ${value}`,
+        sep: ` ${glyph.sep} `,
+        color: caps.color,
+        unicode: caps.unicode,
+    };
+}
+/**
+ * Whether the terminal can render unicode glyphs. `TERM=dumb` and an explicit
+ * `CRUXY_ASCII` opt-in fall back to the ASCII table; everything else (real
+ * terminals AND pipes) keeps unicode — piping ✓/✗ to a file is fine, and this
+ * preserves pre-U.1 behavior for non-TTY output.
+ *
+ * The single source of the rule: `render/capabilities.ts` calls this to fill
+ * `RenderCapabilities.unicode`, and the boolean-seam surfaces (errors,
+ * approval, plan, onboarding, CLI commands) call it to build a theme without a
+ * signature change.
+ */
+export function detectUnicode(env = process.env) {
+    if (env.CRUXY_ASCII !== undefined && env.CRUXY_ASCII !== "")
+        return false;
+    if (env.TERM === "dumb")
+        return false;
+    return true;
+}
+/**
+ * Build a theme for a surface that only knows a `color` boolean (the U.3
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
+ * from the environment so these surfaces still degrade on dumb terminals,
+ * with no change to their public boolean signatures.
+ */
+export function themeForColor(color, env = process.env) {
+    return resolveTheme({ color, unicode: detectUnicode(env) });
+}

package/dist/theme/tokens.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The terminal design system (U.1): one typed {@link Theme} of semantic tokens
+ * — color *roles* (never raw hues at call sites), a glyph set with ASCII
+ * fallbacks, and structure primitives. Every rendered surface resolves ONE
+ * theme (from {@link RenderCapabilities}) and references roles like
+ * `theme.danger(x)` / `theme.glyph.success`, so the CLI reads as one product
+ * and NO_COLOR / dumb-terminal degradation is handled in exactly one place.
+ *
+ * Picocolors is imported only by `resolve.ts`; this file is pure types + the
+ * two glyph tables.
+ */
+/** A text styler: wraps a string in ANSI, or the identity under NO_COLOR. */
+export type Styler = (text: string) => string;
+/**
+ * Language-token colors for the streaming syntax highlighter. A distinct
+ * sub-palette (not status semantics), centralized here so every color choice
+ * lives in the theme.
+ */
+export interface ThemeSyntax {
+    keyword: Styler;
+    string: Styler;
+    number: Styler;
+    comment: Styler;
+}
+/**
+ * The glyph vocabulary. Concrete strings (resolved to the unicode or ASCII
+ * table), so a call site writes `theme.glyph.success`, never a literal "✓".
+ */
+export interface ThemeGlyphs {
+    /** Success / done. */
+    success: string;
+    /** Failure / error. */
+    failure: string;
+    /** Not-yet-started (plan step). */
+    pending: string;
+    /** In-progress marker (static, non-animated). */
+    running: string;
+    /** Selected-row pointer in pickers. */
+    pointer: string;
+    /** Input caret (REPL prompt, fuzzy query). */
+    caret: string;
+    /** Next-step / relation arrow. */
+    arrow: string;
+    caretUp: string;
+    caretDown: string;
+    /** Text-cursor bar in the fuzzy query line. */
+    cursorBar: string;
+    bullet: string;
+    /** Inline separator (the ` · ` joiner uses this). */
+    sep: string;
+    /** Truncation marker. */
+    ellipsis: string;
+    /** Subagent activity marker. */
+    play: string;
+    /** Animated spinner frames (used only where cursor control exists). */
+    spinnerFrames: readonly string[];
+    /** Non-animated spinner glyph (no-cursor terminals). */
+    spinnerStatic: string;
+}
+/**
+ * The resolved design system handed to a surface. Color roles are stylers
+ * (identity under NO_COLOR); `glyph`/`sep` are concrete strings; the structure
+ * helpers give consistent indentation, headings, and key/value alignment.
+ */
+export interface Theme {
+    /** Errors, destructive risk, failure. (red) */
+    danger: Styler;
+    /** Reversible-mutation risk, warnings. (yellow) */
+    warning: Styler;
+    /** Done / ok. (green) */
+    success: Styler;
+    /** Brand / interactive / links / pointers. (cyan) */
+    accent: Styler;
+    /** Secondary text: hints, causes, codes, rationale. (dim) */
+    muted: Styler;
+    /** Emphasis / headings — a weight, hue-independent; composes with a color. (bold) */
+    strong: Styler;
+    /** Syntax-highlighting sub-palette. */
+    syntax: ThemeSyntax;
+    /** Glyph vocabulary (unicode or ASCII per capabilities). */
+    glyph: ThemeGlyphs;
+    /** Bold heading (alias of {@link strong}, named for intent). */
+    heading: Styler;
+    /** Prefix every line with `2 * level` spaces. */
+    indent(text: string, level?: number): string;
+    /** Aligned `key  value` with a bold key (optionally padded to `keyWidth`). */
+    kv(key: string, value: string, keyWidth?: number): string;
+    /** The inline joiner, e.g. ` · ` (unicode) / ` - ` (ascii). */
+    sep: string;
+    readonly color: boolean;
+    readonly unicode: boolean;
+}
+/** The two axes a theme is resolved from — a structural subset of RenderCapabilities. */
+export interface ThemeCapabilities {
+    color: boolean;
+    unicode: boolean;
+}
+/** The unicode glyph table (real terminals). */
+export declare const UNICODE_GLYPHS: ThemeGlyphs;
+/**
+ * The ASCII glyph table (TERM=dumb / CRUXY_ASCII). Readable, single-byte, no
+ * mojibake — the intentional U.1 degradation for unicode-unsafe terminals.
+ */
+export declare const ASCII_GLYPHS: ThemeGlyphs;

package/dist/theme/tokens.js

@@ -0,0 +1,52 @@
+/**
+ * The terminal design system (U.1): one typed {@link Theme} of semantic tokens
+ * — color *roles* (never raw hues at call sites), a glyph set with ASCII
+ * fallbacks, and structure primitives. Every rendered surface resolves ONE
+ * theme (from {@link RenderCapabilities}) and references roles like
+ * `theme.danger(x)` / `theme.glyph.success`, so the CLI reads as one product
+ * and NO_COLOR / dumb-terminal degradation is handled in exactly one place.
+ *
+ * Picocolors is imported only by `resolve.ts`; this file is pure types + the
+ * two glyph tables.
+ */
+/** The unicode glyph table (real terminals). */
+export const UNICODE_GLYPHS = {
+    success: "✓",
+    failure: "✗",
+    pending: "○",
+    running: "◐",
+    pointer: "❯",
+    caret: "›",
+    arrow: "→",
+    caretUp: "↑",
+    caretDown: "↓",
+    cursorBar: "▏",
+    bullet: "•",
+    sep: "·",
+    ellipsis: "…",
+    play: "⏵",
+    spinnerFrames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    spinnerStatic: "◐",
+};
+/**
+ * The ASCII glyph table (TERM=dumb / CRUXY_ASCII). Readable, single-byte, no
+ * mojibake — the intentional U.1 degradation for unicode-unsafe terminals.
+ */
+export const ASCII_GLYPHS = {
+    success: "[ok]",
+    failure: "[x]",
+    pending: "[ ]",
+    running: "~",
+    pointer: ">",
+    caret: ">",
+    arrow: "->",
+    caretUp: "^",
+    caretDown: "v",
+    cursorBar: "|",
+    bullet: "*",
+    sep: "-",
+    ellipsis: "...",
+    play: ">",
+    spinnerFrames: ["-", "\\", "|", "/"],
+    spinnerStatic: "~",
+};

package/dist/tools/registry.js

@@ -3,6 +3,7 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
+import { makeRunTestsTool } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
@@ -63,6 +64,8 @@ export function buildDefaultRegistry() {
     registry.register(grepFilesTool);
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
+    // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
+    registry.register(makeRunTestsTool());
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);

package/dist/tools/types.d.ts

@@ -101,10 +101,10 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback" | "test";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
-    /** The command to run (shell). */
+    /** The command to run (shell / test). */
     command?: string;
     /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;

package/dist/utils/logger.d.ts

@@ -2,6 +2,8 @@ export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error", "si
 export type LogLevel = (typeof LOG_LEVELS)[number];
 declare class Logger {
     private level;
+    /** Diagnostics go to stderr, so the theme resolves against stderr's color. */
+    private readonly theme;
     setLevel(level: LogLevel): void;
     getLevel(): LogLevel;
     private enabled;

package/dist/utils/logger.js

@@ -1,4 +1,5 @@
-import pc from "picocolors";
+import { shouldUseColor } from "../errors/format.js";
+import { themeForColor } from "../theme/index.js";
 export const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
 const WEIGHT = {
     debug: 10,
@@ -9,6 +10,8 @@ const WEIGHT = {
 };
 class Logger {
     level = "info";
+    /** Diagnostics go to stderr, so the theme resolves against stderr's color. */
+    theme = themeForColor(shouldUseColor(process.stderr));
     setLevel(level) {
         this.level = level;
     }
@@ -20,7 +23,7 @@ class Logger {
     }
     debug(...args) {
         if (this.enabled("debug"))
-            console.error(pc.dim("debug"), ...args);
+            console.error(this.theme.muted("debug"), ...args);
     }
     info(...args) {
         if (this.enabled("info"))
@@ -28,11 +31,11 @@ class Logger {
     }
     warn(...args) {
         if (this.enabled("warn"))
-            console.error(pc.yellow("warn"), ...args);
+            console.error(this.theme.warning("warn"), ...args);
     }
     error(...args) {
         if (this.enabled("error"))
-            console.error(pc.red("error"), ...args);
+            console.error(this.theme.danger("error"), ...args);
     }
     /** Primary user-facing output — always written to stdout. */
     print(...args) {

package/package.json

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