argsbarg 1.3.1 → 1.4.1

package/src/completion.ts

@@ -8,7 +8,7 @@ It keeps completion aligned with the runtime schema so the generated commands,
 options, and descriptions stay in sync with the CLI definition.
 */
 
-import { CliCommand, CliOption } from "./types.ts";
+import { CliCommand, CliOption, CliOptionKind } from "./types.ts";
 
 // ── Shared Types ───────────────────────────────────────────────────────────────
 
@@ -216,6 +216,31 @@ function emitSimulate(ident: string): string {
   return o;
 }
 
+/** Emits bash helper to complete Enum option values when previous token is --name. */
+function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" prev=\"$2\" cur=\"$3\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) {
+      continue;
+    }
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const words = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") COMPREPLY=( $(compgen -W '" + words + "' -- \"$cur\") ); return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
 /** Emits the main `COMPREPLY` driver and `complete -F` registration for bash. */
 function emitMainBodyBash(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
@@ -224,6 +249,7 @@ function emitMainBodyBash(schema: CliCommand, ident: string): string {
   o += "  local prev=\"${COMP_WORDS[COMP_CWORD-1]:-}\"\n";
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$prev\" \"$cur\"; then return; fi\n".replace("${ident}", ident);
   o += "  if [[ $cur == -* ]]; then\n";
   o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
   o += "    local -a optsarr\n";
@@ -289,6 +315,7 @@ export function completionBashScript(schema: CliCommand): string {
   out += emitConsumeShort(ident, scopes);
   out += emitMatchChild(ident, scopes, pathIndex);
   out += emitSimulate(ident);
+  out += emitEnumReplyBash(ident, scopes);
   out += emitMainBodyBash(schema, ident);
 
   return out;
@@ -470,6 +497,31 @@ function emitSimulateZsh(ident: string): string {
   return o;
 }
 
+/** Emits zsh helper to complete Enum option values when previous token is --name. */
+function emitEnumReplyZsh(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=$1 prev=$2\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) {
+      continue;
+    }
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const vals = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") _values " + vals + "; return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
 /** Zsh: `_main` completer and `compdef` registration. */
 function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
@@ -477,6 +529,7 @@ function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   o += "  local curcontext=\"$curcontext\" ret=1\n";
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$words[CURRENT-1]\"; then return 0; fi\n".replace("${ident}", ident);
   o += "  if [[ $PREFIX == -* ]]; then\n";
   o += "    local -a optsarr\n";
   o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
@@ -517,12 +570,13 @@ export function completionZshScript(schema: CliCommand): string {
   out += emitConsumeShortZsh(ident, scopes);
   out += emitMatchChildZsh(ident, scopes, pathIndex);
   out += emitSimulateZsh(ident);
+  out += emitEnumReplyZsh(ident, scopes);
   out += emitMainBodyZsh(schema, ident);
   return out;
 }
 
 /**
- * Returns a schema suitable for help display, including the reserved `completion` subtree.
+ * Returns a schema suitable for help display, including reserved built-in subtrees.
  * Routing roots get `completion` merged; leaf roots are wrapped as a tiny router.
  */
 export function cliPresentationRoot(root: CliCommand): CliCommand {
@@ -534,15 +588,33 @@ export function cliPresentationRoot(root: CliCommand): CliCommand {
       key: root.key,
       description: root.description,
       options: root.options,
-      commands: [cliBuiltinCompletionGroup(root.key)],
+      commands: presentationBuiltins(root),
     } as CliCommand;
   }
   return {
     ...root,
-    commands: [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)],
+    commands: [...(root.commands ?? []), ...presentationBuiltins(root)],
   } as CliCommand;
 }
 
+/** Built-in commands shown in help and merged for routing CLIs. */
+function presentationBuiltins(root: CliCommand): CliCommand[] {
+  const cmds: CliCommand[] = [cliBuiltinCompletionGroup(root.key)];
+  if (root.mcpServer !== undefined) {
+    cmds.push(cliBuiltinMcpCommand());
+  }
+  return cmds;
+}
+
+/** Builds the static `mcp` leaf command (merged when `root.mcpServer` is set). */
+export function cliBuiltinMcpCommand(): CliCommand {
+  return {
+    key: "mcp",
+    description: "Run as an MCP server over stdio (for AI agents).",
+    handler: () => {},
+  };
+}
+
 /**
  * Builds the static `completion` / `bash` / `zsh` command subtree (merged into the program root at runtime).
  */

package/src/context.ts

@@ -7,7 +7,7 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
-import type { CliCommand } from "./types.ts";
+import type { CliCommand, CliInvocation } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /**
@@ -19,6 +19,7 @@ export class CliContext {
   readonly args: string[];
   readonly schema: CliCommand;
   readonly opts: Record<string, string>;
+  readonly invocation: CliInvocation;
 
   /** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -27,12 +28,14 @@ export class CliContext {
     args: string[],
     opts: Record<string, string>,
     schema: CliCommand,
+    invocation: CliInvocation = "cli",
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
     this.args = args;
     this.opts = opts;
     this.schema = schema;
+    this.invocation = invocation;
   }
 
   /** Returns whether a presence flag was set (including implicit "1" for boolean options). */

package/src/help.ts

@@ -151,7 +151,7 @@ function wrapText(text: string, width: number): string[] {
 // ── Option Label Formatting ───────────────────────────────────────────────────
 
 /** Suffix for `--name` in usage (e.g. ` <string>`) based on value kind. */
-function optKindLabel(k: CliOptionKind): string {
+function optKindLabel(k: CliOptionKind, o?: CliOption): string {
   switch (k) {
     case CliOptionKind.Presence:
       return "";
@@ -159,12 +159,22 @@ function optKindLabel(k: CliOptionKind): string {
       return " <number>";
     case CliOptionKind.String:
       return " <string>";
+    case CliOptionKind.Enum: {
+      const choices = o?.choices ?? [];
+      if (choices.length === 0) {
+        return " <choice>";
+      }
+      if (choices.length <= 4) {
+        return " <" + choices.join("|") + ">";
+      }
+      return " <" + choices.slice(0, 3).join("|") + "|…>";
+    }
   }
 }
 
 /** Formats a flag/value option for help tables: `--name`, optional short, optional kind hint. */
 export function cliOptionLabel(o: CliOption, color: boolean): string {
-  let r = "--" + o.name + optKindLabel(o.kind);
+  let r = "--" + o.name + optKindLabel(o.kind, o);
   if (o.shortName) r += ", -" + o.shortName;
   if (!color) return r;