argsbarg 1.5.0 → 2.0.1

package/.cursor/plans/cliprogram_capabilities_refactor_081e1737.plan.md

@@ -0,0 +1,224 @@
+---
+name: CliProgram capabilities refactor
+overview: Introduce `CliNode` / `CliProgram` types and an internal capabilities resolver, replacing `CliCommand` in the public API as a **2.0.0 breaking change**. Keep capability machinery private to avoid locking in unstable internals.
+todos:
+  - id: types-split
+    content: "Refactor src/types.ts: CliNodeBase, CliLeaf, CliRouter, CliNode, CliProgram; remove CliCommand"
+    status: completed
+  - id: capabilities-module
+    content: Add internal src/capabilities.ts (resolveCapabilities, reservedCommandNames)
+    status: completed
+  - id: wire-validate-presentation
+    content: Update validate.ts, presentation.ts, export.ts, dispatch.ts, runtime.ts, invoke.ts to use CliProgram + caps
+    status: completed
+  - id: internal-walkers
+    content: Update parse, context, mcp/tools, completion scopes, install paths to CliNode/CliProgram as appropriate
+    status: completed
+  - id: public-api-2
+    content: Update index.ts exports (CliProgram only), run typegen, bump 2.0.0 CHANGELOG; verify qa-cli + idp-trees compile against local checkout
+    status: completed
+  - id: examples-docs
+    content: Migrate examples + README to CliProgram / satisfies pattern
+    status: completed
+  - id: tests-migrate
+    content: Migrate tests; keep runtime negative tests with cast helpers
+    status: completed
+  - id: nice-to-haves
+    content: "Optional: ctx.program getter, cliValidateProgram rename, satisfies examples, @ts-expect-error type tests"
+    status: completed
+isProject: false
+---
+
+# CliProgram + internal capabilities (2.0)
+
+## Goals
+
+- **Types**: `CliNode` (user tree) + `CliProgram` (what `cliRun` accepts) with root-only `mcpServer` / `install` only on `CliProgram`.
+- **Capabilities**: One internal resolver drives reserved names, help/schema/completion visibility, and dispatch guards.
+- **Exports**: Minimal public surface — no `resolveCapabilities`, no presentation helpers, no builtin command builders.
+- **Breaking**: Drop `CliCommand` from the public API — ship **2.0.0 directly** (Option B; no deprecated alias release).
+
+## Type model
+
+Add to [`src/types.ts`](src/types.ts):
+
+```typescript
+interface CliNodeBase { key; description; notes?; options? }
+
+type CliLeaf = CliNodeBase & { handler; positionals?; mcpTool? }
+type CliRouter = CliNodeBase & { commands: CliNode[]; fallbackCommand?; fallbackMode? }
+type CliNode = CliLeaf | CliRouter
+
+type CliProgram = CliNode & { mcpServer?; install? }
+```
+
+Remove `mcpServer`, `install`, `mcpTool` from a shared `CliCommandBase`. Remove the old `CliCommand` union entirely **inside the repo**.
+
+**Leaf program roots** (`examples/minimal.ts`) remain valid: `CliProgram` = leaf + root config.
+
+```mermaid
+flowchart TB
+  subgraph public [Public API]
+    CliProgram
+    cliRun["cliRun(program)"]
+    cliInvoke["cliInvoke(program, argv)"]
+  end
+  subgraph internal [Internal only]
+    resolveCaps["resolveCapabilities(program)"]
+    presentation["presentationRoot(program)"]
+    dispatch["dispatchBuiltin(...)"]
+  end
+  CliProgram --> cliRun
+  CliProgram --> resolveCaps
+  resolveCaps --> presentation
+  resolveCaps --> dispatch
+  presentation --> help["help / schema / completions"]
+```
+
+## Export policy (intentionally narrow)
+
+### Export from [`src/index.ts`](src/index.ts) only
+
+| Symbol | Action |
+|--------|--------|
+| `CliProgram` | **Add** — primary schema type |
+| `CliCommand` | **Remove** — breaking |
+| `CliNode`, `CliLeaf`, `CliRouter` | **Do not export** — authors use `satisfies CliProgram` or `typeof program.commands[n]` |
+| `CliOption`, `CliPositional`, config types | unchanged |
+| `cliRun`, `cliInvoke`, `CliContext`, enums | unchanged signatures, `CliProgram` param |
+
+Run `just typegen` so [`index.d.ts`](index.d.ts) reflects only the barrel.
+
+### Keep internal (not in barrel, no deep `package.json` exports)
+
+- [`src/capabilities.ts`](src/capabilities.ts) (new): `resolveCapabilities`, `reservedCommandNames`
+- [`src/builtins/presentation.ts`](src/builtins/presentation.ts), [`export.ts`](src/builtins/export.ts), [`dispatch.ts`](src/builtins/dispatch.ts)
+- Completion emitters, install module, `setCompiledExecutableOverride`
+- [`src/completion.ts`](src/completion.ts) shim — trim re-exports if any leak toward public paths; tests import from `builtins/` or `completion.ts` directly in-repo only
+
+**Rule**: If it decides *when* a builtin appears, it stays internal. Consumers only see the resulting CLI behavior.
+
+## Internal capabilities module
+
+New [`src/capabilities.ts`](src/capabilities.ts):
+
+```typescript
+interface CliCapabilities {
+  completion: true;
+  mcp: boolean;      // !!program.mcpServer
+  install: boolean;  // isCompiledExecutable() && program.install?.enabled !== false
+}
+
+function resolveCapabilities(program: CliProgram): CliCapabilities
+function reservedCommandNames(caps: CliCapabilities): string[]
+```
+
+Wire callers to use this instead of re-deriving:
+
+| File | Change |
+|------|--------|
+| [`src/validate.ts`](src/validate.ts) | `cliValidateProgram(program)`; reserved names from `caps`; **keep** runtime root-only checks for untyped/JS abuse |
+| [`src/builtins/presentation.ts`](src/builtins/presentation.ts) | `presentationBuiltins(program, caps)` |
+| [`src/builtins/export.ts`](src/builtins/export.ts) | same |
+| [`src/builtins/dispatch.ts`](src/builtins/dispatch.ts) | derive `caps` once from `program` |
+| [`src/runtime.ts`](src/runtime.ts) | `cliRun(program: CliProgram)` |
+
+Walkers (`parse`, `mcp/tools`, completion scopes) take `CliNode` where they recurse; entrypoints take `CliProgram`.
+
+**Presentation vs user tree**: Help, `--schema`, and completion emitters consume `cliPresentationRoot(program)` (synthetic router with builtin stubs), not raw `CliProgram`. Capability logic decides what gets injected; emitters keep walking the same presentation shape.
+
+**Validate edge cases** (keep at runtime even when TS catches most mistakes):
+
+- `mcpServer` / `install` on inner nodes — reject (untyped/JS abuse)
+- `mcpTool` on program root (leaf-shaped `CliProgram`) — reject (same as today)
+- Reserved command names from `reservedCommandNames(caps)` — drop the old `cliPresentationRoot` escape hatch that skips injection when user already declared `completion`
+
+## Context typing
+
+[`src/context.ts`](src/context.ts):
+
+- Change `ctx.schema` type to `CliProgram` (field name unchanged — avoids extra public surface).
+- **Nice-to-have**: add `get program(): CliProgram` alias returning `this.schema` with JSDoc pointing to `schema` for familiarity. Do **not** export a new type for this.
+
+## Consumer migration (2.0)
+
+### Before/after (representative of qa-cli, idp-trees, and all `: CliCommand`-typed consumers)
+
+```typescript
+// Before (1.x)
+import { cliRun, type CliCommand, CliOptionKind, CliFallbackMode } from "argsbarg";
+const cli: CliCommand = { key: 'myapp', commands: [...], mcpServer: {...} };
+await cliRun(cli);
+
+// After (2.0)
+import { cliRun, type CliProgram, CliOptionKind, CliFallbackMode } from "argsbarg";
+const cli = { key: 'myapp', commands: [...], mcpServer: {...} } satisfies CliProgram;
+await cliRun(cli);
+```
+
+No structural change for well-formed apps — only import + type annotation. `: CliProgram` also works if the consumer prefers explicit annotation over `satisfies`. Both patterns are supported and type-check identically.
+
+### Consumer impact (verified)
+
+| Consumer | Files importing argsbarg | Uses `CliCommand`? | Uses `mcpServer`/`install`? | Migration cost |
+|---|---|---|---|---|
+| qa-cli | 3 (`index.tsx`, `mcpConfig.ts`, `mcp.ts`) | `const cli: CliCommand` | `mcpServer` on root | Replace `CliCommand` → `CliProgram` in 1 import, 1 annotation |
+| idp-trees | 3 (`index.tsx`, `mcp/config.ts`, `headless/mode.ts`) | `const cli: CliCommand` | `mcpServer` on root | Replace `CliCommand` → `CliProgram` in 1 import, 1 annotation |
+
+Both consumers only use `CliCommand` for the root schema annotation. Neither imports `CliNode`/`CliLeaf`/`CliRouter` (they can't — they don't exist yet). Neither has deeply nested command trees (max depth 2). All other imported types (`CliOptionKind`, `CliFallbackMode`, `CliMcpServerConfig`, `CliMcpToolConfig`, `CliInvocation`, `CliContext`, `isInteractiveTty`) remain unchanged — those files need zero changes.
+
+### `install` builtin default behavior
+
+Both qa-cli and idp-trees rely on the `install` builtin being **enabled by default** (they do not set `install` on the root). The capabilities resolver must preserve this: `install: isCompiledExecutable() && program.install?.enabled !== false` — which defaults to enabled when `install` is absent.
+
+## Tests and negative cases
+
+- Update fixtures in [`src/index.test.ts`](src/index.test.ts), [`src/builtins/builtins.test.ts`](src/builtins/builtins.test.ts), [`src/install/install.test.ts`](src/install/install.test.ts): `CliProgram` / `CliNode` internally.
+- Runtime rejection tests (`mcpServer` on nested node) use `as unknown as CliProgram` or a small `invalidProgram()` helper — proves validate still catches misuse without TS.
+
+## Docs and changelog
+
+- [`README.md`](README.md): `CliProgram`, capabilities mental model (1 short paragraph), reserved names derived from config.
+- [`CHANGELOG.md`](CHANGELOG.md): **2.0.0** — `CliCommand` removed; `CliProgram` added; show before/after migration snippet. Include a note that structural schema shape is unchanged — only the type name and annotation pattern differ.
+- Optional short **Architecture** note in README (not a new doc file unless you want one).
+
+### 2.0.0 migration snippet (for CHANGELOG)
+
+```typescript
+// 1.x
+import { type CliCommand } from "argsbarg";
+const cli: CliCommand = { ... };
+// 2.0
+import { type CliProgram } from "argsbarg";
+const cli = { ... } satisfies CliProgram;  // or : CliProgram
+```
+
+## Version and release
+
+**2.0.0** — rename-only breaking change for typed consumers; runtime behavior unchanged.
+
+**Release path (chosen): Option B** — jump straight to 2.0.0. No `CliCommand` deprecated alias in 1.6. Breaking changes are acceptable; known consumers (qa-cli, idp-trees) migrate in one import + one annotation each.
+
+### Pre-release checklist (required before tag)
+
+1. `just test` green in argsbarg
+2. `just typegen` — `index.d.ts` exports `CliProgram` only (no `CliCommand`)
+3. Point qa-cli and idp-trees `package.json` at local argsbarg checkout; confirm `tsc` / build passes with `CliProgram` migration applied in those repos
+4. CHANGELOG 2.0.0 entry with migration snippet
+
+---
+
+## Nice-to-haves (defer if time-boxed)
+
+1. **`satisfies CliProgram`** in all examples (better DX than `: CliProgram` annotation). Verify that `satisfies` still infers precise sub-command types (not widening to `object`), particularly in nested structures like `examples/nested.ts`.
+2. **`ctx.program` getter** — alias for `ctx.schema`; document `schema` as legacy name in JSDoc only (no removal in 2.0).
+3. **Internal rename** `cliValidateRoot` → `cliValidateProgram` (not exported today; safe).
+4. **Type tests** in `src/types.test.ts` — compile-only assertions that invalid shapes fail (e.g. `mcpServer` on `CliNode`) using `@ts-expect-error` snippets.
+5. **README diagram** — small mermaid of user tree vs injected capabilities (documentation only).
+
+## Explicitly out of scope (avoid future breaks)
+
+- Exporting `CliCapabilities`, `resolveCapabilities`, `presentationRoot`, builtin command builders
+- Exporting `CliNode` / `CliLeaf` / `CliRouter` (can add in 2.x if demand appears; not needed for `nested.ts`-style apps)
+- `package.json` subpath exports (`argsbarg/builtins`, etc.)
+- Renaming `ctx.schema` in 2.0 (would break handlers that read `.schema`)

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-06-20
+
+### Removed
+
+- **`CliContext.schema`** — use `ctx.program` (removed alias; `program` is the only field).
+
+## [2.0.0] - 2026-06-20
+
+### Changed (breaking)
+
+- **`CliCommand` removed** — use `CliProgram` as the schema type passed to `cliRun` / `cliInvoke`. The runtime object shape is unchanged; only the type name and how you annotate it differ.
+
+```typescript
+// 1.x
+import { type CliCommand } from "argsbarg";
+const cli: CliCommand = { ... };
+// 2.0
+import { type CliProgram } from "argsbarg";
+const cli = { ... } satisfies CliProgram;  // or : CliProgram
+```
+
+- **Internal type split** — `CliNode` / `CliLeaf` / `CliRouter` model the user command tree; `CliProgram` adds root-only `mcpServer` and `install`. These are not exported from the public API.
+- **Capabilities resolver** — reserved built-in names (`completion`, `install`, `mcp`) are derived from program config and runtime (compiled binary), not from user-declared commands.
+
+### Added
+
+- **`ctx.program`** — alias for `ctx.schema` on `CliContext` (same `CliProgram` value).
+
 ## [1.5.0] - 2026-06-20
 
 ### Added
