@wp-typia/project-tools 0.22.7 → 0.22.9

package/dist/runtime/cli-add-workspace-assets.js

@@ -1,15 +1,17 @@
-import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { syncBlockMetadata, } from "@wp-typia/block-runtime/metadata-core";
 import ts from "typescript";
 import { resolveWorkspaceProject, } from "./workspace-project.js";
-import { readWorkspaceInventory, appendWorkspaceInventoryEntries, } from "./workspace-inventory.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
 import { findPhpFunctionRange, hasPhpFunctionDefinition, quotePhpString, replacePhpFunctionDefinition, } from "./php-utils.js";
 import { assertBindingSourceDoesNotExist, assertEditorPluginDoesNotExist, assertPatternDoesNotExist, assertValidEditorPluginSlot, assertValidGeneratedSlug, getWorkspaceBootstrapPath, normalizeBlockSlug, patchFile, quoteTsString, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
 import { appendPhpSnippetBeforeClosingTag, insertPhpSnippetBeforeWorkspaceAnchors, } from "./cli-add-workspace-mutation.js";
+import { resolveWorkspaceBlockTargetName } from "./block-targets.js";
+import { pathExists, readOptionalUtf8File } from "./fs-async.js";
 import { normalizeOptionalCliString } from "./cli-validation.js";
+import { getPropertyNameText } from "./ts-property-names.js";
 const PATTERN_BOOTSTRAP_CATEGORY = "register_block_pattern_category";
 const BINDING_SOURCE_SERVER_GLOB = "/src/bindings/*/server.php";
 const BINDING_SOURCE_EDITOR_SCRIPT = "build/bindings/index.js";
@@ -48,26 +50,6 @@ function assertValidBindingAttributeName(attributeName) {
     }
     return trimmed;
 }
