@wp-typia/project-tools 0.22.3 → 0.22.4

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

@@ -0,0 +1,247 @@
+/**
+ * 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"];
+/**
+ * Union of supported top-level `wp-typia add` kind ids.
+ */
+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"];
+/**
+ * Union of supported plugin-level REST resource method ids.
+ */
+export type RestResourceMethodId = (typeof REST_RESOURCE_METHOD_IDS)[number];
+/**
+ * Canonical editor-plugin shell surface ids accepted by
+ * `wp-typia add editor-plugin --slot`.
+ */
+export declare const EDITOR_PLUGIN_SLOT_IDS: readonly ["sidebar", "document-setting-panel"];
+/**
+ * Union of canonical editor-plugin shell surface ids.
+ */
+export type EditorPluginSlotId = (typeof EDITOR_PLUGIN_SLOT_IDS)[number];
+/**
+ * Legacy and canonical editor-plugin slot aliases keyed by user-facing input.
+ */
+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";
+};
+/**
+ * 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 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"];
+/**
+ * Union of supported built-in block template ids.
+ */
+export type AddBlockTemplateId = (typeof ADD_BLOCK_TEMPLATE_IDS)[number];
+/**
+ * Options for `wp-typia add variation`.
+ *
+ * @property blockName Existing workspace block slug that owns the variation.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property variationName Human-entered variation name normalized into a slug.
+ */
+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;
+}
+/**
+ * Options for `wp-typia add pattern`.
+ *
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property patternName Human-entered pattern name normalized into a slug.
+ */
+export interface RunAddPatternCommandOptions {
+    cwd?: string;
+    patternName: string;
+}
+/**
+ * Options for `wp-typia add binding-source`.
+ *
+ * @property attributeName Optional block attribute to bind when `blockName` is provided.
+ * @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.
+ */
+export interface RunAddBindingSourceCommandOptions {
+    attributeName?: string;
+    blockName?: string;
+    bindingSourceName: string;
+    cwd?: string;
+}
+/**
+ * Options for `wp-typia add rest-resource`.
+ *
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property methods Optional comma-separated REST method list.
+ * @property namespace Optional REST namespace, defaulting to the workspace namespace.
+ * @property restResourceName Human-entered resource name normalized into a slug.
+ */
+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;
+}
+/**
+ * Options for `wp-typia add ai-feature`.
+ *
+ * @property aiFeatureName Human-entered AI feature name normalized into a slug.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property namespace Optional REST namespace, defaulting to the workspace namespace.
+ */
+export interface RunAddAiFeatureCommandOptions {
+    aiFeatureName: string;
+    cwd?: string;
+    namespace?: string;
+}
+/**
+ * Options for `wp-typia add hooked-block`.
+ *
+ * @property anchorBlockName Full `namespace/block` anchor block name.
+ * @property blockName Existing workspace block slug that receives metadata.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property position Hook position accepted by WordPress block hooks.
+ */
+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;
+}
+/**
+ * Options for `wp-typia add block`.
+ *
+ * @property alternateRenderTargets Optional comma-separated alternate render targets.
+ * @property blockName Human-entered block name normalized into a slug.
+ * @property cwd Working directory used to resolve the nearest official workspace.
+ * @property dataStorageMode Optional persistence storage mode.
+ * @property externalLayerId Optional external layer id to apply.
+ * @property externalLayerSource Optional local, GitHub, or npm external layer source.
+ * @property innerBlocksPreset Optional compound block inner blocks preset.
+ * @property persistencePolicy Optional persistence access policy.
+ * @property selectExternalLayerId Optional selector for interactive external layer choice.
+ * @property templateId Optional built-in block template id.
+ */
+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;
+}
+/**
+ * Captured workspace mutation state used to roll back partial add operations.
+ */
+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[];
+}

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.`);
+}