argsbarg 1.3.0 → 1.4.0

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;
+}

package/src/mcp/server.ts

@@ -0,0 +1,226 @@
+/*
+This module implements the MCP JSON-RPC server over stdio: initialize, tools,
+resources, and ping. Responses are newline-delimited JSON on stdout only.
+*/
+
+import { cliInvoke } from "../invoke.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { CliCommand } from "../types.ts";
+import { buildToolCallSuccess } from "./result.ts";
+import {
+  collectMcpTools,
+  mcpToolCallToArgv,
+  resolveMcpSchemaUri,
+  resolveMcpServerInfo,
+} from "./tools.ts";
+
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+
+/** JSON-RPC request shape from stdin. */
+interface JsonRpcRequest {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: unknown;
+}
+
+/** Writes a JSON-RPC response line to stdout. */
+function writeResponse(msg: Record<string, unknown>): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+/** Writes a JSON-RPC error response. */
+function writeError(id: string | number | null | undefined, code: number, message: string): void {
+  if (id === undefined) {
+    return;
+  }
+  writeResponse({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message },
+  });
+}
+
+/** Handles one NDJSON request line. */
+async function handleRequestLine(root: CliCommand, line: string): Promise<void> {
+  let req: JsonRpcRequest;
+  try {
+    req = JSON.parse(line) as JsonRpcRequest;
+  } catch {
+    return;
+  }
+
+  const id = req.id;
+  const hasId = id !== undefined;
+
+  if (req.jsonrpc !== "2.0") {
+    if (hasId) {
+      writeError(id, -32600, "Invalid Request");
+    }
+    return;
+  }
+
+  const method = req.method ?? "";
+  const params = (req.params ?? {}) as Record<string, unknown>;
+
+  if (method === "notifications/initialized") {
+    return;
+  }
+
+  if (!hasId) {
+    return;
+  }
+
+  try {
+    if (method === "initialize") {
+      const info = resolveMcpServerInfo(root);
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: info.name, version: info.version },
+        },
+      });
+      return;
+    }
+
+    if (method === "ping") {
+      writeResponse({ jsonrpc: "2.0", id, result: {} });
+      return;
+    }
+
+    if (method === "tools/list") {
+      const tools = collectMcpTools(root).map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      }));
+      writeResponse({ jsonrpc: "2.0", id, result: { tools } });
+      return;
+    }
+
+    if (method === "tools/call") {
+      const name = params.name;
+      if (typeof name !== "string") {
+        writeError(id, -32602, "Invalid params: name required");
+        return;
+      }
+      const rawArgs = params.arguments;
+      if (rawArgs !== undefined && (typeof rawArgs !== "object" || rawArgs === null || Array.isArray(rawArgs))) {
+        writeError(id, -32602, "Invalid params: arguments must be an object");
+        return;
+      }
+      const toolList = collectMcpTools(root);
+      const tool = toolList.find((t) => t.name === name);
+      if (!tool) {
+        writeError(id, -32602, `Unknown tool: ${name}`);
+        return;
+      }
+      const argvResult = mcpToolCallToArgv(root, tool, (rawArgs ?? {}) as Record<string, unknown>);
+      if ("error" in argvResult) {
+        writeResponse({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: argvResult.error }],
+            isError: true,
+          },
+        });
+        return;
+      }
+      const invokeResult = await cliInvoke(root, argvResult);
+      if (invokeResult.kind === "ok" && invokeResult.exitCode === 0) {
+        writeResponse({
+          jsonrpc: "2.0",
+          id,
+          result: buildToolCallSuccess(invokeResult.stdout, invokeResult.stderr),
+        });
+        return;
+      }
+      const errText = invokeResult.stderr.trim() || invokeResult.errorMsg || `Exit code ${invokeResult.exitCode}`;
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          content: [{ type: "text", text: errText }],
+          isError: true,
+        },
+      });
+      return;
+    }
+
+    if (method === "resources/list") {
+      const uri = resolveMcpSchemaUri(root);
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          resources: [
+            {
+              uri,
+              name: "cli-schema",
+              description: "Full CLI command tree (same as --schema).",
+              mimeType: "application/json",
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    if (method === "resources/read") {
+      const uri = params.uri;
+      if (typeof uri !== "string") {
+        writeError(id, -32602, "Invalid params: uri required");
+        return;
+      }
+      const expected = resolveMcpSchemaUri(root);
+      if (uri !== expected) {
+        writeError(id, -32602, `Unknown resource: ${uri}`);
+        return;
+      }
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [
+            {
+              uri: expected,
+              mimeType: "application/json",
+              text: cliSchemaJson(root).trimEnd(),
+            },
+          ],
+        },
+      });
+      return;
+    }
+
+    writeError(id, -32601, "Method not found");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Internal error";
+    writeError(id, -32603, message);
+  }
+}
+
+/** Runs the MCP NDJSON read loop on stdin until EOF. */
+export async function mcpServeStdioLoop(root: CliCommand): Promise<void> {
+  let buffer = "";
+  for await (const chunk of Bun.stdin.stream()) {
+    buffer += new TextDecoder().decode(chunk);
+    let nl: number;
+    while ((nl = buffer.indexOf("\n")) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line.length === 0) {
+        continue;
+      }
+      await handleRequestLine(root, line);
+    }
+  }
+  const trailing = buffer.trim();
+  if (trailing.length > 0) {
+    await handleRequestLine(root, trailing);
+  }
+}

