@cruxy/cli 0.8.0 → 0.10.0

package/dist/checkpoint/shadow-store.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointFailed } from "../errors/index.js";
+/**
+ * Shadow-copy checkpoint content store (C.32 fallback substrate): used outside
+ * a git repo, or when git plumbing fails mid-snapshot. File contents live in a
+ * content-addressed pool at `.cruxy/checkpoints/objects/<sha256>` — identical
+ * content across files or checkpoints is stored once, and pruning sweeps
+ * objects no longer referenced by any surviving manifest.
+ *
+ * Writes are temp-file-then-rename so a crash can never leave a torn object; a
+ * torn *read* is impossible because an object either exists complete or not at
+ * all, and a missing object fails loudly.
+ */
+export class ShadowCheckpointStore {
+    kind = "shadow";
+    objectsDir;
+    constructor(root) {
+        this.objectsDir = path.join(root, ".cruxy", "checkpoints", "objects");
+    }
+    hashContent(content) {
+        return createHash("sha256").update(content).digest("hex");
+    }
+    async snapshot(files) {
+        await fsp.mkdir(this.objectsDir, { recursive: true });
+        const entries = [];
+        for (const file of files) {
+            let content;
+            let stat;
+            try {
+                stat = await fsp.lstat(file.absPath);
+                if (!stat.isFile())
+                    continue; // raced from regular file to something else
+                content = await fsp.readFile(file.absPath);
+            }
+            catch (err) {
+                throw checkpointFailed(`could not read ${file.path} for snapshot`, err);
+            }
+            const oid = this.hashContent(content);
+            await this.writeObject(oid, content);
+            entries.push({
+                path: file.path,
+                mode: stat.mode & 0o100 ? "100755" : "100644",
+                oid,
+            });
+        }
+        return entries;
+    }
+    async readContent(entry) {
+        try {
+            return await fsp.readFile(path.join(this.objectsDir, entry.oid));
+        }
+        catch (err) {
+            throw checkpointFailed(`checkpoint content for ${entry.path} is missing from .cruxy/checkpoints/objects (${entry.oid})`, err);
+        }
+    }
+    async collect(referenced) {
+        let names;
+        try {
+            names = await fsp.readdir(this.objectsDir);
+        }
+        catch {
+            return; // no pool yet — nothing to sweep
+        }
+        for (const name of names) {
+            if (referenced.has(name))
+                continue;
+            // Best-effort: a failed unlink just leaves an unreferenced object behind.
+            await fsp.rm(path.join(this.objectsDir, name), { force: true });
+        }
+    }
+    /** Content-addressed write: skip if present, else temp-then-rename (atomic). */
+    async writeObject(oid, content) {
+        const dest = path.join(this.objectsDir, oid);
+        try {
+            await fsp.access(dest);
+            return; // already stored — content-addressing dedupes for free
+        }
+        catch {
+            /* not present — write it */
+        }
+        const tmp = `${dest}.tmp-${process.pid}-${Date.now()}`;
+        try {
+            await fsp.writeFile(tmp, content);
+            await fsp.rename(tmp, dest);
+        }
+        catch (err) {
+            await fsp.rm(tmp, { force: true });
+            throw checkpointFailed(`could not store checkpoint object ${oid}`, err);
+        }
+    }
+}

