@wp-typia/project-tools 0.18.0 → 0.19.0

package/dist/runtime/cli-validation.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * 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 function normalizeOptionalCliString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function looksLikeLocalCliPath(value) {
+    return (path.isAbsolute(value) ||
+        value.startsWith("./") ||
+        value.startsWith("../") ||
+        value.startsWith(".\\") ||
+        value.startsWith("..\\"));
+}
+/**
+ * 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 function resolveLocalCliPathOption(options) {
+    const normalizedValue = normalizeOptionalCliString(options.value);
+    if (!normalizedValue || !looksLikeLocalCliPath(normalizedValue)) {
+        return normalizedValue;
+    }
+    const resolvedPath = path.resolve(options.cwd, normalizedValue);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new Error(`\`${options.label}\` path does not exist: ${resolvedPath}. Check the path relative to ${options.cwd}.`);
+    }
+    return resolvedPath;
+}
+/**
+ * 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 function assertExternalLayerCompositionOptions(options) {
+    if (options.externalLayerId && !options.externalLayerSource) {
+        throw new Error("externalLayerId requires externalLayerSource when composing built-in template layers.");
+    }
+}
+/**
+ * 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 function createBuiltInVariantErrorMessage(options) {
+    return `--variant is only supported for official external template configs. Received variant "${options.variant}" for built-in template "${options.templateId}".`;
+}
+/**
+ * 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 function assertBuiltInTemplateVariantAllowed(options) {
+    if (!options.variant) {
+        return;
+    }
+    throw new Error(createBuiltInVariantErrorMessage({
+        templateId: options.templateId,
+        variant: options.variant,
+    }));
+}

package/dist/runtime/compound-inner-blocks.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Stable preset ids exposed to scaffold and UI consumers for compound
+ * InnerBlocks authoring behavior.
+ */
+export declare const COMPOUND_INNER_BLOCKS_PRESET_IDS: readonly ["freeform", "ordered", "horizontal", "locked-structure"];
+export type CompoundInnerBlocksPresetId = (typeof COMPOUND_INNER_BLOCKS_PRESET_IDS)[number];
+/**
+ * Default preset applied when callers do not provide an explicit compound
+ * InnerBlocks mode.
+ */
+export declare const DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID: CompoundInnerBlocksPresetId;
+export type CompoundInnerBlocksOrientation = "horizontal" | "vertical";
+export type CompoundInnerBlocksTemplateLock = false | "insert" | "all";
+/**
+ * Runtime-facing description of one compound InnerBlocks preset.
+ */
+export interface CompoundInnerBlocksPresetDefinition {
+    description: string;
+    directInsert: boolean;
+    label: string;
+    orientation?: CompoundInnerBlocksOrientation;
+    templateLock: CompoundInnerBlocksTemplateLock;
+}
+/**
+ * Canonical preset registry used by the CLI, generated scaffolds, and TUI
+ * forms.
+ */
+export declare const COMPOUND_INNER_BLOCKS_PRESET_REGISTRY: {
+    readonly freeform: {
+        readonly description: "Unlocked nested authoring with the default inserter and starter child template.";
+        readonly directInsert: false;
+        readonly label: "freeform";
+        readonly orientation: "vertical";
+        readonly templateLock: false;
+    };
+    readonly ordered: {
+        readonly description: "Vertical ordered flow that keeps starter structure fixed while allowing new sibling inserts.";
+        readonly directInsert: true;
+        readonly label: "ordered";
+        readonly orientation: "vertical";
+        readonly templateLock: "insert";
+    };
+    readonly horizontal: {
+        readonly description: "Horizontal nested layout with one-click direct inserts for row or tab style containers.";
+        readonly directInsert: true;
+        readonly label: "horizontal";
+        readonly orientation: "horizontal";
+        readonly templateLock: false;
+    };
+    readonly "locked-structure": {
+        readonly description: "Locked starter structure for guided document shells where authors should only edit seeded children.";
+        readonly directInsert: false;
+        readonly label: "locked-structure";
+        readonly orientation: "vertical";
+        readonly templateLock: "all";
+    };
+};
+/**
+ * Returns whether a string matches one of the supported compound preset ids.
+ */
+export declare function isCompoundInnerBlocksPresetId(value: string): value is CompoundInnerBlocksPresetId;
+/**
+ * Parses a raw CLI or config value into a supported preset id.
+ *
+ * Returns `undefined` for non-string or empty input, and throws when the input
+ * is a non-empty unsupported preset id.
+ */
+export declare function parseCompoundInnerBlocksPreset(value?: string): CompoundInnerBlocksPresetId | undefined;
+/**
+ * Resolves an optional preset id to a concrete preset, defaulting to
+ * `DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID`.
+ */
+export declare function resolveCompoundInnerBlocksPreset(value?: CompoundInnerBlocksPresetId): CompoundInnerBlocksPresetId;
+/**
+ * Looks up the preset definition for the provided preset id, applying the
+ * default preset when the input is omitted.
+ */
+export declare function getCompoundInnerBlocksPresetDefinition(value?: CompoundInnerBlocksPresetId): CompoundInnerBlocksPresetDefinition;

