@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -8,15 +8,17 @@ export function formatAddHelpText() {
     return `Usage:
   wp-typia add admin-view <name> [--source <rest-resource:slug|core-data:kind/name>] [--dry-run]
   wp-typia add block <name> [--template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}>] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--dry-run]
-  wp-typia add integration-env <name> [--wp-env] [--service <none|docker-compose>] [--dry-run]
-  wp-typia add variation <name> --block <block-slug> [--dry-run]
-  wp-typia add style <name> --block <block-slug> [--dry-run]
-  wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug> [--dry-run]
-  wp-typia add pattern <name> [--dry-run]
-  wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--dry-run]
+  wp-typia add integration-env <name> [--wp-env] [--release-zip] [--service <none|docker-compose>] [--dry-run]
+  wp-typia add core-variation <block-name> <name> [--dry-run]
+  wp-typia add core-variation <name> --block <namespace/block> [--dry-run]
+	wp-typia add variation <name> --block <block-slug> [--dry-run]
+	wp-typia add style <name> --block <block-slug> [--dry-run]
+	wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug> [--dry-run]
+  wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--tags <tag,...>] [--thumbnail-url <url>] [--dry-run]
+  wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--from-post-meta|--post-meta <post-meta> [--meta-path <field>]] [--dry-run]
   wp-typia add contract <name> [--type <ExportedTypeName>] [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <${REST_RESOURCE_METHOD_IDS.join(",")}>] [--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--dry-run]
-  wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--dry-run]
+  wp-typia add rest-resource <name> --manual [--namespace <vendor/v1>] [--method <GET|POST|PUT|PATCH|DELETE>] [--auth <public|authenticated|public-write-protected>] [--path <route-pattern>|--route-pattern <route-pattern>] [--permission-callback <callback>] [--controller-class <ClassName>] [--controller-extends <BaseClass>] [--query-type <Type>] [--body-type <Type>] [--response-type <Type>] [--secret-field <field>] [--secret-state-field|--secret-has-value-field <field>] [--secret-preserve-on-empty <true|false>] [--dry-run]
   wp-typia add post-meta <name> --post-type <post-type> [--type <ExportedTypeName>] [--meta-key <meta-key>] [--hide-from-rest] [--dry-run]
   wp-typia add ability <name> [--dry-run]
   wp-typia add ai-feature <name> [--namespace <vendor/v1>] [--dry-run]
@@ -27,21 +29,23 @@ Notes:
   \`wp-typia add\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces scaffolded via \`wp-typia create <project-dir> --template workspace\`.
   Pass \`--dry-run\` to preview the workspace files that would change without writing them.
   Interactive add flows let you choose a template when \`--template\` is omitted; non-interactive runs default to \`basic\`.
+  \`add core-variation\` registers editor-side variations for existing core or external blocks without generating block.json or Typia manifests.
   \`add admin-view\` scaffolds an opt-in DataViews-powered WordPress admin screen under \`src/admin-views/\`.
   Pass \`--source rest-resource:<slug>\` to reuse a list-capable REST resource.
   Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
   Generated admin-view workspaces add \`@wp-typia/dataviews\` and the needed WordPress DataViews packages as opt-in dependencies.
   \`add integration-env\` generates an opt-in local smoke starter under \`scripts/integration-smoke/\`, updates \`.env.example\`, and can add \`@wordpress/env\` plus \`.wp-env.json\` when \`--wp-env\` is passed.
+  Pass \`--release-zip\` to add \`release:zip\`, \`release:zip:check\`, and \`qa:check\` scripts for plugin QA packaging.
   Pass \`--service docker-compose\` to include a placeholder local service stack that can be adapted to project-specific dependencies.
   \`query-loop\` is a create-time scaffold family. Use \`wp-typia create <project-dir> --template query-loop\` instead of \`wp-typia add block\`.
   \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
   \`add style\` registers a Block Styles option for an existing generated block.
   \`add transform\` adds a block-to-block transform into an existing generated block.
-  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
-  \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare an end-to-end bindable attribute on an existing generated block.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/full/\` or \`src/patterns/sections/\` and records typed catalog metadata in \`PATTERNS\`.
+  \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`; pass \`--block\` and \`--attribute\` together to declare an end-to-end bindable attribute on an existing generated block. Pass \`--from-post-meta\` or \`--post-meta\` to generate a source backed by a typed post-meta contract; \`--meta-path\` selects one top-level field as the default binding arg.
   \`add contract\` registers a standalone TypeScript wire contract under \`src/contracts/\` and generates a stable JSON Schema artifact without creating PHP route glue.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`. Use \`--route-pattern\`, \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` when an existing WordPress controller or permission model needs to own part of the generated route surface.
-  Pass \`--manual\` with \`add rest-resource\` to track an external REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files.
+  Pass \`--manual\` with \`add rest-resource\` to track an external/provider REST route with typed schemas, OpenAPI, clients, and drift checks without generating PHP route/controller files. Manual routes may still declare \`--permission-callback\`, \`--controller-class\`, and \`--controller-extends\` as metadata for the route owner. Settings contracts can add \`--secret-field\` with \`--secret-preserve-on-empty\` metadata so generated schemas, clients, and admin forms treat blank secret submissions as preserve-by-default.
   \`add post-meta\` scaffolds a typed post meta contract under \`src/post-meta/\`, generates a schema artifact, and wires \`register_post_meta()\` helpers under \`inc/post-meta/\`.
   \`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/\`.

package/dist/runtime/cli-add-kind-ids.d.ts

@@ -4,7 +4,7 @@
  *
  * Keep this order stable because it drives help output and command metadata.
  */
-export declare const ADD_KIND_IDS: readonly ["admin-view", "block", "integration-env", "variation", "style", "transform", "pattern", "binding-source", "contract", "rest-resource", "post-meta", "ability", "ai-feature", "hooked-block", "editor-plugin"];
+export declare const ADD_KIND_IDS: readonly ["admin-view", "block", "integration-env", "core-variation", "variation", "style", "transform", "pattern", "binding-source", "contract", "rest-resource", "post-meta", "ability", "ai-feature", "hooked-block", "editor-plugin"];
 /**
  * Union of supported top-level `wp-typia add` kind ids.
  */

package/dist/runtime/cli-add-kind-ids.js

@@ -8,6 +8,7 @@ export const ADD_KIND_IDS = [
     "admin-view",
     "block",
     "integration-env",
+    "core-variation",
     "variation",
     "style",
     "transform",

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

@@ -1,5 +1,8 @@
+import { PATTERN_CATALOG_SCOPE_IDS, type PatternCatalogScope } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
 export type { AddKindId } from "./cli-add-kind-ids.js";
+export { PATTERN_CATALOG_SCOPE_IDS };
+export type { PatternCatalogScope };
 /**
  * Supported plugin-level REST resource methods accepted by
  * `wp-typia add rest-resource --methods`.
@@ -87,6 +90,18 @@ export interface RunAddVariationCommandOptions {
     cwd?: string;
     variationName: string;
 }
+/**
+ * Options for `wp-typia add core-variation`.
+ *
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property targetBlockName Full `namespace/block` name that receives the variation.
+ * @property variationName Human-entered variation name normalized into a slug.
+ */
+export interface RunAddCoreVariationCommandOptions {
+    cwd?: string;
+    targetBlockName: string;
+    variationName: string;
+}
 /**
  * Options for `wp-typia add style`.
  *
@@ -126,8 +141,14 @@ export interface RunAddBlockTransformCommandOptions {
  * @property patternName Human-entered pattern name normalized into a slug.
  */
 export interface RunAddPatternCommandOptions {
+    catalogTitle?: string;
+    contentFile?: string;
     cwd?: string;
     patternName: string;
+    patternScope?: PatternCatalogScope | string;
+    sectionRole?: string;
+    tags?: readonly string[] | string;
+    thumbnailUrl?: string;
 }
 /**
  * Options for `wp-typia add binding-source`.
@@ -136,12 +157,18 @@ export interface RunAddPatternCommandOptions {
  * @property blockName Optional existing workspace block slug or full block name.
  * @property bindingSourceName Human-entered binding source name normalized into a slug.
  * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property metaPath Optional top-level post-meta field used as the default
+ * source argument when `postMetaName` is provided.
+ * @property postMetaName Optional generated post-meta contract slug used to
+ * back the binding source with `get_post_meta()`.
  */
 export interface RunAddBindingSourceCommandOptions {
     attributeName?: string;
     blockName?: string;
     bindingSourceName: string;
     cwd?: string;
+    metaPath?: string;
+    postMetaName?: string;
 }
 /**
  * Options for `wp-typia add contract`.
@@ -189,17 +216,17 @@ export interface RunAddPostMetaCommandOptions {
  * @property auth Optional auth intent for manual mode. Defaults to public.
  * @property bodyTypeName Optional exported TypeScript body type for manual
  * mode. Defaults to `<PascalName>Request` for write methods.
- * @property controllerClass Optional generated REST controller class reference.
- * When present, route callbacks delegate through an instantiated controller.
+ * @property controllerClass Optional REST controller class reference. Generated
+ * routes delegate through it; manual/provider routes record it as owner metadata.
  * @property controllerExtends Optional base class for the generated controller
- * wrapper when `controllerClass` is a global class name.
+ * wrapper or declared manual/provider controller owner.
  * @property cwd Working directory used to resolve the nearest official workspace.
  * @property manual Whether to scaffold a type-only external REST contract.
  * @property method HTTP method for manual REST contract mode. Defaults to GET.
  * @property methods Optional comma-separated REST method list.
  * @property namespace Optional REST namespace, defaulting to the workspace namespace.
  * @property permissionCallback Optional PHP callback used for generated REST
- * route permission checks.
+ * route permission checks or declared manual/provider route ownership.
  * @property pathPattern Route path pattern for manual mode, relative to the
  * namespace. Defaults to `/<name>`.
  * @property queryTypeName Optional exported TypeScript query type for manual
@@ -207,10 +234,17 @@ export interface RunAddPostMetaCommandOptions {
  * @property restResourceName Human-entered resource name normalized into a slug.
  * @property responseTypeName Optional exported TypeScript response type for
  * manual mode. Defaults to `<PascalName>Response`.
- * @property routePattern Optional generated item route pattern, relative to the
- * namespace. Defaults to `/<name>/item`.
+ * @property routePattern Optional generated item route pattern, or manual
+ * provider-route alias for `pathPattern`, relative to the namespace.
+ * Generated mode defaults to `/<name>/item`; manual mode defaults to `/<name>`.
  * @property secretFieldName Optional write-only secret field name for manual
  * settings contracts. Requires a request body.
+ * @property secretHasValueFieldName Optional alias for `secretStateFieldName`
+ * when the response field is a safe presence indicator.
+ * @property secretMaskedResponseFieldName Optional alias for
+ * `secretStateFieldName` when the response field represents masked state.
+ * @property secretPreserveOnEmpty Whether blank secret submissions should
+ * preserve the existing value. Defaults to true when `secretFieldName` is set.
  * @property secretStateFieldName Optional masked response boolean field for
  * `secretFieldName`. Defaults to `has<PascalSecretField>`.
  */
@@ -231,6 +265,9 @@ export interface RunAddRestResourceCommandOptions {
     responseTypeName?: string;
     routePattern?: string;
     secretFieldName?: string;
+    secretHasValueFieldName?: string;
+    secretMaskedResponseFieldName?: string;
+    secretPreserveOnEmpty?: boolean;
     secretStateFieldName?: string;
 }
 /**
@@ -310,12 +347,14 @@ export interface RunAddEditorPluginCommandOptions {
  * @property integrationEnvName Human-entered environment name that will be
  * normalized into script and documentation paths.
  * @property service Optional local service starter. Defaults to `none`.
+ * @property withReleaseZip Whether to add release zip packaging scripts.
  * @property withWpEnv Whether to add a local `@wordpress/env` preset and scripts.
  */
 export interface RunAddIntegrationEnvCommandOptions {
     cwd?: string;
     integrationEnvName: string;
     service?: string;
+    withReleaseZip?: boolean;
     withWpEnv?: boolean;
 }
 /**

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

@@ -1,5 +1,7 @@
 import { suggestCloseId } from "./id-suggestions.js";
+import { PATTERN_CATALOG_SCOPE_IDS, } from "./pattern-catalog.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
+export { PATTERN_CATALOG_SCOPE_IDS };
 /**
  * Supported plugin-level REST resource methods accepted by
  * `wp-typia add rest-resource --methods`.

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

@@ -110,6 +110,13 @@ export declare function assertValidManualRestContractAuth(auth?: string): Manual
  * @returns True when the pattern has no regex groups or uses only `(?P<id>...)`.
  */
 export declare function isGeneratedRestResourceRoutePatternCompatible(routePattern: string): boolean;
+/**
+ * Collect unique WordPress named capture parameters from a REST route pattern.
+ *
+ * @param routePattern Route pattern relative to the namespace.
+ * @returns Capture names in first-seen order.
+ */
+export declare function collectRestRouteNamedCaptureNames(routePattern: string): string[];
 export declare function resolveManualRestContractPathPattern(slug: string, pathPattern?: string): string;
 /**
  * Normalize and validate a generated REST resource item route pattern.

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

@@ -332,6 +332,15 @@ export function isGeneratedRestResourceRoutePatternCompatible(routePattern) {
     return (!hasUnsupportedCapture &&
         (!hasRegexGroup || (namedCaptures.length === 1 && namedCaptures[0] === "id")));
 }
+/**
+ * Collect unique WordPress named capture parameters from a REST route pattern.
+ *
+ * @param routePattern Route pattern relative to the namespace.
+ * @returns Capture names in first-seen order.
+ */
+export function collectRestRouteNamedCaptureNames(routePattern) {
+    return Array.from(new Set(Array.from(routePattern.matchAll(REST_ROUTE_NAMED_CAPTURE_PATTERN), (match) => match[1])));
+}
 export function resolveManualRestContractPathPattern(slug, pathPattern) {
     return resolveRestRoutePathPattern({
         defaultPath: `/${slug}`,

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

@@ -0,0 +1,24 @@
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Ensure the workspace bootstrap loads generated ability PHP modules and
+ * enqueues the generated ability editor script module.
+ */
+export declare function ensureAbilityBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensure ability package scripts and WordPress ability runtime dependencies
+ * are present without downgrading existing compatible ranges.
+ */
+export declare function ensureAbilityPackageScripts(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensure `scripts/sync-project.ts` delegates to the generated ability sync
+ * script when present.
+ */
+export declare function ensureAbilitySyncProjectAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensure the workspace build script includes optional ability client entries.
+ */
+export declare function ensureAbilityBuildScriptAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensure webpack discovers the optional ability client registry bundle.
+ */
+export declare function ensureAbilityWebpackAnchors(workspace: WorkspaceProject): Promise<void>;

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

@@ -0,0 +1,294 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import semver from "semver";
+import { getWorkspaceBootstrapPath, patchFile, } from "./cli-add-shared.js";
+import { ABILITY_EDITOR_ASSET, ABILITY_EDITOR_SCRIPT, ABILITY_SERVER_GLOB, WP_ABILITIES_SCRIPT_MODULE_ID, WP_CORE_ABILITIES_SCRIPT_MODULE_ID, } from "./cli-add-workspace-ability-types.js";
+import { appendPhpSnippetBeforeClosingTag, insertPhpSnippetBeforeWorkspaceAnchors, } from "./cli-add-workspace-mutation.js";
+import { readJsonFile } from "./json-utils.js";
+import { DEFAULT_WORDPRESS_ABILITIES_VERSION, DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION, } from "./package-versions.js";
+import { findPhpFunctionRange, hasPhpFunctionCall, hasPhpFunctionDefinition, replacePhpFunctionDefinition, } from "./php-utils.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;
+}
+/**
+ * Ensure the workspace bootstrap loads generated ability PHP modules and
+ * enqueues the generated ability editor script module.
+ */
+export 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 {
+            const functionRange = findPhpFunctionRange(nextSource, enqueueFunctionName);
+            const functionSource = functionRange
+                ? nextSource.slice(functionRange.start, functionRange.end)
+                : "";
+            if (!hasPhpFunctionCall(functionSource, "wp_enqueue_script_module")) {
+                const replacedSource = replacePhpFunctionDefinition(nextSource, enqueueFunctionName, enqueueFunction, { trimReplacementStart: true });
+                if (!replacedSource) {
+                    throw new Error(`Unable to repair ${path.basename(bootstrapPath)} for ${enqueueFunctionName}.`);
+                }
+                nextSource = replacedSource;
+            }
+        }
+        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;
+    });
+}
+/**
+ * Ensure ability package scripts and WordPress ability runtime dependencies
+ * are present without downgrading existing compatible ranges.
+ */
+export async function ensureAbilityPackageScripts(workspace) {
+    const packageJsonPath = path.join(workspace.projectDir, "package.json");
+    const packageJson = await readJsonFile(packageJsonPath, {
+        context: "workspace package manifest",
+    });
+    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");
+}
+/**
+ * Ensure `scripts/sync-project.ts` delegates to the generated ability sync
+ * script when present.
+ */
+export 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;
+    });
+}
+/**
+ * Ensure the workspace build script includes optional ability client entries.
+ */
+export 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;
+    });
+}
+/**
+ * Ensure webpack discovers the optional ability client registry bundle.
+ */
+export 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);
+        });
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Resolve the workspace ability client registry path, preserving JS registries
+ * when older projects already use them.
+ */
+export declare function resolveAbilityRegistryPath(projectDir: string): Promise<string>;
+/**
+ * Rewrite the generated ability client registry while preserving existing
+ * generated entries and extension-suffixed exports.
+ */
+export declare function writeAbilityRegistry(projectDir: string, abilitySlug: string): Promise<void>;

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

@@ -0,0 +1,51 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { readOptionalUtf8File, pathExists } from "./fs-async.js";
+import { buildAbilityRegistrySource, } from "./cli-add-workspace-ability-templates.js";
+import { ABILITY_REGISTRY_END_MARKER, ABILITY_REGISTRY_START_MARKER, } from "./cli-add-workspace-ability-types.js";
+import { escapeRegex } from "./php-utils.js";
+import { readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
+/**
+ * Resolve the workspace ability client registry path, preserving JS registries
+ * when older projects already use them.
+ */
+export async function resolveAbilityRegistryPath(projectDir) {
+    const abilitiesDir = path.join(projectDir, "src", "abilities");
+    for (const candidatePath of [
+        path.join(abilitiesDir, "index.ts"),
+        path.join(abilitiesDir, "index.js"),
+    ]) {
+        if (await pathExists(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return path.join(abilitiesDir, "index.ts");
+}
+async function readAbilityRegistrySlugs(registryPath) {
+    const source = await readOptionalUtf8File(registryPath);
+    if (source === null) {
+        return [];
+    }
+    return Array.from(source.matchAll(/^\s*export\s+\*\s+from\s+['"]\.\/([^/'"]+)\/client(?:\.[cm]?[jt]sx?)?['"];?\s*$/gmu)).map((match) => match[1]);
+}
+/**
+ * Rewrite the generated ability client registry while preserving existing
+ * generated entries and extension-suffixed exports.
+ */
+export async function writeAbilityRegistry(projectDir, abilitySlug) {
+    const abilitiesDir = path.join(projectDir, "src", "abilities");
+    const registryPath = await resolveAbilityRegistryPath(projectDir);
+    await fsp.mkdir(abilitiesDir, { recursive: true });
+    const existingAbilitySlugs = (await readWorkspaceInventoryAsync(projectDir)).abilities.map((entry) => entry.slug);
+    const existingRegistrySlugs = await readAbilityRegistrySlugs(registryPath);
+    const nextAbilitySlugs = Array.from(new Set([...existingAbilitySlugs, ...existingRegistrySlugs, abilitySlug])).sort();
+    const generatedSection = buildAbilityRegistrySource(nextAbilitySlugs);
+    const existingSource = (await readOptionalUtf8File(registryPath)) ?? "";
+    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");
+}

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

@@ -1,4 +1,4 @@
-import { type ScaffoldAbilityWorkspaceOptions } from "./cli-add-workspace-ability-types.js";
+import type { ScaffoldAbilityWorkspaceOptions } from "./cli-add-workspace-ability-types.js";
 /**
  * Write generated workflow ability sources and patch shared workspace anchors.
  */