@wp-typia/project-tools 0.19.3 → 0.20.0

package/dist/runtime/ai-feature-capability.js

@@ -0,0 +1,150 @@
+/** Canonical registry of AI-related features supported by wp-typia today. */
+export const AI_FEATURE_DEFINITIONS = {
+    wordpressAiClient: {
+        description: 'WordPress 7.0 AI Client surface used by AI-capable feature endpoints.',
+        id: 'wordpress-ai-client',
+        label: 'WordPress AI Client',
+        minimumVersions: {
+            wordpress: '7.0',
+        },
+        runtimeGates: [
+            {
+                kind: 'wordpress-core-feature',
+                value: 'WordPress AI Client',
+            },
+        ],
+    },
+    wordpressCoreAbilities: {
+        description: 'Client-side ability discovery surface for editor and admin flows.',
+        id: 'wordpress-core-abilities',
+        label: '@wordpress/core-abilities',
+        minimumVersions: {
+            wordpress: '7.0',
+        },
+        runtimeGates: [
+            {
+                kind: 'script-package',
+                value: '@wordpress/core-abilities',
+            },
+        ],
+    },
+    wordpressMcpPublicMetadata: {
+        description: 'Optional MCP exposure metadata consumed by a separate adapter path rather than core alone.',
+        id: 'wordpress-mcp-public-metadata',
+        label: 'MCP public metadata',
+        runtimeGates: [
+            {
+                kind: 'adapter',
+                value: 'MCP adapter',
+            },
+        ],
+    },
+    wordpressServerAbilities: {
+        description: 'Server-side ability registration and execution surface for WordPress-native abilities.',
+        id: 'wordpress-server-abilities',
+        label: 'WordPress Abilities API',
+        minimumVersions: {
+            wordpress: '6.9',
+        },
+        runtimeGates: [
+            {
+                kind: 'php-function',
+                value: 'wp_register_ability',
+            },
+            {
+                kind: 'php-function',
+                value: 'wp_register_ability_category',
+            },
+        ],
+    },
+};
+const DEFAULT_AI_FEATURE_REGISTRY = Object.values(AI_FEATURE_DEFINITIONS).reduce((accumulator, definition) => {
+    accumulator[definition.id] = definition;
+    return accumulator;
+}, {});
+function parseVersionFloorParts(value) {
+    return value.split('.').map((part, index) => {
+        if (!/^\d+$/.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;
+    }
+    if (!current) {
+        return candidate;
+    }
+    return compareVersionFloors(current, candidate) >= 0 ? current : candidate;
+}
+function normalizeSelections(selections) {
+    const normalized = new Map();
+    for (const selection of selections) {
+        const current = normalized.get(selection.featureId);
+        if (!current || selection.mode === 'required') {
+            normalized.set(selection.featureId, selection);
+        }
+    }
+    return [...normalized.values()];
+}
+/**
+ * Resolves a normalized AI feature capability plan from a list of selections.
+ *
+ * Required selections win when the same feature id appears multiple times, and
+ * the resulting hard minimum platform floor is computed from required features
+ * only.
+ *
+ * @param selections Desired feature selections for a scaffold or projection.
+ * @param registry Feature registry to resolve against. Defaults to the built-in registry.
+ * @returns The normalized capability plan plus required version floors.
+ * @throws When a selection references an unknown feature id.
+ */
+export function resolveAiFeatureCapabilityPlan(selections, registry = DEFAULT_AI_FEATURE_REGISTRY) {
+    const requiredFeatures = [];
+    const optionalFeatures = [];
+    let wordpress;
+    let php;
+    for (const selection of normalizeSelections(selections)) {
+        const definition = registry[selection.featureId];
+        if (!definition) {
+            throw new Error(`Unknown AI feature capability "${selection.featureId}".`);
+        }
+        const resolvedDefinition = {
+            ...definition,
+            mode: selection.mode,
+        };
+        if (selection.mode === 'required') {
+            requiredFeatures.push(resolvedDefinition);
+            wordpress = pickHigherVersionFloor(wordpress, definition.minimumVersions?.wordpress);
+            php = pickHigherVersionFloor(php, definition.minimumVersions?.php);
+            continue;
+        }
+        optionalFeatures.push(resolvedDefinition);
+    }
+    return {
+        hardMinimums: {
+            ...(php ? { php } : {}),
+            ...(wordpress ? { wordpress } : {}),
+        },
+        optionalFeatures,
+        requiredFeatures,
+    };
+}

package/dist/runtime/block-generator-service-spec.js

@@ -5,6 +5,7 @@ import { DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDe
 import { getTemplateById, } from "./template-registry.js";
 import { toPascalCase, toSnakeCase, } from "./string-case.js";
 import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from "./scaffold-identifiers.js";
+import { resolveScaffoldCompatibilityPolicy } from "./scaffold-compatibility.js";
 import { attachScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 function getBuiltInPersistenceSpec({ templateId, dataStorageMode, persistencePolicy, }) {
     if (templateId === "persistence") {
@@ -122,6 +123,7 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
         ? spec.persistence.persistencePolicy
         : "authenticated";
     const queryVariationNamespace = `${namespace}/${slug}`;
+    const compatibility = resolveScaffoldCompatibilityPolicy([]);
     const flatVariables = {
         alternateRenderTargetsCsv: formatAlternateRenderTargets(alternateRenderTargets),
         alternateRenderTargetsJson: JSON.stringify(alternateRenderTargets),
@@ -161,6 +163,9 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
         hasAlternateRenderTargets: alternateRenderTargets.length > 0
             ? "true"
             : "false",
+        requiresAtLeast: compatibility.pluginHeader.requiresAtLeast,
+        requiresPhp: compatibility.pluginHeader.requiresPhp,
+        testedUpTo: compatibility.pluginHeader.testedUpTo,
         projectToolsPackageVersion,
         cssClassName,
         dashCase: slug,
@@ -211,6 +216,7 @@ export function buildTemplateVariablesFromBlockSpec(spec) {
         author: spec.project.author,
         blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
         category: spec.metadata.category,
+        compatibility: compatibility.pluginHeader,
         cssClassName,
         description: spec.metadata.description,
         descriptionJson: flatVariables.descriptionJson,

package/dist/runtime/cli-add-shared.d.ts

@@ -5,7 +5,7 @@ export { normalizeBlockSlug, } from "./scaffold-identifiers.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
-export declare const ADD_KIND_IDS: readonly ["block", "variation", "pattern", "binding-source", "rest-resource", "hooked-block", "editor-plugin"];
+export declare const ADD_KIND_IDS: readonly ["block", "variation", "pattern", "binding-source", "rest-resource", "ability", "ai-feature", "hooked-block", "editor-plugin"];
 export type AddKindId = (typeof ADD_KIND_IDS)[number];
 /**
  * Supported plugin-level REST resource methods accepted by
@@ -43,6 +43,23 @@ export interface RunAddRestResourceCommandOptions {
     namespace?: string;
     restResourceName: string;
 }
+/**
+ * Options for `wp-typia add ability`.
+ *
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @property abilityName Human-entered workflow ability name that will be
+ * normalized into the generated slug.
+ */
+export interface RunAddAbilityCommandOptions {
+    abilityName: string;
+    cwd?: string;
+}
+export interface RunAddAiFeatureCommandOptions {
+    aiFeatureName: string;
+    cwd?: string;
+    namespace?: string;
+}
 export interface RunAddHookedBlockCommandOptions {
     anchorBlockName: string;
     blockName: string;
@@ -140,6 +157,20 @@ export declare function assertVariationDoesNotExist(projectDir: string, blockSlu
 export declare function assertPatternDoesNotExist(projectDir: string, patternSlug: string, inventory: WorkspaceInventory): void;
 export declare function assertBindingSourceDoesNotExist(projectDir: string, bindingSourceSlug: string, inventory: WorkspaceInventory): void;
 export declare function assertRestResourceDoesNotExist(projectDir: string, restResourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a workflow ability scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * The check covers the generated `src/abilities/<slug>` directory,
+ * `inc/abilities/<slug>.php`, and any matching `inventory.abilities` entry.
+ *
+ * @param projectDir Workspace root directory.
+ * @param abilitySlug Normalized workflow ability slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the ability directory, PHP bootstrap, or inventory entry already exists.
+ */
+export declare function assertAbilityDoesNotExist(projectDir: string, abilitySlug: string, inventory: WorkspaceInventory): void;
+export declare function assertAiFeatureDoesNotExist(projectDir: string, aiFeatureSlug: string, inventory: WorkspaceInventory): void;
 /**
  * Ensure an editor plugin scaffold does not already exist on disk or in the
  * workspace inventory.

package/dist/runtime/cli-add-shared.js

@@ -15,6 +15,8 @@ export const ADD_KIND_IDS = [
     "pattern",
     "binding-source",
     "rest-resource",
+    "ability",
+    "ai-feature",
     "hooked-block",
     "editor-plugin",
 ];
@@ -254,6 +256,44 @@ export function assertRestResourceDoesNotExist(projectDir, restResourceSlug, inv
         throw new Error(`A REST resource inventory entry already exists for ${restResourceSlug}. Choose a different name.`);
     }
 }
+/**
+ * Ensure a workflow ability scaffold does not already exist on disk or in the
+ * workspace inventory.
+ *
+ * The check covers the generated `src/abilities/<slug>` directory,
+ * `inc/abilities/<slug>.php`, and any matching `inventory.abilities` entry.
+ *
+ * @param projectDir Workspace root directory.
+ * @param abilitySlug Normalized workflow ability slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the ability directory, PHP bootstrap, or inventory entry already exists.
+ */
+export function assertAbilityDoesNotExist(projectDir, abilitySlug, inventory) {
+    const abilityDir = path.join(projectDir, "src", "abilities", abilitySlug);
+    const abilityPhpPath = path.join(projectDir, "inc", "abilities", `${abilitySlug}.php`);
+    if (fs.existsSync(abilityDir)) {
+        throw new Error(`An ability scaffold already exists at ${path.relative(projectDir, abilityDir)}. Choose a different name.`);
+    }
+    if (fs.existsSync(abilityPhpPath)) {
+        throw new Error(`An ability bootstrap already exists at ${path.relative(projectDir, abilityPhpPath)}. Choose a different name.`);
+    }
+    if (inventory.abilities.some((entry) => entry.slug === abilitySlug)) {
+        throw new Error(`An ability inventory entry already exists for ${abilitySlug}. Choose a different name.`);
+    }
+}
+export function assertAiFeatureDoesNotExist(projectDir, aiFeatureSlug, inventory) {
+    const aiFeatureDir = path.join(projectDir, "src", "ai-features", aiFeatureSlug);
+    const aiFeaturePhpPath = path.join(projectDir, "inc", "ai-features", `${aiFeatureSlug}.php`);
+    if (fs.existsSync(aiFeatureDir)) {
+        throw new Error(`An AI feature already exists at ${path.relative(projectDir, aiFeatureDir)}. Choose a different name.`);
+    }
+    if (fs.existsSync(aiFeaturePhpPath)) {
+        throw new Error(`An AI feature bootstrap already exists at ${path.relative(projectDir, aiFeaturePhpPath)}. Choose a different name.`);
+    }
+    if (inventory.aiFeatures.some((entry) => entry.slug === aiFeatureSlug)) {
+        throw new Error(`An AI feature inventory entry already exists for ${aiFeatureSlug}. Choose a different name.`);
+    }
+}
 /**
  * Ensure an editor plugin scaffold does not already exist on disk or in the
  * workspace inventory.
@@ -282,6 +322,8 @@ export function formatAddHelpText() {
   wp-typia add pattern <name> [--dry-run]
   wp-typia add binding-source <name> [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create,update,delete>] [--dry-run]
+  wp-typia add ability <name> [--dry-run]
+  wp-typia add ai-feature <name> [--namespace <vendor/v1>] [--dry-run]
   wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}> [--dry-run]
   wp-typia add editor-plugin <name> [--slot <${EDITOR_PLUGIN_SLOT_IDS.join("|")}>] [--dry-run]
 
@@ -293,6 +335,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 hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
   \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`.`;
 }

package/dist/runtime/cli-add-workspace-ability.d.ts

@@ -0,0 +1,8 @@
+import { type RunAddAbilityCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one typed workflow ability scaffold to an official workspace project.
+ */
+export declare function runAddAbilityCommand({ abilityName, cwd, }: RunAddAbilityCommandOptions): Promise<{
+    abilitySlug: string;
+    projectDir: string;
+}>;