argsbarg 2.1.1 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-06-20
+
+### Added
+
+- **`version` built-in** — `myapp version` prints `CliProgram.version` (always available; reserved command name).
+
+### Changed
+
+- **`CliProgram.version`** (required) — single source of truth for the `version` built-in and MCP `serverInfo.version`. Removed `mcpServer.version` and automatic `package.json` lookup.
+- **MCP opt-in** — `mcpServer: { enabled: true }` enables MCP; omit `mcpServer` to disable. Empty `mcpServer: {}` is rejected at validation.
+- **MCP identity from `key`** — removed `mcpServer.name`. MCP `serverInfo.name`, schema URI, and `mcp.json` entry keys use `sanitizeToolSegment(root.key)` (e.g. `nested.ts` → `nested_ts://schema`). Shell `command` stays the raw `key`.
+
 ## [2.1.1] - 2026-06-20
 
 ### Changed
@@ -186,7 +198,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - 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/v2.1.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.0.0
 [2.1.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.1.1
 [2.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.1.0
 [2.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v2.0.1

package/README.md

@@ -16,7 +16,7 @@ Why another CLI parser?
 
 *Shell completions* — `completion bash`, `completion zsh`, and `completion fish` 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). Compiled binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
+*Optional MCP server* — set `mcpServer: { enabled: true }` 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). Compiled binaries can install binary, completions, skills, and MCP config with `myapp install` — see [docs/install.md](docs/install.md).
 
 *Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
 
@@ -39,6 +39,7 @@ import { cliRun, type CliProgram, CliOptionKind } from "argsbarg";
 
 const cli = {
   key: "helloapp",
+  version: "1.0.0",
   description: "Tiny demo.",
   positionals: [
     {
@@ -96,17 +97,18 @@ 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` / `completion fish`** — print shell completion scripts to stdout (injected by `cliRun`).
-- **`mcp`** — when `mcpServer` is set on the program root, run as an MCP stdio server (`myapp mcp`).
+- **`version`** — print `CliProgram.version` (`myapp version`).
+- **`mcp`** — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
 - **`install`** — install the binary, completions, skills, and MCP config to the user environment (`myapp install --all --yes`). See [docs/install.md](docs/install.md).
 
-Do not declare a top-level command named **`completion`** or **`install`** — they are reserved.
-When **`mcpServer`** is set, do not declare a top-level command named **`mcp`** — it is reserved for the MCP built-in.
+Do not declare a top-level command named **`completion`**, **`version`**, or **`install`** — they are reserved.
+When **`mcpServer.enabled`** is `true`, do not declare a top-level command named **`mcp`** — it is reserved for the MCP built-in.
 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.
+Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp --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.
 
@@ -185,7 +187,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Capabilities (built-ins)
 
-`completion`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`). Reserved command names follow from that config: `completion` and `install` are always reserved unless `install.enabled: false`; `mcp` is reserved when `mcpServer` is set.
+`completion`, `version`, `install`, and `mcp` are not part of your schema — they are injected at runtime from program-level config (`mcpServer`, `install`). Reserved command names: `completion` and `version` always; `install` unless `install.enabled: false`; `mcp` when `mcpServer.enabled` is `true`.
 
 
 
@@ -226,7 +228,7 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 
-Reserved identifiers (validated at startup): root commands **`completion`**, **`install`**, and **`mcp`** (only when `mcpServer` is set).
+Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, and **`mcp`** (only when `mcpServer.enabled` is `true`).
 
 ---
 

package/docs/install.md

@@ -30,7 +30,7 @@ myapp install --uninstall --yes
 | Claude skill | `--skill` | `~/.claude/skills/<dir>/` when `~/.claude` exists |
 | MCP config | `--mcp` | `~/.cursor/mcp.json` and `~/.claude.json` when MCP is enabled |
 
-`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer` is set).
+`--all` expands to `--bin`, `--completions`, `--skill`, and `--mcp` (when `mcpServer.enabled` is `true`).
 
 Shells not on PATH are skipped silently (no warnings).
 
@@ -64,7 +64,7 @@ Environment:
 
 ## MCP merge behavior
 
-When `--mcp` runs, entries are merged into `mcpServers[<name>]` with:
+When `--mcp` runs, entries are merged into `mcpServers[<sanitized-key>]` with:
 
 ```json
 { "command": "<root.key>", "args": ["mcp"] }

package/docs/mcp.md

@@ -9,15 +9,18 @@ MCP is **opt-in**. Apps that do not set `mcpServer` on the program root behave e
 1. Add `mcpServer` to your program root:
 
 ```typescript
+import pkg from "../package.json" with { type: "json" };
+
 const cli = {
   key: "myapp",
+  version: pkg.version,
   description: "My app.",
-  mcpServer: { name: "myapp", version: "1.0.0" },
+  mcpServer: { enabled: true },
   commands: [/* ... */],
 } satisfies CliProgram;
 ```
 
-`mcpServer: {}` is enough to enable the server. Optional fields override defaults (see [Configuration](#configuration)).
+`mcpServer: { enabled: true }` opts in. Omit `mcpServer` entirely to disable MCP. Empty `mcpServer: {}` is rejected at validation.
 
 2. Run the MCP server:
 
@@ -66,26 +69,27 @@ Set `mcpServer` on the **program root only** (the `CliProgram` passed to `cliRun
 
 | 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 |
+| `enabled` | *(required)* | Must be `true` when `mcpServer` is set |
+| `schemaResourceUri` | `<sanitized root key>://schema` | URI for the built-in 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` |
+| `resources` | `[]` | Custom `CliMcpResource` entries (additive; schema resource is always included) |
+
+MCP `serverInfo.name` and the default schema URI use the sanitized program `key` (non-alphanumeric characters become `_`). Program `version` comes from `CliProgram.version` (also used by the `version` built-in).
 
-Example with all fields:
+Example with optional fields:
 
 ```typescript
 mcpServer: {
-  name: "nested-demo",
-  version: "1.0.0",
-  schemaResourceUri: "argsbarg://schema",
+  enabled: true,
+  shellEnv: true,
+  envFile: "~/.config/myapp/mcp.env",
 }
 ```
 
 ## Tools
 
-Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `ai`) are not exposed as tools.
+Every **user-defined leaf command** in your schema becomes one MCP tool. Built-ins (`completion`, `version`, `install`, `mcp`) are not exposed as tools.
 
 ### Tool names
 
@@ -172,11 +176,11 @@ Help and `--schema` are not available through tool calls; use the schema resourc
 
 ## 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`.
+The built-in schema resource (default URI `<sanitized-key>://schema`, e.g. `nested.ts` → `nested_ts://schema`) exposes your full CLI tree as JSON — the same output as `myapp --schema`. Override with `schemaResourceUri` if needed.
 
 | Property | Value |
 | --- | --- |
-| Default URI | `argsbarg://schema` |
+| Default URI | `<sanitized root key>://schema` |
 | MIME type | `application/json` |
 | Contents | `cliSchemaJson(root)` — handlers omitted, built-ins excluded |
 
@@ -184,6 +188,7 @@ Add custom resources on the program root:
 
 ```typescript
 mcpServer: {
+  enabled: true,
   resources: [
     {
       uri: "myapp://config",

package/examples/mcp-test.ts

@@ -9,10 +9,10 @@ const envFilePath = process.env.ARGS_TEST_ENV_FILE;
 
 const cli = {
   key: "mcp-test",
+  version: "0.0.0-test",
   description: "MCP integration test fixture.",
   mcpServer: {
-    name: "mcp-test",
-    version: "0.0.0-test",
+    enabled: true,
     ...(envFilePath ? { envFile: envFilePath } : {}),
     resources: [
       {

package/examples/minimal.ts

@@ -7,10 +7,12 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind } from "../src/index.ts";
 
 const cli = {
   key: "minimal.ts",
+  version: pkg.version,
   description: "Tiny demo.",
   positionals: [
     {

package/examples/nested.ts

@@ -7,12 +7,14 @@ and fallback commands fit together in one schema.
 It demonstrates how the schema scales beyond one command.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
 const cli = {
   key: "nested.ts",
+  version: pkg.version,
   description: "Nested groups demo.",
-  mcpServer: { name: "nested-demo", version: "1.0.0" },
+  mcpServer: { enabled: true },
   commands: [
     {
       key: "stat",

package/examples/option-required.ts

@@ -7,10 +7,12 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
+import pkg from "../package.json" with { type: "json" };
 import { cliRun, CliProgram, CliOptionKind, CliFallbackMode, isInteractiveTty } from "../src/index.ts";
 
 const cli = {
   key: "option-required.ts",
+  version: pkg.version,
   description: "Demo of a required option.",
   options: [
     {

package/index.d.ts

@@ -106,13 +106,12 @@ export interface CliPositional {
 }
 /**
  * Enables `myapp mcp` and MCP stdio server metadata (program root only).
+ * Must include `enabled: true`; omit `mcpServer` entirely to disable MCP.
  */
 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"`). */
+	/** When `true`, enables the `mcp` built-in and MCP stdio server. */
+	enabled: boolean;
+	/** Resource URI for schema export (default: `<sanitized root key>://schema`). */
 	schemaResourceUri?: string;
 	/**
 	 * Capture the user's login shell environment at MCP server start and merge it
@@ -127,7 +126,7 @@ export interface CliMcpServerConfig {
 	 */
 	envFile?: string;
 	/**
-	 * Custom MCP resources exposed alongside the built-in argsbarg://schema resource.
+	 * Custom MCP resources exposed alongside the built-in schema resource.
 	 * URIs must be unique and must not equal schemaResourceUri.
 	 */
 	resources?: CliMcpResource[];
@@ -218,7 +217,9 @@ export type CliNode = CliLeaf | CliRouter;
  * 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. */
+	/** Program version (printed by the `version` built-in and MCP serverInfo). */
+	version: string;
+	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
 	/** Opt-out and defaults for `install`. */
 	install?: CliInstallConfig;

package/package.json

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

package/src/builtins/builtins.test.ts

@@ -8,8 +8,9 @@ import { CliProgram } from "../types.ts";
 
 const fixture: CliProgram = {
   key: "myapp",
+  version: "0.0.0",
   description: "Demo app.",
-  mcpServer: { name: "myapp" },
+  mcpServer: { enabled: true },
   commands: [
     {
       key: "hello",
@@ -31,7 +32,7 @@ describe("builtins help copy", () => {
   });
 
   test("install omits --mcp option when mcpServer unset", () => {
-    const noMcp: CliProgram = { key: "x", description: "x", handler: () => {} };
+    const noMcp: CliProgram = { key: "x", version: "0.0.0", description: "x", handler: () => {} };
     const names = installBuiltinOptions(noMcp).map((o) => o.name);
     expect(names).not.toContain("mcp");
   });
@@ -56,6 +57,10 @@ describe("presentation root", () => {
     const root = cliPresentationRoot(disabled);
     expect(root.commands?.map((c) => c.key)).not.toContain("install");
   });
+  test("includes version builtin", () => {
+    const root = cliPresentationRoot(fixture);
+    expect(root.commands?.map((c) => c.key)).toContain("version");
+  });
 });
 
 describe("completion emitters", () => {
@@ -75,7 +80,7 @@ describe("completion emitters", () => {
   });
 
   test("zsh script registers compdef", () => {
-    const schema = cliPresentationRoot({ key: "zapp", description: "z", handler: () => {} });
+    const schema = cliPresentationRoot({ key: "zapp", version: "0.0.0", description: "z", handler: () => {} });
     const zsh = completionZshScript(schema);
     expect(zsh).toContain("#compdef zapp");
     expect(zsh).toContain("compdef _zapp zapp");

package/src/builtins/dispatch.ts

@@ -6,6 +6,7 @@ import { completionFishScript } from "./completion-fish.ts";
 import { completionZshScript } from "./completion-zsh.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinVersionCommand } from "./version.ts";
 import { cliBuiltinCompletionGroup as completionGroup } from "./completion-group.ts";
 import { cliPresentationRoot } from "./presentation.ts";
 import { cliMcpServeStdio } from "../mcp.ts";
@@ -56,9 +57,18 @@ export async function dispatchBuiltin(
     return;
   }
 
+  if (pr.path[0] === "version") {
+    if (pr.path.length !== 1) {
+      process.stderr.write("Unknown subcommand: version " + pr.path.slice(1).join(" ") + "\n");
+      process.exit(1);
+    }
+    process.stdout.write(program.version + "\n");
+    process.exit(0);
+  }
+
   if (pr.path[0] === "mcp") {
     if (!caps.mcp) {
-      process.stderr.write("MCP is not enabled. Set mcpServer on the program root.\n");
+      process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
       process.exit(1);
     }
     if (pr.path.length !== 1) {
@@ -127,5 +137,16 @@ export function builtinInterceptRoot(
     };
   }
 
+  if (first === "version") {
+    return {
+      parseRoot: {
+        key: program.key,
+        description: program.description,
+        commands: [cliBuiltinVersionCommand()],
+      },
+      isLeafCompletionIntercept: false,
+    };
+  }
+
   return { parseRoot: program, isLeafCompletionIntercept: false };
 }

package/src/builtins/export.ts

@@ -3,6 +3,7 @@ import type { CliFallbackMode, CliOption, CliPositional, CliProgram } from "../t
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinVersionCommand } from "./version.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -42,7 +43,10 @@ function exportBuiltinNode(cmd: {
 /** Built-in subtrees matching help visibility for `--schema` export. */
 export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
-  const builtins: CliSchemaExport[] = [exportBuiltinNode(cliBuiltinCompletionGroup(program.key))];
+  const builtins: CliSchemaExport[] = [
+    exportBuiltinNode(cliBuiltinCompletionGroup(program.key)),
+    exportBuiltinNode(cliBuiltinVersionCommand()),
+  ];
   if (resolved.install) {
     builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program)));
   }

package/src/builtins/install.ts

@@ -1,3 +1,4 @@
+import { resolveCapabilities } from "../capabilities.ts";
 import { CliProgram, CliOption, CliOptionKind, type CliLeaf } from "../types.ts";
 
 /** Install command options (dynamic: `--mcp` only when MCP is enabled). */
@@ -66,7 +67,7 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
   ];
 
-  if (root.mcpServer !== undefined) {
+  if (resolveCapabilities(root).mcp) {
     opts.splice(4, 0, {
       name: "mcp",
       description: "Add or update MCP server entries in Cursor and Claude config files.",

package/src/builtins/presentation.ts

@@ -5,10 +5,14 @@ import { isCliLeaf, isCliRouter } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
+import { cliBuiltinVersionCommand } from "./version.ts";
 
 /** Built-in command nodes injected for help, schema, and completions. */
 export function presentationBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
-  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program.key)];
+  const builtins: CliNode[] = [
+    cliBuiltinCompletionGroup(program.key),
+    cliBuiltinVersionCommand(),
+  ];
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }

package/src/builtins/version.ts

@@ -0,0 +1,10 @@
+import { type CliLeaf } from "../types.ts";
+
+/** Top-level `version` built-in (leaf). */
+export function cliBuiltinVersionCommand(): CliLeaf {
+  return {
+    key: "version",
+    description: "Print the program version.",
+    handler: () => {},
+  };
+}

package/src/capabilities.ts

@@ -16,14 +16,14 @@ export interface CliCapabilities {
 export function resolveCapabilities(program: CliProgram): CliCapabilities {
   return {
     completion: true,
-    mcp: program.mcpServer !== undefined,
+    mcp: program.mcpServer?.enabled === true,
     install: program.install?.enabled !== false,
   };
 }
 
 /** Reserved top-level command names for the given capabilities. */
 export function reservedCommandNames(caps: CliCapabilities): string[] {
-  const names = ["completion"];
+  const names = ["completion", "version"];
   if (caps.install) {
     names.push("install");
   }