@silvery/commander 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silvery/commander",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Colorized Commander.js help output using ANSI escape codes",
   "keywords": [
     "ansi",
@@ -23,14 +23,14 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
+    "./plain": "./src/plain.ts",
     "./parse": "./src/presets.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@silvery/ansi": ">=0.1.0",
-    "@silvery/style": ">=0.1.0",
+    "@silvery/ansi": ">=0.3.0",
     "commander": ">=12.0.0"
   },
   "peerDependencies": {

package/src/colorize.ts

@@ -1,57 +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.
+ * 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)
  * ```
  */
 
-import { MODIFIERS, FG_COLORS } from "@silvery/style"
-import { detectColor } from "@silvery/ansi"
+import { createStyle } from "@silvery/ansi"
 
-// Derive ANSI escape sequences from @silvery/style constants.
-const RESET = "\x1b[0m"
-const BOLD = `\x1b[${MODIFIERS.bold![0]}m`
-const DIM = `\x1b[${MODIFIERS.dim![0]}m`
-const CYAN = `\x1b[${FG_COLORS.cyan}m`
-const GREEN = `\x1b[${FG_COLORS.green}m`
-const YELLOW = `\x1b[${FG_COLORS.yellow}m`
+// 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() for full detection (respects NO_COLOR,
- * FORCE_COLOR, TERM, etc.).
+ * 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
-  _shouldColorize = detectColor(process.stdout) !== null
-  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
@@ -62,82 +43,57 @@ 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: primary (yellow without theme) */
+  commands?: (text: string) => string
+  /** Style for --flags and -short options. Default: secondary (cyan without theme) */
+  flags?: (text: string) => string
+  /** Style for description text. Default: unstyled (normal foreground) */
+  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: accent (magenta without theme) */
+  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
+
+  // Semantic token fallback: theme token → named color
+  const cmds = options?.commands ?? ((t: string) => s.primary(t))
+  const flags = options?.flags ?? ((t: string) => s.secondary(t))
+  const desc = options?.description ?? ((t: string) => t)
+  const heading = options?.heading ?? ((t: string) => s.bold(t))
+  const brackets = options?.brackets ?? ((t: string) => s.accent(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) => s.bold.primary(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,

package/src/command.ts

@@ -19,7 +19,7 @@
  * ```
  */
 
-import { Command as BaseCommand, Option } from "commander"
+import { Command as BaseCommand, Help, Option } from "commander"
 import { colorizeHelp } from "./colorize.ts"
 import type { StandardSchemaV1 } from "./presets.ts"
 
@@ -44,16 +44,11 @@ function standardSchemaParser<T>(schema: StandardSchemaV1<T>): (value: string) =
 
 // --- Legacy Zod support (pre-3.24, no ~standard) ---
 
-/**
- * Duck-type interface for older Zod schemas that don't implement Standard Schema.
- * Any object with `parse(value: string) => T` and `_def` qualifies.
- */
 interface ZodLike<T = any> {
   parse(value: unknown): T
   _def: unknown
 }
 
-/** Runtime check: is this value a legacy Zod-like schema (without Standard Schema)? */
 function isLegacyZodSchema(value: unknown): value is ZodLike {
   return (
     typeof value === "object" &&
@@ -64,13 +59,11 @@ function isLegacyZodSchema(value: unknown): value is ZodLike {
   )
 }
 
-/** Wrap a legacy Zod schema as a Commander parser function */
 function legacyZodParser<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)
@@ -80,10 +73,50 @@ function legacyZodParser<T>(schema: ZodLike<T>): (value: string) => T {
   }
 }
 
+// --- 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()
   }
 
   /**
@@ -114,8 +147,175 @@ export class Command extends BaseCommand {
     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,5 +1,5 @@
 // Enhanced Commander
-export { Command } from "./command.ts"
+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

package/src/plain.ts

@@ -0,0 +1,22 @@
+/**
+ * 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"