@cruxy/cli 0.8.0 → 0.10.0

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;
+}

package/dist/checkpoint/service.js

@@ -0,0 +1,276 @@
+import { randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointFailed, checkpointNotFound, rollbackApprovalRequired, CruxyError, } from "../errors/index.js";
+import { logger } from "../utils/logger.js";
+import { runGitCapture } from "../vcs/git.js";
+import { captureFiles } from "./capture.js";
+import { GitCheckpointStore } from "./git-store.js";
+import { ShadowCheckpointStore } from "./shadow-store.js";
+import { applyRollback, buildRollbackPreview, computeRollbackPlan, } from "./restore.js";
+/** Is `root` inside a git working tree? (Decides the checkpoint substrate.) */
+export function isGitWorkTree(root) {
+    const res = runGitCapture(["rev-parse", "--is-inside-work-tree"], root);
+    return res.ok && res.stdout.trim() === "true";
+}
+/**
+ * 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 function createCheckpointStore(root, kind) {
+    const resolved = kind ?? (isGitWorkTree(root) ? "git" : "shadow");
+    return resolved === "git"
+        ? new GitCheckpointStore(root)
+        : new ShadowCheckpointStore(root);
+}
+/**
+ * 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 class CheckpointService {
+    root;
+    config;
+    pinnedStore;
+    runSummary = "agent run";
+    active = null;
+    constructor(opts) {
+        this.root = path.resolve(opts.root);
+        this.config = opts.config;
+        this.pinnedStore = opts.store;
+    }
+    /** Start a new undo unit: reset the once-per-run latch and name the run. */
+    beginRun(summary) {
+        this.active = null;
+        const firstLine = summary.split("\n", 1)[0].trim();
+        this.runSummary =
+            firstLine.length > 80
+                ? `${firstLine.slice(0, 79)}…`
+                : firstLine || "agent run";
+    }
+    /**
+     * 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.
+     */
+    async ensureCheckpoint() {
+        if (!this.config.checkpoint.enabled)
+            return null;
+        if (this.active)
+            return this.active;
+        const gitWorkTree = this.pinnedStore
+            ? this.pinnedStore.kind === "git"
+            : isGitWorkTree(this.root);
+        let store = this.pinnedStore ??
+            createCheckpointStore(this.root, gitWorkTree ? "git" : "shadow");
+        let entries;
+        try {
+            entries = await store.snapshot(await captureFiles(this.root, gitWorkTree));
+        }
+        catch (err) {
+            // Git plumbing failed mid-snapshot → shadow-copy fallback (the manifest
+            // records which substrate actually wrote the checkpoint). A pinned store
+            // (tests) never falls back; a shadow failure has nowhere left to go.
+            if (store.kind !== "git" || this.pinnedStore) {
+                throw CruxyError.is(err)
+                    ? err
+                    : checkpointFailed("snapshotting the working tree failed", err);
+            }
+            logger.warn(`git-backed checkpoint failed (${err.message}); falling back to a shadow copy`);
+            store = new ShadowCheckpointStore(this.root);
+            entries = await store.snapshot(await captureFiles(this.root, false));
+        }
+        const checkpoint = {
+            id: newCheckpointId(),
+            createdAt: new Date().toISOString(),
+            runSummary: this.runSummary,
+            store: store.kind,
+            files: entries,
+            touchedPaths: [],
+            hasShellMutations: false,
+        };
+        await this.writeManifest(checkpoint);
+        await this.prune();
+        this.active = checkpoint;
+        logger.debug(`checkpoint ${checkpoint.id} created (${entries.length} files, ${store.kind} store)`);
+        return checkpoint;
+    }
+    /** Attribute mutated paths to the current run (persisted for later rollback). */
+    async recordTouched(absPaths) {
+        if (!this.active || absPaths.length === 0)
+            return;
+        const known = new Set(this.active.touchedPaths);
+        let added = false;
+        for (const abs of absPaths) {
+            const rel = path.relative(this.root, abs).split(path.sep).join("/");
+            if (rel === "" || rel.startsWith("..") || known.has(rel))
+                continue;
+            known.add(rel);
+            this.active.touchedPaths.push(rel);
+            added = true;
+        }
+        if (added)
+            await this.writeManifest(this.active);
+    }
+    /** The run ran a shell command: per-path attribution is no longer possible. */
+    async recordShellMutation() {
+        if (!this.active || this.active.hasShellMutations)
+            return;
+        this.active.hasShellMutations = true;
+        await this.writeManifest(this.active);
+    }
+    /** All checkpoints, newest first. Corrupt manifests are warned about, not fatal. */
+    async list() {
+        let names;
+        try {
+            names = await fsp.readdir(this.dir());
+        }
+        catch {
+            return []; // no checkpoints dir yet
+        }
+        const checkpoints = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            try {
+                checkpoints.push(await this.readManifestFile(path.join(this.dir(), name)));
+            }
+            catch (err) {
+                logger.warn(`skipping unreadable checkpoint manifest ${name}: ${err.message}`);
+            }
+        }
+        checkpoints.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+        return checkpoints;
+    }
+    /** One checkpoint by id, or the newest when `id` is omitted. Fail-loud. */
+    async read(id) {
+        if (id === undefined) {
+            const newest = (await this.list())[0];
+            if (!newest)
+                throw checkpointNotFound();
+            return newest;
+        }
+        const file = path.join(this.dir(), `${id}.json`);
+        try {
+            await fsp.access(file);
+        }
+        catch {
+            throw checkpointNotFound(id);
+        }
+        return this.readManifestFile(file);
+    }
+    /**
+     * The whole gated restore: preview → U.3 destructive approval → apply.
+     * Non-interactive callers are refused up front — there is no auto-rollback.
+     */
+    async rollback(id, deps) {
+        if (!deps.interactive)
+            throw rollbackApprovalRequired();
+        const checkpoint = await this.read(id);
+        const store = this.pinnedStore ?? createCheckpointStore(this.root, checkpoint.store);
+        const plan = await computeRollbackPlan(this.root, checkpoint, store, isGitWorkTree(this.root));
+        if (plan.entries.length === 0)
+            return { kind: "noop", checkpoint };
+        const preview = await buildRollbackPreview(this.root, plan, store);
+        const decision = await deps.requestApproval({ kind: "rollback", preview });
+        if (!decision.allow) {
+            return { kind: "rejected", feedback: decision.feedback };
+        }
+        const applied = await applyRollback(this.root, plan, store);
+        return { kind: "applied", checkpoint, applied };
+    }
+    /** Enforce `checkpoint.retention`: drop oldest manifests, then GC content. */
+    async prune() {
+        const all = await this.list();
+        const doomed = all.slice(this.config.checkpoint.retention);
+        if (doomed.length === 0)
+            return;
+        for (const checkpoint of doomed) {
+            await fsp.rm(path.join(this.dir(), `${checkpoint.id}.json`), {
+                force: true,
+            });
+        }
+        const survivors = all.slice(0, this.config.checkpoint.retention);
+        const referenced = new Set(survivors.flatMap((c) => c.files.map((f) => f.oid)));
+        // The shadow pool is ours to sweep; git's dangling objects belong to git gc.
+        await new ShadowCheckpointStore(this.root).collect(referenced);
+    }
+    // ── manifest persistence ────────────────────────────────────────────────────
+    dir() {
+        return path.join(this.root, ".cruxy", "checkpoints");
+    }
+    async writeManifest(checkpoint) {
+        const dir = this.dir();
+        try {
+            await fsp.mkdir(dir, { recursive: true });
+            // Self-ignoring: git never sees checkpoint state, and the user's own
+            // .gitignore is never edited. Written once, only if absent.
+            const ignoreFile = path.join(dir, ".gitignore");
+            try {
+                await fsp.access(ignoreFile);
+            }
+            catch {
+                await fsp.writeFile(ignoreFile, "*\n");
+            }
+            const file = path.join(dir, `${checkpoint.id}.json`);
+            const tmp = `${file}.tmp-${process.pid}`;
+            await fsp.writeFile(tmp, `${JSON.stringify(checkpoint, null, 2)}\n`);
+            await fsp.rename(tmp, file);
+        }
+        catch (err) {
+            throw checkpointFailed(`writing the checkpoint manifest for ${checkpoint.id} failed`, err);
+        }
+    }
+    async readManifestFile(file) {
+        let raw;
+        try {
+            raw = await fsp.readFile(file, "utf8");
+        }
+        catch (err) {
+            throw checkpointFailed(`reading checkpoint manifest ${file} failed`, err);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw checkpointFailed(`checkpoint manifest ${file} is not valid JSON`, err);
+        }
+        if (!isCheckpointShape(parsed)) {
+            throw checkpointFailed(`checkpoint manifest ${file} is malformed`);
+        }
+        return parsed;
+    }
+}
+/** `ck-<utc-stamp>-<rand>` — sortable, collision-safe enough for a local CLI. */
+function newCheckpointId() {
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+$/, "");
+    return `ck-${stamp}-${randomBytes(2).toString("hex")}`;
+}
+/** Structural check for a parsed manifest — enough to fail loud on corruption. */
+function isCheckpointShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        typeof v.createdAt === "string" &&
+        typeof v.runSummary === "string" &&
+        (v.store === "git" || v.store === "shadow") &&
+        Array.isArray(v.files) &&
+        v.files.every((f) => typeof f === "object" &&
+            f !== null &&
+            typeof f.path === "string" &&
+            typeof f.oid === "string" &&
+            (f.mode === "100644" ||
+                f.mode === "100755")) &&
+        Array.isArray(v.touchedPaths) &&
+        v.touchedPaths.every((p) => typeof p === "string") &&
+        typeof v.hasShellMutations === "boolean");
+}

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

@@ -0,0 +1,23 @@
+import type { CaptureFile, CheckpointStore, FileEntry } from "./types.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 declare class ShadowCheckpointStore implements CheckpointStore {
+    readonly kind: "shadow";
+    private readonly objectsDir;
+    constructor(root: string);
+    hashContent(content: Buffer): string;
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    readContent(entry: FileEntry): Promise<Buffer>;
+    collect(referenced: ReadonlySet<string>): Promise<void>;
+    /** Content-addressed write: skip if present, else temp-then-rename (atomic). */
+    private writeObject;
+}