@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/edits/index.js

@@ -0,0 +1,15 @@
+/**
+ * α6.6 diff escalation — public barrel.
+ *
+ * Surface for callers (CLI integration, future engine adapters, tests).
+ * Keeps the per-layer module path stable so β-tier additions (Layer D
+ * implementation, conflict resolution UI, unified-diff `git apply`
+ * fallback) can land without churn at the import sites.
+ */
+export { applyLayerA, countOccurrences, } from './layer-a-apply.js';
+export { applyLayerB, } from './layer-b-apply.js';
+export { applyLayerC, sha256OfUtf8, } from './layer-c-apply.js';
+export { applyLayerD, LayerDDeferredError, } from './layer-d-ast.js';
+export { MarkerParseError, detectFamily, parseMarkers, } from './marker-parser.js';
+export { dispatchEdit, resolveFamily, } from './dispatch.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,217 @@
+/**
+ * Layer A diff applicator — α6.6 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
+ * 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 #392's pre-fix
+    // version would have written through `+++ NEW ../../../../etc/passwd`
+    // and `+++ NEW .env` markers (triple-review 2026-05-25 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 Claude Code 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-b-apply.js

@@ -0,0 +1,211 @@
+/**
+ * Layer B diff applicator — α6.6 diff escalation Phase 1.
+ *
+ * Layer B is the multi-edit primitive: an ordered list of
+ * `{oldString, newString}` blocks against a single file, applied
+ * ALL-OR-NOTHING. Each block must satisfy the same uniqueness
+ * invariant as Layer A, but evaluated against the WORKING buffer
+ * after the prior blocks land — not the original disk contents. This
+ * lets the model emit edits like "rename `foo` to `bar`, then add a
+ * call to `bar(42)`" without the second edit failing because `foo`
+ * no longer exists.
+ *
+ * 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.
+ *
+ * Roll-back is therefore in-memory — no need to track per-block undo
+ * because nothing touched the disk until the final write.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { countOccurrences, } from './layer-a-apply.js';
+import { applySecurityGate } from './security-gate.js';
+export async function applyLayerB(batch, opts) {
+    // SECURITY GATE — see security-gate.ts. Identical responsibilities
+    // to Layer A: workspace path scoping, protected-basename deny,
+    // symlink-escape re-check. Runs BEFORE the empty-batch fast-path so
+    // a maliciously empty batch targeting `.env` still surfaces the
+    // protected-file rejection rather than the no-edits one.
+    let gateResult;
+    try {
+        gateResult = applySecurityGate(batch.file, { cwd: opts.cwd, toolName: 'layer-b' });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath: batch.file,
+            detail: error instanceof Error ? error.message : String(error),
+            appliedCount: 0,
+        };
+    }
+    if (!gateResult.ok) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: gateResult.reason,
+            absPath: batch.file,
+            detail: gateResult.detail,
+            appliedCount: 0,
+        };
+    }
+    const absPath = gateResult.absPath;
+    if (batch.edits.length === 0) {
+        // An empty edit array is almost always a bug in the marker parser
+        // or the model prompt. Fail loud rather than no-op success.
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'no_match',
+            absPath,
+            detail: 'Layer B batch contains zero sub-edits',
+            appliedCount: 0,
+        };
+    }
+    if (!existsSync(absPath)) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'file_missing',
+            absPath,
+            detail: `file does not exist: ${batch.file}`,
+            appliedCount: 0,
+        };
+    }
+    const original = readFileSync(absPath, 'utf8');
+    let buffer = original;
+    let appliedCount = 0;
+    for (let i = 0; i < batch.edits.length; i += 1) {
+        const sub = batch.edits[i];
+        if (!sub)
+            continue;
+        const stepResult = applyOneToBuffer(buffer, sub);
+        if (!stepResult.ok) {
+            return {
+                ok: false,
+                bytesWritten: 0,
+                reason: stepResult.reason,
+                absPath,
+                matchCount: stepResult.matchCount,
+                detail: `Layer B aborted at sub-edit ${i}: ${stepResult.detail}`,
+                appliedCount,
+                subFailures: [
+                    {
+                        index: i,
+                        reason: stepResult.reason,
+                        matchCount: stepResult.matchCount,
+                        detail: stepResult.detail,
+                    },
+                ],
+            };
+        }
+        buffer = stepResult.buffer;
+        appliedCount += 1;
+    }
+    // No-op detection: if every sub-edit was an identical-replacement,
+    // `appliedCount` would be 0 above because applyOneToBuffer rejects
+    // those. A zero-byte diff with appliedCount === batch.edits.length
+    // is technically possible if the edits cancel each other out; we
+    // accept that quietly because the model presumably knows.
+    if (buffer === original) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'identical_replacement',
+            absPath,
+            detail: 'Layer B batch produced no net change to the file',
+            appliedCount,
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            ok: true,
+            bytesWritten: 0,
+            absPath,
+            matchCount: appliedCount,
+            appliedCount,
+        };
+    }
+    try {
+        atomicWrite(absPath, buffer);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath,
+            detail: error instanceof Error ? error.message : String(error),
+            appliedCount,
+        };
+    }
+    return {
+        ok: true,
+        bytesWritten: Buffer.byteLength(buffer, 'utf8'),
+        absPath,
+        matchCount: appliedCount,
+        appliedCount,
+    };
+}
+function applyOneToBuffer(buffer, sub) {
+    if (sub.oldString === sub.newString) {
+        return {
+            ok: false,
+            reason: 'identical_replacement',
+            detail: 'oldString and newString are identical',
+        };
+    }
+    const count = countOccurrences(buffer, sub.oldString);
+    if (count === 0) {
+        return {
+            ok: false,
+            reason: 'no_match',
+            matchCount: 0,
+            detail: 'oldString not found in current buffer',
+        };
+    }
+    if (count > 1) {
+        return {
+            ok: false,
+            reason: 'ambiguous_match',
+            matchCount: count,
+            detail: `oldString matches ${count} times in current buffer`,
+        };
+    }
+    const idx = buffer.indexOf(sub.oldString);
+    const next = buffer.slice(0, idx) + sub.newString + buffer.slice(idx + sub.oldString.length);
+    return { ok: true, buffer: next };
+}
+/**
+ * Atomic write helper — duplicated from `layer-a-apply.ts` (not exported
+ * to keep the dependency direction one-way: A is the primitive, B
+ * happens to reuse the same disk-write pattern but is otherwise
+ * independent). Both helpers are intentionally small enough that
+ * duplication is cheaper than dragging in a shared util module.
+ */
+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 {
+            // ignore — tmp may not exist yet.
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=layer-b-apply.js.map

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

@@ -0,0 +1,160 @@
+/**
+ * Layer C diff applicator — α6.6 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).
+ *
+ * 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
+ * the safest for sweeping refactors that touch most lines — Layer A
+ * would emit dozens of fragile blocks and Layer B's atomicity goes
+ * out the window past ~10 blocks.
+ *
+ * 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.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync, unlinkSync } from 'node:fs';
+import { applySecurityGate } from './security-gate.js';
+export async function applyLayerC(edit, opts) {
+    // SECURITY GATE — see security-gate.ts. Layer C is the most
+    // dangerous layer (full-file rewrite) so the gate runs FIRST, ahead
+    // of the baseSha check. A missing baseSha on an attempted `.env`
+    // rewrite should surface as `protected_file`, not `write_error`.
+    let gateResult;
+    try {
+        gateResult = applySecurityGate(edit.file, { cwd: opts.cwd, toolName: 'layer-c' });
+    }
+    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 (edit.baseSha256.length === 0) {
+        // An empty baseSha is almost always a marker-parser bug. Refuse
+        // rather than write blind.
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath,
+            detail: 'Layer C requires a non-empty baseSha256',
+        };
+    }
+    if (!existsSync(absPath)) {
+        // Layer C is a REWRITE, not a CREATE. Use Layer A's sibling
+        // `write` tool to create files. Failing loud keeps the layer
+        // semantics honest: Layer C's gate is "file was X when I read
+        // it"; a non-existent file violates the read invariant.
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'file_missing',
+            absPath,
+            detail: `file does not exist: ${edit.file}; Layer C does not create files`,
+        };
+    }
+    const current = readFileSync(absPath, 'utf8');
+    const actualSha = sha256OfUtf8(current);
+    if (actualSha !== edit.baseSha256) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'base_sha_mismatch',
+            absPath,
+            detail: `file changed since model read: expected sha256 ${edit.baseSha256.slice(0, 12)}…, ` +
+                `got ${actualSha.slice(0, 12)}…`,
+            expectedSha256: edit.baseSha256,
+            actualSha256: actualSha,
+        };
+    }
+    if (current === edit.newContents) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'identical_replacement',
+            absPath,
+            detail: 'newContents is identical to current file',
+            expectedSha256: edit.baseSha256,
+            actualSha256: actualSha,
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            ok: true,
+            bytesWritten: 0,
+            absPath,
+            expectedSha256: edit.baseSha256,
+            actualSha256: actualSha,
+        };
+    }
+    try {
+        atomicWrite(absPath, edit.newContents);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            bytesWritten: 0,
+            reason: 'write_error',
+            absPath,
+            detail: error instanceof Error ? error.message : String(error),
+            expectedSha256: edit.baseSha256,
+            actualSha256: actualSha,
+        };
+    }
+    return {
+        ok: true,
+        bytesWritten: Buffer.byteLength(edit.newContents, 'utf8'),
+        absPath,
+        expectedSha256: edit.baseSha256,
+        actualSha256: actualSha,
+    };
+}
+/**
+ * Sha256 of a UTF-8 string. Hex output, lowercased. Centralised so the
+ * apply-side hash and the dispatcher-side hash (when computing the
+ * baseSha for the model on read) agree byte-for-byte.
+ */
+export function sha256OfUtf8(contents) {
+    return createHash('sha256').update(contents, 'utf8').digest('hex');
+}
+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 {
+            // ignore — tmp may not exist.
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=layer-c-apply.js.map

package/dist/core/edits/layer-d-ast.js

@@ -0,0 +1,29 @@
+/**
+ * Sentinel error type the dispatcher recognises. Distinct from the
+ * generic `Error` so the dispatcher can render a friendly
+ * "AST edits land in α6.6b" message rather than a stack trace.
+ *
+ * Caller convention: catch `LayerDDeferredError` explicitly; rethrow
+ * any other error as before.
+ */
+export class LayerDDeferredError extends Error {
+    code = 'LAYER_D_DEFERRED';
+    operation;
+    constructor(operation) {
+        super(`Layer D (AST) edits land in α6.6b — attempted operation: ${operation}. ` +
+            'Use Layer A / B / C until the AST engine ships.');
+        this.name = 'LayerDDeferredError';
+        this.operation = operation;
+    }
+}
+/**
+ * Stub applicator. Always rejects with `LayerDDeferredError`. Returns
+ * the standard `ApplyResult` shape on the (impossible) success path
+ * so the dispatcher can treat all four layers uniformly once Layer D
+ * lights up.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function applyLayerD(edit, _opts) {
+    throw new LayerDDeferredError(edit.operation);
+}
+//# sourceMappingURL=layer-d-ast.js.map