@wp-typia/project-tools 0.19.2 → 0.19.3

package/dist/runtime/external-template-guards.js

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+export const TEMPLATE_SOURCE_TIMEOUT_CODE = "template-source-timeout";
+export const TEMPLATE_SOURCE_TOO_LARGE_CODE = "template-source-too-large";
+const DEFAULT_EXTERNAL_TEMPLATE_TIMEOUT_MS = 20000;
+const DEFAULT_EXTERNAL_TEMPLATE_CONFIG_MAX_BYTES = 256 * 1024;
+const DEFAULT_EXTERNAL_TEMPLATE_PACKAGE_JSON_MAX_BYTES = 1 * 1024 * 1024;
+const DEFAULT_EXTERNAL_TEMPLATE_METADATA_MAX_BYTES = 1 * 1024 * 1024;
+const DEFAULT_EXTERNAL_TEMPLATE_TARBALL_MAX_BYTES = 32 * 1024 * 1024;
+function parsePositiveIntegerEnv(value, fallback) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function createTemplateGuardError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+export function getExternalTemplateTimeoutMs() {
+    return parsePositiveIntegerEnv(process.env.WP_TYPIA_EXTERNAL_TEMPLATE_TIMEOUT_MS, DEFAULT_EXTERNAL_TEMPLATE_TIMEOUT_MS);
+}
+export function getExternalTemplateConfigMaxBytes() {
+    return parsePositiveIntegerEnv(process.env.WP_TYPIA_EXTERNAL_TEMPLATE_CONFIG_MAX_BYTES, DEFAULT_EXTERNAL_TEMPLATE_CONFIG_MAX_BYTES);
+}
+export function getExternalTemplatePackageJsonMaxBytes() {
+    return parsePositiveIntegerEnv(process.env.WP_TYPIA_EXTERNAL_TEMPLATE_PACKAGE_JSON_MAX_BYTES, DEFAULT_EXTERNAL_TEMPLATE_PACKAGE_JSON_MAX_BYTES);
+}
+export function getExternalTemplateMetadataMaxBytes() {
+    return parsePositiveIntegerEnv(process.env.WP_TYPIA_EXTERNAL_TEMPLATE_METADATA_MAX_BYTES, DEFAULT_EXTERNAL_TEMPLATE_METADATA_MAX_BYTES);
+}
+export function getExternalTemplateTarballMaxBytes() {
+    return parsePositiveIntegerEnv(process.env.WP_TYPIA_EXTERNAL_TEMPLATE_TARBALL_MAX_BYTES, DEFAULT_EXTERNAL_TEMPLATE_TARBALL_MAX_BYTES);
+}
+export function createExternalTemplateTimeoutError(label, timeoutMs) {
+    return createTemplateGuardError(TEMPLATE_SOURCE_TIMEOUT_CODE, `Timed out while ${label} after ${timeoutMs}ms.`);
+}
+export function createExternalTemplateTooLargeError(label, maxBytes) {
+    return createTemplateGuardError(TEMPLATE_SOURCE_TOO_LARGE_CODE, `${label} exceeded the external template size limit (${maxBytes} bytes).`);
+}
+export function assertExternalTemplateFileSize(filePath, options) {
+    const stats = fs.statSync(filePath);
+    if (stats.size > options.maxBytes) {
+        throw createExternalTemplateTooLargeError(options.label, options.maxBytes);
+    }
+}
+export async function withExternalTemplateTimeout(label, task, timeoutMs = getExternalTemplateTimeoutMs()) {
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => {
+            reject(createExternalTemplateTimeoutError(label, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        const pendingTask = typeof task === "function" ? task() : task;
+        return await Promise.race([pendingTask, timeoutPromise]);
+    }
+    finally {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+export async function fetchWithExternalTemplateTimeout(input, options) {
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? getExternalTemplateTimeoutMs();
+    const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(input, {
+            ...(options.init ?? {}),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.name === "AbortError" || error.name === "TimeoutError")) {
+            throw createExternalTemplateTimeoutError(options.label, timeoutMs);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
+}
+async function readResponseBodyWithLimit(response, options) {
+    const contentLengthHeader = response.headers.get("content-length");
+    if (typeof contentLengthHeader === "string") {
+        const declaredLength = Number.parseInt(contentLengthHeader, 10);
+        if (Number.isFinite(declaredLength) && declaredLength > options.maxBytes) {
+            throw createExternalTemplateTooLargeError(options.label, options.maxBytes);
+        }
+    }
+    if (!response.body) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (buffer.length > options.maxBytes) {
+            throw createExternalTemplateTooLargeError(options.label, options.maxBytes);
+        }
+        return buffer;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (!value) {
+            continue;
+        }
+        totalBytes += value.byteLength;
+        if (totalBytes > options.maxBytes) {
+            await reader.cancel();
+            throw createExternalTemplateTooLargeError(options.label, options.maxBytes);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+export async function readJsonResponseWithLimit(response, options) {
+    const buffer = await readResponseBodyWithLimit(response, options);
+    try {
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${options.label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function readBufferResponseWithLimit(response, options) {
+    return readResponseBodyWithLimit(response, options);
+}

package/dist/runtime/package-managers.d.ts

@@ -16,6 +16,14 @@ export declare function getPackageManagerSelectOptions(): Array<{
 }>;
 export declare function formatRunScript(packageManagerId: PackageManagerId, scriptName: string, extraArgs?: string): string;
 export declare function formatInstallCommand(packageManagerId: PackageManagerId): string;
+/**
+ * Format a package-manager-specific devDependency install command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packages Package specifiers to add as devDependencies.
+ * @returns Command string suitable for shell execution.
+ */
+export declare function formatAddDevDependenciesCommand(packageManagerId: PackageManagerId, packages: string[]): string;
 /**
  * Format a package-manager-specific one-off package execution command.
  *

package/dist/runtime/package-managers.js

@@ -67,6 +67,19 @@ export function formatRunScript(packageManagerId, scriptName, extraArgs = "") {
 export function formatInstallCommand(packageManagerId) {
     return getPackageManager(packageManagerId).installCommand;
 }
+/**
+ * Format a package-manager-specific devDependency install command.
+ *
+ * @param packageManagerId Package manager identifier.
+ * @param packages Package specifiers to add as devDependencies.
+ * @returns Command string suitable for shell execution.
+ */
+export function formatAddDevDependenciesCommand(packageManagerId, packages) {
+    if (packages.length === 0) {
+        return formatInstallCommand(packageManagerId);
+    }
+    return `${packageManagerId} ${DEV_INSTALL_FLAGS[packageManagerId]} ${packages.join(" ")}`;
+}
 /**
  * Format a package-manager-specific one-off package execution command.
  *

package/dist/runtime/package-versions.d.ts

@@ -7,5 +7,13 @@ interface PackageVersions {
     wpTypiaPackageExactVersion: string;
     wpTypiaPackageVersion: string;
 }
+/**
+ * Clears the in-memory cache used by `getPackageVersions()`.
+ *
+ * Long-lived processes can call this after regenerating or updating package
+ * manifests when they want the next lookup to recompute version metadata
+ * synchronously from disk.
+ */
+export declare function invalidatePackageVersionsCache(): void;
 export declare function getPackageVersions(): PackageVersions;
 export {};

package/dist/runtime/package-versions.js

@@ -31,55 +31,120 @@ function normalizeExactVersion(value) {
     }
     return trimmed.replace(/^[~^<>=]+/, "");
 }
-function readPackageManifest(packageJsonPath) {
+function createContentFingerprint(source) {
+    let hash = 2166136261;
+    for (let index = 0; index < source.length; index += 1) {
+        hash ^= source.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16);
+}
+function resolvePackageManifestLocation(packageJsonPath) {
     try {
-        return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        const stats = fs.statSync(packageJsonPath);
+        const source = fs.readFileSync(packageJsonPath, "utf8");
+        return {
+            cacheKey: `file:${packageJsonPath}:${stats.ino}:${stats.mtimeMs}:${stats.ctimeMs}:${stats.size}:${createContentFingerprint(source)}`,
+            packageJsonPath,
+            source,
+        };
     }
     catch (error) {
         if (getErrorCode(error) === "ENOENT") {
-            return null;
+            return {
+                cacheKey: `missing-file:${packageJsonPath}`,
+                packageJsonPath: null,
+                source: null,
+            };
         }
         throw error;
     }
 }
-function resolveInstalledPackageManifest(packageName) {
+function readPackageManifest(location) {
+    if (!location.packageJsonPath || location.source === null) {
+        return null;
+    }
+    return JSON.parse(location.source);
+}
+function resolveInstalledPackageManifestLocation(packageName) {
     try {
-        return readPackageManifest(require.resolve(`${packageName}/package.json`));
+        return resolvePackageManifestLocation(require.resolve(`${packageName}/package.json`));
     }
     catch (error) {
         if (getErrorCode(error) === "MODULE_NOT_FOUND") {
-            return null;
+            return {
+                cacheKey: `missing-module:${packageName}`,
+                packageJsonPath: null,
+                source: null,
+            };
         }
         throw error;
     }
 }
+function composePackageVersionsCacheKey(locations) {
+    return locations.map((location) => location.cacheKey).join("|");
+}
+/**
+ * Clears the in-memory cache used by `getPackageVersions()`.
+ *
+ * Long-lived processes can call this after regenerating or updating package
+ * manifests when they want the next lookup to recompute version metadata
+ * synchronously from disk.
+ */
+export function invalidatePackageVersionsCache() {
+    cachedPackageVersions = null;
+}
 export function getPackageVersions() {
-    if (cachedPackageVersions) {
-        return cachedPackageVersions;
+    const createManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "package.json"));
+    const blockRuntimeManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia-block-runtime", "package.json"));
+    const wpTypiaManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia", "package.json"));
+    const installedProjectToolsManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/project-tools");
+    const installedApiClientManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/api-client");
+    const installedBlockRuntimeManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/block-runtime");
+    const installedBlockTypesManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/block-types");
+    const installedRestManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/rest");
+    const installedWpTypiaManifestLocation = resolveInstalledPackageManifestLocation("wp-typia");
+    const cacheKey = composePackageVersionsCacheKey([
+        createManifestLocation,
+        blockRuntimeManifestLocation,
+        wpTypiaManifestLocation,
+        installedProjectToolsManifestLocation,
+        installedApiClientManifestLocation,
+        installedBlockRuntimeManifestLocation,
+        installedBlockTypesManifestLocation,
+        installedRestManifestLocation,
+        installedWpTypiaManifestLocation,
+    ]);
+    if (cachedPackageVersions?.cacheKey === cacheKey) {
+        return cachedPackageVersions.versions;
     }
-    const createManifest = readPackageManifest(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "package.json")) ??
-        resolveInstalledPackageManifest("@wp-typia/project-tools") ??
+    const createManifest = readPackageManifest(createManifestLocation) ??
+        readPackageManifest(installedProjectToolsManifestLocation) ??
         {};
-    const blockRuntimeManifest = readPackageManifest(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia-block-runtime", "package.json")) ??
-        resolveInstalledPackageManifest("@wp-typia/block-runtime") ??
+    const blockRuntimeManifest = readPackageManifest(blockRuntimeManifestLocation) ??
+        readPackageManifest(installedBlockRuntimeManifestLocation) ??
         {};
-    const wpTypiaManifest = readPackageManifest(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "..", "wp-typia", "package.json")) ??
-        resolveInstalledPackageManifest("wp-typia") ??
+    const wpTypiaManifest = readPackageManifest(wpTypiaManifestLocation) ??
+        readPackageManifest(installedWpTypiaManifestLocation) ??
         {};
     const blockRuntimeDependencyVersion = normalizeVersionRange(createManifest.dependencies?.["@wp-typia/block-runtime"]);
-    cachedPackageVersions = {
+    const versions = {
         apiClientPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/api-client"] ??
-            resolveInstalledPackageManifest("@wp-typia/api-client")?.version),
+            readPackageManifest(installedApiClientManifestLocation)?.version),
         blockRuntimePackageVersion: blockRuntimeDependencyVersion !== DEFAULT_VERSION_RANGE
             ? blockRuntimeDependencyVersion
             : normalizeVersionRange(blockRuntimeManifest.version),
         blockTypesPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/block-types"] ??
-            resolveInstalledPackageManifest("@wp-typia/block-types")?.version),
+            readPackageManifest(installedBlockTypesManifestLocation)?.version),
         projectToolsPackageVersion: normalizeVersionRange(createManifest.version),
         restPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/rest"] ??
-            resolveInstalledPackageManifest("@wp-typia/rest")?.version),
+            readPackageManifest(installedRestManifestLocation)?.version),
         wpTypiaPackageExactVersion: normalizeExactVersion(wpTypiaManifest.version),
         wpTypiaPackageVersion: normalizeVersionRange(wpTypiaManifest.version),
     };
-    return cachedPackageVersions;
+    cachedPackageVersions = {
+        cacheKey,
+        versions,
+    };
+    return versions;
 }

package/dist/runtime/scaffold-documents.js

@@ -3,6 +3,24 @@ import { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getIniti
 import { formatPackageExecCommand, formatInstallCommand, formatRunScript, } from './package-managers.js';
 import { getPackageVersions } from './package-versions.js';
 import { getScaffoldTemplateVariableGroups } from './scaffold-template-variable-groups.js';
+import { OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from './template-registry.js';
+function formatReadmeTemplateIdentity(templateId) {
+    const normalizedTemplateId = normalizeTemplateLookupId(templateId);
+    if (normalizedTemplateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        return [
+            `- Alias: ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS}`,
+            `- Package: ${OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE}`,
+            '- Type: official workspace scaffold',
+        ].join('\n');
+    }
+    if (normalizedTemplateId === 'query-loop') {
+        return ['- Family: query-loop', '- Type: create-time core/query variation scaffold'].join('\n');
+    }
+    if (isBuiltInTemplateId(normalizedTemplateId)) {
+        return [`- Family: ${normalizedTemplateId}`, '- Type: built-in block scaffold'].join('\n');
+    }
+    return [`- Template id: ${templateId}`, '- Type: custom or external scaffold'].join('\n');
+}
 /**
  * Builds the generated README markdown for one scaffolded project.
  *
@@ -73,7 +91,7 @@ ${variables.description}
 
 ## Template
 
-${templateId}
+${formatReadmeTemplateIdentity(templateId)}
 
 ## Quick Start
 

package/dist/runtime/scaffold-onboarding.d.ts

@@ -22,6 +22,10 @@ export declare function getQuickStartWorkflowNote(packageManager: PackageManager
  * Returns the onboarding note explaining when manual sync is optional.
  */
 export declare function getOptionalOnboardingNote(packageManager: PackageManagerId, templateId?: string, options?: SyncOnboardingOptions): string;
+/**
+ * Returns a shorter optional onboarding note suitable for create completion output.
+ */
+export declare function getOptionalOnboardingShortNote(packageManager: PackageManagerId, templateId?: string, options?: SyncOnboardingOptions): string;
 /**
  * Returns the recommended version-control commands for a fresh scaffold.
  */

package/dist/runtime/scaffold-onboarding.js

@@ -1,7 +1,7 @@
 import { formatPackageExecCommand, formatRunScript, } from "./package-managers.js";
 import { getPackageVersions } from "./package-versions.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
 const INITIAL_COMMIT_COMMANDS = [
     "git init",
     "git add .",
@@ -99,6 +99,30 @@ export function getOptionalOnboardingNote(packageManager, templateId = "basic",
     }
     return `You usually do not need to run ${syncCommand} during a normal ${formatRunScript(packageManager, developmentScript)} session. Run ${syncCommand} before ${formatRunScript(packageManager, "build")}, ${typecheckCommand}, or ${doctorCommand} when you want a reviewable refresh. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` or \`${strictSyncCommand}\` for stricter CI checks.${advancedPersistenceNote} Generated syncs do not create migration history, so refresh before your first commit if this directory is new.`;
 }
+/**
+ * Returns a shorter optional onboarding note suitable for create completion output.
+ */
+export function getOptionalOnboardingShortNote(packageManager, templateId = "basic", options = {}) {
+    const normalizedTemplateId = normalizeTemplateLookupId(templateId);
+    const doctorCommand = getDoctorVerificationCommand(packageManager);
+    if (normalizedTemplateId === "query-loop") {
+        return `No sync step is generated for this Query Loop scaffold. Edit the variation files directly, then rerun ${formatRunScript(packageManager, "build")}, ${formatRunScript(packageManager, "typecheck")}, or ${doctorCommand} when you want a review pass.`;
+    }
+    const optionalSyncScripts = getOptionalSyncScriptNames(normalizedTemplateId, options);
+    const developmentScript = getPrimaryDevelopmentScript(normalizedTemplateId);
+    const devCommand = formatRunScript(packageManager, developmentScript);
+    const isCustomTemplate = !isBuiltInTemplateId(normalizedTemplateId) &&
+        normalizedTemplateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
+    if (isCustomTemplate && optionalSyncScripts.length === 0) {
+        return `Follow the template's own artifact-refresh guidance, then use ${doctorCommand} for a quick environment and workspace sanity check.`;
+    }
+    if (isCustomTemplate && optionalSyncScripts.length > 0) {
+        const syncSteps = optionalSyncScripts.map((scriptName) => formatRunScript(packageManager, scriptName));
+        return `Run ${syncSteps.join(" then ")} before build, typecheck, or ${doctorCommand} when you want a reviewable refresh.`;
+    }
+    const syncCommand = formatRunScript(packageManager, optionalSyncScripts.includes("sync") ? "sync" : "sync-types");
+    return `Skip ${syncCommand} during normal ${devCommand} work. Re-run it before build, typecheck, or ${doctorCommand} when you want a reviewable refresh.`;
+}
 /**
  * Returns the recommended version-control commands for a fresh scaffold.
  */

package/dist/runtime/scaffold.js

@@ -8,13 +8,12 @@ import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
 import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
+import { isBuiltInTemplateId, normalizeTemplateLookupId, } from "./template-registry.js";
 import { resolveTemplateSource } from "./template-source.js";
 import { BlockGeneratorService, } from "./block-generator-service.js";
 import { getTemplateVariables } from "./scaffold-template-variables.js";
 import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 import { assertExternalLayerCompositionOptions, } from "./cli-validation.js";
-const WORKSPACE_TEMPLATE_ALIAS = "workspace";
 export const DATA_STORAGE_MODES = ["post-meta", "custom-table"];
 export const PERSISTENCE_POLICIES = ["authenticated", "public"];
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
@@ -28,9 +27,7 @@ export function isPersistencePolicy(value) {
     return PERSISTENCE_POLICIES.includes(value);
 }
 function normalizeTemplateSelection(templateId) {
-    return templateId === WORKSPACE_TEMPLATE_ALIAS
-        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
-        : templateId;
+    return normalizeTemplateLookupId(templateId);
 }
 async function reportScaffoldProgress(onProgress, event) {
     await onProgress?.(event);

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

@@ -24,6 +24,7 @@ export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
 export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
 export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound", "query-loop"];
 export declare const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+export declare const OFFICIAL_WORKSPACE_TEMPLATE_ALIAS = "workspace";
 export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
 export type PersistencePolicy = "authenticated" | "public";
 export interface TemplateDefinition {
@@ -36,10 +37,31 @@ export interface TemplateDefinition {
 export declare const TEMPLATE_REGISTRY: readonly TemplateDefinition[];
 export declare const TEMPLATE_IDS: BuiltInTemplateId[];
 export declare function isBuiltInTemplateId(templateId: string): templateId is BuiltInTemplateId;
+/**
+ * Returns whether a template id matches the user-facing official workspace alias.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns `true` when the id is the `workspace` alias.
+ */
+export declare function isOfficialWorkspaceTemplateAlias(templateId: string): boolean;
+/**
+ * Converts user-facing template aliases into the registry lookup id.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns The registry id used for template resolution.
+ */
+export declare function normalizeTemplateLookupId(templateId: string): string;
+/**
+ * Converts internal template ids into the id shown in human-facing output.
+ *
+ * @param templateId Template id stored in the registry.
+ * @returns The user-facing template id or alias for display.
+ */
+export declare function getUserFacingTemplateId(templateId: string): string;
 export declare function listTemplates(): readonly TemplateDefinition[];
 export declare function getTemplateById(templateId: string): TemplateDefinition;
 export declare function getTemplateSelectOptions(): Array<{
     label: string;
-    value: TemplateDefinition["id"];
+    value: string;
     hint: string;
 }>;

package/dist/runtime/template-registry.js

@@ -81,6 +81,7 @@ export const BUILTIN_TEMPLATE_IDS = [
     "query-loop",
 ];
 export const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
+export const OFFICIAL_WORKSPACE_TEMPLATE_ALIAS = "workspace";
 export const TEMPLATE_REGISTRY = Object.freeze([
     {
         id: "basic",
@@ -129,14 +130,47 @@ export const TEMPLATE_IDS = [...BUILTIN_TEMPLATE_IDS];
 export function isBuiltInTemplateId(templateId) {
     return BUILTIN_TEMPLATE_IDS.includes(templateId);
 }
+/**
+ * Returns whether a template id matches the user-facing official workspace alias.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns `true` when the id is the `workspace` alias.
+ */
+export function isOfficialWorkspaceTemplateAlias(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_ALIAS;
+}
+/**
+ * Converts user-facing template aliases into the registry lookup id.
+ *
+ * @param templateId Template id or alias supplied by a caller.
+ * @returns The registry id used for template resolution.
+ */
+export function normalizeTemplateLookupId(templateId) {
+    return isOfficialWorkspaceTemplateAlias(templateId)
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
+/**
+ * Converts internal template ids into the id shown in human-facing output.
+ *
+ * @param templateId Template id stored in the registry.
+ * @returns The user-facing template id or alias for display.
+ */
+export function getUserFacingTemplateId(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        ? OFFICIAL_WORKSPACE_TEMPLATE_ALIAS
+        : templateId;
+}
 export function listTemplates() {
     return TEMPLATE_REGISTRY;
 }
 export function getTemplateById(templateId) {
-    const template = TEMPLATE_REGISTRY.find((entry) => entry.id === templateId);
+    const normalizedTemplateId = normalizeTemplateLookupId(templateId);
+    const template = TEMPLATE_REGISTRY.find((entry) => entry.id === normalizedTemplateId);
     if (!template) {
         throw new Error(`Unknown template "${templateId}". Expected one of: ${[
             ...TEMPLATE_IDS,
+            OFFICIAL_WORKSPACE_TEMPLATE_ALIAS,
             OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
         ].join(", ")}`);
     }
@@ -144,8 +178,8 @@ export function getTemplateById(templateId) {
 }
 export function getTemplateSelectOptions() {
     return TEMPLATE_REGISTRY.map((template) => ({
-        label: template.id,
-        value: template.id,
+        label: getUserFacingTemplateId(template.id),
+        value: getUserFacingTemplateId(template.id),
         hint: template.features.join(", "),
     }));
 }

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

@@ -2,6 +2,7 @@
 import fs 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 './object-utils.js';
 import { toSegmentPascalCase } from './string-case.js';
 import { createManagedTempRoot } from './temp-roots.js';
@@ -47,8 +48,12 @@ async function loadExternalTemplateConfig(sourceDir) {
     if (!entryPath) {
         throw new Error(`No external template config entry found in ${sourceDir}.`);
     }
+    assertExternalTemplateFileSize(entryPath, {
+        label: `External template config "${entryPath}"`,
+        maxBytes: getExternalTemplateConfigMaxBytes(),
+    });
     const moduleUrl = `${pathToFileURL(entryPath).href}?mtime=${fs.statSync(entryPath).mtimeMs}`;
-    const loadedModule = (await import(moduleUrl));
+    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}`);
@@ -150,10 +155,11 @@ async function buildExternalTemplateView(context, config, selectedVariant, varia
         mergedView.variant = selectedVariant;
         mergedView[getVariantFlagName(selectedVariant)] = true;
     }
-    if (!config.transformer) {
+    const transformer = config.transformer;
+    if (!transformer) {
         return mergedView;
     }
-    const transformed = await config.transformer(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.');
     }

package/dist/runtime/template-source-remote.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import path from 'node:path';
+import { assertExternalTemplateFileSize, getExternalTemplatePackageJsonMaxBytes, } from './external-template-guards.js';
 import { getBuiltInTemplateLayerDirs, isOmittableBuiltInTemplateLayerDir, } from './template-builtins.js';
 import { copyRawDirectory } from './template-render.js';
 import { createManagedTempRoot } from './temp-roots.js';
@@ -66,6 +67,10 @@ function readTemplatePackageJson(sourceDir) {
             continue;
         }
         try {
+            assertExternalTemplateFileSize(candidate, {
+                label: `Template metadata file "${candidate}"`,
+                maxBytes: getExternalTemplatePackageJsonMaxBytes(),
+            });
             return {
                 packageJson: JSON.parse(fs.readFileSync(candidate, 'utf8')),
                 sourcePath: candidate,