@wp-typia/project-tools 0.20.2 → 0.21.0

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

@@ -5,7 +5,7 @@ export { normalizeBlockSlug, } from "./scaffold-identifiers.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
-export declare const ADD_KIND_IDS: readonly ["block", "variation", "pattern", "binding-source", "rest-resource", "ability", "ai-feature", "hooked-block", "editor-plugin"];
+export declare const ADD_KIND_IDS: readonly ["admin-view", "block", "variation", "style", "transform", "pattern", "binding-source", "rest-resource", "ability", "ai-feature", "hooked-block", "editor-plugin"];
 export type AddKindId = (typeof ADD_KIND_IDS)[number];
 /**
  * Supported plugin-level REST resource methods accepted by
@@ -14,10 +14,18 @@ export type AddKindId = (typeof ADD_KIND_IDS)[number];
 export declare const REST_RESOURCE_METHOD_IDS: readonly ["list", "read", "create", "update", "delete"];
 export type RestResourceMethodId = (typeof REST_RESOURCE_METHOD_IDS)[number];
 /**
- * Supported editor-plugin shell slots accepted by `wp-typia add editor-plugin --slot`.
+ * Supported editor-plugin shell surfaces accepted by
+ * `wp-typia add editor-plugin --slot`.
  */
-export declare const EDITOR_PLUGIN_SLOT_IDS: readonly ["PluginSidebar"];
+export declare const EDITOR_PLUGIN_SLOT_IDS: readonly ["sidebar", "document-setting-panel"];
 export type EditorPluginSlotId = (typeof EDITOR_PLUGIN_SLOT_IDS)[number];
+export declare const EDITOR_PLUGIN_SLOT_ALIASES: {
+    readonly PluginDocumentSettingPanel: "document-setting-panel";
+    readonly PluginSidebar: "sidebar";
+    readonly "document-setting-panel": "document-setting-panel";
+    readonly sidebar: "sidebar";
+};
+export declare function resolveEditorPluginSlotAlias(slot: string): EditorPluginSlotId | undefined;
 /**
  * Supported built-in block families accepted by `wp-typia add block --template`.
  */
@@ -29,11 +37,45 @@ export interface RunAddVariationCommandOptions {
     cwd?: string;
     variationName: string;
 }
+/**
+ * Options for `wp-typia add style`.
+ *
+ * @property blockName Existing workspace block slug that owns the style.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @property styleName Human-entered style name that will be normalized into the
+ * generated style slug.
+ */
+export interface RunAddBlockStyleCommandOptions {
+    blockName: string;
+    cwd?: string;
+    styleName: string;
+}
+/**
+ * Options for `wp-typia add transform`.
+ *
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @property fromBlockName Full `namespace/block` source block name accepted by
+ * WordPress block transform definitions.
+ * @property toBlockName Existing workspace block slug or full block name that
+ * owns the generated transform.
+ * @property transformName Human-entered transform name that will be normalized
+ * into the generated transform slug.
+ */
+export interface RunAddBlockTransformCommandOptions {
+    cwd?: string;
+    fromBlockName: string;
+    toBlockName: string;
+    transformName: string;
+}
 export interface RunAddPatternCommandOptions {
     cwd?: string;
     patternName: string;
 }
 export interface RunAddBindingSourceCommandOptions {
+    attributeName?: string;
+    blockName?: string;
     bindingSourceName: string;
     cwd?: string;
 }
@@ -43,6 +85,22 @@ export interface RunAddRestResourceCommandOptions {
     namespace?: string;
     restResourceName: string;
 }
