goke 6.9.0 → 6.10.0

package/src/goke.ts

@@ -15,6 +15,8 @@ import mri from "./mri.js"
 import { GokeError, coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js"
 import type { StandardJSONSchemaV1 } from "./coerce.js"
 import { createJustBashCommand as createJustBashCommandBridge } from './just-bash.js'
+import { COMPLETION_FLAG, generateCompletionScript, installCompletions, uninstallCompletions, detectShell, detectCompletionShell, validateShell } from './completions.js'
+import type { ShellType } from './completions.js'
 import type { GokeFs } from './goke-fs.js'
 import { EventEmitter, fs as runtimeFs, openInBrowser, process } from '#runtime'
 
@@ -630,10 +632,43 @@ class Command<RawName extends string = string, Opts = {}> {
   action(
     callback: (...args: ActionArgs<RawName, Opts>) => unknown | Promise<unknown>,
   ): this {
+    // Give anonymous functions a name derived from the command so stack traces
+    // show e.g. "command:deploy" instead of "<anonymous>"
+    if (!callback.name) {
+      const label = this.name ? `command:${this.name}` : 'command:default'
+      Object.defineProperty(callback, 'name', { value: label })
+    }
     this.commandAction = callback
     return this
   }
 
+  /**
+   * Return the registered action callback with full type safety.
+   *
+   * Use this in tests to call the action directly without parsing argv.
+   * The returned function has the same typed signature as the `.action()` callback:
+   * `(..positionalArgs, options, executionContext) => unknown | Promise<unknown>`
+   *
+   * Throws if no action has been registered on this command.
+   *
+   * @example
+   * ```ts
+   * const cmd = cli
+   *   .command('deploy', 'Deploy')
+   *   .option('--env <env>', z.enum(['staging', 'production']))
+   *   .action((options, { console }) => console.log(options.env))
+   *
+   * const action = cmd.getAction()
+   * action({ env: 'staging', '--': [] }, cli.createExecutionContext({ stdout }))
+   * ```
+   */
+  getAction(): (...args: ActionArgs<RawName, Opts>) => unknown | Promise<unknown> {
+    if (!this.commandAction) {
+      throw new GokeError(`No action registered on command "${this.name || '(default)'}"`)
+    }
+    return this.commandAction
+  }
+
   isMatched(args: string[]): { matched: boolean; consumedArgs: number } {
     const nameParts = this.name.split(' ').filter(Boolean)
 
@@ -1551,6 +1586,309 @@ class Goke<Opts = {}> extends EventEmitter {
     }
   }
 
+  /**
+   * Register shell completion commands: `completions install` and `completions uninstall`.
+   *
+   * Also wires the hidden `--get-goke-completions` flag that shell scripts call
+   * on each Tab press. When this flag is detected during `parse()`, the CLI
+   * prints matching completions to stdout and exits immediately.
+   *
+   * @example
+   * ```ts
+   * goke('mycli')
+   *   .help()
+   *   .completions()
+   *   .command('deploy', 'Deploy the app')
+   *   .parse(process.argv)
+   *
+   * // Then the user runs:
+   * //   mycli completions install
+   * //   mycli dep<TAB>  →  mycli deploy
+   * ```
+   */
+  completions() {
+    this.command('completions install', 'Install shell completions')
+      .option('--shell [shell]', 'Target shell (zsh or bash). Auto-detected if omitted.')
+      .action(async (options, { console, process: proc }) => {
+        const shell = validateShell(options.shell)
+        const cliPath = proc.argv[1] ?? this.name
+        const result = await installCompletions(this.name, cliPath, shell)
+        console.log(`Wrote ${result.shell} completions to ${result.path}`)
+        if (result.shell === 'zsh') {
+          console.log('Restart your shell or run: autoload -Uz compinit && compinit')
+        } else {
+          console.log('Restart your shell to enable completions.')
+        }
+      })
+
+    this.command('completions uninstall', 'Remove shell completions')
+      .option('--shell [shell]', 'Target shell (zsh or bash). Auto-detected if omitted.')
+      .action(async (options, { console }) => {
+        const shell = validateShell(options.shell)
+        const removed = await uninstallCompletions(this.name, shell)
+        if (removed.length > 0) {
+          for (const p of removed) {
+            console.log(`Removed ${p}`)
+          }
+        } else {
+          console.log('No completion files found to remove.')
+        }
+      })
+
+    this.command('completions script', 'Print the completion script to stdout')
+      .option('--shell [shell]', 'Target shell (zsh or bash). Auto-detected if omitted.')
+      .action((options, { console, process: proc }) => {
+        const shell = validateShell(options.shell) ?? detectShell()
+        if (!shell) {
+          throw new GokeError(
+            'Could not detect shell. Set the SHELL environment variable or pass --shell explicitly.',
+          )
+        }
+        const cliPath = proc.argv[1] ?? this.name
+        const script = generateCompletionScript(shell, this.name, cliPath)
+        console.log(script)
+      })
+
+    return this
+  }
+
+  /**
+   * Compute completions for the given args (as received from the shell script).
+   *
+   * Returns an array of completion strings. For zsh, each entry is `name:description`.
+   * For bash, each entry is just the name.
+   *
+   * @internal Used by parse() when --get-goke-completions is detected.
+   */
+  getCompletions(argv: string[]): string[] {
+    // argv comes from the shell: ["my-cli", "dep", ""] or ["my-cli", "deploy", "--"]
+    // Strip the binary name (first element, which is the CLI name itself)
+    const args = argv.slice(1)
+    const current = args.length > 0 ? args[args.length - 1] : ''
+    const previous = args.slice(0, -1)
+
+    // Use GOKE_COMPLETION_SHELL (set by the shell shim) over $SHELL to avoid
+    // format mismatch when e.g. a bash shim runs on a machine where $SHELL is zsh.
+    const isZsh = detectCompletionShell() === 'zsh'
+
+    const completions: string[] = []
+    const escapeColon = (s: string) => s.replace(/:/g, '\\:')
+
+    // Extract the long --flag from an option's rawName string.
+    // rawName is like "--dry-run", "-v, --verbose", "--port <port>"
+    // Returns the original kebab-case flag including dashes.
+    const getLongFlag = (option: Option): string => {
+      const parts = removeBrackets(option.rawName).split(',').map((s) => s.trim())
+      // Prefer the -- prefixed part; fall back to the last part (short-only flags like -x)
+      const longPart = parts.find((p) => p.startsWith('--')) ?? parts[parts.length - 1]
+      return longPart.startsWith('-') ? longPart : `--${longPart}`
+    }
+
+    // Check if the previous token is a non-boolean option expecting a value.
+    // In that case we should NOT suggest more flags or commands; let the shell
+    // fall back to file completion or return nothing.
+    const isAwaitingOptionValue = (): boolean => {
+      if (previous.length === 0) return false
+      const lastToken = previous[previous.length - 1]
+      if (!lastToken.startsWith('-')) return false
+
+      // Find the option matching this token across all registered options
+      const allOptions = [
+        ...this.globalCommand.options,
+        ...this.commands.flatMap((c) => c.options),
+      ]
+      const tokenName = camelcaseOptionName(lastToken.replace(/^-{1,2}/, ''))
+      for (const option of allOptions) {
+        if (option.names.includes(tokenName)) {
+          // If it takes a value (required or optional) and is not boolean, we're awaiting a value
+          return !option.isBoolean && option.required !== undefined
+        }
+      }
+      return false
+    }
+
+    // If the previous token is a non-boolean option, don't suggest anything.
+    // Let the shell fall back to file completion.
+    if (!current.startsWith('-') && isAwaitingOptionValue()) {
+      return []
+    }
+
+    // Helper to push an option as a completion entry
+    const pushOption = (option: Option) => {
+      const flag = getLongFlag(option)
+      if (isZsh && option.description) {
+        completions.push(`${escapeColon(flag)}:${escapeColon(option.description)}`)
+      } else {
+        completions.push(flag)
+      }
+    }
+
+    // Check if any alias of an option has already been used
+    const isOptionUsed = (option: Option, usedOptions: Set<string>): boolean => {
+      return option.names.some((name) => usedOptions.has(name))
+    }
+
+    // Try to match a command from the previous words
+    let matchedCommand: Command | undefined
+    let consumedArgs = 0
+
+    // Sort by name length (longest first) for greedy matching
+    const sortedCommands = [...this.commands].sort((a, b) => {
+      const aLen = a.name.split(' ').filter(Boolean).length
+      const bLen = b.name.split(' ').filter(Boolean).length
+      return bLen - aLen
+    })
+
+    for (const command of sortedCommands) {
+      const result = command.isMatched(previous as string[])
+      if (result.matched) {
+        matchedCommand = command
+        consumedArgs = result.consumedArgs
+        break
+      }
+    }
+
+    if (matchedCommand) {
+      // We matched a command, suggest its options
+      const usedOptions = new Set(
+        previous.slice(consumedArgs)
+          .filter((a) => a.startsWith('-'))
+          .map((a) => a.replace(/^-{1,2}/, ''))
+          .map(camelcaseOptionName),
+      )
+
+      const allOptions = [...(matchedCommand.globalCommand?.options ?? []), ...matchedCommand.options]
+
+      for (const option of allOptions) {
+        if (option.deprecated) continue
+        // Skip already-used options (check all aliases, not just the primary name)
+        if (option.isBoolean && isOptionUsed(option, usedOptions)) continue
+
+        const flag = getLongFlag(option)
+
+        if (current.startsWith('-')) {
+          if (!flag.startsWith(current)) continue
+        } else if (current !== '') {
+          continue
+        }
+
+        pushOption(option)
+      }
+
+      // If current word doesn't start with -, also suggest subcommands that extend this one
+      if (!current.startsWith('-')) {
+        const prefix = matchedCommand.name ? matchedCommand.name + ' ' : ''
+        for (const cmd of this.commands) {
+          if (cmd._hidden) continue
+          if (cmd === matchedCommand) continue
+          if (cmd.name.startsWith(prefix) && cmd.name !== matchedCommand.name) {
+            const sub = cmd.name.slice(prefix.length).split(' ')[0]
+            if (sub.startsWith(current)) {
+              if (isZsh) {
+                const desc = cmd.description.split('\n')[0].trim()
+                completions.push(desc ? `${escapeColon(sub)}:${escapeColon(desc)}` : sub)
+              } else {
+                completions.push(sub)
+              }
+            }
+          }
+        }
+      }
+    } else {
+      // No command matched yet, suggest commands
+      // Check if some previous words partially match a multi-word command prefix
+      const prevJoined = previous.join(' ')
+
+      for (const command of this.commands) {
+        if (command._hidden) continue
+        if (command.isDefaultCommand) continue
+
+        const cmdName = command.name
+        const cmdParts = cmdName.split(' ').filter(Boolean)
+
+        if (cmdParts.length === 0) continue
+
+        // For single-word commands, just check prefix against current
+        if (cmdParts.length === 1) {
+          if (previous.length === 0 && cmdParts[0].startsWith(current)) {
+            if (isZsh) {
+              const desc = command.description.split('\n')[0].trim()
+              completions.push(desc ? `${escapeColon(cmdParts[0])}:${escapeColon(desc)}` : cmdParts[0])
+            } else {
+              completions.push(cmdParts[0])
+            }
+          }
+          continue
+        }
+
+        // Multi-word commands: check if previous matches the prefix parts
+        const matchPrefix = cmdParts.slice(0, -1).join(' ')
+        const lastPart = cmdParts[cmdParts.length - 1]
+        if (prevJoined === matchPrefix && lastPart.startsWith(current)) {
+          if (isZsh) {
+            const desc = command.description.split('\n')[0].trim()
+            completions.push(desc ? `${escapeColon(lastPart)}:${escapeColon(desc)}` : lastPart)
+          } else {
+            completions.push(lastPart)
+          }
+        }
+      }
+
+      // Also suggest first words of multi-word commands when at root level
+      if (previous.length === 0) {
+        const seenFirstWords = new Set<string>()
+        for (const command of this.commands) {
+          if (command._hidden || command.isDefaultCommand) continue
+          const firstWord = command.name.split(' ')[0]
+          if (!firstWord || seenFirstWords.has(firstWord)) continue
+          // Skip if already added as a single-word command above
+          if (completions.some((c) => {
+            const name = c.split(':')[0].replace(/\\:/g, ':')
+            return name === firstWord
+          })) continue
+          seenFirstWords.add(firstWord)
+          if (firstWord.startsWith(current)) {
+            // For first words of multi-word commands, no description (it's a prefix, not a full command)
+            completions.push(firstWord)
+          }
+        }
+      }
+
+      // Also include default/root command options at root level
+      // (commands with name '' that have their own options)
+      const defaultCommands = this.commands.filter((c) => c.isDefaultCommand)
+      const defaultOptions = defaultCommands.flatMap((c) => c.options)
+
+      // Suggest global options + default command options when current starts with -
+      if (current.startsWith('-') || current === '') {
+        const globalAndDefaultOptions = [...this.globalCommand.options, ...defaultOptions]
+        const seen = new Set<string>()
+
+        for (const option of globalAndDefaultOptions) {
+          if (option.deprecated) continue
+          if (seen.has(option.name)) continue
+          seen.add(option.name)
+
+          const flag = getLongFlag(option)
+
+          if (current.startsWith('-')) {
+            if (!flag.startsWith(current)) continue
+          } else if (current !== '') {
+            continue
+          }
+
+          // Only suggest options when current is - prefixed or empty and no commands matched
+          if (current === '' && completions.length > 0 && !current.startsWith('-')) continue
+
+          pushOption(option)
+        }
+      }
+    }
+
+    // Deduplicate
+    return [...new Set(completions)]
+  }
+
   /**
    * Parse argv
    */
@@ -1566,6 +1904,20 @@ class Goke<Opts = {}> extends EventEmitter {
       this.name = argv[1] ? getFileName(argv[1]) : 'cli'
     }
 
+    // Intercept --get-goke-completions before any command matching/validation.
+    // The shell completion script passes this flag on every Tab press.
+    const completionFlagIndex = argv.indexOf(`--${COMPLETION_FLAG}`)
+    if (completionFlagIndex !== -1) {
+      // Everything after the flag is the words typed so far
+      const completionArgs = argv.slice(completionFlagIndex + 1)
+      const completions = this.getCompletions(completionArgs)
+      for (const c of completions) {
+        this.stdout.write(c + '\n')
+      }
+      this.exit(0)
+      return { args: [], options: {} }
+    }
+
     let shouldParse = true
 
     // Sort by name length (longest first) so "mcp login" matches before "mcp"
@@ -1943,8 +2295,183 @@ class Goke<Opts = {}> extends EventEmitter {
   }
 }
 
+// ─── Doc generation ───
+
+interface DocPage {
+  /** The command name, e.g. "event view". Empty string for the root CLI page. */
+  command: string
+  /** URL-friendly slug, e.g. "event-view". "index" for the root CLI page. */
+  slug: string
+  /** Full markdown content for this command's documentation page. */
+  content: string
+}
+
+interface GenerateDocsOptions {
+  /** The Goke CLI instance to generate docs from. */
+  cli: Goke<any>
+}
+
+/**
+ * Generate markdown documentation pages for every command in a CLI.
+ *
+ * Returns one `DocPage` per non-hidden command, plus a root index page
+ * that lists all available commands. Each page includes an arguments table,
+ * options table, global options, and examples when available.
+ *
+ * @example
+ * ```ts
+ * import { goke, generateDocs } from 'goke'
+ * import fs from 'node:fs'
+ *
+ * const cli = goke('mycli')
+ *   .command('deploy <env>', 'Deploy to an environment')
+ *   .option('--force', 'Skip confirmation')
+ *
+ * const pages = generateDocs({ cli })
+ * for (const page of pages) {
+ *   fs.writeFileSync(`docs/${page.slug}.md`, page.content)
+ * }
+ * ```
+ */
+function generateDocs({ cli }: GenerateDocsOptions): DocPage[] {
+  const pages: DocPage[] = []
+
+  // Collect global options (from globalCommand), excluding deprecated
+  const globalOptions = cli.globalCommand.options.filter((o) => !o.deprecated)
+
+  // Root index page listing all commands
+  const visibleCommands = cli.commands.filter((cmd) => !cmd._hidden)
+  if (visibleCommands.length > 0) {
+    const lines: string[] = []
+    lines.push(`# ${cli.name}`)
+    lines.push('')
+
+    const { versionNumber } = cli.globalCommand
+    if (versionNumber) {
+      lines.push(`Version: ${versionNumber}`)
+      lines.push('')
+    }
+
+    lines.push('## Commands')
+    lines.push('')
+    lines.push('| Command | Description |')
+    lines.push('|---------|-------------|')
+    for (const cmd of visibleCommands) {
+      if (cmd.isDefaultCommand) continue
+      const desc = cmd.description.split('\n')[0].trim()
+      const slug = cmd.name.replace(/\s+/g, '-')
+      lines.push(`| [\`${cmd.name}\`](./${slug}.md) | ${desc} |`)
+    }
+    lines.push('')
+
+    if (globalOptions.length > 0) {
+      lines.push('## Global Options')
+      lines.push('')
+      lines.push(formatOptionsTable(globalOptions))
+      lines.push('')
+    }
+
+    pages.push({ command: '', slug: 'index', content: lines.join('\n') })
+  }
+
+  // One page per command
+  for (const cmd of visibleCommands) {
+    if (cmd.isDefaultCommand) continue
+    const lines: string[] = []
+    const title = cmd.name
+    lines.push(`# ${title}`)
+    lines.push('')
+
+    if (cmd.description) {
+      lines.push(cmd.description)
+      lines.push('')
+    }
+
+    // Usage line
+    const usage = cmd.usageText || cmd.rawName
+    lines.push('## Usage')
+    lines.push('')
+    lines.push('```sh')
+    lines.push(`${cli.name} ${usage}`)
+    lines.push('```')
+    lines.push('')
+
+    // Arguments table
+    if (cmd.args.length > 0) {
+      lines.push('## Arguments')
+      lines.push('')
+      lines.push('| Argument | Required | Description |')
+      lines.push('|----------|----------|-------------|')
+      for (const arg of cmd.args) {
+        const bracket = arg.required
+          ? `<${arg.variadic ? '...' : ''}${arg.value}>`
+          : `[${arg.variadic ? '...' : ''}${arg.value}]`
+        const required = arg.required ? 'Yes' : 'No'
+        const desc = arg.variadic ? `${arg.value} (variadic)` : arg.value
+        lines.push(`| \`${bracket}\` | ${required} | ${desc} |`)
+      }
+      lines.push('')
+    }
+
+    // Command-specific options
+    const cmdOptions = cmd.options.filter((o) => !o.deprecated)
+    if (cmdOptions.length > 0) {
+      lines.push('## Options')
+      lines.push('')
+      lines.push(formatOptionsTable(cmdOptions))
+      lines.push('')
+    }
+
+    // Global options section
+    if (globalOptions.length > 0) {
+      lines.push('## Global Options')
+      lines.push('')
+      lines.push(formatOptionsTable(globalOptions))
+      lines.push('')
+    }
+
+    // Examples
+    if (cmd.examples.length > 0) {
+      lines.push('## Examples')
+      lines.push('')
+      for (const example of cmd.examples) {
+        const text = typeof example === 'function' ? example(cli.name) : example
+        // Auto-wrap in ```sh if not already fenced
+        if (text.trimStart().startsWith('```')) {
+          lines.push(text)
+        } else {
+          lines.push('```sh')
+          lines.push(text)
+          lines.push('```')
+        }
+        lines.push('')
+      }
+    }
+
+    const slug = cmd.name.replace(/\s+/g, '-')
+    pages.push({ command: cmd.name, slug, content: lines.join('\n') })
+  }
+
+  return pages
+}
+
+function formatOptionsTable(options: Option[]): string {
+  const lines: string[] = []
+  lines.push('| Option | Default | Description |')
+  lines.push('|--------|---------|-------------|')
+  for (const opt of options) {
+    const defaultVal = opt.default !== undefined ? `\`${String(opt.default)}\`` : '-'
+    // Escape pipe characters in description for markdown tables
+    const desc = opt.description.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+    lines.push(`| \`${opt.rawName}\` | ${defaultVal} | ${desc} |`)
+  }
+  return lines.join('\n')
+}
+
 // ─── Exports ───
 
-export type { GokeOutputStream, GokeConsole, GokeOptions, GokeProcess, GokeExecutionContext, GokeExecutionContextOverride, GokeFs }
-export { createConsole, Command, GokeProcessExit, openInBrowser }
+export type { GokeOutputStream, GokeConsole, GokeOptions, GokeProcess, GokeExecutionContext, GokeExecutionContextOverride, GokeFs, DocPage, GenerateDocsOptions }
+export { createConsole, Command, GokeProcessExit, openInBrowser, generateDocs }
+export type { ShellType }
+export { generateCompletionScript, installCompletions, uninstallCompletions, detectShell, detectCompletionShell, validateShell }
 export default Goke

package/src/index.ts

@@ -1,6 +1,7 @@
 import Goke from "./goke.js"
 import type { GokeOptions } from "./goke.js"
 import { Command } from "./goke.js"
+import pc from "./picocolors.js"
 
 /**
  * @param name The program name to display in help and version message
@@ -8,9 +9,17 @@ import { Command } from "./goke.js"
  */
 const goke = (name = '', options?: GokeOptions) => new Goke(name, options)
 
+/**
+ * Vendored picocolors instance for terminal colors.
+ * Import this instead of installing picocolors, chalk, or any other color library.
+ */
+export const colors = pc
+
 export default goke
 export { goke, Goke, Command }
-export { createConsole, GokeProcessExit, openInBrowser } from "./goke.js"
-export type { GokeOutputStream, GokeConsole, GokeExecutionContext, GokeExecutionContextOverride, GokeFs, GokeOptions, GokeProcess } from "./goke.js"
+export { createConsole, GokeProcessExit, openInBrowser, generateDocs, generateCompletionScript, installCompletions, uninstallCompletions, detectShell } from "./goke.js"
+export type { GokeOutputStream, GokeConsole, GokeExecutionContext, GokeExecutionContextOverride, GokeFs, GokeOptions, GokeProcess, DocPage, GenerateDocsOptions, ShellType } from "./goke.js"
 export type { StandardTypedV1, StandardJSONSchemaV1, JsonSchema } from "./coerce.js"
 export { GokeError, coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js"
+export { detectAgent, agentInfo, agent, isAgent } from "./agents.js"
+export type { AgentName, AgentInfo } from "./agents.js"

package/src/runtime-browser.ts

@@ -86,7 +86,7 @@ const fs: GokeFs = {
   writeFile: createUnsupportedFsMethod<GokeFs['writeFile']>('writeFile'),
 }
 
-function openInBrowser(_url: string): void {
+async function openInBrowser(_url: string): Promise<void> {
   // Browser builds should decide how to surface URLs themselves.
 }
 

package/src/runtime-node.ts

@@ -2,7 +2,7 @@
  * Node.js runtime bindings for goke core.
  */
 
-import { execSync } from 'child_process'
+import { exec } from 'child_process'
 import { EventEmitter } from 'events'
 import * as nodeFs from 'node:fs/promises'
 import type { GokeFs } from './goke-fs.js'
@@ -10,22 +10,30 @@ import type { GokeFs } from './goke-fs.js'
 const process = globalThis.process
 const fs: GokeFs = nodeFs
 
-function openInBrowser(url: string): void {
+async function openInBrowser(url: string): Promise<void> {
   if (!process.stdout.isTTY) {
-    process.stdout.write(url + '\n')
+    process.stderr.write(url + '\n')
     return
   }
 
+  let cmd: string
+  if (process.platform === 'darwin') {
+    cmd = `open ${JSON.stringify(url)}`
+  } else if (process.platform === 'win32') {
+    cmd = `start "" ${JSON.stringify(url)}`
+  } else {
+    cmd = `xdg-open ${JSON.stringify(url)}`
+  }
+
   try {
-    if (process.platform === 'darwin') {
-      execSync(`open ${JSON.stringify(url)}`, { stdio: 'ignore' })
-    } else if (process.platform === 'win32') {
-      execSync(`start "" ${JSON.stringify(url)}`, { stdio: 'ignore' })
-    } else {
-      execSync(`xdg-open ${JSON.stringify(url)}`, { stdio: 'ignore' })
-    }
+    await new Promise<void>((resolve, reject) => {
+      exec(cmd, { stdio: 'ignore' } as any, (err) => {
+        if (err) reject(err)
+        else resolve()
+      })
+    })
   } catch {
-    process.stdout.write(url + '\n')
+    process.stderr.write(url + '\n')
   }
 }