@cruxy/cli 0.11.0 → 0.13.0

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/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/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.11.0",
+  "version": "0.13.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {