argsbarg 1.3.0 → 1.4.0

package/src/parse.ts

@@ -217,7 +217,7 @@ function consumeOptions(
 // ── Positional Collection ─────────────────────────────────────────────────────
 
 /** Merges option defs from the program root along the routed command path. */
-function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
+export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[] {
   let defs = [...(root.options ?? [])];
   let cmds = root.commands ?? [];
 
@@ -458,7 +458,7 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
   // Walk the command tree
   while (true) {
     if (!forcePositionals) {
-      const orep = consumeOptions(current.options ?? [], false, argv, i, opts);
+      const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
       if (orep.report.err) {
         return {
           kind: ParseKind.Error,

package/src/runtime.ts

@@ -7,9 +7,10 @@ It keeps execution flow out of the public barrel so the exported API stays small
 the runtime responsibilities remain easy to reason about.
 */
 
-import { cliBuiltinCompletionGroup, completionBashScript, completionZshScript } from "./completion.ts";
+import { cliBuiltinCompletionGroup, cliBuiltinMcpCommand, cliPresentationRoot, completionBashScript, completionZshScript } from "./completion.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
+import { cliMcpServeStdio } from "./mcp.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { CliCommand } from "./types.ts";
@@ -22,9 +23,7 @@ function cliRootMergedWithBuiltins(root: CliCommand): CliCommand {
   if (root.handler) {
     return root;
   }
-  const merged = { ...root } as any;
-  merged.commands = [...(root.commands ?? []), cliBuiltinCompletionGroup(root.key)];
-  return merged as CliCommand;
+  return cliPresentationRoot(root);
 }
 
 /**
@@ -48,6 +47,11 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   let parseRoot = root;
   let isLeafCompletionIntercept = false;
 
+  if (root.handler && argv.length >= 1 && argv[0] === "mcp" && !root.mcpServer) {
+    process.stderr.write("Unknown command: mcp\n");
+    process.exit(1);
+  }
+
   // Intercept completion for Leaf roots (since they can't natively have a completion subcommand)
   // but wrap them in a dummy router so that the parser handles `-h` and errors correctly.
   if (root.handler && argv.length >= 1 && argv[0] === "completion") {
@@ -57,6 +61,12 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
       description: root.description,
       commands: [cliBuiltinCompletionGroup(root.key)],
     } as any;
+  } else if (root.handler && argv.length >= 1 && argv[0] === "mcp" && root.mcpServer) {
+    parseRoot = {
+      key: root.key,
+      description: root.description,
+      commands: [cliBuiltinMcpCommand()],
+    } as CliCommand;
   } else {
     parseRoot = cliRootMergedWithBuiltins(root);
   }
@@ -65,7 +75,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
   pr = postParseValidate(parseRoot, pr);
 
   if (pr.kind === ParseKind.Help) {
-    process.stdout.write(cliHelpRender(parseRoot, pr.helpPath, false));
+    process.stdout.write(cliHelpRender(cliPresentationRoot(root), pr.helpPath, false));
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
@@ -78,7 +88,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
     process.stderr.write(msg + "\n");
-    process.stderr.write(cliHelpRender(parseRoot, pr.errorHelpPath, true));
+    process.stderr.write(cliHelpRender(cliPresentationRoot(root), pr.errorHelpPath, true));
     process.exit(1);
   }
 
@@ -99,6 +109,18 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     }
   }
 
+  if (pr.path[0] === "mcp") {
+    if (!root.mcpServer) {
+      process.stderr.write("Internal error: mcp not enabled.\n");
+      process.exit(1);
+    }
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: mcp " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    await cliMcpServeStdio(root);
+  }
+
   let current = parseRoot;
   for (const seg of pr.path) {
     const ch = (current.commands ?? []).find((candidate: CliCommand) => candidate.key === seg);
@@ -133,6 +155,6 @@ export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
   process.stderr.write(line + "\n");
-  process.stderr.write(cliHelpRender(ctx.schema, ctx.commandPath, true));
+  process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.schema), ctx.commandPath, true));
   process.exit(1);
 }

package/src/schema.ts

@@ -13,6 +13,7 @@ import {
   CliOption,
   CliPositional,
 } from "./types.ts";
+import { cliBuiltinCompletionGroup } from "./completion.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -34,6 +35,20 @@ export interface CliSchemaExport {
   positionals?: CliPositional[];
 }
 
+/** JSON-safe export of the reserved `completion` subtree (no handler recursion). */
+function exportBuiltinCompletionGroup(appName: string): CliSchemaExport {
+  const group = cliBuiltinCompletionGroup(appName);
+  return {
+    key: group.key,
+    description: group.description,
+    commands: (group.commands ?? []).map((ch) => ({
+      key: ch.key,
+      description: ch.description,
+      ...((ch.notes ?? "").length > 0 ? { notes: ch.notes } : {}),
+    })),
+  };
+}
+
 /** Converts one `CliCommand` node into a JSON-safe export (handlers omitted). */
 function exportCommand(cmd: CliCommand): CliSchemaExport {
   const out: CliSchemaExport = {
@@ -53,6 +68,7 @@ function exportCommand(cmd: CliCommand): CliSchemaExport {
     if ((cmd.positionals ?? []).length > 0) {
       out.positionals = cmd.positionals;
     }
+    out.commands = [exportBuiltinCompletionGroup(cmd.key)];
     return out;
   }
 

package/src/types.ts

@@ -78,6 +78,26 @@ export interface CliPositional {
   argMax?: number;
 }
 
+/**
+ * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ */
+export interface CliMcpServerConfig {
+  /** `initialize` serverInfo.name (default: root `key`). */
+  name?: string;
+  /** `initialize` serverInfo.version (default: see resolveMcpVersion). */
+  version?: string;
+  /** Resource URI for schema export (default: `"argsbarg://schema"`). */
+  schemaResourceUri?: string;
+}
+
+/**
+ * Leaf-only. Controls how this command appears as an MCP tool.
+ */
+export interface CliMcpToolConfig {
+  /** When `false`, omit from `tools/list` (default: exposed). */
+  enabled?: boolean;
+}
+
 /**
  * Base properties shared by all command nodes.
  */
@@ -90,6 +110,10 @@ export interface CliCommandBase {
   notes?: string;
   /** Global or command-level flags/options. */
   options?: CliOption[];
+  /** Root-only. When set, enables the `mcp` built-in subcommand. */
+  mcpServer?: CliMcpServerConfig;
+  /** Leaf-only. Per-tool MCP exposure and metadata. */
+  mcpTool?: CliMcpToolConfig;
 }
 
 /**

package/src/validate.ts

@@ -13,7 +13,7 @@ import {
   CliSchemaValidationError,
 } from "./types.ts";
 
-const reservedCommandNames = ["completion"];
+const reservedCommandNames = ["completion", "mcp"];
 
 /**
  * Validates the static CliCommand tree against ArgBarg rules.
@@ -50,6 +50,21 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     );
   }
 
+  if (!isRoot && cmd.mcpServer !== undefined) {
+    throw new CliSchemaValidationError(
+      "mcpServer is only supported on the program root (not on " + cmd.key + ")",
+    );
+  }
+
+  const isLeaf = "handler" in cmd && !!cmd.handler;
+  if (!isLeaf && cmd.mcpTool !== undefined) {
+    throw new CliSchemaValidationError(
+      "mcpTool is only supported on leaf commands (not on " + cmd.key + ")",
+    );
+  }
+  if (isRoot && cmd.mcpTool !== undefined) {
+    throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
+  }
 
   // Check for duplicate child names
   const seenNames = new Set<string>();