-function resolveBindingTargetBlockSlug(blockName, namespace) {
-    const trimmed = blockName.trim();
-    if (!trimmed) {
-        throw new Error("`wp-typia add binding-source` requires --block <block-slug|namespace/block-slug> to include a value when --attribute is provided.");
-    }
-    const blockNameSegments = trimmed.split("/");
-    if (blockNameSegments.length > 2) {
-        throw new Error(`Binding target block "${trimmed}" must use <block-slug> or <namespace/block-slug> format.`);
-    }
-    if (blockNameSegments.some((segment) => segment.trim() === "")) {
-        throw new Error(`Binding target block "${trimmed}" must use <block-slug> or <namespace/block-slug> format without empty path segments.`);
-    }
-    const [maybeNamespace, maybeSlug] = blockNameSegments.length === 2
-        ? blockNameSegments
-        : [undefined, blockNameSegments[0]];
-    if (maybeNamespace && maybeNamespace !== namespace) {
-        throw new Error(`Binding target block "${trimmed}" uses namespace "${maybeNamespace}". Expected "${namespace}".`);
-    }
-    return normalizeBlockSlug(maybeSlug ?? "");
-}
 function buildEditorPluginConfigEntry(editorPluginSlug, slot) {
     return [
         "\t{",
@@ -237,9 +219,15 @@ function resolveBindingTarget(options, namespace) {
     if (!hasBlock || !hasAttribute) {
         throw new Error("`wp-typia add binding-source` requires --block and --attribute to be provided together.");
     }
+    const targetBlock = resolveWorkspaceBlockTargetName(blockName ?? "", namespace, {
+        empty: () => "`wp-typia add binding-source` requires --block <block-slug|namespace/block-slug> to include a value when --attribute is provided.",
+        emptySegment: (input) => `Binding target block "${input}" must use <block-slug> or <namespace/block-slug> format without empty path segments.`,
+        invalidFormat: (input) => `Binding target block "${input}" must use <block-slug> or <namespace/block-slug> format.`,
+        namespaceMismatch: (input, actualNamespace, expectedNamespace) => `Binding target block "${input}" uses namespace "${actualNamespace}". Expected "${expectedNamespace}".`,
+    });
     return {
         attributeName: assertValidBindingAttributeName(attributeName ?? ""),
-        blockSlug: resolveBindingTargetBlockSlug(blockName ?? "", namespace),
+        blockSlug: targetBlock.blockSlug,
     };
 }
 function formatBindingAttributeTypeMember(attributeName) {
@@ -266,12 +254,6 @@ function getInterfaceDeclaration(source, interfaceName) {
     visit(sourceFile);
     return declaration ? { declaration, sourceFile } : undefined;
 }
-function getPropertyNameText(name) {
-    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
-        return name.text;
-    }
-    return undefined;
-}
 function interfaceHasAttributeMember(declaration, attributeName) {
     return declaration.members.some((member) => ts.isPropertySignature(member) &&
         member.name !== undefined &&
@@ -722,41 +704,53 @@ async function ensureEditorPluginWebpackAnchors(workspace) {
         return nextSource;
     });
 }
-function resolveBindingSourceRegistryPath(projectDir) {
+async function resolveBindingSourceRegistryPath(projectDir) {
     const bindingsDir = path.join(projectDir, "src", "bindings");
-    return [path.join(bindingsDir, "index.ts"), path.join(bindingsDir, "index.js")].find((candidatePath) => fs.existsSync(candidatePath)) ?? path.join(bindingsDir, "index.ts");
+    for (const candidatePath of [
+        path.join(bindingsDir, "index.ts"),
+        path.join(bindingsDir, "index.js"),
+    ]) {
+        if (await pathExists(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return path.join(bindingsDir, "index.ts");
 }
 async function writeBindingSourceRegistry(projectDir, bindingSourceSlug) {
     const bindingsDir = path.join(projectDir, "src", "bindings");
-    const bindingsIndexPath = resolveBindingSourceRegistryPath(projectDir);
+    const bindingsIndexPath = await resolveBindingSourceRegistryPath(projectDir);
     await fsp.mkdir(bindingsDir, { recursive: true });
-    const existingBindingSourceSlugs = fs
-        .readdirSync(bindingsDir, { withFileTypes: true })
+    const existingBindingSourceSlugs = (await fsp.readdir(bindingsDir, { withFileTypes: true }))
         .filter((entry) => entry.isDirectory())
         .map((entry) => entry.name);
     const nextBindingSourceSlugs = Array.from(new Set([...existingBindingSourceSlugs, bindingSourceSlug])).sort();
     await fsp.writeFile(bindingsIndexPath, buildBindingSourceIndexSource(nextBindingSourceSlugs), "utf8");
 }
-function resolveEditorPluginRegistryPath(projectDir) {
+async function resolveEditorPluginRegistryPath(projectDir) {
     const editorPluginsDir = path.join(projectDir, "src", "editor-plugins");
-    return [
+    for (const candidatePath of [
         path.join(editorPluginsDir, "index.ts"),
         path.join(editorPluginsDir, "index.js"),
-    ].find((candidatePath) => fs.existsSync(candidatePath)) ?? path.join(editorPluginsDir, "index.ts");
+    ]) {
+        if (await pathExists(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return path.join(editorPluginsDir, "index.ts");
 }
-function readEditorPluginRegistrySlugs(registryPath) {
-    if (!fs.existsSync(registryPath)) {
+async function readEditorPluginRegistrySlugs(registryPath) {
+    const source = await readOptionalUtf8File(registryPath);
+    if (source === null) {
         return [];
     }
-    const source = fs.readFileSync(registryPath, "utf8");
     return Array.from(source.matchAll(/^\s*import\s+['"]\.\/([^/'"]+)(?:\/index(?:\.[cm]?[jt]sx?)?)?['"];?\s*$/gmu)).map((match) => match[1]);
 }
 async function writeEditorPluginRegistry(projectDir, editorPluginSlug) {
     const editorPluginsDir = path.join(projectDir, "src", "editor-plugins");
-    const registryPath = resolveEditorPluginRegistryPath(projectDir);
+    const registryPath = await resolveEditorPluginRegistryPath(projectDir);
     await fsp.mkdir(editorPluginsDir, { recursive: true });
-    const existingEditorPluginSlugs = readWorkspaceInventory(projectDir).editorPlugins.map((entry) => entry.slug);
-    const existingRegistrySlugs = readEditorPluginRegistrySlugs(registryPath);
+    const existingEditorPluginSlugs = (await readWorkspaceInventoryAsync(projectDir)).editorPlugins.map((entry) => entry.slug);
+    const existingRegistrySlugs = await readEditorPluginRegistrySlugs(registryPath);
     const nextEditorPluginSlugs = Array.from(new Set([...existingEditorPluginSlugs, ...existingRegistrySlugs, editorPluginSlug])).sort();
     await fsp.writeFile(registryPath, buildEditorPluginRegistrySource(nextEditorPluginSlugs), "utf8");
 }
@@ -779,12 +773,12 @@ export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPlu
     const workspace = resolveWorkspaceProject(cwd);
     const editorPluginSlug = assertValidGeneratedSlug("Editor plugin name", normalizeBlockSlug(editorPluginName), "wp-typia add editor-plugin <name> [--slot <sidebar|document-setting-panel>]");
     const resolvedSlot = assertValidEditorPluginSlot(slot);
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     assertEditorPluginDoesNotExist(workspace.projectDir, editorPluginSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);
     const buildScriptPath = path.join(workspace.projectDir, "scripts", "build-workspace.mjs");
-    const editorPluginsIndexPath = resolveEditorPluginRegistryPath(workspace.projectDir);
+    const editorPluginsIndexPath = await resolveEditorPluginRegistryPath(workspace.projectDir);
     const webpackConfigPath = path.join(workspace.projectDir, "webpack.config.js");
     const editorPluginDir = path.join(workspace.projectDir, "src", "editor-plugins", editorPluginSlug);
     const entryFilePath = path.join(editorPluginDir, "index.tsx");
@@ -848,7 +842,7 @@ export async function runAddEditorPluginCommand({ cwd = process.cwd(), editorPlu
 export async function runAddPatternCommand({ cwd = process.cwd(), patternName, }) {
     const workspace = resolveWorkspaceProject(cwd);
     const patternSlug = assertValidGeneratedSlug("Pattern name", normalizeBlockSlug(patternName), "wp-typia add pattern <name>");
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     assertPatternDoesNotExist(workspace.projectDir, patternSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);
@@ -898,7 +892,7 @@ export async function runAddPatternCommand({ cwd = process.cwd(), patternName, }
 export async function runAddBindingSourceCommand({ attributeName, bindingSourceName, blockName, cwd = process.cwd(), }) {
     const workspace = resolveWorkspaceProject(cwd);
     const bindingSourceSlug = assertValidGeneratedSlug("Binding source name", normalizeBlockSlug(bindingSourceName), "wp-typia add binding-source <name> [--block <block-slug|namespace/block-slug> --attribute <attribute>]");
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     assertBindingSourceDoesNotExist(workspace.projectDir, bindingSourceSlug, inventory);
     const target = resolveBindingTarget({
         attributeName,
@@ -907,7 +901,7 @@ export async function runAddBindingSourceCommand({ attributeName, bindingSourceN
     const targetBlock = target ? resolveWorkspaceBlock(inventory, target.blockSlug) : undefined;
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);
-    const bindingsIndexPath = resolveBindingSourceRegistryPath(workspace.projectDir);
+    const bindingsIndexPath = await resolveBindingSourceRegistryPath(workspace.projectDir);
     const bindingSourceDir = path.join(workspace.projectDir, "src", "bindings", bindingSourceSlug);
     const serverFilePath = path.join(bindingSourceDir, "server.php");
     const editorFilePath = path.join(bindingSourceDir, "editor.ts");

package/dist/runtime/cli-add-workspace-rest.js

@@ -7,7 +7,7 @@ import { buildRestResourceApiSource, buildRestResourceConfigEntry, buildRestReso
 import { quotePhpString } from "./php-utils.js";
 import { syncRestResourceArtifacts } from "./rest-resource-artifacts.js";
 import { toPascalCase, toTitleCase } from "./string-case.js";
-import { appendWorkspaceInventoryEntries, readWorkspaceInventory, } from "./workspace-inventory.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
 function buildRestResourceRouteRegistrations(restResourceSlug, methods, functions) {
     const collectionRoutes = [];
@@ -434,7 +434,7 @@ export async function runAddRestResourceCommand({ cwd = process.cwd(), methods,
     const restResourceSlug = assertValidGeneratedSlug("REST resource name", normalizeBlockSlug(restResourceName), "wp-typia add rest-resource <name> [--namespace <vendor/v1>] [--methods <list,read,create>]");
     const resolvedMethods = assertValidRestResourceMethods(methods);
     const resolvedNamespace = resolveRestResourceNamespace(workspace.workspace.namespace, namespace);
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     assertRestResourceDoesNotExist(workspace.projectDir, restResourceSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
     const bootstrapPath = getWorkspaceBootstrapPath(workspace);

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

@@ -1,8 +1,9 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { pathExists } from "./fs-async.js";
+import { assertFullBlockName, resolveWorkspaceTargetBlockName, } from "./block-targets.js";
 import { resolveWorkspaceProject } from "./workspace-project.js";
-import { appendWorkspaceInventoryEntries, readWorkspaceInventory } from "./workspace-inventory.js";
+import { appendWorkspaceInventoryEntries, readWorkspaceInventoryAsync, } from "./workspace-inventory.js";
 import { toKebabCase, toSnakeCase, toTitleCase } from "./string-case.js";
 import { assertBlockStyleDoesNotExist, assertBlockTransformDoesNotExist, assertValidGeneratedSlug, assertValidHookAnchor, assertValidHookedBlockPosition, assertVariationDoesNotExist, getMutableBlockHooks, normalizeBlockSlug, patchFile, quoteTsString, readWorkspaceBlockJson, resolveWorkspaceBlock, rollbackWorkspaceMutation, snapshotWorkspaceFiles, } from "./cli-add-shared.js";
 import { findExecutablePatternMatch, hasExecutablePattern, hasUncommentedPattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
@@ -19,7 +20,6 @@ const BLOCK_TRANSFORMS_IMPORT_PATTERN = /^\s*import\s*\{\s*applyWorkspaceBlockTr
 const BLOCK_TRANSFORMS_CALL_LINE = "applyWorkspaceBlockTransforms(registration.settings);";
 const BLOCK_TRANSFORMS_CALL_PATTERN = /applyWorkspaceBlockTransforms\s*\(\s*registration\s*\.\s*settings\s*\)\s*;?/u;
 const SCAFFOLD_REGISTRATION_SETTINGS_CALL_PATTERN = /registerScaffoldBlockType\s*\(\s*registration\s*\.\s*name\s*,\s*registration\s*\.\s*settings\s*\)\s*;?/u;
-const FULL_BLOCK_NAME_PATTERN = /^[a-z0-9-]+\/[a-z0-9-]+$/u;
 function isIdentifierBoundary(source, index) {
     if (index < 0 || index >= source.length) {
         return true;
@@ -407,38 +407,6 @@ async function writeBlockTransformRegistry(projectDir, blockSlug, transformSlug)
     const nextTransformSlugs = Array.from(new Set([...existingTransformSlugs, transformSlug])).sort();
     await fsp.writeFile(transformsIndexPath, buildBlockTransformIndexSource(nextTransformSlugs), "utf8");
 }
-function assertFullBlockName(blockName, flagName) {
-    const trimmed = blockName.trim();
-    if (!trimmed) {
-        throw new Error(`\`${flagName}\` requires a block name.`);
-    }
-    if (!FULL_BLOCK_NAME_PATTERN.test(trimmed)) {
-        throw new Error(`\`${flagName}\` must use <namespace/block-slug> format.`);
-    }
-    return trimmed;
-}
-function resolveWorkspaceTargetBlockName(blockName, namespace, flagName) {
-    const trimmed = blockName.trim();
-    if (!trimmed) {
-        throw new Error(`\`${flagName}\` requires <block-slug|namespace/block-slug>.`);
-    }
-    const blockNameSegments = trimmed.split("/");
-    if (blockNameSegments.length > 2 ||
-        blockNameSegments.some((segment) => segment.trim() === "")) {
-        throw new Error(`\`${flagName}\` must use <block-slug|namespace/block-slug> format.`);
-    }
-    const [maybeNamespace, maybeSlug] = blockNameSegments.length === 2
-        ? blockNameSegments
-        : [undefined, blockNameSegments[0]];
-    if (maybeNamespace && maybeNamespace !== namespace) {
-        throw new Error(`\`${flagName}\` references namespace "${maybeNamespace}". Expected "${namespace}".`);
-    }
-    const blockSlug = normalizeBlockSlug(maybeSlug ?? "");
-    return {
-        blockName: `${namespace}/${blockSlug}`,
-        blockSlug,
-    };
-}
 /**
  * Re-export the DataViews admin screen scaffold workflow from the focused
  * admin-view runtime helper module.
@@ -484,7 +452,7 @@ export async function runAddVariationCommand({ blockName, cwd = process.cwd(), v
     const workspace = resolveWorkspaceProject(cwd);
     const blockSlug = normalizeBlockSlug(blockName);
     const variationSlug = assertValidGeneratedSlug("Variation name", normalizeBlockSlug(variationName), "wp-typia add variation <name> --block <block-slug>");
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     resolveWorkspaceBlock(inventory, blockSlug);
     assertVariationDoesNotExist(workspace.projectDir, blockSlug, variationSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
@@ -544,7 +512,7 @@ export async function runAddBlockStyleCommand({ blockName, cwd = process.cwd(),
     const workspace = resolveWorkspaceProject(cwd);
     const blockSlug = normalizeBlockSlug(blockName);
     const styleSlug = assertValidGeneratedSlug("Style name", normalizeBlockSlug(styleName), "wp-typia add style <name> --block <block-slug>");
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     resolveWorkspaceBlock(inventory, blockSlug);
     assertBlockStyleDoesNotExist(workspace.projectDir, blockSlug, styleSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
@@ -613,7 +581,7 @@ export async function runAddBlockTransformCommand({ cwd = process.cwd(), fromBlo
     const transformSlug = assertValidGeneratedSlug("Transform name", normalizeBlockSlug(transformName), "wp-typia add transform <name> --from <namespace/block> --to <block-slug|namespace/block-slug>");
     const resolvedFromBlockName = assertFullBlockName(fromBlockName, "--from");
     const target = resolveWorkspaceTargetBlockName(toBlockName, workspace.workspace.namespace, "--to");
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     resolveWorkspaceBlock(inventory, target.blockSlug);
     assertBlockTransformDoesNotExist(workspace.projectDir, target.blockSlug, transformSlug, inventory);
     const blockConfigPath = path.join(workspace.projectDir, "scripts", "block-config.ts");
@@ -684,7 +652,7 @@ export async function runAddBlockTransformCommand({ cwd = process.cwd(), fromBlo
 export async function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd = process.cwd(), position, }) {
     const workspace = resolveWorkspaceProject(cwd);
     const blockSlug = normalizeBlockSlug(blockName);
-    const inventory = readWorkspaceInventory(workspace.projectDir);
+    const inventory = await readWorkspaceInventoryAsync(workspace.projectDir);
     resolveWorkspaceBlock(inventory, blockSlug);
     const resolvedAnchorBlockName = assertValidHookAnchor(anchorBlockName);
     const resolvedPosition = assertValidHookedBlockPosition(position);

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-diagnostics.js

@@ -226,6 +226,12 @@ export function createCliDiagnosticCodeError(code, message, options) {
     error.code = code;
     return error;
 }
+/**
+ * Compatibility-only fallback for legacy or third-party errors that have not
+ * yet been tagged by their throw site. New user-facing failures should pass an
+ * explicit code through `createCliDiagnosticCodeError()` or
+ * `createCliCommandError({ code })` instead of relying on message matching.
+ */
 function inferCliDiagnosticCode(options) {
     const inheritedCode = readCliDiagnosticCode(options.error);
     if (inheritedCode) {

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

@@ -70,6 +70,8 @@ export function getWorkspaceDoctorChecks(cwd) {
     }
     checks.push(getWorkspacePackageMetadataCheck(workspace, workspacePackageJson));
     try {
+        // Doctor checks expose a synchronous API so callers can collect a stable
+        // snapshot without mixing async inventory reads into check aggregation.
         const inventory = readWorkspaceInventory(workspace.projectDir);
         checks.push(createDoctorCheck("Workspace inventory", "pass", formatWorkspaceInventorySummary(inventory)));
         checks.push(...getWorkspaceBlockDoctorChecks(workspace, inventory));

package/dist/runtime/cli-scaffold.js

@@ -1,14 +1,15 @@
-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";
 import { parseAlternateRenderTargets } from "./alternate-render-targets.js";
 import { parseCompoundInnerBlocksPreset } from "./compound-inner-blocks.js";
+import { isCompoundPersistenceEnabled } from "./scaffold-template-variable-groups.js";
 import { formatInstallCommand, formatRunScript, } from "./package-managers.js";
 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";
@@ -31,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);
@@ -424,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)
@@ -444,7 +445,7 @@ export async function runScaffoldFlow({ projectInput, cwd = process.cwd(), templ
                 availableScripts,
                 packageManager: resolvedPackageManager,
                 templateId: resolvedTemplateId,
-                compoundPersistenceEnabled: resolvedResult.result.variables.compoundPersistenceEnabled === "true",
+                compoundPersistenceEnabled: isCompoundPersistenceEnabled(resolvedResult.result.variables),
             }),
             plan: resolvedResult.plan,
             projectDir,

package/dist/runtime/create-template-validation.d.ts

@@ -0,0 +1,10 @@
+export declare const CREATE_TEMPLATE_SELECTION_HINT: string;
+/**
+ * Validate an explicitly supplied create template id before entering the full
+ * scaffold flow.
+ *
+ * Built-in template ids and the workspace alias resolve immediately, common
+ * built-in typos keep suggestion diagnostics, and explicit external template
+ * locators remain deferred to the external template resolver.
+ */
+export declare function validateExplicitCreateTemplateId(templateId: string): string;

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

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { CLI_DIAGNOSTIC_CODES, createCliDiagnosticCodeError, } from "./cli-diagnostics.js";
+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,
+].join("|")}|./path|github:owner/repo/path[#ref]|npm-package>`;
+const TEMPLATE_SUGGESTION_IDS = [
+    ...TEMPLATE_IDS,
+    OFFICIAL_WORKSPACE_TEMPLATE_ALIAS,
+];
+const USER_FACING_TEMPLATE_IDS = [
+    ...TEMPLATE_IDS,
+    OFFICIAL_WORKSPACE_TEMPLATE_ALIAS,
+];
+function normalizeCreateTemplateSelection(templateId) {
+    return templateId === OFFICIAL_WORKSPACE_TEMPLATE_ALIAS
+        ? OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE
+        : templateId;
+}
+function looksLikeWindowsAbsoluteTemplatePath(templateId) {
+    return /^[a-z]:[\\/]/iu.test(templateId) || /^\\\\[^\\]+\\[^\\]+/u.test(templateId);
+}
+function looksLikeExplicitNonNpmExternalTemplateLocator(templateId) {
+    return (path.isAbsolute(templateId) ||
+        looksLikeWindowsAbsoluteTemplatePath(templateId) ||
+        templateId.startsWith("./") ||
+        templateId.startsWith(".\\") ||
+        templateId.startsWith("../") ||
+        templateId.startsWith("..\\") ||
+        templateId.startsWith("@") ||
+        templateId.startsWith("github:") ||
+        templateId.includes("/") ||
+        templateId.includes("\\"));
+}
+function looksLikeExplicitCreateExternalTemplateLocator(templateId) {
+    return (looksLikeExplicitNonNpmExternalTemplateLocator(templateId) ||
+        parseNpmTemplateLocator(templateId) !== null);
+}
+function findMistypedBuiltInTemplateSuggestion(templateId) {
+    const normalizedTemplateId = templateId.trim().toLowerCase();
+    if (normalizedTemplateId.length === 0 ||
+        looksLikeExplicitNonNpmExternalTemplateLocator(normalizedTemplateId)) {
+        return null;
+    }
+    return suggestCloseId(normalizedTemplateId, TEMPLATE_SUGGESTION_IDS);
+}
+function getMistypedBuiltInTemplateMessage(templateId) {
+    const suggestion = findMistypedBuiltInTemplateSuggestion(templateId);
+    if (!suggestion) {
+        return null;
+    }
+    const suggestionDescription = suggestion === OFFICIAL_WORKSPACE_TEMPLATE_ALIAS
+        ? "official workspace scaffold"
+        : "built-in scaffold";
+    return `Unknown template "${templateId}". Did you mean "${suggestion}"? Use \`--template ${suggestion}\` for the ${suggestionDescription}, or pass a local path, \`github:owner/repo/path[#ref]\`, or an npm package spec for an external template.`;
+}
+function getUnknownTemplateMessage(templateId) {
+    return [
+        `Unknown template "${templateId}". Expected one of: ${USER_FACING_TEMPLATE_IDS.join(", ")}.`,
+        "Run `wp-typia templates list` to inspect available templates.",
+        "Pass an explicit external template locator such as `./path`, `github:owner/repo/path[#ref]`, or `@scope/template` for custom templates.",
+    ].join(" ");
+}
+/**
+ * Validate an explicitly supplied create template id before entering the full
+ * scaffold flow.
+ *
+ * Built-in template ids and the workspace alias resolve immediately, common
+ * built-in typos keep suggestion diagnostics, and explicit external template
+ * locators remain deferred to the external template resolver.
+ */
+export function validateExplicitCreateTemplateId(templateId) {
+    const normalizedTemplateId = normalizeCreateTemplateSelection(templateId);
+    if (isRemovedBuiltInTemplateId(templateId)) {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, getRemovedBuiltInTemplateMessage(templateId));
+    }
+    if (normalizedTemplateId === OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE) {
+        return normalizedTemplateId;
+    }
+    if (isBuiltInTemplateId(normalizedTemplateId)) {
+        return getTemplateById(normalizedTemplateId).id;
+    }
+    const mistypedBuiltInTemplateMessage = getMistypedBuiltInTemplateMessage(templateId);
+    if (mistypedBuiltInTemplateMessage) {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, mistypedBuiltInTemplateMessage);
+    }
+    if (!looksLikeExplicitCreateExternalTemplateLocator(normalizedTemplateId)) {
+        throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.UNKNOWN_TEMPLATE, getUnknownTemplateMessage(templateId));
+    }
+    return normalizedTemplateId;
+}

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;
+}