@wp-typia/project-tools 0.16.12 → 0.16.14

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, getOptionalOnboardingNote, getOptionalOnboardingSteps, 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,108 +37,6 @@ export async function ensureDirectory(targetDir, allowExisting = false) {
         throw new Error(`Target directory is not empty: ${targetDir}`);
     }
 }
-export function buildReadme(templateId, variables, packageManager, { withMigrationUi = false, withTestPreset = false, withWpEnv = false, } = {}) {
-    const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
-        compoundPersistenceEnabled: variables.compoundPersistenceEnabled === "true",
-    });
-    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}
-
-## Development
-
-\`\`\`bash
-${formatInstallCommand(packageManager)}
-${formatRunScript(packageManager, developmentScript)}
-\`\`\`
-
-## Build
-
-\`\`\`bash
-${formatRunScript(packageManager, "build")}
-\`\`\`
-
-## Optional First Sync
-
-\`\`\`bash
-${optionalOnboardingSteps.join("\n")}
-\`\`\`
-
-${getOptionalOnboardingNote(packageManager, templateId, {
-        compoundPersistenceEnabled,
-    })}
-
-${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,144 @@
+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\`.`
+        : '';
+    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}` : ''}
+`;
+}
+/**
+ * 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.d.ts

@@ -14,10 +14,22 @@ export declare function getOptionalSyncScriptNames(templateId: string, options?:
  * Formats optional onboarding sync commands for the selected package manager.
  */
 export declare function getOptionalOnboardingSteps(packageManager: PackageManagerId, templateId: string, options?: SyncOnboardingOptions): string[];
+/**
+ * Returns the quick-start note explaining the scaffold's primary local loop.
+ */
+export declare function getQuickStartWorkflowNote(packageManager: PackageManagerId, templateId?: string, options?: SyncOnboardingOptions): string;
 /**
  * Returns the onboarding note explaining when manual sync is optional.
  */
 export declare function getOptionalOnboardingNote(packageManager: PackageManagerId, templateId?: string, options?: SyncOnboardingOptions): string;
+/**
+ * Returns the recommended version-control commands for a fresh scaffold.
+ */
+export declare function getInitialCommitCommands(): string[];
+/**
+ * Returns the version-control note shown after the initial scaffold.
+ */
+export declare function getInitialCommitNote(): string;
 /**
  * Returns source-of-truth guidance for generated artifacts by template mode.
  */

package/dist/runtime/scaffold-onboarding.js

@@ -1,6 +1,11 @@
 import { formatRunScript } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
+const INITIAL_COMMIT_COMMANDS = [
+    "git init",
+    "git add .",
+    'git commit -m "Initial scaffold"',
+];
 function templateHasPersistenceSync(templateId, { compoundPersistenceEnabled = false } = {}) {
     return templateId === "persistence" || (templateId === "compound" && compoundPersistenceEnabled);
 }
