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

package/dist/dry-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../src/dry-run.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAmGf"}
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../src/dry-run.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CA8Gf"}

package/dist/dry-run.js

@@ -30,6 +30,12 @@ export function planGeneration(template, request) {
     }
     const rendered = renderTemplate(template, validation.resolved);
     const changes = [];
+    // Per-file content overlay so that MULTIPLE changes (or a files() create
+    // followed by a changes() op) targeting the SAME file COMPOSE. Without
+    // this every change is evaluated against the original on-disk bytes and
+    // the writer's last same-file write clobbers the earlier ones. Keyed by
+    // absolute path → the cumulative content after the prior change(s).
+    const overlay = new Map();
     // 1) Legacy CREATE-only files() output — unchanged behaviour.
     for (const file of rendered.files) {
         let safe;
@@ -59,14 +65,16 @@ export function planGeneration(template, request) {
                 // unreadable existing file — treat as conflict
             }
             const decision = decideForExisting(file.overwrite ? OverwriteStrategy.Overwrite : overwriteStrategy, existing, file.content);
+            const contents = decision.type === FileChangeType.Skip ? existing : file.content;
             changes.push({
                 type: decision.type,
                 absolutePath,
                 relativePath: relPath,
-                contents: decision.type === FileChangeType.Skip ? existing : file.content,
+                contents,
                 reason: decision.reason,
                 sizeBytes: Buffer.byteLength(file.content, 'utf8'),
             });
+            overlay.set(absolutePath, contents);
         }
         else {
             changes.push({
@@ -77,11 +85,13 @@ export function planGeneration(template, request) {
                 reason: 'New file (does not exist)',
                 sizeBytes: Buffer.byteLength(file.content, 'utf8'),
             });
+            overlay.set(absolutePath, file.content);
         }
     }
-    // 2) v2 planned changes — evaluate against live filesystem.
+    // 2) v2 planned changes — evaluate against the live filesystem, threaded
+    //    through the overlay so successive changes to one file compose.
     for (const tplChange of rendered.changes) {
-        const evaluated = planOne(tplChange, request.projectRoot);
+        const evaluated = planOne(tplChange, request.projectRoot, overlay);
         changes.push(evaluated);
     }
     const { hasConflicts } = summarizeConflicts(changes);
@@ -98,7 +108,7 @@ export function planGeneration(template, request) {
         safe: !hasConflicts && changes.length > 0,
     };
 }
