@wp-typia/project-tools 0.22.2 → 0.22.4

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

@@ -0,0 +1,64 @@
+/**
+ * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
+ */
+export const ADD_KIND_IDS = [
+    "admin-view",
+    "block",
+    "variation",
+    "style",
+    "transform",
+    "pattern",
+    "binding-source",
+    "rest-resource",
+    "ability",
+    "ai-feature",
+    "hooked-block",
+    "editor-plugin",
+];
+/**
+ * Supported plugin-level REST resource methods accepted by
+ * `wp-typia add rest-resource --methods`.
+ */
+export const REST_RESOURCE_METHOD_IDS = [
+    "list",
+    "read",
+    "create",
+    "update",
+    "delete",
+];
+/**
+ * Canonical editor-plugin shell surface ids accepted by
+ * `wp-typia add editor-plugin --slot`.
+ */
+export const EDITOR_PLUGIN_SLOT_IDS = ["sidebar", "document-setting-panel"];
+/**
+ * Legacy and canonical editor-plugin slot aliases keyed by user-facing input.
+ */
+export const EDITOR_PLUGIN_SLOT_ALIASES = {
+    PluginDocumentSettingPanel: "document-setting-panel",
+    PluginSidebar: "sidebar",
+    "document-setting-panel": "document-setting-panel",
+    sidebar: "sidebar",
+};
+/**
+ * Resolve a user-provided editor-plugin slot alias to its canonical id.
+ *
+ * @param slot Raw slot value from CLI input.
+ * @returns The canonical slot id, or `undefined` when unsupported.
+ */
+export function resolveEditorPluginSlotAlias(slot) {
+    const trimmed = slot.trim();
+    if (!Object.prototype.hasOwnProperty.call(EDITOR_PLUGIN_SLOT_ALIASES, trimmed)) {
+        return undefined;
+    }
+    return EDITOR_PLUGIN_SLOT_ALIASES[trimmed];
+}
+/**
+ * Supported built-in block families accepted by `wp-typia add block --template`.
+ */
+export const ADD_BLOCK_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "persistence",
+    "compound",
+];

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

@@ -0,0 +1,87 @@
+import { type HookedBlockPositionId } from "./hooked-blocks.js";
+import { type AddBlockTemplateId, type EditorPluginSlotId, type RestResourceMethodId } from "./cli-add-types.js";
+/**
+ * Namespace format accepted by plugin-level REST resources.
+ */
+export declare const REST_RESOURCE_NAMESPACE_PATTERN: RegExp;
+/**
+ * Validate a normalized workspace-generated slug.
+ *
+ * @param label Human-readable field label used in error messages.
+ * @param slug Normalized slug value to validate.
+ * @param usage CLI usage hint shown when the slug is empty.
+ * @returns The validated slug.
+ * @throws {Error} When the slug is empty or contains unsupported characters.
+ */
+export declare function assertValidGeneratedSlug(label: string, slug: string, usage: string): string;
+/**
+ * Validate a REST resource namespace.
+ *
+ * @param namespace Namespace candidate such as `vendor/v1`.
+ * @returns The trimmed namespace.
+ * @throws {Error} When the namespace is empty or not lowercase slash-separated.
+ */
+export declare function assertValidRestResourceNamespace(namespace: string): string;
+/**
+ * Resolve the effective REST resource namespace for a workspace.
+ *
+ * @param workspaceNamespace Default workspace namespace prefix.
+ * @param namespace Optional explicit namespace from CLI input.
+ * @returns A validated namespace, defaulting to `<workspaceNamespace>/v1`.
+ * @throws {Error} When the resolved namespace is invalid.
+ */
+export declare function resolveRestResourceNamespace(workspaceNamespace: string, namespace?: string): string;
+/**
+ * Parse and validate REST resource method ids from a comma-separated list.
+ *
+ * @param methods Optional comma-separated method list. Defaults to list, read, and create.
+ * @returns Deduplicated canonical REST resource method ids.
+ * @throws {Error} When any method is unsupported or the list is empty.
+ */
+export declare function assertValidRestResourceMethods(methods?: string): RestResourceMethodId[];
+/**
+ * Validate a hooked block insertion position.
+ *
+ * @param position Position candidate from CLI input.
+ * @returns The canonical hooked block position id.
+ * @throws {Error} When the position is not supported.
+ */
+export declare function assertValidHookedBlockPosition(position: string): HookedBlockPositionId;
+/**
+ * Build a PHP-safe workspace identifier prefix for a generated artifact.
+ *
+ * @param workspacePhpPrefix Workspace PHP prefix from project metadata.
+ * @param slug Generated artifact slug to append.
+ * @returns Snake-case PHP prefix for generated identifiers.
+ */
+export declare function buildWorkspacePhpPrefix(workspacePhpPrefix: string, slug: string): string;
+/**
+ * Check whether a value is a supported built-in add block template id.
+ *
+ * @param value Candidate template id from CLI input.
+ * @returns True when the value is an `AddBlockTemplateId`.
+ */
+export declare function isAddBlockTemplateId(value: string): value is AddBlockTemplateId;
+/**
+ * Quote a value for safe insertion into generated TypeScript source.
+ *
+ * @param value Raw string value.
+ * @returns JSON-escaped TypeScript string literal.
+ */
+export declare function quoteTsString(value: string): string;
+/**
+ * Validate a full block name used as a hooked block anchor.
+ *
+ * @param anchorBlockName Anchor block name from CLI input.
+ * @returns The trimmed full block name.
+ * @throws {Error} When the anchor is empty or not `namespace/slug`.
+ */
+export declare function assertValidHookAnchor(anchorBlockName: string): string;
+/**
+ * Validate and normalize the editor plugin shell slot.
+ *
+ * @param slot Optional shell slot. Defaults to `sidebar`.
+ * @returns The canonical editor plugin slot id.
+ * @throws {Error} When the slot is not supported by the workspace scaffold.
+ */
+export declare function assertValidEditorPluginSlot(slot?: string): EditorPluginSlotId;

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

