@wp-typia/project-tools 0.24.4 → 0.24.5

package/dist/runtime/cli/cli-init-apply.d.ts

@@ -0,0 +1,15 @@
+import { type RetrofitInitPlan } from "./cli-init-types.js";
+/**
+ * Apply the previewed retrofit init plan to disk.
+ *
+ * The command snapshots package.json and generated helper targets before
+ * writing, then rolls those files back automatically if any write fails.
+ *
+ * @param projectDir Project root that should receive the retrofit surface.
+ * @param options Optional package-manager override used for emitted scripts and
+ * follow-up guidance.
+ * @returns The applied retrofit init plan describing the persisted changes.
+ */
+export declare function applyInitPlan(projectDir: string, options?: {
+    packageManager?: string;
+}): Promise<RetrofitInitPlan>;

package/dist/runtime/cli/cli-init-apply.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
+import { rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "../add/cli-add-shared.js";
+import { buildNextProjectPackageJson, buildProjectPackageJsonSource, readProjectPackageJson, } from "./cli-init-package-json.js";
+import { createRetrofitPlan, getInitPlan } from "./cli-init-plan.js";
+import { buildRetrofitHelperFiles } from "./cli-init-templates.js";
+import { RETROFIT_APPLY_PREVIEW_NOTE, RETROFIT_ROLLBACK_NOTE, } from "./cli-init-types.js";
+async function createRetrofitMutationSnapshot(projectDir, filePaths) {
+    const scriptsDir = path.join(projectDir, "scripts");
+    const scriptsDirExisted = fs.existsSync(scriptsDir);
+    const fileSources = await snapshotWorkspaceFiles(filePaths);
+    const targetPaths = fileSources
+        .filter((entry) => entry.source === null)
+        .map((entry) => entry.filePath);
+    if (!scriptsDirExisted) {
+        targetPaths.push(scriptsDir);
+    }
+    return {
+        fileSources,
+        snapshotDirs: [],
+        targetPaths,
+    };
+}
+async function writeRetrofitFiles(options) {
+    const helperFiles = buildRetrofitHelperFiles(options.blockTargets);
+    const scriptsDir = path.join(options.projectDir, "scripts");
+    await fsp.mkdir(scriptsDir, { recursive: true });
+    await fsp.writeFile(path.join(options.projectDir, "package.json"), buildProjectPackageJsonSource(options.packageJson), "utf8");
+    for (const [relativePath, source] of Object.entries(helperFiles)) {
+        await fsp.writeFile(path.join(options.projectDir, relativePath), source, "utf8");
+    }
+}
+function buildApplyFailureError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Unable to apply the retrofit init plan safely. The command restored the previous package.json/helper-file snapshot. ${message}`, error instanceof Error ? { cause: error } : undefined);
+}
+function toApplyNotes(previewNotes) {
+    return Array.from(new Set([
+        ...previewNotes.filter((note) => note !== "Preview only: `wp-typia init` does not write files yet." &&
+            note !== RETROFIT_APPLY_PREVIEW_NOTE),
+        RETROFIT_ROLLBACK_NOTE,
+    ]));
+}
+/**
+ * Apply the previewed retrofit init plan to disk.
+ *
+ * The command snapshots package.json and generated helper targets before
+ * writing, then rolls those files back automatically if any write fails.
+ *
+ * @param projectDir Project root that should receive the retrofit surface.
+ * @param options Optional package-manager override used for emitted scripts and
+ * follow-up guidance.
+ * @returns The applied retrofit init plan describing the persisted changes.
+ */
+export async function applyInitPlan(projectDir, options = {}) {
+    const previewPlan = getInitPlan(projectDir, options);
+    if (previewPlan.detectedLayout.kind === "unsupported") {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, "`wp-typia init --apply` requires a supported retrofit layout. Run `wp-typia init` first to inspect the preview plan and any blocking notes.");
+    }
+    if (previewPlan.status === "already-initialized") {
+        return createRetrofitPlan({
+            ...previewPlan,
+            commandMode: "apply",
+            notes: toApplyNotes(previewPlan.notes),
+            status: "already-initialized",
+        });
+    }
+    const nextPackageJson = buildNextProjectPackageJson({
+        packageChanges: previewPlan.packageChanges,
+        packageJson: readProjectPackageJson(previewPlan.projectDir),
+        packageManager: previewPlan.packageManager,
+        projectName: previewPlan.projectName,
+    });
+    const helperFiles = buildRetrofitHelperFiles(previewPlan.blockTargets);
+    const filePaths = [
+        path.join(previewPlan.projectDir, "package.json"),
+        ...Object.keys(helperFiles).map((relativePath) => path.join(previewPlan.projectDir, relativePath)),
+    ];
+    const mutationSnapshot = await createRetrofitMutationSnapshot(previewPlan.projectDir, filePaths);
+    try {
+        await writeRetrofitFiles({
+            blockTargets: previewPlan.blockTargets,
+            packageJson: nextPackageJson,
+            projectDir: previewPlan.projectDir,
+        });
+    }
+    catch (error) {
+        await rollbackWorkspaceMutation(mutationSnapshot);
+        throw buildApplyFailureError(error);
+    }
+    return createRetrofitPlan({
+        ...previewPlan,
+        commandMode: "apply",
+        notes: toApplyNotes(previewPlan.notes),
+        status: "applied",
+    });
+}

package/dist/runtime/cli/cli-init-package-json.d.ts

@@ -0,0 +1,19 @@
+import { type PackageManagerId } from "../shared/package-managers.js";
+import type { InitDependencyChange, InitPackageManagerFieldChange, InitScriptChange, ProjectPackageJson, RetrofitInitPlan } from "./cli-init-types.js";
+export declare function readProjectPackageJson(projectDir: string): ProjectPackageJson | null;
+export declare function resolveInitPackageManager(projectDir: string, packageJson: ProjectPackageJson | null, override?: string): PackageManagerId;
+export declare function getWpTypiaCliSpecifier(): string;
+export declare function buildDependencyChanges(packageJson: ProjectPackageJson | null): InitDependencyChange[];
+export declare function buildScriptChanges(packageJson: ProjectPackageJson | null, packageManager: PackageManagerId): InitScriptChange[];
+export declare function buildPackageManagerFieldChange(packageJson: ProjectPackageJson | null, packageManager: PackageManagerId, options?: {
+    persistExplicitOverride?: boolean;
+}): InitPackageManagerFieldChange | undefined;
+export declare function hasExistingWpTypiaProjectSurface(projectDir: string, packageJson: ProjectPackageJson | null): boolean;
+export declare function buildRequiredDevDependencyMapEntries(): string[];
+export declare function buildNextProjectPackageJson(options: {
+    packageChanges: RetrofitInitPlan["packageChanges"];
+    packageJson: ProjectPackageJson | null;
+    packageManager: PackageManagerId;
+    projectName: string;
+}): ProjectPackageJson;
+export declare function buildProjectPackageJsonSource(packageJson: ProjectPackageJson): string;

package/dist/runtime/cli/cli-init-package-json.js

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
+import { getPackageManager, transformPackageManagerText, } from "../shared/package-managers.js";
+import { getPackageVersions } from "../shared/package-versions.js";
+import { readJsonFileSync } from "../shared/json-utils.js";
+import { parseWorkspacePackageManagerId } from "../workspace/workspace-project.js";
+const BASE_RETROFIT_SCRIPTS = {
+    sync: "tsx scripts/sync-project.ts",
+    "sync-types": "tsx scripts/sync-types-to-block-json.ts",
+    typecheck: "bun run sync --check && tsc --noEmit",
+};
+const BASE_RETROFIT_DEV_DEPENDENCIES = [
+    "@typia/unplugin",
+    "@wp-typia/block-runtime",
+    "@wp-typia/block-types",
+    "tsx",
+    "typescript",
+    "typia",
+];
+export function readProjectPackageJson(projectDir) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return null;
+    }
+    try {
+        return readJsonFileSync(packageJsonPath, {
+            context: "project package manifest",
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Unable to parse ${packageJsonPath}: ${message}`, error instanceof Error ? { cause: error } : undefined);
+    }
+}
+function inferInitPackageManager(projectDir, packageJson) {
+    if (packageJson?.packageManager) {
+        return parseWorkspacePackageManagerId(packageJson.packageManager);
+    }
+    if (fs.existsSync(path.join(projectDir, "bun.lock")) ||
+        fs.existsSync(path.join(projectDir, "bun.lockb"))) {
+        return "bun";
+    }
+    if (fs.existsSync(path.join(projectDir, "pnpm-lock.yaml"))) {
+        return "pnpm";
+    }
+    if (fs.existsSync(path.join(projectDir, "yarn.lock")) ||
+        fs.existsSync(path.join(projectDir, ".yarnrc.yml"))) {
+        return "yarn";
+    }
+    return "npm";
+}
+export function resolveInitPackageManager(projectDir, packageJson, override) {
+    if (!override) {
+        return inferInitPackageManager(projectDir, packageJson);
+    }
+    if (override !== "bun" &&
+        override !== "npm" &&
+        override !== "pnpm" &&
+        override !== "yarn") {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Unknown package manager "${override}". Expected one of: bun, npm, pnpm, yarn.`);
+    }
+    return override;
+}
+export function getWpTypiaCliSpecifier() {
+    const versions = getPackageVersions();
+    return versions.wpTypiaPackageExactVersion === "0.0.0"
+        ? "wp-typia"
+        : `wp-typia@${versions.wpTypiaPackageExactVersion}`;
+}
+function buildRequiredDevDependencyMap() {
+    const versions = getPackageVersions();
+    return {
+        "@typia/unplugin": versions.typiaUnpluginPackageVersion,
+        "@wp-typia/block-runtime": versions.blockRuntimePackageVersion,
+        "@wp-typia/block-types": versions.blockTypesPackageVersion,
+        tsx: versions.tsxPackageVersion,
+        typescript: versions.typescriptPackageVersion,
+        typia: versions.typiaPackageVersion,
+    };
+}
+function getExistingDependencyVersion(packageJson, name) {
+    return packageJson?.devDependencies?.[name] ?? packageJson?.dependencies?.[name];
+}
+export function buildDependencyChanges(packageJson) {
+    const requiredDependencies = buildRequiredDevDependencyMap();
+    return BASE_RETROFIT_DEV_DEPENDENCIES.flatMap((name) => {
+        const requiredValue = requiredDependencies[name];
+        const currentValue = getExistingDependencyVersion(packageJson, name);
+        if (currentValue === requiredValue) {
+            return [];
+        }
+        return [
+            {
+                action: currentValue ? "update" : "add",
+                ...(currentValue ? { currentValue } : {}),
+                name,
+                requiredValue,
+            },
+        ];
+    });
+}
+export function buildScriptChanges(packageJson, packageManager) {
+    const scripts = packageJson?.scripts ?? {};
+    return Object.entries(BASE_RETROFIT_SCRIPTS).flatMap(([name, commandSource]) => {
+        const requiredValue = transformPackageManagerText(commandSource, packageManager);
+        const currentValue = scripts[name];
+        if (currentValue === requiredValue) {
+            return [];
+        }
+        return [
+            {
+                action: typeof currentValue === "string" ? "update" : "add",
+                ...(typeof currentValue === "string" ? { currentValue } : {}),
+                name,
+                requiredValue,
+            },
+        ];
+    });
+}
+export function buildPackageManagerFieldChange(packageJson, packageManager, options = {}) {
+    if (!options.persistExplicitOverride && packageManager === "npm") {
+        return undefined;
+    }
+    const requiredValue = getPackageManager(packageManager).packageManagerField;
+    const currentValue = packageJson?.packageManager;
+    if (currentValue === requiredValue) {
+        return undefined;
+    }
+    return {
+        action: typeof currentValue === "string" ? "update" : "add",
+        ...(typeof currentValue === "string" ? { currentValue } : {}),
+        requiredValue,
+    };
+}
+export function hasExistingWpTypiaProjectSurface(projectDir, packageJson) {
+    const scripts = packageJson?.scripts ?? {};
+    const hasSyncSurface = typeof scripts.sync === "string" || typeof scripts["sync-types"] === "string";
+    const hasHelperFiles = [
+        path.join("scripts", "block-config.ts"),
+        path.join("scripts", "sync-project.ts"),
+        path.join("scripts", "sync-types-to-block-json.ts"),
+    ].every((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
+    const hasRuntimeDeps = typeof getExistingDependencyVersion(packageJson, "@wp-typia/block-runtime") ===
+        "string" &&
+        typeof getExistingDependencyVersion(packageJson, "@wp-typia/block-types") ===
+            "string";
+    return hasSyncSurface && hasHelperFiles && hasRuntimeDeps;
+}
+export function buildRequiredDevDependencyMapEntries() {
+    return Object.entries(buildRequiredDevDependencyMap()).map(([name, version]) => `${name}@${version.replace(/^workspace:/u, "")}`);
+}
+function setDependencyVersion(packageJson, name, requiredValue) {
+    if (packageJson.devDependencies?.[name] !== undefined) {
+        packageJson.devDependencies[name] = requiredValue;
+        return;
+    }
+    if (packageJson.dependencies?.[name] !== undefined) {
+        packageJson.dependencies[name] = requiredValue;
+        return;
+    }
+    packageJson.devDependencies ?? (packageJson.devDependencies = {});
+    packageJson.devDependencies[name] = requiredValue;
+}
+export function buildNextProjectPackageJson(options) {
+    const nextPackageJson = options.packageJson
+        ? JSON.parse(JSON.stringify(options.packageJson))
+        : {
+            name: options.projectName,
+            private: true,
+        };
+    nextPackageJson.devDependencies ?? (nextPackageJson.devDependencies = {});
+    nextPackageJson.scripts ?? (nextPackageJson.scripts = {});
+    for (const dependencyChange of options.packageChanges.addDevDependencies) {
+        setDependencyVersion(nextPackageJson, dependencyChange.name, dependencyChange.requiredValue);
+    }
+    if (options.packageChanges.packageManagerField) {
+        nextPackageJson.packageManager =
+            options.packageChanges.packageManagerField.requiredValue;
+    }
+    else if (!nextPackageJson.packageManager &&
+        options.packageManager !== "npm") {
+        nextPackageJson.packageManager =
+            getPackageManager(options.packageManager).packageManagerField;
+    }
+    for (const scriptChange of options.packageChanges.scripts) {
+        nextPackageJson.scripts[scriptChange.name] = scriptChange.requiredValue;
+    }
+    return nextPackageJson;
+}
+export function buildProjectPackageJsonSource(packageJson) {
+    return `${JSON.stringify(packageJson, null, 2)}\n`;
+}

package/dist/runtime/cli/cli-init-plan-presentation.d.ts

@@ -0,0 +1,16 @@
+import { type PackageManagerId } from "../shared/package-managers.js";
+import type { InitCommandMode, InitPlanLayoutKind, InitPlanStatus, RetrofitInitPlan } from "./cli-init-types.js";
+export declare function buildInitPlanChangeSummary(changes: Pick<RetrofitInitPlan, "generatedArtifacts" | "packageChanges" | "plannedFiles">, options: {
+    includeGeneratedArtifacts: boolean;
+}): string[];
+export declare function buildInitPlanNextSteps(options: {
+    commandMode: InitCommandMode;
+    dependencyChangeCount: number;
+    hasPlannedChanges: boolean;
+    layoutKind: InitPlanLayoutKind;
+    packageManager: PackageManagerId;
+}): string[];
+export declare function buildRetrofitPlanSummary(options: {
+    commandMode: InitCommandMode;
+    status: InitPlanStatus;
+}): string;

package/dist/runtime/cli/cli-init-plan-presentation.js

@@ -0,0 +1,74 @@
+import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, } from "../shared/package-managers.js";
+import { buildRequiredDevDependencyMapEntries, getWpTypiaCliSpecifier, } from "./cli-init-package-json.js";
+export function buildInitPlanChangeSummary(changes, options) {
+    const lines = [];
+    for (const dependencyChange of changes.packageChanges.addDevDependencies) {
+        lines.push(`devDependency ${dependencyChange.action} ${dependencyChange.name} -> ${dependencyChange.requiredValue}`);
+    }
+    if (changes.packageChanges.packageManagerField) {
+        lines.push(`packageManager ${changes.packageChanges.packageManagerField.action} -> ${changes.packageChanges.packageManagerField.requiredValue}`);
+    }
+    for (const scriptChange of changes.packageChanges.scripts) {
+        lines.push(`script ${scriptChange.action} ${scriptChange.name} -> ${scriptChange.requiredValue}`);
+    }
+    for (const filePlan of changes.plannedFiles) {
+        lines.push(`file ${filePlan.action} ${filePlan.path} (${filePlan.purpose})`);
+    }
+    if (options.includeGeneratedArtifacts) {
+        for (const artifactPath of changes.generatedArtifacts) {
+            lines.push(`generated artifact ${artifactPath}`);
+        }
+    }
+    return lines;
+}
+export function buildInitPlanNextSteps(options) {
+    const cliSpecifier = getWpTypiaCliSpecifier();
+    const syncTypesRun = formatRunScript(options.packageManager, "sync-types");
+    const syncRun = formatRunScript(options.packageManager, "sync");
+    const doctorRun = formatPackageExecCommand(options.packageManager, cliSpecifier, "doctor");
+    const migrationInitRun = formatPackageExecCommand(options.packageManager, cliSpecifier, "migrate init --current-migration-version v1");
+    const dependencyInstallCommand = formatAddDevDependenciesCommand(options.packageManager, buildRequiredDevDependencyMapEntries());
+    if (options.layoutKind === "unsupported") {
+        return [
+            "Align the project to one of the supported retrofit layouts listed below, then rerun `wp-typia init`.",
+            dependencyInstallCommand,
+            syncTypesRun,
+            doctorRun,
+        ];
+    }
+    if (options.commandMode === "apply") {
+        return [
+            ...(options.dependencyChangeCount > 0
+                ? [
+                    "Install or reinstall project dependencies so the retrofit sync scripts and metadata generators are available locally.",
+                    dependencyInstallCommand,
+                ]
+                : []),
+            syncRun,
+            doctorRun,
+            `Optional migration bootstrap: ${migrationInitRun}`,
+        ];
+    }
+    return [
+        ...(options.hasPlannedChanges
+            ? [
+                "Re-run `wp-typia init --apply` to write the planned package.json changes and helper files automatically.",
+                ...(options.dependencyChangeCount > 0 ? [dependencyInstallCommand] : []),
+            ]
+            : []),
+        syncRun,
+        doctorRun,
+        `Optional migration bootstrap: ${migrationInitRun}`,
+    ];
+}
+export function buildRetrofitPlanSummary(options) {
+    if (options.status === "already-initialized") {
+        return options.commandMode === "apply"
+            ? "This project already exposes the minimum wp-typia retrofit surface. No files were changed."
+            : "This project already exposes the minimum wp-typia retrofit surface.";
+    }
+    if (options.commandMode === "apply") {
+        return "Applied the minimum wp-typia retrofit surface so package.json and helper scripts are ready for the next install and sync run.";
+    }
+    return "This command previews the minimum wp-typia adoption layer for the current project without rewriting it into a full scaffold.";
+}

package/dist/runtime/cli/cli-init-plan.d.ts

@@ -0,0 +1,39 @@
+import { type PackageManagerId } from "../shared/package-managers.js";
+import { type InitCommandMode, type InitFilePlan, type InitPlanLayoutKind, type InitPlanStatus, type RetrofitInitBlockTarget, type RetrofitInitPlan } from "./cli-init-types.js";
+export declare function buildInitLayoutDetails(projectDir: string): {
+    blockNames: string[];
+    blockTargets: RetrofitInitBlockTarget[];
+    description: string;
+    generatedArtifacts: string[];
+    kind: InitPlanLayoutKind;
+    notes: string[];
+};
+export declare function createRetrofitPlan(options: {
+    commandMode: InitCommandMode;
+    detectedLayout: {
+        blockNames: string[];
+        description: string;
+        kind: InitPlanLayoutKind;
+    };
+    blockTargets: RetrofitInitBlockTarget[];
+    generatedArtifacts: string[];
+    nextSteps?: string[];
+    notes: string[];
+    packageChanges: RetrofitInitPlan["packageChanges"];
+    packageManager: PackageManagerId;
+    plannedFiles: InitFilePlan[];
+    projectDir: string;
+    projectName: string;
+    status: InitPlanStatus;
+}): RetrofitInitPlan;
+/**
+ * Inspect one project directory and return the current retrofit init plan.
+ *
+ * @param projectDir Project root or nested path that should be analyzed.
+ * @param options Optional package-manager override used for emitted scripts and
+ * follow-up guidance.
+ * @returns The preview-only retrofit init plan for the resolved project.
+ */
+export declare function getInitPlan(projectDir: string, options?: {
+    packageManager?: string;
+}): RetrofitInitPlan;