@silvery/commander 0.8.1 → 0.17.3

package/src/command.ts

@@ -1,321 +0,0 @@
-/**
- * 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, Help, 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) ---
-
-interface ZodLike<T = any> {
-  parse(value: unknown): T
-  _def: unknown
-}
-
-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))
-  )
-}
-
-function legacyZodParser<T>(schema: ZodLike<T>): (value: string) => T {
-  return (value: string) => {
-    try {
-      return schema.parse(value)
-    } catch (err: any) {
-      if (err?.issues) {
-        const messages = err.issues.map((i: any) => i.message).join(", ")
-        throw new Error(messages)
-      }
-      throw err
-    }
-  }
-}
-
-// --- Help Section Types ---
-
-/** Position for help sections — mirrors Commander's addHelpText positions. */
-export type HelpSectionPosition = "beforeAll" | "before" | "after" | "afterAll"
-
-/** Content for a help section: rows of [term, description] pairs, or free-form text. */
-export type HelpSectionContent = [string, string][] | string
-
-// Internal storage
-interface StoredSection {
-  position: HelpSectionPosition
-  title: string
-  content: HelpSectionContent
-}
-
-/**
- * Style a section term using Commander's style hooks.
- * Splits the term into segments: option-like (-f), argument brackets (<arg>, [opt]),
- * and command words — each styled with the appropriate hook.
- */
-function styleSectionTerm(term: string, helper: any): string {
-  // Option-like terms: entire term styled as option
-  if (/^\s*-/.test(term)) return helper.styleOptionText(term)
-
-  // Mixed terms: style <arg>/[opt] as arguments, "quoted" as literal values, rest as commands
-  return term.replace(
-    /(<[^>]+>|\[[^\]]+\])|("[^"]*")|([^<["[\]]+)/g,
-    (_match, bracket: string, quoted: string, text: string) => {
-      if (bracket) return helper.styleArgumentText(bracket)
-      if (quoted) return quoted // literal values — default foreground (quotes distinguish them)
-      if (text) return helper.styleCommandText(text)
-      return ""
-    },
-  )
-}
-
-export class Command extends BaseCommand {
-  private _helpSectionList: StoredSection[] = []
-  private _helpSectionsInstalled = false
-
-  constructor(name?: string) {
-    super(name)
-    colorizeHelp(this as any)
-    this._capitalizeBuiltinDescriptions()
-  }
-
-  /**
-   * 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
-   */
-  override option(flags: string, description?: string, parseArgOrDefault?: any, defaultValue?: any): this {
-    if (Array.isArray(parseArgOrDefault)) {
-      const opt = new Option(flags, description ?? "").choices(parseArgOrDefault as string[])
-      this.addOption(opt)
-      return this
-    }
-    if (isStandardSchema(parseArgOrDefault)) {
-      return super.option(flags, description ?? "", standardSchemaParser(parseArgOrDefault), defaultValue)
-    }
-    if (isLegacyZodSchema(parseArgOrDefault)) {
-      return super.option(flags, description ?? "", legacyZodParser(parseArgOrDefault), defaultValue)
-    }
-    if (typeof parseArgOrDefault === "function") {
-      return super.option(flags, description ?? "", parseArgOrDefault, defaultValue)
-    }
-    return super.option(flags, description ?? "", parseArgOrDefault)
-  }
-
-  /**
-   * Add a styled help section — like Commander's `addHelpText` but with
-   * structured content that participates in global column alignment.
-   *
-   * @example
-   * ```ts
-   * // Rows with aligned descriptions (default position: "after")
-   * program.addHelpSection("Getting Started:", [
-   *   ["myapp init", "Initialize a new project"],
-   *   ["myapp serve", "Start the dev server"],
-   * ])
-   *
-   * // Free-form text
-   * program.addHelpSection("Note:", "Requires Node.js 23+")
-   *
-   * // Explicit position
-   * program.addHelpSection("before", "Prerequisites:", [
-   *   ["node >= 23", "Required runtime"],
-   * ])
-   * ```
-   */
-  addHelpSection(title: string, content: HelpSectionContent): this
-  addHelpSection(position: HelpSectionPosition, title: string, content: HelpSectionContent): this
-  addHelpSection(
-    positionOrTitle: HelpSectionPosition | string,
-    titleOrContent: string | HelpSectionContent,
-    content?: HelpSectionContent,
-  ): this {
-    let position: HelpSectionPosition
-    let title: string
-    let body: HelpSectionContent
-
-    if (content !== undefined) {
-      // 3-arg: addHelpSection(position, title, content)
-      position = positionOrTitle as HelpSectionPosition
-      title = titleOrContent as string
-      body = content
-    } else {
-      // 2-arg: addHelpSection(title, content) — defaults to "after"
-      position = "after"
-      title = positionOrTitle
-      body = titleOrContent as HelpSectionContent
-    }
-
-    this._helpSectionList.push({ position, title, content: body })
-    this._installHelpSectionHooks()
-    return this
-  }
-
-  // Subcommands also get colorized help, Standard Schema, and array choices
-  override createCommand(name?: string): Command {
-    return new Command(name)
-  }
-
-  /**
-   * Auto-detect capitalization from user-provided descriptions and match it
-   * for built-in options (-V/--version, -h/--help).
-   */
-  private _capitalizeBuiltinDescriptions(): void {
-    const origHelp = this.helpInformation.bind(this)
-    this.helpInformation = () => {
-      const builtinFlags = new Set(["-V, --version", "-h, --help"])
-      const userDescs = this.options
-        .filter((opt) => !builtinFlags.has(opt.flags) && opt.description && /^[a-zA-Z]/.test(opt.description))
-        .map((opt) => opt.description!)
-      for (const cmd of this.commands) {
-        if (cmd.description() && /^[a-zA-Z]/.test(cmd.description())) {
-          userDescs.push(cmd.description())
-        }
-      }
-      if (userDescs.length > 0) {
-        const capitalCount = userDescs.filter((d) => /^[A-Z]/.test(d)).length
-        if (capitalCount > userDescs.length / 2) {
-          for (const opt of this.options) {
-            if (builtinFlags.has(opt.flags) && opt.description && /^[a-z]/.test(opt.description)) {
-              opt.description = opt.description[0]!.toUpperCase() + opt.description.slice(1)
-            }
-          }
-          const helpOpt = (this as any)._helpOption
-          if (helpOpt?.description && /^[a-z]/.test(helpOpt.description)) {
-            helpOpt.description = helpOpt.description[0]!.toUpperCase() + helpOpt.description.slice(1)
-          }
-        }
-      }
-      return origHelp()
-    }
-  }
-
-  /** Render sections for a given position using the help formatter. */
-  private _renderSections(position: HelpSectionPosition, helper: any, termWidth: number): string {
-    const sections = this._helpSectionList.filter((s) => s.position === position)
-    if (sections.length === 0) return ""
-
-    const lines: string[] = []
-    for (const section of sections) {
-      lines.push("")
-      lines.push(helper.styleTitle(section.title))
-      if (typeof section.content === "string") {
-        for (const line of section.content.split("\n")) {
-          lines.push(`  ${line}`)
-        }
-      } else {
-        for (const [term, desc] of section.content) {
-          const styleTerm = styleSectionTerm(term, helper)
-          lines.push(helper.formatItem(styleTerm, termWidth, helper.styleDescriptionText(desc), helper))
-        }
-      }
-    }
-    lines.push("")
-    return lines.join("\n")
-  }
-
-  /** Install hooks once — merges with existing configureHelp, adds addHelpText for before/afterAll. */
-  private _installHelpSectionHooks(): void {
-    if (this._helpSectionsInstalled) return
-    this._helpSectionsInstalled = true
-
-    const self = this
-    const existing = (this as any)._helpConfiguration ?? {}
-    const origPadWidth = existing.padWidth
-    const origFormatHelp = existing.formatHelp
-    const protoFormatHelp = Help.prototype.formatHelp
-
-    this.configureHelp({
-      ...existing,
-      // Include section term widths in global column alignment
-      padWidth(cmd: any, helper: any) {
-        const base = origPadWidth
-          ? origPadWidth(cmd, helper)
-          : Math.max(
-              helper.longestOptionTermLength(cmd, helper),
-              helper.longestGlobalOptionTermLength?.(cmd, helper) ?? 0,
-              helper.longestSubcommandTermLength(cmd, helper),
-              helper.longestArgumentTermLength(cmd, helper),
-            )
-        let sectionMax = 0
-        for (const section of self._helpSectionList) {
-          if (typeof section.content !== "string") {
-            for (const [term] of section.content) {
-              if (term.length > sectionMax) sectionMax = term.length
-            }
-          }
-        }
-        return Math.max(base, sectionMax)
-      },
-      // Render "before" and "after" sections inside formatHelp
-      formatHelp(cmd: any, helper: any) {
-        const baseHelp = origFormatHelp ? origFormatHelp(cmd, helper) : protoFormatHelp.call(helper, cmd, helper)
-        const termWidth = helper.padWidth(cmd, helper)
-        const before = self._renderSections("before", helper, termWidth)
-        const after = self._renderSections("after", helper, termWidth)
-
-        // "before" goes after the Usage+Description but before Options.
-        // Since we can't inject mid-formatHelp easily, prepend before baseHelp.
-        // "after" appends at the end.
-        return (before ? before + "\n" : "") + baseHelp + after
-      },
-    })
-
-    // "beforeAll" and "afterAll" use Commander's addHelpText (propagates to subcommands)
-    this.addHelpText("beforeAll", () => {
-      const helper = this.createHelp()
-      const termWidth = helper.padWidth(this, helper)
-      return this._renderSections("beforeAll", helper, termWidth)
-    })
-    this.addHelpText("afterAll", () => {
-      const helper = this.createHelp()
-      const termWidth = helper.padWidth(this, helper)
-      return this._renderSections("afterAll", helper, termWidth)
-    })
-  }
-}

