terminal-pilot 0.0.31 → 0.0.33

package/dist/cli.js

@@ -3670,6 +3670,7 @@ function createBaseCommand(config2) {
     kind: "command",
     name: config2.name,
     description: config2.description,
+    hidden: config2.hidden ?? false,
     examples: cloneCommandExamples(config2.examples),
     aliases: [...config2.aliases ?? []],
     positional: [...config2.positional ?? []],
@@ -3686,6 +3687,7 @@ function createBaseCommand(config2) {
   Object.defineProperty(command, commandConfigSymbol, {
     value: {
       scope: cloneScope(config2.scope),
+      hidden: config2.hidden ?? false,
       examples: cloneCommandExamples(config2.examples),
       result: config2.result,
       humanInLoop: config2.humanInLoop,
@@ -3736,6 +3738,7 @@ function materializeCommand(command, inherited) {
     kind: "command",
     name: command.name,
     description: command.description,
+    hidden: internal.hidden,
     examples: cloneCommandExamples(internal.examples),
     aliases: [...command.aliases],
     positional: [...command.positional],
@@ -3752,6 +3755,7 @@ function materializeCommand(command, inherited) {
   Object.defineProperty(materialized, commandConfigSymbol, {
     value: {
       scope: cloneScope(internal.scope),
+      hidden: internal.hidden,
       examples: cloneCommandExamples(internal.examples),
       result: internal.result,
       humanInLoop: internal.humanInLoop,
@@ -12470,6 +12474,7 @@ function createProxyCommand(parent, tool, commandName, connection) {
     kind: "command",
     name: commandName,
     description: tool.description,
+    hidden: false,
     examples: [],
     aliases: [],
     positional: [],
@@ -14549,6 +14554,14 @@ function isNodeVisibleInScope(node, scope) {
 function getVisibleChildren(group, scope) {
   return group.children.filter((child) => isNodeVisibleInScope(child, scope));
 }
+function getHelpChildren(group, scope) {
+  return getVisibleChildren(group, scope).filter((child) => {
+    if (child.kind === "command") {
+      return child.hidden !== true;
+    }
+    return true;
+  });
+}
 function findVisibleChild(group, token, scope) {
   return getVisibleChildren(group, scope).find(
     (child) => child.name === token || child.aliases.includes(token)
@@ -14695,6 +14708,26 @@ function describeHelpValueToken(schema, field) {
   }
   return describeFieldNameValueToken(field.displayPath, field.optionFlag) ?? "value";
 }
+function formatCompactEnumSignatureToken(schema) {
+  if (schema.kind !== "enum" || schema.values.length < 2 || schema.values.length > 3) {
+    return void 0;
+  }
+  const tokens = schema.values.map((value) => String(value));
+  const compact = tokens.every(
+    (token) => token.length > 0 && token.length <= 24 && token.trim() === token && !token.includes("|") && !token.includes("	") && !token.includes("\n") && !token.includes("\r") && !token.includes(" ")
+  );
+  return compact ? tokens.join("|") : void 0;
+}
+function formatCommandParameterFieldFlags(field, globalLongOptionFlags) {
+  if (field.positionalIndex !== void 0 || field.schema.kind === "boolean") {
+    return formatHelpFieldFlags(field, globalLongOptionFlags);
+  }
+  const enumToken = formatCompactEnumSignatureToken(field.schema);
+  if (enumToken !== void 0) {
+    return `${formatOptionFlags(field, globalLongOptionFlags)} ${enumToken}`;
+  }
+  return formatHelpFieldFlags(field, globalLongOptionFlags);
+}
 function describeDynamicFieldType(field) {
   if (field.schema.kind === "record") {
     const valueSchema = unwrapOptional2(field.schema.value);
@@ -14862,7 +14895,7 @@ function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
   const fields = assignPositionals(collected.fields, command.positional);
   return fields.filter((field) => field.global !== true).map(
     (field) => wrapOptionalCommandParameterToken(
-      formatHelpFieldFlags(field, globalLongOptionFlags),
+      formatCommandParameterFieldFlags(field, globalLongOptionFlags),
       field.positionalIndex === void 0 && (field.optional || field.hasDefault)
     )
   ).concat(
@@ -14876,7 +14909,7 @@ function formatCommandRowName(node, casing, globalLongOptionFlags) {
   return name;
 }
 function formatCommandRows(group, scope, casing, globalLongOptionFlags) {
-  return getVisibleChildren(group, scope).map((child) => ({
+  return getHelpChildren(group, scope).map((child) => ({
     name: formatCommandRowName(child, casing, globalLongOptionFlags),
     description: child.description ?? ""
   }));
@@ -14920,7 +14953,7 @@ function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlag
       }
       return;
     }
-    for (const child of getVisibleChildren(node, scope)) {
+    for (const child of getHelpChildren(node, scope)) {
       visit(child);
     }
   };
@@ -14943,6 +14976,17 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
   const tokens = [rootUsageName, subPath, suffix].filter((segment) => segment.length > 0);
   return tokens.join(" ");
 }
+function formatGroupUsageSuffix(group, scope, casing, globalLongOptionFlags) {
+  if (group.default !== void 0 && group.default.hidden === true && group.default.scope.includes(scope)) {
+    const parameterTokens = formatCommandParameterTokens(
+      group.default,
+      casing,
+      globalLongOptionFlags
+    );
+    return ["[command]", "[OPTIONS]", ...parameterTokens].join(" ");
+  }
+  return "[command] [OPTIONS]";
+}
 function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
   const sections = [];
   const globalLongOptionFlags = getGlobalLongOptionFlags(
@@ -14976,7 +15020,11 @@ ${builtInLine}`
   return renderHelpDocument({
     breadcrumb,
     rootUsageName,
-    usageLine: buildUsageLine(breadcrumb, rootUsageName, "[command] [OPTIONS]"),
+    usageLine: buildUsageLine(
+      breadcrumb,
+      rootUsageName,
+      formatGroupUsageSuffix(group, scope, casing, globalLongOptionFlags)
+    ),
     description: group.description,
     requiresAuth: group.requires?.auth === true,
     sections
@@ -15085,6 +15133,8 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
       return null;
     }
     const command = new CommanderCommand(node.name);
+    Reflect.set(command, "_toolcraftHidden", node.hidden);
+    Reflect.set(command, "_toolcraftOriginalName", node.name);
     const collected = collectFields(node.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, node.positional);
     validateUniqueOptionFlags(fields, globalLongOptionFlags);
@@ -15128,6 +15178,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
   if (!isNodeVisibleInScope(node, "cli")) {
     return null;
   }
+  const reservedChildNames = node.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child));
   const visibleChildren = node.children.map(
     (child) => createNodeCommand(
       child,
@@ -15140,6 +15191,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
     )
   ).filter((child) => child !== null);
   const group = new CommanderCommand(node.name);
+  Reflect.set(group, "_toolcraftReservedChildNames", reservedChildNames);
   if (node.description !== void 0) {
     group.description(node.description);
   }
@@ -15154,7 +15206,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
   return group;
 }
 function addCommanderChild(parent, child, isDefault, siblingNames) {
-  if (isDefault && child.name().length === 0) {
+  if (isDefault && (child.name().length === 0 || isToolcraftHiddenCommander(child))) {
     let internalName = "__toolcraft_default__";
     let suffix = 2;
     while (siblingNames.has(internalName)) {
@@ -15162,10 +15214,37 @@ function addCommanderChild(parent, child, isDefault, siblingNames) {
       suffix += 1;
     }
     child.name(internalName);
+    Reflect.set(
+      parent,
+      "_toolcraftHiddenDefaultNames",
+      getToolcraftHiddenDefaultNames(parent).concat([
+        ...new Set([Reflect.get(child, "_toolcraftOriginalName"), ...child.aliases()].filter(
+          (name) => typeof name === "string" && name.length > 0
+        ))
+      ])
+    );
     parent.addCommand(child, { hidden: true, isDefault: true });
     return;
   }
-  parent.addCommand(child, isDefault ? { isDefault: true } : void 0);
+  const options = {
+    ...isDefault ? { isDefault: true } : {},
+    ...isToolcraftHiddenCommander(child) ? { hidden: true } : {}
+  };
+  parent.addCommand(child, Object.keys(options).length > 0 ? options : void 0);
+}
+function isToolcraftHiddenCommander(command) {
+  return Reflect.get(command, "_toolcraftHidden") === true;
+}
+function getToolcraftHiddenDefaultNames(command) {
+  const value = Reflect.get(command, "_toolcraftHiddenDefaultNames");
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function getToolcraftReservedChildNames(command) {
+  const value = Reflect.get(command, "_toolcraftReservedChildNames");
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function getNodeCommandNames(node) {
+  return [node.name, ...node.aliases].filter((name) => name.length > 0);
 }
 function addGlobalOptions(command, presetsEnabled, controls) {
   const options = [];
@@ -15327,6 +15406,37 @@ function resolveOutput(resolvedFlags) {
   }
   return "rich";
 }
+function resolveOutputFromArgv(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] ?? "";
+    if (token === "--json") {
+      return "json";
+    }
+    if (token === "--md" || token === "--markdown") {
+      return "md";
+    }
+    if (token === "--output") {
+      const value = argv[index + 1];
+      if (value === "rich" || value === "md" || value === "json") {
+        return value;
+      }
+      if (value === "markdown") {
+        return "md";
+      }
+      continue;
+    }
+    if (token.startsWith("--output=")) {
+      const value = token.slice("--output=".length);
+      if (value === "rich" || value === "md" || value === "json") {
+        return value;
+      }
+      if (value === "markdown") {
+        return "md";
+      }
+    }
+  }
+  return "rich";
+}
 var DESIGN_SYSTEM_OUTPUT_BY_MODE = {
   rich: "terminal",
   md: "markdown",
@@ -15848,6 +15958,44 @@ function renderApprovalDeclined(error3) {
   logger2.error(error3.message);
   process.exitCode = 1;
 }
+function renderCliErrorPattern(pattern) {
+  const logger2 = createLogger();
+  if (pattern.kind === "usage") {
+    logger2.error(
+      appendUsagePointer(pattern.message, {
+        rootUsageName: pattern.rootUsageName,
+        commandPath: pattern.commandPath
+      })
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (pattern.kind === "runtime-user") {
+    logger2.error(pattern.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (pattern.kind === "toolcraft-bug") {
+    logger2.error(
+      `toolcraft hit an internal invariant: ${pattern.error.message}
+This is a bug in toolcraft or in the command definition; it cannot be worked around by changing argv. Re-run with --debug for a stack trace and file an issue.`
+    );
+    if (pattern.debugStackMode !== void 0 && pattern.error.stack) {
+      process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}
+`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  logger2.error(
+    pattern.debugStackMode !== void 0 ? pattern.message : `${pattern.message} Use --debug for a stack trace.`
+  );
+  if (pattern.debugStackMode !== void 0 && pattern.stack !== void 0) {
+    process.stderr.write(`${formatDebugStack(pattern.stack, pattern.debugStackMode)}
+`);
+  }
+  process.exitCode = 1;
+}
 function validateServices(services) {
   for (const name of Object.keys(services)) {
     if (RESERVED_SERVICE_NAMES.has(name)) {
@@ -16768,79 +16916,79 @@ function renderHttpError(error3, options) {
 `);
   }
 }
-function handleRunError(error3, options) {
+async function handleRunError(error3, options) {
   const logger2 = createLogger();
-  if (error3 instanceof UserError) {
-    logger2.error(
-      appendUsagePointer(error3.message, {
-        rootUsageName: options.rootUsageName,
-        commandPath: options.commandPath
-      })
-    );
-    process.exitCode = 1;
-    return;
-  }
-  if (error3 instanceof Error && error3.name === "ToolcraftBugError") {
-    logger2.error(
-      `toolcraft hit an internal invariant: ${error3.message}
-This is a bug in toolcraft or in the command definition; it cannot be worked around by changing argv. Re-run with --debug for a stack trace and file an issue.`
-    );
-    if (options.debugStackMode !== void 0 && error3.stack) {
-      process.stderr.write(`${formatDebugStack(error3.stack, options.debugStackMode)}
-`);
-    }
-    process.exitCode = 1;
-    return;
-  }
-  if (error3 instanceof CommanderError2) {
-    process.exitCode = error3.exitCode;
-    if (error3.code === "commander.helpDisplayed" || error3.code === "commander.version") {
+  await withOutputFormat2(options.output, async () => {
+    if (error3 instanceof UserError) {
+      renderCliErrorPattern(
+        options.userErrorPattern === "usage" ? {
+          kind: "usage",
+          message: error3.message,
+          rootUsageName: options.rootUsageName,
+          commandPath: options.commandPath
+        } : {
+          kind: "runtime-user",
+          message: error3.message
+        }
+      );
       return;
     }
-    if (error3.code === "commander.unknownCommand") {
-      logger2.error(
-        appendUsagePointer(
-          formatUnknownCommandError(error3, options.program, options.argv ?? process.argv),
-          {
-            rootUsageName: options.rootUsageName,
-            commandPath: options.commandPath
-          }
-        )
-      );
+    if (error3 instanceof Error && error3.name === "ToolcraftBugError") {
+      renderCliErrorPattern({
+        kind: "toolcraft-bug",
+        error: error3,
+        debugStackMode: options.debugStackMode
+      });
       return;
     }
-    if (error3.code === "commander.unknownOption") {
-      const argv = options.argv ?? process.argv;
+    if (error3 instanceof CommanderError2) {
+      process.exitCode = error3.exitCode;
+      if (error3.code === "commander.helpDisplayed" || error3.code === "commander.version") {
+        return;
+      }
+      if (error3.code === "commander.unknownCommand") {
+        logger2.error(
+          appendUsagePointer(
+            formatUnknownCommandError(error3, options.program, options.argv ?? process.argv),
+            {
+              rootUsageName: options.rootUsageName,
+              commandPath: options.commandPath
+            }
+          )
+        );
+        return;
+      }
+      if (error3.code === "commander.unknownOption") {
+        const argv = options.argv ?? process.argv;
+        logger2.error(
+          appendUsagePointer(formatUnknownOptionError(error3, options.program, argv), {
+            rootUsageName: options.rootUsageName,
+            commandPath: options.commandPath.length > 0 ? options.commandPath : findCurrentCommanderCommandPath(options.program, argv)
+          })
+        );
+        return;
+      }
       logger2.error(
-        appendUsagePointer(formatUnknownOptionError(error3, options.program, argv), {
+        appendUsagePointer(formatCommanderErrorMessage(error3), {
           rootUsageName: options.rootUsageName,
-          commandPath: options.commandPath.length > 0 ? options.commandPath : findCurrentCommanderCommandPath(options.program, argv)
+          commandPath: options.commandPath.length > 0 ? options.commandPath : findCurrentCommanderCommandPath(options.program, options.argv ?? process.argv)
         })
       );
       return;
     }
-    logger2.error(
-      appendUsagePointer(formatCommanderErrorMessage(error3), {
-        rootUsageName: options.rootUsageName,
-        commandPath: options.commandPath.length > 0 ? options.commandPath : findCurrentCommanderCommandPath(options.program, options.argv ?? process.argv)
-      })
-    );
-    return;
-  }
-  if (isHttpErrorLike(error3)) {
-    renderHttpError(error3, options);
-    process.exitCode = 1;
-    return;
-  }
-  const message2 = error3 instanceof Error ? error3.message : String(error3);
-  logger2.error(
-    options.debugStackMode !== void 0 ? message2 : `${message2} Use --debug for a stack trace.`
-  );
-  if (options.debugStackMode !== void 0 && error3 instanceof Error && error3.stack) {
-    process.stderr.write(`${formatDebugStack(error3.stack, options.debugStackMode)}
-`);
-  }
-  process.exitCode = 1;
+    if (isHttpErrorLike(error3)) {
+      renderHttpError(error3, options);
+      process.exitCode = 1;
+      return;
+    }
+    const message2 = error3 instanceof Error ? error3.message : String(error3);
+    renderCliErrorPattern({
+      kind: "unexpected",
+      message: message2,
+      stack: error3 instanceof Error ? error3.stack : void 0,
+      debugStackMode: options.debugStackMode
+    });
+  });
 }
 function formatCommanderErrorMessage(error3) {
   return error3.message.startsWith("error:") ? error3.message : `error: ${error3.message}`;
@@ -17004,6 +17152,13 @@ function findUnknownCommanderCommand(program, argv) {
       }
       continue;
     }
+    if (getToolcraftHiddenDefaultNames(current).includes(token) || getToolcraftReservedChildNames(current).includes(token)) {
+      return {
+        input: token,
+        currentCommand: current,
+        commandPath: pathSegments.join(" ")
+      };
+    }
     if (current.commands.length === 0 || getDefaultCommanderCommandName(current) !== void 0) {
       return void 0;
     }
@@ -17040,15 +17195,16 @@ function configureCommanderSuggestionOutput(command) {
 }
 async function runCLI(roots, options = {}) {
   enableSourceMaps();
-  const normalizedRoot = normalizeRoots(roots, process.argv);
+  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(process.argv[1])?.version;
-  const rootUsageName = options.rootUsageName ?? inferProgramName(process.argv);
+  const version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
+  const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
   const controls = resolveCLIControls(options.controls);
   const servicesWithBuiltIns = {
     ...services,
@@ -17059,8 +17215,8 @@ async function runCLI(roots, options = {}) {
     apiVersion: options.apiVersion
   };
   validateServices(services);
-  if (hasHelpFlag(process.argv)) {
-    await renderGeneratedHelp(root, process.argv, { ...options, version });
+  if (hasHelpFlag(argv)) {
+    await renderGeneratedHelp(root, argv, { ...options, version });
     return;
   }
   const program = new CommanderCommand();
@@ -17078,6 +17234,11 @@ async function runCLI(roots, options = {}) {
   if (version !== void 0) {
     program.version(version, "--version");
   }
+  Reflect.set(
+    program,
+    "_toolcraftReservedChildNames",
+    root.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child))
+  );
   let lastActionCommand;
   let resolvedCommandPath = "";
   let errorReportContext;
@@ -17114,7 +17275,7 @@ async function runCLI(roots, options = {}) {
     addCommanderChild(program, command, isDefaultChild, rootChildNames);
   }
   configureCommanderSuggestionOutput(program);
-  const unknownCommand = findUnknownCommanderCommand(program, process.argv);
+  const unknownCommand = findUnknownCommanderCommand(program, argv);
   if (unknownCommand !== void 0) {
     createLogger().error(
       appendUsagePointer(
@@ -17129,7 +17290,7 @@ async function runCLI(roots, options = {}) {
     return;
   }
   try {
-    await program.parseAsync(process.argv);
+    await program.parseAsync(argv);
   } catch (error3) {
     if (error3 instanceof ApprovalDeclinedError) {
       renderApprovalDeclined(error3);
@@ -17137,7 +17298,7 @@ async function runCLI(roots, options = {}) {
     }
     const resolvedFlags = lastActionCommand ? getResolvedFlags(lastActionCommand) : void 0;
     const report = await writeErrorReport({
-      argv: process.argv,
+      argv,
       command: errorReportContext?.command,
       commandPath: errorReportContext?.commandPath ?? resolvedCommandPath,
       env: process.env,
@@ -17152,13 +17313,15 @@ async function runCLI(roots, options = {}) {
       process.stderr.write(`Saved error report to ${report.displayPath}
 `);
     }
-    handleRunError(error3, {
-      debugStackMode: resolvedFlags !== void 0 ? resolveDebugStackMode(resolvedFlags.debug) : getDebugStackModeFromArgv(process.argv),
-      verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : process.argv.includes("--verbose"),
+    await handleRunError(error3, {
+      debugStackMode: resolvedFlags !== void 0 ? resolveDebugStackMode(resolvedFlags.debug) : getDebugStackModeFromArgv(argv),
+      output: resolvedFlags !== void 0 ? resolveOutput(resolvedFlags) : resolveOutputFromArgv(argv),
+      verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : argv.includes("--verbose"),
       program,
-      argv: process.argv,
+      argv,
       rootUsageName,
-      commandPath: resolvedCommandPath
+      commandPath: resolvedCommandPath,
+      userErrorPattern: errorReportContext?.params === void 0 ? "usage" : "runtime-user"
     });
   }
 }
@@ -20521,7 +20684,6 @@ import path22 from "node:path";
 import os3 from "node:os";
 import path23 from "node:path";
 import * as nodeFs2 from "node:fs/promises";
-import { readFile as readFile7 } from "node:fs/promises";
 var DEFAULT_INSTALL_AGENT = "claude-code";
 var DEFAULT_INSTALL_SCOPE = "local";
 var TERMINAL_PILOT_SKILL_NAME = "terminal-pilot";
@@ -20564,19 +20726,15 @@ async function loadTerminalPilotTemplate() {
   if (terminalPilotTemplateCache !== void 0) {
     return terminalPilotTemplateCache;
   }
-  const candidates = [
-    new URL("./templates/terminal-pilot.md", import.meta.url),
-    new URL("../templates/terminal-pilot.md", import.meta.url),
-    new URL("../../../agent-skill-config/src/templates/terminal-pilot.md", import.meta.url)
-  ];
-  for (const candidate of candidates) {
-    try {
-      terminalPilotTemplateCache = await readFile7(candidate, "utf8");
-      return terminalPilotTemplateCache;
-    } catch (error3) {
-      if (!isNotFoundError2(error3)) {
-        throw error3;
-      }
+  try {
+    terminalPilotTemplateCache = await nodeFs2.readFile(
+      new URL("../templates/terminal-pilot.md", import.meta.url),
+      "utf8"
+    );
+    return terminalPilotTemplateCache;
+  } catch (error3) {
+    if (!isNotFoundError2(error3)) {
+      throw error3;
     }
   }
   throw new UserError("terminal-pilot skill template is missing.");