@wp-typia/project-tools 0.22.3 → 0.22.5

package/dist/runtime/cli-add-block-json.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export declare function resolveWorkspaceBlock(inventory: WorkspaceInventory, blockSlug: string): WorkspaceInventory["blocks"][number];
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export declare function readWorkspaceBlockJson(projectDir: string, blockSlug: string): {
+    blockJson: Record<string, unknown>;
+    blockJsonPath: string;
+};
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export declare function getMutableBlockHooks(blockJson: Record<string, unknown>, blockJsonRelativePath: string): Record<string, string>;

package/dist/runtime/cli-add-block-json.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+/**
+ * Resolve an existing workspace block inventory entry by slug.
+ *
+ * @param inventory Parsed workspace inventory that owns available blocks.
+ * @param blockSlug Workspace block slug to locate.
+ * @returns The matching workspace block inventory entry.
+ * @throws {Error} When the block slug is not present in the inventory.
+ */
+export function resolveWorkspaceBlock(inventory, blockSlug) {
+    const block = inventory.blocks.find((entry) => entry.slug === blockSlug);
+    if (!block) {
+        throw new Error(`Unknown workspace block "${blockSlug}". Choose one of: ${inventory.blocks.map((entry) => entry.slug).join(", ")}`);
+    }
+    return block;
+}
+/**
+ * Read and validate a workspace block's `block.json` metadata from disk.
+ *
+ * @param projectDir Absolute workspace root directory.
+ * @param blockSlug Workspace block slug whose metadata should be read.
+ * @returns Parsed block metadata and the absolute `block.json` path.
+ * @throws {Error} When the file is missing or cannot be parsed as scaffold metadata.
+ */
+export function readWorkspaceBlockJson(projectDir, blockSlug) {
+    const blockJsonPath = path.join(projectDir, "src", "blocks", blockSlug, "block.json");
+    if (!fs.existsSync(blockJsonPath)) {
+        throw new Error(`Missing ${path.relative(projectDir, blockJsonPath)} for workspace block "${blockSlug}".`);
+    }
+    let blockJson;
+    try {
+        blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
+    }
+    catch (error) {
+        throw new Error(error instanceof Error
+            ? `Failed to parse ${path.relative(projectDir, blockJsonPath)}: ${error.message}`
+            : `Failed to parse ${path.relative(projectDir, blockJsonPath)}.`);
+    }
+    return {
+        blockJson,
+        blockJsonPath,
+    };
+}
+/**
+ * Return a mutable `blockHooks` object for a parsed block metadata document.
+ *
+ * @param blockJson Parsed block metadata object that may be mutated.
+ * @param blockJsonRelativePath Relative path used in validation error messages.
+ * @returns The existing or newly created mutable `blockHooks` map.
+ * @throws {Error} When `blockHooks` exists but is not an object.
+ */
+export function getMutableBlockHooks(blockJson, blockJsonRelativePath) {
+    const blockHooks = blockJson.blockHooks;
+    if (blockHooks === undefined) {
+        const nextHooks = {};
+        blockJson.blockHooks = nextHooks;
+        return nextHooks;
+    }
+    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
+        throw new Error(`${blockJsonRelativePath} must define blockHooks as an object when present.`);
+    }
+    return blockHooks;
+}

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

