@wp-typia/project-tools 0.18.0 → 0.19.1

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

@@ -1,6 +1,5 @@
 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";
@@ -9,14 +8,19 @@ import { snapshotProjectVersion } from "./migrations.js";
 import { getDefaultAnswers, scaffoldProject } from "./scaffold.js";
 import { copyInterpolatedDirectory, listInterpolatedDirectoryOutputs, } from "./template-render.js";
 import { appendWorkspaceInventoryEntries, } from "./workspace-inventory.js";
+import { createManagedTempRoot } from "./temp-roots.js";
 import { resolveWorkspaceProject, } from "./workspace-project.js";
-import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, normalizeBlockSlug, patchFile, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, patchFile, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { resolveNonEmptyNormalizedBlockSlug, } from "./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 "./template-source.js";
 import { resolveExternalTemplateLayers, } from "./template-layers.js";
 import { formatInstallCommand, } from "./package-managers.js";
+import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
+import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { assertExternalLayerCompositionOptions, normalizeOptionalCliString, resolveLocalCliPathOption, } from "./cli-validation.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.
@@ -61,21 +65,6 @@ async function renderWorkspacePersistenceServerModule(projectDir, variables) {
     const templateDir = buildServerTemplateRoot(variables.persistencePolicy);
     await copyInterpolatedDirectory(templateDir, targetDir, variables);
 }
-function normalizeExternalLayerOption(value) {
-    if (typeof value !== "string") {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function resolveExternalLayerSourceFromCaller(source, callerCwd) {
-    if (typeof source !== "string" ||
-        source.length === 0 ||
-        !(path.isAbsolute(source) || source.startsWith("./") || source.startsWith("../"))) {
-        return source;
-    }
-    return path.resolve(callerCwd, source);
-}
 function hasInstalledWorkspaceDependencies(projectDir) {
     return WORKSPACE_INSTALL_MARKERS.some((marker) => fs.existsSync(path.join(projectDir, marker)));
 }
@@ -207,12 +196,14 @@ async function syncWorkspaceAddedBlockArtifacts(projectDir, templateId, variable
     }
 }
 function assertPersistenceFlagsAllowed(templateId, options) {
-    const hasPersistenceFlags = typeof options.dataStorageMode === "string" ||
+    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") {
@@ -223,9 +214,24 @@ function assertPersistenceFlagsAllowed(templateId, options) {
             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 and --persistence-policy are supported only for \`wp-typia add block --template persistence\` or \`--template compound\`.`);
+    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.
@@ -255,6 +261,9 @@ export async function seedWorkspaceMigrationProject(projectDir, currentMigration
  * 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
@@ -267,16 +276,33 @@ export async function seedWorkspaceMigrationProject(projectDir, currentMigration
  * workspace dependencies have not been installed yet, or target block paths
  * already exist.
  */
-export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataStorageMode, externalLayerId, externalLayerSource, persistencePolicy, selectExternalLayerId, templateId = "basic", }) {
+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)) {
         throw new Error(`Unknown add-block template "${templateId}". Expected one of: ${ADD_BLOCK_TEMPLATE_IDS.join(", ")}`);
     }
     const resolvedTemplateId = templateId;
-    assertPersistenceFlagsAllowed(resolvedTemplateId, { dataStorageMode, persistencePolicy });
+    assertPersistenceFlagsAllowed(resolvedTemplateId, {
+        alternateRenderTargets,
+        dataStorageMode,
+        persistencePolicy,
+    });
+    assertCompoundInnerBlocksPresetAllowed(resolvedTemplateId, innerBlocksPreset);
+    const resolvedInnerBlocksPreset = parseCompoundInnerBlocksPreset(innerBlocksPreset);
     const workspace = resolveWorkspaceProject(cwd);
     assertWorkspaceDependenciesInstalled(workspace);
-    const normalizedExternalLayerId = normalizeExternalLayerOption(externalLayerId);
-    const normalizedExternalLayerSource = resolveExternalLayerSourceFromCaller(normalizeExternalLayerOption(externalLayerSource), cwd);
+    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,
@@ -284,13 +310,18 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
         selectExternalLayerId,
     });
     let tempRoot = "";
