@silvery/commander 0.2.0 → 0.4.0

package/README.md

@@ -1,23 +1,34 @@
 # @silvery/commander
 
-Type-safe, colorized [Commander.js](https://github.com/tj/commander.js) wrapper. Infers option types from `.option()` calls using TypeScript 5.4+ const type parameters and template literal types -- no codegen, no separate type package.
+Enhanced [Commander.js](https://github.com/tj/commander.js) with auto-colorized help, Standard Schema validation, and CLI presets. Drop-in replacement -- `Command` is a subclass of Commander's `Command`.
+
+## Three layers
+
+```typescript
+// Layer 1: Enhanced Commander (auto-colorized help, Standard Schema support)
+import { Command, port, csv } from "@silvery/commander"
+
+// Layer 2: Zero-dep presets (Standard Schema, standalone use)
+import { port, csv, int } from "@silvery/commander/parse"
+
+// Layer 3: Zod + CLI presets (batteries included)
+import { Command, z } from "@silvery/commander"
+```
 
 ## Usage
 
 ```typescript
-import { createCLI } from "@silvery/commander"
+import { Command, port, csv, oneOf } from "@silvery/commander"
 
-const cli = createCLI("myapp")
-  .description("My CLI tool")
+const program = new Command("deploy")
+  .description("Deploy the application")
   .version("1.0.0")
-  .option("-v, --verbose", "Verbose output")
-  .option("-p, --port <number>", "Port to listen on", parseInt)
-  .option("-o, --output [path]", "Output path")
-  .option("--no-color", "Disable color output")
-
-cli.parse()
-const { verbose, port, output, color } = cli.opts()
-//      ^boolean   ^number  ^string|true  ^boolean
+  .option("-p, --port <n>", "Port", port) // number (1-65535)
+  .option("--tags <t>", "Tags", csv) // string[]
+  .option("-e, --env <e>", "Env", oneOf(["dev", "staging", "prod"]))
+
+program.parse()
+const opts = program.opts()
 ```
 
 Help output is automatically colorized using Commander's built-in `configureHelp()` style hooks (headings bold, flags green, commands cyan, descriptions dim, arguments yellow).
@@ -32,103 +43,125 @@ const program = new Command("myapp").description("My CLI tool")
 colorizeHelp(program) // applies recursively to all subcommands
 ```
 
-## Custom parser type inference
+## Standard Schema validation
 
-When `.option()` is called with a parser function as the third argument, the return type is inferred:
-
-```typescript
-const cli = createCLI("deploy")
-  .option("-p, --port <n>", "Port", parseInt) // → port: number
-  .option("-t, --timeout <ms>", "Timeout", Number) // → timeout: number
-  .option("--tags <items>", "Tags", (v) => v.split(",")) // → tags: string[]
-```
-
-Default values can be passed as the fourth argument:
-
-```typescript
-.option("-p, --port <n>", "Port", parseInt, 8080) // → port: number (defaults to 8080)
-```
-
-## Zod 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 to `.option()` for combined parsing, validation, and type inference. This works with the built-in presets, Zod (>=3.24), Valibot (>=1.0), ArkType (>=2.0), and any other library implementing the standard:
 
 ```typescript
+import { Command } from "@silvery/commander"
 import { z } from "zod"
 
-const cli = createCLI("deploy")
+const program = new Command("deploy")
   .option("-p, --port <n>", "Port", z.coerce.number().min(1).max(65535))
-  // → port: number (validated at parse time)
-
-  .option("-e, --env <env>", "Environment", z.enum(["dev", "staging", "prod"]))
-  // → env: "dev" | "staging" | "prod" (union type)
-
+  .option("-e, --env <env>", "Env", z.enum(["dev", "staging", "prod"]))
   .option(
     "--tags <t>",
     "Tags",
     z.string().transform((v) => v.split(",")),
   )
-// → 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
+## Zod CLI presets
 
-Action callbacks receive typed arguments and options:
+Import `z` from `@silvery/commander` for an extended Zod object with CLI-specific schemas:
 
 ```typescript
-const cli = createCLI("deploy")
-  .argument("<env>", "Target environment")
-  .argument("[tag]", "Optional deploy tag")
-  .option("-f, --force", "Force deploy")
-  .action((env, tag, opts) => {
-    // env: string, tag: string | undefined, opts: { force: boolean | undefined }
-  })
+import { Command, z } from "@silvery/commander"
+
+const program = new Command("deploy")
+  .option("-p, --port <n>", "Port", z.port) // z.coerce.number().int().min(1).max(65535)
+  .option("--tags <t>", "Tags", z.csv) // z.string().transform(...)
+  .option("-e, --env <e>", "Env", z.oneOf(["dev", "staging", "prod"]))
+  .option("-r, --retries <n>", "Retries", z.int) // z.coerce.number().int()
 ```
 
-Required arguments (`<name>`) are `string`, optional arguments (`[name]`) are `string | undefined`.
+The `z` export is tree-shakeable -- if you don't import it, Zod won't be in your bundle.
+
+Available `z` CLI presets: `z.port`, `z.int`, `z.uint`, `z.float`, `z.csv`, `z.url`, `z.path`, `z.email`, `z.date`, `z.json`, `z.bool`, `z.intRange(min, max)`, `z.oneOf(values)`.
 
-## Choices narrowing
+## Presets
 
-Use `.optionWithChoices()` to restrict an option to a fixed set of values with union type inference:
+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
-const cli = createCLI("deploy").optionWithChoices("-e, --env <env>", "Environment", ["dev", "staging", "prod"] as const)
-// → env: "dev" | "staging" | "prod" | undefined
+import { Command, port, csv, int, url, oneOf } from "@silvery/commander"
+
+const program = new Command("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"]))
+```
+
+### 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
 
-cli.parse()
-const { env } = cli.opts() // env: "dev" | "staging" | "prod" | undefined
+// .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 }
 ```
 
