@wp-typia/project-tools 0.11.1 → 0.12.0

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

@@ -1,3 +1,4 @@
+import { getWorkspaceBlockSelectOptions } from "./workspace-inventory.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
@@ -8,6 +9,15 @@ export type AddKindId = (typeof ADD_KIND_IDS)[number];
  */
 export declare const ADD_BLOCK_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
 export type AddBlockTemplateId = (typeof ADD_BLOCK_TEMPLATE_IDS)[number];
+interface RunAddVariationCommandOptions {
+    blockName: string;
+    cwd?: string;
+    variationName: string;
+}
+interface RunAddPatternCommandOptions {
+    cwd?: string;
+    patternName: string;
+}
 interface RunAddBlockCommandOptions {
     blockName: string;
     cwd?: string;
@@ -32,7 +42,43 @@ export declare function runAddBlockCommand({ blockName, cwd, dataStorageMode, pe
     templateId: AddBlockTemplateId;
 }>;
 /**
- * Returns the current placeholder guidance for unsupported `wp-typia add` kinds.
+ * 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 createAddPlaceholderMessage(kind: Exclude<AddKindId, "block">): string;
-export {};
+export declare function runAddVariationCommand({ blockName, cwd, variationName, }: RunAddVariationCommandOptions): Promise<{
+    blockSlug: string;
+    projectDir: string;
+    variationSlug: string;
+}>;
+/**
+ * Add one PHP block pattern shell to an official workspace project.
+ *
+ * @param options Command options for the pattern scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.patternName Human-entered pattern name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `patternSlug` and
+ * owning `projectDir` after the pattern file and inventory entry have been
+ * written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the pattern slug is invalid, or when a conflicting file or inventory entry
+ * already exists.
+ */
+export declare function runAddPatternCommand({ cwd, patternName, }: RunAddPatternCommandOptions): Promise<{
+    patternSlug: string;
+    projectDir: string;
+}>;
+export { getWorkspaceBlockSelectOptions };

package/dist/runtime/cli-add.js

@@ -8,7 +8,9 @@ import { snapshotProjectVersion } from "./migrations.js";
 import { getDefaultAnswers, scaffoldProject } from "./scaffold.js";
 import { SHARED_WORKSPACE_TEMPLATE_ROOT, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { toKebabCase, toSnakeCase, } from "./string-case.js";
+import { toKebabCase, toTitleCase, toSnakeCase, } from "./string-case.js";
+import { appendWorkspaceInventoryEntries, getWorkspaceBlockSelectOptions, readWorkspaceInventory, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject, WORKSPACE_TEMPLATE_PACKAGE, } from "./workspace-project.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
@@ -22,26 +24,28 @@ export const ADD_BLOCK_TEMPLATE_IDS = [
     "persistence",
     "compound",
 ];
-const WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
-const BLOCK_CONFIG_ENTRY_MARKER = "\t// wp-typia add block entries";
 const COLLECTION_IMPORT_LINE = "import '../../collection';";
-const EMPTY_BLOCKS_ARRAY = `${BLOCK_CONFIG_ENTRY_MARKER}\n];`;
 const REST_MANIFEST_IMPORT_PATTERN = /import\s*\{[^}]*\bdefineEndpointManifest\b[^}]*\}\s*from\s*["']@wp-typia\/block-runtime\/metadata-core["'];?/m;
-function parsePackageManagerId(packageManagerField) {
-    const packageManagerId = packageManagerField?.split("@", 1)[0];
-    switch (packageManagerId) {
-        case "bun":
-        case "npm":
-        case "pnpm":
-        case "yarn":
-            return packageManagerId;
-        default:
-            return "bun";
-    }
-}
+const VARIATIONS_IMPORT_LINE = "import { registerWorkspaceVariations } from './variations';";
+const VARIATIONS_CALL_LINE = "registerWorkspaceVariations();";
+const PATTERN_BOOTSTRAP_CATEGORY = "register_block_pattern_category";
+const WORKSPACE_GENERATED_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 function normalizeBlockSlug(input) {
     return toKebabCase(input);
 }
+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;
+}
+function getWorkspaceBootstrapPath(workspace) {
+    const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+    return path.join(workspace.projectDir, `${workspaceBaseName}.php`);
+}
 function buildWorkspacePhpPrefix(workspacePhpPrefix, slug) {
     return toSnakeCase(`${workspacePhpPrefix}_${slug}`);
 }
@@ -263,6 +267,205 @@ async function addCollectionImportsForTemplate(projectDir, templateId, variables
     }
     await ensureCollectionImport(path.join(projectDir, "src", "blocks", variables.slugKebabCase, "index.tsx"));
 }
