argsbarg 1.4.0 → 1.4.2

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, CliMcpServerConfig, CliMcpToolConfig, 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

@@ -108,7 +108,7 @@ export async function cliInvoke(root: CliCommand, argv: string[]): Promise<CliIn
   }
 
   const handler = current.handler;
-  const ctx = new CliContext(root.key, pr.path, pr.args, pr.opts, root);
+  const ctx = new CliContext(root.key, pr.path, pr.args, pr.opts, root, "mcp");
 
   let stdout = "";
   let stderr = "";

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/server.ts

@@ -4,13 +4,12 @@ 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 {
+  allMcpResources,
   collectMcpTools,
   mcpToolCallToArgv,
-  resolveMcpSchemaUri,
   resolveMcpServerInfo,
 } from "./tools.ts";
 
@@ -118,6 +117,18 @@ async function handleRequestLine(root: CliCommand, line: string): Promise<void>
         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({
@@ -152,21 +163,13 @@ async function handleRequestLine(root: CliCommand, line: string): Promise<void>
     }
 
     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",
-            },
-          ],
-        },
-      });
+      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;
     }
 
@@ -176,20 +179,29 @@ async function handleRequestLine(root: CliCommand, line: string): Promise<void>
         writeError(id, -32602, "Invalid params: uri required");
         return;
       }
-      const expected = resolveMcpSchemaUri(root);
-      if (uri !== expected) {
+      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: expected,
-              mimeType: "application/json",
-              text: cliSchemaJson(root).trimEnd(),
+              uri: found.uri,
+              mimeType: found.mimeType,
+              text,
             },
           ],
         },

package/src/mcp/tools.ts

@@ -6,6 +6,7 @@ flat JSON tool arguments into argv for cliInvoke.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { collectOptionDefs } from "../parse.ts";
+import { cliSchemaJson } from "../schema.ts";
 import { CliCommand, CliOption, CliOptionKind, CliPositional } from "../types.ts";
 
 /** Default URI for the CLI schema MCP resource. */
@@ -54,6 +55,8 @@ function optionProperty(opt: CliOption): Record<string, unknown> {
       return { type: "string", ...base };
     case CliOptionKind.Number:
       return { type: "number", ...base };
+    case CliOptionKind.Enum:
+      return { type: "string", enum: opt.choices, ...base };
   }
 }
 
@@ -98,6 +101,48 @@ function buildInputSchema(root: CliCommand, path: string[], leaf: CliCommand): R
   return schema;
 }
 
