@wp-typia/project-tools 0.16.14 → 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\`\`\``
         : '';
@@ -37,6 +38,13 @@ export function buildReadme(templateId, variables, packageManager, { withMigrati
     const migrationSection = withMigrationUi
         ? `## Migration UI\n\nThis scaffold already includes an initialized migration workspace at \`v1\`, generated deprecated/runtime artifacts, and an editor-embedded migration dashboard. Migration versions are schema lineage labels and are separate from your package or plugin release version. Use the existing CLI commands to snapshot, diff, scaffold, verify, and fuzz future schema changes.\n\n\`\`\`bash\n${formatRunScript(packageManager, 'migration:doctor')}\n${formatRunScript(packageManager, 'migration:verify')}\n${formatRunScript(packageManager, 'migration:fuzz')}\n\`\`\`\n\nRun \`migration:init\` only when retrofitting migration support into an older project that was not scaffolded with \`--with-migration-ui\`.`
         : '';
+    const advancedSyncSection = optionalOnboardingSteps.length > 0
+        ? `## Advanced Sync\n\n\`\`\`bash\n${optionalOnboardingSteps.join('\n')}\n\`\`\`\n\n${getOptionalOnboardingNote(packageManager, templateId, {
+            compoundPersistenceEnabled,
+        })}`
+        : `## ${noStepsHeading}\n\n${getOptionalOnboardingNote(packageManager, templateId, {
+            compoundPersistenceEnabled,
+        })}`;
     return `# ${variables.title}
 
 ${variables.description}
@@ -63,15 +71,7 @@ ${formatRunScript(packageManager, 'build')}
 ${formatRunScript(packageManager, 'typecheck')}
 \`\`\`
 
-## Advanced Sync
-
-\`\`\`bash
-${optionalOnboardingSteps.join('\n')}
-\`\`\`
-
-${getOptionalOnboardingNote(packageManager, templateId, {
-        compoundPersistenceEnabled,
-    })}
+${advancedSyncSection}
 
 ## Before First Commit
 

package/dist/runtime/scaffold-onboarding.js

@@ -13,6 +13,9 @@ function templateHasPersistenceSync(templateId, { compoundPersistenceEnabled = f
  * Returns the optional sync script names to suggest for a template.
  */
 export function getOptionalSyncScriptNames(templateId, options = {}) {
+    if (templateId === "query-loop") {
+        return [];
+    }
     const availableScripts = new Set(options.availableScripts ?? []);
     if (availableScripts.has("sync")) {
         return ["sync"];
@@ -37,6 +40,9 @@ 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 = {}) {
+    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\`.`;
+    }
     const developmentScript = getPrimaryDevelopmentScript(templateId);
     const devCommand = formatRunScript(packageManager, developmentScript);
     const startCommand = formatRunScript(packageManager, "start");
@@ -55,6 +61,9 @@ export function getQuickStartWorkflowNote(packageManager, templateId = "basic",
  * Returns the onboarding note explaining when manual sync is optional.
  */
 export function getOptionalOnboardingNote(packageManager, templateId = "basic", options = {}) {
+    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.`;
+    }
     const optionalSyncScripts = getOptionalSyncScriptNames(templateId, options);
     const hasUnifiedSync = optionalSyncScripts.includes("sync");
     const syncSteps = optionalSyncScripts.map((scriptName) => formatRunScript(packageManager, scriptName));
@@ -100,6 +109,9 @@ export function getInitialCommitNote() {
  * Returns source-of-truth guidance for generated artifacts by template mode.
  */
 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.";
+    }
     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.";
         if (compoundPersistenceEnabled) {
@@ -123,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-template-variables.js

@@ -73,7 +73,13 @@ export function getTemplateVariables(templateId, answers) {
         dataStorageMode,
         dashCase: slug,
         description,
+        descriptionJson: JSON.stringify(description),
         frontendCssClassName: buildFrontendCssClassName(cssClassName),
+        queryAllowedControlsJson: JSON.stringify([], null, 2),
+        queryPostType: answers.queryPostType?.trim() || 'post',
+        queryPostTypeJson: JSON.stringify(answers.queryPostType?.trim() || 'post'),
+        queryVariationNamespace: `${namespace}/${slug}`,
+        queryVariationNamespaceJson: JSON.stringify(`${namespace}/${slug}`),
         isAuthenticatedPersistencePolicy: persistencePolicy === 'authenticated' ? 'true' : 'false',
         isPublicPersistencePolicy: persistencePolicy === 'public' ? 'true' : 'false',
         bootstrapCredentialDeclarations: persistencePolicy === 'public'

package/dist/runtime/scaffold.d.ts

@@ -15,6 +15,7 @@ export interface ScaffoldAnswers {
     persistencePolicy?: PersistencePolicy;
     /** Snake_case PHP symbol prefix used for generated functions, constants, and keys. */
     phpPrefix?: string;
+    queryPostType?: string;
     slug: string;
     /** Kebab-case WordPress text domain used in block metadata and i18n strings. */
     textDomain?: string;
@@ -46,6 +47,7 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     dashCase: string;
     dataStorageMode: DataStorageMode;
     description: string;
+    descriptionJson: string;
     frontendCssClassName: string;
     keyword: string;
     namespace: string;
@@ -53,6 +55,11 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
     pascalCase: string;
     phpPrefix: string;
     phpPrefixUpper: string;
+    queryAllowedControlsJson: string;
+    queryPostTypeJson: string;
+    queryPostType: string;
+    queryVariationNamespace: string;
+    queryVariationNamespaceJson: string;
     isAuthenticatedPersistencePolicy: "false" | "true";
     isPublicPersistencePolicy: "false" | "true";
     bootstrapCredentialDeclarations: string;
@@ -106,6 +113,7 @@ export interface CollectScaffoldAnswersOptions {
     projectName: string;
     promptText?: (message: string, defaultValue: string, validate?: (value: string) => true | string) => Promise<string>;
     persistencePolicy?: PersistencePolicy;
+    queryPostType?: string;
     textDomain?: string;
     templateId: string;
     withTestPreset?: boolean;
@@ -116,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;
@@ -126,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;
@@ -149,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-defaults.d.ts

@@ -22,6 +22,10 @@ export declare const BUILTIN_TEMPLATE_METADATA_DEFAULTS: Readonly<{
         category: "widgets";
         icon: "screenoptions";
     }>;
+    "query-loop": Readonly<{
+        category: "widgets";
+        icon: "query-pagination";
+    }>;
 }>;
 /**
  * Shared hidden child block metadata defaults for compound scaffolds.
@@ -56,6 +60,9 @@ export declare function getBuiltInTemplateMetadataDefaults(templateId: keyof typ
 }> | Readonly<{
     category: "widgets";
     icon: "screenoptions";
+}> | Readonly<{
+    category: "widgets";
+    icon: "query-pagination";
 }>;
 /**
  * Checks whether a template id points at a removed built-in scaffold.

package/dist/runtime/template-defaults.js

@@ -22,6 +22,10 @@ export const BUILTIN_TEMPLATE_METADATA_DEFAULTS = Object.freeze({
         category: "widgets",
         icon: "screenoptions",
     }),
+    "query-loop": Object.freeze({
+        category: "widgets",
+        icon: "query-pagination",
+    }),
 });
 /**
  * Shared hidden child block metadata defaults for compound scaffolds.

package/dist/runtime/template-registry.d.ts

@@ -14,7 +14,7 @@ export declare const SHARED_MIGRATION_UI_TEMPLATE_ROOT: string;
 export declare const SHARED_WORKSPACE_TEMPLATE_ROOT: string;
 export declare const SHARED_TEST_PRESET_TEMPLATE_ROOT: string;
 export declare const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT: string;
-export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound"];
+export declare const BUILTIN_TEMPLATE_IDS: readonly ["basic", "interactivity", "persistence", "compound", "query-loop"];
 export declare const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export type BuiltInTemplateId = (typeof BUILTIN_TEMPLATE_IDS)[number];
 export type PersistencePolicy = "authenticated" | "public";

package/dist/runtime/template-registry.js

@@ -40,7 +40,13 @@ export const SHARED_MIGRATION_UI_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT,
 export const SHARED_WORKSPACE_TEMPLATE_ROOT = path.join(SHARED_TEMPLATE_ROOT, "workspace");
 export const SHARED_TEST_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "test-preset");
 export const SHARED_WP_ENV_PRESET_TEMPLATE_ROOT = path.join(SHARED_PRESET_TEMPLATE_ROOT, "wp-env");
-export const BUILTIN_TEMPLATE_IDS = ["basic", "interactivity", "persistence", "compound"];
+export const BUILTIN_TEMPLATE_IDS = [
+    "basic",
+    "interactivity",
+    "persistence",
+    "compound",
+    "query-loop",
+];
 export const OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE = "@wp-typia/create-workspace-template";
 export const TEMPLATE_REGISTRY = Object.freeze([
     {
@@ -71,6 +77,13 @@ export const TEMPLATE_REGISTRY = Object.freeze([
         features: ["InnerBlocks", "Hidden child blocks", "Optional persistence layer"],
         templateDir: path.join(TEMPLATE_ROOT, "compound"),
     },
+    {
+        id: "query-loop",
+        description: "A Query Loop block variation scaffold with stable namespace-based identity, inline starter layout, connected pattern presets, custom query seams, and runtime parity hooks",
+        defaultCategory: getBuiltInTemplateMetadataDefaults("query-loop").category,
+        features: ["core/query variation", "Default innerBlocks", "Connected patterns", "Custom query hooks", "Runtime parity hooks", "Allowed controls"],
+        templateDir: path.join(TEMPLATE_ROOT, "query-loop"),
+    },
     {
         id: OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE,
         description: "The official empty workspace template that powers `wp-typia add ...` workflows",

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.
  *