argsbarg 3.5.0 → 3.6.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`CliValueFormat`** — optional `format` on string options: `duration`, `comma-list`, `date`, `date-time`; optional `default` and `pattern` (mutually exclusive with `format`).
+- **`CliContext`** — `durationOpt`, `commaListOpt`, `dateOpt`, `dateTimeOpt`, and `readLeafInputs()` for schema-driven handler reads.
+- **`formats` exports** — `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` for reuse outside handlers.
+
+### Changed
+
+- **Post-parse validation** — applies option `default` values and validates `format` / `pattern` before handlers run.
+- **MCP varargs** — `tools/call` positional arrays must be JSON arrays (comma-separated strings no longer accepted).
+- **MCP comma-list options** — `format: comma-list` accepts string or array in `tools/call`.
+- **`docs mcp`**, **`docs api`**, and **`docs/cli-program.md`** — document value formats and varargs policy.
+- **Cursor rule template** (`docs/templates/cursor/rules/cli-program.mdc`) — thin tripwire that directs agents to read `node_modules/argsbarg/docs/cli-program.md` instead of duplicating authoring guidance.
+
 ## [3.5.0] - 2026-06-22
 
 ### Added
@@ -371,7 +393,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.5.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.1...HEAD
+[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
 [3.4.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v3.4.1

package/README.md

@@ -112,9 +112,9 @@ Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp
 
 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
+### Install CLI
 
-After `bun build --compile` (or when running via `bun`), ship your CLI and let users run:
+argsbarg includes CLI features to manage installation of your compiled bun app. After `bun build --compile` (or when running via `bun`), ship your CLI and let users run:
 
 ```bash
 myapp install --all --yes
@@ -140,12 +140,23 @@ myapp completion fish > ~/.config/fish/completions/myapp.fish
 
 
 
-## Install
+## Quick Start
 
 ```bash
-bun add bun-argsbarg
+bun add argsbarg
 ```
 
+### Cursor / AI agents
+
+Argsbarg ships authoring docs in `node_modules/argsbarg/docs/`. Agents do not load them unless your repo points there — copy the thin Cursor rule after install (it tells agents to **read** `cli-program.md`, not duplicate it):
+
+```bash
+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)**.
+
 
 ## How it works
 
@@ -178,9 +189,13 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 ### Reading values (`CliContext`)
 
-- `ctx.flag("verbose")` — presence options (`boolean`).
+- `ctx.flag("verbose")` / `ctx.hasFlag("verbose")` — presence options (`boolean`).
 - `ctx.stringOpt("name")` / `ctx.numberOpt("count")` — `string | undefined` / `number | null`.
-- `ctx.typedOpt<T>("custom", parseFn)` — pass a custom parsing function for type-safe option resolution.
+- `ctx.durationOpt("timeout")` — duration options (`format: CliValueFormat.Duration`) as milliseconds.
+- `ctx.commaListOpt("services")` — comma-list options as `string[] | undefined`.
+- `ctx.dateOpt("on")` / `ctx.dateTimeOpt("since")` — ISO date / date-time options.
+- `ctx.readLeafInputs()` — coerced option and positional values for the current leaf (schema-driven).
+- `ctx.typedOpt<T>("custom", parseFn)` — custom parsing 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.program` — program root (`CliProgram`) for contextual help.
@@ -221,12 +236,13 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | Symbol | Role |
 | --- | --- |
 | `CliProgram`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
-| `CliOptionKind`, `CliFallbackMode` | Option kinds (`Presence`, `String`, `Number`, `Enum`) and root fallback behavior. |
+| `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.args`, `ctx.invocation`, …). |
+| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.readLeafInputs`, `ctx.invocation`, …). |
 | `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. |
+| `parseDurationMs`, `parseCommaList`, `parseDate`, `parseDateTime` | Optional format parsers for use outside handlers. |
 
 Reserved identifiers (validated at startup): root commands **`completion`**, **`version`**, **`install`**, **`docs`** (when `docs.enabled` is `true`), and **`mcp`** (when `mcpServer.enabled` is `true`).
 

package/docs/cli-program.md

@@ -136,6 +136,65 @@ Do **not** use `mcpTool.description` to paper over missing `--yes`, non-standard
 
 If help text and MCP behavior match after your fixes, **omit `mcpTool` entirely**.
 
+## Value formats
+
+On **string options**, optional metadata improves validation, MCP `inputSchema`, and handler reads:
+
+| Field | Purpose |
+| --- | --- |
+| `format: CliValueFormat.Duration` | Values like `30s`, `20m`, `1h`; read with `ctx.durationOpt(name)` (milliseconds) |
+| `format: CliValueFormat.CommaList` | Single-flag lists (`--services a,b`); MCP may pass string or array; read with `ctx.commaListOpt(name)` |
+| `format: CliValueFormat.Date` | `YYYY-MM-DD`; read with `ctx.dateOpt(name)` |
+| `format: CliValueFormat.DateTime` | RFC 3339 instant; read with `ctx.dateTimeOpt(name)` |
+| `default: "..."` | Applied in post-parse when the option is omitted (not valid with `required: true`) |
+| `pattern: "..."` | Regex validation (mutually exclusive with `format`) |
+
+`format` applies to **string options only** — not positionals. Post-parse keeps raw strings in `ctx.opts`; typed readers return coerced values.
+
+**Example** (duration with default, comma-list flag):
+
+```typescript
+import { CliOptionKind, CliValueFormat } from "argsbarg";
+
+options: [
+  {
+    name: "timeout",
+    description: "Maximum wait time.",
+    kind: CliOptionKind.String,
+    format: CliValueFormat.Duration,
+    default: "20m",
+  },
+  {
+    name: "services",
+    description: "Service names to reset (single env only).",
+    kind: CliOptionKind.String,
+    format: CliValueFormat.CommaList,
+  },
+],
+handler: async (ctx) => {
+  const timeoutMs = ctx.durationOpt("timeout")!; // always set via default
+  const services = ctx.commaListOpt("services"); // string[] | undefined
+},
+```
+
+**Varargs positionals** (`argMax: 0`):
+
+| Surface | Multiple values |
+| --- | --- |
+| CLI | Space-separated words: `myapp uids uid-a uid-b` |
+| MCP | JSON array on the positional key: `{ "uids": ["uid-a", "uid-b"] }` |
+
+Read varargs with `ctx.positional("uids")` (returns `string[]`) or `ctx.args`. Do not comma-split argv tokens or use `format` on positionals.
+
+**`readLeafInputs()`** — for leaves with several flags, one schema-driven read instead of hand-rolled `hasFlag` / `stringOpt` lines:
+
+```typescript
+const { limit, "skip-readiness": skipReadiness, timeout } = ctx.readLeafInputs();
+// duration → number (ms); comma-list → string[]; presence → boolean; number → number
+```
+
+Cross-field rules (e.g. `--match-remote` requires `--branch`) stay in consumer `resolve*` layers — argsbarg does not validate those.
+
 ## 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:
@@ -219,7 +278,22 @@ Do not declare user commands named `completion`, `install`, `mcp`, `version`, or
 
 ## 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.
+Argsbarg ships framework docs under `node_modules/argsbarg/docs/` (same files as this repo’s `docs/`). **This file is the authoritative guide** — the Cursor rule is a thin tripwire that tells agents to read it.
+
+Agents do **not** discover package docs automatically. Wire them in after `bun add argsbarg`:
+
+1. **Copy the Cursor rule** (recommended):
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/argsbarg/docs/templates/cursor/rules/cli-program.mdc .cursor/rules/cli-program.mdc
+```
+
+The template is ~25 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide — re-copy after upgrading argsbarg when the template changes.
+
+2. **Optional:** a second rule for app-only conventions (e.g. `src/cli/shared.ts` flag names, JSON-only handlers, Ink patterns).
+
+3. **Optional:** `.cursor/argsbarg.mdc` or `AGENTS.md` pointing at `node_modules/argsbarg/docs/cli-program.md` for broader context.
 
 ## See also
 

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

