@shrkcrft/generator 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/folder-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"folder-apply.d.ts","sourceRoot":"","sources":["../src/folder-apply.ts"],"names":[],"mappings":"AAeA,OAAO,EAAuB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,cAAc,EAAE,EAC9B,OAAO,EAAE,gBAAgB,GACxB,oBAAoB,CAwHtB"}
+{"version":3,"file":"folder-apply.d.ts","sourceRoot":"","sources":["../src/folder-apply.ts"],"names":[],"mappings":"AAeA,OAAO,EAAuB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,cAAc,EAAE,EAC9B,OAAO,EAAE,gBAAgB,GACxB,oBAAoB,CAgJtB"}

package/dist/folder-apply.js

@@ -12,7 +12,7 @@
  */
 import { existsSync, renameSync, rmSync } from 'node:fs';
 import * as nodePath from 'node:path';
-import { safeResolveTargetPath } from '@shrkcrft/core';
+import { pathEscapesRootViaSymlink, safeResolveTargetPath } from '@shrkcrft/core';
 import { checkFolderOpSafety, FolderOpSafety } from "./folder-safety.js";
 function resolveAbs(projectRoot, p) {
     return nodePath.isAbsolute(p) ? p : nodePath.resolve(projectRoot, p);
@@ -93,6 +93,17 @@ export function applyFolderOps(ops, options) {
                 applied.push({ ...baseResult, applied: false });
                 continue;
             }
+            // Defense in depth: re-verify the SOURCE has not become a symlink that
+            // escapes the sandbox between safety-check and mutation (TOCTOU window).
+            if (pathEscapesRootViaSymlink(options.projectRoot, absTarget)) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `rename-folder source "${op.targetPath}" resolves outside the project root (symlink escape).`,
+                });
+                continue;
+            }
             try {
                 renameSync(absTarget, safeAbsNewPath);
                 applied.push({ ...baseResult, applied: true });
@@ -113,6 +124,19 @@ export function applyFolderOps(ops, options) {
                 applied.push({ ...baseResult, applied: false });
                 continue;
             }
+            // Defense in depth: re-verify the target has not become a symlink that
+            // escapes the sandbox before a recursive delete. checkFolderOpSafety
+            // already gates this; a second realpath probe closes the TOCTOU window
+            // so we never rmSync EXTERNAL data.
+            if (pathEscapesRootViaSymlink(options.projectRoot, absTarget)) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `delete-folder target "${op.targetPath}" resolves outside the project root (symlink escape).`,
+                });
+                continue;
+            }
             try {
                 rmSync(absTarget, { recursive: true, force: false });
                 applied.push({ ...baseResult, applied: true });

package/dist/folder-safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"folder-safety.d.ts","sourceRoot":"","sources":["../src/folder-safety.ts"],"names":[],"mappings":"AAeA,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,GAAG,eAAe,EACvC,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,qBAAqB,CAqDvB"}
+{"version":3,"file":"folder-safety.d.ts","sourceRoot":"","sources":["../src/folder-safety.ts"],"names":[],"mappings":"AAgBA,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,eAAe,GAAG,eAAe,EACvC,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACxC,qBAAqB,CA+DvB"}

package/dist/folder-safety.js

