argsbarg 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +387,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.5.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v3.6.0...HEAD
+[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/justfile

@@ -13,14 +13,11 @@ consumers-sync *apps:
     #!/usr/bin/env bash
     root="$(cd "{{justfile_directory()}}" && pwd)"
     ss="$root/../../ss"
-    apps=({{apps}})
-    if [[ ${#apps[@]} -eq 0 ]]; then
-      apps=(idp-trees sqsp-qa-tools sqsp-i18n-tools)
-    fi
+    apps=(idp-trees sqsp-qa-tools sqsp-i18n-tools)
     for app in "${apps[@]}"; do
       dir="$(cd "$ss/$app" && pwd)"
       echo "==> $app ($dir)"
-      (cd "$dir" && npm i argsbarg@latest --no-package-lock && just build && just docgen)
+      (cd "$dir" && bun i argsbarg@latest && just build && just docgen && just install)
     done
 
 # run the minimal example

package/package.json

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

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();
+});

package/src/formats.ts

@@ -0,0 +1,135 @@
+/*
+Named string format validation and parsing for CLI options.
+*/
+
+import { CliValueFormat } from "./types.ts";
+
+const DURATION_RE = /^\d+[hdms]?$/i;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Parses a duration string (e.g. 20m, 1h, 30s) into milliseconds. */
+export function parseDurationMs(durationStr: string): number {
+  const match = durationStr.trim().match(/^(\d+)([hdms]?)$/i);
+  if (!match) {
+    throw new Error("Invalid duration format. Use e.g. 30s, 20m, 1h, 2d");
+  }
+  const amountText = match[1];
+  if (!amountText) {
+    throw new Error("Invalid duration format. Use e.g. 30s, 20m, 1h, 2d");
+  }
+  const amount = Number.parseInt(amountText, 10);
+  const unit = (match[2] || "m").toLowerCase();
+  if (unit === "s") return amount * 1000;
+  if (unit === "m") return amount * 60 * 1000;
+  if (unit === "h") return amount * 60 * 60 * 1000;
+  if (unit === "d") return amount * 24 * 60 * 60 * 1000;
+  return amount * 60 * 1000;
+}
+
+export function validateDuration(s: string): void {
+  if (!DURATION_RE.test(s.trim())) {
+    throw new Error("Invalid duration format. Use e.g. 30s, 20m, 1h, 2d");
+  }
+  parseDurationMs(s);
+}
+
+/** Splits a comma-separated string into trimmed non-empty tokens. */
+export function parseCommaList(s: string): string[] {
+  return s
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function validateCommaList(s: string): void {
+  if (parseCommaList(s).length === 0) {
+    throw new Error("Comma-separated list must contain at least one value");
+  }
+}
+
+/** Returns canonical YYYY-MM-DD after validation. */
+export function parseDate(s: string): string {
+  const trimmed = s.trim();
+  if (!DATE_RE.test(trimmed)) {
+    throw new Error("Invalid date. Use YYYY-MM-DD");
+  }
+  const [y, m, d] = trimmed.split("-").map((part) => Number.parseInt(part, 10));
+  const year = y ?? 0;
+  const month = m ?? 0;
+  const day = d ?? 0;
+  const dt = new Date(Date.UTC(year, month - 1, day));
+  if (dt.getUTCFullYear() !== year || dt.getUTCMonth() !== month - 1 || dt.getUTCDate() !== day) {
+    throw new Error("Invalid date. Use YYYY-MM-DD");
+  }
+  return trimmed;
+}
+
+export function validateDate(s: string): void {
+  parseDate(s);
+}
+
+const DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/** Returns normalized ISO 8601 UTC after validation. */
+export function parseDateTime(s: string): string {
+  const trimmed = s.trim();
+  if (!DATE_TIME_RE.test(trimmed)) {
+    throw new Error("Invalid date-time. Use RFC 3339, e.g. 2026-06-22T15:00:00Z");
+  }
+  const ms = Date.parse(trimmed);
+  if (Number.isNaN(ms)) {
+    throw new Error("Invalid date-time. Use RFC 3339, e.g. 2026-06-22T15:00:00Z");
+  }
+  return new Date(ms).toISOString();
+}
+
+export function validateDateTime(s: string): void {
+  parseDateTime(s);
+}
+
+export function validatePattern(s: string, pattern: string): void {
+  const re = new RegExp(pattern);
+  if (!re.test(s)) {
+    throw new Error(`Value does not match required pattern: ${pattern}`);
+  }
+}
+
+export function formatValidationError(format: CliValueFormat, value: string): string {
+  switch (format) {
+    case CliValueFormat.Duration:
+      return `Invalid duration: ${value} (use e.g. 30s, 20m, 1h, 2d)`;
+    case CliValueFormat.CommaList:
+      return `Invalid comma-separated list: ${value}`;
+    case CliValueFormat.Date:
+      return `Invalid date: ${value} (use YYYY-MM-DD)`;
+    case CliValueFormat.DateTime:
+      return `Invalid date-time: ${value} (use RFC 3339, e.g. 2026-06-22T15:00:00Z)`;
+  }
+}
+
+/** Validates a string value against format and/or pattern metadata. */
+export function validateFormatValue(
+  value: string,
+  format?: CliValueFormat,
+  pattern?: string,
+): void {
+  if (format !== undefined) {
+    switch (format) {
+      case CliValueFormat.Duration:
+        validateDuration(value);
+        return;
+      case CliValueFormat.CommaList:
+        validateCommaList(value);
+        return;
+      case CliValueFormat.Date:
+        validateDate(value);
+        return;
+      case CliValueFormat.DateTime:
+        validateDateTime(value);
+        return;
+    }
+  }
+  if (pattern !== undefined) {
+    validatePattern(value, pattern);
+  }
+}

package/src/index.test.ts

@@ -1960,18 +1960,18 @@ test("ctx.positional varargs matches ctx.args", async () => {
   expect(positional).toEqual(args);
 });
 
-test("mcpToolCallToArgv coerces comma-separated string for varargs", () => {
+test("mcpToolCallToArgv rejects comma-separated string for varargs", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const read = tools.find((t) => t.name === "read")!;
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a,b" });
-  expect(argv).toEqual(["read", "a", "b"]);
+  expect(argv).toEqual({ error: expect.stringContaining("JSON array") });
 });
 
-test("mcpToolCallToArgv coerces single string for varargs", () => {
+test("mcpToolCallToArgv rejects bare string for varargs", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const read = tools.find((t) => t.name === "read")!;
   const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "a" });
-  expect(argv).toEqual(["read", "a"]);
+  expect(argv).toEqual({ error: expect.stringContaining("JSON array") });
 });
 
 test("mcpToolCallToArgv array varargs unchanged", () => {
@@ -1981,11 +1981,11 @@ test("mcpToolCallToArgv array varargs unchanged", () => {
   expect(argv).toEqual(["read", "a", "b"]);
 });
 
-test("mcpToolCallToArgv empty string varargs appends nothing", () => {
+test("mcpToolCallToArgv empty array varargs errors when required", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const read = tools.find((t) => t.name === "read")!;
-  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: "" });
-  expect(argv).toEqual(["read"]);
+  const argv = mcpToolCallToArgv(nestedMcpFixture, read, { files: [] });
+  expect(argv).toEqual({ error: "Missing argument: files" });
 });
 
 // ── Skills ────────────────────────────────────────────────────────────────────

package/src/index.ts

@@ -7,7 +7,14 @@ It gives consumers one stable import path without forcing them to know the inter
 module layout.
 */
 
+export type { CliLeafInputs } from "./context.ts";
 export { CliContext } from "./context.ts";
+export {
+  parseCommaList,
+  parseDate,
+  parseDateTime,
+  parseDurationMs,
+} from "./formats.ts";
 export type { HeadlessContext } from "./headless.ts";
 export {
   formatDryRunMessage,
@@ -46,5 +53,10 @@ export type {
   CliUpdateArtifact,
   CliUpdateGetLatest,
 } from "./types.ts";
-export { CliFallbackMode, CliOptionKind, CliSchemaValidationError } from "./types.ts";
+export {
+  CliFallbackMode,
+  CliOptionKind,
+  CliSchemaValidationError,
+  CliValueFormat,
+} from "./types.ts";
 export { isInteractiveTty } from "./utils.ts";

package/src/mcp/tools.ts

@@ -14,10 +14,13 @@ import {
   CliOptionKind,
   type CliPositional,
   type CliProgram,
+  CliValueFormat,
   isCliLeaf,
   leafOutputSchema,
 } from "../types.ts";
 
+const DURATION_PATTERN = "^\\d+[hdms]?$";
+
 /** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
 export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
@@ -65,12 +68,37 @@ export function mcpToolName(root: CliProgram, path: string[]): string {
 
 /** JSON Schema property for one option. */
 function optionProperty(opt: CliOption): Record<string, unknown> {
-  const base = { description: opt.description };
+  const base: Record<string, unknown> = { description: opt.description };
+  if (opt.default !== undefined) {
+    base.default = opt.default;
+  }
   switch (opt.kind) {
     case CliOptionKind.Presence:
       return { type: "boolean", ...base };
-    case CliOptionKind.String:
-      return { type: "string", ...base };
+    case CliOptionKind.String: {
+      if (opt.format === CliValueFormat.CommaList) {
+        return {
+          oneOf: [
+            { type: "string", ...base },
+            { type: "array", items: { type: "string" }, ...base },
+          ],
+        };
+      }
+      const stringBase = { type: "string", ...base };
+      if (opt.format === CliValueFormat.Duration) {
+        return { ...stringBase, pattern: DURATION_PATTERN };
+      }
+      if (opt.format === CliValueFormat.Date) {
+        return { ...stringBase, format: "date" };
+      }
+      if (opt.format === CliValueFormat.DateTime) {
+        return { ...stringBase, format: "date-time" };
+      }
+      if (opt.pattern !== undefined) {
+        return { ...stringBase, pattern: opt.pattern };
+      }
+      return stringBase;
+    }
     case CliOptionKind.Number:
       return { type: "number", ...base };
     case CliOptionKind.Enum:
@@ -78,6 +106,23 @@ function optionProperty(opt: CliOption): Record<string, unknown> {
   }
 }
 
+function formatMcpOptionValue(opt: CliOption, val: unknown): string | { error: string } {
+  if (opt.format === CliValueFormat.CommaList) {
+    if (Array.isArray(val)) {
+      const items = val.map(String).filter(Boolean);
+      if (items.length === 0) {
+        return { error: `Option --${opt.name} requires at least one value` };
+      }
+      return items.join(",");
+    }
+    if (typeof val === "string") {
+      return val;
+    }
+    return { error: `Option --${opt.name} must be a string or array of strings` };
+  }
+  return String(val);
+}
+
 /** JSON Schema property for one positional slot. */
 function positionalProperty(p: CliPositional): Record<string, unknown> {
   const base = { description: p.description };
@@ -251,7 +296,11 @@ export function mcpToolCallToArgv(
       }
       continue;
     }
-    argv.push(`--${opt.name}`, String(val));
+    const formatted = formatMcpOptionValue(opt, val);
+    if (typeof formatted !== "string") {
+      return formatted;
+    }
+    argv.push(`--${opt.name}`, formatted);
   }
 
   for (const p of tool.leaf.positionals ?? []) {
@@ -260,20 +309,20 @@ export function mcpToolCallToArgv(
 
     if (argMax === 0) {
       const raw = args[p.name];
-      let items: string[];
-      if (Array.isArray(raw)) {
-        items = raw.map(String);
-      } else if (typeof raw === "string") {
-        items = raw.includes(",")
-          ? raw
-              .split(",")
-              .map((s) => s.trim())
-              .filter(Boolean)
-          : raw.trim()
-            ? [raw.trim()]
-            : [];
-      } else {
-        items = [];
+      if (raw === undefined) {
+        if (argMin >= 1) {
+          return { error: `Missing argument: ${p.name} (use a JSON array)` };
+        }
+        continue;
+      }
+      if (!Array.isArray(raw)) {
+        return {
+          error: `Argument ${p.name} must be a JSON array of strings (not a comma-separated string)`,
+        };
+      }
+      const items = raw.map(String).filter(Boolean);
+      if (items.length === 0 && argMin >= 1) {
+        return { error: `Missing argument: ${p.name}` };
       }
       argv.push(...items);
       continue;

package/src/parse.ts

@@ -7,6 +7,7 @@ It keeps handler dispatch and help on one parser so the CLI behavior stays consi
 across every entry path.
 */
 
+import { formatValidationError, validateFormatValue } from "./formats.ts";
 import {
   CliFallbackMode,
   type CliLeaf,
@@ -683,8 +684,15 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
     node = ch;
   }
 
+  const opts = { ...pr.opts };
   for (const d of defs) {
-    if (d.required && !(d.name in pr.opts)) {
+    if (d.default !== undefined && !(d.name in opts)) {
+      opts[d.name] = d.default;
+    }
+  }
+
+  for (const d of defs) {
+    if (d.required && !(d.name in opts)) {
       return {
         kind: ParseKind.Error,
         path: pr.path,
@@ -698,7 +706,7 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
     }
   }
 
-  for (const [k, v] of Object.entries(pr.opts)) {
+  for (const [k, v] of Object.entries(opts)) {
     const d = findOptionByName(defs, k);
     if (!d) {
       return {
@@ -741,7 +749,29 @@ export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
         };
       }
     }
+    if (d.kind === CliOptionKind.String && (d.format !== undefined || d.pattern !== undefined)) {
+      try {
+        validateFormatValue(v, d.format, d.pattern);
+      } catch (err) {
+        const msg =
+          d.format !== undefined
+            ? formatValidationError(d.format, v)
+            : err instanceof Error
+              ? err.message
+              : String(err);
+        return {
+          kind: ParseKind.Error,
+          path: pr.path,
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Invalid value for option --${k}: ${msg}`,
+          errorHelpPath: pr.path,
+        };
+      }
+    }
   }
 
-  return pr;
+  return { ...pr, opts };
 }

package/src/types.ts

@@ -25,6 +25,21 @@ export enum CliOptionKind {
   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 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.
  */
@@ -65,6 +80,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;
 }
 
 /**

package/src/validate.ts

@@ -4,6 +4,7 @@ This module validates CLI schemas before execution.
 
 import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
+import { validateFormatValue } from "./formats.ts";
 import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 import {
   type CliLeaf,
@@ -11,6 +12,7 @@ import {
   CliOptionKind,
   type CliProgram,
   CliSchemaValidationError,
+  CliValueFormat,
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
@@ -226,6 +228,58 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
         `Option '${opt.name}' on '${scopeKey}': choices is only valid for Enum kind`,
       );
     }
+
+    if (opt.format !== undefined || opt.pattern !== undefined || opt.default !== undefined) {
+      validateOptionValueMetadata(scopeKey, opt);
+    }
+  }
+}
+
+function validateOptionValueMetadata(scopeKey: string, opt: import("./types.ts").CliOption): void {
+  const label = `${scopeKey}/${opt.name}`;
+
+  if (opt.default !== undefined) {
+    if (opt.kind === CliOptionKind.Presence) {
+      throw new CliSchemaValidationError(`default is not valid on presence option ${label}`);
+    }
+    if (opt.required) {
+      throw new CliSchemaValidationError(`default cannot be set on required option ${label}`);
+    }
+  }
+
+  if (opt.format !== undefined && opt.pattern !== undefined) {
+    throw new CliSchemaValidationError(
+      `Option ${label}: format and pattern are mutually exclusive`,
+    );
+  }
+
+  if (opt.format !== undefined) {
+    if (opt.kind !== CliOptionKind.String) {
+      throw new CliSchemaValidationError(`Option ${label}: format is only valid on String kind`);
+    }
+    if (!Object.values(CliValueFormat).includes(opt.format)) {
+      throw new CliSchemaValidationError(`Option ${label}: unknown format '${opt.format}'`);
+    }
+  }
+
+  if (opt.pattern !== undefined) {
+    if (opt.kind !== CliOptionKind.String) {
+      throw new CliSchemaValidationError(`Option ${label}: pattern is only valid on String kind`);
+    }
+    try {
+      new RegExp(opt.pattern);
+    } catch {
+      throw new CliSchemaValidationError(`Option ${label}: invalid pattern regex`);
+    }
+  }
+
+  if (opt.default !== undefined) {
+    try {
+      validateFormatValue(opt.default, opt.format, opt.pattern);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new CliSchemaValidationError(`Option ${label}: invalid default: ${msg}`);
+    }
   }
 }