argsbarg 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -7,14 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.3.0] - 2026-06-21
+## [3.3.1] - 2026-06-21
+
+### Added
+
+- **`docs/cli-program.md`** — authoring guide for `CliProgram` and leaves (MCP-free defaults); **headless-capable handlers** and **inline schema by default**.
+- **`docs/templates/cursor/rules/cli-program.mdc`** — concise copy-paste Cursor rule for consumer apps.
 
+### Removed
+
+- **`mcpToolSchemaHints`** — redundant with MCP `inputSchema` option descriptions.
+- **`wantsDryRun`** — use `ctx.hasFlag("dry-run")` instead.
 
-## [3.3.0] - 2026-06-20
+## [3.3.0] - 2026-06-21
 
 ### Added
 
-- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsDryRun`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
+- **Headless helpers** — `shouldRunHeadless`, `shouldRunHeadlessWithPositionals`, `shouldRunHeadlessWithYes`, `wantsExplicitJson`, `requireYesInNonTty`, `formatDryRunMessage` for Ink/MCP CLIs.
 - **`ghReleaseUpdateGetLatest`** — optional `install.updateGetLatest` factory for GitHub releases via `gh`.
 - **`createGhVersionCheck`** — version-check cache, update notices, and background refresh helpers.
 
@@ -234,8 +243,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/v3.3.0...HEAD
-[3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.3.1...HEAD
+[3.3.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.1
 [3.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.3.0
 [3.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.2.0
 [3.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.1.0

package/README.md

@@ -110,7 +110,7 @@ When **`docs.enabled`** is `true`, do not declare a top-level command named **`d
 
 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 docs 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.
+See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: copy **`docs/templates/cursor/rules/cli-program.mdc`** to **`.cursor/rules/cli-program.mdc`**).
 
 ### Install
 

package/docs/ai-skills.md

@@ -44,6 +44,8 @@ Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tool
 | **`myapp install --skill`** | Static shell command catalog for agents |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
+Command catalog lines reuse MCP tool descriptions. See [cli-program.md](cli-program.md).
+
 See also:
 
 - [Bundled docs](bundled-docs.md) — `docs` config and compile-time imports

package/docs/cli-program.md

