@wp-typia/project-tools 0.16.6 → 0.16.8

package/dist/runtime/cli-prompt.d.ts

@@ -12,10 +12,35 @@ export interface ReadlinePrompt {
     select<T extends string>(message: string, options: PromptOption<T>[], defaultValue?: number): Promise<T>;
     text(message: string, defaultValue: string, validate?: ValidateInput): Promise<string>;
 }
+/**
+ * Adapter interface for readline-style prompt interactions.
+ *
+ * Public CLI code uses the native readline implementation, while tests can
+ * substitute lightweight doubles that expose the same `question` and `close`
+ * methods.
+ */
+export interface ReadlineQuestionAdapter {
+    /** Close the underlying prompt interface and release any open handles. */
+    close(): void;
+    /**
+     * Render one prompt and resolve with the collected answer string.
+     *
+     * @param query Prompt text written to the active output stream.
+     * @param callback Callback that receives the entered answer.
+     */
+    question(query: string, callback: (answer: string) => void): void;
+}
 /**
  * Create the default readline-backed prompt implementation for the CLI.
  *
  * @returns A prompt adapter that reads from stdin and writes to stdout.
  */
 export declare function createReadlinePrompt(): ReadlinePrompt;
+/**
+ * Build a prompt adapter around a supplied readline-style question interface.
+ *
+ * This keeps the production CLI path unchanged while letting tests validate
+ * retry behavior without stubbing global stdin/stdout.
+ */
+export declare function createReadlinePromptWithInterface(rl: ReadlineQuestionAdapter): ReadlinePrompt;
 export {};

package/dist/runtime/cli-prompt.js

@@ -9,21 +9,32 @@ export function createReadlinePrompt() {
         input: process.stdin,
         output: process.stdout,
     });
