@cruxy/cli 1.4.0 → 1.6.0

package/dist/checkpoint/run-rollback.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { CheckpointService } from "./service.js";
+import { listSets } from "./set.js";
+import { applySet, buildSetPreview, setIsNoop, validateSet, } from "./set-rollback.js";
+/**
+ * Restore every touched root of one run's {@link CheckpointSet} as a single gated
+ * operation (C.26): validate-all up front, ONE combined preview behind ONE
+ * approval, then a sequential apply that stops and reports on first failure.
+ */
+export async function rollbackSet(set, deps) {
+    const { report } = deps;
+    const t = report.theme;
+    // Validate-all BEFORE any apply — a missing/corrupt member throws here.
+    const members = await validateSet(set, deps.config);
+    if (setIsNoop(members)) {
+        report.print(t.muted(`working tree already matches run ${set.runId} — nothing to roll back`));
+        return { kind: "noop" };
+    }
+    const decision = await deps.requestApproval({
+        kind: "rollback",
+        preview: buildSetPreview(set, members),
+    });
+    if (!decision.allow) {
+        report.print(t.muted("rollback declined — nothing was changed"));
+        return { kind: "declined" };
+    }
+    const applied = await applySet(set, members);
+    const parts = applied.restored.map((name) => {
+        const counts = applied.perRoot[name];
+        return `${name} (${counts.reverted} reverted, ${counts.recreated} recreated, ${counts.deleted} deleted)`;
+    });
+    report.print(`${t.success(t.glyph.success)} restored run ${t.accent(set.runId)} across ` +
+        `${applied.restored.length} root${applied.restored.length === 1 ? "" : "s"} — ${parts.join("; ")}`);
+    printCaveat(report);
+    return { kind: "applied", roots: applied.restored.length };
+}
+/**
+ * Single-root rollback (C.32): restore ONE root to one checkpoint. Reached for an
+ * explicit checkpoint id (the per-member escape hatch — including when the
+ * primary root was removed mid-session and its set index is gone, ⚖︎#7) and as
+ * the JC-F back-compat fallback for a run that predates set manifests.
+ *
+ * `id` omitted → the newest checkpoint for that root.
+ */
+export async function rollbackCheckpoint(root, id, deps) {
+    const { report } = deps;
+    const t = report.theme;
+    const service = new CheckpointService({ root, config: deps.config });
+    const result = await service.rollback(id, {
+        requestApproval: deps.requestApproval,
+        interactive: deps.interactive,
+    });
+    if (result.kind === "noop") {
+        report.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        return { kind: "noop" };
+    }
+    if (result.kind === "rejected") {
+        report.print(t.muted("rollback declined — nothing was changed"));
+        return { kind: "declined" };
+    }
+    const { recreated, reverted, deleted } = result.applied;
+    report.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
+        `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+    printCaveat(report);
+    return { kind: "applied", roots: 1 };
+}
+/**
+ * Roll back the MOST RECENT run under `primaryRoot`, with no picker and no id to
+ * supply — the shape `/undo-last` needs, and the shape `cruxy rollback` already
+ * had for its no-argument case once its picker declines to appear.
+ *
+ * Prefers the set manifest, which is the only record that knows how many roots a
+ * run touched; falls back to the newest single-root checkpoint (logged through
+ * the reporter, never silently) for a run that predates set manifests.
+ *
+ * Returns `null` when there is nothing recorded at all — a fact the caller
+ * phrases, because "no checkpoints yet" means something different at a shell
+ * prompt than it does three turns into a session.
+ */
+export async function rollbackLatestRun(primaryRoot, deps) {
+    const sets = await listSets(primaryRoot); // newest first
+    if (sets.length > 0)
+        return rollbackSet(sets[0], deps);
+    const service = new CheckpointService({
+        root: primaryRoot,
+        config: deps.config,
+    });
+    if ((await service.list()).length === 0)
+        return null;
+    deps.report.print(deps.report.theme.muted(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`));
+    return rollbackCheckpoint(primaryRoot, undefined, deps);
+}
+/**
+ * The one thing a successful rollback must always say. A user who has just
+ * watched a run be undone will reasonably assume it was undone; the parts that
+ * left the working tree were never in the checkpoint to begin with.
+ */
+function printCaveat(report) {
+    report.print(report.theme.muted("note: commits, pushes, and PRs made during the run are not undone"));
+}