@@ -0,0 +1,194 @@
+# Writing `CliProgram` and leaf commands
+
+ArgsBarg turns your schema into help, shell completions, MCP tools, and agent skills. **The same `description` fields you write for humans are the agent contract** for basic apps.
+
+## Minimal app (MCP is free)
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "One-line summary of what the CLI does.",
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "greet",
+      description: "Greet someone by name.",
+      positionals: [
+        { name: "name", description: "Who to greet.", kind: CliOptionKind.String },
+      ],
+      handler: async (ctx) => { /* ... */ },
+    },
+  ],
+} satisfies CliProgram;
+```
+
+No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` comes from options and positionals.
+
+## Inline schema by default
+
+ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.
+
+**Inline by default:**
+
+```typescript
+{
+  key: "reserve",
+  description: "Reserve a QA environment.",
+  options: [
+    { name: "yes", description: "Skip confirmation; use for non-interactive runs.", kind: CliOptionKind.Presence },
+    { name: "dry-run", description: "Preview without mutating.", kind: CliOptionKind.Presence },
+  ],
+  positionals: [
+    { name: "env", description: "Environment name.", kind: CliOptionKind.String, argMin: 0, argMax: 1 },
+  ],
+  handler: async (ctx) => { /* … */ },
+}
+```
+
+**Extract only when well justified:**
+
+| Extract | When |
+| --- | --- |
+| Shared option objects (`DRY_RUN_OPTION`, `JSON_OPTION`) | Identical flag reused on many leaves |
+| Shared spreads (`...MCP_TOOL_MUTATOR`) | Same `mcpTool` metadata on a family of commands |
+| `somethingCommand()` factory | Entry file is large; handler/body is substantial (Ink page, headless dispatch) |
+| `docs.topics` text imports | Compile-time markdown bundling — not schema shape |
+
+**Avoid extracting** thin indirection: a file that only re-exports `{ key, description, options }` with no logic, or splitting every leaf into its own module when the handler is a few lines. If extraction does not reduce duplication or file size materially, keep it inline.
+
+**`satisfies CliProgram`** on the root (or on extracted command factories) preserves type-checking whether inline or not.
+
+## Descriptions
+
+Write for **what the command does**, not how the UI works:
+
+- **Good:** `Reserve a QA environment.`
+- **Weak:** `Opens the reservation wizard.`
+
+Option and positional `description` strings appear in `-h`, MCP `inputSchema`, and generated skills — keep them concrete (`Environment name (e.g. qa2).`).
+
+Use root **`notes`** for cross-cutting hints shown in help (install commands, docs topics, VPN requirements).
+
+## Well-known option names
+
+Prefer **`yes`**, **`dry-run`**, and **`json`** when semantics match. They appear in `-h`, MCP `inputSchema`, and generated skills — write clear option `description` strings (e.g. "Skip confirmation; use for non-interactive runs.").
+
+## When to use `mcpTool` (escape hatches only)
+
+**Omit `mcpTool` unless you have a specific reason.**
+
+### Fix the CLI first
+
+Many "MCP problems" are schema or handler gaps. Prefer these over escape hatches:
+
+| Problem | Fix (not `mcpTool`) |
+| --- | --- |
+| Agents don't know which flags to pass | Use standard option names (`yes`, `dry-run`, `json`); improve option `description` strings |
+| MCP calls hang on prompts | Add `--yes` and a headless code path; use `shouldRunHeadlessWithYes` |
+| Help text describes Ink UI | Rewrite leaf `description` as the action ("Reserve an environment.") |
+| MCP needs different args than humans | Expose the same flags; resolve defaults in the handler for both `cli` and `mcp` |
+| Command "doesn't work" over MCP | Branch on `ctx.invocation === "mcp"` in the handler (stdio is the wire) |
+
+### When escape hatches are appropriate
+
+| Field | Use when |
+| --- | --- |
+| `enabled: false` | Command is **genuinely** CLI-only (open browser, Ink-only flow with no scriptable equivalent) |
+| `requiresEnv: [...]` | Runtime secrets; appended to MCP description and enforced at `tools/call` |
+| `description: "..."` | **Irreducible** MCP limitation (e.g. live tail / `--watch` cannot be streamed on the MCP wire yet) |
+
+Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard flag names, or handlers that only work interactively — fix those instead.
+
+If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
+
+## 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:
+
+- **MCP** (`ctx.invocation === "mcp"` — always non-interactive)
+- **Non-TTY CLI** (pipes, CI, `myapp cmd --yes` in a script)
+- **Explicit flags** (`--json`, `--dry-run`)
+
+Use **one headless implementation** for all three; do not fork separate "MCP handlers."
+
+### When to branch
+
+| Command kind | Headless trigger | Helpers |
+| --- | --- | --- |
+| Read / query | MCP, `--json`, or non-TTY | `shouldRunHeadless`, `wantsExplicitJson` |
+| Mutate | MCP with args + `yes`/`dry-run`, or non-TTY with `--yes` | `shouldRunHeadlessWithYes`, `requireYesInNonTty` |
+| Mutate with positionals | Same, but avoid auto-headless on empty argv | `shouldRunHeadlessWithPositionals` |
+
+### Recommended handler shape
+
+**Mutating command** (wizard optional, script path required):
+
+```typescript
+import {
+  requireYesInNonTty,
+  shouldRunHeadlessWithYes,
+} from "argsbarg";
+
+handler: async (ctx) => {
+  const dryRun = ctx.hasFlag("dry-run");
+  const yes = ctx.hasFlag("yes");
+  const env = ctx.args[0];
+
+  requireYesInNonTty(yes, "Example: myapp reserve qa2 --yes", dryRun);
+
+  if (shouldRunHeadlessWithYes(ctx, { yes, hasRequiredArgs: !!env, dryRun })) {
+    const result = await executeReserve({ dryRun, env, yes });
+    process.stdout.write(`${result.message}\n`);
+    return;
+  }
+
+  await renderInteractiveWizard({ env, yes, dryRun });
+};
+```
+
+**Read / query command** (optional `--json`):
+
+```typescript
+import { shouldRunHeadless, wantsExplicitJson } from "argsbarg";
+
+handler: async (ctx) => {
+  const json = ctx.hasFlag("json");
+
+  if (shouldRunHeadless(ctx, json)) {
+    const data = await fetchStatus(ctx.args[0]);
+    if (wantsExplicitJson(ctx, json)) {
+      process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    } else {
+      process.stdout.write(formatStatusHuman(data));
+    }
+    return;
+  }
+
+  await renderPage(<StatusPage env={ctx.args[0]} />);
+};
+```
+
+### Rules of thumb
+
+1. **Resolvable from flags** — if a human can complete the action with flags, an agent can too (`--env qa2 --yes`). Wizards are optional sugar on TTY.
+2. **`--yes` on mutators** — required for non-TTY CLI scripts; MCP should pass `yes: true` in tool arguments when the schema exposes `yes`.
+3. **Stdout is the contract** — headless paths write results to stdout (or JSON with `--json`); stderr for errors. No Ink on the MCP wire.
+4. **`ctx.invocation === "mcp"`** — use only for wire-specific behavior (pipe child stdout, reject `--watch`, etc.), not to duplicate business logic.
+5. **Hide only when impossible** — `mcpTool.enabled: false` after confirming no headless path exists (browser-only, irreducible streaming).
+
+Basic synchronous handlers do not need this structure — only commands with an interactive branch.
+
+## Reserved names
+
+Do not declare user commands named `completion`, `install`, `mcp`, `version`, `docs`, or `update` at the root — ArgsBarg injects these when configured.
+
+## Cursor rule for consumer repos
+
+Copy `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` to `.cursor/rules/cli-program.mdc` so agents editing your CLI schema follow these conventions.
+
+## See also
+
+- [MCP server](mcp.md) — tools, schema resource, env bootstrapping
+- [Agent skills](ai-skills.md) — `install --skill`
+- [Bundled docs](bundled-docs.md) — `docs` topics and `docs mcp`

