argsbarg 3.4.2 → 3.6.0

package/src/parse.ts

@@ -7,12 +7,12 @@ It keeps handler dispatch and help on one parser so the CLI behavior stays consi
 across every entry path.
 */
 
-import { CliContext } from "./context.ts";
+import { formatValidationError, validateFormatValue } from "./formats.ts";
 import {
-  type CliLeaf,
-  CliNode,
   CliFallbackMode,
-  CliOption,
+  type CliLeaf,
+  type CliNode,
+  type CliOption,
   CliOptionKind,
   isCliLeaf,
   isCliRouter,
@@ -191,17 +191,30 @@ function consumeOptions(
 
     if (tok === "--") {
       idx += 1;
-      return { report: { err: null, stoppedOnUnknown: false, sawDoubleDash: true }, nextIndex: idx };
+      return {
+        report: { err: null, stoppedOnUnknown: false, sawDoubleDash: true },
+        nextIndex: idx,
+      };
     }
 
     if (tok.startsWith("--")) {
       const err = consumeLong(tok);
-      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
-      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+      if (err === "")
+        return {
+          report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false },
+          nextIndex: idx,
+        };
+      if (err)
+        return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
     } else {
       const err = consumeShort(tok);
-      if (err === "") return { report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false }, nextIndex: idx };
-      if (err) return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
+      if (err === "")
+        return {
+          report: { err: null, stoppedOnUnknown: true, sawDoubleDash: false },
+          nextIndex: idx,
+        };
+      if (err)
+        return { report: { err, stoppedOnUnknown: false, sawDoubleDash: false }, nextIndex: idx };
     }
   }
 
@@ -212,7 +225,7 @@ function consumeOptions(
 
 /** Merges option defs from the program root along the routed command path. */
 export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
-  let defs = [...(root.options ?? [])];
+  const defs = [...(root.options ?? [])];
   let node: CliNode = root;
 
   for (const seg of path) {
@@ -343,7 +356,16 @@ function finishLeaf(
     }
   }
 
-  return { kind: ParseKind.Ok, path, opts, args, helpExplicit: false, helpPath: [], errorMsg: "", errorHelpPath: [] };
+  return {
+    kind: ParseKind.Ok,
+    path,
+    opts,
+    args,
+    helpExplicit: false,
+    helpPath: [],
+    errorMsg: "",
+    errorHelpPath: [],
+  };
 }
 
 // ── Main Parser ───────────────────────────────────────────────────────────────
@@ -414,7 +436,16 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       cmdName = root.fallbackCommand;
       node = findChild(root.commands, cmdName);
       if (!node) {
-        return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+        return {
+          kind: ParseKind.Error,
+          path: [],
+          opts: {},
+          args: [],
+          helpExplicit: false,
+          helpPath: [],
+          errorMsg: `Unknown command: ${cmdName}`,
+          errorHelpPath: path,
+        };
       }
     } else {
       return helpResult([], false);
@@ -428,16 +459,26 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       i += 1;
       node = childPick;
     } else {
+      const fallbackCommand = root.fallbackCommand;
       const canRouteUnknown =
-        root.fallbackCommand !== undefined &&
+        fallbackCommand !== undefined &&
         ((root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.MissingOrUnknown ||
           (root.fallbackMode ?? CliFallbackMode.MissingOnly) === CliFallbackMode.UnknownOnly);
 
       if (canRouteUnknown) {
-        cmdName = root.fallbackCommand!;
+        cmdName = fallbackCommand;
         node = findChild(root.commands, cmdName);
         if (!node) {
-          return { kind: ParseKind.Error, path: [], opts: {}, args: [], helpExplicit: false, helpPath: [], errorMsg: `Unknown command: ${cmdName}`, errorHelpPath: path };
+          return {
+            kind: ParseKind.Error,
+            path: [],
+            opts: {},
+            args: [],
+            helpExplicit: false,
+            helpPath: [],
+            errorMsg: `Unknown command: ${cmdName}`,
+            errorHelpPath: path,
+          };
         }
       } else {
         cmdName = peek;
@@ -451,7 +492,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
             args: [],
             helpExplicit: false,
             helpPath: [],
-            errorMsg: forcePositionals ? `Expected subcommand but got positional: ${cmdName}` : `Unknown command: ${cmdName}`,
+            errorMsg: forcePositionals
+              ? `Expected subcommand but got positional: ${cmdName}`
+              : `Unknown command: ${cmdName}`,
             errorHelpPath: path,
           };
         }
@@ -460,7 +503,19 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
   }
 
   path.push(cmdName);
