@wp-typia/project-tools 0.16.7 → 0.16.9

package/dist/runtime/template-layers.js

@@ -0,0 +1,184 @@
+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 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/template-render.d.ts

@@ -16,14 +16,40 @@ export interface CopyRawDirectoryOptions {
     filter?: (sourcePath: string, targetPath: string, entry: fs.Dirent) => boolean | Promise<boolean>;
 }
 /**
- * Render a Mustache template while keeping HTML escaping disabled only for the
- * current render call.
+ * 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): 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 pathExists(targetPath: string): boolean;

package/dist/runtime/template-render.js

@@ -19,25 +19,32 @@ const BINARY_EXTENSIONS = new Set([
     ".woff",
     ".woff2",
 ]);
+const IDENTITY_MUSTACHE_ESCAPE = (value) => value;
 /**
- * Render a Mustache template while keeping HTML escaping disabled only for the
- * current render call.
+ * Render a Mustache template with full Mustache semantics while leaving values
+ * unescaped for scaffold source generation.
  */
 export function renderMustacheTemplateString(template, view) {
-    const originalEscape = Mustache.escape;
-    Mustache.escape = (value) => value;
-    try {
-        return Mustache.render(template, view);
-    }
-    finally {
-        Mustache.escape = originalEscape;
-    }
+    const mustacheModule = Mustache;
+    const writer = new mustacheModule.Writer();
+    return writer.render(template, view, undefined, {
+        escape: IDENTITY_MUSTACHE_ESCAPE,
+    });
 }
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+ * Render direct `{{key}}` placeholders without enabling sections, partials, or
+ * any other Mustache features.
+ */
 function renderInterpolatedString(template, view) {
-    return Object.entries(view).reduce((output, [key, value]) => output.replace(new RegExp(`{{${escapeRegExp(key)}}}`, "g"), value), template);
+    const keys = Object.keys(view);
+    if (keys.length === 0) {
+        return template;
+    }
+    const placeholderPattern = new RegExp(keys.map((key) => `({{${escapeRegExp(key)}}})`).join("|"), "g");
+    return template.replace(placeholderPattern, (match) => view[match.slice(2, -2)] ?? match);
 }
 function isBinaryTemplateFile(filePath) {
     return BINARY_EXTENSIONS.has(path.extname(filePath).toLowerCase());
@@ -51,6 +58,59 @@ function resolveRenderedPath(targetDir, destinationName) {
     }
     return resolvedDestinationPath;
 }
+function stripTemplateExtension(entryName) {
+    return entryName.endsWith(".mustache")
+        ? entryName.slice(0, -".mustache".length)
+        : entryName;
+}
+function renderTemplateDestinationName(entryName, view, renderString) {
+    return renderString(stripTemplateExtension(entryName), view);
+}
+async function traverseTemplateDirectory({ prepareDirectory, renderString, sourceDir, targetDir, view, visitFile, }) {
+    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationName = renderTemplateDestinationName(entry.name, view, renderString);
+        const destinationPath = resolveRenderedPath(targetDir, destinationName);
+        if (entry.isDirectory()) {
+            await prepareDirectory?.(destinationPath);
+            await traverseTemplateDirectory({
+                prepareDirectory,
+                renderString,
+                sourceDir: sourcePath,
+                targetDir: destinationPath,
+                view,
+                visitFile,
+            });
+            continue;
+        }
+        await visitFile({
+            destinationPath,
+            sourcePath,
+        });
+    }
+}
+async function copyTemplateDirectory({ renderString, sourceDir, targetDir, view, }) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    await traverseTemplateDirectory({
+        prepareDirectory: async (directoryPath) => {
+            await fsp.mkdir(directoryPath, { recursive: true });
+        },
+        renderString,
+        sourceDir,
+        targetDir,
+        view,
+        visitFile: async ({ destinationPath, sourcePath }) => {
+            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+            if (isBinaryTemplateFile(sourcePath)) {
+                await fsp.copyFile(sourcePath, destinationPath);
+                return;
+            }
+            const content = await fsp.readFile(sourcePath, "utf8");
+            await fsp.writeFile(destinationPath, renderString(content, view), "utf8");
+        },
+    });
+}
 /**
  * Recursively copies a directory tree without rendering template contents.
  */
@@ -70,53 +130,60 @@ export async function copyRawDirectory(sourceDir, targetDir, options = {}) {
         await fsp.copyFile(sourcePath, targetPath);
     }
 }
+/**
+ * Copy a template directory using full Mustache semantics for filenames and
+ * text-file contents while leaving rendered values unescaped.
+ */
 export async function copyRenderedDirectory(sourceDir, targetDir, view) {
-    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
-    for (const entry of entries) {
-        const sourcePath = path.join(sourceDir, entry.name);
-        const destinationNameTemplate = entry.name.endsWith(".mustache")
-            ? entry.name.slice(0, -".mustache".length)
-            : entry.name;
-        const destinationName = renderMustacheTemplateString(destinationNameTemplate, view);
-        const destinationPath = resolveRenderedPath(targetDir, destinationName);
-        if (entry.isDirectory()) {
-            await fsp.mkdir(destinationPath, { recursive: true });
-            await copyRenderedDirectory(sourcePath, destinationPath, view);
-            continue;
-        }
-        if (isBinaryTemplateFile(sourcePath)) {
-            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
-            await fsp.copyFile(sourcePath, destinationPath);
-            continue;
-        }
-        const content = await fsp.readFile(sourcePath, "utf8");
-        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
-        await fsp.writeFile(destinationPath, renderMustacheTemplateString(content, view), "utf8");
-    }
+    await copyTemplateDirectory({
+        renderString: renderMustacheTemplateString,
+        sourceDir,
+        targetDir,
+        view,
+    });
 }