package/dist/cli/command-catalog.js

@@ -0,0 +1,144 @@
+/**
+ * The catalogue of commands the shells dispatch themselves, and the reserved
+ * name set derived from it (P10 track 0).
+ *
+ * A LEAF MODULE, deliberately: it imports nothing. The reserved set has to be
+ * readable from two places that cannot see each other — `cli/session-commands.ts`,
+ * which dispatches these names, and `hooks/config.ts`, which loads the custom
+ * commands that must not collide with them. Leaving the catalogue in
+ * `session-commands.ts` and importing it from `hooks/` would close a cycle
+ * (`session-commands` → `hooks/index` → `hooks/slash` → `session-commands`) and
+ * put a module-scope `const` in its own TDZ. So the data lives here and both
+ * sides import down into it.
+ *
+ * WHY THIS EXISTS AT ALL: `hooks/slash.ts` used to carry its own hand-written
+ * list of seven "builtins", while `dispatchCommand` intercepted nineteen names
+ * and the TUI three more. The other fifteen were reserved in practice and
+ * reserved nowhere in code: a `.cruxy/commands/status.md` loaded cleanly, listed
+ * itself in `cruxy hooks list` and in the palette, and then never ran, because
+ * `/status` was handled several `if`s before the custom catalogue was consulted.
+ * No warning at load, none at use, and nothing on screen to connect the two.
+ * Deriving the set from the dispatchers instead of restating it is what stops
+ * that gap reopening the next time a command is added.
+ */
+/**
+ * The commands shared by both shells, in the order `/help` lists them.
+ *
+ * ONE catalogue, four consumers: the help text, Tab completion, the command
+ * palette, and now the reserved set. They used to be three hand-maintained
+ * lists — which is how the TUI ended up exporting a command list nothing
+ * consumed while advertising a help text that named commands it could not run.
+ */
+export const COMMAND_CATALOG = [
+    { name: "/help", summary: "show this help" },
+    {
+        name: "/clear",
+        summary: "clear the conversation history (keep the session)",
+    },
+    {
+        name: "/compact",
+        summary: "summarize older history to free up context now",
+    },
+    { name: "/init", summary: "scaffold a project CRUXY.md and load it" },
+    { name: "/reload", summary: "re-read project instructions (CRUXY.md)" },
+    { name: "/status", summary: "show what this session is set up to do" },
+    {
+        name: "/diff",
+        summary: "show uncommitted changes in the workspace",
+        args: "[ref | --since <checkpoint>]",
+    },
+    {
+        name: "/undo-last",
+        summary: "roll back the most recent checkpointed set of file changes",
+    },
+    {
+        name: "/redact",
+        summary: "mask secrets in this conversation so the model stops seeing them",
+    },
+    {
+        name: "/export",
+        summary: "write this conversation to a markdown file",
+        args: "[path]",
+    },
+    {
+        name: "/plan",
+        summary: "toggle plan mode (propose a plan before executing)",
+    },
+    {
+        name: "/mode",
+        summary: "show or set the session mode",
+        args: "[manual | auto-approve | plan | full-auto]",
+    },
+    {
+        name: "/model",
+        summary: "show or set the model for this session",
+        args: "[auto | kavi | vaani | mira]",
+    },
+    {
+        name: "/context",
+        summary: "show where the context budget is going, and what compaction would drop",
+    },
+    {
+        name: "/usage",
+        summary: "show token usage, weighted tokens and cost",
+        args: "[all | last <n>]",
+    },
+    {
+        name: "/budget",
+        summary: "show or set this session's weighted-token budget",
+        args: "[<n> | off]",
+    },
+    { name: "/jobs", summary: "list background jobs and their status" },
+    { name: "/logs", summary: "show a background job's log", args: "<id>" },
+    { name: "/cancel", summary: "cancel a background job", args: "<id>" },
+    {
+        name: "/add-root",
+        summary: "declare another workspace root",
+        args: "<name> <path>",
+    },
+    { name: "/exit", summary: "leave cruxy" },
+    { name: "/quit", summary: "leave cruxy" },
+];
+/**
+ * The three the TUI dispatches before the shared set, and the REPL has no
+ * meaning for. They live HERE rather than in `tui/app.ts` so there is one
+ * reserved set rather than two — a custom `/view` that worked in the REPL and
+ * was inert in the TUI is exactly the split this file exists to prevent, and
+ * the default shell is the one where it would be inert.
+ */
+export const TUI_ONLY_COMMANDS = [
+    {
+        name: "/close",
+        summary: "hide a panel or the whole rail",
+        args: "<sidebar | context | model | git | tools | rail>",
+    },
+    {
+        name: "/open",
+        summary: "show a hidden panel",
+        args: "<sidebar | context | model | git | tools | rail>",
+    },
+    {
+        name: "/view",
+        summary: "show a main-pane view, or list them",
+        args: "[name]",
+    },
+];
+/**
+ * Every name a shell dispatches itself, without its leading slash — sorted, so
+ * it reads as a list rather than as dispatch order.
+ *
+ * A custom command may not take any of these: it would load, list, and then
+ * never run. The loader rejects the collision by name (see `hooks/config.ts`),
+ * which is the only place a user finds out early enough to rename the file.
+ */
+export const RESERVED_SLASH_NAMES = [
+    ...COMMAND_CATALOG,
+    ...TUI_ONLY_COMMANDS,
+]
+    .map((c) => c.name.slice(1))
+    .sort();
+const RESERVED = new Set(RESERVED_SLASH_NAMES);
+/** Is `name` (no leading slash) dispatched by a shell, and so unavailable? */
+export function isReservedSlash(name) {
+    return RESERVED.has(name);
+}