+    return createReadlinePromptWithInterface(rl);
+}
+/**
+ * Build a prompt adapter around a supplied readline-style question interface.
+ *
+ * This keeps the production CLI path unchanged while letting tests validate
+ * retry behavior without stubbing global stdin/stdout.
+ */
+export function createReadlinePromptWithInterface(rl) {
     return {
         async text(message, defaultValue, validate) {
             const suffix = defaultValue ? ` (${defaultValue})` : "";
-            const answer = await new Promise((resolve) => {
-                rl.question(`${message}${suffix}: `, resolve);
-            });
-            const value = String(answer).trim() || defaultValue;
-            if (validate) {
-                const result = validate(value);
-                if (result !== true) {
-                    console.error(`❌ ${typeof result === "string" ? result : "Invalid input"}`);
-                    return this.text(message, defaultValue, validate);
+            while (true) {
+                const answer = await new Promise((resolve) => {
+                    rl.question(`${message}${suffix}: `, resolve);
+                });
+                const value = String(answer).trim() || defaultValue;
+                if (validate) {
+                    const result = validate(value);
+                    if (result !== true) {
+                        console.error(`❌ ${typeof result === "string" ? result : "Invalid input"}`);
+                        continue;
+                    }
                 }
+                return value;
             }
-            return value;
         },
         async select(message, options, defaultValue = 1) {
             if (options.length === 0) {
@@ -34,17 +45,18 @@ export function createReadlinePrompt() {
                 const hint = option.hint ? ` - ${option.hint}` : "";
                 console.log(`  ${index + 1}. ${option.label}${hint}`);
             });
-            const answer = await this.text("Choice", String(defaultValue));
-            const numericChoice = Number(answer);
-            if (!Number.isNaN(numericChoice) && options[numericChoice - 1]) {
-                return options[numericChoice - 1].value;
-            }
-            const directChoice = options.find((option) => option.value === answer);
-            if (directChoice) {
-                return directChoice.value;
+            while (true) {
+                const answer = await this.text("Choice", String(defaultValue));
+                const numericChoice = Number(answer);
+                if (!Number.isNaN(numericChoice) && options[numericChoice - 1]) {
+                    return options[numericChoice - 1].value;
+                }
+                const directChoice = options.find((option) => option.value === answer);
+                if (directChoice) {
+                    return directChoice.value;
+                }
+                console.error(`❌ Invalid selection: ${answer}`);
             }
-            console.error(`❌ Invalid selection: ${answer}`);
-            return this.select(message, options, defaultValue);
         },
         close() {
             rl.close();

package/dist/runtime/cli-scaffold.js

@@ -4,8 +4,7 @@ import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDat
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
-import { isBuiltInTemplateId } from "./template-registry.js";
-const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 function templateUsesPersistenceSettings(templateId, options) {
     if (templateId === "persistence") {
         return true;

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/migration-types.d.ts

@@ -1,56 +1,12 @@
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-export type ManifestTsKind = "string" | "number" | "boolean" | "array" | "object" | "union";
-export interface ManifestConstraints {
-    exclusiveMaximum?: number | null;
-    exclusiveMinimum?: number | null;
-    format?: string | null;
-    maxLength?: number | null;
-    maxItems?: number | null;
-    maximum?: number | null;
-    minLength?: number | null;
-    minItems?: number | null;
-    minimum?: number | null;
-    multipleOf?: number | null;
-    pattern?: string | null;
-    typeTag?: string | null;
-}
-export interface ManifestUnionMetadata {
-    discriminator: string;
-    branches: Record<string, ManifestAttribute>;
-}
-export interface ManifestTsMetadata {
-    items?: ManifestAttribute | null;
-    kind: ManifestTsKind;
-    properties?: Record<string, ManifestAttribute> | null;
-    required?: boolean;
-    union?: ManifestUnionMetadata | null;
-}
-export interface ManifestTypiaMetadata {
-    constraints: ManifestConstraints;
-    defaultValue?: JsonValue | null;
-    hasDefault?: boolean;
-}
-export interface ManifestWpMetadata {
-    defaultValue?: JsonValue | null;
-    enum?: JsonValue[] | null;
-    hasDefault?: boolean;
-    selector?: string | null;
-    source?: "html" | "text" | "rich-text" | null;
-    type?: string | null;
-}
-export interface ManifestAttribute {
-    ts: ManifestTsMetadata;
-    typia: ManifestTypiaMetadata;
-    wp: ManifestWpMetadata;
-}
-export interface ManifestDocument {
-    attributes?: Record<string, ManifestAttribute>;
-    manifestVersion?: number | null;
-    sourceType?: string | null;
-}
+/**
+ * Shared migration contract facade for project-tools runtime.
+ *
+ * Re-exports canonical manifest and migration contracts from
+ * `@wp-typia/block-runtime/migration-types` and layers project-tools-specific
+ * migration workspace types on top.
+ */
+import type { JsonValue, ManifestAttribute, ManifestDocument } from "@wp-typia/block-runtime/migration-types";
+export type { JsonPrimitive, JsonValue, ManifestAttribute, ManifestConstraints, ManifestDocument, ManifestTsKind, ManifestTsMetadata, ManifestTypiaMetadata, ManifestUnionMetadata, ManifestWpMetadata, } from "@wp-typia/block-runtime/migration-types";
 export interface ManifestSummaryAttribute {
     constraints: ManifestAttribute["typia"]["constraints"];
     defaultValue: ManifestAttribute["typia"]["defaultValue"] | null;

package/dist/runtime/scaffold.js

@@ -13,13 +13,12 @@ import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-man
 import { toKebabCase, toPascalCase, toSnakeCase, toTitleCase, } from "./string-case.js";
 import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from "./block-generator-service.js";
 const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 const PHP_PREFIX_PATTERN = /^[a-z_][a-z0-9_]*$/;
 const PHP_PREFIX_MAX_LENGTH = 50;
-const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const LOCKFILES = {

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}".`);
+        }
+    }
+}