argsbarg 1.3.1 → 1.4.1

package/README.md

@@ -10,9 +10,15 @@ Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dep
 
 Why another CLI parser?
 
-*Schema-first* -- define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
+*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface centralized, clear, and self-describing upfront.
 
-*Bun-optimized* -- built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
+*Beautiful `-h` screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+
+*Shell completions* — `completion bash` and `completion zsh` built-ins generate installable scripts from your schema so users get tab completion for commands, flags, and positionals without extra tooling.
+
+*Optional MCP server* — set `mcpServer: {}` on the program root to expose leaf commands as MCP tools and the full CLI tree as a schema resource (`myapp mcp` over stdio). See [docs/mcp.md](docs/mcp.md).
+
+*Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
@@ -72,7 +78,7 @@ await cliRun(cli);
 Everything you need for a first-class CLI:
 
 - **Nested subcommands** (`CliCommand` with `commands` for groups, `handler` for leaves)
-- **POSIX-style options** (`-x`, `--long`, `--long=value`)
+- **POSIX-style options** (`-x`, `--long`, `--long=value`) — kinds: presence, string, number, **enum** (`choices` array)
 - **Bundled presence flags** (`-abc`)
 - **Positional arguments and varargs tails** (`CliPositional` objects on `positionals`)
 - **Scoped help** at any routing depth (`-h` / `--help`)
@@ -90,11 +96,20 @@ Every app gets:
 - `-h` / `--help` at any routing depth (scoped help).
 - **`--schema`** at the program root — print the full command tree as JSON (for tooling and agents).
 - **`completion bash` / `completion zsh`** — print shell completion scripts to stdout (injected by `cliRun`).
+- **`mcp`** — when `mcpServer: {}` is set on the program root, run an MCP server over stdio (`myapp mcp`).
 
 Do not declare a top-level command named **`completion`** — it is reserved for this built-in.
+Do not declare a top-level command named **`mcp`** — it is reserved when MCP is enabled.
 Do not declare an option named **`schema`** — it is reserved for `--schema`.
 
 
+### MCP (AI agents)
+
+Opt in on the program root with `mcpServer: {}` (or `{ name, version, … }`), then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `argsbarg://schema`. Handlers can read `ctx.invocation` and use `cliInvoke` for headless testing.
+
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details.
+
+
 ### Shell completions
 
 ```bash
@@ -182,10 +197,11 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | Symbol | Role |
 | --- | --- |
 | `CliCommand`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
-| `CliOptionKind`, `CliFallbackMode` | Option kinds and root fallback behavior. |
+| `CliOptionKind`, `CliFallbackMode` | Option kinds (`Presence`, `String`, `Number`, `Enum`) and root fallback behavior. |
 | `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
-| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, …). |
+| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, `ctx.invocation`, …). |
 | `cliRun(root, [argv])` | Validate, parse argv, dispatch, exit. |
