@wp-typia/project-tools 0.19.2 → 0.20.0

package/dist/runtime/cli-doctor-workspace.js

@@ -11,6 +11,10 @@ const WORKSPACE_BINDING_SERVER_GLOB = "/src/bindings/*/server.php";
 const WORKSPACE_BINDING_EDITOR_SCRIPT = "build/bindings/index.js";
 const WORKSPACE_BINDING_EDITOR_ASSET = "build/bindings/index.asset.php";
 const WORKSPACE_REST_RESOURCE_GLOB = "/inc/rest/*.php";
+const WORKSPACE_ABILITY_GLOB = "/inc/abilities/*.php";
+const WORKSPACE_ABILITY_EDITOR_SCRIPT = "build/abilities/index.js";
+const WORKSPACE_ABILITY_EDITOR_ASSET = "build/abilities/index.asset.php";
+const WORKSPACE_AI_FEATURE_GLOB = "/inc/ai-features/*.php";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_SCRIPT = "build/editor-plugins/index.js";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_ASSET = "build/editor-plugins/index.asset.php";
 const WORKSPACE_EDITOR_PLUGIN_EDITOR_STYLE = "build/editor-plugins/style-index.css";
@@ -249,6 +253,126 @@ function checkWorkspaceRestResourceBootstrap(projectDir, packageName, phpPrefix)
         ? "REST resource PHP loader hook is present"
         : "Missing REST resource PHP require glob or init hook");
 }