+/** Resolves MCP tool description with optional override and requiresEnv suffix. */
+function resolveToolDescription(root: CliCommand, path: string[], leaf: CliCommand): string {
+  if (leaf.mcpTool?.description) {
+    return leaf.mcpTool.description;
+  }
+  let desc = mcpToolDescription(path, root.key, leaf.description);
+  const env = leaf.mcpTool?.requiresEnv;
+  if (env && env.length > 0) {
+    desc += ` [requires env: ${env.join(", ")}]`;
+  }
+  return desc;
+}
+
+/** One resolved MCP resource (built-in or user-defined). */
+export interface McpResourceEntry {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType: string;
+  load: () => string;
+}
+
+/** Returns built-in schema resource plus user mcpServer.resources. */
+export function allMcpResources(root: CliCommand): McpResourceEntry[] {
+  const schemaUri = resolveMcpSchemaUri(root);
+  const builtIn: McpResourceEntry = {
+    uri: schemaUri,
+    name: "cli-schema",
+    description: "Full CLI command tree (same as --schema).",
+    mimeType: "application/json",
+    load: () => cliSchemaJson(root),
+  };
+  const user = (root.mcpServer?.resources ?? []).map((r) => ({
+    uri: r.uri,
+    name: r.name,
+    description: r.description,
+    mimeType: r.mimeType ?? "text/plain",
+    load: r.load,
+  }));
+  return [builtIn, ...user];
+}
+
 /** Recursively collects MCP tool definitions from user leaf commands. */
 export function collectMcpTools(root: CliCommand): McpToolDef[] {
   const out: McpToolDef[] = [];
@@ -113,7 +158,7 @@ export function collectMcpTools(root: CliCommand): McpToolDef[] {
       }
       out.push({
         name: mcpToolName(root, path),
-        description: mcpToolDescription(path, root.key, cmd.description),
+        description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
         inputSchema: buildInputSchema(root, path, cmd),
@@ -187,12 +232,20 @@ export function mcpToolCallToArgv(
     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));
+      const raw = args[p.name];
+      let items: string[];
+      if (Array.isArray(raw)) {
+        items = raw.map(String);
+      } else if (typeof raw === "string") {
+        items = raw.includes(",")
+          ? raw.split(",").map((s) => s.trim()).filter(Boolean)
+          : raw.trim()
+            ? [raw.trim()]
+            : [];
+      } else {
+        items = [];
       }
+      argv.push(...items);
       continue;
     }
 

package/src/mcp.ts

@@ -3,6 +3,7 @@ This module starts the ArgsBarg MCP stdio server for opt-in program roots.
 */
 
 import { mcpServeStdioLoop } from "./mcp/server.ts";
+import { bootstrapMcpEnv } from "./mcp/env.ts";
 import { CliCommand } from "./types.ts";
 
 /**
@@ -11,6 +12,9 @@ import { CliCommand } from "./types.ts";
  */
 export async function cliMcpServeStdio(root: CliCommand): Promise<never> {
   try {
+    if (root.mcpServer) {
+      bootstrapMcpEnv(root.mcpServer);
+    }
     await mcpServeStdioLoop(root);
     process.exit(0);
   } catch (err) {

package/src/parse.ts

@@ -231,11 +231,6 @@ export function collectOptionDefs(root: CliCommand, path: string[]): CliOption[]
   return defs;
 }
 
-/** True when every positional slot has bounded arity (no `argMax: 0` varargs tail). */
-function allowsTrailingOptions(positionals: CliCommand["positionals"]): boolean {
-  return (positionals ?? []).every((p) => (p.argMax ?? 1) !== 0);
-}
-
 /** Fills `args` for a leaf from `startIdx` according to `node.positionals`. */
 function finishLeaf(
   node: CliCommand,
@@ -244,7 +239,7 @@ function finishLeaf(
   path: string[],
   opts: Record<string, string>,
   optionDefs: CliOption[],
-  forcePositionals: boolean,
+  forcePositionalsIn: boolean,
 ): ParseResult {
   /** Builds a parse error for positional consumption failures. */
   function errorResult(msg: string): ParseResult {
@@ -263,6 +258,7 @@ function finishLeaf(
 
   let idx = startIdx;
   const args: string[] = [];
+  let forcePositionals = forcePositionalsIn;
 
   for (const p of node.positionals ?? []) {
     const { argMin = 1, argMax = 1 } = p;
@@ -288,9 +284,37 @@ function finishLeaf(
     let count = 0;
     if (argMax === 0) {
       while (idx < argv.length) {
-        args.push(argv[idx]);
-        idx += 1;
-        count += 1;
+        const tok = argv[idx];
+
+        if (!forcePositionals && tok === "--") {
+          forcePositionals = true;
+          idx++;
+          continue;
+        }
+
+        if (!forcePositionals && isHelpTok(tok)) {
+          return helpResult(path, true);
+        }
+
+        if (!forcePositionals && tok.startsWith("-")) {
+          // MUST be false — lenient mode swallows unknown flags as positionals silently
+          const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
+          if (tailRep.report.err) {
+            return errorResult(tailRep.report.err);
+          }
+          if (tailRep.report.sawDoubleDash) {
+            forcePositionals = true;
+          }
+          if (tailRep.nextIndex > idx) {
+            idx = tailRep.nextIndex;
+            continue;
+          }
+          return errorResult(`Unexpected option token: ${tok}`);
+        }
+
+        args.push(tok);
+        idx++;
+        count++;
       }
     } else {
       while (count < argMax && idx < argv.length) {
@@ -305,7 +329,7 @@ function finishLeaf(
   }
 
   if (idx < argv.length) {
-    if (forcePositionals || !allowsTrailingOptions(node.positionals)) {
+    if (forcePositionals) {
       return errorResult("Unexpected extra arguments");
     }
 
@@ -483,6 +507,19 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
 
     if (i >= argv.length) {
       if ((current.commands ?? []).length > 0) {
+        const fb = current.fallbackCommand;
+        const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+        if (
+          fb !== undefined &&
+          (fm === CliFallbackMode.MissingOnly || fm === CliFallbackMode.MissingOrUnknown)
+        ) {
+          const fbNode = findChild(current.commands ?? [], fb);
+          if (fbNode) {
+            path.push(fb);
+            current = fbNode;
+            continue;
+          }
+        }
         return helpResult(path, false);
       }
       return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
@@ -513,6 +550,21 @@ export function parse(root: CliCommand, argv: string[]): ParseResult {
     }
 
     if ((current.commands ?? []).length > 0) {
+      const fb = current.fallbackCommand;
+      const fm = current.fallbackMode ?? CliFallbackMode.MissingOnly;
+      const canRouteUnknown =
+        fb !== undefined &&
+        (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
+
+      if (canRouteUnknown) {
+        const fbNode = findChild(current.commands ?? [], fb!);
+        if (fbNode) {
+          path.push(fb!);
+          current = fbNode;
+          continue;
+        }
+      }
+
       return {
         kind: ParseKind.Error,
         path,
@@ -601,6 +653,21 @@ export function postParseValidate(root: CliCommand, pr: ParseResult): ParseResul
         };
       }
     }
+    if (d.kind === CliOptionKind.Enum) {
+      const choices = d.choices ?? [];
+      if (!choices.includes(v)) {
+        return {
+          kind: ParseKind.Error,
+          path: pr.path,
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Option --${k}: '${v}' is not one of: ${choices.join(", ")}`,
+          errorHelpPath: pr.path,
+        };
+      }
+    }
   }
 
   return pr;

package/src/runtime.ts

@@ -136,7 +136,7 @@ export async function cliRun(root: CliCommand, argv: string[] = process.argv.sli
     process.exit(1);
   }
 
-  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot);
+  const ctx = new CliContext(parseRoot.key, pr.path, pr.args, pr.opts, parseRoot, "cli");
   try {
     await Promise.resolve(current.handler(ctx));
     process.exit(0);

package/src/types.ts

@@ -9,7 +9,12 @@ It gives the package one shared model for both library users and internal module
 import type { CliContext } from "./context.ts";
 
 /**
- * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
+ * How a leaf handler was dispatched.
+ */
+export type CliInvocation = "cli" | "mcp";
+
+/**
+ * Option kinds: presence (boolean flag), string (free-form text), number (strict double), or enum (fixed choices).
  */
 export enum CliOptionKind {
   /** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -18,24 +23,25 @@ export enum CliOptionKind {
   String = "string",
   /** Strict floating-point value (parsed at validation time). */
   Number = "number",
+  /** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
+  Enum = "enum",
 }
 
 /**
- * When fallbackCommand is used for missing or unknown top-level tokens.
- * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
 export enum CliFallbackMode {
   /**
-   * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+   * If argv has no next subcommand, route to `fallbackCommand`; if the token is unknown, error.
    */
   MissingOnly = "missingOnly",
   /**
-   * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+   * If argv has no next subcommand or the token is not a known child, route to `fallbackCommand`.
    */
   MissingOrUnknown = "missingOrUnknown",
   /**
-   * If the first token is present but not a known child, route to `fallbackCommand`.
-   * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+   * If the next token is present but not a known child, route to `fallbackCommand`.
+   * When the subcommand token is missing (exhausted argv), do not use fallback (implicit scoped help).
    */
   UnknownOnly = "unknownOnly",
 }
@@ -54,6 +60,11 @@ export interface CliOption {
   shortName?: string;
   /** Whether this option must be provided. Cannot be used with Presence kind. */
   required?: boolean;
+  /**
+   * Allowed values. Required when kind === Enum; ignored otherwise.
+   * Must be a non-empty array of distinct non-empty strings.
+   */
+  choices?: string[];
 }
 
 /**
@@ -88,6 +99,39 @@ export interface CliMcpServerConfig {
   version?: string;
   /** Resource URI for schema export (default: `"argsbarg://schema"`). */
   schemaResourceUri?: string;
+  /**
+   * Capture the user's login shell environment at MCP server start and merge it
+   * into process.env. Solves missing PATH, nvm/rbenv shims, Homebrew binaries,
+   * and shell exports that MCP hosts (e.g. Cursor) don't inherit.
+   */
+  shellEnv?: boolean | string;
+  /**
+   * Path to a .env file loaded into process.env at MCP server start, after shellEnv.
+   * Supports `~` expansion. Warns on stderr if the file does not exist.
+   * Always overwrites — envFile is authoritative for its keys.
+   */
+  envFile?: string;
+  /**
+   * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+   * URIs must be unique and must not equal schemaResourceUri.
+   */
+  resources?: CliMcpResource[];
+}
+
+/**
+ * A custom MCP resource exposed under resources/list and resources/read.
+ */
+export interface CliMcpResource {
+  /** Resource URI (must be unique; must not equal schemaResourceUri). */
+  uri: string;
+  /** Short display name for resources/list. */
+  name: string;
+  /** Optional human description for resources/list. */
+  description?: string;
+  /** MIME type (default: "text/plain"). */
+  mimeType?: string;
+  /** Called at resources/read time; must return the resource body. */
+  load: () => string;
 }
 
 /**
@@ -96,6 +140,17 @@ export interface CliMcpServerConfig {
 export interface CliMcpToolConfig {
   /** When `false`, omit from `tools/list` (default: exposed). */
   enabled?: boolean;
+  /**
+   * Override the generated MCP tool description.
+   * Default: auto-generated from command path and description.
+   */
+  description?: string;
+  /**
+   * Environment variable names required at runtime.
+   * Appended to auto-generated MCP tool descriptions; enforced at tools/call time.
+   * Empty string counts as absent.
+   */
+  requiresEnv?: string[];
 }
 
 /**
@@ -130,17 +185,17 @@ export type CliCommand =
       positionals?: CliPositional[];
       /** Nested subcommands (empty for leaf commands). */
       commands?: never;
-      /** Default top-level subcommand (routing commands only). */
+      /** Default subcommand (routing commands only). */
       fallbackCommand?: never;
-      /** How fallbackCommand is applied (routing commands only). */
+      /** How fallbackCommand is applied at this routing node (routing commands only). */
       fallbackMode?: never;
     })
   | (CliCommandBase & {
       /** Nested subcommands. */
       commands: CliCommand[];
-      /** Default top-level subcommand when argv omits a command or uses an unknown first token. */
+      /** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
       fallbackCommand?: string;
-      /** How fallbackCommand is applied. */
+      /** How fallbackCommand is applied at this routing node (not root-only). */
       fallbackMode?: CliFallbackMode;
       /** Handler function (leaf commands only). */
       handler?: never;