@wp-typia/project-tools 0.20.2 → 0.21.0

package/dist/runtime/cli-validation.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
 /**
  * Normalize one optional CLI string flag by trimming whitespace and collapsing
  * empty strings to `undefined`.
@@ -44,7 +45,7 @@ export function resolveLocalCliPathOption(options) {
     }
     const resolvedPath = path.resolve(options.cwd, normalizedValue);
     if (!fs.existsSync(resolvedPath)) {
-        throw new Error(`\`${options.label}\` path does not exist: ${resolvedPath}. Check the path relative to ${options.cwd}.`);
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `\`${options.label}\` path does not exist: ${resolvedPath}. Check the path relative to ${options.cwd}.`);
     }
     return resolvedPath;
 }
@@ -58,7 +59,7 @@ export function resolveLocalCliPathOption(options) {
  */
 export function assertExternalLayerCompositionOptions(options) {
     if (options.externalLayerId && !options.externalLayerSource) {
-        throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, "externalLayerId requires externalLayerSource when composing built-in template layers.");
     }
 }
 /**
@@ -85,7 +86,7 @@ export function assertBuiltInTemplateVariantAllowed(options) {
     if (!options.variant) {
         return;
     }
-    throw new Error(createBuiltInVariantErrorMessage({
+    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, createBuiltInVariantErrorMessage({
         templateId: options.templateId,
         variant: options.variant,
     }));

package/dist/runtime/index.d.ts

@@ -5,8 +5,11 @@
  * CLI while keeping reusable project logic out of the CLI package itself.
  * Consumers should prefer these exports for scaffold, add, migrate, doctor,
  * and workspace-aware helpers such as `getWorkspaceBlockSelectOptions`,
- * `runAddBlockCommand`, `runAddVariationCommand`, `runAddPatternCommand`,
- * `runAddBindingSourceCommand`, `runAddEditorPluginCommand`,
+ * `runAddBlockCommand`, `runAddBlockStyleCommand`,
+ * `runAddBlockTransformCommand`, `runAddVariationCommand`,
+ * `runAddPatternCommand`, `runAddBindingSourceCommand`,
+ * `runAddEditorPluginCommand`,
+ * `runAddAdminViewCommand`,
  * `runAddHookedBlockCommand`,
  * `HOOKED_BLOCK_POSITION_IDS`, and `runDoctor`.
  */
@@ -26,7 +29,9 @@ export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJso
 export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 export type { EndpointAuthIntent, EndpointOpenApiAuthMode, EndpointOpenApiContractDocument, EndpointOpenApiDocumentOptions, EndpointOpenApiEndpointDefinition, EndpointOpenApiMethod, EndpointWordPressAuthDefinition, EndpointWordPressAuthMechanism, JsonSchemaDocument, JsonSchemaProjectionProfile, JsonSchemaObject, NormalizedEndpointAuthDefinition, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiSecurityScheme, } from "./schema-core.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