package/src/mcp/tools.ts

@@ -0,0 +1,209 @@
+/*
+This module maps CliCommand leaf nodes to MCP tool definitions and converts
+flat JSON tool arguments into argv for cliInvoke.
+*/
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { collectOptionDefs } from "../parse.ts";
+import { CliCommand, CliOption, CliOptionKind, CliPositional } from "../types.ts";
+
+/** Default URI for the CLI schema MCP resource. */
+export const MCP_SCHEMA_URI_DEFAULT = "argsbarg://schema";
+
+/** One MCP tool derived from a leaf CLI command. */
+export interface McpToolDef {
+  /** MCP tool name (underscore-separated path). */
+  name: string;
+  /** Tool description from the leaf command. */
+  description: string;
+  /** Command path segments from the program root. */
+  path: string[];
+  /** Leaf command node. */
+  leaf: CliCommand;
+  /** JSON Schema for tools/call arguments. */
+  inputSchema: Record<string, unknown>;
+}
+
+/** Builds MCP tool description: "{cli path} — {description}". */
+export function mcpToolDescription(path: string[], rootKey: string, description: string): string {
+  const prefix = path.length > 0 ? path.join(" ") : rootKey;
+  return `${prefix} — ${description}`;
+}
+
+/** Sanitizes a command key segment for MCP tool names. */
+export function sanitizeToolSegment(key: string): string {
+  return key.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
+/** Builds the MCP tool name for a leaf at the given path. */
+export function mcpToolName(root: CliCommand, path: string[]): string {
+  if (path.length === 0) {
+    return sanitizeToolSegment(root.key);
+  }
+  return path.map(sanitizeToolSegment).join("_");
+}
+
+/** JSON Schema property for one option. */
+function optionProperty(opt: CliOption): Record<string, unknown> {
+  const base = { description: opt.description };
+  switch (opt.kind) {
+    case CliOptionKind.Presence:
+      return { type: "boolean", ...base };
+    case CliOptionKind.String:
+      return { type: "string", ...base };
+    case CliOptionKind.Number:
+      return { type: "number", ...base };
+  }
+}
+
+/** JSON Schema property for one positional slot. */
+function positionalProperty(p: CliPositional): Record<string, unknown> {
+  const base = { description: p.description };
+  const { argMax = 1 } = p;
+  if (argMax === 0) {
+    return { type: "array", items: { type: "string" }, ...base };
+  }
+  return { type: "string", ...base };
+}
+
+/** Builds inputSchema for a leaf command. */
+function buildInputSchema(root: CliCommand, path: string[], leaf: CliCommand): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const opt of collectOptionDefs(root, path)) {
+    properties[opt.name] = optionProperty(opt);
+    if (opt.required) {
+      required.push(opt.name);
+    }
+  }
+
+  for (const p of leaf.positionals ?? []) {
+    properties[p.name] = positionalProperty(p);
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax === 1 && argMin >= 1) {
+      required.push(p.name);
+    }
+  }
+
+  const schema: Record<string, unknown> = {
+    type: "object",
+    properties,
+    additionalProperties: false,
+  };
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+/** Recursively collects MCP tool definitions from user leaf commands. */
+export function collectMcpTools(root: CliCommand): McpToolDef[] {
+  const out: McpToolDef[] = [];
+
+  /** Walks the command tree and appends leaf tools. */
+  function walk(cmd: CliCommand, path: string[]): void {
+    if ("handler" in cmd && cmd.handler) {
+      if (cmd.key === "completion" || cmd.key === "mcp") {
+        return;
+      }
+      if (cmd.mcpTool?.enabled === false) {
+        return;
+      }
+      out.push({
+        name: mcpToolName(root, path),
+        description: mcpToolDescription(path, root.key, cmd.description),
+        path,
+        leaf: cmd,
+        inputSchema: buildInputSchema(root, path, cmd),
+      });
+      return;
+    }
+    for (const ch of cmd.commands ?? []) {
+      walk(ch, [...path, ch.key]);
+    }
+  }
+
+  if ("handler" in root && root.handler) {
+    walk(root, []);
+  } else {
+    for (const ch of root.commands ?? []) {
+      walk(ch, [ch.key]);
+    }
+  }
+
+  return out;
+}
+
+/** Reads package.json version from cwd synchronously. */
+function resolveMcpVersionFromPackageJson(): string | undefined {
+  try {
+    const text = readFileSync(join(process.cwd(), "package.json"), "utf8");
+    const version = (JSON.parse(text) as { version?: string }).version;
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Resolves MCP server name and version for initialize. */
+export function resolveMcpServerInfo(root: CliCommand): { name: string; version: string } {
+  return {
+    name: root.mcpServer?.name ?? root.key,
+    version: root.mcpServer?.version ?? resolveMcpVersionFromPackageJson() ?? "0.0.0",
+  };
+}
+
+/** Resolves the schema resource URI for this app. */
+export function resolveMcpSchemaUri(root: CliCommand): string {
+  return root.mcpServer?.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+}
+
+/** Converts flat MCP tool arguments to argv for cliInvoke. */
+export function mcpToolCallToArgv(
+  root: CliCommand,
+  tool: McpToolDef,
+  args: Record<string, unknown>,
+): string[] | { error: string } {
+  const argv = [...tool.path];
+
+  for (const opt of collectOptionDefs(root, tool.path)) {
+    const val = args[opt.name];
+    if (val === undefined) {
+      continue;
+    }
+    if (opt.kind === CliOptionKind.Presence) {
+      if (val === true) {
+        argv.push(`--${opt.name}`);
+      }
+      continue;
+    }
+    argv.push(`--${opt.name}`, String(val));
+  }
+
+  for (const p of tool.leaf.positionals ?? []) {
+    const val = args[p.name];
+    const { argMin = 1, argMax = 1 } = p;
+
+    if (argMax === 0) {
+      if (!Array.isArray(val)) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      for (const item of val) {
+        argv.push(String(item));
+      }
+      continue;
+    }
+
+    if (val === undefined) {
+      if (argMin >= 1) {
+        return { error: `Missing argument: ${p.name}` };
+      }
+      continue;
+    }
+    argv.push(String(val));
+  }
+
+  return argv;
+}

package/src/mcp.ts

@@ -0,0 +1,24 @@
+/*
+This module starts the ArgsBarg MCP stdio server for opt-in program roots.
+*/
+
+import { mcpServeStdioLoop } from "./mcp/server.ts";
+import { CliCommand } from "./types.ts";
+
+/**
+ * Runs the MCP JSON-RPC server on stdin/stdout until stdin closes, then exits.
+ * Caller must ensure `root.mcpServer` is set.
+ */
+export async function cliMcpServeStdio(root: CliCommand): Promise<never> {
+  try {
+    await mcpServeStdioLoop(root);
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof Error) {
+      process.stderr.write(err.message + "\n");
+    } else {
+      process.stderr.write("MCP server error.\n");
+    }
+    process.exit(1);
+  }
+}