@silvery/commander 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,171 +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"
-
-/**
- * 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,
-  })
+// Presets and Standard Schema type
+export { int, uint, float, port, url, path, csv, json, bool, date, email, regex, intRange, oneOf } from "./presets.ts"
+export type { Preset, 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

@@ -0,0 +1,196 @@
+/**
+ * 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: "..." }] }
+ * ```
+ */
+
+/**
+ * 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> {
+  /** 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/z.ts

@@ -0,0 +1,45 @@
+/**
+ * Extended Zod object with CLI presets.
+ *
+ * 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"
+ *
+ * const program = new Command("deploy")
+ *   .option("-p, --port <n>", "Port", z.port)
+ *   .option("-e, --env <e>", "Environment", z.oneOf(["dev", "staging", "prod"]))
+ *   .option("--tags <t>", "Tags", z.csv)
+ *
+ * program.parse()
+ * ```
+ */
+
+import * as zod from "zod"
+
+export const z = {
+  ...zod,
+  // CLI presets (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),
+  oneOf: <const T extends readonly [string, ...string[]]>(values: T) => zod.enum(values),
+}