@wp-typia/project-tools 0.16.11 → 0.16.12

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-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 {};