+export type { PackageVersions } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
-export { createReadlinePrompt, createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
-export type { CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";

package/dist/runtime/index.js

@@ -5,8 +5,11 @@
  * CLI while keeping reusable project logic out of the CLI package itself.
  * Consumers should prefer these exports for scaffold, add, migrate, doctor,
  * and workspace-aware helpers such as `getWorkspaceBlockSelectOptions`,
- * `runAddBlockCommand`, `runAddVariationCommand`, `runAddPatternCommand`,
- * `runAddBindingSourceCommand`, `runAddEditorPluginCommand`,
+ * `runAddBlockCommand`, `runAddBlockStyleCommand`,
+ * `runAddBlockTransformCommand`, `runAddVariationCommand`,
+ * `runAddPatternCommand`, `runAddBindingSourceCommand`,
+ * `runAddEditorPluginCommand`,
+ * `runAddAdminViewCommand`,
  * `runAddHookedBlockCommand`,
  * `HOOKED_BLOCK_POSITION_IDS`, and `runDoctor`.
  */
@@ -20,6 +23,7 @@ export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWork
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
 export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
-export { createReadlinePrompt, createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";

package/dist/runtime/package-json-types.d.ts

@@ -0,0 +1,12 @@
+export interface GeneratedPackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    packageManager?: string;
+    scripts?: Record<string, string>;
+    wpTypia?: {
+        projectType?: string;
+        templatePackage?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}

package/dist/runtime/package-json-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,9 +1,13 @@
-interface PackageVersions {
+export interface PackageVersions {
     apiClientPackageVersion: string;
     blockRuntimePackageVersion: string;
     blockTypesPackageVersion: string;
     projectToolsPackageVersion: string;
     restPackageVersion: string;
+    tsxPackageVersion: string;
+    typiaPackageVersion: string;
+    typiaUnpluginPackageVersion: string;
+    typescriptPackageVersion: string;
     wpTypiaPackageExactVersion: string;
     wpTypiaPackageVersion: string;
 }
@@ -14,6 +18,17 @@ interface PackageVersions {
  * manifests when they want the next lookup to recompute version metadata
  * synchronously from disk.
  */
+export declare function clearPackageVersionsCache(): void;
+/**
+ * Backwards-compatible alias for integrations that adopted the original
+ * internal invalidation name before the public cache policy was documented.
+ */
 export declare function invalidatePackageVersionsCache(): void;
+/**
+ * Resolve package versions used in generated manifests and onboarding text.
+ *
+ * The lookup keeps a process-local cached result while recomputing manifest
+ * fingerprints on each call. When the relevant package metadata changes on
+ * disk, the cache key changes and the returned version object is refreshed.
+ */
 export declare function getPackageVersions(): PackageVersions;
-export {};

package/dist/runtime/package-versions.js

@@ -5,6 +5,8 @@ import { PROJECT_TOOLS_PACKAGE_ROOT } from "./template-registry.js";
 const require = createRequire(import.meta.url);
 const DEFAULT_VERSION_RANGE = "^0.0.0";
 const DEFAULT_EXACT_VERSION = "0.0.0";
+const DEFAULT_TSX_PACKAGE_VERSION = "^4.20.5";
+const DEFAULT_TYPIA_UNPLUGIN_PACKAGE_VERSION = "^12.0.1";
 let cachedPackageVersions = null;
 function getErrorCode(error) {
     return typeof error === "object" && error !== null && "code" in error
@@ -31,6 +33,10 @@ function normalizeExactVersion(value) {
     }
     return trimmed.replace(/^[~^<>=]+/, "");
 }
+function normalizeVersionRangeWithFallback(value, fallback) {
+    const normalized = normalizeVersionRange(value);
+    return normalized === DEFAULT_VERSION_RANGE ? fallback : normalized;
+}
 function createContentFingerprint(source) {
     let hash = 2166136261;
     for (let index = 0; index < source.length; index += 1) {
@@ -91,11 +97,26 @@ function composePackageVersionsCacheKey(locations) {
  * manifests when they want the next lookup to recompute version metadata
  * synchronously from disk.
  */
-export function invalidatePackageVersionsCache() {
+export function clearPackageVersionsCache() {
     cachedPackageVersions = null;
 }
+/**
+ * Backwards-compatible alias for integrations that adopted the original
+ * internal invalidation name before the public cache policy was documented.
+ */
+export function invalidatePackageVersionsCache() {
+    clearPackageVersionsCache();
+}
+/**
+ * Resolve package versions used in generated manifests and onboarding text.
+ *
+ * The lookup keeps a process-local cached result while recomputing manifest
+ * fingerprints on each call. When the relevant package metadata changes on
+ * disk, the cache key changes and the returned version object is refreshed.
+ */
 export function getPackageVersions() {
     const createManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, "package.json"));
+    const monorepoManifestLocation = 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");
@@ -103,9 +124,14 @@ export function getPackageVersions() {
     const installedBlockRuntimeManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/block-runtime");
     const installedBlockTypesManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/block-types");
     const installedRestManifestLocation = resolveInstalledPackageManifestLocation("@wp-typia/rest");
+    const installedTsxManifestLocation = resolveInstalledPackageManifestLocation("tsx");
+    const installedTypiaManifestLocation = resolveInstalledPackageManifestLocation("typia");
+    const installedTypiaUnpluginManifestLocation = resolveInstalledPackageManifestLocation("@typia/unplugin");
+    const installedTypescriptManifestLocation = resolveInstalledPackageManifestLocation("typescript");
     const installedWpTypiaManifestLocation = resolveInstalledPackageManifestLocation("wp-typia");
     const cacheKey = composePackageVersionsCacheKey([
         createManifestLocation,
+        monorepoManifestLocation,
         blockRuntimeManifestLocation,
         wpTypiaManifestLocation,
         installedProjectToolsManifestLocation,
@@ -113,6 +139,10 @@ export function getPackageVersions() {
         installedBlockRuntimeManifestLocation,
         installedBlockTypesManifestLocation,
         installedRestManifestLocation,
+        installedTsxManifestLocation,
+        installedTypiaManifestLocation,
+        installedTypiaUnpluginManifestLocation,
+        installedTypescriptManifestLocation,
         installedWpTypiaManifestLocation,
     ]);
     if (cachedPackageVersions?.cacheKey === cacheKey) {
@@ -121,6 +151,7 @@ export function getPackageVersions() {
     const createManifest = readPackageManifest(createManifestLocation) ??
         readPackageManifest(installedProjectToolsManifestLocation) ??
         {};
+    const monorepoManifest = readPackageManifest(monorepoManifestLocation) ?? {};
     const blockRuntimeManifest = readPackageManifest(blockRuntimeManifestLocation) ??
         readPackageManifest(installedBlockRuntimeManifestLocation) ??
         {};
@@ -139,6 +170,20 @@ export function getPackageVersions() {
         projectToolsPackageVersion: normalizeVersionRange(createManifest.version),
         restPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/rest"] ??
             readPackageManifest(installedRestManifestLocation)?.version),
+        tsxPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.tsx ??
+            monorepoManifest.devDependencies?.tsx ??
+            readPackageManifest(installedTsxManifestLocation)?.version, DEFAULT_TSX_PACKAGE_VERSION),
+        typiaPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.typia ??
+            monorepoManifest.devDependencies?.typia ??
+            createManifest.dependencies?.typia ??
+            readPackageManifest(installedTypiaManifestLocation)?.version, DEFAULT_VERSION_RANGE),
+        typiaUnpluginPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.["@typia/unplugin"] ??
+            monorepoManifest.devDependencies?.["@typia/unplugin"] ??
+            readPackageManifest(installedTypiaUnpluginManifestLocation)?.version, DEFAULT_TYPIA_UNPLUGIN_PACKAGE_VERSION),
+        typescriptPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.typescript ??
+            monorepoManifest.devDependencies?.typescript ??
+            createManifest.dependencies?.typescript ??
+            readPackageManifest(installedTypescriptManifestLocation)?.version, DEFAULT_VERSION_RANGE),
         wpTypiaPackageExactVersion: normalizeExactVersion(wpTypiaManifest.version),
         wpTypiaPackageVersion: normalizeVersionRange(wpTypiaManifest.version),
     };

package/dist/runtime/php-utils.d.ts

@@ -0,0 +1,16 @@
+export type PhpFunctionRange = {
+    end: number;
+    source: string;
+    start: number;
+};
+export type PhpFunctionRangeOptions = {
+    includeTrailingNewlines?: boolean;
+};
+export type ReplacePhpFunctionDefinitionOptions = PhpFunctionRangeOptions & {
+    trimReplacementStart?: boolean;
+};
+export declare function escapeRegex(value: string): string;
+export declare function quotePhpString(value: string): string;
+export declare function hasPhpFunctionDefinition(source: string, functionName: string): boolean;
+export declare function findPhpFunctionRange(source: string, functionName: string, options?: PhpFunctionRangeOptions): PhpFunctionRange | null;
+export declare function replacePhpFunctionDefinition(source: string, functionName: string, replacement: string, options?: ReplacePhpFunctionDefinitionOptions): string | null;

package/dist/runtime/php-utils.js

@@ -0,0 +1,59 @@
+export function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+export function quotePhpString(value) {
+    return `'${value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'")}'`;
+}
+export function hasPhpFunctionDefinition(source, functionName) {
+    return new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(source);
+}
+export function findPhpFunctionRange(source, functionName, options = {}) {
+    const signaturePattern = new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\([^)]*\\)\\s*(?::\\s*[^{};]+)?\\s*\\{`, "u");
+    const signatureMatch = signaturePattern.exec(source);
+    if (!signatureMatch) {
+        return null;
+    }
+    const functionStart = signatureMatch.index;
+    const openBraceOffset = signatureMatch[0].lastIndexOf("{");
+    if (openBraceOffset === -1) {
+        return null;
+    }
+    const openBraceIndex = functionStart + openBraceOffset;
+    let depth = 0;
+    for (let index = openBraceIndex; index < source.length; index += 1) {
+        const character = source[index];
+        if (character === "{") {
+            depth += 1;
+            continue;
+        }
+        if (character !== "}") {
+            continue;
+        }
+        depth -= 1;
+        if (depth === 0) {
+            let end = index + 1;
+            if (options.includeTrailingNewlines ?? true) {
+                while (end < source.length && /[\r\n]/u.test(source[end] ?? "")) {
+                    end += 1;
+                }
+            }
+            return {
+                end,
+                source: source.slice(functionStart, end),
+                start: functionStart,
+            };
+        }
+    }
+    return null;
+}
+export function replacePhpFunctionDefinition(source, functionName, replacement, options = {}) {
+    const functionRange = findPhpFunctionRange(source, functionName, options);
+    if (!functionRange) {
+        return null;
+    }
+    return [
+        source.slice(0, functionRange.start),
+        options.trimReplacementStart ? replacement.trimStart() : replacement,
+        source.slice(functionRange.end),
+    ].join("");
+}

package/dist/runtime/scaffold-answer-resolution.js

@@ -2,6 +2,7 @@ import { execSync } from 'node:child_process';
 import path from 'node:path';
 import { PACKAGE_MANAGER_IDS, getPackageManager, } from './package-managers.js';
 import { normalizeBlockSlug, resolveScaffoldIdentifiers, validateBlockSlug, validateNamespace, } from './scaffold-identifiers.js';
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from './cli-diagnostics.js';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
 import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from './template-defaults.js';
 import { parseNpmTemplateLocator } from './template-source-locators.js';
@@ -75,7 +76,7 @@ function normalizeQueryPostType(value) {
     }
     const validationResult = validateQueryPostType(value);
     if (validationResult !== true) {
-        throw new Error(validationResult);
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, validationResult);
     }
     return value.trim().toLowerCase();
 }
@@ -163,7 +164,7 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
     if (templateId) {
         const normalizedTemplateId = normalizeTemplateSelection(templateId);
         if (isRemovedBuiltInTemplateId(templateId)) {
-            throw new Error(getRemovedBuiltInTemplateMessage(templateId));
+            throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, getRemovedBuiltInTemplateMessage(templateId));
         }
         if (normalizedTemplateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
             return normalizedTemplateId;
@@ -173,10 +174,10 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
         }
         const mistypedBuiltInTemplateMessage = getMistypedBuiltInTemplateMessage(templateId);
         if (mistypedBuiltInTemplateMessage) {
-            throw new Error(mistypedBuiltInTemplateMessage);
+            throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, mistypedBuiltInTemplateMessage);
         }
         if (!looksLikeExplicitExternalTemplateLocator(normalizedTemplateId)) {
-            throw new Error(getUnknownTemplateMessage(templateId));
+            throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, getUnknownTemplateMessage(templateId));
         }
         return normalizedTemplateId;
     }
@@ -184,7 +185,7 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
         return 'basic';
     }
     if (!isInteractive || !selectTemplate) {
-        throw new Error(`Template is required in non-interactive mode. Use ${TEMPLATE_SELECTION_HINT}.`);
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `Template is required in non-interactive mode. Use ${TEMPLATE_SELECTION_HINT}.`);
     }
     return normalizeTemplateSelection(await selectTemplate());
 }
@@ -202,7 +203,7 @@ export async function resolvePackageManagerId({ packageManager, yes = false, isI
         return 'npm';
     }
     if (!isInteractive || !selectPackageManager) {
-        throw new Error(`Package manager is required in non-interactive mode. Use --package-manager <${PACKAGE_MANAGER_IDS.join('|')}>.`);
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `Package manager is required in non-interactive mode. Use --package-manager <${PACKAGE_MANAGER_IDS.join('|')}>.`);
     }
     return selectPackageManager();
 }

package/dist/runtime/scaffold-apply-utils.d.ts

@@ -2,8 +2,9 @@ import { type BuiltInBlockArtifact } from "./built-in-block-artifacts.js";
 import type { BuiltInCodeArtifact } from "./built-in-block-code-artifacts.js";
 import { type BuiltInTemplateId } from "./template-registry.js";
 import type { PackageManagerId } from "./package-managers.js";
+export { applyWorkspaceMigrationCapability, isOfficialWorkspaceProject, } from "./scaffold-bootstrap.js";
 import type { ScaffoldProgressEvent, ScaffoldTemplateVariables } from "./scaffold.js";
-export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
+export { buildGitignore, buildReadme, mergeTextLines } from "./scaffold-documents.js";
 export interface InstallDependenciesOptions {
     packageManager: PackageManagerId;
     projectDir: string;
@@ -27,8 +28,6 @@ export declare function replaceTextRecursively(targetDir: string, packageManager
     repositoryReference?: string;
 }): Promise<void>;
 export declare function defaultInstallDependencies({ projectDir, packageManager, }: InstallDependenciesOptions): Promise<void>;
-export declare function isOfficialWorkspaceProject(projectDir: string): boolean;
-export declare function applyWorkspaceMigrationCapability(projectDir: string, packageManager: PackageManagerId): Promise<void>;
 /**
  * Applies a built-in scaffold into the target directory, including generated
  * code artifacts, starter manifests, preset files, and placeholder rewrites.

package/dist/runtime/scaffold-apply-utils.js

@@ -5,19 +5,17 @@ import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
-import { getPackageVersions } from "./package-versions.js";
-import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
 import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
 import { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 import { formatNonEmptyTargetDirectoryError, } from "./scaffold-bootstrap.js";
 import { stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { formatInstallCommand, formatPackageExecCommand, transformPackageManagerText, } from "./package-managers.js";
+import { formatInstallCommand, transformPackageManagerText, } from "./package-managers.js";
 import { normalizePackageJson } from "./scaffold-package-manager-files.js";
+export { applyWorkspaceMigrationCapability, isOfficialWorkspaceProject, } from "./scaffold-bootstrap.js";
 import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
-export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
+export { buildGitignore, buildReadme, mergeTextLines } from "./scaffold-documents.js";
 async function reportScaffoldProgress(onProgress, event) {
     await onProgress?.(event);
 }
@@ -208,44 +206,6 @@ export async function defaultInstallDependencies({ projectDir, packageManager, }
         stdio: "inherit",
     });
 }
-export function isOfficialWorkspaceProject(projectDir) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-        return false;
-    }
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-    return (packageJson.wpTypia?.projectType === "workspace" &&
-        packageJson.wpTypia?.templatePackage === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE);
-}
-export async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
-    const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
-        ? "wp-typia"
-        : `wp-typia@${wpTypiaPackageVersion.replace(/^[~^]/u, "")}`;
-    const migrationCli = (args) => formatPackageExecCommand(packageManager, canonicalCliSpecifier, `migrate ${args}`);
-    packageJson.scripts = {
-        ...(packageJson.scripts ?? {}),
-        "migration:init": migrationCli("init --current-migration-version v1"),
-        "migration:snapshot": migrationCli("snapshot"),
-        "migration:diff": migrationCli("diff"),
-        "migration:scaffold": migrationCli("scaffold"),
-        "migration:doctor": migrationCli("doctor --all"),
-        "migration:fixtures": migrationCli("fixtures --all"),
-        "migration:verify": migrationCli("verify --all"),
-        "migration:fuzz": migrationCli("fuzz --all"),
-    };
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
-    writeMigrationConfig(projectDir, {
-        blocks: [],
-        currentMigrationVersion: "v1",
-        snapshotDir: "src/migrations/versions",
-        supportedMigrationVersions: ["v1"],
-    });
-    ensureMigrationDirectories(projectDir, []);
-    writeInitialMigrationScaffold(projectDir, "v1", []);
-}
 /**
  * Applies a built-in scaffold into the target directory, including generated
  * code artifacts, starter manifests, preset files, and placeholder rewrites.

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

@@ -0,0 +1,112 @@
+/**
+ * Environment variable that disables external template cache reads and writes.
+ *
+ * Set to `0`, `false`, `no`, or `off` to bypass the cache.
+ */
+export declare const EXTERNAL_TEMPLATE_CACHE_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE";
+/**
+ * Environment variable that overrides the external template cache root.
+ */
+export declare const EXTERNAL_TEMPLATE_CACHE_DIR_ENV = "WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR";
+/**
+ * Serializable metadata recorded in the cache marker for diagnostics.
+ */
+type ExternalTemplateCacheMetadata = Record<string, string | null>;
+/**
+ * Describes a deterministic external template cache entry.
+ *
+ * `namespace` scopes independent cache families, `keyParts` identify the exact
+ * source/integrity tuple, and `metadata` is persisted to the marker file.
+ */
+export interface ExternalTemplateCacheDescriptor {
+    /**
+     * Ordered values that deterministically identify one cached template source.
+     */
+    keyParts: readonly string[];
+    /**
+     * Diagnostic values persisted to the cache marker after sanitization.
+     */
+    metadata: ExternalTemplateCacheMetadata;
+    /**
+     * Cache family scope, stored as a single safe directory segment.
+     */
+    namespace: string;
+}
+/**
+ * Result returned when a cache entry is reused or populated.
+ */
+export interface ExternalTemplateCacheResolution {
+    /**
+     * Whether the returned source directory came from an existing cache entry.
+     */
+    cacheHit: boolean;
+    /**
+     * Populated or reused template source directory.
+     */
+    sourceDir: string;
+}
+/**
+ * Metadata-only lookup descriptor for finding an existing reusable cache entry.
+ */
+export interface ExternalTemplateCacheLookupDescriptor {
+    /**
+     * Metadata fields that must match the sanitized marker metadata.
+     */
+    metadata: ExternalTemplateCacheMetadata;
+    /**
+     * Cache family scope, stored as a single safe directory segment.
+     */
+    namespace: string;
+}
+/**
+ * Checks whether remote external template source caching is enabled.
+ *
+ * Caching is enabled by default. Set `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE` to
+ * `0`, `false`, `no`, or `off` to force uncached resolution.
+ *
+ * @param env Environment object to inspect, defaulting to `process.env`.
+ * @returns Whether external template source cache reads and writes are enabled.
+ */
+export declare function isExternalTemplateCacheEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolves the external template source cache root directory.
+ *
+ * `WP_TYPIA_EXTERNAL_TEMPLATE_CACHE_DIR` overrides the location. Without an
+ * override, wp-typia uses a per-user `wp-typia-template-source-cache-*`
+ * directory inside the operating system temp directory.
+ *
+ * @param env Environment object to inspect, defaulting to `process.env`.
+ * @returns Absolute cache root directory path.
+ */
+export declare function getExternalTemplateCacheRoot(env?: NodeJS.ProcessEnv): string;
+/**
+ * Creates a deterministic cache key from source identity and integrity parts.
+ *
+ * @param keyParts Ordered values that identify one cached template source.
+ * @returns SHA-256 hex digest of the JSON-serialized key parts.
+ */
+export declare function createExternalTemplateCacheKey(keyParts: readonly string[]): string;
+/**
+ * Finds a reusable cache entry whose marker metadata includes the expected fields.
+ *
+ * This lookup is intended for resilient fallbacks where a caller cannot compute
+ * the exact deterministic key but can safely reuse a previously validated local
+ * cache entry for the same source identity.
+ *
+ * @param descriptor Cache namespace and marker metadata fields to match.
+ * @returns Existing cache resolution details, or `null` when no safe entry exists.
+ */
+export declare function findReusableExternalTemplateSourceCache(descriptor: ExternalTemplateCacheLookupDescriptor): Promise<ExternalTemplateCacheResolution | null>;
+/**
+ * Resolves or populates a cached external template source directory.
+ *
+ * Returns `null` when caching is disabled. Cache misses populate a temporary
+ * directory first and then atomically move it into place; concurrent writers
+ * that lose the race reuse the completed marker/source pair.
+ *
+ * @param descriptor Namespace, key parts, and metadata for the cache entry.
+ * @param populateSourceDir Callback that writes the guarded source on a miss.
+ * @returns Cache resolution details, or `null` when caching is disabled.
+ */
+export declare function resolveExternalTemplateSourceCache(descriptor: ExternalTemplateCacheDescriptor, populateSourceDir: (sourceDir: string) => Promise<void>): Promise<ExternalTemplateCacheResolution | null>;
+export {};