@wp-typia/project-tools 0.19.3 → 0.20.0

package/dist/runtime/cli-doctor-workspace.js

@@ -11,6 +11,10 @@ const WORKSPACE_BINDING_SERVER_GLOB = "/src/bindings/*/server.php";
 const WORKSPACE_BINDING_EDITOR_SCRIPT = "build/bindings/index.js";
 const WORKSPACE_BINDING_EDITOR_ASSET = "build/bindings/index.asset.php";
 const WORKSPACE_REST_RESOURCE_GLOB = "/inc/rest/*.php";
+const WORKSPACE_ABILITY_GLOB = "/inc/abilities/*.php";
+const WORKSPACE_ABILITY_EDITOR_SCRIPT = "build/abilities/index.js";
+const WORKSPACE_ABILITY_EDITOR_ASSET = "build/abilities/index.asset.php";
+const WORKSPACE_AI_FEATURE_GLOB = "/inc/ai-features/*.php";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_SCRIPT = "build/editor-plugins/index.js";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_ASSET = "build/editor-plugins/index.asset.php";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_STYLE = "build/editor-plugins/style-index.css";
@@ -249,6 +253,126 @@ function checkWorkspaceRestResourceBootstrap(projectDir, packageName, phpPrefix)
         ? "REST resource PHP loader hook is present"
         : "Missing REST resource PHP require glob or init hook");
 }
