@pugi/cli 0.1.0-beta.12 → 0.1.0-beta.13

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