@cruxy/cli 0.12.0 → 0.13.0

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

@@ -32,7 +32,11 @@ declare const parameters: z.ZodObject<{
     command?: string | undefined;
 }>;
 export interface RunTestsToolDeps {
-    /** Execution seam (tests inject a fake; default spawns the real command). */
+    /**
+     * Execution seam (tests inject a fake). When unset, the runner is chosen per
+     * run from `ctx.sandbox`: present → {@link SandboxTestRunner} (run in the box,
+     * C.16), absent → host {@link CommandTestRunner} — unchanged.
+     */
     runner?: TestRunner;
     /** Detection seam (defaults to config + package.json detection). */
     detect?: (ctx: ToolContext) => TestCommand | null;

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { ErrorCode } from "../errors/index.js";
 import { detectTestCommand } from "./detect.js";
 import { CommandTestRunner } from "./runner.js";
+import { SandboxTestRunner } from "./sandbox-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
@@ -58,7 +59,6 @@ function renderResult(result, command, iteration) {
 }
 /** 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();
@@ -104,6 +104,13 @@ export function makeRunTestsTool(deps = {}) {
                     error: decision.feedback ?? "test run denied by the user",
                 };
             }
+            // Substrate chosen by ctx.sandbox (C.16): in the box when enabled, else
+            // host — identical result shape either way. An explicit deps.runner
+            // (tests) always wins. A sandbox that can't run throws (fail loud).
+            const runner = deps.runner ??
+                (ctx.sandbox
+                    ? new SandboxTestRunner(ctx.sandbox)
+                    : new CommandTestRunner());
             const result = await runner.run(resolved.command, {
                 cwd: ctx.cwd,
                 timeoutMs: ctx.config.shell.timeoutMs,

package/dist/testing/sandbox-runner.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxService } from "../sandbox/index.js";
+import type { TestRunner, TestRunOptions, TestRunResult } from "./types.js";
+/**
+ * A {@link TestRunner} that runs the suite inside the C.16 sandbox instead of
+ * on the host. It maps the neutral sandbox {@link ExecResult} onto the exact
+ * same {@link TestRunResult} the host {@link CommandTestRunner} produces — so
+ * honest-green (`passed = exitCode === 0`), tail-biased capture, and the
+ * timeout note all hold identically inside the box. A container-start failure
+ * is NOT swallowed into a result: `sandbox.exec` throws a coded error that
+ * propagates (fail loud), never a fabricated pass.
+ */
+export declare class SandboxTestRunner implements TestRunner {
+    private readonly sandbox;
+    constructor(sandbox: SandboxService);
+    run(command: string, opts: TestRunOptions): Promise<TestRunResult>;
+}

package/dist/testing/sandbox-runner.js

@@ -0,0 +1,47 @@
+import { parseFailures } from "./parse.js";
+/**
+ * A {@link TestRunner} that runs the suite inside the C.16 sandbox instead of
+ * on the host. It maps the neutral sandbox {@link ExecResult} onto the exact
+ * same {@link TestRunResult} the host {@link CommandTestRunner} produces — so
+ * honest-green (`passed = exitCode === 0`), tail-biased capture, and the
+ * timeout note all hold identically inside the box. A container-start failure
+ * is NOT swallowed into a result: `sandbox.exec` throws a coded error that
+ * propagates (fail loud), never a fabricated pass.
+ */
+export class SandboxTestRunner {
+    sandbox;
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+    }
+    async run(command, opts) {
+        const result = await this.sandbox.exec(command, {
+            cwd: opts.cwd,
+            timeoutMs: opts.timeoutMs,
+            maxOutputBytes: opts.captureBytes,
+            capture: "tail", // failures live at the end of test output
+        });
+        if (result.timedOut) {
+            return {
+                passed: false,
+                exitCode: null,
+                durationMs: result.durationMs,
+                failures: [],
+                output: result.output +
+                    `\n… [test run timed out after ${opts.timeoutMs}ms and was killed]`,
+                outputTruncated: result.outputTruncated,
+            };
+        }
+        // THE honest-green rule, unchanged by the substrate: exit 0 means passed.
+        const passed = result.exitCode === 0;
+        const parsed = passed ? { failures: [] } : parseFailures(result.output);
+        return {
+            passed,
+            exitCode: result.exitCode,
+            durationMs: result.durationMs,
+            ...(parsed.total !== undefined ? { total: parsed.total } : {}),
+            failures: parsed.failures,
+            output: result.output,
+            outputTruncated: result.outputTruncated,
+        };
+    }
+}

package/dist/tools/shell/run-command.js

@@ -26,9 +26,43 @@ export const runCommandTool = {
                 error: decision.feedback ?? "command denied by the user",
             };
         }
-        return runBounded(input.command, ctx);
+        // Substrate is chosen SOLELY by ctx.sandbox: present → run in the box (C.16),
+        // never on the host; absent → host, unchanged. There is no fallback path — a
+        // sandbox that can't run throws a coded error (see runSandboxed) rather than
+        // silently reaching runBounded.
+        return ctx.sandbox
+            ? runSandboxed(input.command, ctx)
+            : runBounded(input.command, ctx);
     },
 };
+/**
+ * Run inside the sandbox and map the neutral ExecResult onto the IDENTICAL
+ * ToolResult the host path produces — same "exit code N" framing, same
+ * truncation note, same timeout message — so the tool is substrate-agnostic.
+ * A container-start / image failure throws a coded CruxyError from
+ * `sandbox.exec` and propagates; we deliberately do not catch it (fail loud).
+ */
+function runSandboxed(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return ctx
+        .sandbox.exec(command, {
+        cwd: ctx.cwd,
+        timeoutMs,
+        maxOutputBytes,
+        capture: "head",
+    })
+        .then((result) => {
+        if (result.timedOut) {
+            return { ok: false, error: `timed out after ${timeoutMs}ms` };
+        }
+        const exit = result.exitCode ?? "unknown";
+        let output = `exit code ${exit}\n${result.output}`;
+        if (result.outputTruncated) {
+            output += `\n… [output truncated at ${maxOutputBytes} bytes]`;
+        }
+        return { ok: true, output };
+    });
+}
 /** Spawn the command, capture bounded output, and enforce the timeout. */
 function runBounded(command, ctx) {
     const { timeoutMs, maxOutputBytes } = ctx.config.shell;

package/dist/tools/types.d.ts

@@ -1,6 +1,7 @@
 import type { z, ZodTypeAny } from "zod";
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/types.js";
+import type { SandboxService } from "../sandbox/index.js";
 import type { logger } from "../utils/logger.js";
 /** The leveled logger instance shared across the CLI. */
 type Logger = typeof logger;
@@ -131,6 +132,15 @@ export interface ToolContext {
      * tools never call this.
      */
     requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    /**
+     * Isolation substrate for the shell + test tools (C.16). Present ONLY when
+     * the sandbox is enabled; when set, `run_command`/`run_tests` execute the
+     * approved command inside the container and NEVER on the host. Its mere
+     * presence is the switch — there is no host fallback once it is set (an
+     * unavailable runtime fails loud at construction, before this is ever
+     * populated). Absent → host execution, unchanged.
+     */
+    sandbox?: SandboxService;
 }
 /**
  * The one interface every tool implements. `parameters` is a zod schema; it both

package/package.json

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