@wp-typia/project-tools 0.16.7 → 0.16.9

package/dist/runtime/template-source.js

@@ -1,25 +1,32 @@
 /// <reference path="./external-template-modules.d.ts" />
-import fs from "node:fs";
-import { promises as fsp } from "node:fs";
-import { createRequire } from "node:module";
-import os from "node:os";
-import path from "node:path";
-import { execFileSync } from "node:child_process";
-import { pathToFileURL } from "node:url";
-import npa from "npm-package-arg";
-import semver from "semver";
-import { x as extractTarball } from "tar";
-import { BUILTIN_TEMPLATE_IDS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, isBuiltInTemplateId, } from "./template-registry.js";
-import { isPlainObject } from "./object-utils.js";
-import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
-import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, resolveBuiltInTemplateSource, } from "./template-builtins.js";
-import { getPackageVersions } from "./package-versions.js";
-import { toSegmentPascalCase } from "./string-case.js";
-import { copyRawDirectory, copyRenderedDirectory } from "./template-render.js";
-const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES = ["index.js", "index.cjs", "index.mjs"];
-const TEMPLATE_WARNING_MESSAGE = "wp-typia owns package/tooling/sync setup for generated projects, so this external template setting is ignored.";
+import fs from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import npa from 'npm-package-arg';
+import semver from 'semver';
+import { x as extractTarball } from 'tar';
+import { BUILTIN_TEMPLATE_IDS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, isBuiltInTemplateId, } from './template-registry.js';
+import { isPlainObject } from './object-utils.js';
+import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from './template-defaults.js';
+import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, resolveBuiltInTemplateSource, } from './template-builtins.js';
+import { loadExternalTemplateLayerManifest } from './template-layers.js';
+import { getPackageVersions } from './package-versions.js';
+import { toSegmentPascalCase } from './string-case.js';
+import { copyRawDirectory, copyRenderedDirectory } from './template-render.js';
+const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES = [
+    'index.js',
+    'index.cjs',
+    'index.mjs',
+];
+const TEMPLATE_WARNING_MESSAGE = 'wp-typia owns package/tooling/sync setup for generated projects, so this external template setting is ignored.';
 function isTemplatePathLocator(templateId) {
-    return path.isAbsolute(templateId) || templateId.startsWith("./") || templateId.startsWith("../");
+    return (path.isAbsolute(templateId) ||
+        templateId.startsWith('./') ||
+        templateId.startsWith('../'));
 }
 function getTemplateWarning(key) {
     return `Ignoring external template config key "${key}": ${TEMPLATE_WARNING_MESSAGE}`;
@@ -27,7 +34,7 @@ function getTemplateWarning(key) {
 function resolveSourceSubpath(sourceDir, relativePath) {
     const targetPath = path.resolve(sourceDir, relativePath);
     const relativeTarget = path.relative(sourceDir, targetPath);
-    if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+    if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
         throw new Error(`Template path "${relativePath}" must stay within ${sourceDir}.`);
     }
     return targetPath;
@@ -42,38 +49,40 @@ function getExternalTemplateEntry(sourceDir) {
     return null;
 }
 function selectRegistryVersion(metadata, locator) {
-    const distTags = isPlainObject(metadata["dist-tags"]) ? metadata["dist-tags"] : {};
+    const distTags = isPlainObject(metadata['dist-tags'])
+        ? metadata['dist-tags']
+        : {};
     const versions = isPlainObject(metadata.versions) ? metadata.versions : {};
     const versionKeys = Object.keys(versions);
-    if (locator.type === "version") {
+    if (locator.type === 'version') {
         if (!versions[locator.fetchSpec]) {
             throw new Error(`npm template package version not found: ${locator.raw}`);
         }
         return locator.fetchSpec;
     }
-    if (locator.type === "tag") {
+    if (locator.type === 'tag') {
         const taggedVersion = distTags[locator.fetchSpec];
-        if (typeof taggedVersion !== "string") {
+        if (typeof taggedVersion !== 'string') {
             throw new Error(`npm template package tag not found: ${locator.raw}`);
         }
         return taggedVersion;
     }
-    const range = locator.fetchSpec.trim().length > 0 ? locator.fetchSpec : "*";
+    const range = locator.fetchSpec.trim().length > 0 ? locator.fetchSpec : '*';
     const matchedVersion = semver.maxSatisfying(versionKeys, range);
     if (matchedVersion) {
         return matchedVersion;
     }
     if (locator.fetchSpec.trim().length > 0) {
-        throw new Error(`Unable to resolve npm template version for ${locator.raw}. Requested "${locator.fetchSpec}" but available versions are: ${versionKeys.join(", ") || "(none)"}.`);
+        throw new Error(`Unable to resolve npm template version for ${locator.raw}. Requested "${locator.fetchSpec}" but available versions are: ${versionKeys.join(', ') || '(none)'}.`);
     }
     const latestVersion = distTags.latest;
-    if (typeof latestVersion === "string" && versions[latestVersion]) {
+    if (typeof latestVersion === 'string' && versions[latestVersion]) {
         return latestVersion;
     }
     throw new Error(`Unable to resolve a published npm template version for ${locator.raw}.`);
 }
 async function fetchNpmTemplateSource(locator) {
-    const registryBase = (process.env.NPM_CONFIG_REGISTRY ?? "https://registry.npmjs.org").replace(/\/$/, "");
+    const registryBase = (process.env.NPM_CONFIG_REGISTRY ?? 'https://registry.npmjs.org').replace(/\/$/, '');
     const metadataResponse = await fetch(`${registryBase}/${encodeURIComponent(locator.name)}`);
     if (!metadataResponse.ok) {
         throw new Error(`Failed to fetch npm template metadata for ${locator.raw}: ${metadataResponse.status}`);
@@ -86,10 +95,10 @@ async function fetchNpmTemplateSource(locator) {
         throw new Error(`npm template metadata is missing dist information for ${locator.raw}@${resolvedVersion}.`);
     }
     const tarballUrl = versionMetadata.dist.tarball;
-    if (typeof tarballUrl !== "string" || tarballUrl.length === 0) {
+    if (typeof tarballUrl !== 'string' || tarballUrl.length === 0) {
         throw new Error(`npm template metadata is missing tarball URL for ${locator.raw}@${resolvedVersion}.`);
     }
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-template-source-"));
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
     const cleanup = async () => {
         await fsp.rm(tempRoot, { force: true, recursive: true });
     };
@@ -98,8 +107,8 @@ async function fetchNpmTemplateSource(locator) {
         if (!tarballResponse.ok) {
             throw new Error(`Failed to download npm template tarball for ${locator.raw}: ${tarballResponse.status}`);
         }
-        const tarballPath = path.join(tempRoot, "template.tgz");
-        const unpackDir = path.join(tempRoot, "source");
+        const tarballPath = path.join(tempRoot, 'template.tgz');
+        const unpackDir = path.join(tempRoot, 'source');
         await fsp.mkdir(unpackDir, { recursive: true });
         await fsp.writeFile(tarballPath, Buffer.from(await tarballResponse.arrayBuffer()));
         await extractTarball({
@@ -120,14 +129,14 @@ async function fetchNpmTemplateSource(locator) {
     }
 }
 async function normalizeWpTypiaTemplateSeed(seed) {
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-template-source-"));
-    const normalizedDir = path.join(tempRoot, "template");
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
+    const normalizedDir = path.join(tempRoot, 'template');
     try {
         await copyRawDirectory(seed.blockDir, normalizedDir, {
             filter: (sourcePath, _targetPath, entry) => {
                 const mustacheVariantPath = path.join(path.dirname(sourcePath), `${entry.name}.mustache`);
                 return !(entry.isFile() &&
-                    (entry.name === "package.json" || entry.name === "README.md") &&
+                    (entry.name === 'package.json' || entry.name === 'README.md') &&
                     fs.existsSync(mustacheVariantPath));
             },
         });
@@ -154,21 +163,23 @@ async function normalizeWpTypiaTemplateSeed(seed) {
  * use an already-installed template without forcing a registry fetch.
  */
 function resolveInstalledNpmTemplateSource(locator, cwd) {
-    if (locator.rawSpec !== "" && locator.rawSpec !== "*") {
+    if (locator.rawSpec !== '' && locator.rawSpec !== '*') {
         return null;
     }
-    const workspacePackagesRoot = path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..");
+    const workspacePackagesRoot = path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, '..');
     if (fs.existsSync(workspacePackagesRoot)) {
-        for (const entry of fs.readdirSync(workspacePackagesRoot, { withFileTypes: true })) {
+        for (const entry of fs.readdirSync(workspacePackagesRoot, {
+            withFileTypes: true,
+        })) {
             if (!entry.isDirectory()) {
                 continue;
             }
             const packageDir = path.join(workspacePackagesRoot, entry.name);
-            const packageJsonPath = path.join(packageDir, "package.json");
+            const packageJsonPath = path.join(packageDir, 'package.json');
             if (!fs.existsSync(packageJsonPath)) {
                 continue;
             }
-            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
             if (manifest.name === locator.name) {
                 return {
                     blockDir: packageDir,
@@ -177,7 +188,7 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
             }
         }
     }
-    const workspaceRequire = createRequire(path.join(path.resolve(cwd), "__wp_typia_template_resolver__.cjs"));
+    const workspaceRequire = createRequire(path.join(path.resolve(cwd), '__wp_typia_template_resolver__.cjs'));
     try {
         const packageJsonPath = fs.realpathSync(workspaceRequire.resolve(`${locator.name}/package.json`));
         const sourceDir = path.dirname(packageJsonPath);
@@ -187,13 +198,14 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
         };
     }
     catch (error) {
-        const errorCode = typeof error === "object" && error !== null && "code" in error
+        const errorCode = typeof error === 'object' && error !== null && 'code' in error
             ? String(error.code)
-            : "";
-        if (errorCode === "MODULE_NOT_FOUND" ||
-            errorCode === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
-            for (const basePath of workspaceRequire.resolve.paths(locator.name) ?? []) {
-                const packageJsonPath = path.join(basePath, locator.name, "package.json");
+            : '';
+        if (errorCode === 'MODULE_NOT_FOUND' ||
+            errorCode === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+            for (const basePath of workspaceRequire.resolve.paths(locator.name) ??
+                []) {
+                const packageJsonPath = path.join(basePath, locator.name, 'package.json');
                 if (!fs.existsSync(packageJsonPath)) {
                     continue;
                 }
@@ -209,12 +221,12 @@ function resolveInstalledNpmTemplateSource(locator, cwd) {
     }
 }
 function isOfficialWorkspaceTemplateSeed(seed) {
-    const packageJsonPath = path.join(seed.rootDir, "package.json");
+    const packageJsonPath = path.join(seed.rootDir, 'package.json');
     if (!fs.existsSync(packageJsonPath)) {
         return false;
     }
     try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
         return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     }
     catch {
@@ -222,11 +234,13 @@ function isOfficialWorkspaceTemplateSeed(seed) {
     }
 }
 export function parseGitHubTemplateLocator(templateId) {
-    if (!templateId.startsWith("github:")) {
+    if (!templateId.startsWith('github:')) {
         return null;
     }
-    const [locatorBody, refSegment] = templateId.slice("github:".length).split("#", 2);
-    const segments = locatorBody.split("/").filter(Boolean);
+    const [locatorBody, refSegment] = templateId
+        .slice('github:'.length)
+        .split('#', 2);
+    const segments = locatorBody.split('/').filter(Boolean);
     if (segments.length < 3) {
         throw new Error(`GitHub template locators must look like github:owner/repo/path[#ref]. Received: ${templateId}`);
     }
@@ -235,11 +249,13 @@ export function parseGitHubTemplateLocator(templateId) {
         owner,
         repo,
         ref: refSegment ?? null,
-        sourcePath: sourcePathSegments.join("/"),
+        sourcePath: sourcePathSegments.join('/'),
     };
 }
 export function parseNpmTemplateLocator(templateId) {
-    if (isBuiltInTemplateId(templateId) || isTemplatePathLocator(templateId) || templateId.startsWith("github:")) {
+    if (isBuiltInTemplateId(templateId) ||
+        isTemplatePathLocator(templateId) ||
+        templateId.startsWith('github:')) {
         return null;
     }
     try {
@@ -248,9 +264,11 @@ export function parseNpmTemplateLocator(templateId) {
             return null;
         }
         const parsedWithRawSpec = parsed;
-        const rawSpec = typeof parsedWithRawSpec.rawSpec === "string" ? parsedWithRawSpec.rawSpec : "";
+        const rawSpec = typeof parsedWithRawSpec.rawSpec === 'string'
+            ? parsedWithRawSpec.rawSpec
+            : '';
         return {
-            fetchSpec: typeof parsed.fetchSpec === "string" ? parsed.fetchSpec : "",
+            fetchSpec: typeof parsed.fetchSpec === 'string' ? parsed.fetchSpec : '',
             name: parsed.name,
             raw: templateId,
             rawSpec,
@@ -267,21 +285,22 @@ export function parseTemplateLocator(templateId) {
     }
     const githubLocator = parseGitHubTemplateLocator(templateId);
     if (githubLocator) {
-        return { kind: "github", locator: githubLocator };
+        return { kind: 'github', locator: githubLocator };
     }
     if (isTemplatePathLocator(templateId)) {
-        return { kind: "path", templatePath: templateId };
+        return { kind: 'path', templatePath: templateId };
     }
     const npmLocator = parseNpmTemplateLocator(templateId);
     if (npmLocator) {
-        return { kind: "npm", locator: npmLocator };
+        return { kind: 'npm', locator: npmLocator };
     }
-    throw new Error(`Unknown template "${templateId}". Expected one of: ${BUILTIN_TEMPLATE_IDS.join(", ")}, a local path, github:owner/repo/path[#ref], or an npm package spec.`);
+    throw new Error(`Unknown template "${templateId}". Expected one of: ${BUILTIN_TEMPLATE_IDS.join(', ')}, a local path, github:owner/repo/path[#ref], or an npm package spec.`);
 }
 function getDefaultCategoryFromBlockJson(blockJson) {
-    return typeof blockJson.category === "string" && blockJson.category.trim().length > 0
+    return typeof blockJson.category === 'string' &&
+        blockJson.category.trim().length > 0
         ? blockJson.category.trim()
-        : "widgets";
+        : 'widgets';
 }
 function getDefaultCategory(sourceDir) {
     try {
@@ -289,7 +308,7 @@ function getDefaultCategory(sourceDir) {
         return getDefaultCategoryFromBlockJson(blockJson);
     }
     catch {
-        return "widgets";
+        return 'widgets';
     }
 }
 function getTemplateVariableContext(variables) {
@@ -312,31 +331,41 @@ function getTemplateVariableContext(variables) {
     };
 }
 async function detectTemplateSourceFormat(sourceDir) {
-    if (fs.existsSync(path.join(sourceDir, "package.json.mustache"))) {
-        return "wp-typia";
+    if (fs.existsSync(path.join(sourceDir, 'package.json.mustache'))) {
+        return 'wp-typia';
+    }
+    if (await loadExternalTemplateLayerManifest(sourceDir)) {
+        throw new Error(`Template source at ${sourceDir} is an external layer package. External layers currently compose only through built-in scaffolds via the runtime API, not as standalone template ids.`);
     }
     if (getExternalTemplateEntry(sourceDir)) {
-        return "create-block-external";
+        return 'create-block-external';
     }
-    const sourceRoot = fs.existsSync(path.join(sourceDir, "src")) ? path.join(sourceDir, "src") : sourceDir;
+    const sourceRoot = fs.existsSync(path.join(sourceDir, 'src'))
+        ? path.join(sourceDir, 'src')
+        : sourceDir;
     const blockJsonCandidates = [
-        path.join(sourceDir, "block.json"),
-        path.join(sourceRoot, "block.json"),
+        path.join(sourceDir, 'block.json'),
+        path.join(sourceRoot, 'block.json'),
     ];
     const hasBlockJson = blockJsonCandidates.some((candidate) => fs.existsSync(candidate));
-    const hasIndexFile = ["index.js", "index.jsx", "index.ts", "index.tsx"].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
-    const hasEditFile = ["edit.js", "edit.jsx", "edit.ts", "edit.tsx"].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
-    const hasSaveFile = ["save.js", "save.jsx", "save.ts", "save.tsx"].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
+    const hasIndexFile = ['index.js', 'index.jsx', 'index.ts', 'index.tsx'].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
+    const hasEditFile = ['edit.js', 'edit.jsx', 'edit.ts', 'edit.tsx'].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
+    const hasSaveFile = ['save.js', 'save.jsx', 'save.ts', 'save.tsx'].some((filename) => fs.existsSync(path.join(sourceRoot, filename)));
     if (hasBlockJson && hasIndexFile && hasEditFile && hasSaveFile) {
-        return "create-block-subset";
+        return 'create-block-subset';
     }
     throw new Error(`Unsupported template source at ${sourceDir}. Expected a wp-typia template directory, an official create-block external template config, or a create-block subset with block.json and src/index/edit/save files.`);
 }
 function readRemoteBlockJson(blockDir) {
-    const sourceRoot = fs.existsSync(path.join(blockDir, "src")) ? path.join(blockDir, "src") : blockDir;
-    for (const candidate of [path.join(blockDir, "block.json"), path.join(sourceRoot, "block.json")]) {
+    const sourceRoot = fs.existsSync(path.join(blockDir, 'src'))
+        ? path.join(blockDir, 'src')
+        : blockDir;
+    for (const candidate of [
+        path.join(blockDir, 'block.json'),
+        path.join(sourceRoot, 'block.json'),
+    ]) {
         if (fs.existsSync(candidate)) {
-            return JSON.parse(fs.readFileSync(candidate, "utf8"));
+            return JSON.parse(fs.readFileSync(candidate, 'utf8'));
         }
     }
     throw new Error(`Unable to locate block.json in ${blockDir}`);
@@ -354,72 +383,83 @@ async function assertNoSymlinks(sourceDir) {
     }
 }
 function renderTypeScriptLiteral(value) {
-    if (typeof value === "string") {
+    if (typeof value === 'string') {
         return JSON.stringify(value);
     }
-    if (typeof value === "number" || typeof value === "boolean") {
+    if (typeof value === 'number' || typeof value === 'boolean') {
         return String(value);
     }
-    return "undefined";
+    return 'undefined';
 }
 function renderTagsForAttribute(attribute) {
     const tags = [];
-    if (typeof attribute.default === "string" || typeof attribute.default === "number" || typeof attribute.default === "boolean") {
+    if (typeof attribute.default === 'string' ||
+        typeof attribute.default === 'number' ||
+        typeof attribute.default === 'boolean') {
         tags.push(`tags.Default<${renderTypeScriptLiteral(attribute.default)}>`);
     }
     return tags;
 }
 function renderAttributeBaseType(attributeName, attribute) {
     if (Array.isArray(attribute.enum) && attribute.enum.length > 0) {
-        return attribute.enum.map((item) => renderTypeScriptLiteral(item)).join(" | ");
+        return attribute.enum
+            .map((item) => renderTypeScriptLiteral(item))
+            .join(' | ');
     }
     switch (attribute.type) {
-        case "string":
-            return "string";
-        case "number":
-            return "number";
-        case "boolean":
-            return "boolean";
-        case "array":
-            return "unknown[]";
-        case "object":
-            return "Record<string, unknown>";
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'array':
+            return 'unknown[]';
+        case 'object':
+            return 'Record<string, unknown>';
         default:
-            if (typeof attributeName === "string" && attributeName.toLowerCase().includes("class")) {
-                return "string";
+            if (typeof attributeName === 'string' &&
+                attributeName.toLowerCase().includes('class')) {
+                return 'string';
             }
-            return "unknown";
+            return 'unknown';
     }
 }
 function buildRemoteTypesSource(blockJson, context) {
     const attributes = (blockJson.attributes ?? {});
-    const lines = ['import { tags } from "typia";', "", `export interface ${context.pascalCase}Attributes {`];
+    const lines = [
+        'import { tags } from "typia";',
+        '',
+        `export interface ${context.pascalCase}Attributes {`,
+    ];
     for (const [name, attribute] of Object.entries(attributes)) {
         const baseType = renderAttributeBaseType(name, attribute);
         const tagList = renderTagsForAttribute(attribute);
-        const baseTypeWithGrouping = tagList.length > 0 && baseType.includes(" | ") ? `(${baseType})` : baseType;
-        const renderedType = [baseTypeWithGrouping, ...tagList].join(" & ");
+        const baseTypeWithGrouping = tagList.length > 0 && baseType.includes(' | ')
+            ? `(${baseType})`
+            : baseType;
+        const renderedType = [baseTypeWithGrouping, ...tagList].join(' & ');
         lines.push(`  ${JSON.stringify(name)}?: ${renderedType};`);
     }
-    lines.push("}", "");
-    return lines.join("\n");
+    lines.push('}', '');
+    return lines.join('\n');
 }
 function buildRemoteBlockJsonTemplate(blockJson) {
     const merged = {
         ...blockJson,
-        description: "{{description}}",
-        name: "{{namespace}}/{{slug}}",
-        textdomain: "{{textDomain}}",
-        title: "{{title}}",
+        description: '{{description}}',
+        name: '{{namespace}}/{{slug}}',
+        textdomain: '{{textDomain}}',
+        title: '{{title}}',
     };
     if (!Array.isArray(merged.keywords) || merged.keywords.length === 0) {
-        merged.keywords = ["{{keyword}}", "typia", "block"];
+        merged.keywords = ['{{keyword}}', 'typia', 'block'];
     }
-    return `${JSON.stringify(merged, null, "\t")}\n`;
+    return `${JSON.stringify(merged, null, '\t')}\n`;
 }
 async function rewriteBlockJsonImports(directory) {
-    const textExtensions = new Set([".js", ".jsx", ".ts", ".tsx"]);
-    const targetBlockJsonPath = path.join(directory, "block.json");
+    const textExtensions = new Set(['.js', '.jsx', '.ts', '.tsx']);
+    const targetBlockJsonPath = path.join(directory, 'block.json');
     async function visit(currentPath) {
         const stats = await fsp.stat(currentPath);
         if (stats.isDirectory()) {
@@ -432,32 +472,36 @@ async function rewriteBlockJsonImports(directory) {
         if (!textExtensions.has(path.extname(currentPath))) {
             return;
         }
-        const content = await fsp.readFile(currentPath, "utf8");
-        const relativeSpecifier = path.relative(path.dirname(currentPath), targetBlockJsonPath).replace(/\\/g, "/");
-        const normalizedSpecifier = relativeSpecifier.startsWith(".") ? relativeSpecifier : `./${relativeSpecifier}`;
+        const content = await fsp.readFile(currentPath, 'utf8');
+        const relativeSpecifier = path
+            .relative(path.dirname(currentPath), targetBlockJsonPath)
+            .replace(/\\/g, '/');
+        const normalizedSpecifier = relativeSpecifier.startsWith('.')
+            ? relativeSpecifier
+            : `./${relativeSpecifier}`;
         const next = content.replace(/(['"])\.{1,2}\/[^'"]*block\.json\1/g, `$1${normalizedSpecifier}$1`);
         if (next !== content) {
-            await fsp.writeFile(currentPath, next, "utf8");
+            await fsp.writeFile(currentPath, next, 'utf8');
         }
     }
     await visit(directory);
 }
 async function patchRemotePackageJson(templateDir, needsInteractivity) {
-    const packageJsonPath = path.join(templateDir, "package.json.mustache");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const packageJsonPath = path.join(templateDir, 'package.json.mustache');
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, 'utf8'));
     const existingDependencies = { ...(packageJson.dependencies ?? {}) };
     const existingDevDependencies = { ...(packageJson.devDependencies ?? {}) };
-    delete existingDependencies["@wp-typia/project-tools"];
-    delete existingDevDependencies["@wp-typia/project-tools"];
+    delete existingDependencies['@wp-typia/project-tools'];
+    delete existingDevDependencies['@wp-typia/project-tools'];
     packageJson.devDependencies = {
-        "@wp-typia/block-runtime": "{{blockRuntimePackageVersion}}",
-        "@wp-typia/block-types": "{{blockTypesPackageVersion}}",
+        '@wp-typia/block-runtime': '{{blockRuntimePackageVersion}}',
+        '@wp-typia/block-types': '{{blockTypesPackageVersion}}',
         ...existingDevDependencies,
     };
     if (needsInteractivity) {
         packageJson.dependencies = {
             ...existingDependencies,
-            "@wordpress/interactivity": "^6.29.0",
+            '@wordpress/interactivity': '^6.29.0',
         };
     }
     else if (Object.keys(existingDependencies).length > 0) {
@@ -466,13 +510,18 @@ async function patchRemotePackageJson(templateDir, needsInteractivity) {
     else {
         delete packageJson.dependencies;
     }
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
 }
 function getSeedSourceRoot(blockDir) {
-    return fs.existsSync(path.join(blockDir, "src")) ? path.join(blockDir, "src") : blockDir;
+    return fs.existsSync(path.join(blockDir, 'src'))
+        ? path.join(blockDir, 'src')
+        : blockDir;
 }
 function findSeedRenderPhp(seed) {
-    for (const candidate of [path.join(seed.blockDir, "render.php"), path.join(seed.rootDir, "render.php")]) {
+    for (const candidate of [
+        path.join(seed.blockDir, 'render.php'),
+        path.join(seed.rootDir, 'render.php'),
+    ]) {
         if (fs.existsSync(candidate)) {
             return candidate;
         }
@@ -481,49 +530,49 @@ function findSeedRenderPhp(seed) {
 }
 async function removeSeedEntryConflicts(templateDir) {
     for (const filename of [
-        "block.json",
-        "block.json.mustache",
-        "edit.js",
-        "edit.jsx",
-        "edit.ts",
-        "edit.tsx",
-        "edit.tsx.mustache",
-        "hooks.ts",
-        "hooks.ts.mustache",
-        "index.js",
-        "index.jsx",
-        "index.ts",
-        "index.tsx",
-        "index.tsx.mustache",
-        "save.js",
-        "save.jsx",
-        "save.ts",
-        "save.tsx",
-        "save.tsx.mustache",
-        "style.css",
-        "style.scss",
-        "style.scss.mustache",
-        "types.ts",
-        "types.ts.mustache",
-        "validators.ts",
-        "validators.ts.mustache",
-        "view.js",
-        "view.jsx",
-        "view.ts",
-        "view.tsx",
+        'block.json',
+        'block.json.mustache',
+        'edit.js',
+        'edit.jsx',
+        'edit.ts',
+        'edit.tsx',
+        'edit.tsx.mustache',
+        'hooks.ts',
+        'hooks.ts.mustache',
+        'index.js',
+        'index.jsx',
+        'index.ts',
+        'index.tsx',
+        'index.tsx.mustache',
+        'save.js',
+        'save.jsx',
+        'save.ts',
+        'save.tsx',
+        'save.tsx.mustache',
+        'style.css',
+        'style.scss',
+        'style.scss.mustache',
+        'types.ts',
+        'types.ts.mustache',
+        'validators.ts',
+        'validators.ts.mustache',
+        'view.js',
+        'view.jsx',
+        'view.ts',
+        'view.tsx',
     ]) {
-        await fsp.rm(path.join(templateDir, "src", filename), { force: true });
+        await fsp.rm(path.join(templateDir, 'src', filename), { force: true });
     }
 }
 async function normalizeCreateBlockSubset(seed, context) {
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-remote-template-"));
-    const templateDir = path.join(tempRoot, "template");
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-remote-template-'));
+    const templateDir = path.join(tempRoot, 'template');
     const blockJson = readRemoteBlockJson(seed.blockDir);
     const sourceRoot = getSeedSourceRoot(seed.blockDir);
     await fsp.mkdir(templateDir, { recursive: true });
-    for (const layerDir of getBuiltInTemplateLayerDirs("basic")) {
+    for (const layerDir of getBuiltInTemplateLayerDirs('basic')) {
         if (!fs.existsSync(layerDir)) {
-            if (isOmittableBuiltInTemplateLayerDir("basic", layerDir)) {
+            if (isOmittableBuiltInTemplateLayerDir('basic', layerDir)) {
                 continue;
             }
             throw new Error(`Built-in template layer is missing: ${layerDir}`);
@@ -534,31 +583,41 @@ async function normalizeCreateBlockSubset(seed, context) {
         });
     }
     await removeSeedEntryConflicts(templateDir);
-    await fsp.cp(sourceRoot, path.join(templateDir, "src"), { recursive: true, force: true });
+    await fsp.cp(sourceRoot, path.join(templateDir, 'src'), {
+        recursive: true,
+        force: true,
+    });
     const remoteRenderPath = findSeedRenderPhp(seed);
     if (remoteRenderPath) {
-        await fsp.copyFile(remoteRenderPath, path.join(templateDir, "render.php"));
+        await fsp.copyFile(remoteRenderPath, path.join(templateDir, 'render.php'));
     }
     if (seed.assetsDir && fs.existsSync(seed.assetsDir)) {
-        await fsp.cp(seed.assetsDir, path.join(templateDir, "assets"), { recursive: true, force: true });
-    }
-    await fsp.writeFile(path.join(templateDir, "src", "types.ts"), buildRemoteTypesSource(blockJson, context), "utf8");
-    await fsp.writeFile(path.join(templateDir, "src", "block.json"), buildRemoteBlockJsonTemplate(blockJson), "utf8");
-    await rewriteBlockJsonImports(path.join(templateDir, "src"));
-    const needsInteractivity = typeof blockJson.viewScriptModule === "string" ||
-        typeof blockJson.viewScript === "string" ||
-        fs.existsSync(path.join(templateDir, "src", "view.js")) ||
-        fs.existsSync(path.join(templateDir, "src", "view.ts")) ||
-        fs.existsSync(path.join(templateDir, "src", "view.tsx")) ||
-        fs.existsSync(path.join(templateDir, "src", "interactivity.js")) ||
-        fs.existsSync(path.join(templateDir, "src", "interactivity.ts"));
+        await fsp.cp(seed.assetsDir, path.join(templateDir, 'assets'), {
+            recursive: true,
+            force: true,
+        });
+    }
+    await fsp.writeFile(path.join(templateDir, 'src', 'types.ts'), buildRemoteTypesSource(blockJson, context), 'utf8');
+    await fsp.writeFile(path.join(templateDir, 'src', 'block.json'), buildRemoteBlockJsonTemplate(blockJson), 'utf8');
+    await rewriteBlockJsonImports(path.join(templateDir, 'src'));
+    const needsInteractivity = typeof blockJson.viewScriptModule === 'string' ||
+        typeof blockJson.viewScript === 'string' ||
+        fs.existsSync(path.join(templateDir, 'src', 'view.js')) ||
+        fs.existsSync(path.join(templateDir, 'src', 'view.ts')) ||
+        fs.existsSync(path.join(templateDir, 'src', 'view.tsx')) ||
+        fs.existsSync(path.join(templateDir, 'src', 'interactivity.js')) ||
+        fs.existsSync(path.join(templateDir, 'src', 'interactivity.ts'));
     await patchRemotePackageJson(templateDir, needsInteractivity);
     return {
-        id: "remote:create-block-subset",
+        id: 'remote:create-block-subset',
         defaultCategory: getDefaultCategoryFromBlockJson(blockJson),
-        description: "A wp-typia scaffold normalized from a create-block subset source",
-        features: ["Remote source", "create-block adapter", "Typia metadata pipeline"],
-        format: "create-block-subset",
+        description: 'A wp-typia scaffold normalized from a create-block subset source',
+        features: [
+            'Remote source',
+            'create-block adapter',
+            'Typia metadata pipeline',
+        ],
+        format: 'create-block-subset',
         selectedVariant: seed.selectedVariant ?? null,
         templateDir,
         warnings: seed.warnings ?? [],
@@ -583,15 +642,15 @@ async function loadExternalTemplateConfig(sourceDir) {
     }
     const warnings = [];
     for (const ignoredKey of [
-        "pluginTemplatesPath",
-        "wpScripts",
-        "wpEnv",
-        "customScripts",
-        "npmDependencies",
-        "npmDevDependencies",
-        "customPackageJSON",
-        "pluginReadme",
-        "pluginHeader",
+        'pluginTemplatesPath',
+        'wpScripts',
+        'wpEnv',
+        'customScripts',
+        'npmDependencies',
+        'npmDevDependencies',
+        'customPackageJSON',
+        'pluginReadme',
+        'pluginHeader',
     ]) {
         if (ignoredKey in loadedConfig) {
             warnings.push(getTemplateWarning(ignoredKey));
@@ -621,11 +680,11 @@ function getVariantConfig(config, requestedVariant) {
     }
     const selectedVariant = requestedVariant ?? variantKeys[0];
     if (!selectedVariant || !isPlainObject(config.variants?.[selectedVariant])) {
-        throw new Error(`Unknown template variant "${requestedVariant}". Expected one of: ${variantKeys.join(", ")}`);
+        throw new Error(`Unknown template variant "${requestedVariant}". Expected one of: ${variantKeys.join(', ')}`);
     }
     return {
         selectedVariant,
-        variantConfig: config.variants?.[selectedVariant],
+        variantConfig: config.variants?.[selectedVariant] ?? {},
     };
 }
 function extractVariantRenderValues(variantConfig) {
@@ -651,7 +710,7 @@ async function buildExternalTemplateView(context, config, selectedVariant, varia
     }
     const transformed = await config.transformer(mergedView);
     if (!isPlainObject(transformed)) {
-        throw new Error("External template transformer(view) must return an object.");
+        throw new Error('External template transformer(view) must return an object.');
     }
     return {
         ...mergedView,
@@ -661,28 +720,35 @@ async function buildExternalTemplateView(context, config, selectedVariant, varia
 async function renderCreateBlockExternalTemplate(sourceDir, context, requestedVariant) {
     const { config, warnings } = await loadExternalTemplateConfig(sourceDir);
     const { selectedVariant, variantConfig } = getVariantConfig(config, requestedVariant);
-    const blockTemplatesPath = (typeof variantConfig.blockTemplatesPath === "string" ? variantConfig.blockTemplatesPath : config.blockTemplatesPath) ??
-        null;
+    const blockTemplatesPath = (typeof variantConfig.blockTemplatesPath === 'string'
+        ? variantConfig.blockTemplatesPath
+        : config.blockTemplatesPath) ?? null;
     if (!blockTemplatesPath) {
-        throw new Error("External template config must define blockTemplatesPath.");
+        throw new Error('External template config must define blockTemplatesPath.');
     }
-    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-create-block-external-"));
+    const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-create-block-external-'));
     const cleanup = async () => {
         await fsp.rm(tempRoot, { force: true, recursive: true });
     };
     try {
-        const renderedRoot = path.join(tempRoot, "rendered");
-        const folderName = (typeof variantConfig.folderName === "string" ? variantConfig.folderName : config.folderName) || ".";
+        const renderedRoot = path.join(tempRoot, 'rendered');
+        const folderName = (typeof variantConfig.folderName === 'string'
+            ? variantConfig.folderName
+            : config.folderName) || '.';
         const blockDir = resolveSourceSubpath(renderedRoot, folderName);
         const view = await buildExternalTemplateView(context, config, selectedVariant, variantConfig);
         const blockTemplateDir = resolveSourceSubpath(sourceDir, blockTemplatesPath);
         await copyRenderedDirectory(blockTemplateDir, blockDir, view);
-        const assetsPath = typeof variantConfig.assetsPath === "string" ? variantConfig.assetsPath : config.assetsPath;
-        if (typeof assetsPath === "string" && assetsPath.trim().length > 0) {
-            await copyRawDirectory(resolveSourceSubpath(sourceDir, assetsPath), path.join(tempRoot, "assets"));
+        const assetsPath = typeof variantConfig.assetsPath === 'string'
+            ? variantConfig.assetsPath
+            : config.assetsPath;
+        if (typeof assetsPath === 'string' && assetsPath.trim().length > 0) {
+            await copyRawDirectory(resolveSourceSubpath(sourceDir, assetsPath), path.join(tempRoot, 'assets'));
         }
         return {
-            assetsDir: fs.existsSync(path.join(tempRoot, "assets")) ? path.join(tempRoot, "assets") : undefined,
+            assetsDir: fs.existsSync(path.join(tempRoot, 'assets'))
+                ? path.join(tempRoot, 'assets')
+                : undefined,
             blockDir,
             cleanup,
             rootDir: tempRoot,
@@ -696,22 +762,23 @@ async function renderCreateBlockExternalTemplate(sourceDir, context, requestedVa
     }
 }
 async function resolveGitHubTemplateSource(locator) {
-    const remoteRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-template-source-"));
+    const remoteRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-template-source-'));
     const cleanup = async () => {
         await fsp.rm(remoteRoot, { force: true, recursive: true });
     };
-    const checkoutDir = path.join(remoteRoot, "source");
+    const checkoutDir = path.join(remoteRoot, 'source');
     try {
-        const args = ["clone", "--depth", "1"];
+        const args = ['clone', '--depth', '1'];
         if (locator.ref) {
-            args.push("--branch", locator.ref);
+            args.push('--branch', locator.ref);
         }
         args.push(`https://github.com/${locator.owner}/${locator.repo}.git`, checkoutDir);
-        execFileSync("git", args, { stdio: "ignore" });
+        execFileSync('git', args, { stdio: 'ignore' });
         const sourceDir = path.resolve(checkoutDir, locator.sourcePath);
         const relativeSourceDir = path.relative(checkoutDir, sourceDir);
-        if (relativeSourceDir.startsWith("..") || path.isAbsolute(relativeSourceDir)) {
-            throw new Error("GitHub template path must stay within the cloned repository.");
+        if (relativeSourceDir.startsWith('..') ||
+            path.isAbsolute(relativeSourceDir)) {
+            throw new Error('GitHub template path must stay within the cloned repository.');
         }
         if (!fs.existsSync(sourceDir)) {
             throw new Error(`GitHub template path does not exist: ${locator.sourcePath}`);
@@ -728,8 +795,16 @@ async function resolveGitHubTemplateSource(locator) {
         throw error;
     }
 }
-async function resolveTemplateSeed(locator, cwd) {
-    if (locator.kind === "path") {
+/**
+ * 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 async function resolveTemplateSeed(locator, cwd) {
+    if (locator.kind === 'path') {
         const sourceDir = path.resolve(cwd, locator.templatePath);
         if (!fs.existsSync(sourceDir)) {
             throw new Error(`Template path does not exist: ${sourceDir}`);
@@ -740,7 +815,7 @@ async function resolveTemplateSeed(locator, cwd) {
             rootDir: sourceDir,
         };
     }
-    if (locator.kind === "github") {
+    if (locator.kind === 'github') {
         return resolveGitHubTemplateSource(locator.locator);
     }
     const installedSource = resolveInstalledNpmTemplateSource(locator.locator, cwd);
@@ -756,8 +831,8 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
             throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for built-in template "${templateId}".`);
         }
         return resolveBuiltInTemplateSource(templateId, {
-            persistenceEnabled: variables.compoundPersistenceEnabled === "true",
-            persistencePolicy: variables.persistencePolicy === "public" ? "public" : "authenticated",
+            persistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+            persistencePolicy: variables.persistencePolicy === 'public' ? 'public' : 'authenticated',
         });
     }
     const locator = parseTemplateLocator(templateId);
@@ -767,7 +842,7 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
     let normalizedSeed = null;
     try {
         const format = await detectTemplateSourceFormat(seed.blockDir);
-        if (format === "wp-typia") {
+        if (format === 'wp-typia') {
             if (variant) {
                 throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for "${templateId}".`);
             }
@@ -775,8 +850,8 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
             return {
                 id: templateId,
                 defaultCategory: getDefaultCategory(seed.blockDir),
-                description: "A remote wp-typia template source",
-                features: ["Remote source", "wp-typia format"],
+                description: 'A remote wp-typia template source',
+                features: ['Remote source', 'wp-typia format'],
                 format,
                 isOfficialWorkspaceTemplate,
                 templateDir: normalizedSeed.blockDir,
@@ -784,14 +859,14 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
             };
         }
         normalizedSeed =
-            format === "create-block-external"
+            format === 'create-block-external'
                 ? await renderCreateBlockExternalTemplate(seed.blockDir, context, variant)
                 : variant
                     ? (() => {
                         throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for "${templateId}".`);
                     })()
                     : seed;
-        if (format === "create-block-external") {
+        if (format === 'create-block-external') {
             const normalized = await normalizeCreateBlockSubset(normalizedSeed, context);
             return {
                 ...normalized,
@@ -799,10 +874,14 @@ export async function resolveTemplateSource(templateId, cwd, variables, variant)
                     await normalized.cleanup?.();
                     await seed.cleanup?.();
                 },
-                description: "A wp-typia scaffold normalized from an official create-block external template",
-                features: ["Remote source", "official external template", "Typia metadata pipeline"],
+                description: 'A wp-typia scaffold normalized from an official create-block external template',
+                features: [
+                    'Remote source',
+                    'official external template',
+                    'Typia metadata pipeline',
+                ],
                 format,
-                id: "remote:create-block-external",
+                id: 'remote:create-block-external',
                 isOfficialWorkspaceTemplate,
                 selectedVariant: normalizedSeed.selectedVariant ?? null,
                 warnings: normalizedSeed.warnings ?? [],