argsbarg 3.4.2 → 3.6.0

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

@@ -22,28 +22,20 @@ test("shouldRunHeadless is true for MCP and json", () => {
 });
 
 test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
-  expect(
-    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false),
-  ).toBe(false);
-  expect(
-    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false),
-  ).toBe(true);
+  expect(shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false)).toBe(
+    false,
+  );
+  expect(shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false)).toBe(
+    true,
+  );
 });
 
 test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
   expect(
-    shouldRunHeadlessWithYes(
-      { invocation: "cli" },
-      { yes: true, hasRequiredArgs: true },
-      false,
-    ),
+    shouldRunHeadlessWithYes({ invocation: "cli" }, { yes: true, hasRequiredArgs: true }, false),
   ).toBe(true);
   expect(
-    shouldRunHeadlessWithYes(
-      { invocation: "cli" },
-      { yes: false, hasRequiredArgs: true },
-      false,
-    ),
+    shouldRunHeadlessWithYes({ invocation: "cli" }, { yes: false, hasRequiredArgs: true }, false),
   ).toBe(false);
   expect(
     shouldRunHeadlessWithYes(

package/src/help.ts

@@ -7,8 +7,16 @@ It keeps help formatting shared across help and error paths so users see one con
 style no matter how help is reached.
 */
 
-import { CliNode, CliOption, CliOptionKind, CliPositional, CliRouter, isCliLeaf, isCliRouter } from "./types.ts";
 import { visibleOptions, visibleSubcommands } from "./hidden.ts";
+import {
+  type CliNode,
+  type CliOption,
+  CliOptionKind,
+  type CliPositional,
+  type CliRouter,
+  isCliLeaf,
+  isCliRouter,
+} from "./types.ts";
 
 // ── ANSI Style Helpers ────────────────────────────────────────────────────────
 
@@ -52,10 +60,10 @@ const style = {
 
 const kBoxTL = "\u256D"; // ╭
 const kBoxTR = "\u256E"; // ╮
-const kBoxV = "\u2502";  // │
+const kBoxV = "\u2502"; // │
 const kBoxBL = "\u2570"; // ╰
 const kBoxBR = "\u256F"; // ╯
-const kBoxH = "\u2500";  // ─
+const kBoxH = "\u2500"; // ─
 
 // ── Terminal Detection ────────────────────────────────────────────────────────
 
@@ -119,7 +127,7 @@ function wrapParagraph(text: string, width: number): string[] {
       continue;
     }
     if (cur.length + 1 + word.length <= available) {
-      cur += " " + word;
+      cur += ` ${word}`;
     } else {
       out.push(cur);
       cur = word;
@@ -166,24 +174,24 @@ function optKindLabel(k: CliOptionKind, o?: CliOption): string {
         return " <choice>";
       }
       if (choices.length <= 4) {
-        return " <" + choices.join("|") + ">";
+        return ` <${choices.join("|")}>`;
       }
-      return " <" + choices.slice(0, 3).join("|") + "|…>";
+      return ` <${choices.slice(0, 3).join("|")}|…>`;
     }
   }
 }
 
 /** Formats a flag/value option for help tables: `--name`, optional short, optional kind hint. */
 export function cliOptionLabel(o: CliOption, color: boolean): string {
-  let r = "--" + o.name + optKindLabel(o.kind, o);
-  if (o.shortName) r += ", -" + o.shortName;
+  let r = `--${o.name}${optKindLabel(o.kind, o)}`;
+  if (o.shortName) r += `, -${o.shortName}`;
   if (!color) return r;
 
   const sepIdx = r.indexOf(", ");
   if (sepIdx === -1) return style.aquaBold(r);
   const left = r.slice(0, sepIdx);
   const right = r.slice(sepIdx + 2);
-  return style.aquaBold(left) + " " + style.greenBright(right);
+  return `${style.aquaBold(left)} ${style.greenBright(right)}`;
 }
 
 /** Placeholder in `notes` for the root program key (resolved in help, schema, and docs api). */
@@ -199,9 +207,9 @@ export function cliPositionalLabel(p: CliPositional, color: boolean): string {
   const { argMin = 1, argMax = 1 } = p;
   let r: string;
   if (argMax === 1) {
-    r = argMin === 0 ? "[" + p.name + "]" : "<" + p.name + ">";
+    r = argMin === 0 ? `[${p.name}]` : `<${p.name}>`;
   } else {
-    r = argMin === 0 ? "[" + p.name + "...]" : "<" + p.name + "...>";
+    r = argMin === 0 ? `[${p.name}...]` : `<${p.name}...>`;
   }
   if (!color) return r;
   return style.aquaBold(r);
@@ -222,8 +230,8 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
   if (lines.length === 0) return [];
 
   const titleLead = color
-    ? style.gray(kBoxH + " ") + style.grayBoldTitle(title) + style.gray(" ")
-    : kBoxH + " " + title + " ";
+    ? style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ")
+    : `${kBoxH} ${title} `;
 
   let contentWidth = visibleWidth(titleLead) + 1;
   for (const line of lines) {
@@ -238,19 +246,25 @@ function renderTextBox(title: string, lines: string[], hw: number, color: boolea
   const out: string[] = [];
   out.push(
     (color ? style.gray(kBoxTL) : kBoxTL) +
-    titleLead +
-    (color ? style.gray(repeatBoxH(headerFill) + kBoxTR) : repeatBoxH(headerFill) + kBoxTR),
+      titleLead +
+      (color ? style.gray(repeatBoxH(headerFill) + kBoxTR) : repeatBoxH(headerFill) + kBoxTR),
   );
 
   for (const line of lines) {
     const padded = padVisible(line, contentWidth);
     out.push(
-      (color ? style.gray(kBoxV) : kBoxV) + " " + padded + " " + (color ? style.gray(kBoxV) : kBoxV),
+      (color ? style.gray(kBoxV) : kBoxV) +
+        " " +
+        padded +
+        " " +
+        (color ? style.gray(kBoxV) : kBoxV),
     );
   }
 
   out.push(
-    (color ? style.gray(kBoxBL + repeatBoxH(borderWidth) + kBoxBR) : kBoxBL + repeatBoxH(borderWidth) + kBoxBR),
+    color
+      ? style.gray(kBoxBL + repeatBoxH(borderWidth) + kBoxBR)
+      : kBoxBL + repeatBoxH(borderWidth) + kBoxBR,
   );
 
   return out;
@@ -265,7 +279,7 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
     labelWidth = Math.max(labelWidth, visibleWidth(row.label));
   }
 
-  const titleChunk = kBoxH + " " + title + " ";
+  const titleChunk = `${kBoxH} ${title} `;
   const minimumContentWidth = Math.max(visibleWidth(titleChunk) + 1, labelWidth + 2 + 18);
   let contentWidth = Math.max(hw - 2, minimumContentWidth);
   const descWidth = Math.max(1, contentWidth - labelWidth - 2);
@@ -274,20 +288,22 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
   for (const row of rows) {
     const wrapped = wrapText(row.description, descWidth);
     const first =
-      row.label + spaces(labelWidth - visibleWidth(row.label)) + "  " +
+      row.label +
+      spaces(labelWidth - visibleWidth(row.label)) +
+      "  " +
       (color ? style.white(wrapped[0]) : wrapped[0]);
     bodyLines.push(first);
     for (let idx = 1; idx < wrapped.length; idx++) {
       const pad = color ? style.gray(spaces(labelWidth)) : spaces(labelWidth);
-      bodyLines.push(pad + "  " + (color ? style.white(wrapped[idx]) : wrapped[idx]));
+      bodyLines.push(`${pad}  ${color ? style.white(wrapped[idx]) : wrapped[idx]}`);
     }
   }
 
   let titleLead: string;
   if (color) {
-    titleLead = style.gray(kBoxH + " ") + style.grayBoldTitle(title) + style.gray(" ");
+    titleLead = style.gray(`${kBoxH} `) + style.grayBoldTitle(title) + style.gray(" ");
   } else {
-    titleLead = kBoxH + " " + title + " ";
+    titleLead = `${kBoxH} ${title} `;
   }
 
   contentWidth = Math.max(contentWidth, visibleWidth(titleLead) + 1);
@@ -302,19 +318,25 @@ function renderTableBox(title: string, rows: HelpRow[], hw: number, color: boole
   const out: string[] = [];
   out.push(
     (color ? style.gray(kBoxTL) : kBoxTL) +
-    titleLead +
-    (color ? style.gray(repeatBoxH(headerFill) + kBoxTR) : repeatBoxH(headerFill) + kBoxTR),
+      titleLead +
+      (color ? style.gray(repeatBoxH(headerFill) + kBoxTR) : repeatBoxH(headerFill) + kBoxTR),
   );
 
   for (const line of bodyLines) {
     const padded = padVisible(line, contentWidth);
     out.push(
-      (color ? style.gray(kBoxV) : kBoxV) + " " + padded + " " + (color ? style.gray(kBoxV) : kBoxV),
+      (color ? style.gray(kBoxV) : kBoxV) +
+        " " +
+        padded +
+        " " +
+        (color ? style.gray(kBoxV) : kBoxV),
     );
   }
 
   out.push(
-    (color ? style.gray(kBoxBL + repeatBoxH(borderWidth) + kBoxBR) : kBoxBL + repeatBoxH(borderWidth) + kBoxBR),
+    color
+      ? style.gray(kBoxBL + repeatBoxH(borderWidth) + kBoxBR)
+      : kBoxBL + repeatBoxH(borderWidth) + kBoxBR,
   );
 
   return out;
@@ -332,7 +354,7 @@ function usageLines(
 ): string[] {
   let fullPath = appName;
   for (const seg of helpPath) {
-    fullPath += " " + seg;
+    fullPath += ` ${seg}`;
   }
   const usageOpts = color ? style.aquaBold("[OPTIONS]") : "[OPTIONS]";
   const usageCmd = color ? style.aquaBold("COMMAND") : "COMMAND";
@@ -341,15 +363,15 @@ function usageLines(
   const out: string[] = [];
   if (helpPath.length === 0) {
     if (hasCommands) {
-      out.push(fullPath + " " + usageOpts + " " + usageCmd + " " + usageArgs);
+      out.push(`${fullPath} ${usageOpts} ${usageCmd} ${usageArgs}`);
     } else {
-      out.push(fullPath + " " + usageOpts);
+      out.push(`${fullPath} ${usageOpts}`);
     }
     return out;
   }
-  out.push(fullPath + " " + usageOpts + (hasArgs ? (" " + usageArgs) : ""));
+  out.push(`${fullPath} ${usageOpts}${hasArgs ? ` ${usageArgs}` : ""}`);
   if (hasCommands) {
-    out.push(fullPath + " " + usageCmd + " " + usageArgs);
+    out.push(`${fullPath} ${usageCmd} ${usageArgs}`);
   }
   return out;
 }
@@ -357,12 +379,10 @@ function usageLines(
 /** Table rows for named options, including synthetic built-in rows. */
 function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
-  const helpLabel = color
-    ? style.aquaBold("--help, ") + style.greenBright("-h")
-    : "--help, -h";
+  const helpLabel = color ? style.aquaBold("--help, ") + style.greenBright("-h") : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
   for (const o of defs) {
-    const desc = o.required ? "(required) " + o.description : o.description;
+    const desc = o.required ? `(required) ${o.description}` : o.description;
     rows.push({ label: cliOptionLabel(o, color), description: desc });
   }
   return rows;
@@ -392,7 +412,7 @@ function appendNotesBox(
   if ((notes ?? "").length === 0) {
     return;
   }
-  const resolved = cliResolveNotes(notes!, appKey);
+  const resolved = cliResolveNotes(notes ?? "", appKey);
   lines.push("");
   lines.push(renderTextBox("Notes", wrapText(resolved, hw - 4), hw, color).join("\n"));
 }
@@ -401,7 +421,7 @@ function appendNotesBox(
  * Renders full help for the app root or a nested command, following `helpPath` from the root key.
  * `useStderr` is reserved for call-site consistency; width and color use stdout TTY.
  */
-export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr: boolean): string {
+export function cliHelpRender(schema: CliRouter, helpPath: string[], _useStderr: boolean): string {
   const hw = getHelpWidth();
   const color = isStdoutTTY();
 
@@ -421,7 +441,12 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(schema.options), color), hw, color);
+    const optBox = renderTableBox(
+      "Options",
+      rowsForOptions(visibleOptions(schema.options), color),
+      hw,
+      color,
+    );
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -433,7 +458,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       );
     }
     appendNotesBox(lines, schema.notes, schema.key, hw, color);
-    return lines.join("\n") + "\n\n";
+    return `${lines.join("\n")}\n\n`;
   }
 
   let layer = schema.commands ?? [];
@@ -441,13 +466,13 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
   for (const seg of helpPath) {
     const ch = layer.find((c: CliNode) => c.key === seg);
     if (!ch) {
-      return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
+      return `${color ? style.red("Unknown help path.") : "Unknown help path."}\n`;
     }
     node = ch;
     layer = isCliRouter(ch) ? ch.commands : [];
   }
   if (!node) {
-    return (color ? style.red("Unknown help path.") : "Unknown help path.") + "\n";
+    return `${color ? style.red("Unknown help path.") : "Unknown help path."}\n`;
   }
 
   const lines: string[] = [];
@@ -471,7 +496,12 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(visibleOptions(node.options), color), hw, color);
+  const optBox = renderTableBox(
+    "Options",
+    rowsForOptions(visibleOptions(node.options), color),
+    hw,
+    color,
+  );
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));
@@ -499,5 +529,5 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     appendNotesBox(lines, node.notes, schema.key, hw, color);
   }
 
