@wp-typia/project-tools 0.18.0 → 0.19.1

package/dist/runtime/package-versions.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { PROJECT_TOOLS_PACKAGE_ROOT } from "./template-registry.js";
 const require = createRequire(import.meta.url);
 const DEFAULT_VERSION_RANGE = "^0.0.0";
+const DEFAULT_EXACT_VERSION = "0.0.0";
 let cachedPackageVersions = null;
 function getErrorCode(error) {
     return typeof error === "object" && error !== null && "code" in error
@@ -20,6 +21,16 @@ function normalizeVersionRange(value) {
     }
     return /^[~^<>=]/.test(trimmed) ? trimmed : `^${trimmed}`;
 }
+function normalizeExactVersion(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return DEFAULT_EXACT_VERSION;
+    }
+    if (trimmed.startsWith("workspace:")) {
+        return DEFAULT_EXACT_VERSION;
+    }
+    return trimmed.replace(/^[~^<>=]+/, "");
+}
 function readPackageManifest(packageJsonPath) {
     try {
         return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
@@ -67,6 +78,7 @@ export function getPackageVersions() {
         projectToolsPackageVersion: normalizeVersionRange(createManifest.version),
         restPackageVersion: normalizeVersionRange(createManifest.dependencies?.["@wp-typia/rest"] ??
             resolveInstalledPackageManifest("@wp-typia/rest")?.version),
+        wpTypiaPackageExactVersion: normalizeExactVersion(wpTypiaManifest.version),
         wpTypiaPackageVersion: normalizeVersionRange(wpTypiaManifest.version),
     };
     return cachedPackageVersions;

package/dist/runtime/scaffold-answer-resolution.js

@@ -10,6 +10,7 @@ const TEMPLATE_SELECTION_HINT = `--template <${[
     WORKSPACE_TEMPLATE_ALIAS,
 ].join('|')}|./path|github:owner/repo/path[#ref]|npm-package>`;
 const TEMPLATE_SUGGESTION_IDS = [...TEMPLATE_IDS, WORKSPACE_TEMPLATE_ALIAS];
+const QUERY_POST_TYPE_RULE = 'Use lowercase, 1-20 chars, and only a-z, 0-9, "_" or "-".';
 /**
  * Detect the current author name from local Git config.
  *
@@ -50,12 +51,15 @@ export function getDefaultAnswers(projectName, templateId) {
     };
 }
 function validateQueryPostType(value) {
-    const normalizedValue = value.trim().toLowerCase();
+    const rawValue = value.trim();
+    const normalizedValue = rawValue.toLowerCase();
     if (normalizedValue.length === 0) {
         return 'Query post type is required.';
     }
     if (!/^[a-z0-9_-]{1,20}$/u.test(normalizedValue)) {
-        return 'Query post type must be lowercase, 1-20 chars, and only a-z, 0-9, "_" or "-".';
+        return rawValue === normalizedValue
+            ? `Query post type "${rawValue}" is invalid. ${QUERY_POST_TYPE_RULE}`
+            : `Query post type "${rawValue}" normalizes to "${normalizedValue}", which is invalid. ${QUERY_POST_TYPE_RULE}`;
     }
     return true;
 }
@@ -63,11 +67,11 @@ function normalizeQueryPostType(value) {
     if (typeof value !== 'string') {
         return undefined;
     }
-    const normalizedValue = value.trim().toLowerCase();
-    if (validateQueryPostType(normalizedValue) !== true) {
-        throw new Error('Query post type must be lowercase, 1-20 chars, and only a-z, 0-9, "_" or "-".');
+    const validationResult = validateQueryPostType(value);
+    if (validationResult !== true) {
+        throw new Error(validationResult);
     }
-    return normalizedValue;
+    return value.trim().toLowerCase();
 }
 function normalizeTemplateSelection(templateId) {
     return templateId === WORKSPACE_TEMPLATE_ALIAS

package/dist/runtime/scaffold-bootstrap.js

@@ -7,6 +7,7 @@ import { syncPersistenceRestArtifacts } from "./persistence-rest-artifacts.js";
 import { getPackageVersions } from "./package-versions.js";
 import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
+import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 /**
  * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
@@ -71,8 +72,11 @@ export async function writeStarterManifestFiles(targetDir, templateId, variables
  * @returns A promise that resolves after any required persistence artifacts are generated.
  */
 export async function seedBuiltInPersistenceArtifacts(targetDir, templateId, variables) {
+    const compoundGroup = getScaffoldTemplateVariableGroups(variables).compound;
     const needsPersistenceArtifacts = templateId === "persistence" ||
-        (templateId === "compound" && variables.compoundPersistenceEnabled === "true");
+        (templateId === "compound" &&
+            compoundGroup.enabled &&
+            compoundGroup.persistenceEnabled);
     if (!needsPersistenceArtifacts) {
         return;
     }

package/dist/runtime/scaffold-documents.js

@@ -1,6 +1,8 @@
 import { getPrimaryDevelopmentScript } from './local-dev-presets.js';
 import { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getInitialCommitNote, getOptionalOnboardingNote, getOptionalOnboardingSteps, getQuickStartWorkflowNote, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from './scaffold-onboarding.js';
-import { formatInstallCommand, formatRunScript, } from './package-managers.js';
+import { formatPackageExecCommand, formatInstallCommand, formatRunScript, } from './package-managers.js';
+import { getPackageVersions } from './package-versions.js';
+import { getScaffoldTemplateVariableGroups } from './scaffold-template-variable-groups.js';
 /**
  * Builds the generated README markdown for one scaffolded project.
  *
@@ -11,18 +13,38 @@ import { formatInstallCommand, formatRunScript, } from './package-managers.js';
  * @returns Markdown README content for the generated project root.
  */
 export function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
+    const variableGroups = getScaffoldTemplateVariableGroups(variables);
+    const compoundPersistenceEnabled = variableGroups.compound.enabled &&
+        variableGroups.compound.persistenceEnabled;
     const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+        compoundPersistenceEnabled,
     });
     const initialCommitCommands = getInitialCommitCommands();
     const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+        compoundPersistenceEnabled,
     });
