@wp-typia/project-tools 0.22.6 → 0.22.8

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 fs from "node:fs";
 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;
@@ -381,8 +381,7 @@ async function writeVariationRegistry(projectDir, blockSlug, variationSlug) {
     const variationsDir = path.join(projectDir, "src", "blocks", blockSlug, "variations");
     const variationsIndexPath = path.join(variationsDir, "index.ts");
     await fsp.mkdir(variationsDir, { recursive: true });
-    const existingVariationSlugs = fs
-        .readdirSync(variationsDir)
+    const existingVariationSlugs = (await fsp.readdir(variationsDir))
         .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts")
         .map((entry) => entry.replace(/\.ts$/u, ""));
     const nextVariationSlugs = Array.from(new Set([...existingVariationSlugs, variationSlug])).sort();
@@ -392,8 +391,7 @@ async function writeBlockStyleRegistry(projectDir, blockSlug, styleSlug) {
     const stylesDir = path.join(projectDir, "src", "blocks", blockSlug, "styles");
     const stylesIndexPath = path.join(stylesDir, "index.ts");
     await fsp.mkdir(stylesDir, { recursive: true });
-    const existingStyleSlugs = fs
-        .readdirSync(stylesDir)
+    const existingStyleSlugs = (await fsp.readdir(stylesDir))
         .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts")
         .map((entry) => entry.replace(/\.ts$/u, ""));
     const nextStyleSlugs = Array.from(new Set([...existingStyleSlugs, styleSlug])).sort();
@@ -403,45 +401,12 @@ async function writeBlockTransformRegistry(projectDir, blockSlug, transformSlug)
     const transformsDir = path.join(projectDir, "src", "blocks", blockSlug, "transforms");
     const transformsIndexPath = path.join(transformsDir, "index.ts");
     await fsp.mkdir(transformsDir, { recursive: true });
-    const existingTransformSlugs = fs
-        .readdirSync(transformsDir)
+    const existingTransformSlugs = (await fsp.readdir(transformsDir))
         .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts")
         .map((entry) => entry.replace(/\.ts$/u, ""));
     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.
@@ -487,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");
@@ -495,7 +460,7 @@ export async function runAddVariationCommand({ blockName, cwd = process.cwd(), v
     const variationsDir = path.join(workspace.projectDir, "src", "blocks", blockSlug, "variations");
     const variationFilePath = path.join(variationsDir, `${variationSlug}.ts`);
     const variationsIndexPath = path.join(variationsDir, "index.ts");
-    const shouldRemoveVariationsDirOnRollback = !fs.existsSync(variationsDir);
+    const shouldRemoveVariationsDirOnRollback = !(await pathExists(variationsDir));
     const mutationSnapshot = {
         fileSources: await snapshotWorkspaceFiles([
             blockConfigPath,
@@ -547,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");
@@ -555,7 +520,7 @@ export async function runAddBlockStyleCommand({ blockName, cwd = process.cwd(),
     const stylesDir = path.join(workspace.projectDir, "src", "blocks", blockSlug, "styles");
     const styleFilePath = path.join(stylesDir, `${styleSlug}.ts`);
     const stylesIndexPath = path.join(stylesDir, "index.ts");
-    const shouldRemoveStylesDirOnRollback = !fs.existsSync(stylesDir);
+    const shouldRemoveStylesDirOnRollback = !(await pathExists(stylesDir));
     const mutationSnapshot = {
         fileSources: await snapshotWorkspaceFiles([
             blockConfigPath,
@@ -616,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");
@@ -624,7 +589,7 @@ export async function runAddBlockTransformCommand({ cwd = process.cwd(), fromBlo
     const transformsDir = path.join(workspace.projectDir, "src", "blocks", target.blockSlug, "transforms");
     const transformFilePath = path.join(transformsDir, `${transformSlug}.ts`);
     const transformsIndexPath = path.join(transformsDir, "index.ts");
-    const shouldRemoveTransformsDirOnRollback = !fs.existsSync(transformsDir);
+    const shouldRemoveTransformsDirOnRollback = !(await pathExists(transformsDir));
     const mutationSnapshot = {
         fileSources: await snapshotWorkspaceFiles([
             blockConfigPath,
@@ -687,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);
@@ -695,7 +660,7 @@ export async function runAddHookedBlockCommand({ anchorBlockName, blockName, cwd
     if (resolvedAnchorBlockName === selfHookAnchor) {
         throw new Error("`wp-typia add hooked-block` cannot hook a block relative to its own block name.");
     }
-    const { blockJson, blockJsonPath } = readWorkspaceBlockJson(workspace.projectDir, blockSlug);
+    const { blockJson, blockJsonPath } = await readWorkspaceBlockJson(workspace.projectDir, blockSlug);
     const blockJsonRelativePath = path.relative(workspace.projectDir, blockJsonPath);
     const blockHooks = getMutableBlockHooks(blockJson, blockJsonRelativePath);
     if (Object.prototype.hasOwnProperty.call(blockHooks, resolvedAnchorBlockName)) {

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-init-plan-presentation.d.ts

@@ -0,0 +1,16 @@
+import { type PackageManagerId } from "./package-managers.js";
+import type { InitCommandMode, InitPlanLayoutKind, InitPlanStatus, RetrofitInitPlan } from "./cli-init-types.js";
+export declare function buildInitPlanChangeSummary(changes: Pick<RetrofitInitPlan, "generatedArtifacts" | "packageChanges" | "plannedFiles">, options: {
+    includeGeneratedArtifacts: boolean;
+}): string[];
+export declare function buildInitPlanNextSteps(options: {
+    commandMode: InitCommandMode;
+    dependencyChangeCount: number;
+    hasPlannedChanges: boolean;
+    layoutKind: InitPlanLayoutKind;
+    packageManager: PackageManagerId;
+}): string[];
+export declare function buildRetrofitPlanSummary(options: {
+    commandMode: InitCommandMode;
+    status: InitPlanStatus;
+}): string;

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

@@ -0,0 +1,74 @@
+import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, } from "./package-managers.js";
+import { buildRequiredDevDependencyMapEntries, getWpTypiaCliSpecifier, } from "./cli-init-package-json.js";
+export function buildInitPlanChangeSummary(changes, options) {
+    const lines = [];
+    for (const dependencyChange of changes.packageChanges.addDevDependencies) {
+        lines.push(`devDependency ${dependencyChange.action} ${dependencyChange.name} -> ${dependencyChange.requiredValue}`);
+    }
+    if (changes.packageChanges.packageManagerField) {
+        lines.push(`packageManager ${changes.packageChanges.packageManagerField.action} -> ${changes.packageChanges.packageManagerField.requiredValue}`);
+    }
+    for (const scriptChange of changes.packageChanges.scripts) {
+        lines.push(`script ${scriptChange.action} ${scriptChange.name} -> ${scriptChange.requiredValue}`);
+    }
+    for (const filePlan of changes.plannedFiles) {
+        lines.push(`file ${filePlan.action} ${filePlan.path} (${filePlan.purpose})`);
+    }
+    if (options.includeGeneratedArtifacts) {
+        for (const artifactPath of changes.generatedArtifacts) {
+            lines.push(`generated artifact ${artifactPath}`);
+        }
+    }
+    return lines;
+}
+export function buildInitPlanNextSteps(options) {
+    const cliSpecifier = getWpTypiaCliSpecifier();
+    const syncTypesRun = formatRunScript(options.packageManager, "sync-types");
+    const syncRun = formatRunScript(options.packageManager, "sync");
+    const doctorRun = formatPackageExecCommand(options.packageManager, cliSpecifier, "doctor");
+    const migrationInitRun = formatPackageExecCommand(options.packageManager, cliSpecifier, "migrate init --current-migration-version v1");
+    const dependencyInstallCommand = formatAddDevDependenciesCommand(options.packageManager, buildRequiredDevDependencyMapEntries());
+    if (options.layoutKind === "unsupported") {
+        return [
+            "Align the project to one of the supported retrofit layouts listed below, then rerun `wp-typia init`.",
+            dependencyInstallCommand,
+            syncTypesRun,
+            doctorRun,
+        ];
+    }
+    if (options.commandMode === "apply") {
+        return [
+            ...(options.dependencyChangeCount > 0
+                ? [
+                    "Install or reinstall project dependencies so the retrofit sync scripts and metadata generators are available locally.",
+                    dependencyInstallCommand,
+                ]
+                : []),
+            syncRun,
+            doctorRun,
+            `Optional migration bootstrap: ${migrationInitRun}`,
+        ];
+    }
+    return [
+        ...(options.hasPlannedChanges
+            ? [
+                "Re-run `wp-typia init --apply` to write the planned package.json changes and helper files automatically.",
+                ...(options.dependencyChangeCount > 0 ? [dependencyInstallCommand] : []),
+            ]
+            : []),
+        syncRun,
+        doctorRun,
+        `Optional migration bootstrap: ${migrationInitRun}`,
+    ];
+}
+export function buildRetrofitPlanSummary(options) {
+    if (options.status === "already-initialized") {
+        return options.commandMode === "apply"
+            ? "This project already exposes the minimum wp-typia retrofit surface. No files were changed."
+            : "This project already exposes the minimum wp-typia retrofit surface.";
+    }
+    if (options.commandMode === "apply") {
+        return "Applied the minimum wp-typia retrofit surface so package.json and helper scripts are ready for the next install and sync run.";
+    }
+    return "This command previews the minimum wp-typia adoption layer for the current project without rewriting it into a full scaffold.";
+}

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

@@ -3,9 +3,10 @@ import path from "node:path";
 import { analyzeSourceTypes } from "@wp-typia/block-runtime/metadata-parser";
 import ts from "typescript";
 import { discoverMigrationInitLayout } from "./migration-project.js";
-import { formatAddDevDependenciesCommand, formatPackageExecCommand, formatRunScript, } from "./package-managers.js";
+import { formatPackageExecCommand, formatRunScript } from "./package-managers.js";
 import { toPascalCase } from "./string-case.js";
-import { buildDependencyChanges, buildPackageManagerFieldChange, buildRequiredDevDependencyMapEntries, buildScriptChanges, getWpTypiaCliSpecifier, hasExistingWpTypiaProjectSurface, readProjectPackageJson, resolveInitPackageManager, } from "./cli-init-package-json.js";
+import { buildDependencyChanges, buildPackageManagerFieldChange, buildScriptChanges, getWpTypiaCliSpecifier, hasExistingWpTypiaProjectSurface, readProjectPackageJson, resolveInitPackageManager, } from "./cli-init-package-json.js";
+import { buildInitPlanChangeSummary, buildInitPlanNextSteps, buildRetrofitPlanSummary, } from "./cli-init-plan-presentation.js";
 import { RETROFIT_APPLY_PREVIEW_NOTE, SUPPORTED_RETROFIT_LAYOUT_NOTE, } from "./cli-init-types.js";
 import { tryResolveWorkspaceProject } from "./workspace-project.js";
 function normalizeRelativePath(value) {
@@ -161,82 +162,9 @@ function buildPlannedFiles(projectDir, layoutKind) {
         },
     ];
 }
-function buildChangeSummary(changes, options) {
-    const lines = [];
-    for (const dependencyChange of changes.packageChanges.addDevDependencies) {
-        lines.push(`devDependency ${dependencyChange.action} ${dependencyChange.name} -> ${dependencyChange.requiredValue}`);
-    }
-    if (changes.packageChanges.packageManagerField) {
-        lines.push(`packageManager ${changes.packageChanges.packageManagerField.action} -> ${changes.packageChanges.packageManagerField.requiredValue}`);
-    }
-    for (const scriptChange of changes.packageChanges.scripts) {
-        lines.push(`script ${scriptChange.action} ${scriptChange.name} -> ${scriptChange.requiredValue}`);
-    }
-    for (const filePlan of changes.plannedFiles) {
-        lines.push(`file ${filePlan.action} ${filePlan.path} (${filePlan.purpose})`);
-    }
-    if (options.includeGeneratedArtifacts) {
-        for (const artifactPath of changes.generatedArtifacts) {
-            lines.push(`generated artifact ${artifactPath}`);
-        }
-    }
-    return lines;
-}
-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,
-        ];
-    }
-    if (options.commandMode === "apply") {
-        return [
-            ...(options.dependencyChangeCount > 0
-                ? [
-                    "Install or reinstall project dependencies so the retrofit sync scripts and metadata generators are available locally.",
-                    dependencyInstallCommand,
-                ]
-                : []),
-            syncRun,
-            doctorRun,
-            `Optional migration bootstrap: ${migrationInitRun}`,
-        ];
-    }
-    const steps = [
-        ...(options.hasPlannedChanges
-            ? [
-                "Re-run `wp-typia init --apply` to write the planned package.json changes and helper files automatically.",
-                ...(options.dependencyChangeCount > 0 ? [dependencyInstallCommand] : []),
-            ]
-            : []),
-        syncRun,
-        doctorRun,
-        `Optional migration bootstrap: ${migrationInitRun}`,
-    ];
-    return steps;
-}
-function buildRetrofitPlanSummary(options) {
-    if (options.status === "already-initialized") {
-        return options.commandMode === "apply"
-            ? "This project already exposes the minimum wp-typia retrofit surface. No files were changed."
-            : "This project already exposes the minimum wp-typia retrofit surface.";
-    }
-    if (options.commandMode === "apply") {
-        return "Applied the minimum wp-typia retrofit surface so package.json and helper scripts are ready for the next install and sync run.";
-    }
-    return "This command previews the minimum wp-typia adoption layer for the current project without rewriting it into a full scaffold.";
-}
 export function createRetrofitPlan(options) {
     const includeGeneratedArtifacts = options.commandMode === "preview-only";
-    const plannedChanges = buildChangeSummary({
+    const plannedChanges = buildInitPlanChangeSummary({
         generatedArtifacts: options.generatedArtifacts,
         packageChanges: options.packageChanges,
         plannedFiles: options.plannedFiles,
@@ -249,7 +177,7 @@ export function createRetrofitPlan(options) {
         detectedLayout: options.detectedLayout,
         generatedArtifacts: options.generatedArtifacts,
         nextSteps: options.nextSteps ??
-            buildNextSteps({
+            buildInitPlanNextSteps({
                 commandMode: options.commandMode,
                 dependencyChangeCount: options.packageChanges.addDevDependencies.length,
                 hasPlannedChanges: plannedChanges.length > 0,

package/dist/runtime/cli-scaffold.js

@@ -4,6 +4,7 @@ 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";
@@ -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;