@@ -1,29 +1,23 @@
 ---
-description: Argsbarg CliProgram authoring; copy to .cursor/rules/cli-program.mdc
-globs: "**/*.{ts,tsx}"
+description: Argsbarg schema — read framework docs before editing CLI commands
+globs: "src/**/commands/**/*.{ts,tsx},src/index.{ts,tsx}"
 alwaysApply: false
 ---
 
-**argsbarg** — `CliProgram` drives help, MCP, and skills. Full guide: `node_modules/argsbarg/docs/cli-program.md`.
+When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
 
-## 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`
+1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
+2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
+3. `install`, completions, skills → `node_modules/argsbarg/docs/install.md`.
+4. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
 
-## Schema
-- **Inline** options, positionals, and handler schema; extract to `export const …Command = { … } satisfies CliLeaf` (or router type) when shared flags, `mcpTool` spreads, or large handlers justify a module — not zero-arg wrapper functions
-- Leaf descriptions: action-oriented, not UI jargon
-- Prefer option names `yes`, `dry-run`, `json` when semantics match; describe non-interactive use on the option
+**Hard rules** (details and examples are in the docs above — do not contradict them):
 
-## `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.
+- Reserved root commands: `completion`, `install`, `mcp`, `version`, `docs`, `update`.
+- `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
+- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`), `requiresEnv`, or an irreducible wire limit — fix schema and headless handlers first.
+- 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.
 
