@wp-typia/project-tools 0.16.13 → 0.17.0

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

@@ -0,0 +1,163 @@
+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';
+/**
+ * Detect the current author name from local Git config.
+ *
+ * @returns The configured Git author name, or `"Your Name"` when unavailable.
+ */
+export function detectAuthor() {
+    try {
+        return (execSync('git config user.name', {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() || 'Your Name');
+    }
+    catch {
+        return 'Your Name';
+    }
+}
+/**
+ * Compute the default scaffold answers for one project and template pair.
+ *
+ * @param projectName User-supplied project directory or block name seed.
+ * @param templateId Selected scaffold template identifier.
+ * @returns Normalized default answers for scaffold prompts and non-interactive flows.
+ */
+export function getDefaultAnswers(projectName, templateId) {
+    const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
+    const slugDefault = normalizeBlockSlug(projectName) || 'my-wp-typia-block';
+    return {
+        author: detectAuthor(),
+        dataStorageMode: templateId === 'persistence' ? 'custom-table' : undefined,
+        description: template?.description ?? 'A WordPress block scaffolded from a remote template',
+        namespace: slugDefault,
+        persistencePolicy: templateId === 'persistence' ? 'authenticated' : undefined,
+        phpPrefix: toSnakeCase(slugDefault),
+        queryPostType: templateId === 'query-loop' ? 'post' : undefined,
+        slug: slugDefault,
+        textDomain: slugDefault,
+        title: toTitleCase(slugDefault),
+    };
+}
+function validateQueryPostType(value) {
+    const normalizedValue = value.trim().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 true;
+}
+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 "-".');
+    }
+    return normalizedValue;
+}
+function normalizeTemplateSelection(templateId) {
+    return templateId === WORKSPACE_TEMPLATE_ALIAS
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
+/**
+ * Resolve the scaffold template id from flags, defaults, and interactive selection.
+ *
+ * @param options Template resolution options for interactive and non-interactive flows.
+ * @returns The normalized template identifier to scaffold.
+ */
+export async function resolveTemplateId({ templateId, yes = false, isInteractive = false, selectTemplate, }) {
+    if (templateId) {
+        const normalizedTemplateId = normalizeTemplateSelection(templateId);
+        if (isRemovedBuiltInTemplateId(templateId)) {
+            throw new Error(getRemovedBuiltInTemplateMessage(templateId));
+        }
+        if (isBuiltInTemplateId(normalizedTemplateId)) {
+            return getTemplateById(normalizedTemplateId).id;
+        }
+        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>.`);
+    }
+    return normalizeTemplateSelection(await selectTemplate());
+}
+/**
+ * Resolve the package manager id from flags, defaults, and interactive selection.
+ *
+ * @param options Package manager resolution options for interactive and non-interactive flows.
+ * @returns The normalized package manager id.
+ */
+export async function resolvePackageManagerId({ packageManager, yes = false, isInteractive = false, selectPackageManager, }) {
+    if (packageManager) {
+        return getPackageManager(packageManager).id;
+    }
+    if (yes) {
+        return 'npm';
+    }
+    if (!isInteractive || !selectPackageManager) {
+        throw new Error(`Package manager is required in non-interactive mode. Use --package-manager <${PACKAGE_MANAGER_IDS.join('|')}>.`);
+    }
+    return selectPackageManager();
+}
+/**
+ * Collect scaffold answers from defaults, CLI overrides, and optional prompts.
+ *
+ * @param options Answer collection inputs including prompt callbacks and explicit overrides.
+ * @returns The normalized scaffold answers used for rendering and file generation.
+ */
+export async function collectScaffoldAnswers({ projectName, templateId, yes = false, dataStorageMode, namespace, persistencePolicy, phpPrefix, promptText, queryPostType, textDomain, }) {
+    const defaults = getDefaultAnswers(projectName, templateId);
+    if (yes) {
+        const identifiers = resolveScaffoldIdentifiers({
+            namespace: namespace ?? defaults.namespace,
+            phpPrefix,
+            slug: defaults.slug,
+            textDomain,
+        });
+        return {
+            ...defaults,
+            dataStorageMode: dataStorageMode ?? defaults.dataStorageMode,
+            namespace: identifiers.namespace,
+            persistencePolicy: persistencePolicy ?? defaults.persistencePolicy,
+            phpPrefix: identifiers.phpPrefix,
+            queryPostType: normalizeQueryPostType(queryPostType ?? defaults.queryPostType),
+            textDomain: identifiers.textDomain,
+        };
+    }
+    if (!promptText) {
+        throw new Error('Interactive answers require a promptText callback.');
+    }
+    const identifiers = resolveScaffoldIdentifiers({
+        namespace: namespace ?? (await promptText('Namespace', defaults.namespace, validateNamespace)),
+        phpPrefix,
+        slug: await promptText('Block slug', defaults.slug, validateBlockSlug),
+        textDomain,
+    });
+    return {
+        author: await promptText('Author', defaults.author),
+        dataStorageMode: dataStorageMode ?? defaults.dataStorageMode,
+        description: await promptText('Description', defaults.description),
+        namespace: identifiers.namespace,
+        persistencePolicy: persistencePolicy ?? defaults.persistencePolicy,
+        phpPrefix: identifiers.phpPrefix,
+        queryPostType: templateId === 'query-loop'
+            ? normalizeQueryPostType(await promptText('Query post type', queryPostType ?? defaults.queryPostType ?? 'post', validateQueryPostType))
+            : normalizeQueryPostType(queryPostType ?? defaults.queryPostType),
+        slug: identifiers.slug,
+        textDomain: identifiers.textDomain,
+        title: await promptText('Block title', toTitleCase(identifiers.slug)),
+    };
+}
+import { execSync } from 'node:child_process';

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

@@ -3,27 +3,12 @@ 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";
+export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 export interface InstallDependenciesOptions {
     packageManager: PackageManagerId;
     projectDir: string;
 }
 export declare function ensureDirectory(targetDir: string, allowExisting?: boolean): Promise<void>;
-/**
- * Builds the generated README markdown for one scaffolded project.
- *
- * @param templateId Scaffold template family or template identifier.
- * @param variables Interpolated scaffold variables used in generated content.
- * @param packageManager Package manager used to format install and script commands.
- * @param options Optional README sections enabled by scaffold presets.
- * @returns Markdown README content for the generated project root.
- */
-export declare function buildReadme(templateId: string, variables: ScaffoldTemplateVariables, packageManager: PackageManagerId, { withMigrationUi, withTestPreset, withWpEnv, }?: {
-    withMigrationUi?: boolean;
-    withTestPreset?: boolean;
-    withWpEnv?: boolean;
-}): string;
-export declare function buildGitignore(): string;
-export declare function mergeTextLines(primaryContent: string, existingContent: string): string;
 export declare function writeStarterManifestFiles(targetDir: string, templateId: string, variables: ScaffoldTemplateVariables, artifacts?: readonly BuiltInBlockArtifact[]): Promise<void>;
 /**
  * Seed REST-derived persistence artifacts into a newly scaffolded built-in

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

@@ -3,18 +3,19 @@ import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, getPrimaryDevelopmentScript, } from "./local-dev-presets.js";
+import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
 import { applyMigrationUiCapability } from "./migration-ui-capability.js";
 import { getPackageVersions } from "./package-versions.js";
 import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
 import { syncPersistenceRestArtifacts, } from "./persistence-rest-artifacts.js";
-import { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getInitialCommitNote, getOptionalOnboardingNote, getOptionalOnboardingSteps, getQuickStartWorkflowNote, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from "./scaffold-onboarding.js";
+import { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.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, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { formatInstallCommand, formatPackageExecCommand, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
 import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
+export { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const LOCKFILES = {
@@ -36,131 +37,6 @@ export async function ensureDirectory(targetDir, allowExisting = false) {
         throw new Error(`Target directory is not empty: ${targetDir}`);
     }
 }
-/**
- * Builds the generated README markdown for one scaffolded project.
- *
- * @param templateId Scaffold template family or template identifier.
- * @param variables Interpolated scaffold variables used in generated content.
- * @param packageManager Package manager used to format install and script commands.
- * @param options Optional README sections enabled by scaffold presets.
- * @returns Markdown README content for the generated project root.
- */
-export function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
-    const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
-    });
-    const initialCommitCommands = getInitialCommitCommands();
-    const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
-    });
-    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === "true";
-    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 compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
-    const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
-        compoundPersistenceEnabled,
-        slug: variables.slug,
-    });
-    const developmentScript = getPrimaryDevelopmentScript(templateId);
-    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\`\`\``
-        : "";
-    const testPresetSection = withTestPreset
-        ? `## Local Test Preset\n\n\`\`\`bash\n${formatRunScript(packageManager, "wp-env:start:test")}\n${formatRunScript(packageManager, "wp-env:wait:test")}\n${formatRunScript(packageManager, "test:e2e")}\n\`\`\`\n\nThe generated smoke test uses \`.wp-env.test.json\` and verifies that the scaffolded block registers in the WordPress editor.`
-        : "";
-    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\`.`
-        : "";
-    return `# ${variables.title}
-
-${variables.description}
-
-## Template
-
-${templateId}
-
-## Quick Start
-
-\`\`\`bash
-${formatInstallCommand(packageManager)}
-${formatRunScript(packageManager, developmentScript)}
-\`\`\`
-
-${getQuickStartWorkflowNote(packageManager, templateId, {
-        compoundPersistenceEnabled,
-    })}
-
-## Build and Verify
-
-\`\`\`bash
-${formatRunScript(packageManager, "build")}
-${formatRunScript(packageManager, "typecheck")}
-\`\`\`
-
-## Advanced Sync
-
-\`\`\`bash
-${optionalOnboardingSteps.join("\n")}
-\`\`\`
-
-${getOptionalOnboardingNote(packageManager, templateId, {
-        compoundPersistenceEnabled,
-    })}
-
-## Before First Commit
-
-\`\`\`bash
-${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}` : ""}
-`;
-}
-export function buildGitignore() {
-    return `# Dependencies
-node_modules/
-.yarn/
-.pnp.*
-
-# Build
-build/
-dist/
-
-# Editor
-.vscode/
-.idea/
-
-# OS
-.DS_Store
-Thumbs.db
-
-# WordPress
-*.log
-.wp-env/
-`;
-}
-export function mergeTextLines(primaryContent, existingContent) {
-    const normalizedPrimary = primaryContent.replace(/\r\n/g, "\n").trimEnd();
-    const normalizedExisting = existingContent.replace(/\r\n/g, "\n").trimEnd();
-    const mergedLines = [];
-    const seen = new Set();
-    for (const line of [...normalizedPrimary.split("\n"), ...normalizedExisting.split("\n")]) {
-        if (line.length === 0 && mergedLines[mergedLines.length - 1] === "") {
-            continue;
-        }
-        if (line.length > 0 && seen.has(line)) {
-            continue;
-        }
-        if (line.length > 0) {
-            seen.add(line);
-        }
-        mergedLines.push(line);
-    }
-    return `${mergedLines.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
-}
 export async function writeStarterManifestFiles(targetDir, templateId, variables, artifacts) {
     const manifests = artifacts
         ? artifacts.map((artifact) => ({

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

@@ -0,0 +1,34 @@
+import type { PackageManagerId } from './package-managers.js';
+import type { ScaffoldTemplateVariables } from './scaffold.js';
+/**
+ * Builds the generated README markdown for one scaffolded project.
+ *
+ * @param templateId Scaffold template family or template identifier.
+ * @param variables Interpolated scaffold variables used in generated content.
+ * @param packageManager Package manager used to format install and script commands.
+ * @param options Optional README sections enabled by scaffold presets.
+ * @returns Markdown README content for the generated project root.
+ */
+export declare function buildReadme(templateId: string, variables: ScaffoldTemplateVariables, packageManager: PackageManagerId, { withMigrationUi, withTestPreset, withWpEnv, }?: {
+    withMigrationUi?: boolean;
+    withTestPreset?: boolean;
+    withWpEnv?: boolean;
+}): string;
+/**
+ * Build the default `.gitignore` contents for a scaffolded project.
+ *
+ * @returns A newline-terminated `.gitignore` string covering dependency, build, editor, OS, and WordPress artifacts.
+ */
+export declare function buildGitignore(): string;
+/**
+ * Merge generated and existing text files while keeping line order stable.
+ *
+ * Existing unique lines are appended after the primary content, duplicate
+ * non-empty lines are removed, and runs of more than two blank lines collapse
+ * to a single empty separator.
+ *
+ * @param primaryContent Newly generated text that should appear first.
+ * @param existingContent Existing file contents preserved after unique generated lines.
+ * @returns The merged text block with a trailing newline.
+ */
+export declare function mergeTextLines(primaryContent: string, existingContent: string): string;

package/dist/runtime/scaffold-documents.js

@@ -0,0 +1,143 @@
+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';
+/**
+ * Builds the generated README markdown for one scaffolded project.
+ *
+ * @param templateId Scaffold template family or template identifier.
+ * @param variables Interpolated scaffold variables used in generated content.
+ * @param packageManager Package manager used to format install and script commands.
+ * @param options Optional README sections enabled by scaffold presets.
+ * @returns Markdown README content for the generated project root.
+ */
+export function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
+    const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
+        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+    });
+    const initialCommitCommands = getInitialCommitCommands();
+    const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
+        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === 'true',
+    });
+    const compoundPersistenceEnabled = variables.compoundPersistenceEnabled === 'true';
+    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 compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
+    const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
+        compoundPersistenceEnabled,
+        slug: variables.slug,
+    });
+    const developmentScript = getPrimaryDevelopmentScript(templateId);
+    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\`\`\``
+        : '';
+    const testPresetSection = withTestPreset
+        ? `## Local Test Preset\n\n\`\`\`bash\n${formatRunScript(packageManager, 'wp-env:start:test')}\n${formatRunScript(packageManager, 'wp-env:wait:test')}\n${formatRunScript(packageManager, 'test:e2e')}\n\`\`\`\n\nThe generated smoke test uses \`.wp-env.test.json\` and verifies that the scaffolded block registers in the WordPress editor.`
+        : '';
+    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,
+        })}`
+        : `## Artifact Refresh\n\n${getOptionalOnboardingNote(packageManager, templateId, {
+            compoundPersistenceEnabled,
+        })}`;
+    return `# ${variables.title}
+
+${variables.description}
+
+## Template
+
+${templateId}
+
+## Quick Start
+
+\`\`\`bash
+${formatInstallCommand(packageManager)}
+${formatRunScript(packageManager, developmentScript)}
+\`\`\`
+
+${getQuickStartWorkflowNote(packageManager, templateId, {
+        compoundPersistenceEnabled,
+    })}
+
+## Build and Verify
+
+\`\`\`bash
+${formatRunScript(packageManager, 'build')}
+${formatRunScript(packageManager, 'typecheck')}
+\`\`\`
+
+${advancedSyncSection}
+
+## Before First Commit
+
+\`\`\`bash
+${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}` : ''}
+`;
+}
+/**
+ * Build the default `.gitignore` contents for a scaffolded project.
+ *
+ * @returns A newline-terminated `.gitignore` string covering dependency, build, editor, OS, and WordPress artifacts.
+ */
+export function buildGitignore() {
+    return `# Dependencies
+node_modules/
+.yarn/
+.pnp.*
+
+# Build
+build/
+dist/
+
+# Editor
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# WordPress
+*.log
+.wp-env/
+`;
+}
+/**
+ * Merge generated and existing text files while keeping line order stable.
+ *
+ * Existing unique lines are appended after the primary content, duplicate
+ * non-empty lines are removed, and runs of more than two blank lines collapse
+ * to a single empty separator.
+ *
+ * @param primaryContent Newly generated text that should appear first.
+ * @param existingContent Existing file contents preserved after unique generated lines.
+ * @returns The merged text block with a trailing newline.
+ */
+export function mergeTextLines(primaryContent, existingContent) {
+    const normalizedPrimary = primaryContent.replace(/\r\n/g, '\n').trimEnd();
+    const normalizedExisting = existingContent.replace(/\r\n/g, '\n').trimEnd();
+    const mergedLines = [];
+    const seen = new Set();
+    for (const line of [...normalizedPrimary.split('\n'), ...normalizedExisting.split('\n')]) {
+        if (line.length === 0 && mergedLines[mergedLines.length - 1] === '') {
+            continue;
+        }
+        if (line.length > 0 && seen.has(line)) {
+            continue;
+        }
+        if (line.length > 0) {
+            seen.add(line);
+        }
+        mergedLines.push(line);
+    }
+    return `${mergedLines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}

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, "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\`.`;
+    }
     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 \`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.`;
+    }
     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) {

package/dist/runtime/scaffold-template-variables.d.ts

@@ -0,0 +1,9 @@
+import type { ScaffoldAnswers, ScaffoldTemplateVariables } from './scaffold.js';
+/**
+ * Build the normalized template variables used by scaffold rendering.
+ *
+ * @param templateId Selected scaffold template identifier.
+ * @param answers Normalized scaffold answers collected from defaults, flags, and prompts.
+ * @returns Template variables ready for file interpolation and generated artifacts.
+ */
+export declare function getTemplateVariables(templateId: string, answers: ScaffoldAnswers): ScaffoldTemplateVariables;