@@ -0,0 +1,147 @@
+import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
+import { toSnakeCase, } from "./string-case.js";
+import { ADD_BLOCK_TEMPLATE_IDS, EDITOR_PLUGIN_SLOT_IDS, REST_RESOURCE_METHOD_IDS, resolveEditorPluginSlotAlias, } from "./cli-add-types.js";
+const WORKSPACE_GENERATED_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Namespace format accepted by plugin-level REST resources.
+ */
+export const REST_RESOURCE_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*(?:\/[a-z0-9-]+)+$/u;
+/**
+ * Validate a normalized workspace-generated slug.
+ *
+ * @param label Human-readable field label used in error messages.
+ * @param slug Normalized slug value to validate.
+ * @param usage CLI usage hint shown when the slug is empty.
+ * @returns The validated slug.
+ * @throws {Error} When the slug is empty or contains unsupported characters.
+ */
+export function assertValidGeneratedSlug(label, slug, usage) {
+    if (!slug) {
+        throw new Error(`${label} is required. Use \`${usage}\`.`);
+    }
+    if (!WORKSPACE_GENERATED_SLUG_PATTERN.test(slug)) {
+        throw new Error(`${label} must start with a letter and contain only lowercase letters, numbers, and hyphens.`);
+    }
+    return slug;
+}
+/**
+ * Validate a REST resource namespace.
+ *
+ * @param namespace Namespace candidate such as `vendor/v1`.
+ * @returns The trimmed namespace.
+ * @throws {Error} When the namespace is empty or not lowercase slash-separated.
+ */
+export function assertValidRestResourceNamespace(namespace) {
+    const trimmed = namespace.trim();
+    if (!trimmed) {
+        throw new Error("REST resource namespace is required. Use `--namespace <vendor/v1>` or let the workspace default apply.");
+    }
+    if (!REST_RESOURCE_NAMESPACE_PATTERN.test(trimmed)) {
+        throw new Error("REST resource namespace must use lowercase slash-separated segments like `demo-space/v1`.");
+    }
+    return trimmed;
+}
+/**
+ * Resolve the effective REST resource namespace for a workspace.
+ *
+ * @param workspaceNamespace Default workspace namespace prefix.
+ * @param namespace Optional explicit namespace from CLI input.
+ * @returns A validated namespace, defaulting to `<workspaceNamespace>/v1`.
+ * @throws {Error} When the resolved namespace is invalid.
+ */
+export function resolveRestResourceNamespace(workspaceNamespace, namespace) {
+    return assertValidRestResourceNamespace(namespace ?? `${workspaceNamespace}/v1`);
+}
+/**
+ * Parse and validate REST resource method ids from a comma-separated list.
+ *
+ * @param methods Optional comma-separated method list. Defaults to list, read, and create.
+ * @returns Deduplicated canonical REST resource method ids.
+ * @throws {Error} When any method is unsupported or the list is empty.
+ */
+export function assertValidRestResourceMethods(methods) {
+    const rawMethods = typeof methods === "string" && methods.trim().length > 0
+        ? methods.split(",").map((value) => value.trim()).filter(Boolean)
+        : ["list", "read", "create"];
+    const normalizedMethods = Array.from(new Set(rawMethods));
+    const invalidMethods = normalizedMethods.filter((method) => !REST_RESOURCE_METHOD_IDS.includes(method));
+    if (invalidMethods.length > 0) {
+        throw new Error(`REST resource methods must be a comma-separated list of: ${REST_RESOURCE_METHOD_IDS.join(", ")}.`);
+    }
+    if (normalizedMethods.length === 0) {
+        throw new Error(`REST resource methods must include at least one of: ${REST_RESOURCE_METHOD_IDS.join(", ")}.`);
+    }
+    return normalizedMethods;
+}
+/**
+ * Validate a hooked block insertion position.
+ *
+ * @param position Position candidate from CLI input.
+ * @returns The canonical hooked block position id.
+ * @throws {Error} When the position is not supported.
+ */
+export function assertValidHookedBlockPosition(position) {
+    if (HOOKED_BLOCK_POSITION_IDS.includes(position)) {
+        return position;
+    }
+    throw new Error(`Hook position must be one of: ${HOOKED_BLOCK_POSITION_IDS.join(", ")}.`);
+}
+/**
+ * Build a PHP-safe workspace identifier prefix for a generated artifact.
+ *
+ * @param workspacePhpPrefix Workspace PHP prefix from project metadata.
+ * @param slug Generated artifact slug to append.
+ * @returns Snake-case PHP prefix for generated identifiers.
+ */
+export function buildWorkspacePhpPrefix(workspacePhpPrefix, slug) {
+    return toSnakeCase(`${workspacePhpPrefix}_${slug}`);
+}
+/**
+ * Check whether a value is a supported built-in add block template id.
+ *
+ * @param value Candidate template id from CLI input.
+ * @returns True when the value is an `AddBlockTemplateId`.
+ */
+export function isAddBlockTemplateId(value) {
+    return ADD_BLOCK_TEMPLATE_IDS.includes(value);
+}
+/**
+ * Quote a value for safe insertion into generated TypeScript source.
+ *
+ * @param value Raw string value.
+ * @returns JSON-escaped TypeScript string literal.
+ */
+export function quoteTsString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Validate a full block name used as a hooked block anchor.
+ *
+ * @param anchorBlockName Anchor block name from CLI input.
+ * @returns The trimmed full block name.
+ * @throws {Error} When the anchor is empty or not `namespace/slug`.
+ */
+export function assertValidHookAnchor(anchorBlockName) {
+    const trimmed = anchorBlockName.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name>.");
+    }
+    if (!HOOKED_BLOCK_ANCHOR_PATTERN.test(trimmed)) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name> to use the full `namespace/slug` block name format.");
+    }
+    return trimmed;
+}
+/**
+ * Validate and normalize the editor plugin shell slot.
+ *
+ * @param slot Optional shell slot. Defaults to `sidebar`.
+ * @returns The canonical editor plugin slot id.
+ * @throws {Error} When the slot is not supported by the workspace scaffold.
+ */
+export function assertValidEditorPluginSlot(slot = "sidebar") {
+    const alias = resolveEditorPluginSlotAlias(slot);
+    if (alias) {
+        return alias;
+    }
+    throw new Error(`Editor plugin slot must be one of: ${EDITOR_PLUGIN_SLOT_IDS.join(", ")}. Legacy aliases: PluginSidebar, PluginDocumentSettingPanel.`);
+}

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