-function planOne(tplChange, projectRoot) {
+function planOne(tplChange, projectRoot, overlay) {
     const op = tplChange.operation;
     let safe;
     try {
@@ -121,15 +131,23 @@ function planOne(tplChange, projectRoot) {
         targetPath: tplChange.targetPath,
         operation: op,
     };
-    const existing = existsSync(safe.absolutePath)
-        ? readFileSafe(safe.absolutePath)
-        : null;
-    return evaluatePlannedChange({
+    // Prefer the overlay (cumulative result of prior same-file changes) over
+    // the on-disk bytes so successive ops on one file compose deterministically.
+    const existing = overlay?.has(safe.absolutePath)
+        ? (overlay.get(safe.absolutePath) ?? null)
+        : existsSync(safe.absolutePath)
+            ? readFileSafe(safe.absolutePath)
+            : null;
+    const result = evaluatePlannedChange({
         change,
         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;
 }
 function readFileSafe(absolutePath) {
     try {
@@ -170,6 +188,8 @@ function previewContentForOperation(op) {
             return `${op.enumName}.${op.entryName} = '${op.entryValue}'`;
         case 'insert-object-entry':
             return `${op.objectName}.${op.entryKey}: ${op.entryValue}`;
+        case 'insert-array-entry':
+            return `${op.arrayName} ⟵ ${op.entryValue}`;
         case 'insert-before-closing-brace':
             return op.snippet;
         case 'insert-between-anchors':

package/dist/file-change.d.ts

@@ -1,4 +1,4 @@
-import type { IPlannedOperation } from './planned-change.js';
+import type { IPlannedOperation } from './operations.js';
 export declare enum FileChangeType {
     Create = "create",
     /** Legacy v1 full-file overwrite when the same template is regenerated. */

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

@@ -1 +1 @@
-{"version":3,"file":"file-change.d.ts","sourceRoot":"","sources":["../src/file-change.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,2EAA2E;IAC3E,MAAM,WAAW;IACjB,yDAAyD;IACzD,MAAM,WAAW;IACjB,0EAA0E;IAC1E,WAAW,iBAAiB;IAC5B,2EAA2E;IAC3E,YAAY,kBAAkB;IAC9B,oDAAoD;IACpD,OAAO,YAAY;IACnB,+DAA+D;IAC/D,MAAM,WAAW;IACjB,iEAAiE;IACjE,YAAY,kBAAkB;IAC9B,4DAA4D;IAC5D,YAAY,kBAAkB;IAC9B,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B"}
+{"version":3,"file":"file-change.d.ts","sourceRoot":"","sources":["../src/file-change.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,2EAA2E;IAC3E,MAAM,WAAW;IACjB,yDAAyD;IACzD,MAAM,WAAW;IACjB,0EAA0E;IAC1E,WAAW,iBAAiB;IAC5B,2EAA2E;IAC3E,YAAY,kBAAkB;IAC9B,oDAAoD;IACpD,OAAO,YAAY;IACnB,+DAA+D;IAC/D,MAAM,WAAW;IACjB,iEAAiE;IACjE,YAAY,kBAAkB;IAC9B,4DAA4D;IAC5D,YAAY,kBAAkB;IAC9B,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B"}

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

@@ -1 +1 @@
-{"version":3,"file":"folder-apply.d.ts","sourceRoot":"","sources":["../src/folder-apply.ts"],"names":[],"mappings":"AAcA,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,CAsGtB"}
+{"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,6 +12,7 @@
  */
 import { existsSync, renameSync, rmSync } from 'node:fs';
 import * as nodePath from 'node:path';
+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);
@@ -60,7 +61,26 @@ export function applyFolderOps(ops, options) {
                 });
                 continue;
             }
-            if (existsSync(absNewPath)) {
+            // The rename DESTINATION is never validated by checkFolderOpSafety (which
+            // only checks targetPath), and resolveAbs even allows absolute newPaths —
+            // so `newPath: '../sibling'` or '/etc/x' would move the folder OUTSIDE the
+            // project root. Enforce containment through the same chokepoint as writes.
+            let safeNew;
+            try {
+                safeNew = safeResolveTargetPath(op.newPath, options.projectRoot);
+            }
+            catch (e) {
+                const pathErr = e;
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `rename-folder destination "${op.newPath}" is outside the project root (${pathErr.code}).`,
+                });
+                continue;
+            }
+            const safeAbsNewPath = safeNew.absolutePath;
+            if (existsSync(safeAbsNewPath)) {
                 rejected.push({
                     ...baseResult,
                     applied: false,
@@ -73,8 +93,19 @@ 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, absNewPath);
+                renameSync(absTarget, safeAbsNewPath);
                 applied.push({ ...baseResult, applied: true });
             }
             catch (e) {
@@ -93,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/index.d.ts

@@ -12,6 +12,7 @@ export * from './planned-change.js';
 export * from './folder-safety.js';
 export * from './folder-apply.js';
 export * from './synthetic-plan.js';
+export * from './package-delegate-plan.js';
 export * from './spec/index.js';
 export * from './grounding/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -12,5 +12,6 @@ export * from "./planned-change.js";
 export * from "./folder-safety.js";
 export * from "./folder-apply.js";
 export * from "./synthetic-plan.js";
+export * from "./package-delegate-plan.js";
 export * from "./spec/index.js";
 export * from "./grounding/index.js";

package/dist/operations.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Operation union — declared by templates, persisted in saved plans.
+ * Part of the v2 generation model.
+ */
+export type PlannedOperationKind = 'create' | 'append' | 'insert-after' | 'insert-before' | 'replace' | 'export' | 'ensure-import' | 'insert-enum-entry' | 'insert-object-entry' | 'insert-array-entry' | 'insert-before-closing-brace' | 'insert-between-anchors';
+export interface ICreateOperation {
+    kind: 'create';
+    content: string;
+    description?: string;
+}
+export 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;
+}
+export 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;
+}
+export interface IInsertBeforeOperation {
+    kind: 'insert-before';
+    anchor: string;
+    snippet: string;
+    ifMissing?: string;
+    description?: string;
+}
+export 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;
+}
+export 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;
+}
+export 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;
+}
+export 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;
+}
+export interface IInsertObjectEntryOperation {
+    kind: 'insert-object-entry';
+    /** Object identifier, e.g. `ROUTE_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;
+}
+export interface IInsertArrayEntryOperation {
+    kind: 'insert-array-entry';
+    /**
+     * Array identifier — a `const`/`let`/`var` bound to an array literal,
+     * e.g. `editorScopeEntries` or `DEFAULT_PANELS`. The element is inserted
+     * 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`). */
+    ifMissing?: string;
+    description?: string;
+}
+export 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;
+}
+export 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 | IInsertArrayEntryOperation | IInsertBeforeClosingBraceOperation | IInsertBetweenAnchorsOperation;
+//# sourceMappingURL=operations.d.ts.map

package/dist/operations.d.ts.map

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

package/dist/operations.js

@@ -0,0 +1,5 @@
+/**
+ * Operation union — declared by templates, persisted in saved plans.
+ * Part of the v2 generation model.
+ */
+export {};

package/dist/package-delegate-plan.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { type AppError, type Result } from '@shrkcrft/core';
+import type { IGenerationPlan } from './generation-plan.js';
+import type { ISavedPlan } from './saved-plan.js';
+export declare const DELEGATE_TEMPLATE_PREFIX = "__delegate/";
+/** A raw operation as parsed from a worker (structurally `IDelegateRawOp`). */
+export interface IDelegateOpInput {
+    targetPath: string;
+    operation: {
+        kind: string;
+    } & Record<string, unknown>;
+}
+export interface IPackageDelegateInput {
+    ops: readonly IDelegateOpInput[];
+    /** `IPlannedOperation` kinds the recipe permits; others are dropped. */
+    allowedOps: readonly string[];
+    /** Recipe id — becomes the synthetic templateId `__delegate/<id>`. */
+    recipeId: string;
+    projectRoot: string;
+}
+export interface IDroppedOp {
+    kind: string;
+    targetPath: string;
+    reason: string;
+}
+export interface IPackageDelegateResult {
+    /** Conflict-free, ready to sign. Present only when `ready`. */
+    plan?: ISavedPlan;
+    /** The evaluated generation plan (changes + conflicts) — always present. */
+    generation: IGenerationPlan;
+    /** Ops whose kind was not in `allowedOps`. */
+    droppedOps: readonly IDroppedOp[];
+    /** True when no conflicts — the plan is built and ready to sign + apply. */
+    ready: boolean;
+}
+export declare function packageDelegatePlan(input: IPackageDelegateInput): Result<IPackageDelegateResult, AppError>;
+//# sourceMappingURL=package-delegate-plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"package-delegate-plan.d.ts","sourceRoot":"","sources":["../src/package-delegate-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAmBlD,eAAO,MAAM,wBAAwB,gBAAgB,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjC,wEAAwE;IACxE,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,eAAe,CAAC;IAC5B,8CAA8C;IAC9C,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC;IAClC,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAoE1C"}