@wp-typia/project-tools 0.23.1 → 0.24.0

package/dist/runtime/cli-add-workspace-block-transform.js

@@ -0,0 +1,197 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { assertFullBlockName, resolveWorkspaceTargetBlockName, } from "./block-targets.js";
+import { pathExists } from "./fs-async.js";
+import { assertBlockTransformDoesNotExist, assertValidGeneratedSlug, normalizeBlockSlug, quoteTsString, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureWorkspaceRegistrationSettingsCall } from "./cli-add-workspace-registration-hooks.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject } from "./workspace-project.js";
+import { toSnakeCase, toTitleCase } from "./string-case.js";
+const BLOCK_TRANSFORMS_IMPORT_LINE = "import { applyWorkspaceBlockTransforms } from './transforms';";
+const BLOCK_TRANSFORMS_IMPORT_PATTERN = /^\s*import\s*\{\s*applyWorkspaceBlockTransforms\s*\}\s*from\s*["']\.\/transforms["']\s*;?\s*$/mu;
+const BLOCK_TRANSFORMS_CALL_LINE = "applyWorkspaceBlockTransforms(registration.settings);";
+const BLOCK_TRANSFORMS_CALL_PATTERN = /applyWorkspaceBlockTransforms\s*\(\s*registration\s*\.\s*settings\s*\)\s*;?/u;
+function buildWorkspaceConstName(prefix, slug) {
+    return `workspace${prefix}_${toSnakeCase(slug)}`;
+}
+function buildBlockTransformConfigEntry(options) {
+    return [
+        "\t{",
+        `\t\tblock: ${quoteTsString(options.blockSlug)},`,
+        `\t\tfile: ${quoteTsString(`src/blocks/${options.blockSlug}/transforms/${options.transformSlug}.ts`)},`,
+        `\t\tfrom: ${quoteTsString(options.fromBlockName)},`,
+        `\t\tslug: ${quoteTsString(options.transformSlug)},`,
+        `\t\tto: ${quoteTsString(options.toBlockName)},`,
+        "\t},",
+    ].join("\n");
+}
+function getBlockTransformConstBindings(transformSlugs) {
+    const seenConstNames = new Map();
+    return transformSlugs.map((transformSlug) => {
+        const constName = buildWorkspaceConstName("BlockTransform", transformSlug);
+        const previousSlug = seenConstNames.get(constName);
+        if (previousSlug && previousSlug !== transformSlug) {
+            throw new Error(`Transform slugs "${previousSlug}" and "${transformSlug}" generate the same registry identifier "${constName}". Rename one of the transforms.`);
+        }
+        seenConstNames.set(constName, transformSlug);
+        return { constName, transformSlug };
+    });
+}
+function buildBlockTransformSource(options) {
+    const transformTitle = toTitleCase(options.transformSlug);
+    const transformConstName = buildWorkspaceConstName("BlockTransform", options.transformSlug);
+    return `import { createBlock } from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+import metadata from '../block.json';
+
+type TransformAttributes = Record<string, unknown>;
+type TransformInnerBlock = ReturnType<typeof createBlock>;
+
+function mapTransformAttributes(attributes: TransformAttributes): TransformAttributes {
+\tconst content = attributes.content;
+
+\treturn typeof content === 'string' ? { content } : {};
+}
+
+export const ${transformConstName} = {
+\ttype: 'block',
+\tblocks: [${quoteTsString(options.fromBlockName)}],
+\ttitle: __( ${quoteTsString(transformTitle)}, ${quoteTsString(options.textDomain)} ),
+\ttransform: (
+\t\tattributes: TransformAttributes,
+\t\tinnerBlocks: TransformInnerBlock[] = [],
+\t) => createBlock(metadata.name, mapTransformAttributes(attributes), innerBlocks),
+} as const;
+`;
+}
+function buildBlockTransformIndexSource(transformSlugs) {
+    const transformBindings = getBlockTransformConstBindings(transformSlugs);
+    const importLines = transformBindings
+        .map(({ constName, transformSlug }) => `import { ${constName} } from './${transformSlug}';`)
+        .join("\n");
+    const transformConstNames = transformBindings
+        .map(({ constName }) => constName)
+        .join(",\n\t");
+    return `${importLines ? `${importLines}\n\n` : ""}type BlockSettingsWithTransforms = {
+\ttransforms?: {
+\t\tfrom?: unknown[];
+\t\tto?: unknown[];
+\t};
+};
+
+const WORKSPACE_BLOCK_TRANSFORMS = [
+\t${transformConstNames}
+\t// wp-typia add transform entries
+] as const;
+
+export function applyWorkspaceBlockTransforms(settings: BlockSettingsWithTransforms) {
+\tconst transforms = settings.transforms ?? {};
+
+\tsettings.transforms = {
+\t\t...transforms,
+\t\tfrom: [...(transforms.from ?? []), ...WORKSPACE_BLOCK_TRANSFORMS],
+\t};
+}
+`;
+}
+async function ensureBlockTransformRegistrationHook(blockIndexPath) {
+    await ensureWorkspaceRegistrationSettingsCall({
+        blockIndexPath,
+        callLine: BLOCK_TRANSFORMS_CALL_LINE,
+        callPattern: BLOCK_TRANSFORMS_CALL_PATTERN,
+        importLine: BLOCK_TRANSFORMS_IMPORT_LINE,
+        importPattern: BLOCK_TRANSFORMS_IMPORT_PATTERN,
+    });
+}
+async function writeBlockTransformRegistry(projectDir, blockSlug, transformSlug) {
+    const transformsDir = path.join(projectDir, "src", "blocks", blockSlug, "transforms");
+    const transformsIndexPath = path.join(transformsDir, "index.ts");
+    await fsp.mkdir(transformsDir, { recursive: true });
+    const existingTransformSlugs = (await fsp.readdir(transformsDir))
+        .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts")
+        .map((entry) => entry.replace(/\.ts$/u, ""));
+    const nextTransformSlugs = Array.from(new Set([...existingTransformSlugs, transformSlug])).sort();
+    await fsp.writeFile(transformsIndexPath, buildBlockTransformIndexSource(nextTransformSlugs), "utf8");
+}
+/**
+ * Add one block-to-block transform registration to an existing workspace block.
+ *
+ * @param options Command options for the block transform scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.fromBlockName Source block name for `--from`. This must be the
+ * full `namespace/block` form because transforms may originate from WordPress
+ * core or third-party blocks outside the workspace.
+ * @param options.toBlockName Target block for `--to`. A workspace block slug is
+ * resolved against the workspace namespace, while a full `namespace/block` name
+ * must still point at an existing workspace block.
+ * @param options.transformName Human-entered transform name that will be
+ * normalized and validated before files are written.
+ * @returns A promise that resolves with the normalized target `blockSlug`,
+ * resolved `fromBlockName`, resolved `toBlockName`, `transformSlug`, and owning
+ * `projectDir` after the transform module, transform registry, entrypoint hook,
+ * and inventory entry have been written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the target block is unknown, when `--from` is not a full block name, when
+ * `--to` uses a non-workspace namespace, when the target block entrypoint does
+ * not expose `registration.settings`, when the transform slug is invalid, or
+ * when a conflicting file or inventory entry already exists.
+ */
+export async function runAddBlockTransformCommand({ cwd = process.cwd(), fromBlockName, toBlockName, transformName, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const transformSlug = assertValidGeneratedSlug("Transform name", normalizeBlockSlug(transformName), "wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug>");
+    const resolvedFromBlockName = assertFullBlockName(fromBlockName, "--from");
+    const target = resolveWorkspaceTargetBlockName(toBlockName, workspace.workspace.namespace, "--to");
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    resolveWorkspaceBlock(inventory, target.blockSlug);
+    assertBlockTransformDoesNotExist(workspace.projectDir, target.blockSlug, transformSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const blockIndexPath = path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "index.tsx");
+    const transformsDir = path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "transforms");
+    const transformFilePath = path.join(transformsDir, `${transformSlug}.ts`);
+    const transformsIndexPath = path.join(transformsDir, "index.ts");
+    const shouldRemoveTransformsDirOnRollback = !(await pathExists(transformsDir));
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            blockIndexPath,
+            transformsIndexPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [
+            transformFilePath,
+            ...(shouldRemoveTransformsDirOnRollback ? [transformsDir] : []),
+        ],
+    };
+    try {
+        await fsp.mkdir(transformsDir, { recursive: true });
+        await fsp.writeFile(transformFilePath, buildBlockTransformSource({
+            fromBlockName: resolvedFromBlockName,
+            textDomain: workspace.workspace.textDomain,
+            transformSlug,
+        }), "utf8");
+        await writeBlockTransformRegistry(workspace.projectDir, target.blockSlug, transformSlug);
+        await ensureBlockTransformRegistrationHook(blockIndexPath);
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            blockTransformEntries: [
+                buildBlockTransformConfigEntry({
+                    blockSlug: target.blockSlug,
+                    fromBlockName: resolvedFromBlockName,
+                    toBlockName: target.blockName,
+                    transformSlug,
+                }),
+            ],
+        });
+        return {
+            blockSlug: target.blockSlug,
+            fromBlockName: resolvedFromBlockName,
+            projectDir: workspace.projectDir,
+            toBlockName: target.blockName,
+            transformSlug,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { pathExists } from "./fs-async.js";
 import { assertContractDoesNotExist, assertValidGeneratedSlug, assertValidTypeScriptIdentifier, normalizeBlockSlug, } from "./cli-add-shared.js";
 import { executeWorkspaceMutationPlan } from "./cli-add-workspace-mutation.js";
-import { ensureContractSyncScriptAnchors } from "./cli-add-workspace-rest-anchors.js";
+import { ensureContractSyncScriptAnchors, } from "./cli-add-workspace-rest-contract-sync-anchors.js";
 import { buildContractConfigEntry, buildContractTypesSource, } from "./cli-add-workspace-contract-source-emitters.js";
 import { syncStandaloneContractArtifacts } from "./contract-artifacts.js";
 import { toPascalCase } from "./string-case.js";

package/dist/runtime/cli-add-workspace-core-variation.d.ts

@@ -0,0 +1,20 @@
+import { type RunAddCoreVariationCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one editor-side variation registration for an existing core or external block.
+ *
+ * @param options Command options for the core-variation scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.targetBlockName Full `namespace/block` name that receives the variation.
+ * @param options.variationName Human-entered variation name normalized into the generated slug.
+ * @returns The normalized variation metadata and owning workspace directory.
+ * @throws {Error} When the command is run outside an official workspace, the
+ * target block name is not full `namespace/block` form, or the generated file
+ * already exists.
+ */
+export declare function runAddCoreVariationCommand({ cwd, targetBlockName, variationName, }: RunAddCoreVariationCommandOptions): Promise<{
+    projectDir: string;
+    targetBlockName: string;
+    variationFile: string;
+    variationSlug: string;
+}>;

package/dist/runtime/cli-add-workspace-core-variation.js

@@ -0,0 +1,322 @@
+import fs, { promises as fsp } from "node:fs";
+import path from "node:path";
+import { assertFullBlockName } from "./block-targets.js";
+import { assertValidGeneratedSlug, normalizeBlockSlug, quoteTsString, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureEditorPluginBootstrapAnchors, ensureEditorPluginBuildScriptAnchors, ensureEditorPluginWebpackAnchors, resolveEditorPluginRegistryPath, writeEditorPluginRegistry, } from "./cli-add-workspace-editor-plugin.js";
+import { pathExists } from "./fs-async.js";
+import { toKebabCase, toPascalCase, toTitleCase } from "./string-case.js";
+import { resolveWorkspaceProject } from "./workspace-project.js";
+const CORE_VARIATIONS_EDITOR_PLUGIN_SLUG = "core-variations";
+const CORE_VARIATION_USAGE = "wp-typia add core-variation <block-name> <name> or wp-typia add core-variation <name> --block <namespace/block>";
+const CORE_VARIATION_SIMPLE_CONTAINER_BLOCKS = new Set([
+    "core/column",
+    "core/cover",
+    "core/group",
+    "core/media-text",
+]);
+function getCoreVariationRootDir(projectDir) {
+    return path.join(projectDir, "src", "editor-plugins", CORE_VARIATIONS_EDITOR_PLUGIN_SLUG);
+}
+function getCoreVariationBlockDir(projectDir, targetBlockName) {
+    const [namespace, blockSlug] = targetBlockName.split("/");
+    return path.join(getCoreVariationRootDir(projectDir), namespace ?? "", blockSlug ?? "");
+}
+function getCoreVariationFilePath(projectDir, targetBlockName, variationSlug) {
+    return path.join(getCoreVariationBlockDir(projectDir, targetBlockName), `${variationSlug}.ts`);
+}
+function getCoreVariationIndexPath(projectDir) {
+    return path.join(getCoreVariationRootDir(projectDir), "index.ts");
+}
+function buildCoreVariationIdentifier(targetBlockName, variationSlug) {
+    return toKebabCase(`${targetBlockName}-${variationSlug}`)
+        .split("-")
+        .filter(Boolean)
+        .join("_");
+}
+function buildCoreVariationConstName(targetBlockName, variationSlug) {
+    return `coreVariation_${buildCoreVariationIdentifier(targetBlockName, variationSlug)}`;
+}
+function buildCoreVariationBlockConstName(targetBlockName, variationSlug) {
+    return `${buildCoreVariationIdentifier(targetBlockName, variationSlug).toUpperCase()}_BLOCK_NAME`;
+}
+function buildCoreVariationAttributesTypeName(targetBlockName, variationSlug) {
+    return `${toPascalCase(`${targetBlockName}-${variationSlug}`)}Attributes`;
+}
+function buildCoreVariationAttributesConstName(targetBlockName, variationSlug) {
+    return `${buildCoreVariationIdentifier(targetBlockName, variationSlug)}Attributes`;
+}
+function buildCoreVariationInnerBlocksConstName(targetBlockName, variationSlug) {
+    return `${buildCoreVariationIdentifier(targetBlockName, variationSlug)}InnerBlocks`;
+}
+function buildCoreVariationImportPath(ref) {
+    return `./${ref.targetBlockName}/${ref.variationSlug}`;
+}
+function formatCoreVariationTitle(variationSlug) {
+    return toTitleCase(variationSlug);
+}
+function assertCoreVariationDoesNotExist(projectDir, targetBlockName, variationSlug) {
+    const variationFilePath = getCoreVariationFilePath(projectDir, targetBlockName, variationSlug);
+    if (fs.existsSync(variationFilePath)) {
+        throw new Error(`A core block variation already exists at ${path.relative(projectDir, variationFilePath)}. Choose a different name.`);
+    }
+}
+function assertCoreVariationSlugIsNotRegistryIndex(variationSlug) {
+    if (variationSlug === "index") {
+        throw new Error("Core variation name must not normalize to `index`. Choose a different name so the variation module can be registered.");
+    }
+}
+function buildCoreVariationInnerBlocksSource(options) {
+    if (options.targetBlockName === "core/columns") {
+        return `export const ${options.constName} = [
+\t[
+\t\t'core/column',
+\t\t{},
+\t\t[
+\t\t\t[
+\t\t\t\t'core/heading',
+\t\t\t\t{
+\t\t\t\t\tlevel: 2,
+\t\t\t\t\tplaceholder: __( ${quoteTsString("Add a section heading")}, ${quoteTsString(options.textDomain)} ),
+\t\t\t\t},
+\t\t\t],
+\t\t\t[
+\t\t\t\t'core/paragraph',
+\t\t\t\t{
+\t\t\t\t\tplaceholder: __( ${quoteTsString("Add supporting copy")}, ${quoteTsString(options.textDomain)} ),
+\t\t\t\t},
+\t\t\t],
+\t\t],
+\t],
+] satisfies BlockTemplate;`;
+    }
+    if (CORE_VARIATION_SIMPLE_CONTAINER_BLOCKS.has(options.targetBlockName)) {
+        return `export const ${options.constName} = [
+\t[
+\t\t'core/heading',
+\t\t{
+\t\t\tlevel: 2,
+\t\t\tplaceholder: __( ${quoteTsString("Add a section heading")}, ${quoteTsString(options.textDomain)} ),
+\t\t},
+\t],
+\t[
+\t\t'core/paragraph',
+\t\t{
+\t\t\tplaceholder: __( ${quoteTsString("Add supporting copy")}, ${quoteTsString(options.textDomain)} ),
+\t\t},
+\t],
+] satisfies BlockTemplate;`;
+    }
+    return `// Non-container core blocks can keep this empty or replace it with a
+// block-supported InnerBlocks template when the target block accepts children.
+export const ${options.constName} = [] satisfies BlockTemplate;`;
+}
+function buildCoreVariationSource(options) {
+    const attributesTypeName = buildCoreVariationAttributesTypeName(options.targetBlockName, options.variationSlug);
+    const blockConstName = buildCoreVariationBlockConstName(options.targetBlockName, options.variationSlug);
+    const attributesConstName = buildCoreVariationAttributesConstName(options.targetBlockName, options.variationSlug);
+    const innerBlocksConstName = buildCoreVariationInnerBlocksConstName(options.targetBlockName, options.variationSlug);
+    const variationConstName = buildCoreVariationConstName(options.targetBlockName, options.variationSlug);
+    const variationTitle = formatCoreVariationTitle(options.variationSlug);
+    const variationClassName = `is-${options.variationSlug}`;
+    return `import type {
+\tBlockTemplate,
+\tBlockVariation,
+} from '@wp-typia/block-types/blocks/registration';
+import { __ } from '@wordpress/i18n';
+
+export const ${blockConstName} = ${quoteTsString(options.targetBlockName)};
+
+export interface ${attributesTypeName} {
+\tclassName?: string;
+\tmetadata?: {
+\t\tname?: string;
+\t};
+\t[key: string]: unknown;
+}
+
+export const ${attributesConstName} = {
+\tclassName: ${quoteTsString(variationClassName)},
+\tmetadata: {
+\t\tname: ${quoteTsString(variationTitle)},
+\t},
+} satisfies ${attributesTypeName};
+
+${buildCoreVariationInnerBlocksSource({
+        constName: innerBlocksConstName,
+        targetBlockName: options.targetBlockName,
+        textDomain: options.textDomain,
+    })}
+
+export const ${variationConstName} = {
+\tname: ${quoteTsString(options.variationSlug)},
+\ttitle: __( ${quoteTsString(variationTitle)}, ${quoteTsString(options.textDomain)} ),
+\tdescription: __(
+\t\t${quoteTsString(`A starter ${options.targetBlockName} variation for ${variationTitle}.`)},
+\t\t${quoteTsString(options.textDomain)},
+\t),
+\tcategory: 'design',
+\ticon: 'layout',
+\tkeywords: [
+\t\t__( ${quoteTsString("variation")}, ${quoteTsString(options.textDomain)} ),
+\t\t__( ${quoteTsString(variationTitle)}, ${quoteTsString(options.textDomain)} ),
+\t],
+\tattributes: ${attributesConstName},
+\tinnerBlocks: ${innerBlocksConstName},
+\tisActive: ['className'],
+\tscope: ['block', 'inserter', 'transform'],
+} satisfies BlockVariation<${attributesTypeName}>;
+`;
+}
+async function readCoreVariationModuleRefs(coreVariationsDir) {
+    if (!(await pathExists(coreVariationsDir))) {
+        return [];
+    }
+    const refs = [];
+    const namespaceEntries = await fsp.readdir(coreVariationsDir, {
+        withFileTypes: true,
+    });
+    for (const namespaceEntry of namespaceEntries) {
+        if (!namespaceEntry.isDirectory()) {
+            continue;
+        }
+        const namespaceDir = path.join(coreVariationsDir, namespaceEntry.name);
+        const blockEntries = await fsp.readdir(namespaceDir, {
+            withFileTypes: true,
+        });
+        for (const blockEntry of blockEntries) {
+            if (!blockEntry.isDirectory()) {
+                continue;
+            }
+            const blockDir = path.join(namespaceDir, blockEntry.name);
+            const variationEntries = await fsp.readdir(blockDir, {
+                withFileTypes: true,
+            });
+            for (const variationEntry of variationEntries) {
+                if (!variationEntry.isFile() || !variationEntry.name.endsWith(".ts")) {
+                    continue;
+                }
+                const variationSlug = variationEntry.name.replace(/\.ts$/u, "");
+                if (variationSlug === "index") {
+                    continue;
+                }
+                refs.push({
+                    targetBlockName: `${namespaceEntry.name}/${blockEntry.name}`,
+                    variationSlug,
+                });
+            }
+        }
+    }
+    return refs.sort((left, right) => {
+        const leftKey = `${left.targetBlockName}/${left.variationSlug}`;
+        const rightKey = `${right.targetBlockName}/${right.variationSlug}`;
+        return leftKey.localeCompare(rightKey);
+    });
+}
+function buildCoreVariationIndexSource(refs) {
+    const importLines = refs
+        .map((ref, index) => {
+        const blockConstName = buildCoreVariationBlockConstName(ref.targetBlockName, ref.variationSlug);
+        const variationConstName = buildCoreVariationConstName(ref.targetBlockName, ref.variationSlug);
+        return `import { ${blockConstName} as CORE_VARIATION_BLOCK_${index}, ${variationConstName} as coreVariationEntry${index} } from '${buildCoreVariationImportPath(ref)}';`;
+    })
+        .join("\n");
+    const entryLines = refs
+        .map((_, index) => {
+        return `\t{ blockName: CORE_VARIATION_BLOCK_${index}, variation: coreVariationEntry${index} },`;
+    })
+        .join("\n");
+    return `import { registerBlockVariation } from '@wordpress/blocks';
+${importLines ? `\n${importLines}\n` : ""}
+const WORKSPACE_CORE_VARIATIONS = [
+${entryLines}
+] as const;
+
+export function registerWorkspaceCoreVariations() {
+\tfor (const { blockName, variation } of WORKSPACE_CORE_VARIATIONS) {
+\t\tregisterBlockVariation(blockName, variation);
+\t}
+}
+
+registerWorkspaceCoreVariations();
+`;
+}
+async function writeCoreVariationRegistry(projectDir, targetBlockName, textDomain, variationSlug) {
+    const coreVariationsDir = getCoreVariationRootDir(projectDir);
+    const targetBlockDir = getCoreVariationBlockDir(projectDir, targetBlockName);
+    const variationFilePath = getCoreVariationFilePath(projectDir, targetBlockName, variationSlug);
+    await fsp.mkdir(targetBlockDir, { recursive: true });
+    await fsp.writeFile(variationFilePath, buildCoreVariationSource({
+        targetBlockName,
+        textDomain,
+        variationSlug,
+    }), "utf8");
+    const refs = await readCoreVariationModuleRefs(coreVariationsDir);
+    await fsp.writeFile(getCoreVariationIndexPath(projectDir), buildCoreVariationIndexSource(refs), "utf8");
+}
+/**
+ * Add one editor-side variation registration for an existing core or external block.
+ *
+ * @param options Command options for the core-variation scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.targetBlockName Full `namespace/block` name that receives the variation.
+ * @param options.variationName Human-entered variation name normalized into the generated slug.
+ * @returns The normalized variation metadata and owning workspace directory.
+ * @throws {Error} When the command is run outside an official workspace, the
+ * target block name is not full `namespace/block` form, or the generated file
+ * already exists.
+ */
+export async function runAddCoreVariationCommand({ cwd = process.cwd(), targetBlockName, variationName, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const resolvedTargetBlockName = assertFullBlockName(targetBlockName, "core-variation target");
+    const variationSlug = assertValidGeneratedSlug("Core variation name", normalizeBlockSlug(variationName), CORE_VARIATION_USAGE);
+    assertCoreVariationSlugIsNotRegistryIndex(variationSlug);
+    assertCoreVariationDoesNotExist(workspace.projectDir, resolvedTargetBlockName, variationSlug);
+    const bootstrapPath = path.join(workspace.projectDir, `${workspace.packageName.split("/").pop() ?? workspace.packageName}.php`);
+    const buildScriptPath = path.join(workspace.projectDir, "scripts", "build-workspace.mjs");
+    const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
+    const editorPluginsIndexPath = await resolveEditorPluginRegistryPath(workspace.projectDir);
+    const coreVariationsDir = getCoreVariationRootDir(workspace.projectDir);
+    const targetNamespaceDir = path.join(coreVariationsDir, resolvedTargetBlockName.split("/")[0] ?? "");
+    const targetBlockDir = getCoreVariationBlockDir(workspace.projectDir, resolvedTargetBlockName);
+    const variationFilePath = getCoreVariationFilePath(workspace.projectDir, resolvedTargetBlockName, variationSlug);
+    const coreVariationsIndexPath = getCoreVariationIndexPath(workspace.projectDir);
+    const shouldRemoveCoreVariationsDir = !(await pathExists(coreVariationsDir));
+    const shouldRemoveTargetNamespaceDir = !shouldRemoveCoreVariationsDir && !(await pathExists(targetNamespaceDir));
+    const shouldRemoveTargetBlockDir = !shouldRemoveCoreVariationsDir &&
+        !shouldRemoveTargetNamespaceDir &&
+        !(await pathExists(targetBlockDir));
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            bootstrapPath,
+            buildScriptPath,
+            editorPluginsIndexPath,
+            webpackConfigPath,
+            coreVariationsIndexPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [
+            variationFilePath,
+            ...(shouldRemoveCoreVariationsDir ? [coreVariationsDir] : []),
+            ...(shouldRemoveTargetNamespaceDir ? [targetNamespaceDir] : []),
+            ...(shouldRemoveTargetBlockDir ? [targetBlockDir] : []),
+        ],
+    };
+    try {
+        await ensureEditorPluginBootstrapAnchors(workspace);
+        await ensureEditorPluginBuildScriptAnchors(workspace);
+        await ensureEditorPluginWebpackAnchors(workspace);
+        await writeCoreVariationRegistry(workspace.projectDir, resolvedTargetBlockName, workspace.workspace.textDomain, variationSlug);
+        await writeEditorPluginRegistry(workspace.projectDir, CORE_VARIATIONS_EDITOR_PLUGIN_SLUG);
+        return {
+            projectDir: workspace.projectDir,
+            targetBlockName: resolvedTargetBlockName,
+            variationFile: path.relative(workspace.projectDir, variationFilePath),
+            variationSlug,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -0,0 +1,37 @@
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Ensures the workspace bootstrap enqueues the shared editor plugin bundle.
+ *
+ * @param workspace Official workspace metadata used to locate and patch the bootstrap file.
+ * @returns A promise that resolves after the bootstrap anchors are present.
+ */
+export declare function ensureEditorPluginBootstrapAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensures the workspace build script includes the shared editor plugin entry.
+ *
+ * @param workspace Official workspace metadata used to locate the build script.
+ * @returns A promise that resolves after the build script anchors are present.
+ */
+export declare function ensureEditorPluginBuildScriptAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Ensures the workspace webpack config builds the shared editor plugin entry.
+ *
+ * @param workspace Official workspace metadata used to locate the webpack config.
+ * @returns A promise that resolves after the webpack anchors are present.
+ */
+export declare function ensureEditorPluginWebpackAnchors(workspace: WorkspaceProject): Promise<void>;
+/**
+ * Resolves the editor plugin registry path, preferring existing TypeScript or JavaScript registries.
+ *
+ * @param projectDir Workspace root directory to inspect.
+ * @returns A promise for the registry path to read or write.
+ */
+export declare function resolveEditorPluginRegistryPath(projectDir: string): Promise<string>;
+/**
+ * Rewrites the shared editor plugin registry with the requested plugin slug included.
+ *
+ * @param projectDir Workspace root directory that owns `src/editor-plugins`.
+ * @param editorPluginSlug Editor plugin slug that must be imported by the registry.
+ * @returns A promise that resolves after the registry has been written.
+ */
+export declare function writeEditorPluginRegistry(projectDir: string, editorPluginSlug: string): Promise<void>;