@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/templates/scaffold.js

@@ -0,0 +1,255 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { getPackageManager } from "../shared/package-managers.js";
+import { buildGitignore, buildReadme, mergeTextLines, removeQueryLoopPlaceholderFiles, replaceTextRecursively, } from "./scaffold-apply-utils.js";
+import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
+import { runAddIntegrationEnvCommand } from "../add/cli-add-workspace-integration-env.js";
+import { applyMigrationUiCapability } from "../migration/migration-ui-capability.js";
+import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
+import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
+import { copyInterpolatedDirectory } from "./template-render.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
+import { resolveTemplateSource } from "./template-source.js";
+import { BlockGeneratorService, } from "./block-generator-service.js";
+import { getTemplateVariables } from "./scaffold-template-variables.js";
+import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+import { assertExternalLayerCompositionOptions, } from "../cli/cli-validation.js";
+import { pathExists } from "../shared/fs-async.js";
+export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
+export const PERSISTENCE_POLICIES = ["authenticated", "public"];
+/** Supported create profile ids for opt-in workspace scaffold presets. */
+export const CREATE_PROFILE_IDS = ["plugin-qa"];
+export { buildBlockCssClassName } from "./scaffold-identifiers.js";
+export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
+export { getTemplateVariables } from "./scaffold-template-variables.js";
+export { getScaffoldTemplateVariableGroups, } from "./scaffold-template-variable-groups.js";
+export function isDataStorageMode(value) {
+    return DATA_STORAGE_MODES.includes(value);
+}
+export function isPersistencePolicy(value) {
+    return PERSISTENCE_POLICIES.includes(value);
+}
+/**
+ * Return whether a raw string is a supported create profile id.
+ */
+export function isCreateProfileId(value) {
+    return CREATE_PROFILE_IDS.includes(value);
+}
+/**
+ * Resolve an optional create profile flag into a validated profile id.
+ *
+ * Empty input disables profile application; unknown ids throw with the allowed
+ * profile list for CLI diagnostics.
+ */
+export function resolveCreateProfileId(profile) {
+    if (profile === undefined || profile.trim().length === 0) {
+        return undefined;
+    }
+    const normalizedProfile = profile.trim();
+    if (isCreateProfileId(normalizedProfile)) {
+        return normalizedProfile;
+    }
+    throw new Error(`Unknown create profile "${profile}". Expected one of: ${CREATE_PROFILE_IDS.join(", ")}.`);
+}
+function normalizeTemplateSelection(templateId) {
+    return normalizeTemplateLookupId(templateId);
+}
+function assertCreateProfileTemplateCompatibility({ profile, templateId, }) {
+    if (!profile) {
+        return;
+    }
+    if (profile === "plugin-qa" && templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        throw new Error("`--profile plugin-qa` currently supports only the official workspace template. Use `--template workspace` or add QA files later with `wp-typia add integration-env <name> --wp-env --release-zip`.");
+    }
+}
+async function applyCreateProfile({ profile, projectDir, }) {
+    if (profile !== "plugin-qa") {
+        return;
+    }
+    await runAddIntegrationEnvCommand({
+        cwd: projectDir,
+        integrationEnvName: "local-smoke",
+        service: "none",
+        withReleaseZip: true,
+        withWpEnv: true,
+    });
+}
+async function reportScaffoldProgress(onProgress, event) {
+    await onProgress?.(event);
+}
+export async function scaffoldProject({ projectDir, templateId, answers, alternateRenderTargets, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, profile, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+    const resolvedTemplateId = normalizeTemplateSelection(templateId);
+    const resolvedPackageManager = getPackageManager(packageManager).id;
+    const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
+    assertCreateProfileTemplateCompatibility({
+        profile,
+        templateId: resolvedTemplateId,
+    });
+    assertExternalLayerCompositionOptions({
+        externalLayerId,
+        externalLayerSource,
+    });
+    if (isBuiltInTemplate) {
+        const blockGeneratorService = new BlockGeneratorService();
+        await reportScaffoldProgress(onProgress, {
+            detail: "Preparing template layers, variants, and generated artifact plans.",
+            phase: "resolve-template",
+            title: "Resolving scaffold template",
+        });
+        const plan = await blockGeneratorService.plan({
+            allowExistingDir,
+            alternateRenderTargets,
+            answers,
+            cwd,
+            dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
+            externalLayerId,
+            externalLayerSource,
+            externalLayerSourceLabel,
+            noInstall,
+            packageManager: resolvedPackageManager,
+            persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
+            projectDir,
+            repositoryReference,
+            templateId: resolvedTemplateId,
+            variant,
+            withMigrationUi,
+            withTestPreset,
+            withWpEnv,
+        });
+        const validated = await blockGeneratorService.validate({ plan });
+        const rendered = await blockGeneratorService.render({ validated });
+        return blockGeneratorService.apply({
+            installDependencies,
+            onProgress,
+            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,
+        persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
+    });
+    await reportScaffoldProgress(onProgress, {
+        detail: "Loading template files, variants, and external package metadata when needed.",
+        phase: "resolve-template",
+        title: "Resolving scaffold template",
+    });
+    const templateSource = await resolveTemplateSource(resolvedTemplateId, cwd, variables, variant);
+    const supportsMigrationUi = isBuiltInTemplate ||
+        templateSource.isOfficialWorkspaceTemplate === true ||
+        templateSource.supportsMigrationUi === true;
+    if (withMigrationUi && !supportsMigrationUi) {
+        await templateSource.cleanup?.();
+        throw new Error("`--with-migration-ui` is currently supported only for built-in templates and workspace-capable wp-typia templates.");
+    }
+    try {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Copying scaffold files into the target project directory.",
+            phase: "generate-files",
+            title: "Generating project files",
+        });
+        await ensureScaffoldDirectory(projectDir, allowExistingDir);
+        await copyInterpolatedDirectory(templateSource.templateDir, projectDir, variables);
+    }
+    finally {
+        if (templateSource.cleanup) {
+            await templateSource.cleanup();
+        }
+    }
+    const isWorkspace = isWorkspaceProject(projectDir);
+    if (isBuiltInTemplate) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Writing starter manifests, local presets, and template-specific generated artifacts.",
+            phase: "seed-artifacts",
+            title: "Seeding scaffold artifacts",
+        });
+        await writeStarterManifestFiles(projectDir, resolvedTemplateId, variables);
+        await seedBuiltInPersistenceArtifacts(projectDir, resolvedTemplateId, variables);
+        await applyLocalDevPresetFiles({
+            projectDir,
+            variables,
+            withTestPreset,
+            withWpEnv,
+        });
+        if (withMigrationUi) {
+            await applyMigrationUiCapability({
+                packageManager: resolvedPackageManager,
+                projectDir,
+                templateId: resolvedTemplateId,
+                variables,
+            });
+        }
+        await removeQueryLoopPlaceholderFiles(projectDir, resolvedTemplateId);
+    }
+    else if (withMigrationUi && isWorkspace) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Initializing workspace migration scripts and starter migration files.",
+            phase: "seed-artifacts",
+            title: "Seeding scaffold artifacts",
+        });
+        await applyWorkspaceMigrationCapability(projectDir, resolvedPackageManager);
+    }
+    await reportScaffoldProgress(onProgress, {
+        detail: "Writing README, normalizing package metadata, and aligning package-manager files.",
+        phase: "finalize-project",
+        title: "Finalizing scaffold output",
+    });
+    const readmePath = path.join(projectDir, "README.md");
+    if (!(await pathExists(readmePath))) {
+        await fsp.writeFile(readmePath, buildReadme(resolvedTemplateId, variables, resolvedPackageManager, {
+            withMigrationUi: isBuiltInTemplate || isWorkspace ? withMigrationUi : false,
+            withTestPreset: isBuiltInTemplate ? withTestPreset : false,
+            withWpEnv: isBuiltInTemplate ? withWpEnv : false,
+        }), "utf8");
+    }
+    const gitignorePath = path.join(projectDir, ".gitignore");
+    const existingGitignore = (await pathExists(gitignorePath))
+        ? await fsp.readFile(gitignorePath, "utf8")
+        : "";
+    await fsp.writeFile(gitignorePath, mergeTextLines(buildGitignore(), existingGitignore), "utf8");
+    await normalizePackageJson(projectDir, resolvedPackageManager);
+    if (isBuiltInTemplate) {
+        const variableGroups = getScaffoldTemplateVariableGroups(variables);
+        await applyGeneratedProjectDxPackageJson({
+            compoundPersistenceEnabled: variableGroups.compound.enabled &&
+                variableGroups.compound.persistenceEnabled,
+            packageManager: resolvedPackageManager,
+            projectDir,
+            templateId: resolvedTemplateId,
+            withTestPreset,
+            withWpEnv,
+        });
+    }
+    await applyCreateProfile({
+        profile,
+        projectDir,
+    });
+    await normalizePackageManagerFiles(projectDir, resolvedPackageManager);
+    await removeUnexpectedLockfiles(projectDir, resolvedPackageManager);
+    await replaceTextRecursively(projectDir, resolvedPackageManager, {
+        repositoryReference,
+    });
+    if (!noInstall) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Installing project dependencies with the selected package manager.",
+            phase: "install-dependencies",
+            title: "Installing dependencies",
+        });
+        const installer = installDependencies ?? defaultInstallDependencies;
+        await installer({
+            projectDir,
+            packageManager: resolvedPackageManager,
+        });
+    }
+    return {
+        projectDir,
+        selectedVariant: templateSource.selectedVariant ?? null,
+        templateId: resolvedTemplateId,
+        packageManager: resolvedPackageManager,
+        variables,
+        warnings: templateSource.warnings ?? [],
+    };
+}

