npm - @silvery/commander - Versions diffs - 0.3.0 → 0.5.0 - Mend

@silvery/commander 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,198 +1,178 @@
 # @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 type-safe options, auto-colorized help, [Standard Schema](https://github.com/standard-schema/standard-schema) validation, and built-in CLI types.
+Drop-in replacement -- `Command` is a subclass of Commander's `Command` with full type inference for options, arguments, and parsed values. Install once, Commander is included.
 ## Usage
 ```typescript
-import { createCLI } from "@silvery/commander"
+import { Command, port, csv } from "@silvery/commander"
-const cli = createCLI("myapp")
-  .description("My CLI tool")
+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
-```
-Help output is automatically colorized using Commander's built-in `configureHelp()` style hooks (headings bold, flags green, commands cyan, descriptions dim, arguments yellow).
-You can also use `colorizeHelp()` standalone with a plain Commander `Command`:
-```typescript
-import { Command } from "commander"
-import { colorizeHelp } from "@silvery/commander"
+  .option("-p, --port <n>", "Port", port)
+  .option("--tags <t>", "Tags", csv)
+  .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
-const program = new Command("myapp").description("My CLI tool")
-colorizeHelp(program) // applies recursively to all subcommands
+program.parse()
 ```
-## Presets
+Help output is automatically colorized -- bold headings, green flags, cyan commands, dim descriptions, yellow arguments. Uses [Commander's](https://github.com/tj/commander.js) built-in `configureHelp()` style hooks.
-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.
+Colorization works out of the box with raw ANSI codes. Install [`@silvery/ansi`](https://github.com/beorn/silvery/tree/main/packages/ansi) for full terminal capability detection (respects `NO_COLOR`, `FORCE_COLOR`, and `isTTY`).
-```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
+## Validated options with built-in types
-Presets also work outside Commander for validating env vars, config files, etc. Import from the `@silvery/commander/parse` subpath for tree-shaking:
+Commander's `.option()` accepts a string and gives you a string back. Our built-in types parse and validate in one step:
 ```typescript
-import { port, csv, oneOf } from "@silvery/commander/parse"
+import { Command, port, csv, int } from "@silvery/commander"
-// .parse() — returns value or throws
-const dbPort = port.parse(process.env.DB_PORT ?? "5432")  // 3000
+new Command("deploy")
+  .option("-p, --port <n>", "Port", port) // number (1-65535, validated)
+  .option("--tags <t>", "Tags", csv) // string[]
+  .option("-r, --retries <n>", "Retries", int) // number (integer)
+  .option("-e, --env <e>", "Env", ["dev", "staging", "prod"]) // choices
+```
-// .safeParse() — returns result object, never throws
-const result = port.safeParse("abc")
-// { success: false, issues: [{ message: 'Expected port (1-65535), got "abc"' }] }
+These types are **not part of Commander** -- they're provided by `@silvery/commander`. Each implements [Standard Schema v1](https://github.com/standard-schema/standard-schema), so they work with any schema-aware tooling. They have zero dependencies.
-// Standard Schema ~standard.validate() also available
-const validated = port["~standard"].validate("8080")
-// { value: 8080 }
-```
+### Available types
-### 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
+| Type    | Output     | 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                   |
+| `regex` | `RegExp`   | Valid regex pattern                      |
+### Factory type
 ```typescript
-import { intRange, oneOf } from "@silvery/commander"
+import { intRange } from "@silvery/commander"
-intRange(1, 100)       // Preset<number> — integer within bounds
-oneOf(["a", "b", "c"]) // Preset<"a" | "b" | "c"> — enum from values
+intRange(1, 100) // CLIType<number> -- integer within bounds
 ```
-## Custom parser type inference
+### Array choices
-When `.option()` is called with a parser function as the third argument, the return type is inferred:
+Pass an array as the third argument to restrict an option to a fixed set of values:
 ```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[]
+.option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
 ```
-Default values can be passed as the fourth argument:
+Commander validates the choice at parse time and rejects invalid values.
+### Standalone usage
+Types work outside Commander too -- for validating env vars, config files, etc.:
 ```typescript
-.option("-p, --port <n>", "Port", parseInt, 8080) // → port: number (defaults to 8080)
+import { port, csv } from "@silvery/commander/parse"
+port.parse("3000") // 3000
+port.parse("abc") // throws: 'Expected port (1-65535), got "abc"'
+port.safeParse("3000") // { success: true, value: 3000 }
+port.safeParse("abc") // { success: false, issues: [{ message: "..." }] }
 ```
+The `/parse` subpath has zero dependencies -- no Commander, no [Zod](https://github.com/colinhacks/zod).
 ## Standard Schema validation
-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:
+Pass any [Standard Schema v1](https://github.com/standard-schema/standard-schema) schema as the third argument to `.option()`. This works with [Zod](https://github.com/colinhacks/zod) (>=3.24), [Valibot](https://github.com/fabian-hiller/valibot) (>=1.0), [ArkType](https://github.com/arktypeio/arktype) (>=2.0), and any library implementing the protocol:
 ```typescript
+import { Command } from "@silvery/commander"
 import { z } from "zod"
-const cli = createCLI("deploy")
+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)
 ```
-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.
+Schema libraries are optional peer dependencies -- detected at runtime, never imported at the top level.
-## Typed action handlers
+## Zod CLI types
-Action callbacks receive typed arguments and options:
+Import `z` from `@silvery/commander` for [Zod](https://github.com/colinhacks/zod) extended 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"
+new Command("deploy")
+  .option("-p, --port <n>", "Port", z.port)
+  .option("--tags <t>", "Tags", z.csv)
+  .option("-r, --retries <n>", "Retries", z.int)
+  .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
 ```
-Required arguments (`<name>`) are `string`, optional arguments (`[name]`) are `string | undefined`.
+The `z` export is tree-shakeable -- if you don't import it, [Zod](https://github.com/colinhacks/zod) won't be in your bundle. Requires `zod` as a peer dependency.
-## Choices narrowing
+Available: `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)`.
-Use `.optionWithChoices()` to restrict an option to a fixed set of values with union type inference:
+## Function parsers
-```typescript
-const cli = createCLI("deploy").optionWithChoices("-e, --env <env>", "Environment", ["dev", "staging", "prod"] as const)
-// → env: "dev" | "staging" | "prod" | undefined
+[Commander's](https://github.com/tj/commander.js) standard parser function pattern also works:
-cli.parse()
-const { env } = cli.opts() // env: "dev" | "staging" | "prod" | undefined
+```typescript
+new Command("app")
+  .option("-p, --port <n>", "Port", parseInt) // number
+  .option("--tags <items>", "Tags", (v) => v.split(",")) // string[]
+  .option("-p, --port <n>", "Port", parseInt, 8080) // number (with default)
 ```
-Commander validates the choice at parse time and rejects invalid values.
-## Environment variable support
+## colorizeHelp()
-Chain `.env()` to set an environment variable fallback for the last-added option:
+Use standalone with a plain [Commander](https://github.com/tj/commander.js) `Command` (without subclassing):
 ```typescript
-.option("-p, --port <n>", "Port").env("PORT")
+import { Command } from "commander"
+import { colorizeHelp } from "@silvery/commander"
+const program = new Command("myapp")
+colorizeHelp(program) // applies recursively to all subcommands
 ```
-## Improvements over @commander-js/extra-typings
-| 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                         |
+## Import paths
+| Path                       | What                            | Dependencies                                    |
+| -------------------------- | ------------------------------- | ----------------------------------------------- |
+| `@silvery/commander`       | Command, colorizeHelp, types, z | [commander](https://github.com/tj/commander.js) |
+| `@silvery/commander/parse` | Types only (.parse/.safeParse)  | none                                            |
+## Beyond extra-typings
+Built on the shoulders of [@commander-js/extra-typings](https://github.com/commander-js/extra-typings). We add:
+- **Auto-colorized help** -- bold headings, green flags, cyan commands
+- **Built-in validation** via [Standard Schema](https://github.com/standard-schema/standard-schema) -- works with [Zod](https://github.com/colinhacks/zod), [Valibot](https://github.com/fabian-hiller/valibot), [ArkType](https://github.com/arktypeio/arktype)
+- **14 CLI types** -- `port`, `csv`, `int`, `url`, `email` and more, usable standalone via `.parse()`/`.safeParse()`
+- **NO_COLOR support** via [`@silvery/ansi`](https://github.com/beorn/silvery/tree/main/packages/ansi) (optional)
+- **Commander included** -- one install, no peer dep setup
 ## 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
+- **[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
+- **[Standard Schema](https://github.com/standard-schema/standard-schema)** -- universal schema interop protocol
+- **[@silvery/ansi](https://github.com/beorn/silvery/tree/main/packages/ansi)** -- optional terminal capability detection
 ## License

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/commander",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -20,6 +20,7 @@
     "src"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
     "./parse": "./src/presets.ts"
@@ -27,32 +28,19 @@
   "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",
-    "valibot": ">=1.0.0",
-    "arktype": ">=2.0.0"
+    "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "commander": {
-      "optional": true
-    },
-    "@commander-js/extra-typings": {
-      "optional": true
-    },
     "@silvery/ansi": {
       "optional": true
     },
     "zod": {
       "optional": true
-    },
-    "valibot": {
-      "optional": true
-    },
-    "arktype": {
-      "optional": true
     }
   },
   "engines": {

package/src/colorize.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * Enhanced Commander Command with auto-colorized help, Standard Schema support,
+ * and array-as-choices detection.
+ *
+ * Subclasses Commander's Command so `new Command("app")` just works --
+ * it's Commander with auto-colorized help, automatic Standard Schema /
+ * legacy Zod detection, and array choices in `.option()`.
+ *
+ * @example
+ * ```ts
+ * import { Command, port, csv } from "@silvery/commander"
+ *
+ * new Command("deploy")
+ *   .option("-p, --port <n>", "Port", port)
+ *   .option("--tags <t>", "Tags", csv)
+ *   .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
+ *
+ * program.parse()
+ * ```
+ */
+import { Command as BaseCommand, Option } 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 smart third-argument detection.
+   *
+   * The third argument is detected in order:
+   * 1. **Array** -- treated as choices (Commander `.choices()`)
+   * 2. **Standard Schema v1** -- wrapped as a parser function
+   * 3. **Legacy Zod** (pre-3.24, has `_def` + `parse`) -- wrapped as a parser
+   * 4. **Function** -- passed through as Commander's parser function
+   * 5. **Anything else** -- passed through as a default value
+   */
+  option(flags: string, description?: string, parseArgOrDefault?: any, defaultValue?: any): this {
+    if (Array.isArray(parseArgOrDefault)) {
+      const opt = new Option(flags, description ?? "").choices(parseArgOrDefault)
+      this.addOption(opt)
+      return 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, Standard Schema, and array choices
+  createCommand(name?: string): Command {
+    return new Command(name)
+  }
+}