+/**
+ * Options for `wp-typia add admin-view`.
+ *
+ * @property adminViewName Human-entered admin screen name that will be
+ * normalized into the generated slug.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @property source Optional data source locator. The first supported source is
+ * `rest-resource:<slug>`, which wires the generated screen to an existing
+ * list-capable REST resource.
+ */
+export interface RunAddAdminViewCommandOptions {
+    adminViewName: string;
+    cwd?: string;
+    source?: string;
+}
 /**
  * Options for `wp-typia add ability`.
  *
@@ -73,7 +131,7 @@ export interface RunAddHookedBlockCommandOptions {
  * Defaults to `process.cwd()`.
  * @property editorPluginName Human-entered editor plugin name that will be
  * normalized into the generated slug.
- * @property slot Optional editor shell slot. Defaults to `PluginSidebar`.
+ * @property slot Optional editor shell slot. Defaults to `sidebar`.
  */
 export interface RunAddEditorPluginCommandOptions {
     cwd?: string;
@@ -143,7 +201,7 @@ export declare function assertValidHookAnchor(anchorBlockName: string): string;
 /**
  * Validate and normalize the editor plugin shell slot.
  *
- * @param slot Optional shell slot. Defaults to `PluginSidebar`.
+ * @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.
  */
@@ -157,6 +215,16 @@ export declare function assertVariationDoesNotExist(projectDir: string, blockSlu
 export declare function assertPatternDoesNotExist(projectDir: string, patternSlug: string, inventory: WorkspaceInventory): void;
 export declare function assertBindingSourceDoesNotExist(projectDir: string, bindingSourceSlug: string, inventory: WorkspaceInventory): void;
 export declare function assertRestResourceDoesNotExist(projectDir: string, restResourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a DataViews admin screen scaffold does not already exist on disk or in
+ * the workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param adminViewSlug Normalized admin screen slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory, PHP bootstrap, or inventory entry already exists.
+ */
+export declare function assertAdminViewDoesNotExist(projectDir: string, adminViewSlug: string, inventory: WorkspaceInventory): void;
 /**
  * Ensure a workflow ability scaffold does not already exist on disk or in the
  * workspace inventory.

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

@@ -10,8 +10,11 @@ export { normalizeBlockSlug, } from "./scaffold-identifiers.js";
  * 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",
@@ -32,9 +35,23 @@ export const REST_RESOURCE_METHOD_IDS = [
     "delete",
 ];
 /**
- * Supported editor-plugin shell slots accepted by `wp-typia add editor-plugin --slot`.
+ * Supported editor-plugin shell surfaces accepted by
+ * `wp-typia add editor-plugin --slot`.
  */
-export const EDITOR_PLUGIN_SLOT_IDS = ["PluginSidebar"];
+export const EDITOR_PLUGIN_SLOT_IDS = ["sidebar", "document-setting-panel"];
+export const EDITOR_PLUGIN_SLOT_ALIASES = {
+    PluginDocumentSettingPanel: "document-setting-panel",
+    PluginSidebar: "sidebar",
+    "document-setting-panel": "document-setting-panel",
+    sidebar: "sidebar",
+};
+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`.
  */
@@ -175,15 +192,16 @@ export function assertValidHookAnchor(anchorBlockName) {
 /**
  * Validate and normalize the editor plugin shell slot.
  *
- * @param slot Optional shell slot. Defaults to `PluginSidebar`.
+ * @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 = "PluginSidebar") {
-    if (EDITOR_PLUGIN_SLOT_IDS.includes(slot)) {
-        return slot;
+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(", ")}.`);
+    throw new Error(`Editor plugin slot must be one of: ${EDITOR_PLUGIN_SLOT_IDS.join(", ")}. Legacy aliases: PluginSidebar, PluginDocumentSettingPanel.`);
 }
 export function readWorkspaceBlockJson(projectDir, blockSlug) {
     const blockJsonPath = path.join(projectDir, "src", "blocks", blockSlug, "block.json");
@@ -256,6 +274,28 @@ export function assertRestResourceDoesNotExist(projectDir, restResourceSlug, inv
         throw new Error(`A REST resource inventory entry already exists for ${restResourceSlug}. Choose a different name.`);
     }
 }
+/**
+ * Ensure a DataViews admin screen scaffold does not already exist on disk or in
+ * the workspace inventory.
+ *
+ * @param projectDir Workspace root directory.
+ * @param adminViewSlug Normalized admin screen slug.
+ * @param inventory Parsed workspace inventory.
+ * @throws {Error} When the directory, PHP bootstrap, or inventory entry already exists.
+ */
+export function assertAdminViewDoesNotExist(projectDir, adminViewSlug, inventory) {
+    const adminViewDir = path.join(projectDir, "src", "admin-views", adminViewSlug);
+    const adminViewPhpPath = path.join(projectDir, "inc", "admin-views", `${adminViewSlug}.php`);
+    if (fs.existsSync(adminViewDir)) {
+        throw new Error(`An admin view already exists at ${path.relative(projectDir, adminViewDir)}. Choose a different name.`);
+    }
+    if (fs.existsSync(adminViewPhpPath)) {
+        throw new Error(`An admin view bootstrap already exists at ${path.relative(projectDir, adminViewPhpPath)}. Choose a different name.`);
+    }
+    if (inventory.adminViews.some((entry) => entry.slug === adminViewSlug)) {
+        throw new Error(`An admin view inventory entry already exists for ${adminViewSlug}. Choose a different name.`);
+    }
+}
 /**
  * Ensure a workflow ability scaffold does not already exist on disk or in the
  * workspace inventory.
@@ -317,10 +357,13 @@ export function assertEditorPluginDoesNotExist(projectDir, editorPluginSlug, inv
  */
 export function formatAddHelpText() {
     return `Usage:
-  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 admin-view <name> [--source <rest-resource:slug>] [--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 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> [--dry-run]
+  wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>] [--dry-run]
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create,update,delete>] [--dry-run]
   wp-typia add ability <name> [--dry-run]
   wp-typia add ai-feature <name> [--namespace <vendor/v1>] [--dry-run]
@@ -330,13 +373,17 @@ export function formatAddHelpText() {
 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 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.
   \`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/\`.
+  \`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 rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
   \`add ability\` scaffolds typed workflow abilities under \`src/abilities/\` and server registration under \`inc/abilities/\`.
   \`add ai-feature\` scaffolds server-owned AI feature endpoints under \`src/ai-features/\` and PHP route glue under \`inc/ai-features/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
-  \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`.`;
+  \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`; legacy aliases \`PluginSidebar\` and \`PluginDocumentSettingPanel\` resolve to \`sidebar\` and \`document-setting-panel\`.`;
 }

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

@@ -5,7 +5,8 @@ import { syncTypeSchemas } from "@wp-typia/block-runtime/metadata-core";
 import semver from "semver";
 import { appendWorkspaceInventoryEntries, readWorkspaceInventory, } from "./workspace-inventory.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
-import { toTitleCase } from "./string-case.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";
 const ABILITY_SERVER_GLOB = "/inc/abilities/*.php";
@@ -17,46 +18,6 @@ const WP_ABILITIES_PACKAGE_VERSION = "^0.10.0";
 const WP_CORE_ABILITIES_PACKAGE_VERSION = "^0.9.0";
 const WP_ABILITIES_SCRIPT_MODULE_ID = "@wordpress/abilities";
 const WP_CORE_ABILITIES_SCRIPT_MODULE_ID = "@wordpress/core-abilities";
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
-function quotePhpString(value) {
-    return `'${value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'")}'`;
-}
-function findPhpFunctionRange(source, functionName) {
-    const functionPattern = new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\([^)]*\\)\\s*\\{`, "u");
-    const match = functionPattern.exec(source);
-    if (!match) {
-        return null;
-    }
-    const openingBraceIndex = match.index + match[0].length - 1;
-    let depth = 0;
-    for (let index = openingBraceIndex; index < source.length; index += 1) {
-        const character = source[index];
-        if (character === "{") {
-            depth += 1;
-        }
-        else if (character === "}") {
-            depth -= 1;
-            if (depth === 0) {
-                const end = index + 1;
-                return {
-                    end,
-                    source: source.slice(match.index, end),
-                    start: match.index,
-                };
-            }
-        }
-    }
-    return null;
-}
-function replacePhpFunctionDefinition(source, functionName, replacement) {
-    const functionRange = findPhpFunctionRange(source, functionName);
-    if (!functionRange) {
-        return source;
-    }
-    return `${source.slice(0, functionRange.start)}${replacement.trimStart()}${source.slice(functionRange.end)}`;
-}
 function resolveManagedDependencyVersion(existingVersion, requiredVersion) {
     if (!existingVersion) {
         return requiredVersion;
@@ -70,13 +31,6 @@ function resolveManagedDependencyVersion(existingVersion, requiredVersion) {
         ? existingVersion
         : requiredVersion;
 }
-function toPascalCaseFromAbilitySlug(abilitySlug) {
-    return normalizeBlockSlug(abilitySlug)
-        .split("-")
-        .filter(Boolean)
-        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
-        .join("");
-}
 function toAbilityCategorySlug(workspaceNamespace) {
     const normalizedNamespace = workspaceNamespace
         .replace(/[^a-z0-9-]+/gu, "-")
@@ -85,7 +39,7 @@ function toAbilityCategorySlug(workspaceNamespace) {
     return `${normalizedNamespace || "workspace"}-workflows`;
 }
 function buildAbilityConfigEntry(abilitySlug, compatibilityPolicy) {
-    const pascalCase = toPascalCaseFromAbilitySlug(abilitySlug);
+    const pascalCase = toPascalCase(abilitySlug);
     return [
         "\t{",
         `\t\tclientFile: ${quoteTsString(`src/abilities/${abilitySlug}/client.ts`)},`,
@@ -127,7 +81,7 @@ function buildAbilityConfigSource(abilitySlug, workspaceNamespace) {
     }, null, 2)}\n`;
 }
 function buildAbilityTypesSource(abilitySlug) {
-    const pascalCase = toPascalCaseFromAbilitySlug(abilitySlug);
+    const pascalCase = toPascalCase(abilitySlug);
     return `export interface ${pascalCase}AbilityInput {
 \tcontextId: number;
 \tnote?: string;
@@ -142,7 +96,7 @@ export interface ${pascalCase}AbilityOutput {
 `;
 }
 function buildAbilityDataSource(abilitySlug) {
-    const pascalCase = toPascalCaseFromAbilitySlug(abilitySlug);
+    const pascalCase = toPascalCase(abilitySlug);
     const abilityConstBase = abilitySlug
         .toUpperCase()
         .replace(/[^A-Z0-9]+/gu, "_")
@@ -242,7 +196,7 @@ export async function run${pascalCase}Ability(
 `;
 }
 function buildAbilityClientSource(abilitySlug) {
-    const pascalCase = toPascalCaseFromAbilitySlug(abilitySlug);
+    const pascalCase = toPascalCase(abilitySlug);
     return `/**
  * Re-export the typed ${pascalCase} ability client helpers.
  *
@@ -651,7 +605,6 @@ function ${enqueueFunctionName}() {
             /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
             /\?>\s*$/u,
         ];
-        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(nextSource);
         const insertPhpSnippet = (snippet) => {
             for (const anchor of insertionAnchors) {
                 const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
@@ -670,14 +623,15 @@ function ${enqueueFunctionName}() {
             }
             nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
         };
-        if (!hasPhpFunctionDefinition(loadFunctionName)) {
+        if (!hasPhpFunctionDefinition(nextSource, loadFunctionName)) {
             insertPhpSnippet(loadFunction);
         }
-        if (!hasPhpFunctionDefinition(enqueueFunctionName)) {
+        if (!hasPhpFunctionDefinition(nextSource, enqueueFunctionName)) {
             insertPhpSnippet(enqueueFunction);
         }
         else if (!findPhpFunctionRange(nextSource, enqueueFunctionName)?.source.includes("wp_enqueue_script_module")) {
-            nextSource = replacePhpFunctionDefinition(nextSource, enqueueFunctionName, enqueueFunction);
+            nextSource =
+                replacePhpFunctionDefinition(nextSource, enqueueFunctionName, enqueueFunction, { trimReplacementStart: true }) ?? nextSource;
         }
         if (!nextSource.includes(loadHook)) {
             appendPhpSnippet(loadHook);
@@ -882,7 +836,7 @@ export async function runAddAbilityCommand({ abilityName, cwd = process.cwd(), }
         await fsp.writeFile(dataFilePath, buildAbilityDataSource(abilitySlug), "utf8");
         await fsp.writeFile(clientFilePath, buildAbilityClientSource(abilitySlug), "utf8");
         await fsp.writeFile(phpFilePath, buildAbilityPhpSource(abilitySlug, workspace), "utf8");
-        const pascalCase = toPascalCaseFromAbilitySlug(abilitySlug);
+        const pascalCase = toPascalCase(abilitySlug);
         await syncTypeSchemas({
             jsonSchemaFile: `src/abilities/${abilitySlug}/input.schema.json`,
             projectRoot: workspace.projectDir,

package/dist/runtime/cli-add-workspace-admin-view.d.ts

@@ -0,0 +1,23 @@
+import { type RunAddAdminViewCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one DataViews-powered WordPress admin screen scaffold to an official
+ * workspace project.
+ *
+ * @param options Command options for the admin-view scaffold workflow.
+ * @param options.adminViewName Human-entered admin screen name that will be
+ * normalized and validated before files are written.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.source Optional data source locator. `rest-resource:<slug>`
+ * wires the screen to an existing list-capable REST resource.
+ * @returns A promise that resolves with the normalized `adminViewSlug`, optional
+ * `source`, and owning `projectDir` after scaffold files and inventory entries
+ * are written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the slug/source is invalid, or when a conflicting file or inventory entry exists.
+ */
+export declare function runAddAdminViewCommand({ adminViewName, cwd, source, }: RunAddAdminViewCommandOptions): Promise<{
+    adminViewSlug: string;
+    projectDir: string;
+    source?: string;
+}>;