@wp-typia/project-tools 0.11.1

package/dist/runtime/template-source.js

@@ -0,0 +1,821 @@
+/// <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, PROJECT_TOOLS_PACKAGE_ROOT, SHARED_BASE_TEMPLATE_ROOT, TEMPLATE_ROOT, isBuiltInTemplateId, } from "./template-registry.js";
+import { isPlainObject } from "./object-utils.js";
+import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
+import { 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.";
+const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+function isTemplatePathLocator(templateId) {
+    return path.isAbsolute(templateId) || templateId.startsWith("./") || templateId.startsWith("../");
+}
+function getTemplateWarning(key) {
+    return `Ignoring external template config key "${key}": ${TEMPLATE_WARNING_MESSAGE}`;
+}
+function resolveSourceSubpath(sourceDir, relativePath) {
+    const targetPath = path.resolve(sourceDir, relativePath);
+    const relativeTarget = path.relative(sourceDir, targetPath);
+    if (relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) {
+        throw new Error(`Template path "${relativePath}" must stay within ${sourceDir}.`);
+    }
+    return targetPath;
+}
+function getExternalTemplateEntry(sourceDir) {
+    for (const filename of EXTERNAL_TEMPLATE_ENTRY_CANDIDATES) {
+        const candidate = path.join(sourceDir, filename);
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function selectRegistryVersion(metadata, locator) {
+    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 (!versions[locator.fetchSpec]) {
+            throw new Error(`npm template package version not found: ${locator.raw}`);
+        }
+        return locator.fetchSpec;
+    }
+    if (locator.type === "tag") {
+        const taggedVersion = distTags[locator.fetchSpec];
+        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 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)"}.`);
+    }
+    const latestVersion = distTags.latest;
+    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 metadataResponse = await fetch(`${registryBase}/${encodeURIComponent(locator.name)}`);
+    if (!metadataResponse.ok) {
+        throw new Error(`Failed to fetch npm template metadata for ${locator.raw}: ${metadataResponse.status}`);
+    }
+    const metadata = (await metadataResponse.json());
+    const resolvedVersion = selectRegistryVersion(metadata, locator);
+    const versions = isPlainObject(metadata.versions) ? metadata.versions : {};
+    const versionMetadata = versions[resolvedVersion];
+    if (!isPlainObject(versionMetadata) || !isPlainObject(versionMetadata.dist)) {
+        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) {
+        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 cleanup = async () => {
+        await fsp.rm(tempRoot, { force: true, recursive: true });
+    };
+    try {
+        const tarballResponse = await fetch(tarballUrl);
+        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");
+        await fsp.mkdir(unpackDir, { recursive: true });
+        await fsp.writeFile(tarballPath, Buffer.from(await tarballResponse.arrayBuffer()));
+        await extractTarball({
+            cwd: unpackDir,
+            file: tarballPath,
+            strip: 1,
+        });
+        await assertNoSymlinks(unpackDir);
+        return {
+            blockDir: unpackDir,
+            cleanup,
+            rootDir: unpackDir,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+async function normalizeWpTypiaTemplateSeed(seed) {
+    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") &&
+                    fs.existsSync(mustacheVariantPath));
+            },
+        });
+    }
+    catch (error) {
+        await fsp.rm(tempRoot, { force: true, recursive: true });
+        throw error;
+    }
+    return {
+        blockDir: normalizedDir,
+        cleanup: async () => {
+            await fsp.rm(tempRoot, { force: true, recursive: true });
+            await seed.cleanup?.();
+        },
+        rootDir: normalizedDir,
+        selectedVariant: seed.selectedVariant,
+        warnings: seed.warnings,
+    };
+}
+/**
+ * Resolve a locally installed npm template package from the caller workspace.
+ *
+ * Bare package ids are preferred here so monorepo and offline workflows can
+ * use an already-installed template without forcing a registry fetch.
+ */
+function resolveInstalledNpmTemplateSource(locator, cwd) {
+    if (locator.rawSpec !== "" && locator.rawSpec !== "*") {
+        return null;
+    }
+    const workspacePackagesRoot = path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..");
+    if (fs.existsSync(workspacePackagesRoot)) {
+        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");
+            if (!fs.existsSync(packageJsonPath)) {
+                continue;
+            }
+            const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+            if (manifest.name === locator.name) {
+                return {
+                    blockDir: packageDir,
+                    rootDir: packageDir,
+                };
+            }
+        }
+    }
+    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);
+        return {
+            blockDir: sourceDir,
+            rootDir: sourceDir,
+        };
+    }
+    catch (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 (!fs.existsSync(packageJsonPath)) {
+                    continue;
+                }
+                const sourceDir = path.dirname(fs.realpathSync(packageJsonPath));
+                return {
+                    blockDir: sourceDir,
+                    rootDir: sourceDir,
+                };
+            }
+            return null;
+        }
+        throw error;
+    }
+}
+function isOfficialWorkspaceTemplateSeed(seed) {
+    const packageJsonPath = path.join(seed.rootDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return packageJson.name === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseGitHubTemplateLocator(templateId) {
+    if (!templateId.startsWith("github:")) {
+        return null;
+    }
+    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}`);
+    }
+    const [owner, repo, ...sourcePathSegments] = segments;
+    return {
+        owner,
+        repo,
+        ref: refSegment ?? null,
+        sourcePath: sourcePathSegments.join("/"),
+    };
+}
+export function parseNpmTemplateLocator(templateId) {
+    if (isBuiltInTemplateId(templateId) || isTemplatePathLocator(templateId) || templateId.startsWith("github:")) {
+        return null;
+    }
+    try {
+        const parsed = npa(templateId);
+        if (!parsed.registry || !parsed.name) {
+            return null;
+        }
+        const parsedWithRawSpec = parsed;
+        const rawSpec = typeof parsedWithRawSpec.rawSpec === "string" ? parsedWithRawSpec.rawSpec : "";
+        return {
+            fetchSpec: typeof parsed.fetchSpec === "string" ? parsed.fetchSpec : "",
+            name: parsed.name,
+            raw: templateId,
+            rawSpec,
+            type: parsed.type,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function parseTemplateLocator(templateId) {
+    if (isRemovedBuiltInTemplateId(templateId)) {
+        throw new Error(getRemovedBuiltInTemplateMessage(templateId));
+    }
+    const githubLocator = parseGitHubTemplateLocator(templateId);
+    if (githubLocator) {
+        return { kind: "github", locator: githubLocator };
+    }
+    if (isTemplatePathLocator(templateId)) {
+        return { kind: "path", templatePath: templateId };
+    }
+    const npmLocator = parseNpmTemplateLocator(templateId);
+    if (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.`);
+}
+function getDefaultCategoryFromBlockJson(blockJson) {
+    return typeof blockJson.category === "string" && blockJson.category.trim().length > 0
+        ? blockJson.category.trim()
+        : "widgets";
+}
+function getDefaultCategory(sourceDir) {
+    try {
+        const blockJson = readRemoteBlockJson(sourceDir);
+        return getDefaultCategoryFromBlockJson(blockJson);
+    }
+    catch {
+        return "widgets";
+    }
+}
+function getTemplateVariableContext(variables) {
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    return {
+        ...variables,
+        apiClientPackageVersion: variables.apiClientPackageVersion ?? apiClientPackageVersion,
+        blockRuntimePackageVersion: variables.blockRuntimePackageVersion ?? blockRuntimePackageVersion,
+        blockTypesPackageVersion: variables.blockTypesPackageVersion ?? blockTypesPackageVersion,
+        projectToolsPackageVersion: variables.projectToolsPackageVersion ?? projectToolsPackageVersion,
+        description: variables.description,
+        keyword: variables.keyword,
+        namespace: variables.namespace,
+        pascalCase: variables.pascalCase,
+        phpPrefix: variables.phpPrefix,
+        restPackageVersion: variables.restPackageVersion ?? restPackageVersion,
+        slug: variables.slug,
+        textDomain: variables.textDomain,
+        title: variables.title,
+    };
+}
+async function detectTemplateSourceFormat(sourceDir) {
+    if (fs.existsSync(path.join(sourceDir, "package.json.mustache"))) {
+        return "wp-typia";
+    }
+    if (getExternalTemplateEntry(sourceDir)) {
+        return "create-block-external";
+    }
+    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"),
+    ];
+    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)));
+    if (hasBlockJson && hasIndexFile && hasEditFile && hasSaveFile) {
+        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")]) {
+        if (fs.existsSync(candidate)) {
+            return JSON.parse(fs.readFileSync(candidate, "utf8"));
+        }
+    }
+    throw new Error(`Unable to locate block.json in ${blockDir}`);
+}
+async function assertNoSymlinks(sourceDir) {
+    const stats = await fsp.lstat(sourceDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Template sources 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 renderTypeScriptLiteral(value) {
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return "undefined";
+}
+function renderTagsForAttribute(attribute) {
+    const tags = [];
+    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(" | ");
+    }
+    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>";
+        default:
+            if (typeof attributeName === "string" && attributeName.toLowerCase().includes("class")) {
+                return "string";
+            }
+            return "unknown";
+    }
+}
+function buildRemoteTypesSource(blockJson, context) {
+    const attributes = (blockJson.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(" & ");
+        lines.push(`  ${JSON.stringify(name)}?: ${renderedType};`);
+    }
+    lines.push("}", "");
+    return lines.join("\n");
+}
+function buildRemoteBlockJsonTemplate(blockJson) {
+    const merged = {
+        ...blockJson,
+        description: "{{description}}",
+        name: "{{namespace}}/{{slug}}",
+        textdomain: "{{textDomain}}",
+        title: "{{title}}",
+    };
+    if (!Array.isArray(merged.keywords) || merged.keywords.length === 0) {
+        merged.keywords = ["{{keyword}}", "typia", "block"];
+    }
+    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");
+    async function visit(currentPath) {
+        const stats = await fsp.stat(currentPath);
+        if (stats.isDirectory()) {
+            const entries = await fsp.readdir(currentPath);
+            for (const entry of entries) {
+                await visit(path.join(currentPath, entry));
+            }
+            return;
+        }
+        if (!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 next = content.replace(/(['"])\.{1,2}\/[^'"]*block\.json\1/g, `$1${normalizedSpecifier}$1`);
+        if (next !== content) {
+            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 existingDependencies = { ...(packageJson.dependencies ?? {}) };
+    const existingDevDependencies = { ...(packageJson.devDependencies ?? {}) };
+    delete existingDependencies["@wp-typia/project-tools"];
+    delete existingDevDependencies["@wp-typia/project-tools"];
+    packageJson.devDependencies = {
+        "@wp-typia/block-runtime": "{{blockRuntimePackageVersion}}",
+        "@wp-typia/block-types": "{{blockTypesPackageVersion}}",
+        ...existingDevDependencies,
+    };
+    if (needsInteractivity) {
+        packageJson.dependencies = {
+            ...existingDependencies,
+            "@wordpress/interactivity": "^6.29.0",
+        };
+    }
+    else if (Object.keys(existingDependencies).length > 0) {
+        packageJson.dependencies = existingDependencies;
+    }
+    else {
+        delete packageJson.dependencies;
+    }
+    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;
+}
+function findSeedRenderPhp(seed) {
+    for (const candidate of [path.join(seed.blockDir, "render.php"), path.join(seed.rootDir, "render.php")]) {
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+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",
+    ]) {
+        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 blockJson = readRemoteBlockJson(seed.blockDir);
+    const sourceRoot = getSeedSourceRoot(seed.blockDir);
+    await fsp.mkdir(templateDir, { recursive: true });
+    for (const layerDir of [SHARED_BASE_TEMPLATE_ROOT, path.join(TEMPLATE_ROOT, "basic")]) {
+        await fsp.cp(layerDir, templateDir, {
+            recursive: true,
+            force: true,
+        });
+    }
+    await removeSeedEntryConflicts(templateDir);
+    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"));
+    }
+    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 patchRemotePackageJson(templateDir, needsInteractivity);
+    return {
+        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",
+        selectedVariant: seed.selectedVariant ?? null,
+        templateDir,
+        warnings: seed.warnings ?? [],
+        cleanup: async () => {
+            await fsp.rm(tempRoot, { force: true, recursive: true });
+            if (seed.cleanup) {
+                await seed.cleanup();
+            }
+        },
+    };
+}
+async function loadExternalTemplateConfig(sourceDir) {
+    const entryPath = getExternalTemplateEntry(sourceDir);
+    if (!entryPath) {
+        throw new Error(`No external template config entry found in ${sourceDir}.`);
+    }
+    const moduleUrl = `${pathToFileURL(entryPath).href}?mtime=${fs.statSync(entryPath).mtimeMs}`;
+    const loadedModule = (await import(moduleUrl));
+    const loadedConfig = loadedModule.default ?? loadedModule;
+    if (!isPlainObject(loadedConfig)) {
+        throw new Error(`External template config must export an object: ${entryPath}`);
+    }
+    const warnings = [];
+    for (const ignoredKey of [
+        "pluginTemplatesPath",
+        "wpScripts",
+        "wpEnv",
+        "customScripts",
+        "npmDependencies",
+        "npmDevDependencies",
+        "customPackageJSON",
+        "pluginReadme",
+        "pluginHeader",
+    ]) {
+        if (ignoredKey in loadedConfig) {
+            warnings.push(getTemplateWarning(ignoredKey));
+        }
+    }
+    return {
+        config: loadedConfig,
+        warnings,
+    };
+}
+function getVariantFlagName(variantName) {
+    return `is${toSegmentPascalCase(variantName)}Variant`;
+}
+function getVariantKeys(config) {
+    return isPlainObject(config.variants) ? Object.keys(config.variants) : [];
+}
+function getVariantConfig(config, requestedVariant) {
+    const variantKeys = getVariantKeys(config);
+    if (variantKeys.length === 0) {
+        if (requestedVariant) {
+            throw new Error(`Variant "${requestedVariant}" was requested, but the external template does not define any variants.`);
+        }
+        return {
+            selectedVariant: null,
+            variantConfig: {},
+        };
+    }
+    const selectedVariant = requestedVariant ?? variantKeys[0];
+    if (!selectedVariant || !isPlainObject(config.variants?.[selectedVariant])) {
+        throw new Error(`Unknown template variant "${requestedVariant}". Expected one of: ${variantKeys.join(", ")}`);
+    }
+    return {
+        selectedVariant,
+        variantConfig: config.variants?.[selectedVariant],
+    };
+}
+function extractVariantRenderValues(variantConfig) {
+    const values = { ...variantConfig };
+    delete values.assetsPath;
+    delete values.blockTemplatesPath;
+    delete values.folderName;
+    delete values.transformer;
+    return values;
+}
+async function buildExternalTemplateView(context, config, selectedVariant, variantConfig) {
+    const mergedView = {
+        ...(config.defaultValues ?? {}),
+        ...extractVariantRenderValues(variantConfig),
+        ...context,
+    };
+    if (selectedVariant) {
+        mergedView.variant = selectedVariant;
+        mergedView[getVariantFlagName(selectedVariant)] = true;
+    }
+    if (!config.transformer) {
+        return mergedView;
+    }
+    const transformed = await config.transformer(mergedView);
+    if (!isPlainObject(transformed)) {
+        throw new Error("External template transformer(view) must return an object.");
+    }
+    return {
+        ...mergedView,
+        ...transformed,
+    };
+}
+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;
+    if (!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 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 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"));
+        }
+        return {
+            assetsDir: fs.existsSync(path.join(tempRoot, "assets")) ? path.join(tempRoot, "assets") : undefined,
+            blockDir,
+            cleanup,
+            rootDir: tempRoot,
+            selectedVariant,
+            warnings,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+async function resolveGitHubTemplateSource(locator) {
+    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");
+    try {
+        const args = ["clone", "--depth", "1"];
+        if (locator.ref) {
+            args.push("--branch", locator.ref);
+        }
+        args.push(`https://github.com/${locator.owner}/${locator.repo}.git`, checkoutDir);
+        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 (!fs.existsSync(sourceDir)) {
+            throw new Error(`GitHub template path does not exist: ${locator.sourcePath}`);
+        }
+        await assertNoSymlinks(sourceDir);
+        return {
+            blockDir: sourceDir,
+            cleanup,
+            rootDir: sourceDir,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+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}`);
+        }
+        await assertNoSymlinks(sourceDir);
+        return {
+            blockDir: sourceDir,
+            rootDir: sourceDir,
+        };
+    }
+    if (locator.kind === "github") {
+        return resolveGitHubTemplateSource(locator.locator);
+    }
+    const installedSource = resolveInstalledNpmTemplateSource(locator.locator, cwd);
+    if (installedSource) {
+        await assertNoSymlinks(installedSource.blockDir);
+        return installedSource;
+    }
+    return fetchNpmTemplateSource(locator.locator);
+}
+export async function resolveTemplateSource(templateId, cwd, variables, variant) {
+    if (isBuiltInTemplateId(templateId)) {
+        if (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",
+        });
+    }
+    const locator = parseTemplateLocator(templateId);
+    const context = getTemplateVariableContext(variables);
+    const seed = await resolveTemplateSeed(locator, cwd);
+    const isOfficialWorkspaceTemplate = isOfficialWorkspaceTemplateSeed(seed);
+    let normalizedSeed = null;
+    try {
+        const format = await detectTemplateSourceFormat(seed.blockDir);
+        if (format === "wp-typia") {
+            if (variant) {
+                throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for "${templateId}".`);
+            }
+            normalizedSeed = await normalizeWpTypiaTemplateSeed(seed);
+            return {
+                id: templateId,
+                defaultCategory: getDefaultCategory(seed.blockDir),
+                description: "A remote wp-typia template source",
+                features: ["Remote source", "wp-typia format"],
+                format,
+                isOfficialWorkspaceTemplate,
+                templateDir: normalizedSeed.blockDir,
+                cleanup: normalizedSeed.cleanup,
+            };
+        }
+        normalizedSeed =
+            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") {
+            const normalized = await normalizeCreateBlockSubset(normalizedSeed, context);
+            return {
+                ...normalized,
+                cleanup: async () => {
+                    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"],
+                format,
+                id: "remote:create-block-external",
+                isOfficialWorkspaceTemplate,
+                selectedVariant: normalizedSeed.selectedVariant ?? null,
+                warnings: normalizedSeed.warnings ?? [],
+            };
+        }
+        const normalized = await normalizeCreateBlockSubset(normalizedSeed, context);
+        return {
+            ...normalized,
+            isOfficialWorkspaceTemplate,
+        };
+    }
+    catch (error) {
+        if (normalizedSeed?.cleanup && normalizedSeed !== seed) {
+            await normalizedSeed.cleanup();
+        }
+        if (seed.cleanup) {
+            await seed.cleanup();
+        }
+        throw error;
+    }
+}