goke 6.9.0 → 6.10.0

package/dist/__test__/index.test.js

@@ -132,6 +132,35 @@ describe('error formatting', () => {
         expect(text).toMatch(/at /);
     });
 });
+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();
@@ -1955,3 +1984,38 @@ 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', '--': [] }, 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/dist/__test__/readme-examples.test.js

@@ -3,7 +3,7 @@
  */
 import { describe, expect, test } from 'vitest';
 import { z } from 'zod';
-import goke, { openInBrowser } from '../index.js';
+import goke, { openInBrowser, generateDocs } from '../index.js';
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
 const stripAnsi = (text) => text.replace(ANSI_RE, '');
 function createTestOutputStream() {
@@ -133,7 +133,7 @@ describe('documented command APIs', () => {
         expect(help).toContain('Deploy safely first');
         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;
@@ -153,7 +153,7 @@ describe('documented command APIs', () => {
             return true;
         });
         try {
-            openInBrowser(url);
+            await openInBrowser(url);
         }
         finally {
             process.stdout.write = originalStdoutWrite;
@@ -163,7 +163,143 @@ describe('documented command APIs', () => {
                 value: originalIsTTY,
             });
         }
-        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/dist/__test__/types.test-d.js

@@ -434,6 +434,33 @@ describe('type-level: README TypeScript examples', () => {
             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(); // input
+        expectTypeOf(action).parameter(1).toEqualTypeOf(); // 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();
+    });
     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/dist/agents.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/**
+ * Known AI coding agent names.
+ */
+export type AgentName = (string & {}) | 'cursor' | 'claude' | 'devin' | 'replit' | 'gemini' | 'codex' | 'auggie' | 'opencode' | 'kiro' | 'goose' | 'pi';
+/**
+ * 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 declare function detectAgent(): AgentInfo;
+/** Detected agent info, evaluated once at import time. */
+export declare const agentInfo: AgentInfo;
+/** Name of the detected agent, or undefined if not running inside one. */
+export declare const agent: AgentName | undefined;
+/** Whether the current process is running inside an AI coding agent. */
+export declare const isAgent: boolean;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,CAAC,MAAM,GAAG,EAAE,CAAC,GACb,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,UAAU,GACV,MAAM,GACN,OAAO,GACP,IAAI,CAAA;AAgCR;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,IAAI,SAAS,CAavC;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,EAAE,SAAyC,CAAA;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,KAAK,EAAE,SAAS,GAAG,SAA0B,CAAA;AAE1D,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,OAA0B,CAAA"}

package/dist/agents.js

@@ -0,0 +1,63 @@
+/**
+ * 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 = globalThis.process?.env || Object.create(null);
+function envMatcher(envKey, regex) {
+    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 = [
+    // 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/)]],
+];
+/**
+ * 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() {
+    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 = /* #__PURE__ */ detectAgent();
+/** Name of the detected agent, or undefined if not running inside one. */
+export const agent = agentInfo.name;
+/** Whether the current process is running inside an AI coding agent. */
+export const isAgent = !!agentInfo.name;

package/dist/completions.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Shell completion support for goke CLIs.
+ *
+ * Two pieces work together:
+ * 1. A hidden `--get-goke-completions` flag in the CLI binary. When present,
+ *    the CLI skips normal execution and prints matching completions to stdout.
+ * 2. A shell-specific shim script installed into an fpath/completion directory.
+ *    On each Tab press the shell calls the CLI binary with the flag + current words.
+ *
+ * The `installCompletions` function finds a writable completion directory and
+ * writes the shim. Since the shim calls the binary on every Tab, completions
+ * are always up-to-date with the installed CLI.
+ */
+/** The hidden flag the shell script passes to the CLI on each Tab press */
+export declare const COMPLETION_FLAG = "get-goke-completions";
+/**
+ * Zsh completion script template.
+ *
+ * The `#compdef` header lets zsh autoload this as an fpath function.
+ * On Tab press it calls the CLI binary with `--get-goke-completions` and
+ * all typed words. The binary returns `name:description` pairs (one per line)
+ * and zsh renders them with `_describe`.
+ */
+export declare const zshTemplate = "#compdef {{app_name}}\n###-begin-{{app_name}}-completions-###\n_{{app_name_safe}}_completions() {\n  local reply\n  local si=$IFS\n  IFS=$'\\n' reply=($(COMP_CWORD=\"$((CURRENT-1))\" COMP_LINE=\"$BUFFER\" COMP_POINT=\"$CURSOR\" GOKE_COMPLETION_SHELL=zsh {{app_path}} --get-goke-completions \"${words[@]}\"))\n  IFS=$si\n  if [[ ${#reply} -gt 0 ]]; then\n    _describe 'values' reply\n  else\n    _default\n  fi\n}\nif [[ \"'${zsh_eval_context[-1]}\" == \"loadautofunc\" ]]; then\n  _{{app_name_safe}}_completions \"$@\"\nelse\n  compdef _{{app_name_safe}}_completions {{app_name}}\nfi\n###-end-{{app_name}}-completions-###\n";
+/**
+ * Bash completion script template.
+ *
+ * On Tab press bash calls the function which invokes the CLI binary with
+ * `--get-goke-completions` and all typed words. The binary returns plain
+ * completion strings (one per line).
+ */
+export declare const bashTemplate = "###-begin-{{app_name}}-completions-###\n_{{app_name_safe}}_completions()\n{\n    local cur_word args type_list\n\n    cur_word=\"${COMP_WORDS[COMP_CWORD]}\"\n    args=(\"${COMP_WORDS[@]}\")\n\n    # Bash 3 compatible (no mapfile). Works on macOS default bash.\n    local IFS=$'\\n'\n    type_list=($(GOKE_COMPLETION_SHELL=bash {{app_path}} --get-goke-completions \"${args[@]}\"))\n    unset IFS\n    COMPREPLY=($(compgen -W \"$( printf '%q ' \"${type_list[@]}\" )\" -- \"${cur_word}\" |\n        awk '/ / { print \"\\\"\"$0\"\\\"\" } /^[^ ]+$/ { print $0 }'))\n\n    if [ ${#COMPREPLY[@]} -eq 0 ]; then\n      COMPREPLY=()\n    fi\n\n    return 0\n}\ncomplete -o bashdefault -o default -F _{{app_name_safe}}_completions {{app_name}}\n###-end-{{app_name}}-completions-###\n";
+export type ShellType = 'zsh' | 'bash';
+/**
+ * Detect the current shell from environment variables.
+ * Returns 'zsh', 'bash', or null if unrecognized.
+ */
+export declare function detectShell(): ShellType | null;
+/**
+ * Validate and normalize a shell value from user input.
+ * Returns a valid ShellType or throws if the value is invalid.
+ */
+export declare function validateShell(value: unknown): ShellType | undefined;
+/**
+ * Detect which shell format to use for completion output.
+ * Prefers the explicit GOKE_COMPLETION_SHELL env var (set by the shell shim)
+ * over the login $SHELL. This prevents format mismatch when a bash shim runs
+ * on a system where $SHELL is zsh.
+ */
+export declare function detectCompletionShell(): ShellType | null;
+/**
+ * Generate a completion script for the given shell.
+ *
+ * @param shell - Target shell ('zsh' or 'bash')
+ * @param cliName - The CLI binary name (e.g. 'my-cli')
+ * @param cliPath - Full path to the CLI binary. If not provided, uses cliName.
+ */
+export declare function generateCompletionScript(shell: ShellType, cliName: string, cliPath?: string): string;
+interface InstallResult {
+    /** The file path where the completion script was written */
+    path: string;
+    /** The shell the script was generated for */
+    shell: ShellType;
+}
+/**
+ * Find a writable completion directory, generate the shell script, and write it.
+ *
+ * For zsh, scans `$fpath` directories plus well-known fallbacks.
+ * For bash, scans XDG and legacy user completion dirs.
+ *
+ * Throws if no writable directory is found.
+ *
+ * @param cliName - The CLI binary name
+ * @param cliPath - Full path to the CLI binary
+ * @param shell - Target shell. Auto-detected from $SHELL if omitted.
+ */
+export declare function installCompletions(cliName: string, cliPath: string, shell?: ShellType): Promise<InstallResult>;
+/**
+ * Remove an installed completion script.
+ *
+ * Searches the same candidate directories as `installCompletions` and removes
+ * any matching completion files found.
+ *
+ * @returns The paths that were removed, or empty array if none found.
+ */
+export declare function uninstallCompletions(cliName: string, shell?: ShellType): Promise<string[]>;
+export {};
+//# sourceMappingURL=completions.d.ts.map

package/dist/completions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../src/completions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,2EAA2E;AAC3E,eAAO,MAAM,eAAe,yBAAyB,CAAA;AAIrD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,qnBAmBvB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,ywBAuBxB,CAAA;AAID,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAA;AAEtC;;;GAGG;AACH,wBAAgB,WAAW,IAAI,SAAS,GAAG,IAAI,CAK9C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAInE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,GAAG,IAAI,CAIxD;AAUD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CASR;AA+BD,UAAU,aAAa;IACrB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,6CAA6C;IAC7C,KAAK,EAAE,SAAS,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,aAAa,CAAC,CA4FxB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAsDnB"}