@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/core/edits/dispatch.js

@@ -1,5 +1,6 @@
 /**
- * Diff dispatch — α6.6 escalation Phase 1.
+ * Diff dispatch — α6.6 escalation Phase 1, β1b Pl8 transactional layer
+ * (2026-05-26).
  *
  * Reads a raw model response containing one or more SEARCH/REPLACE
  * envelopes, normalises them through `marker-parser`, and routes each
@@ -21,16 +22,36 @@
  * the writeFile. A crash between the two leaves a recoverable trail —
  * the operator (or `pugi resume`) sees the intent and can re-attempt.
  *
+ * β1b Pl8 — transactional rollback: when the caller supplies
+ * `transactional: { sessionId, taskId, workspaceRoot }`, the dispatcher
+ * wraps the multi-file edits in a session journal (see
+ * `core/edits/journal.ts`). On non-zero exit / budget kill / partial
+ * fail it runs `rollbackDispatch()`:
+ *
+ *   - tracked files that EXISTED before → `git restore -- <file>`
+ *   - newly created files (existed=false) → `fs.unlink`
+ *   - untracked files that EXISTED before → restore from in-memory
+ *     pre-content snapshot (sha256_before validated)
+ *
+ * Pattern mirrors `tools/apply-patch.ts::rollbackFiles` (PR #413). The
+ * journal is the durability layer that lets a process crash recover
+ * across PIDs; the in-memory snapshot covers the single-process case
+ * where the journal write itself failed.
+ *
  * The dispatcher is intentionally side-effect-light: no logging, no
  * stdout writes, no exit-code mutation. The CLI integration layer in
  * `cli.ts` owns operator-facing rendering; the dispatcher returns
  * structured data and lets the caller decide UX.
  */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
 import { LayerDDeferredError, applyLayerD } from './layer-d-ast.js';
 import { applyLayerA } from './layer-a-apply.js';
 import { applyLayerB } from './layer-b-apply.js';
 import { applyLayerC } from './layer-c-apply.js';
 import { MarkerParseError, parseMarkers, } from './marker-parser.js';
+import { appendEntry, snapshotForDispatch, } from './journal.js';
 /**
  * Parse `raw` into edits and apply each in order. Aggregate results,
  * preserving order. Never throws — parse failures surface as a single
@@ -65,13 +86,208 @@ export async function dispatchEdit(raw, opts) {
         // render "no edits proposed".
         return [];
     }
+    // β1b Pl8 — transactional path. When enabled, snapshot every target
+    // file BEFORE the first applicator runs so we can roll back if a
+    // later edit fails. Snapshot also drives the journal entry so a
+    // post-crash recovery can replay rollback in a fresh process.
+    //
+    // The journal write itself is best-effort: a disk-full / EACCES
+    // failure must NOT block the dispatch. The in-memory snapshot
+    // still carries every pre-existing file's content, so single-
+    // process rollback degrades cleanly. The operator sees the
+    // journal-failed warning via the session events mirror (caller's
+    // responsibility to emit).
+    let snapshot = null;
+    let preContent = null;
+    if (opts.transactional && !opts.dryRun) {
+        const targets = Array.from(new Set(parsed.map((e) => editFile(e))));
+        snapshot = snapshotForDispatch(opts.transactional.workspaceRoot, targets);
+        preContent = new Map();
+        for (const e of snapshot) {
+            if (!e.existed)
+                continue;
+            const abs = resolve(opts.transactional.workspaceRoot, e.path);
+            try {
+                preContent.set(e.path, readFileSync(abs));
+            }
+            catch {
+                /* file vanished between snapshot + read — treat as not-snapshotted */
+            }
+        }
+        appendEntry(opts.transactional.workspaceRoot, opts.transactional.sessionId, {
+            ts: Date.now(),
+            taskId: opts.transactional.taskId,
+            files: snapshot,
+        });
+    }
     const out = [];
