@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/core/edits/journal.js

@@ -1,199 +0,0 @@
-/**
- * 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,217 +0,0 @@
-/**
- * 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 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.
- *
- * Cursor's silent partial-match falling back to inline rewrite is the
- * documented anti-pattern in the spec; we do not replicate it.
- *
- * Writes use the tmp + rename atomic pattern (matches `writeTool` in
- * `apps/pugi-cli/src/tools/file-tools.ts`). A crash mid-write leaves
- * the original file intact; the `.pugi-tmp-*` file is the only
- * orphan and trivially identifiable.
- */
-import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
-import { applySecurityGate } from './security-gate.js';
-/**
- * Apply a single Layer A edit. The function is intentionally pure with
- * respect to errors — any failure returns a structured `ApplyResult`
- * rather than throwing. The dispatcher aggregates results; throwing
- * here would force the dispatcher to translate exceptions back into the
- * same shape on every layer.
- */
-export async function applyLayerA(edit, opts) {
-    // SECURITY GATE — fail-fast before ANY filesystem read/write.
-    // 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's pre-fix
-    // version would have written through `+++ NEW ../../../../etc/passwd`
-    // and `+++ NEW .env` markers (triple-review P0).
-    let gateResult;
-    try {
-        gateResult = applySecurityGate(edit.file, { cwd: opts.cwd, toolName: 'layer-a' });
-    }
-    catch (error) {
-        // The gate only throws on unexpected filesystem errors (anything
-        // other than ENOENT / ENOTDIR on the realpath calls). Treat those
-        // as a write error so the dispatcher records the actual cause.
-        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}`,
-        };
-    }
-    // Whitespace-sensitive: read as UTF-8 with no normalisation. CRLF
-    // vs LF differences in the model's emitted `oldString` will fail
-    // `no_match` LOUD rather than silently re-line-ending the file.
-    const before = readFileSync(absPath, 'utf8');
-    const matchCount = countOccurrences(before, edit.oldString);
-    if (matchCount === 0) {
-        return {
-            ok: false,
-            bytesWritten: 0,
-            reason: 'no_match',
-            absPath,
-            matchCount: 0,
-            detail: `oldString not found in ${edit.file}`,
-        };
-    }
-    if (matchCount > 1) {
-        return {
-            ok: false,
-            bytesWritten: 0,
-            reason: 'ambiguous_match',
-            absPath,
-            matchCount,
-            detail: `oldString matches ${matchCount} times in ${edit.file}; extend context to disambiguate`,
-        };
-    }
-    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 the upstream tool Edit-tool contract.
-        return {
-            ok: false,
-            bytesWritten: 0,
-            reason: 'identical_replacement',
-            absPath,
-            matchCount: 1,
-            detail: 'oldString and newString are identical — no-op',
-        };
-    }
-    const after = applySingleReplace(before, edit.oldString, edit.newString);
-    if (opts.dryRun) {
-        return {
-            ok: true,
-            bytesWritten: 0,
-            absPath,
-            matchCount: 1,
-        };
-    }
-    try {
-        atomicWrite(absPath, 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(after, 'utf8'),
-        absPath,
-        matchCount: 1,
-    };
-}
-/**
- * Count exact (whitespace-sensitive) occurrences of `needle` in `haystack`.
- * Empty needle returns 0 — a model that emits an empty `oldString` is
- * either bug or attempting a full-file replacement, both of which
- * Layer A rejects in favour of Layer C.
- *
- * Implemented via repeated `indexOf` (not `split(needle).length - 1`)
- * to avoid building an O(N) intermediate array for large files.
- */
-export function countOccurrences(haystack, needle) {
-    if (needle.length === 0)
-        return 0;
-    let count = 0;
-    let from = 0;
-    while (true) {
-        const idx = haystack.indexOf(needle, from);
-        if (idx === -1)
-            return count;
-        count += 1;
-        from = idx + needle.length;
-    }
-}
-/**
- * Replace the SINGLE occurrence of `needle` in `haystack` with
- * `replacement`. Pre-condition: caller verified `countOccurrences === 1`.
- * Returns the original buffer if no match (defensive; should not occur).
- */
-function applySingleReplace(haystack, needle, replacement) {
-    const idx = haystack.indexOf(needle);
-    if (idx === -1)
-        return haystack;
-    return haystack.slice(0, idx) + replacement + haystack.slice(idx + needle.length);
-}
-/**
- * Atomic write helper — writes contents to `<path>.pugi-tmp-<ts>-<rand>`
- * then renames over the target. The rename(2) syscall is atomic on
- * POSIX filesystems, so a crash between `writeFileSync` and `renameSync`
- * leaves the ORIGINAL file intact. The orphaned tmp file is named with
- * `pugi-tmp` so a janitor sweep can clean stale artifacts.
- *
- * Mirrors the same pattern used by `writeTool` and `editTool` in
- * `apps/pugi-cli/src/tools/file-tools.ts` so the audit story is
- * uniform.
- */
-function atomicWrite(absPath, contents) {
-    // Suffix combines clock + random so two concurrent edits on the same
-    // file from a single process do not collide (Date.now() resolution is
-    // millisecond-bounded; two writes inside the same ms would clobber).
-    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) {
-        // Best-effort cleanup; if the tmp never landed the unlink will
-        // ENOENT and we swallow that. Surface the original error to the
-        // caller via re-throw so the apply result records `write_error`.
-        try {
-            unlinkSync(tmp);
-        }
-        catch {
-            // tmp file may not exist if writeFileSync itself failed.
-        }
-        throw error;
-    }
-}
-//# sourceMappingURL=layer-a-apply.js.map

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

@@ -1,198 +0,0 @@
-/**
- * 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