@cruxy/cli 0.10.0 → 0.12.0

package/dist/render/tty-renderer.js

@@ -1,13 +1,10 @@
-import pc from "picocolors";
+import { resolveTheme } from "../theme/index.js";
 import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
 import { createStreamHighlighter, } from "./highlight.js";
 import { composeStatusLine, ELAPSED_AFTER_MS, formatElapsed, phaseIdentity, } from "./state.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
-/** Spinner frames (braille); a static glyph when animation is disabled. */
-const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-const STATIC_FRAME = "◐";
 const SPINNER_INTERVAL_MS = 100;
 /**
  * The interactive renderer: committed content is append-only; the one transient
@@ -37,7 +34,7 @@ const SPINNER_INTERVAL_MS = 100;
 export class TtyRenderer {
     caps;
     out;
-    colors;
+    theme;
     print;
     highlighter;
     wroteInSegment = false;
@@ -59,8 +56,8 @@ export class TtyRenderer {
     constructor(caps, out) {
         this.caps = caps;
         this.out = out;
-        this.colors = pc.createColors(caps.color);
-        this.highlighter = createStreamHighlighter(this.colors);
+        this.theme = resolveTheme(caps);
+        this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
     }
     newPrinter() {
@@ -115,7 +112,7 @@ export class TtyRenderer {
         const elapsed = this.phase !== null && this.caps.spinner
             ? Date.now() - this.phaseStartedAt
             : undefined;
-        return composeStatusLine(this.progressState, this.phase, elapsed);
+        return composeStatusLine(this.progressState, this.phase, elapsed, this.theme.glyph);
     }
     /** Redraw the live line from current state, or hide it when there is none. */
     refresh() {
@@ -138,16 +135,19 @@ export class TtyRenderer {
     }
     drawLine(text) {
         this.lineVisible = true;
+        const frames = this.theme.glyph.spinnerFrames;
         const glyph = this.caps.spinner
-            ? FRAMES[this.frame % FRAMES.length]
-            : STATIC_FRAME;
+            ? frames[this.frame % frames.length]
+            : this.theme.glyph.spinnerStatic;
         // Reserve glyph + space; truncate so the live line can never soft-wrap.
         const room = Math.max(1, this.caps.width - 2);
-        const line = text.length > room ? text.slice(0, Math.max(0, room - 1)) + "…" : text;
-        this.out.write(`${CLEAR_LINE}${this.colors.cyan(glyph)} ${this.colors.dim(line)}`);
+        const line = text.length > room
+            ? text.slice(0, Math.max(0, room - 1)) + this.theme.glyph.ellipsis
+            : text;
+        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${this.theme.muted(line)}`);
     }
     beginTurn() {
-        this.highlighter = createStreamHighlighter(this.colors);
+        this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
         this.wroteInSegment = false;
     }
@@ -169,13 +169,15 @@ export class TtyRenderer {
         if (this.closed)
             return;
         const room = Math.max(1, this.caps.width);
-        const line = text.length > room ? text.slice(0, room - 1) + "…" : text;
-        this.commit(this.colors.dim(line) + "\n");
+        const line = text.length > room
+            ? text.slice(0, room - 1) + this.theme.glyph.ellipsis
+            : text;
+        this.commit(this.theme.muted(line) + "\n");
     }
     preview(preview) {
         if (this.closed)
             return;
-        const block = renderActionPreview(preview, this.colors);
+        const block = renderActionPreview(preview, this.theme);
         if (block)
             this.commit(block + "\n");
     }
@@ -237,7 +239,8 @@ export class TtyRenderer {
         // honest even with CRUXY_NO_SPINNER; shown only once it means something.
         const elapsed = started === null ? 0 : Date.now() - started.at;
         const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
-        this.note(`${event.ok ? "✓" : "✗"} ${event.label}${suffix}`);
+        const mark = event.ok ? this.theme.glyph.success : this.theme.glyph.failure;
+        this.note(`${mark} ${event.label}${suffix}`);
     }
     promptResolved() {
         if (this.closed)

package/dist/render/types.d.ts

@@ -1,4 +1,5 @@
 import type { ActionPreview } from "../tools/types.js";
+import type { Theme } from "../theme/index.js";
 /**
  * The streaming render seam (U.2): the agent loop talks to a
  * {@link StreamRenderer}, never to raw stdout. Two implementations exist —
@@ -21,6 +22,9 @@ export interface RenderCapabilities {
     cursor: boolean;
     /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
     spinner: boolean;
+    /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
+     * independent of `color`. Drives the theme's glyph table, not its stylers. */
+    unicode: boolean;
     /** Terminal columns; 80 when unknown (non-TTY). */
     width: number;
 }
@@ -97,6 +101,9 @@ export type ToolLifecycleEvent = {
  */
 export interface StreamRenderer {
     readonly caps: RenderCapabilities;
+    /** The one resolved design system (U.1) — glyphs/roles for chrome a
+     * surface emits through this renderer (e.g. the subagent trail notes). */
+    readonly theme: Theme;
     /** Start a user turn: reset leading-newline trim and code-fence state. */
     beginTurn(): void;
     /**

package/dist/subagent/orchestrator.js

@@ -67,7 +67,9 @@ export class SubagentOrchestrator {
             },
         };
         const label = taskLabel(spec.task);
-        deps.renderer?.note(`⏵ subagent: ${label}`);
+        if (deps.renderer) {
+            deps.renderer.note(`${deps.renderer.theme.glyph.play} subagent: ${label}`);
+        }
         deps.renderer?.setPhase({ kind: "subagent", label });
         // The isolation seam: a brand-new history seeded with ONLY the task. The
         // parent's messages are never in scope here, and this array dies with the
@@ -96,7 +98,9 @@ export class SubagentOrchestrator {
                 deps.renderer?.setPhase(null);
                 throw err;
             }
-            deps.renderer?.note(`✗ subagent failed: ${label}`);
+            if (deps.renderer) {
+                deps.renderer.note(`${deps.renderer.theme.glyph.failure} subagent failed: ${label}`);
+            }
             deps.renderer?.setPhase(null);
             return {
                 status: "failed",
@@ -123,7 +127,9 @@ export class SubagentOrchestrator {
             usage: run.usage,
         };
         if (run.stop === "completed") {
-            this.deps.renderer?.note(`✓ subagent done: ${label}`);
+            const r = this.deps.renderer;
+            if (r)
+                r.note(`${r.theme.glyph.success} subagent done: ${label}`);
             return { status: "done", ...base };
         }
         // Both cap paths are the same outcome for the parent: a truncated, partial
@@ -132,7 +138,9 @@ export class SubagentOrchestrator {
         const reason = run.stop === "budget"
             ? (run.stopReason ?? "budget cap reached")
             : `agent.maxIterations ceiling reached (${this.deps.config.agent.maxIterations})`;
-        this.deps.renderer?.note(`✗ subagent stopped (budget): ${label}`);
+        const r = this.deps.renderer;
+        if (r)
+            r.note(`${r.theme.glyph.failure} subagent stopped (budget): ${label}`);
         return {
             status: "budget-exceeded",
             ...base,
@@ -195,12 +203,16 @@ function lastAssistantText(messages) {
  */
 class SubagentRenderer {
     caps;
+    theme;
     inner;
     label;
+    prefix;
     constructor(inner, label) {
         this.inner = inner;
         this.label = label;
         this.caps = inner.caps;
+        this.theme = inner.theme;
+        this.prefix = `subagent ${inner.theme.glyph.sep} `;
     }
     /** Turn framing belongs to the parent's turn — the child's is dropped. */
     beginTurn() { }
@@ -209,7 +221,7 @@ class SubagentRenderer {
     write() { }
     endSegment() { }
     note(text) {
-        this.inner.note(`subagent · ${text}`);
+        this.inner.note(`${this.prefix}${text}`);
     }
     preview(preview) {
         this.inner.preview(preview);
@@ -231,7 +243,10 @@ class SubagentRenderer {
     /** The plan executor owns the progress register (C.31) — never the child. */
     progress() { }
     toolLifecycle(event) {
-        this.inner.toolLifecycle({ ...event, label: `subagent · ${event.label}` });
+        this.inner.toolLifecycle({
+            ...event,
+            label: `${this.prefix}${event.label}`,
+        });
     }
     promptResolved() {
         this.inner.promptResolved();

package/dist/testing/detect.d.ts

@@ -0,0 +1,3 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { TestCommand } from "./types.js";
+export declare function detectTestCommand(cwd: string, config: CruxyConfig): TestCommand | null;

package/dist/testing/detect.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve the project's test command (C.13). Order: explicit `test.command`
+ * config, then package.json `scripts.test`. Returns `null` when neither
+ * yields one — cruxy NEVER invents a test command; the caller surfaces the
+ * coded not-configured error instead.
+ */
+/** npm's scaffold placeholder is an error message, not a test suite. */
+const NPM_PLACEHOLDER = /no test specified/i;
+export function detectTestCommand(cwd, config) {
+    if (config.test.command) {
+        return { command: config.test.command, source: "config" };
+    }
+    const script = readTestScript(cwd);
+    if (script === null)
+        return null;
+    return { command: `${packageManager(cwd)} test`, source: "package-json" };
+}
+/** The package.json `scripts.test` value, or null if absent/placeholder/unreadable. */
+function readTestScript(cwd) {
+    try {
+        const raw = readFileSync(path.join(cwd, "package.json"), "utf8");
+        const pkg = JSON.parse(raw);
+        const script = pkg.scripts?.test;
+        if (typeof script !== "string" || script.trim() === "")
+            return null;
+        if (NPM_PLACEHOLDER.test(script))
+            return null;
+        return script;
+    }
+    catch {
+        // No package.json / unparseable → not detected (never a crash).
+        return null;
+    }
+}
+/** Pick the package manager by lockfile; npm when nothing identifies one. */
+function packageManager(cwd) {
+    if (existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    return "npm";
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./detect.js";
+export * from "./runner.js";
+export * from "./parse.js";
+export * from "./run-tests-tool.js";

package/dist/testing/parse.d.ts

@@ -0,0 +1,33 @@
+import type { FailureParser, TestFailure } from "./types.js";
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export declare const parseVitest: FailureParser;
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export declare const parseJest: FailureParser;
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export declare const defaultParsers: readonly FailureParser[];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export declare function parseFailures(output: string): {
+    failures: TestFailure[];
+    total?: number;
+};

package/dist/testing/parse.js

@@ -0,0 +1,137 @@
+/**
+ * Best-effort failure extraction (C.13). Two conservative parsers ship —
+ * vitest-style and jest-style — behind the pluggable {@link FailureParser}
+ * seam. The contract: extract only what a pattern positively recognizes;
+ * when nothing matches, return NOTHING (the caller falls back to the raw
+ * tail). Parsers never decide pass/fail and never invent counts — `message`
+ * fields are verbatim runner output, not summaries we authored.
+ */
+/**
+ * Vitest: per-test failure lines (`FAIL src/x.test.ts > suite > name`, also
+ * `×`/`✗` markers) and the `Tests  2 failed | 570 passed (572)` summary.
+ * Plain file-level `FAIL <file>` lines are deliberately left to the jest
+ * parser, which owns the file+bullet association.
+ */
+export const parseVitest = (output) => {
+    const failures = [];
+    for (const line of output.split("\n")) {
+        const match = /^\s*(?:FAIL|✗|×)\s+(\S+)\s+>\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            failures.push({
+                name: match[2],
+                message: line.trim(),
+                file: match[1],
+            });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^\s*Tests\s+.*\((\d+)\)\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Jest: `FAIL <file>` headers with `● <name>` bullets underneath (the bullet's
+ * following indented lines are its message, verbatim), and the
+ * `Tests: …, N total` summary. A FAIL header with no bullets (e.g. a suite
+ * that failed to load) becomes one file-level failure.
+ */
+export const parseJest = (output) => {
+    const failures = [];
+    const lines = output.split("\n");
+    let currentFile;
+    const filesWithBullets = new Set();
+    const bareFiles = [];
+    for (let i = 0; i < lines.length; i++) {
+        const fail = /^\s*FAIL\s+(\S+)\s*$/.exec(lines[i]);
+        if (fail) {
+            currentFile = fail[1];
+            bareFiles.push(fail[1]);
+            continue;
+        }
+        const bullet = /^\s*●\s+(.+?)\s*$/.exec(lines[i]);
+        if (bullet) {
+            failures.push({
+                name: bullet[1],
+                message: bulletMessage(lines, i),
+                ...(currentFile ? { file: currentFile } : {}),
+            });
+            if (currentFile)
+                filesWithBullets.add(currentFile);
+        }
+    }
+    // A failed suite with no per-test bullets is still one honest failure.
+    for (const file of bareFiles) {
+        if (!filesWithBullets.has(file)) {
+            failures.push({ name: file, message: `FAIL ${file}`, file });
+        }
+    }
+    attachLines(failures, output);
+    const total = /^Tests:.*?(\d+)\s+total\s*$/m.exec(output);
+    return {
+        failures,
+        ...(total ? { total: Number(total[1]) } : {}),
+    };
+};
+/**
+ * Up to three non-blank lines under a jest bullet — its verbatim message.
+ * Jest separates the bullet from its detail with a blank line, so leading
+ * blanks are skipped; collection stops at the next blank, the next bullet,
+ * or the cap.
+ */
+function bulletMessage(lines, bulletIndex) {
+    const body = [];
+    for (let j = bulletIndex + 1; j < lines.length && body.length < 3; j++) {
+        const text = lines[j].trim();
+        if (text === "") {
+            if (body.length === 0)
+                continue; // the separator blank under the bullet
+            break;
+        }
+        if (/^\s*●\s+/.test(lines[j]))
+            break;
+        body.push(text);
+    }
+    return body.length > 0 ? body.join("\n") : lines[bulletIndex].trim();
+}
+/**
+ * Attach `line` to failures whose file appears in a `file:line:col` stack
+ * reference anywhere in the output (vitest `❯ file:39:5`, jest
+ * `at … (file:12:15)`). First reference per file wins; no reference → no line.
+ */
+function attachLines(failures, output) {
+    if (failures.length === 0)
+        return;
+    const firstLineFor = new Map();
+    for (const match of output.matchAll(/([^\s():]+):(\d+):\d+/g)) {
+        if (!firstLineFor.has(match[1])) {
+            firstLineFor.set(match[1], Number(match[2]));
+        }
+    }
+    for (const failure of failures) {
+        if (failure.file === undefined || failure.line !== undefined)
+            continue;
+        const line = firstLineFor.get(failure.file);
+        if (line !== undefined)
+            failure.line = line;
+    }
+}
+/** Parser order: most-specific first. The pluggable seam for new frameworks. */
+export const defaultParsers = [
+    parseVitest,
+    parseJest,
+];
+/**
+ * Run the parser chain; the first parser that recognizes anything wins.
+ * Nothing recognized → empty failures, no total — the raw tail is the result.
+ */
+export function parseFailures(output) {
+    for (const parser of defaultParsers) {
+        const result = parser(output);
+        if (result.failures.length > 0 || result.total !== undefined) {
+            return result;
+        }
+    }
+    return { failures: [] };
+}

package/dist/testing/run-tests-tool.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { Tool, ToolContext } from "../tools/types.js";
+import type { TestCommand, TestRunner } from "./types.js";
+/**
+ * The `run_tests` tool (C.13): execute the project's test suite and return a
+ * structured result the model can iterate on (edit → re-run → repeat). The
+ * iteration loop itself is the ordinary agent loop; this module contributes
+ * the two guarantees that make it trustworthy — honest green (exit-code-only)
+ * and a hard cap on consecutive failing runs.
+ */
+/**
+ * Counts consecutive FAILING test executions; a green run resets it. When the
+ * count reaches the cap, the next attempt is refused with the coded
+ * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
+ * resets — so the episode ends loudly, but a deliberate later attempt (a new
+ * user instruction) starts fresh rather than finding a permanently dead tool.
+ * Per-turn work stays bounded regardless via `agent.maxIterations`.
+ */
+export declare class TestIterationBudget {
+    private failedRuns;
+    /** Runs already spent in the current failing streak. */
+    get spent(): number;
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations: number): boolean;
+    record(passed: boolean): void;
+}
+declare const parameters: z.ZodObject<{
+    command: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    command?: string | undefined;
+}, {
+    command?: string | undefined;
+}>;
+export interface RunTestsToolDeps {
+    /** Execution seam (tests inject a fake; default spawns the real command). */
+    runner?: TestRunner;
+    /** Detection seam (defaults to config + package.json detection). */
+    detect?: (ctx: ToolContext) => TestCommand | null;
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export declare function makeRunTestsTool(deps?: RunTestsToolDeps): Tool<typeof parameters>;
+export {};

package/dist/testing/run-tests-tool.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { ErrorCode } from "../errors/index.js";
+import { detectTestCommand } from "./detect.js";
+import { CommandTestRunner } from "./runner.js";
+/**
+ * The `run_tests` tool (C.13): execute the project's test suite and return a
+ * structured result the model can iterate on (edit → re-run → repeat). The
+ * iteration loop itself is the ordinary agent loop; this module contributes
+ * the two guarantees that make it trustworthy — honest green (exit-code-only)
+ * and a hard cap on consecutive failing runs.
+ */
+/**
+ * Counts consecutive FAILING test executions; a green run resets it. When the
+ * count reaches the cap, the next attempt is refused with the coded
+ * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
+ * resets — so the episode ends loudly, but a deliberate later attempt (a new
+ * user instruction) starts fresh rather than finding a permanently dead tool.
+ * Per-turn work stays bounded regardless via `agent.maxIterations`.
+ */
+export class TestIterationBudget {
+    failedRuns = 0;
+    /** Runs already spent in the current failing streak. */
+    get spent() {
+        return this.failedRuns;
+    }
+    /** True when the next run must be refused; resets the streak as it trips. */
+    trip(maxIterations) {
+        if (this.failedRuns < maxIterations)
+            return false;
+        this.failedRuns = 0;
+        return true;
+    }
+    record(passed) {
+        this.failedRuns = passed ? 0 : this.failedRuns + 1;
+    }
+}
+const parameters = z.object({
+    command: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Override the detected test command (still requires approval). " +
+        "Omit to use the project's configured/detected command."),
+});
+/** The wire shape fed back to the model — structured, bounded, honest. */
+function renderResult(result, command, iteration) {
+    return JSON.stringify({
+        passed: result.passed,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        command: command.command,
+        ...(result.total !== undefined ? { total: result.total } : {}),
+        failures: result.failures,
+        iteration,
+        output: result.output,
+        outputTruncated: result.outputTruncated,
+    });
+}
+/** Build the `run_tests` tool. One instance = one session's iteration budget. */
+export function makeRunTestsTool(deps = {}) {
+    const runner = deps.runner ?? new CommandTestRunner();
+    const detect = deps.detect ??
+        ((ctx) => detectTestCommand(ctx.cwd, ctx.config));
+    const budget = new TestIterationBudget();
+    return {
+        name: "run_tests",
+        description: "Run the project's test suite and get a structured result: passed (from the exit code), " +
+            "extracted failures with file/line where recognizable, and the output tail. " +
+            "Use it to verify changes: run, read the failures, fix, re-run. The edit→re-run loop is " +
+            "capped — when the iteration limit trips, stop, summarize the remaining failures, and ask the user.",
+        parameters,
+        async execute(input, ctx) {
+            // Resolve the command first: detection failure needs no approval and
+            // must be a coded, actionable error — never an invented command.
+            let resolved;
+            if (input.command !== undefined) {
+                resolved = { command: input.command, source: "override" };
+            }
+            else {
+                const detected = detect(ctx);
+                if (detected === null)
+                    return { ok: false, error: NOT_FOUND };
+                resolved = detected;
+            }
+            // Iteration cap BEFORE the gate and the run: a refused attempt executes
+            // nothing and costs nothing.
+            const max = ctx.config.test.maxIterations;
+            if (budget.trip(max)) {
+                return {
+                    ok: false,
+                    error: `${ErrorCode.TestIterationLimit}: tests are still failing after ${max} run${max === 1 ? "" : "s"}. ` +
+                        "Stop iterating. Summarize the remaining failures and what you tried, then ask the user how to proceed.",
+                };
+            }
+            // U.3 gate (destructive tier, exact-command grant scope). A thrown
+            // CRUXY_E_APPROVAL_REQUIRED (non-interactive) propagates — do not catch.
+            const decision = await ctx.requestApproval({
+                kind: "test",
+                command: resolved.command,
+            });
+            if (!decision.allow) {
+                return {
+                    ok: false,
+                    error: decision.feedback ?? "test run denied by the user",
+                };
+            }
+            const result = await runner.run(resolved.command, {
+                cwd: ctx.cwd,
+                timeoutMs: ctx.config.shell.timeoutMs,
+                captureBytes: ctx.config.test.captureBytes,
+            });
+            budget.record(result.passed);
+            const payload = renderResult(result, resolved, {
+                run: result.passed ? 0 : budget.spent,
+                max,
+            });
+            // Failing tests are an is_error result so the U.4 trail note reads ✗ —
+            // the payload is identical either way; the model reasons over both.
+            return result.passed
+                ? { ok: true, output: payload }
+                : { ok: false, error: payload };
+        },
+    };
+}
+/** The coded not-configured message, actionable for model and user alike. */
+const NOT_FOUND = `${ErrorCode.TestCommandNotFound}: no test command found — package.json has no usable ` +
+    "`scripts.test` and `test.command` is not configured. Ask the user to set `test.command` " +
+    '(e.g. `cruxy config set test.command "pnpm test"`); do not guess a command.';

package/dist/testing/runner.d.ts

@@ -0,0 +1,26 @@
+import type { TestRunner, TestRunOptions, TestRunResult } from "./types.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 declare class CommandTestRunner implements TestRunner {
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}
+/**
+ * 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 declare class TailCapture {
+    private readonly cap;
+    private chunks;
+    private bytes;
+    truncated: boolean;
+    constructor(cap: number);
+    push(buf: Buffer): void;
+    text(): string;
+}