goke 6.8.0 → 6.10.0

package/src/__test__/index.test.ts

@@ -160,6 +160,39 @@ describe('error formatting', () => {
   })
 })
 
+describe('anonymous action naming', () => {
+  test('inline anonymous function gets named after the command', () => {
+    const cli = gokeTestable('mycli')
+    const cmd = cli.command('deploy', 'Deploy app')
+    // Inline arrow functions passed directly to .action() have no name,
+    // so goke assigns one based on the command name for better stack traces.
+    cmd.action(() => {})
+    expect(cmd.commandAction!.name).toBe('command:deploy')
+  })
+
+  test('inline anonymous function on multi-word command gets full name', () => {
+    const cli = gokeTestable('mycli')
+    const cmd = cli.command('db migrate', 'Run migrations')
+    cmd.action(() => {})
+    expect(cmd.commandAction!.name).toBe('command:db migrate')
+  })
+
+  test('named function keeps its original name', () => {
+    const cli = gokeTestable('mycli')
+    const cmd = cli.command('build', 'Build app')
+    function myBuildAction() {}
+    cmd.action(myBuildAction)
+    expect(cmd.commandAction!.name).toBe('myBuildAction')
+  })
+
+  test('default command action gets "command:default" name', () => {
+    const cli = gokeTestable('mycli')
+    const cmd = cli.command('', 'Default command')
+    cmd.action(() => {})
+    expect(cmd.commandAction!.name).toBe('command:default')
+  })
+})
+
 describe('injected fs', () => {
   test('command actions can use the default node fs for cli storage', async () => {
     const stdout = createTestOutputStream()
@@ -2336,3 +2369,211 @@ describe('middleware', () => {
     expect(order).toEqual(['sync1', 'async', 'sync2', 'action'])
   })
 })
+
+describe('use() with sub-CLI composition', () => {
+  test('basic composition: sub-CLI command runs via parent', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let matched = ''
+
+    sub
+      .command('deploy', 'Deploy the app')
+      .action(() => { matched = 'deploy' })
+
+    parent.use(sub)
+    parent.parse(['node', 'bin', 'deploy'], { run: true })
+    expect(matched).toBe('deploy')
+  })
+
+  test('multiple sub-CLIs composed together', () => {
+    const parent = goke('mycli')
+    const subA = goke()
+    const subB = goke()
+    let matched = ''
+
+    subA.command('login', 'Login').action(() => { matched = 'login' })
+    subB.command('deploy', 'Deploy').action(() => { matched = 'deploy' })
+
+    parent.use(subA).use(subB)
+
+    parent.parse(['node', 'bin', 'login'], { run: true })
+    expect(matched).toBe('login')
+
+    matched = ''
+    parent.parse(['node', 'bin', 'deploy'], { run: true })
+    expect(matched).toBe('deploy')
+  })
+
+  test('sub-CLI command with options and schema coercion', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let result: any = {}
+
+    sub
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number().describe('Port'))
+      .option('--host <host>', z.string().describe('Host'))
+      .action((options) => { result = options })
+
+    parent.use(sub)
+    parent.parse('node bin serve --port 3000 --host localhost'.split(' '), { run: true })
+
+    expect(result.port).toBe(3000)
+    expect(typeof result.port).toBe('number')
+    expect(result.host).toBe('localhost')
+  })
+
+  test('sub-CLI command with positional args', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let receivedId = ''
+
+    sub
+      .command('get <id>', 'Get a resource')
+      .action((id) => { receivedId = id })
+
+    parent.use(sub)
+    parent.parse(['node', 'bin', 'get', 'abc123'], { run: true })
+
+    expect(receivedId).toBe('abc123')
+  })
+
+  test('sub-CLI with multi-word commands', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let matched = ''
+
+    sub.command('mcp login', 'Login to MCP').action(() => { matched = 'mcp login' })
+    sub.command('mcp logout', 'Logout from MCP').action(() => { matched = 'mcp logout' })
+
+    parent.use(sub)
+
+    parent.parse(['node', 'bin', 'mcp', 'login'], { run: true })
+    expect(matched).toBe('mcp login')
+
+    matched = ''
+    parent.parse(['node', 'bin', 'mcp', 'logout'], { run: true })
+    expect(matched).toBe('mcp logout')
+  })
+
+  test('help output includes composed commands', () => {
+    const stdout = createTestOutputStream()
+    const parent = goke('mycli', { stdout })
+    const sub = goke()
+
+    sub.command('selfhost', 'Set up on your own workspace')
+      .option('-t, --token [token]', 'Admin token')
+
+    parent.command('init', 'Initialize project')
+    parent.use(sub)
+    parent.help()
+    parent.parse(['node', 'bin', '--help'], { run: false })
+
+    expect(stdout.text).toContain('init')
+    expect(stdout.text).toContain('selfhost')
+    expect(stdout.text).toContain('Set up on your own workspace')
+  })
+
+  test('sub-CLI middlewares are NOT copied to parent', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let subMiddlewareCalled = false
+    const order: string[] = []
+
+    sub.use(() => { subMiddlewareCalled = true })
+    sub.command('deploy', 'Deploy').action(() => { order.push('deploy') })
+
+    parent.use(() => { order.push('parent-mw') })
+    parent.use(sub)
+
+    parent.parse(['node', 'bin', 'deploy'], { run: true })
+
+    expect(subMiddlewareCalled).toBe(false)
+    expect(order).toEqual(['parent-mw', 'deploy'])
+  })
+
+  test('parent global options are available to composed commands', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let result: any = {}
+
+    parent.option('--verbose', 'Verbose output')
+
+    sub
+      .command('build', 'Build')
+      .option('--target <target>', 'Build target')
+      .action((options) => { result = options })
+
+    parent.use(sub)
+    parent.parse('node bin build --verbose --target production'.split(' '), { run: true })
+
+    expect(result.verbose).toBe(true)
+    expect(result.target).toBe('production')
+  })
+
+  test('composed commands coexist with inline commands', () => {
+    const parent = goke('mycli')
+    const sub = goke()
+    let matched = ''
+
+    parent.command('init', 'Initialize').action(() => { matched = 'init' })
+
+    sub.command('deploy', 'Deploy').action(() => { matched = 'deploy' })
+    sub.command('rollback', 'Rollback').action(() => { matched = 'rollback' })
+
+    parent.use(sub)
+
+    parent.parse(['node', 'bin', 'init'], { run: true })
+    expect(matched).toBe('init')
+
+    matched = ''
+    parent.parse(['node', 'bin', 'deploy'], { run: true })
+    expect(matched).toBe('deploy')
+
+    matched = ''
+    parent.parse(['node', 'bin', 'rollback'], { run: true })
+    expect(matched).toBe('rollback')
+  })
+})
+
+describe('getAction()', () => {
+  test('returns the action callable with correct behavior', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout, exit: () => {} })
+
+    const cmd = cli
+      .command('deploy', 'Deploy the app')
+      .option('--env <env>', z.enum(['staging', 'production']).describe('Target environment'))
+      .action((options, { console }) => {
+        console.log(`Deploying to ${options.env}`)
+      })
+
+    const action = cmd.getAction()
+    const ctx = cli.createExecutionContext()
+    action({ env: 'staging' as const, '--': [] }, ctx)
+    expect(stdout.text).toBe('Deploying to staging\n')
+  })
+
+  test('works with positional args', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout, exit: () => {} })
+
+    const cmd = cli
+      .command('get <id>', 'Fetch by id')
+      .option('--format <format>', z.string().describe('Output format'))
+      .action((id, options, { console }) => {
+        console.log(`${id}:${options.format}`)
+      })
+
+    const action = cmd.getAction()
+    const ctx = cli.createExecutionContext()
+    action('abc123', { format: 'json', '--': [] }, ctx)
+    expect(stdout.text).toBe('abc123:json\n')
+  })
+
+  test('throws when no action is registered', () => {
+    const cli = goke('mycli')
+    const cmd = cli.command('noop', 'No action')
+    expect(() => cmd.getAction()).toThrow(/No action registered/)
+  })
+})

