@wp-typia/project-tools 0.20.1 → 0.21.0

package/dist/runtime/cli-init.js

@@ -1,10 +1,19 @@
 import fs from "node:fs";
+import { promises as fsp } from "node:fs";
 import path from "node:path";
+import { analyzeSourceTypes } from "@wp-typia/block-runtime/metadata-parser";
+import ts from "typescript";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
+import { quoteTsString, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
 import { discoverMigrationInitLayout } from "./migration-project.js";
 import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
 import { getPackageVersions } from "./package-versions.js";
+import { toPascalCase } from "./string-case.js";
+import { updateWorkspaceInventorySource } from "./workspace-inventory.js";
 import { parseWorkspacePackageManagerId, tryResolveWorkspaceProject, } from "./workspace-project.js";
 const SUPPORTED_RETROFIT_LAYOUT_NOTE = "Supported retrofit layouts currently mirror the migration bootstrap detector: `src/block.json` + `src/types.ts` + `src/save.tsx`, legacy root `block.json` + `src/types.ts` + `src/save.tsx`, or multi-block `src/blocks/*/block.json` workspaces.";
+const RETROFIT_APPLY_PREVIEW_NOTE = "If you rerun with `wp-typia init --apply`, package.json and generated helper files are snapshotted and rolled back automatically if a write fails.";
+const RETROFIT_ROLLBACK_NOTE = "Apply mode writes package.json and generated helper files with rollback-on-failure protection.";
 const BASE_RETROFIT_SCRIPTS = {
     sync: "tsx scripts/sync-project.ts",
     "sync-types": "tsx scripts/sync-types-to-block-json.ts",
@@ -26,7 +35,14 @@ function readProjectPackageJson(projectDir) {
     if (!fs.existsSync(packageJsonPath)) {
         return null;
     }
-    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    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) {
@@ -45,6 +61,18 @@ function inferInitPackageManager(projectDir, packageJson) {
     }
     return "npm";
 }
+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;
+}
 function getWpTypiaCliSpecifier() {
     const versions = getPackageVersions();
     return versions.wpTypiaPackageExactVersion === "0.0.0"
@@ -54,12 +82,12 @@ function getWpTypiaCliSpecifier() {
 function buildRequiredDevDependencyMap() {
     const versions = getPackageVersions();
     return {
-        "@typia/unplugin": "^12.0.1",
+        "@typia/unplugin": versions.typiaUnpluginPackageVersion,
         "@wp-typia/block-runtime": versions.blockRuntimePackageVersion,
         "@wp-typia/block-types": versions.blockTypesPackageVersion,
-        tsx: "^4.20.5",
-        typescript: "^5.9.2",
-        typia: "^12.0.1",
+        tsx: versions.tsxPackageVersion,
+        typescript: versions.typescriptPackageVersion,
+        typia: versions.typiaPackageVersion,
     };
 }
 function getExistingDependencyVersion(packageJson, name) {
@@ -101,8 +129,8 @@ function buildScriptChanges(packageJson, packageManager) {
         ];
     });
 }
-function buildPackageManagerFieldChange(packageJson, packageManager) {
-    if (packageManager === "npm") {
+function buildPackageManagerFieldChange(packageJson, packageManager, options = {}) {
+    if (!options.persistExplicitOverride && packageManager === "npm") {
         return undefined;
     }
     const requiredValue = getPackageManager(packageManager).packageManagerField;
@@ -127,14 +155,298 @@ function buildGeneratedArtifactPaths(blockJsonFile, manifestFile) {
     ];
     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,
+    };
+}
+function buildRetrofitBlockConfigEntry(target) {
+    return [
+        "\t{",
+        `\t\tslug: ${quoteTsString(target.slug)},`,
+        `\t\tattributeTypeName: ${quoteTsString(target.attributeTypeName)},`,
+        `\t\tblockJsonFile: ${quoteTsString(target.blockJsonFile)},`,
+        `\t\tmanifestFile: ${quoteTsString(target.manifestFile)},`,
+        `\t\ttypesFile: ${quoteTsString(target.typesFile)},`,
+        "\t},",
+    ].join("\n");
+}
+function buildRetrofitBlockConfigSource(targets) {
+    const blockEntries = targets.map(buildRetrofitBlockConfigEntry).join("\n");
+    const baseSource = `export interface WorkspaceBlockConfig {
+\tattributeTypeName: string;
+\tapiTypesFile?: string;
+\tblockJsonFile?: string;
+\tmanifestFile?: string;
+\topenApiFile?: string;
+\trestManifest?: ReturnType<
+\t\ttypeof import( '@wp-typia/block-runtime/metadata-core' ).defineEndpointManifest
+\t>;
+\tslug: string;
+\ttypesFile: string;
+}
+
+export const BLOCKS: WorkspaceBlockConfig[] = [
+${blockEntries}
+];
+`;
+    return `${updateWorkspaceInventorySource(baseSource)}\n`;
+}
+function buildRetrofitSyncTypesScriptSource() {
+    return `/* eslint-disable no-console */
+import path from 'node:path';
+
+import { syncBlockMetadata } from '@wp-typia/block-runtime/metadata-core';
+
+import { BLOCKS } from './block-config';
+
+function parseCliOptions( argv: string[] ) {
+\tconst options = {
+\t\tcheck: false,
+\t};
+
+\tfor ( const argument of argv ) {
+\t\tif ( argument === '--check' ) {
+\t\t\toptions.check = true;
+\t\t\tcontinue;
+\t\t}
+
+\t\tthrow new Error( \`Unknown sync-types flag: \${ argument }\` );
+\t}
+
+\treturn options;
+}
+
+async function main() {
+\tconst options = parseCliOptions( process.argv.slice( 2 ) );
+
+\tif ( BLOCKS.length === 0 ) {
+\t\tconsole.log(
+\t\t\toptions.check
+\t\t\t\t? 'ℹ️ No retrofit blocks are registered yet. \`sync-types --check\` is already clean.'
+\t\t\t\t: 'ℹ️ No retrofit blocks are registered yet. Add one block target to scripts/block-config.ts before rerunning sync-types.'
+\t\t);
+\t\treturn;
+\t}
+
+\tfor ( const block of BLOCKS ) {
+\t\tconst blockDir = path.dirname( block.typesFile );
+\t\tconst blockJsonFile =
+\t\t\tblock.blockJsonFile ?? path.join( blockDir, 'block.json' );
+\t\tconst manifestFile =
+\t\t\tblock.manifestFile ?? path.join( blockDir, 'typia.manifest.json' );
+\t\tconst manifestDir = path.dirname( manifestFile );
+\t\tconst result = await syncBlockMetadata(
+\t\t\t{
+\t\t\t\tblockJsonFile,
+\t\t\t\tjsonSchemaFile: path.join( manifestDir, 'typia.schema.json' ),
+\t\t\t\tmanifestFile,
+\t\t\t\topenApiFile: path.join( manifestDir, 'typia.openapi.json' ),
+\t\t\t\tsourceTypeName: block.attributeTypeName,
+\t\t\t\ttypesFile: block.typesFile,
+\t\t\t},
+\t\t\t{
+\t\t\t\tcheck: options.check,
+\t\t\t}
+\t\t);
+\t\tfor ( const warning of result.lossyProjectionWarnings ) {
+\t\t\tconsole.warn( \`⚠️ \${ block.slug }: \${ warning }\` );
+\t\t}
+\t\tfor ( const warning of result.phpGenerationWarnings ) {
+\t\t\tconsole.warn( \`⚠️ \${ block.slug }: \${ warning }\` );
+\t\t}
+
+\t\tconsole.log(
+\t\t\toptions.check
+\t\t\t\t? \`✅ \${ block.slug }: block.json, typia.manifest.json, typia-validator.php, typia.schema.json, and typia.openapi.json are already up to date with the TypeScript types!\`
+\t\t\t\t: \`✅ \${ block.slug }: block.json, typia.manifest.json, typia-validator.php, typia.schema.json, and typia.openapi.json were generated from TypeScript types!\`
+\t\t);
+\t\tconsole.log( '📝 Generated attributes:', result.attributeNames );
+\t}
+}
+
+main().catch( ( error ) => {
+\tconsole.error( '❌ Type sync failed:', error );
+\tprocess.exit( 1 );
+} );
+`;
+}
+function buildRetrofitSyncProjectScriptSource() {
+    return `/* eslint-disable no-console */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+interface SyncCliOptions {
+\tcheck: boolean;
+}
+
+function parseCliOptions( argv: string[] ): SyncCliOptions {
+\tconst options: SyncCliOptions = {
+\t\tcheck: false,
+\t};
+
+\tfor ( const argument of argv ) {
+\t\tif ( argument === '--check' ) {
+\t\t\toptions.check = true;
+\t\t\tcontinue;
+\t\t}
+
+\t\tthrow new Error( \`Unknown sync flag: \${ argument }\` );
+\t}
+
+\treturn options;
+}
+
+function getSyncScriptEnv() {
+\tconst binaryDirectory = path.join( process.cwd(), 'node_modules', '.bin' );
+\tconst inheritedPath =
+\t\tprocess.env.PATH ??
+\t\tprocess.env.Path ??
+\t\tObject.entries( process.env ).find(
+\t\t\t( [ key ] ) => key.toLowerCase() === 'path'
+\t\t)?.[ 1 ] ??
+\t\t'';
+\tconst nextPath = fs.existsSync( binaryDirectory )
+\t\t? \`\${ binaryDirectory }\${ path.delimiter }\${ inheritedPath }\`
+\t\t: inheritedPath;
+\tconst env: NodeJS.ProcessEnv = {
+\t\t...process.env,
+\t};
+
+\tfor ( const key of Object.keys( env ) ) {
+\t\tif ( key.toLowerCase() === 'path' ) {
+\t\t\tdelete env[ key ];
+\t\t}
+\t}
+
+\tenv.PATH = nextPath;
+
+\treturn env;
+}
+
+function runSyncScript( scriptPath: string, options: SyncCliOptions ) {
+\tconst args = [ scriptPath ];
+\tif ( options.check ) {
+\t\targs.push( '--check' );
+\t}
+
+\tconst result = spawnSync( 'tsx', args, {
+\t\tcwd: process.cwd(),
+\t\tenv: getSyncScriptEnv(),
+\t\tshell: process.platform === 'win32',
+\t\tstdio: 'inherit',
+\t} );
+
+\tif ( result.error ) {
+\t\tif ( ( result.error as NodeJS.ErrnoException ).code === 'ENOENT' ) {
+\t\t\tthrow new Error(
+\t\t\t\t'Unable to resolve \`tsx\` for project sync. Install project dependencies or rerun the command through your package manager.'
+\t\t\t);
+\t\t}
+
+\t\tthrow result.error;
+\t}
+
+\tif ( result.status !== 0 ) {
+\t\tthrow new Error( \`Sync script failed: \${ scriptPath }\` );
+\t}
+}
+
+async function main() {
+\tconst options = parseCliOptions( process.argv.slice( 2 ) );
+\tconst syncTypesScriptPath = path.join( 'scripts', 'sync-types-to-block-json.ts' );
+
+\trunSyncScript( syncTypesScriptPath, options );
+
+\tconsole.log(
+\t\toptions.check
+\t\t\t? '✅ Generated project metadata is already synchronized.'
+\t\t\t: '✅ Generated project metadata was synchronized.'
+\t);
+}
+
+main().catch( ( error ) => {
+\tconsole.error( '❌ Project sync failed:', error );
+\tprocess.exit( 1 );
+} );
+`;
+}
 function buildLayoutDetails(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: discoveredLayout.blocks.map((block) => block.blockName),
-                description: `Detected a supported multi-block retrofit candidate (${discoveredLayout.blocks.length} targets).`,
-                generatedArtifacts: discoveredLayout.blocks.flatMap((block) => buildGeneratedArtifactPaths(block.blockJsonFile, block.manifestFile)),
+                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.",
@@ -143,6 +455,7 @@ function buildLayoutDetails(projectDir) {
         }
         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",
@@ -157,6 +470,7 @@ function buildLayoutDetails(projectDir) {
         const message = error instanceof Error ? error.message : String(error);
         return {
             blockNames: [],
+            blockTargets: [],
             description: "No supported retrofit layout was auto-detected yet.",
             generatedArtifacts: [],
             kind: "unsupported",
@@ -164,35 +478,49 @@ function buildLayoutDetails(projectDir) {
         };
     }
 }
-function hasExistingWpTypiaProjectSurface(packageJson) {
+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 && hasRuntimeDeps;
+    return hasSyncSurface && hasHelperFiles && hasRuntimeDeps;
 }
-function buildPlannedFiles(layoutKind) {
-    const plannedFiles = [
+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.",
         },
     ];
-    if (layoutKind === "unsupported") {
-        plannedFiles.unshift({
-            path: "package.json",
-            purpose: "Add the minimum wp-typia devDependencies and scripts once the project matches a supported retrofit layout.",
-        });
-    }
-    return plannedFiles;
 }
-function buildChangeSummary(changes) {
+function buildChangeSummary(changes, options) {
     const lines = [];
     for (const dependencyChange of changes.packageChanges.addDevDependencies) {
         lines.push(`devDependency ${dependencyChange.action} ${dependencyChange.name} -> ${dependencyChange.requiredValue}`);
@@ -204,10 +532,12 @@ function buildChangeSummary(changes) {
         lines.push(`script ${scriptChange.action} ${scriptChange.name} -> ${scriptChange.requiredValue}`);
     }
     for (const filePlan of changes.plannedFiles) {
-        lines.push(`file add ${filePlan.path} (${filePlan.purpose})`);
+        lines.push(`file ${filePlan.action} ${filePlan.path} (${filePlan.purpose})`);
     }
-    for (const artifactPath of changes.generatedArtifacts) {
-        lines.push(`generated artifact ${artifactPath}`);
+    if (options.includeGeneratedArtifacts) {
+        for (const artifactPath of changes.generatedArtifacts) {
+            lines.push(`generated artifact ${artifactPath}`);
+        }
     }
     return lines;
 }
@@ -226,11 +556,24 @@ function buildNextSteps(options) {
             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}`,
+        ];
+    }
     const steps = [
-        ...(options.changeSummaryLines.length > 0
+        ...(options.hasPlannedChanges
             ? [
-                "Apply the planned package.json changes and helper files listed below.",
-                dependencyInstallCommand,
+                "Re-run `wp-typia init --apply` to write the planned package.json changes and helper files automatically.",
+                ...(options.dependencyChangeCount > 0 ? [dependencyInstallCommand] : []),
             ]
             : []),
         syncRun,
@@ -242,13 +585,148 @@ function buildNextSteps(options) {
 function buildRequiredDevDependencyMapEntries() {
     return Object.entries(buildRequiredDevDependencyMap()).map(([name, version]) => `${name}@${version.replace(/^workspace:/u, "")}`);
 }
-export function getInitPlan(projectDir) {
+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.";
+}
+function createRetrofitPlan(options) {
+    const includeGeneratedArtifacts = options.commandMode === "preview-only";
+    const plannedChanges = buildChangeSummary({
+        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 ??
+            buildNextSteps({
+                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,
+        }),
+    };
+}
+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;
+}
+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;
+}
+function buildProjectPackageJsonSource(packageJson) {
+    return `${JSON.stringify(packageJson, null, 2)}\n`;
+}
+function buildRetrofitHelperFiles(blockTargets) {
+    return {
+        [path.join("scripts", "block-config.ts")]: buildRetrofitBlockConfigSource(blockTargets),
+        [path.join("scripts", "sync-project.ts")]: buildRetrofitSyncProjectScriptSource(),
+        [path.join("scripts", "sync-types-to-block-json.ts")]: buildRetrofitSyncTypesScriptSource(),
+    };
+}
+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);
+}
+/**
+ * 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 = inferInitPackageManager(resolvedProjectDir, packageJson);
+    const packageManager = resolveInitPackageManager(resolvedProjectDir, packageJson, options.packageManager);
     const workspace = tryResolveWorkspaceProject(resolvedProjectDir);
     if (workspace) {
-        return {
+        const workspacePackageJson = readProjectPackageJson(workspace.projectDir);
+        const workspacePackageManager = resolveInitPackageManager(workspace.projectDir, workspacePackageJson, options.packageManager);
+        const cliSpecifier = getWpTypiaCliSpecifier();
+        return createRetrofitPlan({
+            blockTargets: [],
             commandMode: "preview-only",
             detectedLayout: {
                 blockNames: [],
@@ -257,8 +735,9 @@ export function getInitPlan(projectDir) {
             },
             generatedArtifacts: [],
             nextSteps: [
-                formatPackageExecCommand(packageManager, getWpTypiaCliSpecifier(), "doctor"),
-                "Use `wp-typia add ...` to extend this workspace instead of rerunning init.",
+                "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.",
@@ -267,13 +746,12 @@ export function getInitPlan(projectDir) {
                 addDevDependencies: [],
                 scripts: [],
             },
+            packageManager: workspacePackageManager,
             plannedFiles: [],
-            packageManager,
             projectDir: workspace.projectDir,
             projectName: workspace.packageName,
             status: "already-initialized",
-            summary: "This directory is already an official wp-typia workspace. No retrofit bootstrap is needed.",
-        };
+        });
     }
     const projectName = typeof packageJson?.name === "string" && packageJson.name.length > 0
         ? packageJson.name
@@ -281,11 +759,13 @@ export function getInitPlan(projectDir) {
     const layout = buildLayoutDetails(resolvedProjectDir);
     const dependencyChanges = buildDependencyChanges(packageJson);
     const scriptChanges = buildScriptChanges(packageJson, packageManager);
-    const packageManagerFieldChange = buildPackageManagerFieldChange(packageJson, packageManager);
+    const packageManagerFieldChange = buildPackageManagerFieldChange(packageJson, packageManager, {
+        persistExplicitOverride: typeof options.packageManager === "string",
+    });
     const rawPlannedFiles = layout.kind === "generated-project" || layout.kind === "official-workspace"
         ? []
-        : buildPlannedFiles(layout.kind);
-    const hasExistingSurface = hasExistingWpTypiaProjectSurface(packageJson);
+        : buildPlannedFiles(resolvedProjectDir, layout.kind);
+    const hasExistingSurface = hasExistingWpTypiaProjectSurface(resolvedProjectDir, packageJson);
     const status = hasExistingSurface &&
         dependencyChanges.length === 0 &&
         scriptChanges.length === 0 &&
@@ -306,32 +786,16 @@ export function getInitPlan(projectDir) {
             description: layout.description,
             kind: layout.kind,
         };
-    const plan = {
+    return createRetrofitPlan({
+        blockTargets: layout.blockTargets,
         commandMode: "preview-only",
         detectedLayout,
         generatedArtifacts: status === "already-initialized" && detectedLayout.kind === "generated-project"
             ? []
             : layout.generatedArtifacts,
-        nextSteps: buildNextSteps({
-            changeSummaryLines: buildChangeSummary({
-                generatedArtifacts: status === "already-initialized" &&
-                    detectedLayout.kind === "generated-project"
-                    ? []
-                    : layout.generatedArtifacts,
-                packageChanges: {
-                    addDevDependencies: dependencyChanges,
-                    ...(packageManagerFieldChange
-                        ? { packageManagerField: packageManagerFieldChange }
-                        : {}),
-                    scripts: scriptChanges,
-                },
-                plannedFiles,
-            }),
-            layoutKind: detectedLayout.kind,
-            packageManager,
-        }),
         notes: Array.from(new Set([
             "Preview only: `wp-typia init` does not write files yet.",
+            RETROFIT_APPLY_PREVIEW_NOTE,
             ...layout.notes,
         ])),
         packageChanges: {
@@ -341,14 +805,89 @@ export function getInitPlan(projectDir) {
                 : {}),
             scripts: scriptChanges,
         },
-        plannedFiles,
         packageManager,
+        plannedFiles,
         projectDir: resolvedProjectDir,
         projectName,
         status,
-        summary: status === "already-initialized"
-            ? "This project already exposes the minimum wp-typia retrofit surface."
-            : "This command previews the minimum wp-typia adoption layer for the current project without rewriting it into a full scaffold.",
-    };
-    return plan;
+    });
+}
+/**
+ * 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: Array.from(new Set([
+                ...previewPlan.notes.filter((note) => note !== "Preview only: `wp-typia init` does not write files yet." &&
+                    note !== RETROFIT_APPLY_PREVIEW_NOTE),
+                RETROFIT_ROLLBACK_NOTE,
+            ])),
+            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: Array.from(new Set([
+            ...previewPlan.notes.filter((note) => note !== "Preview only: `wp-typia init` does not write files yet." &&
+                note !== RETROFIT_APPLY_PREVIEW_NOTE),
+            RETROFIT_ROLLBACK_NOTE,
+        ])),
+        status: "applied",
+    });
+}
+/**
+ * Execute `wp-typia init` in preview or apply mode.
+ *
+ * @param options Resolved command options including the target project
+ * directory, optional package-manager override, and whether writes should be
+ * applied.
+ * @returns The previewed or applied retrofit init plan.
+ */
+export async function runInitCommand(options) {
+    return options.apply
+        ? applyInitPlan(options.projectDir, {
+            packageManager: options.packageManager,
+        })
+        : getInitPlan(options.projectDir, {
+            packageManager: options.packageManager,
+        });
 }