-## 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`
+**App-specific conventions:** add below or in a separate `.cursor/rules/` file (shared flags path, Ink vs JSON-only, etc.).

package/index.d.ts

@@ -17,6 +17,20 @@ export declare enum CliOptionKind {
 	/** Fixed set of allowed string values. Requires non-empty `choices` on the option. */
 	Enum = "enum"
 }
+/**
+ * Named validation/coercion for string options (`format` on `CliOption`).
+ * Positionals do not use `format`; varargs use space-separated CLI tokens and JSON arrays over MCP.
+ */
+export declare enum CliValueFormat {
+	/** Duration text such as `30s`, `20m`, `1h`, `2d` (default unit minutes when omitted). */
+	Duration = "duration",
+	/** Comma-separated list on a single option value (`--services a,b`). */
+	CommaList = "comma-list",
+	/** Calendar date `YYYY-MM-DD`. */
+	Date = "date",
+	/** RFC 3339 instant with `Z` or numeric offset. */
+	DateTime = "date-time"
+}
 /**
  * When `fallbackCommand` is used for missing or unknown subcommand tokens at a routing node.
  */
@@ -56,6 +70,15 @@ export interface CliOption {
 	 * Must be a non-empty array of distinct non-empty strings.
 	 */
 	choices?: string[];
+	/**
+	 * Named string validation for `kind: String` options. Mutually exclusive with `pattern`.
+	 * Not supported on positionals.
+	 */
+	format?: CliValueFormat;
+	/** Default value applied in post-parse when the option is omitted. */
+	default?: string;
+	/** Regex pattern for string options. Mutually exclusive with `format`. */
+	pattern?: string;
 }
 /**
  * An ordered positional argument slot, listed on leaf `positionals`.
@@ -280,6 +303,8 @@ export declare class CliSchemaValidationError extends Error {
 	/** Creates a schema validation error with a human-readable rule violation. */
 	constructor(message: string);
 }
+/** Coerced leaf inputs keyed by option and positional names. */
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
 /**
  * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
@@ -303,11 +328,31 @@ export declare class CliContext {
 	 * This is the TypeScript-native advantage over the Swift version.
 	 */
 	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+	/** Duration option in milliseconds (post-parse validated). */
+	durationOpt(name: string): number | undefined;
+	/** Comma-list option as a string array (post-parse validated). */
+	commaListOpt(name: string): string[] | undefined;
+	/** Date option as canonical YYYY-MM-DD (post-parse validated). */
+	dateOpt(name: string): string | undefined;
+	/** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
+	dateTimeOpt(name: string): string | undefined;
 	/** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
 	positional(name: string): string | string[] | undefined;
+	/** Reads coerced option and positional values for the current leaf from schema metadata. */
+	readLeafInputs(): CliLeafInputs;
+	private _readOptionValue;
+	private _leafNode;
 	private _posMap;
 	private _positionalMap;
 }
+/** Parses a duration string (e.g. 20m, 1h, 30s) into milliseconds. */
+export declare function parseDurationMs(durationStr: string): number;
+/** Splits a comma-separated string into trimmed non-empty tokens. */
+export declare function parseCommaList(s: string): string[];
+/** Returns canonical YYYY-MM-DD after validation. */
+export declare function parseDate(s: string): string;
+/** Returns normalized ISO 8601 UTC after validation. */
+export declare function parseDateTime(s: string): string;
 /** Minimal context for headless routing helpers. */
 export type HeadlessContext = Pick<CliContext, "invocation">;
 /** True when `--json` was passed or the handler was invoked via MCP. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "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/src/context.ts

@@ -7,10 +7,15 @@ It keeps handlers small with a typed read API for flags, strings, numbers, and c
 parsed values.
 */
 
