@wp-typia/project-tools 0.16.5 → 0.16.7

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

@@ -0,0 +1,518 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { syncBlockMetadata, } from "@wp-typia/block-runtime/metadata-core";
+import { ensureMigrationDirectories, parseMigrationConfig, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
+import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
+import { snapshotProjectVersion } from "./migrations.js";
+import { getDefaultAnswers, scaffoldProject } from "./scaffold.js";
+import { copyInterpolatedDirectory, } from "./template-render.js";
+import { SHARED_WORKSPACE_TEMPLATE_ROOT, } from "./template-registry.js";
+import { appendWorkspaceInventoryEntries, } from "./workspace-inventory.js";
+import { resolveWorkspaceProject, } from "./workspace-project.js";
+import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, normalizeBlockSlug, patchFile, quoteTsString, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+const COLLECTION_IMPORT_LINE = "import '../../collection';";
+const REST_MANIFEST_IMPORT_PATTERN = /import\s*\{[^}]*\bdefineEndpointManifest\b[^}]*\}\s*from\s*["']@wp-typia\/block-runtime\/metadata-core["'];?/m;
+function buildServerTemplateRoot(persistencePolicy) {
+    return path.join(SHARED_WORKSPACE_TEMPLATE_ROOT, persistencePolicy === "public" ? "persistence-public" : "persistence-auth");
+}
+function buildSingleBlockConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tslug: ${quoteTsString(variables.slugKebabCase)},`,
+        `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}Attributes`)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildPersistenceBlockConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tapiTypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/api-types.ts`)},`,
+        `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}Attributes`)},`,
+        "\t\trestManifest: defineEndpointManifest( {",
+        "\t\t\tcontracts: {",
+        "\t\t\t\t'bootstrap-query': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}BootstrapQuery`)},`,
+        "\t\t\t\t},",
+        "\t\t\t\t'bootstrap-response': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}BootstrapResponse`)},`,
+        "\t\t\t\t},",
+        "\t\t\t\t'state-query': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateQuery`)},`,
+        "\t\t\t\t},",
+        "\t\t\t\t'state-response': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateResponse`)},`,
+        "\t\t\t\t},",
+        "\t\t\t\t'write-state-request': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}WriteStateRequest`)},`,
+        "\t\t\t\t},",
+        "\t\t\t},",
+        "\t\t\tendpoints: [",
+        "\t\t\t\t{",
+        "\t\t\t\t\tauth: 'public',",
+        "\t\t\t\t\tmethod: 'GET',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`get${variables.pascalCase}State`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/state`)},`,
+        "\t\t\t\t\tqueryContract: 'state-query',",
+        "\t\t\t\t\tresponseContract: 'state-response',",
+        `\t\t\t\t\tsummary: 'Read the current persisted state.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t},",
+        "\t\t\t\t{",
+        `\t\t\t\t\tauth: ${quoteTsString(variables.restWriteAuthIntent)},`,
+        "\t\t\t\t\tbodyContract: 'write-state-request',",
+        "\t\t\t\t\tmethod: 'POST',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`write${variables.pascalCase}State`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/state`)},`,
+        "\t\t\t\t\tresponseContract: 'state-response',",
+        `\t\t\t\t\tsummary: 'Write the current persisted state.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t\twordpressAuth: {",
+        `\t\t\t\t\t\tmechanism: ${quoteTsString(variables.restWriteAuthMechanism)},`,
+        "\t\t\t\t\t},",
+        "\t\t\t\t},",
+        "\t\t\t\t{",
+        "\t\t\t\t\tauth: 'public',",
+        "\t\t\t\t\tmethod: 'GET',",
+        `\t\t\t\t\toperationId: ${quoteTsString(`get${variables.pascalCase}Bootstrap`)},`,
+        `\t\t\t\t\tpath: ${quoteTsString(`/${variables.namespace}/v1/${variables.slugKebabCase}/bootstrap`)},`,
+        "\t\t\t\t\tqueryContract: 'bootstrap-query',",
+        "\t\t\t\t\tresponseContract: 'bootstrap-response',",
+        `\t\t\t\t\tsummary: 'Read fresh session bootstrap state for the current viewer.',`,
+        `\t\t\t\t\ttags: [ ${quoteTsString(variables.title)} ],`,
+        "\t\t\t\t},",
+        "\t\t\t],",
+        "\t\t\tinfo: {",
+        `\t\t\t\ttitle: ${quoteTsString(`${variables.title} REST API`)},`,
+        "\t\t\t\tversion: '1.0.0',",
+        "\t\t\t},",
+        "\t\t} ),",
+        `\t\topenApiFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/api.openapi.json`)},`,
+        `\t\tslug: ${quoteTsString(variables.slugKebabCase)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildCompoundChildConfigEntry(variables) {
+    return [
+        "\t{",
+        `\t\tslug: ${quoteTsString(`${variables.slugKebabCase}-item`)},`,
+        `\t\tattributeTypeName: ${quoteTsString(`${variables.pascalCase}ItemAttributes`)},`,
+        `\t\ttypesFile: ${quoteTsString(`src/blocks/${variables.slugKebabCase}-item/types.ts`)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildConfigEntries(templateId, variables) {
+    if (templateId === "basic" || templateId === "interactivity") {
+        return [buildSingleBlockConfigEntry(variables)];
+    }
+    if (templateId === "persistence") {
+        return [buildPersistenceBlockConfigEntry(variables)];
+    }
+    if (variables.compoundPersistenceEnabled === "true") {
+        return [
+            buildPersistenceBlockConfigEntry(variables),
+            buildCompoundChildConfigEntry(variables),
+        ];
+    }
+    return [
+        buildSingleBlockConfigEntry(variables),
+        buildCompoundChildConfigEntry(variables),
+    ];
+}
+function buildMigrationBlocks(templateId, variables) {
+    if (templateId === "compound") {
+        return [
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+                key: variables.slugKebabCase,
+                manifestFile: `src/blocks/${variables.slugKebabCase}/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}/types.ts`,
+            },
+            {
+                blockJsonFile: `src/blocks/${variables.slugKebabCase}-item/block.json`,
+                blockName: `${variables.namespace}/${variables.slugKebabCase}-item`,
+                key: `${variables.slugKebabCase}-item`,
+                manifestFile: `src/blocks/${variables.slugKebabCase}-item/typia.manifest.json`,
+                saveFile: `src/blocks/${variables.slugKebabCase}-item/save.tsx`,
+                typesFile: `src/blocks/${variables.slugKebabCase}-item/types.ts`,
+            },
+        ];
+    }
+    return [
+        {
+            blockJsonFile: `src/blocks/${variables.slugKebabCase}/block.json`,
+            blockName: `${variables.namespace}/${variables.slugKebabCase}`,
+            key: variables.slugKebabCase,
+            manifestFile: `src/blocks/${variables.slugKebabCase}/typia.manifest.json`,
+            saveFile: `src/blocks/${variables.slugKebabCase}/save.tsx`,
+            typesFile: `src/blocks/${variables.slugKebabCase}/types.ts`,
+        },
+    ];
+}
+async function ensureCollectionImport(filePath) {
+    await patchFile(filePath, (source) => {
+        if (source.includes(COLLECTION_IMPORT_LINE)) {
+            return source;
+        }
+        if (source.includes("import metadata from './block.json';")) {
+            return source.replace("import metadata from './block.json';", `${COLLECTION_IMPORT_LINE}\nimport metadata from './block.json';`);
+        }
+        return `${COLLECTION_IMPORT_LINE}\n${source}`;
+    });
+}
+async function copyTempDirectory(sourceDir, targetDir) {
+    await fsp.mkdir(path.dirname(targetDir), { recursive: true });
+    await fsp.cp(sourceDir, targetDir, { recursive: true });
+}
+async function addCollectionImportsForTemplate(projectDir, templateId, variables) {
+    if (templateId === "compound") {
+        await ensureCollectionImport(path.join(projectDir, "src", "blocks", variables.slugKebabCase, "index.tsx"));
+        await ensureCollectionImport(path.join(projectDir, "src", "blocks", `${variables.slugKebabCase}-item`, "index.tsx"));
+        return;
+    }
+    await ensureCollectionImport(path.join(projectDir, "src", "blocks", variables.slugKebabCase, "index.tsx"));
+}
+function ensureBlockConfigCanAddRestManifests(source) {
+    const importLine = "import { defineEndpointManifest } from '@wp-typia/block-runtime/metadata-core';";
+    if (REST_MANIFEST_IMPORT_PATTERN.test(source)) {
+        return source;
+    }
+    return `${importLine}\n\n${source}`;
+}
+async function appendBlockConfigEntries(projectDir, entries, needsRestManifestImport) {
+    await appendWorkspaceInventoryEntries(projectDir, {
+        blockEntries: entries,
+        transformSource: needsRestManifestImport ? ensureBlockConfigCanAddRestManifests : undefined,
+    });
+}
+async function renderWorkspacePersistenceServerModule(projectDir, variables) {
+    const targetDir = path.join(projectDir, "src", "blocks", variables.slugKebabCase);
+    const templateDir = buildServerTemplateRoot(variables.persistencePolicy);
+    await copyInterpolatedDirectory(templateDir, targetDir, variables);
+}
+const COMPOUND_SHARED_SUPPORT_FILES = ["hooks.ts", "validator-toolkit.ts"];
+const LEGACY_ASSERT_PATTERN = /assert:\s*typia\.createAssert</u;
+const LEGACY_MANIFEST_PATTERN = /\r?\n[ \t]*manifest:\s*currentManifest,/u;
+const LEGACY_TOOLKIT_CALL_PATTERN = /createTemplateValidatorToolkit<\s*(?<typeName>[A-Za-z0-9_]+)\s*>\s*\(\s*\{/u;
+const LEGACY_VALIDATOR_TOOLKIT_IMPORT_PATTERN = /from\s*["']\.\.\/\.\.\/validator-toolkit["']/u;
+const TYPIA_IMPORT_PATTERN = /^[\uFEFF \t]*import\s+typia\s+from\s*["']typia["'];?/mu;
+const COMPATIBLE_COMPOUND_TOOLKIT_PATTERNS = [
+    /interface\s+TemplateValidatorFunctions\s*<\s*T\s+extends\s+object\s*>\s*\{/u,
+    /\bassert\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']assert["']\s*\]/u,
+    /\bclone\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']clone["']\s*\]/u,
+    /\bis\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']is["']\s*\]/u,
+    /\bprune\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']prune["']\s*\]/u,
+    /\brandom\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']random["']\s*\]/u,
+    /\bvalidate\s*:\s*ScaffoldValidatorToolkitOptions\s*<\s*T\s*>\s*\[\s*["']validate["']\s*\]/u,
+    /createTemplateValidatorToolkit\s*<\s*T\s+extends\s+object\s*>\s*\(\s*\{/u,
+];
+function shouldRefreshCompoundValidatorToolkit(source) {
+    return (source === null ||
+        !COMPATIBLE_COMPOUND_TOOLKIT_PATTERNS.every((pattern) => pattern.test(source)));
+}
+function isLegacyCompoundValidatorSource(source) {
+    return (typeof source === "string" &&
+        LEGACY_VALIDATOR_TOOLKIT_IMPORT_PATTERN.test(source) &&
+        !LEGACY_ASSERT_PATTERN.test(source));
+}
+function hasTypiaImport(source) {
+    return TYPIA_IMPORT_PATTERN.test(source.replace(/\/\*[\s\S]*?\*\//gu, ""));
+}
+function upgradeLegacyCompoundValidatorSource(source) {
+    const typeNameMatch = source.match(LEGACY_TOOLKIT_CALL_PATTERN);
+    const typeName = typeNameMatch?.groups?.typeName;
+    if (!typeName) {
+        throw new Error("Unable to upgrade a legacy compound validator without a generated type import.");
+    }
+    let nextSource = source;
+    if (!hasTypiaImport(nextSource)) {
+        nextSource = `import typia from 'typia';\n${nextSource}`;
+    }
+    nextSource = nextSource.replace(LEGACY_TOOLKIT_CALL_PATTERN, [
+        `createTemplateValidatorToolkit< ${typeName} >( {`,
+        `\tassert: typia.createAssert< ${typeName} >(),`,
+        `\tclone: typia.misc.createClone< ${typeName} >() as (`,
+        `\t\tvalue: ${typeName},`,
+        `\t) => ${typeName},`,
+        `\tis: typia.createIs< ${typeName} >(),`,
+    ].join("\n") + "\n");
+    const replacedManifest = nextSource.replace(LEGACY_MANIFEST_PATTERN, [
+        "",
+        "\tmanifest: currentManifest,",
+        `\tprune: typia.misc.createPrune< ${typeName} >(),`,
+        `\trandom: typia.createRandom< ${typeName} >() as (`,
+        "\t\t...args: unknown[]",
+        `\t) => ${typeName},`,
+        `\tvalidate: typia.createValidate< ${typeName} >(),`,
+    ].join("\n"));
+    if (replacedManifest === nextSource) {
+        throw new Error("Unable to upgrade legacy compound validator: manifest anchor not found.");
+    }
+    return replacedManifest;
+}
+async function collectLegacyCompoundValidatorPaths(projectDir) {
+    const blocksDir = path.join(projectDir, "src", "blocks");
+    if (!fs.existsSync(blocksDir)) {
+        return [];
+    }
+    const blockEntries = await fsp.readdir(blocksDir, { withFileTypes: true });
+    const validatorPaths = await Promise.all(blockEntries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
+        const validatorPath = path.join(blocksDir, entry.name, "validators.ts");
+        const validatorSource = await readOptionalFile(validatorPath);
+        return isLegacyCompoundValidatorSource(validatorSource) ? validatorPath : null;
+    }));
+    return validatorPaths.filter((validatorPath) => validatorPath !== null);
+}
+async function ensureCompoundWorkspaceSupportFiles(projectDir, tempProjectDir, legacyValidatorPaths) {
+    for (const fileName of COMPOUND_SHARED_SUPPORT_FILES) {
+        const sourcePath = path.join(tempProjectDir, "src", fileName);
+        if (!fs.existsSync(sourcePath)) {
+            continue;
+        }
+        const targetPath = path.join(projectDir, "src", fileName);
+        const currentSource = await readOptionalFile(targetPath);
+        if (fileName === "validator-toolkit.ts"
+            ? shouldRefreshCompoundValidatorToolkit(currentSource)
+            : currentSource === null) {
+            await fsp.mkdir(path.dirname(targetPath), { recursive: true });
+            await fsp.copyFile(sourcePath, targetPath);
+        }
+    }
+    for (const validatorPath of legacyValidatorPaths) {
+        const currentSource = await readOptionalFile(validatorPath);
+        if (!isLegacyCompoundValidatorSource(currentSource)) {
+            continue;
+        }
+        await fsp.writeFile(validatorPath, upgradeLegacyCompoundValidatorSource(currentSource), "utf8");
+    }
+}
+async function copyScaffoldedBlockSlice(projectDir, templateId, tempProjectDir, variables, legacyValidatorPaths = []) {
+    if (templateId === "compound") {
+        await ensureCompoundWorkspaceSupportFiles(projectDir, tempProjectDir, legacyValidatorPaths);
+        await copyTempDirectory(path.join(tempProjectDir, "src", "blocks", variables.slugKebabCase), path.join(projectDir, "src", "blocks", variables.slugKebabCase));
+        await copyTempDirectory(path.join(tempProjectDir, "src", "blocks", `${variables.slugKebabCase}-item`), path.join(projectDir, "src", "blocks", `${variables.slugKebabCase}-item`));
+        if (variables.compoundPersistenceEnabled === "true") {
+            await renderWorkspacePersistenceServerModule(projectDir, variables);
+        }
+        return;
+    }
+    await copyTempDirectory(path.join(tempProjectDir, "src"), path.join(projectDir, "src", "blocks", variables.slugKebabCase));
+    if (templateId === "persistence") {
+        await renderWorkspacePersistenceServerModule(projectDir, variables);
+    }
+}
+function collectWorkspaceBlockPaths(projectDir, templateId, variables) {
+    if (templateId === "compound") {
+        return [
+            path.join(projectDir, "src", "blocks", variables.slugKebabCase),
+            path.join(projectDir, "src", "blocks", `${variables.slugKebabCase}-item`),
+        ];
+    }
+    return [path.join(projectDir, "src", "blocks", variables.slugKebabCase)];
+}
+function assertBlockTargetsDoNotExist(projectDir, templateId, variables) {
+    for (const targetPath of collectWorkspaceBlockPaths(projectDir, templateId, variables)) {
+        if (fs.existsSync(targetPath)) {
+            throw new Error(`A block already exists at ${path.relative(projectDir, targetPath)}. Choose a different name.`);
+        }
+    }
+}
+async function updateWorkspaceMigrationConfigIfPresent(projectDir, newBlocks) {
+    const configPath = path.join(projectDir, "src", "migrations", "config.ts");
+    if (!fs.existsSync(configPath)) {
+        return;
+    }
+    const configSource = await fsp.readFile(configPath, "utf8");
+    const config = parseMigrationConfig(configSource);
+    const existingBlocks = Array.isArray(config.blocks) ? config.blocks : [];
+    const nextBlocks = [
+        ...existingBlocks,
+        ...newBlocks.filter((block) => !existingBlocks.some((existing) => existing.key === block.key)),
+    ];
+    writeMigrationConfig(projectDir, {
+        ...config,
+        blocks: nextBlocks,
+    });
+    snapshotProjectVersion(projectDir, config.currentMigrationVersion, {
+        skipConfigUpdate: true,
+    });
+}
+async function syncWorkspaceBlockMetadata(projectDir, slug, sourceTypeName, typesFile) {
+    await syncBlockMetadata({
+        blockJsonFile: path.join("src", "blocks", slug, "block.json"),
+        jsonSchemaFile: path.join("src", "blocks", slug, "typia.schema.json"),
+        manifestFile: path.join("src", "blocks", slug, "typia.manifest.json"),
+        openApiFile: path.join("src", "blocks", slug, "typia.openapi.json"),
+        projectRoot: projectDir,
+        sourceTypeName,
+        typesFile,
+    });
+}
+async function syncWorkspacePersistenceArtifacts(projectDir, variables) {
+    await syncPersistenceRestArtifacts({
+        apiTypesFile: path.join("src", "blocks", variables.slugKebabCase, "api-types.ts"),
+        outputDir: path.join("src", "blocks", variables.slugKebabCase),
+        projectDir,
+        variables,
+    });
+}
+async function syncWorkspaceAddedBlockArtifacts(projectDir, templateId, variables) {
+    await syncWorkspaceBlockMetadata(projectDir, variables.slugKebabCase, `${variables.pascalCase}Attributes`, path.join("src", "blocks", variables.slugKebabCase, "types.ts"));
+    if (templateId === "compound") {
+        await syncWorkspaceBlockMetadata(projectDir, `${variables.slugKebabCase}-item`, `${variables.pascalCase}ItemAttributes`, path.join("src", "blocks", `${variables.slugKebabCase}-item`, "types.ts"));
+    }
+    if (templateId === "persistence" ||
+        (templateId === "compound" && variables.compoundPersistenceEnabled === "true")) {
+        await syncWorkspacePersistenceArtifacts(projectDir, variables);
+    }
+}
+function assertPersistenceFlagsAllowed(templateId, options) {
+    const hasPersistenceFlags = typeof options.dataStorageMode === "string" ||
+        typeof options.persistencePolicy === "string";
+    if (!hasPersistenceFlags) {
+        return;
+    }
+    if (templateId === "persistence" || templateId === "compound") {
+        if (typeof options.dataStorageMode === "string" &&
+            options.dataStorageMode !== "custom-table" &&
+            options.dataStorageMode !== "post-meta") {
+            throw new Error(`Unsupported data storage mode "${options.dataStorageMode}". Expected one of: post-meta, custom-table.`);
+        }
+        if (typeof options.persistencePolicy === "string" &&
+            options.persistencePolicy !== "authenticated" &&
+            options.persistencePolicy !== "public") {
+            throw new Error(`Unsupported persistence policy "${options.persistencePolicy}". Expected one of: authenticated, public.`);
+        }
+        return;
+    }
+    throw new Error(`--data-storage and --persistence-policy are supported only for \`wp-typia add block --template persistence\` or \`--template compound\`.`);
+}
+/**
+ * Seeds an empty official workspace migration project before any blocks are added.
+ *
+ * @param projectDir Absolute path to the workspace root that will own the
+ * migration config and generated scaffold files.
+ * @param currentMigrationVersion Initial migration label to record as the
+ * current version in the seeded workspace.
+ */
+export async function seedWorkspaceMigrationProject(projectDir, currentMigrationVersion) {
+    writeMigrationConfig(projectDir, {
+        blocks: [],
+        currentMigrationVersion,
+        snapshotDir: "src/migrations/versions",
+        supportedMigrationVersions: [currentMigrationVersion],
+    });
+    ensureMigrationDirectories(projectDir, []);
+    writeInitialMigrationScaffold(projectDir, currentMigrationVersion, []);
+}
+/**
+ * Adds one built-in block slice to an official workspace project.
+ *
+ * @param options Command options for the built-in workspace block scaffold flow.
+ * @param options.blockName Human-entered block name that will be normalized
+ * into the generated workspace block slug.
+ * @param options.cwd Working directory used to resolve the nearest official
+ * workspace. Defaults to `process.cwd()`.
+ * @param options.dataStorageMode Optional storage mode for persistence-capable
+ * templates.
+ * @param options.persistencePolicy Optional persistence policy for
+ * persistence-capable templates.
+ * @param options.templateId Built-in block family to scaffold. Defaults to
+ * `"basic"`.
+ * @returns A promise that resolves with the created block slugs, the owning
+ * project directory, and the resolved template id after workspace mutation
+ * succeeds.
+ * @throws {Error} When the template id is unknown, persistence flags are used
+ * with unsupported templates, the command runs outside an official workspace,
+ * or target block paths already exist.
+ */
+export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataStorageMode, persistencePolicy, templateId = "basic", }) {
+    if (!isAddBlockTemplateId(templateId)) {
+        throw new Error(`Unknown add-block template "${templateId}". Expected one of: ${ADD_BLOCK_TEMPLATE_IDS.join(", ")}`);
+    }
+    const resolvedTemplateId = templateId;
+    assertPersistenceFlagsAllowed(resolvedTemplateId, { dataStorageMode, persistencePolicy });
+    const workspace = resolveWorkspaceProject(cwd);
+    const normalizedSlug = normalizeBlockSlug(blockName);
+    if (!normalizedSlug) {
+        throw new Error("Block name is required. Use `wp-typia add block <name> --template <family>`.");
+    }
+    const defaults = getDefaultAnswers(normalizedSlug, resolvedTemplateId);
+    let tempRoot = "";
+    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 migrationConfigSource = await readOptionalFile(migrationConfigPath);
+        const migrationConfig = migrationConfigSource === null ? null : parseMigrationConfig(migrationConfigSource);
+        const compoundSupportPaths = resolvedTemplateId === "compound"
+            ? COMPOUND_SHARED_SUPPORT_FILES.map((fileName) => path.join(workspace.projectDir, "src", fileName))
+            : [];
+        const legacyCompoundValidatorPaths = resolvedTemplateId === "compound"
+            ? await collectLegacyCompoundValidatorPaths(workspace.projectDir)
+            : [];
+        const result = await scaffoldProject({
+            answers: {
+                ...defaults,
+                author: workspace.author,
+                namespace: workspace.workspace.namespace,
+                phpPrefix: blockPhpPrefix,
+                slug: normalizedSlug,
+                textDomain: workspace.workspace.textDomain,
+                title: defaults.title,
+            },
+            cwd: workspace.projectDir,
+            dataStorageMode: dataStorageMode,
+            noInstall: true,
+            packageManager: workspace.packageManager,
+            persistencePolicy: persistencePolicy,
+            projectDir: tempProjectDir,
+            templateId: resolvedTemplateId,
+        });
+        assertBlockTargetsDoNotExist(workspace.projectDir, resolvedTemplateId, result.variables);
+        const mutationSnapshot = {
+            fileSources: await snapshotWorkspaceFiles([
+                blockConfigPath,
+                migrationConfigPath,
+                ...compoundSupportPaths,
+                ...legacyCompoundValidatorPaths,
+            ]),
+            snapshotDirs: migrationConfig === null
+                ? []
+                : buildMigrationBlocks(resolvedTemplateId, result.variables).map((block) => path.join(workspace.projectDir, ...migrationConfig.snapshotDir.split("/"), migrationConfig.currentMigrationVersion, block.key)),
+            targetPaths: collectWorkspaceBlockPaths(workspace.projectDir, resolvedTemplateId, result.variables),
+        };
+        try {
+            await copyScaffoldedBlockSlice(workspace.projectDir, resolvedTemplateId, tempProjectDir, result.variables, legacyCompoundValidatorPaths);
+            await addCollectionImportsForTemplate(workspace.projectDir, resolvedTemplateId, result.variables);
+            await appendBlockConfigEntries(workspace.projectDir, buildConfigEntries(resolvedTemplateId, result.variables), resolvedTemplateId === "persistence" ||
+                (resolvedTemplateId === "compound" &&
+                    result.variables.compoundPersistenceEnabled === "true"));
+            await syncWorkspaceAddedBlockArtifacts(workspace.projectDir, resolvedTemplateId, result.variables);
+            await updateWorkspaceMigrationConfigIfPresent(workspace.projectDir, buildMigrationBlocks(resolvedTemplateId, result.variables));
+            return {
+                blockSlugs: collectWorkspaceBlockPaths(workspace.projectDir, resolvedTemplateId, result.variables).map((targetPath) => path.basename(targetPath)),
+                projectDir: workspace.projectDir,
+                templateId: resolvedTemplateId,
+            };
+        }
+        catch (error) {
+            await rollbackWorkspaceMutation(mutationSnapshot);
+            throw error;
+        }
+    }
+    finally {
+        if (tempRoot) {
+            await fsp.rm(tempRoot, { force: true, recursive: true });
+        }
+    }
+}

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

