wp-typia 0.22.3 → 0.22.5

package/dist-bunli/node-cli.js

@@ -3,7 +3,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // package.json
 var package_default = {
   name: "wp-typia",
-  version: "0.22.3",
+  version: "0.22.5",
   description: "Canonical CLI package for wp-typia scaffolding and project workflows",
   packageManager: "bun@1.3.11",
   type: "module",
@@ -73,7 +73,7 @@ var package_default = {
     "@bunli/tui": "0.6.0",
     "@bunli/utils": "0.6.0",
     "@wp-typia/api-client": "^0.4.5",
-    "@wp-typia/project-tools": "0.22.3",
+    "@wp-typia/project-tools": "0.22.5",
     "better-result": "^2.7.0",
     react: "^19.2.5",
     "react-dom": "^19.2.5",
@@ -97,8 +97,8 @@ var package_default = {
 
 // src/node-cli.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES6,
-  createCliCommandError as createCliCommandError2,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES7,
+  createCliCommandError as createCliCommandError3,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError6,
   formatCliDiagnosticError,
   serializeCliDiagnosticError as serializeCliDiagnosticError2
@@ -336,7 +336,7 @@ var SYNC_OPTION_METADATA = {
 };
 var DOCTOR_OPTION_METADATA = {
   format: {
-    description: "Use `json` for machine-readable doctor check output.",
+    description: "Use `json` for machine-readable doctor check output or `text` for human-readable output.",
     type: "string"
   }
 };
@@ -353,7 +353,7 @@ var GLOBAL_OPTION_METADATA = {
     type: "string"
   },
   format: {
-    description: "Output format for supported commands.",
+    description: "Output format for supported commands (`json` or `text`).",
     type: "string"
   },
   id: {
@@ -580,7 +580,7 @@ function resolveCommandOptionValues(metadata, options) {
 
 // src/cli-diagnostic-output.ts
 import {
-  createCliCommandError,
+  createCliCommandError as createCliCommandError2,
   serializeCliDiagnosticError
 } from "@wp-typia/project-tools/cli-diagnostics";
 
@@ -624,6 +624,72 @@ function findFirstPositionalIndex(argv, metadata) {
   const positionalIndexes = collectPositionalIndexes(argv, metadata);
   return positionalIndexes[0] ?? -1;
 }
+function findFirstPositional(argv, metadata) {
+  const firstPositionalIndex = findFirstPositionalIndex(argv, metadata);
+  return firstPositionalIndex === -1 ? undefined : argv[firstPositionalIndex];
+}
+
+// src/cli-command-resolution.ts
+function resolveEntrypointCliCommand(argv) {
+  return findFirstPositional(argv, COMMAND_ROUTING_METADATA) ?? "wp-typia";
+}
+
+// src/cli-output-format.ts
+import {
+  CLI_DIAGNOSTIC_CODES,
+  createCliCommandError
+} from "@wp-typia/project-tools/cli-diagnostics";
+var PUBLIC_CLI_OUTPUT_FORMATS = ["json", "text"];
+var LEGACY_CLI_OUTPUT_FORMAT_ALIASES = ["toon"];
+var SUPPORTED_CLI_OUTPUT_FORMATS = [
+  ...PUBLIC_CLI_OUTPUT_FORMATS,
+  ...LEGACY_CLI_OUTPUT_FORMAT_ALIASES
+];
+var SUPPORTED_CLI_OUTPUT_FORMAT_VALUES = SUPPORTED_CLI_OUTPUT_FORMATS;
+function formatSupportedCliOutputFormats() {
+  return PUBLIC_CLI_OUTPUT_FORMATS.join(", ");
+}
+function isSupportedCliOutputFormat(value) {
+  return typeof value === "string" && SUPPORTED_CLI_OUTPUT_FORMAT_VALUES.includes(value);
+}
+function formatInvalidCliOutputFormatMessage(value) {
+  return `Invalid --format value "${value}". Supported values: ${formatSupportedCliOutputFormats()}.`;
+}
+function assertSupportedCliOutputFormat(value, argv) {
+  if (isSupportedCliOutputFormat(value)) {
+    return;
+  }
+  throw createCliCommandError({
+    code: CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT,
+    command: resolveEntrypointCliCommand(argv),
+    detailLines: [formatInvalidCliOutputFormatMessage(value)]
+  });
+}
+function validateCliOutputFormatArgv(argv) {
+  for (let index = 0;index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--") {
+      return;
+    }
+    if (arg === "--format") {
+      const next = argv[index + 1];
+      if (next && !next.startsWith("-")) {
+        assertSupportedCliOutputFormat(next, argv);
+        index += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith("--format=")) {
+      const value = arg.slice("--format=".length);
+      if (value) {
+        assertSupportedCliOutputFormat(value, argv);
+      }
+    }
+  }
+}
 
 // src/cli-diagnostic-output.ts
 function prefersStructuredCliArgv(argv) {
@@ -653,7 +719,7 @@ import {
 
 // src/add-kind-registry.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES2,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES3,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError2
 } from "@wp-typia/project-tools/cli-diagnostics";
 
@@ -675,7 +741,7 @@ var ADD_KIND_IDS = [
 
 // src/cli-string-flags.ts
 import {
-  CLI_DIAGNOSTIC_CODES,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES2,
   createCliDiagnosticCodeError
 } from "@wp-typia/project-tools/cli-diagnostics";
 function readOptionalCliStringFlagValue(flags, name, mode) {
@@ -684,12 +750,12 @@ function readOptionalCliStringFlagValue(flags, name, mode) {
     return;
   }
   if (typeof value !== "string") {
-    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
+    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
   }
   const trimmed = value.trim();
   if (trimmed.length === 0) {
     if (mode === "strict") {
-      throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
+      throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
     }
     return;
   }
@@ -704,7 +770,7 @@ function readOptionalStrictStringFlag(flags, name) {
 function requireStrictStringFlag(flags, name, message) {
   const value = readOptionalStrictStringFlag(flags, name);
   if (!value) {
-    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, message);
   }
   return value;
 }
@@ -712,7 +778,7 @@ function readOptionalPairedStrictStringFlags(flags, leftName, rightName, message
   const leftValue = readOptionalStrictStringFlag(flags, leftName);
   const rightValue = readOptionalStrictStringFlag(flags, rightName);
   if (Boolean(leftValue) !== Boolean(rightValue)) {
-    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, message);
   }
   return [leftValue, rightValue];
 }
@@ -793,7 +859,7 @@ var NAME_NAMESPACE_VISIBLE_FIELDS = [
 ];
 function requireAddKindName(context, message) {
   if (!context.name) {
-    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, message);
   }
   return context.name;
 }
@@ -812,6 +878,18 @@ function createNamedExecutionPlan(context, options) {
 function isAddPersistenceTemplate(template) {
   return template === "persistence" || template === "compound";
 }
+function formatAddBlockTemplateIds(addRuntime) {
+  return addRuntime.ADD_BLOCK_TEMPLATE_IDS.join(", ");
+}
+function assertAddBlockTemplateId(context, templateId) {
+  if (context.addRuntime.isAddBlockTemplateId(templateId)) {
+    return templateId;
+  }
+  if (templateId === "query-loop") {
+    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.INVALID_ARGUMENT, "`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.");
+  }
+  throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.UNKNOWN_TEMPLATE, `Unknown add-block template "${templateId}". Expected one of: ${formatAddBlockTemplateIds(context.addRuntime)}. Run \`wp-typia templates list\` to inspect available templates.`);
+}
 var ADD_KIND_REGISTRY = {
   "admin-view": defineAddKindRegistryEntry({
     completion: {
@@ -918,7 +996,8 @@ var ADD_KIND_REGISTRY = {
       const dataStorageMode = readOptionalStrictStringFlag(context.flags, "data-storage");
       const innerBlocksPreset = readOptionalStrictStringFlag(context.flags, "inner-blocks-preset");
       const persistencePolicy = readOptionalStrictStringFlag(context.flags, "persistence-policy");
-      let resolvedTemplateId = readOptionalStrictStringFlag(context.flags, "template");
+      const requestedTemplateId = readOptionalStrictStringFlag(context.flags, "template");
+      let resolvedTemplateId = requestedTemplateId ? assertAddBlockTemplateId(context, requestedTemplateId) : undefined;
       if (!resolvedTemplateId && context.isInteractiveSession) {
         const templatePrompt = await context.getOrCreatePrompt();
         resolvedTemplateId = await templatePrompt.select("Select a block template", context.addRuntime.ADD_BLOCK_TEMPLATE_IDS.map((templateId) => ({
@@ -1334,7 +1413,7 @@ import os from "node:os";
 import path from "node:path";
 import { isPlainObject as isRecord } from "@wp-typia/api-client/runtime-primitives";
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES3,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES4,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError3
 } from "@wp-typia/project-tools/cli-diagnostics";
 var WP_TYPIA_CONFIG_SOURCES = [
@@ -1372,7 +1451,7 @@ async function readJsonFile(filePath) {
     return isRecord(parsed) ? parsed : null;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES3.INVALID_ARGUMENT, `Unable to parse ${filePath}: ${message}`, error instanceof Error ? { cause: error } : undefined);
+    throw createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES4.INVALID_ARGUMENT, `Unable to parse ${filePath}: ${message}`, error instanceof Error ? { cause: error } : undefined);
   }
 }
 function resolveConfigPath(cwd, source) {
@@ -1425,7 +1504,7 @@ function extractWpTypiaConfigOverride(argv) {
 
 // src/runtime-bridge.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES5,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES6,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError5
 } from "@wp-typia/project-tools/cli-diagnostics";
 
@@ -1557,9 +1636,10 @@ async function simulateWorkspaceAddDryRun({
 }
 
 // src/runtime-bridge-output.ts
-import fs3 from "node:fs";
-import path3 from "node:path";
-import { formatPackageExecCommand } from "@wp-typia/project-tools/package-managers";
+import {
+  formatPackageExecCommand,
+  inferPackageManagerId
+} from "@wp-typia/project-tools/package-managers";
 
 // src/output-markers.ts
 var UNICODE_OUTPUT_MARKERS = {
@@ -1806,32 +1886,6 @@ function buildInitCompletionPayload(plan, markerOptions) {
     warningLines: plan.notes
   };
 }
-function inferProjectPackageManager(projectDir) {
-  try {
-    const packageJsonPath = path3.join(projectDir, "package.json");
-    if (fs3.existsSync(packageJsonPath)) {
-      const manifest = JSON.parse(fs3.readFileSync(packageJsonPath, "utf8"));
-      if (manifest.packageManager?.startsWith("bun@"))
-        return "bun";
-      if (manifest.packageManager?.startsWith("pnpm@"))
-        return "pnpm";
-      if (manifest.packageManager?.startsWith("yarn@"))
-        return "yarn";
-      if (manifest.packageManager?.startsWith("npm@"))
-        return "npm";
-    }
-  } catch {}
-  if (fs3.existsSync(path3.join(projectDir, "bun.lock")) || fs3.existsSync(path3.join(projectDir, "bun.lockb"))) {
-    return "bun";
-  }
-  if (fs3.existsSync(path3.join(projectDir, "pnpm-lock.yaml"))) {
-    return "pnpm";
-  }
-  if (fs3.existsSync(path3.join(projectDir, "yarn.lock")) || fs3.existsSync(path3.join(projectDir, ".yarnrc.yml"))) {
-    return "yarn";
-  }
-  return "npm";
-}
 function buildMigrationCompletionPayload(options, markerOptions) {
   const summaryLines = options.lines.filter((line) => line.trim().length > 0);
   return {
@@ -1841,7 +1895,7 @@ function buildMigrationCompletionPayload(options, markerOptions) {
 }
 function buildAddCompletionPayload(options, markerOptions) {
   const verificationLines = [
-    formatPackageExecCommand(options.packageManager ?? inferProjectPackageManager(options.projectDir), `wp-typia@${package_default.version}`, "doctor")
+    formatPackageExecCommand(options.packageManager ?? inferPackageManagerId(options.projectDir), `wp-typia@${package_default.version}`, "doctor")
   ];
   const verificationNote = "Run doctor via your package manager for a quick inventory and generated-artifact check after the add workflow.";
   const completion = buildAddKindCompletionDetails(options.kind, {
@@ -1902,12 +1956,17 @@ function isInteractiveTerminal({
 }
 // src/runtime-bridge-sync.ts
 import { spawnSync } from "node:child_process";
-import fs4 from "node:fs";
-import path4 from "node:path";
+import fs3 from "node:fs";
+import path3 from "node:path";
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES4,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES5,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError4
 } from "@wp-typia/project-tools/cli-diagnostics";
+import {
+  formatInstallCommand,
+  formatRunScript,
+  inferPackageManagerId as inferPackageManagerId2
+} from "@wp-typia/project-tools/package-managers";
 var SYNC_INSTALL_MARKERS = [
   "node_modules",
   ".pnp.cjs",
@@ -1922,66 +1981,17 @@ function resolveSyncExecutionTarget(subcommand) {
   if (subcommand === "ai") {
     return "ai";
   }
-  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES4.INVALID_COMMAND, `Unknown sync subcommand "${subcommand}". Expected one of: "ai".`);
-}
-function formatRunScript(packageManagerId, scriptName, extraArgs = "") {
-  const args = extraArgs.trim();
-  if (packageManagerId === "bun") {
-    return args ? `bun run ${scriptName} ${args}` : `bun run ${scriptName}`;
-  }
-  if (packageManagerId === "npm") {
-    return args ? `npm run ${scriptName} -- ${args}` : `npm run ${scriptName}`;
-  }
-  if (packageManagerId === "pnpm") {
-    return args ? `pnpm run ${scriptName} ${args}` : `pnpm run ${scriptName}`;
-  }
-  return args ? `yarn run ${scriptName} ${args}` : `yarn run ${scriptName}`;
-}
-function formatInstallCommand(packageManagerId) {
-  switch (packageManagerId) {
-    case "bun":
-      return "bun install";
-    case "pnpm":
-      return "pnpm install";
-    case "yarn":
-      return "yarn install";
-    default:
-      return "npm install";
-  }
+  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.INVALID_COMMAND, `Unknown sync subcommand "${subcommand}". Expected one of: "ai".`);
 }
 function getSyncRootError(cwd) {
-  return createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES4.OUTSIDE_PROJECT_ROOT, `No generated wp-typia project root was found at ${cwd}. Run \`wp-typia sync\` from a scaffolded project or official workspace root that already contains generated sync scripts. If you expected this directory to work, cd into the scaffold root first or rerun the scaffold before syncing.`);
-}
-function inferSyncPackageManager(cwd, packageManagerField) {
-  const field = String(packageManagerField ?? "");
-  if (field.startsWith("bun@"))
-    return "bun";
-  if (field.startsWith("npm@"))
-    return "npm";
-  if (field.startsWith("pnpm@"))
-    return "pnpm";
-  if (field.startsWith("yarn@"))
-    return "yarn";
-  if (fs4.existsSync(path4.join(cwd, "bun.lock")) || fs4.existsSync(path4.join(cwd, "bun.lockb"))) {
-    return "bun";
-  }
-  if (fs4.existsSync(path4.join(cwd, "pnpm-lock.yaml"))) {
-    return "pnpm";
-  }
-  if (fs4.existsSync(path4.join(cwd, "yarn.lock")) || fs4.existsSync(path4.join(cwd, ".pnp.cjs")) || fs4.existsSync(path4.join(cwd, ".pnp.loader.mjs")) || fs4.existsSync(path4.join(cwd, ".yarnrc.yml"))) {
-    return "yarn";
-  }
-  if (fs4.existsSync(path4.join(cwd, "package-lock.json")) || fs4.existsSync(path4.join(cwd, "npm-shrinkwrap.json"))) {
-    return "npm";
-  }
-  return "npm";
+  return createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.OUTSIDE_PROJECT_ROOT, `No generated wp-typia project root was found at ${cwd}. Run \`wp-typia sync\` from a scaffolded project or official workspace root that already contains generated sync scripts. If you expected this directory to work, cd into the scaffold root first or rerun the scaffold before syncing.`);
 }
 function resolveSyncProjectContext(cwd) {
-  const packageJsonPath = path4.join(cwd, "package.json");
-  if (!fs4.existsSync(packageJsonPath)) {
+  const packageJsonPath = path3.join(cwd, "package.json");
+  if (!fs3.existsSync(packageJsonPath)) {
     throw getSyncRootError(cwd);
   }
-  const packageJson = JSON.parse(fs4.readFileSync(packageJsonPath, "utf8"));
+  const packageJson = JSON.parse(fs3.readFileSync(packageJsonPath, "utf8"));
   const scripts = packageJson.scripts ?? {};
   const syncScripts = {
     sync: typeof scripts.sync === "string" ? {
@@ -2007,17 +2017,17 @@ function resolveSyncProjectContext(cwd) {
   return {
     cwd,
     packageJsonPath,
-    packageManager: inferSyncPackageManager(cwd, packageJson.packageManager),
+    packageManager: inferPackageManagerId2(cwd, packageJson.packageManager),
     scripts: syncScripts
   };
 }
 function findInstalledDependencyMarkerDir(projectDir) {
-  let currentDir = path4.resolve(projectDir);
+  let currentDir = path3.resolve(projectDir);
   while (true) {
-    if (SYNC_INSTALL_MARKERS.some((marker) => fs4.existsSync(path4.join(currentDir, marker)))) {
+    if (SYNC_INSTALL_MARKERS.some((marker) => fs3.existsSync(path3.join(currentDir, marker)))) {
       return currentDir;
     }
-    const parentDir = path4.dirname(currentDir);
+    const parentDir = path3.dirname(currentDir);
     if (parentDir === currentDir) {
       return null;
     }
@@ -2040,7 +2050,7 @@ function assertSyncDependenciesInstalled(project, target) {
   if (markerDir) {
     return;
   }
-  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES4.DEPENDENCIES_NOT_INSTALLED, `Project dependencies have not been installed yet. Run \`${formatInstallCommand(project.packageManager)}\` from the project root before \`wp-typia sync\`. The generated sync scripts rely on local tools such as \`tsx\`.`);
+  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.DEPENDENCIES_NOT_INSTALLED, `Project dependencies have not been installed yet. Run \`${formatInstallCommand(project.packageManager)}\` from the project root before \`wp-typia sync\`. The generated sync scripts rely on local tools such as \`tsx\`.`);
 }
 function getPackageManagerRunInvocation(packageManager, scriptName, extraArgs) {
   switch (packageManager) {
@@ -2078,7 +2088,7 @@ function buildSyncPlannedCommands(project, extraArgs, target) {
   if (target === "ai") {
     const syncAiCommand2 = createSyncPlannedCommand(project, "sync-ai", extraArgs);
     if (!syncAiCommand2) {
-      throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES4.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define a \`sync-ai\` script for \`wp-typia sync ai\`.`);
+      throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define a \`sync-ai\` script for \`wp-typia sync ai\`.`);
     }
     return [syncAiCommand2];
   }
@@ -2087,7 +2097,7 @@ function buildSyncPlannedCommands(project, extraArgs, target) {
   }
   const syncTypesCommand = createSyncPlannedCommand(project, "sync-types", extraArgs);
   if (!syncTypesCommand) {
-    throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES4.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`);
+    throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`);
   }
   const plannedCommands = [syncTypesCommand];
   const syncRestCommand = createSyncPlannedCommand(project, "sync-rest", extraArgs);
@@ -2161,8 +2171,8 @@ var loadCliScaffoldRuntime = () => import("@wp-typia/project-tools/cli-scaffold"
 var loadCliTemplatesRuntime = () => import("@wp-typia/project-tools/cli-templates");
 var loadMigrationsRuntime = () => import("@wp-typia/project-tools/migrations");
 async function wrapCliCommandError(command, error) {
-  const { createCliCommandError: createCliCommandError2 } = await loadCliDiagnosticsRuntime();
-  return createCliCommandError2({ command, error });
+  const { createCliCommandError: createCliCommandError3 } = await loadCliDiagnosticsRuntime();
+  return createCliCommandError3({ command, error });
 }
 function shouldWrapCliCommandError(options) {
   if (options.emitOutput === false) {
@@ -2367,13 +2377,13 @@ async function executeAddCommand({
       if (emitOutput) {
         printLine(addRuntime.formatAddHelpText());
       }
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.MISSING_ARGUMENT, `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`);
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT, `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`);
     }
     if (!isAddKindId(kind)) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.INVALID_COMMAND, `Unknown add kind "${kind}". Expected one of: ${formatAddKindList()}.`);
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND, `Unknown add kind "${kind}". Expected one of: ${formatAddKindList()}.`);
     }
     if (dryRun && !supportsAddKindDryRun(kind)) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.INVALID_ARGUMENT, `\`wp-typia add ${kind}\` does not support \`--dry-run\` yet.`);
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_ARGUMENT, `\`wp-typia add ${kind}\` does not support \`--dry-run\` yet.`);
     }
     const executionContext = {
       addRuntime,
@@ -2425,16 +2435,16 @@ async function executeTemplatesCommand({ flags }, printLine = console.log) {
   }
   if (subcommand === "inspect") {
     if (!flags.id) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.MISSING_ARGUMENT, "`wp-typia templates inspect` requires <template-id>.");
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT, "`wp-typia templates inspect` requires <template-id>.");
     }
     const template = getTemplateById(flags.id);
     if (!template) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.INVALID_ARGUMENT, `Unknown template "${flags.id}".`);
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_ARGUMENT, `Unknown template "${flags.id}".`);
     }
     printBlock([formatTemplateDetails(template)], printLine);
     return;
   }
-  throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES5.INVALID_COMMAND, `Unknown templates subcommand "${subcommand}". Expected list or inspect.`);
+  throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND, `Unknown templates subcommand "${subcommand}". Expected list or inspect.`);
 }
 async function executeInitCommand({ apply, cwd, packageManager, projectDir }, options = {}) {
   try {
@@ -2522,7 +2532,7 @@ async function executeMigrateCommand({
 }
 
 // src/command-contract.ts
-import path5 from "node:path";
+import path4 from "node:path";
 
 // src/command-registry.ts
 var WP_TYPIA_CANONICAL_CREATE_USAGE = "wp-typia create <project-dir>";
@@ -2736,7 +2746,7 @@ function looksLikeStructuredProjectInput(value) {
   return value.startsWith("@") && value.includes("/");
 }
 function assertPositionalAliasProjectDir(projectDir) {
-  const normalizedProjectDir = path5.normalize(projectDir).replace(/[\\/]+$/u, "") || path5.normalize(projectDir);
+  const normalizedProjectDir = path4.normalize(projectDir).replace(/[\\/]+$/u, "") || path4.normalize(projectDir);
   if (normalizedProjectDir === "." || normalizedProjectDir === "..") {
     throw new Error(`The positional alias does not scaffold into \`${projectDir}\`. Use \`${WP_TYPIA_CANONICAL_CREATE_USAGE}\` with an explicit child directory instead.`);
   }
@@ -2785,9 +2795,9 @@ var NODE_FALLBACK_RUNTIME_SUMMARY_LINES = [
   `Install Bun 1.3.11+ or use \`bunx wp-typia ...\` for the full Bunli/OpenTUI runtime and Bun-only command surfaces such as \`skills\`, \`completions\`, and \`mcp\`. ${STANDALONE_GUIDANCE_LINE}`,
   "Output markers: WP_TYPIA_ASCII=1 forces ASCII markers, WP_TYPIA_ASCII=0 opts back into Unicode markers, and non-empty NO_COLOR requests ASCII markers when WP_TYPIA_ASCII is unset."
 ];
-function printLine(line = "") {
+var printLine = (line) => {
   console.log(line);
-}
+};
 function printBlock2(lines) {
   for (const line of lines) {
     printLine(line);
@@ -2819,7 +2829,7 @@ function parseGlobalFlags(argv) {
     };
   } catch (error) {
     if (error instanceof Error && /\`--format\` requires a value\.|\`--id\` requires a value\./.test(error.message)) {
-      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT, error.message);
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT, error.message);
     }
     throw error;
   }
@@ -2874,91 +2884,58 @@ function renderGeneralHelp() {
     `- ${WP_TYPIA_POSITIONAL_ALIAS_USAGE}`
   ]);
 }
-function renderTemplatesHelp() {
-  printBlock2([
-    "wp-typia templates <list|inspect>",
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(TEMPLATES_OPTION_METADATA)
-  ]);
-}
-function renderCreateHelp() {
-  printBlock2([
-    `Usage: ${WP_TYPIA_CANONICAL_CREATE_USAGE}`,
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(CREATE_OPTION_METADATA)
-  ]);
-}
-function renderInitHelp() {
-  printBlock2([
-    "Usage: wp-typia init [project-dir]",
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    "Preview-by-default retrofit planner for existing WordPress block or plugin projects. Re-run with --apply to write package.json updates and helper scripts.",
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(INIT_OPTION_METADATA)
-  ]);
-}
-function renderAddHelp() {
-  printBlock2([
-    "Usage: wp-typia add <kind> <name>",
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    `Supported kinds: ${formatAddKindList()}`,
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(ADD_OPTION_METADATA)
-  ]);
-}
-function renderMigrateHelp() {
-  printBlock2([
-    `Usage: ${WP_TYPIA_CANONICAL_MIGRATE_USAGE}`,
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(MIGRATE_OPTION_METADATA)
-  ]);
-}
-function renderSyncHelp() {
-  printBlock2([
-    "Usage: wp-typia sync [ai]",
-    "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
-    "",
-    "Supported flags:",
-    ...formatNodeFallbackOptionHelp(SYNC_OPTION_METADATA)
-  ]);
-}
-function renderDoctorHelp() {
+function renderNodeFallbackCommandHelp(config) {
   printBlock2([
-    "Usage: wp-typia doctor [--format json]",
+    config.heading,
     "",
     ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
     "",
-    "Runs read-only environment readiness checks. Official wp-typia workspace roots also get inventory, source-tree drift, iframe/API v3 compatibility, and shared convention checks.",
-    "",
+    ...config.bodyLines ? [...config.bodyLines, ""] : [],
     "Supported flags:",
-    ...formatNodeFallbackOptionHelp(DOCTOR_OPTION_METADATA)
+    ...formatNodeFallbackOptionHelp(config.optionMetadata)
   ]);
 }
-var NODE_FALLBACK_HELP_RENDERERS = {
-  add: renderAddHelp,
-  create: renderCreateHelp,
-  doctor: renderDoctorHelp,
-  init: renderInitHelp,
-  migrate: renderMigrateHelp,
-  sync: renderSyncHelp,
-  templates: renderTemplatesHelp
+var NODE_FALLBACK_COMMAND_HELP_CONFIG = {
+  add: {
+    bodyLines: [`Supported kinds: ${formatAddKindList()}`],
+    heading: "Usage: wp-typia add <kind> <name>",
+    optionMetadata: ADD_OPTION_METADATA
+  },
+  create: {
+    heading: `Usage: ${WP_TYPIA_CANONICAL_CREATE_USAGE}`,
+    optionMetadata: CREATE_OPTION_METADATA
+  },
+  doctor: {
+    bodyLines: [
+      "Runs read-only environment readiness checks. Official wp-typia workspace roots also get inventory, source-tree drift, iframe/API v3 compatibility, and shared convention checks."
+    ],
+    heading: "Usage: wp-typia doctor [--format json]",
+    optionMetadata: DOCTOR_OPTION_METADATA
+  },
+  init: {
+    bodyLines: [
+      "Preview-by-default retrofit planner for existing WordPress block or plugin projects. Re-run with --apply to write package.json updates and helper scripts."
+    ],
+    heading: "Usage: wp-typia init [project-dir]",
+    optionMetadata: INIT_OPTION_METADATA
+  },
+  migrate: {
+    heading: `Usage: ${WP_TYPIA_CANONICAL_MIGRATE_USAGE}`,
+    optionMetadata: MIGRATE_OPTION_METADATA
+  },
+  sync: {
+    heading: "Usage: wp-typia sync [ai]",
+    optionMetadata: SYNC_OPTION_METADATA
+  },
+  templates: {
+    heading: "wp-typia templates <list|inspect>",
+    optionMetadata: TEMPLATES_OPTION_METADATA
+  }
 };
+var NODE_FALLBACK_HELP_RENDERERS = Object.fromEntries(Object.entries(NODE_FALLBACK_COMMAND_HELP_CONFIG).map(([command, config]) => [
+  command,
+  () => renderNodeFallbackCommandHelp(config)
+]));
 function renderVersion(options = {}) {
   if (options.format === "json") {
     printLine(JSON.stringify({
@@ -2982,16 +2959,16 @@ function renderTemplatesJson(flags, subcommand) {
   }
   const templateId = flags.id;
   if (!templateId) {
-    throw createCliCommandError2({
-      code: CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT,
+    throw createCliCommandError3({
+      code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
       command: "templates",
       detailLines: ["`wp-typia templates inspect` requires <template-id>."]
     });
   }
   const template = getTemplateById(templateId);
   if (!template) {
-    throw createCliCommandError2({
-      code: CLI_DIAGNOSTIC_CODES6.INVALID_ARGUMENT,
+    throw createCliCommandError3({
+      code: CLI_DIAGNOSTIC_CODES7.INVALID_ARGUMENT,
       command: "templates",
       detailLines: [`Unknown template "${templateId}".`]
     });
@@ -3001,8 +2978,8 @@ function renderTemplatesJson(flags, subcommand) {
   }, null, 2));
 }
 function renderUnsupportedCommand(command) {
-  throw createCliCommandError2({
-    code: CLI_DIAGNOSTIC_CODES6.UNSUPPORTED_COMMAND,
+  throw createCliCommandError3({
+    code: CLI_DIAGNOSTIC_CODES7.UNSUPPORTED_COMMAND,
     command,
     detailLines: [
       [
@@ -3017,7 +2994,7 @@ function renderUnsupportedCommand(command) {
 async function renderDoctorJson() {
   const [
     { getDoctorChecks },
-    { createCliCommandError: createCliCommandError3, getDoctorFailureDetailLines }
+    { createCliCommandError: createCliCommandError4, getDoctorFailureDetailLines }
   ] = await Promise.all([
     import("@wp-typia/project-tools/cli-doctor"),
     import("@wp-typia/project-tools/cli-diagnostics")
@@ -3027,8 +3004,8 @@ async function renderDoctorJson() {
     checks
   }, null, 2));
   if (checks.some((check) => check.status === "fail")) {
-    throw createCliCommandError3({
-      code: CLI_DIAGNOSTIC_CODES6.DOCTOR_CHECK_FAILED,
+    throw createCliCommandError4({
+      code: CLI_DIAGNOSTIC_CODES7.DOCTOR_CHECK_FAILED,
       command: "doctor",
       detailLines: getDoctorFailureDetailLines(checks),
       summary: "One or more doctor checks failed."
@@ -3044,8 +3021,8 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
     if (!positionals[1]) {
       const { formatAddHelpText } = await import("@wp-typia/project-tools/cli-add");
       printLine(formatAddHelpText());
-      throw createCliCommandError2({
-        code: CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT,
+      throw createCliCommandError3({
+        code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
         command: "add",
         detailLines: [
           `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`
@@ -3064,7 +3041,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
           name: positionals[2]
         });
       } catch (error) {
-        throw createCliCommandError2({
+        throw createCliCommandError3({
           command: "add",
           error
         });
@@ -3092,8 +3069,8 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
   }) => {
     const projectDir = positionals[1];
     if (!projectDir) {
-      throw createCliCommandError2({
-        code: CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT,
+      throw createCliCommandError3({
+        code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
         command: "create",
         detailLines: [
           "`wp-typia create` requires <project-dir>.",
@@ -3111,7 +3088,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
         projectDir
       });
     } catch (error) {
-      throw createCliCommandError2({
+      throw createCliCommandError3({
         command: "create",
         error
       });
@@ -3189,7 +3166,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
         }));
       }
     } catch (error) {
-      throw createCliCommandError2({
+      throw createCliCommandError3({
         command: "sync",
         error
       });
@@ -3203,8 +3180,8 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
     const templateId = typeof mergedFlags.id === "string" ? mergedFlags.id : positionals[2];
     const resolvedSubcommand = templateId ? "inspect" : subcommand ?? "list";
     if (resolvedSubcommand !== "list" && resolvedSubcommand !== "inspect") {
-      throw createCliCommandError2({
-        code: CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND,
+      throw createCliCommandError3({
+        code: CLI_DIAGNOSTIC_CODES7.INVALID_COMMAND,
         command: "templates",
         detailLines: [
           `Unknown templates subcommand "${resolvedSubcommand}". Expected list or inspect.`
@@ -3229,6 +3206,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
 async function runNodeCli(argv = process.argv.slice(2)) {
   const normalizedArgv = normalizeWpTypiaArgv(argv);
   const { argv: argvWithoutConfigOverride, configOverridePath } = extractWpTypiaConfigOverride(normalizedArgv);
+  validateCliOutputFormatArgv(argvWithoutConfigOverride);
   const { argv: cliArgv, flags } = parseGlobalFlags(argvWithoutConfigOverride);
   const { flags: commandFlags, positionals } = parseArgv(cliArgv);
   const rawMergedFlags = {
@@ -3305,4 +3283,4 @@ export {
   hasFlagBeforeTerminator
 };
 
-//# debugId=2746E868E408BAB564756E2164756E21
+//# debugId=A8E2D093C9BAE2C064756E2164756E21