@wp-typia/project-tools 0.24.4 → 0.24.5

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

@@ -0,0 +1,69 @@
+/**
+ * Internal built-in template metadata defaults used by scaffold rendering.
+ */
+export const BUILTIN_BLOCK_METADATA_VERSION = "0.1.0";
+/**
+ * Built-in parent block metadata defaults keyed by template id.
+ */
+export const BUILTIN_TEMPLATE_METADATA_DEFAULTS = Object.freeze({
+    basic: Object.freeze({
+        category: "text",
+        icon: "smiley",
+    }),
+    interactivity: Object.freeze({
+        category: "widgets",
+        icon: "smiley",
+    }),
+    persistence: Object.freeze({
+        category: "widgets",
+        icon: "database",
+    }),
+    compound: Object.freeze({
+        category: "widgets",
+        icon: "screenoptions",
+    }),
+    "query-loop": Object.freeze({
+        category: "widgets",
+        icon: "query-pagination",
+    }),
+});
+/**
+ * Shared hidden child block metadata defaults for compound scaffolds.
+ */
+export const COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS = Object.freeze({
+    category: "widgets",
+    icon: "excerpt-view",
+});
+/**
+ * Legacy built-in template ids that were removed in favor of persistence modes.
+ */
+export const REMOVED_BUILTIN_TEMPLATE_IDS = ["data", "persisted"];
+/**
+ * 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 function getBuiltInTemplateMetadataDefaults(templateId) {
+    return BUILTIN_TEMPLATE_METADATA_DEFAULTS[templateId];
+}
+/**
+ * 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 function isRemovedBuiltInTemplateId(templateId) {
+    return REMOVED_BUILTIN_TEMPLATE_IDS.includes(templateId);
+}
+/**
+ * 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 function getRemovedBuiltInTemplateMessage(templateId) {
+    return `Built-in template "${templateId}" was removed. Use --template persistence --persistence-policy ${templateId === "data" ? "public" : "authenticated"} instead.`;
+}

package/dist/runtime/templates/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 {};

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

@@ -0,0 +1,187 @@
+import path from "node:path";
+import { promises as fsp } from "node:fs";
+import { pathExists } from "../shared/fs-async.js";
+import { readJsonFile } from "../shared/json-utils.js";
+import { isPlainObject } from "../shared/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 (!(await pathExists(manifestPath))) {
+        return null;
+    }
+    const raw = await readJsonFile(manifestPath, {
+        context: "template layer manifest",
+    });
+    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 getSelectableExternalLayers(manifest) {
+    const layerIds = Object.keys(manifest.layers);
+    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));
+    return publicLayerIds.map((layerId) => ({
+        description: manifest.layers[layerId]?.description,
+        extends: [...(manifest.layers[layerId]?.extends ?? [])],
+        id: layerId,
+    }));
+}
+function getDefaultExternalLayerId(manifest) {
+    const selectableLayers = getSelectableExternalLayers(manifest);
+    if (selectableLayers.length === 1) {
+        return selectableLayers[0].id;
+    }
+    const layerIds = Object.keys(manifest.layers);
+    throw new Error(`External layer package defines multiple selectable layers (${layerIds.join(", ")}). Pass an explicit externalLayerId or rerun through the interactive CLI selector.`);
+}
+export async function listSelectableExternalTemplateLayers(sourceRoot) {
+    const manifest = await loadExternalTemplateLayerManifest(sourceRoot);
+    if (!manifest) {
+        throw new Error(`No ${TEMPLATE_LAYER_MANIFEST_FILENAME} manifest found in ${sourceRoot}.`);
+    }
+    return getSelectableExternalLayers(manifest);
+}
+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/templates/template-registry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Resolve the canonical `@wp-typia/project-tools` package root.
+ *
+ * When `WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT` is set, the override is only
+ * accepted if it points at a readable package manifest whose `name` matches
+ * `@wp-typia/project-tools`. Invalid or stale overrides are ignored and normal
+ * upward package-root discovery continues.
+ */
+export declare function resolvePackageRoot(startDir: string): string;
+export declare const PROJECT_TOOLS_PACKAGE_ROOT: string;
+export declare const TEMPLATE_ROOT: string;
+export declare const SHARED_TEMPLATE_ROOT: string;
+export declare const SHARED_BASE_TEMPLATE_ROOT: string;
+export declare const SHARED_COMPOUND_TEMPLATE_ROOT: string;
+export declare const SHARED_PERSISTENCE_TEMPLATE_ROOT: string;
+export declare const SHARED_PRESET_TEMPLATE_ROOT: string;
+export declare const SHARED_REST_HELPER_TEMPLATE_ROOT: string;
+export declare const SHARED_MIGRATION_UI_TEMPLATE_ROOT: string;
+/**
+ * Shared workspace template overlay root used by workspace scaffolding flows.
+ */
+export declare const SHARED_WORKSPACE_TEMPLATE_ROOT: string;
+export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
+export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
+export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound", "query-loop"];
+export declare const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+export declare const OFFICIAL_WORKSPACE_TEMPLATE_ALIAS = "workspace";
+export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
+export type PersistencePolicy = "authenticated" | "public";
+export interface TemplateDefinition {
+    id: string;
+    description: string;
+    defaultCategory: string;
+    features: string[];
+    templateDir: string;
+}
+export declare const TEMPLATE_REGISTRY: readonly TemplateDefinition[];
+export declare const TEMPLATE_IDS: BuiltInTemplateId[];
+export declare function isBuiltInTemplateId(templateId: string): templateId is BuiltInTemplateId;
+/**
+ * Returns whether a template id matches the user-facing official workspace alias.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns `true` when the id is the `workspace` alias.
+ */
+export declare function isOfficialWorkspaceTemplateAlias(templateId: string): boolean;
+/**
+ * Converts user-facing template aliases into the registry lookup id.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns The registry id used for template resolution.
+ */
+export declare function normalizeTemplateLookupId(templateId: string): string;
+/**
+ * Converts internal template ids into the id shown in human-facing output.
+ *
+ * @param templateId Template id stored in the registry.
+ * @returns The user-facing template id or alias for display.
+ */
+export declare function getUserFacingTemplateId(templateId: string): string;
+export declare function listTemplates(): readonly TemplateDefinition[];
+export declare function getTemplateById(templateId: string): TemplateDefinition;
+export declare function getTemplateSelectOptions(): Array<{
+    label: string;
+    value: string;
+    hint: string;
+}>;

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