package/dist/cli/commands/hooks.js

@@ -76,7 +76,7 @@ function printCommands(commands, t) {
 function printErrors(errors, t) {
     if (errors.length === 0)
         return;
-    logger.print(`\n${t.danger(t.heading("malformed (excluded, never run):"))}`);
+    logger.print(`\n${t.danger(t.heading("excluded (never run):"))}`);
     for (const e of errors) {
         logger.print(`  ${t.muted(`[${e.source}]`)} ${t.strong(e.name)} — ${e.message}`);
     }

package/dist/cli/commands/rollback.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { Command } from "commander";
 import { themeForColor } from "../../theme/index.js";
 import { loadConfig } from "../../config/index.js";
-import { CheckpointService, applySet, buildSetPreview, listSets, setIsNoop, validateSet, } from "../../checkpoint/index.js";
+import { CheckpointService, listSets, rollbackCheckpoint, rollbackSet, } from "../../checkpoint/index.js";
 import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
 import { fuzzyFind, selectList } from "../../components/index.js";
 import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
@@ -42,14 +42,18 @@ async function pickCheckpoint(service) {
     return result.kind === "selected" ? result.value : null;
 }
 /**
- * Legacy single-root rollback (C.32): restore one root's checkpoint. Reached for
+ * Legacy single-root rollback (C.32) with this surface's picker in front of it:
  * an explicit `cruxy rollback <id>` (the per-member escape hatch — including when
- * the primary root was removed mid-session and its set index is gone, ⚖︎#7) and as
- * the JC-F back-compat fallback for a pre-set-manifest run.
+ * the primary root was removed mid-session and its set index is gone, ⚖︎#7), or
+ * the JC-F back-compat fallback for a pre-set-manifest run, where a command line
+ * that named nothing gets to choose.
+ *
+ * The rollback ITSELF is `rollbackCheckpoint` (P10 track 1) — shared with
+ * `/undo-last`. Only the picker is this command's.
  */
-async function legacyRollback(root, config, approval, interactive, id, t) {
-    const service = new CheckpointService({ root, config });
+async function pickAndRollback(root, id, deps, t) {
     if (id === undefined) {
+        const service = new CheckpointService({ root, config: deps.config });
         const picked = await pickCheckpoint(service);
         if (picked === null) {
             logger.print(t.muted("rollback cancelled — nothing was changed"));
@@ -57,53 +61,7 @@ async function legacyRollback(root, config, approval, interactive, id, t) {
         }
         id = picked?.id;
     }
-    const result = await service.rollback(id, {
-        requestApproval: (action) => approval.requestApproval(action),
-        interactive,
-    });
-    if (result.kind === "noop") {
-        logger.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
-        return;
-    }
-    if (result.kind === "rejected") {
-        logger.print(t.muted("rollback declined — nothing was changed"));
-        return;
-    }
-    const { recreated, reverted, deleted } = result.applied;
-    logger.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
-        `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
-    logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
-}
-/**
- * Set-based rollback (C.26): restore every touched root of the latest run as one
- * gated operation. Validate-ALL members up front (missing/corrupt →
- * `CHECKPOINT_SET_INCOMPLETE`, nothing applied), one combined per-root preview and
- * one U.3 approval, then a sequential apply that stops on first failure
- * (`CHECKPOINT_SET_PARTIAL`, R3). Both coded errors propagate to the boundary.
- */
-async function setRollback(config, approval, t, set) {
-    // Validate-all BEFORE any apply — a missing/corrupt member throws here.
-    const members = await validateSet(set, config);
-    if (setIsNoop(members)) {
-        logger.print(t.muted(`working tree already matches run ${set.runId} — nothing to roll back`));
-        return;
-    }
-    const decision = await approval.requestApproval({
-        kind: "rollback",
-        preview: buildSetPreview(set, members),
-    });
-    if (!decision.allow) {
-        logger.print(t.muted("rollback declined — nothing was changed"));
-        return;
-    }
-    const applied = await applySet(set, members);
-    const parts = applied.restored.map((name) => {
-        const counts = applied.perRoot[name];
-        return `${name} (${counts.reverted} reverted, ${counts.recreated} recreated, ${counts.deleted} deleted)`;
-    });
-    logger.print(`${t.success(t.glyph.success)} restored run ${t.accent(set.runId)} across ` +
-        `${applied.restored.length} root${applied.restored.length === 1 ? "" : "s"} — ${parts.join("; ")}`);
-    logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+    await rollbackCheckpoint(root, id, deps);
 }
 /**
  * `cruxy rollback [id]` (C.32/C.26) — restore the working tree to a run's
@@ -139,6 +97,12 @@ export function rollbackCommand() {
             interactive,
             io: defaultPromptIO(shouldUseColor()),
         });
+        const deps = {
+            config,
+            requestApproval: (action) => approval.requestApproval(action),
+            interactive,
+            report: { print: (line) => logger.print(line), theme: t },
+        };
         const sets = await listSets(primaryRoot); // newest first
         if (id !== undefined) {
             // A job/run id first: if `<id>` names a set manifest (a background job's
@@ -146,19 +110,19 @@ export function rollbackCommand() {
             // it as a single checkpoint id (the per-member escape hatch).
             const jobSet = sets.find((s) => s.runId === id);
             if (jobSet) {
-                await setRollback(config, approval, t, jobSet);
+                await rollbackSet(jobSet, deps);
                 return;
             }
-            await legacyRollback(primaryRoot, config, approval, interactive, id, t);
+            await pickAndRollback(primaryRoot, id, deps, t);
             return;
         }
         // No set manifest → JC-F: fall back to legacy single-root, logged (never
         // silent). The primary root name matches single-root workspace naming.
         if (sets.length === 0) {
             logger.info(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`);
-            await legacyRollback(primaryRoot, config, approval, interactive, undefined, t);
+            await pickAndRollback(primaryRoot, undefined, deps, t);
             return;
         }
-        await setRollback(config, approval, t, sets[0]);
+        await rollbackSet(sets[0], deps);
     });
 }

