@silvery/commander 0.6.0 → 0.7.0

package/README.md

@@ -12,44 +12,54 @@ npm install @silvery/commander
 import { Command, z } from "@silvery/commander"
 
 const program = new Command("deploy")
-  .description("Deploy to an environment")
+  .description("Deploy services to an environment")
   .version("1.0.0")
   .option("-e, --env <env>", "Target environment", z.enum(["dev", "staging", "prod"]))
+  .option("-f, --force", "Skip confirmation")
+  .option("-v, --verbose", "Verbose output")
+
+program
+  .command("start <service>")
+  .description("Start a service")
   .option("-p, --port <n>", "Port number", z.port)
   .option("-r, --retries <n>", "Retry count", z.int)
-  .option("--tags <t>", "Labels", z.csv)
-  .option("-f, --force", "Skip confirmation")
+  .action((service, opts) => {
+    /* ... */
+  })
+
+program
+  .command("stop <service>")
+  .description("Stop a running service")
+  .action((service) => {
+    /* ... */
+  })
+
+program
+  .command("status")
+  .description("Show service status")
+  .option("--json", "Output as JSON")
+  .action((opts) => {
+    /* ... */
+  })
 
 program.parse()
-const { env, port, retries, tags, force } = program.opts()
-//      │      │     │         │      └─ boolean | undefined
-//      │      │     │         └──────── string[]
-//      │      │     └────────────────── number
-//      │      └──────────────────────── number (1–65535)
-//      └─────────────────────────────── "dev" | "staging" | "prod"
+const { env, force, verbose } = program.opts()
+//      │     │       └─ boolean | undefined
+//      │     └────────── boolean | undefined
+//      └──────────────── "dev" | "staging" | "prod"
 ```
 
 With plain Commander, `opts()` returns `Record<string, any>` — every value is untyped. With `@silvery/commander`, each option's type is inferred from its schema: `z.port` produces `number`, `z.enum(...)` produces a union, `z.csv` produces `string[]`. Invalid values are rejected at parse time with clear error messages — not silently passed through as strings.
 
 [Zod](https://github.com/colinhacks/zod) is entirely optional — `z` is tree-shaken from your bundle if you don't import it. Without Zod, use the built-in types (`port`, `int`, `csv`) or plain Commander.
 
-<pre><code>$ deploy --help
-
-<b>Usage:</b> <span style="color:#56b6c2">deploy</span> <span style="color:#98c379">[options]</span>
-
-Deploy to an environment
+Help is auto-colorized — bold headings, green flags, cyan commands, dim descriptions:
 
-<b>Options:</b>
-  <span style="color:#98c379">-V, --version</span>      <span style="color:#888">output the version number</span>
-  <span style="color:#98c379">-e, --env &lt;env&gt;</span>    <span style="color:#888">Target environment</span>
-  <span style="color:#98c379">-p, --port &lt;n&gt;</span>     <span style="color:#888">Port number</span>
-  <span style="color:#98c379">-r, --retries &lt;n&gt;</span>  <span style="color:#888">Retry count</span>
-  <span style="color:#98c379">--tags &lt;t&gt;</span>         <span style="color:#888">Labels</span>
-  <span style="color:#98c379">-f, --force</span>        <span style="color:#888">Skip confirmation</span>
-  <span style="color:#98c379">-h, --help</span>         <span style="color:#888">display help for command</span>
-</code></pre>
+<p align="center">
+  <img src="help-output.svg" alt="Colorized help output" width="80%" />
+</p>
 
-Help is auto-colorized — bold headings, green flags, cyan commands, dim descriptions. Options with [Zod](https://github.com/colinhacks/zod) schemas or built-in types are validated at parse time with clear error messages.
+Options with [Zod](https://github.com/colinhacks/zod) schemas or built-in types are validated at parse time with clear error messages.
 
 ## What's included
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/commander",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -29,16 +29,13 @@
     "access": "public"
   },
   "dependencies": {
+    "@silvery/ansi": ">=1.0.0",
     "commander": ">=12.0.0"
   },
   "peerDependencies": {
-    "@silvery/ansi": ">=0.1.0",
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "@silvery/ansi": {
-      "optional": true
-    },
     "zod": {
       "optional": true
     }

package/src/colorize.ts

@@ -1,71 +1,38 @@
 /**
- * Commander.js help colorization using ANSI escape codes.
+ * Commander.js help colorization using @silvery/ansi.
  *
  * 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.
+ * rather than regex post-processing.
  *
  * @example
  * ```ts
  * import { Command } from "@silvery/commander"
+ * // Command auto-colorizes in its constructor — no manual call needed.
+ * // For plain 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"
+import { createStyle } from "@silvery/ansi"
+
+// Auto-detect terminal color level. The Style instance handles the full
+// degradation chain: truecolor → 256 → basic (ANSI 16) → null (no color).
+// When level is null (NO_COLOR), style methods return plain text.
+const s = createStyle()
 
 /**
  * Check if color output should be enabled.
- * Uses @silvery/ansi detectColor() if available, falls back to basic
- * NO_COLOR/FORCE_COLOR/isTTY checks.
+ * Delegates to @silvery/ansi's auto-detection (NO_COLOR, FORCE_COLOR, TERM).
  */
-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}`
+  return s.level > 0
 }
 
 /**
  * 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
@@ -76,82 +43,56 @@ export interface CommandLike {
   readonly commands: readonly any[]
 }
 
-/** Color scheme for help output. Values are raw ANSI escape sequences. */
+/** Color scheme for help output. Each value is a styling function (text → styled text). */
 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
+  /** Style for command/subcommand names. Default: cyan */
+  commands?: (text: string) => string
+  /** Style for --flags and -short options. Default: green */
+  flags?: (text: string) => string
+  /** Style for description text. Default: dim */
+  description?: (text: string) => string
+  /** Style for section headings (Usage:, Options:, etc.). Default: bold */
+  heading?: (text: string) => string
+  /** Style for <required> and [optional] argument brackets. Default: yellow */
+  brackets?: (text: string) => 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.
+ * post-processing the formatted string.
  *
  * @param program - A Commander Command instance (or compatible object)
- * @param options - Override default ANSI color codes for each element
+ * @param options - Override default style functions 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
+  // Ensure style generates codes — at minimum basic (ANSI 16).
+  // Auto-detected level may be higher (256/truecolor) for richer output.
+  // May be 0 if NO_COLOR is set; in that case, force basic since Commander
+  // handles the final strip via configureOutput.
+  if (s.level === 0) s.level = 1
+
+  const cmds = options?.commands ?? ((t: string) => s.cyan(t))
+  const flags = options?.flags ?? ((t: string) => s.green(t))
+  const desc = options?.description ?? ((t: string) => s.dim(t))
+  const heading = options?.heading ?? ((t: string) => s.bold(t))
+  const brackets = options?.brackets ?? ((t: string) => s.yellow(t))
 
   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
-    },
+    styleTitle: (str: string) => heading(str),
+    styleCommandText: (str: string) => cmds(str),
+    styleOptionText: (str: string) => flags(str),
+    styleSubcommandText: (str: string) => cmds(str),
+    styleArgumentText: (str: string) => brackets(str),
+    styleDescriptionText: (str: string) => desc(str),
+    styleCommandDescription: (str: string) => 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().
+  // a TTY. Without this, Commander strips ANSI codes from helpInformation().
   program.configureOutput({
     getOutHasColors: () => true,
     getErrHasColors: () => true,