package/dist/runtime/compound-inner-blocks.js

@@ -0,0 +1,88 @@
+/**
+ * Stable preset ids exposed to scaffold and UI consumers for compound
+ * InnerBlocks authoring behavior.
+ */
+export const COMPOUND_INNER_BLOCKS_PRESET_IDS = [
+    "freeform",
+    "ordered",
+    "horizontal",
+    "locked-structure",
+];
+/**
+ * Default preset applied when callers do not provide an explicit compound
+ * InnerBlocks mode.
+ */
+export const DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID = "freeform";
+/**
+ * Canonical preset registry used by the CLI, generated scaffolds, and TUI
+ * forms.
+ */
+export const COMPOUND_INNER_BLOCKS_PRESET_REGISTRY = {
+    freeform: {
+        description: "Unlocked nested authoring with the default inserter and starter child template.",
+        directInsert: false,
+        label: "freeform",
+        orientation: "vertical",
+        templateLock: false,
+    },
+    ordered: {
+        description: "Vertical ordered flow that keeps starter structure fixed while allowing new sibling inserts.",
+        directInsert: true,
+        label: "ordered",
+        orientation: "vertical",
+        templateLock: "insert",
+    },
+    horizontal: {
+        description: "Horizontal nested layout with one-click direct inserts for row or tab style containers.",
+        directInsert: true,
+        label: "horizontal",
+        orientation: "horizontal",
+        templateLock: false,
+    },
+    "locked-structure": {
+        description: "Locked starter structure for guided document shells where authors should only edit seeded children.",
+        directInsert: false,
+        label: "locked-structure",
+        orientation: "vertical",
+        templateLock: "all",
+    },
+};
+/**
+ * Returns whether a string matches one of the supported compound preset ids.
+ */
+export function isCompoundInnerBlocksPresetId(value) {
+    return COMPOUND_INNER_BLOCKS_PRESET_IDS.includes(value);
+}
+/**
+ * Parses a raw CLI or config value into a supported preset id.
+ *
+ * Returns `undefined` for non-string or empty input, and throws when the input
+ * is a non-empty unsupported preset id.
+ */
+export function parseCompoundInnerBlocksPreset(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalizedValue = value.trim();
+    if (normalizedValue.length === 0) {
+        return undefined;
+    }
+    if (!isCompoundInnerBlocksPresetId(normalizedValue)) {
+        throw new Error(`Unsupported InnerBlocks preset "${value}". Expected one of: ${COMPOUND_INNER_BLOCKS_PRESET_IDS.join(", ")}.`);
+    }
+    return normalizedValue;
+}
+/**
+ * Resolves an optional preset id to a concrete preset, defaulting to
+ * `DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID`.
+ */
+export function resolveCompoundInnerBlocksPreset(value) {
+    return value ?? DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID;
+}
+/**
+ * Looks up the preset definition for the provided preset id, applying the
+ * default preset when the input is omitted.
+ */
+export function getCompoundInnerBlocksPresetDefinition(value) {
+    return COMPOUND_INNER_BLOCKS_PRESET_REGISTRY[resolveCompoundInnerBlocksPreset(value)];
+}

package/dist/runtime/index.d.ts

@@ -10,6 +10,8 @@
  * `runAddHookedBlockCommand`,
  * `HOOKED_BLOCK_POSITION_IDS`, and `runDoctor`.
  */
