@wp-typia/project-tools 0.17.0 → 0.18.0

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

@@ -28,6 +28,7 @@ export function buildReadme(templateId, variables, packageManager, { withMigrati
         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 +42,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}

package/dist/runtime/scaffold-onboarding.js

@@ -41,7 +41,7 @@ export function getOptionalOnboardingSteps(packageManager, templateId, options =
  */
 export function getQuickStartWorkflowNote(packageManager, templateId = "basic", options = {}) {
     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 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\`.`;
     }
     const developmentScript = getPrimaryDevelopmentScript(templateId);
     const devCommand = formatRunScript(packageManager, developmentScript);
@@ -62,7 +62,7 @@ export function getQuickStartWorkflowNote(packageManager, templateId = "basic",
  */
 export function getOptionalOnboardingNote(packageManager, templateId = "basic", options = {}) {
     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 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.`;
     }
     const optionalSyncScripts = getOptionalSyncScriptNames(templateId, options);
     const hasUnifiedSync = optionalSyncScripts.includes("sync");
@@ -135,9 +135,13 @@ 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')}
 \`\`\`
 
-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.`;
 }
 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") {

package/dist/runtime/scaffold.d.ts

@@ -124,6 +124,11 @@ interface InstallDependenciesOptions {
     packageManager: PackageManagerId;
     projectDir: string;
 }
+export interface ScaffoldProgressEvent {
+    detail: string;
+    phase: "finalize-project" | "generate-files" | "install-dependencies" | "resolve-template" | "seed-artifacts";
+    title: string;
+}
 interface ScaffoldProjectOptions {
     allowExistingDir?: boolean;
     answers: ScaffoldAnswers;
@@ -134,6 +139,7 @@ interface ScaffoldProjectOptions {
     externalLayerSourceLabel?: string;
     installDependencies?: ((options: InstallDependenciesOptions) => Promise<void>) | undefined;
     noInstall?: boolean;
+    onProgress?: ((event: ScaffoldProgressEvent) => void | Promise<void>) | undefined;
     packageManager: PackageManagerId;
     persistencePolicy?: PersistencePolicy;
     projectDir: string;
@@ -157,4 +163,4 @@ export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackage
 export { getTemplateVariables } from "./scaffold-template-variables.js";
 export declare function isDataStorageMode(value: string): value is DataStorageMode;
 export declare function isPersistencePolicy(value: string): value is PersistencePolicy;
-export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;
+export declare function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd, allowExistingDir, noInstall, installDependencies, onProgress, variant, withMigrationUi, withTestPreset, withWpEnv, }: ScaffoldProjectOptions): Promise<ScaffoldProjectResult>;

package/dist/runtime/scaffold.js

@@ -2,10 +2,10 @@ import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { getPackageManager } from "./package-managers.js";
-import { buildGitignore, buildReadme, mergeTextLines, replaceTextRecursively, } from "./scaffold-apply-utils.js";
+import { buildGitignore, buildReadme, mergeTextLines, removeQueryLoopPlaceholderFiles, replaceTextRecursively, } from "./scaffold-apply-utils.js";
 import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
-import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isOfficialWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
+import { applyWorkspaceMigrationCapability, ensureScaffoldDirectory, isWorkspaceProject, seedBuiltInPersistenceArtifacts, writeStarterManifestFiles, } from "./scaffold-bootstrap.js";
 import { defaultInstallDependencies, normalizePackageJson, normalizePackageManagerFiles, removeUnexpectedLockfiles, } from "./scaffold-package-manager-files.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
@@ -29,7 +29,10 @@ function normalizeTemplateSelection(templateId) {
         ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
         : templateId;
 }
-export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
+async function reportScaffoldProgress(onProgress, event) {
+    await onProgress?.(event);
+}
+export async function scaffoldProject({ projectDir, templateId, answers, dataStorageMode, persistencePolicy, packageManager, externalLayerId, externalLayerSource, externalLayerSourceLabel, repositoryReference, cwd = process.cwd(), allowExistingDir = false, noInstall = false, installDependencies = undefined, onProgress = undefined, variant, withMigrationUi = false, withTestPreset = false, withWpEnv = false, }) {
     const resolvedTemplateId = normalizeTemplateSelection(templateId);
     const resolvedPackageManager = getPackageManager(packageManager).id;
     const isBuiltInTemplate = isBuiltInTemplateId(resolvedTemplateId);
@@ -38,6 +41,11 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
     }
     if (isBuiltInTemplate) {
         const blockGeneratorService = new BlockGeneratorService();
+        await reportScaffoldProgress(onProgress, {
+            detail: "Preparing template layers, variants, and generated artifact plans.",
+            phase: "resolve-template",
+            title: "Resolving scaffold template",
+        });
         const plan = await blockGeneratorService.plan({
             allowExistingDir,
             answers,
@@ -61,6 +69,7 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
         const rendered = await blockGeneratorService.render({ validated });
         return blockGeneratorService.apply({
             installDependencies,
+            onProgress,
             rendered,
         });
     }
@@ -72,13 +81,25 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
         dataStorageMode: dataStorageMode ?? answers.dataStorageMode,
         persistencePolicy: persistencePolicy ?? answers.persistencePolicy,
     });
+    await reportScaffoldProgress(onProgress, {
+        detail: "Loading template files, variants, and external package metadata when needed.",
+        phase: "resolve-template",
+        title: "Resolving scaffold template",
+    });
     const templateSource = await resolveTemplateSource(resolvedTemplateId, cwd, variables, variant);
-    const supportsMigrationUi = isBuiltInTemplate || templateSource.isOfficialWorkspaceTemplate === true;
+    const supportsMigrationUi = isBuiltInTemplate ||
+        templateSource.isOfficialWorkspaceTemplate === true ||
+        templateSource.supportsMigrationUi === true;
     if (withMigrationUi && !supportsMigrationUi) {
         await templateSource.cleanup?.();
-        throw new Error("`--with-migration-ui` is currently supported only for built-in templates and @wp-typia/create-workspace-template.");
+        throw new Error("`--with-migration-ui` is currently supported only for built-in templates and workspace-capable wp-typia templates.");
     }
     try {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Copying scaffold files into the target project directory.",
+            phase: "generate-files",
+            title: "Generating project files",
+        });
         await ensureScaffoldDirectory(projectDir, allowExistingDir);
         await copyInterpolatedDirectory(templateSource.templateDir, projectDir, variables);
     }
@@ -87,8 +108,13 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
             await templateSource.cleanup();
         }
     }
