@silvery/commander 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+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.
 
 ## Usage
 
@@ -11,13 +11,13 @@ const cli = createCLI("myapp")
   .description("My CLI tool")
   .version("1.0.0")
   .option("-v, --verbose", "Verbose output")
-  .option("-p, --port <number>", "Port to listen on")
+  .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   ^string  ^string|true  ^boolean
+//      ^boolean   ^number  ^string|true  ^boolean
 ```
 
 Help output is automatically colorized using Commander's built-in `configureHelp()` style hooks (headings bold, flags green, commands cyan, descriptions dim, arguments yellow).
@@ -32,29 +32,166 @@ const program = new Command("myapp").description("My CLI tool")
 colorizeHelp(program) // applies recursively to all subcommands
 ```
 
-## Improvements over @commander-js/extra-typings
+## 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:
+
+```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)
+```
+
+## Standard Schema validation
 
-| Feature | extra-typings | @silvery/commander |
-|---|---|---|
-| Type inference | 1536-line .d.ts with recursive generic accumulation | ~60 lines using TS 5.4+ const type params + template literals |
-| Colorized help | Not included | Built-in via Commander's native style hooks |
-| Package size | Types only (25 lines runtime) | Types + colorizer (~200 lines, zero deps) |
-| Installation | Separate package alongside commander | Single package, re-exports Commander |
-| React dependency | None | None |
-| Negated flags (--no-X) | Partial | Key extraction + boolean type inference |
-| Typed action handlers | Yes (full signature inference) | Not yet (planned) |
-| Custom parser types | Yes (.option with parseFloat -> number) | Not yet (planned) |
+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:
 
-## What's planned
+```typescript
+import { z } from "zod"
+
+const cli = createCLI("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(
+    "--tags <t>",
+    "Tags",
+    z.string().transform((v) => v.split(",")),
+  )
+// → tags: string[] (transformed)
+```
+
+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
+
+Action callbacks receive typed arguments and options:
+
+```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 }
+  })
+```
+
+Required arguments (`<name>`) are `string`, optional arguments (`[name]`) are `string | undefined`.
+
+## Choices narrowing
+
+Use `.optionWithChoices()` to restrict an option to a fixed set of values with union type inference:
+
+```typescript
+const cli = createCLI("deploy").optionWithChoices("-e, --env <env>", "Environment", ["dev", "staging", "prod"] as const)
+// → env: "dev" | "staging" | "prod" | undefined
+
+cli.parse()
+const { env } = cli.opts() // env: "dev" | "staging" | "prod" | undefined
+```
+
+Commander validates the choice at parse time and rejects invalid values.
+
+## Environment variable support
+
+Chain `.env()` to set an environment variable fallback for the last-added option:
+
+```typescript
+.option("-p, --port <n>", "Port").env("PORT")
+```
+
+## Improvements over @commander-js/extra-typings
 
-- Custom parser function type inference (`.option("-p, --port <n>", "Port", parseInt)` -> `number`)
-- Typed action handler signatures
-- `.choices()` narrowing to union types
+| 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)                              |
+| 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 + 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                         |
 
 ## Credits
 
-- **Commander.js** by TJ Holowaychuk and contributors -- the underlying CLI framework
-- **@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
+- [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
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/commander",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -21,14 +21,19 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./parse": "./src/presets.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "@commander-js/extra-typings": ">=12.0.0",
-    "commander": ">=12.0.0"
+    "@silvery/ansi": ">=0.1.0",
+    "commander": ">=12.0.0",
+    "zod": ">=3.0.0",
+    "valibot": ">=1.0.0",
+    "arktype": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "commander": {
@@ -36,6 +41,18 @@
     },
     "@commander-js/extra-typings": {
       "optional": true
+    },
+    "@silvery/ansi": {
+      "optional": true
+    },
+    "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.
@@ -33,6 +38,34 @@ 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}`
@@ -128,6 +161,9 @@ export function colorizeHelp(program: CommandLike, options?: ColorizeHelpOptions
   // 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,

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

@@ -5,7 +5,7 @@
  * to infer option types from .option() calls. Inspired by
  * @commander-js/extra-typings, which achieves similar results with a
  * 1536-line .d.ts using recursive generic accumulation. This
- * implementation achieves the same inference in ~60 lines of type-level
+ * implementation achieves the same inference in ~100 lines of type-level
  * code by leveraging modern TS features (const type params, template
  * literal types, conditional mapped types).
  *
@@ -16,13 +16,13 @@
  * const cli = createCLI("myapp")
  *   .description("My app")
  *   .option("-v, --verbose", "Increase verbosity")
- *   .option("-p, --port <number>", "Port to listen on")
+ *   .option("-p, --port <number>", "Port to listen on", parseInt)
  *   .option("-o, --output [path]", "Output path")
  *   .option("--no-color", "Disable color output")
  *
  * cli.parse()
  * const opts = cli.opts()
- * //    ^? { verbose: boolean, port: string, output: string | true, color: boolean }
+ * //    ^? { verbose: boolean, port: number, output: string | true, color: boolean }
  * ```
  */
 