+function getWorkspaceAbilityRequiredFiles(ability) {
+    return Array.from(new Set([
+        ability.clientFile,
+        ability.configFile,
+        ability.dataFile,
+        ability.inputSchemaFile,
+        ability.outputSchemaFile,
+        ability.phpFile,
+        ability.typesFile,
+    ]));
+}
+function checkWorkspaceAbilityConfig(projectDir, ability) {
+    const configPath = path.join(projectDir, ability.configFile);
+    if (!fs.existsSync(configPath)) {
+        return createDoctorCheck(`Ability config ${ability.slug}`, "fail", `Missing ${ability.configFile}`);
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const abilityId = typeof config.abilityId === "string" ? config.abilityId.trim() : "";
+        const categorySlug = typeof config.category?.slug === "string"
+            ? config.category.slug.trim()
+            : "";
+        const hasValidAbilityId = /^[a-z0-9-]+\/[a-z0-9-]+$/u.test(abilityId);
+        const hasValidCategorySlug = /^[a-z0-9-]+$/u.test(categorySlug);
+        return createDoctorCheck(`Ability config ${ability.slug}`, hasValidAbilityId && hasValidCategorySlug ? "pass" : "fail", hasValidAbilityId && hasValidCategorySlug
+            ? `Ability id ${abilityId} in category ${categorySlug} is valid`
+            : "Ability config must define a valid abilityId (`namespace/ability-name`) and category.slug.");
+    }
+    catch (error) {
+        return createDoctorCheck(`Ability config ${ability.slug}`, "fail", error instanceof Error ? error.message : String(error));
+    }
+}
+function checkWorkspaceAbilityBootstrap(projectDir, packageName, phpPrefix) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("Ability bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const loadFunctionName = `${phpPrefix}_load_workflow_abilities`;
+    const enqueueFunctionName = `${phpPrefix}_enqueue_workflow_abilities`;
+    const loadHook = `add_action( 'plugins_loaded', '${loadFunctionName}' );`;
+    const adminEnqueueHook = `add_action( 'admin_enqueue_scripts', '${enqueueFunctionName}' );`;
+    const editorEnqueueHook = `add_action( 'enqueue_block_editor_assets', '${enqueueFunctionName}' );`;
+    const hasLoaderHook = source.includes(loadHook);
+    const hasAdminEnqueueHook = source.includes(adminEnqueueHook);
+    const hasEditorEnqueueHook = source.includes(editorEnqueueHook);
+    const hasServerGlob = source.includes(WORKSPACE_ABILITY_GLOB);
+    const hasEditorScript = source.includes(WORKSPACE_ABILITY_EDITOR_SCRIPT);
+    const hasEditorAsset = source.includes(WORKSPACE_ABILITY_EDITOR_ASSET);
+    return createDoctorCheck("Ability bootstrap", hasLoaderHook &&
+        hasAdminEnqueueHook &&
+        hasEditorEnqueueHook &&
+        hasServerGlob &&
+        hasEditorScript &&
+        hasEditorAsset
+        ? "pass"
+        : "fail", hasLoaderHook &&
+        hasAdminEnqueueHook &&
+        hasEditorEnqueueHook &&
+        hasServerGlob &&
+        hasEditorScript &&
+        hasEditorAsset
+        ? "Ability loader and admin/editor client bootstrap hooks are present"
+        : "Missing ability loader hook or build/abilities script asset references");
+}
+function checkWorkspaceAbilityIndex(projectDir, abilities) {
+    const indexRelativePath = [
+        path.join("src", "abilities", "index.ts"),
+        path.join("src", "abilities", "index.js"),
+    ].find((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
+    if (!indexRelativePath) {
+        return createDoctorCheck("Abilities index", "fail", "Missing src/abilities/index.ts or src/abilities/index.js");
+    }
+    const indexPath = path.join(projectDir, indexRelativePath);
+    const source = fs.readFileSync(indexPath, "utf8");
+    const missingExports = abilities.filter((ability) => {
+        const exportPattern = new RegExp(`^\\s*export\\s+(?:\\*\\s+from|\\{[^}]+\\}\\s+from)\\s+['"\`]\\./${escapeRegex(ability.slug)}\\/client['"\`]`, "mu");
+        return !exportPattern.test(source);
+    });
+    return createDoctorCheck("Abilities index", missingExports.length === 0 ? "pass" : "fail", missingExports.length === 0
+        ? "Ability client helpers are aggregated"
+        : `Missing ability exports for: ${missingExports.map((entry) => entry.slug).join(", ")}`);
+}
+function getWorkspaceAiFeatureRequiredFiles(aiFeature) {
+    return Array.from(new Set([
+        aiFeature.aiSchemaFile,
+        aiFeature.apiFile,
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-request.schema.json"),
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-response.schema.json"),
+        path.join(path.dirname(aiFeature.typesFile), "api-schemas", "feature-result.schema.json"),
+        aiFeature.clientFile,
+        aiFeature.dataFile,
+        aiFeature.openApiFile,
+        aiFeature.phpFile,
+        aiFeature.typesFile,
+        aiFeature.validatorsFile,
+    ]));
+}
+function checkWorkspaceAiFeatureConfig(aiFeature) {
+    const hasNamespace = REST_RESOURCE_NAMESPACE_PATTERN.test(aiFeature.namespace);
+    return createDoctorCheck(`AI feature config ${aiFeature.slug}`, hasNamespace ? "pass" : "fail", hasNamespace
+        ? `AI feature namespace ${aiFeature.namespace} is valid`
+        : "AI feature namespace is invalid");
+}
+function checkWorkspaceAiFeatureBootstrap(projectDir, packageName, phpPrefix) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("AI feature bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const registerFunctionName = `${phpPrefix}_register_ai_features`;
+    const registerHook = `add_action( 'init', '${registerFunctionName}', 20 );`;
+    const hasServerGlob = source.includes(WORKSPACE_AI_FEATURE_GLOB);
+    const hasRegisterHook = source.includes(registerHook);
+    return createDoctorCheck("AI feature bootstrap", hasServerGlob && hasRegisterHook ? "pass" : "fail", hasServerGlob && hasRegisterHook
+        ? "AI feature PHP loader hook is present"
+        : "Missing AI feature PHP require glob or init hook");
+}
 function getWorkspaceEditorPluginRequiredFiles(editorPlugin) {
     const editorPluginDir = path.join("src", "editor-plugins", editorPlugin.slug);
     return Array.from(new Set([
@@ -377,7 +501,7 @@ export function getWorkspaceDoctorChecks(cwd) {
     checks.push(checkWorkspacePackageMetadata(workspace, workspacePackageJson));
     try {
         const inventory = readWorkspaceInventory(workspace.projectDir);
-        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s), ${inventory.restResources.length} REST resource(s), ${inventory.editorPlugins.length} editor plugin(s)`));
+        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s), ${inventory.restResources.length} REST resource(s), ${inventory.abilities.length} ability scaffold(s), ${inventory.aiFeatures.length} AI feature(s), ${inventory.editorPlugins.length} editor plugin(s)`));
         for (const block of inventory.blocks) {
             checks.push(checkExistingFiles(workspace.projectDir, `Block ${block.slug}`, getWorkspaceBlockRequiredFiles(block)));
             checks.push(checkWorkspaceBlockMetadata(workspace.projectDir, workspace, block));
@@ -422,6 +546,21 @@ export function getWorkspaceDoctorChecks(cwd) {
             checks.push(checkWorkspaceRestResourceConfig(restResource));
             checks.push(checkExistingFiles(workspace.projectDir, `REST resource ${restResource.slug}`, getWorkspaceRestResourceRequiredFiles(restResource)));
         }
+        if (inventory.abilities.length > 0) {
+            checks.push(checkWorkspaceAbilityBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
+            checks.push(checkWorkspaceAbilityIndex(workspace.projectDir, inventory.abilities));
+        }
+        for (const ability of inventory.abilities) {
+            checks.push(checkWorkspaceAbilityConfig(workspace.projectDir, ability));
+            checks.push(checkExistingFiles(workspace.projectDir, `Ability ${ability.slug}`, getWorkspaceAbilityRequiredFiles(ability)));
+        }
+        if (inventory.aiFeatures.length > 0) {
+            checks.push(checkWorkspaceAiFeatureBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
+        }
+        for (const aiFeature of inventory.aiFeatures) {
+            checks.push(checkWorkspaceAiFeatureConfig(aiFeature));
+            checks.push(checkExistingFiles(workspace.projectDir, `AI feature ${aiFeature.slug}`, getWorkspaceAiFeatureRequiredFiles(aiFeature)));
+        }
         if (inventory.editorPlugins.length > 0) {
             checks.push(checkWorkspaceEditorPluginBootstrap(workspace.projectDir, workspace.packageName, workspace.workspace.phpPrefix));
             checks.push(checkWorkspaceEditorPluginIndex(workspace.projectDir, inventory.editorPlugins));

package/dist/runtime/cli-help.js

@@ -17,11 +17,14 @@ export function formatHelpText() {
   wp-typia create <project-dir> [--template persistence] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia create <project-dir> [--template compound] [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>] [--namespace <value>] [--text-domain <value>] [--php-prefix <value>] [--with-migration-ui] [--with-wp-env] [--with-test-preset] [--yes] [--dry-run] [--no-install] [--package-manager <id>]
   wp-typia <project-dir> [create flags...]
+  wp-typia init [project-dir]
   wp-typia add block <name> --template <basic|interactivity|persistence|compound> [--external-layer-source <./path|github:owner/repo/path[#ref]|npm-package>] [--external-layer-id <layer-id>] [--inner-blocks-preset <freeform|ordered|horizontal|locked-structure>] [--alternate-render-targets <email,mjml,plain-text>] [--data-storage <post-meta|custom-table>] [--persistence-policy <authenticated|public>]
   wp-typia add variation <name> --block <block-slug>
   wp-typia add pattern <name>
   wp-typia add binding-source <name>
   wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <method[,method...]>]
+  wp-typia add ability <name>
+  wp-typia add ai-feature <name> [--namespace <vendor/v1>]
   wp-typia add editor-plugin <name> [--slot <PluginSidebar>]
   wp-typia add hooked-block <block-slug> --anchor <anchor-block-name> --position <before|after|firstChild|lastChild>
   wp-typia migrate <init|snapshot|diff|scaffold|verify|doctor|fixtures|fuzz> [...]
@@ -37,15 +40,19 @@ Package managers: ${PACKAGE_MANAGER_IDS.join(", ")}
 Notes:
   \`wp-typia create\` is the canonical scaffold command.
   \`wp-typia <project-dir>\` remains a backward-compatible alias to \`create\` when \`<project-dir>\` is the only positional argument.
+  \`wp-typia init\` is a preview-only retrofit planner for existing projects. It does not write files yet.
   Use \`--template workspace\` as shorthand for \`@wp-typia/create-workspace-template\`, the official empty workspace scaffold behind \`wp-typia add ...\`.
   \`query-loop\` is create-only. Use \`wp-typia create <project-dir> --template query-loop\`; \`wp-typia add block\` accepts only basic, interactivity, persistence, and compound families.
   \`add variation\` uses an existing workspace block from \`scripts/block-config.ts\`.
   \`add pattern\` scaffolds a namespaced PHP pattern shell under \`src/patterns/\`.
   \`add binding-source\` scaffolds shared PHP and editor registration under \`src/bindings/\`.
   \`add rest-resource\` scaffolds plugin-level TypeScript REST contracts under \`src/rest/\` and PHP route glue under \`inc/rest/\`.
+  \`add ability\` scaffolds typed workflow abilities under \`src/abilities/\` and server registration under \`inc/abilities/\`.
+  \`add ai-feature\` scaffolds server-owned AI feature endpoints under \`src/ai-features/\` and PHP route glue under \`inc/ai-features/\`.
   \`add editor-plugin\` scaffolds a document-level editor extension under \`src/editor-plugins/\`.
   \`add hooked-block\` patches an existing workspace block's \`block.json\` \`blockHooks\` metadata.
   \`wp-typia doctor\` always checks environment readiness and reports when it only ran environment-level diagnostics; official workspace roots also get inventory and source-tree drift checks.
+  \`wp-typia init\` previews the minimum sync/doctor/migration adoption layer for supported existing layouts before a future write mode exists.
   \`wp-typia migrate doctor --all\` checks migration target alignment, snapshots, fixtures, and generated migration artifacts.
   \`migrate\` is the canonical migration command; \`migrations\` is no longer supported.`;
 }

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

@@ -0,0 +1,49 @@
+import { type PackageManagerId } from "./package-managers.js";
+type InitPlanAction = "add" | "update";
+type InitPlanStatus = "already-initialized" | "preview";
+type InitPlanLayoutKind = "generated-project" | "multi-block" | "official-workspace" | "single-block" | "unsupported";
+interface InitDependencyChange {
+    action: InitPlanAction;
+    currentValue?: string;
+    name: string;
+    requiredValue: string;
+}
+interface InitScriptChange {
+    action: InitPlanAction;
+    currentValue?: string;
+    name: string;
+    requiredValue: string;
+}
+interface InitPackageManagerFieldChange {
+    action: InitPlanAction;
+    currentValue?: string;
+    requiredValue: string;
+}
+interface InitFilePlan {
+    path: string;
+    purpose: string;
+}
+export interface RetrofitInitPlan {
+    commandMode: "preview-only";
+    detectedLayout: {
+        blockNames: string[];
+        description: string;
+        kind: InitPlanLayoutKind;
+    };
+    generatedArtifacts: string[];
+    nextSteps: string[];
+    notes: string[];
+    packageChanges: {
+        addDevDependencies: InitDependencyChange[];
+        packageManagerField?: InitPackageManagerFieldChange;
+        scripts: InitScriptChange[];
+    };
+    plannedFiles: InitFilePlan[];
+    packageManager: PackageManagerId;
+    projectDir: string;
+    projectName: string;
+    status: InitPlanStatus;
+    summary: string;
+}
+export declare function getInitPlan(projectDir: string): RetrofitInitPlan;
+export {};

package/dist/runtime/cli-init.js

@@ -0,0 +1,354 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverMigrationInitLayout } from "./migration-project.js";
+import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, getPackageManager, transformPackageManagerText, } from "./package-managers.js";
+import { getPackageVersions } from "./package-versions.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 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",
+];
+function normalizeRelativePath(value) {
+    return value.replace(/\\/gu, "/");
+}
+function readProjectPackageJson(projectDir) {
+    const packageJsonPath = path.join(projectDir, "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        return null;
+    }
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+}
+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";
+}
+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": "^12.0.1",
+        "@wp-typia/block-runtime": versions.blockRuntimePackageVersion,
+        "@wp-typia/block-types": versions.blockTypesPackageVersion,
+        tsx: "^4.20.5",
+        typescript: "^5.9.2",
+        typia: "^12.0.1",
+    };
+}
+function getExistingDependencyVersion(packageJson, name) {
+    return packageJson?.devDependencies?.[name] ?? packageJson?.dependencies?.[name];
+}
+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,
+            },
+        ];
+    });
+}
+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,
+            },
+        ];
+    });
+}
+function buildPackageManagerFieldChange(packageJson, packageManager) {
+    if (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,
+    };
+}
+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 buildLayoutDetails(projectDir) {
+    try {
+        const discoveredLayout = discoverMigrationInitLayout(projectDir);
+        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)),
+                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],
+            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: [],
+            description: "No supported retrofit layout was auto-detected yet.",
+            generatedArtifacts: [],
+            kind: "unsupported",
+            notes: [message, SUPPORTED_RETROFIT_LAYOUT_NOTE],
+        };
+    }
+}
+function hasExistingWpTypiaProjectSurface(packageJson) {
+    const scripts = packageJson?.scripts ?? {};
+    const hasSyncSurface = typeof scripts.sync === "string" || typeof scripts["sync-types"] === "string";
+    const hasRuntimeDeps = typeof getExistingDependencyVersion(packageJson, "@wp-typia/block-runtime") ===
+        "string" &&
+        typeof getExistingDependencyVersion(packageJson, "@wp-typia/block-types") ===
+            "string";
+    return hasSyncSurface && hasRuntimeDeps;
+}
+function buildPlannedFiles(layoutKind) {
+    const plannedFiles = [
+        {
+            path: "scripts/sync-types-to-block-json.ts",
+            purpose: "Generate block.json and Typia metadata artifacts from the current TypeScript source of truth.",
+        },
+        {
+            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) {
+    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 add ${filePlan.path} (${filePlan.purpose})`);
+    }
+    for (const artifactPath of changes.generatedArtifacts) {
+        lines.push(`generated artifact ${artifactPath}`);
+    }
+    return lines;
+}
+function buildNextSteps(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,
+        ];
+    }
+    const steps = [
+        ...(options.changeSummaryLines.length > 0
+            ? [
+                "Apply the planned package.json changes and helper files listed below.",
+                dependencyInstallCommand,
+            ]
+            : []),
+        syncRun,
+        doctorRun,
+        `Optional migration bootstrap: ${migrationInitRun}`,
+    ];
+    return steps;
+}
+function buildRequiredDevDependencyMapEntries() {
+    return Object.entries(buildRequiredDevDependencyMap()).map(([name, version]) => `${name}@${version.replace(/^workspace:/u, "")}`);
+}
+export function getInitPlan(projectDir) {
+    const resolvedProjectDir = path.resolve(projectDir);
+    const packageJson = readProjectPackageJson(resolvedProjectDir);
+    const packageManager = inferInitPackageManager(resolvedProjectDir, packageJson);
+    const workspace = tryResolveWorkspaceProject(resolvedProjectDir);
+    if (workspace) {
+        return {
+            commandMode: "preview-only",
+            detectedLayout: {
+                blockNames: [],
+                description: "Already an official wp-typia workspace.",
+                kind: "official-workspace",
+            },
+            generatedArtifacts: [],
+            nextSteps: [
+                formatPackageExecCommand(packageManager, getWpTypiaCliSpecifier(), "doctor"),
+                "Use `wp-typia add ...` to extend this workspace instead of rerunning init.",
+            ],
+            notes: [
+                "The official workspace template already owns inventory, doctor, and add-command workflows.",
+            ],
+            packageChanges: {
+                addDevDependencies: [],
+                scripts: [],
+            },
+            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
+        : path.basename(resolvedProjectDir);
+    const layout = buildLayoutDetails(resolvedProjectDir);
+    const dependencyChanges = buildDependencyChanges(packageJson);
+    const scriptChanges = buildScriptChanges(packageJson, packageManager);
+    const packageManagerFieldChange = buildPackageManagerFieldChange(packageJson, packageManager);
+    const rawPlannedFiles = layout.kind === "generated-project" || layout.kind === "official-workspace"
+        ? []
+        : buildPlannedFiles(layout.kind);
+    const hasExistingSurface = hasExistingWpTypiaProjectSurface(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,
+        };
+    const plan = {
+        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.",
+            ...layout.notes,
+        ])),
+        packageChanges: {
+            addDevDependencies: dependencyChanges,
+            ...(packageManagerFieldChange
+                ? { packageManagerField: packageManagerFieldChange }
+                : {}),
+            scripts: scriptChanges,
+        },
+        plannedFiles,
+        packageManager,
+        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;
+}

package/dist/runtime/cli-scaffold.d.ts

@@ -18,6 +18,7 @@ interface GetOptionalOnboardingOptions {
 }
 interface OptionalOnboardingGuidance {
     note: string;
+    shortNote: string;
     steps: string[];
 }
 export interface ScaffoldDryRunPlan {

package/dist/runtime/cli-scaffold.js

@@ -7,7 +7,7 @@ import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { createManagedTempRoot } from "./temp-roots.js";
-import { getOptionalOnboardingNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
+import { getOptionalOnboardingNote, getOptionalOnboardingShortNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
 import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
@@ -254,6 +254,10 @@ export function getOptionalOnboarding({ availableScripts, packageManager, templa
             availableScripts,
             compoundPersistenceEnabled,
         }),
+        shortNote: getOptionalOnboardingShortNote(packageManager, templateId, {
+            availableScripts,
+            compoundPersistenceEnabled,
+        }),
         steps: getOptionalOnboardingSteps(packageManager, templateId, {
             availableScripts,
             compoundPersistenceEnabled,