@wp-typia/project-tools 0.22.5 → 0.22.7

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

@@ -0,0 +1,191 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
+import { getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { getPackageVersions } from "./package-versions.js";
+import { parseWorkspacePackageManagerId } from "./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;
+    }
+    const source = fs.readFileSync(packageJsonPath, "utf8");
+    try {
+        return JSON.parse(source);
+    }
+    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-init-plan-presentation.d.ts

@@ -0,0 +1,16 @@
+import { type PackageManagerId } from "./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-init-plan-presentation.js

@@ -0,0 +1,74 @@
+import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, } from "./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-init-plan.d.ts

@@ -0,0 +1,39 @@
+import { type PackageManagerId } from "./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;

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

@@ -0,0 +1,303 @@
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeSourceTypes } from "@wp-typia/block-runtime/metadata-parser";
+import ts from "typescript";
+import { discoverMigrationInitLayout } from "./migration-project.js";
+import { formatPackageExecCommand, formatRunScript } from "./package-managers.js";
+import { toPascalCase } from "./string-case.js";
+import { buildDependencyChanges, buildPackageManagerFieldChange, buildScriptChanges, getWpTypiaCliSpecifier, hasExistingWpTypiaProjectSurface, readProjectPackageJson, resolveInitPackageManager, } from "./cli-init-package-json.js";
+import { buildInitPlanChangeSummary, buildInitPlanNextSteps, buildRetrofitPlanSummary, } from "./cli-init-plan-presentation.js";
+import { RETROFIT_APPLY_PREVIEW_NOTE, SUPPORTED_RETROFIT_LAYOUT_NOTE, } from "./cli-init-types.js";
+import { tryResolveWorkspaceProject } from "./workspace-project.js";
+function normalizeRelativePath(value) {
+    return value.replace(/\\/gu, "/");
+}
+function buildGeneratedArtifactPaths(blockJsonFile, manifestFile) {
+    const manifestDir = path.dirname(manifestFile);
+    const artifactPaths = [
+        blockJsonFile,
+        manifestFile,
+        path.join(manifestDir, "typia.schema.json"),
+        path.join(manifestDir, "typia-validator.php"),
+        path.join(manifestDir, "typia.openapi.json"),
+    ];
+    return Array.from(new Set(artifactPaths.map((filePath) => normalizeRelativePath(filePath))));
+}
+function collectNamedSourceTypeCandidates(typesSource) {
+    const sourceFile = ts.createSourceFile("types.ts", typesSource, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    return sourceFile.statements.flatMap((statement) => {
+        if (ts.isInterfaceDeclaration(statement) ||
+            ts.isTypeAliasDeclaration(statement)) {
+            return [statement.name.text];
+        }
+        return [];
+    });
+}
+function isObjectLikeSourceType(projectDir, typesFile, sourceTypeName) {
+    const analyzedTypes = analyzeSourceTypes({
+        projectRoot: projectDir,
+        typesFile,
+    }, [sourceTypeName]);
+    return analyzedTypes[sourceTypeName]?.kind === "object";
+}
+function inferRetrofitAttributeTypeName(projectDir, block) {
+    const typesPath = path.join(projectDir, block.typesFile);
+    const typesSource = fs.readFileSync(typesPath, "utf8");
+    const blockNameSegments = block.blockName.split("/");
+    const slug = blockNameSegments[blockNameSegments.length - 1] ?? block.key;
+    const candidateNames = collectNamedSourceTypeCandidates(typesSource);
+    const validCandidates = candidateNames.filter((candidateName) => isObjectLikeSourceType(projectDir, block.typesFile, candidateName));
+    const preferredName = `${toPascalCase(slug)}Attributes`;
+    if (validCandidates.includes(preferredName)) {
+        return preferredName;
+    }
+    const attributeCandidates = validCandidates.filter((candidateName) => candidateName.endsWith("Attributes"));
+    if (attributeCandidates.length === 1) {
+        return attributeCandidates[0];
+    }
+    if (validCandidates.length === 1) {
+        return validCandidates[0];
+    }
+    if (validCandidates.length === 0) {
+        throw new Error(`Unable to infer an object-like source type from ${block.typesFile}. Add one interface or type alias such as ${preferredName} before rerunning \`wp-typia init\`.`);
+    }
+    throw new Error(`Unable to infer a unique source type from ${block.typesFile}. Candidate object-like exports: ${validCandidates.join(", ")}. Rename one to ${preferredName} or leave a single object-like attributes type before rerunning \`wp-typia init\`.`);
+}
+function buildRetrofitBlockTarget(projectDir, block) {
+    const blockNameSegments = block.blockName.split("/");
+    const slug = blockNameSegments[blockNameSegments.length - 1] ?? block.key;
+    return {
+        attributeTypeName: inferRetrofitAttributeTypeName(projectDir, block),
+        blockJsonFile: block.blockJsonFile,
+        blockName: block.blockName,
+        manifestFile: block.manifestFile,
+        saveFile: block.saveFile,
+        slug,
+        typesFile: block.typesFile,
+    };
+}
+export function buildInitLayoutDetails(projectDir) {
+    try {
+        const discoveredLayout = discoverMigrationInitLayout(projectDir);
+        const discoveredBlocks = discoveredLayout.mode === "multi"
+            ? discoveredLayout.blocks
+            : [discoveredLayout.block];
+        let blockTargets;
+        try {
+            blockTargets = discoveredBlocks.map((block) => buildRetrofitBlockTarget(projectDir, block));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                blockNames: discoveredBlocks.map((block) => block.blockName),
+                blockTargets: [],
+                description: "Detected supported block files, but could not infer retrofit block-config metadata automatically yet.",
+                generatedArtifacts: [],
+                kind: "unsupported",
+                notes: [message, SUPPORTED_RETROFIT_LAYOUT_NOTE],
+            };
+        }
+        if (discoveredLayout.mode === "multi") {
+            return {
+                blockNames: discoveredBlocks.map((block) => block.blockName),
+                blockTargets,
+                description: `Detected a supported multi-block retrofit candidate (${discoveredBlocks.length} targets).`,
+                generatedArtifacts: discoveredBlocks.flatMap((block) => buildGeneratedArtifactPaths(block.blockJsonFile, block.manifestFile)),
+                kind: "multi-block",
+                notes: [
+                    "Migration bootstrap can stay optional. Add it later with `wp-typia migrate init --current-migration-version v1` once the typed sync surface is in place.",
+                ],
+            };
+        }
+        return {
+            blockNames: [discoveredLayout.block.blockName],
+            blockTargets,
+            description: "Detected a supported single-block retrofit candidate.",
+            generatedArtifacts: buildGeneratedArtifactPaths(discoveredLayout.block.blockJsonFile, discoveredLayout.block.manifestFile),
+            kind: "single-block",
+            notes: discoveredLayout.block.blockJsonFile === "block.json"
+                ? [
+                    "Legacy root `block.json` layouts are still supported for retrofit planning, but newer scaffolds keep generated block metadata under `src/`.",
+                ]
+                : [],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            blockNames: [],
+            blockTargets: [],
+            description: "No supported retrofit layout was auto-detected yet.",
+            generatedArtifacts: [],
+            kind: "unsupported",
+            notes: [message, SUPPORTED_RETROFIT_LAYOUT_NOTE],
+        };
+    }
+}
+function buildPlannedFiles(projectDir, layoutKind) {
+    if (layoutKind === "unsupported") {
+        return [];
+    }
+    return [
+        {
+            action: fs.existsSync(path.join(projectDir, "scripts", "block-config.ts"))
+                ? "update"
+                : "add",
+            path: "scripts/block-config.ts",
+            purpose: "Declare the current retrofit block targets so sync-types can regenerate metadata from the existing TypeScript source of truth.",
+        },
+        {
+            action: fs.existsSync(path.join(projectDir, "scripts", "sync-types-to-block-json.ts"))
+                ? "update"
+                : "add",
+            path: "scripts/sync-types-to-block-json.ts",
+            purpose: "Generate block.json and Typia metadata artifacts from the current TypeScript source of truth.",
+        },
+        {
+            action: fs.existsSync(path.join(projectDir, "scripts", "sync-project.ts"))
+                ? "update"
+                : "add",
+            path: "scripts/sync-project.ts",
+            purpose: "Provide one shared sync entrypoint that can grow into sync-rest or workspace-aware refresh steps later.",
+        },
+    ];
+}
+export function createRetrofitPlan(options) {
+    const includeGeneratedArtifacts = options.commandMode === "preview-only";
+    const plannedChanges = buildInitPlanChangeSummary({
+        generatedArtifacts: options.generatedArtifacts,
+        packageChanges: options.packageChanges,
+        plannedFiles: options.plannedFiles,
+    }, {
+        includeGeneratedArtifacts,
+    });
+    return {
+        blockTargets: options.blockTargets,
+        commandMode: options.commandMode,
+        detectedLayout: options.detectedLayout,
+        generatedArtifacts: options.generatedArtifacts,
+        nextSteps: options.nextSteps ??
+            buildInitPlanNextSteps({
+                commandMode: options.commandMode,
+                dependencyChangeCount: options.packageChanges.addDevDependencies.length,
+                hasPlannedChanges: plannedChanges.length > 0,
+                layoutKind: options.detectedLayout.kind,
+                packageManager: options.packageManager,
+            }),
+        notes: options.notes,
+        packageChanges: options.packageChanges,
+        plannedFiles: options.plannedFiles,
+        packageManager: options.packageManager,
+        projectDir: options.projectDir,
+        projectName: options.projectName,
+        status: options.status,
+        summary: buildRetrofitPlanSummary({
+            commandMode: options.commandMode,
+            status: options.status,
+        }),
+    };
+}
+/**
+ * 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 function getInitPlan(projectDir, options = {}) {
+    const resolvedProjectDir = path.resolve(projectDir);
+    const packageJson = readProjectPackageJson(resolvedProjectDir);
+    const packageManager = resolveInitPackageManager(resolvedProjectDir, packageJson, options.packageManager);
+    const workspace = tryResolveWorkspaceProject(resolvedProjectDir);
+    if (workspace) {
+        const workspacePackageJson = readProjectPackageJson(workspace.projectDir);
+        const workspacePackageManager = resolveInitPackageManager(workspace.projectDir, workspacePackageJson, options.packageManager);
+        const cliSpecifier = getWpTypiaCliSpecifier();
+        return createRetrofitPlan({
+            blockTargets: [],
+            commandMode: "preview-only",
+            detectedLayout: {
+                blockNames: [],
+                description: "Already an official wp-typia workspace.",
+                kind: "official-workspace",
+            },
+            generatedArtifacts: [],
+            nextSteps: [
+                "Use `wp-typia add <kind> <name>` to extend the official workspace instead of rerunning init.",
+                formatRunScript(workspacePackageManager, "sync"),
+                formatPackageExecCommand(workspacePackageManager, cliSpecifier, "doctor"),
+            ],
+            notes: [
+                "The official workspace template already owns inventory, doctor, and add-command workflows.",
+            ],
+            packageChanges: {
+                addDevDependencies: [],
+                scripts: [],
+            },
+            packageManager: workspacePackageManager,
+            plannedFiles: [],
+            projectDir: workspace.projectDir,
+            projectName: workspace.packageName,
+            status: "already-initialized",
+        });
+    }
+    const projectName = typeof packageJson?.name === "string" && packageJson.name.length > 0
+        ? packageJson.name
+        : path.basename(resolvedProjectDir);
+    const layout = buildInitLayoutDetails(resolvedProjectDir);
+    const dependencyChanges = buildDependencyChanges(packageJson);
+    const scriptChanges = buildScriptChanges(packageJson, packageManager);
+    const packageManagerFieldChange = buildPackageManagerFieldChange(packageJson, packageManager, {
+        persistExplicitOverride: typeof options.packageManager === "string",
+    });
+    const rawPlannedFiles = layout.kind === "generated-project" || layout.kind === "official-workspace"
+        ? []
+        : buildPlannedFiles(resolvedProjectDir, layout.kind);
+    const hasExistingSurface = hasExistingWpTypiaProjectSurface(resolvedProjectDir, packageJson);
+    const status = hasExistingSurface &&
+        dependencyChanges.length === 0 &&
+        scriptChanges.length === 0 &&
+        packageManagerFieldChange === undefined
+        ? "already-initialized"
+        : "preview";
+    const plannedFiles = status === "already-initialized" ? [] : rawPlannedFiles;
+    const detectedLayout = status === "already-initialized" && hasExistingSurface
+        ? {
+            blockNames: layout.blockNames,
+            description: layout.kind === "unsupported"
+                ? "Already exposes the minimum wp-typia sync surface."
+                : `Already exposes the minimum wp-typia sync surface for ${layout.kind === "multi-block" ? "a multi-block project" : "a single-block project"}.`,
+            kind: "generated-project",
+        }
+        : {
+            blockNames: layout.blockNames,
+            description: layout.description,
+            kind: layout.kind,
+        };
+    return createRetrofitPlan({
+        blockTargets: layout.blockTargets,
+        commandMode: "preview-only",
+        detectedLayout,
+        generatedArtifacts: status === "already-initialized" && detectedLayout.kind === "generated-project"
+            ? []
+            : layout.generatedArtifacts,
+        notes: Array.from(new Set([
+            "Preview only: `wp-typia init` does not write files yet.",
+            RETROFIT_APPLY_PREVIEW_NOTE,
+            ...layout.notes,
+        ])),
+        packageChanges: {
+            addDevDependencies: dependencyChanges,
+            ...(packageManagerFieldChange
+                ? { packageManagerField: packageManagerFieldChange }
+                : {}),
+            scripts: scriptChanges,
+        },
+        packageManager,
+        plannedFiles,
+        projectDir: resolvedProjectDir,
+        projectName,
+        status,
+    });
+}

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

@@ -0,0 +1,27 @@
+import type { RetrofitInitBlockTarget } from "./cli-init-types.js";
+/**
+ * Generate the `scripts/block-config.ts` source for retrofit block targets.
+ *
+ * @param targets Existing block targets detected by the init plan.
+ * @returns Complete TypeScript source for the generated block config helper.
+ */
+export declare function buildRetrofitBlockConfigSource(targets: RetrofitInitBlockTarget[]): string;
+/**
+ * Generate the `scripts/sync-types-to-block-json.ts` helper source.
+ *
+ * @returns Complete TypeScript source for the metadata sync helper.
+ */
+export declare function buildRetrofitSyncTypesScriptSource(): string;
+/**
+ * Generate the `scripts/sync-project.ts` orchestration helper source.
+ *
+ * @returns Complete TypeScript source for the project sync entrypoint.
+ */
+export declare function buildRetrofitSyncProjectScriptSource(): string;
+/**
+ * Build the helper file source map written by `wp-typia init --apply`.
+ *
+ * @param blockTargets Existing block targets detected by the init plan.
+ * @returns Relative helper file paths mapped to their generated source.
+ */
+export declare function buildRetrofitHelperFiles(blockTargets: RetrofitInitBlockTarget[]): Record<string, string>;