-import type { CliInvocation, CliNode, CliProgram } from "./types.ts";
-import { isCliLeaf, isCliRouter } from "./types.ts";
+import { parseCommaList, parseDate, parseDateTime, parseDurationMs } from "./formats.ts";
+import { collectOptionDefs } from "./parse.ts";
+import type { CliInvocation, CliLeaf, CliNode, CliOption, CliProgram } from "./types.ts";
+import { CliOptionKind, CliValueFormat, isCliLeaf, isCliRouter } from "./types.ts";
 import { strictParseDouble } from "./utils.ts";
 
+/** Coerced leaf inputs keyed by option and positional names. */
+export type CliLeafInputs = Record<string, boolean | number | string | string[] | undefined>;
+
 /**
  * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
  */
@@ -70,38 +75,109 @@ export class CliContext {
     }
   }
 
+  /** Duration option in milliseconds (post-parse validated). */
+  durationOpt(name: string): number | undefined {
+    const s = this.opts[name];
+    if (s === undefined) return undefined;
+    return parseDurationMs(s);
+  }
+
+  /** Comma-list option as a string array (post-parse validated). */
+  commaListOpt(name: string): string[] | undefined {
+    const s = this.opts[name];
+    if (s === undefined) return undefined;
+    return parseCommaList(s);
+  }
+
+  /** Date option as canonical YYYY-MM-DD (post-parse validated). */
+  dateOpt(name: string): string | undefined {
+    const s = this.opts[name];
+    if (s === undefined) return undefined;
+    return parseDate(s);
+  }
+
+  /** Date-time option as normalized ISO 8601 UTC (post-parse validated). */
+  dateTimeOpt(name: string): string | undefined {
+    const s = this.opts[name];
+    if (s === undefined) return undefined;
+    return parseDateTime(s);
+  }
+
   /** Returns the value(s) for a named positional slot. Varargs slots return string[]; single slots return string | undefined. */
   positional(name: string): string | string[] | undefined {
     return this._positionalMap()[name];
   }
 
