@shrkcrft/generator 0.1.0-alpha.2

package/dist/planned-change.js

@@ -0,0 +1,507 @@
+/**
+ * Planned change model — v2.
+ *
+ * v1 templates emit CREATE-only entries via `files() → ITemplateFile[]`. The
+ * v2 model lets templates declare explicit UPDATE-style operations (append,
+ * insert-after, insert-before, replace, export) alongside CREATE entries.
+ *
+ * Each operation:
+ *   - is declared by the template as a small structured intent;
+ *   - is evaluated at plan time against the live file system;
+ *   - resolves to a concrete `IFileChange` with precomputed final contents,
+ *     a kind ("append" / "insert-after" / ... / "skip" / "conflict"),
+ *     and a reason that explains what the engine decided.
+ *
+ * Hard rules preserved by this module:
+ *   - No arbitrary code execution. Operations are data, not closures.
+ *   - No hidden post-apply hooks. Every byte written ends up in `contents` and
+ *     is shown in dry-run / plan review.
+ *   - Same write path as v1: `generator-engine.generate()` writes the
+ *     precomputed `contents`. Apply does not re-interpret the operation.
+ *   - MCP stays read-only — this module is pure logic.
+ */
+import { FileChangeType } from "./file-change.js";
+export function evaluatePlannedChange(input) {
+    const { change, absolutePath, relativePath, existing } = input;
+    const op = change.operation;
+    switch (op.kind) {
+        case 'create':
+            return evaluateCreate(op, absolutePath, relativePath, existing);
+        case 'append':
+            return evaluateAppend(op, absolutePath, relativePath, existing);
+        case 'insert-after':
+            return evaluateInsertAt(op, 'after', absolutePath, relativePath, existing);
+        case 'insert-before':
+            return evaluateInsertAt(op, 'before', absolutePath, relativePath, existing);
+        case 'replace':
+            return evaluateReplace(op, absolutePath, relativePath, existing);
+        case 'export':
+            return evaluateExport(op, absolutePath, relativePath, existing);
+        case 'ensure-import':
+            return evaluateEnsureImport(op, absolutePath, relativePath, existing);
+        case 'insert-enum-entry':
+            return evaluateInsertEnumEntry(op, absolutePath, relativePath, existing);
+        case 'insert-object-entry':
+            return evaluateInsertObjectEntry(op, absolutePath, relativePath, existing);
+        case 'insert-before-closing-brace':
+            return evaluateInsertBeforeClosingBrace(op, absolutePath, relativePath, existing);
+        case 'insert-between-anchors':
+            return evaluateInsertBetweenAnchors(op, absolutePath, relativePath, existing);
+    }
+}
+function evaluateCreate(op, absolutePath, relativePath, existing) {
+    if (existing !== null) {
+        if (existing === op.content) {
+            return mkChange(FileChangeType.Skip, absolutePath, relativePath, op.content, 'No changes (identical contents)', op);
+        }
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, op.content, 'overwrite strategy: never (file exists)', op);
+    }
+    return mkChange(FileChangeType.Create, absolutePath, relativePath, op.content, 'New file (does not exist)', op);
+}
+function evaluateAppend(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, op.snippet, 'append: target file does not exist', op);
+    }
+    const marker = op.ifMissing ?? op.snippet;
+    if (marker.length > 0 && existing.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'append: snippet already present (idempotent)', op);
+    }
+    const next = existing.endsWith('\n') ? existing + op.snippet : existing + '\n' + op.snippet;
+    return mkChange(FileChangeType.Append, absolutePath, relativePath, next, `append +${byteLen(op.snippet)}B`, op);
+}
+function evaluateInsertAt(op, position, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, op.snippet, `insert-${position}: target file does not exist`, op);
+    }
+    const marker = op.ifMissing ?? op.snippet;
+    if (marker.length > 0 && existing.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, `insert-${position}: snippet already present (idempotent)`, op);
+    }
+    const idx = existing.indexOf(op.anchor);
+    if (idx < 0) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-${position}: anchor not found`, op);
+    }
+    // Ambiguity: multiple anchors → conflict (caller must be explicit).
+    if (existing.indexOf(op.anchor, idx + op.anchor.length) >= 0) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-${position}: anchor matches multiple sites (ambiguous)`, op);
+    }
+    const cut = position === 'after' ? idx + op.anchor.length : idx;
+    const next = existing.slice(0, cut) + op.snippet + existing.slice(cut);
+    const type = position === 'after' ? FileChangeType.InsertAfter : FileChangeType.InsertBefore;
+    return mkChange(type, absolutePath, relativePath, next, `insert-${position} +${byteLen(op.snippet)}B`, op);
+}
+function evaluateReplace(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, op.replaceWith, 'replace: target file does not exist', op);
+    }
+    // Already-applied detection: if the file already contains the replacement
+    // and not the original `find`, we treat as Skip (idempotent).
+    const findCount = countOccurrences(existing, op.find);
+    const replaceCount = countOccurrences(existing, op.replaceWith);
+    if (findCount === 0 && replaceCount > 0) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'replace: already applied', op);
+    }
+    if (findCount === 0) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, 'replace: find text not found', op);
+    }
+    const expected = op.expectMatches ?? 1;
+    if (findCount !== expected) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `replace: expected ${expected} match(es), found ${findCount}`, op);
+    }
+    const next = replaceAllLiteral(existing, op.find, op.replaceWith);
+    return mkChange(FileChangeType.Replace, absolutePath, relativePath, next, `replace ${findCount}×`, op);
+}
+function evaluateExport(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, buildExportLine(op), 'export: target barrel file does not exist', op);
+    }
+    const line = buildExportLine(op);
+    const marker = op.ifMissing ?? line;
+    if (existing.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'export: already present (idempotent)', op);
+    }
+    const next = existing.endsWith('\n') ? existing + line + '\n' : existing + '\n' + line + '\n';
+    return mkChange(FileChangeType.Export, absolutePath, relativePath, next, `export +1 line`, op);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function mkChange(type, absolutePath, relativePath, contents, reason, operation) {
+    return {
+        type,
+        absolutePath,
+        relativePath,
+        contents,
+        reason,
+        sizeBytes: byteLen(contents),
+        operation,
+    };
+}
+function byteLen(s) {
+    return Buffer.byteLength(s, 'utf8');
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let from = 0;
+    while (true) {
+        const i = haystack.indexOf(needle, from);
+        if (i < 0)
+            return count;
+        count += 1;
+        from = i + needle.length;
+    }
+}
+function replaceAllLiteral(haystack, find, replaceWith) {
+    if (find.length === 0)
+        return haystack;
+    let out = '';
+    let from = 0;
+    while (true) {
+        const i = haystack.indexOf(find, from);
+        if (i < 0) {
+            out += haystack.slice(from);
+            return out;
+        }
+        out += haystack.slice(from, i) + replaceWith;
+        from = i + find.length;
+    }
+}
+function buildExportLine(op) {
+    if (op.symbols && op.symbols.length > 0) {
+        return `export { ${op.symbols.join(', ')} } from '${op.from}';`;
+    }
+    return `export * from '${op.from}';`;
+}
+/**
+ * True if a change kind is an UPDATE-like operation (writes to an existing
+ * file via a structural mutation). CREATE/Skip/Conflict/legacy-Update are not
+ * update-like in the v2 sense.
+ */
+export function isUpdateLike(type) {
+    return (type === FileChangeType.Append ||
+        type === FileChangeType.InsertAfter ||
+        type === FileChangeType.InsertBefore ||
+        type === FileChangeType.Replace ||
+        type === FileChangeType.Export);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Higher-level primitive evaluators
+// ─────────────────────────────────────────────────────────────────────────────
+function evaluateEnsureImport(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'ensure-import: target file does not exist', op);
+    }
+    const desiredSymbols = [...(op.symbols ?? [])].filter((s) => s.length > 0);
+    const fromSpec = op.from;
+    const importRegex = buildImportRegex(fromSpec, op.typeOnly ?? false);
+    const existingMatches = matchAll(existing, importRegex);
+    const knownSymbols = new Set();
+    let knownDefault = null;
+    let knownNamespace = null;
+    for (const m of existingMatches) {
+        const defBinding = m.groups?.['def'];
+        const nsBinding = m.groups?.['ns'];
+        const named = m.groups?.['named'];
+        if (defBinding)
+            knownDefault = defBinding;
+        if (nsBinding)
+            knownNamespace = nsBinding;
+        if (named) {
+            for (const piece of named.split(',')) {
+                const sym = piece.replace(/^\s*(?:type\s+)?/, '').replace(/\s+as\s+.*$/, '').trim();
+                if (sym.length > 0)
+                    knownSymbols.add(sym);
+            }
+        }
+    }
+    const wantsDefault = op.defaultBinding && op.defaultBinding.length > 0
+        ? op.defaultBinding
+        : null;
+    const wantsNamespace = op.namespaceBinding && op.namespaceBinding.length > 0
+        ? op.namespaceBinding
+        : null;
+    const missingSymbols = desiredSymbols.filter((s) => !knownSymbols.has(s));
+    const needsDefault = wantsDefault !== null && knownDefault !== wantsDefault;
+    const needsNamespace = wantsNamespace !== null && knownNamespace !== wantsNamespace;
+    if (missingSymbols.length === 0 &&
+        !needsDefault &&
+        !needsNamespace) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'ensure-import: already present (idempotent)', op);
+    }
+    // Compose a new import line. If there is an existing line we can merge into,
+    // append the missing symbols to it; otherwise insert a fresh import at the
+    // top of the file (after the leading comment block / shebang if any).
+    if (existingMatches.length === 1 && wantsDefault === null && wantsNamespace === null) {
+        const m = existingMatches[0];
+        const namedGroup = m.groups?.['named'] ?? '';
+        const merged = mergeNamedSymbols(namedGroup, missingSymbols);
+        const newLine = m[0].replace(/\{[^}]*\}/, `{ ${merged} }`);
+        const next = existing.slice(0, m.index) + newLine + existing.slice(m.index + m[0].length);
+        return mkChange(FileChangeType.InsertAfter, absolutePath, relativePath, next, `ensure-import: merged ${missingSymbols.length} symbol(s) into existing import`, op);
+    }
+    if (existingMatches.length > 1) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `ensure-import: ${existingMatches.length} import lines reference "${fromSpec}" (ambiguous)`, op);
+    }
+    const importLine = buildImportLine(fromSpec, op.typeOnly ?? false, desiredSymbols, wantsDefault, wantsNamespace);
+    const insertAt = findImportInsertionPoint(existing);
+    const next = existing.slice(0, insertAt) + importLine + '\n' + existing.slice(insertAt);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `ensure-import: added "${fromSpec}"`, op);
+}
+function evaluateInsertEnumEntry(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-enum-entry: target file does not exist', op);
+    }
+    const enumBlock = findEnumBlock(existing, op.enumName);
+    if (!enumBlock) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-enum-entry: enum "${op.enumName}" not found`, op);
+    }
+    if (enumBlock.duplicate) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-enum-entry: enum "${op.enumName}" appears multiple times (ambiguous)`, op);
+    }
+    const body = existing.slice(enumBlock.openIdx + 1, enumBlock.closeIdx);
+    if (new RegExp(`\\b${escapeRegex(op.entryName)}\\s*=`).test(body)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, `insert-enum-entry: ${op.enumName}.${op.entryName} already present (idempotent)`, op);
+    }
+    const indent = detectIndent(body) || '  ';
+    const trailingTrim = body.replace(/[\s,]+$/, '');
+    const needsComma = trailingTrim.length > 0;
+    const valueLiteral = `'${op.entryValue.replace(/'/g, "\\'")}'`;
+    const insertion = `${needsComma ? ',\n' : '\n'}${indent}${op.entryName} = ${valueLiteral}`;
+    const next = existing.slice(0, enumBlock.openIdx + 1 + trailingTrim.length) +
+        insertion +
+        existing.slice(enumBlock.openIdx + 1 + trailingTrim.length);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-enum-entry: added ${op.enumName}.${op.entryName}`, op);
+}
+function evaluateInsertObjectEntry(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-object-entry: target file does not exist', op);
+    }
+    const obj = findObjectLiteralBlock(existing, op.objectName);
+    if (!obj) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-object-entry: object "${op.objectName}" not found`, op);
+    }
+    if (obj.duplicate) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-object-entry: object "${op.objectName}" appears multiple times (ambiguous)`, op);
+    }
+    const body = existing.slice(obj.openIdx + 1, obj.closeIdx);
+    if (new RegExp(`\\b${escapeRegex(op.entryKey)}\\s*:`).test(body)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, `insert-object-entry: ${op.objectName}.${op.entryKey} already present (idempotent)`, op);
+    }
+    const indent = detectIndent(body) || '  ';
+    const trailingTrim = body.replace(/[\s,]+$/, '');
+    const needsComma = trailingTrim.length > 0;
+    const insertion = `${needsComma ? ',\n' : '\n'}${indent}${op.entryKey}: ${op.entryValue}`;
+    const next = existing.slice(0, obj.openIdx + 1 + trailingTrim.length) +
+        insertion +
+        existing.slice(obj.openIdx + 1 + trailingTrim.length);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-object-entry: added ${op.objectName}.${op.entryKey}`, op);
+}
+function evaluateInsertBeforeClosingBrace(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-before-closing-brace: target file does not exist', op);
+    }
+    const marker = op.ifMissing ?? op.snippet;
+    if (marker.length > 0 && existing.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'insert-before-closing-brace: already present (idempotent)', op);
+    }
+    const block = findBlockByName(existing, op.containerName);
+    if (!block) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-before-closing-brace: container "${op.containerName}" not found`, op);
+    }
+    if (block.duplicate) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-before-closing-brace: container "${op.containerName}" appears multiple times (ambiguous)`, op);
+    }
+    const indent = detectIndent(existing.slice(block.openIdx + 1, block.closeIdx)) || '  ';
+    const insertion = `${indent}${op.snippet}\n`;
+    const next = existing.slice(0, block.closeIdx) + insertion + existing.slice(block.closeIdx);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-before-closing-brace: inserted into "${op.containerName}"`, op);
+}
+function evaluateInsertBetweenAnchors(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-between-anchors: target file does not exist', op);
+    }
+    const marker = op.ifMissing ?? op.snippet;
+    if (marker.length > 0 && existing.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, 'insert-between-anchors: already present (idempotent)', op);
+    }
+    // Anchor matching is line-bounded so anchors like `// region:body`
+    // and `// region:body:end` don't trigger false-positive ambiguity.
+    const beginMatches = findLineBoundedOccurrences(existing, op.beginAnchor);
+    if (beginMatches.length === 0) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, 'insert-between-anchors: begin anchor not found', op);
+    }
+    if (beginMatches.length > 1) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, 'insert-between-anchors: begin anchor matches multiple sites (ambiguous)', op);
+    }
+    const beginIdx = beginMatches[0];
+    const endMatches = findLineBoundedOccurrences(existing, op.endAnchor, beginIdx + op.beginAnchor.length);
+    if (endMatches.length === 0) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, 'insert-between-anchors: end anchor not found after begin anchor', op);
+    }
+    const endIdx = endMatches[0];
+    const insertionPoint = beginIdx + op.beginAnchor.length;
+    const between = existing.slice(insertionPoint, endIdx);
+    const sep = between.endsWith('\n') ? '' : '\n';
+    const next = existing.slice(0, endIdx) + sep + op.snippet + '\n' + existing.slice(endIdx);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-between-anchors: inserted between anchors`, op);
+}
+/**
+ * Return indices where `needle` appears in `haystack` AS A FULL LINE-
+ * BOUNDED OCCURRENCE: the character immediately after must be EOL or EOF.
+ * The character before must be start-of-file or a newline.
+ */
+function findLineBoundedOccurrences(haystack, needle, startAt = 0) {
+    const out = [];
+    if (needle.length === 0)
+        return out;
+    let from = startAt;
+    while (true) {
+        const i = haystack.indexOf(needle, from);
+        if (i < 0)
+            return out;
+        const afterChar = haystack[i + needle.length];
+        const beforeChar = i === 0 ? '\n' : haystack[i - 1];
+        const beforeOk = beforeChar === '\n' || beforeChar === '\r' || i === 0 ||
+            // Tolerate leading whitespace on the anchor line.
+            /[ \t]/.test(beforeChar ?? '');
+        const afterOk = afterChar === undefined || afterChar === '\n' || afterChar === '\r';
+        if (beforeOk && afterOk)
+            out.push(i);
+        from = i + needle.length;
+    }
+}
+// ─── Helpers for primitive evaluators ───────────────────────────────────────
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildImportRegex(fromSpec, typeOnly) {
+    const fromEsc = escapeRegex(fromSpec);
+    // Match: import [type] [<default>,] [* as <ns>,] [{ <named> },] from '<from>'
+    const prefix = typeOnly ? 'import\\s+type\\s+' : 'import(?:\\s+type)?\\s+';
+    return new RegExp(`${prefix}(?:(?<def>[A-Za-z_$][A-Za-z0-9_$]*)\\s*,?\\s*)?(?:\\*\\s+as\\s+(?<ns>[A-Za-z_$][A-Za-z0-9_$]*)\\s*,?\\s*)?(?:\\{(?<named>[^}]*)\\}\\s*)?from\\s+['"]${fromEsc}['"];?`, 'g');
+}
+function matchAll(input, re) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(input)) !== null) {
+        out.push(m);
+        if (m.index === re.lastIndex)
+            re.lastIndex += 1;
+    }
+    return out;
+}
+function mergeNamedSymbols(existingNamed, additions) {
+    const seen = new Set();
+    const out = [];
+    const push = (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return;
+        const key = trimmed.replace(/^type\s+/, '').replace(/\s+as\s+.*$/, '');
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(trimmed);
+    };
+    for (const piece of existingNamed.split(','))
+        push(piece);
+    for (const sym of additions)
+        push(sym);
+    return out.join(', ');
+}
+function buildImportLine(fromSpec, typeOnly, symbols, defaultBinding, namespaceBinding) {
+    const keyword = typeOnly ? 'import type' : 'import';
+    const parts = [];
+    if (defaultBinding)
+        parts.push(defaultBinding);
+    if (namespaceBinding)
+        parts.push(`* as ${namespaceBinding}`);
+    if (symbols.length > 0)
+        parts.push(`{ ${symbols.join(', ')} }`);
+    if (parts.length === 0) {
+        return `${keyword} '${fromSpec}';`;
+    }
+    return `${keyword} ${parts.join(', ')} from '${fromSpec}';`;
+}
+function findImportInsertionPoint(source) {
+    // Skip shebang + leading line comments + leading block comments.
+    let i = 0;
+    if (source.startsWith('#!')) {
+        const nl = source.indexOf('\n');
+        if (nl < 0)
+            return source.length;
+        i = nl + 1;
+    }
+    while (i < source.length) {
+        // Skip whitespace lines.
+        if (source[i] === '\n' || source[i] === '\r' || source[i] === '\t' || source[i] === ' ') {
+            i += 1;
+            continue;
+        }
+        if (source.startsWith('//', i)) {
+            const nl = source.indexOf('\n', i);
+            i = nl < 0 ? source.length : nl + 1;
+            continue;
+        }
+        if (source.startsWith('/*', i)) {
+            const end = source.indexOf('*/', i + 2);
+            if (end < 0)
+                return source.length;
+            i = end + 2;
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+function findEnumBlock(source, enumName) {
+    const re = new RegExp(`\\benum\\s+${escapeRegex(enumName)}\\s*\\{`, 'g');
+    return findBraceBlock(source, re);
+}
+function findObjectLiteralBlock(source, objectName) {
+    const re = new RegExp(`\\b(?:const|let|var)\\s+${escapeRegex(objectName)}\\b[^=]*=\\s*\\{`, 'g');
+    return findBraceBlock(source, re);
+}
+function findBlockByName(source, name) {
+    // Matches `class Name {`, `interface Name {`, `enum Name {`, `namespace Name {`.
+    const re = new RegExp(`\\b(?:class|interface|enum|namespace|module)\\s+${escapeRegex(name)}\\b[^{]*\\{`, 'g');
+    return findBraceBlock(source, re);
+}
+function findBraceBlock(source, headRegex) {
+    headRegex.lastIndex = 0;
+    const first = headRegex.exec(source);
+    if (!first)
+        return null;
+    const openIdx = first.index + first[0].length - 1;
+    const second = headRegex.exec(source);
+    const duplicate = second !== null;
+    const closeIdx = findMatchingClose(source, openIdx);
+    if (closeIdx < 0)
+        return null;
+    return { openIdx, closeIdx, duplicate };
+}
+function findMatchingClose(source, openBraceIdx) {
+    let depth = 0;
+    let i = openBraceIdx;
+    while (i < source.length) {
+        const ch = source[i];
+        if (ch === '{')
+            depth += 1;
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+        i += 1;
+    }
+    return -1;
+}
+function detectIndent(body) {
+    const match = body.match(/^([ \t]+)\S/m);
+    if (!match)
+        return null;
+    return match[1] ?? null;
+}

package/dist/saved-plan.d.ts

@@ -0,0 +1,110 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IGenerationPlan } from './generation-plan.js';
+import type { IPlannedOperation } from './planned-change.js';
+/** v1 schema marker — kept for legacy CREATE-only plans. */
+export declare const SAVED_PLAN_SCHEMA_V1 = "sharkcraft.plan/v1";
+/** v2 schema marker — emitted when any change carries a v2 operation. */
+export declare const SAVED_PLAN_SCHEMA_V2 = "sharkcraft.plan/v2";
+/** Default exported alias — points at v1 for backward-compat with consumers. */
+export declare const SAVED_PLAN_SCHEMA = "sharkcraft.plan/v1";
+export type SavedPlanSchema = typeof SAVED_PLAN_SCHEMA_V1 | typeof SAVED_PLAN_SCHEMA_V2;
+export interface ISavedPlanExpectedChange {
+    type: string;
+    relativePath: string;
+    sizeBytes: number;
+    /**
+     * v2-only — the operation intent that produced this change. Present iff
+     * the schema is `sharkcraft.plan/v2`. Tampering with this field invalidates
+     * the HMAC signature (canonical JSON includes the whole `expectedChanges`).
+     */
+    operation?: IPlannedOperation;
+}
+/**
+ * Folder operations carried by a saved plan.
+ *
+ * Folder ops are NOT files; they live alongside `expectedChanges`. The HMAC
+ * signature naturally covers them because the canonical-JSON encoding sorts
+ * keys and includes any present field. Apply executes folder ops via
+ * `applyFolderOps()` after explicit `--allow-folder-ops` (and
+ * `--allow-delete-folder` for deletes).
+ */
+export interface ISavedPlanFolderOp {
+    kind: 'rename-folder' | 'delete-folder';
+    targetPath: string;
+    newPath?: string;
+    reason?: string;
+}
+export interface ISavedPlan {
+    /** Schema marker for forward-compat. */
+    schema: SavedPlanSchema;
+    templateId: string;
+    /** Primary kebab-case name passed to the template. Optional. */
+    name?: string;
+    variables: Record<string, string>;
+    /** Absolute path of the project root the plan was created against. */
+    projectRoot: string;
+    /** ISO timestamp of when the plan was saved. */
+    createdAt: string;
+    /**
+     * Optional summary of the plan's expected changes at save time. Used as a
+     * sanity check during `shrk apply`; if the live plan diverges, the CLI
+     * surfaces a warning before writing.
+     */
+    expectedChanges?: ReadonlyArray<ISavedPlanExpectedChange>;
+    /**
+     * Folder operations carried alongside file changes. The HMAC
+     * signature covers this field via canonical-JSON. Apply executes these
+     * via `applyFolderOps()` only when explicit `--allow-folder-ops` (and
+     * `--allow-delete-folder` for deletes) is passed.
+     */
+    folderOps?: ReadonlyArray<ISavedPlanFolderOp>;
+    /** Optional free-form notes from whoever saved the plan. */
+    note?: string;
+    /**
+     * Optional HMAC signature. Excluded from the canonical JSON that's signed.
+     */
+    signature?: {
+        algo: 'sha256';
+        hmac: string;
+        signedAt: string;
+    };
+}
+export interface BuildSavedPlanInput {
+    templateId: string;
+    name?: string;
+    variables: Record<string, string>;
+    projectRoot: string;
+    plan: IGenerationPlan;
+    note?: string;
+    /**
+     * Folder operations to carry alongside the file plan. Tags the plan
+     * as v2.
+     */
+    folderOps?: readonly ISavedPlanFolderOp[];
+}
+/**
+ * Build a saved plan. If any change in the plan carries a v2 operation, the
+ * resulting plan is tagged `sharkcraft.plan/v2`; otherwise v1.
+ */
+export declare function buildSavedPlan(input: BuildSavedPlanInput): ISavedPlan;
+export declare function savePlanToFile(plan: ISavedPlan, filePath: string): Result<void, AppError>;
+export declare function readPlanFromFile(filePath: string): Result<ISavedPlan, AppError>;
+export interface IPlanDiff {
+    relativePath: string;
+    /** "added" | "removed" | "type-changed" | "size-changed" | "operation-changed" */
+    kind: 'added' | 'removed' | 'type-changed' | 'size-changed' | 'operation-changed';
+    detail?: string;
+}
+/**
+ * Compare the saved plan's expected changes with a freshly-computed plan's
+ * changes. Returns an empty array when they match. v2 plans additionally
+ * detect operation-intent drift (e.g. signed `append` became `replace` in
+ * the template).
+ */
+export declare function diffPlanChanges(saved: ISavedPlan, fresh: IGenerationPlan): IPlanDiff[];
+/**
+ * Folder-op divergence. Returns an empty array when saved and live
+ * folder ops match (by kind+targetPath+newPath).
+ */
+export declare function diffPlanFolderOps(saved: ISavedPlan, liveFolderOps: readonly ISavedPlanFolderOp[]): IPlanDiff[];
+//# sourceMappingURL=saved-plan.d.ts.map

package/dist/saved-plan.d.ts.map

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