-  return lines.join("\n") + "\n\n";
+  return `${lines.join("\n")}\n\n`;
 }

package/src/hidden-mcpb.test.ts

@@ -1,13 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { cliPresentationRoot, cliParseRoot } from "./builtins/presentation.ts";
+import { join } from "node:path";
 import { exportPresentationBuiltins } from "./builtins/export.ts";
+import { cliParseRoot, cliPresentationRoot } from "./builtins/presentation.ts";
 import { cliHelpRender } from "./help.ts";
-import { cliSchemaExport } from "./schema.ts";
-import { collectMcpTools } from "./mcp/tools.ts";
 import { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
+import { collectMcpTools } from "./mcp/tools.ts";
+import { cliSchemaExport } from "./schema.ts";
 import { CliOptionKind, type CliProgram } from "./types.ts";
 
 const hiddenFixture: CliProgram = {
@@ -116,7 +116,8 @@ describe("mcp bundle", () => {
     expect(manifest.manifest_version).toBe("0.3");
     expect((manifest.server as { type: string }).type).toBe("binary");
     expect((manifest.server as { entry_point: string }).entry_point).toBe("myapp");
-    const mcpConfig = (manifest.server as { mcp_config: { command: string; args: string[] } }).mcp_config;
+    const mcpConfig = (manifest.server as { mcp_config: { command: string; args: string[] } })
+      .mcp_config;
     expect(mcpConfig.command).toBe("${__dirname}/myapp");
     expect(mcpConfig.args).toEqual(["mcp"]);
     expect((manifest.compatibility as { platforms: string[] }).platforms).toEqual(["darwin"]);

package/src/hidden.ts

@@ -3,8 +3,8 @@ Filters hidden commands and options from presentation surfaces (help, schema, co
 Parsing still uses the full tree via cliParseRoot.
 */
 
-import type { CliNode, CliOption, CliRouter } from "./types.ts";
-import { isCliLeaf, isCliRouter } from "./types.ts";
+import type { CliNode, CliOption } from "./types.ts";
+import { isCliRouter } from "./types.ts";
 
 /** Options visible in help, schema, completions, and MCP tool schemas. */
 export function visibleOptions(options: CliOption[] | undefined): CliOption[] {