@@ -12,6 +12,7 @@
 import { existsSync, statSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import * as nodeOs from 'node:os';
+import { pathEscapesRootViaSymlink } from '@shrkcrft/core';
 export var FolderOpSafety;
 (function (FolderOpSafety) {
     FolderOpSafety["Safe"] = "safe";
@@ -33,6 +34,16 @@ export function checkFolderOpSafety(projectRoot, target, kind, options) {
             reason: `Target path "${target}" resolves to "${abs}" which is outside the project root "${normalisedRoot}".`,
         };
     }
+    // Realpath-aware containment — a lexically-clean path can still traverse an
+    // in-root symlink (e.g. `linkdir -> ../outside`) so that `linkdir/secret`
+    // physically lives outside the sandbox. A destructive rmSync/renameSync on
+    // such a path would corrupt EXTERNAL data while reporting success.
+    if (pathEscapesRootViaSymlink(normalisedRoot, abs)) {
+        return {
+            safety: FolderOpSafety.Unsafe,
+            reason: `Target path "${target}" resolves to "${abs}" which is outside the project root (symlink escape).`,
+        };
+    }
     if (abs === normalisedRoot) {
         return { safety: FolderOpSafety.Unsafe, reason: 'Target path resolves to the project root.' };
     }

package/dist/generator-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator-engine.d.ts","sourceRoot":"","sources":["../src/generator-engine.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CA2DrC"}
+{"version":3,"file":"generator-engine.d.ts","sourceRoot":"","sources":["../src/generator-engine.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CA2ErC"}

package/dist/generator-engine.js

@@ -21,8 +21,15 @@ export function generate(template, request) {
     if (plan.hasConflicts) {
         return err(new AppErrorImpl(ERROR_CODES.TARGET_FILE_EXISTS, 'Generation refused: plan has conflicts (use --force / different overwrite strategy)', { details: { conflicts: plan.changes.filter((c) => c.type === FileChangeType.Conflict) } }));
     }
-    const written = [];
-    let totalBytes = 0;
+    // Multiple changes can target the SAME path (e.g. create-then-insert). The
+    // overlay in planGeneration makes each change's `contents` cumulative, so the
+    // LAST writeable change per path already carries the composed result. Write
+    // each distinct path once and count written/totalBytes by distinct path —
+    // matching the synthetic-plan writer. Writing every change would double-count
+    // and re-write the same file. (Single-op-per-path plans, the common case, are
+    // unchanged.)
+    const lastWriteableByPath = new Map();
+    const writeOrder = [];
     let skipped = 0;
     for (const change of plan.changes) {
         if (change.type === FileChangeType.Skip) {
@@ -30,15 +37,23 @@ export function generate(template, request) {
             continue;
         }
         if (isWriteableChange(change.type)) {
-            try {
-                mkdirSync(dirname(change.absolutePath), { recursive: true });
-                writeFileSync(change.absolutePath, change.contents, 'utf8');
-                written.push(change);
-                totalBytes += change.sizeBytes;
-            }
-            catch (e) {
-                return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${change.absolutePath}`, { details: { path: change.absolutePath }, cause: e }));
-            }
+            if (!lastWriteableByPath.has(change.absolutePath))
+                writeOrder.push(change.absolutePath);
+            lastWriteableByPath.set(change.absolutePath, change);
+        }
+    }
+    const written = [];
+    let totalBytes = 0;
+    for (const path of writeOrder) {
+        const change = lastWriteableByPath.get(path);
+        try {
+            mkdirSync(dirname(change.absolutePath), { recursive: true });
+            writeFileSync(change.absolutePath, change.contents, 'utf8');
+            written.push(change);
+            totalBytes += change.sizeBytes;
+        }
+        catch (e) {
+            return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${change.absolutePath}`, { details: { path: change.absolutePath }, cause: e }));
         }
     }
     return ok({

package/dist/operations.d.ts

@@ -112,6 +112,21 @@ export interface IInsertArrayEntryOperation {
      * before the array's matching closing bracket.
      */
     arrayName: string;
+    /**
+     * Fallback array identifiers tried, in order, when `arrayName` does not
+     * resolve in the target project (registration arrays are often named
+     * differently across codebases). The first cleanly-resolved candidate
+     * wins. When none resolve, the op surfaces an actionable manual-wiring
+     * conflict instead of an opaque "array not found".
+     */
+    arrayNameAlternatives?: readonly string[];
+    /**
+     * Precise manual-wiring instruction shown when no candidate array resolves.
+     * When set, it replaces the synthesized "wire <entry> into <array> manually"
+     * message — letting a template author mark this step as a MANUAL follow-up
+     * with exact guidance instead of an opaque conflict.
+     */
+    manualStepInstruction?: string;
     /** Element source text to add (already source-formatted, no trailing comma). */
     entryValue: string;
     /** Optional idempotency marker (default = `entryValue`). */

package/dist/operations.d.ts.map

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

package/dist/planned-change.js

@@ -309,12 +309,26 @@ function evaluateInsertArrayEntry(op, absolutePath, relativePath, existing) {
     if (existing === null) {
         return mkChange(FileChangeType.Conflict, absolutePath, relativePath, '', 'insert-array-entry: target file does not exist', op);
     }
-    const arr = findArrayLiteralBlock(existing, op.arrayName);
-    if (!arr) {
-        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-array-entry: array "${op.arrayName}" not found`, 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.duplicate) {
-        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-array-entry: array "${op.arrayName}" appears multiple times (ambiguous)`, op);
+    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.
@@ -572,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/synthetic-plan.d.ts.map

@@ -1 +1 @@
-{"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,CAsCjB;AAwCD,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,CAoDzC"}
+{"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"}

package/dist/synthetic-plan.js

@@ -27,6 +27,14 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
     const warnings = [];
     let hasConflicts = false;
     const expected = plan.expectedChanges ?? [];
+    // Per-file content overlay so MULTIPLE ops on the SAME file COMPOSE: each op
+    // sees the cumulative result of the prior ops on that path rather than the
+    // original on-disk bytes. Mirrors the template path in dry-run.ts. Without
+    // it, [append A, append B] loses A (the writer's last same-path write
+    // clobbers earlier ones) and create-then-modify on one NEW path
+    // false-conflicts (op2 reads stale disk). Keyed by absolute path → the
+    // cumulative content after the prior op(s).
+    const overlay = new Map();
     for (const e of expected) {
         if (!e.operation) {
             // Without an operation we cannot reconstruct contents — surface as
@@ -43,7 +51,7 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
             hasConflicts = true;
             continue;
         }
-        const change = applyOperation(projectRoot, e.relativePath, e.operation);
+        const change = applyOperation(projectRoot, e.relativePath, e.operation, overlay);
         if (change.type === FileChangeType.Conflict)
             hasConflicts = true;
         changes.push(change);
@@ -62,7 +70,7 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
     }
     return out;
 }
-function applyOperation(projectRoot, relativePath, operation) {
+function applyOperation(projectRoot, relativePath, operation, overlay) {
     // Route through the single generator chokepoint instead of a bare resolve, so
     // a traversal / absolute `relativePath` in a hand-crafted or tampered plan
     // can't write OUTSIDE the project root. An unsafe path becomes a Conflict,
@@ -82,13 +90,24 @@ function applyOperation(projectRoot, relativePath, operation) {
             sizeBytes: 0,
         };
     }
-    const existing = existsSync(safe.absolutePath) ? readFileSync(safe.absolutePath, 'utf8') : null;
-    return evaluatePlannedChange({
+    // Prefer the overlay (the cumulative result of prior same-file ops) over the
+    // on-disk bytes so op N sees the result of ops 1..N-1. Falls back to the live
+    // file, then to absent (`null`) for a brand-new path.
+    const existing = overlay.has(safe.absolutePath)
+        ? (overlay.get(safe.absolutePath) ?? null)
+        : existsSync(safe.absolutePath)
+            ? readFileSync(safe.absolutePath, 'utf8')
+            : null;
+    const result = evaluatePlannedChange({
         change: { targetPath: safe.relativePath, operation },
         absolutePath: safe.absolutePath,
         relativePath: safe.relativePath,
         existing,
     });
+    // Record the cumulative content (Skip/Conflict carry the unchanged bytes,
+    // which is exactly what a later op on the same file should see).
+    overlay.set(safe.absolutePath, result.contents);
+    return result;
 }
 /**
  * Write evaluated changes from a synthetic plan directly. The caller
@@ -118,26 +137,42 @@ export function writeSyntheticPlan(plan) {
             return err(new AppErrorImpl(ERROR_CODES.INVALID_INPUT, `Refused to write ${change.relativePath}: contents carry a <<ccr:…>> marker (a compressed/lossy blob is not apply-grade source).`, { details: { path: change.relativePath } }));
         }
     }
-    const written = [];
-    let totalBytes = 0;
-    let skipped = 0;
+    // Compose multiple ops on the SAME path into ONE write. `evaluateSavedPlanInPlace`
+    // threads an overlay, so the LAST writeable change for a path already carries
+    // the cumulative result of every prior same-path op (any trailing Skip leaves
+    // those bytes unchanged). Writing that once — instead of every op's contents
+    // in order, last-write-wins — avoids redundant writes and keeps the success
+    // count honest: `written` and `summary.written` count DISTINCT paths.
+    const lastWriteableByPath = new Map();
+    const skipPaths = new Set();
     for (const change of plan.changes) {
-        if (change.type === FileChangeType.Skip) {
-            skipped += 1;
-            continue;
+        if (isWriteableSyntheticChange(change.type)) {
+            lastWriteableByPath.set(change.absolutePath, change);
         }
-        if (!isWriteableSyntheticChange(change.type))
-            continue;
+        else if (change.type === FileChangeType.Skip) {
+            skipPaths.add(change.absolutePath);
+        }
+    }
+    const written = [];
+    let totalBytes = 0;
+    for (const [absolutePath, change] of lastWriteableByPath) {
         try {
-            mkdirSync(nodePath.dirname(change.absolutePath), { recursive: true });
-            writeFileSync(change.absolutePath, change.contents, 'utf8');
+            mkdirSync(nodePath.dirname(absolutePath), { recursive: true });
+            writeFileSync(absolutePath, change.contents, 'utf8');
             written.push(change);
             totalBytes += change.sizeBytes;
         }
         catch (e) {
-            return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${change.absolutePath}`, { details: { path: change.absolutePath }, cause: e }));
+            return err(new AppErrorImpl(ERROR_CODES.FILE_WRITE_ERROR, `Failed to write ${absolutePath}`, { details: { path: absolutePath }, cause: e }));
         }
     }
+    // A path counts as skipped only when EVERY op on it resolved to Skip (a path
+    // that was also written is not a skip).
+    let skipped = 0;
+    for (const p of skipPaths) {
+        if (!lastWriteableByPath.has(p))
+            skipped += 1;
+    }
     return ok({
         summary: { written: written.length, skipped, conflicts: 0, totalBytes },
         written,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/generator",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "SharkCraft plan-first generator: GenerationPlan, FileChange, dry-run, safe writes.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,10 +43,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.22",
-    "@shrkcrft/templates": "^0.1.0-alpha.22",
-    "@shrkcrft/rules": "^0.1.0-alpha.22",
-    "@shrkcrft/paths": "^0.1.0-alpha.22"
+    "@shrkcrft/core": "^0.1.0-alpha.24",
+    "@shrkcrft/templates": "^0.1.0-alpha.24",
+    "@shrkcrft/rules": "^0.1.0-alpha.24",
+    "@shrkcrft/paths": "^0.1.0-alpha.24"
   },
   "publishConfig": {
     "access": "public"