@wp-typia/project-tools 0.22.8 → 0.22.10

package/dist/runtime/ai-artifacts.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { buildWordPressAiArtifacts, } from './wordpress-ai.js';
+import { getOptionalNodeErrorCode, isFileNotFoundError, } from './fs-async.js';
 export { buildWordPressAiArtifacts, buildWordPressAbilitiesDocument, projectWordPressAiSchema, } from './wordpress-ai.js';
 function normalizeGeneratedArtifactContent(content) {
     return content.replace(/\r\n?/g, '\n');
@@ -25,13 +26,11 @@ async function reconcileGeneratedAiArtifacts(artifacts, check) {
             }
         }
         catch (error) {
-            const code = error && typeof error === 'object' && 'code' in error
-                ? error.code
-                : undefined;
-            if (code === 'ENOENT') {
+            if (isFileNotFoundError(error)) {
                 issues.push(`- ${artifact.filePath} (missing)`);
                 continue;
             }
+            const code = getOptionalNodeErrorCode(error);
             issues.push(`- ${artifact.filePath} (unreadable: ${error instanceof Error ? error.message : code ?? 'unknown'})`);
         }
     }

package/dist/runtime/ai-feature-artifacts.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
 import { projectWordPressAiSchema } from "./ai-artifacts.js";
+import { isFileNotFoundError } from "./fs-async.js";
 function normalizeGeneratedArtifactContent(content) {
     return content.replace(/\r\n?/g, "\n");
 }
