@wp-typia/project-tools 0.16.7 → 0.16.8

package/README.md

@@ -6,7 +6,8 @@ Package roles:
 
 - `wp-typia` owns the CLI, help, TUI, completions, skills, MCP, and bin entry.
 - `@wp-typia/project-tools` owns scaffold, add-block, migrate, template, doctor, and schema project helpers.
-  It also owns the typed generator boundary via `BlockSpec` and `BlockGeneratorService`,
+  It also owns the typed generator boundary via `BlockSpec`, `BlockGeneratorService`,
+  and `inspectBlockGeneration(...)`,
   plus the emitter-owned built-in structural/code path where built-in
   templates no longer ship structural, TS/TSX, style, or block-local `render.php`
   Mustache files.
@@ -50,4 +51,18 @@ files and starter `typia.manifest.json` now come from the emitter path, while
 project bootstrap/package-manager files, sync scripts, shared REST helpers, and
 the remaining non-block assets still come from Mustache-backed template copy.
 
+The higher-level generator architecture record, including the current phase map
+and the non-mutating `plan -> validate -> render -> apply` tool-facing usage
+model, lives in
+[`docs/block-generator-architecture.md`](../../docs/block-generator-architecture.md).
+The public non-mutating controller/tool contract now lives in
+[`docs/block-generator-tool-contract.md`](../../docs/block-generator-tool-contract.md).
+
+Reusable external layer packages on top of the built-in shared scaffold model
+are now available programmatically through `scaffoldProject(...)`,
+`BlockGeneratorService`, and `inspectBlockGeneration(...)` via
+`externalLayerSource` and optional `externalLayerId`. The RFC/CLI UX record
+still lives in
+[`docs/external-template-layer-composition.md`](../../docs/external-template-layer-composition.md).
+
 If you need metadata sync, editor helpers, validation helpers, or other generated-project runtime utilities, import them directly from `@wp-typia/block-runtime/*`.

package/dist/runtime/block-generator-service.d.ts

