@wp-typia/project-tools 0.18.0 → 0.19.0

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

@@ -10,13 +10,17 @@ import { getDefaultAnswers, scaffoldProject } from "./scaffold.js";
 import { copyInterpolatedDirectory, listInterpolatedDirectoryOutputs, } from "./template-render.js";
 import { appendWorkspaceInventoryEntries, } from "./workspace-inventory.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,
@@ -285,10 +311,11 @@ export async function runAddBlockCommand({ blockName, cwd = process.cwd(), dataS
     });
     let tempRoot = "";
     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-"));
         const tempProjectDir = path.join(tempRoot, normalizedSlug);
@@ -305,9 +332,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,

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-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;

package/dist/runtime/cli-scaffold.js

@@ -3,12 +3,15 @@ import { promises as fsp } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, scaffoldProject, } from "./scaffold.js";
+import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
+import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
 import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
+import { assertBuiltInTemplateVariantAllowed, resolveLocalCliPathOption, normalizeOptionalCliString, } from "./cli-validation.js";
 async function listRelativeProjectFiles(rootDir) {
     const relativeFiles = [];
     async function visit(currentDir) {
@@ -36,13 +39,14 @@ async function assertDryRunTargetDirectoryReady(projectDir, allowExistingDir) {
         throw new Error(formatNonEmptyTargetDirectoryError(projectDir));
     }
 }
-async function buildScaffoldDryRunPlan({ allowExistingDir, answers, cwd, dataStorageMode, externalLayerId, externalLayerSource, externalLayerSourceLabel, installDependencies, noInstall, onProgress, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }) {
+async function buildScaffoldDryRunPlan({ allowExistingDir, alternateRenderTargets, answers, cwd, dataStorageMode, externalLayerId, externalLayerSource, externalLayerSourceLabel, installDependencies, noInstall, onProgress, packageManager, persistencePolicy, projectDir, templateId, variant, withMigrationUi, withTestPreset, withWpEnv, }) {
     await assertDryRunTargetDirectoryReady(projectDir, allowExistingDir);
     const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "wp-typia-scaffold-plan-"));
     const previewProjectDir = path.join(tempRoot, "preview-project");
     try {
         const result = await scaffoldProject({
             allowExistingDir: false,
+            alternateRenderTargets,
             answers,
             cwd,
             dataStorageMode,
@@ -109,14 +113,74 @@ function templateUsesPersistenceSettings(templateId, options) {
 function templateSupportsPersistenceFlags(templateId) {
     return templateId === "persistence" || templateId === "compound";
 }
+function templateSupportsCompoundInnerBlocksPreset(templateId) {
+    return templateId === "compound";
+}
+function createTemplateLabel(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        ? "`--template workspace`"
+        : `"${templateId}"`;
+}
+function collectTemplateCapabilityWarnings(options) {
+    const warnings = [];
+    const trimmedQueryPostType = options.queryPostType?.trim();
+    if (trimmedQueryPostType &&
+        options.templateId !== "query-loop" &&
+        (isBuiltInTemplateId(options.templateId) ||
+            options.templateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE)) {
+        warnings.push(`\`--query-post-type\` only applies to \`wp-typia create --template query-loop\`, which scaffolds a create-time \`core/query\` variation instead of a standalone block. ${createTemplateLabel(options.templateId)} will ignore "${trimmedQueryPostType}".`);
+    }
+    if (options.withMigrationUi === true &&
+        !isBuiltInTemplateId(options.templateId) &&
+        options.templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        warnings.push(`\`--with-migration-ui\` was ignored for ${createTemplateLabel(options.templateId)}. Migration UI currently scaffolds built-in templates and the official \`--template workspace\` flow; external templates still need to opt into that surface explicitly.`);
+    }
+    return warnings;
+}
+function templateSupportsAlternateRenderTargets(options) {
+    if (!options.alternateRenderTargets) {
+        return false;
+    }
+    if (options.templateId === "persistence") {
+        return true;
+    }
+    if (options.templateId !== "compound") {
+        return false;
+    }
+    return templateUsesPersistenceSettings(options.templateId, {
+        dataStorageMode: options.dataStorageMode,
+        persistencePolicy: options.persistencePolicy,
+    });
+}
 function validateCreateFlagContract(options) {
-    const { dataStorageMode, persistencePolicy, templateId, variant } = options;
+    const { alternateRenderTargets, dataStorageMode, innerBlocksPreset, persistencePolicy, templateId, variant, } = options;
     if ((dataStorageMode || persistencePolicy) &&
         !templateSupportsPersistenceFlags(templateId)) {
         throw new Error("`--data-storage` and `--persistence-policy` are supported only for `wp-typia create --template persistence` or `--template compound`.");
     }
-    if (variant && isBuiltInTemplateId(templateId)) {
-        throw new Error(`--variant is only supported for official external template configs. Received variant "${variant}" for built-in template "${templateId}".`);
+    if (alternateRenderTargets &&
+        !templateSupportsAlternateRenderTargets({
+            alternateRenderTargets,
+            dataStorageMode,
+            persistencePolicy,
+            templateId,
+        })) {
+        if (templateId === "compound") {
+            throw new Error("`--alternate-render-targets` on `wp-typia create --template compound` requires the persistence-enabled server render path. Add `--data-storage <post-meta|custom-table>` or `--persistence-policy <authenticated|public>` first.");
+        }
+        throw new Error("`--alternate-render-targets` is supported only for `wp-typia create --template persistence` or persistence-enabled `--template compound` scaffolds.");
+    }
+    parseAlternateRenderTargets(alternateRenderTargets);
+    if (innerBlocksPreset &&
+        !templateSupportsCompoundInnerBlocksPreset(templateId)) {
+        throw new Error("`--inner-blocks-preset` is supported only for `wp-typia create --template compound`.");
+    }
+    parseCompoundInnerBlocksPreset(innerBlocksPreset);
+    if (isBuiltInTemplateId(templateId)) {
+        assertBuiltInTemplateVariantAllowed({
+            templateId,
+            variant,
+        });
     }
 }
 function parseSelectableValue(label, value, isValue, allowedValues) {
@@ -203,14 +267,13 @@ export function getOptionalOnboarding({ availableScripts, packageManager, templa
  * project.
  * @returns The scaffold result together with next-step guidance.
  */
-export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, dataStorageMode, dryRun = false, externalLayerId, externalLayerSource, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes = false, noInstall = false, onProgress, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
-    const normalizedExternalLayerId = typeof externalLayerId === "string" && externalLayerId.trim().length > 0
-        ? externalLayerId.trim()
-        : undefined;
-    const normalizedExternalLayerSource = typeof externalLayerSource === "string" &&
-        externalLayerSource.trim().length > 0
-        ? externalLayerSource.trim()
-        : undefined;
+export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templateId, alternateRenderTargets, dataStorageMode, dryRun = false, externalLayerId, externalLayerSource, innerBlocksPreset, persistencePolicy, packageManager, namespace, textDomain, phpPrefix, queryPostType, yes = false, noInstall = false, onProgress, isInteractive = false, allowExistingDir = false, selectTemplate, selectDataStorage, selectExternalLayerId, selectPersistencePolicy, selectPackageManager, promptText, installDependencies = undefined, variant, selectWithTestPreset, selectWithWpEnv, selectWithMigrationUi, withMigrationUi, withTestPreset, withWpEnv, }) {
+    const normalizedExternalLayerId = normalizeOptionalCliString(externalLayerId);
+    const normalizedExternalLayerSource = resolveLocalCliPathOption({
+        cwd,
+        label: "--external-layer-source",
+        value: externalLayerSource,
+    });
     validateCreateProjectInput(projectInput);
     const resolvedTemplateId = await resolveTemplateId({
         templateId,
@@ -219,11 +282,14 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         selectTemplate,
     });
     validateCreateFlagContract({
+        alternateRenderTargets,
         dataStorageMode,
+        innerBlocksPreset,
         persistencePolicy,
         templateId: resolvedTemplateId,
         variant,
     });
+    const resolvedInnerBlocksPreset = parseCompoundInnerBlocksPreset(innerBlocksPreset);
     const resolvedExternalLayerSelection = isBuiltInTemplateId(resolvedTemplateId) && isInteractive
         ? await resolveOptionalInteractiveExternalLayerId({
             callerCwd: cwd,
@@ -302,9 +368,13 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
             yes,
             promptText,
         });
+        if (resolvedTemplateId === "compound" && resolvedInnerBlocksPreset) {
+            answers.compoundInnerBlocksPreset = resolvedInnerBlocksPreset;
+        }
         const resolvedResult = dryRun
             ? await buildScaffoldDryRunPlan({
                 allowExistingDir,
+                alternateRenderTargets,
                 answers,
                 cwd,
                 dataStorageMode: resolvedDataStorage,
@@ -326,6 +396,7 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
             : {
                 plan: undefined,
                 result: await scaffoldProject({
+                    alternateRenderTargets,
                     answers,
                     allowExistingDir,
                     cwd,
@@ -386,6 +457,11 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
                 ...resolvedResult.result,
                 warnings: [
                     ...resolvedResult.result.warnings,
+                    ...collectTemplateCapabilityWarnings({
+                        queryPostType,
+                        templateId: resolvedTemplateId,
+                        withMigrationUi,
+                    }),
                     ...collectProjectDirectoryWarnings(projectDir),
                 ],
             },

package/dist/runtime/cli-templates.js

@@ -21,6 +21,10 @@ export function formatTemplateFeatures(template) {
     if (capabilityHints.length > 0) {
         lines.push(`  Supports: ${capabilityHints.join(" • ")}`);
     }
+    const specialNotes = getTemplateSpecialNotes(template);
+    if (specialNotes.length > 0) {
+        lines.push(`  Notes: ${specialNotes.join(" • ")}`);
+    }
     if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
         lines.push(`  Alias: ${WORKSPACE_TEMPLATE_ALIAS} (\`--template ${WORKSPACE_TEMPLATE_ALIAS}\`)`);
     }
@@ -51,6 +55,13 @@ export function formatTemplateDetails(template) {
             detailLines.push(`  - ${capabilityHint}`);
         }
     }
+    const specialNotes = getTemplateSpecialNotes(template);
+    if (specialNotes.length > 0) {
+        detailLines.push("Notes:");
+        for (const specialNote of specialNotes) {
+            detailLines.push(`  - ${specialNote}`);
+        }
+    }
     detailLines.push("Logical layers:");
     for (const logicalLayer of getTemplateLogicalLayerSummaries(template)) {
         detailLines.push(`  - ${logicalLayer}`);
@@ -60,7 +71,12 @@ export function formatTemplateDetails(template) {
 }
 function getTemplateCapabilityHints(template) {
     if (template.id === "persistence" || template.id === "compound") {
-        return ["--data-storage", "--persistence-policy", "external layers"];
+        return [
+            "--alternate-render-targets",
+            "--data-storage",
+            "--persistence-policy",
+            "external layers",
+        ];
     }
     if (template.id === "query-loop") {
         return ["--query-post-type", "external layers"];
@@ -70,6 +86,15 @@ function getTemplateCapabilityHints(template) {
     }
     return [];
 }
+function getTemplateSpecialNotes(template) {
+    if (template.id === "query-loop") {
+        return [
+            "Create-time variation scaffold only; use `wp-typia create <project-dir> --template query-loop` instead of `wp-typia add block`.",
+            "Owns a `core/query` variation, so it does not generate `src/types.ts`, `block.json`, or Typia manifests.",
+        ];
+    }
+    return [];
+}
 function getTemplateIdentityLines(template) {
     if (template.id === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
         return [

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

@@ -0,0 +1,66 @@
+/**
+ * Normalize one optional CLI string flag by trimming whitespace and collapsing
+ * empty strings to `undefined`.
+ *
+ * @param value Raw CLI value before normalization.
+ * @returns The trimmed string when present, otherwise `undefined`.
+ */
+export declare function normalizeOptionalCliString(value?: string): string | undefined;
+/**
+ * Resolve one CLI path flag relative to the caller when it is expressed as a
+ * local filesystem path.
+ *
+ * Non-local values such as npm package specs or `github:` locators pass
+ * through unchanged. Local relative and absolute paths are resolved against the
+ * provided `cwd` and must exist on disk.
+ *
+ * @param options Path resolution inputs for one CLI flag.
+ * @param options.cwd Caller working directory used for relative path
+ * resolution.
+ * @param options.label Human-readable option label used in thrown errors.
+ * @param options.value Raw CLI value before trimming and path resolution.
+ * @returns The normalized string, or `undefined` when the option was omitted.
+ * @throws When a local-looking path resolves to a missing filesystem entry.
+ */
+export declare function resolveLocalCliPathOption(options: {
+    cwd: string;
+    label: string;
+    value?: string;
+}): string | undefined;
+/**
+ * Validate the built-in template composition rule for external layers.
+ *
+ * @param options External layer CLI options after normalization.
+ * @param options.externalLayerId Optional selected layer id.
+ * @param options.externalLayerSource Optional layer source locator or path.
+ * @throws When `externalLayerId` is provided without `externalLayerSource`.
+ */
+export declare function assertExternalLayerCompositionOptions(options: {
+    externalLayerId?: string;
+    externalLayerSource?: string;
+}): void;
+/**
+ * Build the shared error message used when a built-in template receives a
+ * `--variant` override.
+ *
+ * @param options Built-in template context.
+ * @param options.templateId Built-in template id that rejected the variant.
+ * @param options.variant User-supplied variant override.
+ * @returns The canonical user-facing error message.
+ */
+export declare function createBuiltInVariantErrorMessage(options: {
+    templateId: string;
+    variant: string;
+}): string;
+/**
+ * Reject unsupported `--variant` usage for built-in templates.
+ *
+ * @param options Built-in template validation context.
+ * @param options.templateId Built-in template id being scaffolded.
+ * @param options.variant Optional variant override from CLI flags.
+ * @throws When a built-in template receives any explicit `--variant` value.
+ */
+export declare function assertBuiltInTemplateVariantAllowed(options: {
+    templateId: string;
+    variant?: string;
+}): void;