argsbarg 1.3.1 → 1.4.0

package/src/index.test.ts

@@ -10,11 +10,19 @@ shell output regressions.
 import { completionBashScript, completionZshScript } from "./completion.ts";
 import { cliHelpRender } from "./help.ts";
 import { CliCommand, CliFallbackMode, CliOptionKind } from "./index.ts";
+import {
+  collectMcpTools,
+  mcpToolCallToArgv,
+  mcpToolDescription,
+  sanitizeToolSegment,
+} from "./mcp/tools.ts";
+import { buildToolCallSuccess } from "./mcp/result.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
 import { cliValidateRoot } from "./validate.ts";
 import { expect, test } from "bun:test";
 import { $ } from "bun";
+import { join } from "node:path";
 
 test("bundled short presence flags", () => {
   const root: CliCommand = {
@@ -639,4 +647,349 @@ test("completion scripts offer --schema at the program root only", () => {
 
   const zsh = completionZshScript(root);
   expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
+});
+
+const nestedMcpFixture: CliCommand = {
+  key: "nested.ts",
+  description: "Nested groups demo.",
+  mcpServer: { name: "nested-demo", version: "1.0.0" },
+  commands: [
+    {
+      key: "stat",
+      description: "File metadata.",
+      options: [
+        {
+          name: "json",
+          description: "Emit handler output as JSON.",
+          kind: CliOptionKind.Presence,
+        },
+      ],
+      commands: [
+        {
+          key: "owner",
+          description: "Ownership helpers.",
+          commands: [
+            {
+              key: "lookup",
+              description: "Resolve owner info.",
+              options: [
+                {
+                  name: "user-name",
+                  description: "User to look up.",
+                  kind: CliOptionKind.String,
+                  shortName: "u",
+                },
+              ],
+              positionals: [
+                {
+                  name: "path",
+                  description: "File or directory.",
+                  kind: CliOptionKind.String,
+                },
+              ],
+              handler: () => {},
+            },
+          ],
+        },
+      ],
+    },
+    {
+      key: "read",
+      description: "Print the first line of each file.",
+      positionals: [
+        {
+          name: "files",
+          description: "Paths to read.",
+          kind: CliOptionKind.String,
+          argMax: 0,
+        },
+      ],
+      handler: () => {},
+    },
+    {
+      key: "hidden",
+      description: "Internal debug.",
+      mcpTool: { enabled: false },
+      handler: () => {},
+    },
+  ],
+  fallbackCommand: "read",
+  fallbackMode: CliFallbackMode.MissingOrUnknown,
+};
+
+/** Sends NDJSON MCP requests to a subprocess and collects responses by id. */
+async function mcpRequest(requests: object[]): Promise<Map<string | number, object>> {
+  const proc = Bun.spawn(["bun", "run", "examples/nested.ts", "mcp"], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const input = requests.map((r) => JSON.stringify(r) + "\n").join("");
+  proc.stdin.write(input);
+  proc.stdin.end();
+
+  const timeout = setTimeout(() => proc.kill(), 10_000);
+  const stdout = await new Response(proc.stdout).text();
+  await proc.exited;
+  clearTimeout(timeout);
+
+  const byId = new Map<string | number, object>();
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const msg = JSON.parse(trimmed) as { id?: string | number };
+    if (msg.id !== undefined) {
+      byId.set(msg.id, msg);
+    }
+  }
+  return byId;
+}
+
+test("sanitizeToolSegment normalizes dotted app keys", () => {
+  expect(sanitizeToolSegment("minimal.ts")).toBe("minimal_ts");
+});
+
+test("mcpToolDescription formats CLI path and root-leaf prefix", () => {
+  expect(mcpToolDescription(["stat", "owner", "lookup"], "nested.ts", "Resolve owner info.")).toBe(
+    "stat owner lookup — Resolve owner info.",
+  );
+  expect(mcpToolDescription(["read"], "nested.ts", "Print files.")).toBe("read — Print files.");
+  expect(mcpToolDescription([], "helloapp", "Tiny demo.")).toBe("helloapp — Tiny demo.");
+});
+
+test("collectMcpTools lists user leaf commands only", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const names = tools.map((t) => t.name);
+  expect(names).toContain("stat_owner_lookup");
+  expect(names).toContain("read");
+  expect(names).not.toContain("hidden");
+  expect(names).not.toContain("mcp");
+  expect(names).not.toContain("completion");
+  const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
+  expect(lookup.description).toBe("stat owner lookup — Resolve owner info.");
+});
+
+test("collectMcpTools merges parent options into inputSchema", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
+  const schema = lookup.inputSchema as { properties: Record<string, unknown>; required?: string[] };
+  expect(schema.properties.json).toBeDefined();
+  expect(schema.required).toContain("path");
+});
+
+test("mcpToolCallToArgv builds nested lookup argv", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, lookup, {
+    "user-name": "alice",
+    path: "./x",
+    json: true,
+  });
+  expect(argv).toEqual(["stat", "owner", "lookup", "--json", "--user-name", "alice", "./x"]);
+});
+
+test("mcpToolCallToArgv expands varargs positionals", () => {
+  const tools = collectMcpTools(nestedMcpFixture);
+  const read = tools.find((t) => t.name === "read")!;
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: ["a", "b"] });
+  expect(argv).toEqual(["read", "a", "b"]);
+});
+
+test("reserved command name mcp is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "mcp",
+        description: "bad",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/Reserved command name: mcp/);
+});
+
+test("mcpServer on non-root node is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "x",
+        description: "cmd",
+        mcpServer: {},
+        handler: () => {},
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/mcpServer is only supported on the program root/);
+});
+
+test("mcpTool on root is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    mcpTool: { enabled: false },
+    handler: () => {},
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/mcpTool is only supported on leaf commands/);
+});
+
+test("mcpTool on routing node is rejected", () => {
+  const root: CliCommand = {
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "group",
+        description: "group",
+        mcpTool: { enabled: false },
+        commands: [
+          {
+            key: "leaf",
+            description: "leaf",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  };
+  expect(() => cliValidateRoot(root)).toThrow(/mcpTool is only supported on leaf commands/);
+});
+
+test("buildToolCallSuccess returns stdout only", () => {
+  const result = buildToolCallSuccess("hello\n", "");
+  expect(result.isError).toBe(false);
+  expect(result.content).toEqual([{ type: "text", text: "hello\n" }]);
+  expect(result.structuredContent).toBeUndefined();
+});
+
+test("buildToolCallSuccess adds stderr as second content block", () => {
+  const result = buildToolCallSuccess("out\n", "warn\n");
+  expect(result.content).toEqual([
+    { type: "text", text: "out\n" },
+    { type: "text", text: "warn" },
+  ]);
+  expect(result.structuredContent).toBeUndefined();
+});
+
+test("buildToolCallSuccess stderr-only still includes stdout slot", () => {
+  const result = buildToolCallSuccess("", "warn\n");
+  expect(result.content).toEqual([
+    { type: "text", text: "" },
+    { type: "text", text: "warn" },
+  ]);
+});
+
+test("buildToolCallSuccess parses JSON structuredContent", () => {
+  const result = buildToolCallSuccess('{"a":1}\n', "");
+  expect(result.structuredContent).toEqual({ a: 1 });
+  expect(result.content[0]!.text).toBe('{"a":1}\n');
+});
+
+test("buildToolCallSuccess skips structuredContent for plain text", () => {
+  const result = buildToolCallSuccess("lookup user=x\n", "");
+  expect(result.structuredContent).toBeUndefined();
+});
+
+test("buildToolCallSuccess parses JSON primitives", () => {
+  const result = buildToolCallSuccess("true\n", "");
+  expect(result.structuredContent).toBe(true);
+});
+
+test("MCP initialize returns tools and resources capabilities", async () => {
+  const responses = await mcpRequest([{ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }]);
+  const res = responses.get(1) as { result: { capabilities: Record<string, unknown> } };
+  expect(res.result.capabilities.tools).toBeDefined();
+  expect(res.result.capabilities.resources).toBeDefined();
+});
+
+test("MCP tools/list includes stat_owner_lookup", async () => {
+  const responses = await mcpRequest([{ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }]);
+  const res = responses.get(2) as { result: { tools: { name: string; inputSchema: { required?: string[] } }[] } };
+  const lookup = res.result.tools.find((t) => t.name === "stat_owner_lookup");
+  expect(lookup).toBeDefined();
+  expect(lookup!.inputSchema.required).toContain("path");
+});
+
+test("MCP resources/read returns schema JSON", async () => {
+  const responses = await mcpRequest([
+    { jsonrpc: "2.0", id: 3, method: "resources/read", params: { uri: "argsbarg://schema" } },
+  ]);
+  const res = responses.get(3) as { result: { contents: { text: string }[] } };
+  const schema = JSON.parse(res.result.contents[0]!.text);
+  expect(schema.key).toBe("nested.ts");
+});
+
+test("MCP tools/call runs stat_owner_lookup", async () => {
+  const readme = join(import.meta.dir, "..", "README.md");
+  const responses = await mcpRequest([
+    {
+      jsonrpc: "2.0",
+      id: 4,
+      method: "tools/call",
+      params: {
+        name: "stat_owner_lookup",
+        arguments: { path: readme, "user-name": "test" },
+      },
+    },
+  ]);
+  const res = responses.get(4) as { result: { content: { text: string }[]; isError: boolean } };
+  expect(res.result.isError).toBe(false);
+  expect(res.result.content[0]!.text).toContain("lookup user=test");
+});
+
+test("MCP tools/call returns structuredContent for JSON stdout", async () => {
+  const readme = join(import.meta.dir, "..", "README.md");
+  const responses = await mcpRequest([
+    {
+      jsonrpc: "2.0",
+      id: 6,
+      method: "tools/call",
+      params: {
+        name: "stat_owner_lookup",
+        arguments: { path: readme, "user-name": "test", json: true },
+      },
+    },
+  ]);
+  const res = responses.get(6) as {
+    result: {
+      content: { text: string }[];
+      structuredContent?: { user: string; path: string };
+      isError: boolean;
+    };
+  };
+  expect(res.result.isError).toBe(false);
+  expect(res.result.structuredContent).toEqual({ user: "test", path: readme });
+  expect(JSON.parse(res.result.content[0]!.text.trim())).toEqual({ user: "test", path: readme });
+});
+
+test("MCP tools/call errors on missing required positional", async () => {
+  const responses = await mcpRequest([
+    {
+      jsonrpc: "2.0",
+      id: 5,
+      method: "tools/call",
+      params: { name: "stat_owner_lookup", arguments: { "user-name": "test" } },
+    },
+  ]);
+  const res = responses.get(5) as { result: { isError: boolean; content: { text: string }[] } };
+  expect(res.result.isError).toBe(true);
+  expect(res.result.content[0]!.text).toContain("Missing argument: path");
+});
+
+test("MCP ping returns empty result", async () => {
+  const responses = await mcpRequest([{ jsonrpc: "2.0", id: 99, method: "ping", params: {} }]);
+  const res = responses.get(99) as { result: Record<string, never> };
+  expect(res.result).toEqual({});
+});
+
+test("minimal.ts mcp without opt-in fails", async () => {
+  const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
+  expect(exitCode).toBe(1);
+  expect(stderr.toString()).toContain("mcp");
 });

package/src/index.ts

@@ -10,5 +10,5 @@ module layout.
 export { CliContext } from "./context.ts";
 export { cliErrWithHelp, cliRun } from "./runtime";
 export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
-export type { CliCommand, CliHandler, CliOption, CliPositional } from "./types.ts";
+export type { CliCommand, CliHandler, CliMcpServerConfig, CliMcpToolConfig, CliOption, CliPositional } from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/invoke.ts

@@ -0,0 +1,192 @@
+/*
+This module invokes leaf CLI handlers without exiting the process.
+It parses argv against the user schema, captures stdout/stderr, and patches
+process.exit so MCP tool calls can run handlers repeatedly.
+*/
+
+import { CliContext } from "./context.ts";
+import { parse, postParseValidate, ParseKind } from "./parse.ts";
+import { CliCommand } from "./types.ts";
+import { format } from "node:util";
+
+/** Outcome of a non-exiting CLI invocation. */
+export type CliInvokeKind = "ok" | "help" | "schema" | "error";
+
+/** Result of cliInvoke: captured output and exit metadata without process.exit. */
+export interface CliInvokeResult {
+  /** Invocation outcome. */
+  kind: CliInvokeKind;
+  /** Simulated exit code. */
+  exitCode: number;
+  /** Captured stdout during handler execution. */
+  stdout: string;
+  /** Captured stderr during handler execution. */
+  stderr: string;
+  /** Set when kind === "error" (parse/validation message). */
+  errorMsg?: string;
+}
+
+/** Thrown internally when a patched process.exit fires during handler execution. */
+class CliInvokeExit extends Error {
+  /** Exit code passed to process.exit. */
+  readonly code: number;
+
+  /** Creates an exit signal with the given status code. */
+  constructor(code: number) {
+    super(`process.exit(${code})`);
+    this.name = "CliInvokeExit";
+    this.code = code;
+  }
+}
+
+/** Looks up a subcommand or routing node by `key`. */
+function findChild(cmds: CliCommand[], name: string): CliCommand | undefined {
+  return cmds.find((c) => c.key === name);
+}
+
+/**
+ * Parses argv against the user root, runs the leaf handler, and returns captured output.
+ * Never calls process.exit.
+ */
+export async function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult> {
+  let pr = parse(root, argv);
+  pr = postParseValidate(root, pr);
+
+  if (pr.kind === ParseKind.Help) {
+    return {
+      kind: "help",
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+      errorMsg: "Help is not available via MCP tool calls.",
+    };
+  }
+
+  if (pr.kind === ParseKind.Schema) {
+    return {
+      kind: "schema",
+      exitCode: 1,
+      stdout: "",
+      stderr: "",
+      errorMsg: "Schema export is not available via MCP tool calls.",
+    };
+  }
+
+  if (pr.kind === ParseKind.Error) {
+    return {
+      kind: "error",
+      exitCode: 1,
+      stdout: "",
+      stderr: pr.errorMsg,
+      errorMsg: pr.errorMsg,
+    };
+  }
+
+  let current: CliCommand = root;
+  for (const seg of pr.path) {
+    const ch = findChild(current.commands ?? [], seg);
+    if (!ch) {
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout: "",
+        stderr: "Internal error: missing handler for path.",
+        errorMsg: "Internal error: missing handler for path.",
+      };
+    }
+    current = ch;
+  }
+
+  if (!("handler" in current) || !current.handler) {
+    return {
+      kind: "error",
+      exitCode: 1,
+      stdout: "",
+      stderr: "Internal error: missing handler for path.",
+      errorMsg: "Internal error: missing handler for path.",
+    };
+  }
+
+  const handler = current.handler;
+  const ctx = new CliContext(root.key, pr.path, pr.args, pr.opts, root);
+
+  let stdout = "";
+  let stderr = "";
+  const origExit = process.exit;
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  const origStderrWrite = process.stderr.write.bind(process.stderr);
+  const origConsoleLog = console.log;
+  const origConsoleError = console.error;
+  const origConsoleInfo = console.info;
+  const origConsoleWarn = console.warn;
+
+  process.exit = ((code?: number) => {
+    throw new CliInvokeExit(code ?? 0);
+  }) as typeof process.exit;
+
+  process.stdout.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+    stdout += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+    if (typeof args[0] === "function") {
+      (args[0] as () => void)();
+    }
+    return true;
+  }) as typeof process.stdout.write;
+
+  process.stderr.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+    stderr += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+    if (typeof args[0] === "function") {
+      (args[0] as () => void)();
+    }
+    return true;
+  }) as typeof process.stderr.write;
+
+  console.log = (...args: unknown[]) => {
+    stdout += format(...args) + "\n";
+  };
+  console.info = (...args: unknown[]) => {
+    stdout += format(...args) + "\n";
+  };
+  console.warn = (...args: unknown[]) => {
+    stderr += format(...args) + "\n";
+  };
+  console.error = (...args: unknown[]) => {
+    stderr += format(...args) + "\n";
+  };
+
+  try {
+    await Promise.resolve(handler(ctx));
+    return { kind: "ok", exitCode: 0, stdout, stderr };
+  } catch (err) {
+    if (err instanceof CliInvokeExit) {
+      if (err.code === 0) {
+        return { kind: "ok", exitCode: 0, stdout, stderr };
+      }
+      const msg = stderr.trim() || `Exit code ${err.code}`;
+      return { kind: "error", exitCode: err.code, stdout, stderr, errorMsg: msg };
+    }
+    if (err instanceof Error) {
+      return {
+        kind: "error",
+        exitCode: 1,
+        stdout,
+        stderr: err.message + "\n",
+        errorMsg: err.message,
+      };
+    }
+    return {
+      kind: "error",
+      exitCode: 1,
+      stdout,
+      stderr: "Unknown error\n",
+      errorMsg: "Unknown error",
+    };
+  } finally {
+    process.exit = origExit;
+    process.stdout.write = origStdoutWrite;
+    process.stderr.write = origStderrWrite;
+    console.log = origConsoleLog;
+    console.error = origConsoleError;
+    console.info = origConsoleInfo;
+    console.warn = origConsoleWarn;
+  }
+}