@@ -21,10 +22,7 @@ async function reconcileGeneratedArtifact(options) {
         }
     }
     catch (error) {
-        const code = error && typeof error === "object" && "code" in error
-            ? error.code
-            : undefined;
-        if (code === "ENOENT") {
+        if (isFileNotFoundError(error)) {
             throw new Error(`Generated AI feature artifact is missing: ${options.label} (${options.filePath}).`);
         }
         throw error;

package/dist/runtime/cli-add-block.js

@@ -9,7 +9,7 @@ import { copyInterpolatedDirectory, listInterpolatedDirectoryOutputs, } from "./
 import { appendWorkspaceInventoryEntries, } from "./workspace-inventory.js";
 import { createManagedTempRoot } from "./temp-roots.js";
 import { resolveWorkspaceProject, } from "./workspace-project.js";
-import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, patchFile, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
+import { ADD_BLOCK_TEMPLATE_IDS, buildWorkspacePhpPrefix, isAddBlockTemplateId, patchFile, readOptionalFile, rollbackWorkspaceMutation, snapshotWorkspaceFiles, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 import { resolveNonEmptyNormalizedBlockSlug, } from "./scaffold-identifiers.js";
 import { buildConfigEntries, buildMigrationBlocks, buildServerTemplateRoot, } from "./cli-add-block-config.js";
 import { COMPOUND_SHARED_SUPPORT_FILES, collectLegacyCompoundValidatorPaths, ensureBlockConfigCanAddRestManifests, ensureCompoundWorkspaceSupportFiles, } from "./cli-add-block-legacy-validator.js";
@@ -80,6 +80,13 @@ async function assertWorkspaceDependenciesInstalled(workspace) {
     }
     throw new Error(`Workspace dependencies have not been installed yet. Run \`${formatInstallCommand(workspace.packageManager)}\` from the workspace root before using \`wp-typia add block ...\`.`);
 }
+function getMistypedAddBlockTemplateMessage(templateId) {
+    const suggestion = suggestAddBlockTemplateId(templateId);
+    if (!suggestion) {
+        return null;
+    }
+    return `Unknown add-block template "${templateId}". Did you mean "${suggestion}"? Use \`--template ${suggestion}\`, or run \`wp-typia templates list\` to inspect available templates.`;
+}
 async function copyScaffoldedBlockSlice(projectDir, templateId, tempProjectDir, variables, legacyValidatorPaths = []) {
     if (templateId === "compound") {
         await ensureCompoundWorkspaceSupportFiles(projectDir, tempProjectDir, legacyValidatorPaths);
@@ -287,6 +294,10 @@ export async function runAddBlockCommand({ alternateRenderTargets, blockName, cw
         throw new Error("`wp-typia add block --template query-loop` is not supported. Query Loop is a create-time `core/query` variation scaffold, so use `wp-typia create <project-dir> --template query-loop` instead.");
     }
     if (!isAddBlockTemplateId(templateId)) {
+        const mistypedAddBlockTemplateMessage = getMistypedAddBlockTemplateMessage(templateId);
+        if (mistypedAddBlockTemplateMessage) {
+            throw new Error(mistypedAddBlockTemplateMessage);
+        }
         throw new Error(`Unknown add-block template "${templateId}". Expected one of: ${ADD_BLOCK_TEMPLATE_IDS.join(", ")}. Run \`wp-typia templates list\` to inspect available templates.`);
     }
     const resolvedTemplateId = templateId;

package/dist/runtime/cli-add-filesystem.js

@@ -1,5 +1,6 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
+import { readOptionalUtf8File } from "./fs-async.js";
 /**
  * Resolve the primary PHP bootstrap file for an official workspace.
  *
@@ -24,15 +25,7 @@ export async function patchFile(filePath, transform) {
  * Read a file when it exists and otherwise return `null`.
  */
 export async function readOptionalFile(filePath) {
-    try {
-        return await fsp.readFile(filePath, "utf8");
-    }
-    catch (error) {
-        if (isFileNotFoundError(error)) {
-            return null;
-        }
-        throw error;
-    }
+    return readOptionalUtf8File(filePath);
 }
 /**
  * Restore a file to its captured source, deleting it when the snapshot was `null`.
@@ -69,9 +62,3 @@ export async function rollbackWorkspaceMutation(snapshot) {
         await restoreOptionalFile(filePath, source);
     }
 }
-function isFileNotFoundError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === "ENOENT");
-}

package/dist/runtime/cli-add-types.d.ts

@@ -42,6 +42,14 @@ export declare const ADD_BLOCK_TEMPLATE_IDS: readonly ["basic", "interactivity",
  * Union of supported built-in block template ids.
  */
 export type AddBlockTemplateId = (typeof ADD_BLOCK_TEMPLATE_IDS)[number];
+/**
+ * Suggest the closest supported add-block template id for typo diagnostics.
+ *
+ * @param templateId Raw `wp-typia add block --template` value.
+ * @returns The closest supported template id when it is within the shared
+ * close-id threshold, otherwise `null`.
+ */
+export declare function suggestAddBlockTemplateId(templateId: string): AddBlockTemplateId | null;
 /**
  * Options for `wp-typia add variation`.
  *

package/dist/runtime/cli-add-types.js

@@ -1,3 +1,4 @@
+import { suggestCloseId } from "./id-suggestions.js";
 export { ADD_KIND_IDS } from "./cli-add-kind-ids.js";
 /**
  * Supported plugin-level REST resource methods accepted by
@@ -46,3 +47,15 @@ export const ADD_BLOCK_TEMPLATE_IDS = [
     "persistence",
     "compound",
 ];
+/**
+ * Suggest the closest supported add-block template id for typo diagnostics.
+ *
+ * @param templateId Raw `wp-typia add block --template` value.
+ * @returns The closest supported template id when it is within the shared
+ * close-id threshold, otherwise `null`.
+ */
+export function suggestAddBlockTemplateId(templateId) {
+    return suggestCloseId(templateId, ADD_BLOCK_TEMPLATE_IDS, {
+        maxDistance: 3,
+    });
+}

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

@@ -7,8 +7,9 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export type { AddBlockTemplateId, AddKindId, EditorPluginSlotId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
-export { getWorkspaceBlockSelectOptions } from "./workspace-inventory.js";
+export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";
+export type { WorkspaceBlockSelectOption } from "./workspace-inventory.js";

package/dist/runtime/cli-add.js

@@ -7,7 +7,7 @@
  * - `cli-add-block` for built-in block scaffolding
  * - `cli-add-workspace` for workspace mutation commands
  */
-export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, } from "./cli-add-shared.js";
+export { ADD_BLOCK_TEMPLATE_IDS, ADD_KIND_IDS, EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, isAddBlockTemplateId, suggestAddBlockTemplateId, } from "./cli-add-shared.js";
 export { runAddBlockCommand, seedWorkspaceMigrationProject, } from "./cli-add-block.js";
 export { runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, } from "./cli-add-workspace.js";
-export { getWorkspaceBlockSelectOptions } from "./workspace-inventory.js";
+export { getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, } from "./workspace-inventory.js";

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

@@ -11,7 +11,8 @@
  * `runAddAdminViewCommand` for DataViews-backed admin screen scaffolds,
  * `runAddAbilityCommand` for typed workflow ability scaffolds,
  * and `HOOKED_BLOCK_POSITION_IDS`,
- * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
+ * `getWorkspaceBlockSelectOptions`, `getWorkspaceBlockSelectOptionsAsync`, and
+ * `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
@@ -31,11 +32,12 @@
 export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export type { CompoundInnerBlocksPresetId } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export type { EditorPluginSlotId } from "./cli-add.js";
+export type { WorkspaceBlockSelectOption } from "./workspace-inventory.js";
 export type { HookedBlockPositionId } from "./hooked-blocks.js";
 export { formatHelpText } from "./cli-help.js";
 export { getNextSteps, getOptionalOnboarding, runScaffoldFlow, } from "./cli-scaffold.js";

package/dist/runtime/cli-core.js

@@ -11,7 +11,8 @@
  * `runAddAdminViewCommand` for DataViews-backed admin screen scaffolds,
  * `runAddAbilityCommand` for typed workflow ability scaffolds,
  * and `HOOKED_BLOCK_POSITION_IDS`,
- * `getWorkspaceBlockSelectOptions`, and `seedWorkspaceMigrationProject` for
+ * `getWorkspaceBlockSelectOptions`, `getWorkspaceBlockSelectOptionsAsync`, and
+ * `seedWorkspaceMigrationProject` for
  * explicit `wp-typia add` flows,
  * `runAddAiFeatureCommand` for server-owned WordPress AI feature scaffolds,
  * `runAddRestResourceCommand` for plugin-level REST resource scaffolds,
@@ -30,7 +31,7 @@
  */
 export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
-export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
+export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";
 export { HOOKED_BLOCK_POSITION_IDS } from "./hooked-blocks.js";
 export { formatHelpText } from "./cli-help.js";

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

@@ -90,6 +90,9 @@ export function resolveWorkspaceBootstrapPath(projectDir, packageName) {
  * @returns A passing or failing `DoctorCheck` describing any missing files.
  */
 export function checkExistingFiles(projectDir, label, filePaths) {
+    // Workspace category collectors remain synchronous pure mappers after the
+    // async inventory snapshot is loaded, so these small existence probes stay
+    // sync to preserve their current non-Promise APIs and output ordering.
     const missing = filePaths
         .filter((filePath) => typeof filePath === "string")
         .filter((filePath) => !fs.existsSync(path.join(projectDir, filePath)));

package/dist/runtime/cli-doctor-workspace.d.ts

@@ -15,4 +15,4 @@ import type { DoctorCheck } from "./cli-doctor.js";
  * @param cwd Working directory expected to host an official workspace.
  * @returns Ordered workspace check rows ready for CLI rendering.
  */
-export declare function getWorkspaceDoctorChecks(cwd: string): DoctorCheck[];
+export declare function getWorkspaceDoctorChecks(cwd: string): Promise<DoctorCheck[]>;

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

@@ -3,7 +3,7 @@ import { getWorkspaceBlockDoctorChecks, } from "./cli-doctor-workspace-blocks.js
 import { getWorkspaceFeatureDoctorChecks, } from "./cli-doctor-workspace-features.js";
 import { getMigrationWorkspaceHintCheck, getWorkspacePackageMetadataCheck, } from "./cli-doctor-workspace-package.js";
 import { createDoctorCheck, createDoctorScopeCheck, } from "./cli-doctor-workspace-shared.js";
-import { readWorkspaceInventory } from "./workspace-inventory.js";
+import { readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { getInvalidWorkspaceProjectReason, parseWorkspacePackageJson, tryResolveWorkspaceProject, } from "./workspace-project.js";
 function formatWorkspaceInventorySummary(inventory) {
     return [
@@ -36,11 +36,13 @@ function formatWorkspaceInventorySummary(inventory) {
  * @param cwd Working directory expected to host an official workspace.
  * @returns Ordered workspace check rows ready for CLI rendering.
  */
-export function getWorkspaceDoctorChecks(cwd) {
+export async function getWorkspaceDoctorChecks(cwd) {
     const checks = [];
     let workspace = null;
     let invalidWorkspaceReason = null;
     try {
+        // Workspace discovery and package parsing intentionally stay synchronous
+        // because they share compatibility helpers with sync add/migration callers.
         invalidWorkspaceReason = getInvalidWorkspaceProjectReason(cwd);
         workspace = tryResolveWorkspaceProject(cwd);
     }
@@ -62,6 +64,9 @@ export function getWorkspaceDoctorChecks(cwd) {
     checks.push(createDoctorScopeCheck("pass", `Scope: full workspace diagnostics for ${workspace.workspace.namespace}. Environment readiness checks ran and workspace-scoped diagnostics are enabled for the package metadata, inventory, source-tree drift, and any configured migration hint rows below.`));
     let workspacePackageJson;
     try {
+        // Keep package metadata parsing sync until workspace-project exposes an
+        // async companion; the surrounding doctor orchestration already awaits
+        // async inventory reads below.
         workspacePackageJson = parseWorkspacePackageJson(workspace.projectDir);
     }
     catch (error) {
@@ -70,7 +75,7 @@ export function getWorkspaceDoctorChecks(cwd) {
     }
     checks.push(getWorkspacePackageMetadataCheck(workspace, workspacePackageJson));
     try {
-        const inventory = readWorkspaceInventory(workspace.projectDir);
+        const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
         checks.push(createDoctorCheck("Workspace inventory", "pass", formatWorkspaceInventorySummary(inventory)));
         checks.push(...getWorkspaceBlockDoctorChecks(workspace, inventory));
         checks.push(...getWorkspaceBindingDoctorChecks(workspace, inventory));

package/dist/runtime/cli-doctor.js

@@ -15,7 +15,7 @@ import { getWorkspaceDoctorChecks } from "./cli-doctor-workspace.js";
 export async function getDoctorChecks(cwd) {
     return [
         ...(await getEnvironmentDoctorChecks(cwd)),
-        ...getWorkspaceDoctorChecks(cwd),
+        ...(await getWorkspaceDoctorChecks(cwd)),
     ];
 }
 /**

package/dist/runtime/cli-scaffold.js

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { collectScaffoldAnswers, DATA_STORAGE_MODES, PERSISTENCE_POLICIES, isDataStorageMode, isPersistencePolicy, resolvePackageManagerId, resolveTemplateId, scaffoldProject, } from "./scaffold.js";
@@ -10,6 +9,7 @@ import { getPrimaryDevelopmentScript } from "./local-dev-presets.js";
 import { createManagedTempRoot } from "./temp-roots.js";
 import { getOptionalOnboardingNote, getOptionalOnboardingShortNote, getOptionalOnboardingSteps, } from "./scaffold-onboarding.js";
 import { formatNonEmptyTargetDirectoryError } from "./scaffold-bootstrap.js";
+import { pathExists } from "./fs-async.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, isBuiltInTemplateId, } from "./template-registry.js";
 import { resolveOptionalInteractiveExternalLayerId, } from "./external-layer-selection.js";
 import { assertBuiltInTemplateVariantAllowed, resolveLocalCliPathOption, normalizeOptionalCliString, } from "./cli-validation.js";
@@ -32,7 +32,7 @@ async function listRelativeProjectFiles(rootDir) {
     return relativeFiles.sort((left, right) => left.localeCompare(right));
 }
 async function assertDryRunTargetDirectoryReady(projectDir, allowExistingDir) {
-    if (!fs.existsSync(projectDir) || allowExistingDir) {
+    if (!(await pathExists(projectDir)) || allowExistingDir) {
         return;
     }
     const entries = await fsp.readdir(projectDir);
@@ -425,7 +425,7 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
         let availableScripts;
         if (!dryRun) {
             try {
-                const parsedPackageJson = JSON.parse(fs.readFileSync(path.join(projectDir, "package.json"), "utf8"));
+                const parsedPackageJson = JSON.parse(await fsp.readFile(path.join(projectDir, "package.json"), "utf8"));
                 const scripts = parsedPackageJson.scripts &&
                     typeof parsedPackageJson.scripts === "object" &&
                     !Array.isArray(parsedPackageJson.scripts)

package/dist/runtime/create-template-validation.js

@@ -3,6 +3,7 @@ import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagn
 import { OFFICIAL_WORKSPACE_TEMPLATE_ALIAS, OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, TEMPLATE_IDS, getTemplateById, isBuiltInTemplateId, } from "./template-registry.js";
 import { getRemovedBuiltInTemplateMessage, isRemovedBuiltInTemplateId, } from "./template-defaults.js";
 import { parseNpmTemplateLocator } from "./template-source-locators.js";
+import { suggestCloseId } from "./id-suggestions.js";
 export const CREATE_TEMPLATE_SELECTION_HINT = `--template <${[
     ...TEMPLATE_IDS,
     OFFICIAL_WORKSPACE_TEMPLATE_ALIAS,
@@ -39,40 +40,13 @@ function looksLikeExplicitCreateExternalTemplateLocator(templateId) {
     return (looksLikeExplicitNonNpmExternalTemplateLocator(templateId) ||
         parseNpmTemplateLocator(templateId) !== null);
 }
-function getEditDistance(left, right) {
-    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-    const current = new Array(right.length + 1);
-    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
-        current[0] = leftIndex + 1;
-        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
-            const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
-            current[rightIndex + 1] = Math.min(current[rightIndex] + 1, previous[rightIndex + 1] + 1, previous[rightIndex] + substitutionCost);
-        }
-        for (let index = 0; index < current.length; index += 1) {
-            previous[index] = current[index];
-        }
-    }
-    return previous[right.length];
-}
 function findMistypedBuiltInTemplateSuggestion(templateId) {
     const normalizedTemplateId = templateId.trim().toLowerCase();
     if (normalizedTemplateId.length === 0 ||
         looksLikeExplicitNonNpmExternalTemplateLocator(normalizedTemplateId)) {
         return null;
     }
-    let bestCandidate = null;
-    for (const candidateId of TEMPLATE_SUGGESTION_IDS) {
-        const distance = getEditDistance(normalizedTemplateId, candidateId);
-        if (bestCandidate === null || distance < bestCandidate.distance) {
-            bestCandidate = {
-                distance,
-                id: candidateId,
-            };
-        }
-    }
-    return bestCandidate && bestCandidate.distance <= 2
-        ? bestCandidate.id
-        : null;
+    return suggestCloseId(normalizedTemplateId, TEMPLATE_SUGGESTION_IDS);
 }
 function getMistypedBuiltInTemplateMessage(templateId) {
     const suggestion = findMistypedBuiltInTemplateSuggestion(templateId);

package/dist/runtime/fs-async.d.ts

@@ -19,6 +19,13 @@ export declare function readOptionalUtf8File(filePath: string): Promise<string |
  * @returns The string error code, or an empty string when unavailable.
  */
 export declare function getNodeErrorCode(error: unknown): string;
+/**
+ * Extract a Node.js error code from an unknown thrown value when available.
+ *
+ * @param error Unknown error value.
+ * @returns The string error code, or `undefined` when unavailable.
+ */
+export declare function getOptionalNodeErrorCode(error: unknown): string | undefined;
 /**
  * Return whether an unknown error represents a missing filesystem path.
  *

package/dist/runtime/fs-async.js

@@ -38,9 +38,18 @@ export async function readOptionalUtf8File(filePath) {
  * @returns The string error code, or an empty string when unavailable.
  */
 export function getNodeErrorCode(error) {
+    return getOptionalNodeErrorCode(error) ?? "";
+}
+/**
+ * Extract a Node.js error code from an unknown thrown value when available.
+ *
+ * @param error Unknown error value.
+ * @returns The string error code, or `undefined` when unavailable.
+ */
+export function getOptionalNodeErrorCode(error) {
     return typeof error === "object" && error !== null && "code" in error
         ? String(error.code)
-        : "";
+        : undefined;
 }
 /**
  * Return whether an unknown error represents a missing filesystem path.
@@ -49,5 +58,5 @@ export function getNodeErrorCode(error) {
  * @returns `true` when the error has Node.js code `ENOENT`.
  */
 export function isFileNotFoundError(error) {
-    return getNodeErrorCode(error) === "ENOENT";
+    return getOptionalNodeErrorCode(error) === "ENOENT";
 }

package/dist/runtime/id-suggestions.d.ts

@@ -0,0 +1,21 @@
+export interface SuggestCloseIdOptions {
+    /**
+     * Maximum edit distance accepted for a suggestion.
+     *
+     * Defaults to `2`, matching the create-template typo guard.
+     */
+    maxDistance?: number;
+    /**
+     * Normalizes user input and candidates before comparing them.
+     *
+     * Defaults to trimming and lowercasing for CLI id-like values.
+     */
+    normalize?: (value: string) => string;
+}
+/**
+ * Suggest the closest known id for a user-provided CLI value.
+ *
+ * This helper is intentionally generic so command-specific validation can keep
+ * its own wording and special-case handling while sharing typo thresholds.
+ */
+export declare function suggestCloseId<const TCandidate extends string>(input: string, candidates: readonly TCandidate[], options?: SuggestCloseIdOptions): TCandidate | null;

package/dist/runtime/id-suggestions.js

@@ -0,0 +1,48 @@
+function normalizeCloseId(value) {
+    return value.trim().toLowerCase();
+}
+function getEditDistance(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    const current = new Array(right.length + 1);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        current[0] = leftIndex + 1;
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
+            current[rightIndex + 1] = Math.min(current[rightIndex] + 1, previous[rightIndex + 1] + 1, previous[rightIndex] + substitutionCost);
+        }
+        for (let index = 0; index < current.length; index += 1) {
+            previous[index] = current[index];
+        }
+    }
+    return previous[right.length];
+}
+/**
+ * Suggest the closest known id for a user-provided CLI value.
+ *
+ * This helper is intentionally generic so command-specific validation can keep
+ * its own wording and special-case handling while sharing typo thresholds.
+ */
+export function suggestCloseId(input, candidates, options = {}) {
+    const normalize = options.normalize ?? normalizeCloseId;
+    const normalizedInput = normalize(input);
+    if (normalizedInput.length === 0) {
+        return null;
+    }
+    const maxDistance = options.maxDistance ?? 2;
+    if (maxDistance < 0) {
+        return null;
+    }
+    let bestCandidate = null;
+    for (const candidateId of candidates) {
+        const distance = getEditDistance(normalizedInput, normalize(candidateId));
+        if (bestCandidate === null || distance < bestCandidate.distance) {
+            bestCandidate = {
+                distance,
+                id: candidateId,
+            };
+        }
+    }
+    return bestCandidate && bestCandidate.distance <= maxDistance
+        ? bestCandidate.id
+        : null;
+}

package/dist/runtime/index.d.ts

@@ -5,6 +5,7 @@
  * CLI while keeping reusable project logic out of the CLI package itself.
  * Consumers should prefer these exports for scaffold, add, migrate, doctor,
  * and workspace-aware helpers such as `getWorkspaceBlockSelectOptions`,
+ * `getWorkspaceBlockSelectOptionsAsync`,
  * `runAddBlockCommand`, `runAddBlockStyleCommand`,
  * `runAddBlockTransformCommand`, `runAddVariationCommand`,
  * `runAddPatternCommand`, `runAddBindingSourceCommand`,
@@ -29,11 +30,13 @@ export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJso
 export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 export type { EndpointAuthIntent, EndpointOpenApiAuthMode, EndpointOpenApiContractDocument, EndpointOpenApiDocumentOptions, EndpointOpenApiEndpointDefinition, EndpointOpenApiMethod, EndpointWordPressAuthDefinition, EndpointWordPressAuthMechanism, JsonSchemaDocument, JsonSchemaProjectionProfile, JsonSchemaObject, NormalizedEndpointAuthDefinition, OpenApiDocument, OpenApiInfo, OpenApiOperation, OpenApiParameter, OpenApiPathItem, OpenApiSecurityScheme, } from "./schema-core.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { suggestCloseId } from "./id-suggestions.js";
+export type { SuggestCloseIdOptions } from "./id-suggestions.js";
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export type { PackageVersions } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
 export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
 export type { ExternalTemplateCachePruneOptions, ExternalTemplateCachePruneResult, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
-export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
-export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, DoctorCheck, EditorPluginSlotId, HookedBlockPositionId, ReadlinePrompt, WorkspaceBlockSelectOption, } from "./cli-core.js";

package/dist/runtime/index.js

@@ -5,6 +5,7 @@
  * CLI while keeping reusable project logic out of the CLI package itself.
  * Consumers should prefer these exports for scaffold, add, migrate, doctor,
  * and workspace-aware helpers such as `getWorkspaceBlockSelectOptions`,
+ * `getWorkspaceBlockSelectOptionsAsync`,
  * `runAddBlockCommand`, `runAddBlockStyleCommand`,
  * `runAddBlockTransformCommand`, `runAddVariationCommand`,
  * `runAddPatternCommand`, `runAddBindingSourceCommand`,
@@ -23,8 +24,9 @@ export { parseWorkspacePackageManagerId, resolveWorkspaceProject, tryResolveWork
 export { manifestAttributeToJsonSchema, projectJsonSchemaDocument, manifestToJsonSchema, manifestToOpenApi, normalizeEndpointAuthDefinition, } from "./schema-core.js";
 export { buildCompoundChildStarterManifestDocument, getStarterManifestFiles, stringifyStarterManifest, } from "./starter-manifests.js";
 export { PACKAGE_MANAGER_IDS, PACKAGE_MANAGERS, formatPackageExecCommand, formatInstallCommand, formatRunScript, getPackageManager, getPackageManagerSelectOptions, transformPackageManagerText, } from "./package-managers.js";
+export { suggestCloseId } from "./id-suggestions.js";
 export { clearPackageVersionsCache, getPackageVersions, invalidatePackageVersionsCache, } from "./package-versions.js";
 export { TEMPLATE_IDS, TEMPLATE_REGISTRY, getTemplateById, getTemplateSelectOptions, listTemplates, } from "./template-registry.js";
 export { EXTERNAL_TEMPLATE_CACHE_TTL_DAYS_ENV, pruneExternalTemplateCache, } from "./template-source-cache.js";
 export { STALE_TEMP_ROOT_MAX_AGE_MS, WP_TYPIA_TEMP_ROOT_PREFIX, cleanupManagedTempRoot, cleanupStaleTempRoots, createManagedTempRoot, getTrackedTempRoots, } from "./temp-roots.js";
-export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";
+export { createReadlinePrompt, createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatAddHelpText, formatDoctorCheckLine, formatDoctorSummaryLine, formatHelpText, formatTemplateDetails, formatTemplateFeatures, formatTemplateSummary, getDoctorChecks, getDoctorFailureDetailLines, getFailingDoctorChecks, getNextSteps, getOptionalOnboarding, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, HOOKED_BLOCK_POSITION_IDS, EDITOR_PLUGIN_SLOT_IDS, isCliDiagnosticError, runAddAdminViewCommand, runAddAbilityCommand, runAddAiFeatureCommand, runAddBindingSourceCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runDoctor, runAddVariationCommand, runScaffoldFlow, } from "./cli-core.js";

package/dist/runtime/migration-maintenance-verify.js

@@ -59,6 +59,9 @@ export function verifyProjectMigrations(projectDir, { all = false, fromMigration
     return { verifiedVersions: targetVersions };
 }
 function recordWorkspaceMigrationTargetAlignment(projectDir, state, recordCheck) {
+    // `migrate doctor` is still a synchronous maintenance command: it shares
+    // sync migration project loading, generated artifact comparisons, and
+    // execFileSync verification with the rest of migration maintenance.
     let invalidWorkspaceReason = null;
     let workspace;
     try {
@@ -76,6 +79,8 @@ function recordWorkspaceMigrationTargetAlignment(projectDir, state, recordCheck)
         return;
     }
     try {
+        // Maintenance verification is intentionally synchronous so it can compare
+        // migration state against a single inventory snapshot.
         const inventory = readWorkspaceInventory(workspace.projectDir);
         const expectedTargets = inventory.blocks.map((block) => `${workspace.workspace.namespace}/${block.slug}`);
         const configuredTargets = state.blocks.map((block) => block.blockName);

package/dist/runtime/migration-render-generated.js

@@ -217,6 +217,10 @@ export function renderPhpMigrationRegistryFile(state, entries) {
     return `<?php
 declare(strict_types=1);
 
+if ( ! defined( 'ABSPATH' ) ) {
+\texit;
+}
+
 /**
  * Generated from advanced migration snapshots. Do not edit manually.
  */

package/dist/runtime/package-versions.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import { getOptionalNodeErrorCode } from './fs-async.js';
 import { PROJECT_TOOLS_PACKAGE_ROOT } from './template-registry.js';
 const require = createRequire(import.meta.url);
 const DEFAULT_VERSION_RANGE = '^0.0.0';
@@ -21,11 +22,6 @@ export const DEFAULT_WORDPRESS_DATA_VERSION = '^9.28.0';
 export const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = '^14.1.0';
 export const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = '^0.1.1';
 let cachedPackageVersions = null;
-function getErrorCode(error) {
-    return typeof error === 'object' && error !== null && 'code' in error
-        ? String(error.code)
-        : undefined;
-}
 function normalizeVersionRange(value) {
     const trimmed = value?.trim();
     if (!trimmed) {
@@ -82,7 +78,7 @@ function resolvePackageManifestLocation(packageJsonPath) {
         };
     }
     catch (error) {
-        if (getErrorCode(error) === 'ENOENT') {
+        if (getOptionalNodeErrorCode(error) === 'ENOENT') {
             return {
                 cacheKey: `missing-file:${packageJsonPath}`,
                 packageJsonPath: null,
@@ -114,7 +110,7 @@ function resolveInstalledPackageManifestLocation(packageName) {
         return resolvePackageManifestLocation(require.resolve(`${packageName}/package.json`));
     }
     catch (error) {
-        if (getErrorCode(error) === 'MODULE_NOT_FOUND') {
+        if (getOptionalNodeErrorCode(error) === 'MODULE_NOT_FOUND') {
             return {
                 cacheKey: `missing-module:${packageName}`,
                 packageJsonPath: null,