@wp-typia/project-tools 0.11.1

package/README.md

@@ -0,0 +1,32 @@
+# `@wp-typia/project-tools`
+
+Programmatic project orchestration package for `wp-typia`.
+
+Package roles:
+
+- `wp-typia` owns the CLI, help, TUI, completions, skills, MCP, and bin entry.
+- `@wp-typia/project-tools` owns scaffold, add-block, migrate, template, doctor, and schema project helpers.
+- `@wp-typia/block-runtime/*` owns generated-project runtime helpers.
+- `@wp-typia/create` is the deprecated legacy package shell.
+
+Supported public imports:
+
+- `@wp-typia/project-tools`
+- `@wp-typia/project-tools/schema-core`
+
+Example:
+
+```ts
+import {
+	getTemplateById,
+	parseMigrationArgs,
+	projectJsonSchemaDocument,
+	resolvePackageManagerId,
+} from "@wp-typia/project-tools";
+```
+
+```ts
+import { normalizeEndpointAuthDefinition } from "@wp-typia/project-tools/schema-core";
+```
+
+If you need metadata sync, editor helpers, validation helpers, or other generated-project runtime utilities, import them directly from `@wp-typia/block-runtime/*`.

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

@@ -0,0 +1,38 @@
+/**
+ * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
+ */
+export declare const ADD_KIND_IDS: readonly ["block", "variation", "pattern"];
+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];
+interface RunAddBlockCommandOptions {
+    blockName: string;
+    cwd?: string;
+    dataStorageMode?: string;
+    persistencePolicy?: string;
+    templateId?: string;
+}
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+export declare function formatAddHelpText(): string;
+/**
+ * Seeds an empty official workspace migration project before any blocks are added.
+ */
+export declare function seedWorkspaceMigrationProject(projectDir: string, currentMigrationVersion: string): Promise<void>;
+/**
+ * Adds one built-in block slice to an official workspace project.
+ */
+export declare function runAddBlockCommand({ blockName, cwd, dataStorageMode, persistencePolicy, templateId, }: RunAddBlockCommandOptions): Promise<{
+    blockSlugs: string[];
+    projectDir: string;
+    templateId: AddBlockTemplateId;
+}>;
+/**
+ * Returns the current placeholder guidance for unsupported `wp-typia add` kinds.
+ */
+export declare function createAddPlaceholderMessage(kind: Exclude<AddKindId, "block">): string;
+export {};

package/dist/runtime/cli-add.js