+    let crashError = null;
     for (const edit of parsed) {
         const intent = makeIntent(edit);
         opts.onIntent?.(intent);
-        const result = await applyOne(edit, opts);
+        let result;
+        try {
+            result = await applyOne(edit, opts);
+        }
+        catch (error) {
+            // applyOne does not throw today (errors are returned as
+            // `ok: false`), but a future applicator that does throw —
+            // or a budget-kill that arrives mid-write — needs deterministic
+            // rollback. Catch + record + break so the rollback below runs.
+            crashError = error;
+            const msg = error instanceof Error ? error.message : String(error);
+            result = {
+                layer: 'layer-a',
+                file: editFile(edit),
+                ok: false,
+                bytesWritten: 0,
+                reason: 'apply_error',
+                detail: `dispatch threw: ${msg}`,
+            };
+        }
         out.push(result);
         opts.onResult?.(result);
+        if (!result.ok && opts.transactional && snapshot && preContent) {
+            // Rollback every snapshotted file then break out — partial
+            // success is unacceptable in transactional mode.
+            const rollback = rollbackDispatch(opts.transactional.workspaceRoot, snapshot, preContent);
+            if (!rollback.ok) {
+                // Surface the rollback failure as an additional synthetic
+                // result so the caller can render the operator-facing
+                // message without losing the original failure context.
+                const failure = {
+                    layer: 'layer-a',
+                    file: '',
+                    ok: false,
+                    bytesWritten: 0,
+                    reason: 'rollback_failed',
+                    detail: rollback.detail,
+                };
+                out.push(failure);
+                opts.onResult?.(failure);
+            }
+            if (crashError) {
+                // Re-throw post-rollback so the caller learns the dispatch
+                // crashed (vs returned ok: false). Rollback already completed
+                // so the workspace is consistent.
+                throw crashError;
+            }
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * Workspace-relative path for a parsed edit, regardless of layer.
+ * Hoisted because the snapshot + intent both need the same answer.
+ */
+function editFile(edit) {
+    switch (edit.kind) {
+        case 'layer-a':
+        case 'layer-b':
+        case 'layer-c':
+        case 'layer-d':
+            return edit.edit.file;
+    }
+}
+/**
+ * Roll the workspace back to the pre-dispatch state captured in
+ * `snapshot`. Mirrors `tools/apply-patch.ts::rollbackFiles`:
+ *
+ *   - existed-before + git-tracked → `git restore -- <file>` (cheap
+ *     + atomic against the index).
+ *   - existed-before + untracked   → restore from the in-memory
+ *     preContent buffer (sha256_before validates the snapshot still
+ *     matches what we hold; if not we punt with `partial_rollback`).
+ *   - newly created                → fs.unlink (force).
+ *
+ * Best-effort: every per-file failure is collected into the detail
+ * string so the operator can manually fix the residual state. The
+ * dispatcher does not abort on the first error so an unrelated
+ * permission glitch on one file doesn't strand the others.
+ *
+ * Exported for the spec suite + a future operator command
+ * (`pugi resume --rollback <taskId>` ships in β2).
+ */
+export function rollbackDispatch(workspaceRoot, snapshot, preContent) {
+    if (snapshot.length === 0)
+        return { ok: true };
+    // Filter to workspace-internal paths only. A snapshot entry that
+    // escaped the workspace would already have aborted upstream; the
+    // filter is belt + braces against a future bug.
+    const safe = snapshot.filter((e) => {
+        const abs = resolve(workspaceRoot, e.path);
+        return abs === workspaceRoot || abs.startsWith(workspaceRoot + sep);
+    });
+    const failures = [];
+    const tracked = listTrackedFiles(workspaceRoot, safe.map((e) => e.path));
+    for (const entry of safe) {
+        const abs = resolve(workspaceRoot, entry.path);
+        if (!entry.existed) {
+            try {
+                // β1b r1: `recursive: true` so rollback handles the case where
+                // the dispatcher created an intermediate directory (e.g. a new
+                // `src/feature/` tree). Without it the unlink fails on a dir
+                // and the journal-replay leaves an orphan workspace path.
+                rmSync(abs, { force: true, recursive: true });
+            }
+            catch (error) {
+                failures.push(`${entry.path}: unlink failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            continue;
+        }
+        if (tracked.has(entry.path)) {
+            const result = spawnSync('git', ['restore', '--', entry.path], {
+                cwd: workspaceRoot,
+                encoding: 'utf8',
+            });
+            if (result.status !== 0) {
+                failures.push(`${entry.path}: git restore failed: ${(result.stderr ?? '').trim() || 'non-zero exit'}`);
+            }
+            continue;
+        }
+        // Untracked-but-existed: write back from memory.
+        const buf = preContent.get(entry.path);
+        if (!buf) {
+            failures.push(`${entry.path}: pre-content snapshot missing (partial rollback)`);
+            continue;
+        }
+        try {
+            writeFileSync(abs, buf);
+        }
+        catch (error) {
+            failures.push(`${entry.path}: rewrite failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures.length === 0)
+        return { ok: true };
+    return { ok: false, detail: failures.join('; ') };
+}
+/**
+ * Ask git which of `paths` are tracked. A single `git ls-files
+ * --error-unmatch` call would fail-fast on the first untracked path,
+ * so we use `git ls-files -- <paths...>` which lists only tracked
+ * matches. Returns a Set of workspace-relative paths.
+ *
+ * Pure-stdlib fallback when git is unavailable: returns an empty
+ * Set — every "existed" entry then routes to the untracked-restore
+ * path via the in-memory preContent map. Slower per file but still
+ * correct.
+ */
+function listTrackedFiles(cwd, paths) {
+    if (paths.length === 0)
+        return new Set();
+    const result = spawnSync('git', ['ls-files', '--', ...paths], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return new Set();
+    const out = new Set();
+    for (const line of (result.stdout ?? '').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+            out.add(trimmed);
     }
     return out;
 }

package/dist/core/edits/journal.js

@@ -0,0 +1,199 @@
+/**
+ * Edit journal — β1b Pl8 (2026-05-26).
+ *
+ * Per-session append-only log of file-mutation INTENT before the
+ * dispatcher runs. Lives at `<root>/.pugi/sessions/<sessionId>/journal.jsonl`,
+ * one JSON entry per multi-file dispatch. On a non-zero exit / budget
+ * kill / OOM crash, the journal lets `git restore` / `fs.unlink` revert
+ * the workspace to its pre-dispatch state.
+ *
+ * Shape:
+ *
+ *   ```ts
+ *   {
+ *     ts: number,           // ms epoch — opens chronological replay
+ *     taskId: string,       // engine task id (`<kind>-<ts>`) for correlation
+ *     files: [{
+ *       path: string,             // workspace-relative
+ *       existed: boolean,         // existed BEFORE the dispatch
+ *       sha256_before?: string,   // present iff existed === true
+ *     }],
+ *   }
+ *   ```
+ *
+ * The journal records ONLY intent: it does not enumerate the post-state
+ * (a per-edit `applied` event already lives in `events.jsonl`). On
+ * rollback we need the pre-state to know:
+ *   - whether to `git restore` (the file existed before and is git-
+ *     tracked) OR `fs.unlink` (the file did NOT exist before — it was
+ *     created by the failed dispatch).
+ *   - whether to fall back to writing the cached `sha256_before` source
+ *     when neither git nor fs can recover (untracked file that existed
+ *     before — the dispatcher MUST have cached the pre-content; we
+ *     surface a `partial_rollback` reason and let the operator decide).
+ *
+ * Why a separate journal vs reusing `events.jsonl`:
+ *   - events.jsonl mixes status + tool_call + tool_result + outcome
+ *     records from the engine loop. A crash mid-dispatch leaves the
+ *     file in a state where reconstructing "files we MIGHT have
+ *     touched" requires correlating multiple event types. The journal
+ *     hoists the rollback-relevant subset into one line per dispatch
+ *     so the recovery code is grep-able + audit-readable.
+ *   - The journal is also forward-compatible with a future
+ *     `pugi resume --rollback <taskId>` operator command — single
+ *     source of truth for "what would I undo".
+ *
+ * Best-effort writes: a journal failure (disk full, .pugi unwritable)
+ * must NEVER block the actual edit. The dispatcher proceeds with
+ * `journalEntryId: null` and surfaces a warning in the session's
+ * status events. Rollback then degrades to apply-patch-style
+ * pre-existing snapshot (the dispatcher keeps an in-memory copy too).
+ *
+ * Brand voice: ASCII only, no banned words. Operator-facing tail
+ * (jq friendly).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+/**
+ * Compute the on-disk journal path for a session. The directory is
+ * created lazily by `appendEntry` so a read against a missing session
+ * does not silently mkdir.
+ */
+export function journalPath(workspaceRoot, sessionId) {
+    return resolve(workspaceRoot, '.pugi', 'sessions', sessionId, 'journal.jsonl');
+}
+/**
+ * sha256 of a file's bytes. Used by `snapshotForDispatch` to capture
+ * the pre-content fingerprint so rollback can detect "file was changed
+ * between intent + rollback" cases (rare but real — a concurrent
+ * external editor + the dispatcher hitting the same path).
+ *
+ * Returns null when the file cannot be hashed (missing / unreadable);
+ * caller treats absent fingerprint as `existed=false`.
+ */
+export function sha256File(absPath) {
+    try {
+        const buf = readFileSync(absPath);
+        const h = createHash('sha256');
+        h.update(buf);
+        return h.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a snapshot of the pre-dispatch state for every workspace-relative
+ * path the dispatcher is about to touch. Pure read; no writes.
+ *
+ * `paths` are workspace-relative. The journal records the SAME shape so
+ * the rollback path can re-resolve against the same `workspaceRoot`
+ * without ambiguity.
+ */
+export function snapshotForDispatch(workspaceRoot, paths) {
+    const out = [];
+    for (const rel of paths) {
+        const abs = resolve(workspaceRoot, rel);
+        if (existsSync(abs)) {
+            // Hash only on regular files; sha256File returns null for
+            // directories or unreadable inodes and we degrade cleanly.
+            try {
+                const st = statSync(abs);
+                if (st.isFile()) {
+                    const sha = sha256File(abs);
+                    out.push({ path: rel, existed: true, ...(sha ? { sha256_before: sha } : {}) });
+                    continue;
+                }
+            }
+            catch {
+                /* fall through — treat as non-existent for rollback */
+            }
+        }
+        out.push({ path: rel, existed: false });
+    }
+    return out;
+}
+/**
+ * Append one journal entry. Best-effort: any I/O failure returns false
+ * and the dispatcher proceeds without journal-backed rollback. The
+ * in-memory `JournalFileEntry[]` snapshot still drives the immediate
+ * post-crash rollback inside the same process.
+ */
+export function appendEntry(workspaceRoot, sessionId, entry) {
+    const path = journalPath(workspaceRoot, sessionId);
+    try {
+        mkdirSync(join(workspaceRoot, '.pugi', 'sessions', sessionId), {
+            recursive: true,
+            mode: 0o700,
+        });
+    }
+    catch {
+        return false;
+    }
+    try {
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', mode: 0o600 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read every journal entry for a session, oldest-first. Malformed
+ * lines are dropped silently — a single bad line should not nuke
+ * recovery. Returns `[]` when the file is missing.
+ *
+ * Synchronous (mirrors `recordToolCall` etc) because the operator-
+ * facing rollback path needs to be deterministic; a partially-
+ * streamed read would race the very crash recovery it is supporting.
+ */
+export function readEntries(workspaceRoot, sessionId) {
+    const path = journalPath(workspaceRoot, sessionId);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (!parsed ||
+                typeof parsed !== 'object' ||
+                typeof parsed.taskId !== 'string' ||
+                typeof parsed.ts !== 'number' ||
+                !Array.isArray(parsed.files)) {
+                continue;
+            }
+            // β1b r1 defense-in-depth: validate every `files[]` entry too.
+            // A malformed file entry (missing `path`, wrong `existed` type)
+            // would silently feed garbage into the rollback path; better to
+            // drop the whole journal line than to attempt restore against a
+            // bogus snapshot.
+            const candidate = parsed;
+            const allFilesValid = candidate.files.every((f) => f !== null &&
+                typeof f === 'object' &&
+                typeof f.path === 'string' &&
+                f.path.length > 0 &&
+                typeof f.existed === 'boolean' &&
+                (f.sha256_before === undefined ||
+                    typeof f.sha256_before === 'string'));
+            if (!allFilesValid)
+                continue;
+            out.push(candidate);
+        }
+        catch {
+            /* drop malformed line */
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=journal.js.map