wp-typia 0.19.0 → 0.20.0

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.19.0",
+  version: "0.20.0",
   description: "Canonical CLI package for wp-typia scaffolding and project workflows",
   packageManager: "bun@1.3.11",
   type: "module",
@@ -19,14 +19,17 @@ var package_default = {
   scripts: {
     generate: "bun scripts/generate-bunli-metadata.ts",
     build: "bun run generate && bun scripts/build-bunli-runtime.ts",
+    "build:standalone": "bun scripts/build-standalone-runtime.ts --targets native --outdir ./dist-standalone",
+    "build:standalone:release": "bun scripts/build-standalone-runtime.ts --targets darwin-arm64,darwin-x64,linux-arm64,linux-x64,windows-x64 --outdir ./.cache/standalone/raw",
     "bunli:generate": "bun run generate",
     "bunli:build": "bun run build",
     "bunli:dev": "bun src/cli.ts",
     "bunli:test": "bun test tests/*.test.ts",
     dev: "bun run build && node bin/wp-typia.js",
+    "standalone:prepare-release-assets": "bun scripts/prepare-standalone-release-assets.ts --input-dir ./.cache/standalone/raw --outdir ./.cache/standalone/release-assets",
     test: "cd ../wp-typia-project-tools && bun run build && cd ../wp-typia && bun run build && bun test tests/*.test.ts",
     "test:coverage": "cd ../wp-typia-project-tools && bun run build && cd ../wp-typia && bun run build && bun test tests/*.test.ts --coverage --coverage-reporter=lcov --coverage-dir=coverage",
-    clean: "rm -rf .bunli dist-bunli",
+    clean: "rm -rf .bunli .cache/standalone dist-bunli dist-standalone",
     prepack: "bun run build"
   },
   keywords: [
@@ -67,7 +70,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.19.0",
+    "@wp-typia/project-tools": "0.19.1",
     "better-result": "^2.7.0",
     react: "^19.2.5",
     "react-dom": "^19.2.5",
@@ -91,8 +94,10 @@ var package_default = {
 
 // src/node-cli.ts
 import {
+  CLI_DIAGNOSTIC_CODES,
   createCliCommandError,
-  formatCliDiagnosticError
+  formatCliDiagnosticError,
+  serializeCliDiagnosticError
 } from "@wp-typia/project-tools/cli-diagnostics";
 
 // src/command-option-metadata.ts
@@ -108,7 +113,7 @@ var CREATE_OPTION_METADATA = {
   },
   "dry-run": {
     argumentKind: "flag",
-    description: "Preview scaffold output without writing files to the target directory.",
+    description: "Preview scaffold output for a logical <project-dir> without writing files to the target directory.",
     type: "boolean"
   },
   "external-layer-id": {
@@ -203,7 +208,7 @@ var ADD_OPTION_METADATA = {
   },
   "dry-run": {
     argumentKind: "flag",
-    description: "Preview workspace file updates without writing them.",
+    description: "Preview workspace file updates and completion guidance without writing them.",
     type: "boolean"
   },
   "external-layer-id": {
@@ -313,6 +318,102 @@ function formatNodeFallbackOptionHelp(metadata) {
     return `- --${name}${short}: ${option.description}`;
   });
 }
+function buildCommandOptionParser(...metadataMaps) {
+  const metadata = Object.assign({}, ...metadataMaps);
+  return {
+    booleanOptionNames: new Set(collectOptionNamesByType(metadata, "boolean")),
+    shortFlagMap: new Map(Object.entries(metadata).flatMap(([name, option]) => option.short ? [[option.short, { name, type: option.type }]] : [])),
+    stringOptionNames: new Set(collectOptionNamesByType(metadata, "string"))
+  };
+}
+function parseCommandArgvWithMetadata(argv, options) {
+  const flags = {};
+  const positionals = [];
+  const booleanOptionNames = new Set(options.parser.booleanOptionNames);
+  for (const optionName of options.extraBooleanOptionNames ?? []) {
+    booleanOptionNames.add(optionName);
+  }
+  for (let index = 0;index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (arg.length === 2 && arg.startsWith("-")) {
+      const shortFlag = options.parser.shortFlagMap.get(arg.slice(1));
+      if (!shortFlag) {
+        throw new Error(`Unknown option \`${arg}\`.`);
+      }
+      if (shortFlag.type === "boolean") {
+        flags[shortFlag.name] = true;
+        continue;
+      }
+      const next = argv[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error(`\`${arg}\` requires a value.`);
+      }
+      flags[shortFlag.name] = next;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const option = arg.slice(2);
+      const separatorIndex = option.indexOf("=");
+      const rawName = separatorIndex === -1 ? option : option.slice(0, separatorIndex);
+      const inlineValue = separatorIndex === -1 ? undefined : option.slice(separatorIndex + 1);
+      if (booleanOptionNames.has(rawName)) {
+        flags[rawName] = true;
+        continue;
+      }
+      if (!options.parser.stringOptionNames.has(rawName)) {
+        throw new Error(`Unknown option \`--${rawName}\`.`);
+      }
+      if (inlineValue !== undefined) {
+        if (!inlineValue) {
+          throw new Error(`\`--${rawName}\` requires a value.`);
+        }
+        flags[rawName] = inlineValue;
+        continue;
+      }
+      const next = argv[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error(`\`--${rawName}\` requires a value.`);
+      }
+      flags[rawName] = next;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option \`${arg}\`.`);
+    }
+    positionals.push(arg);
+  }
+  return {
+    flags,
+    positionals
+  };
+}
+function resolveCommandOptionValues(metadata, options) {
+  const resolved = {};
+  const optionNames = options.optionNames ?? Object.keys(metadata);
+  for (const optionName of optionNames) {
+    const name = String(optionName);
+    const descriptor = metadata[name];
+    if (!descriptor) {
+      continue;
+    }
+    const value = options.flags?.[name] ?? options.defaults?.[name];
+    if (descriptor.type === "boolean") {
+      resolved[name] = Boolean(value ?? false);
+      continue;
+    }
+    resolved[name] = typeof value === "string" ? value : undefined;
+  }
+  return resolved;
+}
 
 // src/node-cli.ts
 import {
@@ -433,8 +534,8 @@ function extractWpTypiaConfigOverride(argv) {
 // src/runtime-bridge-add-dry-run.ts
 import fs2 from "node:fs";
 import { promises as fsp } from "node:fs";
-import os2 from "node:os";
 import path2 from "node:path";
+import { createManagedTempRoot } from "@wp-typia/project-tools/temp-roots";
 var SKIPPED_COPY_ROOT_ENTRIES = new Set([".git", "node_modules"]);
 var SKIPPED_COMPARE_ROOT_ENTRIES = new Set([
   ".git",
@@ -540,7 +641,7 @@ async function simulateWorkspaceAddDryRun({
   const { resolveWorkspaceProject } = await import("@wp-typia/project-tools/workspace-project");
   const workspace = resolveWorkspaceProject(cwd);
   const relativeCwd = path2.relative(workspace.projectDir, path2.resolve(cwd));
-  const tempRoot = await fsp.mkdtemp(path2.join(os2.tmpdir(), "wp-typia-add-plan-"));
+  const { path: tempRoot, cleanup } = await createManagedTempRoot("wp-typia-add-plan-");
   const simulatedProjectDir = path2.join(tempRoot, "workspace");
   try {
     await copyWorkspaceProject(workspace.projectDir, simulatedProjectDir);
@@ -553,11 +654,13 @@ async function simulateWorkspaceAddDryRun({
       result
     };
   } finally {
-    await fsp.rm(tempRoot, { force: true, recursive: true });
+    await cleanup();
   }
 }
 
 // src/runtime-bridge-output.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
 import { formatPackageExecCommand } from "@wp-typia/project-tools/package-managers";
 function printCompletionPayload(payload, options = {}) {
   const printLine = options.printLine ?? console.log;
@@ -636,6 +739,32 @@ function buildCreateDryRunPayload(flow) {
     warningLines: flow.result.warnings
   };
 }
+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) {
   const summaryLines = options.lines.filter((line) => line.trim().length > 0);
   return {
@@ -644,9 +773,20 @@ function buildMigrationCompletionPayload(options) {
   };
 }
 function buildAddCompletionPayload(options) {
+  const verificationLines = [
+    formatPackageExecCommand(options.packageManager ?? inferProjectPackageManager(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.";
   switch (options.kind) {
     case "variation":
       return {
+        nextSteps: [
+          `Review src/blocks/${options.values.blockSlug}/variations/${options.values.variationSlug}.ts.`,
+          "Run your workspace build or dev command to pick up the new variation."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Variation: ${options.values.variationSlug}`,
           `Target block: ${options.values.blockSlug}`,
@@ -656,6 +796,13 @@ function buildAddCompletionPayload(options) {
       };
     case "pattern":
       return {
+        nextSteps: [
+          `Review src/patterns/${options.values.patternSlug}.php.`,
+          "Run your workspace build or dev command to verify the new pattern registration."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Pattern: ${options.values.patternSlug}`,
           `Project directory: ${options.projectDir}`
@@ -664,6 +811,13 @@ function buildAddCompletionPayload(options) {
       };
     case "binding-source":
       return {
+        nextSteps: [
+          `Review src/bindings/${options.values.bindingSourceSlug}/server.php and src/bindings/${options.values.bindingSourceSlug}/editor.ts.`,
+          "Run your workspace build or dev command to verify the binding source hooks and editor registration."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Binding source: ${options.values.bindingSourceSlug}`,
           `Project directory: ${options.projectDir}`
@@ -672,6 +826,13 @@ function buildAddCompletionPayload(options) {
       };
     case "rest-resource":
       return {
+        nextSteps: [
+          `Review src/rest/${options.values.restResourceSlug}/ and inc/rest/${options.values.restResourceSlug}.php.`,
+          "Run your workspace build or dev command to verify the generated REST resource contract."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `REST resource: ${options.values.restResourceSlug}`,
           `Namespace: ${options.values.namespace}`,
@@ -682,6 +843,13 @@ function buildAddCompletionPayload(options) {
       };
     case "editor-plugin":
       return {
+        nextSteps: [
+          `Review src/editor-plugins/${options.values.editorPluginSlug}/.`,
+          "Run your workspace build or dev command to verify the new editor plugin registration."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Editor plugin: ${options.values.editorPluginSlug}`,
           `Slot: ${options.values.slot}`,
@@ -691,6 +859,13 @@ function buildAddCompletionPayload(options) {
       };
     case "hooked-block":
       return {
+        nextSteps: [
+          `Review src/blocks/${options.values.blockSlug}/block.json for the new blockHooks entry.`,
+          "Run your workspace build or dev command to verify the updated hooked-block metadata."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Block: ${options.values.blockSlug}`,
           `Anchor: ${options.values.anchorBlockName}`,
@@ -701,6 +876,13 @@ function buildAddCompletionPayload(options) {
       };
     default:
       return {
+        nextSteps: [
+          "Review the generated sources under src/blocks/ and the updated scripts/block-config.ts entry.",
+          "Run your workspace build or dev command to verify the new scaffolded block family."
+        ],
+        optionalLines: verificationLines,
+        optionalNote: verificationNote,
+        optionalTitle: "Verify workspace health (optional):",
         summaryLines: [
           `Blocks: ${options.values.blockSlugs}`,
           `Template family: ${options.values.templateId}`,
@@ -742,10 +924,19 @@ function toExternalLayerPromptOptions(options) {
     value: option.id
   }));
 }
+
+// src/runtime-capabilities.ts
+function isInteractiveTerminal({
+  stdin = process.stdin,
+  stdout = process.stdout,
+  term = process.env.TERM
+} = {}) {
+  return Boolean(stdin?.isTTY) && Boolean(stdout?.isTTY) && term !== "dumb";
+}
 // src/runtime-bridge-sync.ts
 import { spawnSync } from "node:child_process";
-import fs3 from "node:fs";
-import path3 from "node:path";
+import fs4 from "node:fs";
+import path4 from "node:path";
 var SYNC_INSTALL_MARKERS = ["node_modules", ".pnp.cjs", ".pnp.loader.mjs"];
 var LOCAL_SYNC_TOOL_PATTERN = /(^|[\s;&|()])(?:tsx|wp-scripts)(?=($|[\s;&|()]))/u;
 function formatRunScript(packageManagerId, scriptName, extraArgs = "") {
@@ -774,7 +965,7 @@ function formatInstallCommand(packageManagerId) {
   }
 }
 function getSyncRootError(cwd) {
-  return new Error(`No generated wp-typia project root was found at ${cwd}. Run \`wp-typia sync\` from a scaffolded project or official workspace root.`);
+  return new Error(`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 ?? "");
@@ -786,26 +977,26 @@ function inferSyncPackageManager(cwd, packageManagerField) {
     return "pnpm";
   if (field.startsWith("yarn@"))
     return "yarn";
-  if (fs3.existsSync(path3.join(cwd, "bun.lock")) || fs3.existsSync(path3.join(cwd, "bun.lockb"))) {
+  if (fs4.existsSync(path4.join(cwd, "bun.lock")) || fs4.existsSync(path4.join(cwd, "bun.lockb"))) {
     return "bun";
   }
-  if (fs3.existsSync(path3.join(cwd, "pnpm-lock.yaml"))) {
+  if (fs4.existsSync(path4.join(cwd, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (fs3.existsSync(path3.join(cwd, "yarn.lock")) || fs3.existsSync(path3.join(cwd, ".pnp.cjs")) || fs3.existsSync(path3.join(cwd, ".pnp.loader.mjs")) || fs3.existsSync(path3.join(cwd, ".yarnrc.yml"))) {
+  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 (fs3.existsSync(path3.join(cwd, "package-lock.json")) || fs3.existsSync(path3.join(cwd, "npm-shrinkwrap.json"))) {
+  if (fs4.existsSync(path4.join(cwd, "package-lock.json")) || fs4.existsSync(path4.join(cwd, "npm-shrinkwrap.json"))) {
     return "npm";
   }
   return "npm";
 }
 function resolveSyncProjectContext(cwd) {
-  const packageJsonPath = path3.join(cwd, "package.json");
-  if (!fs3.existsSync(packageJsonPath)) {
+  const packageJsonPath = path4.join(cwd, "package.json");
+  if (!fs4.existsSync(packageJsonPath)) {
     throw getSyncRootError(cwd);
   }
-  const packageJson = JSON.parse(fs3.readFileSync(packageJsonPath, "utf8"));
+  const packageJson = JSON.parse(fs4.readFileSync(packageJsonPath, "utf8"));
   const scripts = packageJson.scripts ?? {};
   const syncScripts = {
     sync: typeof scripts.sync === "string" ? scripts.sync : undefined,
@@ -823,12 +1014,12 @@ function resolveSyncProjectContext(cwd) {
   };
 }
 function findInstalledDependencyMarkerDir(projectDir) {
-  let currentDir = path3.resolve(projectDir);
+  let currentDir = path4.resolve(projectDir);
   while (true) {
-    if (SYNC_INSTALL_MARKERS.some((marker) => fs3.existsSync(path3.join(currentDir, marker)))) {
+    if (SYNC_INSTALL_MARKERS.some((marker) => fs4.existsSync(path4.join(currentDir, marker)))) {
       return currentDir;
     }
-    const parentDir = path3.dirname(currentDir);
+    const parentDir = path4.dirname(currentDir);
     if (parentDir === currentDir) {
       return null;
     }
@@ -950,6 +1141,29 @@ function pushFlag(argv, name, value) {
   }
   argv.push(`--${name}`, String(value));
 }
+async function executeWorkspaceAddWithOptionalDryRun(options) {
+  const simulated = options.dryRun ? await simulateWorkspaceAddDryRun({
+    cwd: options.cwd,
+    execute: options.execute
+  }) : null;
+  const result = simulated?.result ?? await options.execute(options.cwd);
+  const completion = options.buildCompletion(result);
+  if (!options.dryRun) {
+    return emitCompletion(completion, {
+      emitOutput: options.emitOutput ?? true,
+      printLine: options.printLine,
+      warnLine: options.warnLine
+    });
+  }
+  return emitCompletion(buildAddDryRunPayload({
+    completion,
+    fileOperations: simulated.fileOperations
+  }), {
+    emitOutput: options.emitOutput ?? true,
+    printLine: options.printLine,
+    warnLine: options.warnLine
+  });
+}
 var PACKAGE_MANAGER_PROMPT_OPTIONS = [
   { label: "npm", value: "npm", hint: "Use npm" },
   { label: "pnpm", value: "pnpm", hint: "Use pnpm" },
@@ -997,7 +1211,7 @@ async function executeCreateCommand({
     loadCliScaffoldRuntime(),
     loadCliTemplatesRuntime()
   ]);
-  const shouldPrompt = interactive ?? (!Boolean(flags.yes) && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY));
+  const shouldPrompt = interactive ?? (!Boolean(flags.yes) && isInteractiveTerminal());
   const activePrompt = shouldPrompt ? prompt ?? createReadlinePrompt() : undefined;
   const shouldPromptForExternalLayerSelection = Boolean(activePrompt) && activePrompt !== prompt;
   const effectiveYes = Boolean(flags.yes) || Boolean(flags["dry-run"]) && !Boolean(activePrompt);
@@ -1074,15 +1288,14 @@ async function executeAddCommand({
   prompt,
   warnLine = console.warn
 }) {
-  if (!kind) {
-    const { formatAddHelpText } = await loadCliAddRuntime();
-    printLine(formatAddHelpText());
-    return;
-  }
-  const addRuntime = await loadCliAddRuntime();
   let activePrompt;
   const dryRun = Boolean(flags["dry-run"]);
   try {
+    const addRuntime = await loadCliAddRuntime();
+    if (!kind) {
+      printLine(addRuntime.formatAddHelpText());
+      throw new Error("`wp-typia add` requires <kind>. Usage: wp-typia add <block|variation|pattern|binding-source|rest-resource|editor-plugin|hooked-block> ...");
+    }
     if (kind === "variation") {
       if (!name) {
         throw new Error("`wp-typia add variation` requires <name>. Usage: wp-typia add variation <name> --block <block-slug>");
@@ -1091,94 +1304,69 @@ async function executeAddCommand({
       if (!blockSlug) {
         throw new Error("`wp-typia add variation` requires --block <block-slug>.");
       }
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "variation",
+          projectDir: result.projectDir,
+          values: {
+            blockSlug: result.blockSlug,
+            variationSlug: result.variationSlug
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddVariationCommand({
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddVariationCommand({
           blockName: blockSlug,
-          cwd: simulatedCwd,
+          cwd: targetCwd,
           variationName: name
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddVariationCommand({
-        blockName: blockSlug,
-        cwd,
-        variationName: name
-      });
-      const completion2 = buildAddCompletionPayload({
-        kind: "variation",
-        projectDir: result2.projectDir,
-        values: {
-          blockSlug: result2.blockSlug,
-          variationSlug: result2.variationSlug
-        }
+        }),
+        printLine
       });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind === "pattern") {
       if (!name) {
         throw new Error("`wp-typia add pattern` requires <name>. Usage: wp-typia add pattern <name>.");
       }
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "pattern",
+          projectDir: result.projectDir,
+          values: {
+            patternSlug: result.patternSlug
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddPatternCommand({
-          cwd: simulatedCwd,
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddPatternCommand({
+          cwd: targetCwd,
           patternName: name
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddPatternCommand({
-        cwd,
-        patternName: name
-      });
-      const completion2 = buildAddCompletionPayload({
-        kind: "pattern",
-        projectDir: result2.projectDir,
-        values: {
-          patternSlug: result2.patternSlug
-        }
+        }),
+        printLine
       });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind === "binding-source") {
       if (!name) {
         throw new Error("`wp-typia add binding-source` requires <name>. Usage: wp-typia add binding-source <name>.");
       }
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "binding-source",
+          projectDir: result.projectDir,
+          values: {
+            bindingSourceSlug: result.bindingSourceSlug
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddBindingSourceCommand({
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddBindingSourceCommand({
           bindingSourceName: name,
-          cwd: simulatedCwd
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddBindingSourceCommand({
-        bindingSourceName: name,
-        cwd
-      });
-      const completion2 = buildAddCompletionPayload({
-        kind: "binding-source",
-        projectDir: result2.projectDir,
-        values: {
-          bindingSourceSlug: result2.bindingSourceSlug
-        }
+          cwd: targetCwd
+        }),
+        printLine
       });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind === "rest-resource") {
       if (!name) {
@@ -1186,71 +1374,52 @@ async function executeAddCommand({
       }
       const methods = readOptionalStringFlag(flags, "methods");
       const namespace = readOptionalStringFlag(flags, "namespace");
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "rest-resource",
+          projectDir: result.projectDir,
+          values: {
+            methods: result.methods.join(", "),
+            namespace: result.namespace,
+            restResourceSlug: result.restResourceSlug
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddRestResourceCommand({
-          cwd: simulatedCwd,
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddRestResourceCommand({
+          cwd: targetCwd,
           methods,
           namespace,
           restResourceName: name
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddRestResourceCommand({
-        cwd,
-        methods,
-        namespace,
-        restResourceName: name
+        }),
+        printLine
       });
-      const completion2 = buildAddCompletionPayload({
-        kind: "rest-resource",
-        projectDir: result2.projectDir,
-        values: {
-          methods: result2.methods.join(", "),
-          namespace: result2.namespace,
-          restResourceSlug: result2.restResourceSlug
-        }
-      });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind === "editor-plugin") {
       if (!name) {
         throw new Error("`wp-typia add editor-plugin` requires <name>. Usage: wp-typia add editor-plugin <name> [--slot <PluginSidebar>].");
       }
       const slot = readOptionalStringFlag(flags, "slot");
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "editor-plugin",
+          projectDir: result.projectDir,
+          values: {
+            editorPluginSlug: result.editorPluginSlug,
+            slot: result.slot
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddEditorPluginCommand({
-          cwd: simulatedCwd,
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddEditorPluginCommand({
+          cwd: targetCwd,
           editorPluginName: name,
           slot
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddEditorPluginCommand({
-        cwd,
-        editorPluginName: name,
-        slot
+        }),
+        printLine
       });
-      const completion2 = buildAddCompletionPayload({
-        kind: "editor-plugin",
-        projectDir: result2.projectDir,
-        values: {
-          editorPluginSlug: result2.editorPluginSlug,
-          slot: result2.slot
-        }
-      });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind === "hooked-block") {
       if (!name) {
@@ -1264,37 +1433,27 @@ async function executeAddCommand({
       if (!position) {
         throw new Error("`wp-typia add hooked-block` requires --position <before|after|firstChild|lastChild>.");
       }
-      const simulated2 = dryRun ? await simulateWorkspaceAddDryRun({
+      return executeWorkspaceAddWithOptionalDryRun({
+        buildCompletion: (result) => buildAddCompletionPayload({
+          kind: "hooked-block",
+          projectDir: result.projectDir,
+          values: {
+            anchorBlockName: result.anchorBlockName,
+            blockSlug: result.blockSlug,
+            position: result.position
+          }
+        }),
         cwd,
-        execute: (simulatedCwd) => addRuntime.runAddHookedBlockCommand({
+        dryRun,
+        emitOutput,
+        execute: (targetCwd) => addRuntime.runAddHookedBlockCommand({
           anchorBlockName,
           blockName: name,
-          cwd: simulatedCwd,
+          cwd: targetCwd,
           position
-        })
-      }) : null;
-      const result2 = simulated2?.result ?? await addRuntime.runAddHookedBlockCommand({
-        anchorBlockName,
-        blockName: name,
-        cwd,
-        position
+        }),
+        printLine
       });
-      const completion2 = buildAddCompletionPayload({
-        kind: "hooked-block",
-        projectDir: result2.projectDir,
-        values: {
-          anchorBlockName: result2.anchorBlockName,
-          blockSlug: result2.blockSlug,
-          position: result2.position
-        }
-      });
-      if (!dryRun) {
-        return emitCompletion(completion2, { emitOutput, printLine });
-      }
-      return emitCompletion(buildAddDryRunPayload({
-        completion: completion2,
-        fileOperations: simulated2.fileOperations
-      }), { emitOutput, printLine });
     }
     if (kind !== "block") {
       throw new Error(`Unknown add kind "${kind}". Expected one of: block, variation, pattern, binding-source, rest-resource, editor-plugin, hooked-block.`);
@@ -1307,7 +1466,7 @@ async function executeAddCommand({
     }
     const externalLayerId = readOptionalStringFlag(flags, "external-layer-id");
     const externalLayerSource = readOptionalStringFlag(flags, "external-layer-source");
-    const shouldPromptForLayerSelection = Boolean(externalLayerSource) && !Boolean(externalLayerId) && (interactive ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)));
+    const shouldPromptForLayerSelection = Boolean(externalLayerSource) && !Boolean(externalLayerId) && (interactive ?? isInteractiveTerminal());
     const promptRuntime = shouldPromptForLayerSelection ? await loadCliPromptRuntime() : undefined;
     activePrompt = shouldPromptForLayerSelection ? prompt ?? promptRuntime?.createReadlinePrompt() : undefined;
     const selectPrompt = activePrompt;
@@ -1316,12 +1475,23 @@ async function executeAddCommand({
     const innerBlocksPreset = readOptionalStringFlag(flags, "inner-blocks-preset");
     const persistencePolicy = readOptionalStringFlag(flags, "persistence-policy");
     const resolvedTemplateId = readOptionalStringFlag(flags, "template");
-    const simulated = dryRun ? await simulateWorkspaceAddDryRun({
+    return executeWorkspaceAddWithOptionalDryRun({
+      buildCompletion: (result) => buildAddCompletionPayload({
+        kind: "block",
+        projectDir: result.projectDir,
+        values: {
+          blockSlugs: result.blockSlugs.join(", "),
+          templateId: result.templateId
+        },
+        warnings: result.warnings
+      }),
       cwd,
-      execute: (simulatedCwd) => addRuntime.runAddBlockCommand({
+      dryRun,
+      emitOutput,
+      execute: (targetCwd) => addRuntime.runAddBlockCommand({
         alternateRenderTargets,
         blockName: name,
-        cwd: simulatedCwd,
+        cwd: targetCwd,
         dataStorageMode,
         externalLayerId,
         externalLayerSource,
@@ -1329,36 +1499,10 @@ async function executeAddCommand({
         persistencePolicy,
         selectExternalLayerId: selectPrompt ? (options) => selectPrompt.select("Select an external layer", toExternalLayerPromptOptions(options), 1) : undefined,
         templateId: resolvedTemplateId
-      })
-    }) : null;
-    const result = simulated?.result ?? await addRuntime.runAddBlockCommand({
-      alternateRenderTargets,
-      blockName: name,
-      cwd,
-      dataStorageMode,
-      externalLayerId,
-      externalLayerSource,
-      innerBlocksPreset,
-      persistencePolicy,
-      selectExternalLayerId: selectPrompt ? (options) => selectPrompt.select("Select an external layer", toExternalLayerPromptOptions(options), 1) : undefined,
-      templateId: resolvedTemplateId
-    });
-    const completion = buildAddCompletionPayload({
-      kind: "block",
-      projectDir: result.projectDir,
-      values: {
-        blockSlugs: result.blockSlugs.join(", "),
-        templateId: result.templateId
-      },
-      warnings: result.warnings
+      }),
+      printLine,
+      warnLine
     });
-    if (!dryRun) {
-      return emitCompletion(completion, { emitOutput, printLine, warnLine });
-    }
-    return emitCompletion(buildAddDryRunPayload({
-      completion,
-      fileOperations: simulated.fileOperations
-    }), { emitOutput, printLine, warnLine });
   } catch (error) {
     if (!shouldWrapCliCommandError({ emitOutput })) {
       throw error;
@@ -1464,7 +1608,7 @@ async function executeMigrateCommand({
 }
 
 // src/command-contract.ts
-import path4 from "node:path";
+import path5 from "node:path";
 var WP_TYPIA_CANONICAL_CREATE_USAGE = "wp-typia create <project-dir>";
 var WP_TYPIA_POSITIONAL_ALIAS_USAGE = "wp-typia <project-dir>";
 var WP_TYPIA_CANONICAL_MIGRATE_USAGE = "wp-typia migrate <subcommand>";
@@ -1482,6 +1626,7 @@ var WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES = [
   "completions",
   "complete"
 ];
+var SHARED_OPTION_PARSER = buildCommandOptionParser(ADD_OPTION_METADATA, GLOBAL_OPTION_METADATA, CREATE_OPTION_METADATA, MIGRATE_OPTION_METADATA, TEMPLATES_OPTION_METADATA);
 var STRING_OPTION_NAMES_BY_COMMAND = {
   add: new Set(collectOptionNamesByType(ADD_OPTION_METADATA, "string")),
   create: new Set(collectOptionNamesByType(CREATE_OPTION_METADATA, "string")),
@@ -1489,13 +1634,7 @@ var STRING_OPTION_NAMES_BY_COMMAND = {
   templates: new Set(collectOptionNamesByType(TEMPLATES_OPTION_METADATA, "string"))
 };
 var GLOBAL_STRING_OPTION_NAMES = new Set(collectOptionNamesByType(GLOBAL_OPTION_METADATA, "string"));
-var SHORT_OPTION_NAMES_WITH_VALUES = new Set(Object.values({
-  ...ADD_OPTION_METADATA,
-  ...GLOBAL_OPTION_METADATA,
-  ...CREATE_OPTION_METADATA,
-  ...MIGRATE_OPTION_METADATA,
-  ...TEMPLATES_OPTION_METADATA
-}).filter((option) => option.type === "string").flatMap((option) => ("short" in option) && typeof option.short === "string" ? [option.short] : []));
+var SHORT_OPTION_NAMES_WITH_VALUES = new Set([...SHARED_OPTION_PARSER.shortFlagMap.entries()].filter(([, option]) => option.type === "string").map(([short]) => short));
 function isLongOptionValueConsumer(optionName) {
   if (GLOBAL_STRING_OPTION_NAMES.has(optionName)) {
     return true;
@@ -1649,7 +1788,7 @@ function looksLikeStructuredProjectInput(value) {
   return value.startsWith("@") && value.includes("/");
 }
 function assertPositionalAliasProjectDir(projectDir) {
-  const normalizedProjectDir = path4.normalize(projectDir).replace(/[\\/]+$/u, "") || path4.normalize(projectDir);
+  const normalizedProjectDir = path5.normalize(projectDir).replace(/[\\/]+$/u, "") || path5.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.`);
   }
@@ -1689,28 +1828,8 @@ function normalizeWpTypiaArgv(argv) {
 }
 
 // src/node-cli.ts
-var STRING_FLAG_NAMES = new Set([
-  ...collectOptionNamesByType(GLOBAL_OPTION_METADATA, "string"),
-  ...collectOptionNamesByType(CREATE_OPTION_METADATA, "string"),
-  ...collectOptionNamesByType(ADD_OPTION_METADATA, "string"),
-  ...collectOptionNamesByType(MIGRATE_OPTION_METADATA, "string"),
-  ...collectOptionNamesByType(TEMPLATES_OPTION_METADATA, "string")
-]);
-var BOOLEAN_FLAG_NAMES = new Set([
-  ...collectOptionNamesByType(CREATE_OPTION_METADATA, "boolean"),
-  ...collectOptionNamesByType(ADD_OPTION_METADATA, "boolean"),
-  ...collectOptionNamesByType(MIGRATE_OPTION_METADATA, "boolean"),
-  "check",
-  "help",
-  "version"
-]);
-var SHORT_FLAG_MAP = new Map(Object.entries({
-  ...GLOBAL_OPTION_METADATA,
-  ...CREATE_OPTION_METADATA,
-  ...ADD_OPTION_METADATA,
-  ...MIGRATE_OPTION_METADATA,
-  ...TEMPLATES_OPTION_METADATA
-}).flatMap(([name, option]) => ("short" in option) && typeof option.short === "string" ? [[option.short, { name, type: option.type }]] : []));
+var NODE_FALLBACK_OPTION_PARSER = buildCommandOptionParser(GLOBAL_OPTION_METADATA, CREATE_OPTION_METADATA, ADD_OPTION_METADATA, MIGRATE_OPTION_METADATA, TEMPLATES_OPTION_METADATA);
+var NODE_FALLBACK_BOOLEAN_OPTION_NAMES = ["check", "help", "version"];
 var NODE_FALLBACK_RUNTIME_SUMMARY_LINES = [
   "Runtime: Node fallback",
   "Human-readable fallback for common non-interactive create/add/migrate flows, doctor, sync, templates, --help, and --version when Bun is unavailable.",
@@ -1782,84 +1901,24 @@ async function applyNodeFallbackConfigDefaults(command, subcommand, flags, confi
     config = mergeWpTypiaUserConfig(config, overrideConfig);
   }
   if (command === "create") {
-    return {
-      ...getCreateDefaults(config),
-      ...flags
-    };
+    return resolveCommandOptionValues(CREATE_OPTION_METADATA, {
+      defaults: getCreateDefaults(config),
+      flags
+    });
   }
   if (command === "add" && subcommand === "block") {
-    return {
-      ...getAddBlockDefaults(config),
-      ...flags
-    };
+    return resolveCommandOptionValues(ADD_OPTION_METADATA, {
+      defaults: getAddBlockDefaults(config),
+      flags
+    });
   }
   return flags;
 }
 function parseArgv(argv) {
-  const flags = {};
-  const positionals = [];
-  for (let index = 0;index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (!arg) {
-      continue;
-    }
-    if (arg === "--") {
-      positionals.push(...argv.slice(index + 1));
-      break;
-    }
-    if (arg.length === 2 && arg.startsWith("-")) {
-      const shortFlag = SHORT_FLAG_MAP.get(arg.slice(1));
-      if (!shortFlag) {
-        throw new Error(`Unknown option \`${arg}\`.`);
-      }
-      if (shortFlag.type === "boolean") {
-        flags[shortFlag.name] = true;
-        continue;
-      }
-      const next = argv[index + 1];
-      if (!next || next.startsWith("-")) {
-        throw new Error(`\`${arg}\` requires a value.`);
-      }
-      flags[shortFlag.name] = next;
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("--")) {
-      const option = arg.slice(2);
-      const separatorIndex = option.indexOf("=");
-      const rawName = separatorIndex === -1 ? option : option.slice(0, separatorIndex);
-      const inlineValue = separatorIndex === -1 ? undefined : option.slice(separatorIndex + 1);
-      if (BOOLEAN_FLAG_NAMES.has(rawName)) {
-        flags[rawName] = true;
-        continue;
-      }
-      if (!STRING_FLAG_NAMES.has(rawName)) {
-        throw new Error(`Unknown option \`--${rawName}\`.`);
-      }
-      if (inlineValue !== undefined) {
-        if (!inlineValue) {
-          throw new Error(`\`--${rawName}\` requires a value.`);
-        }
-        flags[rawName] = inlineValue;
-        continue;
-      }
-      const next = argv[index + 1];
-      if (!next || next.startsWith("-")) {
-        throw new Error(`\`--${rawName}\` requires a value.`);
-      }
-      flags[rawName] = next;
-      index += 1;
-      continue;
-    }
-    if (arg.startsWith("-")) {
-      throw new Error(`Unknown option \`${arg}\`.`);
-    }
-    positionals.push(arg);
-  }
-  return {
-    flags,
-    positionals
-  };
+  return parseCommandArgvWithMetadata(argv, {
+    extraBooleanOptionNames: NODE_FALLBACK_BOOLEAN_OPTION_NAMES,
+    parser: NODE_FALLBACK_OPTION_PARSER
+  });
 }
 function renderGeneralHelp() {
   printBlock2([
@@ -1941,22 +2000,37 @@ function renderTemplatesJson(flags, subcommand) {
   }
   const templateId = flags.id;
   if (!templateId) {
-    throw new Error("`wp-typia templates inspect` requires <template-id>.");
+    throw createCliCommandError({
+      code: CLI_DIAGNOSTIC_CODES.MISSING_ARGUMENT,
+      command: "templates",
+      detailLines: ["`wp-typia templates inspect` requires <template-id>."]
+    });
   }
   const template = getTemplateById(templateId);
   if (!template) {
-    throw new Error(`Unknown template "${templateId}".`);
+    throw createCliCommandError({
+      code: CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT,
+      command: "templates",
+      detailLines: [`Unknown template "${templateId}".`]
+    });
   }
   printLine(JSON.stringify({
     template
   }, null, 2));
 }
 function renderUnsupportedCommand(command) {
-  throw new Error([
-    `The Bun-free fallback runtime does not support \`${command}\` yet.`,
-    "Supported without Bun: `--version`, `--help`, non-interactive `create`/`add`/`migrate`, `doctor`, `sync`, `templates list`, and `templates inspect`.",
-    "Install Bun 1.3.11+ or use `bunx wp-typia ...` for the full Bunli-powered runtime."
-  ].join(" "));
+  throw createCliCommandError({
+    code: CLI_DIAGNOSTIC_CODES.UNSUPPORTED_COMMAND,
+    command,
+    detailLines: [
+      [
+        `The Bun-free fallback runtime does not support \`${command}\` yet.`,
+        "Supported without Bun: `--version`, `--help`, non-interactive `create`/`add`/`migrate`, `doctor`, `sync`, `templates list`, and `templates inspect`.",
+        "Install Bun 1.3.11+ or use `bunx wp-typia ...` for the full Bunli-powered runtime."
+      ].join(" ")
+    ],
+    summary: "This command requires the Bun-powered runtime."
+  });
 }
 async function renderDoctorJson() {
   const [{ getDoctorChecks }, { createCliCommandError: createCliCommandError2, getDoctorFailureDetailLines }] = await Promise.all([
@@ -2043,7 +2117,10 @@ async function runNodeCli(argv = process.argv.slice(2)) {
     if (!projectDir) {
       throw createCliCommandError({
         command: "create",
-        detailLines: ["`wp-typia create` requires <project-dir>."]
+        detailLines: [
+          "`wp-typia create` requires <project-dir>.",
+          "`--dry-run` still needs a logical project directory name because wp-typia derives slugs, package names, and planned file paths from it."
+        ]
       });
     }
     await executeCreateCommand({
@@ -2055,6 +2132,16 @@ async function runNodeCli(argv = process.argv.slice(2)) {
     return;
   }
   if (command === "add") {
+    if (!positionals[1]) {
+      const { formatAddHelpText } = await import("@wp-typia/project-tools/cli-add");
+      printLine(formatAddHelpText());
+      throw createCliCommandError({
+        command: "add",
+        detailLines: [
+          "`wp-typia add` requires <kind>. Usage: wp-typia add <block|variation|pattern|binding-source|rest-resource|editor-plugin|hooked-block> ..."
+        ]
+      });
+    }
     await executeAddCommand({
       cwd: process.cwd(),
       flags: mergedFlags,
@@ -2081,10 +2168,17 @@ async function runNodeCli(argv = process.argv.slice(2)) {
     return;
   }
   if (command === "sync") {
-    await executeSyncCommand({
-      check: Boolean(mergedFlags.check),
-      cwd: process.cwd()
-    });
+    try {
+      await executeSyncCommand({
+        check: Boolean(mergedFlags.check),
+        cwd: process.cwd()
+      });
+    } catch (error) {
+      throw createCliCommandError({
+        command: "sync",
+        error
+      });
+    }
     return;
   }
   renderUnsupportedCommand(command ?? "(missing)");
@@ -2093,8 +2187,23 @@ async function runNodeCliEntrypoint(argv = process.argv.slice(2)) {
   try {
     await runNodeCli(argv);
   } catch (error) {
+    let prefersStructuredErrorOutput = false;
+    try {
+      const normalizedArgv = normalizeWpTypiaArgv(argv);
+      const { argv: argvWithoutConfigOverride } = extractWpTypiaConfigOverride(normalizedArgv);
+      const { flags } = parseGlobalFlags(argvWithoutConfigOverride);
+      prefersStructuredErrorOutput = flags.format === "json";
+    } catch {}
+    if (prefersStructuredErrorOutput) {
+      console.error(JSON.stringify({
+        ok: false,
+        error: serializeCliDiagnosticError(error)
+      }, null, 2));
+      process.exitCode = 1;
+      return;
+    }
     console.error(`Error: ${await formatCliDiagnosticError(error)}`);
-    process.exit(1);
+    process.exitCode = 1;
   }
 }
 export {
@@ -2104,4 +2213,4 @@ export {
   hasFlagBeforeTerminator
 };
 
-//# debugId=7B916CF74AF5C70064756E2164756E21
+//# debugId=F7CDE5FD3282D0B964756E2164756E21