@@ -0,0 +1,93 @@
+import { type HookedBlockPositionId } from "./hooked-blocks.js";
+import { type WorkspaceInventory } from "./workspace-inventory.js";
+import { type WorkspaceProject } from "./workspace-project.js";
+/**
+ * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
+ */
+export declare const ADD_KIND_IDS: readonly ["block", "variation", "pattern", "binding-source", "hooked-block"];
+export type AddKindId = (typeof ADD_KIND_IDS)[number];
+/**
+ * Supported built-in block families accepted by `wp-typia add block --template`.
+ */
+export declare const ADD_BLOCK_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
+export type AddBlockTemplateId = (typeof ADD_BLOCK_TEMPLATE_IDS)[number];
+export interface RunAddVariationCommandOptions {
+    blockName: string;
+    cwd?: string;
+    variationName: string;
+}
+export interface RunAddPatternCommandOptions {
+    cwd?: string;
+    patternName: string;
+}
+export interface RunAddBindingSourceCommandOptions {
+    bindingSourceName: string;
+    cwd?: string;
+}
+export interface RunAddHookedBlockCommandOptions {
+    anchorBlockName: string;
+    blockName: string;
+    cwd?: string;
+    position: string;
+}
+export interface RunAddBlockCommandOptions {
+    blockName: string;
+    cwd?: string;
+    dataStorageMode?: string;
+    persistencePolicy?: string;
+    templateId?: string;
+}
+export interface WorkspaceMutationSnapshot {
+    /** Snapshots of file contents taken before the mutation starts. */
+    fileSources: Array<{
+        /** Absolute file path recorded for rollback. */
+        filePath: string;
+        /** Previous file contents, or `null` when the file did not exist. */
+        source: string | null;
+    }>;
+    /** Snapshot directories created while seeding migration history. */
+    snapshotDirs: string[];
+    /** Files or directories created by the mutation that should be removed on rollback. */
+    targetPaths: string[];
+}
+export declare function normalizeBlockSlug(input: string): string;
+export declare function assertValidGeneratedSlug(label: string, slug: string, usage: string): string;
+export declare function assertValidHookedBlockPosition(position: string): HookedBlockPositionId;
+export declare function getWorkspaceBootstrapPath(workspace: WorkspaceProject): string;
+export declare function buildWorkspacePhpPrefix(workspacePhpPrefix: string, slug: string): string;
+export declare function isAddBlockTemplateId(value: string): value is AddBlockTemplateId;
+export declare function quoteTsString(value: string): string;
+/**
+ * Apply a text transform to an existing file only when the contents change.
+ */
+export declare function patchFile(filePath: string, transform: (source: string) => string): Promise<void>;
+/**
+ * Read a file when it exists and otherwise return `null`.
+ */
+export declare function readOptionalFile(filePath: string): Promise<string | null>;
+/**
+ * Restore a file to its captured source, deleting it when the snapshot was `null`.
+ */
+export declare function restoreOptionalFile(filePath: string, source: string | null): Promise<void>;
+/**
+ * Capture the current contents of a set of workspace files for rollback.
+ */
+export declare function snapshotWorkspaceFiles(filePaths: string[]): Promise<WorkspaceMutationSnapshot["fileSources"]>;
+/**
+ * Undo a partially applied workspace mutation from a captured snapshot.
+ */
+export declare function rollbackWorkspaceMutation(snapshot: WorkspaceMutationSnapshot): Promise<void>;
+export declare function resolveWorkspaceBlock(inventory: WorkspaceInventory, blockSlug: string): WorkspaceInventory["blocks"][number];
+export declare function assertValidHookAnchor(anchorBlockName: string): string;
+export declare function readWorkspaceBlockJson(projectDir: string, blockSlug: string): {
+    blockJson: Record<string, unknown>;
+    blockJsonPath: string;
+};
+export declare function getMutableBlockHooks(blockJson: Record<string, unknown>, blockJsonRelativePath: string): Record<string, string>;
+export declare function assertVariationDoesNotExist(projectDir: string, blockSlug: string, variationSlug: string, inventory: WorkspaceInventory): void;
+export declare function assertPatternDoesNotExist(projectDir: string, patternSlug: string, inventory: WorkspaceInventory): void;
+export declare function assertBindingSourceDoesNotExist(projectDir: string, bindingSourceSlug: string, inventory: WorkspaceInventory): void;
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+export declare function formatAddHelpText(): string;