mindweave 0.0.1 → 2.1.2

package/dist/tools/editCore.js

@@ -0,0 +1,283 @@
+/**
+ * editCore.ts — the pure matching/splice logic shared by the edit tool.
+ *
+ * One source of truth for HOW a find-and-replace is applied, kept pure (string in,
+ * string out — no fs, no EOL handling) so it's unit-tested once and both tools inherit
+ * the same guarantees. The tools wrap it with the disk/EOL/approval concerns; deciding
+ * WHAT to change stays the model's job.
+ *
+ * ── Matching is TIERED, and the tiers are deliberately shallow ──────────────────
+ *
+ * Two failures dominate in practice, and they need opposite treatments:
+ *
+ *   1. The model's text is right but its INDENTATION drifted (it retyped a block from
+ *      memory, or copied out of a context where leading space was normalized). An
+ *      exact matcher rejects this, the model retries with the same mistake, and a turn
+ *      burns. Tier 2 fixes it: compare line-by-line with each line trimmed.
+ *   2. The text genuinely appears more than once. No amount of cleverness resolves
+ *      that — only more context or an explicit replace_all does.
+ *
+ * The temptation is to keep adding ever-looser tiers until something always matches.
+ * That is what the widely-copied "many replacers, first hit wins" design does, and it
+ * has a known, unfixed failure mode: a loose tier silently matches the WRONG block and
+ * corrupts the file, because nothing checks whether a stricter reading was ambiguous.
+ * A wrong edit applied confidently is far worse than a refused edit, so this module
+ * takes the opposite stance:
+ *
+ *   - Tiers run strictest-first and STOP at the first tier that finds anything.
+ *     A tier that finds 2 matches reports an ambiguity; it never falls through to a
+ *     looser tier hoping for a cleaner answer, because "looser" only ever means "more
+ *     ways to be wrong".
+ *   - Every tier counts matches across the WHOLE text before touching anything, so
+ *     ambiguity is detected rather than raced past.
+ *   - No block-anchor tier (match on first/last line, guess the middle). That is the
+ *     specific mechanism behind the corruption reports, and the cases it rescues are
+ *     exactly the cases most likely to hit the wrong function.
+ *
+ * When a match can't be made unambiguously, the failure carries the actual candidate
+ * LOCATIONS back to the model (see `describeMatches`), so its retry is informed rather
+ * than another guess at the same string.
+ */
+/** Normalize CRLF → LF so a model's LF `old_string` matches a CRLF file. */
+export function normalizeLf(s) {
+    return s.replace(/\r\n/g, "\n");
+}
+/** Count non-overlapping occurrences of `needle` in `haystack`. */
+export function occurrences(haystack, needle) {
+    if (needle === "")
+        return 0;
+    let count = 0;
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            return count;
+        count++;
+        from = at + needle.length;
+    }
+}
+/** 1-based line number of a char offset. */
+export function lineAt(text, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < text.length; i++)
+        if (text[i] === "\n")
+            line++;
+    return line;
+}
+/** Every exact occurrence of `needle`, as spans. */
+function exactMatches(haystack, needle) {
+    const out = [];
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            return out;
+        out.push({ start: at, end: at + needle.length, line: lineAt(haystack, at) });
+        from = at + needle.length;
+    }
+}
+/**
+ * Every occurrence where each line matches after trimming (pure).
+ *
+ * This is the one concession to imprecision, and it is a narrow one: the SEQUENCE of
+ * lines and their trimmed content must correspond exactly, so only the surrounding
+ * whitespace is forgiven. It cannot skip lines, reorder them, or match a different
+ * number of them, which is what keeps it from wandering onto the wrong block the way a
+ * first-line/last-line anchor does.
+ *
+ * The span returned covers the file's OWN lines, so the replacement splices against
+ * real file text and the file's indentation is never silently rewritten.
+ */
+function lineTrimmedMatches(haystack, needle) {
+    const needleLines = needle.split("\n");
+    // A trailing newline in the needle produces an empty last element that should not be
+    // required to correspond to a real line.
+    if (needleLines.length > 1 && needleLines[needleLines.length - 1] === "")
+        needleLines.pop();
+    if (needleLines.length === 0)
+        return [];
+    const wanted = needleLines.map((l) => l.trim());
+    const fileLines = haystack.split("\n");
+    // Char offset of the start of each line, so a line index converts back to a span.
+    const offsets = [];
+    let acc = 0;
+    for (const l of fileLines) {
+        offsets.push(acc);
+        acc += l.length + 1; // +1 for the newline
+    }
+    const out = [];
+    for (let i = 0; i + wanted.length <= fileLines.length; i++) {
+        let hit = true;
+        for (let j = 0; j < wanted.length; j++) {
+            if (fileLines[i + j].trim() !== wanted[j]) {
+                hit = false;
+                break;
+            }
+        }
+        if (!hit)
+            continue;
+        const start = offsets[i];
+        const lastIdx = i + wanted.length - 1;
+        // End at the last matched line's end, excluding its newline — mirrors how an exact
+        // match that stops mid-file behaves.
+        const end = offsets[lastIdx] + fileLines[lastIdx].length;
+        out.push({ start, end, line: i + 1 });
+        i = lastIdx; // non-overlapping
+    }
+    return out;
+}
+/**
+ * Locate `needle` in `haystack`, strictest tier first (pure).
+ *
+ * Stops at the FIRST tier that finds anything at all — including a tier that finds too
+ * many. Falling through an ambiguous exact match to a looser tier is precisely how a
+ * matcher ends up confidently editing the wrong place.
+ */
+export function findMatches(haystack, needle) {
+    const exact = exactMatches(haystack, needle);
+    if (exact.length > 0)
+        return { tier: "exact", matches: exact };
+    const trimmed = lineTrimmedMatches(haystack, needle);
+    if (trimmed.length > 0)
+        return { tier: "line-trimmed", matches: trimmed };
+    return { tier: "exact", matches: [] };
+}
+/** Context lines shown around each candidate, and how far that will grow to make the
+ *  candidates tell each other apart. */
+const CONTEXT_LINES = 2;
+const MAX_CONTEXT_LINES = 10;
+/**
+ * Render the candidate locations for the model (pure).
+ *
+ * The reason this exists: an error that says only "matches 2 places" tells the model
+ * which RULE it broke but nothing it can act on, so its retry is another guess about a
+ * file it may have read many turns ago. Observed consequence — a retry that differed
+ * from the original attempt by a single newline, then failed identically, costing two
+ * round trips to reach a string the model could have copied straight out of this text.
+ *
+ * With the candidates in front of it the model can either lift a unique anchor
+ * verbatim, or see that every occurrence should change and pass `replace_all`.
+ */
+export function describeMatches(haystack, matches, max = 4) {
+    const lines = haystack.split("\n");
+    const shown = matches.slice(0, max);
+    const window = (m, pad) => ({
+        from: Math.max(1, m.line - pad),
+        to: Math.min(lines.length, m.line + pad),
+    });
+    /**
+     * The comparable substance of a candidate's window.
+     *
+     * Line numbers are excluded because they differ by construction, and blank lines and
+     * indentation are excluded because differing only in those is not a difference the
+     * model can build a unique `old_string` out of. What counts as "distinguishable" here
+     * has to mean "gives the model something to anchor on", or the widening loop stops as
+     * soon as two windows are technically unequal and hands back two blocks that are, for
+     * every practical purpose, the same.
+     */
+    const contentOf = (m, pad) => {
+        const { from, to } = window(m, pad);
+        return lines
+            .slice(from - 1, to)
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .join("\n");
+    };
+    // Widen the window until the candidates are actually DISTINGUISHABLE. Duplicated code
+    // usually comes with duplicated surroundings — two identical helpers on two similar
+    // classes — so a fixed window can render every candidate the same and leave the model
+    // exactly where it started, with no unique anchor to lift. Growing until they differ
+    // is what makes this report useful rather than merely informative.
+    let pad = CONTEXT_LINES;
+    while (pad < MAX_CONTEXT_LINES && new Set(shown.map((m) => contentOf(m, pad))).size < shown.length) {
+        pad += 2;
+    }
+    const blocks = shown.map((m, i) => {
+        const { from, to } = window(m, pad);
+        const body = [];
+        for (let n = from; n <= to; n++) {
+            // The match line is marked so the model can see which one is the candidate
+            // rather than having to count.
+            body.push(`${n === m.line ? ">" : " "} ${String(n).padStart(5)} | ${lines[n - 1]}`);
+        }
+        return `  ${i + 1}. line ${m.line}\n${body.join("\n")}`;
+    });
+    const more = matches.length > shown.length ? `\n\n  … and ${matches.length - shown.length} more.` : "";
+    // Stated every time rather than only when the blocks look alike. Deciding "alike" is
+    // itself unreliable — a window clipped at the start of the file always differs from
+    // one in the middle, whatever the code around them says — and a conditional that
+    // cannot be made to fire is worse than a sentence that is always true.
+    const hint = "\n\nExtend old_string with a line that differs between them (a class or function name above the block), " +
+        "or set replace_all: true if all of them should change.";
+    return blocks.join("\n\n") + more + hint;
+}
+/**
+ * Apply one exact edit to already-LF-normalized `text`. The `oldString`/`newString`
+ * are normalized here too. Returns the updated text and where the change landed, or
+ * a `reason` describing why it couldn't apply (identical / not found / ambiguous).
+ * Splices by index so a `$` in the replacement is never a special pattern.
+ */
+export function applyOneEdit(text, op) {
+    // Normalize BOTH sides to LF: the file on disk may be CRLF while the model's
+    // old_string (copied from LF text it was shown) is LF. This is a representation
+    // fix, not fuzzy matching.
+    const haystack = normalizeLf(text);
+    const needle = normalizeLf(op.oldString);
+    const replacement = normalizeLf(op.newString);
+    if (needle === "")
+        return { ok: false, reason: "old_string is empty — it must identify the text to replace" };
+    if (needle === replacement)
+        return { ok: false, reason: "old_string and new_string are identical — nothing to change" };
+    const { matches } = findMatches(haystack, needle);
+    if (matches.length === 0) {
+        return {
+            ok: false,
+            reason: "old_string not found. It must match the file's text, allowing only for differences in each line's " +
+                "leading/trailing whitespace. Re-read the file and copy the target text from what you are shown",
+        };
+    }
+    if (matches.length > 1 && !op.replaceAll) {
+        // Hand back WHERE, not just how many. See `describeMatches`.
+        return {
+            ok: false,
+            reason: `old_string matches ${matches.length} places. Either extend it with surrounding lines until it is ` +
+                `unique, or set replace_all: true to change every occurrence. The candidates:\n\n` +
+                describeMatches(haystack, matches),
+        };
+    }
+    // Splice by index, right-to-left so earlier spans keep their offsets. Never via
+    // string.replace: a `$` in the replacement would be read as a pattern reference.
+    const targets = op.replaceAll ? matches : [matches[0]];
+    let updated = haystack;
+    for (let i = targets.length - 1; i >= 0; i--) {
+        const m = targets[i];
+        updated = updated.slice(0, m.start) + replacement + updated.slice(m.end);
+    }
+    const changeStart = targets[0].start;
+    const changeEnd = targets[targets.length - 1].start + replacement.length;
+    return { ok: true, updated, count: targets.length, changeStart, changeEnd };
+}
+/**
+ * Apply edits in order to normalized `text`, each seeing the result of the one
+ * before (so a later edit can target text an earlier edit produced). ATOMIC: the
+ * first failure aborts the whole sequence with the offending edit's index and
+ * reason — the caller writes nothing, so a file is never left half-edited.
+ */
+export function applyEditSequence(text, ops) {
+    let current = normalizeLf(text);
+    let total = 0;
+    let spanStart = -1;
+    let spanEnd = 0;
+    for (let i = 0; i < ops.length; i++) {
+        const r = applyOneEdit(current, ops[i]);
+        if (!r.ok)
+            return { ok: false, index: i, reason: r.reason };
+        current = r.updated;
+        total += r.count;
+        if (spanStart < 0 && r.changeStart >= 0)
+            spanStart = r.changeStart;
+        spanEnd = Math.max(spanEnd, r.changeEnd);
+    }
+    return { ok: true, updated: current, total, spanStart: Math.max(0, spanStart), spanEnd };
+}
+//# sourceMappingURL=editCore.js.map