-    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === 'true';
-    const publicPersistencePolicyNote = variables.isPublicPersistencePolicy === 'true'
+    const publicPersistencePolicyNote = variableGroups.persistence.enabled && variableGroups.persistence.auth.isPublic
         ? 'Public persistence writes use signed short-lived tokens, per-request ids, and coarse rate limiting by default. Add application-specific abuse controls before using the same pattern for high-value metrics or experiments.'
         : null;
+    const alternateRenderTargetSection = variableGroups.alternateRenderTargets.enabled
+        ? `## Alternate Render Targets\n\nThis scaffold keeps \`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render.php` : 'src/render.php'}\` as the default web render boundary and also generates ${[
+            variableGroups.alternateRenderTargets.hasEmail
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-email.php` : 'src/render-email.php'}\``
+                : null,
+            variableGroups.alternateRenderTargets.hasMjml
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-mjml.php` : 'src/render-mjml.php'}\``
+                : null,
+            variableGroups.alternateRenderTargets.hasPlainText
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-text.php` : 'src/render-text.php'}\``
+                : null,
+        ]
+            .filter((value) => Boolean(value))
+            .join(', ')}. All of those entries delegate through \`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-targets.php` : 'src/render-targets.php'}\`, so attribute normalization, validation, and render-target adapter hooks stay aligned across web, email, MJML, and plain-text integrations.`
+        : '';
     const compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
+    const compoundInnerBlocksSection = templateId === 'compound'
+        ? `## Compound InnerBlocks Presets\n\nThis scaffold starts with the \`${variables.compoundInnerBlocksPreset}\` preset for compound container authoring. Static nested relationships still belong in each generated \`block.json\` via \`allowedBlocks\`, \`parent\`, and \`ancestor\`, while \`src/blocks/${variables.slugKebabCase}/children.ts\` owns editor-only \`InnerBlocks\` behavior such as \`orientation\`, \`templateLock\`, \`defaultBlock\`, and \`directInsert\`.\n\n- \`freeform\`: unlocked inserter flow with the starter child template.\n- \`ordered\`: vertical ordered flow with \`templateLock="insert"\` and direct inserts.\n- \`horizontal\`: row-like nested authoring with direct inserts.\n- \`locked-structure\`: fully locked starter structure.\n\nWhen you need to change that authoring behavior later, update the preset helpers in \`src/blocks/${variables.slugKebabCase}/children.ts\` and keep fixed child constraints metadata-owned instead of duplicating them in editor props. If you need tighter wrapper ownership or sibling markup control, switch the generated edit components to \`useInnerBlocksProps\` and reuse \`getRootInnerBlocksPropsOptions()\` / \`getChildInnerBlocksPropsOptions( metadata.name )\` so the same preset behavior carries forward without rebuilding the option set by hand.`
+        : '';
     const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
         compoundPersistenceEnabled,
         slug: variables.slug,
