@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/templates/scaffold-compatibility.js

@@ -0,0 +1,159 @@
+/**
+ * Compatibility policy helpers for generated scaffold outputs.
+ *
+ * The policy keeps plugin headers, runtime gates, and workspace inventory
+ * metadata aligned when optional or required AI-capable features are added.
+ */
+import { AI_FEATURE_DEFINITIONS, resolveAiFeatureCapabilityPlan, } from '../add/ai-feature-capability.js';
+import { parseVersionFloorParts, pickHigherVersionFloor, } from '../shared/version-floor.js';
+/**
+ * Baseline headers used by scaffold output before optional features are added.
+ */
+export const DEFAULT_SCAFFOLD_COMPATIBILITY = {
+    requiresAtLeast: '6.7',
+    requiresPhp: '8.0',
+    testedUpTo: '6.9',
+};
+/**
+ * Optional WordPress AI Client surface used by server-only AI feature scaffold.
+ */
+export const OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY = [
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressAiClient.id,
+        mode: 'optional',
+    },
+];
+/**
+ * Required Abilities API surface used by typed workflow ability scaffold.
+ */
+export const REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY = [
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressServerAbilities.id,
+        mode: 'required',
+    },
+    {
+        featureId: AI_FEATURE_DEFINITIONS.wordpressCoreAbilities.id,
+        mode: 'required',
+    },
+];
+function pickHigherScaffoldVersionFloor(current, candidate) {
+    return pickHigherVersionFloor(current, candidate) ?? current;
+}
+function pickHigherHeaderVersionFloor(policyValue, currentValue, { headerName, onWarning, }) {
+    const normalizedCurrentValue = currentValue.trim();
+    if (!normalizedCurrentValue) {
+        return policyValue;
+    }
+    try {
+        return pickHigherScaffoldVersionFloor(policyValue, normalizedCurrentValue);
+    }
+    catch (error) {
+        const warning = [
+            `Invalid plugin header version floor for ${headerName}: "${normalizedCurrentValue}".`,
+            'Expected dotted numeric segments such as "6.7" or "8.1.2".',
+            `Replacing it with compatibility policy value "${policyValue}".`,
+        ].join(' ');
+        if (!onWarning) {
+            throw new Error(warning, { cause: error });
+        }
+        onWarning(warning);
+        return policyValue;
+    }
+}
+function assertPolicyVersionFloor(headerName, value) {
+    try {
+        parseVersionFloorParts(value);
+    }
+    catch (error) {
+        throw new Error([
+            `Invalid scaffold compatibility policy floor for ${headerName}: "${value}".`,
+            'Expected dotted numeric segments such as "6.7" or "8.1.2".',
+        ].join(' '), { cause: error });
+    }
+}
+function assertPluginHeaderPolicyVersionFloors(pluginHeader) {
+    assertPolicyVersionFloor('Requires at least', pluginHeader.requiresAtLeast);
+    assertPolicyVersionFloor('Tested up to', pluginHeader.testedUpTo);
+    assertPolicyVersionFloor('Requires PHP', pluginHeader.requiresPhp);
+}
+function formatRuntimeGate(feature) {
+    return (feature.runtimeGates ?? []).map((gate) => `${feature.label}: ${gate.kind} ${gate.value}`);
+}
+function getPolicyMode(capabilityPlan) {
+    if (capabilityPlan.requiredFeatures.length > 0) {
+        return 'required';
+    }
+    if (capabilityPlan.optionalFeatures.length > 0) {
+        return 'optional';
+    }
+    return 'baseline';
+}
+/**
+ * Resolve plugin header floors and capability gates for scaffold selections.
+ */
+export function resolveScaffoldCompatibilityPolicy(selections, { baseline = DEFAULT_SCAFFOLD_COMPATIBILITY, } = {}) {
+    const capabilityPlan = resolveAiFeatureCapabilityPlan(selections);
+    const requiresAtLeast = pickHigherScaffoldVersionFloor(baseline.requiresAtLeast, capabilityPlan.hardMinimums.wordpress);
+    const requiresPhp = pickHigherScaffoldVersionFloor(baseline.requiresPhp, capabilityPlan.hardMinimums.php);
+    const testedUpTo = pickHigherScaffoldVersionFloor(baseline.testedUpTo, requiresAtLeast);
+    return {
+        capabilityPlan,
+        pluginHeader: {
+            requiresAtLeast,
+            requiresPhp,
+            testedUpTo,
+        },
+    };
+}
+/**
+ * Convert a resolved policy into workspace-inventory-safe JSON metadata.
+ */
+export function createScaffoldCompatibilityConfig(policy) {
+    const { capabilityPlan } = policy;
+    return {
+        hardMinimums: capabilityPlan.hardMinimums,
+        mode: getPolicyMode(capabilityPlan),
+        optionalFeatureIds: capabilityPlan.optionalFeatures.map((feature) => feature.id),
+        optionalFeatures: capabilityPlan.optionalFeatures.map((feature) => feature.label),
+        requiredFeatureIds: capabilityPlan.requiredFeatures.map((feature) => feature.id),
+        requiredFeatures: capabilityPlan.requiredFeatures.map((feature) => feature.label),
+        runtimeGates: [
+            ...capabilityPlan.requiredFeatures.flatMap(formatRuntimeGate),
+            ...capabilityPlan.optionalFeatures.flatMap(formatRuntimeGate),
+        ],
+    };
+}
+/**
+ * Render compatibility metadata as formatted TypeScript object literal JSON.
+ */
+export function renderScaffoldCompatibilityConfig(policy, indent = '\t\t') {
+    const config = createScaffoldCompatibilityConfig(policy);
+    return JSON.stringify(config, null, '\t')
+        .split('\n')
+        .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+        .join('\n');
+}
+function replacePluginHeaderVersionFloor(source, pattern, policyValue, headerName, options) {
+    return source.replace(pattern, (_match, prefix, currentValue, lineEnding) => {
+        const versionPrefix = prefix.endsWith(':') ? `${prefix} ` : prefix;
+        return `${versionPrefix}${pickHigherHeaderVersionFloor(policyValue, currentValue, {
+            headerName,
+            onWarning: options.onWarning,
+        })}${lineEnding}`;
+    });
+}
+/**
+ * Patch a generated plugin bootstrap header without lowering custom floors.
+ *
+ * Preserves the original header line endings while replacing empty version
+ * strings with policy values. Malformed user-authored values are reported
+ * through `options.onWarning`; without a warning handler they throw instead of
+ * falling back silently.
+ */
+export function updatePluginHeaderCompatibility(source, policy, options = {}) {
+    const { pluginHeader } = policy;
+    assertPluginHeaderPolicyVersionFloors(pluginHeader);
+    const nextSource = replacePluginHeaderVersionFloor(source, /(\* Requires at least:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresAtLeast, 'Requires at least', options);
+    const nextSourceWithTestedUpTo = replacePluginHeaderVersionFloor(nextSource, /(\* Tested up to:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.testedUpTo, 'Tested up to', options);
+    return replacePluginHeaderVersionFloor(nextSourceWithTestedUpTo, /(\* Requires PHP:[^\S\r\n]*)([^\r\n]*)(\r?)/u, pluginHeader.requiresPhp, 'Requires PHP', options);
+}

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

@@ -0,0 +1,34 @@
+import type { PackageManagerId } from '../shared/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/templates/scaffold-documents.js

@@ -0,0 +1,197 @@
+import { getPrimaryDevelopmentScript } from './local-dev-presets.js';
+import { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getInitialCommitNote, getOptionalOnboardingNote, getOptionalOnboardingSteps, getQuickStartWorkflowNote, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from './scaffold-onboarding.js';
+import { formatPackageExecCommand, formatInstallCommand, formatRunScript, } from '../shared/package-managers.js';
+import { getPackageVersions } from '../shared/package-versions.js';
+import { getScaffoldTemplateVariableGroups } from './scaffold-template-variable-groups.js';
+import { OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, normalizeTemplateLookupId, } from './template-registry.js';
+function formatReadmeTemplateIdentity(templateId) {
+    const normalizedTemplateId = normalizeTemplateLookupId(templateId);
+    if (normalizedTemplateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        return [
+            `- Alias: ${OFFICIAL_WORKSPACE_TEMPLATE_ALIAS}`,
+            `- Package: ${OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE}`,
+            '- Type: official workspace scaffold',
+        ].join('\n');
+    }
+    if (normalizedTemplateId === 'query-loop') {
+        return ['- Family: query-loop', '- Type: create-time core/query variation scaffold'].join('\n');
+    }
+    if (isBuiltInTemplateId(normalizedTemplateId)) {
+        return [`- Family: ${normalizedTemplateId}`, '- Type: built-in block scaffold'].join('\n');
+    }
+    return [`- Template id: ${templateId}`, '- Type: custom or external scaffold'].join('\n');
+}
+function getPackageManagerInstallGuidance(packageManager) {
+    if (packageManager !== 'npm') {
+        return '';
+    }
+    const installCommand = formatInstallCommand(packageManager);
+    return [
+        '',
+        `> npm note: the scaffold uses \`${installCommand}\` for the first install so npm does not spend the initial create flow in the audit resolver. Run \`npm audit\` separately when you want npm vulnerability output.`,
+        '> If npm prints React peer dependency noise from WordPress block-editor packages, validate with `npm run typecheck` and `npm run build` before changing WordPress package ranges.',
+    ].join('\n');
+}
+/**
+ * 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 variableGroups = getScaffoldTemplateVariableGroups(variables);
+    const compoundPersistenceEnabled = variableGroups.compound.enabled &&
+        variableGroups.compound.persistenceEnabled;
+    const optionalOnboardingSteps = getOptionalOnboardingSteps(packageManager, templateId, {
+        compoundPersistenceEnabled,
+    });
+    const initialCommitCommands = getInitialCommitCommands();
+    const sourceOfTruthNote = getTemplateSourceOfTruthNote(templateId, {
+        compoundPersistenceEnabled,
+    });
+    const publicPersistencePolicyNote = variableGroups.persistence.enabled && variableGroups.persistence.auth.isPublic
+        ? 'Public persistence writes use signed short-lived tokens, per-request ids, and coarse rate limiting by default. Add application-specific abuse controls before using the same pattern for high-value metrics or experiments.'
+        : null;
+    const alternateRenderTargetSection = variableGroups.alternateRenderTargets.enabled
+        ? `## Alternate Render Targets\n\nThis scaffold keeps \`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render.php` : 'src/render.php'}\` as the default web render boundary and also generates ${[
+            variableGroups.alternateRenderTargets.hasEmail
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-email.php` : 'src/render-email.php'}\``
+                : null,
+            variableGroups.alternateRenderTargets.hasMjml
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-mjml.php` : 'src/render-mjml.php'}\``
+                : null,
+            variableGroups.alternateRenderTargets.hasPlainText
+                ? `\`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-text.php` : 'src/render-text.php'}\``
+                : null,
+        ]
+            .filter((value) => Boolean(value))
+            .join(', ')}. All of those entries delegate through \`${templateId === 'compound' ? `src/blocks/${variables.slugKebabCase}/render-targets.php` : 'src/render-targets.php'}\`, so attribute normalization, validation, and render-target adapter hooks stay aligned across web, email, MJML, and plain-text integrations.`
+        : '';
+    const compoundExtensionWorkflowSection = getCompoundExtensionWorkflowSection(packageManager, templateId);
+    const compoundInnerBlocksSection = templateId === 'compound'
+        ? `## Compound InnerBlocks Presets\n\nThis scaffold starts with the \`${variables.compoundInnerBlocksPreset}\` preset for compound container authoring. Static nested relationships still belong in each generated \`block.json\` via \`allowedBlocks\`, \`parent\`, and \`ancestor\`, while \`src/blocks/${variables.slugKebabCase}/children.ts\` owns editor-only \`InnerBlocks\` behavior such as \`orientation\`, \`templateLock\`, \`defaultBlock\`, and \`directInsert\`.\n\n- \`freeform\`: unlocked inserter flow with the starter child template.\n- \`ordered\`: vertical ordered flow with \`templateLock="insert"\` and direct inserts.\n- \`horizontal\`: row-like nested authoring with direct inserts.\n- \`locked-structure\`: fully locked starter structure.\n\nWhen you need to change that authoring behavior later, update the preset helpers in \`src/blocks/${variables.slugKebabCase}/children.ts\` and keep fixed child constraints metadata-owned instead of duplicating them in editor props. If you need tighter wrapper ownership or sibling markup control, switch the generated edit components to \`useInnerBlocksProps\` and reuse \`getRootInnerBlocksPropsOptions()\` / \`getChildInnerBlocksPropsOptions( metadata.name )\` so the same preset behavior carries forward without rebuilding the option set by hand.`
+        : '';
+    const phpRestExtensionPointsSection = getPhpRestExtensionPointsSection(templateId, {
+        compoundPersistenceEnabled,
+        slug: variables.slug,
+    });
+    const developmentScript = getPrimaryDevelopmentScript(templateId);
+    const noStepsHeading = templateId === 'query-loop' ? 'Variation Workflow' : 'Artifact Refresh';
+    const wpEnvSection = withWpEnv
+        ? `## Local WordPress\n\n\`\`\`bash\n${formatRunScript(packageManager, 'wp-env:start')}\n${formatRunScript(packageManager, 'wp-env:stop')}\n${formatRunScript(packageManager, 'wp-env:reset')}\n\`\`\``
+        : '';
+    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,
+        })}`
+        : `## ${noStepsHeading}\n\n${getOptionalOnboardingNote(packageManager, templateId, {
+            compoundPersistenceEnabled,
+        })}`;
+    return `# ${variables.title}
+
+${variables.description}
+
+## Template
+
+${formatReadmeTemplateIdentity(templateId)}
+
+## Quick Start
+
+\`\`\`bash
+${formatInstallCommand(packageManager)}
+${formatRunScript(packageManager, developmentScript)}
+\`\`\`
+${getPackageManagerInstallGuidance(packageManager)}
+
+${getQuickStartWorkflowNote(packageManager, templateId, {
+        compoundPersistenceEnabled,
+    })}
+
+## Build and Verify
+
+\`\`\`bash
+${formatRunScript(packageManager, 'build')}
+${formatRunScript(packageManager, 'typecheck')}
+${formatPackageExecCommand(packageManager, `wp-typia@${getPackageVersions().wpTypiaPackageExactVersion}`, 'doctor')}
+\`\`\`
+
+${advancedSyncSection}
+
+## Before First Commit
+
+\`\`\`bash
+${initialCommitCommands.join('\n')}
+\`\`\`
+
+${getInitialCommitNote()}
+
+${sourceOfTruthNote}${publicPersistencePolicyNote ? `\n\n${publicPersistencePolicyNote}` : ''}${alternateRenderTargetSection ? `\n\n${alternateRenderTargetSection}` : ''}${compoundInnerBlocksSection ? `\n\n${compoundInnerBlocksSection}` : ''}${migrationSection ? `\n\n${migrationSection}` : ''}${compoundExtensionWorkflowSection ? `\n\n${compoundExtensionWorkflowSection}` : ''}${wpEnvSection ? `\n\n${wpEnvSection}` : ''}${testPresetSection ? `\n\n${testPresetSection}` : ''}${phpRestExtensionPointsSection ? `\n\n${phpRestExtensionPointsSection}` : ''}
+`;
+}
+/**
+ * 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/templates/scaffold-identifiers.d.ts

@@ -0,0 +1,51 @@
+export interface ResolvedScaffoldIdentifiers {
+    namespace: string;
+    phpPrefix: string;
+    slug: string;
+    textDomain: string;
+}
+export declare function validateBlockSlug(input: string): true | string;
+export declare function validateNamespace(input: string): true | string;
+export declare function validateTextDomain(input: string): true | string;
+export declare function validatePhpPrefix(input: string): true | string;
+export declare function assertValidIdentifier(label: string, value: string, validate: (value: string) => true | string): string;
+export declare function normalizeBlockSlug(input: string): string;
+/**
+ * Normalize one human-entered block slug and reject values that collapse to an
+ * empty generated slug.
+ *
+ * @param options Normalization context for one block-like name.
+ * @param options.input Raw user input before kebab-case normalization.
+ * @param options.label Human-readable field label used in thrown errors.
+ * @param options.usage Example CLI usage shown when the input is blank.
+ * @returns A non-empty normalized slug.
+ * @throws When the input is blank after trimming.
+ * @throws When normalization removes every character from the original input.
+ */
+export declare function resolveNonEmptyNormalizedBlockSlug(options: {
+    input: string;
+    label: string;
+    usage: string;
+}): string;
+export declare function resolveValidatedBlockSlug(value: string): string;
+export declare function resolveValidatedNamespace(value: string): string;
+export declare function resolveValidatedTextDomain(value: string): string;
+export declare function resolveValidatedPhpPrefix(value: string): string;
+/**
+ * Builds the generated WordPress wrapper CSS class for a scaffolded block.
+ *
+ * Returns `wp-block-{namespace}-{slug}` when a non-empty namespace is present,
+ * or `wp-block-{slug}` when the namespace is empty or undefined. When the
+ * normalized namespace equals the normalized slug, appends `-block` so the
+ * generated class avoids repeated namespace segments without colliding with the
+ * default core wrapper classes. Both inputs are normalized and validated with
+ * the same scaffold identifier rules used for block names.
+ */
+export declare function buildBlockCssClassName(namespace: string | undefined, slug: string): string;
+export declare function buildFrontendCssClassName(blockCssClassName: string): string;
+export declare function resolveScaffoldIdentifiers({ namespace, phpPrefix, slug, textDomain, }: {
+    namespace: string;
+    phpPrefix?: string;
+    slug: string;
+    textDomain?: string;
+}): ResolvedScaffoldIdentifiers;

package/dist/runtime/templates/scaffold-identifiers.js

@@ -0,0 +1,105 @@
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "../cli/cli-diagnostics.js";
+import { toKebabCase, toSnakeCase, } from "../shared/string-case.js";
+const BLOCK_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+const PHP_PREFIX_PATTERN = /^[a-z_][a-z0-9_]*$/;
+const PHP_PREFIX_MAX_LENGTH = 50;
+export function validateBlockSlug(input) {
+    return BLOCK_SLUG_PATTERN.test(input) || "Use lowercase letters, numbers, and hyphens only";
+}
+export function validateNamespace(input) {
+    return BLOCK_SLUG_PATTERN.test(toKebabCase(input))
+        ? true
+        : "Use lowercase letters, numbers, and hyphens only";
+}
+export function validateTextDomain(input) {
+    return BLOCK_SLUG_PATTERN.test(toKebabCase(input))
+        ? true
+        : "Use lowercase letters, numbers, and hyphens only";
+}
+export function validatePhpPrefix(input) {
+    const normalizedPrefix = toSnakeCase(input);
+    if (normalizedPrefix.length > PHP_PREFIX_MAX_LENGTH) {
+        return `Use ${PHP_PREFIX_MAX_LENGTH} characters or fewer to keep generated database identifiers within MySQL limits`;
+    }
+    return PHP_PREFIX_PATTERN.test(normalizedPrefix)
+        ? true
+        : "Use letters, numbers, and underscores only, starting with a letter";
+}
+export function assertValidIdentifier(label, value, validate) {
+    const result = validate(value);
+    if (result !== true) {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, typeof result === "string" ? `${label}: ${result}` : `${label} is invalid`);
+    }
+    return value;
+}
+export function normalizeBlockSlug(input) {
+    return toKebabCase(input);
+}
+/**
+ * Normalize one human-entered block slug and reject values that collapse to an
+ * empty generated slug.
+ *
+ * @param options Normalization context for one block-like name.
+ * @param options.input Raw user input before kebab-case normalization.
+ * @param options.label Human-readable field label used in thrown errors.
+ * @param options.usage Example CLI usage shown when the input is blank.
+ * @returns A non-empty normalized slug.
+ * @throws When the input is blank after trimming.
+ * @throws When normalization removes every character from the original input.
+ */
+export function resolveNonEmptyNormalizedBlockSlug(options) {
+    const normalizedSlug = normalizeBlockSlug(options.input);
+    if (normalizedSlug.length > 0) {
+        return normalizedSlug;
+    }
+    if (options.input.trim().length === 0) {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `${options.label} is required. Use \`${options.usage}\`.`);
+    }
+    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `${options.label} "${options.input.trim()}" normalizes to an empty slug. Use letters or numbers so wp-typia can generate a block slug.`);
+}
+export function resolveValidatedBlockSlug(value) {
+    return assertValidIdentifier("Block slug", normalizeBlockSlug(value), validateBlockSlug);
+}
+export function resolveValidatedNamespace(value) {
+    return assertValidIdentifier("Namespace", toKebabCase(value), validateNamespace);
+}
+export function resolveValidatedTextDomain(value) {
+    return assertValidIdentifier("Text domain", toKebabCase(value), validateTextDomain);
+}
+export function resolveValidatedPhpPrefix(value) {
+    return assertValidIdentifier("PHP prefix", toSnakeCase(value), validatePhpPrefix);
+}
+/**
+ * Builds the generated WordPress wrapper CSS class for a scaffolded block.
+ *
+ * Returns `wp-block-{namespace}-{slug}` when a non-empty namespace is present,
+ * or `wp-block-{slug}` when the namespace is empty or undefined. When the
+ * normalized namespace equals the normalized slug, appends `-block` so the
+ * generated class avoids repeated namespace segments without colliding with the
+ * default core wrapper classes. Both inputs are normalized and validated with
+ * the same scaffold identifier rules used for block names.
+ */
+export function buildBlockCssClassName(namespace, slug) {
+    const normalizedSlug = resolveValidatedBlockSlug(slug);
+    const normalizedNamespace = typeof namespace === "string" && namespace.trim().length > 0
+        ? resolveValidatedNamespace(namespace)
+        : "";
+    if (normalizedNamespace === normalizedSlug) {
+        return `wp-block-${normalizedSlug}-block`;
+    }
+    return normalizedNamespace.length > 0
+        ? `wp-block-${normalizedNamespace}-${normalizedSlug}`
+        : `wp-block-${normalizedSlug}`;
+}
+export function buildFrontendCssClassName(blockCssClassName) {
+    return `${blockCssClassName}-frontend`;
+}
+export function resolveScaffoldIdentifiers({ namespace, phpPrefix, slug, textDomain, }) {
+    const normalizedSlug = resolveValidatedBlockSlug(slug);
+    return {
+        namespace: resolveValidatedNamespace(namespace),
+        phpPrefix: resolveValidatedPhpPrefix(phpPrefix ?? normalizedSlug),
+        slug: normalizedSlug,
+        textDomain: resolveValidatedTextDomain(textDomain ?? normalizedSlug),
+    };
+}

