argsbarg 3.4.2 → 3.6.0

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.test.ts

@@ -1,8 +1,8 @@
 import { expect, test } from "bun:test";
+import { cliSchemaExport } from "../schema.ts";
 import type { CliProgram } from "../types.ts";
 import { CliOptionKind } from "../types.ts";
 import { generateApiGuide, generateApiGuideBody } from "./api-guide.ts";
-import { cliSchemaExport } from "../schema.ts";
 
 const nestedFixture: CliProgram = {
   key: "nested.ts",
@@ -125,7 +125,7 @@ test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
     ],
   };
   const schema = cliSchemaExport(fixture);
-  expect(schema.commands![0]!.outputSchema).toEqual({
+  expect(schema.commands?.[0]?.outputSchema).toEqual({
     type: "object",
     properties: { id: { type: "string" } },
     required: ["id"],

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,9 +113,9 @@ function renderCommandNode(
 
   if ((node.options ?? []).length > 0) {
     lines.push("#### Options", "");
-    lines.push("| Option | Type | Required | Description |");
-    lines.push("| --- | --- | --- | --- |");
-    for (const opt of node.options!) {
+    lines.push("| Option | Type | Required | Format / default | Description |");
+    lines.push("| --- | --- | --- | --- | --- |");
+    for (const opt of node.options ?? []) {
       lines.push(formatOptionRow(opt));
     }
     lines.push("");
@@ -111,7 +125,7 @@ function renderCommandNode(
     lines.push("#### Positionals", "");
     lines.push("| Argument | Type | Required | Description |");
     lines.push("| --- | --- | --- | --- |");
-    for (const p of node.positionals!) {
+    for (const p of node.positionals ?? []) {
       lines.push(formatPositionalRow(p));
     }
     lines.push("");

package/src/docs/builtin.ts

@@ -1,4 +1,11 @@
-import { CliFallbackMode, CliOptionKind, type CliLeaf, type CliOption, type CliProgram, type CliRouter } from "../types.ts";
+import {
+  CliFallbackMode,
+  type CliLeaf,
+  type CliOption,
+  CliOptionKind,
+  type CliProgram,
+  type CliRouter,
+} from "../types.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
   docsEffectiveDefaultTopic,
@@ -16,7 +23,11 @@ const DOCS_SAVE_OPTION: CliOption = {
   kind: CliOptionKind.Presence,
 };
 
-function runDocsTopic(program: CliProgram, topic: string, ctx: { hasFlag(name: string): boolean }): void {
+function runDocsTopic(
+  program: CliProgram,
+  topic: string,
+  ctx: { hasFlag(name: string): boolean },
+): void {
   if (ctx.hasFlag("save")) {
     process.stdout.write(`${saveDocsTopic(program, topic)}\n`);
     return;
@@ -43,24 +54,32 @@ function docsRouterNotes(): string {
 
 /** Built-in `docs` router with bundled topic subcommands. */
 export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
-  const docs = program.docs!;
+  const docs = program.docs;
+  if (!docs) {
+    throw new Error("docs not enabled");
+  }
   const leaves: CliLeaf[] = [];
 
   for (const key of docsUserTopicKeys(docs)) {
-    const topic = docs.topics[key]!;
+    const topic = docs.topics[key];
+    if (!topic) {
+      throw new Error(`docs topic missing: ${key}`);
+    }
     leaves.push(docsLeaf(program, key, docsTopicDescription(key, topic.description)));
   }
 
   if (docsIncludesMcpTopic(program)) {
-    leaves.push(
-      docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."),
-    );
+    leaves.push(docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."));
   }
 
   leaves.push(
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
     docsLeaf(program, "api", "Print the full command reference as markdown."),
-    docsLeaf(program, "skill", "Print a reference agent SKILL, use `install --skill` for optimized."),
+    docsLeaf(
+      program,
+      "skill",
+      "Print a reference agent SKILL, use `install --skill` for optimized.",
+    ),
   );
 
   return {

package/src/docs/docs.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
 import { completionBashScript } from "../completion.ts";
 import { cliInvoke } from "../index.ts";
 import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
-import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
+import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { saveDocsTopic } from "./save.ts";
 
 let workDir: string;
@@ -64,13 +64,15 @@ test("docs reserved when enabled", () => {
 
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
-  root.docs!.topics.schema = { text: "nope" };
+  const docs = root.docs;
+  if (!docs) throw new Error("expected docs fixture");
+  docs.topics.schema = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete root.docs!.topics.schema;
-  root.docs!.topics.skill = { text: "nope" };
+  delete docs.topics.schema;
+  docs.topics.skill = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete root.docs!.topics.skill;
-  root.docs!.topics.api = { text: "nope" };
+  delete docs.topics.skill;
+  docs.topics.api = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
@@ -127,9 +129,9 @@ test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode).toBeDefined();
-  expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(
-    true,
-  );
+  expect(
+    docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme"),
+  ).toBe(true);
 });
 
 test("docs schema prints JSON", async () => {
@@ -199,6 +201,11 @@ test("generateMcpGuide includes schema URI and install targets", () => {
   expect(guide).toContain("myapp://schema");
   expect(guide).toContain("~/.cursor/mcp.json");
   expect(guide).toContain("claude_desktop_config.json");
+  expect(guide).toContain("## Installation");
+  expect(guide).toContain("## Running directly");
+  expect(guide).toContain("install --bin");
+  expect(guide).toContain("OpenAI Codex");
+  expect(guide).toContain("ChatGPT");
 });
 
 test("docs --save writes topic file", async () => {

package/src/docs/mcp-guide.ts

@@ -1,11 +1,75 @@
-import { collectOptionDefs } from "../parse.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "../install/mcp-opencode.ts";
 import {
   collectMcpTools,
+  type McpToolDef,
   mcpServerId,
   resolveMcpSchemaUri,
-  type McpToolDef,
 } from "../mcp/tools.ts";
-import { type CliProgram, CliOptionKind } from "../types.ts";
+import { collectOptionDefs } from "../parse.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
+
+/** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
+function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
+  const openCodeEntry = expectedOpenCodeMcpEntry(root);
+
+  lines.push(
+    "| OpenCode | `~/.config/opencode/*` (when `~/.config/opencode` exists) |",
+    "| OpenAI Codex | `~/.codex/config.toml` via `codex mcp add` (when `codex` is on PATH) |",
+    "| ChatGPT desktop | `chatgpt_mcp_config.json` (when ChatGPT app data exists) |",
+    "",
+    "Claude Desktop paths by platform:",
+    "",
+    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
+    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
+    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
+    "",
+    "ChatGPT desktop JSON (when auto-installed):",
+    "",
+    "- **macOS:** `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json`",
+    "- **Windows:** `%APPDATA%\\OpenAI\\ChatGPT\\chatgpt_mcp_config.json`",
+    "",
+    "Restart Claude Desktop and ChatGPT desktop after changing their config files.",
+    "",
+    "### Manual fallbacks",
+    "",
+    "**OpenCode** (no `~/.config/opencode` yet):",
+    "",
+    "```json",
+    JSON.stringify(
+      {
+        $schema: OPENCODE_CONFIG_SCHEMA,
+        mcp: { [serverId]: openCodeEntry },
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "**Codex** (`codex` not on PATH):",
+    "",
+    "```toml",
+    `[mcp_servers.${serverId}]`,
+    `command = "${root.key}"`,
+    'args = ["mcp"]',
+    "```",
+    "",
+    `Or after installing Codex CLI: \`codex mcp add ${serverId} -- ${root.key} mcp\`.`,
+    "",
+    "### ChatGPT web (Connectors)",
+    "",
+    `OpenAI's documented path for **ChatGPT web/desktop** is **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL** — not local stdio. ChatGPT does not spawn \`${root.key} mcp\` directly.`,
+    "",
+    "For local stdio, bridge and tunnel, then register the HTTPS URL in Connectors:",
+    "",
+    `1. Expose \`${root.key} mcp\` over HTTP (e.g. \`mcp-remote\`).`,
+    "2. Tunnel if needed (ngrok, Cloudflare Tunnel).",
+    "3. Add the public URL as a custom connector.",
+    "",
+    "Desktop `chatgpt_mcp_config.json` is merged when the ChatGPT app is installed; support varies by build. Use Connectors when local JSON is absent or tools do not appear.",
+    "",
+  );
+}
 
 /** Formats one exposed MCP tool for the auto-generated MCP guide. */
 function formatToolLine(root: CliProgram, tool: McpToolDef): string {
@@ -24,23 +88,36 @@ export function generateMcpGuide(root: CliProgram): string {
   const tools = collectMcpTools(root);
   const schemaUri = resolveMcpSchemaUri(root);
   const serverId = mcpServerId(root);
-  const mcp = root.mcpServer!;
+  const mcp = root.mcpServer;
+  if (!mcp) {
+    throw new Error("MCP server not enabled");
+  }
+  const caps = resolveCapabilities(root);
 
   const lines: string[] = [
     `# MCP server (${root.key})`,
     "",
     `${root.key} exposes an MCP server with features similar to the CLI.`,
     "",
-    "## Quick start",
-    "",
-    "```bash",
-    `${root.key} mcp`,
-    "```",
-    "",
-    "## Client setup",
+    "## Installation",
     "",
     "### `install --mcp`",
     "",
+  ];
+
+  if (caps.install) {
+    lines.push(
+      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`${root.key} install --bin --yes\` or \`install --all --yes\`). Host configs reference the binary by name.`,
+      "",
+    );
+  } else {
+    lines.push(
+      `The CLI binary \`${root.key}\` must already be on your PATH. Host configs reference it by name.`,
+      "",
+    );
+  }
+
+  lines.push(
     "```bash",
     `${root.key} install --mcp --yes`,
     "```",
@@ -52,18 +129,14 @@ export function generateMcpGuide(root: CliProgram): string {
     "| Cursor | `~/.cursor/mcp.json` (when `~/.cursor` exists) |",
     "| Claude Code | `~/.claude.json` |",
     "| Claude Desktop | `claude_desktop_config.json` (when Claude Desktop app data exists) |",
+  );
+
+  appendManualHostSetup(lines, root, serverId);
+
+  lines.push(
+    "### Manual `mcpServers` entry",
     "",
-    "Claude Desktop paths by platform:",
-    "",
-    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
-    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
-    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
-    "",
-    "Restart Claude Desktop after changing its config.",
-    "",
-    "### Manual entry",
-    "",
-    "Add under `mcpServers` in the host config:",
+    "For Cursor, Claude, and ChatGPT desktop JSON configs, add under `mcpServers`:",
     "",
     "```json",
     JSON.stringify(
@@ -80,7 +153,15 @@ export function generateMcpGuide(root: CliProgram): string {
     ),
     "```",
     "",
-  ];
+    "## Running directly",
+    "",
+    "Start the stdio MCP server without editing host config:",
+    "",
+    "```bash",
+    `${root.key} mcp`,
+    "```",
+    "",
+  );
 
   if (mcp.shellEnv || mcp.envFile) {
     lines.push("## Environment", "");
@@ -91,7 +172,7 @@ export function generateMcpGuide(root: CliProgram): string {
     }
     if (mcp.envFile) {
       lines.push(
-        "- **`envFile`** — loads `" + mcp.envFile + "` after shell env (overrides for its keys).",
+        `- **\`envFile\`** — loads \`${mcp.envFile}\` after shell env (overrides for its keys).`,
       );
     }
     lines.push("");
@@ -125,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/docs/resolve.ts

@@ -1,6 +1,6 @@
-import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { generateSkillBundle } from "../skill/generate.ts";
+import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { generateApiGuide } from "./api-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
@@ -31,7 +31,11 @@ export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
   if (keys.length === 0) {
     throw new Error("docs.topics must be non-empty");
   }
-  return keys[0]!;
+  const first = keys[0];
+  if (first === undefined) {
+    throw new Error("docs.topics must be non-empty");
+  }
+  return first;
 }
 
 /** Whether MCP auto-guide topic is included. */
@@ -53,7 +57,10 @@ export function docsTopicDescription(key: string, custom?: string): string {
 
 /** Markdown body for one docs topic key. */
 export function docsTopicText(program: CliProgram, topic: string): string {
-  const docs = program.docs!;
+  const docs = program.docs;
+  if (!docs) {
+    throw new Error("docs not enabled");
+  }
   if (topic === "mcp") {
     if (!docsIncludesMcpTopic(program)) {
       throw new Error("Unknown docs topic 'mcp'.");

package/src/docs/save.ts

@@ -1,8 +1,8 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 import type { CliProgram } from "../types.ts";
 import { docsTopicContent } from "./resolve.ts";
-import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
@@ -21,12 +21,20 @@ export function docsSaveGeneratedHint(program: CliProgram, topic: string): strin
 }
 
 /** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
-export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
+export function applySaveGeneratedHint(
+  program: CliProgram,
+  topic: string,
+  content: string,
+): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
   const hint = docsSaveGeneratedHint(program, topic);
-  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
+  return insertGeneratedHint(
+    content,
+    hint,
+    topic === "skill" ? { afterFrontmatter: true } : undefined,
+  );
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */

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