@@ -0,0 +1,561 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defineEndpointManifest, syncBlockMetadata, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+import { ensureMigrationDirectories, parseMigrationConfig, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
+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";
+/**
+ * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
+ */
+export const ADD_KIND_IDS = ["block", "variation", "pattern"];
+/**
+ * Supported built-in block families accepted by `wp-typia add block --template`.
+ */
+export const ADD_BLOCK_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "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";
+    }
+}
+function normalizeBlockSlug(input) {
+    return toKebabCase(input);
+}
+function buildWorkspacePhpPrefix(workspacePhpPrefix, slug) {
+    return toSnakeCase(`${workspacePhpPrefix}_${slug}`);
+}
+function isAddBlockTemplateId(value) {
+    return ADD_BLOCK_TEMPLATE_IDS.includes(value);
+}
+function quoteTsString(value) {
+    return JSON.stringify(value);
+}
+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'state-query': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateQuery`)},`,
+        "\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'state-response': {",
+        `\t\t\t\t\tsourceTypeName: ${quoteTsString(`${variables.pascalCase}StateResponse`)},`,
+        "\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\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 buildPersistenceEndpointManifest(variables) {
+    return defineEndpointManifest({
+        contracts: {
+            "state-query": {
+                sourceTypeName: `${variables.pascalCase}StateQuery`,
+            },
+            "write-state-request": {
+                sourceTypeName: `${variables.pascalCase}WriteStateRequest`,
+            },
+            "state-response": {
+                sourceTypeName: `${variables.pascalCase}StateResponse`,
+            },
+        },
+        endpoints: [
+            {
+                auth: "public",
+                method: "GET",
+                operationId: `get${variables.pascalCase}State`,
+                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
+                queryContract: "state-query",
+                responseContract: "state-response",
+                summary: "Read the current persisted state.",
+                tags: [variables.title],
+            },
+            {
+                auth: variables.restWriteAuthIntent,
+                bodyContract: "write-state-request",
+                method: "POST",
+                operationId: `write${variables.pascalCase}State`,
+                path: `/${variables.namespace}/v1/${variables.slugKebabCase}/state`,
+                responseContract: "state-response",
+                summary: "Write the current persisted state.",
+                tags: [variables.title],
+                wordpressAuth: {
+                    mechanism: variables.restWriteAuthMechanism,
+                },
+            },
+        ],
+        info: {
+            title: `${variables.title} REST API`,
+            version: "1.0.0",
+        },
+    });
+}
+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 patchFile(filePath, transform) {
+    const currentSource = await fsp.readFile(filePath, "utf8");
+    const nextSource = transform(currentSource);
+    if (nextSource !== currentSource) {
+        await fsp.writeFile(filePath, nextSource, "utf8");
+    }
+}
+async function readOptionalFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return fsp.readFile(filePath, "utf8");
+}
+async function restoreOptionalFile(filePath, source) {
+    if (source === null) {
+        await fsp.rm(filePath, { force: true });
+        return;
+    }
+    await fsp.mkdir(path.dirname(filePath), { recursive: true });
+    await fsp.writeFile(filePath, source, "utf8");
+}
+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) {
+    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];`);
+    });
+}
+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 copyScaffoldedBlockSlice(projectDir, templateId, tempProjectDir, variables) {
+    if (templateId === "compound") {
+        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) {
+    const manifest = buildPersistenceEndpointManifest(variables);
+    const apiTypesFile = path.join("src", "blocks", variables.slugKebabCase, "api-types.ts");
+    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
+        await syncTypeSchemas({
+            jsonSchemaFile: path.join("src", "blocks", variables.slugKebabCase, "api-schemas", `${baseName}.schema.json`),
+            openApiFile: path.join("src", "blocks", variables.slugKebabCase, "api-schemas", `${baseName}.openapi.json`),
+            projectRoot: projectDir,
+            sourceTypeName: contract.sourceTypeName,
+            typesFile: apiTypesFile,
+        });
+    }
+    await syncRestOpenApi({
+        manifest,
+        openApiFile: path.join("src", "blocks", variables.slugKebabCase, "api.openapi.json"),
+        projectRoot: projectDir,
+        typesFile: apiTypesFile,
+    });
+    await syncEndpointClient({
+        clientFile: path.join("src", "blocks", variables.slugKebabCase, "api-client.ts"),
+        manifest,
+        projectRoot: projectDir,
+        typesFile: apiTypesFile,
+    });
+}
+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 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";
+    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\`.`);
+}
+/**
+ * Returns help text for the canonical `wp-typia add` subcommands.
+ */
+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
+
+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.`;
+}
+/**
+ * Seeds an empty official workspace migration project before any blocks are added.
+ */
+export async function seedWorkspaceMigrationProject(projectDir, currentMigrationVersion) {
+    writeMigrationConfig(projectDir, {
+        blocks: [],
+        currentMigrationVersion,
+        snapshotDir: "src/migrations/versions",
+        supportedMigrationVersions: [currentMigrationVersion],
+    });
+    ensureMigrationDirectories(projectDir, []);
+    writeInitialMigrationScaffold(projectDir, currentMigrationVersion, []);
+}
+async function rollbackWorkspaceMutation(projectDir, 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);
+}
+/**
+ * Adds one built-in block slice to an official workspace project.
+ */
+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 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 migrationConfig = migrationConfigSource === null ? null : parseMigrationConfig(migrationConfigSource);
+        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 = {
+            blockConfigSource,
+            migrationConfigSource,
+            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);
+            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(workspace.projectDir, mutationSnapshot);
+            throw error;
+        }
+    }
+    finally {
+        if (tempRoot) {
+            await fsp.rm(tempRoot, { force: true, recursive: true });
+        }
+    }
+}
+/**
+ * Returns the current placeholder guidance for unsupported `wp-typia add` kinds.
+ */
+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.`;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Public runtime helper barrel consumed by the canonical `wp-typia` package.
+ *
+ * These exports do not make `@wp-typia/project-tools` the CLI owner again. Command
+ * taxonomy, help text ownership, and published bin responsibility stay in
+ * `packages/wp-typia`.
+ *
+ * Import `formatAddHelpText`, `runAddBlockCommand`,
+ * `createAddPlaceholderMessage`, and `seedWorkspaceMigrationProject` for
+ * explicit `wp-typia add` flows,
+ * `getDoctorChecks`, `runDoctor`, and `DoctorCheck` for diagnostics,
+ * `formatHelpText` for top-level CLI usage output, scaffold helpers such as
+ * `createReadlinePrompt`, `getNextSteps`, `getOptionalOnboarding`,
+ * `runScaffoldFlow`, and `ReadlinePrompt` for interactive project creation,
+ * and template helpers such as `formatTemplateDetails`,
+ * `formatTemplateFeatures`, `formatTemplateSummary`, `getTemplateById`,
+ * `getTemplateSelectOptions`, `listTemplates`, and `isBuiltInTemplateId` for
+ * template inspection flows.
+ */
+export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
+export { createAddPlaceholderMessage, formatAddHelpText, runAddBlockCommand, seedWorkspaceMigrationProject } from "./cli-add.js";
+export { formatHelpText } from "./cli-help.js";
+export { getNextSteps, getOptionalOnboarding, runScaffoldFlow, } from "./cli-scaffold.js";
+export { createReadlinePrompt, type ReadlinePrompt } from "./cli-prompt.js";
+export { formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getTemplateById, getTemplateSelectOptions, isBuiltInTemplateId, listTemplates, } from "./cli-templates.js";