package/src/__test__/just-bash.test.ts

@@ -389,4 +389,28 @@ describe('createJustBashCommand', () => {
       exitCode: 7,
     })
   })
+
+  test('truncates captured output to just-bash maxOutputSize and appends a notice', async () => {
+    const { Bash } = await import('just-bash')
+    const cli = gokeTestable('parent')
+
+    cli
+      .command('spam-stderr', 'Write too much stderr')
+      .action((options, { console }) => {
+        console.error('x'.repeat(60))
+        console.error('y'.repeat(60))
+      })
+
+    const bash = new Bash({
+      executionLimits: { maxOutputSize: 80 },
+      customCommands: [await cli.createJustBashCommand()],
+    })
+
+    const result = await bash.exec('parent spam-stderr')
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toBe('')
+    expect(result.stderr.length).toBeLessThanOrEqual(80)
+    expect(result.stderr).toBe(`${'x'.repeat(60)}\n[output truncated]\n`)
+  })
 })

package/src/__test__/readme-examples.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest'
 import { z } from 'zod'
-import goke, { openInBrowser } from '../index.js'
+import goke, { openInBrowser, generateDocs } from '../index.js'
 import type { GokeOptions, GokeOutputStream } from '../index.js'
 
 const ANSI_RE = /\x1B\[[0-9;]*m/g
@@ -187,7 +187,7 @@ describe('documented command APIs', () => {
     expect(stdout.text).toBe('')
   })
 
-  test('openInBrowser prints the URL to stdout in non-tty environments', () => {
+  test('openInBrowser prints the URL to stdout in non-tty environments', async () => {
     const url = 'https://example.com/dashboard'
     const originalStdoutWrite = process.stdout.write
     const originalStderrWrite = process.stderr.write
@@ -209,7 +209,7 @@ describe('documented command APIs', () => {
     }) as typeof process.stderr.write
 
     try {
-      openInBrowser(url)
+      await openInBrowser(url)
     } finally {
       process.stdout.write = originalStdoutWrite
       process.stderr.write = originalStderrWrite
@@ -219,7 +219,155 @@ describe('documented command APIs', () => {
       })
     }
 
-    expect(stdout).toBe(`${url}\n`)
-    expect(stderr).toBe('')
+    expect(stdout).toBe('')
+    expect(stderr).toBe(`${url}\n`)
+  })
+})
+
+describe('generateDocs', () => {
+  test('generates pages for CLI with multiple commands', () => {
+    const cli = gokeTestable('sentry')
+      .version('1.0.0')
+      .help()
+
+    cli
+      .command('event view <id>', 'View details of a specific event')
+      .option('-w, --web', 'Open in browser')
+      .option('--spans <spans>', z.string().default('3').describe('Span tree depth limit'))
+      .example('```\nsentry event view abc123\n```')
+
+    cli
+      .command('event list <issue>', 'List events for an issue')
+      .option('-n, --limit <limit>', z.number().default(25).describe('Number of events'))
+      .option('-q, --query <query>', 'Search query')
+
+    cli
+      .command('hidden-cmd', 'Should not appear')
+      .hidden()
+
+    const pages = generateDocs({ cli })
+
+    expect(pages.map((p) => p.slug)).toMatchInlineSnapshot(`
+      [
+        "index",
+        "event-view",
+        "event-list",
+      ]
+    `)
+
+    // Index page
+    expect(pages[0].content).toMatchInlineSnapshot(`
+      "# sentry
+
+      Version: 1.0.0
+
+      ## Commands
+
+      | Command | Description |
+      |---------|-------------|
+      | [\`event view\`](./event-view.md) | View details of a specific event |
+      | [\`event list\`](./event-list.md) | List events for an issue |
+
+      ## Global Options
+
+      | Option | Default | Description |
+      |--------|---------|-------------|
+      | \`-v, --version\` | - | Display version number |
+      | \`-h, --help\` | - | Display this message |
+      "
+    `)
+
+    // Command page with examples
+    expect(pages[1].content).toMatchInlineSnapshot(`
+      "# event view
+
+      View details of a specific event
+
+      ## Usage
+
+      \`\`\`sh
+      sentry event view <id>
+      \`\`\`
+
+      ## Arguments
+
+      | Argument | Required | Description |
+      |----------|----------|-------------|
+      | \`<id>\` | Yes | id |
+
+      ## Options
+
+      | Option | Default | Description |
+      |--------|---------|-------------|
+      | \`-w, --web\` | - | Open in browser |
+      | \`--spans <spans>\` | \`3\` | Span tree depth limit |
+
+      ## Global Options
+
+      | Option | Default | Description |
+      |--------|---------|-------------|
+      | \`-v, --version\` | - | Display version number |
+      | \`-h, --help\` | - | Display this message |
+
+      ## Examples
+
+      \`\`\`
+      sentry event view abc123
+      \`\`\`
+      "
+    `)
+
+    // Command page without examples
+    expect(pages[2].content).toMatchInlineSnapshot(`
+      "# event list
+
+      List events for an issue
+
+      ## Usage
+
+      \`\`\`sh
+      sentry event list <issue>
+      \`\`\`
+
+      ## Arguments
+
+      | Argument | Required | Description |
+      |----------|----------|-------------|
+      | \`<issue>\` | Yes | issue |
+
+      ## Options
+
+      | Option | Default | Description |
+      |--------|---------|-------------|
+      | \`-n, --limit <limit>\` | \`25\` | Number of events |
+      | \`-q, --query <query>\` | - | Search query |
+
+      ## Global Options
+
+      | Option | Default | Description |
+      |--------|---------|-------------|
+      | \`-v, --version\` | - | Display version number |
+      | \`-h, --help\` | - | Display this message |
+      "
+    `)
+  })
+
+  test('handles CLI with no commands', () => {
+    const cli = gokeTestable('empty')
+    const pages = generateDocs({ cli })
+    expect(pages).toEqual([])
+  })
+
+  test('skips deprecated options', () => {
+    const cli = gokeTestable('mycli')
+    cli
+      .command('deploy', 'Deploy the app')
+      .option('--force', 'Skip confirmation')
+      .option('--old-flag', z.boolean().meta({ deprecated: true }).describe('Use --force instead'))
+
+    const pages = generateDocs({ cli })
+    const deployPage = pages.find((p) => p.slug === 'deploy')!
+    // The deprecated option should not appear
+    expect(deployPage.content).not.toContain('old-flag')
   })
 })

package/src/__test__/types.test-d.ts

@@ -481,6 +481,74 @@ describe('type-level: README TypeScript examples', () => {
       })
   })
 