-  let current = node!;
+  if (!node) {
+    return {
+      kind: ParseKind.Error,
+      path,
+      opts: {},
+      args: [],
+      helpExplicit: false,
+      helpPath: [],
+      errorMsg: `Unknown command: ${cmdName}`,
+      errorHelpPath: path,
+    };
+  }
+  let current = node;
 
   // Walk the command tree
   while (true) {
@@ -508,7 +563,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       if (!isCliLeaf(current)) {
         return helpResult(path, false);
       }
-      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+      return finishLeaf(
+        current,
+        i,
+        argv,
+        path,
+        opts,
+        collectOptionDefs(root, path),
+        forcePositionals,
+      );
     }
 
     const tok = argv[i];
@@ -542,10 +605,10 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         fb !== undefined &&
         (fm === CliFallbackMode.MissingOrUnknown || fm === CliFallbackMode.UnknownOnly);
 
-      if (canRouteUnknown) {
-        const fbNode = findChild(current.commands, fb!);
+      if (canRouteUnknown && fb !== undefined) {
+        const fbNode = findChild(current.commands, fb);
         if (fbNode) {
-          path.push(fb!);
+          path.push(fb);
           current = fbNode;
           continue;
         }
@@ -558,7 +621,9 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
         args: [],
         helpExplicit: false,
         helpPath: [],
-        errorMsg: forcePositionals ? `Expected subcommand but got positional: ${tok}` : `Unknown subcommand: ${tok}`,
+        errorMsg: forcePositionals
+          ? `Expected subcommand but got positional: ${tok}`
+          : `Unknown subcommand: ${tok}`,
         errorHelpPath: path,
       };
     }
@@ -566,7 +631,15 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     if (!isCliLeaf(current)) {
       return helpResult(path, false);
     }
-    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals);
+    return finishLeaf(
+      current,
+      i,
+      argv,
+      path,
+      opts,
+      collectOptionDefs(root, path),
+      forcePositionals,
+    );
   }
 }
 
@@ -578,7 +651,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
 export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