@@ -149,7 +177,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v2.0.1...HEAD
+[2.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.0.1
+[2.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.0.0
 [1.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.5.0
 [1.4.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.3
 [1.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.4.2

package/README.md

@@ -35,9 +35,9 @@ Shell completions! -->
 ## Usage
 
 ```typescript
-import { cliRun, CliCommand, CliOptionKind } from "argsbarg";
+import { cliRun, type CliProgram, CliOptionKind } from "argsbarg";
 
-const cli: CliCommand = {
+const cli = {
   key: "helloapp",
   description: "Tiny demo.",
   positionals: [
@@ -64,7 +64,7 @@ const cli: CliCommand = {
     }
     console.log(`hello ${name}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);
 ```
@@ -77,7 +77,7 @@ await cliRun(cli);
 
 Everything you need for a first-class CLI:
 
-- **Nested subcommands** (`CliCommand` with `commands` for groups, `handler` for leaves)
+- **Nested subcommands** (router nodes with `commands`, leaf nodes with `handler`)
 - **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`)
@@ -147,7 +147,7 @@ bun add bun-argsbarg
 
 ## How it works
 
-1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
+1. Build a **program root** with `satisfies CliProgram` (or `: CliProgram`): `key` is the app/binary name, `commands` are top-level subcommands, `options` are global flags. A router root must not set `handler` or declare `positionals` (validated at startup). A leaf root may set `handler` and `positionals` directly. Use `fallbackCommand` / `fallbackMode` on any **routing node** for default subcommand routing (not root-only).
 2. Call `await cliRun(root)` with that root — validates, parses argv, renders help or errors, invokes the leaf handler, and `process.exit`s with status **0** on success, **1** on implicit help or error (explicit `--help` → **0**).
 3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
 
@@ -181,7 +181,11 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 - `ctx.typedOpt<T>("custom", parseFn)` — pass a custom parsing function for type-safe option resolution.
 - `ctx.args` — positional words in order as `string[]`.
 - `ctx.positional("name")` — named positional lookup; varargs slots return `string[]`, single slots return `string | undefined`.
-- `ctx.schema` — merged program root (`CliCommand`) for contextual help.
+- `ctx.program` — program root (`CliProgram`) for contextual help.
+
+### Capabilities (built-ins)
+
+`completion`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, compiled binary + `install`). Reserved command names follow from that config: `completion` and `install` are always reserved; `mcp` is reserved when `mcpServer` is set.
 
 
 
@@ -192,7 +196,7 @@ Check the `examples/` directory for full working scripts:
 | Example | File | Shows |
 | --- | --- | --- |
 | `ArgsBargMinimal` | `examples/minimal.ts` | String + presence flags, `MissingOrUnknown` fallback. |
-| `ArgsBargNested` | `examples/nested.ts` | Nested `CliCommand` tree, positional tails, async handlers. |
+| `ArgsBargNested` | `examples/nested.ts` | Nested command tree, positional tails, async handlers. |
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -214,7 +218,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 
 | Symbol | Role |
 | --- | --- |
-| `CliCommand`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
+| `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
 | `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`, `ctx.invocation`, …). |

package/docs/install.md

@@ -75,10 +75,10 @@ If an existing entry differs, the command exits with an error unless `--yes` is
 ## Opt out
 
 ```typescript
-const cli: CliCommand = {
+const cli = {
   key: "myapp",
   description: "...",
   install: { enabled: false },
   // ...
-};
+} satisfies CliProgram;
 ```

package/docs/mcp.md

@@ -9,12 +9,12 @@ MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave e
 1. Add `mcpServer` to your program root:
 
 ```typescript
-const cli: CliCommand = {
+const cli = {
   key: "myapp",
   description: "My app.",
   mcpServer: { name: "myapp", version: "1.0.0" },
   commands: [/* ... */],
-};
+} satisfies CliProgram;
 ```
 
 `mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
@@ -62,7 +62,7 @@ Any host that spawns a subprocess and wires stdin/stdout works the same way: the
 
 ## Configuration
 
-Set `mcpServer` on the **program root only** (the `CliCommand` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
+Set `mcpServer` on the **program root only** (the `CliProgram` passed to `cliRun`). Validation rejects `mcpServer` on nested nodes.
 
 | Field | Default | Purpose |
 | --- | --- | --- |

package/examples/mcp-test.ts

@@ -3,11 +3,11 @@
 MCP test fixture for subprocess integration tests only.
 */
 
-import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
 const envFilePath = process.env.ARGS_TEST_ENV_FILE;
 
-const cli: CliCommand = {
+const cli = {
   key: "mcp-test",
   description: "MCP integration test fixture.",
   mcpServer: {
@@ -61,6 +61,6 @@ const cli: CliCommand = {
       },
     },
   ],
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/minimal.ts

@@ -7,9 +7,9 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, CliOptionKind } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "minimal.ts",
   description: "Tiny demo.",
   positionals: [
@@ -36,6 +36,6 @@ const cli: CliCommand = {
     }
     console.log(`hello ${name}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/nested.ts

@@ -7,9 +7,9 @@ and fallback commands fit together in one schema.
 It demonstrates how the schema scales beyond one command.
 */
 
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "nested.ts",
   description: "Nested groups demo.",
   mcpServer: { name: "nested-demo", version: "1.0.0" },
@@ -97,6 +97,6 @@ const cli: CliCommand = {
   ],
   fallbackCommand: "read",
   fallbackMode: CliFallbackMode.MissingOrUnknown,
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/examples/option-required.ts

@@ -7,9 +7,9 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
+import { cliRun, CliProgram, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
 
-const cli: CliCommand = {
+const cli = {
   key: "option-required.ts",
   description: "Demo of a required option.",
   options: [
@@ -42,6 +42,6 @@ const cli: CliCommand = {
     console.log(`requiredNonTty: ${requiredNonTty}`);
     console.log(`optional: ${optional}`);
   },
-};
+} satisfies CliProgram;
 
 await cliRun(cli);

package/index.d.ts

@@ -7,11 +7,11 @@ export declare class CliContext {
 	readonly appName: string;
 	readonly commandPath: string[];
 	readonly args: string[];
-	readonly schema: CliCommand;
+	readonly program: CliProgram;
 	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);
+	/** Captures the program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, program: CliProgram, 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. */
@@ -64,7 +64,7 @@ export declare enum CliFallbackMode {
 	UnknownOnly = "unknownOnly"
 }
 /**
- * A named flag or value option (`--long`, `-short`), listed on `CliCommand.options`.
+ * A named flag or value option (`--long`, `-short`), listed on command `options`.
  */
 export interface CliOption {
 	/** Option name (e.g., "name", "verbose"). */
@@ -84,7 +84,7 @@ export interface CliOption {
 	choices?: string[];
 }
 /**
- * An ordered positional argument slot, listed on `CliCommand.positionals`.
+ * An ordered positional argument slot, listed on leaf `positionals`.
  */
 export interface CliPositional {
 	/** Positional name (used in help and error messages). */
@@ -105,7 +105,7 @@ export interface CliPositional {
 	argMax?: number;
 }
 /**
- * Root-only. Enables `myapp mcp` and MCP stdio server metadata.
+ * Enables `myapp mcp` and MCP stdio server metadata (program root only).
  */
 export interface CliMcpServerConfig {
 	/** `initialize` serverInfo.name (default: root `key`). */
@@ -166,7 +166,7 @@ export interface CliMcpToolConfig {
 	requiresEnv?: string[];
 }
 /**
- * Root-only. Opt-out and defaults for the `install` built-in (compiled binaries only).
+ * Opt-out and defaults for the `install` built-in (compiled binaries only; program root only).
  */
 export interface CliInstallConfig {
 	/** When `false`, hide/disable `install` (default: enabled). */
@@ -175,9 +175,9 @@ export interface CliInstallConfig {
 	prefix?: string;
 }
 /**
- * Base properties shared by all command nodes.
+ * Base properties shared by all nodes in the user command tree.
  */
-export interface CliCommandBase {
+export interface CliNodeBase {
 	/** Program or command key (e.g., "myapp", "stat", "owner"). */
 	key: string;
 	/** Short description shown in help. */
@@ -186,49 +186,50 @@ 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;
-	/** Root-only. Opt-out and defaults for `install` (compiled binaries only). */
-	install?: CliInstallConfig;
-	/** Leaf-only. Per-tool MCP exposure and metadata. */
-	mcpTool?: CliMcpToolConfig;
 }
 /**
- * A command node: either a routing group (has commands) or a leaf (has handler).
- *
- * The value passed to cliRun is the program root: name is the app/binary name.
- * The root may be a routing group or a leaf command.
+ * A leaf command node with a handler and optional positionals.
  */
-export type CliCommand = (CliCommandBase & {
+export type CliLeaf = CliNodeBase & {
 	/** Handler function for leaf commands. */
 	handler: CliHandler;
 	/** Positional argument definitions. */
 	positionals?: CliPositional[];
-	/** Nested subcommands (empty for leaf commands). */
-	commands?: never;
-	/** Default subcommand (routing commands only). */
-	fallbackCommand?: never;
-	/** How fallbackCommand is applied at this routing node (routing commands only). */
-	fallbackMode?: never;
-}) | (CliCommandBase & {
+	/** Per-tool MCP exposure and metadata. */
+	mcpTool?: CliMcpToolConfig;
+};
+/**
+ * A routing command node with nested subcommands.
+ */
+export type CliRouter = CliNodeBase & {
 	/** Nested subcommands. */
-	commands: CliCommand[];
+	commands: CliNode[];
 	/** Default subcommand when argv omits a command or uses an unknown token at this routing node. */
 	fallbackCommand?: string;
-	/** How fallbackCommand is applied at this routing node (not root-only). */
+	/** How fallbackCommand is applied at this routing node. */
 	fallbackMode?: CliFallbackMode;
-	/** Handler function (leaf commands only). */
-	handler?: never;
-	/** Positional argument definitions (leaf commands only). */
-	positionals?: never;
-});
+};
+/**
+ * A node in the user-defined command tree (router or leaf).
+ */
+export type CliNode = CliLeaf | CliRouter;
+/**
+ * Program root passed to `cliRun` / `cliInvoke`.
+ * May be a leaf or router, plus optional program-level MCP and install config.
+ */
+export type CliProgram = CliNode & {
+	/** When set, enables the `mcp` built-in subcommand. */
+	mcpServer?: CliMcpServerConfig;
+	/** Opt-out and defaults for `install` (compiled binaries only). */
+	install?: CliInstallConfig;
+};
 /**
  * Handler closure type for leaf commands.
  * Supports both sync and async handlers.
  */
 export type CliHandler = (ctx: CliContext) => void | Promise<void>;
 /**
- * Error thrown when the static CliCommand tree violates ArgsBarg rules.
+ * Error thrown when the static CLI tree violates ArgsBarg rules.
  */
 export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
@@ -253,8 +254,8 @@ export interface CliInvokeResult {
  * Parses argv against the user root, runs the leaf handler, and returns captured output.
  * Never calls process.exit.
  */
-export declare function cliInvoke(root: CliCommand, argv: string[]): Promise<CliInvokeResult>;
-export declare function cliRun(root: CliCommand, argv?: string[]): Promise<never>;
+export declare function cliInvoke(root: CliProgram, argv: string[]): Promise<CliInvokeResult>;
+export declare function cliRun(program: CliProgram, argv?: string[]): Promise<never>;
 export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 /** True when stdin is a TTY. */
 export declare const isInteractiveTty: boolean;

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -4,10 +4,10 @@ import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliPresentationRoot } from "./presentation.ts";
 import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
 import { exportPresentationBuiltins } from "./export.ts";
-import { CliCommand } from "../types.ts";
+import { CliProgram } from "../types.ts";
 import { setCompiledExecutableOverride } from "../install/compiled.ts";
 
-const fixture: CliCommand = {
+const fixture: CliProgram = {
   key: "myapp",
   description: "Demo app.",
   mcpServer: { name: "myapp" },
@@ -38,7 +38,7 @@ describe("builtins help copy", () => {
 
   test("install omits --mcp option when mcpServer unset", () => {
     setCompiledExecutableOverride(true);
-    const noMcp: CliCommand = { key: "x", description: "x", handler: () => {} };
+    const noMcp: CliProgram = { key: "x", description: "x", handler: () => {} };
     const names = installBuiltinOptions(noMcp).map((o) => o.name);
     expect(names).not.toContain("mcp");
   });