+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 buildPatternConfigEntry(patternSlug) {
+    return [
+        "\t{",
+        `\t\tfile: ${quoteTsString(`src/patterns/${patternSlug}.php`)},`,
+        `\t\tslug: ${quoteTsString(patternSlug)},`,
+        "\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 '@wordpress/blocks';
+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}
+}
+`;
+}
+function buildPatternSource(patternSlug, namespace, textDomain) {
+    const patternTitle = toTitleCase(patternSlug);
+    return `<?php
+if ( ! defined( 'ABSPATH' ) ) {
+\treturn;
+}
+
+register_block_pattern(
+\t'${namespace}/${patternSlug}',
+\tarray(
+\t\t'title'       => __( ${JSON.stringify(patternTitle)}, '${textDomain}' ),
+\t\t'description' => __( ${JSON.stringify(`A starter pattern for ${patternTitle}.`)}, '${textDomain}' ),
+\t\t'categories'  => array( '${namespace}' ),
+\t\t'content'     => '<!-- wp:paragraph --><p>' . esc_html__( 'Describe this pattern here.', '${textDomain}' ) . '</p><!-- /wp:paragraph -->',
+\t)
+);
+`;
+}
+async function ensureVariationRegistrationHook(blockIndexPath) {
+    await patchFile(blockIndexPath, (source) => {
+        let nextSource = source;
+        if (!nextSource.includes(VARIATIONS_IMPORT_LINE)) {
+            nextSource = `${VARIATIONS_IMPORT_LINE}\n${nextSource}`;
+        }
+        if (!nextSource.includes(VARIATIONS_CALL_LINE)) {
+            const callInsertionPatterns = [
+                /(registerBlockType<[\s\S]*?\);\s*)/u,
+                /(registerBlockType\([\s\S]*?\);\s*)/u,
+            ];
+            let inserted = false;
+            for (const pattern of callInsertionPatterns) {
+                const candidate = nextSource.replace(pattern, (match) => `${match}\n${VARIATIONS_CALL_LINE}\n`);
+                if (candidate !== nextSource) {
+                    nextSource = candidate;
+                    inserted = true;
+                    break;
+                }
+            }
+            if (!inserted) {
+                nextSource = `${nextSource.trimEnd()}\n\n${VARIATIONS_CALL_LINE}\n`;
+            }
+        }
+        if (!nextSource.includes(VARIATIONS_CALL_LINE)) {
+            throw new Error(`Unable to inject ${VARIATIONS_CALL_LINE} into ${path.basename(blockIndexPath)}.`);
+        }
+        return nextSource;
+    });
+}
+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 = fs.existsSync(variationsDir)
+        ? fs
+            .readdirSync(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");
+}
+async function ensurePatternBootstrapAnchors(workspace) {
+    const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    await patchFile(bootstrapPath, (source) => {
+        let nextSource = source;
+        const patternCategoryFunctionName = `${workspace.workspace.phpPrefix}_register_pattern_category`;
+        const patternRegistrationFunctionName = `${workspace.workspace.phpPrefix}_register_patterns`;
+        const patternCategoryHook = `add_action( 'init', '${patternCategoryFunctionName}' );`;
+        const patternRegistrationHook = `add_action( 'init', '${patternRegistrationFunctionName}', 20 );`;
+        const patternFunctions = `
+
+function ${patternCategoryFunctionName}() {
+\tif ( function_exists( 'register_block_pattern_category' ) ) {
+\t\tregister_block_pattern_category(
+\t\t\t'${workspace.workspace.namespace}',
+\t\t\tarray(
+\t\t\t\t'label' => __( ${JSON.stringify(`${toTitleCase(workspaceBaseName)} Patterns`)}, '${workspace.workspace.textDomain}' ),
+\t\t\t)
+\t\t);
+\t}
+}
+
+function ${patternRegistrationFunctionName}() {
+\tforeach ( glob( __DIR__ . '/src/patterns/*.php' ) ?: array() as $pattern_module ) {
+\t\trequire $pattern_module;
+\t}
+}
+`;
+        if (!nextSource.includes(PATTERN_BOOTSTRAP_CATEGORY)) {
+            const insertionAnchors = [
+                /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
+                /\?>\s*$/u,
+            ];
+            let inserted = false;
+            for (const anchor of insertionAnchors) {
+                const candidate = nextSource.replace(anchor, (match) => `${patternFunctions}\n${match}`);
+                if (candidate !== nextSource) {
+                    nextSource = candidate;
+                    inserted = true;
+                    break;
+                }
+            }
+            if (!inserted) {
+                nextSource = `${nextSource.trimEnd()}\n${patternFunctions}\n`;
+            }
+        }
+        if (!nextSource.includes(patternCategoryFunctionName) ||
+            !nextSource.includes(patternRegistrationFunctionName)) {
+            throw new Error(`Unable to inject pattern bootstrap functions into ${path.basename(bootstrapPath)}.`);
+        }
+        if (!nextSource.includes(patternCategoryHook)) {
+            nextSource = `${nextSource.trimEnd()}\n${patternCategoryHook}\n`;
+        }
+        if (!nextSource.includes(patternRegistrationHook)) {
+            nextSource = `${nextSource.trimEnd()}\n${patternRegistrationHook}\n`;
+        }
+        return nextSource;
+    });
+}
 function ensureBlockConfigCanAddRestManifests(source) {
     const importLine = "import { defineEndpointManifest } from '@wp-typia/block-runtime/metadata-core';";
     if (REST_MANIFEST_IMPORT_PATTERN.test(source)) {
@@ -271,21 +474,18 @@ function ensureBlockConfigCanAddRestManifests(source) {
     return `${importLine}\n\n${source}`;
 }
 async function appendBlockConfigEntries(projectDir, entries, needsRestManifestImport) {
-    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
-    await patchFile(blockConfigPath, (source) => {
-        let nextSource = source;
-        if (needsRestManifestImport) {
-            nextSource = ensureBlockConfigCanAddRestManifests(nextSource);
-        }
-        if (nextSource.includes(BLOCK_CONFIG_ENTRY_MARKER)) {
-            return nextSource.replace(BLOCK_CONFIG_ENTRY_MARKER, `${entries.join("\n")}\n${BLOCK_CONFIG_ENTRY_MARKER}`);
-        }
-        if (nextSource.includes(EMPTY_BLOCKS_ARRAY)) {
-            return nextSource.replace(EMPTY_BLOCKS_ARRAY, `${entries.join("\n")}\n];`);
-        }
-        return nextSource.replace("];", `${entries.join("\n")}\n];`);
+    await appendWorkspaceInventoryEntries(projectDir, {
+        blockEntries: entries,
+        transformSource: needsRestManifestImport ? ensureBlockConfigCanAddRestManifests : undefined,
     });
 }
+async function snapshotWorkspaceFiles(filePaths) {
+    const uniquePaths = Array.from(new Set(filePaths));
+    return Promise.all(uniquePaths.map(async (filePath) => ({
+        filePath,
+        source: await readOptionalFile(filePath),
+    })));
+}
 async function renderWorkspacePersistenceServerModule(projectDir, variables) {
     const targetDir = path.join(projectDir, "src", "blocks", variables.slugKebabCase);
     const templateDir = buildServerTemplateRoot(variables.persistencePolicy);
@@ -387,39 +587,6 @@ async function syncWorkspaceAddedBlockArtifacts(projectDir, templateId, variable
         await syncWorkspacePersistenceArtifacts(projectDir, variables);
     }
 }
-function resolveWorkspaceProject(startDir) {
-    let currentDir = path.resolve(startDir);
-    while (true) {
-        const packageJsonPath = path.join(currentDir, "package.json");
-        if (fs.existsSync(packageJsonPath)) {
-            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-            if (packageJson.wpTypia?.projectType === "workspace" &&
-                packageJson.wpTypia?.templatePackage === WORKSPACE_TEMPLATE_PACKAGE &&
-                typeof packageJson.wpTypia.namespace === "string" &&
-                typeof packageJson.wpTypia.textDomain === "string" &&
-                typeof packageJson.wpTypia.phpPrefix === "string") {
-                return {
-                    author: typeof packageJson.author === "string" ? packageJson.author : "Your Name",
-                    packageManager: parsePackageManagerId(packageJson.packageManager),
-                    projectDir: currentDir,
-                    workspace: {
-                        namespace: packageJson.wpTypia.namespace,
-                        phpPrefix: packageJson.wpTypia.phpPrefix,
-                        projectType: "workspace",
-                        templatePackage: WORKSPACE_TEMPLATE_PACKAGE,
-                        textDomain: packageJson.wpTypia.textDomain,
-                    },
-                };
-            }
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
-            break;
-        }
-        currentDir = parentDir;
-    }
-    throw new Error(`This command must run inside a ${WORKSPACE_TEMPLATE_PACKAGE} project. Create one with \`wp-typia create my-plugin --template ${WORKSPACE_TEMPLATE_PACKAGE}\` first.`);
-}
 function assertPersistenceFlagsAllowed(templateId, options) {
     const hasPersistenceFlags = typeof options.dataStorageMode === "string" ||
         typeof options.persistencePolicy === "string";
@@ -447,12 +614,13 @@ function assertPersistenceFlagsAllowed(templateId, options) {
 export function formatAddHelpText() {
     return `Usage:
   wp-typia add block <name> --template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}> [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
-  wp-typia add variation
-  wp-typia add pattern
+  wp-typia add variation <name> --block <block-slug>
+  wp-typia add pattern <name>
 
 Notes:
-  \`wp-typia add block\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces.
-  \`wp-typia add variation\` and \`wp-typia add pattern\` are reserved placeholders for follow-up workflows.`;
+  \`wp-typia add\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces.
+  \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
+  \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.`;
 }
 /**
  * Seeds an empty official workspace migration project before any blocks are added.
@@ -467,15 +635,16 @@ export async function seedWorkspaceMigrationProject(projectDir, currentMigration
     ensureMigrationDirectories(projectDir, []);
     writeInitialMigrationScaffold(projectDir, currentMigrationVersion, []);
 }
-async function rollbackWorkspaceMutation(projectDir, snapshot) {
+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 });
     }
-    await restoreOptionalFile(path.join(projectDir, "scripts", "block-config.ts"), snapshot.blockConfigSource);
-    await restoreOptionalFile(path.join(projectDir, "src", "migrations", "config.ts"), snapshot.migrationConfigSource);
+    for (const { filePath, source } of snapshot.fileSources) {
+        await restoreOptionalFile(filePath, source);
+    }
 }
 /**
  * Adds one built-in block slice to an official workspace project.
@@ -496,9 +665,10 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
     try {
         tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-add-block-"));
         const tempProjectDir = path.join(tempRoot, normalizedSlug);
+        const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+        const migrationConfigPath = path.join(workspace.projectDir, "src", "migrations", "config.ts");
         const blockPhpPrefix = buildWorkspacePhpPrefix(workspace.workspace.phpPrefix, normalizedSlug);
-        const blockConfigSource = await readOptionalFile(path.join(workspace.projectDir, "scripts", "block-config.ts"));
-        const migrationConfigSource = await readOptionalFile(path.join(workspace.projectDir, "src", "migrations", "config.ts"));
+        const migrationConfigSource = await readOptionalFile(migrationConfigPath);
         const migrationConfig = migrationConfigSource === null ? null : parseMigrationConfig(migrationConfigSource);
         const result = await scaffoldProject({
             answers: {
@@ -520,8 +690,7 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
         });
         assertBlockTargetsDoNotExist(workspace.projectDir, resolvedTemplateId, result.variables);
         const mutationSnapshot = {
-            blockConfigSource,
-            migrationConfigSource,
+            fileSources: await snapshotWorkspaceFiles([blockConfigPath, migrationConfigPath]),
             snapshotDirs: migrationConfig === null
                 ? []
                 : buildMigrationBlocks(resolvedTemplateId, result.variables).map((block) => path.join(workspace.projectDir, ...migrationConfig.snapshotDir.split("/"), migrationConfig.currentMigrationVersion, block.key)),
@@ -542,7 +711,7 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
             };
         }
         catch (error) {
-            await rollbackWorkspaceMutation(workspace.projectDir, mutationSnapshot);
+            await rollbackWorkspaceMutation(mutationSnapshot);
             throw error;
         }
     }
@@ -552,10 +721,130 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
         }
     }
 }
+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;
+}
+function assertVariationDoesNotExist(projectDir, blockSlug, variationSlug, inventory) {
+    const variationPath = path.join(projectDir, "src", "blocks", blockSlug, "variations", `${variationSlug}.ts`);
+    if (fs.existsSync(variationPath)) {
+        throw new Error(`A variation already exists at ${path.relative(projectDir, variationPath)}. Choose a different name.`);
+    }
+    if (inventory.variations.some((entry) => entry.block === blockSlug && entry.slug === variationSlug)) {
+        throw new Error(`A variation inventory entry already exists for ${blockSlug}/${variationSlug}. Choose a different name.`);
+    }
+}
+function assertPatternDoesNotExist(projectDir, patternSlug, inventory) {
+    const patternPath = path.join(projectDir, "src", "patterns", `${patternSlug}.php`);
+    if (fs.existsSync(patternPath)) {
+        throw new Error(`A pattern already exists at ${path.relative(projectDir, patternPath)}. Choose a different name.`);
+    }
+    if (inventory.patterns.some((entry) => entry.slug === patternSlug)) {
+        throw new Error(`A pattern inventory entry already exists for ${patternSlug}. Choose a different name.`);
+    }
+}
+/**
+ * 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 = readWorkspaceInventory(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 mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([
+            blockConfigPath,
+            blockIndexPath,
+            variationsIndexPath,
+        ]),
+        snapshotDirs: [],
+        targetPaths: [variationFilePath],
+    };
+    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;
+    }
+}
 /**
- * Returns the current placeholder guidance for unsupported `wp-typia add` kinds.
+ * Add one PHP block pattern shell to an official workspace project.
+ *
+ * @param options Command options for the pattern scaffold workflow.
+ * @param options.cwd Working directory used to resolve the nearest official workspace.
+ * Defaults to `process.cwd()`.
+ * @param options.patternName Human-entered pattern name that will be normalized
+ * and validated before files are written.
+ * @returns A promise that resolves with the normalized `patternSlug` and
+ * owning `projectDir` after the pattern file and inventory entry have been
+ * written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the pattern slug is invalid, or when a conflicting file or inventory entry
+ * already exists.
  */
-export function createAddPlaceholderMessage(kind) {
-    const issueNumber = kind === "variation" ? "#157" : "#158";
-    return `\`wp-typia add ${kind}\` is not implemented yet. Track ${issueNumber} for the first supported ${kind} workflow.`;
+export async function runAddPatternCommand({ cwd = process.cwd(), patternName, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const patternSlug = assertValidGeneratedSlug("Pattern name", normalizeBlockSlug(patternName), "wp-typia add pattern <name>");
+    const inventory = readWorkspaceInventory(workspace.projectDir);
+    assertPatternDoesNotExist(workspace.projectDir, patternSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    const patternFilePath = path.join(workspace.projectDir, "src", "patterns", `${patternSlug}.php`);
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([blockConfigPath, bootstrapPath]),
+        snapshotDirs: [],
+        targetPaths: [patternFilePath],
+    };
+    try {
+        await fsp.mkdir(path.dirname(patternFilePath), { recursive: true });
+        await ensurePatternBootstrapAnchors(workspace);
+        await fsp.writeFile(patternFilePath, buildPatternSource(patternSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            patternEntries: [buildPatternConfigEntry(patternSlug)],
+        });
+        return {
+            patternSlug,
+            projectDir: workspace.projectDir,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
 }
+export { getWorkspaceBlockSelectOptions };

package/dist/runtime/cli-core.d.ts

@@ -6,7 +6,8 @@
  * `packages/wp-typia`.
  *
  * Import `formatAddHelpText`, `runAddBlockCommand`,
- * `createAddPlaceholderMessage`, and `seedWorkspaceMigrationProject` for
+ * `runAddVariationCommand`, `runAddPatternCommand`,
+ * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
  * `formatHelpText` for top-level CLI usage output, scaffold helpers such as
@@ -18,7 +19,7 @@
  * template inspection flows.
  */
 export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
-export { createAddPlaceholderMessage, formatAddHelpText, runAddBlockCommand, seedWorkspaceMigrationProject } from "./cli-add.js";
+export { formatAddHelpText, getWorkspaceBlockSelectOptions, runAddBlockCommand, runAddPatternCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { formatHelpText } from "./cli-help.js";
 export { getNextSteps, getOptionalOnboarding, runScaffoldFlow, } from "./cli-scaffold.js";
 export { createReadlinePrompt, type ReadlinePrompt } from "./cli-prompt.js";

package/dist/runtime/cli-core.js

@@ -6,7 +6,8 @@
  * `packages/wp-typia`.
  *
  * Import `formatAddHelpText`, `runAddBlockCommand`,
- * `createAddPlaceholderMessage`, and `seedWorkspaceMigrationProject` for
+ * `runAddVariationCommand`, `runAddPatternCommand`,
+ * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
  * `formatHelpText` for top-level CLI usage output, scaffold helpers such as
@@ -18,7 +19,7 @@
  * template inspection flows.
  */
 export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
-export { createAddPlaceholderMessage, formatAddHelpText, runAddBlockCommand, seedWorkspaceMigrationProject } from "./cli-add.js";
+export { formatAddHelpText, getWorkspaceBlockSelectOptions, runAddBlockCommand, runAddPatternCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { formatHelpText } from "./cli-help.js";
 export { getNextSteps, getOptionalOnboarding, runScaffoldFlow, } from "./cli-scaffold.js";
 export { createReadlinePrompt } from "./cli-prompt.js";