@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -0,0 +1,22 @@
+import { type RunAddVariationCommandOptions } from "./cli-add-shared.js";
+/**
+ * Add one variation entry to an existing workspace block.
+ *
+ * @param options Command options for the variation scaffold workflow.
+ * @param options.blockName Target workspace block slug that will own the variation.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.variationName Human-entered variation name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `blockSlug`,
+ * `variationSlug`, and owning `projectDir` after the variation files 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 the variation slug is invalid, or when a
+ * conflicting file or inventory entry already exists.
+ */
+export declare function runAddVariationCommand({ blockName, cwd, variationName, }: RunAddVariationCommandOptions): Promise<{
+    blockSlug: string;
+    projectDir: string;
+    variationSlug: string;
+}>;

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

@@ -0,0 +1,162 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { pathExists } from "./fs-async.js";
+import { assertVariationDoesNotExist, assertValidGeneratedSlug, normalizeBlockSlug, quoteTsString, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ensureWorkspaceEntrypointCall } from "./cli-add-workspace-registration-hooks.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject } from "./workspace-project.js";
+import { toKebabCase, toTitleCase } from "./string-case.js";
+const VARIATIONS_IMPORT_LINE = "import { registerWorkspaceVariations } from './variations';";
+const VARIATIONS_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceVariations\s*\}\s*from\s*["']\.\/variations["']\s*;?\s*$/mu;
+const VARIATIONS_CALL_LINE = "registerWorkspaceVariations();";
+const VARIATIONS_CALL_PATTERN = /registerWorkspaceVariations\s*\(\s*\)\s*;?/u;
+function buildVariationConfigEntry(blockSlug, variationSlug) {
+    return [
+        "\t{",
+        `\t\tblock: ${quoteTsString(blockSlug)},`,
+        `\t\tfile: ${quoteTsString(`src/blocks/${blockSlug}/variations/${variationSlug}.ts`)},`,
+        `\t\tslug: ${quoteTsString(variationSlug)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildVariationConstName(variationSlug) {
+    const identifierSegments = toKebabCase(variationSlug)
+        .split("-")
+        .filter(Boolean);
+    return `workspaceVariation_${identifierSegments.join("_")}`;
+}
+function getVariationConstBindings(variationSlugs) {
+    const seenConstNames = new Map();
+    return variationSlugs.map((variationSlug) => {
+        const constName = buildVariationConstName(variationSlug);
+        const previousSlug = seenConstNames.get(constName);
+        if (previousSlug && previousSlug !== variationSlug) {
+            throw new Error(`Variation slugs "${previousSlug}" and "${variationSlug}" generate the same registry identifier "${constName}". Rename one of the variations.`);
+        }
+        seenConstNames.set(constName, variationSlug);
+        return { constName, variationSlug };
+    });
+}
+function buildVariationSource(variationSlug, textDomain) {
+    const variationTitle = toTitleCase(variationSlug);
+    const variationConstName = buildVariationConstName(variationSlug);
+    return `import type { BlockVariation } from '@wp-typia/block-types/blocks/registration';
+import { __ } from '@wordpress/i18n';
+
+export const ${variationConstName} = {
+\tname: ${quoteTsString(variationSlug)},
+\ttitle: __( ${quoteTsString(variationTitle)}, ${quoteTsString(textDomain)} ),
+\tdescription: __(
+\t\t${quoteTsString(`A starter variation for ${variationTitle}.`)},
+\t\t${quoteTsString(textDomain)},
+\t),
+\tattributes: {},
+\tscope: ['inserter'],
+} satisfies BlockVariation;
+`;
+}
+function buildVariationIndexSource(variationSlugs) {
+    const variationBindings = getVariationConstBindings(variationSlugs);
+    const importLines = variationBindings
+        .map(({ constName, variationSlug }) => {
+        return `import { ${constName} } from './${variationSlug}';`;
+    })
+        .join("\n");
+    const variationConstNames = variationBindings
+        .map(({ constName }) => constName)
+        .join(",\n\t\t");
+    return `import { registerBlockVariation } from '@wordpress/blocks';
+import metadata from '../block.json';
+${importLines ? `\n${importLines}` : ""}
+
+const WORKSPACE_VARIATIONS = [
+\t${variationConstNames}
+\t// wp-typia add variation entries
+];
+
+export function registerWorkspaceVariations() {
+\tfor (const variation of WORKSPACE_VARIATIONS) {
+\t\tregisterBlockVariation(metadata.name, variation);
+\t}
+}
+`;
+}
+async function ensureVariationRegistrationHook(blockIndexPath) {
+    await ensureWorkspaceEntrypointCall({
+        blockIndexPath,
+        callLine: VARIATIONS_CALL_LINE,
+        callPattern: VARIATIONS_CALL_PATTERN,
+        importLine: VARIATIONS_IMPORT_LINE,
+        importPattern: VARIATIONS_IMPORT_PATTERN,
+    });
+}
+async function writeVariationRegistry(projectDir, blockSlug, variationSlug) {
+    const variationsDir = path.join(projectDir, "src", "blocks", blockSlug, "variations");
+    const variationsIndexPath = path.join(variationsDir, "index.ts");
+    await fsp.mkdir(variationsDir, { recursive: true });
+    const existingVariationSlugs = (await fsp.readdir(variationsDir))
+        .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts")
+        .map((entry) => entry.replace(/\.ts$/u, ""));
+    const nextVariationSlugs = Array.from(new Set([...existingVariationSlugs, variationSlug])).sort();
+    await fsp.writeFile(variationsIndexPath, buildVariationIndexSource(nextVariationSlugs), "utf8");
+}
+/**
+ * Add one variation entry to an existing workspace block.
+ *
+ * @param options Command options for the variation scaffold workflow.
+ * @param options.blockName Target workspace block slug that will own the variation.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.variationName Human-entered variation name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `blockSlug`,
+ * `variationSlug`, and owning `projectDir` after the variation files 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 the variation slug is invalid, or when a
+ * conflicting file or inventory entry already exists.
+ */
+export async function runAddVariationCommand({ blockName, cwd = process.cwd(), variationName, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const blockSlug = normalizeBlockSlug(blockName);
+    const variationSlug = assertValidGeneratedSlug("Variation name", normalizeBlockSlug(variationName), "wp-typia add variation <name> --block <block-slug>");
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
+    resolveWorkspaceBlock(inventory, blockSlug);
+    assertVariationDoesNotExist(workspace.projectDir, blockSlug, variationSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const blockIndexPath = path.join(workspace.projectDir, "src", "blocks", blockSlug, "index.tsx");
+    const variationsDir = path.join(workspace.projectDir, "src", "blocks", blockSlug, "variations");
+    const variationFilePath = path.join(variationsDir, `${variationSlug}.ts`);
+    const variationsIndexPath = path.join(variationsDir, "index.ts");
+    const shouldRemoveVariationsDirOnRollback = !(await pathExists(variationsDir));
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            blockIndexPath,
+            variationsIndexPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [
+            variationFilePath,
+            ...(shouldRemoveVariationsDirOnRollback ? [variationsDir] : []),
+        ],
+    };
+    try {
+        await fsp.mkdir(variationsDir, { recursive: true });
+        await fsp.writeFile(variationFilePath, buildVariationSource(variationSlug, workspace.workspace.textDomain), "utf8");
+        await writeVariationRegistry(workspace.projectDir, blockSlug, variationSlug);
+        await ensureVariationRegistrationHook(blockIndexPath);
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            variationEntries: [buildVariationConfigEntry(blockSlug, variationSlug)],
+        });
+        return {
+            blockSlug,
+            projectDir: workspace.projectDir,
+            variationSlug,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}

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

@@ -1,136 +1,71 @@
-import type { HookedBlockPositionId } from "./hooked-blocks.js";
-import { type RunAddBlockStyleCommandOptions, type RunAddBlockTransformCommandOptions, type RunAddHookedBlockCommandOptions, type RunAddVariationCommandOptions } from "./cli-add-shared.js";
+/**
+ * Compatibility facade for workspace add commands.
+ *
+ * Keep the public runtime import path stable while each workflow lives in a
+ * focused implementation module.
+ */
+/**
+ * Re-export the typed workflow ability scaffold workflow from the focused
+ * ability runtime helper module.
+ */
+export { runAddAbilityCommand } from "./cli-add-workspace-ability.js";
 /**
  * Re-export the DataViews admin screen scaffold workflow from the focused
  * admin-view runtime helper module.
  */
-export { runAddAdminViewCommand, } from "./cli-add-workspace-admin-view.js";
+export { runAddAdminViewCommand } from "./cli-add-workspace-admin-view.js";
+/**
+ * Re-export the server-only AI feature scaffold workflow from the focused
+ * AI-feature runtime helper module.
+ */
+export { runAddAiFeatureCommand } from "./cli-add-workspace-ai.js";
 /**
  * Re-export focused workspace asset scaffold commands from the companion
  * `cli-add-workspace-assets` module.
  */
-export { runAddEditorPluginCommand, runAddBindingSourceCommand, runAddPatternCommand, } from "./cli-add-workspace-assets.js";
+export { runAddBindingSourceCommand, runAddEditorPluginCommand, runAddPatternCommand, } from "./cli-add-workspace-assets.js";
 /**
- * Re-export the local integration environment scaffold workflow from the
- * focused integration-env runtime helper module.
+ * Re-export the block style scaffold workflow from the focused block-style
+ * runtime helper module.
  */
-export { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
+export { runAddBlockStyleCommand } from "./cli-add-workspace-block-style.js";
 /**
- * Re-export the plugin-level REST resource scaffold workflow from the focused
- * rest-resource runtime helper module.
+ * Re-export the block transform scaffold workflow from the focused
+ * block-transform runtime helper module.
  */
-export { runAddRestResourceCommand } from "./cli-add-workspace-rest.js";
+export { runAddBlockTransformCommand, } from "./cli-add-workspace-block-transform.js";
 /**
  * Re-export the standalone contract scaffold workflow from the focused
  * contract runtime helper module.
  */
 export { runAddContractCommand } from "./cli-add-workspace-contract.js";
 /**
- * Re-export the typed post-meta contract scaffold workflow from the focused
- * post-meta runtime helper module.
+ * Re-export the generic core/external block variation scaffold workflow from
+ * the focused core-variation runtime helper module.
  */
-export { runAddPostMetaCommand } from "./cli-add-workspace-post-meta.js";
+export { runAddCoreVariationCommand } from "./cli-add-workspace-core-variation.js";
 /**
- * Re-export the typed workflow ability scaffold workflow from the focused
- * ability runtime helper module.
+ * Re-export the hooked-block scaffold workflow from the focused hooked-block
+ * runtime helper module.
  */
-export { runAddAbilityCommand } from "./cli-add-workspace-ability.js";
+export { runAddHookedBlockCommand } from "./cli-add-workspace-hooked-block.js";
 /**
- * Re-export the server-only AI feature scaffold workflow from the focused
- * AI-feature runtime helper module.
- */
-export { runAddAiFeatureCommand } from "./cli-add-workspace-ai.js";
-/**
- * Add one variation entry to an existing workspace block.
- *
- * @param options Command options for the variation scaffold workflow.
- * @param options.blockName Target workspace block slug that will own the variation.
- * @param options.cwd Working directory used to resolve the nearest official workspace.
- * Defaults to `process.cwd()`.
- * @param options.variationName Human-entered variation name that will be normalized
- * and validated before files are written.
- * @returns A promise that resolves with the normalized `blockSlug`,
- * `variationSlug`, and owning `projectDir` after the variation files 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 the variation slug is invalid, or when a
- * conflicting file or inventory entry already exists.
+ * Re-export the local integration environment scaffold workflow from the
+ * focused integration-env runtime helper module.
  */
-export declare function runAddVariationCommand({ blockName, cwd, variationName, }: RunAddVariationCommandOptions): Promise<{
-    blockSlug: string;
-    projectDir: string;
-    variationSlug: string;
-}>;
+export { runAddIntegrationEnvCommand } from "./cli-add-workspace-integration-env.js";
 /**
- * Add one Block Styles registration to an existing workspace block.
- *
- * @param options Command options for the Block Styles scaffold workflow.
- * @param options.blockName Target workspace block slug that will own the style.
- * @param options.cwd Working directory used to resolve the nearest official workspace.
- * Defaults to `process.cwd()`.
- * @param options.styleName Human-entered style name that will be normalized and
- * validated before files are written.
- * @returns A promise that resolves with the normalized `blockSlug`, `styleSlug`,
- * and owning `projectDir` after the style module, style 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 the style slug is invalid, or when a
- * conflicting file or inventory entry already exists.
+ * Re-export the typed post-meta contract scaffold workflow from the focused
+ * post-meta runtime helper module.
  */
-export declare function runAddBlockStyleCommand({ blockName, cwd, styleName, }: RunAddBlockStyleCommandOptions): Promise<{
-    blockSlug: string;
-    projectDir: string;
-    styleSlug: string;
-}>;
+export { runAddPostMetaCommand } from "./cli-add-workspace-post-meta.js";
 /**
- * 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.
+ * Re-export the plugin-level REST resource scaffold workflow from the focused
+ * rest-resource runtime helper module.
  */
-export declare function runAddBlockTransformCommand({ cwd, fromBlockName, toBlockName, transformName, }: RunAddBlockTransformCommandOptions): Promise<{
-    blockSlug: string;
-    fromBlockName: string;
-    projectDir: string;
-    toBlockName: string;
-    transformSlug: string;
-}>;
+export { runAddRestResourceCommand } from "./cli-add-workspace-rest.js";
 /**
- * Add one `blockHooks` entry to an existing official workspace block.
- *
- * @param options Command options for the hooked-block workflow.
- * @param options.anchorBlockName Full block name that will anchor the insertion.
- * @param options.blockName Existing workspace block slug to patch.
- * @param options.cwd Working directory used to resolve the nearest official workspace.
- * Defaults to `process.cwd()`.
- * @param options.position Hook position to store in `block.json`.
- * @returns A promise that resolves with the normalized target block slug, anchor
- * block name, position, and owning project directory after `block.json` is written.
- * @throws {Error} When the command is run outside an official workspace, when
- * the target block is unknown, when required flags are missing, or when the
- * block already defines a hook for the requested anchor.
+ * Re-export the block variation scaffold workflow from the focused variation
+ * runtime helper module.
  */
-export declare function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd, position, }: RunAddHookedBlockCommandOptions): Promise<{
-    anchorBlockName: string;
-    blockSlug: string;
-    position: HookedBlockPositionId;
-    projectDir: string;
-}>;
+export { runAddVariationCommand } from "./cli-add-workspace-variation.js";