@cruxy/cli 0.7.0 → 0.9.0

package/dist/checkpoint/git-store.d.ts

@@ -0,0 +1,61 @@
+import type { CaptureFile, CheckpointStore, FileEntry } from "./types.js";
+/**
+ * Git-object-backed checkpoint content store (C.32 primary substrate).
+ *
+ * How a snapshot works — and exactly why it can never disturb the user's git
+ * state. Every git invocation is one of these five, and nothing else:
+ *
+ *   1. `git rev-parse --absolute-git-dir`          (read-only)
+ *   2. `git update-index --add -z --stdin`, with `GIT_INDEX_FILE` pointing at a
+ *      **temporary index file in os.tmpdir()**. Git hashes each captured file
+ *      into `.git/objects` as loose blobs and stages them *in the temp index*.
+ *      The user's `.git/index` is never opened for writing.
+ *   3. `git write-tree`, same `GIT_INDEX_FILE` — writes tree objects, returns
+ *      the root tree oid.
+ *   4. `git ls-files --stage -z`, same `GIT_INDEX_FILE` — reads back
+ *      `mode oid stage\tpath` per file for the manifest. The temp index is then
+ *      deleted.
+ *   5. `git cat-file blob <oid>` on restore/preview                (read-only)
+ *
+ * No `commit-tree`, no `update-ref`, no `stash`, no branch: **no ref is ever
+ * created or moved, and HEAD / the index / the stash are never written.** The
+ * blobs and trees are deliberately *dangling* — referenced only by the manifest
+ * JSON under `.cruxy/checkpoints/`.
+ *
+ * Enforced, not assumed: {@link snapshot} fingerprints the user-visible state
+ * (raw `.git/HEAD` bytes, a hash of `.git/index`, `git for-each-ref`, and
+ * `git stash list`) before and after, and throws CRUXY_E_CHECKPOINT_FAILED
+ * naming what moved if anything drifted.
+ *
+ * Accepted trade-off: dangling objects are subject to `git gc --prune`. The
+ * default two-week grace plus retention pruning makes that a non-issue, but a
+ * user running `git gc --prune=now` can orphan a manifest — then rollback fails
+ * loudly (never restores partial state), and the shadow store remains the
+ * fallback substrate for new checkpoints.
+ */
+export declare class GitCheckpointStore implements CheckpointStore {
+    private readonly root;
+    readonly kind: "git";
+    constructor(root: string);
+    /** Git blob sha-1: `sha1("blob <len>\0" + content)` — matches `git hash-object`. */
+    hashContent(content: Buffer): string;
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    readContent(entry: FileEntry): Promise<Buffer>;
+    /** Dangling objects belong to git's own gc; nothing for us to sweep. */
+    collect(): Promise<void>;
+    /** Parse `git ls-files --stage -z` from the temp index into manifest entries. */
+    private readStagedEntries;
+    /**
+     * Run git with binary-safe stdout (restore must round-trip arbitrary bytes),
+     * optional stdin, and optional extra env. Local to this store on purpose —
+     * `runGitCapture` is text-mode and env-less, and the rest of the CLI should
+     * stay that way.
+     */
+    private git;
+    /**
+     * Everything a user can observe of their git state, byte-for-byte: HEAD file,
+     * index contents, every ref (branches, tags, remotes, stash tip — packed or
+     * loose, via for-each-ref), and the full stash reflog (stash list).
+     */
+    private fingerprint;
+}

