@silvery/commander 0.3.0 → 0.5.0

package/src/index.ts

@@ -1,176 +1,14 @@
-// Re-export Commander classes (drop-in replacement for @silvery/commander)
-export { Command, Option, Argument, CommanderError, InvalidArgumentError, Help } from "commander"
-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.
- *
- * 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[]
-}
+// Enhanced Commander
+export { Command } from "./command.ts"
+export { colorizeHelp, shouldColorize, type ColorizeHelpOptions, type CommandLike } from "./colorize.ts"
 
-/** 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)
+// Re-export Commander's other classes
+export { Option, Argument, CommanderError, InvalidArgumentError, Help } from "commander"
+export type { OptionValues } from "commander"
 
-  // 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,
-  })
+// Built-in types and Standard Schema
+export { int, uint, float, port, url, path, csv, json, bool, date, email, regex, intRange } from "./presets.ts"
+export type { CLIType, StandardSchemaV1 } from "./presets.ts"
 
-  // Apply recursively to all existing subcommands
-  for (const sub of program.commands) {
-    colorizeHelp(sub, options)
-  }
-}
+// Tree-shakeable: only evaluated if user imports z
+export { z } from "./z.ts"

package/src/presets.ts

@@ -1,20 +1,19 @@
 /**
- * Pre-built Standard Schema v1 presets for common CLI argument patterns.
+ * Built-in CLI types — Standard Schema v1 validators 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,
+ * Each type 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"
+ * import { Command, port, csv } from "@silvery/commander"
  *
- * const cli = createCLI("deploy")
+ * new Command("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"]))
+ *   .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
  *
  * // Standalone usage (outside Commander)
  * port.parse("3000")       // 3000
@@ -22,18 +21,34 @@
  * ```
  */
 
-import type { StandardSchemaV1 } from "./typed.ts"
+/**
+ * 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> }> }
+  }
+}
 
-/** A Standard Schema v1 preset with standalone parse/safeParse methods. */
-export interface Preset<T> extends StandardSchemaV1<T> {
+/** A Standard Schema v1 CLI type with standalone parse/safeParse methods. */
+export interface CLIType<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> = {
+function createType<T>(vendor: string, validate: (value: unknown) => T): CLIType<T> {
+  const schema: CLIType<T> = {
     "~standard": {
       version: 1,
       vendor,
@@ -62,7 +77,7 @@ function createPreset<T>(vendor: string, validate: (value: unknown) => T): Prese
 const VENDOR = "@silvery/commander"
 
 /** Integer (coerced from string). */
-export const int = createPreset<number>(VENDOR, (v) => {
+export const int = createType<number>(VENDOR, (v) => {
   const s = String(v).trim()
   if (s === "") throw new Error(`Expected integer, got "${v}"`)
   const n = Number(s)
@@ -71,7 +86,7 @@ export const int = createPreset<number>(VENDOR, (v) => {
 })
 
 /** Unsigned integer (>= 0, coerced from string). */
-export const uint = createPreset<number>(VENDOR, (v) => {
+export const uint = createType<number>(VENDOR, (v) => {
   const s = String(v).trim()
   if (s === "") throw new Error(`Expected unsigned integer (>= 0), got "${v}"`)
   const n = Number(s)
@@ -80,7 +95,7 @@ export const uint = createPreset<number>(VENDOR, (v) => {
 })
 
 /** Float (coerced from string). */
-export const float = createPreset<number>(VENDOR, (v) => {
+export const float = createType<number>(VENDOR, (v) => {
   const s = String(v).trim()
   if (s === "" || s === "NaN") throw new Error(`Expected number, got "${v}"`)
   const n = Number(s)
@@ -89,14 +104,14 @@ export const float = createPreset<number>(VENDOR, (v) => {
 })
 
 /** Port number (1-65535). */
-export const port = createPreset<number>(VENDOR, (v) => {
+export const port = createType<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) => {
+export const url = createType<string>(VENDOR, (v) => {
   const s = String(v)
   try {
     new URL(s)
@@ -107,14 +122,14 @@ export const url = createPreset<string>(VENDOR, (v) => {
 })
 
 /** File path (non-empty string). */
-export const path = createPreset<string>(VENDOR, (v) => {
+export const path = createType<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) => {
+export const csv = createType<string[]>(VENDOR, (v) => {
   return String(v)
     .split(",")
     .map((s) => s.trim())
@@ -122,7 +137,7 @@ export const csv = createPreset<string[]>(VENDOR, (v) => {
 })
 
 /** JSON string to parsed value. */
-export const json = createPreset<unknown>(VENDOR, (v) => {
+export const json = createType<unknown>(VENDOR, (v) => {
   try {
     return JSON.parse(String(v))
   } catch {
@@ -131,7 +146,7 @@ export const json = createPreset<unknown>(VENDOR, (v) => {
 })
 
 /** Boolean string ("true"/"false"/"1"/"0"/"yes"/"no"). */
-export const bool = createPreset<boolean>(VENDOR, (v) => {
+export const bool = createType<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
@@ -139,21 +154,21 @@ export const bool = createPreset<boolean>(VENDOR, (v) => {
 })
 
 /** Date string to Date object. */
-export const date = createPreset<Date>(VENDOR, (v) => {
+export const date = createType<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) => {
+export const email = createType<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) => {
+export const regex = createType<RegExp>(VENDOR, (v) => {
   try {
     return new RegExp(String(v))
   } catch {
@@ -162,20 +177,10 @@ export const regex = createPreset<RegExp>(VENDOR, (v) => {
 })
 
 /** Integer with min/max bounds (factory). */
-export function intRange(min: number, max: number): Preset<number> {
-  return createPreset<number>(VENDOR, (v) => {
+export function intRange(min: number, max: number): CLIType<number> {
+  return createType<number>(VENDOR, (v) => {
     const n = Number(v)
-    if (!Number.isInteger(n) || n < min || n > max)
-      throw new Error(`Expected integer ${min}-${max}, got "${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/z.ts

@@ -0,0 +1,44 @@
+/**
+ * Extended Zod object with CLI types.
+ *
+ * Spreads all of Zod's exports and adds CLI-specific schemas.
+ * Tree-shakeable -- only evaluated if user imports `z`.
+ *
+ * @example
+ * ```ts
+ * import { z, Command } from "@silvery/commander"
+ *
+ * new Command("deploy")
+ *   .option("-p, --port <n>", "Port", z.port)
+ *   .option("--tags <t>", "Tags", z.csv)
+ *   .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
+ *
+ * program.parse()
+ * ```
+ */
+
+import * as zod from "zod"
+
+export const z = {
+  ...zod,
+  // CLI types (built on Zod schemas)
+  port: zod.coerce.number().int().min(1).max(65535),
+  int: zod.coerce.number().int(),
+  uint: zod.coerce.number().int().min(0),
+  float: zod.coerce.number(),
+  csv: zod.string().transform((v: string) =>
+    v
+      .split(",")
+      .map((s: string) => s.trim())
+      .filter(Boolean),
+  ),
+  url: zod.string().url(),
+  path: zod.string().min(1),
+  email: zod.string().email(),
+  date: zod.coerce.date(),
+  json: zod.string().transform((v: string) => JSON.parse(v)),
+  bool: zod
+    .enum(["true", "false", "1", "0", "yes", "no", "y", "n"] as const)
+    .transform((v: string) => ["true", "1", "yes", "y"].includes(v)),
+  intRange: (min: number, max: number) => zod.coerce.number().int().min(min).max(max),
+}