@shrkcrft/generator 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/package-delegate-plan.js

@@ -0,0 +1,253 @@
+/**
+ * Package a delegate worker's raw edit into a SIGNED-ready synthetic plan.
+ *
+ * This is the deterministic chokepoint between a stochastic worker and the
+ * write path. It:
+ *   1. drops ops whose `kind` is not in the recipe's `allowedOps` (reported,
+ *      never applied);
+ *   2. validates every remaining op's fields against the real operation union —
+ *      a malformed op refuses the whole package (the worker must retry);
+ *   3. evaluates the ops against the live file system via the SAME
+ *      `evaluateSavedPlanInPlace` apply uses, so anchor-not-found / ambiguous /
+ *      file-missing all surface as conflicts BEFORE anything is signed;
+ *   4. builds an `ISavedPlan` (templateId `__delegate/<recipe>`) the caller
+ *      signs + applies through the unmodified apply pipeline.
+ *
+ * No model, no network. The raw-op input type is declared locally so the
+ * generator layer carries no dependency on `@shrkcrft/ai`.
+ */
+import { err, ok, AppErrorImpl, ERROR_CODES } from '@shrkcrft/core';
+import { buildSavedPlan } from "./saved-plan.js";
+import { evaluateSavedPlanInPlace } from "./synthetic-plan.js";
+export const DELEGATE_TEMPLATE_PREFIX = '__delegate/';
+export function packageDelegatePlan(input) {
+    const allowed = new Set(input.allowedOps);
+    const droppedOps = [];
+    const expectedChanges = [];
+    for (const raw of input.ops) {
+        const kind = raw.operation.kind;
+        if (!allowed.has(kind)) {
+            droppedOps.push({
+                kind,
+                targetPath: raw.targetPath,
+                reason: `op kind "${kind}" is not in the recipe's allowedOps`,
+            });
+            continue;
+        }
+        const coerced = coerceOperation(raw.operation);
+        if (!coerced.ok) {
+            return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `delegate op for ${raw.targetPath}: ${coerced.error}`));
+        }
+        expectedChanges.push({
+            type: 'pending',
+            relativePath: raw.targetPath,
+            sizeBytes: 0,
+            operation: coerced.value,
+        });
+    }
+    if (expectedChanges.length === 0) {
+        return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, droppedOps.length > 0
+            ? `delegate edit had ${droppedOps.length} op(s), all of disallowed kinds`
+            : 'delegate edit contained no operations'));
+    }
+    // Evaluate against the live FS through the SAME path apply uses — conflicts
+    // (ambiguous anchor, file missing, replace 0/>N) surface here, before signing.
+    const draft = {
+        schema: 'sharkcraft.plan/v2',
+        templateId: `${DELEGATE_TEMPLATE_PREFIX}${input.recipeId}`,
+        variables: {},
+        projectRoot: input.projectRoot,
+        createdAt: new Date().toISOString(),
+        expectedChanges,
+    };
+    const generation = evaluateSavedPlanInPlace(draft, input.projectRoot);
+    if (generation.hasConflicts) {
+        return ok({ generation, droppedOps, ready: false });
+    }
+    const plan = buildSavedPlan({
+        templateId: draft.templateId,
+        variables: {},
+        projectRoot: input.projectRoot,
+        plan: generation,
+    });
+    return ok({ plan, generation, droppedOps, ready: true });
+}
+function coerceOperation(raw) {
+    const k = raw.kind;
+    switch (k) {
+        case 'create': {
+            const content = reqStr(raw, 'content');
+            if (content === null)
+                return fail('content');
+            const op = { kind: 'create', content };
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'append': {
+            const snippet = reqStr(raw, 'snippet');
+            if (snippet === null)
+                return fail('snippet');
+            const op = { kind: 'append', snippet };
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-after':
+        case 'insert-before': {
+            const anchor = reqStr(raw, 'anchor');
+            const snippet = reqStr(raw, 'snippet');
+            if (anchor === null)
+                return fail('anchor');
+            if (snippet === null)
+                return fail('snippet');
+            const op = { kind: k, anchor, snippet };
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'replace': {
+            const find = reqStr(raw, 'find');
+            const replaceWith = reqStrAllowEmpty(raw, 'replaceWith');
+            if (find === null)
+                return fail('find');
+            if (replaceWith === null)
+                return fail('replaceWith');
+            const op = { kind: 'replace', find, replaceWith };
+            const expectMatches = optNum(raw, 'expectMatches');
+            if (expectMatches !== undefined)
+                op.expectMatches = expectMatches;
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'export': {
+            const from = reqStr(raw, 'from');
+            if (from === null)
+                return fail('from');
+            const op = { kind: 'export', from };
+            const symbols = optStrArr(raw, 'symbols');
+            if (symbols)
+                op.symbols = symbols;
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'ensure-import': {
+            const from = reqStr(raw, 'from');
+            if (from === null)
+                return fail('from');
+            const op = { kind: 'ensure-import', from };
+            const symbols = optStrArr(raw, 'symbols');
+            if (symbols)
+                op.symbols = symbols;
+            const typeOnly = optBool(raw, 'typeOnly');
+            if (typeOnly !== undefined)
+                op.typeOnly = typeOnly;
+            addOptStr(op, raw, 'defaultBinding');
+            addOptStr(op, raw, 'namespaceBinding');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-enum-entry': {
+            const enumName = reqStr(raw, 'enumName');
+            const entryName = reqStr(raw, 'entryName');
+            const entryValue = reqStr(raw, 'entryValue');
+            if (enumName === null)
+                return fail('enumName');
+            if (entryName === null)
+                return fail('entryName');
+            if (entryValue === null)
+                return fail('entryValue');
+            const op = { kind: 'insert-enum-entry', enumName, entryName, entryValue };
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-object-entry': {
+            const objectName = reqStr(raw, 'objectName');
+            const entryKey = reqStr(raw, 'entryKey');
+            const entryValue = reqStr(raw, 'entryValue');
+            if (objectName === null)
+                return fail('objectName');
+            if (entryKey === null)
+                return fail('entryKey');
+            if (entryValue === null)
+                return fail('entryValue');
+            const op = { kind: 'insert-object-entry', objectName, entryKey, entryValue };
+            const shorthand = optBool(raw, 'shorthand');
+            if (shorthand !== undefined)
+                op.shorthand = shorthand;
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-array-entry': {
+            const arrayName = reqStr(raw, 'arrayName');
+            const entryValue = reqStr(raw, 'entryValue');
+            if (arrayName === null)
+                return fail('arrayName');
+            if (entryValue === null)
+                return fail('entryValue');
+            const op = { kind: 'insert-array-entry', arrayName, entryValue };
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-before-closing-brace': {
+            const containerName = reqStr(raw, 'containerName');
+            const snippet = reqStr(raw, 'snippet');
+            if (containerName === null)
+                return fail('containerName');
+            if (snippet === null)
+                return fail('snippet');
+            const op = { kind: 'insert-before-closing-brace', containerName, snippet };
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        case 'insert-between-anchors': {
+            const beginAnchor = reqStr(raw, 'beginAnchor');
+            const endAnchor = reqStr(raw, 'endAnchor');
+            const snippet = reqStr(raw, 'snippet');
+            if (beginAnchor === null)
+                return fail('beginAnchor');
+            if (endAnchor === null)
+                return fail('endAnchor');
+            if (snippet === null)
+                return fail('snippet');
+            const op = { kind: 'insert-between-anchors', beginAnchor, endAnchor, snippet };
+            addOptStr(op, raw, 'ifMissing');
+            addOptStr(op, raw, 'description');
+            return { ok: true, value: op };
+        }
+        default:
+            return { ok: false, error: `unsupported op kind "${k}"` };
+    }
+}
+function fail(field) {
+    return { ok: false, error: `"${field}" must be a non-empty string` };
+}
+function reqStr(raw, field) {
+    const v = raw[field];
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+function reqStrAllowEmpty(raw, field) {
+    const v = raw[field];
+    return typeof v === 'string' ? v : null;
+}
+function addOptStr(target, raw, field) {
+    const v = raw[field];
+    if (typeof v === 'string')
+        target[field] = v;
+}
+function optStrArr(raw, field) {
+    const v = raw[field];
+    if (Array.isArray(v) && v.every((s) => typeof s === 'string'))
+        return v;
+    return undefined;
+}
+function optBool(raw, field) {
+    const v = raw[field];
+    return typeof v === 'boolean' ? v : undefined;
+}
+function optNum(raw, field) {
+    const v = raw[field];
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}

package/dist/planned-change.d.ts

@@ -21,128 +21,8 @@
  *   - MCP stays read-only — this module is pure logic.
  */
 import { FileChangeType, type IFileChange } from './file-change.js';
-export type PlannedOperationKind = 'create' | 'append' | 'insert-after' | 'insert-before' | 'replace' | 'export' | 'ensure-import' | 'insert-enum-entry' | 'insert-object-entry' | 'insert-before-closing-brace' | 'insert-between-anchors';
-interface ICreateOperation {
-    kind: 'create';
-    content: string;
-    description?: string;
-}
-interface IAppendOperation {
-    kind: 'append';
-    /**
-     * The snippet to append at the end of the file. The engine adds a single
-     * `\n` separator between the existing trailing content and the snippet if
-     * the existing file does not already end with a newline.
-     */
-    snippet: string;
-    /**
-     * Optional idempotency marker. If the existing file already contains this
-     * string anywhere, the operation is skipped (already applied).
-     */
-    ifMissing?: string;
-    description?: string;
-}
-interface IInsertAfterOperation {
-    kind: 'insert-after';
-    /** Literal substring that must appear exactly once in the file. */
-    anchor: string;
-    /** The snippet to insert immediately after `anchor`. */
-    snippet: string;
-    /** Idempotency check; default = `snippet`. */
-    ifMissing?: string;
-    description?: string;
-}
-interface IInsertBeforeOperation {
-    kind: 'insert-before';
-    anchor: string;
-    snippet: string;
-    ifMissing?: string;
-    description?: string;
-}
-interface IReplaceOperation {
-    kind: 'replace';
-    /** Literal substring to find. */
-    find: string;
-    /** Replacement text. */
-    replaceWith: string;
-    /**
-     * If provided, the engine requires exactly this many matches; otherwise the
-     * default is exactly 1. Multiple matches without an explicit `expectMatches`
-     * is a conflict (ambiguous replace).
-     */
-    expectMatches?: number;
-    description?: string;
-}
-interface IExportOperation {
-    kind: 'export';
-    /** The symbol/path to re-export. */
-    from: string;
-    /** Optional named symbols. When omitted, emits `export * from`. */
-    symbols?: readonly string[];
-    /** Idempotency check; default = computed export line. */
-    ifMissing?: string;
-    description?: string;
-}
-interface IEnsureImportOperation {
-    kind: 'ensure-import';
-    /** Module specifier, e.g. `'./events'` or `'@app/plugin-core'`. */
-    from: string;
-    /**
-     * Named symbols to ensure. The op is a NO-OP for symbols already imported
-     * from `from`. Default import (`type: 'default'`) and namespace import
-     * (`type: 'namespace'`) are also supported via dedicated fields below.
-     */
-    symbols?: readonly string[];
-    /** Treat the import as `import type { ... }` instead of value import. */
-    typeOnly?: boolean;
-    /** Default import binding (e.g. `import Foo from 'foo'`). */
-    defaultBinding?: string;
-    /** Namespace import binding (e.g. `import * as foo from 'foo'`). */
-    namespaceBinding?: string;
-    description?: string;
-}
-interface IInsertEnumEntryOperation {
-    kind: 'insert-enum-entry';
-    /** Enum identifier, e.g. `PaginationEventType`. */
-    enumName: string;
-    /** Identifier of the new enum member, e.g. `ITEM_SELECTED`. */
-    entryName: string;
-    /** Literal string value to assign, e.g. `'pagination.itemSelected'`. */
-    entryValue: string;
-    description?: string;
-}
-interface IInsertObjectEntryOperation {
-    kind: 'insert-object-entry';
-    /** Object identifier, e.g. `FEATURE_KEYS`. */
-    objectName: string;
-    /** Key to add. */
-    entryKey: string;
-    /** Value literal (already source-formatted). */
-    entryValue: string;
-    /** When `true`, allow shorthand entries; default `false`. */
-    shorthand?: boolean;
-    description?: string;
-}
-interface IInsertBeforeClosingBraceOperation {
-    kind: 'insert-before-closing-brace';
-    /** Container identifier, e.g. an interface/class/enum name. */
-    containerName: string;
-    /** Snippet inserted immediately before the matching closing brace. */
-    snippet: string;
-    /** Optional idempotency marker (default = `snippet`). */
-    ifMissing?: string;
-    description?: string;
-}
-interface IInsertBetweenAnchorsOperation {
-    kind: 'insert-between-anchors';
-    beginAnchor: string;
-    endAnchor: string;
-    snippet: string;
-    /** Optional idempotency marker (default = `snippet`). */
-    ifMissing?: string;
-    description?: string;
-}
-export type IPlannedOperation = ICreateOperation | IAppendOperation | IInsertAfterOperation | IInsertBeforeOperation | IReplaceOperation | IExportOperation | IEnsureImportOperation | IInsertEnumEntryOperation | IInsertObjectEntryOperation | IInsertBeforeClosingBraceOperation | IInsertBetweenAnchorsOperation;
+import { type IPlannedOperation } from './operations.js';
+export * from './operations.js';
 export interface IPlannedChange {
     /** Final file path relative to project root. */
     targetPath: string;
@@ -163,5 +43,4 @@ export declare function evaluatePlannedChange(input: IEvaluateInput): IFileChang
  * update-like in the v2 sense.
  */
 export declare function isUpdateLike(type: FileChangeType): boolean;
-export {};
 //# sourceMappingURL=planned-change.d.ts.map

package/dist/planned-change.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"planned-change.d.ts","sourceRoot":"","sources":["../src/planned-change.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"planned-change.d.ts","sourceRoot":"","sources":["../src/planned-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EACL,KAAK,iBAAiB,EAOvB,MAAM,iBAAiB,CAAC;AAMzB,cAAc,iBAAiB,CAAC;AAIhC,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAMD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,cAAc,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CA8BxE;AA8SD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAQ1D"}

package/dist/planned-change.js

@@ -21,6 +21,11 @@
  *   - MCP stays read-only — this module is pure logic.
  */
 import { FileChangeType } from "./file-change.js";
+// The operation model lives in ./operations.ts. Re-export it from here — this
+// module is the public face of the planned-change pipeline, and its consumers
+// (dry-run, saved-plan, synthetic-plan, and the @shrkcrft/generator barrel)
+// import the operation types from this path.
+export * from "./operations.js";
 export function evaluatePlannedChange(input) {
     const { change, absolutePath, relativePath, existing } = input;
     const op = change.operation;
@@ -43,6 +48,8 @@ export function evaluatePlannedChange(input) {
             return evaluateInsertEnumEntry(op, absolutePath, relativePath, existing);
         case 'insert-object-entry':
             return evaluateInsertObjectEntry(op, absolutePath, relativePath, existing);
+        case 'insert-array-entry':
+            return evaluateInsertArrayEntry(op, absolutePath, relativePath, existing);
         case 'insert-before-closing-brace':
             return evaluateInsertBeforeClosingBrace(op, absolutePath, relativePath, existing);
         case 'insert-between-anchors':
@@ -298,6 +305,47 @@ function evaluateInsertObjectEntry(op, absolutePath, relativePath, existing) {
         existing.slice(obj.openIdx + 1 + trailingTrim.length);
     return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-object-entry: added ${op.objectName}.${op.entryKey}`, op);
 }
+function evaluateInsertArrayEntry(op, absolutePath, relativePath, existing) {
+    if (existing === null) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-array-entry: target file does not exist', op);
+    }
+    // Try the primary array name, then each declared alternative in order. The
+    // first cleanly-resolved (present + unambiguous) array wins. This lets a
+    // template target a project whose registration array is named differently
+    // without silently dead-ending.
+    const candidates = [op.arrayName, ...(op.arrayNameAlternatives ?? [])].filter((n) => n.length > 0);
+    let arr = null;
+    let sawAmbiguous = false;
+    for (const name of candidates) {
+        const found = findArrayLiteralBlock(existing, name);
+        if (!found)
+            continue;
+        if (found.duplicate) {
+            sawAmbiguous = true;
+            continue;
+        }
+        arr = found;
+        break;
+    }
+    if (!arr) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, unresolvedArrayReason(op, candidates, sawAmbiguous), op);
+    }
+    // Idempotency: skip when the element (or its caller-supplied marker) is
+    // already present anywhere inside the array body.
+    const body = existing.slice(arr.openIdx + 1, arr.closeIdx);
+    const marker = op.ifMissing ?? op.entryValue;
+    if (marker.length > 0 && body.includes(marker)) {
+        return mkChange(FileChangeType.Skip, absolutePath, relativePath, existing, `insert-array-entry: "${op.arrayName}" already contains entry (idempotent)`, op);
+    }
+    const indent = detectIndent(body) || '  ';
+    const trailingTrim = body.replace(/[\s,]+$/, '');
+    const needsComma = trailingTrim.length > 0;
+    const insertion = `${needsComma ? ',\n' : '\n'}${indent}${op.entryValue}`;
+    const next = existing.slice(0, arr.openIdx + 1 + trailingTrim.length) +
+        insertion +
+        existing.slice(arr.openIdx + 1 + trailingTrim.length);
+    return mkChange(FileChangeType.InsertBefore, absolutePath, relativePath, next, `insert-array-entry: added entry to ${op.arrayName}`, 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);
@@ -465,6 +513,39 @@ function findObjectLiteralBlock(source, objectName) {
     const re = new RegExp(`\\b(?:const|let|var)\\s+${escapeRegex(objectName)}\\b[^=]*=\\s*\\{`, 'g');
     return findBraceBlock(source, re);
 }
+function findArrayLiteralBlock(source, arrayName) {
+    const re = new RegExp(`\\b(?:const|let|var)\\s+${escapeRegex(arrayName)}\\b[^=]*=\\s*\\[`, 'g');
+    return findBracketBlock(source, re);
+}
+function findBracketBlock(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 = findMatchingCloseBracket(source, openIdx);
+    if (closeIdx < 0)
+        return null;
+    return { openIdx, closeIdx, duplicate };
+}
+function findMatchingCloseBracket(source, openBracketIdx) {
+    let depth = 0;
+    let i = openBracketIdx;
+    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 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');
@@ -505,3 +586,26 @@ function detectIndent(body) {
         return null;
     return match[1] ?? null;
 }
+/**
+ * Build the actionable reason for an `insert-array-entry` op whose target
+ * array (and all declared alternatives) could not be resolved. Instead of an
+ * opaque "array not found", the message tells the human exactly what to wire
+ * by hand — preserving the template's "zero manual wiring" promise as an
+ * explicit, honest fallback. A template author may override the message with
+ * `op.manualStepInstruction`.
+ */
+function unresolvedArrayReason(op, candidates, sawAmbiguous) {
+    if (op.manualStepInstruction && op.manualStepInstruction.trim().length > 0) {
+        return `insert-array-entry: MANUAL — ${op.manualStepInstruction.trim()}`;
+    }
+    const entry = oneLineEntryLabel(op.ifMissing ?? op.entryValue);
+    const tried = candidates.map((c) => `"${c}"`).join(', ');
+    const why = sawAmbiguous
+        ? `registration array ${tried} appears multiple times (ambiguous)`
+        : `no registration array found (tried ${tried})`;
+    return `insert-array-entry: ${why} — wire ${entry} into ${op.arrayName} manually`;
+}
+function oneLineEntryLabel(raw) {
+    const collapsed = raw.replace(/\s+/g, ' ').trim();
+    return collapsed.length > 60 ? collapsed.slice(0, 57) + '…' : collapsed;
+}

package/dist/saved-plan.d.ts

@@ -12,6 +12,24 @@ export interface ISavedPlanExpectedChange {
     type: string;
     relativePath: string;
     sizeBytes: number;
+    /**
+     * SHA-256 hex digest of the exact rendered body that `gen --print` shows.
+     * Always emitted by `buildSavedPlan`; may be absent on legacy plans written
+     * before body/digest persistence. The plan is the review/apply artifact, so
+     * this digest lets a later review or apply verify — WITHOUT re-rendering —
+     * that the live content still matches what was previewed. Covered by the
+     * HMAC signature (canonical JSON includes the whole `expectedChanges`).
+     */
+    sha256?: string;
+    /**
+     * The exact rendered file body that would be written — byte-identical to
+     * what `gen --print` / `--show-content` displays. Embedded so the saved
+     * plan carries enough to be reviewed for correctness, diffed against HEAD,
+     * and re-applied deterministically instead of storing only a byte count.
+     * Always emitted by `buildSavedPlan`; may be absent on legacy plans. Covered
+     * by the HMAC signature.
+     */
+    body?: string;
     /**
      * v2-only — the operation intent that produced this change. Present iff
      * the schema is `sharkcraft.plan/v2`. Tampering with this field invalidates
@@ -87,12 +105,20 @@ export interface BuildSavedPlanInput {
  * resulting plan is tagged `sharkcraft.plan/v2`; otherwise v1.
  */
 export declare function buildSavedPlan(input: BuildSavedPlanInput): ISavedPlan;
+/** SHA-256 hex digest of a rendered file body (UTF-8). */
+export declare function sha256Hex(body: string): string;
 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';
+    /**
+     * "added" | "removed" | "type-changed" | "size-changed" |
+     * "operation-changed" | "content-changed". `content-changed` fires when the
+     * live body's digest differs from the saved `sha256` even though the byte
+     * count matches — a same-size content edit that a size check alone would
+     * miss.
+     */
+    kind: 'added' | 'removed' | 'type-changed' | 'size-changed' | 'operation-changed' | 'content-changed';
     detail?: string;
 }
 /**

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

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

package/dist/saved-plan.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
 /** v1 schema marker — kept for legacy CREATE-only plans. */
 export const SAVED_PLAN_SCHEMA_V1 = 'sharkcraft.plan/v1';
@@ -20,6 +21,11 @@ export function buildSavedPlan(input) {
             type: String(c.type),
             relativePath: c.relativePath,
             sizeBytes: c.sizeBytes,
+            // Persist the exact rendered body (what `--print` shows) plus its
+            // digest, so the saved plan IS the reviewable / re-appliable artifact
+            // rather than a bare byte count. Both are covered by the HMAC signature.
+            sha256: sha256Hex(c.contents),
+            body: c.contents,
         };
         if (c.operation !== undefined)
             entry.operation = c.operation;
@@ -41,6 +47,10 @@ export function buildSavedPlan(input) {
         out.folderOps = [...input.folderOps];
     return out;
 }
+/** SHA-256 hex digest of a rendered file body (UTF-8). */
+export function sha256Hex(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
 export function savePlanToFile(plan, filePath) {
     try {
         mkdirSync(dirname(filePath), { recursive: true });
@@ -202,6 +212,16 @@ export function diffPlanChanges(saved, fresh) {
                 detail: `${expected.sizeBytes}B → ${actual.sizeBytes}B`,
             });
         }
+        else if (expected.sha256 !== undefined &&
+            sha256Hex(actual.contents) !== expected.sha256) {
+            // Same byte count, different bytes: only the persisted digest catches
+            // this. Legacy plans without `sha256` skip the check (size-only).
+            out.push({
+                relativePath: expected.relativePath,
+                kind: 'content-changed',
+                detail: 'body digest mismatch (same size, different content)',
+            });
+        }
     }
     for (const [key, actual] of freshByKey) {
         if (!expectedByKey.has(key)) {

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

@@ -1 +1 @@
-{"version":3,"file":"synthetic-plan.d.ts","sourceRoot":"","sources":["../src/synthetic-plan.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,eAAe,CAsCjB;AAuBD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAsCzC"}
+{"version":3,"file":"synthetic-plan.d.ts","sourceRoot":"","sources":["../src/synthetic-plan.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,WAAW,EAAE,MAAM,GAClB,eAAe,CA8CjB;AAoDD,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAWD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GACpB,MAAM,CAAC,qBAAqB,EAAE,QAAQ,CAAC,CAmEzC"}