-  let defs = [...(root.options ?? [])];
+  const defs = [...(root.options ?? [])];
   let node: CliNode = root;
 
   for (const seg of pr.path) {
@@ -611,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,
@@ -626,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 {
@@ -669,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/runtime.ts

@@ -2,26 +2,29 @@
 This module runs parsed commands, help, errors, completion, and leaf handlers.
 */
 
-import { resolveCapabilities } from "./capabilities.ts";
 import { builtinInterceptRoot, dispatchBuiltin } from "./builtins/dispatch.ts";
 import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
-import type { CliRouter } from "./types.ts";
-import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
+import { resolveCapabilities } from "./capabilities.ts";
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
-import { parse, postParseValidate, ParseKind } from "./parse.ts";
+import { ParseKind, parse, postParseValidate } from "./parse.ts";
+import type { CliRouter } from "./types.ts";
+import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
   return cliParseRoot(program);
 }
 
-export async function cliRun(program: CliProgram, argv: string[] = process.argv.slice(2)): Promise<never> {
+export async function cliRun(
+  program: CliProgram,
+  argv: string[] = process.argv.slice(2),
+): Promise<never> {
   try {
     cliValidateProgram(program);
   } catch (err) {
     if (err instanceof Error) {
-      process.stderr.write(err.message + "\n");
+      process.stderr.write(`${err.message}\n`);
     } else {
       process.stderr.write("Invalid CLI definition.\n");
     }
@@ -31,12 +34,16 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   const caps = resolveCapabilities(program);
 
   if (argv.length >= 1 && argv[0] === "mcp" && !caps.mcp) {
-    process.stderr.write("MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n");
+    process.stderr.write(
+      "MCP is not enabled. Set mcpServer: { enabled: true } on the program root.\n",
+    );
     process.exit(1);
   }
 
   if (argv.length >= 1 && argv[0] === "install" && !caps.install) {
-    process.stderr.write("install is disabled. Remove install.enabled: false from the program root.\n");
+    process.stderr.write(
+      "install is disabled. Remove install.enabled: false from the program root.\n",
+    );
     process.exit(1);
   }
 
@@ -75,13 +82,16 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
   if (pr.kind === "error") {
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;
-    process.stderr.write(msg + "\n");
+    process.stderr.write(`${msg}\n`);
     process.stderr.write(cliHelpRender(cliPresentationRoot(program), pr.errorHelpPath, true));
     process.exit(1);
   }
 
   if (pr.kind === ParseKind.Ok) {
-    await dispatchBuiltin(program, pr, { isLeafCompletionIntercept, parseRoot: completionParseRoot });
+    await dispatchBuiltin(program, pr, {
+      isLeafCompletionIntercept,
+      parseRoot: completionParseRoot,
+    });
   }
 
   let current: CliNode = parseRoot;
@@ -109,7 +119,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(0);
   } catch (err) {
     if (err instanceof Error) {
-      process.stderr.write(err.message + "\n");
+      process.stderr.write(`${err.message}\n`);
     }
     process.exit(1);
   }
@@ -118,7 +128,7 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
 export function cliErrWithHelp(ctx: CliContext, msg: string): never {
   const color = process.stderr.isTTY;
   const line = color ? `\u001B[31m${msg}\u001B[0m` : msg;
-  process.stderr.write(line + "\n");
+  process.stderr.write(`${line}\n`);
   process.stderr.write(cliHelpRender(cliPresentationRoot(ctx.program), ctx.commandPath, true));
   process.exit(1);
 }

package/src/schema.ts

@@ -2,10 +2,16 @@
 This module serializes the CLI schema tree to JSON for machine-readable introspection.
 */
 
-import { type CliNode, type CliProgram, isCliLeaf, isCliRouter, leafOutputSchema } from "./types.ts";
-import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
+import { type CliSchemaExport, exportPresentationBuiltins } from "./builtins/export.ts";
 import { cliResolveNotes } from "./help.ts";
 import { visibleOptions } from "./hidden.ts";
+import {
+  type CliNode,
+  type CliProgram,
+  isCliLeaf,
+  isCliRouter,
+  leafOutputSchema,
+} from "./types.ts";
 
 const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
 
@@ -60,8 +66,8 @@ function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
 /** Resolves `{argsbarg:program}` in exported notes using the root program key. */
 function resolveSchemaNotes(node: CliSchemaExport, appKey: string): CliSchemaExport {
   const out: CliSchemaExport = { ...node };
-  if ((out.notes ?? "").length > 0) {
-    out.notes = cliResolveNotes(out.notes!, appKey);
+  if ((out.notes ?? "").length > 0 && out.notes !== undefined) {
+    out.notes = cliResolveNotes(out.notes, appKey);
   }
   if (out.commands) {
     out.commands = out.commands.map((ch) => resolveSchemaNotes(ch, appKey));
@@ -83,7 +89,7 @@ export function cliSchemaExport(root: CliProgram): CliSchemaExport {
 }
 
 export function cliSchemaJson(root: CliProgram): string {
-  return JSON.stringify(cliSchemaExport(root), null, 2) + "\n";
+  return `${JSON.stringify(cliSchemaExport(root), null, 2)}\n`;
 }
 
 export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -3,9 +3,9 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 */
 
 import { generateApiGuide } from "../docs/api-guide.ts";
+import { collectMcpTools, type McpToolDef, sanitizeToolSegment } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
-import { collectMcpTools, sanitizeToolSegment, type McpToolDef } from "../mcp/tools.ts";
-import { CliProgram, CliOptionKind } from "../types.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
 
 export type SkillTarget = "cursor" | "claude";
 
@@ -18,7 +18,7 @@ export interface SkillBundle {
 /** Truncates text to maxLen with ellipsis. */
 function truncate(text: string, maxLen: number): string {
   if (text.length <= maxLen) return text;
-  return text.slice(0, maxLen - 1) + "…";
+  return `${text.slice(0, maxLen - 1)}…`;
 }
 
 /** Builds third-person skill description for YAML frontmatter. */
@@ -54,7 +54,7 @@ function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   }
   const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
   for (const e of enums) {
-    line += ` (\`--${e.name}\`: ${e.choices!.join(" | ")})`;
+    line += ` (\`--${e.name}\`: ${e.choices?.join(" | ")})`;
   }
   const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
   if (varargs.length > 0) {

package/src/skill/install.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CliProgram } from "../types.ts";
+import type { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
 
@@ -25,7 +25,11 @@ function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean):
 }
 
 /** Writes SKILL.md and reference.md; returns changed file paths. */
-export function cliSkillInstall(root: CliProgram, target: SkillTarget, opts: SkillInstallOpts): string[] {
+export function cliSkillInstall(
+  root: CliProgram,
+  target: SkillTarget,
+  opts: SkillInstallOpts,
+): string[] {
   const bundle = generateSkillBundle(root, target);
   const { skillMd, referenceMd } = applySkillInstallHints(root, bundle.skillMd, bundle.referenceMd);
   const dir = resolveSkillDir(target, bundle.dirName, opts.global ?? false);

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

@@ -3,17 +3,19 @@ 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,
   type CliNode,
-  type CliProgram,
   CliOptionKind,
+  type CliProgram,
   CliSchemaValidationError,
+  CliValueFormat,
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
-import { resolveMcpSchemaUri } from "./mcp/tools.ts";
-import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
 
 /** Validates `docs` configuration on the program root. */
 function validateDocsConfig(docs: import("./types.ts").CliDocsConfig): void {
@@ -93,17 +95,17 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const rogue = node as CliProgram;
     if (rogue.mcpServer !== undefined) {
       throw new CliSchemaValidationError(
-        "mcpServer is only supported on the program root (not on " + node.key + ")",
+        `mcpServer is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.install !== undefined) {
       throw new CliSchemaValidationError(
-        "install is only supported on the program root (not on " + node.key + ")",
+        `install is only supported on the program root (not on ${node.key})`,
       );
     }
     if (rogue.docs !== undefined) {
       throw new CliSchemaValidationError(
-        "docs is only supported on the program root (not on " + node.key + ")",
+        `docs is only supported on the program root (not on ${node.key})`,
       );
     }
   }
@@ -115,9 +117,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const outputSchema = node.outputSchema;
     const legacyOutputSchema = node.mcpTool?.outputSchema;
     if (outputSchema !== undefined && legacyOutputSchema !== undefined) {
-      throw new CliSchemaValidationError(
-        "Set outputSchema on the leaf only, not under mcpTool",
-      );
+      throw new CliSchemaValidationError("Set outputSchema on the leaf only, not under mcpTool");
     }
     const resolved = outputSchema ?? legacyOutputSchema;
     if (
@@ -132,7 +132,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     const rogue = node as unknown as CliLeaf;
     if (rogue.mcpTool !== undefined) {
       throw new CliSchemaValidationError(
-        "mcpTool is only supported on leaf commands (not on " + node.key + ")",
+        `mcpTool is only supported on leaf commands (not on ${node.key})`,
       );
     }
   }
@@ -160,9 +160,7 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     }
 
     if (node.fallbackMode !== undefined && node.fallbackCommand === undefined) {
-      throw new CliSchemaValidationError(
-        `fallbackMode requires fallbackCommand on '${node.key}'`,
-      );
+      throw new CliSchemaValidationError(`fallbackMode requires fallbackCommand on '${node.key}'`);
     }
 
     if (node.fallbackCommand !== undefined) {
@@ -230,13 +228,70 @@ 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}`);
+    }
   }
 }
 
-function validatePositionals(scopeKey: string, positionals: import("./types.ts").CliPositional[]): void {
+function validatePositionals(
+  scopeKey: string,
+  positionals: import("./types.ts").CliPositional[],
+): void {
   for (const p of positionals) {
     if (p.argMin !== undefined && p.argMin < 0) {
-      throw new CliSchemaValidationError(`argMin must be >= 0 for positional ${scopeKey}/${p.name}`);
+      throw new CliSchemaValidationError(
+        `argMin must be >= 0 for positional ${scopeKey}/${p.name}`,
+      );
     }
     if (p.argMax !== undefined && p.argMax < 0) {
       throw new CliSchemaValidationError(
@@ -262,7 +317,11 @@ function validatePositionals(scopeKey: string, positionals: import("./types.ts")
   }
 
   for (let idx = 0; idx < positionals.length; idx++) {
-    const { argMax = 1 } = positionals[idx]!;
+    const positional = positionals[idx];
+    if (!positional) {
+      continue;
+    }
+    const { argMax = 1 } = positional;
     if (argMax === 0 && idx + 1 < positionals.length) {
       throw new CliSchemaValidationError(
         `Unlimited positional (argMax == 0) must be last in scope ${scopeKey}`,