@@ -41,7 +41,7 @@ import { colorizeHelp } from "./index.ts"
 // Negated flags (--no-X) are detected and produce a `X: boolean` key.
 
 /** Flatten intersection types for clean hover output */
-type Prettify<T> = { [K in keyof T]: T[K] } & {}
+export type Prettify<T> = { [K in keyof T]: T[K] } & {}
 
 /** Check if a flags string is a negated flag like "--no-color" */
 type IsNegated<S extends string> = S extends `${string}--no-${string}` ? true : false
@@ -72,27 +72,125 @@ type CamelCase<S extends string> = S extends `${infer A}-${infer B}${infer Rest}
   : S
 
 /** Determine the value type from a flags string */
-type FlagValueType<S extends string> = IsNegated<S> extends true
-  ? boolean // negated flags are always boolean
-  : S extends `${string}<${string}>`
-    ? string // required arg → string
-    : S extends `${string}[${string}]`
-      ? string | true // optional arg → string | true
-      : boolean // no arg → boolean
+type FlagValueType<S extends string> =
+  IsNegated<S> extends true
+    ? boolean // negated flags are always boolean
+    : S extends `${string}<${string}>`
+      ? string // required arg → string
+      : S extends `${string}[${string}]`
+        ? string | true // optional arg → string | true
+        : boolean // no arg → boolean
 
 /** Add a flag to an options record */
 type AddOption<Opts, Flags extends string, Default = undefined> = Opts & {
   [K in ExtractLongName<Flags>]: Default extends undefined ? FlagValueType<Flags> | undefined : FlagValueType<Flags>
 }
 
+// --- Type-level argument parsing ---
+
+/** Extract whether an argument is required (<name>) or optional ([name]) */
+type ArgType<S extends string> = S extends `<${string}>`
+  ? string
+  : S extends `[${string}]`
+    ? string | undefined
+    : string
+
+// --- Typed opts helper (resolves accumulated Opts for action handlers) ---
+/** Resolve accumulated option types for use in action handler signatures */
+export type TypedOpts<Opts> = Prettify<Opts>
+
+// --- Standard Schema support (v1) ---
+
+/**
+ * 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> {
+  parse(value: unknown): T
+  _def: unknown
+}
+
+/** 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 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
+    }
+  }
+}
+
 // --- Typed Command ---
 
 /**
- * A Commander Command with inferred option types.
+ * A Commander Command with inferred option and argument types.
  * Wraps Commander's Command and tracks option types at the type level.
  * Help is automatically colorized.
+ *
+ * @typeParam Opts - Accumulated option types from .option() calls
+ * @typeParam Args - Accumulated argument types from .argument() calls (tuple)
  */
-export class TypedCommand<Opts = {}> {
+export class TypedCommand<Opts = {}, Args extends any[] = []> {
   readonly _cmd: BaseCommand
 
   constructor(name?: string) {
@@ -112,14 +210,52 @@ export class TypedCommand<Opts = {}> {
     return this
   }
 
-  /** Add an option with type inference */
+  /**
+   * Add an option with type inference.
+   *
+   * 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, 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,
+    schema: Z,
+  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: InferZodOutput<Z> }, Args>
+
+  option<const F extends string, P extends (value: string, previous: any) => any>(
+    flags: F,
+    description: string,
+    parseArg: P,
+    defaultValue?: ReturnType<P>,
+  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: ReturnType<P> }, Args>
+
   option<const F extends string, D = undefined>(
     flags: F,
     description?: string,
     defaultValue?: D,
-  ): TypedCommand<AddOption<Opts, F, D>> {
-    ;(this._cmd as any).option(flags, description ?? "", defaultValue)
-    return this as any
+  ): TypedCommand<AddOption<Opts, F, D>, Args>
+
+  option(flags: string, description?: string, parseArgOrDefault?: any, defaultValue?: any): any {
+    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 {
+      ;(this._cmd as any).option(flags, description ?? "", parseArgOrDefault)
+    }
+    return this
   }
 
   /** Add a required option */
@@ -127,11 +263,31 @@ export class TypedCommand<Opts = {}> {
     flags: F,
     description?: string,
     defaultValue?: string,
-  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: FlagValueType<F> }> {
+  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: FlagValueType<F> }, Args> {
     ;(this._cmd as any).requiredOption(flags, description ?? "", defaultValue)
     return this as any
   }
 
+  /**
+   * Add an option with a fixed set of allowed values (choices).
+   * The option type is narrowed to a union of the provided values.
+   *
+   * @example
+   * ```ts
+   * .optionWithChoices("-e, --env <env>", "Environment", ["dev", "staging", "prod"] as const)
+   * // → env: "dev" | "staging" | "prod" | undefined
+   * ```
+   */
+  optionWithChoices<const F extends string, const C extends readonly string[]>(
+    flags: F,
+    description: string,
+    choices: C,
+  ): TypedCommand<Opts & { [K in ExtractLongName<F>]: C[number] | undefined }, Args> {
+    const option = new Option(flags, description).choices(choices as unknown as string[])
+    ;(this._cmd as any).addOption(option)
+    return this as any
+  }
+
   /** Add a subcommand */
   command(nameAndArgs: string, description?: string): TypedCommand<{}> {
     const sub = (this._cmd as any).command(nameAndArgs, description)
@@ -142,14 +298,24 @@ export class TypedCommand<Opts = {}> {
     return typed
   }
 
-  /** Add an argument */
-  argument(name: string, description?: string, defaultValue?: unknown): this {
+  /**
+   * Add an argument with type tracking.
+   * `<name>` = required (string), `[name]` = optional (string | undefined).
+   */
+  argument<const N extends string>(
+    name: N,
+    description?: string,
+    defaultValue?: unknown,
+  ): TypedCommand<Opts, [...Args, ArgType<N>]> {
     this._cmd.argument(name, description ?? "", defaultValue)
-    return this
+    return this as any
   }
 
-  /** Set action handler */
-  action(fn: (this: TypedCommand<Opts>, ...args: any[]) => void | Promise<void>): this {
+  /**
+   * Set action handler with typed parameters.
+   * Callback receives: ...arguments, opts, command.
+   */
+  action(fn: (...args: [...Args, Prettify<Opts>, TypedCommand<Opts, Args>]) => void | Promise<void>): this {
     this._cmd.action(fn as any)
     return this
   }
@@ -263,6 +429,17 @@ export class TypedCommand<Opts = {}> {
     this._cmd.showSuggestionAfterError(displaySuggestion)
     return this
   }
+
+  /** Set environment variable for the last added option (passthrough) */
+  env(name: string): this {
+    // Commander's .env() is on Option, not Command. We apply it to the last option.
+    const opts = (this._cmd as any).options as any[]
+    if (opts.length > 0) {
+      opts[opts.length - 1].envVar = name
+      opts[opts.length - 1].envVarRequired = false
+    }
+    return this
+  }
 }
 
 /**
@@ -276,11 +453,11 @@ export class TypedCommand<Opts = {}> {
  *   .description("My tool")
  *   .version("1.0.0")
  *   .option("-v, --verbose", "Verbose output")
- *   .option("-p, --port <number>", "Port")
+ *   .option("-p, --port <number>", "Port", parseInt)
  *
  * program.parse()
  * const { verbose, port } = program.opts()
- * //      ^boolean   ^string | undefined
+ * //      ^boolean   ^number | undefined
  * ```
  */
 export function createCLI(name?: string): TypedCommand<{}> {