@wp-typia/project-tools 0.11.1 → 0.13.0

package/dist/runtime/cli-add.js

@@ -8,11 +8,14 @@ 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 { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
+import { resolveWorkspaceProject, WORKSPACE_TEMPLATE_PACKAGE, } from "./workspace-project.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
-export const ADD_KIND_IDS = ["block", "variation", "pattern"];
+export const ADD_KIND_IDS = ["block", "variation", "pattern", "binding-source", "hooked-block"];
 /**
  * Supported built-in block families accepted by `wp-typia add block --template`.
  */
@@ -22,26 +25,37 @@ 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 BINDING_SOURCE_SERVER_GLOB = "/src/bindings/*/server.php";
+const BINDING_SOURCE_EDITOR_SCRIPT = "build/bindings/index.js";
+const BINDING_SOURCE_EDITOR_ASSET = "build/bindings/index.asset.php";
+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 assertValidHookedBlockPosition(position) {
+    if (HOOKED_BLOCK_POSITION_IDS.includes(position)) {
+        return position;
+    }
+    throw new Error(`Hook position must be one of: ${HOOKED_BLOCK_POSITION_IDS.join(", ")}.`);
+}
+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 +277,357 @@ 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 buildBindingSourceConfigEntry(bindingSourceSlug) {
+    return [
+        "\t{",
+        `\t\teditorFile: ${quoteTsString(`src/bindings/${bindingSourceSlug}/editor.ts`)},`,
+        `\t\tserverFile: ${quoteTsString(`src/bindings/${bindingSourceSlug}/server.php`)},`,
+        `\t\tslug: ${quoteTsString(bindingSourceSlug)},`,
+        "\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)
+);
+`;
+}
+function buildBindingSourceServerSource(bindingSourceSlug, namespace, textDomain) {
+    const bindingSourceTitle = toTitleCase(bindingSourceSlug);
+    return `<?php
+if ( ! defined( 'ABSPATH' ) ) {
+\treturn;
+}
+
+if ( ! function_exists( 'register_block_bindings_source' ) ) {
+\treturn;
+}
+
+register_block_bindings_source(
+\t'${namespace}/${bindingSourceSlug}',
+\tarray(
+\t\t'label' => __( ${JSON.stringify(bindingSourceTitle)}, '${textDomain}' ),
+\t\t'get_value_callback' => static function( array $source_args ) : string {
+\t\t\t$field = isset( $source_args['field'] ) && is_string( $source_args['field'] )
+\t\t\t\t? $source_args['field']
+\t\t\t\t: '${bindingSourceSlug}';
+
+\t\t\treturn sprintf(
+\t\t\t\t__( 'Replace %s with real binding source data.', '${textDomain}' ),
+\t\t\t\t$field
+\t\t\t);
+\t\t},
+\t)
+);
+`;
+}
+function buildBindingSourceEditorSource(bindingSourceSlug, namespace, textDomain) {
+    const bindingSourceTitle = toTitleCase(bindingSourceSlug);
+    return `import { registerBlockBindingsSource } from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+
+registerBlockBindingsSource( {
+\tname: ${quoteTsString(`${namespace}/${bindingSourceSlug}`)},
+\tlabel: __( ${quoteTsString(bindingSourceTitle)}, ${quoteTsString(textDomain)} ),
+\tgetFieldsList() {
+\t\treturn [
+\t\t\t{
+\t\t\t\tlabel: __( ${quoteTsString(bindingSourceTitle)}, ${quoteTsString(textDomain)} ),
+\t\t\t\ttype: 'string',
+\t\t\t\targs: {
+\t\t\t\t\tfield: ${quoteTsString(bindingSourceSlug)},
+\t\t\t\t},
+\t\t\t},
+\t\t];
+\t},
+\tgetValues( { bindings } ) {
+\t\tconst values: Record<string, string> = {};
+\t\tfor ( const attributeName of Object.keys( bindings ) ) {
+\t\t\tvalues[ attributeName ] = ${quoteTsString(`TODO: replace ${bindingSourceSlug} with real editor-side values.`)};
+\t\t}
+\t\treturn values;
+\t},
+} );
+`;
+}
+function buildBindingSourceIndexSource(bindingSourceSlugs) {
+    const importLines = bindingSourceSlugs
+        .map((bindingSourceSlug) => `import './${bindingSourceSlug}/editor';`)
+        .join("\n");
+    return `${importLines}${importLines ? "\n\n" : ""}// wp-typia add binding-source entries\n`;
+}
+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;
+    });
+}
+async function ensureBindingSourceBootstrapAnchors(workspace) {
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    await patchFile(bootstrapPath, (source) => {
+        let nextSource = source;
+        const workspaceBaseName = workspace.packageName.split("/").pop() ?? workspace.packageName;
+        const bindingRegistrationFunctionName = `${workspace.workspace.phpPrefix}_register_binding_sources`;
+        const bindingEditorEnqueueFunctionName = `${workspace.workspace.phpPrefix}_enqueue_binding_sources_editor`;
+        const bindingRegistrationHook = `add_action( 'init', '${bindingRegistrationFunctionName}', 20 );`;
+        const bindingEditorEnqueueHook = `add_action( 'enqueue_block_editor_assets', '${bindingEditorEnqueueFunctionName}' );`;
+        const bindingRegistrationFunction = `
+
+function ${bindingRegistrationFunctionName}() {
+\tforeach ( glob( __DIR__ . '${BINDING_SOURCE_SERVER_GLOB}' ) ?: array() as $binding_source_module ) {
+\t\trequire_once $binding_source_module;
+\t}
+}
+`;
+        const bindingEditorEnqueueFunction = `
+
+function ${bindingEditorEnqueueFunctionName}() {
+\t$script_path = __DIR__ . '/${BINDING_SOURCE_EDITOR_SCRIPT}';
+\t$asset_path  = __DIR__ . '/${BINDING_SOURCE_EDITOR_ASSET}';
+
+\tif ( ! file_exists( $script_path ) || ! file_exists( $asset_path ) ) {
+\t\treturn;
+\t}
+
+\t$asset = require $asset_path;
+\tif ( ! is_array( $asset ) ) {
+\t\t$asset = array();
+\t}
+
+\twp_enqueue_script(
+\t\t'${workspaceBaseName}-binding-sources',
+\t\tplugins_url( '${BINDING_SOURCE_EDITOR_SCRIPT}', __FILE__ ),
+\t\tisset( $asset['dependencies'] ) && is_array( $asset['dependencies'] ) ? $asset['dependencies'] : array(),
+\t\tisset( $asset['version'] ) ? $asset['version'] : filemtime( $script_path ),
+\t\ttrue
+\t);
+}
+`;
+        const insertionAnchors = [
+            /add_action\(\s*["']init["']\s*,\s*["'][^"']+_load_textdomain["']\s*\);\s*\n/u,
+            /\?>\s*$/u,
+        ];
+        const hasPhpFunctionDefinition = (functionName) => new RegExp(`function\\s+${functionName}\\s*\\(`, "u").test(nextSource);
+        const insertPhpSnippet = (snippet) => {
+            for (const anchor of insertionAnchors) {
+                const candidate = nextSource.replace(anchor, (match) => `${snippet}\n${match}`);
+                if (candidate !== nextSource) {
+                    nextSource = candidate;
+                    return;
+                }
+            }
+            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
+        };
+        const appendPhpSnippet = (snippet) => {
+            const closingTagPattern = /\?>\s*$/u;
+            if (closingTagPattern.test(nextSource)) {
+                nextSource = nextSource.replace(closingTagPattern, `${snippet}\n?>`);
+                return;
+            }
+            nextSource = `${nextSource.trimEnd()}\n${snippet}\n`;
+        };
+        if (!hasPhpFunctionDefinition(bindingRegistrationFunctionName)) {
+            insertPhpSnippet(bindingRegistrationFunction);
+        }
+        if (!hasPhpFunctionDefinition(bindingEditorEnqueueFunctionName)) {
+            insertPhpSnippet(bindingEditorEnqueueFunction);
+        }
+        if (!nextSource.includes(bindingRegistrationHook)) {
+            appendPhpSnippet(bindingRegistrationHook);
+        }
+        if (!nextSource.includes(bindingEditorEnqueueHook)) {
+            appendPhpSnippet(bindingEditorEnqueueHook);
+        }
+        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 +636,35 @@ 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 writeBindingSourceRegistry(projectDir, bindingSourceSlug) {
+    const bindingsDir = path.join(projectDir, "src", "bindings");
+    const bindingsIndexPath = resolveBindingSourceRegistryPath(projectDir);
+    await fsp.mkdir(bindingsDir, { recursive: true });
+    const existingBindingSourceSlugs = fs.existsSync(bindingsDir)
+        ? fs
+            .readdirSync(bindingsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+        : [];
+    const nextBindingSourceSlugs = Array.from(new Set([...existingBindingSourceSlugs, bindingSourceSlug])).sort();
+    await fsp.writeFile(bindingsIndexPath, buildBindingSourceIndexSource(nextBindingSourceSlugs), "utf8");
+}
+function resolveBindingSourceRegistryPath(projectDir) {
+    const bindingsDir = path.join(projectDir, "src", "bindings");
+    return [path.join(bindingsDir, "index.ts"), path.join(bindingsDir, "index.js")].find((candidatePath) => fs.existsSync(candidatePath)) ?? path.join(bindingsDir, "index.ts");
+}
+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 +766,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 +793,17 @@ 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>
+  wp-typia add binding-source <name>
+  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}>
 
 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/\`.
+  \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
+  \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.`;
 }
 /**
  * Seeds an empty official workspace migration project before any blocks are added.
@@ -467,15 +818,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 +848,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 +873,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 +894,7 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
             };
         }
         catch (error) {
-            await rollbackWorkspaceMutation(workspace.projectDir, mutationSnapshot);
+            await rollbackWorkspaceMutation(mutationSnapshot);
             throw error;
         }
     }
@@ -552,10 +904,284 @@ 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 assertValidHookAnchor(anchorBlockName) {
+    const trimmed = anchorBlockName.trim();
+    if (!trimmed) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name>.");
+    }
+    if (!HOOKED_BLOCK_ANCHOR_PATTERN.test(trimmed)) {
+        throw new Error("`wp-typia add hooked-block` requires --anchor <anchor-block-name> to use the full `namespace/slug` block name format.");
+    }
+    return trimmed;
+}
+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 = 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)}.`);
+    }
+    if (!blockJson || typeof blockJson !== "object" || Array.isArray(blockJson)) {
+        throw new Error(`${path.relative(projectDir, blockJsonPath)} must contain a JSON object.`);
+    }
+    return {
+        blockJson: blockJson,
+        blockJsonPath,
+    };
+}
+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;
+}
+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.`);
+    }
+}
+function assertBindingSourceDoesNotExist(projectDir, bindingSourceSlug, inventory) {
+    const bindingSourceDir = path.join(projectDir, "src", "bindings", bindingSourceSlug);
+    if (fs.existsSync(bindingSourceDir)) {
+        throw new Error(`A binding source already exists at ${path.relative(projectDir, bindingSourceDir)}. Choose a different name.`);
+    }
+    if (inventory.bindingSources.some((entry) => entry.slug === bindingSourceSlug)) {
+        throw new Error(`A binding source inventory entry already exists for ${bindingSourceSlug}. 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;
+    }
+}
+/**
+ * Add one block binding source scaffold to an official workspace project.
+ *
+ * @param options Command options for the binding-source scaffold workflow.
+ * @param options.bindingSourceName Human-entered binding source name that will
+ * be normalized and validated before files are written.
+ * @param options.cwd Working directory used to resolve the nearest official
+ * workspace. Defaults to `process.cwd()`.
+ * @returns A promise that resolves with the normalized `bindingSourceSlug` and
+ * owning `projectDir` after the server/editor files and inventory entry have
+ * been written successfully.
+ * @throws {Error} When the command is run outside an official workspace, when
+ * the slug is invalid, or when a conflicting file or inventory entry exists.
+ */
+export async function runAddBindingSourceCommand({ bindingSourceName, cwd = process.cwd(), }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const bindingSourceSlug = assertValidGeneratedSlug("Binding source name", normalizeBlockSlug(bindingSourceName), "wp-typia add binding-source <name>");
+    const inventory = readWorkspaceInventory(workspace.projectDir);
+    assertBindingSourceDoesNotExist(workspace.projectDir, bindingSourceSlug, inventory);
+    const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
+    const bootstrapPath = getWorkspaceBootstrapPath(workspace);
+    const bindingsIndexPath = resolveBindingSourceRegistryPath(workspace.projectDir);
+    const bindingSourceDir = path.join(workspace.projectDir, "src", "bindings", bindingSourceSlug);
+    const serverFilePath = path.join(bindingSourceDir, "server.php");
+    const editorFilePath = path.join(bindingSourceDir, "editor.ts");
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([blockConfigPath, bootstrapPath, bindingsIndexPath]),
+        snapshotDirs: [],
+        targetPaths: [bindingSourceDir],
+    };
+    try {
+        await fsp.mkdir(bindingSourceDir, { recursive: true });
+        await ensureBindingSourceBootstrapAnchors(workspace);
+        await fsp.writeFile(serverFilePath, buildBindingSourceServerSource(bindingSourceSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
+        await fsp.writeFile(editorFilePath, buildBindingSourceEditorSource(bindingSourceSlug, workspace.workspace.namespace, workspace.workspace.textDomain), "utf8");
+        await writeBindingSourceRegistry(workspace.projectDir, bindingSourceSlug);
+        await appendWorkspaceInventoryEntries(workspace.projectDir, {
+            bindingSourceEntries: [buildBindingSourceConfigEntry(bindingSourceSlug)],
+        });
+        return {
+            bindingSourceSlug,
+            projectDir: workspace.projectDir,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
+}
+/**
+ * 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.
+ */
+export async function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd = process.cwd(), position, }) {
+    const workspace = resolveWorkspaceProject(cwd);
+    const blockSlug = normalizeBlockSlug(blockName);
+    const inventory = readWorkspaceInventory(workspace.projectDir);
+    resolveWorkspaceBlock(inventory, blockSlug);
+    const resolvedAnchorBlockName = assertValidHookAnchor(anchorBlockName);
+    const resolvedPosition = assertValidHookedBlockPosition(position);
+    const selfHookAnchor = `${workspace.workspace.namespace}/${blockSlug}`;
+    if (resolvedAnchorBlockName === selfHookAnchor) {
+        throw new Error("`wp-typia add hooked-block` cannot hook a block relative to its own block name.");
+    }
+    const { blockJson, blockJsonPath } = readWorkspaceBlockJson(workspace.projectDir, blockSlug);
+    const blockJsonRelativePath = path.relative(workspace.projectDir, blockJsonPath);
+    const blockHooks = getMutableBlockHooks(blockJson, blockJsonRelativePath);
+    if (Object.prototype.hasOwnProperty.call(blockHooks, resolvedAnchorBlockName)) {
+        throw new Error(`${blockJsonRelativePath} already defines a blockHooks entry for "${resolvedAnchorBlockName}".`);
+    }
+    const mutationSnapshot = {
+        fileSources: await snapshotWorkspaceFiles([blockJsonPath]),
+        snapshotDirs: [],
+        targetPaths: [],
+    };
+    try {
+        blockHooks[resolvedAnchorBlockName] = resolvedPosition;
+        await fsp.writeFile(blockJsonPath, JSON.stringify(blockJson, null, "\t"), "utf8");
+        return {
+            anchorBlockName: resolvedAnchorBlockName,
+            blockSlug,
+            position: resolvedPosition,
+            projectDir: workspace.projectDir,
+        };
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw error;
+    }
 }
+export { getWorkspaceBlockSelectOptions };