package/dist/tools/editCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editCore.js","sourceRoot":"","sources":["../../src/tools/editCore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAoCH,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,OAAO,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,MAAc;IAC1D,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,CAAC,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,SAAS,CAAC;QACR,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC5B,KAAK,EAAE,CAAC;QACR,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,MAAc;IACjD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI;YAAE,IAAI,EAAE,CAAC;IACjF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oDAAoD;AACpD,SAAS,YAAY,CAAC,QAAgB,EAAE,MAAc;IACpD,MAAM,GAAG,GAAY,EAAE,CAAC;IACxB,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,SAAS,CAAC;QACR,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1B,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7E,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CAAC,QAAgB,EAAE,MAAc;IAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvC,qFAAqF;IACrF,yCAAyC;IACzC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE;QAAE,WAAW,CAAC,GAAG,EAAE,CAAC;IAC5F,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAEhD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvC,kFAAkF;IAClF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,GAAG,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,qBAAqB;IAC5C,CAAC;IAED,MAAM,GAAG,GAAY,EAAE,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3D,IAAI,GAAG,GAAG,IAAI,CAAC;QACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,IAAI,SAAS,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,GAAG,GAAG,KAAK,CAAC;gBACZ,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,mFAAmF;QACnF,qCAAqC;QACrC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAE,GAAG,SAAS,CAAC,OAAO,CAAE,CAAC,MAAM,CAAC;QAC3D,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,CAAC,GAAG,OAAO,CAAC,CAAC,kBAAkB;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,MAAc;IAC1D,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC/D,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACxC,CAAC;AAED;wCACwC;AACxC,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,OAAyB,EAAE,GAAG,GAAG,CAAC;IAClF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAEpC,MAAM,MAAM,GAAG,CAAC,CAAQ,EAAE,GAAW,EAAgC,EAAE,CAAC,CAAC;QACvE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;QAC/B,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;KACzC,CAAC,CAAC;IACH;;;;;;;;;OASG;IACH,MAAM,SAAS,GAAG,CAAC,CAAQ,EAAE,GAAW,EAAU,EAAE;QAClD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,KAAK;aACT,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;aACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC,CAAC;IAEF,sFAAsF;IACtF,oFAAoF;IACpF,sFAAsF;IACtF,qFAAqF;IACrF,mEAAmE;IACnE,IAAI,GAAG,GAAG,aAAa,CAAC;IACxB,OAAO,GAAG,GAAG,iBAAiB,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACnG,GAAG,IAAI,CAAC,CAAC;IACX,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAChC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,2EAA2E;YAC3E,+BAA+B;YAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACvG,qFAAqF;IACrF,oFAAoF;IACpF,iFAAiF;IACjF,uEAAuE;IACvE,MAAM,IAAI,GACR,0GAA0G;QAC1G,wDAAwD,CAAC;IAC3D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,EAAU;IACnD,6EAA6E;IAC7E,gFAAgF;IAChF,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IAE9C,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,4DAA4D,EAAE,CAAC;IAC9G,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6DAA6D,EAAE,CAAC;IAExH,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,oGAAoG;gBACpG,gGAAgG;SACnG,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;QACzC,6DAA6D;QAC7D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,sBAAsB,OAAO,CAAC,MAAM,+DAA+D;gBACnG,kFAAkF;gBAClF,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,iFAAiF;IACjF,MAAM,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;IACxD,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QACtB,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC;IACtC,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC;IAC1E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AAC9E,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,GAAa;IAC3D,IAAI,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;QACzC,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5D,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QACpB,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC;QACjB,IAAI,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC;YAAE,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC;QACnE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;AAC3F,CAAC"}

