wp-typia 0.22.4 → 0.22.6

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.4",
+  version: "0.22.6",
   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.4",
+    "@wp-typia/project-tools": "0.22.6",
     "better-result": "^2.7.0",
     react: "^19.2.5",
     "react-dom": "^19.2.5",
@@ -97,15 +97,18 @@ var package_default = {
 
 // src/node-cli.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES7,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES8,
   createCliCommandError as createCliCommandError3,
-  createCliDiagnosticCodeError as createCliDiagnosticCodeError6,
   formatCliDiagnosticError,
   serializeCliDiagnosticError as serializeCliDiagnosticError2
 } from "@wp-typia/project-tools/cli-diagnostics";
 
 // src/command-option-metadata.ts
 import { z } from "zod";
+import {
+  CLI_DIAGNOSTIC_CODES,
+  createCliDiagnosticCodeError
+} from "@wp-typia/project-tools/cli-diagnostics";
 var CREATE_OPTION_METADATA = {
   "alternate-render-targets": {
     description: "Comma-separated alternate render targets for dynamic block scaffolds (email,mjml,plain-text).",
@@ -336,7 +339,7 @@ var SYNC_OPTION_METADATA = {
 };
 var DOCTOR_OPTION_METADATA = {
   format: {
-    description: "Use `json` for machine-readable doctor check output or `toon` for human-readable output.",
+    description: "Use `json` for machine-readable doctor check output or `text` for human-readable output.",
     type: "string"
   }
 };
@@ -353,7 +356,7 @@ var GLOBAL_OPTION_METADATA = {
     type: "string"
   },
   format: {
-    description: "Output format for supported commands (`json` or `toon`).",
+    description: "Output format for supported commands (`json` or `text`).",
     type: "string"
   },
   id: {
@@ -419,6 +422,12 @@ function buildArgvWalkerRoutingMetadata(...metadataMaps) {
   };
 }
 var COMMAND_ROUTING_METADATA = buildArgvWalkerRoutingMetadata(ALL_COMMAND_OPTION_METADATA);
+function createMissingOptionValueError(optionLabel) {
+  return createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT, `\`${optionLabel}\` requires a value.`);
+}
+function createUnknownOptionError(optionLabel) {
+  return createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Unknown option \`${optionLabel}\`.`);
+}
 function extractKnownOptionValuesFromArgv(argv, options) {
   const flags = {};
   const nextArgv = [];
@@ -444,7 +453,7 @@ function extractKnownOptionValuesFromArgv(argv, options) {
       }
       const next = argv[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new Error(`\`${arg}\` requires a value.`);
+        throw createMissingOptionValueError(arg);
       }
       flags[shortFlag.name] = next;
       index += 1;
@@ -469,14 +478,14 @@ function extractKnownOptionValuesFromArgv(argv, options) {
       }
       if (inlineValue !== undefined) {
         if (!inlineValue) {
-          throw new Error(`\`--${rawName}\` requires a value.`);
+          throw createMissingOptionValueError(`--${rawName}`);
         }
         flags[rawName] = inlineValue;
         continue;
       }
       const next = argv[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new Error(`\`--${rawName}\` requires a value.`);
+        throw createMissingOptionValueError(`--${rawName}`);
       }
       flags[rawName] = next;
       index += 1;
@@ -508,7 +517,7 @@ function parseCommandArgvWithMetadata(argv, options) {
     if (arg.length === 2 && arg.startsWith("-")) {
       const shortFlag = options.parser.shortFlagMap.get(arg.slice(1));
       if (!shortFlag) {
-        throw new Error(`Unknown option \`${arg}\`.`);
+        throw createUnknownOptionError(arg);
       }
       if (shortFlag.type === "boolean") {
         flags[shortFlag.name] = true;
@@ -516,7 +525,7 @@ function parseCommandArgvWithMetadata(argv, options) {
       }
       const next = argv[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new Error(`\`${arg}\` requires a value.`);
+        throw createMissingOptionValueError(arg);
       }
       flags[shortFlag.name] = next;
       index += 1;
@@ -532,25 +541,25 @@ function parseCommandArgvWithMetadata(argv, options) {
         continue;
       }
       if (!options.parser.stringOptionNames.has(rawName)) {
-        throw new Error(`Unknown option \`--${rawName}\`.`);
+        throw createUnknownOptionError(`--${rawName}`);
       }
       if (inlineValue !== undefined) {
         if (!inlineValue) {
-          throw new Error(`\`--${rawName}\` requires a value.`);
+          throw createMissingOptionValueError(`--${rawName}`);
         }
         flags[rawName] = inlineValue;
         continue;
       }
       const next = argv[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new Error(`\`--${rawName}\` requires a value.`);
+        throw createMissingOptionValueError(`--${rawName}`);
       }
       flags[rawName] = next;
       index += 1;
       continue;
     }
     if (arg.startsWith("-")) {
-      throw new Error(`Unknown option \`${arg}\`.`);
+      throw createUnknownOptionError(arg);
     }
     positionals.push(arg);
   }
@@ -584,12 +593,6 @@ import {
   serializeCliDiagnosticError
 } from "@wp-typia/project-tools/cli-diagnostics";
 
-// src/cli-output-format.ts
-import {
-  CLI_DIAGNOSTIC_CODES,
-  createCliCommandError
-} from "@wp-typia/project-tools/cli-diagnostics";
-
 // bin/argv-walker.js
 function normalizeOptionSet(values) {
   return values instanceof Set ? values : new Set(values);
@@ -635,26 +638,66 @@ function findFirstPositional(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
-var SUPPORTED_CLI_OUTPUT_FORMATS = ["json", "toon"];
+import {
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES2,
+  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 SUPPORTED_CLI_OUTPUT_FORMATS.join(", ");
+  return PUBLIC_CLI_OUTPUT_FORMATS.join(", ");
 }
 function isSupportedCliOutputFormat(value) {
-  return SUPPORTED_CLI_OUTPUT_FORMATS.includes(value);
+  return typeof value === "string" && SUPPORTED_CLI_OUTPUT_FORMAT_VALUES.includes(value);
+}
+function normalizeCliOutputFormatArgv(argv) {
+  let normalized;
+  for (let index = 0;index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--") {
+      break;
+    }
+    if (arg === "--format") {
+      const next = argv[index + 1];
+      if (next === "text") {
+        normalized ??= [...argv];
+        normalized[index + 1] = "toon";
+      }
+      if (next && !next.startsWith("-")) {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === "--format=text") {
+      normalized ??= [...argv];
+      normalized[index] = "--format=toon";
+    }
+  }
+  return normalized ?? argv;
 }
 function formatInvalidCliOutputFormatMessage(value) {
   return `Invalid --format value "${value}". Supported values: ${formatSupportedCliOutputFormats()}.`;
 }
-function resolveEntrypointCliCommand(argv) {
-  return findFirstPositional(argv, COMMAND_ROUTING_METADATA) ?? "wp-typia";
-}
 function assertSupportedCliOutputFormat(value, argv) {
   if (isSupportedCliOutputFormat(value)) {
     return;
   }
   throw createCliCommandError({
-    code: CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT,
+    code: CLI_DIAGNOSTIC_CODES2.INVALID_ARGUMENT,
     command: resolveEntrypointCliCommand(argv),
     detailLines: [formatInvalidCliOutputFormatMessage(value)]
   });
@@ -713,30 +756,17 @@ import {
 
 // src/add-kind-registry.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES3,
-  createCliDiagnosticCodeError as createCliDiagnosticCodeError2
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES4,
+  createCliDiagnosticCodeError as createCliDiagnosticCodeError3
 } from "@wp-typia/project-tools/cli-diagnostics";
 
 // src/add-kind-ids.ts
-var ADD_KIND_IDS = [
-  "admin-view",
-  "block",
-  "variation",
-  "style",
-  "transform",
-  "pattern",
-  "binding-source",
-  "rest-resource",
-  "ability",
-  "ai-feature",
-  "hooked-block",
-  "editor-plugin"
-];
+import { ADD_KIND_IDS } from "@wp-typia/project-tools/cli-add-kind-ids";
 
 // src/cli-string-flags.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES2,
-  createCliDiagnosticCodeError
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES3,
+  createCliDiagnosticCodeError as createCliDiagnosticCodeError2
 } from "@wp-typia/project-tools/cli-diagnostics";
 function readOptionalCliStringFlagValue(flags, name, mode) {
   const value = flags[name];
@@ -744,12 +774,12 @@ function readOptionalCliStringFlagValue(flags, name, mode) {
     return;
   }
   if (typeof value !== "string") {
-    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
+    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
   }
   const trimmed = value.trim();
   if (trimmed.length === 0) {
     if (mode === "strict") {
-      throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
+      throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, `\`--${name}\` requires a value.`);
     }
     return;
   }
@@ -764,7 +794,7 @@ function readOptionalStrictStringFlag(flags, name) {
 function requireStrictStringFlag(flags, name, message) {
   const value = readOptionalStrictStringFlag(flags, name);
   if (!value) {
-    throw createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES2.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, message);
   }
   return value;
 }
@@ -772,7 +802,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_CODES2.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, message);
   }
   return [leftValue, rightValue];
 }
@@ -853,7 +883,7 @@ var NAME_NAMESPACE_VISIBLE_FIELDS = [
 ];
 function requireAddKindName(context, message) {
   if (!context.name) {
-    throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.MISSING_ARGUMENT, message);
+    throw createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES4.MISSING_ARGUMENT, message);
   }
   return context.name;
 }