@@ -0,0 +1,191 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readJsonFileSync } from "../shared/json-utils.js";
+import { getBuiltInTemplateMetadataDefaults } from "./template-defaults.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_TOOLS_PACKAGE_ROOT_ENV = "WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT";
+const PROJECT_TOOLS_PACKAGE_NAME = "@wp-typia/project-tools";
+function resolveValidProjectToolsPackageRoot(candidateRoot) {
+    const packageJsonPath = path.join(candidateRoot, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return undefined;
+    }
+    try {
+        const packageJson = readJsonFileSync(packageJsonPath, {
+            context: "project-tools package manifest override",
+        });
+        return packageJson.name === PROJECT_TOOLS_PACKAGE_NAME
+            ? candidateRoot
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the canonical `@wp-typia/project-tools` package root.
+ *
+ * When `WP_TYPIA_PROJECT_TOOLS_PACKAGE_ROOT` is set, the override is only
+ * accepted if it points at a readable package manifest whose `name` matches
+ * `@wp-typia/project-tools`. Invalid or stale overrides are ignored and normal
+ * upward package-root discovery continues.
+ */
+export function resolvePackageRoot(startDir) {
+    const overriddenPackageRoot = process.env[PROJECT_TOOLS_PACKAGE_ROOT_ENV]?.trim();
+    if (overriddenPackageRoot) {
+        const resolvedOverride = path.resolve(overriddenPackageRoot);
+        const validOverride = resolveValidProjectToolsPackageRoot(resolvedOverride);
+        if (validOverride) {
+            return validOverride;
+        }
+    }
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(packageJsonPath)) {
+            try {
+                const packageJson = readJsonFileSync(packageJsonPath, {
+                    context: "project-tools package root discovery manifest",
+                });
+                if (packageJson.name === PROJECT_TOOLS_PACKAGE_NAME) {
+                    return currentDir;
+                }
+            }
+            catch {
+                // Ignore malformed package.json while walking upward; discovery should
+                // keep searching parent directories instead of failing on unrelated files.
+            }
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            throw new Error("Unable to resolve the @wp-typia/project-tools package root.");
+        }
+        currentDir = parentDir;
+    }
+}
+export const PROJECT_TOOLS_PACKAGE_ROOT = resolvePackageRoot(__dirname);
+export const TEMPLATE_ROOT = path.join(PROJECT_TOOLS_PACKAGE_ROOT, "templates");
+export const SHARED_TEMPLATE_ROOT = path.join(TEMPLATE_ROOT, "_shared");
+export const SHARED_BASE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "base");
+export const SHARED_COMPOUND_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "compound");
+export const SHARED_PERSISTENCE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "persistence");
+export const SHARED_PRESET_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "presets");
+export const SHARED_REST_HELPER_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "rest-helpers");
+export const SHARED_MIGRATION_UI_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "migration-ui");
+/**
+ * Shared workspace template overlay root used by workspace scaffolding flows.
+ */
+export const SHARED_WORKSPACE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "workspace");
+export const SHARED_TEST_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset");
+export const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env");
+export const BUILTIN_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "persistence",
+    "compound",
+    "query-loop",
+];
+export const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+export const OFFICIAL_WORKSPACE_TEMPLATE_ALIAS = "workspace";
+export const TEMPLATE_REGISTRY = Object.freeze([
+    {
+        id: "basic",
+        description: "A lightweight WordPress block with Typia validation",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("basic").category,
+        features: ["Type-safe attributes", "Runtime validation", "Minimal setup"],
+        templateDir: path.join(TEMPLATE_ROOT, "basic"),
+    },
+    {
+        id: "interactivity",
+        description: "An interactive WordPress block with Typia validation and Interactivity API",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("interactivity").category,
+        features: ["Interactivity API", "Client-side state", "Event handling"],
+        templateDir: path.join(TEMPLATE_ROOT, "interactivity"),
+    },
+    {
+        id: "persistence",
+        description: "A persistence-aware WordPress block with Typia validation, typed REST contracts, and selectable public or authenticated write policies",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("persistence").category,
+        features: ["Interactivity API", "Typed REST client", "Schema sync", "Persistence policies"],
+        templateDir: path.join(TEMPLATE_ROOT, "persistence"),
+    },
+    {
+        id: "compound",
+        description: "A parent-and-child WordPress block scaffold with InnerBlocks, optional persistence wiring, and hidden implementation child blocks",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("compound").category,
+        features: ["InnerBlocks", "Hidden child blocks", "Optional persistence layer"],
+        templateDir: path.join(TEMPLATE_ROOT, "compound"),
+    },
+    {
+        id: "query-loop",
+        description: "A Query Loop block variation scaffold with stable namespace-based identity, inline starter layout, connected pattern presets, custom query seams, and runtime parity hooks",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("query-loop").category,
+        features: ["core/query variation", "Default innerBlocks", "Connected patterns", "Custom query hooks", "Runtime parity hooks", "Allowed controls"],
+        templateDir: path.join(TEMPLATE_ROOT, "query-loop"),
+    },
+    {
+        id: OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
+        description: "The official empty workspace template that powers `wp-typia add ...` workflows",
+        defaultCategory: "workspace",
+        features: ["Workspace inventory", "Add block workflows", "Workspace doctor and migrate"],
+        templateDir: path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "create-workspace-template"),
+    },
+]);
+export const TEMPLATE_IDS = [...BUILTIN_TEMPLATE_IDS];
+export function isBuiltInTemplateId(templateId) {
+    return BUILTIN_TEMPLATE_IDS.includes(templateId);
+}
+/**
+ * Returns whether a template id matches the user-facing official workspace alias.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns `true` when the id is the `workspace` alias.
+ */
+export function isOfficialWorkspaceTemplateAlias(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_ALIAS;
+}
+/**
+ * Converts user-facing template aliases into the registry lookup id.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns The registry id used for template resolution.
+ */
+export function normalizeTemplateLookupId(templateId) {
+    return isOfficialWorkspaceTemplateAlias(templateId)
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
+/**
+ * Converts internal template ids into the id shown in human-facing output.
+ *
+ * @param templateId Template id stored in the registry.
+ * @returns The user-facing template id or alias for display.
+ */
+export function getUserFacingTemplateId(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        ? OFFICIAL_WORKSPACE_TEMPLATE_ALIAS
+        : templateId;
+}
+export function listTemplates() {
+    return TEMPLATE_REGISTRY;
+}
+export function getTemplateById(templateId) {
+    const normalizedTemplateId = normalizeTemplateLookupId(templateId);
+    const template = TEMPLATE_REGISTRY.find((entry) => entry.id === normalizedTemplateId);
+    if (!template) {
+        throw new Error(`Unknown template "${templateId}". Expected one of: ${[
+            ...TEMPLATE_IDS,
+            OFFICIAL_WORKSPACE_TEMPLATE_ALIAS,
+            OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
+        ].join(", ")}`);
+    }
+    return template;
+}
+export function getTemplateSelectOptions() {
+    return TEMPLATE_REGISTRY.map((template) => ({
+        label: getUserFacingTemplateId(template.id),
+        value: getUserFacingTemplateId(template.id),
+        hint: template.features.join(", "),
+    }));
+}

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

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+export type TemplateRenderView = Record<string, unknown>;
+/**
+ * Optional controls for raw directory copies.
+ *
+ * The filter runs for each discovered entry before copying. Returning `false`
+ * skips only that entry; when the skipped entry is a directory, the subtree is
+ * skipped as well.
+ */
+export interface CopyRawDirectoryOptions {
+    /**
+     * Predicate that decides whether a discovered entry should be copied.
+     *
+     * Throwing or rejecting aborts the copy and bubbles to the caller.
+     */
+    filter?: CopyDirectoryFilter;
+}
+export type CopyDirectoryFilter = (sourcePath: string, destinationPath: string, entry: fs.Dirent) => boolean | Promise<boolean>;
+/**
+ * Render a Mustache template with full Mustache semantics while leaving values
+ * unescaped for scaffold source generation.
+ */
+export declare function renderMustacheTemplateString(template: string, view: TemplateRenderView): string;
+/**
+ * Recursively copies a directory tree without rendering template contents.
+ */
+export declare function copyRawDirectory(sourceDir: string, targetDir: string, options?: CopyRawDirectoryOptions): Promise<void>;
+/**
+ * Copy a template directory using full Mustache semantics for filenames and
+ * text-file contents while leaving rendered values unescaped.
+ */
+export declare function copyRenderedDirectory(sourceDir: string, targetDir: string, view: TemplateRenderView, options?: {
+    filter?: CopyDirectoryFilter;
+}): Promise<void>;
+/**
+ * Copy a template directory using direct `{{key}}` replacement only.
+ *
+ * This intentionally preserves literal Mustache sections, partials, and other
+ * advanced constructs so built-in scaffold copy paths keep their historical
+ * interpolation behavior.
+ */
+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 pathExistsSync(targetPath: string): boolean;