argsbarg 3.6.1 → 3.6.3

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.3] - 2026-06-23
+
+### Added
+
+- **`docs/README.md`** — documentation map (framework vs consumer docgen).
+- **`docs/developing.md`** — maintainer workflow (`consumer-dev`, `consumers-sync`, npm `files`).
+- **`examples/formats.ts`** — `CliValueFormat`, `default`, and `readLeafInputs()` demo.
+
+### Changed
+
+- **`cli-program.md`** — `CliLeafInputs` / `readLeafInputs()` semantics, upgrading to 3.6+, read-once-resolve-once cross-links.
+- **`bundled-docs.md`** — framework docs vs consumer docgen.
+- **`docs/mcp.md`** — varargs JSON array only (fixes stale comma-string guidance).
+
+## [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
@@ -393,7 +413,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.1...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.3...HEAD
+[3.6.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.6.3
+[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

package/README.md

@@ -155,7 +155,7 @@ mkdir -p .cursor/rules
 cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
 ```
 
-Add app-specific conventions in a second rule if needed. Full guide: **[docs/cli-program.md](docs/cli-program.md)**.
+Add app-specific conventions in a second rule if needed. Documentation map: **[docs/README.md](docs/README.md)**. Authoring guide: **[docs/cli-program.md](docs/cli-program.md)**.
 
 
 ## How it works
@@ -214,6 +214,7 @@ Check the `examples/` directory for full working scripts:
 | --- | --- | --- |
 | `ArgsBargMinimal` | `examples/minimal.ts` | String + presence flags, `MissingOrUnknown` fallback. |
 | `ArgsBargNested` | `examples/nested.ts` | Nested command tree, positional tails, async handlers. |
+| `ArgsBargFormats` | `examples/formats.ts` | `CliValueFormat`, `default`, `readLeafInputs()`. |
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -225,6 +226,8 @@ minimal.ts hello --name world
 eval "$(nested.ts completion zsh)"
 nested.ts stat owner lookup -u alice ./README.md
 nested.ts read ./README.md
+
+bun ./examples/formats.ts run --tags demo,docs --on 2026-06-22
 ```
 
 
@@ -238,7 +241,8 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
 | `CliOptionKind`, `CliValueFormat`, `CliFallbackMode` | Option kinds, value formats (`duration`, `comma-list`, `date`, `date-time`), and root fallback behavior. |
 | `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
-| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
+| `CliContext` | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
+| `CliLeafInputs` | Record type returned by `readLeafInputs()` — coerced option/positional values keyed by schema name. |
 | `cliRun(root, [argv])` | Validate, parse argv, dispatch, exit. |
 | `cliInvoke(root, argv)` | Parse and dispatch without exiting; returns captured stdout/stderr. |
 | `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |

package/docs/README.md

@@ -0,0 +1,32 @@
+# Argsbarg documentation
+
+Start here to pick the right guide.
+
+| If you are… | Read |
+| --- | --- |
+| **New to argsbarg** | [../README.md](../README.md) — install, minimal usage, public API |
+| **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
+| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `install --mcp` |
+| **Shipping install / completions / skills** | [install.md](install.md) — `myapp install`, shell completions |
+| **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
+| **Agent skills** | [ai-skills.md](ai-skills.md) — `install --skill`, `docs skill` |
+| **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
+| **Cursor / IDE agents in a consumer app** | Copy [templates/cursor/rules/cli-program.mdc](templates/cursor/rules/cli-program.mdc) to `.cursor/rules/` |
+
+## Framework docs vs consumer docgen
+
+| Source | What it is | Where it lives |
+| --- | --- | --- |
+| **Framework docs** | How argsbarg works; authoring conventions | This directory — shipped in `node_modules/argsbarg/docs/` after `bun add argsbarg` |
+| **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs api`, `docs schema`, `docs mcp` — written to `./docs/` with `--save` |
+| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc` — copy into your repo and append app conventions |
+
+Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (Cursor rule, `AGENTS.md`, or an `alwaysApply` project rule). Generated `./docs/api.md` in a consumer repo describes **your** CLI, not argsbarg itself.
+
+## Examples
+
+| Example | Shows |
+| --- | --- |
+| [../examples/minimal.ts](../examples/minimal.ts) | Presence + string flags, fallback routing |
+| [../examples/nested.ts](../examples/nested.ts) | Nested commands, varargs, MCP + `docs` |
+| [../examples/formats.ts](../examples/formats.ts) | `CliValueFormat`, `default`, `readLeafInputs()` |

package/docs/bundled-docs.md

@@ -2,6 +2,19 @@
 
 ArgsBarg can expose bundled markdown topics as the built-in `docs` command group. Opt in on the program root with `docs: { enabled: true, topics: { ... } }`.
 
+## Framework docs vs your app's docgen
+
+Two documentation layers often coexist in a consumer repo:
+
+| Layer | Contents | How agents/humans get it |
+| --- | --- | --- |
+| **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [Cursor rule](templates/cursor/rules/cli-program.mdc) or `AGENTS.md` |
+| **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs api`, `docs schema`, `docs mcp` — save with `--save` to `./docs/` |
+
+Do not confuse them: editing `./docs/api.md` after docgen updates **your** app reference; it does not change argsbarg's framework guides. When MCP behavior changes (e.g. varargs arrays in 3.6+), update consumer `docs/mcp.md` via **`myapp docs mcp --save`** and bump the `argsbarg` dependency.
+
+See [docs/README.md](README.md) for the full documentation map.
+
 ## Quick start
 
 ```typescript

package/docs/cli-program.md

@@ -2,6 +2,8 @@
 
 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.
 
+**Documentation map:** [docs/README.md](README.md) — which guide to read for MCP, install, consumer docgen, and Cursor setup.
+
 ## Minimal app (MCP is free)
 
 ```typescript
@@ -193,8 +195,105 @@ const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs()
 // duration → number (ms); comma-list → string[]; presence → boolean; number → number
 ```
 
+**`CliLeafInputs`** — return type of `readLeafInputs()` (exported from `"argsbarg"`). A flat record keyed by **schema option and positional names** (hyphens preserved, e.g. `"skip-readiness"`). Values are coerced per kind/format:
+
+| Schema | Value in `CliLeafInputs` |
+| --- | --- |
+| Presence | `boolean` |
+| Number | `number` or `undefined` if omitted |
+| String (plain) | `string` or `undefined` |
+| `format: duration` | `number` (milliseconds) |
+| `format: comma-list` | `string[]` |
+| `format: date` | `string` (`YYYY-MM-DD`) |
+| `format: date-time` | `string` (normalized UTC ISO) |
+| Single positional | `string` or `undefined` |
+| Varargs positional | `string[]` or `undefined` |
+
+Omitted options appear as `undefined` (not absent keys). Options with `default` are filled in post-parse before handlers run, so `readLeafInputs()` and `durationOpt` see defaults. **`ctx.opts` always holds raw strings** — use typed accessors or `readLeafInputs()` for coerced values.
+
+`CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.
+
+See [examples/formats.ts](../examples/formats.ts) for a runnable demo.
+
 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.
+
+## Upgrading to 3.6+
+
+### MCP varargs (breaking)
+
+Varargs positionals (`argMax: 0`) must be a **JSON array** in `tools/call` — comma-separated strings are no longer accepted.
+
+```json
+// before (removed)
+{ "uids": "a,b,c" }
+
+// after
+{ "uids": ["a", "b", "c"] }
+```
+
+CLI argv is unchanged: space-separated words. Use `format: comma-list` on an **option** when a single flag should accept `a,b` or `["a","b"]` over MCP.
+
+### Value formats (optional)
+
+Add `format`, `default`, or `pattern` on string **options**; read with `ctx.durationOpt`, `ctx.commaListOpt`, `ctx.readLeafInputs()`, etc. Replace hand-rolled `split(",")` / `parseDurationMs` try/catch where the schema can declare the shape.
+
+### Handler layering (optional)
+
+Ink + headless + MCP apps benefit from `read*Flags(ctx)` + `resolve*Input(flags)` — see above.
+
 ## 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:
@@ -297,6 +396,8 @@ The template is ~25 lines: when to read which doc, plus hard rules agents often
 
 ## See also
 
+- [Documentation map](README.md) — which doc to read when
+- [Developing argsbarg](developing.md) — release, consumer sync, npm `files`
 - [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`
+- [Bundled docs](bundled-docs.md) — `docs` topics, consumer docgen vs framework docs

package/docs/developing.md

@@ -0,0 +1,50 @@
+# Developing argsbarg
+
+Notes for maintainers of this repository. Also shipped under `node_modules/argsbarg/docs/` for fork maintainers.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.3
+- [just](https://github.com/casey/just) — `just` lists recipes
+- `gh` and `npm` logged in for release
+
+## Day-to-day
+
+```bash
+just check    # typecheck + format
+just test     # check + unit tests
+just typegen  # regenerate index.d.ts
+```
+
+## Release
+
+```bash
+just release patch   # or minor | major
+```
+
+The release script bumps `package.json`, promotes `[Unreleased]` in `CHANGELOG.md`, commits, tags, pushes, creates a GitHub release, and publishes to npm. Run `just test` first (the `just release` recipe does).
+
+Update `CHANGELOG.md` under `[Unreleased]` before releasing.
+
+## Local consumer apps
+
+Sibling repos under `../../ss/` (paths are machine-specific; adjust in `justfile` if needed):
+
+| Recipe | When | Effect |
+| --- | --- | --- |
+| `just consumer-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>` in each consumer |
+| `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, `just build`, `just docgen`, `just install` |
+
+`consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
+
+Re-copy `docs/templates/cursor/rules/cli-program.mdc` into consumer repos when the template changes (append app-specific conventions; do not fork the whole guide).
+
+## npm package contents
+
+`npm publish` does **not** honor `.gitignore`. Only paths listed in `package.json` `files` are included in the tarball (plus always-excluded defaults like `node_modules`).
+
+When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
+
+## Docs
+
+See [README.md](README.md) for the documentation map. Framework authoring guide: [cli-program.md](cli-program.md).

package/docs/mcp.md

@@ -208,7 +208,7 @@ Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
 - **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
-- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. For varargs, agents may also pass a comma-separated string (`"a,b"`) or a single string (`"a"`) — both are coerced to separate argv tokens at dispatch time.
+- **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. **Varargs must be a JSON array** — comma-separated strings are not accepted (use `format: comma-list` on an option when a single flag should accept `"a,b"` or `["a","b"]`).
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).
 

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/examples/formats.ts

@@ -0,0 +1,66 @@
+#!/usr/bin/env bun
+/*
+ * Value formats demo: duration, comma-list, date, default, and readLeafInputs().
+ * Run: bun ./examples/formats.ts run --tags alpha,beta --on 2026-06-22
+ * MCP: pass comma-list as string or array; varargs N/A on this leaf.
+ */
+
+import pkg from "../package.json" with { type: "json" };
+import { cliRun, CliFallbackMode, CliOptionKind, CliValueFormat, type CliProgram } from "../src/index.ts";
+
+const cli = {
+  key: "formats.ts",
+  version: pkg.version,
+  description: "Value formats and readLeafInputs demo.",
+  fallbackCommand: "run",
+  fallbackMode: CliFallbackMode.MissingOnly,
+  mcpServer: { enabled: true },
+  commands: [
+    {
+      key: "run",
+      description: "Print coerced option values from readLeafInputs().",
+      options: [
+        {
+          name: "timeout",
+          description: "Wait budget (default 30s).",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Duration,
+          default: "30s",
+        },
+        {
+          name: "tags",
+          description: "Comma-separated labels.",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.CommaList,
+        },
+        {
+          name: "on",
+          description: "Calendar day (YYYY-MM-DD).",
+          kind: CliOptionKind.String,
+          format: CliValueFormat.Date,
+        },
+        {
+          name: "verbose",
+          description: "Also print raw ctx.opts strings.",
+          kind: CliOptionKind.Presence,
+          shortName: "v",
+        },
+      ],
+      handler: (ctx) => {
+        const inputs = ctx.readLeafInputs();
+        const out = {
+          readLeafInputs: inputs,
+          durationMs: ctx.durationOpt("timeout"),
+          tags: ctx.commaListOpt("tags"),
+          on: ctx.dateOpt("on"),
+        };
+        if (ctx.hasFlag("verbose")) {
+          Object.assign(out, { rawOpts: ctx.opts });
+        }
+        process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+      },
+    },
+  ],
+} satisfies CliProgram;
+
+await cliRun(cli);

package/package.json

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