goke 6.9.0 → 6.11.0

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

@@ -54,7 +54,7 @@ function gokeTestable(name = '', options?: Partial<GokeOptions>) {
 }
 
 describe('injected execution context', () => {
-  test('command action receives injected console and process', () => {
+  test('command action receives injected console and process', async () => {
     const stdout = createTestOutputStream()
     const cli = gokeTestable('mycli', { stdout })
     let seenArgv: string[] | undefined
@@ -66,13 +66,13 @@ describe('injected execution context', () => {
         seenArgv = process.argv
       })
 
-    cli.parse(['node', 'bin', 'status'], { run: true })
+    await cli.parse(['node', 'bin', 'status'], { run: true })
 
     expect(stdout.text).toBe('ready\n')
     expect(seenArgv).toEqual(['node', 'bin', 'status'])
   })
 
-  test('middleware receives injected console and process', () => {
+  test('middleware receives injected console and process', async () => {
     const stdout = createTestOutputStream()
     const cli = gokeTestable('mycli', { stdout })
     let seenArgv: string[] | undefined
@@ -85,7 +85,7 @@ describe('injected execution context', () => {
       .command('build', 'Build')
       .action(() => {})
 
-    cli.parse(['node', 'bin', 'build'], { run: true })
+    await cli.parse(['node', 'bin', 'build'], { run: true })
 
     expect(stdout.text).toBe('middleware\n')
     expect(seenArgv).toEqual(['node', 'bin', 'build'])
@@ -93,14 +93,14 @@ describe('injected execution context', () => {
 })
 
 describe('clone', () => {
-  test('clone creates isolated parse state', () => {
+  test('clone creates isolated parse state', async () => {
     const cli = gokeTestable('mycli')
 
     cli.command('build', 'Build').action(() => {})
 
     const cloned = cli.clone({ exit: () => {} })
 
-    cloned.parse(['node', 'bin', 'build'], { run: false })
+    await cloned.parse(['node', 'bin', 'build'], { run: false })
 
     expect(cloned).not.toBe(cli)
     expect(cloned.matchedCommandName).toBe('build')
@@ -109,7 +109,7 @@ describe('clone', () => {
 })
 
 describe('createExecutionContext', () => {
-  test('returns a context that mirrors the cli defaults when called with no override', () => {
+  test('returns a context that mirrors the cli defaults when called with no override', async () => {
     const stdout = createTestOutputStream()
     const stderr = createTestOutputStream()
     const cli = gokeTestable('mycli', {

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
@@ -52,7 +52,7 @@ describe('README smoke tests', () => {
         console.log(`logs ${deploymentId} ${options.lines}`)
       })
 
-    cli.parse(['node', 'bin', '--env', 'production', 'up', '--dry-run'], { run: false })
+    await cli.parse(['node', 'bin', '--env', 'production', 'up', '--dry-run'], { run: false })
     await cli.runMatchedCommand()
 
     expect(stdout.text).toBe(
@@ -61,7 +61,7 @@ describe('README smoke tests', () => {
 
     stdout.lines.length = 0
 
-    cli.parse(['node', 'bin', 'logs', 'dep_123'], { run: false })
+    await cli.parse(['node', 'bin', 'logs', 'dep_123'], { run: false })
     await cli.runMatchedCommand()
 
     expect(stdout.text).toBe('Environment: staging\nlogs dep_123 100\n')
@@ -96,7 +96,7 @@ describe('README smoke tests', () => {
 
     expect(stripAnsi(cli.helpText())).toContain('mycli lint src/**/*.ts')
 
-    cli.parse(['node', 'bin', '--type', 'bun', '--name', 'Tommy', 'build', 'src/index.ts', '--minify'], { run: false })
+    await cli.parse(['node', 'bin', '--type', 'bun', '--name', 'Tommy', 'build', 'src/index.ts', '--minify'], { run: false })
     await cli.runMatchedCommand()
 
     expect(stdout.text).toBe(
@@ -135,7 +135,7 @@ describe('README smoke tests', () => {
         )
       })
 
-    cli.parse(['node', 'bin', '--env', 'staging', '--dry-run'], { run: false })
+    await cli.parse(['node', 'bin', '--env', 'staging', '--dry-run'], { run: false })
     await cli.runMatchedCommand()
 
     expect(stdout.text).toBe(
@@ -144,7 +144,7 @@ describe('README smoke tests', () => {
 
     stdout.lines.length = 0
 
-    cli.parse(['node', 'bin', 'logs', 'abc123', '--follow'], { run: false })
+    await cli.parse(['node', 'bin', 'logs', 'abc123', '--follow'], { run: false })
     await cli.runMatchedCommand()
 
     expect(stdout.text).toBe(
@@ -154,7 +154,7 @@ describe('README smoke tests', () => {
 })
 
 describe('documented command APIs', () => {
-  test('alias runs the same command through a short name', () => {
+  test('alias runs the same command through a short name', async () => {
     const cli = gokeTestable('mycli')
     let seen = ''
 
@@ -162,12 +162,12 @@ describe('documented command APIs', () => {
       seen = 'install'
     })
 
-    cli.parse(['node', 'bin', 'i'], { run: true })
+    await cli.parse(['node', 'bin', 'i'], { run: true })
 
     expect(seen).toBe('install')
   })
 
-  test('command helpText returns command-specific help without printing', () => {
+  test('command helpText returns command-specific help without printing', async () => {
     const stdout = createTestOutputStream()
     const cli = goke('mycli', { stdout })
 
@@ -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', async () => {
+    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', async () => {
+    const cli = gokeTestable('empty')
+    const pages = generateDocs({ cli })
+    expect(pages).toEqual([])
+  })
+
+  test('skips deprecated options', async () => {
+    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

@@ -522,6 +522,33 @@ describe('type-level: README TypeScript examples', () => {
       })
   })
 
+  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