@@ -0,0 +1,129 @@
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+type ScaffoldFilesystemCollision = {
+    label: string;
+    relativePath: string;
+};
+type ScaffoldInventoryCollision<TEntry> = {
+    entries: readonly TEntry[];
+    exists: (entry: TEntry) => boolean;
+    message: string;
+};
+/**
+ * Ensure scaffold targets do not already exist on disk or in workspace inventory.
+ *
+ * @param options Collision checks to run before writing scaffold files.
+ * @throws {Error} When a filesystem path or inventory entry already exists.
+ */
+export declare function assertScaffoldDoesNotExist<TEntry>(options: {
+    projectDir: string;
+    filesystemCollisions: readonly ScaffoldFilesystemCollision[];
+    inventoryCollision?: ScaffoldInventoryCollision<TEntry>;
+}): void;
+/**
+ * Ensure a block variation scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the variation.
+ * @param variationSlug Normalized variation slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the variation file or inventory entry already exists.
+ */
+export declare function assertVariationDoesNotExist(projectDir: string, blockSlug: string, variationSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a block style scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the style.
+ * @param styleSlug Normalized style slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the style file or inventory entry already exists.
+ */
+export declare function assertBlockStyleDoesNotExist(projectDir: string, blockSlug: string, styleSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a block transform scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the transform.
+ * @param transformSlug Normalized transform slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the transform file or inventory entry already exists.
+ */
+export declare function assertBlockTransformDoesNotExist(projectDir: string, blockSlug: string, transformSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a pattern scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param patternSlug Normalized pattern slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the pattern file or inventory entry already exists.
+ */
+export declare function assertPatternDoesNotExist(projectDir: string, patternSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a binding source scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param bindingSourceSlug Normalized binding source slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the binding directory or inventory entry already exists.
+ */
+export declare function assertBindingSourceDoesNotExist(projectDir: string, bindingSourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Ensure a REST resource scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param restResourceSlug Normalized REST resource slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When REST resource files or inventory entry already exist.
+ */
+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;
+/**
+ * Ensure an AI feature scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param aiFeatureSlug Normalized AI feature slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When AI feature files or inventory entry already exist.
+ */
+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;
+export {};

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

@@ -0,0 +1,293 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Ensure scaffold targets do not already exist on disk or in workspace inventory.
+ *
+ * @param options Collision checks to run before writing scaffold files.
+ * @throws {Error} When a filesystem path or inventory entry already exists.
+ */
+export function assertScaffoldDoesNotExist(options) {
+    for (const collision of options.filesystemCollisions) {
+        const targetPath = path.join(options.projectDir, collision.relativePath);
+        if (fs.existsSync(targetPath)) {
+            throw new Error(`${collision.label} already exists at ${path.relative(options.projectDir, targetPath)}. Choose a different name.`);
+        }
+    }
+    if (options.inventoryCollision &&
+        options.inventoryCollision.entries.some(options.inventoryCollision.exists)) {
+        throw new Error(options.inventoryCollision.message);
+    }
+}
+/**
+ * Ensure a block variation scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the variation.
+ * @param variationSlug Normalized variation slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the variation file or inventory entry already exists.
+ */
+export function assertVariationDoesNotExist(projectDir, blockSlug, variationSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A variation",
+                relativePath: path.join("src", "blocks", blockSlug, "variations", `${variationSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.variations,
+            exists: (entry) => entry.block === blockSlug && entry.slug === variationSlug,
+            message: `A variation inventory entry already exists for ${blockSlug}/${variationSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a block style scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the style.
+ * @param styleSlug Normalized style slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the style file or inventory entry already exists.
+ */
+export function assertBlockStyleDoesNotExist(projectDir, blockSlug, styleSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A block style",
+                relativePath: path.join("src", "blocks", blockSlug, "styles", `${styleSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.blockStyles,
+            exists: (entry) => entry.block === blockSlug && entry.slug === styleSlug,
+            message: `A block style inventory entry already exists for ${blockSlug}/${styleSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a block transform scaffold does not already exist.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param blockSlug Existing workspace block slug that owns the transform.
+ * @param transformSlug Normalized transform slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the transform file or inventory entry already exists.
+ */
+export function assertBlockTransformDoesNotExist(projectDir, blockSlug, transformSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A block transform",
+                relativePath: path.join("src", "blocks", blockSlug, "transforms", `${transformSlug}.ts`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.blockTransforms,
+            exists: (entry) => entry.block === blockSlug && entry.slug === transformSlug,
+            message: `A block transform inventory entry already exists for ${blockSlug}/${transformSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a pattern scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param patternSlug Normalized pattern slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the pattern file or inventory entry already exists.
+ */
+export function assertPatternDoesNotExist(projectDir, patternSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A pattern",
+                relativePath: path.join("src", "patterns", `${patternSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.patterns,
+            exists: (entry) => entry.slug === patternSlug,
+            message: `A pattern inventory entry already exists for ${patternSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a binding source scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param bindingSourceSlug Normalized binding source slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When the binding directory or inventory entry already exists.
+ */
+export function assertBindingSourceDoesNotExist(projectDir, bindingSourceSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A binding source",
+                relativePath: path.join("src", "bindings", bindingSourceSlug),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.bindingSources,
+            exists: (entry) => entry.slug === bindingSourceSlug,
+            message: `A binding source inventory entry already exists for ${bindingSourceSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure a REST resource scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param restResourceSlug Normalized REST resource slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When REST resource files or inventory entry already exist.
+ */
+export function assertRestResourceDoesNotExist(projectDir, restResourceSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "A REST resource",
+                relativePath: path.join("src", "rest", restResourceSlug),
+            },
+            {
+                label: "A REST resource bootstrap",
+                relativePath: path.join("inc", "rest", `${restResourceSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.restResources,
+            exists: (entry) => entry.slug === restResourceSlug,
+            message: `A REST resource inventory entry already exists for ${restResourceSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * 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) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An admin view",
+                relativePath: path.join("src", "admin-views", adminViewSlug),
+            },
+            {
+                label: "An admin view bootstrap",
+                relativePath: path.join("inc", "admin-views", `${adminViewSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.adminViews,
+            exists: (entry) => entry.slug === adminViewSlug,
+            message: `An admin view inventory entry already exists for ${adminViewSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * 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 function assertAbilityDoesNotExist(projectDir, abilitySlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An ability scaffold",
+                relativePath: path.join("src", "abilities", abilitySlug),
+            },
+            {
+                label: "An ability bootstrap",
+                relativePath: path.join("inc", "abilities", `${abilitySlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.abilities,
+            exists: (entry) => entry.slug === abilitySlug,
+            message: `An ability inventory entry already exists for ${abilitySlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * Ensure an AI feature scaffold does not already exist on disk or in inventory.
+ *
+ * Delegates filesystem and inventory checks to `assertScaffoldDoesNotExist`.
+ *
+ * @param projectDir Absolute workspace root used to resolve scaffold paths.
+ * @param aiFeatureSlug Normalized AI feature slug that would be created.
+ * @param inventory Current workspace inventory used for duplicate detection.
+ * @throws {Error} When AI feature files or inventory entry already exist.
+ */
+export function assertAiFeatureDoesNotExist(projectDir, aiFeatureSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An AI feature",
+                relativePath: path.join("src", "ai-features", aiFeatureSlug),
+            },
+            {
+                label: "An AI feature bootstrap",
+                relativePath: path.join("inc", "ai-features", `${aiFeatureSlug}.php`),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.aiFeatures,
+            exists: (entry) => entry.slug === aiFeatureSlug,
+            message: `An AI feature inventory entry already exists for ${aiFeatureSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}
+/**
+ * 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 function assertEditorPluginDoesNotExist(projectDir, editorPluginSlug, inventory) {
+    assertScaffoldDoesNotExist({
+        filesystemCollisions: [
+            {
+                label: "An editor plugin",
+                relativePath: path.join("src", "editor-plugins", editorPluginSlug),
+            },
+        ],
+        inventoryCollision: {
+            entries: inventory.editorPlugins,
+            exists: (entry) => entry.slug === editorPluginSlug,
+            message: `An editor plugin inventory entry already exists for ${editorPluginSlug}. Choose a different name.`,
+        },
+        projectDir,
+    });
+}

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

@@ -0,0 +1,29 @@
+import type { WorkspaceMutationSnapshot } from "./cli-add-types.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * 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 declare function getWorkspaceBootstrapPath(workspace: WorkspaceProject): 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>;

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