@wp-typia/project-tools 0.16.7 → 0.16.9

package/dist/runtime/scaffold-apply-utils.js

@@ -14,6 +14,7 @@ import { stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.j
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 import { formatInstallCommand, formatPackageExecCommand, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LOCKFILES = {
@@ -265,7 +266,11 @@ export async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
         }
     }));
 }
-export async function replaceTextRecursively(targetDir, packageManagerId) {
+/**
+ * Recursively normalizes generated text files for the selected package manager
+ * and repository reference.
+ */
+export async function replaceTextRecursively(targetDir, packageManagerId, { repositoryManifestPaths, repositoryReference, } = {}) {
     const textExtensions = new Set([
         ".css",
         ".js",
@@ -278,6 +283,10 @@ export async function replaceTextRecursively(targetDir, packageManagerId) {
         ".tsx",
         ".txt",
     ]);
+    const resolvedRepositoryReference = repositoryReference ??
+        resolveScaffoldRepositoryReference({
+            manifestPaths: repositoryManifestPaths,
+        });
     async function visit(currentPath) {
         const stats = await fsp.stat(currentPath);
         if (stats.isDirectory()) {
@@ -291,9 +300,7 @@ export async function replaceTextRecursively(targetDir, packageManagerId) {
             return;
         }
         const content = await fsp.readFile(currentPath, "utf8");
-        const nextContent = transformPackageManagerText(content, packageManagerId)
-            .replace(/yourusername\/wp-typia-boilerplate/g, "imjlk/wp-typia")
-            .replace(/yourusername\/wp-typia/g, "imjlk/wp-typia");
+        const nextContent = replaceRepositoryReferencePlaceholders(transformPackageManagerText(content, packageManagerId), resolvedRepositoryReference);
         if (nextContent !== content) {
             await fsp.writeFile(currentPath, nextContent, "utf8");
         }
@@ -344,7 +351,11 @@ export async function applyWorkspaceMigrationCapability(projectDir, packageManag
     ensureMigrationDirectories(projectDir, []);
     writeInitialMigrationScaffold(projectDir, "v1", []);
 }
-export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir = false, packageManager, withMigrationUi = false, withTestPreset = false, withWpEnv = false, noInstall = false, installDependencies, }) {
+/**
+ * Applies a built-in scaffold into the target directory, including generated
+ * code artifacts, starter manifests, preset files, and placeholder rewrites.
+ */
+export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir = false, packageManager, withMigrationUi = false, withTestPreset = false, withWpEnv = false, noInstall = false, installDependencies, repositoryReference, }) {
     await ensureDirectory(projectDir, allowExistingDir);
     await copyInterpolatedDirectory(templateDir, projectDir, variables);
     if (codeArtifacts && codeArtifacts.length > 0) {
@@ -394,7 +405,9 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
     });
     await normalizePackageManagerFiles(projectDir, packageManager);
     await removeUnexpectedLockfiles(projectDir, packageManager);
-    await replaceTextRecursively(projectDir, packageManager);
+    await replaceTextRecursively(projectDir, packageManager, {
+        repositoryReference,
+    });
     if (!noInstall) {
         const installer = installDependencies ?? defaultInstallDependencies;
         await installer({

package/dist/runtime/scaffold-repository-reference.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Default scaffold repository reference used when no GitHub repository metadata
+ * can be resolved from the current runtime package manifests.
+ */
+export declare const DEFAULT_SCAFFOLD_REPOSITORY_REFERENCE = "imjlk/wp-typia";
+/**
+ * Resolves the canonical scaffold repository reference in `owner/repo` format.
+ *
+ * The resolver checks candidate package manifests in priority order, extracts
+ * their `repository` field, and returns the first GitHub slug it can parse.
+ * When no candidate yields a GitHub repository reference, the fallback value
+ * is returned instead.
+ */
+export declare function resolveScaffoldRepositoryReference({ fallback, manifestPaths, }?: {
+    fallback?: string;
+    manifestPaths?: readonly string[];
+}): string;
+/**
+ * Replaces legacy scaffold repository placeholders with a concrete
+ * `owner/repo` reference.
+ */
+export declare function replaceRepositoryReferencePlaceholders(source: string, repositoryReference: string): string;

package/dist/runtime/scaffold-repository-reference.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { PROJECT_TOOLS_PACKAGE_ROOT } from "./template-registry.js";
+const require = createRequire(import.meta.url);
+/**
+ * Default scaffold repository reference used when no GitHub repository metadata
+ * can be resolved from the current runtime package manifests.
+ */
+export const DEFAULT_SCAFFOLD_REPOSITORY_REFERENCE = "imjlk/wp-typia";
+function getErrorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function readRepositoryPackageManifest(packageJsonPath) {
+    try {
+        return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        if (getErrorCode(error) === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function resolveInstalledPackageManifestPath(packageName) {
+    try {
+        return require.resolve(`${packageName}/package.json`);
+    }
+    catch (error) {
+        if (getErrorCode(error) === "MODULE_NOT_FOUND") {
+            return null;
+        }
+        throw error;
+    }
+}
+function getRepositoryFieldValue(manifest) {
+    if (!manifest?.repository) {
+        return undefined;
+    }
+    return typeof manifest.repository === "string"
+        ? manifest.repository
+        : manifest.repository.url;
+}
+function parseRepositoryReference(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const githubShorthandMatch = trimmed.match(/^github:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:#.*)?$/u);
+    if (githubShorthandMatch) {
+        return `${githubShorthandMatch[1]}/${githubShorthandMatch[2]}`;
+    }
+    if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(trimmed)) {
+        return trimmed;
+    }
+    const githubScpMatch = trimmed.match(/^git@github\.com:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:#.*)?$/u);
+    if (githubScpMatch) {
+        return `${githubScpMatch[1]}/${githubScpMatch[2]}`;
+    }
+    const normalizedValue = trimmed
+        .replace(/^git\+/u, "")
+        .replace(/#.*$/u, "");
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(normalizedValue);
+    }
+    catch {
+        return null;
+    }
+    if (parsedUrl.hostname !== "github.com") {
+        return null;
+    }
+    const pathSegments = parsedUrl.pathname
+        .replace(/^\/+/u, "")
+        .replace(/\.git$/u, "")
+        .split("/");
+    if (pathSegments.length < 2 || !pathSegments[0] || !pathSegments[1]) {
+        return null;
+    }
+    return `${pathSegments[0]}/${pathSegments[1]}`;
+}
+function getDefaultRepositoryManifestPaths() {
+    const candidatePaths = [
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "..", "package.json"),
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia", "package.json"),
+        path.join(PROJECT_TOOLS_PACKAGE_ROOT, "package.json"),
+        resolveInstalledPackageManifestPath("wp-typia"),
+        resolveInstalledPackageManifestPath("@wp-typia/project-tools"),
+    ].filter((candidatePath) => Boolean(candidatePath));
+    return candidatePaths.filter((candidatePath, index, allPaths) => allPaths.indexOf(candidatePath) === index);
+}
+/**
+ * Resolves the canonical scaffold repository reference in `owner/repo` format.
+ *
+ * The resolver checks candidate package manifests in priority order, extracts
+ * their `repository` field, and returns the first GitHub slug it can parse.
+ * When no candidate yields a GitHub repository reference, the fallback value
+ * is returned instead.
+ */
+export function resolveScaffoldRepositoryReference({ fallback = DEFAULT_SCAFFOLD_REPOSITORY_REFERENCE, manifestPaths = getDefaultRepositoryManifestPaths(), } = {}) {
+    for (const manifestPath of manifestPaths) {
+        const repositoryReference = parseRepositoryReference(getRepositoryFieldValue(readRepositoryPackageManifest(manifestPath)));
+        if (repositoryReference) {
+            return repositoryReference;
+        }
+    }
+    return fallback;
+}
+/**
+ * Replaces legacy scaffold repository placeholders with a concrete
+ * `owner/repo` reference.
+ */
+export function replaceRepositoryReferencePlaceholders(source, repositoryReference) {
+    return source
+        .replace(/yourusername\/wp-typia-boilerplate/g, repositoryReference)
+        .replace(/yourusername\/wp-typia/g, repositoryReference);
+}

package/dist/runtime/scaffold.d.ts

@@ -115,11 +115,15 @@ interface ScaffoldProjectOptions {
     answers: ScaffoldAnswers;
     cwd?: string;
     dataStorageMode?: DataStorageMode;
+    externalLayerId?: string;
+    externalLayerSource?: string;
+    externalLayerSourceLabel?: string;
     installDependencies?: ((options: InstallDependenciesOptions) => Promise<void>) | undefined;
     noInstall?: boolean;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
     projectDir: string;
+    repositoryReference?: string;
     templateId: string;
     variant?: string;
     withMigrationUi?: boolean;
@@ -153,5 +157,5 @@ export declare function resolveTemplateId({ templateId, yes, isInteractive, sele
 export declare function resolvePackageManagerId({ packageManager, yes, isInteractive, selectPackageManager, }: ResolvePackageManagerOptions): Promise<PackageManagerId>;
 export declare function collectScaffoldAnswers({ projectName, templateId, yes, dataStorageMode, namespace, persistencePolicy, phpPrefix, promptText, textDomain, }: CollectScaffoldAnswersOptions): Promise<ScaffoldAnswers>;
 export declare function getTemplateVariables(templateId: string, answers: ScaffoldAnswers): ScaffoldTemplateVariables;
-export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, cwd, allowExistingDir, noInstall, installDependencies, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
+export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
 export {};

package/dist/runtime/scaffold.js

@@ -3,6 +3,7 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { PACKAGE_MANAGER_IDS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { replaceTextRecursively } from "./scaffold-apply-utils.js";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, getPrimaryDevelopmentScript, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { getPackageVersions } from "./package-versions.js";
@@ -563,41 +564,6 @@ async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
         }
     }));
 }
-async function replaceTextRecursively(targetDir, packageManagerId) {
-    const textExtensions = new Set([
-        ".css",
-        ".js",
-        ".json",
-        ".jsx",
-        ".md",
-        ".php",
-        ".scss",
-        ".ts",
-        ".tsx",
-        ".txt",
-    ]);
-    async function visit(currentPath) {
-        const stats = await fsp.stat(currentPath);
-        if (stats.isDirectory()) {
-            const entries = await fsp.readdir(currentPath);
-            for (const entry of entries) {
-                await visit(path.join(currentPath, entry));
-            }
-            return;
-        }
-        if (path.basename(currentPath) === "package.json" || !textExtensions.has(path.extname(currentPath))) {
-            return;
-        }
-        const content = await fsp.readFile(currentPath, "utf8");
-        const nextContent = transformPackageManagerText(content, packageManagerId)
-            .replace(/yourusername\/wp-typia-boilerplate/g, "imjlk/wp-typia")
-            .replace(/yourusername\/wp-typia/g, "imjlk/wp-typia");
-        if (nextContent !== content) {
-            await fsp.writeFile(currentPath, nextContent, "utf8");
-        }
-    }
-    await visit(targetDir);
-}
 async function defaultInstallDependencies({ projectDir, packageManager, }) {
     execSync(formatInstallCommand(packageManager), {
         cwd: projectDir,
@@ -642,10 +608,13 @@ async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
     ensureMigrationDirectories(projectDir, []);
     writeInitialMigrationScaffold(projectDir, "v1", []);
 }
-export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
     const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    if (externalLayerId && !externalLayerSource) {
+        throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
+    }
     if (isBuiltInTemplate) {
         const blockGeneratorService = new BlockGeneratorService();
         const plan = await blockGeneratorService.plan({
@@ -653,10 +622,14 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             answers,
             cwd,
             dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
+            externalLayerId,
+            externalLayerSource,
+            externalLayerSourceLabel,
             noInstall,
             packageManager: resolvedPackageManager,
             persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
             projectDir,
+            repositoryReference,
             templateId: resolvedTemplateId,
             variant,
             withMigrationUi,
@@ -670,6 +643,9 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             rendered,
         });
     }
+    if (externalLayerSource || externalLayerId) {
+        throw new Error("External template layers currently compose only with built-in templates via `wp-typia create --template <basic|interactivity|persistence|compound>` or `wp-typia add block --template <family>`.");
+    }
     const variables = getTemplateVariables(resolvedTemplateId, {
         ...answers,
         dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
@@ -738,7 +714,9 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     }
     await normalizePackageManagerFiles(projectDir, resolvedPackageManager);
     await removeUnexpectedLockfiles(projectDir, resolvedPackageManager);
-    await replaceTextRecursively(projectDir, resolvedPackageManager);
+    await replaceTextRecursively(projectDir, resolvedPackageManager, {
+        repositoryReference,
+    });
     if (!noInstall) {
         const installer = installDependencies ?? defaultInstallDependencies;
         await installer({

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,37 @@
+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 interface SelectableExternalTemplateLayer {
+    description?: string;
+    extends: string[];
+    id: string;
+}
+export declare function loadExternalTemplateLayerManifest(sourceRoot: string): Promise<ExternalTemplateLayerManifest | null>;
+export declare function listSelectableExternalTemplateLayers(sourceRoot: string): Promise<SelectableExternalTemplateLayer[]>;
+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 {};