@@ -880,9 +910,9 @@ function assertAddBlockTemplateId(context, 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 createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES4.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.`);
+  throw createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES4.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({
@@ -1063,7 +1093,9 @@ var ADD_KIND_REGISTRY = {
         getValues: (result) => ({
           abilitySlug: result.abilitySlug
         }),
-        missingNameMessage: "`wp-typia add ability` requires <name>. Usage: wp-typia add ability <name>."
+        getWarnings: (result) => result.warnings,
+        missingNameMessage: "`wp-typia add ability` requires <name>. Usage: wp-typia add ability <name>.",
+        warnLine: context.warnLine
       });
     },
     sortOrder: 90,
@@ -1407,14 +1439,87 @@ 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_CODES4,
-  createCliDiagnosticCodeError as createCliDiagnosticCodeError3
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES5,
+  createCliDiagnosticCodeError as createCliDiagnosticCodeError4
 } from "@wp-typia/project-tools/cli-diagnostics";
+import { z as z2 } from "zod";
 var WP_TYPIA_CONFIG_SOURCES = [
   "~/.config/wp-typia/config.json",
   ".wp-typiarc",
   ".wp-typiarc.json"
 ];
+var wpTypiaSchemaSourceSchema = z2.object({
+  namespace: z2.string(),
+  path: z2.string()
+}).strict();
+var createConfigSchema = z2.object({
+  "alternate-render-targets": z2.string().optional(),
+  "inner-blocks-preset": z2.string().optional(),
+  "data-storage": z2.string().optional(),
+  "dry-run": z2.boolean().optional(),
+  "external-layer-id": z2.string().optional(),
+  "external-layer-source": z2.string().optional(),
+  namespace: z2.string().optional(),
+  "no-install": z2.boolean().optional(),
+  "package-manager": z2.string().optional(),
+  "persistence-policy": z2.string().optional(),
+  "php-prefix": z2.string().optional(),
+  "query-post-type": z2.string().optional(),
+  template: z2.string().optional(),
+  "text-domain": z2.string().optional(),
+  variant: z2.string().optional(),
+  "with-migration-ui": z2.boolean().optional(),
+  "with-test-preset": z2.boolean().optional(),
+  "with-wp-env": z2.boolean().optional(),
+  yes: z2.boolean().optional()
+}).strict();
+var addBlockConfigSchema = z2.object({
+  "alternate-render-targets": z2.string().optional(),
+  "data-storage": z2.string().optional(),
+  "external-layer-id": z2.string().optional(),
+  "external-layer-source": z2.string().optional(),
+  "inner-blocks-preset": z2.string().optional(),
+  "persistence-policy": z2.string().optional(),
+  template: z2.string().optional()
+}).strict();
+var addConfigSchema = z2.object({
+  block: addBlockConfigSchema.optional()
+}).strict();
+var mcpConfigSchema = z2.object({
+  schemaSources: z2.array(wpTypiaSchemaSourceSchema).optional()
+}).strict();
+var wpTypiaUserConfigSchema = z2.object({
+  add: addConfigSchema.optional(),
+  create: createConfigSchema.optional(),
+  mcp: mcpConfigSchema.optional()
+}).strict();
+function formatIssuePath(issuePath) {
+  if (issuePath.length === 0) {
+    return "config";
+  }
+  return issuePath.map((segment) => typeof segment === "number" ? `[${segment}]` : `.${String(segment)}`).join("").replace(/^\./u, "");
+}
+function formatConfigValidationIssue(issue) {
+  const pathLabel = formatIssuePath(issue.path);
+  if (issue.code === "unrecognized_keys") {
+    const keys = issue.keys.map((key) => `"${String(key)}"`).join(", ");
+    const label = issue.keys.length === 1 ? "unknown key" : "unknown keys";
+    return `${pathLabel}: ${label} ${keys}. Unknown keys are errors in wp-typia config.`;
+  }
+  return `${pathLabel}: ${issue.message}`;
+}
+function validateWpTypiaUserConfig(value, source) {
+  const result = wpTypiaUserConfigSchema.safeParse(value);
+  if (result.success) {
+    return result.data;
+  }
+  const issueLines = result.error.issues.map(formatConfigValidationIssue);
+  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.INVALID_ARGUMENT, [
+    `Invalid wp-typia config at ${source}.`,
+    ...issueLines.map((line) => `- ${line}`)
+  ].join(`
+`));
+}
 function deepMerge(base, incoming) {
   const merged = { ...base };
   for (const [key, value] of Object.entries(incoming)) {
@@ -1436,18 +1541,21 @@ async function readJsonFile(filePath) {
     source = await fs.readFile(filePath, "utf8");
   } catch (error) {
     if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
-      return null;
+      return;
     }
     throw error;
   }
   try {
-    const parsed = JSON.parse(source);
-    return isRecord(parsed) ? parsed : null;
+    return JSON.parse(source);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw createCliDiagnosticCodeError3(CLI_DIAGNOSTIC_CODES4.INVALID_ARGUMENT, `Unable to parse ${filePath}: ${message}`, error instanceof Error ? { cause: error } : undefined);
+    throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.INVALID_ARGUMENT, `Unable to parse ${filePath}: ${message}`, error instanceof Error ? { cause: error } : undefined);
   }
 }
+async function readWpTypiaConfigFile(filePath) {
+  const parsed = await readJsonFile(filePath);
+  return parsed === undefined ? null : validateWpTypiaUserConfig(parsed, filePath);
+}
 function resolveConfigPath(cwd, source) {
   if (source.startsWith("~/")) {
     return path.join(os.homedir(), source.slice(2));
@@ -1458,21 +1566,23 @@ function mergeWpTypiaUserConfig(base, incoming) {
   return deepMerge(base, incoming);
 }
 async function loadWpTypiaUserConfigFromSource(cwd, source) {
-  const config = await readJsonFile(resolveConfigPath(cwd, source));
+  const config = await readWpTypiaConfigFile(resolveConfigPath(cwd, source));
   return config ?? {};
 }
 async function loadWpTypiaUserConfig(cwd) {
   let merged = {};
   for (const source of WP_TYPIA_CONFIG_SOURCES) {
     const configPath = resolveConfigPath(cwd, source);
-    const config = await readJsonFile(configPath);
+    const config = await readWpTypiaConfigFile(configPath);
     if (config) {
       merged = deepMerge(merged, config);
     }
   }
-  const packageJson = await readJsonFile(path.join(cwd, "package.json"));
-  if (packageJson && isRecord(packageJson["wp-typia"])) {
-    merged = deepMerge(merged, packageJson["wp-typia"]);
+  const packageJsonPath = path.join(cwd, "package.json");
+  const packageJson = await readJsonFile(packageJsonPath);
+  if (isRecord(packageJson) && "wp-typia" in packageJson) {
+    const packageConfig = validateWpTypiaUserConfig(packageJson["wp-typia"], `${packageJsonPath}#wp-typia`);
+    merged = deepMerge(merged, packageConfig);
   }
   return merged;
 }