-  private _posMap: Record<string, string | string[]> | undefined;
+  /** Reads coerced option and positional values for the current leaf from schema metadata. */
+  readLeafInputs(): CliLeafInputs {
+    const leaf = this._leafNode();
+    if (!leaf) return {};
 
-  private _positionalMap(): Record<string, string | string[]> {
-    if (this._posMap) return this._posMap;
+    const out: CliLeafInputs = {};
+    for (const opt of collectOptionDefs(this.program, this.commandPath)) {
+      out[opt.name] = this._readOptionValue(opt);
+    }
+    for (const p of leaf.positionals ?? []) {
+      const val = this.positional(p.name);
+      if (val === undefined) {
+        out[p.name] = undefined;
+      } else if (Array.isArray(val)) {
+        out[p.name] = val;
+      } else {
+        out[p.name] = val;
+      }
+    }
+    return out;
+  }
+
+  private _readOptionValue(opt: CliOption): boolean | number | string | string[] | undefined {
+    if (opt.kind === CliOptionKind.Presence) {
+      return this.hasFlag(opt.name);
+    }
+    if (opt.kind === CliOptionKind.Number) {
+      const n = this.numberOpt(opt.name);
+      return n === null ? undefined : n;
+    }
+    if (opt.format === CliValueFormat.Duration) {
+      return this.durationOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.CommaList) {
+      return this.commaListOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.Date) {
+      return this.dateOpt(opt.name);
+    }
+    if (opt.format === CliValueFormat.DateTime) {
+      return this.dateTimeOpt(opt.name);
+    }
+    return this.stringOpt(opt.name);
+  }
 
+  private _leafNode(): CliLeaf | undefined {
     let node: CliNode = this.program;
     for (const seg of this.commandPath) {
-      if (!isCliRouter(node)) {
-        this._posMap = {};
-        return {};
-      }
+      if (!isCliRouter(node)) return undefined;
       const child = node.commands.find((c) => c.key === seg);
-      if (!child) {
-        this._posMap = {};
-        return {};
-      }
+      if (!child) return undefined;
       node = child;
     }
+    return isCliLeaf(node) ? node : undefined;
+  }
+
+  private _posMap: Record<string, string | string[]> | undefined;
+
+  private _positionalMap(): Record<string, string | string[]> {
+    if (this._posMap) return this._posMap;
 
-    if (!isCliLeaf(node)) {
+    const leaf = this._leafNode();
+    if (!leaf) {
       this._posMap = {};
       return {};
     }
 
     const map: Record<string, string | string[]> = {};
     let argIdx = 0;
-    for (const p of node.positionals ?? []) {
+    for (const p of leaf.positionals ?? []) {
       const { argMax = 1 } = p;
       if (argMax === 0) {
         map[p.name] = this.args.slice(argIdx);

package/src/docs/api-guide.ts

@@ -23,6 +23,20 @@ function optionType(opt: CliOption): string {
   return opt.kind;
 }
 
+function optionFormatDefault(opt: CliOption): string {
+  const parts: string[] = [];
+  if (opt.format !== undefined) {
+    parts.push(opt.format);
+  }
+  if (opt.default !== undefined) {
+    parts.push(`default \`${opt.default}\``);
+  }
+  if (opt.pattern !== undefined) {
+    parts.push(`pattern \`${opt.pattern}\``);
+  }
+  return parts.length > 0 ? parts.join("; ") : "—";
+}
+
 /** Markdown table cell for one option flag. */
 function optionLabel(opt: CliOption): string {
   const long = `\`--${opt.name}\``;
@@ -33,7 +47,7 @@ function optionLabel(opt: CliOption): string {
 /** One options table row. */
 function formatOptionRow(opt: CliOption): string {
   const req = opt.required ? "required" : "optional";
-  return `| ${optionLabel(opt)} | ${optionType(opt)} | ${req} | ${opt.description} |`;
+  return `| ${optionLabel(opt)} | ${optionType(opt)} | ${req} | ${optionFormatDefault(opt)} | ${opt.description} |`;
 }
 
 /** One positionals table row. */
@@ -99,8 +113,8 @@ function renderCommandNode(
 
   if ((node.options ?? []).length > 0) {
     lines.push("#### Options", "");
-    lines.push("| Option | Type | Required | Description |");
-    lines.push("| --- | --- | --- | --- |");
+    lines.push("| Option | Type | Required | Format / default | Description |");
+    lines.push("| --- | --- | --- | --- | --- |");
     for (const opt of node.options ?? []) {
       lines.push(formatOptionRow(opt));
     }

package/src/docs/mcp-guide.ts

@@ -206,7 +206,9 @@ export function generateMcpGuide(root: CliProgram): string {
     "Arguments are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
     `See \`${root.key} docs schema\` or the schema resource for per-tool shapes.`,
     "",
-    "Varargs positionals accept a JSON array or a comma-separated string.",
+    "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
+    "Options with `format: comma-list` accept a comma-separated string or JSON array.",
+    "Options with a schema `default` are applied when omitted.",
     "",
     "## Protocol",
     "",

package/src/formats.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "bun:test";
+import {
+  parseCommaList,
+  parseDate,
+  parseDateTime,
+  parseDurationMs,
+  validateFormatValue,
+} from "./formats.ts";
+import { CliValueFormat } from "./types.ts";
+
+test("parseDurationMs parses minutes and hours", () => {
+  expect(parseDurationMs("30s")).toBe(30_000);
+  expect(parseDurationMs("5m")).toBe(5 * 60 * 1000);
+  expect(parseDurationMs("2h")).toBe(2 * 60 * 60 * 1000);
+  expect(parseDurationMs("1d")).toBe(24 * 60 * 60 * 1000);
+});
+
+test("parseCommaList splits and trims", () => {
+  expect(parseCommaList("a,b")).toEqual(["a", "b"]);
+  expect(parseCommaList(" a , b , ")).toEqual(["a", "b"]);
+});
+
+test("parseDate validates calendar dates", () => {
+  expect(parseDate("2026-06-22")).toBe("2026-06-22");
+  expect(() => parseDate("2026-02-30")).toThrow();
+});
+
+test("parseDateTime normalizes to UTC ISO", () => {
+  expect(parseDateTime("2026-06-22T15:00:00Z")).toBe("2026-06-22T15:00:00.000Z");
+  expect(() => parseDateTime("2026-06-22")).toThrow();
+});
+
+test("validateFormatValue rejects invalid duration", () => {
+  expect(() => validateFormatValue("nope", CliValueFormat.Duration)).toThrow();
+});