@wp-typia/project-tools 0.24.3 → 0.24.5

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

@@ -0,0 +1,283 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { applyGeneratedProjectDxPackageJson, applyLocalDevPresetFiles, } from "./local-dev-presets.js";
+import { applyMigrationUiCapability } from "../migration/migration-ui-capability.js";
+import { syncPersistenceRestArtifacts, } from "../add/persistence-rest-artifacts.js";
+import { buildGitignore, buildReadme, mergeTextLines, } from "./scaffold-documents.js";
+import { getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
+import { formatNonEmptyTargetDirectoryError, } from "./scaffold-bootstrap.js";
+import { stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
+import { PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
+import { copyInterpolatedDirectory } from "./template-render.js";
+import { formatInstallCommand, transformPackageManagerText, } from "../shared/package-managers.js";
+import { pathExists, readOptionalUtf8File, } from "../shared/fs-async.js";
+import { normalizePackageJson } from "./scaffold-package-manager-files.js";
+export { applyWorkspaceMigrationCapability, isOfficialWorkspaceProject, } from "./scaffold-bootstrap.js";
+import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
+import { isCompoundPersistenceEnabled } from "./scaffold-template-variable-groups.js";
+export { buildGitignore, buildReadme, mergeTextLines } from "./scaffold-documents.js";
+async function reportScaffoldProgress(onProgress, event) {
+    await onProgress?.(event);
+}
+const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
+const LOCKFILES = {
+    bun: ["bun.lock", "bun.lockb"],
+    npm: ["package-lock.json"],
+    pnpm: ["pnpm-lock.yaml"],
+    yarn: ["yarn.lock"],
+};
+export async function ensureDirectory(targetDir, allowExisting = false) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    if (allowExisting) {
+        return;
+    }
+    const entries = await fsp.readdir(targetDir);
+    if (entries.length > 0) {
+        throw new Error(formatNonEmptyTargetDirectoryError(targetDir));
+    }
+}
+export async function writeStarterManifestFiles(targetDir, templateId, variables, artifacts) {
+    const manifests = artifacts
+        ? artifacts.map((artifact) => ({
+            document: artifact.manifestDocument,
+            relativePath: `${artifact.relativeDir}/typia.manifest.json`,
+        }))
+        : 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");
+    }
+}
+async function writeBuiltInStructuralArtifacts(targetDir, artifacts) {
+    for (const artifact of artifacts) {
+        const destinationDir = path.join(targetDir, artifact.relativeDir);
+        await fsp.mkdir(destinationDir, { recursive: true });
+        await fsp.writeFile(path.join(destinationDir, "types.ts"), artifact.typesSource, "utf8");
+        await fsp.writeFile(path.join(destinationDir, "block.json"), stringifyBuiltInBlockJsonDocument(artifact.blockJsonDocument), "utf8");
+    }
+}
+async function writeBuiltInCodeArtifacts(targetDir, codeArtifacts) {
+    for (const artifact of codeArtifacts) {
+        const destinationPath = path.join(targetDir, artifact.relativePath);
+        await fsp.mkdir(path.dirname(destinationPath), { recursive: true });
+        await fsp.writeFile(destinationPath, artifact.source, "utf8");
+    }
+}
+async 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 (await pathExists(path.join(candidate, "typia", "package.json"))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function withEphemeralScaffoldNodeModules(targetDir, callback) {
+    const targetNodeModulesPath = path.join(targetDir, "node_modules");
+    if (await pathExists(targetNodeModulesPath)) {
+        await callback();
+        return;
+    }
+    const sourceNodeModulesPath = await 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 });
+    }
+}
+/**
+ * Seed REST-derived persistence artifacts into a newly scaffolded built-in
+ * project before the first manual `sync-rest` run.
+ */
+export async function seedBuiltInPersistenceArtifacts(targetDir, templateId, variables) {
+    const needsPersistenceArtifacts = templateId === "persistence" ||
+        (templateId === "compound" && isCompoundPersistenceEnabled(variables));
+    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,
+        });
+    });
+}
+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 });
+}
+export async function removeQueryLoopPlaceholderFiles(projectDir, templateId) {
+    if (templateId !== "query-loop") {
+        return;
+    }
+    await fsp.rm(path.join(projectDir, "src", "validator-toolkit.ts"), {
+        force: true,
+    });
+}
+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 });
+    }));
+}
+/**
+ * Recursively normalizes generated text files for the selected package manager
+ * and repository reference.
+ */
+export async function replaceTextRecursively(targetDir, packageManagerId, { repositoryManifestPaths, repositoryReference, } = {}) {
+    const textExtensions = new Set([
+        ".css",
+        ".js",
+        ".json",
+        ".jsx",
+        ".md",
+        ".php",
+        ".scss",
+        ".ts",
+        ".tsx",
+        ".txt",
+    ]);
+    const resolvedRepositoryReference = repositoryReference ??
+        resolveScaffoldRepositoryReference({
+            manifestPaths: repositoryManifestPaths,
+        });
+    async function visit(currentPath) {
+        const stats = await fsp.stat(currentPath);
+        if (stats.isDirectory()) {
+            const entries = await fsp.readdir(currentPath);
+            for (const entry of entries) {
+                await visit(path.join(currentPath, entry));
+            }
+            return;
+        }
+        if (path.basename(currentPath) === "package.json" || !textExtensions.has(path.extname(currentPath))) {
+            return;
+        }
+        const content = await fsp.readFile(currentPath, "utf8");
+        const nextContent = replaceRepositoryReferencePlaceholders(transformPackageManagerText(content, packageManagerId), resolvedRepositoryReference);
+        if (nextContent !== content) {
+            await fsp.writeFile(currentPath, nextContent, "utf8");
+        }
+    }
+    await visit(targetDir);
+}
+export async function defaultInstallDependencies({ projectDir, packageManager, }) {
+    execSync(formatInstallCommand(packageManager), {
+        cwd: projectDir,
+        stdio: "inherit",
+    });
+}
+/**
+ * Applies a built-in scaffold into the target directory, including generated
+ * code artifacts, starter manifests, preset files, and placeholder rewrites.
+ */
+export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir, templateId, variables, artifacts, codeArtifacts, readmeContent, gitignoreContent, allowExistingDir = false, packageManager, withMigrationUi = false, withTestPreset = false, withWpEnv = false, noInstall = false, installDependencies, repositoryReference, onProgress, }) {
+    await ensureDirectory(projectDir, allowExistingDir);
+    await reportScaffoldProgress(onProgress, {
+        detail: "Copying built-in template files and writing generated source modules.",
+        phase: "generate-files",
+        title: "Generating project files",
+    });
+    await copyInterpolatedDirectory(templateDir, projectDir, variables);
+    if (codeArtifacts && codeArtifacts.length > 0) {
+        await writeBuiltInCodeArtifacts(projectDir, codeArtifacts);
+    }
+    if (artifacts && artifacts.length > 0) {
+        await writeBuiltInStructuralArtifacts(projectDir, artifacts);
+    }
+    await reportScaffoldProgress(onProgress, {
+        detail: "Writing starter manifests, local presets, and seeded template artifacts.",
+        phase: "seed-artifacts",
+        title: "Seeding scaffold artifacts",
+    });
+    await writeStarterManifestFiles(projectDir, templateId, variables, artifacts);
+    await seedBuiltInPersistenceArtifacts(projectDir, templateId, variables);
+    await applyLocalDevPresetFiles({
+        projectDir,
+        variables,
+        withTestPreset,
+        withWpEnv,
+    });
+    if (withMigrationUi) {
+        await applyMigrationUiCapability({
+            packageManager,
+            projectDir,
+            templateId,
+            variables,
+        });
+    }
+    await reportScaffoldProgress(onProgress, {
+        detail: "Writing README, normalizing package metadata, and aligning package-manager files.",
+        phase: "finalize-project",
+        title: "Finalizing scaffold output",
+    });
+    const readmePath = path.join(projectDir, "README.md");
+    if (!(await pathExists(readmePath))) {
+        await fsp.writeFile(readmePath, readmeContent ??
+            buildReadme(templateId, variables, packageManager, {
+                withMigrationUi,
+                withTestPreset,
+                withWpEnv,
+            }), "utf8");
+    }
+    const gitignorePath = path.join(projectDir, ".gitignore");
+    const existingGitignore = await readOptionalUtf8File(gitignorePath) ?? "";
+    await fsp.writeFile(gitignorePath, mergeTextLines(gitignoreContent ?? buildGitignore(), existingGitignore), "utf8");
+    await normalizePackageJson(projectDir, packageManager);
+    await applyGeneratedProjectDxPackageJson({
+        compoundPersistenceEnabled: isCompoundPersistenceEnabled(variables),
+        packageManager,
+        projectDir,
+        templateId,
+        withTestPreset,
+        withWpEnv,
+    });
+    await removeQueryLoopPlaceholderFiles(projectDir, templateId);
+    await normalizePackageManagerFiles(projectDir, packageManager);
+    await removeUnexpectedLockfiles(projectDir, packageManager);
+    await replaceTextRecursively(projectDir, packageManager, {
+        repositoryReference,
+    });
+    if (!noInstall) {
+        await reportScaffoldProgress(onProgress, {
+            detail: "Installing project dependencies with the selected package manager.",
+            phase: "install-dependencies",
+            title: "Installing dependencies",
+        });
+        const installer = installDependencies ?? defaultInstallDependencies;
+        await installer({
+            projectDir,
+            packageManager,
+        });
+    }
+}

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