-Commander validates the choice at parse time and rejects invalid values.
+### 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
 
-## Environment variable support
+```typescript
+import { intRange, oneOf } from "@silvery/commander"
 
-Chain `.env()` to set an environment variable fallback for the last-added option:
+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, Commander infers the return type:
 
 ```typescript
-.option("-p, --port <n>", "Port").env("PORT")
+const program = new Command("deploy")
+  .option("-p, --port <n>", "Port", parseInt) // port: number
+  .option("-t, --timeout <ms>", "Timeout", Number) // timeout: number
+  .option("--tags <items>", "Tags", (v) => v.split(",")) // tags: string[]
 ```
 
-## Improvements over @commander-js/extra-typings
+Default values can be passed as the fourth argument:
 
-| Feature                | extra-typings                                       | @silvery/commander                                              |
-| ---------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
-| 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)                 |
-| 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) |
-| Installation           | Separate package alongside commander                | Single package, re-exports Commander                            |
-| Negated flags (--no-X) | Partial                                             | Key extraction + boolean type inference                         |
+```typescript
+.option("-p, --port <n>", "Port", parseInt, 8080) // port: number (defaults to 8080)
+```
 
 ## Credits
 
 - [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.4.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -20,25 +20,22 @@
     "src"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./parse": "./src/presets.ts"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "commander": ">=12.0.0"
+  },
   "peerDependencies": {
-    "@commander-js/extra-typings": ">=12.0.0",
     "@silvery/ansi": ">=0.1.0",
-    "commander": ">=12.0.0",
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "commander": {
-      "optional": true
-    },
-    "@commander-js/extra-typings": {
-      "optional": true
-    },
     "@silvery/ansi": {
       "optional": true
     },

package/src/colorize.ts

@@ -0,0 +1,164 @@
+/**
+ * Commander.js help colorization using ANSI escape codes.
+ *
+ * Uses Commander's built-in style hooks (styleTitle, styleOptionText, etc.)
+ * rather than regex post-processing. Works with @silvery/commander
+ * or plain commander — accepts a minimal CommandLike interface so Commander
+ * is a peer dependency, not a hard one.
+ *
+ * Zero dependencies — only raw ANSI escape codes.
+ *
+ * @example
+ * ```ts
+ * import { Command } from "@silvery/commander"
+ * import { colorizeHelp } from "@silvery/commander"
+ *
+ * const program = new Command("myapp").description("My CLI tool")
+ * colorizeHelp(program)
+ * ```
+ */
+
+// Raw ANSI escape codes — no framework dependencies.
+const RESET = "\x1b[0m"
+const BOLD = "\x1b[1m"
+const DIM = "\x1b[2m"
+const CYAN = "\x1b[36m"
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+
+/**
+ * Check if color output should be enabled.
+ * Uses @silvery/ansi detectColor() if available, falls back to basic
+ * NO_COLOR/FORCE_COLOR/isTTY checks.
+ */
+let _shouldColorize: boolean | undefined
+
+export function shouldColorize(): boolean {
+  if (_shouldColorize !== undefined) return _shouldColorize
+
+  // Try @silvery/ansi for full detection (respects NO_COLOR, FORCE_COLOR, TERM, etc.)
+  try {
+    const { detectColor } = require("@silvery/ansi") as { detectColor: (stdout: NodeJS.WriteStream) => string | null }
+    _shouldColorize = detectColor(process.stdout) !== null
+  } catch {
+    // Fallback: basic NO_COLOR / FORCE_COLOR / isTTY checks
+    if (process.env.NO_COLOR !== undefined) {
+      _shouldColorize = false
+    } else if (process.env.FORCE_COLOR !== undefined) {
+      _shouldColorize = true
+    } else {
+      _shouldColorize = process.stdout?.isTTY ?? true
+    }
+  }
+
+  return _shouldColorize
+}
+
+/** Wrap a string with ANSI codes, handling nested resets. */
+function ansi(text: string, code: string): string {
+  return `${code}${text}${RESET}`
+}
+
+/**
+ * Minimal interface for Commander's Command — avoids requiring Commander
+ * as a direct dependency. Works with both `commander` and
+ * `@silvery/commander`.
+ *
+ * Uses permissive types to ensure structural compatibility with all
+ * Commander versions, overloads, and generic instantiations.
+ */
+export interface CommandLike {
+  // biome-ignore lint: permissive to match Commander's overloaded signatures
+  configureHelp(...args: any[]): any
+  // biome-ignore lint: permissive to match Commander's overloaded signatures
+  configureOutput(...args: any[]): any
+  // biome-ignore lint: permissive to match Commander's Command[] structurally
+  readonly commands: readonly any[]
+}
+
+/** Color scheme for help output. Values are raw ANSI escape sequences. */
+export interface ColorizeHelpOptions {
+  /** ANSI code for command/subcommand names. Default: cyan */
+  commands?: string
+  /** ANSI code for --flags and -short options. Default: green */
+  flags?: string
+  /** ANSI code for description text. Default: dim */
+  description?: string
+  /** ANSI code for section headings (Usage:, Options:, etc.). Default: bold */
+  heading?: string
+  /** ANSI code for <required> and [optional] argument brackets. Default: yellow */
+  brackets?: string
+}
+
+/**
+ * Apply colorized help output to a Commander.js program and all its subcommands.
+ *
+ * Uses Commander's built-in `configureHelp()` style hooks rather than
+ * post-processing the formatted string. This approach is robust against
+ * formatting changes in Commander and handles wrapping correctly.
+ *
+ * @param program - A Commander Command instance (or compatible object)
+ * @param options - Override default ANSI color codes for each element
+ */
+export function colorizeHelp(program: CommandLike, options?: ColorizeHelpOptions): void {
+  const cmds = options?.commands ?? CYAN
+  const flags = options?.flags ?? GREEN
+  const desc = options?.description ?? DIM
+  const heading = options?.heading ?? BOLD
+  const brackets = options?.brackets ?? YELLOW
+
+  const helpConfig: Record<string, unknown> = {
+    // Section headings: "Usage:", "Options:", "Commands:", "Arguments:"
+    styleTitle(str: string): string {
+      return ansi(str, heading)
+    },
+
+    // Command name in usage line and subcommand terms
+    styleCommandText(str: string): string {
+      return ansi(str, cmds)
+    },
+
+    // Option terms: "-v, --verbose", "--repo <path>", "[options]"
+    styleOptionText(str: string): string {
+      return ansi(str, flags)
+    },
+
+    // Subcommand names in the commands list
+    styleSubcommandText(str: string): string {
+      return ansi(str, cmds)
+    },
+
+    // Argument terms: "<file>", "[dir]"
+    styleArgumentText(str: string): string {
+      return ansi(str, brackets)
+    },
+
+    // Description text for options, subcommands, arguments
+    styleDescriptionText(str: string): string {
+      return ansi(str, desc)
+    },
+
+    // Command description (the main program description line) — keep normal
+    styleCommandDescription(str: string): string {
+      return str
+    },
+  }
+
+  program.configureHelp(helpConfig)
+
+  // Tell Commander that color output is supported, even when stdout is not
+  // a TTY (e.g., piped output, CI, tests). Without this, Commander strips
+  // all ANSI codes from helpInformation() output.
+  //
+  // Callers who want to respect NO_COLOR/FORCE_COLOR should check
+  // shouldColorize() before calling colorizeHelp().
+  program.configureOutput({
+    getOutHasColors: () => true,
+    getErrHasColors: () => true,
+  })
+
+  // Apply recursively to all existing subcommands
+  for (const sub of program.commands) {
+    colorizeHelp(sub, options)
+  }
+}

package/src/command.ts

@@ -0,0 +1,117 @@
+/**
+ * Enhanced Commander Command with auto-colorized help and Standard Schema support.
+ *
+ * Subclasses Commander's Command so `new Command("app")` just works —
+ * it's Commander with auto-colorized help and automatic Standard Schema /
+ * legacy Zod detection in `.option()`.
+ *
+ * @example
+ * ```ts
+ * import { Command } from "@silvery/commander"
+ * import { port, csv } from "@silvery/commander/parse"
+ *
+ * const program = new Command("myapp")
+ *   .description("My CLI tool")
+ *   .version("1.0.0")
+ *   .option("-p, --port <n>", "Port", port)
+ *   .option("--tags <t>", "Tags", csv)
+ *
+ * program.parse()
+ * ```
+ */
+
+import { Command as BaseCommand } from "commander"
+import { colorizeHelp } from "./colorize.ts"
+import type { StandardSchemaV1 } from "./presets.ts"
+
+// --- Standard Schema support ---
+
+/** 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> {
+  parse(value: unknown): T
+  _def: unknown
+}
+
+/** 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) &&
+    !("~standard" in (value as any))
+  )
+}
+
+/** 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)
+    } catch (err: any) {
+      // Format Zod errors as Commander-style messages
+      if (err?.issues) {
+        const messages = err.issues.map((i: any) => i.message).join(", ")
+        throw new Error(messages)
+      }
+      throw err
+    }
+  }
+}
+
+export class Command extends BaseCommand {
+  constructor(name?: string) {
+    super(name)
+    colorizeHelp(this as any)
+  }
+
+  /**
+   * Add an option with automatic Standard Schema / legacy Zod detection.
+   *
+   * When the third argument is a Standard Schema v1 object (Zod >=3.24,
+   * Valibot >=1.0, ArkType >=2.0, or @silvery/commander presets), it's
+   * automatically wrapped as a Commander parser function.
+   *
+   * When the third argument is a legacy Zod schema (pre-3.24, has `_def`
+   * and `parse` but no `~standard`), it's also wrapped automatically.
+   */
+  option(flags: string, description?: string, parseArgOrDefault?: any, defaultValue?: any): this {
+    if (isStandardSchema(parseArgOrDefault)) {
+      return super.option(flags, description ?? "", standardSchemaParser(parseArgOrDefault))
+    }
+    if (isLegacyZodSchema(parseArgOrDefault)) {
+      return super.option(flags, description ?? "", legacyZodParser(parseArgOrDefault))
+    }
+    if (typeof parseArgOrDefault === "function") {
+      return super.option(flags, description ?? "", parseArgOrDefault, defaultValue)
+    }
+    return super.option(flags, description ?? "", parseArgOrDefault)
+  }
+
+  // Subcommands also get colorized help and Standard Schema support
+  createCommand(name?: string): Command {
+    return new Command(name)
+  }
+}