@silvery/commander 0.2.0 → 0.3.0

package/README.md

@@ -32,6 +32,66 @@ const program = new Command("myapp").description("My CLI tool")
 colorizeHelp(program) // applies recursively to all subcommands
 ```
 
+## Presets
+
+Pre-built validators for common CLI argument patterns. Each preset implements [Standard Schema v1](https://github.com/standard-schema/standard-schema) and works with Commander's `.option()` or standalone.
+
+```typescript
+import { createCLI, port, csv, int, url, oneOf } from "@silvery/commander"
+
+const cli = createCLI("deploy")
+  .option("-p, --port <n>", "Port", port)           // number (1-65535, validated)
+  .option("-r, --retries <n>", "Retries", int)      // number (integer)
+  .option("--tags <t>", "Tags", csv)                // string[]
+  .option("--callback <url>", "Callback", url)      // string (validated URL)
+  .option("-e, --env <e>", "Env", oneOf(["dev", "staging", "prod"]))  // "dev" | "staging" | "prod"
+```
+
+### Standalone usage
+
+Presets also work outside Commander for validating env vars, config files, etc. Import from the `@silvery/commander/parse` subpath for tree-shaking:
+
+```typescript
+import { port, csv, oneOf } from "@silvery/commander/parse"
+
+// .parse() — returns value or throws
+const dbPort = port.parse(process.env.DB_PORT ?? "5432")  // 3000
+
+// .safeParse() — returns result object, never throws
+const result = port.safeParse("abc")
+// { success: false, issues: [{ message: 'Expected port (1-65535), got "abc"' }] }
+
+// Standard Schema ~standard.validate() also available
+const validated = port["~standard"].validate("8080")
+// { value: 8080 }
+```
+
+### Available presets
+
+| Preset | Type | Validation |
+| ------ | ---- | ---------- |
+| `int` | `number` | Integer (coerced from string) |
+| `uint` | `number` | Unsigned integer (>= 0) |
+| `float` | `number` | Any finite number (rejects NaN) |
+| `port` | `number` | Integer 1-65535 |
+| `url` | `string` | Valid URL (via `URL` constructor) |
+| `path` | `string` | Non-empty string |
+| `csv` | `string[]` | Comma-separated, trimmed, empty filtered |
+| `json` | `unknown` | Parsed JSON |
+| `bool` | `boolean` | true/false/yes/no/1/0 (case-insensitive) |
+| `date` | `Date` | Valid date string |
+| `email` | `string` | Basic email validation (has @ and .) |
+| `regex` | `RegExp` | Valid regex pattern |
+
+### Factory presets
+
+```typescript
+import { intRange, oneOf } from "@silvery/commander"
+
+intRange(1, 100)       // Preset<number> — integer within bounds
+oneOf(["a", "b", "c"]) // Preset<"a" | "b" | "c"> — enum from values
+```
+
 ## Custom parser type inference
 
 When `.option()` is called with a parser function as the third argument, the return type is inferred:
@@ -49,9 +109,9 @@ Default values can be passed as the fourth argument:
 .option("-p, --port <n>", "Port", parseInt, 8080) // → port: number (defaults to 8080)
 ```
 
-## Zod schema validation
+## Standard Schema validation
 
