argsbarg 1.4.0 → 1.4.2

package/docs/mcp.md

@@ -67,6 +67,9 @@ Set `mcpServer` on the **program root only** (the `CliCommand` passed to `cliRun
 | `name` | root `key` | `serverInfo.name` in the `initialize` response |
 | `version` | `package.json` `version` in cwd, else `"0.0.0"` | `serverInfo.version` |
 | `schemaResourceUri` | `"argsbarg://schema"` | URI for the schema resource |
+| `shellEnv` | off | Capture login-shell `env` at startup (`true` uses `$SHELL`, or pass a shell path) |
+| `envFile` | off | Load a `.env` file after `shellEnv` (`~` supported); warns on stderr if missing |
+| `resources` | `[]` | Custom `CliMcpResource` entries for `resources/list` and `resources/read` |
 
 Example with all fields:
 
@@ -117,12 +120,25 @@ Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/l
 
 Omitted or `enabled: true` exposes the command (default). `mcpTool` is only valid on leaves — not on the program root or routing groups.
 
+### Per-leaf tool metadata
+
+```typescript
+mcpTool: {
+  enabled: true,
+  description: "Custom tools/list text (overrides auto-generated path + help).",
+  requiresEnv: ["API_TOKEN", "DATABASE_URL"],
+}
+```
+
+- **`description`** — when set, replaces the auto-generated `path — help` description entirely (no automatic `requiresEnv` suffix; mention vars in your text if needed).
+- **`requiresEnv`** — on auto-generated descriptions, appended as `[requires env: …]`. Enforced at `tools/call` time before the handler runs. Empty or unset env values count as missing.
+
 ### Tool arguments
 
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
-- **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string and number options match their `CliOptionKind`. Required options are listed in `required`.
-- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`.
+- **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. For varargs, agents may also pass a comma-separated string (`"a,b"`) or a single string (`"a"`) — both are coerced to separate argv tokens at dispatch time.
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
 
@@ -152,9 +168,9 @@ On failure (parse error, validation error, non-zero exit, thrown error), the mes
 
 Help and `--schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
 
-## Schema resource
+## Schema and custom resources
 
-The server advertises one MCP resource: your full CLI tree as JSON — the same output as `myapp --schema`.
+The built-in resource `argsbarg://schema` (or `schemaResourceUri`) exposes your full CLI tree as JSON — the same output as `myapp --schema`.
 
 | Property | Value |
 | --- | --- |
@@ -162,7 +178,79 @@ The server advertises one MCP resource: your full CLI tree as JSON — the same
 | MIME type | `application/json` |
 | Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
 
-Agents can read this resource to discover commands, options, and positionals without guessing tool shapes.
+Add custom resources on the program root:
+
+```typescript
+mcpServer: {
+  resources: [
+    {
+      uri: "myapp://config",
+      name: "config",
+      description: "Resolved app configuration.",
+      mimeType: "application/json",
+      load: () => JSON.stringify({ /* … */ }),
+    },
+  ],
+},
+```
+
+URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchronously at `resources/read` time.
+
+## Invocation context
+
+Handlers receive `ctx.invocation`: `"cli"` for normal `cliRun` dispatch, `"mcp"` for MCP `tools/call`.
+
+Use this to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
+
+```typescript
+handler: async (ctx) => {
+  const proc = Bun.spawn(["my-tool", ...ctx.args], {
+    stdout: ctx.invocation === "mcp" ? "pipe" : "inherit",
+    stderr: "inherit",
+  });
+  // capture proc.stdout when piping…
+};
+```
+
+`Bun.spawn({ stdout: "inherit" })` under MCP corrupts the wire. Prefer `"pipe"` and let argsbarg return captured handler stdout in the tool result.
+
+### `cliInvoke` (public API)
+
+`cliInvoke(root, argv)` runs a leaf handler without exiting the process — useful for tests and headless integrations. Returns `{ kind, exitCode, stdout, stderr }`. MCP tool dispatch uses this internally.
+
+**Note:** Tool output is buffered until the handler completes. Live streaming (e.g. `tail -f`) is not supported yet; see [Design notes](#design-notes).
+
+## Environment bootstrapping
+
+MCP hosts (e.g. Cursor) often spawn your server with a minimal environment — missing `PATH` entries for Homebrew, nvm, rbenv, etc.
+
+At server start (`cliMcpServeStdio`), before the NDJSON loop:
+
+| Order | Source | Behavior |
+| --- | --- | --- |
+| 1 | `shellEnv` | Spawns `$SHELL -l -c env`; merges into `process.env` |
+| 2 | `envFile` | Loads `.env`; **overwrites** keys from step 1 |
+
+**`shellEnv` merge rules:**
+
+- **`PATH`** — shell-only segments are **prepended** to the host `PATH` (always merged).
+- **Other vars** — set only when absent from the host environment (host wins).
+- On failure — one-line warning on **stderr**; server continues.
+
+**`envFile`:**
+
+- Supports `~` expansion.
+- Missing file — warning on stderr, server continues.
+- Keys from the file **always overwrite** `process.env`.
+
+Example:
+
+```typescript
+mcpServer: {
+  shellEnv: true,
+  envFile: "~/.config/myapp/mcp.env",
+},
+```
 
 ## Protocol
 
@@ -179,8 +267,8 @@ Agents can read this resource to discover commands, options, and positionals wit
 | `ping` | Returns `{}`. |
 | `tools/list` | Lists all tools with `name`, `description`, `inputSchema`. |
 | `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
-| `resources/list` | Lists the schema resource. |
-| `resources/read` | Returns schema JSON; params: `uri`. |
+| `resources/list` | Lists schema + custom resources. |
+| `resources/read` | Returns resource body; params: `uri`. |
 
 Requests without an `id` are treated as notifications and do not receive a response (except `notifications/initialized`, which is ignored after parsing).
 
@@ -207,5 +295,6 @@ Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1)
 - **Zero extra dependencies** — hand-rolled NDJSON JSON-RPC on top of ArgsBarg’s existing parser and schema.
 - **Same handlers** — tool calls run your real leaf handlers via an internal invoke path that captures stdout/stderr and does not exit the process, so the MCP server can handle many requests in one process.
 - **User schema only** — tool dispatch uses your program root, not merged presentation builtins.
+- **Buffered output** — MCP tool results are sent after the handler finishes. Incremental stdout (log tail, progress) is not streamed; a future release may add MCP progress notifications.
 
 For the `--schema` export used by the resource, see the main README built-ins section.

package/examples/mcp-test.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/*
+MCP test fixture for subprocess integration tests only.
+*/
+
+import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
+
+const envFilePath = process.env.ARGS_TEST_ENV_FILE;
+
+const cli: CliCommand = {
+  key: "mcp-test",
+  description: "MCP integration test fixture.",
+  mcpServer: {
+    name: "mcp-test",
+    version: "0.0.0-test",
+    ...(envFilePath ? { envFile: envFilePath } : {}),
+    resources: [
+      {
+        uri: "test://hello",
+        name: "hello",
+        description: "Test resource.",
+        mimeType: "text/plain",
+        load: () => "hello resource",
+      },
+    ],
+  },
+  commands: [
+    {
+      key: "echo-env",
+      description: "Echo an env var.",
+      mcpTool: {
+        requiresEnv: ["ARGS_TEST_SECRET"],
+      },
+      options: [
+        {
+          name: "name",
+          description: "Env var name to read.",
+          kind: CliOptionKind.String,
+          required: true,
+        },
+      ],
+      handler: (ctx) => {
+        const name = ctx.stringOpt("name") ?? "";
+        console.log(process.env[name] ?? "");
+      },
+    },
+    {
+      key: "set-mode",
+      description: "Set mode enum.",
+      options: [
+        {
+          name: "mode",
+          description: "Operating mode.",
+          kind: CliOptionKind.Enum,
+          choices: ["dev", "prod"],
+          required: true,
+        },
+      ],
+      handler: (ctx) => {
+        console.log(`mode=${ctx.stringOpt("mode")}`);
+      },
+    },
+  ],
+};
+
+await cliRun(cli);

package/index.d.ts

@@ -1,7 +1,39 @@
 // Generated by dts-bundle-generator v9.5.1
 
 /**
- * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
+ * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
+ */
+export declare class CliContext {
+	readonly appName: string;
+	readonly commandPath: string[];
+	readonly args: string[];
+	readonly schema: CliCommand;
+	readonly opts: Record<string, string>;
+	readonly invocation: CliInvocation;
+	/** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, schema: CliCommand, invocation?: CliInvocation);
+	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
+	hasFlag(name: string): boolean;
+	/** Returns the string value for a string-valued option, if present. */
+	stringOpt(name: string): string | undefined;
+	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
+	numberOpt(name: string): number | null;
+	/**
+	 * Generic typed accessor: parses a stored string using the provided parse function.
+	 * This is the TypeScript-native advantage over the Swift version.
+	 */
+	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+	positional(name: string): string | string[] | undefined;
+	private _posMap;
+	private _positionalMap;
+}
+/**
+ * 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 declare enum CliOptionKind {
 	/** Boolean flag: no value token (may be implicit `"1"` when set). */
@@ -9,24 +41,25 @@ export declare enum CliOptionKind {
 	/** Free-form string value. */
 	String = "string",
 	/** Strict floating-point value (parsed at validation time). */
-	Number = "number"
+	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 declare 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"
 }
@@ -44,6 +77,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[];
 }
 /**
  * An ordered positional argument slot, listed on `CliCommand.positionals`.
@@ -76,6 +114,38 @@ 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;
 }
 /**
  * Leaf-only. Controls how this command appears as an MCP tool.
@@ -83,6 +153,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[];
 }
 /**
  * Base properties shared by all command nodes.
@@ -114,16 +195,16 @@ export type CliCommand = (CliCommandBase & {
 	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;
@@ -142,29 +223,26 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
+/** 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;
+}
 /**
- * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
+ * Parses argv against the user root, runs the leaf handler, and returns captured output.
+ * Never calls process.exit.
  */
-export declare class CliContext {
-	readonly appName: string;
-	readonly commandPath: string[];
-	readonly args: string[];
-	readonly schema: CliCommand;
-	readonly opts: Record<string, string>;
-	/** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
-	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, schema: CliCommand);
-	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
-	hasFlag(name: string): boolean;
-	/** Returns the string value for a string-valued option, if present. */
-	stringOpt(name: string): string | undefined;
-	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
-	numberOpt(name: string): number | null;
-	/**
-	 * Generic typed accessor: parses a stored string using the provided parse function.
-	 * This is the TypeScript-native advantage over the Swift version.
-	 */
-	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
-}
+export declare function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult>;
 /**
  * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

package/src/completion.ts

@@ -8,7 +8,7 @@ It keeps completion aligned with the runtime schema so the generated commands,
 options, and descriptions stay in sync with the CLI definition.
 */
 
-import { CliCommand, CliOption } from "./types.ts";
+import { CliCommand, CliOption, CliOptionKind } from "./types.ts";
 
 // ── Shared Types ───────────────────────────────────────────────────────────────
 
@@ -216,6 +216,31 @@ function emitSimulate(ident: string): string {
   return o;
 }
 
+/** Emits bash helper to complete Enum option values when previous token is --name. */
+function emitEnumReplyBash(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=\"$1\" prev=\"$2\" cur=\"$3\"\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) {
+      continue;
+    }
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const words = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") COMPREPLY=( $(compgen -W '" + words + "' -- \"$cur\") ); return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
 /** Emits the main `COMPREPLY` driver and `complete -F` registration for bash. */
 function emitMainBodyBash(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
@@ -224,6 +249,7 @@ function emitMainBodyBash(schema: CliCommand, ident: string): string {
   o += "  local prev=\"${COMP_WORDS[COMP_CWORD-1]:-}\"\n";
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$prev\" \"$cur\"; then return; fi\n".replace("${ident}", ident);
   o += "  if [[ $cur == -* ]]; then\n";
   o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
   o += "    local -a optsarr\n";
@@ -289,6 +315,7 @@ export function completionBashScript(schema: CliCommand): string {
   out += emitConsumeShort(ident, scopes);
   out += emitMatchChild(ident, scopes, pathIndex);
   out += emitSimulate(ident);
+  out += emitEnumReplyBash(ident, scopes);
   out += emitMainBodyBash(schema, ident);
 
   return out;
@@ -470,6 +497,31 @@ function emitSimulateZsh(ident: string): string {
   return o;
 }
 
+/** Emits zsh helper to complete Enum option values when previous token is --name. */
+function emitEnumReplyZsh(ident: string, scopes: ScopeRec[]): string {
+  let o = "_${ident}_nac_enum_reply() {\n".replace("${ident}", ident);
+  o += "  local sid=$1 prev=$2\n";
+  o += "  case $sid in\n";
+  for (const [i, sc] of scopes.entries()) {
+    const enumOpts = sc.opts.filter((op) => op.kind === CliOptionKind.Enum && (op.choices?.length ?? 0) > 0);
+    if (enumOpts.length === 0) {
+      continue;
+    }
+    o += "    " + i + ")\n";
+    o += "      case $prev in\n";
+    for (const op of enumOpts) {
+      const vals = (op.choices ?? []).map((c) => escShellSingleQuoted(c)).join(" ");
+      o += "        --" + op.name + ") _values " + vals + "; return 0 ;;\n";
+    }
+    o += "      esac\n";
+    o += "      ;;\n";
+  }
+  o += "  esac\n";
+  o += "  return 1\n";
+  o += "}\n";
+  return o;
+}
+
 /** Zsh: `_main` completer and `compdef` registration. */
 function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   const main = mainName(schema.key);
@@ -477,6 +529,7 @@ function emitMainBodyZsh(schema: CliCommand, ident: string): string {
   o += "  local curcontext=\"$curcontext\" ret=1\n";
   o += "  _${ident}_nac_simulate\n".replace("${ident}", ident);
   o += "  local sid=$REPLY_SID\n";
+  o += "  if _${ident}_nac_enum_reply \"$sid\" \"$words[CURRENT-1]\"; then return 0; fi\n".replace("${ident}", ident);
   o += "  if [[ $PREFIX == -* ]]; then\n";
   o += "    local -a optsarr\n";
   o += "    local oname=\"A_${ident}_${sid}_opts\"\n".replace("${ident}", ident);
@@ -517,6 +570,7 @@ export function completionZshScript(schema: CliCommand): string {
   out += emitConsumeShortZsh(ident, scopes);
   out += emitMatchChildZsh(ident, scopes, pathIndex);
   out += emitSimulateZsh(ident);
+  out += emitEnumReplyZsh(ident, scopes);
   out += emitMainBodyZsh(schema, ident);
   return out;
 }

package/src/context.ts

@@ -7,7 +7,7 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
-import type { CliCommand } from "./types.ts";
+import type { CliCommand, CliInvocation } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
 /**
@@ -19,6 +19,7 @@ export class CliContext {
   readonly args: string[];
   readonly schema: CliCommand;
   readonly opts: Record<string, string>;
+  readonly invocation: CliInvocation;
 
   /** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
   constructor(
@@ -27,12 +28,14 @@ export class CliContext {
     args: string[],
     opts: Record<string, string>,
     schema: CliCommand,
+    invocation: CliInvocation = "cli",
   ) {
     this.appName = appName;
     this.commandPath = commandPath;
     this.args = args;
     this.opts = opts;
     this.schema = schema;
+    this.invocation = invocation;
   }
 
   /** Returns whether a presence flag was set (including implicit "1" for boolean options). */
@@ -65,4 +68,42 @@ export class CliContext {
       return null;
     }
   }
+
+  /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
+  positional(name: string): string | string[] | undefined {
+    return this._positionalMap()[name];
+  }
+
+  private _posMap: Record<string, string | string[]> | undefined;
+
+  private _positionalMap(): Record<string, string | string[]> {
+    if (this._posMap) return this._posMap;
+
+    let node: CliCommand = this.schema;
+    for (const seg of this.commandPath) {
+      const child = (node.commands ?? []).find((c) => c.key === seg);
+      if (!child) {
+        this._posMap = {};
+        return {};
+      }
+      node = child;
+    }
+
+    const map: Record<string, string | string[]> = {};
+    let argIdx = 0;
+    for (const p of node.positionals ?? []) {
+      const { argMax = 1 } = p;
+      if (argMax === 0) {
+        map[p.name] = this.args.slice(argIdx);
+        argIdx = this.args.length;
+      } else {
+        const val = this.args[argIdx];
+        if (val !== undefined) map[p.name] = val;
+        argIdx++;
+      }
+    }
+
+    this._posMap = map;
+    return map;
+  }
 }

package/src/help.ts

@@ -151,7 +151,7 @@ function wrapText(text: string, width: number): string[] {
 // ── Option Label Formatting ───────────────────────────────────────────────────
 
 /** Suffix for `--name` in usage (e.g. ` <string>`) based on value kind. */
-function optKindLabel(k: CliOptionKind): string {
+function optKindLabel(k: CliOptionKind, o?: CliOption): string {
   switch (k) {
     case CliOptionKind.Presence:
       return "";
@@ -159,12 +159,22 @@ function optKindLabel(k: CliOptionKind): string {
       return " <number>";
     case CliOptionKind.String:
       return " <string>";
+    case CliOptionKind.Enum: {
+      const choices = o?.choices ?? [];
+      if (choices.length === 0) {
+        return " <choice>";
+      }
+      if (choices.length <= 4) {
+        return " <" + choices.join("|") + ">";
+      }
+      return " <" + choices.slice(0, 3).join("|") + "|…>";
+    }
   }
 }
 
 /** Formats a flag/value option for help tables: `--name`, optional short, optional kind hint. */
 export function cliOptionLabel(o: CliOption, color: boolean): string {
-  let r = "--" + o.name + optKindLabel(o.kind);
+  let r = "--" + o.name + optKindLabel(o.kind, o);
   if (o.shortName) r += ", -" + o.shortName;
   if (!color) return r;