package/src/index.ts

@@ -1,14 +0,0 @@
-// Enhanced Commander
-export { Command, type HelpSectionPosition, type HelpSectionContent } from "./command.ts"
-export { colorizeHelp, shouldColorize, type ColorizeHelpOptions, type CommandLike } from "./colorize.ts"
-
-// Re-export Commander's other classes
-export { Option, Argument, CommanderError, InvalidArgumentError, Help } from "commander"
-export type { OptionValues } from "commander"
-
-// 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"
-
-// Tree-shakeable: only evaluated if user imports z
-export { z } from "./z.ts"

package/src/plain.ts

@@ -1,22 +0,0 @@
-/**
- * Plain Commander — Standard Schema presets without auto-colorization.
- *
- * Exports the base Commander Command (no auto-colorized help) plus the
- * same typed option presets (int, uint, port, csv, intRange). Does NOT
- * import @silvery/ansi — zero styling overhead.
- *
- * For colorization, import `colorizeHelp` from `@silvery/commander` (main entry).
- *
- * @example
- * ```ts
- * import { Command, port, csv } from "@silvery/commander/plain"
- *
- * const program = new Command("myapp")
- *   .option("-p, --port <n>", "Port", port)
- *   .option("-e, --env <e>", "Env", ["dev", "staging", "prod"])
- * ```
- */
-
-export { Command } from "commander"
-export { int, uint, port, csv, intRange } from "./presets.ts"
-export type { StandardSchemaV1 } from "./presets.ts"

package/src/presets.ts

@@ -1,186 +0,0 @@
-/**
- * Built-in CLI types — Standard Schema v1 validators for common CLI argument patterns.
- *
- * Zero dependencies — validation is manual, no Zod/Valibot/ArkType required.
- * Each type implements Standard Schema v1 for interop with any schema library,
- * plus standalone `.parse()` and `.safeParse()` convenience methods.
- *
- * @example
- * ```ts
- * import { Command, port, csv } from "@silvery/commander"
- *
- * 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("-e, --env <e>", "Env", ["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 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 createType<T>(vendor: string, validate: (value: unknown) => T): CLIType<T> {
-  const schema: CLIType<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 = createType<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 = createType<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 = createType<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 = 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 = createType<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 = 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 = createType<string[]>(VENDOR, (v) => {
-  return String(v)
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean)
-})
-
-/** JSON string to parsed value. */
-export const json = createType<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 = 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
-  throw new Error(`Expected boolean (true/false/yes/no/1/0), got "${v}"`)
-})
-
-/** Date string to Date object. */
-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 = 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 = createType<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): 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}"`)
-    return n
-  })
-}

package/src/z.ts

@@ -1,44 +0,0 @@
-/**
- * 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),
-}