@@ -1498,8 +1608,8 @@ function extractWpTypiaConfigOverride(argv) {
 
 // src/runtime-bridge.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES6,
-  createCliDiagnosticCodeError as createCliDiagnosticCodeError5
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES7,
+  createCliDiagnosticCodeError as createCliDiagnosticCodeError6
 } from "@wp-typia/project-tools/cli-diagnostics";
 
 // src/runtime-bridge-add-dry-run.ts
@@ -1953,8 +2063,8 @@ import { spawnSync } from "node:child_process";
 import fs3 from "node:fs";
 import path3 from "node:path";
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES5,
-  createCliDiagnosticCodeError as createCliDiagnosticCodeError4
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES6,
+  createCliDiagnosticCodeError as createCliDiagnosticCodeError5
 } from "@wp-typia/project-tools/cli-diagnostics";
 import {
   formatInstallCommand,
@@ -1975,10 +2085,10 @@ function resolveSyncExecutionTarget(subcommand) {
   if (subcommand === "ai") {
     return "ai";
   }
-  throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.INVALID_COMMAND, `Unknown sync subcommand "${subcommand}". Expected one of: "ai".`);
+  throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND, `Unknown sync subcommand "${subcommand}". Expected one of: "ai".`);
 }
 function getSyncRootError(cwd) {
-  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.`);
+  return createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.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 = path3.join(cwd, "package.json");
@@ -2044,7 +2154,7 @@ function assertSyncDependenciesInstalled(project, target) {
   if (markerDir) {
     return;
   }
-  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\`.`);
+  throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.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) {
@@ -2082,7 +2192,7 @@ function buildSyncPlannedCommands(project, extraArgs, target) {
   if (target === "ai") {
     const syncAiCommand2 = createSyncPlannedCommand(project, "sync-ai", extraArgs);
     if (!syncAiCommand2) {
-      throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define a \`sync-ai\` script for \`wp-typia sync ai\`.`);
+      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define a \`sync-ai\` script for \`wp-typia sync ai\`.`);
     }
     return [syncAiCommand2];
   }
