@cruxy/cli 0.14.0 → 0.16.0

package/dist/hooks/trust.d.ts

@@ -0,0 +1,46 @@
+import type { HookDefinition, HookTrust } from "./types.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export declare function trustPath(): string;
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export declare function fingerprintHooks(hooks: readonly HookDefinition[]): string;
+/** The persisted trust seam — a file-backed store in production, injectable for
+ * tests. `get`/`record` are synchronous (the record is tiny). */
+export interface TrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): HookTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: HookTrust): void;
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export declare function isTrusted(store: TrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export declare function fileTrustStore(file?: string): TrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryTrustStore(seed?: HookTrust[]): TrustStore;

package/dist/hooks/trust.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export function trustPath() {
+    return path.join(globalDir(), TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export function fingerprintHooks(hooks) {
+    const canonical = hooks
+        .map((h) => ({
+        name: h.name,
+        event: h.event,
+        command: h.command.trim().replace(/\s+/g, " "),
+        blocking: h.blocking,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        // Fixed key order — JSON of an object literal preserves insertion order.
+        .map((h) => [h.name, h.event, h.command, h.blocking]);
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export function isTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export function fileTrustStore(file = trustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object"
+                    ? raw
+                    : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export declare const HOOK_EVENTS: readonly ["before-run", "after-run", "before-tool", "after-tool", "on-file-change"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export declare function defaultBlocking(event: HookEvent): boolean;
+/** Where a hook / command was discovered. `project` is the supply-chain-risky
+ * source (another author); `user` is your own `~/.cruxy`. */
+export type HookSource = "project" | "user";
+/** Precedence: a project definition overrides a user one of the same name. */
+export declare const HOOK_SOURCE_PRECEDENCE: readonly HookSource[];
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export declare const HookSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+    command: z.ZodString;
+    blocking: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}>;
+export type HookSpec = z.infer<typeof HookSpecSchema>;
+/** The whole `hooks.json` file shape. */
+export declare const HooksFileSchema: z.ZodObject<{
+    hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+        command: z.ZodString;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    hooks: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[];
+}, {
+    hooks?: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[] | undefined;
+}>;
+/** A validated hook, tagged with its source and with `blocking` resolved. */
+export interface HookDefinition {
+    name: string;
+    event: HookEvent;
+    command: string;
+    /** Resolved (event default applied) — the value the runner acts on. */
+    blocking: boolean;
+    source: HookSource;
+}
+/**
+ * A custom slash command. `prompt` (the safe default) expands a text template
+ * fed to the agent; `shell` binds a command that runs through the SAME gate +
+ * sandbox as everything else. Never arbitrary code by default.
+ */
+export type SlashKind = "prompt" | "shell";
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export declare const SlashFrontmatterSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["prompt", "shell"]>>;
+    description: z.ZodString;
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "shell" | "prompt";
+    description: string;
+    command?: string | undefined;
+}, {
+    description: string;
+    command?: string | undefined;
+    kind?: "shell" | "prompt" | undefined;
+}>;
+export type SlashFrontmatter = z.infer<typeof SlashFrontmatterSchema>;
+/** A validated custom slash command, tagged with source. */
+export interface SlashCommandSpec {
+    name: string;
+    kind: SlashKind;
+    description: string;
+    /** Prompt template (kind `prompt`); `{{args}}` is substituted at expansion. */
+    template?: string;
+    /** Shell command (kind `shell`) — gated + sandboxed when run. */
+    command?: string;
+    source: HookSource;
+}
+/** A malformed hook / command, excluded from the catalog and surfaced loudly
+ * (never eval'd, never silently dropped). */
+export interface HookConfigError {
+    source: HookSource;
+    /** Absolute path of the offending file. */
+    file: string;
+    /** The would-be name (filename / spec name), for display. */
+    name: string;
+    message: string;
+}
+/** The resolved hook catalog: valid definitions (deduped by precedence) + the
+ * malformed ones that were excluded. */
+export interface HookCatalog {
+    hooks: HookDefinition[];
+    commands: SlashCommandSpec[];
+    errors: HookConfigError[];
+}
+/** One repo's recorded trust decision (persisted in `~/.cruxy/trust.json`). The
+ * `fingerprint` binds trust to the exact hook commands seen at trust time. */
+export interface HookTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized project hook specs (see `trust.ts`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}

package/dist/hooks/types.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+// ── lifecycle events ──────────────────────────────────────────────────────────
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export const HOOK_EVENTS = [
+    "before-run",
+    "after-run",
+    "before-tool",
+    "after-tool",
+    "on-file-change",
+];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export function defaultBlocking(event) {
+    return event === "before-run" || event === "before-tool";
+}
+/** Precedence: a project definition overrides a user one of the same name. */
+export const HOOK_SOURCE_PRECEDENCE = [
+    "project",
+    "user",
+];
+// ── hook specs ────────────────────────────────────────────────────────────────
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export const HookSpecSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "hook name must be kebab-case (lowercase letters, digits, hyphens)"),
+    event: z.enum(HOOK_EVENTS),
+    command: z.string().min(1, "hook command must be a non-empty string"),
+    blocking: z.boolean().optional(),
+})
+    .strict();
+/** The whole `hooks.json` file shape. */
+export const HooksFileSchema = z
+    .object({ hooks: z.array(HookSpecSchema).default([]) })
+    .strict();
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export const SlashFrontmatterSchema = z
+    .object({
+    kind: z.enum(["prompt", "shell"]).default("prompt"),
+    description: z.string().min(1),
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.string().min(1).optional(),
+})
+    .strict();

package/dist/onboarding/steps.js

@@ -17,7 +17,7 @@ const c = (io) => themeForColor(io.color);
  */
 export async function acquireKeyStep(io, deps, provider) {
     const col = c(io);
-    io.write(`\nYou'll need a Cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
+    io.write(`\nYou'll need a cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
     for (let attempt = 1; attempt <= MAX_KEY_ATTEMPTS; attempt++) {
         io.write(col.strong("Paste your API key: "));
         const key = (await io.readSecret()).trim();

package/dist/tools/shell/exec.d.ts

@@ -0,0 +1,53 @@
+import type { ToolContext } from "../types.js";
+/**
+ * The ONE gated + sandboxed shell path (C.16 + C.19). Both `run_command` and the
+ * C.19 hook runner funnel through {@link runGatedShell}: a command reaches
+ * execution only after passing the SAME `ctx.requestApproval` gate and only
+ * through the SAME `ctx.sandbox` (or host) substrate. There is deliberately no
+ * second exec route, so a hook can never get a privileged path — proven by the
+ * fact that both callers invoke this exact function.
+ *
+ * The structured {@link ShellExecResult} carries the raw exit code (which
+ * `run_command`'s text `ToolResult` hides) so the hook runner can decide
+ * blocking pass/fail on exit 0 vs non-zero, while `run_command` maps the same
+ * result back to its byte-identical `ToolResult`.
+ */
+/** The raw outcome of executing a shell command (gate already passed). */
+export interface ShellExecResult {
+    /** The wall-clock timeout tripped and the process tree was killed. */
+    timedOut: boolean;
+    /** Numeric exit code, or null when killed / signalled / unknown. */
+    exitCode: number | null;
+    /** Terminating signal (host path only); null under the sandbox. */
+    signal: string | null;
+    /** Combined stdout+stderr, capped to `shell.maxOutputBytes`. */
+    output: string;
+    /** Output was truncated at the cap. */
+    truncated: boolean;
+    /** The host process failed to *start* (spawn error). Sandbox start failures
+     * throw a coded error instead (propagated, never returned here). */
+    spawnError?: string;
+}
+/** The result of the gate + (if allowed) execution. */
+export interface GatedShellOutcome {
+    /** The U.3 gate allowed the command. When false, nothing executed. */
+    approved: boolean;
+    /** The rejection feedback when `approved` is false. */
+    rejection?: string;
+    /** The execution result — present iff `approved`. */
+    exec?: ShellExecResult;
+}
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export declare function runGatedShell(command: string, ctx: ToolContext): Promise<GatedShellOutcome>;
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export declare function execShell(command: string, ctx: ToolContext): Promise<ShellExecResult>;

package/dist/tools/shell/exec.js

@@ -0,0 +1,128 @@
+import { spawn } from "node:child_process";
+/**
+ * Gate `command` through `ctx.requestApproval`, then — only if allowed — execute
+ * it via the sandbox (when `ctx.sandbox` is set) or the bounded host spawn. A
+ * rejection returns `{ approved: false }` and runs nothing. A non-interactive
+ * gate throws `CRUXY_E_APPROVAL_REQUIRED` (propagated, never swallowed); a
+ * sandbox that can't run throws its coded error (fail loud, no host fallback).
+ */
+export async function runGatedShell(command, ctx) {
+    const decision = await ctx.requestApproval({ kind: "shell", command });
+    if (!decision.allow) {
+        return { approved: false, rejection: decision.feedback };
+    }
+    return { approved: true, exec: await execShell(command, ctx) };
+}
+/**
+ * Execute an already-approved command. Substrate is chosen SOLELY by
+ * `ctx.sandbox`: present → the container (C.16), never the host; absent → the
+ * bounded host spawn. No fallback path — a sandbox that can't run throws.
+ */
+export function execShell(command, ctx) {
+    return ctx.sandbox ? runSandboxed(command, ctx) : runBounded(command, ctx);
+}
+/** Run in the sandbox and normalize its neutral ExecResult (start failures
+ * throw coded errors from `sandbox.exec` and propagate — never caught here). */
+async function runSandboxed(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    const result = await ctx.sandbox.exec(command, {
+        cwd: ctx.cwd,
+        timeoutMs,
+        maxOutputBytes,
+        capture: "head",
+    });
+    return {
+        timedOut: result.timedOut,
+        exitCode: result.exitCode,
+        signal: null,
+        output: result.output,
+        truncated: result.outputTruncated,
+    };
+}
+/** Spawn the command on the host, capture bounded output, enforce the timeout. */
+function runBounded(command, ctx) {
+    const { timeoutMs, maxOutputBytes } = ctx.config.shell;
+    return new Promise((resolve) => {
+        // `detached` makes the child its own process-group leader so the whole tree
+        // (the shell plus anything it spawns) can be killed on timeout.
+        const child = spawn(command, { shell: true, cwd: ctx.cwd, detached: true });
+        const chunks = [];
+        let captured = 0;
+        let truncated = false;
+        const capture = (buf) => {
+            if (truncated)
+                return;
+            const room = maxOutputBytes - captured;
+            if (buf.length <= room) {
+                chunks.push(buf);
+                captured += buf.length;
+            }
+            else {
+                if (room > 0) {
+                    chunks.push(buf.subarray(0, room));
+                    captured += room;
+                }
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        // A single guard so the timeout-kill and the natural close can't both fire.
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            killTree(child.pid);
+            resolve({
+                timedOut: true,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated,
+            });
+        }, timeoutMs);
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: null,
+                signal: null,
+                output: "",
+                truncated: false,
+                spawnError: err.message,
+            });
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                exitCode: code,
+                signal: signal ?? null,
+                output: Buffer.concat(chunks).toString("utf8"),
+                truncated,
+            });
+        });
+    });
+}
+/**
+ * Kill the command's entire process group. POSIX-specific (negative pid targets
+ * the group); fine on our darwin/linux targets. Swallows errors — the process
+ * may already be gone.
+ */
+function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or no group — nothing to kill.
+    }
+}

package/dist/tools/shell/run-command.d.ts

@@ -4,6 +4,10 @@ import type { Tool } from "../types.js";
  * Run an arbitrary shell command in the project root. The highest-risk tool we
  * ship: it is gated on `ctx.approve` (a denial runs nothing) and bounded by a
  * timeout that kills the whole process tree plus a cap on captured output.
+ *
+ * Gate + execution live in the shared {@link runGatedShell} (also used by the
+ * C.19 hook runner — the single, un-bypassable shell path); this tool only maps
+ * the structured result back onto its `ToolResult` framing.
  */
 export declare const runCommandTool: Tool<z.ZodObject<{
     command: z.ZodString;