@silvery/commander 0.7.0 → 0.8.0

package/package.json

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

package/src/colorize.ts

@@ -45,15 +45,15 @@ export interface CommandLike {
 
 /** Color scheme for help output. Each value is a styling function (text → styled text). */
 export interface ColorizeHelpOptions {
-  /** Style for command/subcommand names. Default: cyan */
+  /** Style for command/subcommand names. Default: primary (yellow without theme) */
   commands?: (text: string) => string
-  /** Style for --flags and -short options. Default: green */
+  /** Style for --flags and -short options. Default: secondary (cyan without theme) */
   flags?: (text: string) => string
-  /** Style for description text. Default: dim */
+  /** 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: yellow */
+  /** Style for <required> and [optional] argument brackets. Default: accent (magenta without theme) */
   brackets?: (text: string) => string
 }
 
@@ -73,11 +73,12 @@ export function colorizeHelp(program: CommandLike, options?: ColorizeHelpOptions
   // 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))
+  // 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.yellow(t))
+  const brackets = options?.brackets ?? ((t: string) => s.accent(t))
 
   const helpConfig: Record<string, unknown> = {
     styleTitle: (str: string) => heading(str),
@@ -86,7 +87,7 @@ export function colorizeHelp(program: CommandLike, options?: ColorizeHelpOptions
     styleSubcommandText: (str: string) => cmds(str),
     styleArgumentText: (str: string) => brackets(str),
     styleDescriptionText: (str: string) => desc(str),
-    styleCommandDescription: (str: string) => str,
+    styleCommandDescription: (str: string) => s.bold.primary(str),
   }
 
   program.configureHelp(helpConfig)

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"