@@ -2091,7 +2201,7 @@ function buildSyncPlannedCommands(project, extraArgs, target) {
   }
   const syncTypesCommand = createSyncPlannedCommand(project, "sync-types", extraArgs);
   if (!syncTypesCommand) {
-    throw createCliDiagnosticCodeError4(CLI_DIAGNOSTIC_CODES5.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`);
+    throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.CONFIGURATION_MISSING, `Expected ${project.packageJsonPath} to define either a \`sync\` or \`sync-types\` script.`);
   }
   const plannedCommands = [syncTypesCommand];
   const syncRestCommand = createSyncPlannedCommand(project, "sync-rest", extraArgs);
@@ -2371,13 +2481,13 @@ async function executeAddCommand({
       if (emitOutput) {
         printLine(addRuntime.formatAddHelpText());
       }
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT, `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`);
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT, `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`);
     }
     if (!isAddKindId(kind)) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND, `Unknown add kind "${kind}". Expected one of: ${formatAddKindList()}.`);
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.INVALID_COMMAND, `Unknown add kind "${kind}". Expected one of: ${formatAddKindList()}.`);
     }
     if (dryRun && !supportsAddKindDryRun(kind)) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_ARGUMENT, `\`wp-typia add ${kind}\` does not support \`--dry-run\` yet.`);
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.INVALID_ARGUMENT, `\`wp-typia add ${kind}\` does not support \`--dry-run\` yet.`);
     }
     const executionContext = {
       addRuntime,
@@ -2429,16 +2539,16 @@ async function executeTemplatesCommand({ flags }, printLine = console.log) {
   }
   if (subcommand === "inspect") {
     if (!flags.id) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.MISSING_ARGUMENT, "`wp-typia templates inspect` requires <template-id>.");
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT, "`wp-typia templates inspect` requires <template-id>.");
     }
     const template = getTemplateById(flags.id);
     if (!template) {
-      throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_ARGUMENT, `Unknown template "${flags.id}".`);
+      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.INVALID_ARGUMENT, `Unknown template "${flags.id}".`);
     }
     printBlock([formatTemplateDetails(template)], printLine);
     return;
   }
