argsbarg 1.4.0 → 1.4.1

package/src/parse.ts

@@ -601,6 +601,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,6 +23,8 @@ 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",
 }
 
 /**
@@ -54,6 +61,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 +100,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 +141,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[];
 }
 
 /**

package/src/validate.ts

@@ -12,6 +12,7 @@ import {
   CliOptionKind,
   CliSchemaValidationError,
 } from "./types.ts";
+import { MCP_SCHEMA_URI_DEFAULT } from "./mcp/tools.ts";
 
 const reservedCommandNames = ["completion", "mcp"];
 
@@ -66,6 +67,19 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
     throw new CliSchemaValidationError("mcpTool is only supported on leaf commands");
   }
 
+  if (isRoot && cmd.mcpServer?.resources) {
+    const schemaUri = cmd.mcpServer.schemaResourceUri ?? MCP_SCHEMA_URI_DEFAULT;
+    const uris = cmd.mcpServer.resources.map((r) => r.uri);
+    if (uris.includes(schemaUri)) {
+      throw new CliSchemaValidationError(
+        `mcpServer.resources URI '${schemaUri}' conflicts with the built-in schema resource`,
+      );
+    }
+    if (new Set(uris).size !== uris.length) {
+      throw new CliSchemaValidationError("mcpServer.resources URIs must be unique");
+    }
+  }
+
   // Check for duplicate child names
   const seenNames = new Set<string>();
   for (const child of cmd.commands ?? []) {
@@ -103,6 +117,30 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
       }
       seenShorts.add(opt.shortName);
     }
+
+    if (opt.kind === CliOptionKind.Enum) {
+      if (!opt.choices || opt.choices.length === 0) {
+        throw new CliSchemaValidationError(
+          `Option '${opt.name}' on '${cmd.key}': Enum kind requires non-empty choices`,
+        );
+      }
+      if (new Set(opt.choices).size !== opt.choices.length) {
+        throw new CliSchemaValidationError(
+          `Option '${opt.name}' on '${cmd.key}': Enum choices must be distinct`,
+        );
+      }
+      for (const choice of opt.choices) {
+        if (choice.length === 0) {
+          throw new CliSchemaValidationError(
+            `Option '${opt.name}' on '${cmd.key}': Enum choices must be non-empty strings`,
+          );
+        }
+      }
+    } else if (opt.choices !== undefined) {
+      throw new CliSchemaValidationError(
+        `Option '${opt.name}' on '${cmd.key}': choices is only valid for Enum kind`,
+      );
+    }
   }
 
   // Validate positionals