package/dist/tools/editFile.js

@@ -0,0 +1,183 @@
+/**
+ * editFile.ts — a surgical find-and-replace on one file.
+ *
+ * The workhorse mutating tool. It replaces an exact `old_string` with
+ * `new_string`. Reliability comes from the tool REFUSING bad edits, not from the
+ * model being careful — the three refusals below make the classic failure modes
+ * (editing a file you never read, a stale/typo'd match, an ambiguous match)
+ * structurally impossible:
+ *
+ *  - read-before-edit: the file must have been read this session, so the model's
+ *    `old_string` is copied from real content, not imagined.
+ *  - must-exist: zero matches errors instead of silently doing nothing, so the
+ *    model learns its match was wrong.
+ *  - unique-match: more than one match (without replace_all) errors and hands back
+ *    WHERE the candidates are, so an edit never lands in the wrong place and the
+ *    retry is informed rather than another guess.
+ *
+ * Matching is exact first, then line-trimmed — and stops there. It is deliberately not
+ * a stack of ever-looser matchers: past a point, "looser" only means "more ways to edit
+ * the wrong block", which is a corruption bug rather than a convenience. The reasoning,
+ * and what is deliberately NOT implemented, lives in editCore.ts.
+ * (Deciding *what* to change is the model's job; this tool only applies it.)
+ */
+import { promises as fs } from "node:fs";
+import { recordWrite, relativize } from "./paths.js";
+import { editDetail, lineCount, magnitude, rangeLabel, withScope } from "./detail.js";
+import { applyEol } from "./eol.js";
+import { applyOneEdit } from "./editCore.js";
+import { prepareEditTarget, fail, failQuietly, errText } from "./editTarget.js";
+export const editFile = {
+    name: "edit_file",
+    readOnly: false,
+    // The old wording said `old_string` "must match the file's text", which undersold the
+    // matcher in a way that costs real work: matching is tiered, so indentation and line
+    // endings are already forgiven. A model told it needs the exact bytes re-reads whole
+    // files to get them and retries edits that would have applied. What the tiers do NOT
+    // forgive is stated just as plainly, because a matcher that sounds infinitely lenient
+    // invites the sloppy input that makes a wrong-place edit possible. See editCore.ts.
+    description: "Replace a string in a file with another. This is the DEFAULT editing tool: reach for " +
+        "it whenever you are changing one place in a file. Read the file first. " +
+        "`old_string` has to identify exactly ONE place, and it is matched on content rather " +
+        "than on formatting: if an exact match is not found, each line is compared with its " +
+        "leading and trailing whitespace ignored, and line endings are normalized on both " +
+        "sides. So you do not need to reproduce a file's exact indentation, and a CRLF file " +
+        "is not a problem. What is never forgiven is a skipped, reordered, or extra line. " +
+        "If `old_string` matches SEVERAL places the file is left untouched and you get the " +
+        "candidate locations back with surrounding context: pick one and include enough " +
+        "nearby lines to make it unique, or set `replace_all` to change every occurrence. " +
+        "If the SAME file needs changing in several separate places, use multi_edit instead " +
+        "of calling this repeatedly. Use write_file only to create a new file or replace one " +
+        "wholesale.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["path", "old_string", "new_string"],
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the file, absolute or relative to the working directory.",
+            },
+            old_string: {
+                type: "string",
+                description: "The exact text to replace. Include enough surrounding lines to make it unique.",
+            },
+            new_string: {
+                type: "string",
+                description: "The replacement text. Use an empty string to delete old_string.",
+            },
+            replace_all: {
+                type: "boolean",
+                description: "Replace every occurrence instead of requiring a unique match. Default false.",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const rawPath = typeof args.path === "string" ? args.path.trim() : "";
+        if (!rawPath)
+            return fail("`path` is required.");
+        if (typeof args.old_string !== "string" || args.old_string === "") {
+            return fail("`old_string` is required and must not be empty — it identifies the text to replace.");
+        }
+        if (typeof args.new_string !== "string") {
+            return fail("`new_string` is required (use an empty string to delete old_string).");
+        }
+        const oldString = args.old_string;
+        const newString = args.new_string;
+        const replaceAll = args.replace_all === true;
+        if (oldString === newString) {
+            return fail("`old_string` and `new_string` are identical — nothing to change.");
+        }
+        const target = await prepareEditTarget(ctx, rawPath, "editing");
+        if (!target.ok)
+            return target.error;
+        const { filePath, content, eol } = target;
+        // Match line-ending-agnostically. The file on disk may use CRLF (Windows)
+        // while the model's old_string — copied from text it was shown — uses LF; an
+        // exact byte match would then fail on every multi-line edit. Normalizing the
+        // CR the model can't see is a representation fix, not fuzzy matching: we still
+        // match whitespace and indentation exactly (handled in editCore). The file's
+        // own line endings are preserved on write.
+        const applied = applyOneEdit(content, { oldString, newString, replaceAll });
+        // A match that didn't land is the model's to correct — it gets the reason and the
+        // candidate locations, and retries. Not the user's business, so it stays off screen.
+        if (!applied.ok)
+            return failQuietly(`${applied.reason} (in ${rawPath}).`);
+        const { updated: updatedNorm, count, changeStart, changeEnd } = applied;
+        const updated = applyEol(updatedNorm, eol);
+        // Snapshot the pre-edit bytes for /undo before touching disk.
+        ctx.checkpoints?.backup(filePath, content, updated);
+        try {
+            await fs.writeFile(filePath, updated, "utf8");
+        }
+        catch (error) {
+            return fail(`could not write ${rawPath}: ${errText(error)}`);
+        }
+        // Still seen+touched this session — record the new state (with the edited region
+        // as this file's focus, so a large file localizes to it in the working set).
+        await recordWrite(ctx, filePath, {
+            start: charToLine(updatedNorm, Math.max(0, changeStart)) + 1,
+            end: charToLine(updatedNorm, changeEnd) + 1,
+        });
+        const shown = relativize(ctx, filePath);
+        const n = replaceAll ? count : 1;
+        const plural = n === 1 ? "" : "s";
+        // Hand back the changed region WITH fresh line numbers. This is what stops the
+        // model from re-reading the whole file after every edit (the loop that bloats a
+        // multi-edit task): it can target its next edit straight from this snippet.
+        const window = numberedWindow(updatedNorm, Math.max(0, changeStart), changeEnd);
+        const span = replaceAll && n > 1 ? ` (showing the first of ${n} sites)` : "";
+        // The scope of the change — WHERE and HOW MUCH — so the row shows more than a bare
+        // diff: the line range touched (or "N sites" for a spread replace_all) and ± lines.
+        const startLine = charToLine(updatedNorm, Math.max(0, changeStart)) + 1;
+        const endLine = charToLine(updatedNorm, changeEnd) + 1;
+        const removed = lineCount(oldString) * n;
+        const added = lineCount(newString) * n;
+        const scope = replaceAll && n > 1
+            ? `${n} sites · ${magnitude(removed, added)}`
+            : `${rangeLabel(startLine, endLine)} · ${magnitude(removed, added)}`;
+        return {
+            output: `Edited ${shown}: ${n} replacement${plural}.\n` +
+                `Updated region${span} — line-numbered so you can make further edits without re-reading:\n${window}`,
+            summary: `edited ${shown} · ${scope}`,
+            detail: withScope(scope, editDetail(oldString, newString)),
+        };
+    },
+};
+/**
+ * Render the lines spanning [startChar, endChar] in `text`, plus `pad` lines of
+ * context on each side, with 1-based right-aligned line numbers. Pure and indexed
+ * on the normalized (LF) text, so it's independent of the file's real EOL. Bounded
+ * by `maxLines` so a sweeping replace can't flood the result.
+ */
+export function numberedWindow(text, startChar, endChar, pad = 4, maxLines = 30) {
+    const lines = text.split("\n");
+    const startLine = charToLine(text, startChar);
+    const endLine = charToLine(text, endChar);
+    const from = Math.max(0, startLine - pad);
+    let to = Math.min(lines.length - 1, endLine + pad);
+    let truncated = false;
+    if (to - from + 1 > maxLines) {
+        to = from + maxLines - 1;
+        truncated = true;
+    }
+    const width = String(to + 1).length;
+    const out = [];
+    for (let i = from; i <= to; i++) {
+        out.push(`${String(i + 1).padStart(width)}  ${lines[i] ?? ""}`);
+    }
+    if (truncated)
+        out.push("    … (region continues; re-read the file if you need the rest)");
+    return out.join("\n");
+}
+/** The 0-based line a character offset falls on (count of newlines before it). */
+export function charToLine(text, charIndex) {
+    let line = 0;
+    const limit = Math.min(charIndex, text.length);
+    for (let i = 0; i < limit; i++) {
+        if (text[i] === "\n")
+            line++;
+    }
+    return line;
+}
+//# sourceMappingURL=editFile.js.map

