@wp-typia/project-tools 0.24.4 → 0.24.5

package/dist/runtime/templates/template-source-external.js

@@ -0,0 +1,241 @@
+/// <reference path="./external-template-modules.d.ts" />
+import fs from 'node:fs';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertExternalTemplateFileSize, getExternalTemplateConfigMaxBytes, withExternalTemplateTimeout, } from './external-template-guards.js';
+import { isPlainObject } from '../shared/object-utils.js';
+import { toSegmentPascalCase } from '../shared/string-case.js';
+import { createManagedTempRoot } from '../shared/temp-roots.js';
+import { copyRawDirectory, copyRenderedDirectory } from './template-render.js';
+import { pathExists } from '../shared/fs-async.js';
+/**
+ * Candidate filenames for official external template config entrypoints.
+ */
+export const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES = [
+    'index.js',
+    'index.cjs',
+    'index.mjs',
+];
+export const EXTERNAL_TEMPLATE_TRUST_WARNING = 'External template configs execute trusted JavaScript during scaffolding. Review the template source before using local paths, GitHub repos, or npm packages you do not already trust.';
+const TEMPLATE_WARNING_MESSAGE = 'wp-typia owns package/tooling/sync setup for generated projects, so this external template setting is ignored.';
+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;
+}
+/**
+ * Search a source directory for the first supported external template entry.
+ *
+ * @deprecated Since 0.22.10. Use `findExternalTemplateEntry()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export 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;
+}
+/**
+ * Search a source directory for a supported external template entry asynchronously.
+ *
+ * @param sourceDir Directory that may contain an external template config entry.
+ * @returns The first matching entry path, or null when no supported entry exists.
+ */
+export async function findExternalTemplateEntry(sourceDir) {
+    for (const filename of EXTERNAL_TEMPLATE_ENTRY_CANDIDATES) {
+        const candidate = path.join(sourceDir, filename);
+        if (await pathExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function loadExternalTemplateConfig(sourceDir) {
+    const entryPath = await findExternalTemplateEntry(sourceDir);
+    if (!entryPath) {
+        throw new Error(`No external template config entry found in ${sourceDir}.`);
+    }
+    assertExternalTemplateFileSize(entryPath, {
+        label: `External template config "${entryPath}"`,
+        maxBytes: getExternalTemplateConfigMaxBytes(),
+    });
+    const entryStats = await fsp.stat(entryPath);
+    const moduleUrl = `${pathToFileURL(entryPath).href}?mtime=${entryStats.mtimeMs}`;
+    const loadedModule = (await withExternalTemplateTimeout(`loading external template config "${entryPath}"`, () => import(moduleUrl)));
+    const loadedConfig = loadedModule.default ?? loadedModule;
+    if (!isPlainObject(loadedConfig)) {
+        throw new Error(`External template config must export an object: ${entryPath}`);
+    }
+    const warnings = [EXTERNAL_TEMPLATE_TRUST_WARNING];
+    for (const ignoredKey of [
+        '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.pluginTemplatesPath;
+    delete values.transformer;
+    return values;
+}
+function resolveConfiguredTemplatePath(config, variantConfig) {
+    const variantPluginTemplatesPath = typeof variantConfig.pluginTemplatesPath === 'string'
+        ? variantConfig.pluginTemplatesPath
+        : null;
+    const variantBlockTemplatesPath = typeof variantConfig.blockTemplatesPath === 'string'
+        ? variantConfig.blockTemplatesPath
+        : null;
+    const configBlockTemplatesPath = typeof config.blockTemplatesPath === 'string'
+        ? config.blockTemplatesPath
+        : null;
+    const configPluginTemplatesPath = typeof config.pluginTemplatesPath === 'string'
+        ? config.pluginTemplatesPath
+        : null;
+    const templatePath = variantPluginTemplatesPath ??
+        variantBlockTemplatesPath ??
+        configBlockTemplatesPath ??
+        configPluginTemplatesPath;
+    if (!templatePath) {
+        throw new Error('External template config must define blockTemplatesPath or pluginTemplatesPath.');
+    }
+    const configuredFolderName = (typeof variantConfig.folderName === 'string'
+        ? variantConfig.folderName
+        : config.folderName) ?? null;
+    return {
+        folderName: configuredFolderName || '.',
+        formatHint: templatePath === variantPluginTemplatesPath ||
+            templatePath === configPluginTemplatesPath
+            ? 'wp-typia'
+            : 'create-block-subset',
+        templatePath,
+    };
+}
+async function buildExternalTemplateView(context, config, selectedVariant, variantConfig) {
+    const mergedView = {
+        ...(config.defaultValues ?? {}),
+        ...extractVariantRenderValues(variantConfig),
+        ...context,
+    };
+    if (selectedVariant) {
+        mergedView.variant = selectedVariant;
+        mergedView[getVariantFlagName(selectedVariant)] = true;
+    }
+    const transformer = config.transformer;
+    if (!transformer) {
+        return mergedView;
+    }
+    const transformed = await withExternalTemplateTimeout(`running external template transformer for "${context.slug}"`, () => Promise.resolve(transformer(mergedView)));
+    if (!isPlainObject(transformed)) {
+        throw new Error('External template transformer(view) must return an object.');
+    }
+    return {
+        ...mergedView,
+        ...transformed,
+    };
+}
+/**
+ * Load an official external template config and render its seed.
+ *
+ * @param sourceDir Source directory that contains the external template config.
+ * @param context Template render context used for the selected variant.
+ * @param requestedVariant Optional explicit variant override.
+ * @returns A rendered temporary seed directory with optional assets and cleanup.
+ */
+export async function renderCreateBlockExternalTemplate(sourceDir, context, requestedVariant) {
+    const { config, warnings } = await loadExternalTemplateConfig(sourceDir);
+    const { selectedVariant, variantConfig } = getVariantConfig(config, requestedVariant);
+    const { folderName, formatHint, templatePath } = resolveConfiguredTemplatePath(config, variantConfig);
+    const { path: tempRoot, cleanup } = await createManagedTempRoot('wp-typia-create-block-external-');
+    try {
+        const renderedRoot = path.join(tempRoot, 'rendered');
+        const blockDir = resolveSourceSubpath(renderedRoot, folderName);
+        const view = await buildExternalTemplateView(context, config, selectedVariant, variantConfig);
+        const blockTemplateDir = resolveSourceSubpath(sourceDir, templatePath);
+        await copyRenderedDirectory(blockTemplateDir, blockDir, view, {
+            filter: async (sourcePath, _destinationPath, entry) => {
+                const mustacheVariantPath = path.join(path.dirname(sourcePath), `${entry.name}.mustache`);
+                return !(entry.isFile() &&
+                    (entry.name === 'package.json' || entry.name === 'README.md') &&
+                    (await pathExists(mustacheVariantPath)));
+            },
+        });
+        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 assetsDir = path.join(tempRoot, 'assets');
+        return {
+            assetsDir: (await pathExists(assetsDir)) ? assetsDir : undefined,
+            blockDir,
+            cleanup,
+            formatHint,
+            rootDir: tempRoot,
+            selectedVariant,
+            warnings,
+        };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { GitHubTemplateLocator, NpmTemplateLocator, RemoteTemplateLocator } from './template-source-contracts.js';
+export declare function parseGitHubTemplateLocator(templateId: string): GitHubTemplateLocator | null;
+export declare function parseNpmTemplateLocator(templateId: string): NpmTemplateLocator | null;
+export declare function parseTemplateLocator(templateId: string): RemoteTemplateLocator;

package/dist/runtime/templates/template-source-locators.js

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import npa from 'npm-package-arg';
+import { BUILTIN_TEMPLATE_IDS, isBuiltInTemplateId, } from './template-registry.js';
+import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from './template-defaults.js';
+function isTemplatePathLocator(templateId) {
+    return (path.isAbsolute(templateId) ||
+        templateId.startsWith('./') ||
+        templateId.startsWith('../'));
+}
+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.`);
+}

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

@@ -0,0 +1,7 @@
+export { renderCreateBlockExternalTemplate } from './template-source-external.js';
+export { getTemplateProjectType, getTemplateProjectTypeAsync, getDefaultCategory, getDefaultCategoryAsync, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
+import type { TemplateSourceFormat, TemplateVariableContext } from './template-source-contracts.js';
+export declare function getTemplateVariableContext(variables: {
+    [key: string]: string;
+}): TemplateVariableContext;
+export declare function detectTemplateSourceFormat(sourceDir: string): Promise<TemplateSourceFormat>;

package/dist/runtime/templates/template-source-normalization.js

@@ -0,0 +1,58 @@
+/// <reference path="./external-template-modules.d.ts" />
+import path from 'node:path';
+import { loadExternalTemplateLayerManifest } from './template-layers.js';
+import { getPackageVersions } from '../shared/package-versions.js';
+import { findExternalTemplateEntry } from './template-source-external.js';
+import { getTemplateProjectTypeAsync } from './template-source-remote.js';
+import { pathExists } from '../shared/fs-async.js';
+export { renderCreateBlockExternalTemplate } from './template-source-external.js';
+export { getTemplateProjectType, getTemplateProjectTypeAsync, getDefaultCategory, getDefaultCategoryAsync, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
+export function getTemplateVariableContext(variables) {
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, wpTypiaPackageVersion, } = getPackageVersions();
+    return {
+        ...variables,
+        apiClientPackageVersion: variables.apiClientPackageVersion ?? apiClientPackageVersion,
+        blockRuntimePackageVersion: variables.blockRuntimePackageVersion ?? blockRuntimePackageVersion,
+        blockTypesPackageVersion: variables.blockTypesPackageVersion ?? blockTypesPackageVersion,
+        projectToolsPackageVersion: variables.projectToolsPackageVersion ?? projectToolsPackageVersion,
+        wpTypiaPackageVersion: variables.wpTypiaPackageVersion ?? wpTypiaPackageVersion,
+        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,
+    };
+}
+export async function detectTemplateSourceFormat(sourceDir) {
+    if (await pathExists(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 (await findExternalTemplateEntry(sourceDir)) {
+        return 'create-block-external';
+    }
+    if ((await getTemplateProjectTypeAsync(sourceDir)) !== null) {
+        return 'wp-typia';
+    }
+    const sourceRoot = await pathExists(path.join(sourceDir, 'src'))
+        ? path.join(sourceDir, 'src')
+        : sourceDir;
+    const blockJsonCandidates = [
+        path.join(sourceDir, 'block.json'),
+        path.join(sourceRoot, 'block.json'),
+    ];
+    const hasBlockJson = (await Promise.all(blockJsonCandidates.map((candidate) => pathExists(candidate)))).some(Boolean);
+    const hasIndexFile = (await Promise.all(['index.js', 'index.jsx', 'index.ts', 'index.tsx'].map((filename) => pathExists(path.join(sourceRoot, filename))))).some(Boolean);
+    const hasEditFile = (await Promise.all(['edit.js', 'edit.jsx', 'edit.ts', 'edit.tsx'].map((filename) => pathExists(path.join(sourceRoot, filename))))).some(Boolean);
+    const hasSaveFile = (await Promise.all(['save.js', 'save.jsx', 'save.ts', 'save.tsx'].map((filename) => pathExists(path.join(sourceRoot, filename))))).some(Boolean);
+    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.`);
+}

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

@@ -0,0 +1,52 @@
+import type { ResolvedTemplateSource, SeedSource, TemplateVariableContext } from './template-source-contracts.js';
+/**
+ * Read a remote block source and return its default block category.
+ *
+ * @deprecated Since 0.22.10. Use `getDefaultCategoryAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param sourceDir Block source directory that may contain a block.json file.
+ * @returns The declared block category, or "widgets" when detection fails.
+ */
+export declare function getDefaultCategory(sourceDir: string): string;
+/**
+ * Read a remote block source and return its default block category asynchronously.
+ *
+ * @param sourceDir Block source directory that may contain a block.json file.
+ * @returns The declared block category, or "widgets" when detection fails.
+ */
+export declare function getDefaultCategoryAsync(sourceDir: string): Promise<string>;
+/**
+ * Read `wpTypia.projectType` from a rendered or source template package
+ * manifest and return it when present.
+ *
+ * @deprecated Since 0.22.10. Use `getTemplateProjectTypeAsync()` from async
+ * template-source paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ */
+export declare function getTemplateProjectType(sourceDir: string): string | null;
+/**
+ * Read `wpTypia.projectType` from template metadata asynchronously.
+ *
+ * @param sourceDir Template source directory to inspect.
+ * @returns The project type when present, otherwise `null`.
+ */
+export declare function getTemplateProjectTypeAsync(sourceDir: string): Promise<string | null>;
+/**
+ * Copy a wp-typia seed into a normalized temporary template directory.
+ *
+ * @param seed Seed source whose files should be normalized into a temp root.
+ * @returns A cloned seed whose cleanup removes the temp root and original seed.
+ */
+export declare function normalizeWpTypiaTemplateSeed(seed: SeedSource): Promise<SeedSource>;
+/**
+ * Convert a create-block subset seed into a normalized wp-typia template source.
+ *
+ * @param seed Seed source produced from a remote create-block subset.
+ * @param context Template variable context used for generated artifacts.
+ * @returns A normalized template source rooted in a temporary directory.
+ */
+export declare function normalizeCreateBlockSubset(seed: SeedSource, context: TemplateVariableContext): Promise<ResolvedTemplateSource>;