@wp-typia/project-tools 0.19.2 → 0.20.0

package/dist/runtime/cli-templates.js

@@ -1,5 +1,4 @@
-import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./template-registry.js";
-const WORKSPACE_TEMPLATE_ALIAS = "workspace";
+import { OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, getUserFacingTemplateId, getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./template-registry.js";
 /**
  * Format one line of template list output for a built-in template.
  *
@@ -7,7 +6,7 @@ const WORKSPACE_TEMPLATE_ALIAS = "workspace";
  * @returns One-line summary text for `templates list`.
  */
 export function formatTemplateSummary(template) {
-    return `${template.id.padEnd(14)} ${template.description}`;
+    return `${getUserFacingTemplateId(template.id).padEnd(14)} ${template.description}`;
 }
 /**
  * Format the feature and capability hint lines shown under a template summary.
@@ -17,6 +16,10 @@ export function formatTemplateSummary(template) {
  */
 export function formatTemplateFeatures(template) {
     const lines = [`  Features: ${template.features.join(" • ")}`];
+    const bestForHint = getTemplateBestForHint(template);
+    if (bestForHint) {
+        lines.push(`  Best for: ${bestForHint}`);
+    }
     const capabilityHints = getTemplateCapabilityHints(template);
     if (capabilityHints.length > 0) {
         lines.push(`  Supports: ${capabilityHints.join(" • ")}`);
@@ -26,7 +29,7 @@ export function formatTemplateFeatures(template) {
         lines.push(`  Notes: ${specialNotes.join(" • ")}`);
     }
     if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
-        lines.push(`  Alias: ${WORKSPACE_TEMPLATE_ALIAS} (\`--template ${WORKSPACE_TEMPLATE_ALIAS}\`)`);
+        lines.push(`  Alias: ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS} (\`--template ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS}\`)`);
     }
     return lines.join("\n");
 }
@@ -43,8 +46,9 @@ export function formatTemplateFeatures(template) {
  */
 export function formatTemplateDetails(template) {
     const detailLines = [
-        template.id,
+        getUserFacingTemplateId(template.id),
         `Summary: ${template.description}`,
+        `Best for: ${getTemplateBestForHint(template)}`,
         ...getTemplateIdentityLines(template),
         `Category: ${template.defaultCategory}`,
     ];
@@ -69,6 +73,24 @@ export function formatTemplateDetails(template) {
     detailLines.push(`Features: ${template.features.join(", ")}`);
     return detailLines.join("\n");
 }
+function getTemplateBestForHint(template) {
+    if (template.id === "basic") {
+        return "minimal static-first block scaffolds with Typia validation and the lightest default surface";
+    }
+    if (template.id === "interactivity") {
+        return "interactive single-block experiences that keep client-side state and actions inside one scaffold";
+    }
+    if (template.id === "persistence") {
+        return "typed REST-backed blocks that need persistence-aware reads, writes, and schema refresh workflows";
+    }
+    if (template.id === "compound") {
+        return "parent-and-child block families that own nested authoring conventions and optional persistence wiring";
+    }
+    if (template.id === "query-loop") {
+        return "create-time `core/query` variations with connected starter patterns instead of `add block` families";
+    }
+    return "official multi-block workspaces that extend through `wp-typia add ...` and workspace doctor flows";
+}
 function getTemplateCapabilityHints(template) {
     if (template.id === "persistence" || template.id === "compound") {
         return [
@@ -99,11 +121,19 @@ function getTemplateIdentityLines(template) {
     if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
         return [
             "Identity:",
+            `  - User-facing alias: ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS} (\`--template ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS}\`)`,
             `  - Official package: ${OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE}`,
-            `  - Alias: ${WORKSPACE_TEMPLATE_ALIAS} (\`--template ${WORKSPACE_TEMPLATE_ALIAS}\`)`,
             "Type: official workspace scaffold",
         ];
     }
+    if (template.id === "query-loop") {
+        return [
+            "Identity:",
+            "  - Built-in template id: query-loop",
+            "Type: create-time core/query variation scaffold",
+            "Output model: variation-only scaffold; does not generate block.json or Typia manifests",
+        ];
+    }
     return [
         "Identity:",
         `  - Built-in template id: ${template.id}`,

package/dist/runtime/external-template-guards.d.ts

@@ -0,0 +1,31 @@
+export declare const TEMPLATE_SOURCE_TIMEOUT_CODE: "template-source-timeout";
+export declare const TEMPLATE_SOURCE_TOO_LARGE_CODE: "template-source-too-large";
+export declare function getExternalTemplateTimeoutMs(): number;
+export declare function getExternalTemplateConfigMaxBytes(): number;
+export declare function getExternalTemplatePackageJsonMaxBytes(): number;
+export declare function getExternalTemplateMetadataMaxBytes(): number;
+export declare function getExternalTemplateTarballMaxBytes(): number;
+export declare function createExternalTemplateTimeoutError(label: string, timeoutMs: number): Error & {
+    code: typeof TEMPLATE_SOURCE_TIMEOUT_CODE;
+};
+export declare function createExternalTemplateTooLargeError(label: string, maxBytes: number): Error & {
+    code: typeof TEMPLATE_SOURCE_TOO_LARGE_CODE;
+};
+export declare function assertExternalTemplateFileSize(filePath: string, options: {
+    label: string;
+    maxBytes: number;
+}): void;
+export declare function withExternalTemplateTimeout<T>(label: string, task: Promise<T> | (() => Promise<T>), timeoutMs?: number): Promise<T>;
+export declare function fetchWithExternalTemplateTimeout(input: string, options: {
+    init?: RequestInit;
+    label: string;
+    timeoutMs?: number;
+}): Promise<Response>;
+export declare function readJsonResponseWithLimit(response: Response, options: {
+    label: string;
+    maxBytes: number;
+}): Promise<Record<string, unknown>>;
+export declare function readBufferResponseWithLimit(response: Response, options: {
+    label: string;
+    maxBytes: number;
+}): Promise<Buffer>;

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/index.d.ts

@@ -13,6 +13,8 @@
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, isCompoundInnerBlocksPresetId, parseCompoundInnerBlocksPreset, resolveCompoundInnerBlocksPreset, } from "./compound-inner-blocks.js";
 export type { CompoundInnerBlocksPresetDefinition, CompoundInnerBlocksPresetId, CompoundInnerBlocksTemplateLock, } from "./compound-inner-blocks.js";
 export { scaffoldProject, collectScaffoldAnswers, getScaffoldTemplateVariableGroups, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
+export { DEFAULT_SCAFFOLD_COMPATIBILITY, OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY, createScaffoldCompatibilityConfig, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, updatePluginHeaderCompatibility, } from "./scaffold-compatibility.js";
+export type { ScaffoldCompatibilityConfig, ScaffoldCompatibilityPolicy, ScaffoldPluginHeaderCompatibility, } from "./scaffold-compatibility.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export type { BasicScaffoldTemplateVariableGroups, CompoundScaffoldTemplateVariableGroups, ExternalScaffoldTemplateVariableGroups, FlatScaffoldTemplateVariables, InteractivityScaffoldTemplateVariableGroups, PersistenceScaffoldTemplateVariableGroups, QueryLoopScaffoldTemplateVariableGroups, ScaffoldTemplateFamily, ScaffoldTemplateVariableGroups, } from "./scaffold.js";
 export type { ApplyBlockInput, BlockGenerationTarget, BlockSpec, PlanBlockInput, PlanBlockResult, RenderBlockInput, RenderBlockResult, ValidateBlockInput, ValidateBlockResult, } from "./block-generator-service.js";
@@ -26,5 +28,5 @@ export type { EndpointAuthIntent, EndpointOpenApiAuthMode, EndpointOpenApiContra
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.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, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.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";

package/dist/runtime/index.js

@@ -12,6 +12,7 @@
  */
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, isCompoundInnerBlocksPresetId, parseCompoundInnerBlocksPreset, resolveCompoundInnerBlocksPreset, } from "./compound-inner-blocks.js";
 export { scaffoldProject, collectScaffoldAnswers, getScaffoldTemplateVariableGroups, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
+export { DEFAULT_SCAFFOLD_COMPATIBILITY, OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY, REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY, createScaffoldCompatibilityConfig, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, updatePluginHeaderCompatibility, } from "./scaffold-compatibility.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";
 export { formatMigrationHelpText, parseMigrationArgs, runMigrationCommand, } from "./migrations.js";
@@ -21,4 +22,4 @@ export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, str
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.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, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.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";

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-compatibility.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Compatibility policy helpers for generated scaffold outputs.
+ *
+ * The policy keeps plugin headers, runtime gates, and workspace inventory
+ * metadata aligned when optional or required AI-capable features are added.
+ */
+import { type AiFeatureCapabilitySelection, type AiFeatureCompatibilityFloor, type ResolvedAiFeatureCapabilityPlan } from "./ai-feature-capability.js";
+/**
+ * WordPress plugin header version floors emitted by scaffold templates.
+ */
+export interface ScaffoldPluginHeaderCompatibility {
+    requiresAtLeast: string;
+    requiresPhp: string;
+    testedUpTo: string;
+}
+/**
+ * Resolved compatibility policy for a set of scaffold feature capabilities.
+ */
+export interface ScaffoldCompatibilityPolicy {
+    capabilityPlan: ResolvedAiFeatureCapabilityPlan;
+    pluginHeader: ScaffoldPluginHeaderCompatibility;
+}
+/**
+ * Serializable compatibility metadata stored in generated workspace inventory.
+ */
+export interface ScaffoldCompatibilityConfig {
+    hardMinimums: AiFeatureCompatibilityFloor;
+    mode: "baseline" | "optional" | "required";
+    optionalFeatures: string[];
+    requiredFeatures: string[];
+    runtimeGates: string[];
+}
+/**
+ * Baseline headers used by scaffold output before optional features are added.
+ */
+export declare const DEFAULT_SCAFFOLD_COMPATIBILITY: ScaffoldPluginHeaderCompatibility;
+/**
+ * Optional WordPress AI Client surface used by server-only AI feature scaffold.
+ */
+export declare const OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY: readonly AiFeatureCapabilitySelection[];
+/**
+ * Required Abilities API surface used by typed workflow ability scaffold.
+ */
+export declare const REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY: readonly AiFeatureCapabilitySelection[];
+/**
+ * Resolve plugin header floors and capability gates for scaffold selections.
+ */
+export declare function resolveScaffoldCompatibilityPolicy(selections: readonly AiFeatureCapabilitySelection[], { baseline, }?: {
+    baseline?: ScaffoldPluginHeaderCompatibility;
+}): ScaffoldCompatibilityPolicy;
+/**
+ * Convert a resolved policy into workspace-inventory-safe JSON metadata.
+ */
+export declare function createScaffoldCompatibilityConfig(policy: ScaffoldCompatibilityPolicy): ScaffoldCompatibilityConfig;
+/**
+ * Render compatibility metadata as formatted TypeScript object literal JSON.
+ */
+export declare function renderScaffoldCompatibilityConfig(policy: ScaffoldCompatibilityPolicy, indent?: string): string;
+/**
+ * Patch a generated plugin bootstrap header without lowering custom floors.
+ *
+ * Preserves the original header line endings while replacing empty or invalid
+ * version strings with the policy values.
+ */
+export declare function updatePluginHeaderCompatibility(source: string, policy: ScaffoldCompatibilityPolicy): string;