+  test('use() with sub-CLI preserves parent middleware typing', () => {
+    const sub = goke()
+    sub
+      .command('deploy', 'Deploy the app')
+      .option('--force', z.boolean())
+      .action((options) => {
+        // Sub-CLI command's action sees its own options
+        expectTypeOf(options.force).toEqualTypeOf<boolean | undefined>()
+      })
+
+    goke('test')
+      .option('--verbose', z.boolean().default(false).describe('Verbose'))
+      .use(sub)
+      .use((options) => {
+        // Parent middleware still sees parent's accumulated options after .use(subCli)
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean>()
+      })
+      .command('build', 'Build')
+      .option('--target <target>', z.string())
+      .action((options) => {
+        // Parent's inline command still sees global options
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean>()
+        expectTypeOf(options.target).toEqualTypeOf<string>()
+      })
+  })
+
+  test('use() with sub-CLI does not leak sub-CLI types to parent', () => {
+    const sub = goke()
+      .option('--sub-only <val>', z.string())
+    sub.command('sub-cmd', 'Sub command').action(() => {})
+
+    goke('test')
+      .option('--parent-only <val>', z.number())
+      .use(sub)
+      .use((options) => {
+        expectTypeOf(options.parentOnly).toEqualTypeOf<number>()
+        // @ts-expect-error subOnly is not declared on the parent
+        options.subOnly
+      })
+  })
+
+  test('getAction() returns correctly typed function', () => {
+    const cmd = goke('test')
+      .command('convert <input> <output>', 'Convert file format')
+      .option('--quality <quality>', z.number())
+      .option('--format <format>', z.enum(['png', 'jpg']))
+      .action((input, output, options, ctx) => {
+        void input; void output; void options; void ctx
+      })
+
+    const action = cmd.getAction()
+    expectTypeOf(action).parameter(0).toEqualTypeOf<string>() // input
+    expectTypeOf(action).parameter(1).toEqualTypeOf<string>() // output
+  })
+
+  test('getAction() with no positional args has (options, ctx) signature', () => {
+    const cmd = goke('test')
+      .command('deploy', 'Deploy')
+      .option('--env <env>', z.enum(['staging', 'production']))
+      .action((options, ctx) => {
+        void options; void ctx
+      })
+
+    const action = cmd.getAction()
+    // First param is options with env
+    expectTypeOf(action).parameter(0).toMatchTypeOf<{ env: 'staging' | 'production' }>()
+  })
+
   test('README global options and middleware example stays typed end-to-end', () => {
     // `z.boolean().default(false)` and `z.string().default(...)` are
     // effectively required at runtime: the default applies when the flag is

package/src/agents.ts

@@ -0,0 +1,101 @@
+/**
+ * AI coding agent detection for goke CLIs.
+ *
+ * Detects whether the current process is running inside an AI coding agent
+ * (Claude, Cursor, Codex, Gemini, etc.) by checking environment variables.
+ * Ported from unjs/std-env with the same detection logic.
+ *
+ * CLI authors can use this to adjust behavior: skip interactive prompts,
+ * prefer structured output, avoid browser opens, etc.
+ */
+
+const env: Record<string, string | undefined> =
+  globalThis.process?.env || Object.create(null)
+
+/**
+ * Known AI coding agent names.
+ */
+export type AgentName =
+  | (string & {})
+  | 'cursor'
+  | 'claude'
+  | 'devin'
+  | 'replit'
+  | 'gemini'
+  | 'codex'
+  | 'auggie'
+  | 'opencode'
+  | 'kiro'
+  | 'goose'
+  | 'pi'
+
+type EnvCheck = string | (() => boolean)
+
+type InternalAgent = [agentName: AgentName, envChecks: EnvCheck[]]
+
+function envMatcher(envKey: string, regex: RegExp) {
+  return () => {
+    const value = env[envKey]
+    return value ? regex.test(value) : false
+  }
+}
+
+// Detection order matters: specific agents first, IDE-based agents last
+// so that agents running inside those IDEs are detected by their own env vars first.
+const agents: InternalAgent[] = [
+  // CLI agents
+  ['claude', ['CLAUDECODE', 'CLAUDE_CODE']],
+  ['replit', ['REPL_ID']],
+  ['gemini', ['GEMINI_CLI']],
+  ['codex', ['CODEX_SANDBOX', 'CODEX_THREAD_ID']],
+  ['opencode', ['OPENCODE']],
+  ['pi', [envMatcher('PATH', /\.pi[\\/]agent/)]],
+  ['auggie', ['AUGMENT_AGENT']],
+  ['goose', ['GOOSE_PROVIDER']],
+
+  // IDE-based agents (checked last)
+  ['devin', [envMatcher('EDITOR', /devin/)]],
+  ['cursor', ['CURSOR_AGENT']],
+  ['kiro', [envMatcher('TERM_PROGRAM', /kiro/)]],
+]
+
+/**
+ * Information about the detected AI coding agent.
+ */
+export type AgentInfo = {
+  /** The name of the detected agent, or undefined if no agent was detected. */
+  name?: AgentName
+}
+
+/**
+ * Detect the current AI coding agent from environment variables.
+ *
+ * Checks `AI_AGENT` env var first (explicit override), then scans for
+ * known agent-specific env vars in priority order.
+ *
+ * Supported agents: `cursor`, `claude`, `devin`, `replit`, `gemini`,
+ * `codex`, `auggie`, `opencode`, `kiro`, `goose`, `pi`
+ */
+export function detectAgent(): AgentInfo {
+  const aiAgent = env.AI_AGENT
+  if (aiAgent) {
+    return { name: aiAgent.toLowerCase() }
+  }
+  for (const [name, checks] of agents) {
+    for (const check of checks) {
+      if (typeof check === 'string' ? env[check] : check()) {
+        return { name }
+      }
+    }
+  }
+  return {}
+}
+
+/** Detected agent info, evaluated once at import time. */
+export const agentInfo: AgentInfo = /* #__PURE__ */ detectAgent()
+
+/** Name of the detected agent, or undefined if not running inside one. */
+export const agent: AgentName | undefined = agentInfo.name
+
+/** Whether the current process is running inside an AI coding agent. */
+export const isAgent: boolean = !!agentInfo.name