package/dist/checkpoint/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Working-tree checkpoints (C.32): a complete snapshot of everything the agent
+ * could touch, captured before a run's first mutation, so `cruxy rollback` can
+ * undo the entire run — creates, edits, deletes — in one gated operation.
+ *
+ * Two layers, deliberately separated:
+ *   • {@link CheckpointStore} — the *content substrate* (where file bytes
+ *     live), swappable like VectorStore: git-object-backed in a repo, a
+ *     content-addressed shadow copy otherwise.
+ *   • The manifest — uniform JSON under `.cruxy/checkpoints/`, owned by the
+ *     service regardless of substrate, so list/prune/rollback never care which
+ *     store wrote a checkpoint.
+ *
+ * Explicit boundary: checkpoints cover WORKING-TREE file state only. They can
+ * never undo git commits, pushes, or PRs made during a run (C.15) — that is
+ * stated in the rollback preview, not silently implied.
+ */
+/** A file selected for capture: project-relative POSIX path + where it is on disk. */
+export interface CaptureFile {
+    path: string;
+    absPath: string;
+}
+/** Which content substrate a checkpoint was written with. */
+export type CheckpointStoreKind = "git" | "shadow";
+/**
+ * One captured file in a checkpoint manifest. `oid` is the content address in
+ * the store that wrote it: a git blob sha-1 for the git store, a sha-256 for
+ * the shadow store. `mode` preserves the executable bit across restore.
+ */
+export interface FileEntry {
+    path: string;
+    mode: "100644" | "100755";
+    oid: string;
+}
+/** A persisted checkpoint: identity, provenance, and the full pre-run manifest. */
+export interface Checkpoint {
+    /** Stable id, e.g. `ck-20260703T141530-a4f2`. */
+    id: string;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    /** One line describing the run this checkpoint protects. */
+    runSummary: string;
+    store: CheckpointStoreKind;
+    /** Every file that existed (and was capturable) before the run's first mutation. */
+    files: FileEntry[];
+    /**
+     * Project-relative paths the tracked run mutated through file tools, recorded
+     * as the run proceeds. At rollback time, a difference on a path NOT in this
+     * list is an *external* change — surfaced loudly in the preview.
+     */
+    touchedPaths: string[];
+    /**
+     * True when the run executed approved shell commands: a shell command can
+     * touch any path, so per-file attribution becomes impossible and the preview
+     * says so instead of guessing.
+     */
+    hasShellMutations: boolean;
+}
+/**
+ * The content substrate seam. Implementations persist and retrieve file
+ * *contents* only — manifests are the service's job.
+ *
+ * THE invariant (git store): snapshot/read must never disturb user-visible git
+ * state — HEAD, the index, the stash, or any ref. The git store self-checks
+ * this at runtime and fails loudly on drift.
+ */
+export interface CheckpointStore {
+    readonly kind: CheckpointStoreKind;
+    /** Persist the current contents of `files`; returns the manifest entries. */
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    /** The content address `snapshot` would give this buffer (for diffing). */
+    hashContent(content: Buffer): string;
+    /** Read one captured file's bytes back. Throws CRUXY_E_CHECKPOINT_FAILED if gone. */
+    readContent(entry: FileEntry): Promise<Buffer>;
+    /**
+     * Best-effort GC after prune: drop stored content whose oid is no longer
+     * referenced by any surviving manifest. The git store is a no-op (dangling
+     * objects belong to git's own gc); the shadow store sweeps its object pool.
+     */
+    collect(referenced: ReadonlySet<string>): Promise<void>;
+}
+/** What rollback will do to one path. */
+export type RollbackAction = 
+/** The run deleted it — recreate from the checkpoint. */
+"recreate"
+/** The run edited it — revert content (and mode) to the checkpoint. */
+ | "revert"
+/** The run created it — delete it. */
+ | "delete";
+export interface RollbackEntry {
+    path: string;
+    action: RollbackAction;
+    /**
+     * True when this path changed since the checkpoint but the tracked run never
+     * touched it — concurrent user (or other-tool) work that rollback would
+     * clobber. Always surfaced in the preview; never overwritten silently.
+     */
+    external: boolean;
+    /** Checkpoint-side content to restore (recreate/revert; absent for delete). */
+    entry?: FileEntry;
+}
+/** The computed diff between the current working tree and a checkpoint. */
+export interface RollbackPlan {
+    checkpoint: Checkpoint;
+    /** Sorted by path; empty means the tree already matches the checkpoint. */
+    entries: RollbackEntry[];
+    /** The `external: true` paths, for the preview's warning block. */
+    externalPaths: string[];
+    /** Mirrors {@link Checkpoint.hasShellMutations}: attribution is unknowable. */
+    attributionUnknown: boolean;
+}
+/** Counts of what a successful rollback actually did. */
+export interface RollbackApplied {
+    recreated: number;
+    reverted: number;
+    deleted: number;
+}