-    const isOfficialWorkspace = isOfficialWorkspaceProject(projectDir);
+    const isWorkspace = isWorkspaceProject(projectDir);
     if (isBuiltInTemplate) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Writing starter manifests, local presets, and template-specific generated artifacts.",
+            phase: "seed-artifacts",
+            title: "Seeding scaffold artifacts",
+        });
         await writeStarterManifestFiles(projectDir, resolvedTemplateId, variables);
         await seedBuiltInPersistenceArtifacts(projectDir, resolvedTemplateId, variables);
         await applyLocalDevPresetFiles({
@@ -105,14 +131,25 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
                 variables,
             });
         }
+        await removeQueryLoopPlaceholderFiles(projectDir, resolvedTemplateId);
     }
-    else if (withMigrationUi && isOfficialWorkspace) {
+    else if (withMigrationUi && isWorkspace) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Initializing workspace migration scripts and starter migration files.",
+            phase: "seed-artifacts",
+            title: "Seeding scaffold artifacts",
+        });
         await applyWorkspaceMigrationCapability(projectDir, resolvedPackageManager);
     }
+    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, buildReadme(resolvedTemplateId, variables, resolvedPackageManager, {
-            withMigrationUi: isBuiltInTemplate || isOfficialWorkspace ? withMigrationUi : false,
+            withMigrationUi: isBuiltInTemplate || isWorkspace ? withMigrationUi : false,
             withTestPreset: isBuiltInTemplate ? withTestPreset : false,
             withWpEnv: isBuiltInTemplate ? withWpEnv : false,
         }), "utf8");