+function getWorkspaceAbilityRequiredFiles(ability) {
+    return Array.from(new Set([
+        ability.clientFile,
+        ability.configFile,
+        ability.dataFile,
+        ability.inputSchemaFile,
+        ability.outputSchemaFile,
+        ability.phpFile,
+        ability.typesFile,
+    ]));
+}
+function checkWorkspaceAbilityConfig(projectDir, ability) {
+    const configPath = path.join(projectDir, ability.configFile);
+    if (!fs.existsSync(configPath)) {
+        return createDoctorCheck(`Ability config ${ability.slug}`, "fail", `Missing ${ability.configFile}`);
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const abilityId = typeof config.abilityId === "string" ? config.abilityId.trim() : "";
+        const categorySlug = typeof config.category?.slug === "string"
+            ? config.category.slug.trim()
+            : "";
+        const hasValidAbilityId = /^[a-z0-9-]+\/[a-z0-9-]+$/u.test(abilityId);
+        const hasValidCategorySlug = /^[a-z0-9-]+$/u.test(categorySlug);
+        return createDoctorCheck(`Ability config ${ability.slug}`, hasValidAbilityId && hasValidCategorySlug ? "pass" : "fail", hasValidAbilityId && hasValidCategorySlug
+            ? `Ability id ${abilityId} in category ${categorySlug} is valid`
+            : "Ability config must define a valid abilityId (`namespace/ability-name`) and category.slug.");
+    }
+    catch (error) {
+        return createDoctorCheck(`Ability config ${ability.slug}`, "fail", error instanceof Error ? error.message : String(error));
+    }
+}
+function checkWorkspaceAbilityBootstrap(projectDir, packageName, phpPrefix) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("Ability bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const loadFunctionName = `${phpPrefix}_load_workflow_abilities`;
+    const enqueueFunctionName = `${phpPrefix}_enqueue_workflow_abilities`;
+    const loadHook = `add_action( 'plugins_loaded', '${loadFunctionName}' );`;
+    const adminEnqueueHook = `add_action( 'admin_enqueue_scripts', '${enqueueFunctionName}' );`;
+    const editorEnqueueHook = `add_action( 'enqueue_block_editor_assets', '${enqueueFunctionName}' );`;
+    const hasLoaderHook = source.includes(loadHook);
+    const hasAdminEnqueueHook = source.includes(adminEnqueueHook);
+    const hasEditorEnqueueHook = source.includes(editorEnqueueHook);
+    const hasServerGlob = source.includes(WORKSPACE_ABILITY_GLOB);
+    const hasEditorScript = source.includes(WORKSPACE_ABILITY_EDITOR_SCRIPT);
+    const hasEditorAsset = source.includes(WORKSPACE_ABILITY_EDITOR_ASSET);
+    return createDoctorCheck("Ability bootstrap", hasLoaderHook &&
+        hasAdminEnqueueHook &&
+        hasEditorEnqueueHook &&
+        hasServerGlob &&
+        hasEditorScript &&
+        hasEditorAsset
+        ? "pass"
+        : "fail", hasLoaderHook &&
+        hasAdminEnqueueHook &&
+        hasEditorEnqueueHook &&
+        hasServerGlob &&
+        hasEditorScript &&
+        hasEditorAsset
+        ? "Ability loader and admin/editor client bootstrap hooks are present"
+        : "Missing ability loader hook or build/abilities script asset references");
+}
+function checkWorkspaceAbilityIndex(projectDir, abilities) {
+    const indexRelativePath = [
+        path.join("src", "abilities", "index.ts"),
+        path.join("src", "abilities", "index.js"),
+    ].find((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
+    if (!indexRelativePath) {
+        return createDoctorCheck("Abilities index", "fail", "Missing src/abilities/index.ts or src/abilities/index.js");
+    }
+    const indexPath = path.join(projectDir, indexRelativePath);
+    const source = fs.readFileSync(indexPath, "utf8");
+    const missingExports = abilities.filter((ability) => {
+        const exportPattern = new RegExp(`^\\s*export\\s+(?:\\*\\s+from|\\{[^}]+\\}\\s+from)\\s+['"\`]\\./${escapeRegex(ability.slug)}\\/client['"\`]`, "mu");
+        return !exportPattern.test(source);
+    });
+    return createDoctorCheck("Abilities index", missingExports.length === 0 ? "pass" : "fail", missingExports.length === 0
+        ? "Ability client helpers are aggregated"
+        : `Missing ability exports for: ${missingExports.map((entry) => entry.slug).join(", ")}`);
+}
+function getWorkspaceAiFeatureRequiredFiles(aiFeature) {
+    return Array.from(new Set([
+        aiFeature.aiSchemaFile,
+        aiFeature.apiFile,
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-request.schema.json"),
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-response.schema.json"),
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-result.schema.json"),
+        aiFeature.clientFile,
+        aiFeature.dataFile,
+        aiFeature.openApiFile,
+        aiFeature.phpFile,
+        aiFeature.typesFile,
+        aiFeature.validatorsFile,
+    ]));
+}
+function checkWorkspaceAiFeatureConfig(aiFeature) {
+    const hasNamespace = REST_RESOURCE_NAMESPACE_PATTERN.test(aiFeature.namespace);
+    return createDoctorCheck(`AI feature config ${aiFeature.slug}`, hasNamespace ? "pass" : "fail", hasNamespace
+        ? `AI feature namespace ${aiFeature.namespace} is valid`
+        : "AI feature namespace is invalid");
+}
+function checkWorkspaceAiFeatureBootstrap(projectDir, packageName, phpPrefix) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("AI feature bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const registerFunctionName = `${phpPrefix}_register_ai_features`;
+    const registerHook = `add_action( 'init', '${registerFunctionName}', 20 );`;
+    const hasServerGlob = source.includes(WORKSPACE_AI_FEATURE_GLOB);
+    const hasRegisterHook = source.includes(registerHook);
+    return createDoctorCheck("AI feature bootstrap", hasServerGlob && hasRegisterHook ? "pass" : "fail", hasServerGlob && hasRegisterHook
+        ? "AI feature PHP loader hook is present"
+        : "Missing AI feature PHP require glob or init hook");
+}
 function getWorkspaceEditorPluginRequiredFiles(editorPlugin) {
     const editorPluginDir = path.join("src", "editor-plugins", editorPlugin.slug);
     return Array.from(new Set([
@@ -377,7 +501,7 @@ export function getWorkspaceDoctorChecks(cwd) {
     checks.push(checkWorkspacePackageMetadata(workspace, workspacePackageJson));
     try {
         const inventory = readWorkspaceInventory(workspace.projectDir);
-        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s), ${inventory.restResources.length} REST resource(s), ${inventory.editorPlugins.length} editor plugin(s)`));
+        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s), ${inventory.restResources.length} REST resource(s), ${inventory.abilities.length} ability scaffold(s), ${inventory.aiFeatures.length} AI feature(s), ${inventory.editorPlugins.length} editor plugin(s)`));
         for (const block of inventory.blocks) {
             checks.push(checkExistingFiles(workspace.projectDir, `Block ${block.slug}`, getWorkspaceBlockRequiredFiles(block)));
             checks.push(checkWorkspaceBlockMetadata(workspace.projectDir, workspace, block));
@@ -422,6 +546,21 @@ export function getWorkspaceDoctorChecks(cwd) {
             checks.push(checkWorkspaceRestResourceConfig(restResource));
             checks.push(checkExistingFiles(workspace.projectDir, `REST resource ${restResource.slug}`, getWorkspaceRestResourceRequiredFiles(restResource)));
         }
+        if (inventory.abilities.length > 0) {
+            checks.push(checkWorkspaceAbilityBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
+            checks.push(checkWorkspaceAbilityIndex(workspace.projectDir, inventory.abilities));
+        }
+        for (const ability of inventory.abilities) {
+            checks.push(checkWorkspaceAbilityConfig(workspace.projectDir, ability));
+            checks.push(checkExistingFiles(workspace.projectDir, `Ability ${ability.slug}`, getWorkspaceAbilityRequiredFiles(ability)));
+        }
+        if (inventory.aiFeatures.length > 0) {
+            checks.push(checkWorkspaceAiFeatureBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
+        }
+        for (const aiFeature of inventory.aiFeatures) {
+            checks.push(checkWorkspaceAiFeatureConfig(aiFeature));
+            checks.push(checkExistingFiles(workspace.projectDir, `AI feature ${aiFeature.slug}`, getWorkspaceAiFeatureRequiredFiles(aiFeature)));
+        }
         if (inventory.editorPlugins.length > 0) {
             checks.push(checkWorkspaceEditorPluginBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
             checks.push(checkWorkspaceEditorPluginIndex(workspace.projectDir, inventory.editorPlugins));

package/dist/runtime/cli-help.js

@@ -23,6 +23,8 @@ export function formatHelpText() {
   wp-typia add pattern <name>
   wp-typia add binding-source <name>
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <method[,method...]>]
+  wp-typia add ability <name>
+  wp-typia add ai-feature <name> [--namespace <vendor/v1>]
   wp-typia add editor-plugin <name> [--slot <PluginSidebar>]
   wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <before|after|firstChild|lastChild>
   wp-typia migrate <init|snapshot|diff|scaffold|verify|doctor|fixtures|fuzz> [...]
@@ -45,6 +47,8 @@ Notes:
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
+  \`add ability\` scaffolds typed workflow abilities under \`src/abilities/\` and server registration under \`inc/abilities/\`.
+  \`add ai-feature\` scaffolds server-owned AI feature endpoints under \`src/ai-features/\` and PHP route glue under \`inc/ai-features/\`.
   \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
   \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory and source-tree drift checks.

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/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;

package/dist/runtime/scaffold-compatibility.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { AI_FEATURE_DEFINITIONS, resolveAiFeatureCapabilityPlan, } from "./ai-feature-capability.js";
+/**
+ * Baseline headers used by scaffold output before optional features are added.
+ */
+export const DEFAULT_SCAFFOLD_COMPATIBILITY = {
+    requiresAtLeast: "6.7",
+    requiresPhp: "8.0",
+    testedUpTo: "6.9",
+};
+/**
+ * Optional WordPress AI Client surface used by server-only AI feature scaffold.
+ */
+export const OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY = [
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressAiClient.id,
+        mode: "optional",
+    },
+];
+/**
+ * Required Abilities API surface used by typed workflow ability scaffold.
+ */
+export const REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY = [
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressServerAbilities.id,
+        mode: "required",
+    },
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressCoreAbilities.id,
+        mode: "required",
+    },
+];
+function parseVersionFloorParts(value) {
+    return value.split(".").map((part, index) => {
+        if (!/^\d+$/u.test(part)) {
+            throw new Error(`parseVersionFloorParts received an invalid version floor "${value}" at segment ${index + 1}.`);
+        }
+        return Number.parseInt(part, 10);
+    });
+}
+function compareVersionFloors(left, right) {
+    const leftParts = parseVersionFloorParts(left);
+    const rightParts = parseVersionFloorParts(right);
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftValue = leftParts[index] ?? 0;
+        const rightValue = rightParts[index] ?? 0;
+        if (leftValue > rightValue) {
+            return 1;
+        }
+        if (leftValue < rightValue) {
+            return -1;
+        }
+    }
+    return 0;
+}
+function pickHigherVersionFloor(current, candidate) {
+    if (!candidate) {
+        return current;
+    }
+    return compareVersionFloors(current, candidate) >= 0 ? current : candidate;
+}
+function pickHigherHeaderVersionFloor(policyValue, currentValue) {
+    const normalizedCurrentValue = currentValue.trim();
+    if (!normalizedCurrentValue) {
+        return policyValue;
+    }
+    try {
+        return pickHigherVersionFloor(policyValue, normalizedCurrentValue);
+    }
+    catch {
+        return policyValue;
+    }
+}
+function formatRuntimeGate(feature) {
+    return (feature.runtimeGates ?? []).map((gate) => `${feature.label}: ${gate.kind} ${gate.value}`);
+}
+function getPolicyMode(capabilityPlan) {
+    if (capabilityPlan.requiredFeatures.length > 0) {
+        return "required";
+    }
+    if (capabilityPlan.optionalFeatures.length > 0) {
+        return "optional";
+    }
+    return "baseline";
+}
+/**
+ * Resolve plugin header floors and capability gates for scaffold selections.
+ */
+export function resolveScaffoldCompatibilityPolicy(selections, { baseline = DEFAULT_SCAFFOLD_COMPATIBILITY, } = {}) {
+    const capabilityPlan = resolveAiFeatureCapabilityPlan(selections);
+    const requiresAtLeast = pickHigherVersionFloor(baseline.requiresAtLeast, capabilityPlan.hardMinimums.wordpress);
+    const requiresPhp = pickHigherVersionFloor(baseline.requiresPhp, capabilityPlan.hardMinimums.php);
+    const testedUpTo = pickHigherVersionFloor(baseline.testedUpTo, requiresAtLeast);
+    return {
+        capabilityPlan,
+        pluginHeader: {
+            requiresAtLeast,
+            requiresPhp,
+            testedUpTo,
+        },
+    };
+}
+/**
+ * Convert a resolved policy into workspace-inventory-safe JSON metadata.
+ */
+export function createScaffoldCompatibilityConfig(policy) {
+    const { capabilityPlan } = policy;
+    return {
+        hardMinimums: capabilityPlan.hardMinimums,
+        mode: getPolicyMode(capabilityPlan),
+        optionalFeatures: capabilityPlan.optionalFeatures.map((feature) => feature.label),
+        requiredFeatures: capabilityPlan.requiredFeatures.map((feature) => feature.label),
+        runtimeGates: [
+            ...capabilityPlan.requiredFeatures.flatMap(formatRuntimeGate),
+            ...capabilityPlan.optionalFeatures.flatMap(formatRuntimeGate),
+        ],
+    };
+}
+/**
+ * Render compatibility metadata as formatted TypeScript object literal JSON.
+ */
+export function renderScaffoldCompatibilityConfig(policy, indent = "\t\t") {
+    const config = createScaffoldCompatibilityConfig(policy);
+    return JSON.stringify(config, null, "\t")
+        .split("\n")
+        .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+        .join("\n");
+}
+function replacePluginHeaderVersionFloor(source, pattern, policyValue) {
+    return source.replace(pattern, (_match, prefix, currentValue, lineEnding) => {
+        const versionPrefix = prefix.endsWith(":") ? `${prefix} ` : prefix;
+        return `${versionPrefix}${pickHigherHeaderVersionFloor(policyValue, currentValue)}${lineEnding}`;
+    });
+}
+/**
+ * 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 function updatePluginHeaderCompatibility(source, policy) {
+    const { pluginHeader } = policy;
+    const nextSource = replacePluginHeaderVersionFloor(source, /(\* Requires at least:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresAtLeast);
+    const nextSourceWithTestedUpTo = replacePluginHeaderVersionFloor(nextSource, /(\* Tested up to:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.testedUpTo);
+    return replacePluginHeaderVersionFloor(nextSourceWithTestedUpTo, /(\* Requires PHP:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresPhp);
+}

package/dist/runtime/scaffold-template-variable-groups.d.ts

@@ -1,9 +1,11 @@
+import type { ScaffoldPluginHeaderCompatibility } from "./scaffold-compatibility.js";
 export declare const SCAFFOLD_TEMPLATE_VARIABLE_GROUPS: unique symbol;
 export type ScaffoldTemplateFamily = "basic" | "interactivity" | "persistence" | "compound" | "query-loop" | "external";
 export interface ScaffoldSharedTemplateVariableGroup {
     author: string;
     blockMetadataVersion: string;
     category: string;
+    compatibility: ScaffoldPluginHeaderCompatibility;
     cssClassName: string;
     description: string;
     descriptionJson: string;

package/dist/runtime/scaffold-template-variables.js

@@ -6,6 +6,7 @@ import { DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDe
 import { getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
 import { toPascalCase, toSnakeCase, } from './string-case.js';
 import { attachScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+import { resolveScaffoldCompatibilityPolicy } from "./scaffold-compatibility.js";
 /**
  * Build the normalized template variables used by scaffold rendering.
  *
@@ -58,6 +59,7 @@ export function getTemplateVariables(templateId, answers) {
     const persistencePolicy = templateId === 'persistence' || compoundPersistenceEnabled
         ? answers.persistencePolicy ?? 'authenticated'
         : 'authenticated';
+    const compatibility = resolveScaffoldCompatibilityPolicy([]);
     const flatVariables = {
         alternateRenderTargetsCsv: '',
         alternateRenderTargetsJson: '[]',
@@ -92,6 +94,8 @@ export function getTemplateVariables(templateId, answers) {
         hasAlternatePlainTextRenderTarget: 'false',
         hasAlternateRenderTargets: 'false',
         projectToolsPackageVersion,
+        requiresAtLeast: compatibility.pluginHeader.requiresAtLeast,
+        requiresPhp: compatibility.pluginHeader.requiresPhp,
         cssClassName,
         dataStorageMode,
         dashCase: slug,
@@ -118,6 +122,7 @@ export function getTemplateVariables(templateId, answers) {
         phpPrefix,
         phpPrefixUpper,
         restPackageVersion,
+        testedUpTo: compatibility.pluginHeader.testedUpTo,
         publicWriteRequestIdDeclaration: persistencePolicy === 'public'
             ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
             : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
@@ -162,6 +167,7 @@ export function getTemplateVariables(templateId, answers) {
             author: answers.author.trim(),
             blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
             category: metadataDefaults?.category ?? template?.defaultCategory ?? 'widgets',
+            compatibility: compatibility.pluginHeader,
             cssClassName,
             description,
             descriptionJson: JSON.stringify(description),

package/dist/runtime/scaffold.d.ts

@@ -58,6 +58,8 @@ export interface FlatScaffoldTemplateVariables extends Record<string, string> {
     hasAlternatePlainTextRenderTarget: "false" | "true";
     hasAlternateRenderTargets: "false" | "true";
     projectToolsPackageVersion: string;
+    requiresAtLeast: string;
+    requiresPhp: string;
     cssClassName: string;
     dashCase: string;
     dataStorageMode: DataStorageMode;
@@ -90,6 +92,7 @@ export interface FlatScaffoldTemplateVariables extends Record<string, string> {
     slugSnakeCase: string;
     textDomain: string;
     textdomain: string;
+    testedUpTo: string;
     title: string;
     titleJson: string;
     titleCase: string;