terminal-pilot 0.0.33 → 0.0.34

package/dist/cli.js

@@ -920,7 +920,7 @@ function formatColumns(opts) {
       return [`${firstIndent}${row.left}`];
     }
     const rightLines = wrapWords(row.right, rightWidth);
-    if (visibleWidth(row.left) > leftWidth) {
+    if (visibleWidth(row.left) >= leftWidth) {
       return [
         `${firstIndent}${row.left}`,
         ...rightLines.map((line) => `${continuationIndent}${line}`)
@@ -1057,7 +1057,7 @@ function formatColumns2(opts) {
       return [`${firstIndent}${row.left}`];
     }
     const rightLines = wrapWords2(row.right, rightWidth);
-    if (row.left.length > leftWidth) {
+    if (row.left.length >= leftWidth) {
       return [
         `${firstIndent}${row.left}`,
         ...rightLines.map((line) => `${continuationIndent}${line}`)
@@ -1877,9 +1877,9 @@ var GLYPHS = {
   barEnd: glyph("\u2514", "-"),
   radioActive: glyph("\u25CF", ">"),
   radioInactive: glyph("\u25CB", " "),
-  checkboxActive: glyph("\u25FB", "[ ]"),
-  checkboxSelected: glyph("\u25FC", "[+]"),
-  checkboxInactive: glyph("\u25FB", "[ ]"),
+  checkboxActive: "[ ]",
+  checkboxSelected: "[x]",
+  checkboxInactive: "[ ]",
   passwordMask: glyph("\u2022", "*"),
   ellipsis: "..."
 };
@@ -1930,6 +1930,9 @@ function mapKey(name, char) {
   if (char === " ") {
     return "space";
   }
+  if (char !== void 0 && aliases[char] !== void 0) {
+    return aliases[char];
+  }
   if (!name) {
     return void 0;
   }
@@ -3309,6 +3312,50 @@ var S = {
   Json
 };
 
+// ../toolcraft/src/runtime-logging.ts
+var LOG_LEVEL_RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5
+};
+var LOG_LEVELS = Object.freeze([
+  "silent",
+  "error",
+  "warn",
+  "info",
+  "debug",
+  "trace"
+]);
+function isLogLevel(value) {
+  return LOG_LEVELS.includes(value);
+}
+function shouldEmitDiagnostic(eventLevel, configuredLevel) {
+  if (eventLevel === "silent" || configuredLevel === "silent") {
+    return false;
+  }
+  return LOG_LEVEL_RANK[eventLevel] <= LOG_LEVEL_RANK[configuredLevel];
+}
+function createRuntimeLogger(options = {}) {
+  const level = options.level ?? "warn";
+  const sink = options.logger;
+  return {
+    level,
+    emit(event) {
+      if (!shouldEmitDiagnostic(event.level, level)) {
+        return;
+      }
+      if (typeof sink === "function") {
+        sink(event);
+        return;
+      }
+      sink?.emit(event);
+    }
+  };
+}
+
 // ../toolcraft/src/package-metadata.ts
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
@@ -7805,14 +7852,16 @@ function getVisibleCliChildren(root) {
   return root.kind === "group" ? root.children.filter(isNodeVisibleInCli) : [];
 }
 function createHandlerContext(command, params17) {
+  const diagnostics = createRuntimeLogger();
   return {
     params: params17,
     secrets: resolveCommandSecrets(command),
     fetch: globalThis.fetch,
     fs: createFs(),
     env: createEnv(),
-    progress() {
-      return void 0;
+    diagnostics,
+    progress(message2) {
+      diagnostics.emit({ level: "info", message: message2, category: "progress" });
     }
   };
 }
@@ -7885,11 +7934,7 @@ var showParams = S.Object({
   approvalId: S.String()
 });
 var runParams = S.Object({
-  approvalId: S.String(),
-  dryRun: S.Optional(S.Boolean({
-    description: "Preview the approval without prompting or executing it",
-    scope: ["cli"]
-  }))
+  approvalId: S.String()
 });
 var approvalsGroup = markApprovalsBuiltIn(
   defineGroup({
@@ -7946,10 +7991,6 @@ var approvalsGroup = markApprovalsBuiltIn(
         scope: runScope,
         params: runParams,
         handler: async ({ params: params17, runtimeOptions, root }) => {
-          if (params17.dryRun === true) {
-            const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
-            return tasks.get(params17.approvalId);
-          }
           return runApproval(params17.approvalId, runtimeOptions, root);
         },
         render: {
@@ -10348,7 +10389,7 @@ var McpClient = class {
       await onPromptsChanged();
     });
     messageLayer.onNotification("notifications/message", async (params17) => {
-      if (onLog === void 0 || !isObjectRecord5(params17) || !isLogLevel(params17.level)) {
+      if (onLog === void 0 || !isObjectRecord5(params17) || !isLogLevel2(params17.level)) {
         return;
       }
       if (!hasOwn(params17, "data")) {
@@ -11703,7 +11744,7 @@ function hasOwn(value, property) {
 function isRequestId(value) {
   return typeof value === "string" || typeof value === "number";
 }
-function isLogLevel(value) {
+function isLogLevel2(value) {
   return value === "debug" || value === "info" || value === "notice" || value === "warning" || value === "error" || value === "critical" || value === "alert" || value === "emergency";
 }
 function toRequestId(value) {
@@ -13383,6 +13424,125 @@ function getExpectedNumberDescription(schema) {
   return bounds.length === 0 ? type2 : `${type2} ${bounds.join(" and ")}`;
 }
 
+// ../toolcraft/src/api-error-summary.ts
+var REQUEST_ID_FIELDS = ["request_id", "requestId", "id"];
+var CODE_FIELDS = ["code", "error_code", "errorCode", "error"];
+var MESSAGE_FIELDS = ["message", "detail", "title", "error_description"];
+function summarizeHttpError(error3) {
+  const body = redactHttpBody(error3.response.body);
+  const retryAfter = getHeader(error3.response.headers, "retry-after");
+  const message2 = extractMessage(body);
+  const summary = {
+    status: error3.response.status,
+    statusText: error3.response.statusText,
+    requestMethod: error3.request.method,
+    requestUrl: error3.request.url,
+    ...message2 === void 0 ? {} : { message: message2 },
+    ...optionalString("requestId", getHeader(error3.response.headers, "x-request-id") ?? extractFirstString(body, REQUEST_ID_FIELDS)),
+    ...optionalString("code", extractCode(body)),
+    ...optionalString("retryAfter", retryAfter),
+    ...optionalArray("fieldErrors", extractFieldErrors(body)),
+    ...optionalString("hint", createHttpErrorHint(error3.response.status, retryAfter))
+  };
+  return summary;
+}
+function createHttpErrorHint(status, retryAfter) {
+  if (status === 401 || status === 403) {
+    return "Check the configured API credentials and permissions.";
+  }
+  if ((status === 429 || status === 503) && retryAfter !== void 0) {
+    return `Retry after ${retryAfter}.`;
+  }
+  return void 0;
+}
+function extractMessage(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const graphqlMessage = extractGraphQlMessage(body);
+  if (graphqlMessage !== void 0) {
+    return graphqlMessage;
+  }
+  return extractFirstString(body, MESSAGE_FIELDS);
+}
+function extractCode(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const graphqlCode = extractGraphQlCode(body);
+  if (graphqlCode !== void 0) {
+    return graphqlCode;
+  }
+  return extractFirstString(body, CODE_FIELDS);
+}
+function extractGraphQlMessage(body) {
+  const [first] = Array.isArray(body.errors) ? body.errors : [];
+  return isPlainObject4(first) && typeof first.message === "string" ? first.message : void 0;
+}
+function extractGraphQlCode(body) {
+  const [first] = Array.isArray(body.errors) ? body.errors : [];
+  if (!isPlainObject4(first) || !isPlainObject4(first.extensions)) {
+    return void 0;
+  }
+  return typeof first.extensions.code === "string" ? first.extensions.code : void 0;
+}
+function extractFieldErrors(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const candidates = [body.field_errors, body.fieldErrors, body.errors, body.non_field_errors];
+  const flattened = candidates.flatMap((candidate) => flattenFieldErrors(candidate, []));
+  return flattened.length === 0 ? void 0 : flattened;
+}
+function flattenFieldErrors(value, path25) {
+  if (typeof value === "string") {
+    return [{ path: formatPath2(path25), message: value }];
+  }
+  if (Array.isArray(value)) {
+    if (value.every((entry) => typeof entry === "string")) {
+      return value.map((message2) => ({ path: formatPath2(path25), message: message2 }));
+    }
+    return value.flatMap((entry, index) => flattenFieldErrors(entry, [...path25, String(index)]));
+  }
+  if (!isPlainObject4(value)) {
+    return [];
+  }
+  return Object.entries(value).flatMap(([key2, nested]) => flattenFieldErrors(nested, [...path25, key2]));
+}
+function formatPath2(path25) {
+  return path25.length === 0 ? "error" : path25.join(".");
+}
+function extractFirstString(body, fields) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  for (const field of fields) {
+    const value = body[field];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function getHeader(headers, name) {
+  const lowerName = name.toLowerCase();
+  for (const [key2, value] of Object.entries(headers)) {
+    if (key2.toLowerCase() === lowerName && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function optionalString(name, value) {
+  return value === void 0 ? {} : { [name]: value };
+}
+function optionalArray(name, value) {
+  return value === void 0 ? {} : { [name]: value };
+}
+function isPlainObject4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // ../toolcraft/src/renderer.ts
 import YAML from "yaml";
 function isObject(value) {
@@ -13430,6 +13590,9 @@ function unwrapMcpEnvelope(result) {
 function isArrayOfObjects(value) {
   return Array.isArray(value) && value.every((entry) => isObject(entry));
 }
+function isNonEmptyArrayOfObjects(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((entry) => isObject(entry));
+}
 function stringifyValue2(value) {
   if (value === void 0) {
     return "";
@@ -13484,10 +13647,26 @@ function detailRows(result, depth = 0) {
       rows.push(...detailRows(value, depth + 1));
       continue;
     }
+    if (isNonEmptyArrayOfObjects(value)) {
+      rows.push({ label, value: "" });
+      rows.push(...arrayObjectDetailRows(value, depth + 1));
+      continue;
+    }
     rows.push({ label, value: displayScalar(value) });
   }
   return rows;
 }
+function arrayObjectDetailRows(value, depth) {
+  return value.flatMap((entry, index) => {
+    if (value.length === 1) {
+      return detailRows(entry, depth);
+    }
+    return [
+      { label: `${"  ".repeat(depth)}${index + 1}`, value: "" },
+      ...detailRows(entry, depth + 1)
+    ];
+  });
+}
 function displayScalar(value) {
   if (typeof value === "boolean") {
     return value ? "Yes" : "No";
@@ -13518,17 +13697,31 @@ function directScalarRows(result) {
 function directObjectSections(result) {
   return Object.entries(result).filter(([, value]) => isObject(value)).map(([key2, value]) => ({ title: humanizeKey(key2), rows: detailRows(value) })).filter((section) => section.rows.length > 0);
 }
+function directArrayObjectSections(result) {
+  return Object.entries(result).flatMap(([key2, value]) => {
+    if (!isNonEmptyArrayOfObjects(value)) {
+      return [];
+    }
+    const title = humanizeKey(key2);
+    return value.map((entry, index) => ({
+      title: value.length === 1 ? title : `${title} ${index + 1}`,
+      rows: detailRows(entry)
+    })).filter((section) => section.rows.length > 0);
+  });
+}
 function renderObjectCard(result, primitives, title) {
   const scalarRows = directScalarRows(result);
   const nestedSections = directObjectSections(result);
-  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value)).map(([key2, value]) => ({ label: humanizeKey(key2), value: displayScalar(value) }));
+  const arrayObjectSections = directArrayObjectSections(result);
+  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value) && !isNonEmptyArrayOfObjects(value)).map(([key2, value]) => ({ label: humanizeKey(key2), value: displayScalar(value) }));
   return renderDetailCard({
     theme: primitives.getTheme(),
     title,
     sections: [
       { rows: scalarRows },
       ...nestedSections,
-      { title: "Lists", rows: listRows }
+      { title: "Lists", rows: listRows },
+      ...arrayObjectSections
     ]
   });
 }
@@ -13817,11 +14010,12 @@ var RESERVED_SERVICE_NAMES = /* @__PURE__ */ new Set([
   "fetch",
   "fs",
   "env",
+  "diagnostics",
   "progress",
   "runtimeOptions",
   "root"
 ]);
-var RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
+var RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 var NULL_OPTION_VALUE = /* @__PURE__ */ Symbol("toolcraft.cli.null");
 function inferProgramName(argv) {
   const entrypoint = argv[1];
@@ -14458,6 +14652,7 @@ function createOption(field, globalLongOptionFlags) {
 function resolveCLIControls(controls) {
   return {
     debug: controls?.debug === true,
+    logLevel: controls?.logLevel === true,
     output: controls?.output === true,
     verbose: controls?.verbose === true,
     yes: controls?.yes === true
@@ -14477,6 +14672,9 @@ function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
   if (controls.debug) {
     flags.push("--debug");
   }
+  if (controls.logLevel) {
+    flags.push("--log-level");
+  }
   if (controls.verbose) {
     flags.push("--verbose");
   }
@@ -14520,6 +14718,9 @@ function createCommanderOption(flags, description, field) {
 function hasHelpFlag(argv) {
   return argv.some((token) => HELP_FLAGS.has(token));
 }
+function normalizeVerboseAlias(argv) {
+  return argv.map((token) => token === "-v" ? "--verbose" : token);
+}
 function resolveHelpOutput(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index] ?? "";
@@ -14567,7 +14768,7 @@ function findVisibleChild(group, token, scope) {
     (child) => child.name === token || child.aliases.includes(token)
   );
 }
-function resolveHelpTarget(root, argv, scope, rootDisplayName) {
+function resolveHelpTarget(root, argv, scope, rootUsageName, rootDisplayName) {
   const breadcrumb = [rootDisplayName ?? root.name];
   let current = root;
   for (const token of argv.slice(2)) {
@@ -14579,7 +14780,9 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
     }
     const child = findVisibleChild(current, token, scope);
     if (child === void 0) {
-      break;
+      throw new UserError(
+        formatUnknownHelpCommandMessage(current, token, scope, rootUsageName, breadcrumb)
+      );
     }
     breadcrumb.push(child.name);
     current = child;
@@ -14589,6 +14792,16 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
     node: current
   };
 }
+function formatUnknownHelpCommandMessage(group, input, scope, rootUsageName, breadcrumb) {
+  const suggestions = suggest(
+    input,
+    getHelpChildren(group, scope).map((child) => child.name)
+  );
+  const commandPath = breadcrumb.slice(1).join(" ");
+  const helpTarget = commandPath.length === 0 ? rootUsageName : `${rootUsageName} ${commandPath}`;
+  return `${formatSuggestionMessage(`Unknown command "${input}".`, suggestions)}
+Run ${helpTarget} --help for usage.`;
+}
 function formatHelpFieldFlags(field, globalLongOptionFlags) {
   if (field.positionalIndex !== void 0) {
     return formatPositionalToken(field);
@@ -14925,11 +15138,17 @@ function formatGlobalOptionsLine(ctx) {
   if (ctx.controls.output) {
     flags.push("--output <format>");
   }
+  if (ctx.controls.verbose) {
+    flags.push("-v, --verbose");
+  }
   if (ctx.showVersion) {
     flags.push("--version");
   }
   return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
 }
+function formatLeafGlobalOptionsLine(ctx) {
+  return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+}
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
   const seen = /* @__PURE__ */ new Map();
   const visit = (node) => {
@@ -15047,6 +15266,10 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     sections.push(`${text.sectionHeader("Options")}
 ${formatHelpOptionList(optionRows)}`);
   }
+  const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
+  if (builtInLine.length > 0) {
+    sections.push(builtInLine);
+  }
   const secretRows = formatSecretRows(command.secrets);
   if (secretRows.length > 0) {
     sections.push(
@@ -15071,6 +15294,91 @@ ${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`
     sections
   });
 }
+function renderJsonHelp(target, root, casing, globalOptions, rootUsageName) {
+  const globalLongOptionFlags = getGlobalLongOptionFlags(
+    globalOptions.presetsEnabled,
+    globalOptions.showVersion,
+    globalOptions.controls
+  );
+  const node = target.node;
+  if (node.kind === "group") {
+    const commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags);
+    const isRoot = node === root;
+    return `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        kind: "group",
+        name: target.breadcrumb.at(-1) ?? rootUsageName,
+        path: target.breadcrumb.filter((segment) => segment.length > 0),
+        usage: buildUsageLine(
+          target.breadcrumb,
+          rootUsageName,
+          formatGroupUsageSuffix(node, "cli", casing, globalLongOptionFlags)
+        ),
+        ...node.description === void 0 ? {} : { description: node.description },
+        commands: commandRows.map((row) => ({ name: row.name, description: row.description })),
+        options: isRoot ? collectSchemaGlobalFieldRows(node, "cli", casing, globalLongOptionFlags).map((row) => ({
+          name: row.flags.split(/[ ,]+/)[0]?.replace(/^--/, "") ?? row.flags,
+          flags: row.flags.split(", "),
+          type: "unknown",
+          description: row.description,
+          required: false
+        })) : []
+      },
+      null,
+      2
+    )}
+`;
+  }
+  const collected = collectFields(node.params, casing, globalLongOptionFlags);
+  const fields = assignPositionals(collected.fields, node.positional);
+  const positionalFields = fields.filter((field) => field.positionalIndex !== void 0);
+  const usageSuffix = positionalFields.length > 0 ? `[OPTIONS] ${positionalFields.map(formatPositionalToken).join(" ")}` : "[OPTIONS]";
+  return `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      kind: "command",
+      name: node.name,
+      path: target.breadcrumb.filter((segment) => segment.length > 0),
+      usage: buildUsageLine(target.breadcrumb, rootUsageName, usageSuffix),
+      ...node.description === void 0 ? {} : { description: node.description },
+      options: fields.filter((field) => field.global !== true).map((field) => formatJsonHelpOption(field, globalLongOptionFlags)),
+      secrets: Object.entries(node.secrets).map(([name, secret]) => ({
+        name,
+        env: secret.env,
+        required: secret.optional !== true,
+        ...secret.description === void 0 ? {} : { description: secret.description }
+      })),
+      examples: node.examples
+    },
+    null,
+    2
+  )}
+`;
+}
+function formatJsonHelpOption(field, globalLongOptionFlags) {
+  return {
+    name: field.displayPath,
+    flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
+    type: formatJsonHelpSchemaType(field.schema),
+    ...field.description === void 0 ? {} : { description: field.description },
+    required: field.requiredWhenActive,
+    ...field.hasDefault ? { default: field.defaultValue } : {},
+    ...field.positionalIndex === void 0 ? {} : { positional: true }
+  };
+}
+function formatJsonHelpSchemaType(schema) {
+  if (schema.kind === "enum") {
+    return "enum";
+  }
+  if (schema.kind === "array") {
+    return "array";
+  }
+  if (schema.kind === "json") {
+    return "json";
+  }
+  return schema.kind;
+}
 function renderHelpDocument(input) {
   const title = input.breadcrumb.filter((segment) => segment.length > 0).join(" ") || input.rootUsageName;
   const description = input.description ?? "";
@@ -15094,11 +15402,27 @@ function renderHelpDocument(input) {
 `;
 }
 async function renderGeneratedHelp(root, argv, options) {
-  const target = resolveHelpTarget(root, argv, "cli", options.rootDisplayName);
   const output = resolveHelpOutput(argv);
   const casing = options.casing ?? "kebab";
   const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
+  const target = resolveHelpTarget(root, argv, "cli", rootUsageName, options.rootDisplayName);
   const controls = resolveCLIControls(options.controls);
+  if (output === "json") {
+    process.stdout.write(
+      renderJsonHelp(
+        target,
+        root,
+        casing,
+        {
+          controls,
+          showVersion: options.version !== void 0,
+          presetsEnabled: options.presets === true
+        },
+        rootUsageName
+      )
+    );
+    return;
+  }
   await withOutputFormat2(output, async () => {
     const rendered = target.node.kind === "group" ? renderGroupHelp(
       target.node,
@@ -15218,9 +15542,11 @@ function addCommanderChild(parent, child, isDefault, siblingNames) {
       parent,
       "_toolcraftHiddenDefaultNames",
       getToolcraftHiddenDefaultNames(parent).concat([
-        ...new Set([Reflect.get(child, "_toolcraftOriginalName"), ...child.aliases()].filter(
-          (name) => typeof name === "string" && name.length > 0
-        ))
+        ...new Set(
+          [Reflect.get(child, "_toolcraftOriginalName"), ...child.aliases()].filter(
+            (name) => typeof name === "string" && name.length > 0
+          )
+        )
       ])
     );
     parent.addCommand(child, { hidden: true, isDefault: true });
@@ -15277,6 +15603,13 @@ function addGlobalOptions(command, presetsEnabled, controls) {
       new Option("--debug [mode]", "Print stack traces for unexpected errors.").preset("trim").argParser(parseDebugStackMode)
     );
   }
+  if (controls.logLevel) {
+    options.push(
+      new Option("--log-level <level>", "Set runtime diagnostic log level.").argParser(
+        parseLogLevel
+      )
+    );
+  }
   if (controls.verbose) {
     options.push(new Option("--verbose", "Print detailed runtime diagnostics."));
   }
@@ -15296,6 +15629,29 @@ function parseDebugStackMode(value) {
     formatInvalidEnumMessage("--debug", String(value), ["raw"], { candidates: ["raw"] })
   );
 }
+function parseLogLevel(value) {
+  if (isLogLevel(value)) {
+    return value;
+  }
+  throw new InvalidArgumentError(
+    formatInvalidEnumMessage("--log-level", value, [...LOG_LEVELS], {
+      candidates: ["warn", "debug", "trace"],
+      threshold: 3
+    })
+  );
+}
+function writeCLIDiagnosticEvent(event) {
+  const transcript = event.data?.transcript;
+  if (typeof transcript === "string") {
+    process.stderr.write(transcript);
+    return;
+  }
+  if (event.category === "progress" || event.level === "trace") {
+    return;
+  }
+  process.stderr.write(`${event.message}
+`);
+}
 function setNestedValue(target, path25, value) {
   let cursor2 = target;
   for (let index = 0; index < path25.length - 1; index += 1) {
@@ -15486,7 +15842,7 @@ function createEnv2(values = process.env) {
     }
   };
 }
-function isPlainObject4(value) {
+function isPlainObject5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function hasFieldValue(value) {
@@ -15618,7 +15974,7 @@ async function loadPresetValues(fields, presetPath) {
       { cause: error3 }
     );
   }
-  if (!isPlainObject4(parsedPreset)) {
+  if (!isPlainObject5(parsedPreset)) {
     throw new UserError(`Preset file "${presetPath}" must contain a JSON object.`);
   }
   const fieldByPath = new Map(fields.map((field) => [field.displayPath, field]));
@@ -15637,7 +15993,7 @@ async function loadPresetValues(fields, presetPath) {
           `Preset file "${presetPath}" contains unknown parameter "${displayPath}".`
         );
       }
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         throw new UserError(
           `Preset file "${presetPath}" has an invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
         );
@@ -15680,8 +16036,8 @@ function matchesFixtureValue(expected, actual) {
     }
     return expected.every((item, index) => matchesFixtureValue(item, actual[index]));
   }
-  if (isPlainObject4(expected)) {
-    if (!isPlainObject4(actual)) {
+  if (isPlainObject5(expected)) {
+    if (!isPlainObject5(actual)) {
       return false;
     }
     return Object.entries(expected).every(
@@ -15744,9 +16100,9 @@ function createFixtureFetch(entries) {
   };
 }
 function createFixtureFs(definition) {
-  const fsDefinition = isPlainObject4(definition) ? definition : {};
-  const readFileEntries = isPlainObject4(fsDefinition.readFile) ? fsDefinition.readFile : {};
-  const existsEntries = isPlainObject4(fsDefinition.exists) ? fsDefinition.exists : {};
+  const fsDefinition = isPlainObject5(definition) ? definition : {};
+  const readFileEntries = isPlainObject5(fsDefinition.readFile) ? fsDefinition.readFile : {};
+  const existsEntries = isPlainObject5(fsDefinition.exists) ? fsDefinition.exists : {};
   return {
     readFile: async (filePath) => {
       if (Object.prototype.hasOwnProperty.call(readFileEntries, filePath)) {
@@ -15769,10 +16125,10 @@ function createFixtureFs(definition) {
 function resolveFixtureMethodResult(methodName, definition, args) {
   if (Array.isArray(definition)) {
     for (const entry of definition) {
-      if (!isPlainObject4(entry)) {
+      if (!isPlainObject5(entry)) {
         continue;
       }
-      const explicitMatcher = isPlainObject4(entry.request) ? entry.request : void 0;
+      const explicitMatcher = isPlainObject5(entry.request) ? entry.request : void 0;
       const matcher = explicitMatcher ?? Object.fromEntries(
         Object.entries(entry).filter(
           ([key2]) => key2 !== "result" && key2 !== "response" && key2 !== "error"
@@ -15784,7 +16140,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
         matched = matchesFixtureValue(matcher.args, args);
       } else if (Object.keys(matcher).length === 0) {
         matched = true;
-      } else if (isPlainObject4(firstArg)) {
+      } else if (isPlainObject5(firstArg)) {
         matched = matchesFixtureValue(matcher, firstArg);
       } else if (args.length === 1 && Object.keys(matcher).length === 1) {
         const [[, expectedValue]] = Object.entries(matcher);
@@ -15805,7 +16161,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
       return Promise.resolve(null);
     }
   }
-  if (isPlainObject4(definition)) {
+  if (isPlainObject5(definition)) {
     const firstArg = args[0];
     if (typeof firstArg === "string" && Object.prototype.hasOwnProperty.call(definition, firstArg)) {
       return Promise.resolve(definition[firstArg]);
@@ -15817,7 +16173,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
   return Promise.resolve(null);
 }
 function createFixtureService(definition) {
-  const methods = isPlainObject4(definition) ? definition : {};
+  const methods = isPlainObject5(definition) ? definition : {};
   return new Proxy(
     {},
     {
@@ -15915,7 +16271,7 @@ async function resolveFixtureRuntime(command, services, requirementOptions, runt
     };
   }
   const scenario = await loadFixtureScenario(command, selector);
-  const scenarioServices = isPlainObject4(scenario.services) ? scenario.services : {};
+  const scenarioServices = isPlainObject5(scenario.services) ? scenario.services : {};
   const customServiceNames = /* @__PURE__ */ new Set([
     ...Object.keys(services),
     ...Object.keys(scenarioServices).filter((name) => !RESERVED_SERVICE_NAMES.has(name))
@@ -15975,6 +16331,19 @@ function renderCliErrorPattern(pattern) {
     process.exitCode = 1;
     return;
   }
+  if (pattern.kind === "definition") {
+    logger2.error(
+      `Command definition error: ${pattern.error.message}
+This is a bug in the generated command definition, not in your command arguments.
+Run with --debug for a stack trace.`
+    );
+    if (pattern.debugStackMode !== void 0 && pattern.error.stack) {
+      process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}
+`);
+    }
+    process.exitCode = 1;
+    return;
+  }
   if (pattern.kind === "toolcraft-bug") {
     logger2.error(
       `toolcraft hit an internal invariant: ${pattern.error.message}
@@ -16241,7 +16610,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       if (itemSchema.kind !== "object") {
         return value;
       }
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected indexed object entries, got ${describeReceived(value)}.`
@@ -16276,7 +16645,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       );
     }
     case "object": {
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
@@ -16307,7 +16676,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       return result;
     }
     case "record": {
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
@@ -16637,7 +17006,7 @@ function getResolvedFlags(command) {
   const flags = command.optsWithGlobals();
   return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, onErrorReportContext) {
+async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, diagnosticsOptions, onErrorReportContext) {
   const logger2 = createLogger();
   const primitives = {
     logger: logger2,
@@ -16648,6 +17017,10 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
   const optionValues = state.actionCommand.optsWithGlobals();
   const resolvedFlags = optionValues;
   const output = resolveOutput(resolvedFlags);
+  const diagnostics = createRuntimeLogger({
+    level: resolvedFlags.logLevel ?? (diagnosticsOptions.verboseControlEnabled && resolvedFlags.verbose ? "trace" : diagnosticsOptions.logLevel),
+    logger: diagnosticsOptions.logger ?? writeCLIDiagnosticEvent
+  });
   const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
   const runtime = await resolveFixtureRuntime(
     state.command,
@@ -16661,7 +17034,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
     fetch: runtime.fetch,
     fs: runtime.fs,
     env: runtime.env,
+    diagnostics,
     progress(message2) {
+      diagnostics.emit({ level: "info", message: message2, category: "progress" });
       logger2.info(message2);
     }
   };
@@ -16738,18 +17113,18 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
   }
 }
 function isStringRecord(value) {
-  return isPlainObject4(value) && Object.values(value).every((entry) => typeof entry === "string");
+  return isPlainObject5(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
 function isHttpErrorLike(error3) {
-  if (!isPlainObject4(error3)) {
+  if (!isPlainObject5(error3)) {
     return false;
   }
-  if (error3.name !== "HttpError" || typeof error3.message !== "string") {
+  if (typeof error3.name !== "string" || typeof error3.message !== "string") {
     return false;
   }
   const request = error3.request;
   const response = error3.response;
-  return isPlainObject4(request) && typeof request.method === "string" && typeof request.url === "string" && isStringRecord(request.headers) && isPlainObject4(response) && typeof response.status === "number" && typeof response.statusText === "string" && isStringRecord(response.headers) && hasOwnProperty3(response, "body");
+  return isPlainObject5(request) && typeof request.method === "string" && typeof request.url === "string" && isStringRecord(request.headers) && isPlainObject5(response) && typeof response.status === "number" && typeof response.statusText === "string" && isStringRecord(response.headers) && hasOwnProperty3(response, "body");
 }
 function hasTypedOptionalField(value, field, type2) {
   return !hasOwnProperty3(value, field) || typeof value[field] === type2;
@@ -16758,7 +17133,7 @@ function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
 function isProblemDetailsLike(body) {
-  if (!isPlainObject4(body)) {
+  if (!isPlainObject5(body)) {
     return false;
   }
   if (!hasTypedOptionalField(body, "type", "string")) {
@@ -16779,11 +17154,11 @@ function isProblemDetailsLike(body) {
   return hasOwnNonEmptyString(body, "title") || hasOwnNonEmptyString(body, "detail");
 }
 function isGraphQLErrorEnvelopeLike(body) {
-  if (!isPlainObject4(body) || !Array.isArray(body.errors) || body.errors.length === 0) {
+  if (!isPlainObject5(body) || !Array.isArray(body.errors) || body.errors.length === 0) {
     return false;
   }
   return body.errors.every((error3) => {
-    if (!isPlainObject4(error3) || typeof error3.message !== "string") {
+    if (!isPlainObject5(error3) || typeof error3.message !== "string") {
       return false;
     }
     if (hasOwnProperty3(error3, "path")) {
@@ -16793,7 +17168,7 @@ function isGraphQLErrorEnvelopeLike(body) {
       }
     }
     if (hasOwnProperty3(error3, "extensions")) {
-      if (!isPlainObject4(error3.extensions)) {
+      if (!isPlainObject5(error3.extensions)) {
         return false;
       }
       if (hasOwnProperty3(error3.extensions, "code") && typeof error3.extensions.code !== "string") {
@@ -16876,6 +17251,7 @@ function formatHttpErrorSnippet(body) {
 }
 function renderHttpError(error3, options) {
   const detailed = options.verbose || options.debugStackMode !== void 0;
+  const summary = summarizeHttpError(error3);
   const lines = [
     styleHttpErrorLine(`Request:  ${error3.request.method} ${error3.request.url}`, text.muted)
   ];
@@ -16902,11 +17278,27 @@ function renderHttpError(error3, options) {
       indentHttpErrorBlock(formatHttpErrorBody(error3.response.body))
     );
   } else {
-    lines.push(
-      "",
-      `Response body: ${formatHttpErrorSnippet(error3.response.body)}`,
-      "Re-run with --verbose to see headers and full body."
-    );
+    const summaryLines = [
+      summary.code === void 0 ? void 0 : `Code:     ${summary.code}`,
+      summary.message === void 0 ? void 0 : `Message:  ${summary.message}`,
+      summary.requestId === void 0 ? void 0 : `Request id: ${summary.requestId}`,
+      summary.retryAfter === void 0 ? void 0 : `Retry after: ${summary.retryAfter}`,
+      summary.hint === void 0 ? void 0 : `Hint:     ${summary.hint}`
+    ].filter((line) => line !== void 0);
+    if (summary.fieldErrors !== void 0 && summary.fieldErrors.length > 0) {
+      summaryLines.push(
+        "",
+        "Field errors:",
+        ...summary.fieldErrors.map((fieldError) => `  ${fieldError.path}: ${fieldError.message}`)
+      );
+    }
+    lines.push("");
+    if (summaryLines.length > 0) {
+      lines.push(...summaryLines);
+    } else {
+      lines.push(`Response body: ${formatHttpErrorSnippet(error3.response.body)}`);
+    }
+    lines.push("Re-run with --verbose to see headers and full body.");
   }
   process.stderr.write(`${lines.join("\n")}
 `);
@@ -16921,7 +17313,11 @@ async function handleRunError(error3, options) {
   await withOutputFormat2(options.output, async () => {
     if (error3 instanceof UserError) {
       renderCliErrorPattern(
-        options.userErrorPattern === "usage" ? {
+        options.userErrorPattern === "definition" ? {
+          kind: "definition",
+          error: error3,
+          debugStackMode: options.debugStackMode
+        } : options.userErrorPattern === "usage" ? {
           kind: "usage",
           message: error3.message,
           rootUsageName: options.rootUsageName,
@@ -17159,13 +17555,23 @@ function findUnknownCommanderCommand(program, argv) {
         commandPath: pathSegments.join(" ")
       };
     }
-    if (current.commands.length === 0 || getDefaultCommanderCommandName(current) !== void 0) {
+    if (current.commands.length === 0) {
       return void 0;
     }
     const child = current.commands.find(
       (command) => command.name() === token || command.aliases().includes(token)
     );
     if (child === void 0) {
+      if (getDefaultCommanderCommandName(current) !== void 0) {
+        if (shouldRejectDefaultCommandToken(current, token, pathSegments)) {
+          return {
+            input: token,
+            currentCommand: current,
+            commandPath: pathSegments.join(" ")
+          };
+        }
+        return void 0;
+      }
       return {
         input: token,
         currentCommand: current,
@@ -17177,6 +17583,36 @@ function findUnknownCommanderCommand(program, argv) {
   }
   return void 0;
 }
+function shouldRejectDefaultCommandToken(command, token, pathSegments) {
+  return pathSegments.length === 0 && isBareCommandLikeToken(token) && hasNonDefaultPublicChildCommand(command);
+}
+function hasNonDefaultPublicChildCommand(command) {
+  const defaultName = getDefaultCommanderCommandName(command);
+  return command.commands.some(
+    (child) => child.name() !== defaultName && !isToolcraftHiddenCommander(child) && !getToolcraftReservedChildNames(command).includes(child.name())
+  );
+}
+function isBareCommandLikeToken(token) {
+  if (token.length === 0) {
+    return false;
+  }
+  for (const character of token) {
+    if (!isCommandNameCharacter(character)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isCommandNameCharacter(character) {
+  const code = character.codePointAt(0);
+  if (code === void 0) {
+    return false;
+  }
+  const isLowercaseLetter = code >= 97 && code <= 122;
+  const isUppercaseLetter = code >= 65 && code <= 90;
+  const isDigit = code >= 48 && code <= 57;
+  return isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_";
+}
 function getDefaultCommanderCommandName(command) {
   const candidate = command;
   return typeof candidate._defaultCommandName === "string" ? candidate._defaultCommandName : void 0;
@@ -17195,101 +17631,116 @@ function configureCommanderSuggestionOutput(command) {
 }
 async function runCLI(roots, options = {}) {
   enableSourceMaps();
-  const argv = [...options.argv ?? process.argv];
-  const normalizedRoot = normalizeRoots(roots, argv);
-  const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
-  await resolveMcpProxies(root, { projectRoot: options.projectRoot });
-  const casing = options.casing ?? "kebab";
-  const services = options.services ?? {};
-  const runtimeOptions = options.humanInLoop ?? {};
-  const runtimeFetch = options.fetch ?? globalThis.fetch;
-  const version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
-  const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
   const controls = resolveCLIControls(options.controls);
-  const servicesWithBuiltIns = {
-    ...services,
-    runtimeOptions,
-    root
-  };
-  const requirementOptions = {
-    apiVersion: options.apiVersion
-  };
-  validateServices(services);
-  if (hasHelpFlag(argv)) {
-    await renderGeneratedHelp(root, argv, { ...options, version });
-    return;
-  }
-  const program = new CommanderCommand();
-  program.name(root.name);
-  program.exitOverride();
-  program.showHelpAfterError();
-  program.addHelpCommand(false);
-  const presetsEnabled = options.presets === true;
-  const globalLongOptionFlags = getGlobalLongOptionFlags(
-    presetsEnabled,
-    version !== void 0,
-    controls
-  );
-  addGlobalOptions(program, presetsEnabled, controls);
-  if (version !== void 0) {
-    program.version(version, "--version");
-  }
-  Reflect.set(
-    program,
-    "_toolcraftReservedChildNames",
-    root.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child))
-  );
+  const argv = controls.verbose ? normalizeVerboseAlias([...options.argv ?? process.argv]) : [...options.argv ?? process.argv];
+  const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
   let lastActionCommand;
   let resolvedCommandPath = "";
+  let program;
+  let version;
+  let userErrorPattern = "definition";
   let errorReportContext;
-  const execute = async (state) => {
-    lastActionCommand = state.actionCommand;
-    resolvedCommandPath = formatCliCommandPath(state.commandPath);
-    await executeCommand(
-      state,
-      servicesWithBuiltIns,
-      requirementOptions,
-      runtimeFetch,
+  try {
+    const normalizedRoot = normalizeRoots(roots, argv);
+    const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
+    const casing = options.casing ?? "kebab";
+    const services = options.services ?? {};
+    const runtimeOptions = options.humanInLoop ?? {};
+    const runtimeFetch = options.fetch ?? globalThis.fetch;
+    version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
+    const servicesWithBuiltIns = {
+      ...services,
       runtimeOptions,
-      (context) => {
-        errorReportContext = context;
-      }
-    );
-  };
-  const rootChildNames = new Set(
-    root.children.filter((candidate) => isNodeVisibleInScope(candidate, "cli")).map((candidate) => candidate.name)
-  );
-  for (const child of root.children) {
-    const command = createNodeCommand(
-      child,
-      casing,
-      globalLongOptionFlags,
-      execute,
+      root
+    };
+    const requirementOptions = {
+      apiVersion: options.apiVersion
+    };
+    validateServices(services);
+    if (hasHelpFlag(argv)) {
+      userErrorPattern = "usage";
+      await renderGeneratedHelp(root, argv, { ...options, version });
+      return;
+    }
+    if (argv.length <= 2 && root.default?.scope.includes("cli") !== true) {
+      userErrorPattern = "usage";
+      await renderGeneratedHelp(root, argv, { ...options, version });
+      return;
+    }
+    program = new CommanderCommand();
+    program.name(root.name);
+    program.exitOverride();
+    program.showHelpAfterError();
+    program.addHelpCommand(false);
+    const presetsEnabled = options.presets === true;
+    const globalLongOptionFlags = getGlobalLongOptionFlags(
       presetsEnabled,
+      version !== void 0,
       controls
     );
-    if (command === null) {
-      continue;
+    addGlobalOptions(program, presetsEnabled, controls);
+    if (version !== void 0) {
+      program.version(version, "--version");
     }
-    const isDefaultChild = root.default !== void 0 && root.default.scope.includes("cli") && (command.name() === root.default.name || command.aliases().includes(root.default.name));
-    addCommanderChild(program, command, isDefaultChild, rootChildNames);
-  }
-  configureCommanderSuggestionOutput(program);
-  const unknownCommand = findUnknownCommanderCommand(program, argv);
-  if (unknownCommand !== void 0) {
-    createLogger().error(
-      appendUsagePointer(
-        formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand),
+    Reflect.set(
+      program,
+      "_toolcraftReservedChildNames",
+      root.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child))
+    );
+    const execute = async (state) => {
+      lastActionCommand = state.actionCommand;
+      resolvedCommandPath = formatCliCommandPath(state.commandPath);
+      await executeCommand(
+        state,
+        servicesWithBuiltIns,
+        requirementOptions,
+        runtimeFetch,
+        runtimeOptions,
         {
-          rootUsageName,
-          commandPath: unknownCommand.commandPath
+          logLevel: options.logLevel,
+          logger: options.logger,
+          verboseControlEnabled: controls.verbose
+        },
+        (context) => {
+          errorReportContext = context;
         }
-      )
+      );
+    };
+    const rootChildNames = new Set(
+      root.children.filter((candidate) => isNodeVisibleInScope(candidate, "cli")).map((candidate) => candidate.name)
     );
-    process.exitCode = 1;
-    return;
-  }
-  try {
+    for (const child of root.children) {
+      const command = createNodeCommand(
+        child,
+        casing,
+        globalLongOptionFlags,
+        execute,
+        presetsEnabled,
+        controls
+      );
+      if (command === null) {
+        continue;
+      }
+      const isDefaultChild = root.default !== void 0 && root.default.scope.includes("cli") && (command.name() === root.default.name || command.aliases().includes(root.default.name));
+      addCommanderChild(program, command, isDefaultChild, rootChildNames);
+    }
+    configureCommanderSuggestionOutput(program);
+    const unknownCommand = findUnknownCommanderCommand(program, argv);
+    if (unknownCommand !== void 0) {
+      createLogger().error(
+        appendUsagePointer(
+          formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand),
+          {
+            rootUsageName,
+            commandPath: unknownCommand.commandPath
+          }
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
+    userErrorPattern = "usage";
     await program.parseAsync(argv);
   } catch (error3) {
     if (error3 instanceof ApprovalDeclinedError) {
@@ -17321,7 +17772,7 @@ async function runCLI(roots, options = {}) {
       argv,
       rootUsageName,
       commandPath: resolvedCommandPath,
-      userErrorPattern: errorReportContext?.params === void 0 ? "usage" : "runtime-user"
+      userErrorPattern: errorReportContext?.params === void 0 ? userErrorPattern : "runtime-user"
     });
   }
 }