argsbarg 1.3.1 → 1.4.1

package/src/index.ts

@@ -7,8 +7,19 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
+export { cliInvoke } from "./invoke.ts";
+export type { CliInvokeKind, CliInvokeResult } from "./invoke.ts";
 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,
+  CliInvocation,
+  CliMcpResource,
+  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, "mcp");
+
+  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/env.ts

@@ -0,0 +1,99 @@
+/*
+This module bootstraps process.env for MCP servers from login shell and .env files.
+*/
+
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+/** Parses `env` stdout from a login shell into a key/value map. */
+export function captureShellEnv(shell: string): Record<string, string> {
+  const result = spawnSync(shell, ["-l", "-c", "env"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  if (result.error || result.status !== 0) {
+    return {};
+  }
+  const env: Record<string, string> = {};
+  for (const line of result.stdout.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0) {
+      env[line.slice(0, eq)] = line.slice(eq + 1);
+    }
+  }
+  return env;
+}
+
+/** Merges captured shell env into process.env (PATH merged; host wins for other keys). */
+export function applyShellEnv(env: Record<string, string>): void {
+  for (const [key, val] of Object.entries(env)) {
+    if (key === "PATH") {
+      const existing = process.env.PATH ?? "";
+      const existingParts = new Set(existing.split(":"));
+      const shellOnly = val.split(":").filter((p) => p.length > 0 && !existingParts.has(p));
+      if (shellOnly.length > 0) {
+        process.env.PATH = [...shellOnly, existing].join(":");
+      }
+    } else if (process.env[key] === undefined) {
+      process.env[key] = val;
+    }
+  }
+}
+
+/** Loads a .env file into process.env (always overwrites). Warns on stderr if missing. */
+export function loadEnvFile(envFile: string): void {
+  const resolved = envFile.startsWith("~")
+    ? envFile.replace("~", process.env.HOME ?? "")
+    : envFile;
+  let text: string;
+  try {
+    text = readFileSync(resolved, "utf8");
+  } catch {
+    process.stderr.write(`[argsbarg] envFile not found: ${envFile}\n`);
+    return;
+  }
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq < 1) {
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    if (key) {
+      process.env[key] = val;
+    }
+  }
+}
+
+/** Applies mcpServer shellEnv and envFile bootstrap in order. */
+export function bootstrapMcpEnv(config: {
+  shellEnv?: boolean | string;
+  envFile?: string;
+}): void {
+  const shellEnvCfg = config.shellEnv;
+  if (shellEnvCfg) {
+    const shell =
+      typeof shellEnvCfg === "string"
+        ? shellEnvCfg
+        : (process.env.SHELL ?? (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash"));
+    const captured = captureShellEnv(shell);
+    if (Object.keys(captured).length === 0) {
+      process.stderr.write(`[argsbarg] shellEnv: failed to capture shell environment from ${shell}\n`);
+    } else {
+      applyShellEnv(captured);
+    }
+  }
+  if (config.envFile) {
+    loadEnvFile(config.envFile);
+  }
+}

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,238 @@
+/*
+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 { CliCommand } from "../types.ts";
+import { buildToolCallSuccess } from "./result.ts";
+import {
+  allMcpResources,
+  collectMcpTools,
+  mcpToolCallToArgv,
+  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 missingEnv = (tool.leaf.mcpTool?.requiresEnv ?? []).filter((k) => !process.env[k]);
+      if (missingEnv.length > 0) {
+        writeResponse({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [{ type: "text", text: `Missing required env: ${missingEnv.join(", ")}` }],
+            isError: true,
+          },
+        });
+        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 resources = allMcpResources(root).map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: r.mimeType,
+      }));
+      writeResponse({ jsonrpc: "2.0", id, result: { resources } });
+      return;
+    }
+
+    if (method === "resources/read") {
+      const uri = params.uri;
+      if (typeof uri !== "string") {
+        writeError(id, -32602, "Invalid params: uri required");
+        return;
+      }
+      const all = allMcpResources(root);
+      const found = all.find((r) => r.uri === uri);
+      if (!found) {
+        writeError(id, -32602, `Unknown resource: ${uri}`);
+        return;
+      }
+      let text: string;
+      try {
+        text = found.load();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeError(id, -32603, `Resource load failed: ${message}`);
+        return;
+      }
+      writeResponse({
+        jsonrpc: "2.0",
+        id,
+        result: {
+          contents: [
+            {
+              uri: found.uri,
+              mimeType: found.mimeType,
+              text,
+            },
+          ],
+        },
+      });
+      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);
+  }
+}