package/dist/runtime/templates/starter-manifests.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scaffold-time starter manifest builders for generated projects.
+ *
+ * These helpers now reuse the Phase 2 built-in artifact model so generated
+ * `types.ts`, `block.json`, and starter `typia.manifest.json` all share the
+ * same attribute metadata source of truth.
+ */
+import type { ManifestDocument } from "../migration/migration-types.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+/**
+ * Builds the starter manifest used by generated compound child blocks.
+ */
+export declare function buildCompoundChildStarterManifestDocument(childTypeName: string, childTitle: string, bodyPlaceholder?: string): ManifestDocument;
+/**
+ * Returns the starter manifest files that should be seeded for a built-in
+ * template before the first sync.
+ */
+export declare function getStarterManifestFiles(templateId: string, variables: ScaffoldTemplateVariables): Array<{
+    document: ManifestDocument;
+    relativePath: string;
+}>;
+/**
+ * Serializes a starter manifest using the generated-project JSON formatting
+ * convention.
+ */
+export declare function stringifyStarterManifest(document: ManifestDocument): string;

package/dist/runtime/templates/starter-manifests.js

@@ -0,0 +1,33 @@
+import { buildBuiltInBlockArtifacts, buildCompoundChildStarterManifestDocument as buildCompoundChildStarterManifestFromArtifacts, } from "./built-in-block-artifacts.js";
+/**
+ * Builds the starter manifest used by generated compound child blocks.
+ */
+export function buildCompoundChildStarterManifestDocument(childTypeName, childTitle, bodyPlaceholder) {
+    return buildCompoundChildStarterManifestFromArtifacts(childTypeName, childTitle, bodyPlaceholder);
+}
+/**
+ * Returns the starter manifest files that should be seeded for a built-in
+ * template before the first sync.
+ */
+export function getStarterManifestFiles(templateId, variables) {
+    if (templateId !== "basic" &&
+        templateId !== "interactivity" &&
+        templateId !== "persistence" &&
+        templateId !== "compound") {
+        return [];
+    }
+    return buildBuiltInBlockArtifacts({
+        templateId,
+        variables,
+    }).map((artifact) => ({
+        document: artifact.manifestDocument,
+        relativePath: `${artifact.relativeDir}/typia.manifest.json`,
+    }));
+}
+/**
+ * Serializes a starter manifest using the generated-project JSON formatting
+ * convention.
+ */
+export function stringifyStarterManifest(document) {
+    return `${JSON.stringify(document, null, "\t")}\n`;
+}

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