package/dist/checkpoint/types.js

@@ -0,0 +1,18 @@
+/**
+ * Working-tree checkpoints (C.32): a complete snapshot of everything the agent
+ * could touch, captured before a run's first mutation, so `cruxy rollback` can
+ * undo the entire run — creates, edits, deletes — in one gated operation.
+ *
+ * Two layers, deliberately separated:
+ *   • {@link CheckpointStore} — the *content substrate* (where file bytes
+ *     live), swappable like VectorStore: git-object-backed in a repo, a
+ *     content-addressed shadow copy otherwise.
+ *   • The manifest — uniform JSON under `.cruxy/checkpoints/`, owned by the
+ *     service regardless of substrate, so list/prune/rollback never care which
+ *     store wrote a checkpoint.
+ *
+ * Explicit boundary: checkpoints cover WORKING-TREE file state only. They can
+ * never undo git commits, pushes, or PRs made during a run (C.15) — that is
+ * stated in the rollback preview, not silently implied.
+ */
+export {};

package/dist/cli/commands/checkpoint.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy checkpoint` (C.32) — inspect the working-tree snapshots that back
+ * `cruxy rollback`. Creation is automatic (before a run's first mutation);
+ * this command only lists.
+ */
+export declare function checkpointCommand(): Command;

package/dist/cli/commands/checkpoint.js

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { CheckpointService } from "../../checkpoint/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy checkpoint` (C.32) — inspect the working-tree snapshots that back
+ * `cruxy rollback`. Creation is automatic (before a run's first mutation);
+ * this command only lists.
+ */
+export function checkpointCommand() {
+    const cmd = new Command("checkpoint").description("working-tree checkpoints — the undo units behind `cruxy rollback`");
+    cmd
+        .command("list")
+        .description("list saved checkpoints, newest first")
+        .action(async () => {
+        const { config } = loadConfig();
+        const service = new CheckpointService({ root: process.cwd(), config });
+        const checkpoints = await service.list();
+        if (checkpoints.length === 0) {
+            logger.print(pc.dim("no checkpoints yet — one is created automatically before an agent run's first file change"));
+            return;
+        }
+        for (const c of checkpoints) {
+            const files = `${c.files.length} file${c.files.length === 1 ? "" : "s"}`;
+            logger.print(`${pc.cyan(c.id)}  ${pc.dim(c.createdAt)}  ${pc.dim(`[${c.store}]`)}  ${files}  ${c.runSummary}`);
+        }
+        logger.print(pc.dim(`\nrestore one with \`cruxy rollback <id>\` (or \`cruxy rollback\` for the newest)`));
+    });
+    return cmd;
+}

package/dist/cli/commands/rollback.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/**
+ * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
+ * undoing everything an agent run changed (creates, edits, deletes) in one
+ * operation. Destructive by definition, so it is preview-first and gated
+ * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
+ * coded error before anything is computed. Out of scope, stated in the
+ * preview: commits, pushes, and PRs made during the run are not undone.
+ */
+export declare function rollbackCommand(): Command;

package/dist/cli/commands/rollback.js

@@ -0,0 +1,96 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { CheckpointService } 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";
+import { logger } from "../../utils/logger.js";
+/** One picker row: id, age, and what the run was about. */
+function checkpointLabel(c) {
+    return `${c.id}  ${c.createdAt}  ${c.runSummary}`;
+}
+/**
+ * Choose which checkpoint to restore when the user gave no id (U.7 dogfood).
+ * One checkpoint → it, no ceremony. A short list → arrow-key SelectList with
+ * the newest preselected, so Enter-once matches the old "defaults to the
+ * most recent" behavior. A long list → type-to-filter FuzzyFinder. Returns
+ * `null` on cancel (nothing restored) — cancellation is a result, not an
+ * error.
+ */
+async function pickCheckpoint(service) {
+    const checkpoints = await service.list(); // newest first
+    if (checkpoints.length === 0)
+        return undefined; // let rollback() fail loud
+    if (checkpoints.length === 1)
+        return checkpoints[0];
+    const common = {
+        title: "pick a checkpoint to roll back to (newest first)",
+        nonInteractiveHint: ["or pass the id directly: `cruxy rollback <id>`"],
+        // Non-TTY can't reach here (refused above), but the components' own
+        // fallback still names the flag if that ever changes.
+        defaultValue: checkpoints[0],
+    };
+    const result = checkpoints.length > 10
+        ? await fuzzyFind(checkpoints, { ...common, toLabel: checkpointLabel })
+        : await selectList(checkpoints, {
+            ...common,
+            toLabel: checkpointLabel,
+            initialIndex: 0,
+        });
+    return result.kind === "selected" ? result.value : null;
+}
+/**
+ * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
+ * undoing everything an agent run changed (creates, edits, deletes) in one
+ * operation. Destructive by definition, so it is preview-first and gated
+ * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
+ * coded error before anything is computed. Out of scope, stated in the
+ * preview: commits, pushes, and PRs made during the run are not undone.
+ */
+export function rollbackCommand() {
+    return new Command("rollback")
+        .description("restore the working tree to a checkpoint, undoing an agent run's file changes")
+        .argument("[id]", "checkpoint id (defaults to the most recent)")
+        .action(async (id) => {
+        const interactive = Boolean(process.stdin.isTTY);
+        // Refuse before touching anything: rollback is a deliberate, interactive
+        // act. There is no flag to bypass this, by design.
+        if (!interactive)
+            throw rollbackApprovalRequired();
+        const { config } = loadConfig();
+        const root = process.cwd();
+        const service = new CheckpointService({ root, config });
+        const approval = new ApprovalService({
+            cwd: root,
+            interactive,
+            io: defaultPromptIO(shouldUseColor()),
+        });
+        // No id given → pick one interactively (U.7). Enter-once still restores
+        // the newest, exactly as before the picker existed.
+        if (id === undefined) {
+            const picked = await pickCheckpoint(service);
+            if (picked === null) {
+                logger.print(pc.dim("rollback cancelled — nothing was changed"));
+                return;
+            }
+            id = picked?.id;
+        }
+        const result = await service.rollback(id, {
+            requestApproval: (action) => approval.requestApproval(action),
+            interactive,
+        });
+        if (result.kind === "noop") {
+            logger.print(pc.dim(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+            return;
+        }
+        if (result.kind === "rejected") {
+            logger.print(pc.dim("rollback declined — nothing was changed"));
+            return;
+        }
+        const { recreated, reverted, deleted } = result.applied;
+        logger.print(`${pc.green("✓")} restored checkpoint ${pc.cyan(result.checkpoint.id)} — ` +
+            `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+        logger.print(pc.dim("note: commits, pushes, and PRs made during the run are not undone"));
+    });
+}

package/dist/cli/commands/run.js

@@ -4,6 +4,7 @@ import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
+import { CheckpointService } from "../../checkpoint/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
@@ -53,11 +54,18 @@ export function runCommand() {
         // One renderer for the whole run (U.2): the streaming path and the
         // approval prompt's status-suspend hook must share the same live region.
         const renderer = createRenderer();
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer);
+        // Checkpoint-before-first-mutation (C.32): the service is latched per run
+        // and fires from the approval seam inside the session, so one instance
+        // covers the one-shot path, every REPL turn, and plan-mode execution.
+        const checkpoints = config.checkpoint.enabled
+            ? new CheckpointService({ root: process.cwd(), config })
+            : undefined;
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints);
         if (interactive) {
-            await runInteractive(session, undefined, renderer);
+            await runInteractive(session, undefined, renderer, checkpoints);
             return;
         }
+        checkpoints?.beginRun(prompt);
         // One-shot: a single turn, then exit. Preserves scripting/pipe use.
         // Assistant text streams to stdout delta by delta (same as the REPL);
         // piped output degrades to the plain renderer (no ANSI, chrome on stderr).

package/dist/cli/program.js

@@ -10,6 +10,8 @@ import { skillsCommand } from "./commands/skills.js";
 import { prCommand } from "./commands/pr.js";
 import { loginCommand } from "./commands/login.js";
 import { initCommand } from "./commands/init.js";
+import { checkpointCommand } from "./commands/checkpoint.js";
+import { rollbackCommand } from "./commands/rollback.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -36,6 +38,8 @@ export function buildProgram() {
     program.addCommand(prCommand());
     program.addCommand(loginCommand());
     program.addCommand(initCommand());
+    program.addCommand(checkpointCommand());
+    program.addCommand(rollbackCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/repl.d.ts

@@ -1,6 +1,12 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
+import type { CheckpointService } from "../checkpoint/index.js";
 import { type StreamRenderer } from "../render/index.js";
+/**
+ * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
+ * sync with the dispatch below and the HELP text.
+ */
+export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/exit", "/quit"];
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;
@@ -17,4 +23,4 @@ export interface ReplIO {
  * live region, anything else the plain append-only renderer); `cruxy run`
  * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService): Promise<void>;

package/dist/cli/repl.js

@@ -1,9 +1,23 @@
 import readline from "node:readline";
 import pc from "picocolors";
+import { makeReplCompleter } from "../components/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { createRenderer } from "../render/index.js";
 import { logger } from "../utils/logger.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
+/**
+ * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
+ * sync with the dispatch below and the HELP text.
+ */
+export const REPL_COMMANDS = [
+    "/help",
+    "/clear",
+    "/compact",
+    "/reload",
+    "/plan",
+    "/exit",
+    "/quit",
+];
 const HELP = `Commands:
   /help          show this help
   /clear         clear the conversation history (keep the session)
@@ -35,6 +49,9 @@ function readLine(io, prompt) {
     const rl = readline.createInterface({
         input: io.input,
         output: io.output,
+        // Tab-completion for slash commands (U.7): readline rewrites the edit
+        // buffer only — completing never submits, Enter remains the sole trigger.
+        completer: makeReplCompleter(() => REPL_COMMANDS),
     });
     return new Promise((resolve) => {
         let answered = false;
@@ -74,16 +91,16 @@ function printReplError(err) {
  * live region, anything else the plain append-only renderer); `cruxy run`
  * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr)) {
+export async function runInteractive(session, io = defaultIO(), renderer = createRenderer(io.output, process.stderr), checkpoints) {
     logger.print(pc.dim("interactive session — /help for commands, /exit or Ctrl+D to quit"));
     try {
-        await replLoop(session, io, renderer);
+        await replLoop(session, io, renderer, checkpoints);
     }
     finally {
         renderer.close();
     }
 }
-async function replLoop(session, io, renderer) {
+async function replLoop(session, io, renderer, checkpoints) {
     for (;;) {
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
@@ -138,6 +155,9 @@ async function replLoop(session, io, renderer) {
         // line. Errors (provider/API failures) log and return to the prompt rather
         // than killing the REPL.
         try {
+            // Each REPL turn is its own undo unit (C.32): a fresh checkpoint latch,
+            // so `cruxy rollback` reverts exactly one turn's mutations.
+            checkpoints?.beginRun(trimmed);
             await session.send(line, renderer);
         }
         catch (err) {

package/dist/cli/session-factory.d.ts

@@ -1,6 +1,19 @@
 import type { CruxyConfig } from "../config/index.js";
+import type { ApprovalDecision } from "../approval/index.js";
+import type { CheckpointService } from "../checkpoint/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import { type ApproveAction } from "../tools/index.js";
 import { Session } from "../agent/index.js";
+/**
+ * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
+ * whole point: a tool mutates only *after* `requestApproval` resolves, so
+ * snapshotting after an `allow` decision but before returning it means the
+ * checkpoint always lands before the run's first mutation — and a denied
+ * action never creates one. The same seam records which paths the run touched
+ * (file actions) or that attribution is lost (shell), for rollback's
+ * external-change detection.
+ */
+export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, checkpoints: CheckpointService | undefined, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -10,4 +23,4 @@ import { Session } from "../agent/index.js";
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService): Session;