argsbarg 3.6.0 → 3.6.2

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.2] - 2026-06-23
+
+### Added
+
+- **`cli-program.md`** — “Read flags once, resolve once” pattern for multi-surface leaves (`read*Flags` + `resolve*Input`).
+
+## [3.6.1] - 2026-06-23
+
+### Fixed
+
+- **npm package** — `package.json` `files` whitelist so publish no longer ships `.cursor/`, `.private/`, `.github/`, or other dev-only paths (npm does not honor `.gitignore`).
+
 ## [3.6.0] - 2026-06-23
 
 ### Added
@@ -387,7 +399,9 @@ 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/v3.6.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.2...HEAD
+[3.6.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.2
+[3.6.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.1
 [3.6.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.0
 [3.5.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.5.0
 [3.4.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.2

package/docs/cli-program.md

@@ -195,6 +195,59 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 
 Cross-field rules (e.g. `--match-remote` requires `--branch`) stay in consumer `resolve*` layers — argsbarg does not validate those.
 
+## Read flags once, resolve once
+
+For apps with **Ink + headless + MCP** (multiple surfaces per leaf), avoid scattering `ctx.hasFlag` / `ctx.stringOpt` through the handler. Use two layers:
+
+| Layer | Responsibility |
+| --- | --- |
+| **`read*Flags(ctx)`** | Read coerced values from `ctx` (`readLeafInputs()`, `durationOpt`, `commaListOpt`, shared mutator flags) into one typed struct |
+| **`resolve*Input(flags)`** | Cross-field validation and defaults; returns `{ ok, input }` or `{ ok: false, error }` |
+
+The handler calls **`read*Flags` once**, passes the struct to **`resolve*Input`**, then branches to Ink, headless, or MCP with the same resolved input.
+
+**Shared reads** — when many leaves share options (`yes`, `dry-run`, `json`), one app-level helper (e.g. `readMutatingFlags(ctx)`) plus per-command extensions:
+
+```typescript
+// cli/flags.ts
+export function readMutatingFlags(ctx: CliContext) {
+  const dryRun = ctx.hasFlag("dry-run");
+  return {
+    dryRun,
+    yes: ctx.hasFlag("yes"),
+    explicitJson: wantsExplicitJson(ctx, ctx.hasFlag("json")),
+  };
+}
+
+// commands/reset/resolve.ts
+export function readResetFlags(ctx: CliContext) {
+  return {
+    ...readMutatingFlags(ctx),
+    env: ctx.args[0],
+    force: ctx.hasFlag("force"),
+    services: ctx.commaListOpt("services"),
+  };
+}
+
+export function resolveResetInput(flags: ReturnType<typeof readResetFlags>) {
+  if (!flags.env) return { ok: false, error: "…" };
+  return { ok: true, input: { env: flags.env, force: flags.force, services: flags.services } };
+}
+
+// command handler
+handler: async (ctx) => {
+  const flags = readResetFlags(ctx);
+  await dispatchMutatingCommand({
+    dryRun: flags.dryRun,
+    headless: shouldRunHeadlessWithYes(ctx, { yes: flags.yes, hasRequiredArgs: !!flags.env, dryRun: flags.dryRun }),
+    resolve: () => resolveResetInput(flags),
+    /* … */
+  });
+};
+```
+
+**JSON-only CLIs** — a single `readCommandOptions(ctx)` wrapping `readLeafInputs()` per shared option set is usually enough; full `resolve*` layering is optional.
+
 ## Headless-capable handlers
 
 Simple leaves (read args, print stdout) are already headless — no extra work. **Any handler that might mount Ink, prompt, or open a browser should also implement a scriptable fast path** for:

package/docs/templates/cursor/rules/cli-program.mdc

@@ -19,5 +19,6 @@ When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 - Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
 - String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
 - Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
+- Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
 
 **App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "type": "module",
   "engines": {
     "bun": ">=1.3"
@@ -20,6 +20,15 @@
       "default": "./src/index.ts"
     }
   },
+  "files": [
+    "src",
+    "index.d.ts",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
     "@types/bun": "^1.3.12",

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

@@ -1,224 +0,0 @@
----
-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/.cursor/plans/mcp_v1.1_polish_e9656029.plan.md

@@ -1,260 +0,0 @@
----
-name: MCP v1.1 polish
-overview: "Ship four agent-focused MCP improvements: richer tool descriptions with CLI paths, per-leaf `mcpEnabled` opt-out, stderr surfaced on successful tool calls, and `structuredContent` when handler stdout is valid JSON."
-todos:
-  - id: types-mcpEnabled
-    content: "Add mcpEnabled?: boolean to CliCommandBase; validate leaf-only in validate.ts"
-    status: completed
-  - id: tool-descriptions
-    content: Add mcpToolDescription(path, rootKey, description); enrich descriptions; filter mcpEnabled === false
-    status: completed
-  - id: result-builder
-    content: Create src/mcp/result.ts with buildToolCallSuccess (stderr blocks + JSON structuredContent)
-    status: completed
-  - id: server-wire
-    content: Wire buildToolCallSuccess into tools/call success path in server.ts
-    status: completed
-  - id: tests
-    content: Unit tests for description, mcpEnabled, result builder; subprocess tests for JSON structuredContent and stderr-on-success
-    status: completed
-  - id: docs-changelog
-    content: Update docs/mcp.md and CHANGELOG.md; run just typegen and just test
-    status: completed
-isProject: false
----
-
-# MCP follow-up improvements plan
-
-Four targeted enhancements to the existing opt-in MCP server. No new dependencies, no protocol transport changes, no public export of internals beyond the new `mcpEnabled` schema field.
-
-```mermaid
-flowchart LR
-  subgraph toolsList [tools/list]
-    Walk[collectMcpTools]
-    Desc["path + description"]
-    Filter[mcpEnabled filter]
-  end
-  subgraph toolCall [tools/call]
-    Invoke[cliInvoke]
-    Build[buildToolCallResult]
-    Resp["content + structuredContent?"]
-  end
-  Walk --> Filter --> Desc
-  Invoke --> Build --> Resp
-```
-
----
-
-## 1. CLI path in tool descriptions
-
-**Goal:** Agents see the human invocation path without reading the schema resource first.
-
-**Format:**
-
-| Path | Leaf description | MCP `description` |
-| --- | --- | --- |
-| `["stat","owner","lookup"]` | `Resolve owner info.` | `stat owner lookup — Resolve owner info.` |
-| `["read"]` | `Print the first line…` | `read — Print the first line…` |
-| `[]` (root leaf app) | `Tiny demo.` | `{root.key} — Tiny demo.` |
-
-Use em dash (`—`) between path and description. Path segments are raw `key` values (not sanitized tool names). Every tool description uses the `prefix — description` form — there is no bare-description fallback.
-
-**Implementation:**
-
-- Add helper in [`src/mcp/tools.ts`](src/mcp/tools.ts). The helper **must** receive `rootKey` so root-leaf apps (empty path) can use the program name as the prefix:
-
-```typescript
-/** Builds MCP tool description: "{cli path} — {description}". */
-function mcpToolDescription(path: string[], rootKey: string, description: string): string {
-  const prefix = path.length > 0 ? path.join(" ") : rootKey;
-  return `${prefix} — ${description}`;
-}
-```
-
-- Call from `collectMcpTools` when building each `McpToolDef.description`:
-
-```typescript
-description: mcpToolDescription(path, root.key, cmd.description),
-```
-
-- `tools/list` already maps `t.description` — no server change needed.
-
-**Tests:** Update [`src/index.test.ts`](src/index.test.ts):
-
-- `stat_owner_lookup` description is `stat owner lookup — Resolve owner info.`
-- If testing a root-leaf fixture, description is `{root.key} — {description}`.
-
----
-
-## 2. Per-leaf opt-out via `mcpEnabled`
-
-**Goal:** Authors can keep CLI commands for humans while hiding them from MCP tool discovery.
-
-**Schema change** in [`src/types.ts`](src/types.ts):
-
-```typescript
-export interface CliCommandBase {
-  // ...existing fields...
-  /** Leaf-only. When `false`, omit this command from MCP tools (default: exposed). */
-  mcpEnabled?: boolean;
-}
-```
-
-**Semantics:**
-
-- Omitted or `true` → leaf is exposed (current behavior).
-- `false` → skipped in `collectMcpTools` walk.
-- Root `mcp?: CliMcpConfig` unchanged — it enables the server; `mcpEnabled` is unrelated.
-
-**Validation** in [`src/validate.ts`](src/validate.ts) `walkCommand`:
-
-- If `isRoot && cmd.mcpEnabled !== undefined` → throw `mcpEnabled is only supported on leaf commands`.
-- If routing node (has `commands`, no `handler`) and `mcpEnabled !== undefined` → same error.
-- No validation needed for `false` vs `true` beyond that.
-
-**Tool collection** in [`src/mcp/tools.ts`](src/mcp/tools.ts) `walk`:
-
-```typescript
-if ("handler" in cmd && cmd.handler) {
-  if (cmd.key === "completion" || cmd.key === "mcp") return;
-  if (cmd.mcpEnabled === false) return;
-  // push tool...
-}
-```
-
-**Schema export:** Leave [`src/schema.ts`](src/schema.ts) unchanged for v1 — `--schema` still lists all commands (CLI discovery). Only MCP `tools/list` respects `mcpEnabled`. Document this distinction in [`docs/mcp.md`](docs/mcp.md).
-
-**Example (optional):** Add a hidden leaf in `nestedMcpFixture` only (not `examples/nested.ts`) with `mcpEnabled: false` to prove filtering without cluttering the demo app.
-
----
-
-## 3. stderr on successful tool calls
-
-**Goal:** Warnings and diagnostic output on stderr are not silently dropped when `exitCode === 0`.
-
-**Current behavior** ([`src/mcp/server.ts`](src/mcp/server.ts) ~L133–141): success returns only `invokeResult.stdout`.
-
-**New behavior:** Extract a small builder (new file [`src/mcp/result.ts`](src/mcp/result.ts) recommended to keep server readable):
-
-```typescript
-export interface McpToolCallSuccess {
-  content: { type: "text"; text: string }[];
-  structuredContent?: unknown;
-  isError: false;
-}
-
-export function buildToolCallSuccess(stdout: string, stderr: string): McpToolCallSuccess
-```
-
-**stderr formatting rules:**
-
-- If `stderr.trim()` is empty → single `content` item with stdout (or empty string if stdout empty).
-- If stderr non-empty → **two** `content` items:
-  1. `{ type: "text", text: stdout }` (may be empty string)
-  2. `{ type: "text", text: stderr.trim() }` — **raw stderr text, no `stderr:` prefix**
-
-Use multiple content blocks rather than concatenating into one string so hosts can distinguish streams; the second block’s position in the array is the signal that it came from stderr. Some MCP hosts render content blocks with their own labeling — a literal `stderr:` prefix would leak into user-visible tool output. Existing failure path (~L144–151) already prefers stderr — leave as-is.
-
-**Tests:**
-
-- Unit test `buildToolCallSuccess` with stdout-only, stderr-only, both.
-- Subprocess test: add a fixture leaf (in test fixture or temporary nested command) that `console.warn`s on stderr but exits 0; assert two content blocks and `isError: false`.
-
----
-
-## 4. `structuredContent` when stdout is valid JSON
-
-**Goal:** When handlers emit JSON (e.g. `nested.ts` with `--json`), MCP clients get machine-readable output per [MCP tools spec](https://modelcontextprotocol.io/specification/draft/server/tools).
-
-**Parsing rules** (in `buildToolCallSuccess`):
-
-1. Let `trimmed = stdout.trim()`.
-2. If `trimmed.length === 0` → no `structuredContent`.
-3. Try `JSON.parse(trimmed)`.
-4. On success → set `structuredContent` to the parsed value (object, array, or primitive — all valid per 2025 spec).
-5. On `SyntaxError` → no `structuredContent` (plain text handlers unchanged).
-6. **Always** keep `content[0].text` as the raw stdout string when stdout is non-empty (spec: structured tools SHOULD also return serialized JSON in `content` — we already have the raw stdout which satisfies this for JSON handlers).
-
-**Primitive footgun (document, do not guard):** `JSON.parse("true")` yields `structuredContent: true`. A handler that intentionally prints the string `true` as human-readable output would get machine-typed output. This is spec-correct and rare in practice. Document in [`docs/mcp.md`](docs/mcp.md) rather than limiting to `typeof parsed === "object"` — that would reject valid JSON arrays and primitives that the 2025 spec explicitly allows.
-
-**Do not** auto-generate `outputSchema` in this release — that requires schema author input or inference and is out of scope.
-
-**Server wiring** in [`src/mcp/server.ts`](src/mcp/server.ts):
-
-```typescript
-const result = buildToolCallSuccess(invokeResult.stdout, invokeResult.stderr);
-writeResponse({ jsonrpc: "2.0", id, result });
-```
-
-Spread `structuredContent` onto result only when defined.
-
-**Tests:**
-
-- Unit: `buildToolCallSuccess('{"a":1}\n', '')` → `structuredContent: { a: 1 }`, content text preserved.
-- Unit: `buildToolCallSuccess('lookup user=x\n', '')` → no `structuredContent`.
-- Unit: `buildToolCallSuccess('true\n', '')` → `structuredContent: true` (documents primitive behavior).
-- Subprocess: extend existing `stat_owner_lookup` test or add parallel test with `json: true`:
-
-```typescript
-params: {
-  name: "stat_owner_lookup",
-  arguments: { path: readme, "user-name": "test", json: true },
-}
-```
-
-Assert `result.structuredContent` deep-equals `{ user: "test", path: readme }` and `content[0].text` is valid JSON string.
-
----
-
-## Documentation and changelog
-
-Update [`docs/mcp.md`](docs/mcp.md):
-
-- **Tool names** section: document new description format with example (including root-leaf `{root.key} — …` case).
-- **Per-leaf visibility**: `mcpEnabled: false` on leaves; note `--schema` still includes the command.
-- **Tool results**: stderr on success as a second raw-text content block (no prefix); `structuredContent` when stdout is valid JSON (including primitives — document footgun); link to MCP spec.
-- **Short flags**: one-line note that tool args use long option names only (unchanged, but good to document while editing).
-
-Update [`CHANGELOG.md`](CHANGELOG.md) under `[Unreleased]`:
-
-- Richer MCP tool descriptions with CLI paths.
-- `mcpEnabled` leaf opt-out.
-- MCP tool success responses include stderr when present.
-- MCP tool success responses include `structuredContent` for JSON stdout.
-
-Trim [`README.md`](README.md) MCP blurb only if needed — one line pointing to docs is enough.
-
----
-
-## Type declarations and release hygiene
-
-- Run `just typegen` after [`src/types.ts`](src/types.ts) change so [`index.d.ts`](index.d.ts) exports `mcpEnabled`.
-- Run `just test` (typecheck + lint + `bun test`).
-
-**Public API surface:** Only `mcpEnabled?: boolean` on `CliCommandBase` is new. `cliInvoke`, `buildToolCallSuccess`, and MCP runtime remain internal.
-
----
-
-## File change summary
-
-| File | Changes |
-| --- | --- |
-| [`src/types.ts`](src/types.ts) | Add `mcpEnabled?: boolean` with JSDoc |
-| [`src/validate.ts`](src/validate.ts) | Reject `mcpEnabled` on root and routing nodes |
-| [`src/mcp/tools.ts`](src/mcp/tools.ts) | `mcpToolDescription`, filter `mcpEnabled === false` |
-| [`src/mcp/result.ts`](src/mcp/result.ts) | **New** — `buildToolCallSuccess` |
-| [`src/mcp/server.ts`](src/mcp/server.ts) | Use builder for success path |
-| [`src/index.test.ts`](src/index.test.ts) | Unit + subprocess tests for all four features |
-| [`docs/mcp.md`](docs/mcp.md) | Document behavior |
-| [`CHANGELOG.md`](CHANGELOG.md) | Unreleased entries |
-| [`index.d.ts`](index.d.ts) | Regenerated via typegen |
-
----
-
-## Out of scope (explicitly deferred)
-
-- Tool list caching
-- `outputSchema` on tools
-- Hiding `mcpEnabled: false` commands from `--schema`
-- Group-level `mcpEnabled` inheritance
-- `mcp.json` / Cursor config changes