-  throw createCliDiagnosticCodeError5(CLI_DIAGNOSTIC_CODES6.INVALID_COMMAND, `Unknown templates subcommand "${subcommand}". Expected list or inspect.`);
+  throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.INVALID_COMMAND, `Unknown templates subcommand "${subcommand}". Expected list or inspect.`);
 }
 async function executeInitCommand({ apply, cwd, packageManager, projectDir }, options = {}) {
   try {
@@ -2682,6 +2792,60 @@ var SHORT_OPTION_NAMES_WITH_VALUES = new Set([...SHARED_OPTION_PARSER.shortFlagM
 function isReservedTopLevelCommandName(value) {
   return WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES.includes(value);
 }
+function getLongOptionName(arg) {
+  return arg.slice(2).split("=", 1)[0] ?? "";
+}
+function hasUnknownOptionBefore(argv, endIndex) {
+  for (let index = 0;index < endIndex; index += 1) {
+    const arg = argv[index];
+    if (arg === "--") {
+      return false;
+    }
+    if (!arg.startsWith("-") || arg === "-") {
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const optionName = getLongOptionName(arg);
+      if (!SHARED_OPTION_PARSER.booleanOptionNames.has(optionName) && !SHARED_OPTION_PARSER.stringOptionNames.has(optionName)) {
+        return true;
+      }
+      if (!arg.includes("=") && SHARED_OPTION_PARSER.stringOptionNames.has(optionName) && argv[index + 1] && !argv[index + 1].startsWith("-")) {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg.length === 2) {
+      const option = SHARED_OPTION_PARSER.shortFlagMap.get(arg.slice(1));
+      if (!option) {
+        return true;
+      }
+      if (option.type === "string" && argv[index + 1] && !argv[index + 1].startsWith("-")) {
+        index += 1;
+      }
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+function resolveCanonicalCommandContext(argv) {
+  const positionalIndexes = collectPositionalIndexes(argv, COMMAND_ROUTING_METADATA);
+  const firstPositionalIndex = positionalIndexes[0] ?? -1;
+  if (firstPositionalIndex === -1) {
+    return "wp-typia";
+  }
+  const firstPositional = argv[firstPositionalIndex];
+  if (!firstPositional) {
+    return "wp-typia";
+  }
+  if (hasUnknownOptionBefore(argv, firstPositionalIndex)) {
+    return "wp-typia";
+  }
+  if (isReservedTopLevelCommandName(firstPositional)) {
+    return firstPositional;
+  }
+  return positionalIndexes.length === 1 ? "create" : firstPositional;
+}
 function assertStringOptionValues(argv) {
   const firstPositionalIndex = findFirstPositionalIndex(argv, COMMAND_ROUTING_METADATA);
   if (firstPositionalIndex === -1) {
@@ -2701,7 +2865,7 @@ function assertStringOptionValues(argv) {
       if (SHORT_OPTION_NAMES_WITH_VALUES.has(arg.slice(1))) {
         const next2 = argv[index + 1];
         if (!next2 || next2.startsWith("-")) {
-          throw new Error(`\`${arg}\` requires a value.`);
+          throw createMissingOptionValueError(arg);
         }
         index += 1;
       }
@@ -2716,13 +2880,13 @@ function assertStringOptionValues(argv) {
     }
     if (arg.includes("=")) {
       if (!inlineValue) {
-        throw new Error(`\`--${rawName}\` requires a value.`);
+        throw createMissingOptionValueError(`--${rawName}`);
       }
       continue;
     }
     const next = argv[index + 1];
     if (!next || next.startsWith("-")) {
-      throw new Error(`\`--${rawName}\` requires a value.`);
+      throw createMissingOptionValueError(`--${rawName}`);
     }
     index += 1;
   }
@@ -2789,9 +2953,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);
@@ -2809,24 +2973,17 @@ function hasFlagBeforeTerminator(argv, flag) {
   return false;
 }
 function parseGlobalFlags(argv) {
-  try {
-    const { argv: nextArgv, flags } = extractKnownOptionValuesFromArgv(argv, {
-      optionNames: ["format", "id"],
-      parser: NODE_FALLBACK_OPTION_PARSER
-    });
-    return {
-      argv: nextArgv,
-      flags: {
-        format: typeof flags.format === "string" ? flags.format : undefined,
-        id: typeof flags.id === "string" ? flags.id : undefined
-      }
-    };
-  } catch (error) {
-    if (error instanceof Error && /\`--format\` requires a value\.|\`--id\` requires a value\./.test(error.message)) {
-      throw createCliDiagnosticCodeError6(CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT, error.message);
+  const { argv: nextArgv, flags } = extractKnownOptionValuesFromArgv(argv, {
+    optionNames: ["format", "id"],
+    parser: NODE_FALLBACK_OPTION_PARSER
+  });
+  return {
+    argv: nextArgv,
+    flags: {
+      format: typeof flags.format === "string" ? flags.format : undefined,
+      id: typeof flags.id === "string" ? flags.id : undefined
     }
-    throw error;
-  }
+  };
 }
 async function applyNodeFallbackConfigDefaults(command, subcommand, flags, configOverridePath, cwd) {
   let config = await loadWpTypiaUserConfig(cwd);
@@ -2878,91 +3035,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({
@@ -2987,7 +3111,7 @@ function renderTemplatesJson(flags, subcommand) {
   const templateId = flags.id;
   if (!templateId) {
     throw createCliCommandError3({
-      code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
+      code: CLI_DIAGNOSTIC_CODES8.MISSING_ARGUMENT,
       command: "templates",
       detailLines: ["`wp-typia templates inspect` requires <template-id>."]
     });
@@ -2995,7 +3119,7 @@ function renderTemplatesJson(flags, subcommand) {
   const template = getTemplateById(templateId);
   if (!template) {
     throw createCliCommandError3({
-      code: CLI_DIAGNOSTIC_CODES7.INVALID_ARGUMENT,
+      code: CLI_DIAGNOSTIC_CODES8.INVALID_ARGUMENT,
       command: "templates",
       detailLines: [`Unknown template "${templateId}".`]
     });
@@ -3006,7 +3130,7 @@ function renderTemplatesJson(flags, subcommand) {
 }
 function renderUnsupportedCommand(command) {
   throw createCliCommandError3({
-    code: CLI_DIAGNOSTIC_CODES7.UNSUPPORTED_COMMAND,
+    code: CLI_DIAGNOSTIC_CODES8.UNSUPPORTED_COMMAND,
     command,
     detailLines: [
       [
@@ -3032,7 +3156,7 @@ async function renderDoctorJson() {
   }, null, 2));
   if (checks.some((check) => check.status === "fail")) {
     throw createCliCommandError4({
-      code: CLI_DIAGNOSTIC_CODES7.DOCTOR_CHECK_FAILED,
+      code: CLI_DIAGNOSTIC_CODES8.DOCTOR_CHECK_FAILED,
       command: "doctor",
       detailLines: getDoctorFailureDetailLines(checks),
       summary: "One or more doctor checks failed."
@@ -3049,7 +3173,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
       const { formatAddHelpText } = await import("@wp-typia/project-tools/cli-add");
       printLine(formatAddHelpText());
       throw createCliCommandError3({
-        code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
+        code: CLI_DIAGNOSTIC_CODES8.MISSING_ARGUMENT,
         command: "add",
         detailLines: [
           `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`
@@ -3097,7 +3221,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
     const projectDir = positionals[1];
     if (!projectDir) {
       throw createCliCommandError3({
-        code: CLI_DIAGNOSTIC_CODES7.MISSING_ARGUMENT,
+        code: CLI_DIAGNOSTIC_CODES8.MISSING_ARGUMENT,
         command: "create",
         detailLines: [
           "`wp-typia create` requires <project-dir>.",
@@ -3208,7 +3332,7 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
     const resolvedSubcommand = templateId ? "inspect" : subcommand ?? "list";
     if (resolvedSubcommand !== "list" && resolvedSubcommand !== "inspect") {
       throw createCliCommandError3({
-        code: CLI_DIAGNOSTIC_CODES7.INVALID_COMMAND,
+        code: CLI_DIAGNOSTIC_CODES8.INVALID_COMMAND,
         command: "templates",
         detailLines: [
           `Unknown templates subcommand "${resolvedSubcommand}". Expected list or inspect.`
@@ -3234,7 +3358,8 @@ 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 outputFormatArgv = normalizeCliOutputFormatArgv(argvWithoutConfigOverride);
+  const { argv: cliArgv, flags } = parseGlobalFlags(outputFormatArgv);
   const { flags: commandFlags, positionals } = parseArgv(cliArgv);
   const rawMergedFlags = {
     ...commandFlags,
@@ -3291,9 +3416,13 @@ async function runNodeCliEntrypoint(argv = process.argv.slice(2)) {
     await runNodeCli(argv);
   } catch (error) {
     if (prefersStructuredErrorOutput) {
+      const diagnostic = createCliCommandError3({
+        command: resolveCanonicalCommandContext(argv),
+        error
+      });
       process.stderr.write(`${JSON.stringify({
         ok: false,
-        error: serializeCliDiagnosticError2(error)
+        error: serializeCliDiagnosticError2(diagnostic)
       }, null, 2)}
 `);
       process.exitCode = 1;
@@ -3310,4 +3439,4 @@ export {
   hasFlagBeforeTerminator
 };
 
-//# debugId=8CAE70B24462975F64756E2164756E21
+//# debugId=C0474E5751A0C9C164756E2164756E21