@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/core/edits/journal.js

@@ -0,0 +1,199 @@
+/**
+ * Edit journal — β1b Pl8 .
+ *
+ * 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

package/dist/core/edits/layer-a-apply.js

@@ -1,24 +1,24 @@
 /**
- * Layer A diff applicator — α6.6 diff escalation Phase 1.
+ * Layer A diff applicator — diff escalation Phase 1.
  *
  * Layer A is the default and lowest-risk edit primitive: a single
  * `{file, oldString, newString}` block that must match exactly once
- * (whitespace-sensitive). It mirrors the Claude Code Edit-tool semantics
+ * (whitespace-sensitive). It mirrors the the upstream tool Edit-tool semantics
  * by design: agents emit a chunk of context guaranteed to be unique
  * inside the file, and we replace it.
  *
  * Three failure modes are surfaced LOUD (never silent partial match):
  *
- *   - `no_match`        — oldString does not appear in the file at all.
- *                          Model must re-read with broader context.
- *   - `ambiguous_match` — oldString appears 2+ times. Model must extend
- *                          the context to disambiguate (line above /
- *                          below / function name / etc.). The result
- *                          carries the match count so the dispatcher
- *                          can surface it to the operator.
- *   - `file_missing`    — the target file does not exist on disk.
- *                          Layer A NEVER creates files — that is the
- *                          job of the write tool or Layer C.
+ *  - `no_match`       — oldString does not appear in the file at all.
+ *                         Model must re-read with broader context.
+ *  - `ambiguous_match` — oldString appears 2+ times. Model must extend
+ *                         the context to disambiguate (line above /
+ *                         below / function name / etc.). The result
+ *                         carries the match count so the dispatcher
+ *                         can surface it to the operator.
+ *  - `file_missing`   — the target file does not exist on disk.
+ *                         Layer A NEVER creates files — that is the
+ *                         job of the write tool or Layer C.
  *
  * Cursor's silent partial-match falling back to inline rewrite is the
  * documented anti-pattern in the spec; we do not replicate it.
@@ -42,9 +42,9 @@ export async function applyLayerA(edit, opts) {
     // The gate runs three checks in order: workspace path scoping,
     // protected-basename / suffix / credential-path deny, and a
     // realpath-based symlink-escape re-check. See `security-gate.ts`
-    // for the full rationale. Bypassing this is how PR #392's pre-fix
+    // for the full rationale. Bypassing this is how PR's pre-fix
     // version would have written through `+++ NEW ../../../../etc/passwd`
-    // and `+++ NEW .env` markers (triple-review 2026-05-25 P0).
+    // and `+++ NEW .env` markers (triple-review P0).
     let gateResult;
     try {
         gateResult = applySecurityGate(edit.file, { cwd: opts.cwd, toolName: 'layer-a' });
@@ -108,7 +108,7 @@ export async function applyLayerA(edit, opts) {
     if (edit.oldString === edit.newString) {
         // Treat no-op edits as a failure so the model corrects itself
         // rather than silently believing the patch landed. This matches
-        // the Claude Code Edit-tool contract.
+        // the the upstream tool Edit-tool contract.
         return {
             ok: false,
             bytesWritten: 0,

package/dist/core/edits/layer-a-fuzzy-apply.js

@@ -0,0 +1,198 @@
+/**
+ * Layer A.5 — fuzzy SEARCH/REPLACE applicator.
+ *
+ * Wraps `tryFuzzyLadder` with the same security gate + atomic-write
+ * machinery Layer A uses, then escalates to disk. Sits between Layer
+ * A strict-exact (which already failed with `no_match`) and Layer C
+ * rewrite (which requires the model к re-emit the whole file).
+ *
+ * Failure semantics:
+ *
+ *  - `no_match`        — all three tiers failed. Operator + model
+ *                         treat this identically к Layer A's
+ *                         `no_match`: re-read with broader context.
+ *  - `ambiguous_match` — a tier found 2+ equally-scored candidates.
+ *                         Surfaces matchCount so the dispatcher can
+ *                         tell the model "extend context".
+ *  - `file_missing`    — target file does not exist; ladder never
+ *                         creates files (parity с Layer A).
+ *  - `identical_replacement` — search and replace are identical;
+ *                         would no-op; surfaced LOUD.
+ *
+ * Inspired by Aider editblock_coder.py (Apache-2.0). independent implementation
+ * implementation; no Aider source code copied.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { applySecurityGate } from './security-gate.js';
+import { tryFuzzyLadder } from './fuzzy-ladder.js';
+export async function applyLayerAFuzzy(edit, opts) {
+    // Security gate — identical к Layer A. Path scoping + protected
+    // basename + symlink-escape re-check. Bypassing this is how a
+    // fuzzy retry could rescue an otherwise-failed `.env` edit.
+    let gateResult;
+    try {
+        gateResult = applySecurityGate(edit.file, { cwd: opts.cwd, toolName: 'layer-a-fuzzy' });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath: edit.file,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (!gateResult.ok) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: gateResult.reason,
+            absPath: edit.file,
+            detail: gateResult.detail,
+        };
+    }
+    const absPath = gateResult.absPath;
+    if (!existsSync(absPath)) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'file_missing',
+            absPath,
+            detail: `file does not exist: ${edit.file}`,
+        };
+    }
+    if (edit.oldString === edit.newString) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'identical_replacement',
+            absPath,
+            detail: 'oldString and newString are identical — no-op',
+        };
+    }
+    const before = readFileSync(absPath, 'utf8');
+    const ladder = tryFuzzyLadder(before, edit.oldString, edit.newString, {
+        minRatio: opts.minRatio,
+        lengthFlex: opts.lengthFlex,
+    });
+    if (ladder.kind === 'no_match') {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'no_match',
+            absPath,
+            matchCount: 0,
+            detail: ladder.detail,
+        };
+    }
+    if (ladder.kind === 'ambiguous') {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'ambiguous_match',
+            absPath,
+            matchCount: ladder.candidateCount,
+            detail: ladder.detail,
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            ok: true,
+            bytesWritten: 0,
+            absPath,
+            matchCount: 1,
+            fuzzyTier: ladder.tier,
+            fuzzyScore: ladder.score,
+        };
+    }
+    // Triple-review P1-3 — re-verify the security gate immediately
+    // before the destructive write. The upstream gate ran BEFORE the
+    // ladder; on a slow ladder (large file, tier-3 LCS scan) a symlink
+    // swap could have re-targeted `absPath` between the two checks. The
+    // gate is cheap relative to a fuzzy edit, and double-running it
+    // closes the TOCTOU window opened by the per-tool reuse of `absPath`.
+    // We pin the re-check to the same tool-name so audit logs correlate.
+    let gateRecheck;
+    try {
+        gateRecheck = applySecurityGate(edit.file, { cwd: opts.cwd, toolName: 'layer-a-fuzzy' });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath,
+            matchCount: 1,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (!gateRecheck.ok) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: gateRecheck.reason,
+            absPath,
+            matchCount: 1,
+            detail: `pre-write recheck: ${gateRecheck.detail}`,
+        };
+    }
+    if (gateRecheck.absPath !== absPath) {
+        // The gate resolved to a DIFFERENT path on re-run — a symlink swap
+        // or a parent-dir mutation occurred between the two gate calls.
+        // Refuse the write loud rather than landing on the new target.
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'symlink_escape',
+            absPath,
+            matchCount: 1,
+            detail: `pre-write recheck resolved to a different path: ${gateRecheck.absPath} != ${absPath}`,
+        };
+    }
+    try {
+        atomicWrite(absPath, ladder.after);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath,
+            matchCount: 1,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return {
+        ok: true,
+        bytesWritten: Buffer.byteLength(ladder.after, 'utf8'),
+        absPath,
+        matchCount: 1,
+        fuzzyTier: ladder.tier,
+        fuzzyScore: ladder.score,
+    };
+}
+/**
+ * Atomic write — mirrors `layer-a-apply::atomicWrite`. Duplicated
+ * intentionally (not exported from Layer A) because the fuzzy module
+ * stays decoupled from Layer A's internals — if Layer A's write path
+ * ever diverges (e.g. mode bits for a future executable-bit support)
+ * the fuzzy ladder should evolve independently.
+ */
+function atomicWrite(absPath, contents) {
+    const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const tmp = `${absPath}.pugi-tmp-${suffix}`;
+    try {
+        writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
+        renameSync(tmp, absPath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // tmp may not exist if writeFileSync itself failed.
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=layer-a-fuzzy-apply.js.map

package/dist/core/edits/layer-b-apply.js

@@ -1,5 +1,5 @@
 /**
- * Layer B diff applicator — α6.6 diff escalation Phase 1.
+ * Layer B diff applicator — diff escalation Phase 1.
  *
  * Layer B is the multi-edit primitive: an ordered list of
  * `{oldString, newString}` blocks against a single file, applied
@@ -12,14 +12,14 @@
  *
  * Atomicity story:
  *
- *   1. We mutate a single in-memory string buffer.
- *   2. Every block runs through `applyOneToBuffer` and either advances
- *      the buffer or returns a structured failure.
- *   3. On ANY block failure we discard the buffer and write nothing.
- *      The on-disk file remains exactly as it was on entry.
- *   4. On total success we hand the final buffer to the same atomic
- *      tmp+rename writer Layer A uses, so a crash mid-write can never
- *      leave a partially-edited file.
+ *  1. We mutate a single in-memory string buffer.
+ *  2. Every block runs through `applyOneToBuffer` and either advances
+ *     the buffer or returns a structured failure.
+ *  3. On ANY block failure we discard the buffer and write nothing.
+ *     The on-disk file remains exactly as it was on entry.
+ *  4. On total success we hand the final buffer to the same atomic
+ *     tmp+rename writer Layer A uses, so a crash mid-write can never
+ *     leave a partially-edited file.
  *
  * Roll-back is therefore in-memory — no need to track per-block undo
  * because nothing touched the disk until the final write.

package/dist/core/edits/layer-c-apply.js

@@ -1,15 +1,15 @@
 /**
- * Layer C diff applicator — α6.6 diff escalation Phase 1.
+ * Layer C diff applicator — diff escalation Phase 1.
  *
  * Layer C is the full-file rewrite escape hatch. The model emits the
  * complete new file contents plus a sha256 of the file as it was when
  * the model READ it. We compute the current sha256 of the on-disk
  * file, compare, and either:
  *
- *   - Match — atomically write the new contents.
- *   - Mismatch — refuse with `base_sha_mismatch`. The model must
- *     re-read the file and resubmit; the disk version changed between
- *     read and write (filewatcher event, parallel edit, human typing).
+ *  - Match — atomically write the new contents.
+ *  - Mismatch — refuse with `base_sha_mismatch`. The model must
+ *    re-read the file and resubmit; the disk version changed between
+ *    read and write (filewatcher event, parallel edit, human typing).
  *
  * This is the "I rewrote the entire file" path. It is the heaviest
  * Layer because the wire payload is the full file body, but it is also
@@ -19,7 +19,7 @@
  *
  * The sha256 gate is the load-bearing safety. Without it, Layer C
  * silently overwrites concurrent edits; with it, the operator
- * (and Mira) sees a clean `mismatch` event and can resolve manually.
+ * (and Pugi) sees a clean `mismatch` event and can resolve manually.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';