goke 6.9.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()
@@ -2502,3 +2535,45 @@ describe('use() with sub-CLI composition', () => {
     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__/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

@@ -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