@wp-typia/project-tools 0.17.0 → 0.19.0

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

@@ -1,9 +1,16 @@
+import { execSync } from 'node:child_process';
 import { PACKAGE_MANAGER_IDS, getPackageManager, } from './package-managers.js';
 import { normalizeBlockSlug, resolveScaffoldIdentifiers, validateBlockSlug, validateNamespace, } from './scaffold-identifiers.js';
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
 import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from './template-defaults.js';
 import { toSnakeCase, toTitleCase, } from './string-case.js';
 const WORKSPACE_TEMPLATE_ALIAS = 'workspace';
+const TEMPLATE_SELECTION_HINT = `--template <${[
+    ...TEMPLATE_IDS,
+    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.
  *
@@ -44,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;
 }
@@ -57,17 +67,71 @@ 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
         ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
         : templateId;
 }
+function looksLikeExplicitExternalTemplateLocator(templateId) {
+    return (templateId.startsWith('./') ||
+        templateId.startsWith('../') ||
+        templateId.startsWith('/') ||
+        templateId.startsWith('@') ||
+        templateId.startsWith('github:') ||
+        templateId.includes('/'));
+}
+function getEditDistance(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    const current = new Array(right.length + 1);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        current[0] = leftIndex + 1;
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
+            current[rightIndex + 1] = Math.min(current[rightIndex] + 1, previous[rightIndex + 1] + 1, previous[rightIndex] + substitutionCost);
+        }
+        for (let index = 0; index < current.length; index += 1) {
+            previous[index] = current[index];
+        }
+    }
+    return previous[right.length];
+}
+function findMistypedBuiltInTemplateSuggestion(templateId) {
+    const normalizedTemplateId = templateId.trim().toLowerCase();
+    if (normalizedTemplateId.length === 0 ||
+        looksLikeExplicitExternalTemplateLocator(normalizedTemplateId)) {
+        return null;
+    }
+    let bestCandidate = null;
+    for (const candidateId of TEMPLATE_SUGGESTION_IDS) {
+        const distance = getEditDistance(normalizedTemplateId, candidateId);
+        if (bestCandidate === null ||
+            distance < bestCandidate.distance) {
+            bestCandidate = {
+                distance,
+                id: candidateId,
+            };
+        }
+    }
+    return bestCandidate && bestCandidate.distance <= 2
+        ? bestCandidate.id
+        : null;
+}
+function getMistypedBuiltInTemplateMessage(templateId) {
+    const suggestion = findMistypedBuiltInTemplateSuggestion(templateId);
+    if (!suggestion) {
+        return null;
+    }
+    const suggestionDescription = suggestion === WORKSPACE_TEMPLATE_ALIAS
+        ? 'official workspace scaffold'
+        : 'built-in scaffold';
+    return `Unknown template "${templateId}". Did you mean "${suggestion}"? Use \`--template ${suggestion}\` for the ${suggestionDescription}, or pass a local path, \`github:owner/repo/path[#ref]\`, or an npm package spec for an external template.`;
+}
 /**
  * Resolve the scaffold template id from flags, defaults, and interactive selection.
  *
@@ -80,16 +144,23 @@ export async function resolveTemplateId({ templateId, yes = false, isInteractive
         if (isRemovedBuiltInTemplateId(templateId)) {
             throw new Error(getRemovedBuiltInTemplateMessage(templateId));
         }
+        if (normalizedTemplateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+            return normalizedTemplateId;
+        }
         if (isBuiltInTemplateId(normalizedTemplateId)) {
             return getTemplateById(normalizedTemplateId).id;
         }
+        const mistypedBuiltInTemplateMessage = getMistypedBuiltInTemplateMessage(templateId);
+        if (mistypedBuiltInTemplateMessage) {
+            throw new Error(mistypedBuiltInTemplateMessage);
+        }
         return normalizedTemplateId;
     }
     if (yes) {
         return 'basic';
     }
     if (!isInteractive || !selectTemplate) {
-        throw new Error(`Template is required in non-interactive mode. Use --template <${TEMPLATE_IDS.join('|')}|./path|github:owner/repo/path[#ref]|npm-package>.`);
+        throw new Error(`Template is required in non-interactive mode. Use ${TEMPLATE_SELECTION_HINT}.`);
     }
     return normalizeTemplateSelection(await selectTemplate());
 }
@@ -160,4 +231,3 @@ export async function collectScaffoldAnswers({ projectName, templateId, yes = fa
         title: await promptText('Block title', toTitleCase(identifiers.slug)),
     };
 }
-import { execSync } from 'node:child_process';

package/dist/runtime/scaffold-apply-utils.d.ts

@@ -2,7 +2,7 @@ import { type BuiltInBlockArtifact } from "./built-in-block-artifacts.js";
 import type { BuiltInCodeArtifact } from "./built-in-block-code-artifacts.js";
 import { type BuiltInTemplateId } from "./template-registry.js";
 import type { PackageManagerId } from "./package-managers.js";
-import type { ScaffoldTemplateVariables } from "./scaffold.js";
+import type { ScaffoldProgressEvent, ScaffoldTemplateVariables } from "./scaffold.js";
 export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 export interface InstallDependenciesOptions {
     packageManager: PackageManagerId;
@@ -16,7 +16,7 @@ export declare function writeStarterManifestFiles(targetDir: string, templateId:
  */
 export declare function seedBuiltInPersistenceArtifacts(targetDir: string, templateId: BuiltInTemplateId, variables: ScaffoldTemplateVariables): Promise<void>;
 export declare function normalizePackageManagerFiles(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
-export declare function normalizePackageJson(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
+export declare function removeQueryLoopPlaceholderFiles(projectDir: string, templateId: string): Promise<void>;
 export declare function removeUnexpectedLockfiles(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
 /**
  * Recursively normalizes generated text files for the selected package manager
@@ -33,7 +33,7 @@ export declare function applyWorkspaceMigrationCapability(projectDir: string, pa
  * Applies a built-in scaffold into the target directory, including generated
  * code artifacts, starter manifests, preset files, and placeholder rewrites.
  */
-export declare function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir, packageManager, withMigrationUi, withTestPreset, withWpEnv, noInstall, installDependencies, repositoryReference, }: {
+export declare function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir, packageManager, withMigrationUi, withTestPreset, withWpEnv, noInstall, installDependencies, repositoryReference, onProgress, }: {
     projectDir: string;
     templateDir: string;
     templateId: BuiltInTemplateId;
@@ -50,4 +50,5 @@ export declare function applyBuiltInScaffoldProjectFiles({ projectDir, templateD
     noInstall?: boolean;
     installDependencies?: ((options: InstallDependenciesOptions) => Promise<void>) | undefined;
     repositoryReference?: string;
+    onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
 }): Promise<void>;

package/dist/runtime/scaffold-apply-utils.js

@@ -10,12 +10,17 @@ import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrati
 import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
 import { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+import { formatNonEmptyTargetDirectoryError, } from "./scaffold-bootstrap.js";
 import { stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, } from "./template-registry.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
-import { formatInstallCommand, formatPackageExecCommand, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { formatInstallCommand, formatPackageExecCommand, transformPackageManagerText, } from "./package-managers.js";
+import { normalizePackageJson } from "./scaffold-package-manager-files.js";
 import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
 export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
+async function reportScaffoldProgress(onProgress, event) {
+    await onProgress?.(event);
+}
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LOCKFILES = {
@@ -34,7 +39,7 @@ export async function ensureDirectory(targetDir, allowExisting = false) {
     }
     const entries = await fsp.readdir(targetDir);
     if (entries.length > 0) {
-        throw new Error(`Target directory is not empty: ${targetDir}`);
+        throw new Error(formatNonEmptyTargetDirectoryError(targetDir));
     }
 }
 export async function writeStarterManifestFiles(targetDir, templateId, variables, artifacts) {
@@ -135,22 +140,13 @@ export async function normalizePackageManagerFiles(targetDir, packageManagerId)
         await fsp.rm(yarnRcPath, { force: true });
     }
 }
-export async function normalizePackageJson(targetDir, packageManagerId) {
-    const packageJsonPath = path.join(targetDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
+export async function removeQueryLoopPlaceholderFiles(projectDir, templateId) {
+    if (templateId !== "query-loop") {
         return;
     }
-    const packageManager = getPackageManager(packageManagerId);
-    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    packageJson.packageManager = packageManager.packageManagerField;
-    if (packageJson.scripts) {
-        for (const [key, value] of Object.entries(packageJson.scripts)) {
-            if (typeof value === "string") {
-                packageJson.scripts[key] = transformPackageManagerText(value, packageManagerId);
-            }
-        }
-    }
-    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+    await fsp.rm(path.join(projectDir, "src", "validator-toolkit.ts"), {
+        force: true,
+    });
 }
 export async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
     const keep = new Set(LOCKFILES[packageManagerId] ?? []);
@@ -254,8 +250,13 @@ export async function applyWorkspaceMigrationCapability(projectDir, packageManag
  * Applies a built-in scaffold into the target directory, including generated
  * code artifacts, starter manifests, preset files, and placeholder rewrites.
  */
-export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir = false, packageManager, withMigrationUi = false, withTestPreset = false, withWpEnv = false, noInstall = false, installDependencies, repositoryReference, }) {
+export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir = false, packageManager, withMigrationUi = false, withTestPreset = false, withWpEnv = false, noInstall = false, installDependencies, repositoryReference, onProgress, }) {
     await ensureDirectory(projectDir, allowExistingDir);
+    await reportScaffoldProgress(onProgress, {
+        detail: "Copying built-in template files and writing generated source modules.",
+        phase: "generate-files",
+        title: "Generating project files",
+    });
     await copyInterpolatedDirectory(templateDir, projectDir, variables);
     if (codeArtifacts && codeArtifacts.length > 0) {
         await writeBuiltInCodeArtifacts(projectDir, codeArtifacts);
@@ -263,6 +264,11 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
     if (artifacts && artifacts.length > 0) {
         await writeBuiltInStructuralArtifacts(projectDir, artifacts);
     }
+    await reportScaffoldProgress(onProgress, {
+        detail: "Writing starter manifests, local presets, and seeded template artifacts.",
+        phase: "seed-artifacts",
+        title: "Seeding scaffold artifacts",
+    });
     await writeStarterManifestFiles(projectDir, templateId, variables, artifacts);
     await seedBuiltInPersistenceArtifacts(projectDir, templateId, variables);
     await applyLocalDevPresetFiles({
@@ -279,6 +285,11 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
             variables,
         });
     }
+    await reportScaffoldProgress(onProgress, {
+        detail: "Writing README, normalizing package metadata, and aligning package-manager files.",
+        phase: "finalize-project",
+        title: "Finalizing scaffold output",
+    });
     const readmePath = path.join(projectDir, "README.md");
     if (!fs.existsSync(readmePath)) {
         await fsp.writeFile(readmePath, readmeContent ??
@@ -302,12 +313,18 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
         withTestPreset,
         withWpEnv,
     });
+    await removeQueryLoopPlaceholderFiles(projectDir, templateId);
     await normalizePackageManagerFiles(projectDir, packageManager);
     await removeUnexpectedLockfiles(projectDir, packageManager);
     await replaceTextRecursively(projectDir, packageManager, {
         repositoryReference,
     });
     if (!noInstall) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Installing project dependencies with the selected package manager.",
+            phase: "install-dependencies",
+            title: "Installing dependencies",
+        });
         const installer = installDependencies ?? defaultInstallDependencies;
         await installer({
             projectDir,

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

@@ -9,6 +9,14 @@ import type { BuiltInTemplateId } from "./template-registry.js";
  * @returns A promise that resolves once the directory precondition is satisfied.
  */
 export declare function ensureScaffoldDirectory(targetDir: string, allowExisting?: boolean): Promise<void>;
+/**
+ * Format the actionable error message used when a scaffold target directory
+ * already exists and is not empty.
+ *
+ * @param targetDir Absolute path to the target directory being evaluated.
+ * @returns A human-readable error string with next-step guidance.
+ */
+export declare function formatNonEmptyTargetDirectoryError(targetDir: string): string;
 /**
  * Writes built-in starter manifest files into a scaffolded project.
  *
@@ -28,6 +36,13 @@ export declare function writeStarterManifestFiles(targetDir: string, templateId:
  * @returns A promise that resolves after any required persistence artifacts are generated.
  */
 export declare function seedBuiltInPersistenceArtifacts(targetDir: string, templateId: BuiltInTemplateId, variables: ScaffoldTemplateVariables): Promise<void>;
+/**
+ * Detects whether a scaffolded project declares the workspace project model.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies a workspace scaffold.
+ */
+export declare function isWorkspaceProject(projectDir: string): boolean;
 /**
  * Detects whether a scaffolded project is the official workspace template.
  *

package/dist/runtime/scaffold-bootstrap.js

@@ -25,9 +25,26 @@ export async function ensureScaffoldDirectory(targetDir, allowExisting = false)
     }
     const entries = await fsp.readdir(targetDir);
     if (entries.length > 0) {
-        throw new Error(`Target directory is not empty: ${targetDir}`);
+        throw new Error(formatNonEmptyTargetDirectoryError(targetDir));
     }
 }
+function readGeneratedPackageJson(projectDir) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return null;
+    }
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+}
+/**
+ * Format the actionable error message used when a scaffold target directory
+ * already exists and is not empty.
+ *
+ * @param targetDir Absolute path to the target directory being evaluated.
+ * @returns A human-readable error string with next-step guidance.
+ */
+export function formatNonEmptyTargetDirectoryError(targetDir) {
+    return `Target directory is not empty: ${targetDir}. Choose a new project directory, or empty this directory before rerunning the scaffold.`;
+}
 /**
  * Writes built-in starter manifest files into a scaffolded project.
  *
@@ -77,6 +94,15 @@ export async function seedBuiltInPersistenceArtifacts(targetDir, templateId, var
         });
     });
 }
+/**
+ * Detects whether a scaffolded project declares the workspace project model.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies a workspace scaffold.
+ */
+export function isWorkspaceProject(projectDir) {
+    return readGeneratedPackageJson(projectDir)?.wpTypia?.projectType === "workspace";
+}
 /**
  * Detects whether a scaffolded project is the official workspace template.
  *
@@ -84,12 +110,8 @@ export async function seedBuiltInPersistenceArtifacts(targetDir, templateId, var
  * @returns `true` when the project metadata identifies the official workspace template.
  */
 export function isOfficialWorkspaceProject(projectDir) {
-    const packageJsonPath = path.join(projectDir, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-        return false;
-    }
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-    return (packageJson.wpTypia?.projectType === "workspace" &&
+    const packageJson = readGeneratedPackageJson(projectDir);
+    return (packageJson?.wpTypia?.projectType === "workspace" &&
         packageJson.wpTypia?.templatePackage === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE);
 }
 /**

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,12 +23,31 @@ 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,
     });
     const developmentScript = getPrimaryDevelopmentScript(templateId);
+    const noStepsHeading = templateId === 'query-loop' ? 'Variation Workflow' : 'Artifact Refresh';
     const wpEnvSection = withWpEnv
         ? `## Local WordPress\n\n\`\`\`bash\n${formatRunScript(packageManager, 'wp-env:start')}\n${formatRunScript(packageManager, 'wp-env:stop')}\n${formatRunScript(packageManager, 'wp-env:reset')}\n\`\`\``
         : '';
@@ -41,7 +61,7 @@ export function buildReadme(templateId, variables, packageManager, { withMigrati
         ? `## Advanced Sync\n\n\`\`\`bash\n${optionalOnboardingSteps.join('\n')}\n\`\`\`\n\n${getOptionalOnboardingNote(packageManager, templateId, {
             compoundPersistenceEnabled,
         })}`
-        : `## Artifact Refresh\n\n${getOptionalOnboardingNote(packageManager, templateId, {
+        : `## ${noStepsHeading}\n\n${getOptionalOnboardingNote(packageManager, templateId, {
             compoundPersistenceEnabled,
         })}`;
     return `# ${variables.title}
@@ -68,6 +88,7 @@ ${getQuickStartWorkflowNote(packageManager, templateId, {
 \`\`\`bash
 ${formatRunScript(packageManager, 'build')}
 ${formatRunScript(packageManager, 'typecheck')}
+${formatPackageExecCommand(packageManager, `wp-typia@${getPackageVersions().wpTypiaPackageExactVersion}`, 'doctor')}
 \`\`\`
 
 ${advancedSyncSection}
@@ -80,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, "start")} 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 \`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, "start")}, 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.";
@@ -135,9 +141,15 @@ export function getCompoundExtensionWorkflowSection(packageManager, templateId)
 
 \`\`\`bash
 ${formatRunScript(packageManager, "add-child", '--slug faq-item --title "FAQ Item"')}
+
+${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 a new hidden child block type, updates \`scripts/block-config.ts\` and \`src/blocks/*/children.ts\`, and leaves the default seeded child template unchanged.`;
+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-package-manager-files.js

@@ -38,7 +38,12 @@ export async function normalizePackageJson(targetDir, packageManagerId) {
     }
     const packageManager = getPackageManager(packageManagerId);
     const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
-    packageJson.packageManager = packageManager.packageManagerField;
+    if (packageManagerId === "npm") {
+        delete packageJson.packageManager;
+    }
+    else {
+        packageJson.packageManager = packageManager.packageManagerField;
+    }
     if (packageJson.scripts) {
         for (const [key, value] of Object.entries(packageJson.scripts)) {
             if (typeof value === "string") {