@silvery/commander 0.1.0 → 0.2.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,104 @@ const program = new Command("myapp").description("My CLI tool")
 colorizeHelp(program) // applies recursively to all subcommands
 ```
 
-## Improvements over @commander-js/extra-typings
+## 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)
+```
+
+## Zod schema validation
+
+Pass a [Zod](https://zod.dev) schema as the third argument for combined parsing, validation, and type inference:
+
+```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)
+```
+
+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.
+
+## Typed action handlers
 
-| 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) |
+Action callbacks receive typed arguments and options:
 
-## What's planned
+```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)                              |
+| 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                         |
 
 ## 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
+- [@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.2.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -28,7 +28,9 @@
   },
   "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"
   },
   "peerDependenciesMeta": {
     "commander": {
@@ -36,6 +38,12 @@
     },
     "@commander-js/extra-typings": {
       "optional": true
+    },
+    "@silvery/ansi": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {

package/src/index.ts

@@ -33,6 +33,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 +156,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/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,85 @@ 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>
+
+// --- Zod schema support (duck-typed, no import) ---
+
+/**
+ * Duck-type interface for Zod-like schemas.
+ * Avoids importing zod — it's an optional peer dependency.
+ * 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 Zod-like schema? */
+function isZodSchema(value: unknown): value is ZodLike {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as any).parse === "function" &&
+    "_def" in (value as any)
+  )
+}
+
+/** Wrap a Zod schema as a Commander parser function */
+function zodParser<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 +170,43 @@ export class TypedCommand<Opts = {}> {
     return this
   }
 
-  /** Add an option with type inference */
+  /**
+   * Add an option with type inference.
+   *
+   * Supports four 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
+   */
+  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 (isZodSchema(parseArgOrDefault)) {
+      ;(this._cmd as any).option(flags, description ?? "", zodParser(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 +214,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 +249,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 +380,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 +404,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<{}> {