+export { COMPOUND_INNER_BLOCKS_PRESET_IDS, DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, isCompoundInnerBlocksPresetId, parseCompoundInnerBlocksPreset, resolveCompoundInnerBlocksPreset, } from "./compound-inner-blocks.js";
+export type { CompoundInnerBlocksPresetDefinition, CompoundInnerBlocksPresetId, CompoundInnerBlocksTemplateLock, } from "./compound-inner-blocks.js";
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export type { ApplyBlockInput, BlockGenerationTarget, BlockSpec, PlanBlockInput, PlanBlockResult, RenderBlockInput, RenderBlockResult, ValidateBlockInput, ValidateBlockResult, } from "./block-generator-service.js";

package/dist/runtime/index.js

@@ -10,6 +10,7 @@
  * `runAddHookedBlockCommand`,
  * `HOOKED_BLOCK_POSITION_IDS`, and `runDoctor`.
  */
+export { COMPOUND_INNER_BLOCKS_PRESET_IDS, DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID, getCompoundInnerBlocksPresetDefinition, isCompoundInnerBlocksPresetId, parseCompoundInnerBlocksPreset, resolveCompoundInnerBlocksPreset, } from "./compound-inner-blocks.js";
 export { scaffoldProject, collectScaffoldAnswers, getDefaultAnswers, getTemplateVariables, resolvePackageManagerId, resolveTemplateId, } from "./scaffold.js";
 export { BlockGeneratorService } from "./block-generator-service.js";
 export { BLOCK_GENERATION_TOOL_CONTRACT_VERSION, inspectBlockGeneration, } from "./block-generator-tool-contract.js";

package/dist/runtime/migration-command-surface.js

@@ -19,6 +19,8 @@ export function formatMigrationHelpText() {
 
 Notes:
   \`migrate init\` auto-detects supported single-block and \`src/blocks/*\` multi-block layouts.
+  \`migrate init\` only retrofits migration support into projects that already match those layouts.
+  A broader project-level \`wp-typia init\` path remains future work.
   Migration versions use strict schema labels like \`v1\`, \`v2\`, and \`v3\`.
   \`migrate wizard\` is TTY-only and helps you choose one legacy migration version to preview.
   \`migrate plan\` and \`migrate wizard\` are read-only previews; they do not scaffold rules or fixtures.

package/dist/runtime/package-versions.d.ts

@@ -4,6 +4,7 @@ interface PackageVersions {
     blockTypesPackageVersion: string;
     projectToolsPackageVersion: string;
     restPackageVersion: string;
+    wpTypiaPackageExactVersion: string;
     wpTypiaPackageVersion: string;
 }
 export declare function getPackageVersions(): PackageVersions;

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-documents.js

@@ -1,6 +1,7 @@
 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';
 /**
  * Builds the generated README markdown for one scaffolded project.
  *
@@ -22,7 +23,25 @@ export function buildReadme(templateId, variables, packageManager, { withMigrati
     const publicPersistencePolicyNote = variables.isPublicPersistencePolicy === 'true'
         ? '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 = variables.hasAlternateRenderTargets === 'true'
+        ? `## 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 ${[
+            variables.hasAlternateEmailRenderTarget === 'true'
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-email.php` : 'src/render-email.php'}\``
+                : null,
+            variables.hasAlternateMjmlRenderTarget === 'true'
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-mjml.php` : 'src/render-mjml.php'}\``
+                : null,
+            variables.hasAlternatePlainTextRenderTarget === 'true'
+                ? `\`${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 +88,7 @@ ${getQuickStartWorkflowNote(packageManager, templateId, {
 \`\`\`bash
 ${formatRunScript(packageManager, 'build')}
 ${formatRunScript(packageManager, 'typecheck')}
+${formatPackageExecCommand(packageManager, `wp-typia@${getPackageVersions().wpTypiaPackageExactVersion}`, 'doctor')}
 \`\`\`
 
 ${advancedSyncSection}
@@ -81,7 +101,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-variables.js

@@ -2,6 +2,7 @@ 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';
 /**
@@ -43,6 +44,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'
@@ -55,6 +58,8 @@ export function getTemplateVariables(templateId, answers) {
         ? answers.persistencePolicy ?? 'authenticated'
         : 'authenticated';
     return {
+        alternateRenderTargetsCsv: '',
+        alternateRenderTargetsJson: '[]',
         apiClientPackageVersion,
         author: answers.author.trim(),
         blockRuntimePackageVersion,
@@ -68,6 +73,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,