package/src/mcp/result.ts

@@ -0,0 +1,57 @@
+/*
+This module builds MCP tools/call success results from captured handler output.
+*/
+
+/** Text content block in an MCP tool result. */
+export interface McpTextContent {
+  type: "text";
+  text: string;
+}
+
+/** Successful MCP tools/call result payload. */
+export interface McpToolCallSuccess {
+  content: McpTextContent[];
+  structuredContent?: unknown;
+  isError: false;
+}
+
+/** Parses stdout as JSON when the full trimmed string is valid JSON. */
+function parseStructuredStdout(stdout: string): unknown | undefined {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Builds a successful tools/call result from captured handler stdout/stderr.
+ * stderr is a second content block when non-empty; structuredContent is set when stdout is JSON.
+ */
+export function buildToolCallSuccess(stdout: string, stderr: string): McpToolCallSuccess {
+  const content: McpTextContent[] = [];
+  if (stdout.length > 0) {
+    content.push({ type: "text", text: stdout });
+  }
+  const errText = stderr.trim();
+  if (errText.length > 0) {
+    if (content.length === 0) {
+      content.push({ type: "text", text: "" });
+    }
+    content.push({ type: "text", text: errText });
+  }
+  if (content.length === 0) {
+    content.push({ type: "text", text: "" });
+  }
+
+  const structuredContent = parseStructuredStdout(stdout);
+  const result: McpToolCallSuccess = { content, isError: false };
+  if (structuredContent !== undefined) {
+    result.structuredContent = structuredContent;
+  }
+  return result;
+}