argsbarg 3.5.0 → 3.6.1

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