@@ -28,6 +33,24 @@ export function getOptionalSyncScriptNames(templateId, options = {}) {
 export function getOptionalOnboardingSteps(packageManager, templateId, options = {}) {
     return getOptionalSyncScriptNames(templateId, options).map((scriptName) => formatRunScript(packageManager, scriptName));
 }
+/**
+ * Returns the quick-start note explaining the scaffold's primary local loop.
+ */
+export function getQuickStartWorkflowNote(packageManager, templateId = "basic", options = {}) {
+    const developmentScript = getPrimaryDevelopmentScript(templateId);
+    const devCommand = formatRunScript(packageManager, developmentScript);
+    const startCommand = formatRunScript(packageManager, "start");
+    if (developmentScript === "start") {
+        return `${startCommand} is the primary local entry point for this template. If the template also exposes a dedicated watch mode or alternate editor workflow, follow that template-specific documentation alongside the generated project scripts.`;
+    }
+    if (developmentScript !== "dev") {
+        return `${devCommand} is the primary local entry point for this template. Use ${startCommand} when you want the scaffold's one-shot startup flow instead of the watch-oriented workflow.`;
+    }
+    if (templateHasPersistenceSync(templateId, options)) {
+        return `${devCommand} keeps the editor, type-derived artifacts, and REST-derived artifacts moving together during local development. Use ${startCommand} when you want a one-shot sync plus editor startup without the long-running watch loop.`;
+    }
+    return `${devCommand} keeps the editor and type-derived artifacts moving together during local development. Use ${startCommand} when you want a one-shot sync plus editor startup without the long-running watch loop.`;
+}
 /**
  * Returns the onboarding note explaining when manual sync is optional.
  */
@@ -46,18 +69,32 @@ export function getOptionalOnboardingNote(packageManager, templateId = "basic",
     const advancedPersistenceNote = templateHasPersistenceSync(templateId, options)
         ? ` ${syncRestCommand} remains available for advanced REST-only refreshes, but it now fails fast when type-derived artifacts are stale; run \`${syncCommand}\` or \`${syncTypesCommand}\` first.`
         : "";
+    const isCustomTemplate = !isBuiltInTemplateId(templateId) &&
+        templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE;
     const fallbackCustomTemplateNote = !hasUnifiedSync &&
         syncSteps.length > 0 &&
-        !isBuiltInTemplateId(templateId) &&
-        templateId !== OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        isCustomTemplate
         ? `Run ${syncSteps.join(" then ")} manually before build, typecheck, or commit. ${syncCheckCommand} verifies the current type-derived artifacts without rewriting them.${optionalSyncScripts.includes("sync-rest") ? ` ${syncRestCommand} remains available for REST-only refreshes after ${syncTypesCommand}.` : ""}`
         : null;
     if (fallbackCustomTemplateNote) {
         return fallbackCustomTemplateNote;
     }
-    return `${formatRunScript(packageManager, developmentScript)} ${developmentScript === "dev"
-        ? "watches the relevant sync scripts during local development."
-        : "remains the primary local entry point."} ${formatRunScript(packageManager, "start")} still runs one-shot syncs before starting, while ${formatRunScript(packageManager, "build")} and ${typecheckCommand} verify that generated metadata/schema artifacts are already current through ${syncCheckCommand}. Run ${syncCommand} manually when you want to refresh generated artifacts before build, typecheck, or commit. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` to fail only on lossy WordPress projections, or \`${strictSyncCommand}\` for a CI-friendly JSON report that fails on all warnings.${advancedPersistenceNote} They do not create migration history.`;
+    if (isCustomTemplate && syncSteps.length === 0) {
+        return "No optional sync command was detected for this custom template. Follow the template's own artifact-refresh guidance before build, typecheck, or your first commit.";
+    }
+    return `You usually do not need to run ${syncCommand} during a normal ${formatRunScript(packageManager, developmentScript)} session. Run ${syncCommand} manually when you want a reviewable artifact refresh before ${formatRunScript(packageManager, "build")}, ${typecheckCommand}, or your first commit. ${syncTypesCommand} stays warn-only by default; use \`${failOnLossySyncCommand}\` to fail only on lossy WordPress projections, or \`${strictSyncCommand}\` for the stricter CI-oriented report.${advancedPersistenceNote} They do not create migration history. If this directory is new, create your first Git commit after that refresh.`;
+}
+/**
+ * Returns the recommended version-control commands for a fresh scaffold.
+ */
+export function getInitialCommitCommands() {
+    return [...INITIAL_COMMIT_COMMANDS];
+}
+/**
+ * Returns the version-control note shown after the initial scaffold.
+ */
+export function getInitialCommitNote() {
+    return "Skip `git init` if this directory already lives inside an existing repository. If you want generated artifacts refreshed before the first checkpoint, run your manual sync step first and then create the commit.";
 }
 /**
  * Returns source-of-truth guidance for generated artifacts by template mode.

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;

package/dist/runtime/scaffold-template-variables.js

@@ -0,0 +1,111 @@
+import { buildTemplateVariablesFromBlockSpec, createBuiltInBlockSpec, } from './block-generator-service.js';
+import { getPackageVersions } from './package-versions.js';
+import { buildBlockCssClassName, buildFrontendCssClassName, resolveScaffoldIdentifiers, } from './scaffold-identifiers.js';
+import { BUILTIN_BLOCK_METADATA_VERSION, COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS, getBuiltInTemplateMetadataDefaults, } from './template-defaults.js';
+import { getTemplateById, isBuiltInTemplateId, } from './template-registry.js';
+import { toPascalCase, toSnakeCase, } from './string-case.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 function getTemplateVariables(templateId, answers) {
+    if (isBuiltInTemplateId(templateId)) {
+        return buildTemplateVariablesFromBlockSpec(createBuiltInBlockSpec({
+            answers,
+            dataStorageMode: answers.dataStorageMode,
+            persistencePolicy: answers.persistencePolicy,
+            templateId,
+        }));
+    }
+    const { apiClientPackageVersion, blockRuntimePackageVersion, blockTypesPackageVersion, projectToolsPackageVersion, restPackageVersion, } = getPackageVersions();
+    const template = isBuiltInTemplateId(templateId) ? getTemplateById(templateId) : null;
+    const metadataDefaults = isBuiltInTemplateId(templateId)
+        ? getBuiltInTemplateMetadataDefaults(templateId)
+        : null;
+    const identifiers = resolveScaffoldIdentifiers({
+        namespace: answers.namespace,
+        phpPrefix: answers.phpPrefix,
+        slug: answers.slug,
+        textDomain: answers.textDomain,
+    });
+    const slug = identifiers.slug;
+    const slugSnakeCase = toSnakeCase(slug);
+    const pascalCase = toPascalCase(slug);
+    const title = answers.title.trim();
+    const namespace = identifiers.namespace;
+    const description = answers.description.trim();
+    const textDomain = identifiers.textDomain;
+    const phpPrefix = identifiers.phpPrefix;
+    const phpPrefixUpper = phpPrefix.toUpperCase();
+    const compoundChildTitle = `${title} Item`;
+    const cssClassName = buildBlockCssClassName(namespace, slug);
+    const compoundChildCssClassName = buildBlockCssClassName(namespace, `${slug}-item`);
+    const compoundPersistenceEnabled = templateId === 'persistence'
+        ? true
+        : templateId === 'compound'
+            ? Boolean(answers.dataStorageMode || answers.persistencePolicy)
+            : false;
+    const dataStorageMode = templateId === 'persistence' || compoundPersistenceEnabled
+        ? answers.dataStorageMode ?? 'custom-table'
+        : 'custom-table';
+    const persistencePolicy = templateId === 'persistence' || compoundPersistenceEnabled
+        ? answers.persistencePolicy ?? 'authenticated'
+        : 'authenticated';
+    return {
+        apiClientPackageVersion,
+        author: answers.author.trim(),
+        blockRuntimePackageVersion,
+        blockMetadataVersion: BUILTIN_BLOCK_METADATA_VERSION,
+        blockTypesPackageVersion,
+        category: metadataDefaults?.category ?? template?.defaultCategory ?? 'widgets',
+        icon: metadataDefaults?.icon ?? 'smiley',
+        compoundChildTitle,
+        compoundChildCategory: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.category,
+        compoundChildCssClassName,
+        compoundChildIcon: COMPOUND_CHILD_BLOCK_METADATA_DEFAULTS.icon,
+        compoundChildTitleJson: JSON.stringify(compoundChildTitle),
+        compoundPersistenceEnabled: compoundPersistenceEnabled ? 'true' : 'false',
+        projectToolsPackageVersion,
+        cssClassName,
+        dataStorageMode,
+        dashCase: slug,
+        description,
+        frontendCssClassName: buildFrontendCssClassName(cssClassName),
+        isAuthenticatedPersistencePolicy: persistencePolicy === 'authenticated' ? 'true' : 'false',
+        isPublicPersistencePolicy: persistencePolicy === 'public' ? 'true' : 'false',
+        bootstrapCredentialDeclarations: persistencePolicy === 'public'
+            ? "publicWriteExpiresAt?: number & tags.Type< 'uint32' >;\n\tpublicWriteToken?: string & tags.MinLength< 1 > & tags.MaxLength< 512 >;"
+            : "restNonce?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        persistencePolicyDescriptionJson: JSON.stringify(persistencePolicy === 'authenticated'
+            ? 'Writes require a logged-in user and a valid REST nonce.'
+            : 'Anonymous writes use signed short-lived public tokens, per-request ids, and coarse rate limiting.'),
+        keyword: slug.replace(/-/g, ' '),
+        namespace,
+        needsMigration: '{{needsMigration}}',
+        pascalCase,
+        phpPrefix,
+        phpPrefixUpper,
+        restPackageVersion,
+        publicWriteRequestIdDeclaration: persistencePolicy === 'public'
+            ? "publicWriteRequestId: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;"
+            : "publicWriteRequestId?: string & tags.MinLength< 1 > & tags.MaxLength< 128 >;",
+        restWriteAuthIntent: persistencePolicy === 'public'
+            ? 'public-write-protected'
+            : 'authenticated',
+        restWriteAuthMechanism: persistencePolicy === 'public' ? 'public-signed-token' : 'rest-nonce',
+        restWriteAuthMode: persistencePolicy === 'public' ? 'public-signed-token' : 'authenticated-rest-nonce',
+        slug,
+        slugCamelCase: pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1),
+        slugKebabCase: slug,
+        slugSnakeCase,
+        textDomain,
+        textdomain: textDomain,
+        title,
+        titleJson: JSON.stringify(title),
+        titleCase: pascalCase,
+        persistencePolicy,
+    };
+}

package/dist/runtime/scaffold.d.ts

@@ -81,19 +81,25 @@ export interface ScaffoldTemplateVariables extends Record<string, string> {
  * can surface custom ids. Downstream code uses `isBuiltInTemplateId()` to
  * distinguish built-in templates from custom sources.
  */
-interface ResolveTemplateOptions {
+export interface ResolveTemplateOptions {
     isInteractive?: boolean;
     selectTemplate?: () => Promise<string>;
     templateId?: string;
     yes?: boolean;
 }
-interface ResolvePackageManagerOptions {
+/**
+ * Options for resolving the package manager in CLI and interactive scaffold flows.
+ */
+export interface ResolvePackageManagerOptions {
     isInteractive?: boolean;
     packageManager?: string;
     selectPackageManager?: () => Promise<PackageManagerId>;
     yes?: boolean;
 }
-interface CollectScaffoldAnswersOptions {
+/**
+ * Options for collecting scaffold answers from defaults, overrides, and prompts.
+ */
+export interface CollectScaffoldAnswersOptions {
     dataStorageMode?: DataStorageMode;
     namespace?: string;
     phpPrefix?: string;
@@ -139,12 +145,8 @@ export interface ScaffoldProjectResult {
     warnings: string[];
 }
 export { buildBlockCssClassName } from "./scaffold-identifiers.js";
+export { collectScaffoldAnswers, detectAuthor, getDefaultAnswers, resolvePackageManagerId, resolveTemplateId, } from "./scaffold-answer-resolution.js";
+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 detectAuthor(): string;
-export declare function getDefaultAnswers(projectName: string, templateId: string): ScaffoldAnswers;
-export declare function resolveTemplateId({ templateId, yes, isInteractive, selectTemplate, }: ResolveTemplateOptions): Promise<string>;
-export declare function resolvePackageManagerId({ packageManager, yes, isInteractive, selectPackageManager, }: ResolvePackageManagerOptions): Promise<PackageManagerId>;
-export declare function collectScaffoldAnswers({ projectName, templateId, yes, dataStorageMode, namespace, persistencePolicy, phpPrefix, promptText, textDomain, }: CollectScaffoldAnswersOptions): Promise<ScaffoldAnswers>;
-export declare function getTemplateVariables(templateId: string, answers: ScaffoldAnswers): ScaffoldTemplateVariables;
 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>;