@@ -0,0 +1,5 @@
+import { type ScaffoldAbilityWorkspaceOptions } from "./cli-add-workspace-ability-types.js";
+/**
+ * Write generated workflow ability sources and patch shared workspace anchors.
+ */
+export declare function scaffoldAbilityWorkspace({ abilitySlug, compatibilityPolicy, workspace, }: ScaffoldAbilityWorkspaceOptions): Promise<void>;

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

@@ -0,0 +1,366 @@
+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 { buildAbilityClientSource, buildAbilityConfigEntry, buildAbilityConfigSource, buildAbilityDataSource, buildAbilityPhpSource, buildAbilityRegistrySource, buildAbilitySyncScriptSource, buildAbilityTypesSource, } from "./cli-add-workspace-ability-templates.js";
+import { ABILITY_EDITOR_ASSET, ABILITY_EDITOR_SCRIPT, ABILITY_REGISTRY_END_MARKER, ABILITY_REGISTRY_START_MARKER, ABILITY_SERVER_GLOB, WP_ABILITIES_SCRIPT_MODULE_ID, WP_CORE_ABILITIES_SCRIPT_MODULE_ID, } from "./cli-add-workspace-ability-types.js";
+import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
+import { appendPhpSnippetBeforeClosingTag, executeWorkspaceMutationPlan, insertPhpSnippetBeforeWorkspaceAnchors, } from "./cli-add-workspace-mutation.js";
+import { updatePluginHeaderCompatibility, } from "./scaffold-compatibility.js";
+import { DEFAULT_WORDPRESS_ABILITIES_VERSION, DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION, } from "./package-versions.js";
+import { escapeRegex, findPhpFunctionRange, hasPhpFunctionDefinition, replacePhpFunctionDefinition, } from "./php-utils.js";
+import { toPascalCase } from "./string-case.js";
+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 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);
+}
+`;
+        if (!hasPhpFunctionDefinition(nextSource, loadFunctionName)) {
+            nextSource = insertPhpSnippetBeforeWorkspaceAnchors(nextSource, loadFunction);
+        }
+        if (!hasPhpFunctionDefinition(nextSource, enqueueFunctionName)) {
+            nextSource = insertPhpSnippetBeforeWorkspaceAnchors(nextSource, enqueueFunction);
+        }
+        else if (!findPhpFunctionRange(nextSource, enqueueFunctionName)?.source.includes("wp_enqueue_script_module")) {
+            nextSource =
+                replacePhpFunctionDefinition(nextSource, enqueueFunctionName, enqueueFunction, { trimReplacementStart: true }) ?? nextSource;
+        }
+        if (!nextSource.includes(loadHook)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, loadHook);
+        }
+        if (!nextSource.includes(adminEnqueueHook)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, adminEnqueueHook);
+        }
+        if (!nextSource.includes(editorEnqueueHook)) {
+            nextSource = appendPhpSnippetBeforeClosingTag(nextSource, 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 ||
+            !/['"]src\/bindings\/index\.(?:ts|js)['"]/u.test(match[2]) ||
+            !/['"]src\/editor-plugins\/index\.(?:tsx|ts|js)['"]/u.test(match[2])) {
+            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, (fullMatch, sharedEntries) => {
+            const missingAbilityEntries = [
+                "'src/abilities/index.ts'",
+                "'src/abilities/index.js'",
+            ].filter((entry) => !sharedEntries.includes(entry));
+            if (missingAbilityEntries.length === 0) {
+                return fullMatch;
+            }
+            const itemIndent = sharedEntries.match(/\n([ \t]*)['"]/u)?.[1] ?? "\t\t";
+            const trimmedEntries = sharedEntries.replace(/\s*$/u, "");
+            const trailingWhitespace = sharedEntries.slice(trimmedEntries.length);
+            const separator = trimmedEntries.trimEnd().endsWith(",") ? "" : ",";
+            const nextEntries = `${trimmedEntries}${separator}` +
+                missingAbilityEntries.map((entry) => `\n${itemIndent}${entry},`).join("") +
+                trailingWhitespace;
+            return fullMatch.replace(sharedEntries, nextEntries);
+        });
+        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, (fullMatch, sharedEntries) => {
+            if (/['"]abilities\/index['"]/u.test(sharedEntries)) {
+                return fullMatch;
+            }
+            const tupleIndent = sharedEntries.match(/\n([ \t]*)\[/u)?.[1] ?? "\t\t";
+            const nestedIndent = `${tupleIndent}\t`;
+            const trimmedEntries = sharedEntries.replace(/\s*$/u, "");
+            const trailingWhitespace = sharedEntries.slice(trimmedEntries.length);
+            const separator = trimmedEntries.trimEnd().endsWith(",") ? "" : ",";
+            const abilityTuple = [
+                `${tupleIndent}[`,
+                `${nestedIndent}'abilities/index',`,
+                `${nestedIndent}[ 'src/abilities/index.ts', 'src/abilities/index.js' ],`,
+                `${tupleIndent}],`,
+            ].join("\n");
+            const nextEntries = `${trimmedEntries}${separator}\n${abilityTuple}` + trailingWhitespace;
+            return fullMatch.replace(sharedEntries, nextEntries);
+        });
+    });
+}
+/**
+ * Write generated workflow ability sources and patch shared workspace anchors.
+ */
+export async function scaffoldAbilityWorkspace({ abilitySlug, compatibilityPolicy, workspace, }) {
+    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`);
+    await executeWorkspaceMutationPlan({
+        filePaths: [
+            blockConfigPath,
+            bootstrapPath,
+            buildScriptPath,
+            packageJsonPath,
+            syncAbilitiesScriptPath,
+            syncProjectScriptPath,
+            webpackConfigPath,
+            abilitiesIndexPath,
+        ],
+        targetPaths: [abilityDir, phpFilePath, syncAbilitiesScriptPath],
+        run: async () => {
+            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),
+                ],
+            });
+        },
+    });
+}