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

package/dist/core/edits/dispatch.js

@@ -1,511 +0,0 @@
-/**
- * Diff dispatch — escalation Phase 1, β1b Pl8 transactional layer
- * .
- *
- * Reads a raw model response containing one or more SEARCH/REPLACE
- * envelopes, normalises them through `marker-parser`, and routes each
- * parsed edit to the correct applicator:
- *
- *  - `layer-a` → applyLayerA
- *  - `layer-b` → applyLayerB
- *  - `layer-c` → applyLayerC
- *  - `layer-d` → throws LayerDDeferredError, surfaced as a clean
- *                dispatch failure (Layer D ships in )
- *
- * Per-edit results are aggregated into `DispatchResult[]` so callers
- * can render the full apply transcript even when some edits failed.
- * Order is preserved across the response.
- *
- * Crash recovery hook: when a SessionStore-style appendEvent callback
- * is supplied, the dispatcher records the INTENT (parsed edit) BEFORE
- * calling the applicator. The matching `applied` event lands AFTER
- * 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). 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 { commitCheckpoint, formatCheckpointMessage, initShadowRepo, ShadowGitUnavailableError, } from '../checkpoints/shadow-git.js';
-import { detectEditFormat } from './format-detector.js';
-import { LayerDDeferredError, applyLayerD } from './layer-d-ast.js';
-import { applyLayerA } from './layer-a-apply.js';
-import { applyLayerAFuzzy } from './layer-a-fuzzy-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
- * synthetic DispatchResult with `ok: false, layer: 'layer-a', reason:
- * 'marker_parse_error'`. Applicator failures are recorded per-edit.
- */
-export async function dispatchEdit(raw, opts) {
-    const family = resolveFamily(opts.modelTag);
-    // PUGI-79 — resolve the preferred-layer chain ONCE per dispatch.
-    // Caller supplied wins; otherwise the detector derives from modelTag.
-    // The chain is informational here (the parser still routes per
-    // envelope); a future fuzzy-ladder change can read it to influence
-    // retry ordering without revisiting the dispatcher's escalation
-    // contract.
-    const preferredChain = resolvePreferredChain(opts);
-    if (preferredChain)
-        opts.onPreferredLayer?.(preferredChain);
-    let parsed;
-    try {
-        parsed = parseMarkers(raw, family);
-    }
-    catch (error) {
-        if (error instanceof MarkerParseError) {
-            const result = {
-                layer: 'layer-a',
-                file: '',
-                ok: false,
-                bytesWritten: 0,
-                reason: 'marker_parse_error',
-                detail: `${error.message}${error.atLine ? ` (line ${error.atLine})` : ''} — modelHint=${error.modelHint}`,
-                ...(preferredChain ? { expectedLayer: preferredChain.primary } : {}),
-            };
-            opts.onResult?.(result);
-            return [result];
-        }
-        throw error;
-    }
-    if (parsed.length === 0) {
-        // Empty parse but no error == no markers in the payload. This is
-        // not necessarily a failure (the model may have answered with
-        // prose only); surface a single neutral result so the caller can
-        // 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,
-        });
-    }
-    // Per-task shadow git checkpoint hook (backlog). Init the
-    // shadow once per dispatch, then commit after every successful
-    // edit. The init is best-effort — a missing `git` binary or a
-    // chmod failure surfaces through `onCheckpointError` but does not
-    // disable the dispatch.
-    let checkpointStep = opts.checkpoint?.stepStart && Number.isFinite(opts.checkpoint.stepStart)
-        ? Math.max(1, Math.floor(opts.checkpoint.stepStart))
-        : 1;
-    let checkpointEnabled = false;
-    if (opts.checkpoint && !opts.dryRun) {
-        try {
-            initShadowRepo(opts.cwd, opts.checkpoint.taskId);
-            checkpointEnabled = true;
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            opts.checkpoint.onCheckpointError?.(err, '');
-        }
-    }
-    const expectedLayer = preferredChain?.primary;
-    const out = [];
-    let crashError = null;
-    for (const edit of parsed) {
-        const intent = makeIntent(edit);
-        opts.onIntent?.(intent);
-        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}`,
-            };
-        }
-        if (expectedLayer !== undefined) {
-            // PUGI-79: stamp the expected layer on every result so
-            // observability surfaces can compute drift (expected vs actual)
-            // per family. The actual `layer` field is unchanged — the
-            // hint is informational, not a routing override.
-            result = { ...result, expectedLayer };
-        }
-        out.push(result);
-        opts.onResult?.(result);
-        if (result.ok && checkpointEnabled && opts.checkpoint && !opts.dryRun) {
-            // Best-effort shadow commit. Failures here MUST NOT block the
-            // dispatch — the operator already has the edit applied; the
-            // checkpoint is a customer-trust safety net, not a hard gate.
-            try {
-                const absPath = result.absPath ?? resolve(opts.cwd, result.file);
-                const message = formatCheckpointMessage({
-                    taskId: opts.checkpoint.taskId,
-                    step: checkpointStep,
-                    toolName: result.layer,
-                    cwd: opts.cwd,
-                    absPath,
-                });
-                commitCheckpoint(opts.cwd, opts.checkpoint.taskId, message);
-            }
-            catch (error) {
-                const err = error instanceof Error ? error : new Error(String(error));
-                // Disable the shadow hook for the rest of this dispatch if
-                // the git binary is unavailable — repeated probes burn CPU
-                // and add no signal beyond the first failure.
-                if (err instanceof ShadowGitUnavailableError) {
-                    checkpointEnabled = false;
-                }
-                opts.checkpoint.onCheckpointError?.(err, result.file);
-            }
-            checkpointStep += 1;
-        }
-        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;
-}
-/**
- * PUGI-79 helper — resolve the preferred-layer chain for this
- * dispatch. Caller-supplied `preferredLayer` wins; otherwise the
- * detector derives from `modelTag`. Returns null when neither path
- * yields a chain (no caller hint AND no model tag) — the dispatcher
- * skips the observability hook in that case so we do not emit a
- * misleading wildcard reading.
- */
-function resolvePreferredChain(opts) {
-    if (opts.preferredLayer) {
-        // Defensive clone so caller mutations after dispatchEdit returns
-        // cannot poison subsequent calls that share the chain reference.
-        return {
-            primary: opts.preferredLayer.primary,
-            fallback: [...opts.preferredLayer.fallback],
-        };
-    }
-    if (opts.modelTag)
-        return detectEditFormat(opts.modelTag);
-    return null;
-}
-/**
- * Public helper exposed for the marker parser tests + CLI surface that
- * may want to know the resolved family without re-running the auto
- * detector.
- */
-export function resolveFamily(modelTag) {
-    if (!modelTag)
-        return 'auto';
-    const tag = modelTag.toLowerCase();
-    if (tag.startsWith('claude') || tag.startsWith('anthropic/'))
-        return 'anthropic';
-    if (tag.startsWith('gemini') || tag.startsWith('xai/') || tag.startsWith('grok'))
-        return 'gemini';
-    if (tag.startsWith('gpt') || tag.startsWith('o1') || tag.startsWith('openai/'))
-        return 'openai';
-    return 'auto';
-}
-function makeIntent(edit) {
-    switch (edit.kind) {
-        case 'layer-a':
-            return {
-                layer: 'layer-a',
-                file: edit.edit.file,
-                intentSummary: `Layer A: ${edit.edit.file} (oldString ${edit.edit.oldString.length} bytes)`,
-            };
-        case 'layer-b':
-            return {
-                layer: 'layer-b',
-                file: edit.edit.file,
-                intentSummary: `Layer B: ${edit.edit.file} (${edit.edit.edits.length} sub-edits)`,
-            };
-        case 'layer-c':
-            return {
-                layer: 'layer-c',
-                file: edit.edit.file,
-                intentSummary: `Layer C: ${edit.edit.file} (rewrite, ${edit.edit.newContents.length} bytes, baseSha ${edit.edit.baseSha256.slice(0, 12)})`,
-            };
-        case 'layer-d':
-            return {
-                layer: 'layer-d',
-                file: edit.edit.file,
-                intentSummary: `Layer D: ${edit.edit.file} op=${edit.edit.operation}`,
-            };
-    }
-}
-async function applyOne(edit, opts) {
-    const applyOpts = { cwd: opts.cwd, dryRun: opts.dryRun };
-    switch (edit.kind) {
-        case 'layer-a': {
-            const r = await applyLayerA(edit.edit, applyOpts);
-            // Backlog — Layer A.5 escalation. The fuzzy ladder is the
-            // ONLY retry path: every other Layer A failure mode (ambiguous,
-            // file_missing, identical_replacement, security gate denial)
-            // bubbles up untouched because the ladder can't fix them.
-            // ambiguous in particular MUST stay loud — a fuzzy retry on top
-            // of an ambiguous strict match would just pick one of the
-            // strict candidates silently, defeating the disambiguation
-            // contract.
-            if (!r.ok && r.reason === 'no_match' && opts.fuzzy === true) {
-                const fuzzy = await applyLayerAFuzzy(edit.edit, {
-                    cwd: opts.cwd,
-                    dryRun: opts.dryRun,
-                    minRatio: opts.fuzzyMinRatio,
-                    lengthFlex: opts.fuzzyLengthFlex,
-                });
-                const base = toResult('layer-a-fuzzy', edit.edit.file, fuzzy);
-                return {
-                    ...base,
-                    ...(fuzzy.fuzzyTier ? { fuzzyTier: fuzzy.fuzzyTier } : {}),
-                    ...(fuzzy.fuzzyScore !== undefined ? { fuzzyScore: fuzzy.fuzzyScore } : {}),
-                };
-            }
-            return toResult('layer-a', edit.edit.file, r);
-        }
-        case 'layer-b': {
-            const r = await applyLayerB(edit.edit, applyOpts);
-            return {
-                ...toResult('layer-b', edit.edit.file, r),
-                appliedCount: r.appliedCount,
-            };
-        }
-        case 'layer-c': {
-            const r = await applyLayerC(edit.edit, applyOpts);
-            return {
-                ...toResult('layer-c', edit.edit.file, r),
-                expectedSha256: r.expectedSha256,
-                actualSha256: r.actualSha256,
-            };
-        }
-        case 'layer-d': {
-            try {
-                const r = await applyLayerD(edit.edit, applyOpts);
-                return toResult('layer-d', edit.edit.file, r);
-            }
-            catch (error) {
-                if (error instanceof LayerDDeferredError) {
-                    return {
-                        layer: 'layer-d',
-                        file: edit.edit.file,
-                        ok: false,
-                        bytesWritten: 0,
-                        reason: 'layer_d_deferred',
-                        detail: error.message,
-                    };
-                }
-                return {
-                    layer: 'layer-d',
-                    file: edit.edit.file,
-                    ok: false,
-                    bytesWritten: 0,
-                    reason: 'apply_error',
-                    detail: error instanceof Error ? error.message : String(error),
-                };
-            }
-        }
-    }
-}
-function toResult(layer, file, r) {
-    return {
-        layer,
-        file,
-        ok: r.ok,
-        bytesWritten: r.bytesWritten,
-        reason: r.reason,
-        detail: r.detail,
-        matchCount: r.matchCount,
-        absPath: r.absPath,
-    };
-}
-//# sourceMappingURL=dispatch.js.map