goke 6.1.3 → 6.2.0

package/src/coerce.ts

@@ -29,6 +29,25 @@
  *   Tries each type in order, returns first successful coercion.
  */
 
+// ─── GokeError ───
+
+/**
+ * Custom error class for CLI usage errors (unknown options, missing values,
+ * invalid types, etc.). Used by both the coercion layer and the framework
+ * to distinguish user-facing errors from unexpected failures.
+ */
+export class GokeError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, this.constructor)
+    } else {
+      this.stack = new Error(message).stack
+    }
+  }
+}
+
 // ─── Standard Schema types (vendored from @standard-schema/spec v1.1.0) ───
 // https://github.com/standard-schema/standard-schema
 //
@@ -108,23 +127,8 @@ export declare namespace StandardJSONSchemaV1 {
 /**
  * Wraps a plain JSON Schema object into a StandardJSONSchemaV1-compatible object.
  *
- * This is useful for dynamic use cases where you have a raw JSON Schema
- * (e.g. from an MCP tool's inputSchema) and need to pass it to Goke's
- * schema option which expects StandardJSONSchemaV1.
- *
- * @example
- * ```ts
- * import { wrapJsonSchema } from 'goke'
- *
- * // Wrap a plain JSON Schema for use with Goke options
- * const schema = wrapJsonSchema({ type: "number" })
- * cmd.option('--port <port>', 'Port', { schema })
- *
- * // Wrap MCP tool property schemas
- * for (const [name, propSchema] of Object.entries(tool.inputSchema.properties)) {
- *   cmd.option(`--${name} <${name}>`, desc, { schema: wrapJsonSchema(propSchema) })
- * }
- * ```
+ * @internal This is an internal helper used by @goke/mcp to wrap MCP tool schemas.
+ * Users should pass Zod or other StandardSchema-compatible schemas to `.option()`.
  *
  * @param jsonSchema - A plain JSON Schema object (e.g. `{ type: "number" }`)
  * @returns A StandardJSONSchemaV1-compatible object that Goke can use for coercion
@@ -158,6 +162,8 @@ export interface JsonSchema {
   additionalProperties?: boolean | JsonSchema
   default?: unknown
   description?: string
+  /** JSON Schema deprecated annotation (draft 2019-09+) */
+  deprecated?: boolean
 }
 
 /**
@@ -236,7 +242,7 @@ export function coerceBySchema(
       }
     }
     // Schema does NOT expect array — repeated flags are not allowed
-    throw new Error(
+    throw new GokeError(
       `Option --${optionName} does not accept multiple values. ` +
       `Use an array schema (e.g. { type: "array" }) to allow repeated flags.`
     )
@@ -289,7 +295,7 @@ export function coerceBySchema(
         return allowed
       }
     }
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: expected one of ${schema.enum.map(v => JSON.stringify(v)).join(', ')}, got ${JSON.stringify(value)}`
     )
   }
@@ -301,7 +307,7 @@ export function coerceBySchema(
     const targetType = constVal === null ? 'null' : typeof constVal as string
     const coerced = coerceToSingleType(value, targetType, optionName)
     if (coerced === constVal) return coerced
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: expected ${JSON.stringify(constVal)}, got ${JSON.stringify(value)}`
     )
   }
@@ -316,7 +322,7 @@ export function coerceBySchema(
         // Try next variant
       }
     }
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: ${JSON.stringify(value)} does not match any allowed type`
     )
   }
@@ -351,7 +357,7 @@ export function coerceBySchema(
         // Try next type
       }
     }
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: expected ${schemaType.join(' or ')}, got ${JSON.stringify(value)}`
     )
   }
@@ -401,11 +407,11 @@ function coerceToNumber(value: string | boolean, optionName: string): number {
     return value ? 1 : 0
   }
   if (value === '') {
-    throw new Error(`Invalid value for --${optionName}: expected number, got empty string`)
+    throw new GokeError(`Invalid value for --${optionName}: expected number, got empty string`)
   }
   const num = +value
   if (!Number.isFinite(num)) {
-    throw new Error(`Invalid value for --${optionName}: expected number, got ${JSON.stringify(value)}`)
+    throw new GokeError(`Invalid value for --${optionName}: expected number, got ${JSON.stringify(value)}`)
   }
   return num
 }
@@ -413,7 +419,7 @@ function coerceToNumber(value: string | boolean, optionName: string): number {
 function coerceToInteger(value: string | boolean, optionName: string): number {
   const num = coerceToNumber(value, optionName)
   if (num % 1 !== 0) {
-    throw new Error(`Invalid value for --${optionName}: expected integer, got ${JSON.stringify(value)}`)
+    throw new GokeError(`Invalid value for --${optionName}: expected integer, got ${JSON.stringify(value)}`)
   }
   return num
 }
@@ -424,21 +430,21 @@ function coerceToBoolean(value: string | boolean, optionName: string): boolean {
   }
   if (value === 'true') return true
   if (value === 'false') return false
-  throw new Error(
+  throw new GokeError(
     `Invalid value for --${optionName}: expected true or false, got ${JSON.stringify(value)}`
   )
 }
 
 function coerceToNull(value: string | boolean, optionName: string): null {
   if (typeof value === 'string' && value === '') return null
-  throw new Error(
+  throw new GokeError(
     `Invalid value for --${optionName}: expected empty string for null, got ${JSON.stringify(value)}`
   )
 }
 
 function coerceToObject(value: string | boolean, optionName: string): Record<string, unknown> {
   if (typeof value !== 'string') {
-    throw new Error(`Invalid value for --${optionName}: expected JSON object, got ${typeof value}`)
+    throw new GokeError(`Invalid value for --${optionName}: expected JSON object, got ${typeof value}`)
   }
   try {
     const parsed = JSON.parse(value)
@@ -447,7 +453,7 @@ function coerceToObject(value: string | boolean, optionName: string): Record<str
     }
     return parsed as Record<string, unknown>
   } catch {
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: expected valid JSON object, got ${JSON.stringify(value)}`
     )
   }
@@ -455,7 +461,7 @@ function coerceToObject(value: string | boolean, optionName: string): Record<str
 
 function coerceToArray(value: string | boolean, optionName: string): unknown[] {
   if (typeof value !== 'string') {
-    throw new Error(`Invalid value for --${optionName}: expected JSON array, got ${typeof value}`)
+    throw new GokeError(`Invalid value for --${optionName}: expected JSON array, got ${typeof value}`)
   }
   try {
     const parsed = JSON.parse(value)
@@ -464,7 +470,7 @@ function coerceToArray(value: string | boolean, optionName: string): unknown[] {
     }
     return parsed
   } catch {
-    throw new Error(
+    throw new GokeError(
       `Invalid value for --${optionName}: expected valid JSON array, got ${JSON.stringify(value)}`
     )
   }
@@ -521,18 +527,21 @@ export function isStandardSchema(value: unknown): value is StandardJSONSchemaV1
 }
 
 /**
- * Extract description and default value from a StandardJSONSchemaV1-compatible schema.
- * Calls extractJsonSchema() internally and pulls `description` and `default` fields.
+ * Extract description, default value, and deprecated flag from a StandardJSONSchemaV1-compatible schema.
+ * Calls extractJsonSchema() internally and pulls `description`, `default`, and `deprecated` fields.
  */
