argsbarg 6.1.1 → 6.1.3

package/src/{parse.ts → core/parse.ts}

@@ -7,6 +7,8 @@ It keeps handler dispatch and help on one parser so the CLI behavior stays consi
 across every entry path.
 */
 
+import { isCliCallable } from "~/runtime/exposure.ts";
+import { fullStringIsDouble } from "~/utils.ts";
 import { formatValidationError, validateFormatValue } from "./formats.ts";
 import {
   CliFallbackMode,
@@ -14,10 +16,11 @@ import {
   type CliNode,
   type CliOption,
   CliOptionKind,
+  type CliRouter,
   isCliLeaf,
   isCliRouter,
+  isJsonLeaf,
 } from "./types.ts";
-import { fullStringIsDouble } from "./utils.ts";
 
 // ── Parse Result ──────────────────────────────────────────────────────────────
 
@@ -47,6 +50,8 @@ export interface ParseResult {
   helpExplicit: boolean;
   /** Path segments for scoped help (empty for root help). */
   helpPath: string[];
+  /** Path parameter values from `:param` router descent (e.g. `{ id: "qa2" }`). */
+  pathParams: Record<string, string>;
   /** User-facing error message when `kind === Error`. */
   errorMsg: string;
   /** Help path to render next to an error (for contextual help). */
@@ -68,6 +73,24 @@ function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
 }
 
+function isParamRouterKey(key: string): boolean {
+  return key.startsWith(":");
+}
+
+/** Static (non-`:param`) child by key. */
+function findStaticChild(cmds: CliNode[], name: string): CliNode | undefined {
+  const ch = cmds.find((c) => c.key === name);
+  if (!ch || isParamRouterKey(ch.key)) {
+    return undefined;
+  }
+  return ch;
+}
+
+/** The single `:param` router child at this level, if any. */
+function findParamChild(cmds: CliNode[]): CliNode | undefined {
+  return cmds.find((c) => isParamRouterKey(c.key));
+}
+
 /** Resolves a long-option definition by name (without leading `--`). */
 function findOptionByName(defs: CliOption[], name: string): CliOption | undefined {
   return defs.find((o) => o.name === name);
@@ -237,6 +260,50 @@ export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   return defs;
 }
 
+/** Fills `args` for a json leaf from `startIdx` (0 or 1 JSON string positional). */
+function finishJsonLeaf(
+  _node: CliLeaf,
+  startIdx: number,
+  argv: string[],
+  path: string[],
+  opts: Record<string, string>,
+  pathParams: Record<string, string>,
+): ParseResult {
+  let idx = startIdx;
+  const args: string[] = [];
+
+  if (idx < argv.length) {
+    const tok = argv[idx];
+    if (isHelpTok(tok)) {
+      return helpResult(path, true, pathParams);
+    }
+    if (tok === "--") {
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
+    }
+    if (tok.startsWith("-")) {
+      return errorResult(`JSON commands do not accept options: ${tok}`, path, [], pathParams);
+    }
+    args.push(tok);
+    idx += 1;
+  }
+
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments", path, [], pathParams);
+  }
+
+  return {
+    kind: ParseKind.Ok,
+    path,
+    opts,
+    args,
+    pathParams,
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg: "",
+    errorHelpPath: [],
+  };
+}
+
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliLeaf,
@@ -246,6 +313,7 @@ function finishLeaf(
   opts: Record<string, string>,
   optionDefs: CliOption[],
   forcePositionalsIn: boolean,
+  pathParams: Record<string, string>,
 ): ParseResult {
   let idx = startIdx;
   const args: string[] = [];
@@ -256,7 +324,7 @@ function finishLeaf(
     if (argMax === 1) {
       if (argMin >= 1) {
         if (idx >= argv.length) {
-          return errorResult(`Missing positional argument: ${p.name}`, path, []);
+          return errorResult(`Missing positional argument: ${p.name}`, path, [], pathParams);
         }
         args.push(argv[idx]);
         idx += 1;
@@ -284,14 +352,14 @@ function finishLeaf(
         }
 
         if (!forcePositionals && isHelpTok(tok)) {
-          return helpResult(path, true);
+          return helpResult(path, true, pathParams);
         }
 
         if (!forcePositionals && tok.startsWith("-")) {
           // MUST be false — lenient mode swallows unknown flags as positionals silently
           const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
           if (tailRep.report.err) {
-            return errorResult(tailRep.report.err, path, []);
+            return errorResult(tailRep.report.err, path, [], pathParams);
           }
           if (tailRep.report.sawDoubleDash) {
             forcePositionals = true;
@@ -300,7 +368,7 @@ function finishLeaf(
             idx = tailRep.nextIndex;
             continue;
           }
-          return errorResult(`Unexpected option token: ${tok}`, path, []);
+          return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
         }
 
         args.push(tok);
@@ -315,27 +383,27 @@ function finishLeaf(
       }
     }
     if (count < argMin) {
-      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`, path, []);
+      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`, path, [], pathParams);
     }
   }
 
   if (idx < argv.length) {
     if (forcePositionals) {
-      return errorResult("Unexpected extra arguments", path, []);
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
 
     if (isHelpTok(argv[idx])) {
-      return helpResult(path, true);
+      return helpResult(path, true, pathParams);
     }
 
     const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
     if (tailRep.report.err) {
-      return errorResult(tailRep.report.err, path, []);
+      return errorResult(tailRep.report.err, path, [], pathParams);
     }
     idx = tailRep.nextIndex;
 
     if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments", path, []);
+      return errorResult("Unexpected extra arguments", path, [], pathParams);
     }
   }
 
@@ -344,6 +412,7 @@ function finishLeaf(
     path,
     opts,
     args,
+    pathParams,
     helpExplicit: false,
     helpPath: [],
     errorMsg: "",
@@ -354,12 +423,18 @@ function finishLeaf(
 // ── Main Parser ───────────────────────────────────────────────────────────────
 
 /** Builds a user-error parse result; `path` defaults to `errorHelpPath`. */
-function errorResult(errorMsg: string, errorHelpPath: string[] = [], path: string[] = errorHelpPath): ParseResult {
+function errorResult(
+  errorMsg: string,
+  errorHelpPath: string[] = [],
+  path: string[] = errorHelpPath,
+  pathParams: Record<string, string> = {},
+): ParseResult {
   return {
     kind: ParseKind.Error,
     path,
     opts: {},
     args: [],
+    pathParams,
     helpExplicit: false,
     helpPath: [],
     errorMsg,
@@ -368,12 +443,13 @@ function errorResult(errorMsg: string, errorHelpPath: string[] = [], path: strin
 }
 
 /** Builds a help-request result for the current routing path. */
-function helpResult(p: string[], explicit: boolean): ParseResult {
+function helpResult(p: string[], explicit: boolean, pathParams: Record<string, string> = {}): ParseResult {
   return {
     kind: ParseKind.Help,
     path: [],
     opts: {},
     args: [],
+    pathParams,
     helpExplicit: explicit,
     helpPath: p,
     errorMsg: "",
@@ -381,13 +457,45 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
+type DescendResult = { ok: true; node: CliNode; cliEnabled: boolean } | { ok: false; error: ParseResult };
+
+/** Descends into a static or `:param` child, updating path and pathParams. */
+function descendChild(
+  parent: CliRouter,
+  tok: string,
+  path: string[],
+  pathParams: Record<string, string>,
+  cliEnabled: boolean,
+): DescendResult {
+  const staticChild = findStaticChild(parent.commands, tok);
+  if (staticChild) {
+    if (!isCliCallable(staticChild, cliEnabled)) {
+      return { ok: false, error: errorResult(`Unknown subcommand: ${tok}`, path, [], pathParams) };
+    }
+    path.push(tok);
+    return { ok: true, node: staticChild, cliEnabled: isCliCallable(staticChild, cliEnabled) };
+  }
+
+  const paramChild = findParamChild(parent.commands);
+  if (paramChild && isCliCallable(paramChild, cliEnabled)) {
+    const paramName = paramChild.key.slice(1);
+    path.push(paramChild.key);
+    pathParams[paramName] = tok;
+    return { ok: true, node: paramChild, cliEnabled: isCliCallable(paramChild, cliEnabled) };
+  }
+
+  return { ok: false, error: errorResult(`Unknown subcommand: ${tok}`, path, [], pathParams) };
+}
+
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
 export function parse(root: CliNode, argv: string[]): ParseResult {
   let i = 0;
   const path: string[] = [];
+  const pathParams: Record<string, string> = {};
   const opts: Record<string, string> = {};
+  let cliEnabled = true;
 
   const rootLenient =
     isCliRouter(root) &&
@@ -412,7 +520,10 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   let node: CliNode | undefined;
 
   if (isCliLeaf(root)) {
-    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals);
+    if (isJsonLeaf(root)) {
+      return finishJsonLeaf(root, i, argv, path, opts, pathParams);
+    }
+    return finishLeaf(root, i, argv, path, opts, root.options ?? [], forcePositionals, pathParams);
   }
 
   if (i >= argv.length) {
@@ -431,12 +542,41 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     }
   } else {
     const peek = argv[i];
-    const childPick = !forcePositionals ? findChild(root.commands, peek) : undefined;
+    const childPick = !forcePositionals ? findStaticChild(root.commands, peek) : undefined;
 
     if (childPick !== undefined) {
+      if (!isCliCallable(childPick, cliEnabled)) {
+        return errorResult(`Unknown command: ${peek}`, path, [], pathParams);
+      }
       cmdName = peek;
       i += 1;
       node = childPick;
+      cliEnabled = isCliCallable(childPick, cliEnabled);
+    } else if (!forcePositionals && isCliRouter(root)) {
+      const paramChild = findParamChild(root.commands);
+      if (paramChild && isCliCallable(paramChild, cliEnabled)) {
+        cmdName = paramChild.key;
+        pathParams[paramChild.key.slice(1)] = peek;
+        i += 1;
+        node = paramChild;
+        cliEnabled = isCliCallable(paramChild, cliEnabled);
+      } else {
+        const fallbackCommand = root.fallbackCommand;
+        const canRouteUnknown =
+          fallbackCommand !== undefined &&
+          ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
+            (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
+
+        if (canRouteUnknown) {
+          cmdName = fallbackCommand;
+          node = findChild(root.commands, cmdName);
+          if (!node) {
+            return errorResult(`Unknown command: ${cmdName}`, path, [], pathParams);
+          }
+        } else {
+          return errorResult(`Unknown command: ${peek}`, path, [], pathParams);
+        }
+      }
     } else {
       const fallbackCommand = root.fallbackCommand;
       const canRouteUnknown =
@@ -473,6 +613,10 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 
   // Walk the command tree
   while (true) {
+    if (isCliLeaf(current) && isJsonLeaf(current)) {
+      return finishJsonLeaf(current, i, argv, path, opts, pathParams);
+    }
+
     if (!forcePositionals) {
       const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
       if (orep.report.err) {
@@ -485,7 +629,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     }
 
     if (i < argv.length && !forcePositionals && isHelpTok(argv[i])) {
-      return helpResult(path, true);
+      return helpResult(path, true, pathParams);
     }
 
     if (i >= argv.length) {
@@ -497,28 +641,29 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
           if (fbNode) {
             path.push(fb);
             current = fbNode;
+            cliEnabled = isCliCallable(fbNode, cliEnabled);
             continue;
           }
         }
-        return helpResult(path, false);
+        return helpResult(path, false, pathParams);
       }
       if (!isCliLeaf(current)) {
-        return helpResult(path, false);
+        return helpResult(path, false, pathParams);
       }
-      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
     }
 
     const tok = argv[i];
     if (!forcePositionals && tok.startsWith("-")) {
-      return errorResult(`Unexpected option token: ${tok}`, path);
+      return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
     }
 
     if (!forcePositionals && isCliRouter(current)) {
-      const childOpt = findChild(current.commands, tok);
-      if (childOpt !== undefined) {
+      const descended = descendChild(current, tok, path, pathParams, cliEnabled);
+      if (descended.ok) {
         i += 1;
-        path.push(tok);
-        current = childOpt;
+        current = descended.node;
+        cliEnabled = descended.cliEnabled;
         continue;
       }
     }
@@ -534,6 +679,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         if (fbNode) {
           path.push(fb);
           current = fbNode;
+          cliEnabled = isCliCallable(fbNode, cliEnabled);
           continue;
         }
       }
@@ -541,13 +687,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       return errorResult(
         forcePositionals ? `Expected subcommand but got positional: ${tok}` : `Unknown subcommand: ${tok}`,
         path,
+        [],
+        pathParams,
       );
     }
 
     if (!isCliLeaf(current)) {
-      return helpResult(path, false);
+      return helpResult(path, false, pathParams);
     }
-    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
   }
 }
 

package/src/{schema.ts → core/schema.ts}

@@ -2,15 +2,15 @@
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
 */
 
-import { type CliSchemaExport, exportPresentationBuiltins } from "./builtins/export.ts";
-import { cliResolveNotes } from "./help.ts";
-import { visibleOptions } from "./hidden.ts";
+import { type CliSchemaExport, exportPresentationBuiltins } from "~/builtins/export.ts";
+import { cliResolveNotes } from "~/help.ts";
+import { isCliSchemaHidden, visibleOptions } from "~/runtime/exposure.ts";
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter, leafOutputSchema } from "./types.ts";
 
-const RESERVED = new Set(["api", "completion", "configure", "docs", "mcp", "version"]);
+const RESERVED = new Set(["http", "completion", "configure", "docs", "mcp", "version"]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
-  if (cmd.hidden) {
+  if (isCliSchemaHidden(cmd)) {
     return null;
   }
 
@@ -35,6 +35,8 @@ function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
     const outputSchema = leafOutputSchema(cmd);
     if (outputSchema !== undefined) {
       out.outputSchema = outputSchema;
+    } else if (cmd.http?.successContentType !== undefined) {
+      out.outputContentType = cmd.http.successContentType;
     }
     out.commands = exportPresentationBuiltins(root);
     return out;
@@ -67,17 +69,27 @@ function resolveSchemaNotes(node: CliSchemaExport, appKey: string): CliSchemaExp
   return out;
 }
 
+/** JSON-safe command tree export (handlers omitted). */
+export interface CliSchemaRootExport extends CliSchemaExport {
+  /** Program-level error JSON Schema when configured on `httpServer.errors` or `mcpServer.errors`. */
+  errorSchema?: Record<string, unknown>;
+}
+
 /** Returns the JSON-safe command tree (handlers omitted). */
-export function cliSchemaExport(root: CliProgram): CliSchemaExport {
+export function cliSchemaExport(root: CliProgram): CliSchemaRootExport {
   const exported = exportCommand(root, root);
-  if (!exported) {
-    return {
-      key: root.key,
-      description: root.description,
-      commands: exportPresentationBuiltins(root),
-    };
+  const errorSchema = root.httpServer?.errors?.errorSchema ?? root.mcpServer?.errors?.errorSchema;
+  const base: CliSchemaRootExport = !exported
+    ? {
+        key: root.key,
+        description: root.description,
+        commands: exportPresentationBuiltins(root),
+      }
+    : resolveSchemaNotes(exported, root.key);
+  if (errorSchema !== undefined) {
+    base.errorSchema = errorSchema;
   }
-  return resolveSchemaNotes(exported, root.key);
+  return base;
 }
 
 export function cliSchemaJson(root: CliProgram): string {