@@ -41,6 +41,8 @@ export interface BlockSpec {
 export interface BlockGenerationTarget {
     allowExistingDir: boolean;
     cwd: string;
+    externalLayerId?: string;
+    externalLayerSource?: string;
     noInstall: boolean;
     packageManager: PackageManagerId;
     projectDir: string;
@@ -51,6 +53,8 @@ export interface PlanBlockInput {
     answers: ScaffoldAnswers;
     cwd?: string;
     dataStorageMode?: DataStorageMode;
+    externalLayerId?: string;
+    externalLayerSource?: string;
     noInstall?: boolean;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
@@ -95,7 +99,7 @@ export interface ApplyBlockInput {
 export declare function createBuiltInBlockSpec({ answers, dataStorageMode, persistencePolicy, templateId, withMigrationUi, withTestPreset, withWpEnv, }: Omit<PlanBlockInput, "allowExistingDir" | "cwd" | "noInstall" | "packageManager" | "projectDir" | "variant">): BlockSpec;
 export declare function buildTemplateVariablesFromBlockSpec(spec: BlockSpec): ScaffoldTemplateVariables;
 export declare class BlockGeneratorService {
-    plan({ allowExistingDir, answers, cwd, dataStorageMode, noInstall, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }: PlanBlockInput): Promise<PlanBlockResult>;
+    plan({ allowExistingDir, answers, cwd, dataStorageMode, externalLayerId, externalLayerSource, noInstall, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }: PlanBlockInput): Promise<PlanBlockResult>;
     validate({ plan }: ValidateBlockInput): Promise<ValidateBlockResult>;
     render({ validated }: RenderBlockInput): Promise<RenderBlockResult>;
     apply({ rendered, installDependencies, }: ApplyBlockInput): Promise<ScaffoldProjectResult>;

package/dist/runtime/block-generator-service.js

@@ -7,10 +7,62 @@ import { applyBuiltInScaffoldProjectFiles, buildGitignore, buildReadme, } from "
 import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from "./scaffold-identifiers.js";
 import { buildBuiltInBlockArtifacts, } from "./built-in-block-artifacts.js";
 import { buildBuiltInCodeArtifacts, } from "./built-in-block-code-artifacts.js";
+import { getStarterManifestFiles } from "./starter-manifests.js";
+import { resolveTemplateSeed, parseTemplateLocator } from "./template-source.js";
+import { assertExternalTemplateLayersDoNotWriteProtectedOutputs, resolveExternalTemplateLayers, } from "./template-layers.js";
+import { getBuiltInTemplateOverlayDir, getBuiltInTemplateSharedLayerDirs, resolveBuiltInTemplateSourceFromLayerDirs, } from "./template-builtins.js";
 const renderedArtifactCache = new WeakMap();
 function createVariablesFingerprint(variables) {
     return JSON.stringify(variables);
 }
+function buildProtectedTemplateOutputPaths({ codeArtifacts, spec, variables, artifacts, }) {
+    const protectedOutputs = new Set([
+        ".gitignore",
+        "package.json",
+        "scripts/add-compound-child.ts",
+        "scripts/block-config.ts",
+        "scripts/sync-project.ts",
+        "scripts/sync-rest-contracts.ts",
+        "scripts/sync-types-to-block-json.ts",
+        "tsconfig.json",
+        "webpack.config.js",
+        `${variables.slugKebabCase}.php`,
+    ]);
+    for (const artifact of codeArtifacts) {
+        protectedOutputs.add(artifact.relativePath);
+    }
+    for (const artifact of artifacts) {
+        protectedOutputs.add(`${artifact.relativeDir}/block.json`);
+        protectedOutputs.add(`${artifact.relativeDir}/types.ts`);
+    }
+    for (const manifest of getStarterManifestFiles(spec.template.family, variables)) {
+        protectedOutputs.add(manifest.relativePath);
+    }
+    return protectedOutputs;
+}
+function buildCombinedTemplateLayerDirs({ baseLayerDirs, externalEntries, templateId, }) {
+    const orderedLayerDirs = [];
+    const seenLayerDirs = new Set();
+    for (const layerDir of baseLayerDirs) {
+        if (seenLayerDirs.has(layerDir)) {
+            continue;
+        }
+        orderedLayerDirs.push(layerDir);
+        seenLayerDirs.add(layerDir);
+    }
+    for (const entry of externalEntries) {
+        if (seenLayerDirs.has(entry.dir)) {
+            continue;
+        }
+        orderedLayerDirs.push(entry.dir);
+        seenLayerDirs.add(entry.dir);
+    }
+    const overlayDir = getBuiltInTemplateOverlayDir(templateId);
+    if (!seenLayerDirs.has(overlayDir)) {
+        orderedLayerDirs.push(overlayDir);
+    }
+    return orderedLayerDirs;
+}
 function getBuiltInPersistenceSpec({ templateId, dataStorageMode, persistencePolicy, }) {
     if (templateId === "persistence") {
         return {
@@ -146,7 +198,7 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
     };
 }
 export class BlockGeneratorService {
-    async plan({ allowExistingDir = false, answers, cwd = process.cwd(), dataStorageMode, noInstall = false, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    async plan({ allowExistingDir = false, answers, cwd = process.cwd(), dataStorageMode, externalLayerId, externalLayerSource, noInstall = false, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
         return {
             spec: createBuiltInBlockSpec({
                 answers,
@@ -160,6 +212,8 @@ export class BlockGeneratorService {
             target: {
                 allowExistingDir,
                 cwd,
+                externalLayerId,
+                externalLayerSource,
                 noInstall,
                 packageManager,
                 projectDir,
@@ -168,21 +222,90 @@ export class BlockGeneratorService {
         };
     }
     async validate({ plan }) {
+        if (plan.target.externalLayerId && !plan.target.externalLayerSource) {
+            throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
+        }
         if (plan.target.variant) {
             throw new Error(`--variant is only supported for official external template configs. Received variant "${plan.target.variant}" for built-in template "${plan.spec.template.family}".`);
         }
         return plan;
     }
     async render({ validated }) {
-        const templateSource = await resolveBuiltInTemplateSource(validated.spec.template.family, {
-            persistenceEnabled: validated.spec.persistence.enabled,
+        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
+        const persistenceEnabled = validated.spec.persistence.enabled;
+        const artifacts = buildBuiltInBlockArtifacts({
+            templateId: validated.spec.template.family,
+            variables,
+        });
+        const codeArtifacts = buildBuiltInCodeArtifacts({
+            templateId: validated.spec.template.family,
+            variables,
+        });
+        const templateVariantOptions = {
+            persistenceEnabled,
             persistencePolicy: validated.spec.persistence.enabled &&
                 validated.spec.persistence.persistencePolicy === "public"
                 ? "public"
                 : "authenticated",
-        });
-        const variables = buildTemplateVariablesFromBlockSpec(validated.spec);
-        const persistenceEnabled = validated.spec.persistence.enabled;
+        };
+        let templateSource = await resolveBuiltInTemplateSource(validated.spec.template.family, templateVariantOptions);
+        const warnings = [...(templateSource.warnings ?? [])];
+        if (validated.target.externalLayerSource) {
+            let layerSeed;
+            try {
+                layerSeed = await resolveTemplateSeed(parseTemplateLocator(validated.target.externalLayerSource), validated.target.cwd);
+                const resolvedLayers = await resolveExternalTemplateLayers({
+                    externalLayerId: validated.target.externalLayerId,
+                    sourceRoot: layerSeed.rootDir,
+                });
+                const baseLayerDirs = getBuiltInTemplateSharedLayerDirs(validated.spec.template.family, templateVariantOptions);
+                await assertExternalTemplateLayersDoNotWriteProtectedOutputs({
+                    externalEntries: resolvedLayers.entries,
+                    protectedOutputPaths: buildProtectedTemplateOutputPaths({
+                        artifacts,
+                        codeArtifacts,
+                        spec: validated.spec,
+                        variables,
+                    }),
+                    view: variables,
+                });
+                await templateSource.cleanup?.();
+                templateSource = await resolveBuiltInTemplateSourceFromLayerDirs(validated.spec.template.family, buildCombinedTemplateLayerDirs({
+                    baseLayerDirs,
+                    externalEntries: resolvedLayers.entries,
+                    templateId: validated.spec.template.family,
+                }));
+                const layerSourceCleanup = layerSeed.cleanup;
+                const templateCleanup = templateSource.cleanup;
+                templateSource.cleanup = async () => {
+                    const cleanupErrors = [];
+                    try {
+                        await templateCleanup?.();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    try {
+                        await layerSourceCleanup?.();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    if (cleanupErrors.length > 0) {
+                        throw new Error([
+                            "Failed to cleanup composed template sources.",
+                            ...cleanupErrors.map((error) => `- ${error.message}`),
+                        ].join("\n"));
+                    }
+                };
+                warnings.push(`Applied external layer "${resolvedLayers.selectedLayerId}" from "${validated.target.externalLayerSource}".`);
+            }
+            catch (error) {
+                await templateSource.cleanup?.();
+                await layerSeed?.cleanup?.();
+                throw error;
+            }
+        }
         const rendered = {
             ...validated,
             cleanup: templateSource.cleanup,
@@ -202,17 +325,11 @@ export class BlockGeneratorService {
             selectedVariant: null,
             templateDir: templateSource.templateDir,
             variables,
-            warnings: templateSource.warnings ?? [],
+            warnings,
         };
         renderedArtifactCache.set(rendered, {
-            artifacts: buildBuiltInBlockArtifacts({
-                templateId: validated.spec.template.family,
-                variables,
-            }),
-            codeArtifacts: buildBuiltInCodeArtifacts({
-                templateId: validated.spec.template.family,
-                variables,
-            }),
+            artifacts,
+            codeArtifacts,
             variablesFingerprint: createVariablesFingerprint(variables),
         });
         return rendered;

package/dist/runtime/block-generator-tool-contract.d.ts

@@ -0,0 +1,93 @@
+import { BlockGeneratorService, type PlanBlockInput, type PlanBlockResult, type RenderBlockResult, type ValidateBlockResult } from "./block-generator-service.js";
+import type { ManifestDocument } from "./migration-types.js";
+import type { BuiltInTemplateId } from "./template-registry.js";
+/**
+ * Semantic version marker for the public block generation tool contract.
+ *
+ * Increment this number whenever the serialized inspection payload changes in a
+ * breaking way.
+ */
+export declare const BLOCK_GENERATION_TOOL_CONTRACT_VERSION: 1;
+/**
+ * Staged execution points for the non-mutating inspection workflow.
+ *
+ * - `"plan"` returns the normalized `BlockSpec` and target metadata.
+ * - `"validate"` returns the validated generation stage without rendering.
+ * - `"render"` returns the full non-mutating preview, including copied and
+ *   emitted file snapshots.
+ */
+export type BlockGenerationToolStage = "plan" | "validate" | "render";
+/**
+ * Input for the staged, non-mutating block generation inspection entrypoint.
+ *
+ * Extends `PlanBlockInput` with an optional `stopAfter` selector so callers can
+ * stop at `plan`, `validate`, or continue through the full `render` preview.
+ */
+export interface InspectBlockGenerationInput extends PlanBlockInput {
+    stopAfter?: BlockGenerationToolStage;
+}
+export interface BlockGenerationTemplateCopyPreview {
+    owner: "template-copy";
+    relativePath: string;
+}
+export interface BlockGenerationEmittedFilePreview {
+    kind: "generated-source" | "starter-manifest" | "structural";
+    owner: "emitter";
+    relativePath: string;
+    source: string;
+}
+export interface BlockGenerationStarterManifestPreview {
+    document: ManifestDocument;
+    owner: "emitter";
+    relativePath: string;
+    source: string;
+}
+export interface BlockGenerationRenderPreview {
+    copiedTemplateFiles: BlockGenerationTemplateCopyPreview[];
+    emittedFiles: BlockGenerationEmittedFilePreview[];
+    postRender: RenderBlockResult["postRender"] & {
+        installsDependencies: boolean;
+    };
+    selectedVariant: null;
+    starterManifestFiles: BlockGenerationStarterManifestPreview[];
+    template: {
+        description: string;
+        family: BuiltInTemplateId;
+        features: string[];
+        format: "wp-typia";
+    };
+    warnings: string[];
+    readmeContent: string;
+    gitignoreContent: string;
+}
+interface BlockGenerationInspectionBase {
+    contractVersion: typeof BLOCK_GENERATION_TOOL_CONTRACT_VERSION;
+    mutatesWorkspace: false;
+    stage: BlockGenerationToolStage;
+}
+export interface InspectBlockGenerationPlanResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    stage: "plan";
+}
+export interface InspectBlockGenerationValidateResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    stage: "validate";
+    validated: ValidateBlockResult;
+}
+export interface InspectBlockGenerationRenderResult extends BlockGenerationInspectionBase {
+    plan: PlanBlockResult;
+    rendered: BlockGenerationRenderPreview;
+    stage: "render";
+    validated: ValidateBlockResult;
+}
+export type InspectBlockGenerationResult = InspectBlockGenerationPlanResult | InspectBlockGenerationValidateResult | InspectBlockGenerationRenderResult;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter: "plan";
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationPlanResult>;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter: "validate";
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationValidateResult>;
+export declare function inspectBlockGeneration(input: InspectBlockGenerationInput & {
+    stopAfter?: "render" | undefined;
+}, service?: BlockGeneratorService): Promise<InspectBlockGenerationRenderResult>;
+export {};

package/dist/runtime/block-generator-tool-contract.js

@@ -0,0 +1,157 @@
+import { buildBuiltInBlockArtifacts, stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
+import { buildBuiltInCodeArtifacts, } from "./built-in-block-code-artifacts.js";
+import { BlockGeneratorService, } from "./block-generator-service.js";
+import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+import { listInterpolatedDirectoryOutputs } from "./template-render.js";
+/**
+ * Semantic version marker for the public block generation tool contract.
+ *
+ * Increment this number whenever the serialized inspection payload changes in a
+ * breaking way.
+ */
+export const BLOCK_GENERATION_TOOL_CONTRACT_VERSION = 1;
+function buildStarterManifestPreviews(templateId, variables, artifacts) {
+    const starterManifests = getStarterManifestFiles(templateId, variables);
+    const artifactManifests = new Map(artifacts.map((artifact) => [
+        `${artifact.relativeDir}/typia.manifest.json`,
+        artifact.manifestDocument,
+    ]));
+    return starterManifests
+        .map((entry) => {
+        const document = artifactManifests.get(entry.relativePath) ?? entry.document;
+        return {
+            document,
+            owner: "emitter",
+            relativePath: entry.relativePath,
+            source: stringifyStarterManifest(document),
+        };
+    })
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function buildStructuralArtifactPreviews(artifacts) {
+    return artifacts
+        .flatMap((artifact) => [
+        {
+            kind: "structural",
+            owner: "emitter",
+            relativePath: `${artifact.relativeDir}/block.json`,
+            source: stringifyBuiltInBlockJsonDocument(artifact.blockJsonDocument),
+        },
+        {
+            kind: "structural",
+            owner: "emitter",
+            relativePath: `${artifact.relativeDir}/types.ts`,
+            source: artifact.typesSource,
+        },
+    ])
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function buildCodeArtifactPreviews(codeArtifacts) {
+    return codeArtifacts
+        .map((artifact) => ({
+        kind: "generated-source",
+        owner: "emitter",
+        relativePath: artifact.relativePath,
+        source: artifact.source,
+    }))
+        .sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+async function buildRenderPreview(rendered) {
+    const artifacts = buildBuiltInBlockArtifacts({
+        templateId: rendered.spec.template.family,
+        variables: rendered.variables,
+    });
+    const codeArtifacts = buildBuiltInCodeArtifacts({
+        templateId: rendered.spec.template.family,
+        variables: rendered.variables,
+    });
+    const copiedTemplateFiles = await listInterpolatedDirectoryOutputs(rendered.templateDir, rendered.variables);
+    return {
+        copiedTemplateFiles: copiedTemplateFiles.map((relativePath) => ({
+            owner: "template-copy",
+            relativePath,
+        })),
+        emittedFiles: [
+            ...buildStructuralArtifactPreviews(artifacts),
+            ...buildCodeArtifactPreviews(codeArtifacts),
+        ].sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+        gitignoreContent: rendered.gitignoreContent,
+        postRender: {
+            ...rendered.postRender,
+            installsDependencies: !rendered.target.noInstall,
+        },
+        readmeContent: rendered.readmeContent,
+        selectedVariant: rendered.selectedVariant,
+        starterManifestFiles: buildStarterManifestPreviews(rendered.spec.template.family, rendered.variables, artifacts),
+        template: {
+            description: rendered.spec.template.description,
+            family: rendered.spec.template.family,
+            features: [...rendered.spec.template.features],
+            format: "wp-typia",
+        },
+        warnings: [...rendered.warnings],
+    };
+}
+/**
+ * Inspects built-in block generation through the staged generator boundary
+ * without mutating the destination workspace.
+ *
+ * Use `stopAfter` to halt after the `plan`, `validate`, or `render` stage.
+ * The render stage includes copied template file paths, emitter-owned source
+ * previews, starter manifest previews, and post-render intent metadata. Any
+ * temporary render state is cleaned up before the promise resolves.
+ *
+ * @example
+ * ```ts
+ * const inspection = await inspectBlockGeneration({
+ * 	answers,
+ * 	noInstall: true,
+ * 	packageManager: "bun",
+ * 	projectDir: "demo-block",
+ * 	templateId: "basic",
+ * 	stopAfter: "render",
+ * });
+ * ```
+ *
+ * @param input - Planning input plus an optional `stopAfter` stage selector.
+ * @param service - Optional generator service instance. Defaults to a new
+ * `BlockGeneratorService`.
+ * @returns The serialized inspection result for the reached stage.
+ * @throws Propagates planning, validation, or render failures from
+ * `BlockGeneratorService`.
+ */
+export async function inspectBlockGeneration({ stopAfter = "render", ...planInput }, service = new BlockGeneratorService()) {
+    const plan = await service.plan(planInput);
+    if (stopAfter === "plan") {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            stage: "plan",
+        };
+    }
+    const validated = await service.validate({ plan });
+    if (stopAfter === "validate") {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            stage: "validate",
+            validated,
+        };
+    }
+    const rendered = await service.render({ validated });
+    try {
+        return {
+            contractVersion: BLOCK_GENERATION_TOOL_CONTRACT_VERSION,
+            mutatesWorkspace: false,
+            plan,
+            rendered: await buildRenderPreview(rendered),
+            stage: "render",
+            validated,
+        };
+    }
+    finally {
+        await rendered.cleanup?.();
+    }
+}

package/dist/runtime/index.d.ts

@@ -12,6 +12,8 @@
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export type { ApplyBlockInput, BlockGenerationTarget, BlockSpec, PlanBlockInput, PlanBlockResult, RenderBlockInput, RenderBlockResult, ValidateBlockInput, ValidateBlockResult, } from "./block-generator-service.js";
+export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";
+export type { BlockGenerationEmittedFilePreview, BlockGenerationRenderPreview, BlockGenerationStarterManifestPreview, BlockGenerationTemplateCopyPreview, BlockGenerationToolStage, InspectBlockGenerationInput, InspectBlockGenerationPlanResult, InspectBlockGenerationRenderResult, InspectBlockGenerationResult, InspectBlockGenerationValidateResult, } from "./block-generator-tool-contract.js";
 export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
 export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWorkspaceProject, } from "./workspace-project.js";
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";

package/dist/runtime/index.js

@@ -11,6 +11,7 @@
  */
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
+export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";
 export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
 export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWorkspaceProject, } from "./workspace-project.js";
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";

package/dist/runtime/template-builtins.d.ts

@@ -19,6 +19,15 @@ export interface MaterializedBuiltInTemplateSource {
     selectedVariant?: string | null;
     warnings?: string[];
 }
+export interface BuiltInSharedTemplateLayer {
+    dir: string;
+    id: string;
+}
+export declare function listBuiltInSharedTemplateLayers(): readonly BuiltInSharedTemplateLayer[];
+export declare function isBuiltInSharedTemplateLayerId(layerId: string): boolean;
+export declare function getBuiltInSharedTemplateLayerDir(layerId: string): string;
+export declare function getBuiltInTemplateOverlayDir(templateId: BuiltInTemplateId): string;
+export declare function getBuiltInTemplateSharedLayerDirs(templateId: BuiltInTemplateId, { persistenceEnabled, persistencePolicy, }?: BuiltInTemplateVariantOptions): string[];
 /**
  * Returns the ordered overlay directories for a built-in template.
  *
@@ -26,7 +35,7 @@ export interface MaterializedBuiltInTemplateSource {
  * the selected policy layer, and the thin template overlay. All other built-ins
  * resolve to the shared base plus their own template directory.
  */
-export declare function getBuiltInTemplateLayerDirs(templateId: BuiltInTemplateId, { persistenceEnabled, persistencePolicy, }?: BuiltInTemplateVariantOptions): string[];
+export declare function getBuiltInTemplateLayerDirs(templateId: BuiltInTemplateId, options?: BuiltInTemplateVariantOptions): string[];
 /**
  * Returns whether a missing built-in overlay directory is expected because the
  * template family no longer ships any Mustache assets in that layer.
@@ -36,6 +45,7 @@ export declare function getBuiltInTemplateLayerDirs(templateId: BuiltInTemplateI
  * @returns True when the missing layer can be skipped safely.
  */
 export declare function isOmittableBuiltInTemplateLayerDir(templateId: BuiltInTemplateId, layerDir: string): boolean;
+export declare function resolveBuiltInTemplateSourceFromLayerDirs(templateId: BuiltInTemplateId, layerDirs: readonly string[]): Promise<MaterializedBuiltInTemplateSource>;
 /**
  * Materializes a built-in template into a temporary directory by copying each
  * resolved layer in order.

package/dist/runtime/template-builtins.js

@@ -2,20 +2,96 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promises as fsp } from "node:fs";
-import { getTemplateById, SHARED_BASE_TEMPLATE_ROOT, SHARED_COMPOUND_TEMPLATE_ROOT, SHARED_PERSISTENCE_TEMPLATE_ROOT, SHARED_REST_HELPER_TEMPLATE_ROOT, } from "./template-registry.js";
+import { getTemplateById, SHARED_BASE_TEMPLATE_ROOT, SHARED_COMPOUND_TEMPLATE_ROOT, SHARED_MIGRATION_UI_TEMPLATE_ROOT, SHARED_PERSISTENCE_TEMPLATE_ROOT, SHARED_PRESET_TEMPLATE_ROOT, SHARED_REST_HELPER_TEMPLATE_ROOT, SHARED_WORKSPACE_TEMPLATE_ROOT, } from "./template-registry.js";
+const BUILT_IN_SHARED_TEMPLATE_LAYERS = Object.freeze([
+    {
+        dir: SHARED_BASE_TEMPLATE_ROOT,
+        id: "builtin:shared/base",
+    },
+    {
+        dir: path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, "shared"),
+        id: "builtin:shared/rest-helpers/shared",
+    },
+    {
+        dir: path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, "public"),
+        id: "builtin:shared/rest-helpers/public",
+    },
+    {
+        dir: path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, "auth"),
+        id: "builtin:shared/rest-helpers/auth",
+    },
+    {
+        dir: path.join(SHARED_PERSISTENCE_TEMPLATE_ROOT, "core"),
+        id: "builtin:shared/persistence/core",
+    },
+    {
+        dir: path.join(SHARED_PERSISTENCE_TEMPLATE_ROOT, "public"),
+        id: "builtin:shared/persistence/public",
+    },
+    {
+        dir: path.join(SHARED_PERSISTENCE_TEMPLATE_ROOT, "auth"),
+        id: "builtin:shared/persistence/auth",
+    },
+    {
+        dir: path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "core"),
+        id: "builtin:shared/compound/core",
+    },
+    {
+        dir: path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "persistence"),
+        id: "builtin:shared/compound/persistence",
+    },
+    {
+        dir: path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "persistence-public"),
+        id: "builtin:shared/compound/persistence-public",
+    },
+    {
+        dir: path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "persistence-auth"),
+        id: "builtin:shared/compound/persistence-auth",
+    },
+    {
+        dir: path.join(SHARED_MIGRATION_UI_TEMPLATE_ROOT, "common"),
+        id: "builtin:shared/migration-ui/common",
+    },
+    {
+        dir: path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env"),
+        id: "builtin:shared/presets/wp-env",
+    },
+    {
+        dir: path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset"),
+        id: "builtin:shared/presets/test-preset",
+    },
+    {
+        dir: path.join(SHARED_WORKSPACE_TEMPLATE_ROOT, "persistence-public"),
+        id: "builtin:shared/workspace/persistence-public",
+    },
+    {
+        dir: path.join(SHARED_WORKSPACE_TEMPLATE_ROOT, "persistence-auth"),
+        id: "builtin:shared/workspace/persistence-auth",
+    },
+]);
+const BUILT_IN_SHARED_TEMPLATE_LAYER_DIRS = new Map(BUILT_IN_SHARED_TEMPLATE_LAYERS.map((layer) => [layer.id, layer.dir]));
 const OMITTABLE_BUILT_IN_OVERLAY_TEMPLATE_IDS = new Set([
     "basic",
     "persistence",
     "compound",
 ]);
-/**
- * Returns the ordered overlay directories for a built-in template.
- *
- * Persistence templates include the shared base, the persistence core layer,
- * the selected policy layer, and the thin template overlay. All other built-ins
- * resolve to the shared base plus their own template directory.
- */
-export function getBuiltInTemplateLayerDirs(templateId, { persistenceEnabled = false, persistencePolicy = "authenticated", } = {}) {
+export function listBuiltInSharedTemplateLayers() {
+    return BUILT_IN_SHARED_TEMPLATE_LAYERS;
+}
+export function isBuiltInSharedTemplateLayerId(layerId) {
+    return BUILT_IN_SHARED_TEMPLATE_LAYER_DIRS.has(layerId);
+}
+export function getBuiltInSharedTemplateLayerDir(layerId) {
+    const layerDir = BUILT_IN_SHARED_TEMPLATE_LAYER_DIRS.get(layerId);
+    if (!layerDir) {
+        throw new Error(`Unknown built-in shared template layer id: ${layerId}`);
+    }
+    return layerDir;
+}
+export function getBuiltInTemplateOverlayDir(templateId) {
+    return getTemplateById(templateId).templateDir;
+}
+export function getBuiltInTemplateSharedLayerDirs(templateId, { persistenceEnabled = false, persistencePolicy = "authenticated", } = {}) {
     if (templateId === "persistence") {
         return [
             SHARED_BASE_TEMPLATE_ROOT,
@@ -23,21 +99,32 @@ export function getBuiltInTemplateLayerDirs(templateId, { persistenceEnabled = f
             path.join(SHARED_PERSISTENCE_TEMPLATE_ROOT, "core"),
             path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, persistencePolicy === "public" ? "public" : "auth"),
             path.join(SHARED_PERSISTENCE_TEMPLATE_ROOT, persistencePolicy === "public" ? "public" : "auth"),
-            getTemplateById(templateId).templateDir,
         ];
     }
     if (templateId === "compound") {
         const layers = [
             SHARED_BASE_TEMPLATE_ROOT,
             path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "core"),
-            getTemplateById(templateId).templateDir,
         ];
         if (persistenceEnabled) {
             layers.push(path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, "shared"), path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "persistence"), path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, persistencePolicy === "public" ? "public" : "auth"), path.join(SHARED_COMPOUND_TEMPLATE_ROOT, persistencePolicy === "public" ? "persistence-public" : "persistence-auth"));
         }
         return layers;
     }
-    return [SHARED_BASE_TEMPLATE_ROOT, getTemplateById(templateId).templateDir];
+    return [SHARED_BASE_TEMPLATE_ROOT];
+}
+/**
+ * Returns the ordered overlay directories for a built-in template.
+ *
+ * Persistence templates include the shared base, the persistence core layer,
+ * the selected policy layer, and the thin template overlay. All other built-ins
+ * resolve to the shared base plus their own template directory.
+ */
+export function getBuiltInTemplateLayerDirs(templateId, options = {}) {
+    return [
+        ...getBuiltInTemplateSharedLayerDirs(templateId, options),
+        getBuiltInTemplateOverlayDir(templateId),
+    ];
 }
 /**
  * Returns whether a missing built-in overlay directory is expected because the
@@ -51,8 +138,8 @@ export function isOmittableBuiltInTemplateLayerDir(templateId, layerDir) {
     return (OMITTABLE_BUILT_IN_OVERLAY_TEMPLATE_IDS.has(templateId) &&
         layerDir === getTemplateById(templateId).templateDir);
 }
-function resolveMaterializedBuiltInTemplateLayerDirs(templateId, options) {
-    return getBuiltInTemplateLayerDirs(templateId, options).flatMap((layerDir) => {
+function resolveMaterializedTemplateLayerDirs(templateId, layerDirs) {
+    return layerDirs.flatMap((layerDir) => {
         if (fs.existsSync(layerDir)) {
             return [layerDir];
         }
@@ -62,22 +149,14 @@ function resolveMaterializedBuiltInTemplateLayerDirs(templateId, options) {
         throw new Error(`Built-in template layer is missing: ${layerDir}`);
     });
 }
-/**
- * Materializes a built-in template into a temporary directory by copying each
- * resolved layer in order.
- *
- * Callers should invoke the returned `cleanup` function when they no longer
- * need the materialized directory. If copying fails, the temporary directory is
- * removed before the error is rethrown.
- */
-export async function resolveBuiltInTemplateSource(templateId, options = {}) {
+async function materializeBuiltInTemplateSource(templateId, layerDirs) {
     const template = getTemplateById(templateId);
-    const layerDirs = resolveMaterializedBuiltInTemplateLayerDirs(templateId, options);
+    const materializedLayerDirs = resolveMaterializedTemplateLayerDirs(templateId, layerDirs);
     const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-template-"));
     const templateDir = path.join(tempRoot, templateId);
     try {
         await fsp.mkdir(templateDir, { recursive: true });
-        for (const layerDir of layerDirs) {
+        for (const layerDir of materializedLayerDirs) {
             await fsp.cp(layerDir, templateDir, {
                 recursive: true,
                 force: true,
@@ -100,3 +179,17 @@ export async function resolveBuiltInTemplateSource(templateId, options = {}) {
         },
     };
 }
+export async function resolveBuiltInTemplateSourceFromLayerDirs(templateId, layerDirs) {
+    return materializeBuiltInTemplateSource(templateId, layerDirs);
+}
+/**
+ * Materializes a built-in template into a temporary directory by copying each
+ * resolved layer in order.
+ *
+ * Callers should invoke the returned `cleanup` function when they no longer
+ * need the materialized directory. If copying fails, the temporary directory is
+ * removed before the error is rethrown.
+ */
+export async function resolveBuiltInTemplateSource(templateId, options = {}) {
+    return materializeBuiltInTemplateSource(templateId, getBuiltInTemplateLayerDirs(templateId, options));
+}

package/dist/runtime/template-layers.d.ts

@@ -0,0 +1,31 @@
+export declare const TEMPLATE_LAYER_MANIFEST_FILENAME = "wp-typia.layers.json";
+declare const TEMPLATE_LAYER_MANIFEST_VERSION: 1;
+export interface ExternalTemplateLayerDefinition {
+    description?: string;
+    extends?: string[];
+    path: string;
+}
+export interface ExternalTemplateLayerManifest {
+    layers: Record<string, ExternalTemplateLayerDefinition>;
+    version: typeof TEMPLATE_LAYER_MANIFEST_VERSION;
+}
+export interface ResolvedTemplateLayerEntry {
+    dir: string;
+    id: string;
+    kind: "built-in" | "external";
+}
+export interface ResolvedExternalTemplateLayers {
+    entries: ResolvedTemplateLayerEntry[];
+    selectedLayerId: string;
+}
+export declare function loadExternalTemplateLayerManifest(sourceRoot: string): Promise<ExternalTemplateLayerManifest | null>;
+export declare function resolveExternalTemplateLayers({ externalLayerId, sourceRoot, }: {
+    externalLayerId?: string;
+    sourceRoot: string;
+}): Promise<ResolvedExternalTemplateLayers>;
+export declare function assertExternalTemplateLayersDoNotWriteProtectedOutputs({ externalEntries, protectedOutputPaths, view, }: {
+    externalEntries: readonly ResolvedTemplateLayerEntry[];
+    protectedOutputPaths: ReadonlySet<string>;
+    view: Record<string, string>;
+}): Promise<void>;
+export {};

package/dist/runtime/template-layers.js

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+import { promises as fsp } from "node:fs";
+import { isPlainObject } from "./object-utils.js";
+import { getBuiltInSharedTemplateLayerDir, isBuiltInSharedTemplateLayerId, } from "./template-builtins.js";
+import { listInterpolatedDirectoryOutputs } from "./template-render.js";
+export const TEMPLATE_LAYER_MANIFEST_FILENAME = "wp-typia.layers.json";
+const TEMPLATE_LAYER_MANIFEST_VERSION = 1;
+function resolveLayerPath(sourceRoot, relativePath) {
+    const targetPath = path.resolve(sourceRoot, relativePath);
+    const relativeTarget = path.relative(sourceRoot, targetPath);
+    if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+        throw new Error(`Template layer path "${relativePath}" must stay within ${sourceRoot}.`);
+    }
+    return targetPath;
+}
+async function assertNoSymlinks(sourceDir) {
+    const stats = await fsp.lstat(sourceDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Template layer packages may not include symbolic links: ${sourceDir}`);
+    }
+    if (!stats.isDirectory()) {
+        return;
+    }
+    for (const entry of await fsp.readdir(sourceDir)) {
+        await assertNoSymlinks(path.join(sourceDir, entry));
+    }
+}
+function parseLayerDefinition(layerId, value) {
+    if (isBuiltInSharedTemplateLayerId(layerId)) {
+        throw new Error(`Layer "${layerId}" uses a reserved built-in shared layer id and cannot be redefined in ${TEMPLATE_LAYER_MANIFEST_FILENAME}.`);
+    }
+    if (!isPlainObject(value)) {
+        throw new Error(`Layer "${layerId}" in ${TEMPLATE_LAYER_MANIFEST_FILENAME} must be an object.`);
+    }
+    const layerPath = value.path;
+    if (typeof layerPath !== "string" || layerPath.trim().length === 0) {
+        throw new Error(`Layer "${layerId}" must define a non-empty string "path".`);
+    }
+    const layerExtends = value.extends;
+    if (typeof layerExtends !== "undefined" &&
+        (!Array.isArray(layerExtends) ||
+            !layerExtends.every((entry) => typeof entry === "string" && entry.trim().length > 0))) {
+        throw new Error(`Layer "${layerId}" must define "extends" as an array of non-empty strings when present.`);
+    }
+    const description = value.description;
+    if (typeof description !== "undefined" &&
+        (typeof description !== "string" || description.trim().length === 0)) {
+        throw new Error(`Layer "${layerId}" must define "description" as a non-empty string when present.`);
+    }
+    return {
+        description: typeof description === "string" ? description : undefined,
+        extends: Array.isArray(layerExtends) ? [...layerExtends] : undefined,
+        path: layerPath,
+    };
+}
+export async function loadExternalTemplateLayerManifest(sourceRoot) {
+    const manifestPath = path.join(sourceRoot, TEMPLATE_LAYER_MANIFEST_FILENAME);
+    if (!fs.existsSync(manifestPath)) {
+        return null;
+    }
+    const raw = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+    if (!isPlainObject(raw)) {
+        throw new Error(`${TEMPLATE_LAYER_MANIFEST_FILENAME} must export a JSON object.`);
+    }
+    if (raw.version !== TEMPLATE_LAYER_MANIFEST_VERSION) {
+        throw new Error(`${TEMPLATE_LAYER_MANIFEST_FILENAME} must declare "version": ${TEMPLATE_LAYER_MANIFEST_VERSION}.`);
+    }
+    if (!isPlainObject(raw.layers) || Object.keys(raw.layers).length === 0) {
+        throw new Error(`${TEMPLATE_LAYER_MANIFEST_FILENAME} must define a non-empty "layers" object.`);
+    }
+    return {
+        layers: Object.fromEntries(Object.entries(raw.layers).map(([layerId, value]) => [
+            layerId,
+            parseLayerDefinition(layerId, value),
+        ])),
+        version: TEMPLATE_LAYER_MANIFEST_VERSION,
+    };
+}
+function getDefaultExternalLayerId(manifest) {
+    const layerIds = Object.keys(manifest.layers);
+    if (layerIds.length === 1) {
+        return layerIds[0];
+    }
+    const referencedExternalLayerIds = new Set();
+    for (const definition of Object.values(manifest.layers)) {
+        for (const ancestorId of definition.extends ?? []) {
+            if (ancestorId in manifest.layers) {
+                referencedExternalLayerIds.add(ancestorId);
+            }
+        }
+    }
+    const publicLayerIds = layerIds.filter((layerId) => !referencedExternalLayerIds.has(layerId));
+    if (publicLayerIds.length === 1) {
+        return publicLayerIds[0];
+    }
+    throw new Error(`External layer package defines multiple selectable layers (${layerIds.join(", ")}). Pass an explicit externalLayerId until a final CLI selection UX exists.`);
+}
+export async function resolveExternalTemplateLayers({ externalLayerId, sourceRoot, }) {
+    const manifest = await loadExternalTemplateLayerManifest(sourceRoot);
+    if (!manifest) {
+        throw new Error(`No ${TEMPLATE_LAYER_MANIFEST_FILENAME} manifest found in ${sourceRoot}.`);
+    }
+    const manifestDocument = manifest;
+    const selectedLayerId = externalLayerId ?? getDefaultExternalLayerId(manifestDocument);
+    if (!(selectedLayerId in manifestDocument.layers)) {
+        throw new Error(`Unknown external layer "${selectedLayerId}". Expected one of: ${Object.keys(manifestDocument.layers).join(", ")}`);
+    }
+    const entries = [];
+    const emittedLayerIds = new Set();
+    const visitingLayerIds = new Set();
+    async function visitLayer(layerId) {
+        if (isBuiltInSharedTemplateLayerId(layerId)) {
+            if (!emittedLayerIds.has(layerId)) {
+                entries.push({
+                    dir: getBuiltInSharedTemplateLayerDir(layerId),
+                    id: layerId,
+                    kind: "built-in",
+                });
+                emittedLayerIds.add(layerId);
+            }
+            return;
+        }
+        const definition = manifestDocument.layers[layerId];
+        if (!definition) {
+            throw new Error(`Layer "${layerId}" is not defined in ${TEMPLATE_LAYER_MANIFEST_FILENAME}.`);
+        }
+        if (visitingLayerIds.has(layerId)) {
+            throw new Error(`Detected a cycle while resolving external layer "${layerId}".`);
+        }
+        visitingLayerIds.add(layerId);
+        for (const ancestorId of definition.extends ?? []) {
+            await visitLayer(ancestorId);
+        }
+        visitingLayerIds.delete(layerId);
+        if (emittedLayerIds.has(layerId)) {
+            return;
+        }
+        const layerDir = resolveLayerPath(sourceRoot, definition.path);
+        const stats = await fsp.stat(layerDir).catch(() => null);
+        if (!stats || !stats.isDirectory()) {
+            throw new Error(`Layer "${layerId}" points to a missing directory: ${definition.path}`);
+        }
+        await assertNoSymlinks(layerDir);
+        entries.push({
+            dir: layerDir,
+            id: layerId,
+            kind: "external",
+        });
+        emittedLayerIds.add(layerId);
+    }
+    await visitLayer(selectedLayerId);
+    return {
+        entries,
+        selectedLayerId,
+    };
+}
+export async function assertExternalTemplateLayersDoNotWriteProtectedOutputs({ externalEntries, protectedOutputPaths, view, }) {
+    for (const entry of externalEntries) {
+        if (entry.kind !== "external") {
+            continue;
+        }
+        const renderedOutputPaths = await listInterpolatedDirectoryOutputs(entry.dir, view);
+        for (const relativePath of renderedOutputPaths) {
+            if (!protectedOutputPaths.has(relativePath)) {
+                continue;
+            }
+            throw new Error(`External layer "${entry.id}" writes protected output "${relativePath}".`);
+        }
+    }
+}

package/dist/runtime/template-render.d.ts

@@ -26,4 +26,19 @@ export declare function renderMustacheTemplateString(template: string, view: Tem
 export declare function copyRawDirectory(sourceDir: string, targetDir: string, options?: CopyRawDirectoryOptions): Promise<void>;
 export declare function copyRenderedDirectory(sourceDir: string, targetDir: string, view: TemplateRenderView): Promise<void>;
 export declare function copyInterpolatedDirectory(sourceDir: string, targetDir: string, view: Record<string, string>): Promise<void>;
+/**
+ * Lists the output file paths produced by an interpolated template directory
+ * without writing any files to disk.
+ *
+ * This walks the source directory, applies the same filename interpolation and
+ * `.mustache` stripping rules as `copyInterpolatedDirectory(...)`, and returns
+ * normalized output-relative paths under a virtual root.
+ *
+ * @param sourceDir - The template directory to traverse.
+ * @param view - The interpolation map used when resolving file and directory
+ * names.
+ * @returns A sorted array of normalized output paths relative to a virtual
+ * preview root.
+ */
+export declare function listInterpolatedDirectoryOutputs(sourceDir: string, view: Record<string, string>): Promise<string[]>;
 export declare function pathExists(targetPath: string): boolean;

package/dist/runtime/template-render.js

@@ -118,6 +118,42 @@ export async function copyInterpolatedDirectory(sourceDir, targetDir, view) {
         await fsp.writeFile(destinationPath, renderInterpolatedString(content, view), "utf8");
     }
 }
+/**
+ * Lists the output file paths produced by an interpolated template directory
+ * without writing any files to disk.
+ *
+ * This walks the source directory, applies the same filename interpolation and
+ * `.mustache` stripping rules as `copyInterpolatedDirectory(...)`, and returns
+ * normalized output-relative paths under a virtual root.
+ *
+ * @param sourceDir - The template directory to traverse.
+ * @param view - The interpolation map used when resolving file and directory
+ * names.
+ * @returns A sorted array of normalized output paths relative to a virtual
+ * preview root.
+ */
+export async function listInterpolatedDirectoryOutputs(sourceDir, view) {
+    const virtualRoot = path.resolve("/wp-typia-template-preview");
+    const outputs = [];
+    async function visit(currentSourceDir, currentTargetDir) {
+        const entries = await fsp.readdir(currentSourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourcePath = path.join(currentSourceDir, entry.name);
+            const destinationNameTemplate = entry.name.endsWith(".mustache")
+                ? entry.name.slice(0, -".mustache".length)
+                : entry.name;
+            const destinationName = renderInterpolatedString(destinationNameTemplate, view);
+            const destinationPath = resolveRenderedPath(currentTargetDir, destinationName);
+            if (entry.isDirectory()) {
+                await visit(sourcePath, destinationPath);
+                continue;
+            }
+            outputs.push(path.relative(virtualRoot, destinationPath).replace(/\\/g, "/"));
+        }
+    }
+    await visit(sourceDir, virtualRoot);
+    return outputs.sort((left, right) => left.localeCompare(right));
+}
 export function pathExists(targetPath) {
     return fs.existsSync(targetPath);
 }

package/dist/runtime/template-source.d.ts

@@ -52,6 +52,14 @@ interface NpmTemplateLocator {
     rawSpec: string;
     type: string;
 }
+interface SeedSource {
+    assetsDir?: string;
+    blockDir: string;
+    cleanup?: () => Promise<void>;
+    rootDir: string;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
 type RemoteTemplateLocator = {
     kind: "github";
     locator: GitHubTemplateLocator;
@@ -65,6 +73,15 @@ type RemoteTemplateLocator = {
 export declare function parseGitHubTemplateLocator(templateId: string): GitHubTemplateLocator | null;
 export declare function parseNpmTemplateLocator(templateId: string): NpmTemplateLocator | null;
 export declare function parseTemplateLocator(templateId: string): RemoteTemplateLocator;
+/**
+ * Resolves a template locator into a local seed source directory.
+ *
+ * @param locator Remote template locator describing a local path, GitHub source, or npm package.
+ * @param cwd Current working directory used to resolve local template paths.
+ * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
+ * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
+ */
+export declare function resolveTemplateSeed(locator: RemoteTemplateLocator, cwd: string): Promise<SeedSource>;
 export declare function resolveTemplateSource(templateId: string, cwd: string, variables: {
     [key: string]: string;
 }, variant?: string): Promise<ResolvedTemplateSource>;

package/dist/runtime/template-source.js

@@ -13,6 +13,7 @@ import { BUILTIN_TEMPLATE_IDS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOL
 import { isPlainObject } from "./object-utils.js";
 import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, resolveBuiltInTemplateSource, } from "./template-builtins.js";
+import { loadExternalTemplateLayerManifest } from "./template-layers.js";
 import { getPackageVersions } from "./package-versions.js";
 import { toSegmentPascalCase } from "./string-case.js";
 import { copyRawDirectory, copyRenderedDirectory } from "./template-render.js";
@@ -315,6 +316,9 @@ async function detectTemplateSourceFormat(sourceDir) {
     if (fs.existsSync(path.join(sourceDir, "package.json.mustache"))) {
         return "wp-typia";
     }
+    if (await loadExternalTemplateLayerManifest(sourceDir)) {
+        throw new Error(`Template source at ${sourceDir} is an external layer package. External layers currently compose only through built-in scaffolds via the runtime API, not as standalone template ids.`);
+    }
     if (getExternalTemplateEntry(sourceDir)) {
         return "create-block-external";
     }
@@ -728,7 +732,15 @@ async function resolveGitHubTemplateSource(locator) {
         throw error;
     }
 }
-async function resolveTemplateSeed(locator, cwd) {
+/**
+ * Resolves a template locator into a local seed source directory.
+ *
+ * @param locator Remote template locator describing a local path, GitHub source, or npm package.
+ * @param cwd Current working directory used to resolve local template paths.
+ * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
+ * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
+ */
+export async function resolveTemplateSeed(locator, cwd) {
     if (locator.kind === "path") {
         const sourceDir = path.resolve(cwd, locator.templatePath);
         if (!fs.existsSync(sourceDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.16.7",
+  "version": "0.16.8",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",