@@ -0,0 +1,60 @@
+import type { PackageManagerId } from "../shared/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>;
+/**
+ * Format the actionable error message used when a scaffold target directory
+ * already exists and is not empty.
+ *
+ * @param targetDir Absolute path to the target directory being evaluated.
+ * @returns A human-readable error string with next-step guidance.
+ */
+export declare function formatNonEmptyTargetDirectoryError(targetDir: string): string;
+/**
+ * Writes built-in starter manifest files into a scaffolded project.
+ *
+ * @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 declares the workspace project model.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies a workspace scaffold.
+ */
+export declare function isWorkspaceProject(projectDir: string): boolean;
+/**
+ * Detects whether a scaffolded project is the official workspace template.
+ *
+ * @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/templates/scaffold-bootstrap.js

@@ -0,0 +1,214 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { formatPackageExecCommand } from "../shared/package-managers.js";
+import { ensureMigrationDirectories, writeInitialMigrationScaffold, writeMigrationConfig, } from "../migration/migration-project.js";
+import { syncPersistenceRestArtifacts } from "../add/persistence-rest-artifacts.js";
+import { getPackageVersions } from "../shared/package-versions.js";
+import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
+import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
+import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+import { pathExists } from "../shared/fs-async.js";
+import { readJsonFile, readJsonFileSync } from "../shared/json-utils.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) {
+    await fsp.mkdir(targetDir, { recursive: true });
+    if (allowExisting) {
+        return;
+    }
+    const entries = await fsp.readdir(targetDir);
+    if (entries.length > 0) {
+        throw new Error(formatNonEmptyTargetDirectoryError(targetDir));
+    }
+}
+function readGeneratedPackageJson(projectDir) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return null;
+    }
+    return readJsonFileSync(packageJsonPath, {
+        context: "generated package manifest",
+    });
+}
+/**
+ * Format the actionable error message used when a scaffold target directory
+ * already exists and is not empty.
+ *
+ * @param targetDir Absolute path to the target directory being evaluated.
+ * @returns A human-readable error string with next-step guidance.
+ */
+export function formatNonEmptyTargetDirectoryError(targetDir) {
+    return `Target directory is not empty: ${targetDir}. Choose a new project directory, or empty this directory before rerunning the scaffold.`;
+}
+/**
+ * Writes built-in starter manifest files into a scaffolded project.
+ *
+ * @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 compoundGroup = getScaffoldTemplateVariableGroups(variables).compound;
+    const needsPersistenceArtifacts = templateId === "persistence" ||
+        (templateId === "compound" &&
+            compoundGroup.enabled &&
+            compoundGroup.persistenceEnabled);
+    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 declares the workspace project model.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies a workspace scaffold.
+ */
+export function isWorkspaceProject(projectDir) {
+    return readGeneratedPackageJson(projectDir)?.wpTypia?.projectType === "workspace";
+}
+/**
+ * Detects whether a scaffolded project is the official workspace template.
+ *
+ * @param projectDir Absolute scaffold target directory.
+ * @returns `true` when the project metadata identifies the official workspace template.
+ */
+export function isOfficialWorkspaceProject(projectDir) {
+    const packageJson = readGeneratedPackageJson(projectDir);
+    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 = await readJsonFile(packageJsonPath, {
+        context: "workspace package manifest",
+    });
+    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`.
+ */
+async 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 (await pathExists(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 (await pathExists(targetNodeModulesPath)) {
+        await callback();
+        return;
+    }
+    const sourceNodeModulesPath = await 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/templates/scaffold-compatibility.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { type AiFeatureCapabilitySelection, type AiFeatureCompatibilityFloor, type ResolvedAiFeatureCapabilityPlan } from '../add/ai-feature-capability.js';
+/**
+ * WordPress plugin header version floors emitted by scaffold templates.
+ */
+export interface ScaffoldPluginHeaderCompatibility {
+    requiresAtLeast: string;
+    requiresPhp: string;
+    testedUpTo: string;
+}
+/**
+ * Resolved compatibility policy for a set of scaffold feature capabilities.
+ */
+export interface ScaffoldCompatibilityPolicy {
+    capabilityPlan: ResolvedAiFeatureCapabilityPlan;
+    pluginHeader: ScaffoldPluginHeaderCompatibility;
+}
+/**
+ * Serializable compatibility metadata stored in generated workspace inventory.
+ */
+export interface ScaffoldCompatibilityConfig {
+    hardMinimums: AiFeatureCompatibilityFloor;
+    mode: 'baseline' | 'optional' | 'required';
+    optionalFeatureIds: string[];
+    optionalFeatures: string[];
+    requiredFeatureIds: string[];
+    requiredFeatures: string[];
+    runtimeGates: string[];
+}
+/**
+ * Optional hooks for surfacing user-authored compatibility header repairs.
+ */
+export interface UpdatePluginHeaderCompatibilityOptions {
+    /**
+     * Receives warnings when a malformed existing plugin header value is
+     * replaced by the resolved policy floor.
+     */
+    onWarning?: (warning: string) => void;
+}
+/**
+ * Baseline headers used by scaffold output before optional features are added.
+ */
+export declare const DEFAULT_SCAFFOLD_COMPATIBILITY: ScaffoldPluginHeaderCompatibility;
+/**
+ * Optional WordPress AI Client surface used by server-only AI feature scaffold.
+ */
+export declare const OPTIONAL_WORDPRESS_AI_CLIENT_COMPATIBILITY: readonly AiFeatureCapabilitySelection[];
+/**
+ * Required Abilities API surface used by typed workflow ability scaffold.
+ */
+export declare const REQUIRED_WORKSPACE_ABILITY_COMPATIBILITY: readonly AiFeatureCapabilitySelection[];
+/**
+ * Resolve plugin header floors and capability gates for scaffold selections.
+ */
+export declare function resolveScaffoldCompatibilityPolicy(selections: readonly AiFeatureCapabilitySelection[], { baseline, }?: {
+    baseline?: ScaffoldPluginHeaderCompatibility;
+}): ScaffoldCompatibilityPolicy;
+/**
+ * Convert a resolved policy into workspace-inventory-safe JSON metadata.
+ */
+export declare function createScaffoldCompatibilityConfig(policy: ScaffoldCompatibilityPolicy): ScaffoldCompatibilityConfig;
+/**
+ * Render compatibility metadata as formatted TypeScript object literal JSON.
+ */
+export declare function renderScaffoldCompatibilityConfig(policy: ScaffoldCompatibilityPolicy, indent?: string): string;
+/**
+ * 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 declare function updatePluginHeaderCompatibility(source: string, policy: ScaffoldCompatibilityPolicy, options?: UpdatePluginHeaderCompatibilityOptions): string;