@@ -69,6 +91,7 @@ ${getQuickStartWorkflowNote(packageManager, templateId, {
 \`\`\`bash
 ${formatRunScript(packageManager, 'build')}
 ${formatRunScript(packageManager, 'typecheck')}
+${formatPackageExecCommand(packageManager, `wp-typia@${getPackageVersions().wpTypiaPackageExactVersion}`, 'doctor')}
 \`\`\`
 
 ${advancedSyncSection}
@@ -81,7 +104,7 @@ ${initialCommitCommands.join('\n')}
 
 ${getInitialCommitNote()}
 
-${sourceOfTruthNote}${publicPersistencePolicyNote ? `\n\n${publicPersistencePolicyNote}` : ''}${migrationSection ? `\n\n${migrationSection}` : ''}${compoundExtensionWorkflowSection ? `\n\n${compoundExtensionWorkflowSection}` : ''}${wpEnvSection ? `\n\n${wpEnvSection}` : ''}${testPresetSection ? `\n\n${testPresetSection}` : ''}${phpRestExtensionPointsSection ? `\n\n${phpRestExtensionPointsSection}` : ''}
+${sourceOfTruthNote}${publicPersistencePolicyNote ? `\n\n${publicPersistencePolicyNote}` : ''}${alternateRenderTargetSection ? `\n\n${alternateRenderTargetSection}` : ''}${compoundInnerBlocksSection ? `\n\n${compoundInnerBlocksSection}` : ''}${migrationSection ? `\n\n${migrationSection}` : ''}${compoundExtensionWorkflowSection ? `\n\n${compoundExtensionWorkflowSection}` : ''}${wpEnvSection ? `\n\n${wpEnvSection}` : ''}${testPresetSection ? `\n\n${testPresetSection}` : ''}${phpRestExtensionPointsSection ? `\n\n${phpRestExtensionPointsSection}` : ''}
 `;
 }
 /**

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

@@ -10,6 +10,23 @@ export declare function validateTextDomain(input: string): true | string;
 export declare function validatePhpPrefix(input: string): true | string;
 export declare function assertValidIdentifier(label: string, value: string, validate: (value: string) => true | string): string;
 export declare function normalizeBlockSlug(input: string): string;
+/**
+ * Normalize one human-entered block slug and reject values that collapse to an
+ * empty generated slug.
+ *
+ * @param options Normalization context for one block-like name.
+ * @param options.input Raw user input before kebab-case normalization.
+ * @param options.label Human-readable field label used in thrown errors.
+ * @param options.usage Example CLI usage shown when the input is blank.
+ * @returns A non-empty normalized slug.
+ * @throws When the input is blank after trimming.
+ * @throws When normalization removes every character from the original input.
+ */
+export declare function resolveNonEmptyNormalizedBlockSlug(options: {
+    input: string;
+    label: string;
+    usage: string;
+}): string;
 export declare function resolveValidatedBlockSlug(value: string): string;
 export declare function resolveValidatedNamespace(value: string): string;
 export declare function resolveValidatedTextDomain(value: string): string;

package/dist/runtime/scaffold-identifiers.js

@@ -34,6 +34,28 @@ export function assertValidIdentifier(label, value, validate) {
 export function normalizeBlockSlug(input) {
     return toKebabCase(input);
 }
+/**
+ * Normalize one human-entered block slug and reject values that collapse to an
+ * empty generated slug.
+ *
+ * @param options Normalization context for one block-like name.
+ * @param options.input Raw user input before kebab-case normalization.
+ * @param options.label Human-readable field label used in thrown errors.
+ * @param options.usage Example CLI usage shown when the input is blank.
+ * @returns A non-empty normalized slug.
+ * @throws When the input is blank after trimming.
+ * @throws When normalization removes every character from the original input.
+ */
+export function resolveNonEmptyNormalizedBlockSlug(options) {
+    const normalizedSlug = normalizeBlockSlug(options.input);
+    if (normalizedSlug.length > 0) {
+        return normalizedSlug;
+    }
+    if (options.input.trim().length === 0) {
+        throw new Error(`${options.label} is required. Use \`${options.usage}\`.`);
+    }
+    throw new Error(`${options.label} "${options.input.trim()}" normalizes to an empty slug. Use letters or numbers so wp-typia can generate a block slug.`);
+}
 export function resolveValidatedBlockSlug(value) {
     return assertValidIdentifier("Block slug", normalizeBlockSlug(value), validateBlockSlug);
 }

package/dist/runtime/scaffold-onboarding.js

@@ -1,4 +1,5 @@
-import { formatRunScript } from "./package-managers.js";
+import { formatPackageExecCommand, formatRunScript, } from "./package-managers.js";
+import { getPackageVersions } from "./package-versions.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 const INITIAL_COMMIT_COMMANDS = [
@@ -6,6 +7,9 @@ const INITIAL_COMMIT_COMMANDS = [
     "git add .",
     'git commit -m "Initial scaffold"',
 ];
+function getDoctorVerificationCommand(packageManager) {
+    return formatPackageExecCommand(packageManager, `wp-typia@${getPackageVersions().wpTypiaPackageExactVersion}`, "doctor");
+}
 function templateHasPersistenceSync(templateId, { compoundPersistenceEnabled = false } = {}) {
     return templateId === "persistence" || (templateId === "compound" && compoundPersistenceEnabled);
 }
@@ -40,29 +44,31 @@ export function getOptionalOnboardingSteps(packageManager, templateId, options =
  * Returns the quick-start note explaining the scaffold's primary local loop.
  */
 export function getQuickStartWorkflowNote(packageManager, templateId = "basic", options = {}) {
+    const doctorCommand = getDoctorVerificationCommand(packageManager);
     if (templateId === "query-loop") {
-        return `${formatRunScript(packageManager, "dev")} runs the editor build/watch loop that registers your Query Loop variation in the block editor. This scaffold is editor-facing by design: update \`src/index.ts\` when you want to change the variation namespace, default query, allowed controls, or the minimal inline starter layout, update \`src/patterns/*.php\` when you want richer connected layout presets in the inserter, use \`src/query-extension.ts\` when the variation needs custom query params or optional editor-side hooks, and mirror frontend/editor preview query mapping in \`inc/query-runtime.php\`.`;
+        return `${formatRunScript(packageManager, "dev")} runs the editor build/watch loop that registers your Query Loop variation in the block editor. This scaffold intentionally skips \`src/types.ts\`, \`block.json\`, and Typia manifests because the source of truth lives in the variation registration flow. Update \`src/index.ts\` for variation defaults, \`src/patterns/*.php\` for richer connected layouts, \`src/query-extension.ts\` for custom query params, and \`inc/query-runtime.php\` for frontend/editor preview parity. Use ${doctorCommand} when you want a quick environment and workspace sanity check.`;
     }
     const developmentScript = getPrimaryDevelopmentScript(templateId);
     const devCommand = formatRunScript(packageManager, developmentScript);
     const startCommand = formatRunScript(packageManager, "start");
     if (developmentScript === "start") {
-        return `${startCommand} is the primary local entry point for this template. If the template also exposes a dedicated watch mode or alternate editor workflow, follow that template-specific documentation alongside the generated project scripts.`;
+        return `${startCommand} is the primary local entry point for this template. Use ${doctorCommand} when you want a quick environment and workspace sanity check before build or commit.`;
     }
     if (developmentScript !== "dev") {
-        return `${devCommand} is the primary local entry point for this template. Use ${startCommand} when you want the scaffold's one-shot startup flow instead of the watch-oriented workflow.`;
+        return `${devCommand} is the primary local entry point for this template. Use ${startCommand} for the one-shot startup flow, and ${doctorCommand} when you want a quick verification pass before build or commit.`;
     }
     if (templateHasPersistenceSync(templateId, options)) {
-        return `${devCommand} keeps the editor, type-derived artifacts, and REST-derived artifacts moving together during local development. Use ${startCommand} when you want a one-shot sync plus editor startup without the long-running watch loop.`;
+        return `${devCommand} keeps the editor, type-derived artifacts, and REST-derived artifacts moving together during local development. Use ${startCommand} for a one-shot sync plus editor startup, and ${doctorCommand} when you want an explicit verification pass before build or commit.`;
     }
-    return `${devCommand} keeps the editor and type-derived artifacts moving together during local development. Use ${startCommand} when you want a one-shot sync plus editor startup without the long-running watch loop.`;
+    return `${devCommand} keeps the editor and type-derived artifacts moving together during local development. Use ${startCommand} for a one-shot sync plus editor startup, and ${doctorCommand} when you want an explicit verification pass before build or commit.`;
 }
 /**
  * Returns the onboarding note explaining when manual sync is optional.
  */
 export function getOptionalOnboardingNote(packageManager, templateId = "basic", options = {}) {
+    const doctorCommand = getDoctorVerificationCommand(packageManager);
     if (templateId === "query-loop") {
-        return `This scaffold does not generate a \`sync\` script, \`block.json\`, or Typia manifests. Edit \`src/index.ts\` to change the variation contract, edit \`src/patterns/*.php\` when you want richer connected layouts beyond the inline fallback, edit \`src/query-extension.ts\` when you need variation-specific query params or custom editor hooks, and edit \`inc/query-runtime.php\` when those params need frontend or editor preview parity. Then rerun ${formatRunScript(packageManager, "build")}, ${formatRunScript(packageManager, "dev")}, or ${formatRunScript(packageManager, "typecheck")} as needed.`;
+        return `This scaffold owns a \`core/query\` variation, so it does not generate a \`sync\` script, \`src/types.ts\`, \`block.json\`, or Typia manifests. Edit \`src/index.ts\`, \`src/patterns/*.php\`, \`src/query-extension.ts\`, and \`inc/query-runtime.php\` as needed, then rerun ${formatRunScript(packageManager, "build")}, ${formatRunScript(packageManager, "typecheck")}, or ${doctorCommand}.`;
     }
     const optionalSyncScripts = getOptionalSyncScriptNames(templateId, options);
     const hasUnifiedSync = optionalSyncScripts.includes("sync");
@@ -76,7 +82,7 @@ export function getOptionalOnboardingNote(packageManager, templateId = "basic",
     const typecheckCommand = formatRunScript(packageManager, "typecheck");
     const strictSyncCommand = formatRunScript(packageManager, "sync-types", "--strict --report json");
     const advancedPersistenceNote = templateHasPersistenceSync(templateId, options)
-        ? ` ${syncRestCommand} remains available for advanced REST-only refreshes, but it now fails fast when type-derived artifacts are stale; run \`${syncCommand}\` or \`${syncTypesCommand}\` first.`
+        ? ` ${syncRestCommand} remains available for REST-only refreshes after ${syncTypesCommand}.`
         : "";
     const isCustomTemplate = !isBuiltInTemplateId(templateId) &&
         templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
@@ -86,12 +92,12 @@ export function getOptionalOnboardingNote(packageManager, templateId = "basic",
         ? `Run ${syncSteps.join(" then ")} manually before build, typecheck, or commit. ${syncCheckCommand} verifies the current type-derived artifacts without rewriting them.${optionalSyncScripts.includes("sync-rest") ? ` ${syncRestCommand} remains available for REST-only refreshes after ${syncTypesCommand}.` : ""}`
         : null;
     if (fallbackCustomTemplateNote) {
-        return fallbackCustomTemplateNote;
+        return `${fallbackCustomTemplateNote} Use ${doctorCommand} when you want a quick environment and workspace sanity check.`;
     }
     if (isCustomTemplate && syncSteps.length === 0) {
-        return "No optional sync command was detected for this custom template. Follow the template's own artifact-refresh guidance before build, typecheck, or your first commit.";
+        return `No optional sync command was detected for this custom template. Use ${doctorCommand} for a quick environment and workspace sanity check, then follow the template's own artifact-refresh guidance before build, typecheck, or your first commit.`;
     }
-    return `You usually do not need to run ${syncCommand} during a normal ${formatRunScript(packageManager, developmentScript)} session. Run ${syncCommand} manually when you want a reviewable artifact refresh before ${formatRunScript(packageManager, "build")}, ${typecheckCommand}, or your first commit. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` to fail only on lossy WordPress projections, or \`${strictSyncCommand}\` for the stricter CI-oriented report.${advancedPersistenceNote} They do not create migration history. If this directory is new, create your first Git commit after that refresh.`;
+    return `You usually do not need to run ${syncCommand} during a normal ${formatRunScript(packageManager, developmentScript)} session. Run ${syncCommand} before ${formatRunScript(packageManager, "build")}, ${typecheckCommand}, or ${doctorCommand} when you want a reviewable refresh. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` or \`${strictSyncCommand}\` for stricter CI checks.${advancedPersistenceNote} Generated syncs do not create migration history, so refresh before your first commit if this directory is new.`;
 }
 /**
  * Returns the recommended version-control commands for a fresh scaffold.
@@ -110,7 +116,7 @@ export function getInitialCommitNote() {
  */
 export function getTemplateSourceOfTruthNote(templateId, { compoundPersistenceEnabled = false } = {}) {
     if (templateId === "query-loop") {
-        return "`src/index.ts` remains the source of truth for the Query Loop variation name, default query attributes, `allowedControls`, and the minimal inline starter `innerBlocks`. Use `src/patterns/*.php` for richer connected layout presets that stay tied to the same variation namespace, use `src/query-extension.ts` for custom query seed values or optional editor-only hook registration, and use `inc/query-runtime.php` to keep frontend and editor preview query mapping aligned for those custom keys. The generated plugin bootstrap should stay focused on script registration, pattern loading, and explicit runtime glue for the variation.";
+        return "`src/index.ts` remains the source of truth for the Query Loop variation name, default query attributes, `allowedControls`, and the minimal inline starter `innerBlocks`. This scaffold intentionally does not generate `src/types.ts`, `block.json`, or Typia manifests because those artifacts belong to standalone block families, not `core/query` variation ownership. Use `src/patterns/*.php` for richer connected layout presets that stay tied to the same variation namespace, use `src/query-extension.ts` for custom query seed values or optional editor-only hook registration, and use `inc/query-runtime.php` to keep frontend and editor preview query mapping aligned for those custom keys. The generated plugin bootstrap should stay focused on script registration, pattern loading, and explicit runtime glue for the variation.";
     }
     if (templateId === "compound") {
         const compoundBase = "`src/blocks/*/types.ts` files remain the source of truth for each block's `block.json`, `typia.manifest.json`, and `typia-validator.php`. Fresh scaffolds include starter `typia.manifest.json` files so editor imports resolve before the first sync.";
@@ -138,10 +144,12 @@ ${formatRunScript(packageManager, "add-child", '--slug faq-item --title "FAQ Ite
 
 ${formatRunScript(packageManager, "add-child", '--slug section --title "Section" --container --inserter visible')}
 
+${formatRunScript(packageManager, "add-child", '--slug clause --title "Clause" --ancestor section --dry-run')}
+
 ${formatRunScript(packageManager, "add-child", '--slug clause --title "Clause" --ancestor section')}
 \`\`\`
 
-This scaffolds additional compound child block types, updates \`scripts/block-config.ts\` and \`src/blocks/*/children.ts\`, and now supports root-level hidden children, visible container children, and nested ancestor chains for richer document-style block hierarchies.`;
+This scaffolds additional compound child block types, updates \`scripts/block-config.ts\` and \`src/blocks/*/children.ts\`, and now supports root-level hidden children, visible container children, and nested ancestor chains for richer document-style block hierarchies. Pass \`--dry-run\` when you want a validated child-graph preview and planned write list before the script mutates files.`;
 }
 function formatPhpRestExtensionPointsSection({ apiTypesPath, extraNote, mainPhpPath, mainPhpScope, transportPath, }) {
     const schemaJsonGlob = apiTypesPath.replace(/api-types\.ts$/u, "api-schemas/*.schema.json");

package/dist/runtime/scaffold-template-variable-groups.d.ts

@@ -0,0 +1,154 @@
+export declare const SCAFFOLD_TEMPLATE_VARIABLE_GROUPS: unique symbol;
+export type ScaffoldTemplateFamily = "basic" | "interactivity" | "persistence" | "compound" | "query-loop" | "external";
+export interface ScaffoldSharedTemplateVariableGroup {
+    author: string;
+    blockMetadataVersion: string;
+    category: string;
+    cssClassName: string;
+    description: string;
+    descriptionJson: string;
+    frontendCssClassName: string;
+    icon: string;
+    keyword: string;
+    namespace: string;
+    pascalCase: string;
+    phpPrefix: string;
+    phpPrefixUpper: string;
+    slug: string;
+    slugCamelCase: string;
+    slugKebabCase: string;
+    slugSnakeCase: string;
+    textDomain: string;
+    title: string;
+    titleCase: string;
+    titleJson: string;
+    versions: {
+        apiClient: string;
+        blockRuntime: string;
+        blockTypes: string;
+        projectTools: string;
+        rest: string;
+    };
+}
+export interface ScaffoldAlternateRenderTargetVariableGroup {
+    csv: string;
+    enabled: boolean;
+    hasEmail: boolean;
+    hasMjml: boolean;
+    hasPlainText: boolean;
+    json: string;
+    targets: readonly string[];
+}
+export interface DisabledScaffoldCompoundVariableGroup {
+    enabled: false;
+    persistenceEnabled: false;
+}
+export interface EnabledScaffoldCompoundVariableGroup {
+    child: {
+        category: string;
+        cssClassName: string;
+        icon: string;
+        title: string;
+        titleJson: string;
+    };
+    enabled: true;
+    innerBlocks: {
+        description: string;
+        directInsert: boolean;
+        label: string;
+        orientation: "" | "horizontal" | "vertical";
+        orientationExpression: string;
+        preset: string;
+        templateLockExpression: string;
+    };
+    persistenceEnabled: boolean;
+}
+export type ScaffoldCompoundVariableGroup = DisabledScaffoldCompoundVariableGroup | EnabledScaffoldCompoundVariableGroup;
+export interface DisabledScaffoldPersistenceVariableGroup {
+    enabled: false;
+    scope: "none";
+}
+export interface EnabledScaffoldPersistenceVariableGroup {
+    auth: {
+        bootstrapCredentialDeclarations: string;
+        descriptionJson: string;
+        intent: "authenticated" | "public-write-protected";
+        isAuthenticated: boolean;
+        isPublic: boolean;
+        mechanism: "public-signed-token" | "rest-nonce";
+        mode: "authenticated-rest-nonce" | "public-signed-token";
+        publicWriteRequestIdDeclaration: string;
+    };
+    dataStorageMode: "custom-table" | "post-meta";
+    enabled: true;
+    policy: "authenticated" | "public";
+    scope: "compound-parent" | "single";
+}
+export type ScaffoldPersistenceVariableGroup = DisabledScaffoldPersistenceVariableGroup | EnabledScaffoldPersistenceVariableGroup;
+export interface DisabledScaffoldQueryLoopVariableGroup {
+    enabled: false;
+}
+export interface EnabledScaffoldQueryLoopVariableGroup {
+    allowedControls: readonly string[];
+    allowedControlsJson: string;
+    enabled: true;
+    postType: string;
+    postTypeJson: string;
+    variationNamespace: string;
+    variationNamespaceJson: string;
+}
+export type ScaffoldQueryLoopVariableGroup = DisabledScaffoldQueryLoopVariableGroup | EnabledScaffoldQueryLoopVariableGroup;
+interface ScaffoldTemplateVariableGroupsBase {
+    alternateRenderTargets: ScaffoldAlternateRenderTargetVariableGroup;
+    shared: ScaffoldSharedTemplateVariableGroup;
+    template: {
+        description: string;
+    };
+}
+type DisabledTemplateFamilyGroups<TFamily extends "basic" | "interactivity" | "external"> = ScaffoldTemplateVariableGroupsBase & {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup;
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: TFamily;
+};
+export type BasicScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"basic">;
+export type InteractivityScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"interactivity">;
+export interface PersistenceScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: EnabledScaffoldPersistenceVariableGroup & {
+        scope: "single";
+    };
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "persistence";
+}
+export interface CompoundScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: EnabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup | (EnabledScaffoldPersistenceVariableGroup & {
+        scope: "compound-parent";
+    });
+    queryLoop: DisabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "compound";
+}
+export interface QueryLoopScaffoldTemplateVariableGroups extends ScaffoldTemplateVariableGroupsBase {
+    compound: DisabledScaffoldCompoundVariableGroup;
+    persistence: DisabledScaffoldPersistenceVariableGroup;
+    queryLoop: EnabledScaffoldQueryLoopVariableGroup;
+    templateFamily: "query-loop";
+}
+export type ExternalScaffoldTemplateVariableGroups = DisabledTemplateFamilyGroups<"external">;
+export type ScaffoldTemplateVariableGroups = BasicScaffoldTemplateVariableGroups | InteractivityScaffoldTemplateVariableGroups | PersistenceScaffoldTemplateVariableGroups | CompoundScaffoldTemplateVariableGroups | QueryLoopScaffoldTemplateVariableGroups | ExternalScaffoldTemplateVariableGroups;
+export interface ScaffoldTemplateVariableGroupsCarrier {
+    readonly [SCAFFOLD_TEMPLATE_VARIABLE_GROUPS]: ScaffoldTemplateVariableGroups;
+}
+export type CompoundScaffoldTemplateVariablesLike = ScaffoldTemplateVariableGroupsCarrier & {
+    slugKebabCase: string;
+};
+export type PersistenceScaffoldTemplateVariablesLike = ScaffoldTemplateVariableGroupsCarrier & {
+    namespace: string;
+    pascalCase: string;
+    slugKebabCase: string;
+    title: string;
+};
+export declare function attachScaffoldTemplateVariableGroups<TVariables extends Record<string, string>>(variables: TVariables, groups: ScaffoldTemplateVariableGroups): TVariables & ScaffoldTemplateVariableGroupsCarrier;
+export declare function getScaffoldTemplateVariableGroups(variables: ScaffoldTemplateVariableGroupsCarrier): ScaffoldTemplateVariableGroups;
+export {};

package/dist/runtime/scaffold-template-variable-groups.js

@@ -0,0 +1,13 @@
+export const SCAFFOLD_TEMPLATE_VARIABLE_GROUPS = Symbol("wp-typia.scaffold-template-variable-groups");
+export function attachScaffoldTemplateVariableGroups(variables, groups) {
+    Object.defineProperty(variables, SCAFFOLD_TEMPLATE_VARIABLE_GROUPS, {
+        configurable: false,
+        enumerable: false,
+        value: groups,
+        writable: false,
+    });
+    return variables;
+}
+export function getScaffoldTemplateVariableGroups(variables) {
+    return variables[SCAFFOLD_TEMPLATE_VARIABLE_GROUPS];
+}

package/dist/runtime/scaffold-template-variables.js

@@ -2,8 +2,10 @@ import { buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from './
 import { getPackageVersions } from './package-versions.js';
 import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from './scaffold-identifiers.js';
 import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from './template-defaults.js';
+import { DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, } from './compound-inner-blocks.js';
 import { getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
 import { toPascalCase, toSnakeCase, } from './string-case.js';
+import { attachScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
 /**
  * Build the normalized template variables used by scaffold rendering.
  *
@@ -43,6 +45,8 @@ export function getTemplateVariables(templateId, answers) {
     const compoundChildTitle = `${title} Item`;
     const cssClassName = buildBlockCssClassName(namespace, slug);
     const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
+    const compoundInnerBlocksPreset = answers.compoundInnerBlocksPreset ?? DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID;
+    const compoundInnerBlocksPresetDefinition = getCompoundInnerBlocksPresetDefinition(compoundInnerBlocksPreset);
     const compoundPersistenceEnabled = templateId === 'persistence'
         ? true
         : templateId === 'compound'
@@ -54,7 +58,9 @@ export function getTemplateVariables(templateId, answers) {
     const persistencePolicy = templateId === 'persistence' || compoundPersistenceEnabled
         ? answers.persistencePolicy ?? 'authenticated'
         : 'authenticated';
-    return {
+    const flatVariables = {
+        alternateRenderTargetsCsv: '',
+        alternateRenderTargetsJson: '[]',
         apiClientPackageVersion,
         author: answers.author.trim(),
         blockRuntimePackageVersion,
@@ -68,6 +74,23 @@ export function getTemplateVariables(templateId, answers) {
         compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
         compoundChildTitleJson: JSON.stringify(compoundChildTitle),
         compoundPersistenceEnabled: compoundPersistenceEnabled ? 'true' : 'false',
+        compoundInnerBlocksDirectInsert: compoundInnerBlocksPresetDefinition.directInsert
+            ? 'true'
+            : 'false',
+        compoundInnerBlocksOrientation: compoundInnerBlocksPresetDefinition.orientation ?? '',
+        compoundInnerBlocksOrientationExpression: compoundInnerBlocksPresetDefinition.orientation
+            ? `'${compoundInnerBlocksPresetDefinition.orientation}'`
+            : 'undefined',
+        compoundInnerBlocksPreset,
+        compoundInnerBlocksPresetDescription: compoundInnerBlocksPresetDefinition.description,
+        compoundInnerBlocksPresetLabel: compoundInnerBlocksPresetDefinition.label,
+        compoundInnerBlocksTemplateLockExpression: compoundInnerBlocksPresetDefinition.templateLock === false
+            ? 'false'
+            : `'${compoundInnerBlocksPresetDefinition.templateLock}'`,
+        hasAlternateEmailRenderTarget: 'false',
+        hasAlternateMjmlRenderTarget: 'false',
+        hasAlternatePlainTextRenderTarget: 'false',
+        hasAlternateRenderTargets: 'false',
         projectToolsPackageVersion,
         cssClassName,
         dataStorageMode,
@@ -114,4 +137,60 @@ export function getTemplateVariables(templateId, answers) {
         titleCase: pascalCase,
         persistencePolicy,
     };
+    return attachScaffoldTemplateVariableGroups(flatVariables, {
+        alternateRenderTargets: {
+            csv: '',
+            enabled: false,
+            hasEmail: false,
+            hasMjml: false,
+            hasPlainText: false,
+            json: '[]',
+            targets: [],
+        },
+        compound: {
+            enabled: false,
+            persistenceEnabled: false,
+        },
+        persistence: {
+            enabled: false,
+            scope: 'none',
+        },
+        queryLoop: {
+            enabled: false,
+        },
+        shared: {
+            author: answers.author.trim(),
+            blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+            category: metadataDefaults?.category ?? template?.defaultCategory ?? 'widgets',
+            cssClassName,
+            description,
+            descriptionJson: JSON.stringify(description),
+            frontendCssClassName: buildFrontendCssClassName(cssClassName),
+            icon: metadataDefaults?.icon ?? 'smiley',
+            keyword: slug.replace(/-/g, ' '),
+            namespace,
+            pascalCase,
+            phpPrefix,
+            phpPrefixUpper,
+            slug,
+            slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
+            slugKebabCase: slug,
+            slugSnakeCase,
+            textDomain,
+            title,
+            titleCase: pascalCase,
+            titleJson: JSON.stringify(title),
+            versions: {
+                apiClient: apiClientPackageVersion,
+                blockRuntime: blockRuntimePackageVersion,
+                blockTypes: blockTypesPackageVersion,
+                projectTools: projectToolsPackageVersion,
+                rest: restPackageVersion,
+            },
+        },
+        template: {
+            description: template?.description ?? 'External scaffold template variables',
+        },
+        templateFamily: 'external',
+    });
 }