+| `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 
 Reserved identifier (validated at startup): root command **`completion`**.

package/docs/mcp.md

@@ -0,0 +1,300 @@
+# MCP server
+
+ArgsBarg can expose your CLI to AI agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Each **leaf command** becomes an MCP tool; the full command tree is available as a schema resource. The server speaks JSON-RPC over stdio — one JSON object per line on stdin and stdout.
+
+MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave exactly as before.
+
+## Quick start
+
+1. Add `mcpServer` to your program root:
+
+```typescript
+const cli: CliCommand = {
+  key: "myapp",
+  description: "My app.",
+  mcpServer: { name: "myapp", version: "1.0.0" },
+  commands: [/* ... */],
+};
+```
+
+`mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
+
+2. Run the MCP server:
+
+```bash
+myapp mcp
+```
+
+The process reads NDJSON requests from stdin and writes NDJSON responses to stdout. It stays alive until stdin closes.
+
+3. Point your MCP client at that command. See [Client setup](#client-setup).
+
+The `examples/nested.ts` demo enables MCP — try:
+
+```bash
+bun run examples/nested.ts mcp
+```
+
+## Client setup
+
+### Cursor
+
+Add a server entry under `mcpServers` in your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "myapp": {
+      "command": "bun",
+      "args": ["run", "myapp.ts", "mcp"]
+    }
+  }
+}
+```
+
+Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]` only.
+
+### Other MCP hosts
+
+Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** is the subcommand that starts the server.
+
+## Configuration
+
+Set `mcpServer` on the **program root only** (the `CliCommand` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `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:
+
+```typescript
+mcpServer: {
+  name: "nested-demo",
+  version: "1.0.0",
+  schemaResourceUri: "argsbarg://schema",
+}
+```
+
+## Tools
+
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `mcp`) are not exposed as tools.
+
+### Tool names
+
+Tool names are derived from the command path, with each segment sanitized (non-alphanumeric characters become `_`) and joined with `_`.
+
+| CLI invocation | Tool name |
+| --- | --- |
+| `myapp deploy` | `deploy` |
+| `myapp stat owner lookup` | `stat_owner_lookup` |
+| `nested.ts read` | `read` |
+
+### Tool descriptions
+
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash:
+
+| CLI path | MCP `description` |
+| --- | --- |
+| `stat owner lookup` | `stat owner lookup — Resolve owner info.` |
+| `read` | `read — Print the first line of each file.` |
+| (root leaf app) | `{root.key} — Tiny demo.` |
+
+### Per-leaf visibility
+
+Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/list` while keeping it in the CLI and in `--schema` output:
+
+```typescript
+{
+  key: "debug",
+  description: "Internal diagnostics.",
+  mcpTool: { enabled: false },
+  handler: () => { /* ... */ },
+}
+```
+
+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, 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`.
+
+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"`).
+
+Example for `nested.ts stat owner lookup`:
+
+```json
+{
+  "path": "/path/to/file",
+  "user-name": "alice",
+  "json": true
+}
+```
+
+This maps to argv: `stat owner lookup --json --user-name alice /path/to/file`.
+
+Tool arguments use **long option names** only (`user-name`, not `-u`). Short aliases from your schema are not accepted in MCP tool calls.
+
+### Tool results
+
+On success (`isError: false`):
+
+- **stdout** — first `content` text block with the handler’s captured stdout (raw, unchanged).
+- **stderr** — when non-empty, a second `content` text block with trimmed stderr (no prefix). The block’s position signals stderr; hosts may label it themselves.
+- **structuredContent** — when trimmed stdout is valid JSON, the parsed value is also returned per the [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools). Objects and arrays from flags like `--json` are the common case. JSON **primitives** (`true`, `42`, `"hello"`) are parsed too — a handler that prints the literal string `true` as human text would get `structuredContent: true`. Prefer objects for machine-readable output.
+
+On failure (parse error, validation error, non-zero exit, thrown error), the message is returned as text content with `isError: true`. Handler stderr is included when present.
+
+Help and `--schema` are not available through tool calls; use the schema resource or run the CLI directly for those.
+
+## Schema and custom resources
+
+The built-in resource `argsbarg://schema` (or `schemaResourceUri`) exposes your full CLI tree as JSON — the same output as `myapp --schema`.
+
+| Property | Value |
+| --- | --- |
+| Default URI | `argsbarg://schema` |
+| MIME type | `application/json` |
+| Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
+
+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
+
+- **Transport:** stdio, newline-delimited JSON (NDJSON).
+- **JSON-RPC:** version `2.0`.
+- **MCP protocol version:** `2024-11-05` (reported in `initialize`).
+
+### Supported methods
+
+| Method | Description |
+| --- | --- |
+| `initialize` | Returns capabilities (`tools`, `resources`) and `serverInfo`. |
+| `notifications/initialized` | Acknowledged; no response (notification). |
+| `ping` | Returns `{}`. |
+| `tools/list` | Lists all tools with `name`, `description`, `inputSchema`. |
+| `tools/call` | Runs a leaf handler; params: `name`, `arguments` (object). |
+| `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).
+
+### Manual smoke test
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bun run examples/nested.ts mcp
+```
+
+You should get one JSON line on stdout with `result.capabilities` and `result.serverInfo`.
+
+## Reserved names
+
+When MCP is enabled:
+
+- Do not declare a top-level command named **`mcp`** — it is reserved for the built-in subcommand.
+- Do not declare a top-level command named **`completion`** — reserved for shell completions.
+- Do not declare an option named **`schema`** — reserved for `--schema`.
+
+Running `myapp mcp` without `mcpServer` on the root fails with an error (exit 1).
+
+## Design notes
+
+- **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/examples/nested.ts

@@ -12,6 +12,7 @@ import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index
 const cli: CliCommand = {
   key: "nested.ts",
   description: "Nested groups demo.",
+  mcpServer: { name: "nested-demo", version: "1.0.0" },
   commands: [
     {
       key: "stat",

package/index.d.ts

@@ -1,7 +1,35 @@
 // 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;
+}
+/**
+ * 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,7 +37,9 @@ 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.
@@ -44,6 +74,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`.
@@ -66,6 +101,67 @@ export interface CliPositional {
 	 */
 	argMax?: number;
 }
+/**
+ * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ */
+export interface CliMcpServerConfig {
+	/** `initialize` serverInfo.name (default: root `key`). */
+	name?: string;
+	/** `initialize` serverInfo.version (default: see resolveMcpVersion). */
+	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.
+ */
+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.
  */
@@ -78,6 +174,10 @@ export interface CliCommandBase {
 	notes?: string;
 	/** Global or command-level flags/options. */
 	options?: CliOption[];
+	/** Root-only. When set, enables the `mcp` built-in subcommand. */
+	mcpServer?: CliMcpServerConfig;
+	/** Leaf-only. Per-tool MCP exposure and metadata. */
+	mcpTool?: CliMcpToolConfig;
 }
 /**
  * A command node: either a routing group (has commands) or a leaf (has handler).
@@ -120,29 +220,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.3.1",
+  "version": "1.4.1",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"