package/dist/runtime/templates/scaffold-onboarding.d.ts

@@ -0,0 +1,49 @@
+import type { PackageManagerId } from "../shared/package-managers.js";
+interface SyncOnboardingOptions {
+    availableScripts?: string[];
+    compoundPersistenceEnabled?: boolean;
+}
+interface PhpRestExtensionOptions extends SyncOnboardingOptions {
+    slug: string;
+}
+/**
+ * Returns the optional sync script names to suggest for a template.
+ */
+export declare function getOptionalSyncScriptNames(templateId: string, options?: SyncOnboardingOptions): string[];
+/**
+ * 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 a shorter optional onboarding note suitable for create completion output.
+ */
+export declare function getOptionalOnboardingShortNote(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.
+ */
+export declare function getTemplateSourceOfTruthNote(templateId: string, { compoundPersistenceEnabled }?: SyncOnboardingOptions): string;
+/**
+ * Returns the generated-project extension workflow for compound child blocks.
+ */
+export declare function getCompoundExtensionWorkflowSection(packageManager: PackageManagerId, templateId: string): string | null;
+/**
+ * Returns scaffold-local guidance for the main PHP REST customization points.
+ */
+export declare function getPhpRestExtensionPointsSection(templateId: string, { compoundPersistenceEnabled, slug }: PhpRestExtensionOptions): string | null;
+export {};