package/dist/tools/editFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editFile.js","sourceRoot":"","sources":["../../src/tools/editFile.ts"],"names":[],"mappings":"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"}

package/dist/tools/editRipple.js

@@ -0,0 +1,126 @@
+import { chassisForPath } from "./chassisMux.js";
+import { relativize } from "./paths.js";
+/** Edited files checked per step. An edit touching more files than this is a sweeping
+ *  refactor, where a per-file check is the wrong instrument anyway. */
+export const MAX_EDITED = 8;
+/** Reverse dependents pulled in on top. The point is to catch the broken caller, not to
+ *  type-check the repo: a widely-imported file has hundreds and checking them all would
+ *  cost more than the edit did. */
+export const MAX_DEPENDENTS = 12;
+/** Diagnostics quoted into the note. Past this the model needs to look, not read. */
+export const MAX_REPORTED = 20;
+/** Tools whose call means "a file's contents changed on disk". */
+const EDITING_TOOLS = new Set(["edit", "multi_edit", "write_file", "create_file", "apply_patch"]);
+/**
+ * The absolute paths an executed round actually edited.
+ *
+ * Driven off the CALL rather than the result body, because that is the thing that is
+ * true regardless of how a tool phrases success. A failed call is skipped: it changed
+ * nothing, and checking it would report pre-existing errors as if the edit caused them.
+ */
+export function editedPaths(results, resolve) {
+    const out = new Set();
+    for (const r of results) {
+        if (r.isError || !EDITING_TOOLS.has(r.name))
+            continue;
+        const raw = r.args?.path ?? r.args?.file_path;
+        if (typeof raw !== "string" || !raw.trim())
+            continue;
+        const abs = resolve(raw.trim());
+        if (abs)
+            out.add(abs);
+    }
+    return [...out].slice(0, MAX_EDITED);
+}
+/**
+ * Edited files plus their reverse dependents, deduped, edited-first.
+ *
+ * Edited-first is deliberate: if the cap bites, the files the model just touched are
+ * the ones it must not lose. Dependents are the bonus that catches the broken caller.
+ */
+export async function rippleTargets(ctx, edited) {
+    const seen = new Set(edited);
+    const extra = [];
+    for (const abs of edited) {
+        const chassis = chassisForPath(ctx, abs);
+        if (!chassis)
+            continue;
+        let deps = [];
+        try {
+            deps = await chassis.dependents(abs);
+        }
+        catch {
+            // The graph is an assistant, never a gate: if it cannot answer, the edited files
+            // are still checked. A ripple failure must not cost the model its diagnostics.
+            continue;
+        }
+        for (const d of deps) {
+            if (seen.has(d) || extra.length >= MAX_DEPENDENTS)
+                continue;
+            seen.add(d);
+            extra.push(d);
+        }
+    }
+    return [...edited, ...extra];
+}
+/**
+ * Render the note the model receives, or "" when there is nothing worth saying.
+ *
+ * Errors first, then warnings — a turn that produced one type error and nine lint
+ * warnings should not bury the type error. `edited` is named separately so the model
+ * can tell "you broke this file you just wrote" from "you broke a caller over there",
+ * which are different problems with different fixes.
+ */
+export function formatRippleNote(diags, editedSet, label) {
+    if (diags.length === 0)
+        return "";
+    const rank = (d) => (d.severity === "error" ? 0 : 1);
+    const sorted = [...diags].sort((a, b) => rank(a) - rank(b));
+    const shown = sorted.slice(0, MAX_REPORTED);
+    const lines = shown.map((d) => {
+        const where = editedSet.has(d.file) ? "" : " (caller)";
+        return `- ${label(d.file)}:${d.line}${where} ${d.severity}: ${d.message}`;
+    });
+    const hidden = sorted.length - shown.length;
+    const more = hidden > 0 ? `\n(${hidden} more not shown)` : "";
+    const errors = sorted.filter((d) => d.severity === "error").length;
+    return (`[Automatic check after your edit — these are the language server's diagnostics for the ` +
+        `files you just changed and the files that import them. ${errors} error` +
+        `${errors === 1 ? "" : "s"} across ${new Set(shown.map((d) => d.file)).size} file` +
+        `${new Set(shown.map((d) => d.file)).size === 1 ? "" : "s"}. Fix what you caused; a ` +
+        `diagnostic in a file marked (caller) means your change broke code elsewhere. If one ` +
+        `was already there before your edit, say so rather than silently fixing unrelated ` +
+        `code.]\n${lines.join("\n")}${more}`);
+}
+/**
+ * The whole pass: what did this round edit, what does that reach, and is anything broken.
+ *
+ * Returns "" whenever there is nothing to say — no edits, no chassis, no diagnostics.
+ * Never throws: this runs inside the turn loop and a failure here must cost the user
+ * nothing more than the check itself.
+ */
+export async function rippleCheck(ctx, results, resolve) {
+    try {
+        const edited = editedPaths(results, resolve);
+        if (edited.length === 0)
+            return "";
+        const targets = await rippleTargets(ctx, edited);
+        const all = [];
+        await Promise.all(targets.map(async (abs) => {
+            const chassis = chassisForPath(ctx, abs);
+            if (!chassis)
+                return;
+            try {
+                all.push(...(await chassis.diagnostics(abs)));
+            }
+            catch {
+                // One unreachable server must not lose the diagnostics from the others.
+            }
+        }));
+        return formatRippleNote(all, new Set(edited), (abs) => relativize(ctx, abs));
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=editRipple.js.map

package/dist/tools/editRipple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editRipple.js","sourceRoot":"","sources":["../../src/tools/editRipple.ts"],"names":[],"mappings":"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"}