package/dist/checkpoint/git-store.js

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises as fsp, readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { checkpointFailed } from "../errors/index.js";
+import { runGitCapture } from "../vcs/git.js";
+/**
+ * Git-object-backed checkpoint content store (C.32 primary substrate).
+ *
+ * How a snapshot works — and exactly why it can never disturb the user's git
+ * state. Every git invocation is one of these five, and nothing else:
+ *
+ *   1. `git rev-parse --absolute-git-dir`          (read-only)
+ *   2. `git update-index --add -z --stdin`, with `GIT_INDEX_FILE` pointing at a
+ *      **temporary index file in os.tmpdir()**. Git hashes each captured file
+ *      into `.git/objects` as loose blobs and stages them *in the temp index*.
+ *      The user's `.git/index` is never opened for writing.
+ *   3. `git write-tree`, same `GIT_INDEX_FILE` — writes tree objects, returns
+ *      the root tree oid.
+ *   4. `git ls-files --stage -z`, same `GIT_INDEX_FILE` — reads back
+ *      `mode oid stage\tpath` per file for the manifest. The temp index is then
+ *      deleted.
+ *   5. `git cat-file blob <oid>` on restore/preview                (read-only)
+ *
+ * No `commit-tree`, no `update-ref`, no `stash`, no branch: **no ref is ever
+ * created or moved, and HEAD / the index / the stash are never written.** The
+ * blobs and trees are deliberately *dangling* — referenced only by the manifest
+ * JSON under `.cruxy/checkpoints/`.
+ *
+ * Enforced, not assumed: {@link snapshot} fingerprints the user-visible state
+ * (raw `.git/HEAD` bytes, a hash of `.git/index`, `git for-each-ref`, and
+ * `git stash list`) before and after, and throws CRUXY_E_CHECKPOINT_FAILED
+ * naming what moved if anything drifted.
+ *
+ * Accepted trade-off: dangling objects are subject to `git gc --prune`. The
+ * default two-week grace plus retention pruning makes that a non-issue, but a
+ * user running `git gc --prune=now` can orphan a manifest — then rollback fails
+ * loudly (never restores partial state), and the shadow store remains the
+ * fallback substrate for new checkpoints.
+ */
+export class GitCheckpointStore {
+    root;
+    kind = "git";
+    constructor(root) {
+        this.root = root;
+    }
+    /** Git blob sha-1: `sha1("blob <len>\0" + content)` — matches `git hash-object`. */
+    hashContent(content) {
+        return createHash("sha1")
+            .update(`blob ${content.length}\0`)
+            .update(content)
+            .digest("hex");
+    }
+    async snapshot(files) {
+        const before = this.fingerprint();
+        const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), "cruxy-checkpoint-"));
+        const indexFile = path.join(tmpDir, "index");
+        try {
+            const env = { GIT_INDEX_FILE: indexFile };
+            // Stage every captured path into the temp index (writes blobs).
+            const stdin = files.map((f) => `${f.path}\0`).join("");
+            const add = this.git(["update-index", "--add", "-z", "--stdin"], {
+                env,
+                input: stdin,
+            });
+            if (!add.ok) {
+                throw checkpointFailed(`staging files into the temporary index failed: ${add.stderr.trim()}`);
+            }
+            // Persist the tree objects. The oid itself isn't stored — per-file blob
+            // oids from ls-files --stage are what restore needs — but write-tree is
+            // what makes the whole snapshot a single connected object graph.
+            const tree = this.git(["write-tree"], { env });
+            if (!tree.ok) {
+                throw checkpointFailed(`writing the snapshot tree failed: ${tree.stderr.trim()}`);
+            }
+            const entries = this.readStagedEntries(env);
+            const after = this.fingerprint();
+            assertGitStateUnchanged(before, after);
+            return entries;
+        }
+        finally {
+            await fsp.rm(tmpDir, { recursive: true, force: true });
+        }
+    }
+    async readContent(entry) {
+        const res = this.git(["cat-file", "blob", entry.oid]);
+        if (!res.ok) {
+            throw checkpointFailed(`checkpoint content for ${entry.path} is gone from the git object database ` +
+                `(blob ${entry.oid}) — most likely pruned by \`git gc --prune\``);
+        }
+        return res.stdout;
+    }
+    /** Dangling objects belong to git's own gc; nothing for us to sweep. */
+    async collect() {
+        /* no-op by design */
+    }
+    // ── internals ───────────────────────────────────────────────────────────────
+    /** Parse `git ls-files --stage -z` from the temp index into manifest entries. */
+    readStagedEntries(env) {
+        const res = this.git(["ls-files", "--stage", "-z"], { env });
+        if (!res.ok) {
+            throw checkpointFailed(`reading back the staged snapshot failed: ${res.stderr.trim()}`);
+        }
+        const entries = [];
+        for (const record of res.stdout.toString("utf8").split("\0")) {
+            if (record === "")
+                continue;
+            // "<mode> <oid> <stage>\t<path>"
+            const tab = record.indexOf("\t");
+            const [mode, oid] = record.slice(0, tab).split(" ");
+            const relPath = record.slice(tab + 1);
+            if (mode !== "100644" && mode !== "100755") {
+                // Capture filters to regular files, so anything else staging here is a
+                // bug or a race — refuse to write a manifest we can't faithfully restore.
+                throw checkpointFailed(`unsupported file mode ${mode} for ${relPath} in the snapshot`);
+            }
+            entries.push({ path: relPath, mode, oid });
+        }
+        return entries;
+    }
+    /**
+     * Run git with binary-safe stdout (restore must round-trip arbitrary bytes),
+     * optional stdin, and optional extra env. Local to this store on purpose —
+     * `runGitCapture` is text-mode and env-less, and the rest of the CLI should
+     * stay that way.
+     */
+    git(args, opts = {}) {
+        const res = spawnSync("git", args, {
+            cwd: this.root,
+            windowsHide: true,
+            maxBuffer: 1024 * 1024 * 1024,
+            input: opts.input,
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+        const stdout = Buffer.isBuffer(res.stdout) ? res.stdout : Buffer.alloc(0);
+        const stderr = (res.stderr?.toString("utf8") ?? "") ||
+            (res.error ? res.error.message : "");
+        return { ok: res.status === 0 && !res.error, stdout, stderr };
+    }
+    /**
+     * Everything a user can observe of their git state, byte-for-byte: HEAD file,
+     * index contents, every ref (branches, tags, remotes, stash tip — packed or
+     * loose, via for-each-ref), and the full stash reflog (stash list).
+     */
+    fingerprint() {
+        const gitDirRes = runGitCapture(["rev-parse", "--absolute-git-dir"], this.root);
+        const gitDir = gitDirRes.ok ? gitDirRes.stdout.trim() : "";
+        return {
+            head: readFileOr(path.join(gitDir, "HEAD")),
+            index: hashFileOr(path.join(gitDir, "index")),
+            refs: runGitCapture(["for-each-ref", "--format=%(refname) %(objectname)"], this.root).stdout,
+            stash: runGitCapture(["stash", "list"], this.root).stdout,
+        };
+    }
+}
+function readFileOr(file, fallback = "<absent>") {
+    return existsSync(file) ? readFileSync(file, "utf8") : fallback;
+}
+function hashFileOr(file, fallback = "<absent>") {
+    if (!existsSync(file))
+        return fallback;
+    return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+/** The runtime self-check: any drift in user-visible git state is a hard failure. */
+function assertGitStateUnchanged(before, after) {
+    const drifted = Object.keys(before).filter((k) => before[k] !== after[k]);
+    if (drifted.length > 0) {
+        throw checkpointFailed(`snapshot invariant violated: user-visible git state changed (${drifted.join(", ")}) — refusing to continue`);
+    }
+}

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./capture.js";
+export * from "./git-store.js";
+export * from "./shadow-store.js";
+export * from "./restore.js";
+export * from "./service.js";

package/dist/checkpoint/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./capture.js";
+export * from "./git-store.js";
+export * from "./shadow-store.js";
+export * from "./restore.js";
+export * from "./service.js";

package/dist/checkpoint/restore.d.ts

@@ -0,0 +1,23 @@
+import type { ActionPreview } from "../tools/types.js";
+import type { Checkpoint, CheckpointStore, RollbackApplied, RollbackPlan } from "./types.js";
+/**
+ * Diff the current working tree against a checkpoint by content address.
+ * External attribution: a differing path the tracked run never touched is
+ * flagged `external` — unless the run executed shell commands, in which case
+ * attribution is unknowable and the plan says so instead of guessing.
+ */
+export declare function computeRollbackPlan(root: string, checkpoint: Checkpoint, store: CheckpointStore, gitWorkTree: boolean): Promise<RollbackPlan>;
+/**
+ * Build the U.2 preview for a plan: patch-style entries (byte-identical with
+ * apply_patch previews) plus the external-change and boundary annotations that
+ * `renderActionPreview` places *above* the diff.
+ */
+export declare function buildRollbackPreview(root: string, plan: RollbackPlan, store: CheckpointStore): Promise<Extract<ActionPreview, {
+    type: "rollback";
+}>>;
+/**
+ * Apply a plan: recreate deleted files, revert edited ones (content and mode),
+ * then remove run-created files (and any directories that emptied out). Any
+ * failure is a loud CRUXY_E_CHECKPOINT_FAILED; re-running rollback resumes.
+ */
+export declare function applyRollback(root: string, plan: RollbackPlan, store: CheckpointStore): Promise<RollbackApplied>;

package/dist/checkpoint/restore.js

@@ -0,0 +1,195 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointFailed, CruxyError } from "../errors/index.js";
+import { isInside } from "../approval/classify.js";
+import { isBinary } from "../indexing/util.js";
+import { captureFiles } from "./capture.js";
+/**
+ * Rollback planning + application (C.32). The plan is recomputed from disk on
+ * every invocation — never cached — which is what makes rollback idempotent:
+ * a partially-applied rollback re-run picks up exactly the remaining work.
+ */
+/** Per-file cap on preview content lines (the renderer collapses globally too). */
+const FILE_PREVIEW_LINES = 20;
+/**
+ * Diff the current working tree against a checkpoint by content address.
+ * External attribution: a differing path the tracked run never touched is
+ * flagged `external` — unless the run executed shell commands, in which case
+ * attribution is unknowable and the plan says so instead of guessing.
+ */
+export async function computeRollbackPlan(root, checkpoint, store, gitWorkTree) {
+    const current = await captureFiles(root, gitWorkTree);
+    const currentPaths = new Set(current.map((f) => f.path));
+    const manifestPaths = new Set(checkpoint.files.map((e) => e.path));
+    const touched = new Set(checkpoint.touchedPaths);
+    const attributionUnknown = checkpoint.hasShellMutations;
+    const isExternal = (p) => !attributionUnknown && !touched.has(p);
+    const entries = [];
+    for (const entry of checkpoint.files) {
+        const absPath = path.join(root, ...entry.path.split("/"));
+        if (!currentPaths.has(entry.path)) {
+            entries.push({
+                path: entry.path,
+                action: "recreate",
+                external: isExternal(entry.path),
+                entry,
+            });
+            continue;
+        }
+        const content = await fsp.readFile(absPath);
+        const mode = await fileMode(absPath);
+        if (store.hashContent(content) !== entry.oid || mode !== entry.mode) {
+            entries.push({
+                path: entry.path,
+                action: "revert",
+                external: isExternal(entry.path),
+                entry,
+            });
+        }
+    }
+    for (const file of current) {
+        if (!manifestPaths.has(file.path)) {
+            entries.push({
+                path: file.path,
+                action: "delete",
+                external: isExternal(file.path),
+            });
+        }
+    }
+    entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+        checkpoint,
+        entries,
+        externalPaths: entries.filter((e) => e.external).map((e) => e.path),
+        attributionUnknown,
+    };
+}
+/**
+ * Build the U.2 preview for a plan: patch-style entries (byte-identical with
+ * apply_patch previews) plus the external-change and boundary annotations that
+ * `renderActionPreview` places *above* the diff.
+ */
+export async function buildRollbackPreview(root, plan, store) {
+    const files = [];
+    for (const entry of plan.entries) {
+        if (entry.action === "delete") {
+            files.push({ op: "delete", path: entry.path });
+            continue;
+        }
+        // entry.entry is always present for recreate/revert (see RollbackEntry).
+        const restored = await store.readContent(entry.entry);
+        if (entry.action === "recreate") {
+            const { lines, omitted } = previewLines(restored);
+            files.push({
+                op: "create",
+                path: entry.path,
+                lines,
+                omittedLines: omitted,
+            });
+            continue;
+        }
+        const currentPath = path.join(root, ...entry.path.split("/"));
+        const current = await fsp.readFile(currentPath);
+        files.push({
+            op: "update",
+            path: entry.path,
+            hunks: [
+                {
+                    oldStr: previewText(current),
+                    newStr: previewText(restored),
+                },
+            ],
+        });
+    }
+    return {
+        type: "rollback",
+        checkpointId: plan.checkpoint.id,
+        createdAt: plan.checkpoint.createdAt,
+        runSummary: plan.checkpoint.runSummary,
+        files,
+        externalPaths: plan.externalPaths,
+        attributionUnknown: plan.attributionUnknown,
+    };
+}
+/**
+ * Apply a plan: recreate deleted files, revert edited ones (content and mode),
+ * then remove run-created files (and any directories that emptied out). Any
+ * failure is a loud CRUXY_E_CHECKPOINT_FAILED; re-running rollback resumes.
+ */
+export async function applyRollback(root, plan, store) {
+    const applied = { recreated: 0, reverted: 0, deleted: 0 };
+    for (const entry of plan.entries) {
+        const absPath = safeAbsPath(root, entry.path);
+        try {
+            if (entry.action === "delete") {
+                await fsp.rm(absPath, { force: true });
+                await removeEmptyDirs(root, path.dirname(absPath));
+                applied.deleted += 1;
+                continue;
+            }
+            const content = await store.readContent(entry.entry);
+            await fsp.mkdir(path.dirname(absPath), { recursive: true });
+            await fsp.writeFile(absPath, content);
+            await fsp.chmod(absPath, entry.entry.mode === "100755" ? 0o755 : 0o644);
+            applied[entry.action === "recreate" ? "recreated" : "reverted"] += 1;
+        }
+        catch (err) {
+            if (CruxyError.is(err))
+                throw err;
+            throw checkpointFailed(`restoring ${entry.path} failed (${entry.action})`, err);
+        }
+    }
+    return applied;
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+/** Resolve a manifest path and refuse anything that escapes the project root. */
+function safeAbsPath(root, relPath) {
+    const abs = path.resolve(root, ...relPath.split("/"));
+    if (!isInside(path.resolve(root), abs) || abs === path.resolve(root)) {
+        throw checkpointFailed(`manifest path escapes the project root: ${relPath}`);
+    }
+    return abs;
+}
+/** Remove now-empty directories from `dir` up to (never including) `root`. */
+async function removeEmptyDirs(root, dir) {
+    const absRoot = path.resolve(root);
+    let current = path.resolve(dir);
+    while (current !== absRoot && isInside(absRoot, current)) {
+        try {
+            await fsp.rmdir(current); // fails on non-empty — exactly the stop signal
+        }
+        catch {
+            return;
+        }
+        current = path.dirname(current);
+    }
+}
+async function fileMode(absPath) {
+    const stat = await fsp.lstat(absPath);
+    return stat.mode & 0o100 ? "100755" : "100644";
+}
+/** First lines of restored content for a `create` preview; binary → placeholder. */
+function previewLines(content) {
+    if (isBinary(content)) {
+        return { lines: [binaryPlaceholder(content)], omitted: 0 };
+    }
+    const all = content.toString("utf8").replace(/\n$/, "").split("\n");
+    return {
+        lines: all.slice(0, FILE_PREVIEW_LINES),
+        omitted: Math.max(0, all.length - FILE_PREVIEW_LINES),
+    };
+}
+/** Capped text for an `update` hunk side; binary → placeholder. */
+function previewText(content) {
+    if (isBinary(content))
+        return binaryPlaceholder(content);
+    const all = content.toString("utf8").replace(/\n$/, "").split("\n");
+    if (all.length <= FILE_PREVIEW_LINES)
+        return all.join("\n");
+    const shown = all.slice(0, FILE_PREVIEW_LINES);
+    shown.push(`… (+${all.length - FILE_PREVIEW_LINES} more lines)`);
+    return shown.join("\n");
+}
+function binaryPlaceholder(content) {
+    return `«binary file, ${content.length} bytes»`;
+}

package/dist/checkpoint/service.d.ts

@@ -0,0 +1,80 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { ApprovalDecision } from "../approval/types.js";
+import type { ApproveAction } from "../tools/types.js";
+import type { Checkpoint, CheckpointStore, CheckpointStoreKind, RollbackApplied } from "./types.js";
+/** Is `root` inside a git working tree? (Decides the checkpoint substrate.) */
+export declare function isGitWorkTree(root: string): boolean;
+/**
+ * The substrate factory: git-object store inside a repo, shadow store outside.
+ * Pass `kind` to pin the substrate (rollback must read a checkpoint back with
+ * the store that wrote it, recorded in its manifest).
+ */
+export declare function createCheckpointStore(root: string, kind?: CheckpointStoreKind): CheckpointStore;
+export interface CheckpointServiceOptions {
+    root: string;
+    config: CruxyConfig;
+    /** Test seam: pin the content store (disables the git→shadow fallback). */
+    store?: CheckpointStore;
+}
+/** What `rollback()` needs from the caller: the U.3 gate and TTY interactivity. */
+export interface RollbackDeps {
+    requestApproval(action: ApproveAction): Promise<ApprovalDecision>;
+    interactive: boolean;
+}
+export type RollbackResult = 
+/** The working tree already matches the checkpoint — nothing to do. */
+{
+    kind: "noop";
+    checkpoint: Checkpoint;
+}
+/** The user saw the preview and declined; nothing was applied. */
+ | {
+    kind: "rejected";
+    feedback?: string;
+} | {
+    kind: "applied";
+    checkpoint: Checkpoint;
+    applied: RollbackApplied;
+};
+/**
+ * Checkpoint lifecycle (C.32): create once before a run's first mutation,
+ * record what the run touches, list/prune, and drive the gated rollback.
+ * Manifests are JSON under `.cruxy/checkpoints/` — they survive process exit,
+ * so `cruxy rollback` works in a later invocation.
+ */
+export declare class CheckpointService {
+    private readonly root;
+    private readonly config;
+    private readonly pinnedStore?;
+    private runSummary;
+    private active;
+    constructor(opts: CheckpointServiceOptions);
+    /** Start a new undo unit: reset the once-per-run latch and name the run. */
+    beginRun(summary: string): void;
+    /**
+     * The auto-checkpoint hook, called from the approval seam after every allowed
+     * mutating action and latched to fire once per run — before the first
+     * mutation ever reaches disk. Returns the run's checkpoint, or `null` when
+     * the feature is disabled. Fail-loud: if a checkpoint cannot be written by
+     * either substrate, the run must not mutate without its undo protection.
+     */
+    ensureCheckpoint(): Promise<Checkpoint | null>;
+    /** Attribute mutated paths to the current run (persisted for later rollback). */
+    recordTouched(absPaths: string[]): Promise<void>;
+    /** The run ran a shell command: per-path attribution is no longer possible. */
+    recordShellMutation(): Promise<void>;
+    /** All checkpoints, newest first. Corrupt manifests are warned about, not fatal. */
+    list(): Promise<Checkpoint[]>;
+    /** One checkpoint by id, or the newest when `id` is omitted. Fail-loud. */
+    read(id?: string): Promise<Checkpoint>;
+    /**
+     * The whole gated restore: preview → U.3 destructive approval → apply.
+     * Non-interactive callers are refused up front — there is no auto-rollback.
+     */
+    rollback(id: string | undefined, deps: RollbackDeps): Promise<RollbackResult>;
+    /** Enforce `checkpoint.retention`: drop oldest manifests, then GC content. */
+    prune(): Promise<void>;
+    private dir;
+    private writeManifest;
+    private readManifestFile;
+}