@@ -139,6 +176,11 @@ export async function scaffoldProject({ projectDir, templateId, answers, dataSto
         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/template-render.d.ts

@@ -13,8 +13,9 @@ export interface CopyRawDirectoryOptions {
      *
      * Throwing or rejecting aborts the copy and bubbles to the caller.
      */
-    filter?: (sourcePath: string, targetPath: string, entry: fs.Dirent) => boolean | Promise<boolean>;
+    filter?: CopyDirectoryFilter;
 }
+export type CopyDirectoryFilter = (sourcePath: string, destinationPath: string, entry: fs.Dirent) => boolean | Promise<boolean>;
 /**
  * Render a Mustache template with full Mustache semantics while leaving values
  * unescaped for scaffold source generation.
@@ -28,7 +29,9 @@ export declare function copyRawDirectory(sourceDir: string, targetDir: string, o
  * Copy a template directory using full Mustache semantics for filenames and
  * text-file contents while leaving rendered values unescaped.
  */
-export declare function copyRenderedDirectory(sourceDir: string, targetDir: string, view: TemplateRenderView): Promise<void>;
+export declare function copyRenderedDirectory(sourceDir: string, targetDir: string, view: TemplateRenderView, options?: {
+    filter?: CopyDirectoryFilter;
+}): Promise<void>;
 /**
  * Copy a template directory using direct `{{key}}` replacement only.
  *

package/dist/runtime/template-render.js

@@ -66,15 +66,19 @@ function stripTemplateExtension(entryName) {
 function renderTemplateDestinationName(entryName, view, renderString) {
     return renderString(stripTemplateExtension(entryName), view);
 }
-async function traverseTemplateDirectory({ prepareDirectory, renderString, sourceDir, targetDir, view, visitFile, }) {
+async function traverseTemplateDirectory({ filter, prepareDirectory, renderString, sourceDir, targetDir, view, visitFile, }) {
     const entries = await fsp.readdir(sourceDir, { withFileTypes: true });
     for (const entry of entries) {
         const sourcePath = path.join(sourceDir, entry.name);
         const destinationName = renderTemplateDestinationName(entry.name, view, renderString);
         const destinationPath = resolveRenderedPath(targetDir, destinationName);
+        if (filter && !(await filter(sourcePath, destinationPath, entry))) {
+            continue;
+        }
         if (entry.isDirectory()) {
             await prepareDirectory?.(destinationPath);
             await traverseTemplateDirectory({
+                filter,
                 prepareDirectory,
                 renderString,
                 sourceDir: sourcePath,
@@ -90,9 +94,10 @@ async function traverseTemplateDirectory({ prepareDirectory, renderString, sourc
         });
     }
 }
-async function copyTemplateDirectory({ renderString, sourceDir, targetDir, view, }) {
+async function copyTemplateDirectory({ filter, renderString, sourceDir, targetDir, view, }) {
     await fsp.mkdir(targetDir, { recursive: true });
     await traverseTemplateDirectory({
+        filter,
         prepareDirectory: async (directoryPath) => {
             await fsp.mkdir(directoryPath, { recursive: true });
         },
@@ -134,8 +139,9 @@ export async function copyRawDirectory(sourceDir, targetDir, options = {}) {
  * Copy a template directory using full Mustache semantics for filenames and
  * text-file contents while leaving rendered values unescaped.
  */
-export async function copyRenderedDirectory(sourceDir, targetDir, view) {
+export async function copyRenderedDirectory(sourceDir, targetDir, view, options = {}) {
     await copyTemplateDirectory({
+        filter: options.filter,
         renderString: renderMustacheTemplateString,
         sourceDir,
         targetDir,

package/dist/runtime/template-source-contracts.d.ts

@@ -35,6 +35,11 @@ export interface ResolvedTemplateSource {
     features: string[];
     format: TemplateSourceFormat;
     isOfficialWorkspaceTemplate?: boolean;
+    /**
+     * True when the resolved template can participate in scaffold migration UI
+     * seeding, such as rendered wp-typia workspace templates.
+     */
+    supportsMigrationUi?: boolean;
     templateDir: string;
     cleanup?: () => Promise<void>;
     selectedVariant?: string | null;
@@ -58,6 +63,11 @@ export interface ExternalTemplateConfig<TView extends UnknownRecord = TemplateVa
     blockTemplatesPath?: string;
     defaultValues?: Partial<TView>;
     folderName?: string;
+    /**
+     * Relative template root that renders a fuller wp-typia plugin/workspace
+     * scaffold instead of a create-block subset.
+     */
+    pluginTemplatesPath?: string;
     transformer?: (view: TView) => UnknownRecord | Promise<UnknownRecord>;
     variants?: Record<string, Partial<TView>>;
 }
@@ -65,6 +75,7 @@ export interface SeedSource {
     assetsDir?: string;
     blockDir: string;
     cleanup?: () => Promise<void>;
+    formatHint?: 'create-block-subset' | 'wp-typia';
     rootDir: string;
     selectedVariant?: string | null;
     warnings?: string[];

package/dist/runtime/template-source-external.d.ts

@@ -11,7 +11,7 @@ export declare const EXTERNAL_TEMPLATE_ENTRY_CANDIDATES: readonly ["index.js", "
  */
 export declare function getExternalTemplateEntry(sourceDir: string): string | null;
 /**
- * Load an official external create-block template config and render its seed.
+ * Load an official external template config and render its seed.
  *
  * @param sourceDir Source directory that contains the external template config.
  * @param context Template render context used for the selected variant.

package/dist/runtime/template-source-external.js

@@ -55,7 +55,6 @@ async function loadExternalTemplateConfig(sourceDir) {
     }
     const warnings = [];
     for (const ignoredKey of [
-        'pluginTemplatesPath',
         'wpScripts',
         'wpEnv',
         'customScripts',
@@ -105,9 +104,42 @@ function extractVariantRenderValues(variantConfig) {
     delete values.assetsPath;
     delete values.blockTemplatesPath;
     delete values.folderName;
+    delete values.pluginTemplatesPath;
     delete values.transformer;
     return values;
 }
+function resolveConfiguredTemplatePath(config, variantConfig) {
+    const variantPluginTemplatesPath = typeof variantConfig.pluginTemplatesPath === 'string'
+        ? variantConfig.pluginTemplatesPath
+        : null;
+    const variantBlockTemplatesPath = typeof variantConfig.blockTemplatesPath === 'string'
+        ? variantConfig.blockTemplatesPath
+        : null;
+    const configBlockTemplatesPath = typeof config.blockTemplatesPath === 'string'
+        ? config.blockTemplatesPath
+        : null;
+    const configPluginTemplatesPath = typeof config.pluginTemplatesPath === 'string'
+        ? config.pluginTemplatesPath
+        : null;
+    const templatePath = variantPluginTemplatesPath ??
+        variantBlockTemplatesPath ??
+        configBlockTemplatesPath ??
+        configPluginTemplatesPath;
+    if (!templatePath) {
+        throw new Error('External template config must define blockTemplatesPath or pluginTemplatesPath.');
+    }
+    const configuredFolderName = (typeof variantConfig.folderName === 'string'
+        ? variantConfig.folderName
+        : config.folderName) ?? null;
+    return {
+        folderName: configuredFolderName || '.',
+        formatHint: templatePath === variantPluginTemplatesPath ||
+            templatePath === configPluginTemplatesPath
+            ? 'wp-typia'
+            : 'create-block-subset',
+        templatePath,
+    };
+}
 async function buildExternalTemplateView(context, config, selectedVariant, variantConfig) {
     const mergedView = {
         ...(config.defaultValues ?? {}),
@@ -131,7 +163,7 @@ async function buildExternalTemplateView(context, config, selectedVariant, varia
     };
 }
 /**
- * Load an official external create-block template config and render its seed.
+ * Load an official external template config and render its seed.
  *
  * @param sourceDir Source directory that contains the external template config.
  * @param context Template render context used for the selected variant.
@@ -141,25 +173,24 @@ async function buildExternalTemplateView(context, config, selectedVariant, varia
 export async function renderCreateBlockExternalTemplate(sourceDir, context, requestedVariant) {
     const { config, warnings } = await loadExternalTemplateConfig(sourceDir);
     const { selectedVariant, variantConfig } = getVariantConfig(config, requestedVariant);
-    const blockTemplatesPath = (typeof variantConfig.blockTemplatesPath === 'string'
-        ? variantConfig.blockTemplatesPath
-        : config.blockTemplatesPath) ?? null;
-    if (!blockTemplatesPath) {
-        throw new Error('External template config must define blockTemplatesPath.');
-    }
+    const { folderName, formatHint, templatePath } = resolveConfiguredTemplatePath(config, variantConfig);
     const tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'wp-typia-create-block-external-'));
     const cleanup = async () => {
         await fsp.rm(tempRoot, { force: true, recursive: true });
     };
     try {
         const renderedRoot = path.join(tempRoot, 'rendered');
-        const folderName = (typeof variantConfig.folderName === 'string'
-            ? variantConfig.folderName
-            : config.folderName) || '.';
         const blockDir = resolveSourceSubpath(renderedRoot, folderName);
         const view = await buildExternalTemplateView(context, config, selectedVariant, variantConfig);
-        const blockTemplateDir = resolveSourceSubpath(sourceDir, blockTemplatesPath);
-        await copyRenderedDirectory(blockTemplateDir, blockDir, view);
+        const blockTemplateDir = resolveSourceSubpath(sourceDir, templatePath);
+        await copyRenderedDirectory(blockTemplateDir, blockDir, view, {
+            filter: (sourcePath, _destinationPath, entry) => {
+                const mustacheVariantPath = path.join(path.dirname(sourcePath), `${entry.name}.mustache`);
+                return !(entry.isFile() &&
+                    (entry.name === 'package.json' || entry.name === 'README.md') &&
+                    fs.existsSync(mustacheVariantPath));
+            },
+        });
         const assetsPath = typeof variantConfig.assetsPath === 'string'
             ? variantConfig.assetsPath
             : config.assetsPath;
@@ -172,6 +203,7 @@ export async function renderCreateBlockExternalTemplate(sourceDir, context, requ
                 : undefined,
             blockDir,
             cleanup,
+            formatHint,
             rootDir: tempRoot,
             selectedVariant,
             warnings,

package/dist/runtime/template-source-normalization.d.ts

@@ -1,5 +1,5 @@
 export { renderCreateBlockExternalTemplate } from './template-source-external.js';
-export { getDefaultCategory, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
+export { getTemplateProjectType, getDefaultCategory, normalizeCreateBlockSubset, normalizeWpTypiaTemplateSeed, } from './template-source-remote.js';
 import type { TemplateSourceFormat, TemplateVariableContext } from './template-source-contracts.js';
 export declare function getTemplateVariableContext(variables: {
     [key: string]: string;