@shrkcrft/generator 0.1.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @shrkcrft/generator
+
+SharkCraft plan-first generator: GenerationPlan, FileChange, dry-run, safe writes.
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic, local-first toolkit that gives AI coding agents durable project context. See the main repo for documentation, examples, and the `shrk` CLI.
+
+## Install
+
+```bash
+bun add @shrkcrft/generator
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/conflict-handler.d.ts

@@ -0,0 +1,12 @@
+import { OverwriteStrategy } from './overwrite-strategy.js';
+import { FileChangeType, type IFileChange } from './file-change.js';
+export interface IConflictDecision {
+    type: FileChangeType;
+    reason: string;
+}
+export declare function decideForExisting(strategy: OverwriteStrategy, existingContent: string, newContent: string): IConflictDecision;
+export declare function summarizeConflicts(changes: readonly IFileChange[]): {
+    hasConflicts: boolean;
+    count: number;
+};
+//# sourceMappingURL=conflict-handler.d.ts.map

package/dist/conflict-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict-handler.d.ts","sourceRoot":"","sources":["../src/conflict-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAC3B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAkBnB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG;IACnE,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf,CAGA"}

package/dist/conflict-handler.js

@@ -0,0 +1,25 @@
+import { OverwriteStrategy } from "./overwrite-strategy.js";
+import { FileChangeType } from "./file-change.js";
+export function decideForExisting(strategy, existingContent, newContent) {
+    if (existingContent === newContent) {
+        return { type: FileChangeType.Skip, reason: 'No changes (identical contents)' };
+    }
+    switch (strategy) {
+        case OverwriteStrategy.Overwrite:
+            return { type: FileChangeType.Update, reason: 'overwrite strategy: overwrite' };
+        case OverwriteStrategy.Ask:
+            return { type: FileChangeType.Conflict, reason: 'overwrite strategy: ask (requires user)' };
+        case OverwriteStrategy.MergeLater:
+            return {
+                type: FileChangeType.Conflict,
+                reason: 'overwrite strategy: merge-later (would conflict)',
+            };
+        case OverwriteStrategy.Never:
+        default:
+            return { type: FileChangeType.Conflict, reason: 'overwrite strategy: never (file exists)' };
+    }
+}
+export function summarizeConflicts(changes) {
+    const count = changes.filter((c) => c.type === FileChangeType.Conflict).length;
+    return { hasConflicts: count > 0, count };
+}

package/dist/dry-run.d.ts

@@ -0,0 +1,10 @@
+import { type ITemplateDefinition } from '@shrkcrft/templates';
+import type { IGenerationRequest } from './generation-request.js';
+import type { IGenerationPlan } from './generation-plan.js';
+export interface IDryRunResult {
+    plan: IGenerationPlan;
+    /** True if the plan can be safely written without conflicts. */
+    safe: boolean;
+}
+export declare function planGeneration(template: ITemplateDefinition, request: IGenerationRequest): IDryRunResult;
+//# sourceMappingURL=dry-run.d.ts.map

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

@@ -0,0 +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"}

package/dist/dry-run.js

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { safeResolveTargetPath } from '@shrkcrft/core';
+import { renderTemplate, validateTemplateVariables, } from '@shrkcrft/templates';
+import { OverwriteStrategy } from "./overwrite-strategy.js";
+import { FileChangeType } from "./file-change.js";
+import { decideForExisting, summarizeConflicts } from "./conflict-handler.js";
+import { buildNameVariables } from "./naming-strategy.js";
+import { evaluatePlannedChange, } from "./planned-change.js";
+export function planGeneration(template, request) {
+    const warnings = [];
+    const overwriteStrategy = request.overwriteStrategy ?? OverwriteStrategy.Never;
+    const nameVars = request.name ? buildNameVariables(request.name) : {};
+    const merged = { ...nameVars, ...request.variables };
+    const validation = validateTemplateVariables(template.variables, merged);
+    if (!validation.valid) {
+        for (const issue of validation.issues)
+            warnings.push(`${issue.variable}: ${issue.message}`);
+        return {
+            plan: {
+                templateId: template.id,
+                templateName: template.name,
+                changes: [],
+                totalFiles: 0,
+                hasConflicts: false,
+                warnings,
+                postGenerationNotes: template.postGenerationNotes ?? [],
+            },
+            safe: false,
+        };
+    }
+    const rendered = renderTemplate(template, validation.resolved);
+    const changes = [];
+    // 1) Legacy CREATE-only files() output — unchanged behaviour.
+    for (const file of rendered.files) {
+        let safe;
+        try {
+            safe = safeResolveTargetPath(file.targetPath, request.projectRoot);
+        }
+        catch (e) {
+            const err = e;
+            changes.push({
+                type: FileChangeType.Conflict,
+                absolutePath: err.rawPath,
+                relativePath: err.rawPath,
+                contents: file.content,
+                reason: `Refused unsafe target path (${err.code}): ${err.message}`,
+                sizeBytes: Buffer.byteLength(file.content, 'utf8'),
+            });
+            continue;
+        }
+        const absolutePath = safe.absolutePath;
+        const relPath = safe.relativePath;
+        if (existsSync(absolutePath)) {
+            let existing = '';
+            try {
+                existing = readFileSync(absolutePath, 'utf8');
+            }
+            catch {
+                // unreadable existing file — treat as conflict
+            }
+            const decision = decideForExisting(file.overwrite ? OverwriteStrategy.Overwrite : overwriteStrategy, existing, file.content);
+            changes.push({
+                type: decision.type,
+                absolutePath,
+                relativePath: relPath,
+                contents: decision.type === FileChangeType.Skip ? existing : file.content,
+                reason: decision.reason,
+                sizeBytes: Buffer.byteLength(file.content, 'utf8'),
+            });
+        }
+        else {
+            changes.push({
+                type: FileChangeType.Create,
+                absolutePath,
+                relativePath: relPath,
+                contents: file.content,
+                reason: 'New file (does not exist)',
+                sizeBytes: Buffer.byteLength(file.content, 'utf8'),
+            });
+        }
+    }
+    // 2) v2 planned changes — evaluate against live filesystem.
+    for (const tplChange of rendered.changes) {
+        const evaluated = planOne(tplChange, request.projectRoot);
+        changes.push(evaluated);
+    }
+    const { hasConflicts } = summarizeConflicts(changes);
+    return {
+        plan: {
+            templateId: template.id,
+            templateName: template.name,
+            changes,
+            totalFiles: changes.length,
+            hasConflicts,
+            warnings,
+            postGenerationNotes: rendered.postGenerationNotes,
+        },
+        safe: !hasConflicts && changes.length > 0,
+    };
+}
+function planOne(tplChange, projectRoot) {
+    const op = tplChange.operation;
+    let safe;
+    try {
+        safe = safeResolveTargetPath(tplChange.targetPath, projectRoot);
+    }
+    catch (e) {
+        const err = e;
+        const previewContent = previewContentForOperation(op);
+        return {
+            type: FileChangeType.Conflict,
+            absolutePath: err.rawPath,
+            relativePath: err.rawPath,
+            contents: previewContent,
+            reason: `Refused unsafe target path (${err.code}): ${err.message}`,
+            sizeBytes: Buffer.byteLength(previewContent, 'utf8'),
+            operation: op,
+        };
+    }
+    const change = {
+        targetPath: tplChange.targetPath,
+        operation: op,
+    };
+    const existing = existsSync(safe.absolutePath)
+        ? readFileSafe(safe.absolutePath)
+        : null;
+    return evaluatePlannedChange({
+        change,
+        absolutePath: safe.absolutePath,
+        relativePath: safe.relativePath,
+        existing,
+    });
+}
+function readFileSafe(absolutePath) {
+    try {
+        return readFileSync(absolutePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function previewContentForOperation(op) {
+    switch (op.kind) {
+        case 'create':
+            return op.content;
+        case 'append':
+        case 'insert-after':
+        case 'insert-before':
+            return op.snippet;
+        case 'replace':
+            return op.replaceWith;
+        case 'export':
+            return op.symbols && op.symbols.length > 0
+                ? `export { ${op.symbols.join(', ')} } from '${op.from}';`
+                : `export * from '${op.from}';`;
+        case 'ensure-import': {
+            const parts = [];
+            if (op.defaultBinding)
+                parts.push(op.defaultBinding);
+            if (op.namespaceBinding)
+                parts.push(`* as ${op.namespaceBinding}`);
+            if (op.symbols && op.symbols.length > 0)
+                parts.push(`{ ${op.symbols.join(', ')} }`);
+            const keyword = op.typeOnly ? 'import type' : 'import';
+            return parts.length > 0
+                ? `${keyword} ${parts.join(', ')} from '${op.from}';`
+                : `${keyword} '${op.from}';`;
+        }
+        case 'insert-enum-entry':
+            return `${op.enumName}.${op.entryName} = '${op.entryValue}'`;
+        case 'insert-object-entry':
+            return `${op.objectName}.${op.entryKey}: ${op.entryValue}`;
+        case 'insert-before-closing-brace':
+            return op.snippet;
+        case 'insert-between-anchors':
+            return op.snippet;
+    }
+}

package/dist/file-change.d.ts

@@ -0,0 +1,46 @@
+import type { IPlannedOperation } from './planned-change.js';
+export declare enum FileChangeType {
+    Create = "create",
+    /** Legacy v1 full-file overwrite when the same template is regenerated. */
+    Update = "update",
+    /** v2: append snippet at the end of an existing file. */
+    Append = "append",
+    /** v2: insert snippet immediately after an anchor in an existing file. */
+    InsertAfter = "insert-after",
+    /** v2: insert snippet immediately before an anchor in an existing file. */
+    InsertBefore = "insert-before",
+    /** v2: replace literal text in an existing file. */
+    Replace = "replace",
+    /** v2: append a barrel re-export to an existing index file. */
+    Export = "export",
+    /** Rename a folder. Apply-time only; preview-only by default. */
+    RenameFolder = "rename-folder",
+    /** Delete a folder. Hard-gated; preview-only by default. */
+    DeleteFolder = "delete-folder",
+    Skip = "skip",
+    Conflict = "conflict"
+}
+export interface IFileChange {
+    type: FileChangeType;
+    absolutePath: string;
+    relativePath: string;
+    /** Final contents that would be written. For Skip the existing file is shown unchanged. */
+    contents: string;
+    /** Reason why this change has this type. */
+    reason: string;
+    /** Size of contents in bytes. */
+    sizeBytes: number;
+    /**
+     * v2 only — the operation intent that produced this change. Absent on v1
+     * CREATE entries that come from `files()` templates. Used by:
+     *   - `saved-plan` to persist intent (so signature covers the operation)
+     *   - dry-run rendering to show structural info (anchor / snippet preview)
+     *   - apply-time divergence detection
+     *
+     * Type-only import of `IPlannedOperation` is safe: TS erases the import
+     * at compile time, so there is no runtime cycle even though
+     * `planned-change.ts` imports `FileChangeType` from this file.
+     */
+    operation?: IPlannedOperation;
+}
+//# sourceMappingURL=file-change.d.ts.map

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

@@ -0,0 +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"}

package/dist/file-change.js

@@ -0,0 +1,22 @@
+export var FileChangeType;
+(function (FileChangeType) {
+    FileChangeType["Create"] = "create";
+    /** Legacy v1 full-file overwrite when the same template is regenerated. */
+    FileChangeType["Update"] = "update";
+    /** v2: append snippet at the end of an existing file. */
+    FileChangeType["Append"] = "append";
+    /** v2: insert snippet immediately after an anchor in an existing file. */
+    FileChangeType["InsertAfter"] = "insert-after";
+    /** v2: insert snippet immediately before an anchor in an existing file. */
+    FileChangeType["InsertBefore"] = "insert-before";
+    /** v2: replace literal text in an existing file. */
+    FileChangeType["Replace"] = "replace";
+    /** v2: append a barrel re-export to an existing index file. */
+    FileChangeType["Export"] = "export";
+    /** Rename a folder. Apply-time only; preview-only by default. */
+    FileChangeType["RenameFolder"] = "rename-folder";
+    /** Delete a folder. Hard-gated; preview-only by default. */
+    FileChangeType["DeleteFolder"] = "delete-folder";
+    FileChangeType["Skip"] = "skip";
+    FileChangeType["Conflict"] = "conflict";
+})(FileChangeType || (FileChangeType = {}));

package/dist/folder-apply.d.ts

@@ -0,0 +1,29 @@
+import { FolderOpSafety } from './folder-safety.js';
+export interface IFolderOpInput {
+    readonly kind: 'rename-folder' | 'delete-folder';
+    readonly targetPath: string;
+    readonly newPath?: string;
+}
+export interface IFolderOpOptions {
+    readonly projectRoot: string;
+    readonly dryRun?: boolean;
+    readonly allowFolderOps?: boolean;
+    readonly allowDeleteFolder?: boolean;
+}
+export interface IFolderOpResult {
+    readonly op: IFolderOpInput;
+    readonly applied: boolean;
+    readonly safety: FolderOpSafety;
+    readonly reason?: string;
+    readonly absTarget: string;
+    readonly absNewPath?: string;
+}
+export interface IFolderOpApplyReport {
+    readonly schema: 'sharkcraft.folder-op-apply/v1';
+    readonly projectRoot: string;
+    readonly dryRun: boolean;
+    readonly applied: readonly IFolderOpResult[];
+    readonly rejected: readonly IFolderOpResult[];
+}
+export declare function applyFolderOps(ops: readonly IFolderOpInput[], options: IFolderOpOptions): IFolderOpApplyReport;
+//# sourceMappingURL=folder-apply.d.ts.map

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

@@ -0,0 +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"}

package/dist/folder-apply.js

@@ -0,0 +1,117 @@
+/**
+ * Folder operation applier.
+ *
+ * Executes `rename-folder` / `delete-folder` operations with strict safety
+ * gates. Refuses unsafe paths *before* touching the filesystem. The CLI
+ * `shrk apply` command can call this once its plan schema knows how to
+ * carry folder ops in a saved plan; today plugin-lifecycle plans pass an
+ * `IPluginLifecycleFolderOp[]` directly.
+ *
+ * Read-only by default; mutates only when `dryRun === false` AND the
+ * caller has supplied the explicit allow flags.
+ */
+import { existsSync, renameSync, rmSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { checkFolderOpSafety, FolderOpSafety } from "./folder-safety.js";
+function resolveAbs(projectRoot, p) {
+    return nodePath.isAbsolute(p) ? p : nodePath.resolve(projectRoot, p);
+}
+export function applyFolderOps(ops, options) {
+    const applied = [];
+    const rejected = [];
+    const dryRun = options.dryRun !== false; // default true — explicit opt-in to mutate
+    for (const op of ops) {
+        const safetyOptions = {};
+        if (options.allowDeleteFolder)
+            safetyOptions.allowDeleteFolder = true;
+        const safety = checkFolderOpSafety(options.projectRoot, op.targetPath, op.kind, safetyOptions);
+        const absTarget = resolveAbs(options.projectRoot, op.targetPath);
+        const absNewPath = op.newPath ? resolveAbs(options.projectRoot, op.newPath) : undefined;
+        const baseResult = {
+            op,
+            safety: safety.safety,
+            ...(safety.reason ? { reason: safety.reason } : {}),
+            absTarget,
+            ...(absNewPath ? { absNewPath } : {}),
+        };
+        // 1) Safety must be green.
+        if (safety.safety !== FolderOpSafety.Safe) {
+            rejected.push({ ...baseResult, applied: false });
+            continue;
+        }
+        // 2) Allow-flag must be present.
+        if (!options.allowFolderOps) {
+            rejected.push({
+                ...baseResult,
+                applied: false,
+                safety: FolderOpSafety.Unsafe,
+                reason: 'Folder op rejected — pass `--allow-folder-ops` to enable.',
+            });
+            continue;
+        }
+        // 3) Rename specifics.
+        if (op.kind === 'rename-folder') {
+            if (!absNewPath) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: 'rename-folder requires `newPath`.',
+                });
+                continue;
+            }
+            if (existsSync(absNewPath)) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `rename-folder destination "${op.newPath}" already exists.`,
+                });
+                continue;
+            }
+            if (dryRun) {
+                applied.push({ ...baseResult, applied: false });
+                continue;
+            }
+            try {
+                renameSync(absTarget, absNewPath);
+                applied.push({ ...baseResult, applied: true });
+            }
+            catch (e) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `rename failed: ${e.message}`,
+                });
+            }
+            continue;
+        }
+        // 4) Delete specifics — already gated by checkFolderOpSafety via allowDeleteFolder.
+        if (op.kind === 'delete-folder') {
+            if (dryRun) {
+                applied.push({ ...baseResult, applied: false });
+                continue;
+            }
+            try {
+                rmSync(absTarget, { recursive: true, force: false });
+                applied.push({ ...baseResult, applied: true });
+            }
+            catch (e) {
+                rejected.push({
+                    ...baseResult,
+                    applied: false,
+                    safety: FolderOpSafety.Unsafe,
+                    reason: `delete failed: ${e.message}`,
+                });
+            }
+        }
+    }
+    return {
+        schema: 'sharkcraft.folder-op-apply/v1',
+        projectRoot: options.projectRoot,
+        dryRun,
+        applied,
+        rejected,
+    };
+}

package/dist/folder-safety.d.ts

@@ -0,0 +1,12 @@
+export declare enum FolderOpSafety {
+    Safe = "safe",
+    Unsafe = "unsafe"
+}
+export interface IFolderOpSafetyResult {
+    readonly safety: FolderOpSafety;
+    readonly reason?: string;
+}
+export declare function checkFolderOpSafety(projectRoot: string, target: string, kind: 'rename-folder' | 'delete-folder', options?: {
+    allowDeleteFolder?: boolean;
+}): IFolderOpSafetyResult;
+//# sourceMappingURL=folder-safety.d.ts.map

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

@@ -0,0 +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"}

package/dist/folder-safety.js

@@ -0,0 +1,75 @@
+/**
+ * Hard safety gates for folder rename/delete plan operations.
+ *
+ * Folder ops are preview-only by default. Apply must refuse:
+ *   - paths outside the project root
+ *   - paths inside `.git`, `node_modules`, home directories
+ *   - empty / root / absolute paths
+ *   - paths that resolve to the project root itself
+ *
+ * Read-only safety helpers; no side effects.
+ */
+import { existsSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import * as nodeOs from 'node:os';
+export var FolderOpSafety;
+(function (FolderOpSafety) {
+    FolderOpSafety["Safe"] = "safe";
+    FolderOpSafety["Unsafe"] = "unsafe";
+})(FolderOpSafety || (FolderOpSafety = {}));
+const FORBIDDEN_SEGMENTS = new Set(['.git', 'node_modules', '.svn', '.hg']);
+export function checkFolderOpSafety(projectRoot, target, kind, options) {
+    if (!target || target === '/' || target === '.') {
+        return { safety: FolderOpSafety.Unsafe, reason: `Target path "${target}" is the project root or empty.` };
+    }
+    const abs = nodePath.isAbsolute(target) ? target : nodePath.resolve(projectRoot, target);
+    const normalisedRoot = nodePath.resolve(projectRoot);
+    const home = nodeOs.homedir();
+    // Must be inside project root.
+    const rel = nodePath.relative(normalisedRoot, abs);
+    if (rel.startsWith('..') || nodePath.isAbsolute(rel)) {
+        return {
+            safety: FolderOpSafety.Unsafe,
+            reason: `Target path "${target}" resolves to "${abs}" which is outside the project root "${normalisedRoot}".`,
+        };
+    }
+    if (abs === normalisedRoot) {
+        return { safety: FolderOpSafety.Unsafe, reason: 'Target path resolves to the project root.' };
+    }
+    if (abs === home || abs === '/') {
+        return { safety: FolderOpSafety.Unsafe, reason: `Target path resolves to "${abs}" — refuses to operate on home/root directories.` };
+    }
+    for (const seg of abs.split(nodePath.sep)) {
+        if (FORBIDDEN_SEGMENTS.has(seg)) {
+            return {
+                safety: FolderOpSafety.Unsafe,
+                reason: `Target path "${target}" contains forbidden segment "${seg}".`,
+            };
+        }
+    }
+    if (kind === 'delete-folder' && !options?.allowDeleteFolder) {
+        return {
+            safety: FolderOpSafety.Unsafe,
+            reason: 'delete-folder requires explicit `--allow-delete-folder` flag at apply time.',
+        };
+    }
+    // Existing folder check for rename (must exist).
+    if (kind === 'rename-folder' && !existsSync(abs)) {
+        return {
+            safety: FolderOpSafety.Unsafe,
+            reason: `rename-folder target "${target}" does not exist.`,
+        };
+    }
+    if (kind === 'delete-folder' && existsSync(abs)) {
+        try {
+            const st = statSync(abs);
+            if (!st.isDirectory()) {
+                return { safety: FolderOpSafety.Unsafe, reason: `delete-folder target "${target}" is not a directory.` };
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { safety: FolderOpSafety.Safe };
+}

package/dist/generation-plan.d.ts

@@ -0,0 +1,24 @@
+import type { IFileChange } from './file-change.js';
+import type { ISavedPlanFolderOp } from './saved-plan.js';
+export interface IGenerationPlan {
+    templateId: string;
+    templateName: string;
+    changes: readonly IFileChange[];
+    totalFiles: number;
+    hasConflicts: boolean;
+    warnings: readonly string[];
+    postGenerationNotes: readonly string[];
+    /**
+     * Optional folder operations attached to the plan. Carried verbatim
+     * into saved plans and executed via `applyFolderOps()` during `shrk apply`
+     * when explicit allow flags are present.
+     */
+    folderOps?: readonly ISavedPlanFolderOp[];
+}
+export interface IGenerationSummary {
+    written: number;
+    skipped: number;
+    conflicts: number;
+    totalBytes: number;
+}
+//# sourceMappingURL=generation-plan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generation-plan.d.ts","sourceRoot":"","sources":["../src/generation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/generation-plan.js

@@ -0,0 +1 @@
+export {};

package/dist/generation-request.d.ts

@@ -0,0 +1,14 @@
+import type { TemplateVariableValues } from '@shrkcrft/templates';
+import type { NamingStrategy, OverwriteStrategy } from './overwrite-strategy.js';
+export interface IGenerationRequest {
+    templateId: string;
+    /** Primary "name" passed to the template — used as the kebab-case basename, etc. */
+    name?: string;
+    variables: TemplateVariableValues;
+    projectRoot: string;
+    overwriteStrategy?: OverwriteStrategy;
+    namingStrategy?: NamingStrategy;
+    /** If false (default), no files are written — only the plan is returned. */
+    write?: boolean;
+}
+//# sourceMappingURL=generation-request.d.ts.map

package/dist/generation-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-request.d.ts","sourceRoot":"","sources":["../src/generation-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,sBAAsB,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/generation-request.js

@@ -0,0 +1 @@
+export {};

package/dist/generator-engine.d.ts

@@ -0,0 +1,12 @@
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { ITemplateDefinition } from '@shrkcrft/templates';
+import type { IGenerationRequest } from './generation-request.js';
+import type { IGenerationPlan, IGenerationSummary } from './generation-plan.js';
+import { type IFileChange } from './file-change.js';
+export interface IGenerationResult {
+    plan: IGenerationPlan;
+    summary: IGenerationSummary;
+    written: readonly IFileChange[];
+}
+export declare function generate(template: ITemplateDefinition, request: IGenerationRequest): Result<IGenerationResult, AppError>;
+//# sourceMappingURL=generator-engine.d.ts.map