package/docs/mcp.md

@@ -103,9 +103,9 @@ Tool names are derived from the command path, with each segment sanitized (non-a
 
 ### Tool descriptions
 
-Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash:
+Each tool’s `description` includes the human CLI path and the leaf’s help text, separated by an em dash. Tool arguments are defined in `inputSchema` (options and positionals with their descriptions). `mcpTool.requiresEnv` is appended as `[requires env: …]`.
 
-| CLI path | MCP `description` |
+| CLI path | MCP `description` (example) |
 | --- | --- |
 | `stat owner lookup` | `stat owner lookup — Resolve owner info.` |
 | `read` | `read — Print the first line of each file.` |
@@ -126,6 +126,8 @@ Set `mcpTool: { enabled: false }` on a **leaf command** to hide it from `tools/l
 
 Omitted or `enabled: true` exposes the command (default). `mcpTool` is only valid on leaves — not on the program root or routing groups.
 
+**Prefer fixing schema and handlers over `mcpTool` overrides** — standard option names (`yes`, `dry-run`, `json`), headless paths, and clear descriptions usually make MCP work without per-leaf config. See [cli-program.md](cli-program.md).
+
 ### Per-leaf tool metadata
 
 ```typescript
@@ -207,7 +209,9 @@ URIs must be unique and must not equal `schemaResourceUri`. `load()` runs synchr
 
 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:
+MCP is always non-interactive. Commands that can mount Ink or prompts should implement a **headless fast path** (same path as non-TTY CLI with `--yes` / `--json`) — see [cli-program.md — Headless-capable handlers](cli-program.md#headless-capable-handlers).
+
+Use `ctx.invocation` to branch subprocess behavior — MCP stdout is the JSON-RPC wire, so child processes must not inherit it:
 
 ```typescript
 handler: async (ctx) => {

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

@@ -0,0 +1,29 @@
+---
+description: Argsbarg CliProgram authoring; copy to .cursor/rules/cli-program.mdc
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+**argsbarg** — `CliProgram` drives help, MCP, and skills. Full guide: `node_modules/argsbarg/docs/cli-program.md`.
+
+## Defaults
+- `mcpServer: { enabled: true }` for MCP; **omit `mcpTool`** unless an escape hatch is required
+- `description` on root, commands, options, and positionals (→ `-h`, MCP `inputSchema`, skills)
+- `satisfies CliProgram`; root: `key`, `version`, `description`
+- Reserved root commands (do not declare): `completion`, `install`, `mcp`, `version`, `docs`, `update`
+
+## Schema
+- **Inline** options, positionals, and handler schema; extract only for shared flags, `mcpTool` spreads, or large handlers (Ink/dispatch)
+- Leaf descriptions: action-oriented, not UI jargon
+- Prefer option names `yes`, `dry-run`, `json` when semantics match; describe non-interactive use on the option
+
+## `mcpTool` (rare)
+Fix schema/handler first — not for missing `--yes`, wrong flag names, or unfinished headless paths.
+Only: `enabled: false` (CLI-only), `requiresEnv`, or irreducible limits (e.g. streaming `--watch`). Comment why if used.
+
+## Headless
+Interactive commands need one fast path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json`.
+- Mutators: `requireYesInNonTty`, `shouldRunHeadlessWithYes`
+- Queries: `shouldRunHeadless`, `wantsExplicitJson`
+- Varargs/positionals: `shouldRunHeadlessWithPositionals`
+- `ctx.invocation === "mcp"` only for subprocess/TTY wire behavior; use argsbarg headless helpers, not raw `isTTY`

package/index.d.ts

@@ -307,8 +307,6 @@ export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
 export declare const isInteractiveTty: boolean;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
-/** True when `--dry-run` was passed. */
-export declare function wantsDryRun(hasDryRunFlag: boolean): boolean;
 /** True when `--json` was passed or the handler was invoked via MCP. */
 export declare function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3"

package/src/headless.test.ts

@@ -5,15 +5,9 @@ import {
   shouldRunHeadless,
   shouldRunHeadlessWithPositionals,
   shouldRunHeadlessWithYes,
-  wantsDryRun,
   wantsExplicitJson,
 } from "./headless.ts";
 
-test("wantsDryRun detects flag", () => {
-  expect(wantsDryRun(true)).toBe(true);
-  expect(wantsDryRun(false)).toBe(false);
-});
-
 test("wantsExplicitJson includes MCP invocation", () => {
   expect(wantsExplicitJson({ invocation: "cli" }, false)).toBe(false);
   expect(wantsExplicitJson({ invocation: "mcp" }, false)).toBe(true);

package/src/headless.ts

@@ -4,11 +4,6 @@ import { isInteractiveTty } from "./utils.ts";
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 
-/** True when `--dry-run` was passed. */
-export function wantsDryRun(hasDryRunFlag: boolean): boolean {
-  return hasDryRunFlag;
-}
-
 /** True when `--json` was passed or the handler was invoked via MCP. */
 export function wantsExplicitJson(ctx: HeadlessContext, hasJsonFlag: boolean): boolean {
   return hasJsonFlag || ctx.invocation === "mcp";

package/src/index.ts

@@ -34,7 +34,6 @@ export {
   shouldRunHeadless,
   shouldRunHeadlessWithPositionals,
   shouldRunHeadlessWithYes,
-  wantsDryRun,
   wantsExplicitJson,
 } from "./headless.ts";
 export type { HeadlessContext } from "./headless.ts";