-export function extractSchemaMetadata(schema: StandardJSONSchemaV1): { description?: string; default?: unknown } {
+export function extractSchemaMetadata(schema: StandardJSONSchemaV1): { description?: string; default?: unknown; deprecated?: boolean } {
   const jsonSchema = extractJsonSchema(schema)
   if (!jsonSchema) return {}
-  const result: { description?: string; default?: unknown } = {}
+  const result: { description?: string; default?: unknown; deprecated?: boolean } = {}
   if (typeof jsonSchema.description === 'string') {
     result.description = jsonSchema.description
   }
   if (jsonSchema.default !== undefined) {
     result.default = jsonSchema.default
   }
+  if (jsonSchema.deprecated === true) {
+    result.deprecated = true
+  }
   return result
 }

package/src/goke.ts

@@ -2,7 +2,6 @@
  * Goke — a cac-inspired CLI framework.
  *
  * This file contains the entire core framework:
- * - GokeError: custom error class
  * - Option: CLI option parsing (flags, required/optional values)
  * - Command / GlobalCommand: command definition, help/version output
  * - Goke: main CLI class with parsing, matching, and execution
@@ -14,7 +13,7 @@
 import { EventEmitter } from 'events'
 import pc from 'picocolors'
 import mri from "./mri.js"
-import { coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js"
+import { GokeError, coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js"
 import type { StandardJSONSchemaV1 } from "./coerce.js"
 
 // ─── Node.js platform constants ───
@@ -95,14 +94,9 @@ const ANSI_RE = /\x1B\[[0-9;]*m/g
 
 const visibleLength = (value: string) => value.replace(ANSI_RE, '').length
 
-const commandOrange = (value: string) => {
-  if (!pc.isColorSupported) {
-    return value
-  }
-  return `\x1b[38;5;208m${value}\x1b[39m`
-}
+const commandGreen = (value: string) => pc.bold(pc.greenBright(value))
 
-const optionYellow = (value: string) => pc.bold(pc.yellowBright(value))
+const optionBlue = (value: string) => pc.bold(pc.blueBright(value))
 
 const padRight = (str: string, length: number) => {
   return visibleLength(str) >= length ? str : `${str}${' '.repeat(length - visibleLength(str))}`
@@ -223,20 +217,6 @@ const camelcaseOptionName = (name: string) => {
     .join('.')
 }
 
-// ─── GokeError ───
-
-class GokeError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = this.constructor.name
-    if (typeof Error.captureStackTrace === 'function') {
-      Error.captureStackTrace(this, this.constructor)
-    } else {
-      this.stack = new Error(message).stack
-    }
-  }
-}
-
 // ─── Option ───
 
 class Option {
@@ -253,6 +233,8 @@ class Option {
   default?: unknown
   /** Standard JSON Schema V1 schema for type coercion and inference */
   schema?: StandardJSONSchemaV1
+  /** Whether this option is deprecated (hidden from help output) */
+  deprecated?: boolean
 
   /**
    * Create an option.
@@ -273,6 +255,9 @@ class Option {
       if (meta.default !== undefined) {
         this.default = meta.default
       }
+      if (meta.deprecated) {
+        this.deprecated = true
+      }
     } else {
       this.description = ''
     }
@@ -502,7 +487,11 @@ class Command {
     })
   }
 
-  outputHelp() {
+  /**
+   * Return the formatted help string without printing it.
+   * Useful for embedding help text in documentation, tests, or other programmatic uses.
+   */
+  helpText(): string {
     const { name, commands } = this.cli
     const {
       versionNumber,
@@ -528,7 +517,8 @@ class Command {
     if (showCommands) {
       const commandRows = commands.map((command) => {
         const displayName = command.rawName.trim() === '' ? name : command.rawName
-        const displayOptions = command.isDefaultCommand ? [] : command.options
+        // Hide deprecated options from subcommand help output
+        const displayOptions = command.isDefaultCommand ? [] : command.options.filter((o) => !o.deprecated)
         return {
           command,
           displayName,
@@ -556,7 +546,7 @@ class Command {
               descriptionWidth,
               sharedDescriptionColumn,
             )
-            const commandPrefix = `  ${pc.bold(commandOrange(displayName))}`
+            const commandPrefix = `  ${pc.bold(commandGreen(displayName))}`
             const commandPadding = ' '.repeat(
               Math.max(2, sharedDescriptionColumn - (2 + visibleLength(displayName)))
             )
@@ -575,7 +565,7 @@ class Command {
                   descriptionWidth,
                   sharedDescriptionColumn,
                 )
-                const optionPrefix = `    ${optionYellow(option.rawName)}`
+                const optionPrefix = `    ${optionBlue(option.rawName)}`
                 const optionPadding = ' '.repeat(
                   Math.max(2, sharedDescriptionColumn - (4 + visibleLength(option.rawName)))
                 )
@@ -585,9 +575,9 @@ class Command {
               })
               .join('\n')
 
-            return `${headerLine}\n${optionLines}`
+            return `${headerLine}\n\n${optionLines}`
           })
-          .join('\n\n'),
+          .join('\n\n\n'),
       })
     }
 
@@ -621,6 +611,8 @@ class Command {
     if (!this.isGlobalCommand && !this.isDefaultCommand) {
       options = options.filter((option) => option.name !== 'version')
     }
+    // Hide deprecated options from help output
+    options = options.filter((option) => !option.deprecated)
     if (options.length > 0) {
       const longestOptionNameLength = maxVisibleLength(
         options.map((option) => option.rawName)
@@ -638,8 +630,8 @@ class Command {
               descriptionColumn,
             )
             return description
-              ? `  ${optionYellow(optionLabel)}  ${description}`
-              : `  ${optionYellow(optionLabel)}`
+              ? `  ${optionBlue(optionLabel)}  ${description}`
+              : `  ${optionBlue(optionLabel)}`
           })
           .join('\n'),
       })
@@ -674,15 +666,17 @@ class Command {
       sections = helpCallback(sections) || sections
     }
 
-    this.cli.console.log(
-      sections
-        .map((section) => {
-          return section.title
-            ? `${pc.bold(pc.blue(section.title))}:\n${section.body}`
-            : section.body
-        })
-        .join('\n\n')
-    )
+    return sections
+      .map((section) => {
+        return section.title
+          ? `${pc.bold(pc.blue(section.title))}:\n${section.body}`
+          : section.body
+      })
+      .join('\n\n\n')
+  }
+
+  outputHelp() {
+    this.cli.console.log(this.helpText())
   }
 
   outputVersion() {
@@ -793,6 +787,11 @@ interface GokeOptions {
   argv?: string[]
   /** Terminal width used to wrap help output. Defaults to process.stdout.columns, or Infinity when unavailable */
   columns?: number
+  /**
+   * Custom exit function called on CLI errors (unknown option, missing value, etc.).
+   * Defaults to process.exit. Set to a no-op or throw to prevent exit in tests.
+   */
+  exit?: (code: number) => void
 }
 
 /**
@@ -813,6 +812,26 @@ function createConsole(stdout: GokeOutputStream, stderr: GokeOutputStream): Goke
   }
 }
 
+// ─── Error formatting ───
+
+/**
+ * Format an error for CLI output.
+ * Prints a red "error:" prefix with the message, followed by a dimmed stack trace.
+ */
+function formatCliError(err: Error): string {
+  const lines: string[] = []
+  lines.push(`${pc.red(pc.bold('error:'))} ${err.message}`)
+  if (err.stack) {
+    // Extract just the stack frames (skip the first line which is the message)
+    const stackLines = err.stack.split('\n').slice(1)
+    if (stackLines.length > 0) {
+      lines.push('')
+      lines.push(pc.red(pc.dim(stackLines.join('\n'))))
+    }
+  }
+  return lines.join('\n')
+}
+
 // ─── Goke (main CLI class) ───
 
 interface ParsedArgv {
@@ -853,6 +872,8 @@ class Goke extends EventEmitter {
   readonly console: GokeConsole
   /** Terminal width used to wrap help output text */
   readonly columns: number
+  /** Exit function called on CLI errors. Defaults to process.exit */
+  readonly exit: (code: number) => void
 
   #defaultArgv: string[]
 
@@ -871,6 +892,7 @@ class Goke extends EventEmitter {
     this.stderr = options?.stderr ?? process.stderr
     this.console = createConsole(this.stdout, this.stderr)
     this.columns = options?.columns ?? process.stdout.columns ?? Number.POSITIVE_INFINITY
+    this.exit = options?.exit ?? ((code: number) => process.exit(code))
     this.#defaultArgv = options?.argv ?? processArgs
     this.globalCommand = new GlobalCommand(this)
     this.globalCommand.usage('<command> [options]')
@@ -937,18 +959,25 @@ class Goke extends EventEmitter {
     return this
   }
 
+  /**
+   * Return the formatted help string without printing it.
+   * When a sub-command is matched, returns help for that command.
+   * Otherwise returns the global help.
+   */
+  helpText(): string {
+    if (this.matchedCommand) {
+      return this.matchedCommand.helpText()
+    }
+    return this.globalCommand.helpText()
+  }
+
   /**
    * Output the corresponding help message
    * When a sub-command is matched, output the help message for the command
    * Otherwise output the global one.
-   *
    */
   outputHelp() {
-    if (this.matchedCommand) {
-      this.matchedCommand.outputHelp()
-    } else {
-      this.globalCommand.outputHelp()
-    }
+    this.console.log(this.helpText())
   }
 
   /**
@@ -1008,6 +1037,22 @@ class Goke extends EventEmitter {
     this.matchedCommandName = undefined
   }
 
+  /**
+   * Handle a CLI error by formatting it and writing to stderr.
+   * For GokeError / coercion errors, also includes a help hint.
+   */
+  private handleCliError(err: Error): void {
+    this.console.error(formatCliError(err))
+
+    // Add help hint when help is enabled
+    if (this.showHelpOnExit) {
+      const cmdName = this.matchedCommandName
+        ? `${this.name} ${this.matchedCommandName} --help`
+        : `${this.name} --help`
+      this.console.error(`\nRun "${cmdName}" for usage information.`)
+    }
+  }
+
   /**
    * Parse argv
    */
@@ -1032,53 +1077,61 @@ class Goke extends EventEmitter {
       return bLength - aLength
     })
 
-    // Search sub-commands
-    for (const command of sortedCommands) {
-      const parsed = this.mri(argv.slice(2), command)
-
-      const result = command.isMatched(parsed.args as string[])
-      if (result.matched) {
-        shouldParse = false
-        const matchedCommandName = parsed.args.slice(0, result.consumedArgs).join(' ')
-        const parsedInfo = {
-          ...parsed,
-          args: parsed.args.slice(result.consumedArgs),
+    // Search sub-commands — mri() can throw coercion errors, catch them
+    try {
+      for (const command of sortedCommands) {
+        const parsed = this.mri(argv.slice(2), command)
+
+        const result = command.isMatched(parsed.args as string[])
+        if (result.matched) {
+          shouldParse = false
+          const matchedCommandName = parsed.args.slice(0, result.consumedArgs).join(' ')
+          const parsedInfo = {
+            ...parsed,
+            args: parsed.args.slice(result.consumedArgs),
+          }
+          this.setParsedInfo(parsedInfo, command, matchedCommandName)
+          this.emit(`command:${matchedCommandName}`, command)
+          break // Stop after first match (greedy matching)
         }
-        this.setParsedInfo(parsedInfo, command, matchedCommandName)
-        this.emit(`command:${matchedCommandName}`, command)
-        break // Stop after first match (greedy matching)
       }
-    }
 
-    if (shouldParse) {
-      // Search the default command
-      for (const command of this.commands) {
-        if (command.name === '') {
-          // Check if any argument is a prefix of an existing command
-          // If so, don't match the default command (user probably mistyped a subcommand)
-          const parsed = this.mri(argv.slice(2), command)
-          const firstArg = parsed.args[0]
-          if (firstArg) {
-            const isPrefixOfCommand = this.commands.some((cmd) => {
-              if (cmd.name === '') return false
-              const cmdParts = cmd.name.split(' ')
-              return cmdParts[0] === firstArg
-            })
-            if (isPrefixOfCommand) {
-              // Don't match default command - let it fall through to "unknown command"
-              continue
+      if (shouldParse) {
+        // Search the default command
+        for (const command of this.commands) {
+          if (command.name === '') {
+            // Check if any argument is a prefix of an existing command
+            // If so, don't match the default command (user probably mistyped a subcommand)
+            const parsed = this.mri(argv.slice(2), command)
+            const firstArg = parsed.args[0]
+            if (firstArg) {
+              const isPrefixOfCommand = this.commands.some((cmd) => {
+                if (cmd.name === '') return false
+                const cmdParts = cmd.name.split(' ')
+                return cmdParts[0] === firstArg
+              })
+              if (isPrefixOfCommand) {
+                // Don't match default command - let it fall through to "unknown command"
+                continue
+              }
             }
+            shouldParse = false
+            this.setParsedInfo(parsed, command)
+            this.emit(`command:!`, command)
           }
-          shouldParse = false
-          this.setParsedInfo(parsed, command)
-          this.emit(`command:!`, command)
         }
       }
-    }
 
-    if (shouldParse) {
-      const parsed = this.mri(argv.slice(2))
-      this.setParsedInfo(parsed)
+      if (shouldParse) {
+        const parsed = this.mri(argv.slice(2))
+        this.setParsedInfo(parsed)
+      }
+    } catch (err) {
+      if (err instanceof GokeError) {
+        this.handleCliError(err)
+        this.exit(1)
+      }
+      throw err
     }
 
     if (this.options.help && this.showHelpOnExit) {
@@ -1275,11 +1328,17 @@ class Goke extends EventEmitter {
 
     if (!command || !command.commandAction) return
 
-    command.checkUnknownOptions()
-
-    command.checkOptionValue()
-
-    command.checkRequiredArgs()
+    try {
+      command.checkUnknownOptions()
+      command.checkOptionValue()
+      command.checkRequiredArgs()
+    } catch (err) {
+      if (err instanceof GokeError) {
+        this.handleCliError(err)
+        this.exit(1)
+      }
+      throw err
+    }
 
     const actionArgs: any[] = []
     command.args.forEach((arg, index) => {
@@ -1290,7 +1349,22 @@ class Goke extends EventEmitter {
       }
     })
     actionArgs.push(options)
-    return command.commandAction.apply(this, actionArgs)
+
+    const result = command.commandAction.apply(this, actionArgs)
+
+    // If the action returns a promise, catch async errors
+    if (result && typeof result === 'object' && typeof result.catch === 'function') {
+      result.catch((err: unknown) => {
+        if (err instanceof Error) {
+          this.handleCliError(err)
+        } else {
+          this.console.error(`${pc.red(pc.bold('error:'))} ${String(err)}`)
+        }
+        this.exit(1)
+      })
+    }
+
+    return result
   }
 }
 

package/src/index.ts

@@ -13,4 +13,4 @@ export { goke, Goke, Command }
 export { createConsole } from "./goke.js"
 export type { GokeOutputStream, GokeConsole, GokeOptions } from "./goke.js"
 export type { StandardTypedV1, StandardJSONSchemaV1, JsonSchema } from "./coerce.js"
-export { coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js"
+export { GokeError, coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js"