@wp-typia/project-tools 0.22.1 → 0.22.3

package/dist/runtime/cli-add-workspace-ability.js

@@ -1,788 +1,8 @@
-import fs from "node:fs";
-import { promises as fsp } from "node:fs";
-import path from "node:path";
-import { syncTypeSchemas } from "@wp-typia/block-runtime/metadata-core";
-import semver from "semver";
-import { appendWorkspaceInventoryEntries, readWorkspaceInventory, } from "./workspace-inventory.js";
+import { assertAbilityDoesNotExist, assertValidGeneratedSlug, normalizeBlockSlug, } from "./cli-add-shared.js";
+import { scaffoldAbilityWorkspace } from "./cli-add-workspace-ability-scaffold.js";
+import { readWorkspaceInventory } from "./workspace-inventory.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
-import { toPascalCase, toTitleCase } from "./string-case.js";
-import { escapeRegex, findPhpFunctionRange, hasPhpFunctionDefinition, quotePhpString, replacePhpFunctionDefinition, } from "./php-utils.js";
-import { assertAbilityDoesNotExist, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, patchFile, quoteTsString, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
-import { REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY, renderScaffoldCompatibilityConfig, resolveScaffoldCompatibilityPolicy, updatePluginHeaderCompatibility, } from "./scaffold-compatibility.js";
-import { DEFAULT_WORDPRESS_ABILITIES_VERSION, DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION, } from "./package-versions.js";
-const ABILITY_SERVER_GLOB = "/inc/abilities/*.php";
-const ABILITY_EDITOR_SCRIPT = "build/abilities/index.js";
-const ABILITY_EDITOR_ASSET = "build/abilities/index.asset.php";
-const ABILITY_REGISTRY_END_MARKER = "// wp-typia add ability entries end";
-const ABILITY_REGISTRY_START_MARKER = "// wp-typia add ability entries start";
-const WP_ABILITIES_SCRIPT_MODULE_ID = "@wordpress/abilities";
-const WP_CORE_ABILITIES_SCRIPT_MODULE_ID = "@wordpress/core-abilities";
-function resolveManagedDependencyVersion(existingVersion, requiredVersion) {
-    if (!existingVersion) {
-        return requiredVersion;
-    }
-    const existingMinimum = semver.minVersion(existingVersion);
-    const requiredMinimum = semver.minVersion(requiredVersion);
-    if (!existingMinimum || !requiredMinimum) {
-        return requiredVersion;
-    }
-    return semver.gte(existingMinimum, requiredMinimum)
-        ? existingVersion
-        : requiredVersion;
-}
-function toAbilityCategorySlug(workspaceNamespace) {
-    const normalizedNamespace = workspaceNamespace
-        .replace(/[^a-z0-9-]+/gu, "-")
-        .replace(/-{2,}/gu, "-")
-        .replace(/^-|-$/gu, "");
-    return `${normalizedNamespace || "workspace"}-workflows`;
-}
-function buildAbilityConfigEntry(abilitySlug, compatibilityPolicy) {
-    const pascalCase = toPascalCase(abilitySlug);
-    return [
-        "\t{",
-        `\t\tclientFile: ${quoteTsString(`src/abilities/${abilitySlug}/client.ts`)},`,
-        `\t\tcompatibility: ${renderScaffoldCompatibilityConfig(compatibilityPolicy)},`,
-        `\t\tconfigFile: ${quoteTsString(`src/abilities/${abilitySlug}/ability.config.json`)},`,
-        `\t\tdataFile: ${quoteTsString(`src/abilities/${abilitySlug}/data.ts`)},`,
-        `\t\tinputSchemaFile: ${quoteTsString(`src/abilities/${abilitySlug}/input.schema.json`)},`,
-        `\t\tinputTypeName: ${quoteTsString(`${pascalCase}AbilityInput`)},`,
-        `\t\toutputSchemaFile: ${quoteTsString(`src/abilities/${abilitySlug}/output.schema.json`)},`,
-        `\t\toutputTypeName: ${quoteTsString(`${pascalCase}AbilityOutput`)},`,
-        `\t\tphpFile: ${quoteTsString(`inc/abilities/${abilitySlug}.php`)},`,
-        `\t\tslug: ${quoteTsString(abilitySlug)},`,
-        `\t\ttypesFile: ${quoteTsString(`src/abilities/${abilitySlug}/types.ts`)},`,
-        "\t},",
-    ].join("\n");
-}
-function buildAbilityConfigSource(abilitySlug, workspaceNamespace) {
-    const abilityTitle = toTitleCase(abilitySlug);
-    return `${JSON.stringify({
-        abilityId: `${workspaceNamespace}/${abilitySlug}`,
-        category: {
-            description: `Typed editor and admin workflows exposed by the ${workspaceNamespace} workspace.`,
-            label: `${toTitleCase(workspaceNamespace)} Workflows`,
-            slug: toAbilityCategorySlug(workspaceNamespace),
-        },
-        description: `Runs the ${abilityTitle} workflow using a typed server callback.`,
-        label: abilityTitle,
-        meta: {
-            annotations: {
-                destructive: false,
-                idempotent: true,
-                readonly: false,
-            },
-            mcp: {
-                public: false,
-            },
-            showInRest: true,
-        },
-    }, null, 2)}\n`;
-}
-function buildAbilityTypesSource(abilitySlug) {
-    const pascalCase = toPascalCase(abilitySlug);
-    return `export interface ${pascalCase}AbilityInput {
-\tcontextId: number;
-\tnote?: string;
-}
-
-export interface ${pascalCase}AbilityOutput {
-\tprocessedContextId: number;
-\treceivedNote?: string;
-\tstatus: 'ready';
-\tsummary: string;
-}
-`;
-}
-function buildAbilityDataSource(abilitySlug) {
-    const pascalCase = toPascalCase(abilitySlug);
-    const abilityConstBase = abilitySlug
-        .toUpperCase()
-        .replace(/[^A-Z0-9]+/gu, "_")
-        .replace(/_{2,}/gu, "_")
-        .replace(/^_|_$/gu, "");
-    return `import {
-\texecuteAbility,
-\tgetAbilities,
-\tgetAbility as getRegisteredAbility,
-} from '@wordpress/abilities';
-import '@wordpress/core-abilities';
-
-import abilityConfig from './ability.config.json';
-
-import type { ${pascalCase}AbilityInput, ${pascalCase}AbilityOutput } from './types';
-
-interface WordPressAbilityDefinition {
-\tcategory?: string;
-\tdescription?: string;
-\tlabel?: string;
-\tmeta?: Record<string, unknown>;
-\tname?: string;
-}
-
-export const ${abilityConstBase}_ABILITY = abilityConfig;
-export const ${abilityConstBase}_ABILITY_CATEGORY = abilityConfig.category;
-export const ${abilityConstBase}_ABILITY_ID = abilityConfig.abilityId;
-export const ${abilityConstBase}_ABILITY_META = abilityConfig.meta;
-const ABILITY_DISCOVERY_POLL_INTERVAL_MS = 50;
-const ABILITY_DISCOVERY_TIMEOUT_MS = 5000;
-
-export type {
-\t${pascalCase}AbilityInput,
-\t${pascalCase}AbilityOutput,
-};
-
-function sleep( milliseconds: number ): Promise< void > {
-\treturn new Promise( ( resolve ) => {
-\t\tsetTimeout( resolve, milliseconds );
-\t} );
-}
-
-async function waitFor${pascalCase}AbilityRegistration(): Promise< void > {
-\tconst deadline = Date.now() + ABILITY_DISCOVERY_TIMEOUT_MS;
-\twhile ( ! getRegisteredAbility( ${abilityConstBase}_ABILITY_ID ) ) {
-\t\tif ( Date.now() >= deadline ) {
-\t\t\treturn;
-\t\t}
-
-\t\tawait sleep( ABILITY_DISCOVERY_POLL_INTERVAL_MS );
-\t}
-}
-
-export async function list${pascalCase}CategoryAbilities(): Promise< WordPressAbilityDefinition[] > {
-\tawait waitFor${pascalCase}AbilityRegistration();
-
-\treturn getAbilities( {
-\t\tcategory: ${abilityConstBase}_ABILITY_CATEGORY.slug,
-\t} ) as WordPressAbilityDefinition[];
-}
-
-export async function get${pascalCase}Ability(): Promise<
-\t| WordPressAbilityDefinition
-\t| undefined
-> {
-\tawait waitFor${pascalCase}AbilityRegistration();
-
-\treturn getRegisteredAbility( ${abilityConstBase}_ABILITY_ID ) as
-\t\t| WordPressAbilityDefinition
-\t\t| undefined;
-}
-
-export async function require${pascalCase}Ability(): Promise< WordPressAbilityDefinition > {
-\tconst ability = await get${pascalCase}Ability();
-\tif ( ability ) {
-\t\treturn ability;
-\t}
-
-\tthrow new Error(
-\t\t[
-\t\t\t\`Ability "\${ ${abilityConstBase}_ABILITY_ID }" is not available yet.\`,
-\t\t\t'Load the WordPress core abilities integration on this screen and confirm the server-side registration succeeded.',
-\t\t].join( ' ' )
-\t);
-}
-
-export async function run${pascalCase}Ability(
-\tinput: ${pascalCase}AbilityInput
-): Promise< ${pascalCase}AbilityOutput > {
-\tawait waitFor${pascalCase}AbilityRegistration();
-
-\treturn ( await executeAbility(
-\t\t${abilityConstBase}_ABILITY_ID,
-\t\tinput
-\t) ) as ${pascalCase}AbilityOutput;
-}
-`;
-}
-function buildAbilityClientSource(abilitySlug) {
-    const pascalCase = toPascalCase(abilitySlug);
-    return `/**
- * Re-export the typed ${pascalCase} ability client helpers.
- *
- * The helper methods load the WordPress core abilities integration and wait for
- * this server-registered ability before reading or executing it.
- */
-export * from './data';
-`;
-}
-function buildAbilitySyncScriptSource() {
-    return `/* eslint-disable no-console */
-import { syncTypeSchemas } from '@wp-typia/block-runtime/metadata-core';
-
-import {
-\tABILITIES,
-\ttype WorkspaceAbilityConfig,
-} from './block-config';
-
-function parseCliOptions( argv: string[] ) {
-\tconst options = {
-\t\tcheck: false,
-\t};
-
-\tfor ( const argument of argv ) {
-\t\tif ( argument === '--check' ) {
-\t\t\toptions.check = true;
-\t\t\tcontinue;
-\t\t}
-
-\t\tthrow new Error( \`Unknown sync-abilities flag: \${ argument }\` );
-\t}
-
-\treturn options;
-}
-
-function isWorkspaceAbility(
-\tability: WorkspaceAbilityConfig
-): ability is WorkspaceAbilityConfig & {
-\tclientFile: string;
-\tconfigFile: string;
-\tdataFile: string;
-\tinputSchemaFile: string;
-\tinputTypeName: string;
-\toutputSchemaFile: string;
-\toutputTypeName: string;
-\tphpFile: string;
-\ttypesFile: string;
-} {
-\treturn (
-\t\ttypeof ability.clientFile === 'string' &&
-\t\ttypeof ability.configFile === 'string' &&
-\t\ttypeof ability.dataFile === 'string' &&
-\t\ttypeof ability.inputSchemaFile === 'string' &&
-\t\ttypeof ability.inputTypeName === 'string' &&
-\t\ttypeof ability.outputSchemaFile === 'string' &&
-\t\ttypeof ability.outputTypeName === 'string' &&
-\t\ttypeof ability.phpFile === 'string' &&
-\t\ttypeof ability.typesFile === 'string'
-\t);
-}
-
-async function main() {
-\tconst options = parseCliOptions( process.argv.slice( 2 ) );
-\tconst abilities = ABILITIES.filter( isWorkspaceAbility );
-
-\tif ( ABILITIES.length > 0 && abilities.length === 0 ) {
-\t\tconsole.warn(
-\t\t\t'⚠️ Ability inventory entries exist, but none include the required typed schema files. Check scripts/block-config.ts before relying on sync-abilities.'
-\t\t);
-\t}
-
-\tif ( abilities.length === 0 ) {
-\t\tconsole.log(
-\t\t\toptions.check
-\t\t\t\t? 'ℹ️ No typed workflow abilities are registered yet. "sync-abilities --check" is already clean.'
-\t\t\t\t: 'ℹ️ No typed workflow abilities are registered yet.'
-\t\t);
-\t\treturn;
-\t}
-
-\tfor ( const ability of abilities ) {
-\t\tawait syncTypeSchemas(
-\t\t\t{
-\t\t\t\tjsonSchemaFile: ability.inputSchemaFile,
-\t\t\t\tprojectRoot: process.cwd(),
-\t\t\t\tsourceTypeName: ability.inputTypeName,
-\t\t\t\ttypesFile: ability.typesFile,
-\t\t\t},
-\t\t\t{
-\t\t\t\tcheck: options.check,
-\t\t\t}
-\t\t);
-
-\t\tawait syncTypeSchemas(
-\t\t\t{
-\t\t\t\tjsonSchemaFile: ability.outputSchemaFile,
-\t\t\t\tprojectRoot: process.cwd(),
-\t\t\t\tsourceTypeName: ability.outputTypeName,
-\t\t\t\ttypesFile: ability.typesFile,
-\t\t\t},
-\t\t\t{
-\t\t\t\tcheck: options.check,
-\t\t\t}
-\t\t);
-\t}
-
-\tconsole.log(
-\t\toptions.check
-\t\t\t? '✅ Ability input and output schemas are already up to date for all registered workflow abilities!'
-\t\t\t: '✅ Ability input and output schemas generated for all registered workflow abilities!'
-\t);
-}
-
-main().catch( ( error ) => {
-\tconsole.error( '❌ Ability schema sync failed:', error );
-\tprocess.exit( 1 );
-} );
-`;
-}
-function buildAbilityPhpSource(abilitySlug, workspace) {
-    const abilityTitle = toTitleCase(abilitySlug);
-    const abilityPhpId = abilitySlug.replace(/-/g, "_");
-    const categoryRegisterFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_register_ability_category`;
-    const abilityRegisterFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_register_ability`;
-    const configLoaderFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_load_ability_config`;
-    const schemaLoaderFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_load_ability_schema`;
-    const permissionFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_can_execute_ability`;
-    const executeFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_execute_ability`;
-    const metaFactoryFunctionName = `${workspace.workspace.phpPrefix}_${abilityPhpId}_build_ability_meta`;
-    return `<?php
-if ( ! defined( 'ABSPATH' ) ) {
-\treturn;
-}
-
-if ( ! function_exists( '${configLoaderFunctionName}' ) ) {
-\tfunction ${configLoaderFunctionName}() {
-\t\t$project_root = dirname( __DIR__, 2 );
-\t\t$config_path  = $project_root . '/src/abilities/${abilitySlug}/ability.config.json';
-\t\tif ( ! file_exists( $config_path ) ) {
-\t\t\treturn null;
-\t\t}
-
-\t\t$decoded = json_decode( file_get_contents( $config_path ), true );
-\t\treturn is_array( $decoded ) ? $decoded : null;
-\t}
-}
-
-if ( ! function_exists( '${schemaLoaderFunctionName}' ) ) {
-\tfunction ${schemaLoaderFunctionName}( $schema_name ) {
-\t\t$project_root = dirname( __DIR__, 2 );
-\t\t$schema_path  = $project_root . '/src/abilities/${abilitySlug}/' . $schema_name;
-\t\tif ( ! file_exists( $schema_path ) ) {
-\t\t\treturn null;
-\t\t}
-
-\t\t$decoded = json_decode( file_get_contents( $schema_path ), true );
-\t\treturn is_array( $decoded ) ? $decoded : null;
-\t}
-}
-
-if ( ! function_exists( '${metaFactoryFunctionName}' ) ) {
-\tfunction ${metaFactoryFunctionName}( array $config ) {
-\t\t$meta = array(
-\t\t\t'annotations' => isset( $config['meta']['annotations'] ) && is_array( $config['meta']['annotations'] )
-\t\t\t\t? $config['meta']['annotations']
-\t\t\t\t: array(
-\t\t\t\t\t'destructive' => false,
-\t\t\t\t\t'idempotent'  => true,
-\t\t\t\t\t'readonly'    => false,
-\t\t\t\t),
-\t\t\t'show_in_rest' => ! empty( $config['meta']['showInRest'] ),
-\t\t);
-
-\t\tif ( ! empty( $config['meta']['mcp']['public'] ) ) {
-\t\t\t$meta['mcp'] = array(
-\t\t\t\t'public' => true,
-\t\t\t);
-\t\t}
-
-\t\treturn $meta;
-\t}
-}
-
-if ( ! function_exists( '${permissionFunctionName}' ) ) {
-\tfunction ${permissionFunctionName}( $input = array() ) {
-\t\tunset( $input );
-
-\t\treturn current_user_can( 'edit_posts' );
-\t}
-}
-
-if ( ! function_exists( '${executeFunctionName}' ) ) {
-\tfunction ${executeFunctionName}( $input = array() ) {
-\t\t$payload = is_array( $input ) ? $input : array();
-\t\t$context_id = isset( $payload['contextId'] ) ? (int) $payload['contextId'] : 0;
-\t\t$note = isset( $payload['note'] ) && is_string( $payload['note'] )
-\t\t\t? trim( $payload['note'] )
-\t\t\t: '';
-\t\t$result = array(
-\t\t\t'processedContextId' => $context_id,
-\t\t\t'status'             => 'ready',
-\t\t\t'summary'            => sprintf(
-\t\t\t\t/* translators: 1: workflow title, 2: context id */
-\t\t\t\t__( '%1$s processed context %2$d.', ${quotePhpString(workspace.workspace.textDomain)} ),
-\t\t\t\t${quotePhpString(abilityTitle)},
-\t\t\t\t$context_id
-\t\t\t),
-\t\t);
-
-\t\tif ( '' !== $note ) {
-\t\t\t$result['receivedNote'] = $note;
-\t\t}
-
-\t\treturn $result;
-\t}
-}
-
-if ( ! function_exists( '${categoryRegisterFunctionName}' ) ) {
-\tfunction ${categoryRegisterFunctionName}() {
-\t\tif ( ! function_exists( 'wp_register_ability_category' ) ) {
-\t\t\treturn;
-\t\t}
-
-\t\t$config = ${configLoaderFunctionName}();
-\t\tif (
-\t\t\t! is_array( $config ) ||
-\t\t\tempty( $config['category']['slug'] ) ||
-\t\t\tempty( $config['category']['label'] )
-\t\t) {
-\t\t\treturn;
-\t\t}
-
-\t\twp_register_ability_category(
-\t\t\t(string) $config['category']['slug'],
-\t\t\tarray(
-\t\t\t\t'description' => isset( $config['category']['description'] ) && is_string( $config['category']['description'] )
-\t\t\t\t\t? $config['category']['description']
-\t\t\t\t\t: '',
-\t\t\t\t'label'       => (string) $config['category']['label'],
-\t\t\t)
-\t\t);
-\t}
-}
-
-if ( ! function_exists( '${abilityRegisterFunctionName}' ) ) {
-\tfunction ${abilityRegisterFunctionName}() {
-\t\tif ( ! function_exists( 'wp_register_ability' ) ) {
-\t\t\treturn;
-\t\t}
-
-\t\t$config = ${configLoaderFunctionName}();
-\t\tif (
-\t\t\t! is_array( $config ) ||
-\t\t\tempty( $config['abilityId'] ) ||
-\t\t\tempty( $config['category']['slug'] ) ||
-\t\t\tempty( $config['label'] ) ||
-\t\t\tempty( $config['description'] )
-\t\t) {
-\t\t\treturn;
-\t\t}
-
-\t\t$input_schema  = ${schemaLoaderFunctionName}( 'input.schema.json' );
-\t\t$output_schema = ${schemaLoaderFunctionName}( 'output.schema.json' );
-\t\tif ( ! is_array( $output_schema ) ) {
-\t\t\treturn;
-\t\t}
-
-\t\t$args = array(
-\t\t\t'category'            => (string) $config['category']['slug'],
-\t\t\t'description'         => (string) $config['description'],
-\t\t\t'execute_callback'    => ${quotePhpString(executeFunctionName)},
-\t\t\t'label'               => (string) $config['label'],
-\t\t\t'meta'                => ${metaFactoryFunctionName}( $config ),
-\t\t\t'output_schema'       => $output_schema,
-\t\t\t'permission_callback' => ${quotePhpString(permissionFunctionName)},
-\t\t);
-
-\t\tif ( is_array( $input_schema ) ) {
-\t\t\t$args['input_schema'] = $input_schema;
-\t\t}
-
-\t\twp_register_ability(
-\t\t\t(string) $config['abilityId'],
-\t\t\t$args
-\t\t);
-\t}
-}
-
-add_action( 'wp_abilities_api_categories_init', '${categoryRegisterFunctionName}' );
-add_action( 'wp_abilities_api_init', '${abilityRegisterFunctionName}' );
-`;
-}
-function buildAbilityRegistrySource(abilitySlugs) {
-    const exportLines = abilitySlugs
-        .map((abilitySlug) => `export * from './${abilitySlug}/client';`)
-        .join("\n");
-    return [
-        ABILITY_REGISTRY_START_MARKER,
-        exportLines,
-        ABILITY_REGISTRY_END_MARKER,
-    ]
-        .filter((line) => line.length > 0)
-        .join("\n")
-        .concat("\n");
-}
-function resolveAbilityRegistryPath(projectDir) {
-    const abilitiesDir = path.join(projectDir, "src", "abilities");
-    return [path.join(abilitiesDir, "index.ts"), path.join(abilitiesDir, "index.js")].find((candidatePath) => fs.existsSync(candidatePath)) ?? path.join(abilitiesDir, "index.ts");
-}
-function readAbilityRegistrySlugs(registryPath) {
-    if (!fs.existsSync(registryPath)) {
-        return [];
-    }
-    const source = fs.readFileSync(registryPath, "utf8");
-    return Array.from(source.matchAll(/^\s*export\s+\*\s+from\s+['"]\.\/([^/'"]+)\/client['"];?\s*$/gmu)).map((match) => match[1]);
-}
-async function writeAbilityRegistry(projectDir, abilitySlug) {
-    const abilitiesDir = path.join(projectDir, "src", "abilities");
-    const registryPath = resolveAbilityRegistryPath(projectDir);
-    await fsp.mkdir(abilitiesDir, { recursive: true });
-    const existingAbilitySlugs = readWorkspaceInventory(projectDir).abilities.map((entry) => entry.slug);
-    const existingRegistrySlugs = readAbilityRegistrySlugs(registryPath);
-    const nextAbilitySlugs = Array.from(new Set([...existingAbilitySlugs, ...existingRegistrySlugs, abilitySlug])).sort();
-    const generatedSection = buildAbilityRegistrySource(nextAbilitySlugs);
-    const existingSource = fs.existsSync(registryPath)
-        ? fs.readFileSync(registryPath, "utf8")
-        : "";
-    const generatedSectionPattern = new RegExp(`${escapeRegex(ABILITY_REGISTRY_START_MARKER)}[\\s\\S]*?${escapeRegex(ABILITY_REGISTRY_END_MARKER)}\\n?`, "u");
-    const nextSource = existingSource
-        ? generatedSectionPattern.test(existingSource)
-            ? existingSource.replace(generatedSectionPattern, generatedSection)
-            : `${existingSource.trimEnd()}\n\n${generatedSection}`
-        : generatedSection;
-    await fsp.writeFile(registryPath, nextSource, "utf8");
-}
-async function ensureAbilityBootstrapAnchors(workspace) {
-    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
-    await patchFile(bootstrapPath, (source) => {
-        let nextSource = source;
-        const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
-        const loadFunctionName = `${workspace.workspace.phpPrefix}_load_workflow_abilities`;
-        const enqueueFunctionName = `${workspace.workspace.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 loadFunction = `
-
-function ${loadFunctionName}() {
-\tforeach ( glob( __DIR__ . '${ABILITY_SERVER_GLOB}' ) ?: array() as $ability_module ) {
-\t\trequire_once $ability_module;
-\t}
-}
-`;
-        const enqueueFunction = `
-
-function ${enqueueFunctionName}() {
-\tif ( ! class_exists( 'WP_Ability' ) ) {
-\t\treturn;
-\t}
-
-\t$script_path = __DIR__ . '/${ABILITY_EDITOR_SCRIPT}';
-\t$asset_path  = __DIR__ . '/${ABILITY_EDITOR_ASSET}';
-
-\tif ( ! file_exists( $script_path ) || ! file_exists( $asset_path ) ) {
-\t\treturn;
-\t}
-
-\t$asset = require $asset_path;
-\tif ( ! is_array( $asset ) ) {
-\t\t$asset = array();
-\t}
-
-\t$dependencies = isset( $asset['dependencies'] ) && is_array( $asset['dependencies'] )
-\t\t? $asset['dependencies']
-\t\t: array();
-
-\tforeach ( array( '${WP_CORE_ABILITIES_SCRIPT_MODULE_ID}', '${WP_ABILITIES_SCRIPT_MODULE_ID}' ) as $ability_dependency ) {
-\t\t$has_dependency = false;
-\t\tforeach ( $dependencies as $dependency ) {
-\t\t\t$dependency_id = is_array( $dependency ) && isset( $dependency['id'] )
-\t\t\t\t? $dependency['id']
-\t\t\t\t: $dependency;
-\t\t\tif ( $dependency_id === $ability_dependency ) {
-\t\t\t\t$has_dependency = true;
-\t\t\t\tbreak;
-\t\t\t}
-\t\t}
-\t\tif ( ! $has_dependency ) {
-\t\t\t$dependencies[] = $ability_dependency;
-\t\t}
-\t}
-
-\tif ( ! function_exists( 'wp_enqueue_script_module' ) ) {
-\t\treturn;
-\t}
-
-\twp_enqueue_script_module(
-\t\t'${workspaceBaseName}-abilities',
-\t\tplugins_url( '${ABILITY_EDITOR_SCRIPT}', __FILE__ ),
-\t\t$dependencies,
-\t\tisset( $asset['version'] ) ? $asset['version'] : filemtime( $script_path )
-\t);
-}
-`;
-        const insertionAnchors = [
-            /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
-            /\?>\s*$/u,
-        ];
-        const insertPhpSnippet = (snippet) => {
-            for (const anchor of insertionAnchors) {
-                const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
-                if (candidate !== nextSource) {
-                    nextSource = candidate;
-                    return;
-                }
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
-        const appendPhpSnippet = (snippet) => {
-            const closingTagPattern = /\?>\s*$/u;
-            if (closingTagPattern.test(nextSource)) {
-                nextSource = nextSource.replace(closingTagPattern, `${snippet}\n?>`);
-                return;
-            }
-            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
-        };
-        if (!hasPhpFunctionDefinition(nextSource, loadFunctionName)) {
-            insertPhpSnippet(loadFunction);
-        }
-        if (!hasPhpFunctionDefinition(nextSource, enqueueFunctionName)) {
-            insertPhpSnippet(enqueueFunction);
-        }
-        else if (!findPhpFunctionRange(nextSource, enqueueFunctionName)?.source.includes("wp_enqueue_script_module")) {
-            nextSource =
-                replacePhpFunctionDefinition(nextSource, enqueueFunctionName, enqueueFunction, { trimReplacementStart: true }) ?? nextSource;
-        }
-        if (!nextSource.includes(loadHook)) {
-            appendPhpSnippet(loadHook);
-        }
-        if (!nextSource.includes(adminEnqueueHook)) {
-            appendPhpSnippet(adminEnqueueHook);
-        }
-        if (!nextSource.includes(editorEnqueueHook)) {
-            appendPhpSnippet(editorEnqueueHook);
-        }
-        return nextSource;
-    });
-}
-async function ensureAbilityPackageScripts(workspace) {
-    const packageJsonPath = path.join(workspace.projectDir, "package.json");
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    const nextScripts = {
-        ...(packageJson.scripts ?? {}),
-        "sync-abilities": packageJson.scripts?.["sync-abilities"] ?? "tsx scripts/sync-abilities.ts",
-    };
-    const nextDependencies = {
-        ...(packageJson.dependencies ?? {}),
-        [WP_ABILITIES_SCRIPT_MODULE_ID]: resolveManagedDependencyVersion(packageJson.dependencies?.[WP_ABILITIES_SCRIPT_MODULE_ID], DEFAULT_WORDPRESS_ABILITIES_VERSION),
-        [WP_CORE_ABILITIES_SCRIPT_MODULE_ID]: resolveManagedDependencyVersion(packageJson.dependencies?.[WP_CORE_ABILITIES_SCRIPT_MODULE_ID], DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION),
-    };
-    if (JSON.stringify(nextScripts) === JSON.stringify(packageJson.scripts ?? {}) &&
-        JSON.stringify(nextDependencies) === JSON.stringify(packageJson.dependencies ?? {})) {
-        return;
-    }
-    packageJson.scripts = nextScripts;
-    packageJson.dependencies = nextDependencies;
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
-}
-async function ensureAbilitySyncProjectAnchors(workspace) {
-    const syncProjectScriptPath = path.join(workspace.projectDir, "scripts", "sync-project.ts");
-    await patchFile(syncProjectScriptPath, (source) => {
-        let nextSource = source;
-        const syncRestConst = "const syncRestScriptPath = path.join( 'scripts', 'sync-rest-contracts.ts' );";
-        const syncAbilitiesConst = "const syncAbilitiesScriptPath = path.join( 'scripts', 'sync-abilities.ts' );";
-        const syncRestBlockPattern = /if \( fs\.existsSync\( path\.resolve\( process\.cwd\(\), syncRestScriptPath \) \) \) \{\n\s*runSyncScript\( syncRestScriptPath, options \);\n\s*\}/u;
-        const syncAbilitiesBlock = [
-            "if ( fs.existsSync( path.resolve( process.cwd(), syncAbilitiesScriptPath ) ) ) {",
-            "\trunSyncScript( syncAbilitiesScriptPath, options );",
-            "}",
-        ].join("\n");
-        if (!nextSource.includes(syncAbilitiesConst)) {
-            if (!nextSource.includes(syncRestConst)) {
-                throw new Error([
-                    `ensureAbilitySyncProjectAnchors could not patch ${path.basename(syncProjectScriptPath)}.`,
-                    "Missing the expected sync-rest script constant in scripts/sync-project.ts.",
-                    "Restore the generated template or wire sync-abilities manually before retrying.",
-                ].join(" "));
-            }
-            nextSource = nextSource.replace(syncRestConst, `${syncRestConst}\n${syncAbilitiesConst}`);
-        }
-        if (!nextSource.includes("runSyncScript( syncAbilitiesScriptPath, options );")) {
-            if (!syncRestBlockPattern.test(nextSource)) {
-                throw new Error([
-                    `ensureAbilitySyncProjectAnchors could not patch ${path.basename(syncProjectScriptPath)}.`,
-                    "Missing the expected sync-rest invocation block in scripts/sync-project.ts.",
-                    "Restore the generated template or wire sync-abilities manually before retrying.",
-                ].join(" "));
-            }
-            nextSource = nextSource.replace(syncRestBlockPattern, (match) => `${match}\n\n${syncAbilitiesBlock}`);
-        }
-        return nextSource;
-    });
-}
-async function ensureAbilityBuildScriptAnchors(workspace) {
-    const buildScriptPath = path.join(workspace.projectDir, "scripts", "build-workspace.mjs");
-    await patchFile(buildScriptPath, (source) => {
-        let nextSource = source;
-        if (/['"]src\/abilities\/index\.(?:ts|js)['"]/u.test(nextSource)) {
-            return nextSource;
-        }
-        const sharedEntriesPattern = /(for\s*\(\s*const\s+relativePath\s+of\s+\[)([\s\S]*?)(\]\s*\)\s*\{)/u;
-        const match = nextSource.match(sharedEntriesPattern);
-        if (!match ||
-            !match[2].includes("src/bindings/index.ts") ||
-            !match[2].includes("src/editor-plugins/index.ts")) {
-            throw new Error([
-                `ensureAbilityBuildScriptAnchors could not patch ${path.basename(buildScriptPath)}.`,
-                "Missing the expected shared editor entries array in scripts/build-workspace.mjs.",
-                "Restore the generated template or wire abilities/index manually before retrying.",
-            ].join(" "));
-        }
-        nextSource = nextSource.replace(sharedEntriesPattern, `$1
-\t\t'src/bindings/index.ts',
-\t\t'src/bindings/index.js',
-\t\t'src/editor-plugins/index.ts',
-\t\t'src/editor-plugins/index.js',
-\t\t'src/abilities/index.ts',
-\t\t'src/abilities/index.js',
-\t$3`);
-        return nextSource;
-    });
-}
-async function ensureAbilityWebpackAnchors(workspace) {
-    const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
-    await patchFile(webpackConfigPath, (source) => {
-        if (/['"]abilities\/index['"]/u.test(source)) {
-            return source;
-        }
-        const optionalModuleReturnPattern = /(function\s+getOptionalModuleEntries\s*\(\)\s*\{[\s\S]*?)(\n\treturn Object\.fromEntries\(\s*entries\s*\);\n\})/u;
-        if (optionalModuleReturnPattern.test(source)) {
-            return source.replace(optionalModuleReturnPattern, `$1
-
-\tfor ( const [ entryName, candidates ] of [
-\t\t[
-\t\t\t'abilities/index',
-\t\t\t[ 'src/abilities/index.ts', 'src/abilities/index.js' ],
-\t\t],
-\t] ) {
-\t\tfor ( const relativePath of candidates ) {
-\t\t\tconst entryPath = path.resolve( process.cwd(), relativePath );
-\t\t\tif ( ! fs.existsSync( entryPath ) ) {
-\t\t\t\tcontinue;
-\t\t\t}
-
-\t\t\tentries.push( [ entryName, entryPath ] );
-\t\t\tbreak;
-\t\t}
-\t}
-$2`);
-        }
-        const sharedEntriesPattern = /for\s*\(\s*const\s+\[\s*entryName\s*,\s*candidates\s*\]\s+of\s+\[([\s\S]*?)\]\s*\)\s*\{/u;
-        const match = source.match(sharedEntriesPattern);
-        if (!match ||
-            !match[1].includes("bindings/index") ||
-            !match[1].includes("editor-plugins/index")) {
-            throw new Error([
-                `ensureAbilityWebpackAnchors could not patch ${path.basename(webpackConfigPath)}.`,
-                "Missing the expected shared editor entries block in webpack.config.js.",
-                "Restore the generated template or wire abilities/index manually before retrying.",
-            ].join(" "));
-        }
-        return source.replace(sharedEntriesPattern, `for ( const [ entryName, candidates ] of [
-\t\t[
-\t\t\t'bindings/index',
-\t\t\t[ 'src/bindings/index.ts', 'src/bindings/index.js' ],
-\t\t],
-\t\t[
-\t\t\t'editor-plugins/index',
-\t\t\t[ 'src/editor-plugins/index.ts', 'src/editor-plugins/index.js' ],
-\t\t],
-\t\t[
-\t\t\t'abilities/index',
-\t\t\t[ 'src/abilities/index.ts', 'src/abilities/index.js' ],
-\t\t],
-\t] ) {`);
-    });
-}
+import { REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY, resolveScaffoldCompatibilityPolicy, } from "./scaffold-compatibility.js";
 /**
  * Add one typed workflow ability scaffold to an official workspace project.
  */
@@ -792,73 +12,13 @@ export async function runAddAbilityCommand({ abilityName, cwd = process.cwd(), }
     const inventory = readWorkspaceInventory(workspace.projectDir);
     assertAbilityDoesNotExist(workspace.projectDir, abilitySlug, inventory);
     const compatibilityPolicy = resolveScaffoldCompatibilityPolicy(REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY);
-    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
-    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
-    const buildScriptPath = path.join(workspace.projectDir, "scripts", "build-workspace.mjs");
-    const packageJsonPath = path.join(workspace.projectDir, "package.json");
-    const syncAbilitiesScriptPath = path.join(workspace.projectDir, "scripts", "sync-abilities.ts");
-    const syncProjectScriptPath = path.join(workspace.projectDir, "scripts", "sync-project.ts");
-    const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
-    const abilitiesIndexPath = resolveAbilityRegistryPath(workspace.projectDir);
-    const abilityDir = path.join(workspace.projectDir, "src", "abilities", abilitySlug);
-    const configFilePath = path.join(abilityDir, "ability.config.json");
-    const typesFilePath = path.join(abilityDir, "types.ts");
-    const dataFilePath = path.join(abilityDir, "data.ts");
-    const clientFilePath = path.join(abilityDir, "client.ts");
-    const phpFilePath = path.join(workspace.projectDir, "inc", "abilities", `${abilitySlug}.php`);
-    const mutationSnapshot = {
-        fileSources: await snapshotWorkspaceFiles([
-            blockConfigPath,
-            bootstrapPath,
-            buildScriptPath,
-            packageJsonPath,
-            syncAbilitiesScriptPath,
-            syncProjectScriptPath,
-            webpackConfigPath,
-            abilitiesIndexPath,
-        ]),
-        snapshotDirs: [],
-        targetPaths: [abilityDir, phpFilePath, syncAbilitiesScriptPath],
+    await scaffoldAbilityWorkspace({
+        abilitySlug,
+        compatibilityPolicy,
+        workspace,
+    });
+    return {
+        abilitySlug,
+        projectDir: workspace.projectDir,
     };
-    try {
-        await fsp.mkdir(abilityDir, { recursive: true });
-        await fsp.mkdir(path.dirname(phpFilePath), { recursive: true });
-        await ensureAbilityBootstrapAnchors(workspace);
-        await patchFile(bootstrapPath, (source) => updatePluginHeaderCompatibility(source, compatibilityPolicy));
-        await ensureAbilityPackageScripts(workspace);
-        await ensureAbilitySyncProjectAnchors(workspace);
-        await ensureAbilityBuildScriptAnchors(workspace);
-        await ensureAbilityWebpackAnchors(workspace);
-        await fsp.writeFile(syncAbilitiesScriptPath, buildAbilitySyncScriptSource(), "utf8");
-        await fsp.writeFile(configFilePath, buildAbilityConfigSource(abilitySlug, workspace.workspace.namespace), "utf8");
-        await fsp.writeFile(typesFilePath, buildAbilityTypesSource(abilitySlug), "utf8");
-        await fsp.writeFile(dataFilePath, buildAbilityDataSource(abilitySlug), "utf8");
-        await fsp.writeFile(clientFilePath, buildAbilityClientSource(abilitySlug), "utf8");
-        await fsp.writeFile(phpFilePath, buildAbilityPhpSource(abilitySlug, workspace), "utf8");
-        const pascalCase = toPascalCase(abilitySlug);
-        await syncTypeSchemas({
-            jsonSchemaFile: `src/abilities/${abilitySlug}/input.schema.json`,
-            projectRoot: workspace.projectDir,
-            sourceTypeName: `${pascalCase}AbilityInput`,
-            typesFile: `src/abilities/${abilitySlug}/types.ts`,
-        });
-        await syncTypeSchemas({
-            jsonSchemaFile: `src/abilities/${abilitySlug}/output.schema.json`,
-            projectRoot: workspace.projectDir,
-            sourceTypeName: `${pascalCase}AbilityOutput`,
-            typesFile: `src/abilities/${abilitySlug}/types.ts`,
-        });
-        await writeAbilityRegistry(workspace.projectDir, abilitySlug);
-        await appendWorkspaceInventoryEntries(workspace.projectDir, {
-            abilityEntries: [buildAbilityConfigEntry(abilitySlug, compatibilityPolicy)],
-        });
-        return {
-            abilitySlug,
-            projectDir: workspace.projectDir,
-        };
-    }
-    catch (error) {
-        await rollbackWorkspaceMutation(mutationSnapshot);
-        throw error;
-    }
 }