@shrkcrft/generator 0.1.0-alpha.2 → 0.1.0-alpha.21

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,CAwHtB"}

package/dist/folder-apply.js

@@ -12,6 +12,7 @@
  */
 import { existsSync, renameSync, rmSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { 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,
@@ -74,7 +94,7 @@ export function applyFolderOps(ops, options) {
                 continue;
             }
             try {
-                renameSync(absTarget, absNewPath);
+                renameSync(absTarget, safeAbsNewPath);
                 applied.push({ ...baseResult, applied: true });
             }
             catch (e) {

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,141 @@
+/**
+ * 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;
+    /** 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"}

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,33 @@ 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);
+    }
+    const arr = findArrayLiteralBlock(existing, op.arrayName);
+    if (!arr) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-array-entry: array "${op.arrayName}" not found`, op);
+    }
+    if (arr.duplicate) {
+        return mkChange(FileChangeType.Conflict, absolutePath, relativePath, existing, `insert-array-entry: array "${op.arrayName}" appears multiple times (ambiguous)`, 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 +499,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');

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,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"}

package/dist/synthetic-plan.js

@@ -15,6 +15,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
+import { safeResolveTargetPath } from '@shrkcrft/core';
 import { evaluatePlannedChange } from "./planned-change.js";
 import { FileChangeType } from "./file-change.js";
 export const SYNTHETIC_TEMPLATE_PREFIX = '__';
@@ -62,12 +63,30 @@ export function evaluateSavedPlanInPlace(plan, projectRoot) {
     return out;
 }
 function applyOperation(projectRoot, relativePath, operation) {
-    const absolutePath = nodePath.resolve(projectRoot, relativePath);
-    const existing = existsSync(absolutePath) ? readFileSync(absolutePath, 'utf8') : null;
+    // 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,
+    // which writeSyntheticPlan refuses (matching the template path in dry-run.ts).
+    let safe;
+    try {
+        safe = safeResolveTargetPath(relativePath, projectRoot);
+    }
+    catch (e) {
+        const pathErr = e;
+        return {
+            type: FileChangeType.Conflict,
+            absolutePath: pathErr.rawPath,
+            relativePath: pathErr.rawPath,
+            contents: '',
+            reason: `Refused unsafe target path (${pathErr.code}): ${pathErr.message}`,
+            sizeBytes: 0,
+        };
+    }
+    const existing = existsSync(safe.absolutePath) ? readFileSync(safe.absolutePath, 'utf8') : null;
     return evaluatePlannedChange({
-        change: { targetPath: relativePath, operation },
-        absolutePath,
-        relativePath,
+        change: { targetPath: safe.relativePath, operation },
+        absolutePath: safe.absolutePath,
+        relativePath: safe.relativePath,
         existing,
     });
 }
@@ -78,10 +97,27 @@ function applyOperation(projectRoot, relativePath, operation) {
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { AppErrorImpl, ERROR_CODES, err, ok } from '@shrkcrft/core';
+/**
+ * A CCR retrieval marker (`<<ccr:<hex>…>>`) is a pointer into the compress
+ * cache — a LOSSY/compressed view, never apply-grade source. If one ever
+ * reaches a write (e.g. a compressed diff fed into a `create`/`replace` op), it
+ * would corrupt the file. This detector enforces, at the write chokepoint, the
+ * invariant that the compression layer only documents in a comment.
+ */
+const CCR_MARKER_RE = /<<ccr:[0-9a-f]{8,}/;
 export function writeSyntheticPlan(plan) {
     if (plan.hasConflicts) {
         return err(new AppErrorImpl(ERROR_CODES.TARGET_FILE_EXISTS, 'Synthetic plan refused: conflicts present', { details: { conflicts: plan.changes.filter((c) => c.type === FileChangeType.Conflict) } }));
     }
+    // Refuse the WHOLE plan if any writeable change carries a CCR marker — a
+    // compressed/lossy blob must never be written as source.
+    for (const change of plan.changes) {
+        if (!isWriteableSyntheticChange(change.type))
+            continue;
+        if (CCR_MARKER_RE.test(change.contents)) {
+            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;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shrkcrft/generator",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "description": "SharkCraft plan-first generator: GenerationPlan, FileChange, dry-run, safe writes.",
   "license": "MIT",
   "author": "SharkCraft contributors",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -43,10 +43,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.2",
-    "@shrkcrft/templates": "^0.1.0-alpha.2",
-    "@shrkcrft/rules": "^0.1.0-alpha.2",
-    "@shrkcrft/paths": "^0.1.0-alpha.2"
+    "@shrkcrft/core": "^0.1.0-alpha.21",
+    "@shrkcrft/templates": "^0.1.0-alpha.21",
+    "@shrkcrft/rules": "^0.1.0-alpha.21",
+    "@shrkcrft/paths": "^0.1.0-alpha.21"
   },
   "publishConfig": {
     "access": "public"