@wp-typia/project-tools 0.16.11 → 0.16.13

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

@@ -8,6 +8,15 @@ export interface InstallDependenciesOptions {
     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;

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

@@ -8,7 +8,7 @@ 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 { getCompoundExtensionWorkflowSection, getInitialCommitCommands, getInitialCommitNote, getOptionalOnboardingNote, getOptionalOnboardingSteps, getQuickStartWorkflowNote, getPhpRestExtensionPointsSection, getTemplateSourceOfTruthNote, } from "./scaffold-onboarding.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";
@@ -36,10 +36,20 @@ 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",
     });
@@ -70,20 +80,25 @@ ${variables.description}
 
 ${templateId}
 
-## Development
+## Quick Start
 
 \`\`\`bash
 ${formatInstallCommand(packageManager)}
 ${formatRunScript(packageManager, developmentScript)}
 \`\`\`
 
-## Build
+${getQuickStartWorkflowNote(packageManager, templateId, {
+        compoundPersistenceEnabled,
+    })}
+
+## Build and Verify
 
 \`\`\`bash
 ${formatRunScript(packageManager, "build")}
+${formatRunScript(packageManager, "typecheck")}
 \`\`\`
 
-## Optional First Sync
+## Advanced Sync
 
 \`\`\`bash
 ${optionalOnboardingSteps.join("\n")}
@@ -93,6 +108,14 @@ ${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}` : ""}
 `;
 }

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

@@ -0,0 +1,45 @@
+import type { PackageManagerId } from "./package-managers.js";
+import type { ScaffoldTemplateVariables } from "./scaffold.js";
+import type { BuiltInTemplateId } from "./template-registry.js";
+/**
+ * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
+ *
+ * @param targetDir Absolute project directory that will receive scaffold output.
+ * @param allowExisting Whether an existing non-empty directory should be accepted.
+ * @returns A promise that resolves once the directory precondition is satisfied.
+ */
+export declare function ensureScaffoldDirectory(targetDir: string, allowExisting?: boolean): Promise<void>;
+/**
+ * Writes built-in starter manifest files into a scaffolded project.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param templateId Built-in template id being scaffolded.
+ * @param variables Resolved scaffold template variables.
+ * @returns A promise that resolves after all starter manifests are written.
+ */
+export declare function writeStarterManifestFiles(targetDir: string, templateId: string, variables: ScaffoldTemplateVariables): Promise<void>;
+/**
+ * Seed REST-derived persistence artifacts into a newly scaffolded built-in
+ * project before the first manual `sync-rest` run.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param templateId Built-in template id being scaffolded.
+ * @param variables Resolved scaffold template variables for the project.
+ * @returns A promise that resolves after any required persistence artifacts are generated.
+ */
+export declare function seedBuiltInPersistenceArtifacts(targetDir: string, templateId: BuiltInTemplateId, variables: ScaffoldTemplateVariables): Promise<void>;
+/**
+ * Detects whether a scaffolded project is the official workspace template.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies the official workspace template.
+ */
+export declare function isOfficialWorkspaceProject(projectDir: string): boolean;
+/**
+ * Adds migration scripts and starter workspace files to the official workspace template.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @param packageManager Package manager used for generated script commands.
+ * @returns A promise that resolves after scripts and migration starter files are written.
+ */
+export declare function applyWorkspaceMigrationCapability(projectDir: string, packageManager: PackageManagerId): Promise<void>;

package/dist/runtime/scaffold-bootstrap.js

@@ -0,0 +1,185 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatPackageExecCommand } from "./package-managers.js";
+import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "./migration-project.js";
+import { syncPersistenceRestArtifacts } from "./persistence-rest-artifacts.js";
+import { getPackageVersions } from "./package-versions.js";
+import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
+const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
+/**
+ * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
+ *
+ * @param targetDir Absolute project directory that will receive scaffold output.
+ * @param allowExisting Whether an existing non-empty directory should be accepted.
+ * @returns A promise that resolves once the directory precondition is satisfied.
+ */
+export async function ensureScaffoldDirectory(targetDir, allowExisting = false) {
+    if (!fs.existsSync(targetDir)) {
+        await fsp.mkdir(targetDir, { recursive: true });
+        return;
+    }
+    if (allowExisting) {
+        return;
+    }
+    const entries = await fsp.readdir(targetDir);
+    if (entries.length > 0) {
+        throw new Error(`Target directory is not empty: ${targetDir}`);
+    }
+}
+/**
+ * Writes built-in starter manifest files into a scaffolded project.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param templateId Built-in template id being scaffolded.
+ * @param variables Resolved scaffold template variables.
+ * @returns A promise that resolves after all starter manifests are written.
+ */
+export async function writeStarterManifestFiles(targetDir, templateId, variables) {
+    const manifests = getStarterManifestFiles(templateId, variables);
+    for (const { document, relativePath } of manifests) {
+        const destinationPath = path.join(targetDir, relativePath);
+        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+        await fsp.writeFile(destinationPath, stringifyStarterManifest(document), "utf8");
+    }
+}
+/**
+ * Seed REST-derived persistence artifacts into a newly scaffolded built-in
+ * project before the first manual `sync-rest` run.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param templateId Built-in template id being scaffolded.
+ * @param variables Resolved scaffold template variables for the project.
+ * @returns A promise that resolves after any required persistence artifacts are generated.
+ */
+export async function seedBuiltInPersistenceArtifacts(targetDir, templateId, variables) {
+    const needsPersistenceArtifacts = templateId === "persistence" ||
+        (templateId === "compound" && variables.compoundPersistenceEnabled === "true");
+    if (!needsPersistenceArtifacts) {
+        return;
+    }
+    await withEphemeralScaffoldNodeModules(targetDir, async () => {
+        if (templateId === "persistence") {
+            await syncPersistenceRestArtifacts({
+                apiTypesFile: path.join("src", "api-types.ts"),
+                outputDir: "src",
+                projectDir: targetDir,
+                variables,
+            });
+            return;
+        }
+        await syncPersistenceRestArtifacts({
+            apiTypesFile: path.join("src", "blocks", variables.slugKebabCase, "api-types.ts"),
+            outputDir: path.join("src", "blocks", variables.slugKebabCase),
+            projectDir: targetDir,
+            variables,
+        });
+    });
+}
+/**
+ * Detects whether a scaffolded project is the official workspace template.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies the official workspace template.
+ */
+export function isOfficialWorkspaceProject(projectDir) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return (packageJson.wpTypia?.projectType === "workspace" &&
+        packageJson.wpTypia?.templatePackage === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE);
+}
+/**
+ * Adds migration scripts and starter workspace files to the official workspace template.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @param packageManager Package manager used for generated script commands.
+ * @returns A promise that resolves after scripts and migration starter files are written.
+ */
+export async function applyWorkspaceMigrationCapability(projectDir, packageManager) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    const wpTypiaPackageVersion = getPackageVersions().wpTypiaPackageVersion;
+    const canonicalCliSpecifier = wpTypiaPackageVersion === "^0.0.0"
+        ? "wp-typia"
+        : `wp-typia@${wpTypiaPackageVersion.replace(/^[~^]/u, "")}`;
+    const migrationCli = (args) => formatPackageExecCommand(packageManager, canonicalCliSpecifier, `migrate ${args}`);
+    packageJson.scripts = {
+        ...(packageJson.scripts ?? {}),
+        "migration:init": migrationCli("init --current-migration-version v1"),
+        "migration:snapshot": migrationCli("snapshot"),
+        "migration:diff": migrationCli("diff"),
+        "migration:scaffold": migrationCli("scaffold"),
+        "migration:doctor": migrationCli("doctor --all"),
+        "migration:fixtures": migrationCli("fixtures --all"),
+        "migration:verify": migrationCli("verify --all"),
+        "migration:fuzz": migrationCli("fuzz --all"),
+    };
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+    writeMigrationConfig(projectDir, {
+        blocks: [],
+        currentMigrationVersion: "v1",
+        snapshotDir: "src/migrations/versions",
+        supportedMigrationVersions: ["v1"],
+    });
+    ensureMigrationDirectories(projectDir, []);
+    writeInitialMigrationScaffold(projectDir, "v1", []);
+}
+/**
+ * Locate a node_modules directory containing `typia` relative to the project
+ * tools package root.
+ *
+ * Search order:
+ * 1. `PROJECT_TOOLS_PACKAGE_ROOT/node_modules`
+ * 2. The monorepo root resolved from `PROJECT_TOOLS_PACKAGE_ROOT`
+ * 3. The monorepo root `node_modules`
+ *
+ * @returns The first matching path, or `null` when no candidate contains `typia`.
+ */
+function resolveScaffoldGeneratorNodeModulesPath() {
+    const candidates = [
+        path.join(PROJECT_TOOLS_PACKAGE_ROOT, "node_modules"),
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", ".."),
+        path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "..", "node_modules"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(candidate, "typia", "package.json"))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Temporarily symlink a scaffold generator node_modules directory into the
+ * target project while running an async callback.
+ *
+ * The helper resolves the source path via `resolveScaffoldGeneratorNodeModulesPath()`
+ * and uses `EPHEMERAL_NODE_MODULES_LINK_TYPE` for the symlink. The temporary
+ * link is removed in the `finally` block so cleanup still happens if the
+ * callback throws.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param callback Async work that requires a resolvable `node_modules`.
+ * @returns A promise that resolves after the callback and cleanup complete.
+ */
+async function withEphemeralScaffoldNodeModules(targetDir, callback) {
+    const targetNodeModulesPath = path.join(targetDir, "node_modules");
+    if (fs.existsSync(targetNodeModulesPath)) {
+        await callback();
+        return;
+    }
+    const sourceNodeModulesPath = resolveScaffoldGeneratorNodeModulesPath();
+    if (!sourceNodeModulesPath) {
+        throw new Error("Unable to resolve a node_modules directory with typia for scaffold-time REST artifact generation.");
+    }
+    await fsp.symlink(sourceNodeModulesPath, targetNodeModulesPath, EPHEMERAL_NODE_MODULES_LINK_TYPE);
+    try {
+        await callback();
+    }
+    finally {
+        await fsp.rm(targetNodeModulesPath, { force: true, recursive: true });
+    }
+}

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-package-manager-files.d.ts

@@ -0,0 +1,35 @@
+import type { PackageManagerId } from "./package-managers.js";
+/**
+ * Normalizes scaffolded package-manager specific files for the selected toolchain.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after any package-manager sidecar files are updated.
+ */
+export declare function normalizePackageManagerFiles(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
+/**
+ * Rewrites the generated package.json for the selected package manager.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after the package.json file is normalized.
+ */
+export declare function normalizePackageJson(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
+/**
+ * Removes lockfiles that do not match the selected package manager.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after stale lockfiles are removed.
+ */
+export declare function removeUnexpectedLockfiles(targetDir: string, packageManagerId: PackageManagerId): Promise<void>;
+/**
+ * Installs scaffolded project dependencies with the selected package manager.
+ *
+ * @param options Absolute target directory and selected package manager id.
+ * @returns A promise that resolves after the install command completes.
+ */
+export declare function defaultInstallDependencies({ projectDir, packageManager, }: {
+    projectDir: string;
+    packageManager: PackageManagerId;
+}): Promise<void>;

package/dist/runtime/scaffold-package-manager-files.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import { execSync } from "node:child_process";
+import path from "node:path";
+import { formatInstallCommand, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+const LOCKFILES = {
+    bun: ["bun.lock", "bun.lockb"],
+    npm: ["package-lock.json"],
+    pnpm: ["pnpm-lock.yaml"],
+    yarn: ["yarn.lock"],
+};
+/**
+ * Normalizes scaffolded package-manager specific files for the selected toolchain.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after any package-manager sidecar files are updated.
+ */
+export async function normalizePackageManagerFiles(targetDir, packageManagerId) {
+    const yarnRcPath = path.join(targetDir, ".yarnrc.yml");
+    if (packageManagerId === "yarn") {
+        await fsp.writeFile(yarnRcPath, "nodeLinker: node-modules\n", "utf8");
+        return;
+    }
+    await fsp.rm(yarnRcPath, { force: true });
+}
+/**
+ * Rewrites the generated package.json for the selected package manager.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after the package.json file is normalized.
+ */
+export async function normalizePackageJson(targetDir, packageManagerId) {
+    const packageJsonPath = path.join(targetDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return;
+    }
+    const packageManager = getPackageManager(packageManagerId);
+    const packageJson = JSON.parse(await fsp.readFile(packageJsonPath, "utf8"));
+    packageJson.packageManager = packageManager.packageManagerField;
+    if (packageJson.scripts) {
+        for (const [key, value] of Object.entries(packageJson.scripts)) {
+            if (typeof value === "string") {
+                packageJson.scripts[key] = transformPackageManagerText(value, packageManagerId);
+            }
+        }
+    }
+    await fsp.writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "\t")}\n`, "utf8");
+}
+/**
+ * Removes lockfiles that do not match the selected package manager.
+ *
+ * @param targetDir Absolute scaffold target directory.
+ * @param packageManagerId Selected package manager id.
+ * @returns A promise that resolves after stale lockfiles are removed.
+ */
+export async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
+    const keep = new Set(LOCKFILES[packageManagerId] ?? []);
+    const allLockfiles = Object.values(LOCKFILES).flat();
+    await Promise.all(allLockfiles.map(async (filename) => {
+        if (keep.has(filename)) {
+            return;
+        }
+        await fsp.rm(path.join(targetDir, filename), { force: true });
+    }));
+}
+/**
+ * Installs scaffolded project dependencies with the selected package manager.
+ *
+ * @param options Absolute target directory and selected package manager id.
+ * @returns A promise that resolves after the install command completes.
+ */
+export async function defaultInstallDependencies({ projectDir, packageManager, }) {
+    execSync(formatInstallCommand(packageManager), {
+        cwd: projectDir,
+        stdio: "inherit",
+    });
+}

package/dist/runtime/scaffold.d.ts

@@ -138,17 +138,7 @@ export interface ScaffoldProjectResult {
     variables: ScaffoldTemplateVariables;
     warnings: 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 { buildBlockCssClassName } from "./scaffold-identifiers.js";
 export declare function isDataStorageMode(value: string): value is DataStorageMode;
 export declare function isPersistencePolicy(value: string): value is PersistencePolicy;
 export declare function detectAuthor(): string;
@@ -158,4 +148,3 @@ export declare function resolvePackageManagerId({ packageManager, yes, isInterac
 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>;
-export {};