+    let cleanupTempRoot;
     try {
-        const normalizedSlug = normalizeBlockSlug(blockName);
-        if (!normalizedSlug) {
-            throw new Error("Block name is required. Use `wp-typia add block <name> --template <family>`.");
-        }
+        const normalizedSlug = resolveNonEmptyNormalizedBlockSlug({
+            input: blockName,
+            label: "Block name",
+            usage: "wp-typia add block <name> --template <family>",
+        });
         const defaults = getDefaultAnswers(normalizedSlug, resolvedTemplateId);
-        tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-add-block-"));
+        ({
+            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");
@@ -305,9 +336,11 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
             : [];
         const result = await (async () => {
             const scaffoldResult = await scaffoldProject({
+                alternateRenderTargets,
                 answers: {
                     ...defaults,
                     author: workspace.author,
+                    compoundInnerBlocksPreset: resolvedInnerBlocksPreset,
                     namespace: workspace.workspace.namespace,
                     phpPrefix: blockPhpPrefix,
                     slug: normalizedSlug,
@@ -368,9 +401,11 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
         }
     }
     finally {
-        await resolvedExternalLayerSelection.cleanup?.();
-        if (tempRoot) {
-            await fsp.rm(tempRoot, { force: true, recursive: true });
+        try {
+            await resolvedExternalLayerSelection.cleanup?.();
+        }
+        finally {
+            await cleanupTempRoot?.();
         }
     }
 }

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

@@ -1,6 +1,7 @@
 import { type HookedBlockPositionId } from "./hooked-blocks.js";
 import { type WorkspaceInventory } from "./workspace-inventory.js";
 import { type WorkspaceProject } from "./workspace-project.js";
+export { normalizeBlockSlug, } from "./scaffold-identifiers.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
@@ -63,11 +64,13 @@ export interface RunAddEditorPluginCommandOptions {
     slot?: string;
 }
 export interface RunAddBlockCommandOptions {
+    alternateRenderTargets?: string;
     blockName: string;
     cwd?: string;
     dataStorageMode?: string;
     externalLayerId?: string;
     externalLayerSource?: string;
+    innerBlocksPreset?: string;
     persistencePolicy?: string;
     selectExternalLayerId?: (options: Array<{
         description?: string;
@@ -89,7 +92,6 @@ export interface WorkspaceMutationSnapshot {
     /** 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 assertValidRestResourceNamespace(namespace: string): string;
 export declare function resolveRestResourceNamespace(workspaceNamespace: string, namespace?: string): string;

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

@@ -3,8 +3,9 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_IDS, } from "./hooked-blocks.js";
-import { toKebabCase, toSnakeCase, } from "./string-case.js";
+import { toSnakeCase, } from "./string-case.js";
 import { WORKSPACE_TEMPLATE_PACKAGE, } from "./workspace-project.js";
+export { normalizeBlockSlug, } from "./scaffold-identifiers.js";
 /**
  * Supported top-level `wp-typia add` kinds exposed by the canonical CLI.
  */
@@ -43,9 +44,6 @@ export const ADD_BLOCK_TEMPLATE_IDS = [
 ];
 const WORKSPACE_GENERATED_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
 export const REST_RESOURCE_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*(?:\/[a-z0-9-]+)+$/u;
-export function normalizeBlockSlug(input) {
-    return toKebabCase(input);
-}
 export function assertValidGeneratedSlug(label, slug, usage) {
     if (!slug) {
         throw new Error(`${label} is required. Use \`${usage}\`.`);
@@ -279,16 +277,18 @@ export function assertEditorPluginDoesNotExist(projectDir, editorPluginSlug, inv
  */
 export function formatAddHelpText() {
     return `Usage:
-  wp-typia add block <name> --template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
-  wp-typia add variation <name> --block <block-slug>
-  wp-typia add pattern <name>
-  wp-typia add binding-source <name>
-  wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create,update,delete>]
-  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}>
-  wp-typia add editor-plugin <name> [--slot <${EDITOR_PLUGIN_SLOT_IDS.join("|")}>]
+  wp-typia add block <name> --template <${ADD_BLOCK_TEMPLATE_IDS.join("|")}> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--dry-run]
+  wp-typia add variation <name> --block <block-slug> [--dry-run]
+  wp-typia add pattern <name> [--dry-run]
+  wp-typia add binding-source <name> [--dry-run]
+  wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create,update,delete>] [--dry-run]
+  wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <${HOOKED_BLOCK_POSITION_IDS.join("|")}> [--dry-run]
+  wp-typia add editor-plugin <name> [--slot <${EDITOR_PLUGIN_SLOT_IDS.join("|")}>] [--dry-run]
 
 Notes:
-  \`wp-typia add\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces.
+  \`wp-typia add\` runs only inside official ${WORKSPACE_TEMPLATE_PACKAGE} workspaces scaffolded via \`wp-typia create <project-dir> --template workspace\`.
+  Pass \`--dry-run\` to preview the workspace files that would change without writing them.
+  \`query-loop\` is a create-time scaffold family. Use \`wp-typia create <project-dir> --template query-loop\` instead of \`wp-typia add block\`.
   \`add variation\` targets an existing block slug from \`scripts/block-config.ts\`.
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.

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

@@ -27,6 +27,8 @@ export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
 export { createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export type { CliDiagnosticMessage } from "./cli-diagnostics.js";
 export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
+export type { CompoundInnerBlocksPresetId } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export type { EditorPluginSlotId } from "./cli-add.js";
 export type { HookedBlockPositionId } from "./hooked-blocks.js";

package/dist/runtime/cli-core.js

@@ -26,6 +26,7 @@
 export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
 export { createCliCommandError, CliDiagnosticError, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddBindingSourceCommand, runAddBlockCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export { formatHelpText } from "./cli-help.js";
 export { getNextSteps, getOptionalOnboarding, runScaffoldFlow, } from "./cli-scaffold.js";

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

@@ -2,10 +2,24 @@
  * Shared human-readable diagnostics for non-interactive `wp-typia` CLI flows.
  */
 export interface CliDiagnosticMessage {
+    code: CliDiagnosticCode;
     command: string;
     detailLines: string[];
     summary: string;
 }
+export declare const CLI_DIAGNOSTIC_CODES: {
+    readonly COMMAND_EXECUTION: "command-execution";
+    readonly CONFIGURATION_MISSING: "configuration-missing";
+    readonly DEPENDENCIES_NOT_INSTALLED: "dependencies-not-installed";
+    readonly DOCTOR_CHECK_FAILED: "doctor-check-failed";
+    readonly INVALID_ARGUMENT: "invalid-argument";
+    readonly INVALID_COMMAND: "invalid-command";
+    readonly MISSING_ARGUMENT: "missing-argument";
+    readonly MISSING_BUILD_ARTIFACT: "missing-build-artifact";
+    readonly OUTSIDE_PROJECT_ROOT: "outside-project-root";
+    readonly UNSUPPORTED_COMMAND: "unsupported-command";
+};
+export type CliDiagnosticCode = (typeof CLI_DIAGNOSTIC_CODES)[keyof typeof CLI_DIAGNOSTIC_CODES];
 type DoctorCheckLike = {
     detail: string;
     label: string;
@@ -15,6 +29,7 @@ type DoctorCheckLike = {
  * Structured CLI failure carrying a stable summary/detail layout.
  */
 export declare class CliDiagnosticError extends Error {
+    readonly code: CliDiagnosticCode;
     readonly command: string;
     readonly detailLines: string[];
     readonly summary: string;
@@ -29,6 +44,7 @@ export declare function isCliDiagnosticError(error: unknown): error is CliDiagno
  */
 export declare function createCliCommandError(options: {
     command: string;
+    code?: CliDiagnosticCode;
     detailLines?: string[];
     error?: unknown;
     summary?: string;
@@ -38,6 +54,16 @@ export declare function createCliCommandError(options: {
  * plain message so existing non-command failures keep working.
  */
 export declare function formatCliDiagnosticError(error: unknown): string;
+export declare function serializeCliDiagnosticError(error: unknown): {
+    code: CliDiagnosticCode;
+    command?: string;
+    detailLines?: string[];
+    kind: "command-execution";
+    message: string;
+    name: string;
+    summary?: string;
+    tag: "CommandExecutionError";
+};
 /**
  * Format one human-readable doctor check row.
  */

package/dist/runtime/cli-diagnostics.js

@@ -1,8 +1,23 @@
+export const CLI_DIAGNOSTIC_CODES = {
+    COMMAND_EXECUTION: "command-execution",
+    CONFIGURATION_MISSING: "configuration-missing",
+    DEPENDENCIES_NOT_INSTALLED: "dependencies-not-installed",
+    DOCTOR_CHECK_FAILED: "doctor-check-failed",
+    INVALID_ARGUMENT: "invalid-argument",
+    INVALID_COMMAND: "invalid-command",
+    MISSING_ARGUMENT: "missing-argument",
+    MISSING_BUILD_ARTIFACT: "missing-build-artifact",
+    OUTSIDE_PROJECT_ROOT: "outside-project-root",
+    UNSUPPORTED_COMMAND: "unsupported-command",
+};
 const DEFAULT_CLI_FAILURE_SUMMARIES = {
     add: "Unable to complete the requested add workflow.",
     create: "Unable to complete the requested create workflow.",
     doctor: "One or more doctor checks failed.",
+    mcp: "Unable to inspect or sync MCP metadata.",
     migrate: "Unable to complete the requested migration command.",
+    sync: "Unable to complete the requested sync workflow.",
+    templates: "Unable to inspect scaffold templates.",
 };
 const MIN_CLI_WRAP_COLUMNS = 32;
 function parseCliColumns(value) {
@@ -104,6 +119,7 @@ function normalizeDetailLines(detailLines) {
 export class CliDiagnosticError extends Error {
     constructor(message, options) {
         super(formatCliDiagnosticBlock(message), options);
+        this.code = message.code;
         this.command = message.command;
         this.detailLines = [...message.detailLines];
         this.name = "CliDiagnosticError";
@@ -116,6 +132,59 @@ export class CliDiagnosticError extends Error {
 export function isCliDiagnosticError(error) {
     return error instanceof CliDiagnosticError;
 }
+function isCliDiagnosticCode(value) {
+    return Object.values(CLI_DIAGNOSTIC_CODES).includes(value);
+}
+function readCliDiagnosticCode(error) {
+    if (isCliDiagnosticError(error)) {
+        return error.code;
+    }
+    if (typeof error === "object" && error !== null && "code" in error) {
+        const { code } = error;
+        if (isCliDiagnosticCode(code)) {
+            return code;
+        }
+    }
+    return null;
+}
+function inferCliDiagnosticCode(options) {
+    const inheritedCode = readCliDiagnosticCode(options.error);
+    if (inheritedCode) {
+        return inheritedCode;
+    }
+    const haystack = normalizeDetailLines([
+        ...options.detailLines,
+        options.error === undefined ? undefined : getErrorMessage(options.error),
+    ]).join("\n");
+    if (/No MCP schema sources are configured\./u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.CONFIGURATION_MISSING;
+    }
+    if (/Missing bundled build artifacts/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.MISSING_BUILD_ARTIFACT;
+    }
+    if (/No generated wp-typia project root was found/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.OUTSIDE_PROJECT_ROOT;
+    }
+    if (/dependencies have not been installed yet/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.DEPENDENCIES_NOT_INSTALLED;
+    }
+    if (options.command === "doctor") {
+        return CLI_DIAGNOSTIC_CODES.DOCTOR_CHECK_FAILED;
+    }
+    if (/requires <|requires --/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT;
+    }
+    if (/Unknown .*subcommand|Unknown add kind|Unknown template|removed in favor|does not support|The Bun-free fallback runtime does not support|The positional alias only accepts/u.test(haystack)) {
+        return haystack.includes("does not support") ||
+            haystack.includes("The Bun-free fallback runtime does not support")
+            ? CLI_DIAGNOSTIC_CODES.UNSUPPORTED_COMMAND
+            : CLI_DIAGNOSTIC_CODES.INVALID_COMMAND;
+    }
+    if (/Invalid |must start with|cannot hook|cannot nest|cannot use|cannot be|already defines|already exists|Expected one of/u.test(haystack)) {
+        return CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT;
+    }
+    return CLI_DIAGNOSTIC_CODES.COMMAND_EXECUTION;
+}
 /**
  * Build a shared diagnostic error for one CLI command failure.
  */
@@ -125,7 +194,14 @@ export function createCliCommandError(options) {
     }
     const summary = options.summary ?? DEFAULT_CLI_FAILURE_SUMMARIES[options.command] ?? "Command failed.";
     const detailLines = normalizeDetailLines(options.detailLines ?? [options.error === undefined ? undefined : getErrorMessage(options.error)]);
+    const code = options.code ??
+        inferCliDiagnosticCode({
+            command: options.command,
+            detailLines,
+            error: options.error,
+        });
     return new CliDiagnosticError({
+        code,
         command: options.command,
         detailLines,
         summary,
@@ -140,11 +216,42 @@ export function formatCliDiagnosticError(error) {
         return getErrorMessage(error);
     }
     return formatCliDiagnosticBlock({
+        code: error.code,
         command: error.command,
         detailLines: error.detailLines,
         summary: error.summary,
     });
 }
+export function serializeCliDiagnosticError(error) {
+    if (isCliDiagnosticError(error)) {
+        return {
+            code: error.code,
+            command: error.command,
+            detailLines: [...error.detailLines],
+            kind: "command-execution",
+            message: formatCliDiagnosticBlock({
+                code: error.code,
+                command: error.command,
+                detailLines: error.detailLines,
+                summary: error.summary,
+            }),
+            name: error.name,
+            summary: error.summary,
+            tag: "CommandExecutionError",
+        };
+    }
+    return {
+        code: inferCliDiagnosticCode({
+            command: "unknown",
+            detailLines: [],
+            error,
+        }),
+        kind: "command-execution",
+        message: getErrorMessage(error),
+        name: error instanceof Error ? error.name : "Error",
+        tag: "CommandExecutionError",
+    };
+}
 /**
  * Format one human-readable doctor check row.
  */

package/dist/runtime/cli-doctor-workspace.js

@@ -351,21 +351,21 @@ export function getWorkspaceDoctorChecks(cwd) {
         workspace = tryResolveWorkspaceProject(cwd);
     }
     catch (error) {
-        checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace discovery could not continue. Fix the nearby workspace package metadata and rerun `wp-typia doctor`."));
+        checks.push(createDoctorScopeCheck("fail", "Scope: blocked before workspace checks. Environment checks ran, but workspace discovery could not continue. Fix the nearby workspace package metadata and rerun `wp-typia doctor`."));
         checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
         return checks;
     }
     if (!workspace) {
         if (invalidWorkspaceReason) {
-            checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace diagnostics could not continue because a nearby wp-typia workspace candidate is invalid. Fix the workspace package metadata and rerun `wp-typia doctor`."));
+            checks.push(createDoctorScopeCheck("fail", "Scope: blocked before workspace checks. Environment checks ran, but workspace diagnostics could not continue because a nearby wp-typia workspace candidate is invalid. Fix the workspace package metadata and rerun `wp-typia doctor`."));
             checks.push(createDoctorCheck("Workspace package metadata", "fail", invalidWorkspaceReason));
         }
         else {
-            checks.push(createDoctorScopeCheck("pass", "No official wp-typia workspace root was detected, so this run only covered environment readiness. Re-run `wp-typia doctor` from a workspace root if you expected package metadata, inventory, or generated artifact checks."));
+            checks.push(createDoctorScopeCheck("pass", "Scope: environment-only. No official wp-typia workspace root was detected, so this run only covered environment readiness. Re-run `wp-typia doctor` from a workspace root if you expected package metadata, inventory, or generated artifact checks."));
         }
         return checks;
     }
-    checks.push(createDoctorScopeCheck("pass", `Official workspace detected for ${workspace.workspace.namespace}; environment readiness checks ran and workspace-scoped diagnostics are enabled for the package metadata, inventory, source-tree drift, and any configured migration hint rows below.`));
+    checks.push(createDoctorScopeCheck("pass", `Scope: full workspace diagnostics for ${workspace.workspace.namespace}. Environment readiness checks ran and workspace-scoped diagnostics are enabled for the package metadata, inventory, source-tree drift, and any configured migration hint rows below.`));
     let workspacePackageJson;
     try {
         workspacePackageJson = parseWorkspacePackageJson(workspace.projectDir);

package/dist/runtime/cli-help.js

@@ -14,10 +14,10 @@ export function formatHelpText() {
   wp-typia create <project-dir> [--template query-loop] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--query-post-type <post-type>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template <./path|github:owner/repo/path[#ref]>] [--variant <name>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template <npm-package>] [--variant <name>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
-  wp-typia create <project-dir> [--template persistence] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
-  wp-typia create <project-dir> [--template compound] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template persistence] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
+  wp-typia create <project-dir> [--template compound] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia <project-dir> [create flags...]
-  wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
+  wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
   wp-typia add variation <name> --block <block-slug>
   wp-typia add pattern <name>
   wp-typia add binding-source <name>
@@ -38,6 +38,7 @@ Notes:
   \`wp-typia create\` is the canonical scaffold command.
   \`wp-typia <project-dir>\` remains a backward-compatible alias to \`create\` when \`<project-dir>\` is the only positional argument.
   Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
+  \`query-loop\` is create-only. Use \`wp-typia create <project-dir> --template query-loop\`; \`wp-typia add block\` accepts only basic, interactivity, persistence, and compound families.
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.

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

@@ -26,12 +26,14 @@ export interface ScaffoldDryRunPlan {
 }
 interface RunScaffoldFlowOptions {
     allowExistingDir?: boolean;
+    alternateRenderTargets?: string;
     cwd?: string;
     dataStorageMode?: string;
     dryRun?: boolean;
     externalLayerId?: string;
     externalLayerSource?: string;
     installDependencies?: Parameters<typeof scaffoldProject>[0]["installDependencies"];
+    innerBlocksPreset?: string;
     isInteractive?: boolean;
     namespace?: string;
     noInstall?: boolean;
@@ -80,7 +82,7 @@ export declare function getOptionalOnboarding({ availableScripts, packageManager
  * project.
  * @returns The scaffold result together with next-step guidance.
  */
-export declare function runScaffoldFlow({ projectInput, cwd, templateId, dataStorageMode, dryRun, externalLayerId, externalLayerSource, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes, noInstall, onProgress, isInteractive, allowExistingDir, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }: RunScaffoldFlowOptions): Promise<{
+export declare function runScaffoldFlow({ projectInput, cwd, templateId, alternateRenderTargets, dataStorageMode, dryRun, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes, noInstall, onProgress, isInteractive, allowExistingDir, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }: RunScaffoldFlowOptions): Promise<{
     dryRun: boolean;
     optionalOnboarding: OptionalOnboardingGuidance;
     plan: ScaffoldDryRunPlan | undefined;