-Pass a [Zod](https://zod.dev) schema as the third argument for combined parsing, validation, and type inference:
+Pass any [Standard Schema v1](https://github.com/standard-schema/standard-schema) compatible schema as the third argument for combined parsing, validation, and type inference. This works with Zod (>=3.24), Valibot (>=1.0), ArkType (>=2.0), and any other library implementing the standard:
 
 ```typescript
 import { z } from "zod"
@@ -71,7 +131,7 @@ const cli = createCLI("deploy")
 // → tags: string[] (transformed)
 ```
 
-Zod is an optional peer dependency -- duck-typed at runtime, never imported at the top level. If Zod validation fails, the error is formatted as a Commander-style error message.
+Schema libraries are optional peer dependencies -- detected at runtime via the Standard Schema `~standard` interface, never imported at the top level. A legacy fallback supports older Zod versions (pre-3.24) that don't implement Standard Schema yet.
 
 ## Typed action handlers
 
@@ -117,11 +177,12 @@ Chain `.env()` to set an environment variable fallback for the last-added option
 | ---------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
 | Type inference         | 1536-line .d.ts with recursive generic accumulation | ~120 lines using TS 5.4+ const type params + template literals  |
 | Custom parser types    | Yes (.option with parseFloat -> number)             | Yes (parser return type inference)                              |
-| Zod schema support     | No                                                  | Yes (parse + validate + infer from Zod schemas)                 |
+| Standard Schema        | No                                                  | Yes (Zod, Valibot, ArkType, or any Standard Schema v1 library) |
+| Built-in presets       | No                                                  | Yes (port, int, csv, url, oneOf, etc.)                          |
 | Typed action handlers  | Yes (full signature inference)                      | Yes (arguments + options)                                       |
 | Choices narrowing      | Via .addOption()                                    | Via .optionWithChoices()                                        |
 | Colorized help         | Not included                                        | Built-in via Commander's native style hooks                     |
-| Package size           | Types only (25 lines runtime)                       | Types + colorizer + Zod bridge (~300 lines, zero required deps) |
+| Package size           | Types only (25 lines runtime)                       | Types + colorizer + schemas (~500 lines, zero required deps)    |
 | Installation           | Separate package alongside commander                | Single package, re-exports Commander                            |
 | Negated flags (--no-X) | Partial                                             | Key extraction + boolean type inference                         |
 
@@ -129,6 +190,7 @@ Chain `.env()` to set an environment variable fallback for the last-added option
 
 - [Commander.js](https://github.com/tj/commander.js) by TJ Holowaychuk and contributors -- the underlying CLI framework
 - [@commander-js/extra-typings](https://github.com/commander-js/extra-typings) -- inspired the type inference approach; our implementation uses modern TypeScript features (const type parameters, template literal types) to achieve similar results in fewer lines
+- [Standard Schema](https://github.com/standard-schema/standard-schema) -- universal schema interop protocol for type-safe validation
 - [@silvery/ansi](https://github.com/beorn/silvery/tree/main/packages/ansi) -- optional ANSI color detection for respecting NO_COLOR/FORCE_COLOR/terminal capabilities
 - Uses Commander's built-in `configureHelp()` style hooks (added in Commander 12) for colorization
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/commander",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -21,7 +21,8 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./parse": "./src/presets.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -30,7 +31,9 @@
     "@commander-js/extra-typings": ">=12.0.0",
     "@silvery/ansi": ">=0.1.0",
     "commander": ">=12.0.0",
-    "zod": ">=3.0.0"
+    "zod": ">=3.0.0",
+    "valibot": ">=1.0.0",
+    "arktype": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "commander": {
@@ -44,6 +47,12 @@
     },
     "zod": {
       "optional": true
+    },
+    "valibot": {
+      "optional": true
+    },
+    "arktype": {
+      "optional": true
     }
   },
   "engines": {

package/src/index.ts

@@ -4,6 +4,11 @@ export type { OptionValues } from "commander"
 
 // Re-export typed CLI
 export { TypedCommand, createCLI } from "./typed.ts"
+export type { StandardSchemaV1 } from "./typed.ts"
+
+// Re-export presets
+export { int, uint, float, port, url, path, csv, json, bool, date, email, regex, intRange, oneOf } from "./presets.ts"
+export type { Preset } from "./presets.ts"
 
 /**
  * Commander.js help colorization using ANSI escape codes.

package/src/presets.ts

@@ -0,0 +1,181 @@
+/**
+ * Pre-built Standard Schema v1 presets for common CLI argument patterns.
+ *
+ * Zero dependencies — validation is manual, no Zod/Valibot/ArkType required.
+ * Each preset implements Standard Schema v1 for interop with any schema library,
+ * plus standalone `.parse()` and `.safeParse()` convenience methods.
+ *
+ * @example
+ * ```ts
+ * import { createCLI, port, csv, int, url, oneOf } from "@silvery/commander"
+ *
+ * const cli = createCLI("deploy")
+ *   .option("-p, --port <n>", "Port", port)           // number (1-65535)
+ *   .option("-r, --retries <n>", "Retries", int)      // number (integer)
+ *   .option("--tags <t>", "Tags", csv)                // string[]
+ *   .option("--callback <url>", "Callback", url)      // string (validated URL)
+ *   .option("-e, --env <e>", "Env", oneOf(["dev", "staging", "prod"]))
+ *
+ * // Standalone usage (outside Commander)
+ * port.parse("3000")       // 3000
+ * port.safeParse("abc")    // { success: false, issues: [{ message: "..." }] }
+ * ```
+ */
+
+import type { StandardSchemaV1 } from "./typed.ts"
+
+/** A Standard Schema v1 preset with standalone parse/safeParse methods. */
+export interface Preset<T> extends StandardSchemaV1<T> {
+  /** Parse and validate a value, throwing on failure. */
+  parse(value: unknown): T
+  /** Parse and validate a value, returning a result object. */
+  safeParse(value: unknown): { success: true; value: T } | { success: false; issues: Array<{ message: string }> }
+}
+
+function createPreset<T>(vendor: string, validate: (value: unknown) => T): Preset<T> {
+  const schema: Preset<T> = {
+    "~standard": {
+      version: 1,
+      vendor,
+      validate: (value) => {
+        try {
+          return { value: validate(value) }
+        } catch (e: any) {
+          return { issues: [{ message: e.message }] }
+        }
+      },
+    },
+    parse(value: unknown): T {
+      const result = schema["~standard"].validate(value)
+      if ("issues" in result) throw new Error(result.issues[0]?.message ?? "Validation failed")
+      return result.value
+    },
+    safeParse(value: unknown) {
+      const result = schema["~standard"].validate(value)
+      if ("issues" in result) return { success: false as const, issues: [...result.issues] }
+      return { success: true as const, value: result.value }
+    },
+  }
+  return schema
+}
+
+const VENDOR = "@silvery/commander"
+
+/** Integer (coerced from string). */
+export const int = createPreset<number>(VENDOR, (v) => {
+  const s = String(v).trim()
+  if (s === "") throw new Error(`Expected integer, got "${v}"`)
+  const n = Number(s)
+  if (!Number.isInteger(n)) throw new Error(`Expected integer, got "${v}"`)
+  return n
+})
+
+/** Unsigned integer (>= 0, coerced from string). */
+export const uint = createPreset<number>(VENDOR, (v) => {
+  const s = String(v).trim()
+  if (s === "") throw new Error(`Expected unsigned integer (>= 0), got "${v}"`)
+  const n = Number(s)
+  if (!Number.isInteger(n) || n < 0) throw new Error(`Expected unsigned integer (>= 0), got "${v}"`)
+  return n
+})
+
+/** Float (coerced from string). */
+export const float = createPreset<number>(VENDOR, (v) => {
+  const s = String(v).trim()
+  if (s === "" || s === "NaN") throw new Error(`Expected number, got "${v}"`)
+  const n = Number(s)
+  if (Number.isNaN(n)) throw new Error(`Expected number, got "${v}"`)
+  return n
+})
+
+/** Port number (1-65535). */
+export const port = createPreset<number>(VENDOR, (v) => {
+  const n = Number(v)
+  if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error(`Expected port (1-65535), got "${v}"`)
+  return n
+})
+
+/** URL (validated via URL constructor). */
+export const url = createPreset<string>(VENDOR, (v) => {
+  const s = String(v)
+  try {
+    new URL(s)
+    return s
+  } catch {
+    throw new Error(`Expected valid URL, got "${v}"`)
+  }
+})
+
+/** File path (non-empty string). */
+export const path = createPreset<string>(VENDOR, (v) => {
+  const s = String(v)
+  if (!s) throw new Error("Expected non-empty path")
+  return s
+})
+
+/** Comma-separated values to string[]. */
+export const csv = createPreset<string[]>(VENDOR, (v) => {
+  return String(v)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+})
+
+/** JSON string to parsed value. */
+export const json = createPreset<unknown>(VENDOR, (v) => {
+  try {
+    return JSON.parse(String(v))
+  } catch {
+    throw new Error(`Expected valid JSON, got "${v}"`)
+  }
+})
+
+/** Boolean string ("true"/"false"/"1"/"0"/"yes"/"no"). */
+export const bool = createPreset<boolean>(VENDOR, (v) => {
+  const s = String(v).toLowerCase()
+  if (["true", "1", "yes", "y"].includes(s)) return true
+  if (["false", "0", "no", "n"].includes(s)) return false
+  throw new Error(`Expected boolean (true/false/yes/no/1/0), got "${v}"`)
+})
+
+/** Date string to Date object. */
+export const date = createPreset<Date>(VENDOR, (v) => {
+  const d = new Date(String(v))
+  if (isNaN(d.getTime())) throw new Error(`Expected valid date, got "${v}"`)
+  return d
+})
+
+/** Email address (basic validation). */
+export const email = createPreset<string>(VENDOR, (v) => {
+  const s = String(v)
+  if (!s.includes("@") || !s.includes(".")) throw new Error(`Expected email address, got "${v}"`)
+  return s
+})
+
+/** Regex pattern string to RegExp. */
+export const regex = createPreset<RegExp>(VENDOR, (v) => {
+  try {
+    return new RegExp(String(v))
+  } catch {
+    throw new Error(`Expected valid regex, got "${v}"`)
+  }
+})
+
+/** Integer with min/max bounds (factory). */
+export function intRange(min: number, max: number): Preset<number> {
+  return createPreset<number>(VENDOR, (v) => {
+    const n = Number(v)
+    if (!Number.isInteger(n) || n < min || n > max)
+      throw new Error(`Expected integer ${min}-${max}, got "${v}"`)
+    return n
+  })
+}
+
+/** Enum from a fixed set of string values (factory). */
+export function oneOf<const T extends readonly string[]>(values: T): Preset<T[number]> {
+  return createPreset<T[number]>(VENDOR, (v) => {
+    const s = String(v)
+    if (!values.includes(s as any)) throw new Error(`Expected one of [${values.join(", ")}], got "${v}"`)
+    return s as T[number]
+  })
+}

package/src/typed.ts

@@ -99,11 +99,50 @@ type ArgType<S extends string> = S extends `<${string}>`
 /** Resolve accumulated option types for use in action handler signatures */
 export type TypedOpts<Opts> = Prettify<Opts>
 
-// --- Zod schema support (duck-typed, no import) ---
+// --- Standard Schema support (v1) ---
 
 /**
- * Duck-type interface for Zod-like schemas.
- * Avoids importing zod — it's an optional peer dependency.
+ * Standard Schema v1 interface — the universal schema interop protocol.
+ * Supports any schema library that implements Standard Schema (Zod >=3.24,
+ * Valibot >=1.0, ArkType >=2.0, etc.).
+ *
+ * Inlined to avoid any dependency on @standard-schema/spec.
+ * See: https://github.com/standard-schema/standard-schema
+ */
+export interface StandardSchemaV1<T = unknown> {
+  readonly "~standard": {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (
+      value: unknown,
+    ) => { value: T } | { issues: ReadonlyArray<{ message: string; path?: ReadonlyArray<unknown> }> }
+  }
+}
+
+/** Type-level extraction: infer the output type from a Standard Schema */
+type InferStandardSchema<S> = S extends StandardSchemaV1<infer T> ? T : never
+
+/** Runtime check: is this value a Standard Schema v1 object? */
+function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  return typeof value === "object" && value !== null && "~standard" in (value as any)
+}
+
+/** Wrap a Standard Schema as a Commander parser function */
+function standardSchemaParser<T>(schema: StandardSchemaV1<T>): (value: string) => T {
+  return (value: string) => {
+    const result = schema["~standard"].validate(value)
+    if ("issues" in result) {
+      const msg = result.issues.map((i) => i.message).join(", ")
+      throw new Error(msg)
+    }
+    return result.value
+  }
+}
+
+// --- Legacy Zod support (pre-3.24, no ~standard) ---
+
+/**
+ * Duck-type interface for older Zod schemas that don't implement Standard Schema.
  * Any object with `parse(value: string) => T` and `_def` qualifies.
  */
 interface ZodLike<T = any> {
@@ -114,18 +153,19 @@ interface ZodLike<T = any> {
 /** Type-level extraction: if Z is a Zod schema, infer its output type */
 type InferZodOutput<Z> = Z extends { parse(value: unknown): infer T; _def: unknown } ? T : never
 
-/** Runtime check: is this value a Zod-like schema? */
-function isZodSchema(value: unknown): value is ZodLike {
+/** Runtime check: is this value a legacy Zod-like schema (without Standard Schema)? */
+function isLegacyZodSchema(value: unknown): value is ZodLike {
   return (
     typeof value === "object" &&
     value !== null &&
     typeof (value as any).parse === "function" &&
-    "_def" in (value as any)
+    "_def" in (value as any) &&
+    !("~standard" in (value as any))
   )
 }
 
-/** Wrap a Zod schema as a Commander parser function */
-function zodParser<T>(schema: ZodLike<T>): (value: string) => T {
+/** Wrap a legacy Zod schema as a Commander parser function */
+function legacyZodParser<T>(schema: ZodLike<T>): (value: string) => T {
   return (value: string) => {
     try {
       return schema.parse(value)
@@ -173,12 +213,19 @@ export class TypedCommand<Opts = {}, Args extends any[] = []> {
   /**
    * Add an option with type inference.
    *
-   * Supports four overload patterns:
+   * Supports five overload patterns:
    * 1. `.option(flags, description?)` — type inferred from flags syntax
    * 2. `.option(flags, description, defaultValue)` — removes `undefined` from type
    * 3. `.option(flags, description, parser, defaultValue?)` — type inferred from parser return type
-   * 4. `.option(flags, description, zodSchema)` — type inferred from Zod schema output
+   * 4. `.option(flags, description, standardSchema)` — type inferred from Standard Schema output
+   * 5. `.option(flags, description, zodSchema)` — type inferred from Zod schema output (legacy, pre-3.24)
    */
+  option<const F extends string, S extends StandardSchemaV1>(
+    flags: F,
+    description: string,
+    schema: S,
+  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: InferStandardSchema<S> }, Args>
+
   option<const F extends string, Z extends ZodLike>(
     flags: F,
     description: string,
@@ -199,8 +246,10 @@ export class TypedCommand<Opts = {}, Args extends any[] = []> {
   ): TypedCommand<AddOption<Opts, F, D>, Args>
 
   option(flags: string, description?: string, parseArgOrDefault?: any, defaultValue?: any): any {
-    if (isZodSchema(parseArgOrDefault)) {
-      ;(this._cmd as any).option(flags, description ?? "", zodParser(parseArgOrDefault))
+    if (isStandardSchema(parseArgOrDefault)) {
+      ;(this._cmd as any).option(flags, description ?? "", standardSchemaParser(parseArgOrDefault))
+    } else if (isLegacyZodSchema(parseArgOrDefault)) {
+      ;(this._cmd as any).option(flags, description ?? "", legacyZodParser(parseArgOrDefault))
     } else if (typeof parseArgOrDefault === "function") {
       ;(this._cmd as any).option(flags, description ?? "", parseArgOrDefault, defaultValue)
     } else {