package/dist/cli/commands/run.js

@@ -1,10 +1,12 @@
 import { Command } from "commander";
 import { randomUUID } from "node:crypto";
+import { LimitsClient } from "@cruxy/sdk";
+import { LimitsCache } from "../../limits/index.js";
 import { logger } from "../../utils/logger.js";
 import { SessionLog, listSessions, resumeById, resumePicker, shortId, } from "../../session/index.js";
 /** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
 const SIDEBAR_SESSIONS = 10;
-import { loadConfig, resolveApiKey } from "../../config/index.js";
+import { globalDir, loadConfig, resolveApiKey } from "../../config/index.js";
 import { agentIncomplete, authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
@@ -14,7 +16,7 @@ import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService, buildHooksRouter } from "../../hooks/index.js";
 import { DEFAULT_MODE, } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
-import { ContextGauge, createKeyLease, createGitView, createOverviewView, createSettingsView, createTasksView, runTui, TuiRenderer, WorkspaceGitCache, } from "../../tui/index.js";
+import { ContextGauge, createKeyLease, createGitView, createOverviewView, createSettingsView, createTasksView, runTui, TuiRenderer, WorkspaceDiskCache, WorkspaceGitCache, } from "../../tui/index.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
@@ -340,6 +342,28 @@ export async function executeRun(promptParts, opts) {
     // provider, where the constructor's static value stands and `/model` declines.
     if (session.model)
         tui?.attachModel(session.model);
+    // The limits rail panel (P9) — the account's headroom, read from the gateway
+    // that enforces it.
+    //
+    // ONLY ON THE CRUXY PROVIDER, and only with a key. `/limits` is a cruxy
+    // gateway endpoint; a bring-your-own-provider session has no such notion, and
+    // pointing this at someone else's base URL would be a request to a stranger.
+    // The cache is still attached without a key so the panel can say "not signed
+    // in" — a fact worth stating, and one that costs no request to establish.
+    const limitsKey = config.model.provider === "cruxy" ? apiKey : undefined;
+    const limits = new LimitsCache(limitsKey === undefined
+        ? undefined
+        : (signal) => new LimitsClient({
+            apiKey: limitsKey,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        }).read(signal));
+    tui?.attachLimits(limits);
+    // The SAME cache backs the session's weighted-token budget (P10 track 3), so
+    // the rail's headroom bar and `/budget`'s server line are one reading rather
+    // than two probes that can disagree — and so admission control at the fan-out
+    // seam bounds against the window the user can actually see. Attached even
+    // without a TUI: the REPL has no rail, but it has `/budget` and it fans out.
+    session.budget?.attachLimits(limits);
     // The main-pane views (P7). Registered here — the one place that has both the
     // renderer and the session — and after the session exists, because a view
     // reads its live state. Each root gets its own cached git probe: writes fan
@@ -350,8 +374,15 @@ export async function executeRun(promptParts, opts) {
         // a second instance would double the subprocesses to hold two copies of an
         // answer that must agree anyway.
         const workspaceGit = new WorkspaceGitCache(session.toolContext.workspace.roots().map((r) => r.absPath));
+        // Every root, plus `~/.cruxy` — the two kinds of place a run fills up. The
+        // home directory is the one nobody watches: checkpoints shadow-copy the
+        // tree once per run, and they accumulate there rather than in the repo.
+        const workspaceDisk = new WorkspaceDiskCache([
+            ...session.toolContext.workspace.roots().map((r) => r.absPath),
+            globalDir(),
+        ]);
         tui.attachViews([
-            createOverviewView(session, workspaceGit, () => tui.servedTier()),
+            createOverviewView(session, workspaceGit, () => tui.servedTier(), workspaceDisk),
             createGitView(() => session.toolContext.workspace.roots(), workspaceGit),
             // Registered even when background jobs are disabled — the view says so,
             // and a nav whose rows appear and vanish with config is worse than one

package/dist/cli/commands/test.js

@@ -1,7 +1,8 @@
 import { Command } from "commander";
-import pc from "picocolors";
 import { loadConfig } from "../../config/index.js";
-import { testCommandNotFound } from "../../errors/index.js";
+import { shouldUseColor, testCommandNotFound } from "../../errors/index.js";
+import { testResultLines } from "../../render/index.js";
+import { themeForColor } from "../../theme/index.js";
 import { CommandTestRunner, detectTestCommand } from "../../testing/index.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -10,38 +11,49 @@ import { logger } from "../../utils/logger.js";
  * user-invoked, so there is no approval gate (typing the command IS the
  * consent — same as running the suite by hand); the process exit code mirrors
  * the suite's pass/fail so scripts and CI can branch on it.
+ *
+ * The RESULT is rendered by `render/test-view.ts` (P11 track 2), the same
+ * formatter behind `StreamRenderer.testResult`, rather than by a picocolors
+ * path of its own. This command used to print `pc.green("✓")` directly, which
+ * made it the one surface in the CLI that reported a test run differently from
+ * every other — and, because the marks were literals rather than theme tokens,
+ * the one that still printed `✓`/`✗` under `CRUXY_ASCII` and read them out as
+ * bare punctuation to a screen reader. Routing through the shared view fixes
+ * both at once and means the honesty rules encoded there (never infer a passed
+ * count, never imply an empty failure list is exhaustive) apply here too.
  */
 export function testCommand() {
     return new Command("test")
         .description("run the project's test suite once and show the parsed result")
         .action(async () => {
+        const t = themeForColor(shouldUseColor(process.stdout));
         const { config } = loadConfig();
         const cwd = process.cwd();
         const detected = detectTestCommand(cwd, config);
         if (detected === null)
             throw testCommandNotFound();
-        logger.print(pc.dim(`running: ${detected.command}  [${detected.source}]`));
+        logger.print(t.muted(`running: ${detected.command}  [${detected.source}]`));
         const result = await new CommandTestRunner().run(detected.command, {
             cwd,
             timeoutMs: config.shell.timeoutMs,
             captureBytes: config.test.captureBytes,
             shell: config.shell,
         });
-        const seconds = (result.durationMs / 1000).toFixed(1);
-        if (result.passed) {
-            logger.print(`${pc.green("✓")} tests passed${result.total !== undefined ? ` (${result.total})` : ""} in ${seconds}s`);
-            return;
-        }
-        logger.print(`${pc.red("✗")} tests failed (exit ${result.exitCode ?? "signal"}) in ${seconds}s`);
-        for (const failure of result.failures) {
-            const where = failure.file !== undefined
-                ? pc.dim(`  ${failure.file}${failure.line !== undefined ? `:${failure.line}` : ""}`)
-                : "";
-            logger.print(`  ${pc.red("✗")} ${failure.name}${where}`);
+        // The runner's result IS a TestReport plus execution detail (`exitCode`,
+        // the captured `output`) the view has no use for; the command supplies the
+        // one field the runner does not carry, which is what it ran.
+        for (const line of testResultLines({ ...result, command: detected.command }, t)) {
+            logger.print(line);
         }
+        if (result.passed)
+            return;
+        // Nothing parseable — show the honest tail beneath the view's own "no
+        // individual failures were recognized" line. The view says WHAT is
+        // missing; a directly-invoked command can also afford to show the raw
+        // output it was missing from, which is the next thing the user would ask
+        // for and the reason to run `cruxy test` by hand rather than read a log.
         if (result.failures.length === 0) {
-            // Nothing parseable — show the honest tail instead of fake structure.
-            logger.print(pc.dim(result.output.trimEnd()));
+            logger.print(t.muted(result.output.trimEnd()));
         }
         process.exitCode = 1;
     });