@@ -0,0 +1,57 @@
+import { type BuiltInTemplateId } from "./template-registry.js";
+/**
+ * Controls which persistence layer is applied when materializing the built-in
+ * `persistence` template.
+ */
+export type BuiltInPersistencePolicy = "authenticated" | "public";
+export interface BuiltInTemplateVariantOptions {
+    persistenceEnabled?: boolean;
+    persistencePolicy?: BuiltInPersistencePolicy;
+}
+export interface MaterializedBuiltInTemplateSource {
+    id: BuiltInTemplateId;
+    defaultCategory: string;
+    description: string;
+    features: string[];
+    format: "wp-typia";
+    templateDir: string;
+    cleanup?: () => Promise<void>;
+    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.
+ *
+ * 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 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.
+ *
+ * @param templateId Built-in template family being resolved.
+ * @param layerDir Candidate overlay directory for that family.
+ * @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.
+ *
+ * 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 declare function resolveBuiltInTemplateSource(templateId: BuiltInTemplateId, options?: BuiltInTemplateVariantOptions): Promise<MaterializedBuiltInTemplateSource>;

package/dist/runtime/templates/template-builtins.js

@@ -0,0 +1,196 @@
+import path from "node:path";
+import { promises as fsp } from "node:fs";
+import { pathExists } from "../shared/fs-async.js";
+import { createManagedTempRoot } from "../shared/temp-roots.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",
+]);
+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,
+            path.join(SHARED_REST_HELPER_TEMPLATE_ROOT, "shared"),
+            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"),
+        ];
+    }
+    if (templateId === "compound") {
+        const layers = [
+            SHARED_BASE_TEMPLATE_ROOT,
+            path.join(SHARED_COMPOUND_TEMPLATE_ROOT, "core"),
+        ];
+        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];
+}
+/**
+ * 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
+ * template family no longer ships any Mustache assets in that layer.
+ *
+ * @param templateId Built-in template family being resolved.
+ * @param layerDir Candidate overlay directory for that family.
+ * @returns True when the missing layer can be skipped safely.
+ */
+export function isOmittableBuiltInTemplateLayerDir(templateId, layerDir) {
+    return (OMITTABLE_BUILT_IN_OVERLAY_TEMPLATE_IDS.has(templateId) &&
+        layerDir === getTemplateById(templateId).templateDir);
+}
+async function resolveMaterializedTemplateLayerDirs(templateId, layerDirs) {
+    const materializedLayerDirs = [];
+    for (const layerDir of layerDirs) {
+        if (await pathExists(layerDir)) {
+            materializedLayerDirs.push(layerDir);
+            continue;
+        }
+        if (isOmittableBuiltInTemplateLayerDir(templateId, layerDir)) {
+            continue;
+        }
+        throw new Error(`Built-in template layer is missing: ${layerDir}`);
+    }
+    return materializedLayerDirs;
+}
+async function materializeBuiltInTemplateSource(templateId, layerDirs) {
+    const template = getTemplateById(templateId);
+    const materializedLayerDirs = await resolveMaterializedTemplateLayerDirs(templateId, layerDirs);
+    const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-template-");
+    const templateDir = path.join(tempRoot, templateId);
+    try {
+        await fsp.mkdir(templateDir, { recursive: true });
+        for (const layerDir of materializedLayerDirs) {
+            await fsp.cp(layerDir, templateDir, {
+                recursive: true,
+                force: true,
+            });
+        }
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+    return {
+        id: templateId,
+        defaultCategory: template.defaultCategory,
+        description: template.description,
+        features: template.features,
+        format: "wp-typia",
+        templateDir,
+        cleanup,
+    };
+}
+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/templates/template-defaults.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Internal built-in template metadata defaults used by scaffold rendering.
+ */
+export declare const BUILTIN_BLOCK_METADATA_VERSION = "0.1.0";
+/**
+ * Built-in parent block metadata defaults keyed by template id.
+ */
+export declare const BUILTIN_TEMPLATE_METADATA_DEFAULTS: Readonly<{
+    basic: Readonly<{
+        category: "text";
+        icon: "smiley";
+    }>;
+    interactivity: Readonly<{
+        category: "widgets";
+        icon: "smiley";
+    }>;
+    persistence: Readonly<{
+        category: "widgets";
+        icon: "database";
+    }>;
+    compound: Readonly<{
+        category: "widgets";
+        icon: "screenoptions";
+    }>;
+    "query-loop": Readonly<{
+        category: "widgets";
+        icon: "query-pagination";
+    }>;
+}>;
+/**
+ * Shared hidden child block metadata defaults for compound scaffolds.
+ */
+export declare const COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS: Readonly<{
+    category: "widgets";
+    icon: "excerpt-view";
+}>;
+/**
+ * Legacy built-in template ids that were removed in favor of persistence modes.
+ */
+export declare const REMOVED_BUILTIN_TEMPLATE_IDS: readonly ["data", "persisted"];
+/**
+ * Union of removed built-in template ids accepted by compatibility checks.
+ */
+export type RemovedBuiltInTemplateId = (typeof REMOVED_BUILTIN_TEMPLATE_IDS)[number];
+/**
+ * Returns the metadata defaults for a built-in scaffold template id.
+ *
+ * @param templateId Built-in template id whose metadata defaults should be read.
+ * @returns The stable category/icon defaults used by scaffold rendering.
+ */
+export declare function getBuiltInTemplateMetadataDefaults(templateId: keyof typeof BUILTIN_TEMPLATE_METADATA_DEFAULTS): Readonly<{
+    category: "text";
+    icon: "smiley";
+}> | Readonly<{
+    category: "widgets";
+    icon: "smiley";
+}> | Readonly<{
+    category: "widgets";
+    icon: "database";
+}> | Readonly<{
+    category: "widgets";
+    icon: "screenoptions";
+}> | Readonly<{
+    category: "widgets";
+    icon: "query-pagination";
+}>;
+/**
+ * Checks whether a template id points at a removed built-in scaffold.
+ *
+ * @param templateId Template id supplied to scaffold resolution.
+ * @returns True when the template id is one of the removed legacy built-ins.
+ */
+export declare function isRemovedBuiltInTemplateId(templateId: string): templateId is RemovedBuiltInTemplateId;
+/**
+ * Builds the stable recovery guidance shown for removed built-in template ids.
+ *
+ * @param templateId Removed template id, where `data` maps to the public policy and
+ * `persisted` maps to the authenticated policy.
+ * @returns A user-facing error string in the form
+ * `Built-in template "<id>" was removed. Use --template persistence --persistence-policy <policy> instead.`
+ */
+export declare function getRemovedBuiltInTemplateMessage(templateId: RemovedBuiltInTemplateId): string;