+/**
+ * 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 async function copyInterpolatedDirectory(sourceDir, targetDir, view) {
-    const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
-    for (const entry of entries) {
-        const sourcePath = path.join(sourceDir, entry.name);
-        const destinationNameTemplate = entry.name.endsWith(".mustache")
-            ? entry.name.slice(0, -".mustache".length)
-            : entry.name;
-        const destinationName = renderInterpolatedString(destinationNameTemplate, view);
-        const destinationPath = resolveRenderedPath(targetDir, destinationName);
-        if (entry.isDirectory()) {
-            await fsp.mkdir(destinationPath, { recursive: true });
-            await copyInterpolatedDirectory(sourcePath, destinationPath, view);
-            continue;
-        }
-        if (isBinaryTemplateFile(sourcePath)) {
-            await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
-            await fsp.copyFile(sourcePath, destinationPath);
-            continue;
-        }
-        const content = await fsp.readFile(sourcePath, "utf8");
-        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
-        await fsp.writeFile(destinationPath, renderInterpolatedString(content, view), "utf8");
-    }
+    await copyTemplateDirectory({
+        renderString: renderInterpolatedString,
+        sourceDir,
+        targetDir,
+        view,
+    });
+}
+/**
+ * Lists the output file paths produced by an interpolated template directory
+ * without writing any files to disk.
+ *
+ * This walks the source directory, applies the same filename interpolation and
+ * `.mustache` stripping rules as `copyInterpolatedDirectory(...)`, and returns
+ * normalized output-relative paths under a virtual root.
+ *
+ * @param sourceDir - The template directory to traverse.
+ * @param view - The interpolation map used when resolving file and directory
+ * names.
+ * @returns A sorted array of normalized output paths relative to a virtual
+ * preview root.
+ */
+export async function listInterpolatedDirectoryOutputs(sourceDir, view) {
+    const virtualRoot = path.resolve("/wp-typia-template-preview");
+    const outputs = [];
+    await traverseTemplateDirectory({
+        renderString: renderInterpolatedString,
+        sourceDir,
+        targetDir: virtualRoot,
+        view,
+        visitFile: async ({ destinationPath }) => {
+            outputs.push(path.relative(virtualRoot, destinationPath).replace(/\\/g, "/"));
+        },
+    });
+    return outputs.sort((left, right) => left.localeCompare(right));
 }
 export function pathExists(targetPath) {
     return fs.existsSync(targetPath);

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

@@ -1,9 +1,10 @@
-type TemplateSourceFormat = "wp-typia" | "create-block-external" | "create-block-subset";
+import { type UnknownRecord } from './object-utils.js';
+type TemplateSourceFormat = 'wp-typia' | 'create-block-external' | 'create-block-subset';
 /**
  * Public template variables exposed to external template seeds before wp-typia
  * normalizes them into a scaffold project.
  */
-export interface TemplateVariableContext extends Record<string, unknown> {
+export interface TemplateVariableContext extends UnknownRecord {
     /** Version string for `@wp-typia/api-client` used in generated dependencies. */
     apiClientPackageVersion: string;
     /** Version string for `@wp-typia/block-runtime` used in generated dependencies. */
@@ -52,19 +53,36 @@ interface NpmTemplateLocator {
     rawSpec: string;
     type: string;
 }
+interface SeedSource {
+    assetsDir?: string;
+    blockDir: string;
+    cleanup?: () => Promise<void>;
+    rootDir: string;
+    selectedVariant?: string | null;
+    warnings?: string[];
+}
 type RemoteTemplateLocator = {
-    kind: "github";
+    kind: 'github';
     locator: GitHubTemplateLocator;
 } | {
-    kind: "npm";
+    kind: 'npm';
     locator: NpmTemplateLocator;
 } | {
-    kind: "path";
+    kind: 'path';
     templatePath: string;
 };
 export declare function parseGitHubTemplateLocator(templateId: string): GitHubTemplateLocator | null;
 export declare function parseNpmTemplateLocator(templateId: string): NpmTemplateLocator | null;
 export declare function parseTemplateLocator(templateId: string): RemoteTemplateLocator;
+/**
+ * Resolves a template locator into a local seed source directory.
+ *
+ * @param locator Remote template locator describing a local path, GitHub source, or npm package.
+ * @param cwd Current working directory used to resolve local template paths.
+ * @returns A local seed source containing the resolved root and block directory, plus optional cleanup.
+ * @throws When the locator is invalid, the source cannot be fetched, or filesystem validation fails.
+ */
+export declare function resolveTemplateSeed(locator: RemoteTemplateLocator, cwd: string): Promise<SeedSource>;
 export declare function resolveTemplateSource(templateId: string, cwd: string, variables: {
     [key: string]: string;
 }, variant?: string): Promise<ResolvedTemplateSource>;