@wp-typia/project-tools 0.22.2 → 0.22.4

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

@@ -0,0 +1,77 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve the primary PHP bootstrap file for an official workspace.
+ *
+ * @param workspace Workspace metadata that provides `packageName` and `projectDir`.
+ * @returns Absolute path to `<packageBase>.php` in the workspace root.
+ */
+export function getWorkspaceBootstrapPath(workspace) {
+    const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+    return path.join(workspace.projectDir, `${workspaceBaseName}.php`);
+}
+/**
+ * Apply a text transform to an existing file only when the contents change.
+ */
+export async function patchFile(filePath, transform) {
+    const currentSource = await fsp.readFile(filePath, "utf8");
+    const nextSource = transform(currentSource);
+    if (nextSource !== currentSource) {
+        await fsp.writeFile(filePath, nextSource, "utf8");
+    }
+}
+/**
+ * Read a file when it exists and otherwise return `null`.
+ */
+export async function readOptionalFile(filePath) {
+    try {
+        return await fsp.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Restore a file to its captured source, deleting it when the snapshot was `null`.
+ */
+export async function restoreOptionalFile(filePath, source) {
+    if (source === null) {
+        await fsp.rm(filePath, { force: true });
+        return;
+    }
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.writeFile(filePath, source, "utf8");
+}
+/**
+ * Capture the current contents of a set of workspace files for rollback.
+ */
+export async function snapshotWorkspaceFiles(filePaths) {
+    const uniquePaths = Array.from(new Set(filePaths));
+    return Promise.all(uniquePaths.map(async (filePath) => ({
+        filePath,
+        source: await readOptionalFile(filePath),
+    })));
+}
+/**
+ * Undo a partially applied workspace mutation from a captured snapshot.
+ */
+export async function rollbackWorkspaceMutation(snapshot) {
+    for (const targetPath of snapshot.targetPaths) {
+        await fsp.rm(targetPath, { force: true, recursive: true });
+    }
+    for (const snapshotDir of snapshot.snapshotDirs) {
+        await fsp.rm(snapshotDir, { force: true, recursive: true });
+    }
+    for (const { filePath, source } of snapshot.fileSources) {
+        await restoreOptionalFile(filePath, source);
+    }
+}
+function isFileNotFoundError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+export declare function formatAddHelpText(): string;

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

@@ -0,0 +1,41 @@
+import { HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
+import { ADD_BLOCK_TEMPLATE_IDS, EDITOR_PLUGIN_SLOT_IDS, REST_RESOURCE_METHOD_IDS, } from "./cli-add-types.js";
+import { WORKSPACE_TEMPLATE_PACKAGE, } from "./workspace-project.js";
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+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 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 rest-resource <name> [--namespace <vendor/v1>] [--methods <${REST_RESOURCE_METHOD_IDS.join(",")}>] [--dry-run]
+  wp-typia add ability <name> [--dry-run]
+  wp-typia add ai-feature <name> [--namespace <vendor/v1>] [--dry-run]
+  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}> [--dry-run]
+  wp-typia add editor-plugin <name> [--slot <${EDITOR_PLUGIN_SLOT_IDS.join("|")}>] [--dry-run]
+
+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.
+  Pass \`--source core-data:postType/post\` or \`--source core-data:taxonomy/category\` to bind a WordPress-owned entity collection.
+  Public installs currently gate this workflow until \`@wp-typia/dataviews\` is published to npm.
+  \`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 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/\`; legacy aliases \`PluginSidebar\` and \`PluginDocumentSettingPanel\` resolve to \`sidebar\` and \`document-setting-panel\`.`;
+}

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

@@ -1,256 +1,7 @@
-import { type HookedBlockPositionId } from "./hooked-blocks.js";
-import { type WorkspaceInventory } from "./workspace-inventory.js";
-import { type WorkspaceProject } from "./workspace-project.js";
 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 ["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
- * `wp-typia add rest-resource --methods`.
- */
-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 surfaces accepted by
- * `wp-typia add editor-plugin --slot`.
- */
-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`.
- */
-export declare const ADD_BLOCK_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
-export type AddBlockTemplateId = (typeof ADD_BLOCK_TEMPLATE_IDS)[number];
-export declare const REST_RESOURCE_NAMESPACE_PATTERN: RegExp;
-export interface RunAddVariationCommandOptions {
-    blockName: string;
-    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;
-}
-export interface RunAddRestResourceCommandOptions {
-    cwd?: string;
-    methods?: string;
-    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. `rest-resource:<slug>` wires
- * the generated screen to an existing list-capable REST resource.
- * `core-data:<kind>/<name>` binds the screen to a supported WordPress-owned
- * entity collection such as `core-data:postType/post`.
- */
-export interface RunAddAdminViewCommandOptions {
-    adminViewName: string;
-    cwd?: string;
-    source?: string;
-}
-/**
- * Options for `wp-typia add ability`.
- *
- * @property cwd Working directory used to resolve the nearest official workspace.
- * Defaults to `process.cwd()`.
- * @property abilityName Human-entered workflow ability name that will be
- * normalized into the generated slug.
- */
-export interface RunAddAbilityCommandOptions {
-    abilityName: string;
-    cwd?: string;
-}
-export interface RunAddAiFeatureCommandOptions {
-    aiFeatureName: string;
-    cwd?: string;
-    namespace?: string;
-}
-export interface RunAddHookedBlockCommandOptions {
-    anchorBlockName: string;
-    blockName: string;
-    cwd?: string;
-    position: string;
-}
-/**
- * Options for `wp-typia add editor-plugin`.
- *
- * @property cwd Working directory used to resolve the nearest official workspace.
- * 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 `sidebar`.
- */
-export interface RunAddEditorPluginCommandOptions {
-    cwd?: string;
-    editorPluginName: string;
-    slot?: string;
-}
-export interface RunAddBlockCommandOptions {
-    alternateRenderTargets?: string;
-    blockName: string;
-    cwd?: string;
-    dataStorageMode?: string;
-    externalLayerId?: string;
-    externalLayerSource?: string;
-    innerBlocksPreset?: string;
-    persistencePolicy?: string;
-    selectExternalLayerId?: (options: Array<{
-        description?: string;
-        extends: string[];
-        id: string;
-    }>) => Promise<string>;
-    templateId?: string;
-}
-export interface WorkspaceMutationSnapshot {
-    /** Snapshots of file contents taken before the mutation starts. */
-    fileSources: Array<{
-        /** Absolute file path recorded for rollback. */
-        filePath: string;
-        /** Previous file contents, or `null` when the file did not exist. */
-        source: string | null;
-    }>;
-    /** Snapshot directories created while seeding migration history. */
-    snapshotDirs: string[];
-    /** Files or directories created by the mutation that should be removed on rollback. */
-    targetPaths: string[];
-}
-export declare function assertValidGeneratedSlug(label: string, slug: string, usage: string): string;
-export declare function assertValidRestResourceNamespace(namespace: string): string;
-export declare function resolveRestResourceNamespace(workspaceNamespace: string, namespace?: string): string;
-export declare function assertValidRestResourceMethods(methods?: string): RestResourceMethodId[];
-export declare function assertValidHookedBlockPosition(position: string): HookedBlockPositionId;
-export declare function getWorkspaceBootstrapPath(workspace: WorkspaceProject): string;
-export declare function buildWorkspacePhpPrefix(workspacePhpPrefix: string, slug: string): string;
-export declare function isAddBlockTemplateId(value: string): value is AddBlockTemplateId;
-export declare function quoteTsString(value: string): string;
-/**
- * Apply a text transform to an existing file only when the contents change.
- */
-export declare function patchFile(filePath: string, transform: (source: string) => string): Promise<void>;
-/**
- * Read a file when it exists and otherwise return `null`.
- */
-export declare function readOptionalFile(filePath: string): Promise<string | null>;
-/**
- * Restore a file to its captured source, deleting it when the snapshot was `null`.
- */
-export declare function restoreOptionalFile(filePath: string, source: string | null): Promise<void>;
-/**
- * Capture the current contents of a set of workspace files for rollback.
- */
-export declare function snapshotWorkspaceFiles(filePaths: string[]): Promise<WorkspaceMutationSnapshot["fileSources"]>;
-/**
- * Undo a partially applied workspace mutation from a captured snapshot.
- */
-export declare function rollbackWorkspaceMutation(snapshot: WorkspaceMutationSnapshot): Promise<void>;
-export declare function resolveWorkspaceBlock(inventory: WorkspaceInventory, blockSlug: string): WorkspaceInventory["blocks"][number];
-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;
-export declare function readWorkspaceBlockJson(projectDir: string, blockSlug: string): {
-    blockJson: Record<string, unknown>;
-    blockJsonPath: string;
-};
-export declare function getMutableBlockHooks(blockJson: Record<string, unknown>, blockJsonRelativePath: string): Record<string, string>;
-export declare function assertVariationDoesNotExist(projectDir: string, blockSlug: string, variationSlug: string, inventory: WorkspaceInventory): void;
-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.
- *
- * The check covers the generated `src/abilities/<slug>` directory,
- * `inc/abilities/<slug>.php`, and any matching `inventory.abilities` entry.
- *
- * @param projectDir Workspace root directory.
- * @param abilitySlug Normalized workflow ability slug.
- * @param inventory Parsed workspace inventory.
- * @throws {Error} When the ability directory, PHP bootstrap, or inventory entry already exists.
- */
-export declare function assertAbilityDoesNotExist(projectDir: string, abilitySlug: string, inventory: WorkspaceInventory): void;
-export declare function assertAiFeatureDoesNotExist(projectDir: string, aiFeatureSlug: string, inventory: WorkspaceInventory): void;
-/**
- * Ensure an editor plugin scaffold does not already exist on disk or in the
- * workspace inventory.
- *
- * @param projectDir Workspace root directory.
- * @param editorPluginSlug Normalized editor plugin slug.
- * @param inventory Parsed workspace inventory.
- * @throws {Error} When the directory or inventory entry already exists.
- */
-export declare function assertEditorPluginDoesNotExist(projectDir: string, editorPluginSlug: string, inventory: WorkspaceInventory): void;
-/**
- * Returns help text for the canonical `wp-typia add` subcommands.
- */
-export declare function formatAddHelpText(): string;
+export * from "./cli-add-types.js";
+export * from "./cli-add-validation.js";
+export * from "./cli-add-filesystem.js";
+export * from "./cli-add-block-json.js";
+export * from "./cli-add-collision.js";
+export * from "./cli-add-help.js";