@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { readOptionalFile } from "./cli-add-shared.js";
+export 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_VALIDATOR_MANIFEST_IMPORT_PATTERN = /^[\uFEFF \t]*import\s+currentManifest\s+from\s*["']\.\/typia\.manifest\.json["'];?$/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,
+];
+const REST_MANIFEST_IMPORT_PATTERN = /import\s*\{[^}]*\bdefineEndpointManifest\b[^}]*\}\s*from\s*["']@wp-typia\/block-runtime\/metadata-core["'];?/m;
+export 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}`;
+}
+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 replaceFirstNonCommentLine(source, pattern, replacement) {
+    const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
+    const lines = source.split(/\r?\n/);
+    let inBlockComment = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trimStart();
+        if (inBlockComment) {
+            if (trimmed.includes("*/")) {
+                inBlockComment = false;
+            }
+            continue;
+        }
+        if (trimmed.startsWith("//")) {
+            continue;
+        }
+        if (trimmed.startsWith("/*")) {
+            if (!trimmed.includes("*/")) {
+                inBlockComment = true;
+            }
+            continue;
+        }
+        if (!pattern.test(line)) {
+            continue;
+        }
+        lines[index] = replacement;
+        return lines.join(lineEnding);
+    }
+    return source;
+}
+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 = replaceFirstNonCommentLine(nextSource, LEGACY_VALIDATOR_MANIFEST_IMPORT_PATTERN, "import currentManifest from './manifest-defaults-document';");
+    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;
+}
+function renderLegacyManifestDefaultsWrapperSource() {
+    return [
+        "import rawCurrentManifest from './typia.manifest.json';",
+        "import { defineManifestDefaultsDocument } from '@wp-typia/block-runtime/defaults';",
+        "",
+        "const currentManifest = defineManifestDefaultsDocument( rawCurrentManifest );",
+        "",
+        "export default currentManifest;",
+        "",
+    ].join("\n");
+}
+async function ensureLegacyCompoundValidatorManifestDefaultsWrapper(validatorPath) {
+    const validatorDir = path.dirname(validatorPath);
+    const wrapperPath = path.join(validatorDir, "manifest-defaults-document.ts");
+    const manifestPath = path.join(validatorDir, "typia.manifest.json");
+    if (fs.existsSync(wrapperPath) || !fs.existsSync(manifestPath)) {
+        return;
+    }
+    await fsp.writeFile(wrapperPath, renderLegacyManifestDefaultsWrapperSource(), "utf8");
+}
+export 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);
+}
+export 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 ensureLegacyCompoundValidatorManifestDefaultsWrapper(validatorPath);
+        await fsp.writeFile(validatorPath, upgradeLegacyCompoundValidatorSource(currentSource), "utf8");
+    }
+}

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

@@ -0,0 +1,41 @@
+import { type AddBlockTemplateId, type RunAddBlockCommandOptions } from "./cli-add-shared.js";
+/**
+ * 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 declare function seedWorkspaceMigrationProject(projectDir: string, currentMigrationVersion: string): Promise<void>;
+/**
+ * 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.innerBlocksPreset Optional compound-only InnerBlocks preset
+ * (`freeform`, `ordered`, `horizontal`, or `locked-structure`) that controls
+ * the generated authoring defaults for nested compound containers.
+ * @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,
+ * workspace dependencies have not been installed yet, or target block paths
+ * already exist.
+ */
+export declare function runAddBlockCommand({ alternateRenderTargets, blockName, cwd, dataStorageMode, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, selectExternalLayerId, templateId, }: RunAddBlockCommandOptions): Promise<{
+    blockSlugs: string[];
+    projectDir: string;
+    templateId: AddBlockTemplateId;
+    warnings: string[];
+}>;

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

@@ -0,0 +1,428 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { syncBlockMetadata, } from "@wp-typia/block-runtime/metadata-core";
+import { ensureMigrationDirectories, parseMigrationConfig, writeInitialMigrationScaffold, writeMigrationConfig, } from "../migration/migration-project.js";
+import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
+import { snapshotProjectVersion } from "../migration/migrations.js";
+import { getDefaultAnswers, scaffoldProject } from "../templates/scaffold.js";
+import { copyInterpolatedDirectory, listInterpolatedDirectoryOutputs, } from "../templates/template-render.js";
+import { appendWorkspaceInventoryEntries, } from "../workspace/workspace-inventory.js";
+import { createManagedTempRoot } from "../shared/temp-roots.js";
+import { resolveWorkspaceProject, } from "../workspace/workspace-project.js";
+import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, patchFile, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
+import { resolveNonEmptyNormalizedBlockSlug, } from "../templates/scaffold-identifiers.js";
+import { buildConfigEntries, buildMigrationBlocks, buildServerTemplateRoot, } from "./cli-add-block-config.js";
+import { COMPOUND_SHARED_SUPPORT_FILES, collectLegacyCompoundValidatorPaths, ensureBlockConfigCanAddRestManifests, ensureCompoundWorkspaceSupportFiles, } from "./cli-add-block-legacy-validator.js";
+import { parseTemplateLocator, resolveTemplateSeed, } from "../templates/template-source.js";
+import { resolveExternalTemplateLayers, } from "../templates/template-layers.js";
+import { formatInstallCommand, } from "../shared/package-managers.js";
+import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
+import { isCompoundPersistenceEnabled } from "../templates/scaffold-template-variable-groups.js";
+import { resolveOptionalInteractiveExternalLayerId, } from "../templates/external-layer-selection.js";
+import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { assertExternalLayerCompositionOptions, normalizeOptionalCliString, resolveLocalCliPathOption, } from "../cli/cli-validation.js";
+import { pathExists } from "../shared/fs-async.js";
+const COLLECTION_IMPORT_LINE = "import '../../collection';";
+// This is a lightweight preflight heuristic for the common install layouts:
+// node_modules for npm/pnpm/bun/yarn-classic and Yarn PnP marker files.
+// It intentionally favors fast user guidance over exhaustive detection, so
+// stale node_modules or hoisted installs outside the workspace root can still
+// fall through to deeper resolver errors.
+const WORKSPACE_INSTALL_MARKERS = ["node_modules", ".pnp.cjs", ".pnp.loader.mjs"];
+async function ensureCollectionImport(filePath) {
+    await patchFile(filePath, (source) => {
+        if (source.includes(COLLECTION_IMPORT_LINE)) {
+            return source;
+        }
+        if (source.includes("import metadata from './block-metadata';")) {
+            return source.replace("import metadata from './block-metadata';", `${COLLECTION_IMPORT_LINE}\nimport metadata from './block-metadata';`);
+        }
+        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"));
+}
+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);
+}
+async function hasInstalledWorkspaceDependencies(projectDir) {
+    for (const marker of WORKSPACE_INSTALL_MARKERS) {
+        if (await pathExists(path.join(projectDir, marker))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function assertWorkspaceDependenciesInstalled(workspace) {
+    if (await hasInstalledWorkspaceDependencies(workspace.projectDir)) {
+        return;
+    }
+    throw new Error(`Workspace dependencies have not been installed yet. Run \`${formatInstallCommand(workspace.packageManager)}\` from the workspace root before using \`wp-typia add block ...\`.`);
+}
+function getMistypedAddBlockTemplateMessage(templateId) {
+    const suggestion = suggestAddBlockTemplateId(templateId);
+    if (!suggestion) {
+        return null;
+    }
+    return `Unknown add-block template "${templateId}". Did you mean "${suggestion}"? Use \`--template ${suggestion}\`, or run \`wp-typia templates list\` to inspect available templates.`;
+}
+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 (isCompoundPersistenceEnabled(variables)) {
+            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 isSupportedAddBlockLayerOutput(options) {
+    const { relativePath, templateId, variables } = options;
+    if (templateId === "compound") {
+        return (relativePath === "src/hooks.ts" ||
+            relativePath === "src/validator-toolkit.ts" ||
+            relativePath.startsWith(`src/blocks/${variables.slugKebabCase}/`) ||
+            relativePath.startsWith(`src/blocks/${variables.slugKebabCase}-item/`));
+    }
+    return relativePath.startsWith("src/");
+}
+async function assertAddBlockSupportsExternalLayerOutputs(options) {
+    const { callerCwd, externalLayerId, externalLayerSource, templateId, variables, } = options;
+    if (!externalLayerSource) {
+        return;
+    }
+    const layerSeed = await resolveTemplateSeed(parseTemplateLocator(externalLayerSource), callerCwd);
+    try {
+        const resolvedLayers = await resolveExternalTemplateLayers({
+            externalLayerId,
+            sourceRoot: layerSeed.rootDir,
+        });
+        for (const entry of resolvedLayers.entries) {
+            if (entry.kind !== "external") {
+                continue;
+            }
+            for (const relativePath of await listInterpolatedDirectoryOutputs(entry.dir, variables)) {
+                if (isSupportedAddBlockLayerOutput({
+                    relativePath,
+                    templateId,
+                    variables,
+                })) {
+                    continue;
+                }
+                throw new Error(`External layer "${entry.id}" writes workspace-level output "${relativePath}", which \`wp-typia add block\` cannot merge safely. Restrict the layer to block-local files or scaffold it through \`wp-typia create\` instead.`);
+            }
+        }
+    }
+    finally {
+        await layerSeed.cleanup?.();
+    }
+}
+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)];
+}
+async function assertBlockTargetsDoNotExist(projectDir, templateId, variables) {
+    for (const targetPath of collectWorkspaceBlockPaths(projectDir, templateId, variables)) {
+        if (await pathExists(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");
+    const configSource = await readOptionalFile(configPath);
+    if (configSource === null) {
+        return;
+    }
+    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" && isCompoundPersistenceEnabled(variables))) {
+        await syncWorkspacePersistenceArtifacts(projectDir, variables);
+    }
+}
+function assertPersistenceFlagsAllowed(templateId, options) {
+    const hasPersistenceFlags = typeof options.alternateRenderTargets === "string" ||
+        typeof options.dataStorageMode === "string" ||
+        typeof options.persistencePolicy === "string";
+    if (!hasPersistenceFlags) {
+        return;
+    }
+    if (templateId === "persistence" || templateId === "compound") {
+        parseAlternateRenderTargets(options.alternateRenderTargets);
+        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.`);
+        }
+        if (templateId === "compound" &&
+            typeof options.alternateRenderTargets === "string" &&
+            !options.dataStorageMode &&
+            !options.persistencePolicy) {
+            throw new Error("`--alternate-render-targets` on `wp-typia add block --template compound` requires the persistence-enabled server render path. Add `--data-storage <post-meta|custom-table>` or `--persistence-policy <authenticated|public>` first.");
+        }
+        return;
+    }
+    throw new Error(`--data-storage, --persistence-policy, and --alternate-render-targets are supported only for \`wp-typia add block --template persistence\` or persistence-enabled \`--template compound\`.`);
+}
+function assertCompoundInnerBlocksPresetAllowed(templateId, innerBlocksPreset) {
+    if (!innerBlocksPreset) {
+        return;
+    }
+    if (templateId !== "compound") {
+        throw new Error("`--inner-blocks-preset` is supported only for `wp-typia add block --template compound`.");
+    }
+    parseCompoundInnerBlocksPreset(innerBlocksPreset);
+}
+/**
+ * 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.innerBlocksPreset Optional compound-only InnerBlocks preset
+ * (`freeform`, `ordered`, `horizontal`, or `locked-structure`) that controls
+ * the generated authoring defaults for nested compound containers.
+ * @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,
+ * workspace dependencies have not been installed yet, or target block paths
+ * already exist.
+ */
+export async function runAddBlockCommand({ alternateRenderTargets, blockName, cwd = process.cwd(), dataStorageMode, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, selectExternalLayerId, templateId = "basic", }) {
+    if (templateId === "query-loop") {
+        throw new Error("`wp-typia add block --template query-loop` is not supported. Query Loop is a create-time `core/query` variation scaffold, so use `wp-typia create <project-dir> --template query-loop` instead.");
+    }
+    if (!isAddBlockTemplateId(templateId)) {
+        const mistypedAddBlockTemplateMessage = getMistypedAddBlockTemplateMessage(templateId);
+        if (mistypedAddBlockTemplateMessage) {
+            throw new Error(mistypedAddBlockTemplateMessage);
+        }
+        throw new Error(`Unknown add-block template "${templateId}". Expected one of: ${ADD_BLOCK_TEMPLATE_IDS.join(", ")}. Run \`wp-typia templates list\` to inspect available templates.`);
+    }
+    const resolvedTemplateId = templateId;
+    assertPersistenceFlagsAllowed(resolvedTemplateId, {
+        alternateRenderTargets,
+        dataStorageMode,
+        persistencePolicy,
+    });
+    assertCompoundInnerBlocksPresetAllowed(resolvedTemplateId, innerBlocksPreset);
+    const resolvedInnerBlocksPreset = parseCompoundInnerBlocksPreset(innerBlocksPreset);
+    const workspace = resolveWorkspaceProject(cwd);
+    await assertWorkspaceDependenciesInstalled(workspace);
+    const normalizedExternalLayerId = normalizeOptionalCliString(externalLayerId);
+    const normalizedExternalLayerSource = resolveLocalCliPathOption({
+        cwd,
+        label: "--external-layer-source",
+        value: externalLayerSource,
+    });
+    assertExternalLayerCompositionOptions({
+        externalLayerId: normalizedExternalLayerId,
+        externalLayerSource: normalizedExternalLayerSource,
+    });
+    const resolvedExternalLayerSelection = await resolveOptionalInteractiveExternalLayerId({
+        callerCwd: cwd,
+        externalLayerId: normalizedExternalLayerId,
+        externalLayerSource: normalizedExternalLayerSource,
+        selectExternalLayerId,
+    });
+    let tempRoot = "";
+    let cleanupTempRoot;
+    try {
+        const normalizedSlug = resolveNonEmptyNormalizedBlockSlug({
+            input: blockName,
+            label: "Block name",
+            usage: "wp-typia add block <name> --template <family>",
+        });
+        const defaults = getDefaultAnswers(normalizedSlug, resolvedTemplateId);
+        ({
+            path: tempRoot,
+            cleanup: cleanupTempRoot,
+        } = await createManagedTempRoot("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 (async () => {
+            const scaffoldResult = await scaffoldProject({
+                alternateRenderTargets,
+                answers: {
+                    ...defaults,
+                    author: workspace.author,
+                    compoundInnerBlocksPreset: resolvedInnerBlocksPreset,
+                    namespace: workspace.workspace.namespace,
+                    phpPrefix: blockPhpPrefix,
+                    slug: normalizedSlug,
+                    textDomain: workspace.workspace.textDomain,
+                    title: defaults.title,
+                },
+                cwd: workspace.projectDir,
+                dataStorageMode: dataStorageMode,
+                externalLayerId: resolvedExternalLayerSelection.externalLayerId,
+                externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
+                externalLayerSourceLabel: normalizedExternalLayerSource,
+                noInstall: true,
+                packageManager: workspace.packageManager,
+                persistencePolicy: persistencePolicy,
+                projectDir: tempProjectDir,
+                templateId: resolvedTemplateId,
+            });
+            await assertAddBlockSupportsExternalLayerOutputs({
+                callerCwd: cwd,
+                externalLayerId: resolvedExternalLayerSelection.externalLayerId,
+                externalLayerSource: resolvedExternalLayerSelection.externalLayerSource,
+                templateId: resolvedTemplateId,
+                variables: scaffoldResult.variables,
+            });
+            return scaffoldResult;
+        })();
+        await 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" &&
+                    isCompoundPersistenceEnabled(result.variables)));
+            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,
+                warnings: result.warnings,
+            };
+        }
+        catch (error) {
+            await rollbackWorkspaceMutation(mutationSnapshot);
+            throw error;
+        }
+    }
+    finally {
+        try {
+            await resolvedExternalLayerSelection.cleanup?.();
+        }
+        finally {
+            await cleanupTempRoot?.();
+        }
+    }
+}