goke 6.1.3 → 6.2.1

package/src/__test__/index.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from 'vitest'
 import goke, { createConsole } from '../index.js'
-import type { GokeOutputStream } from '../index.js'
+import type { GokeOutputStream, GokeOptions } from '../index.js'
 import { coerceBySchema } from '../coerce.js'
 import { z } from 'zod'
 
@@ -21,6 +21,142 @@ function createTestOutputStream(): GokeOutputStream & { lines: string[]; readonl
   }
 }
 
+/**
+ * Helper: creates a goke instance with exit overridden to a no-op.
+ * This prevents process.exit(1) from killing the test runner while
+ * still allowing the original error to propagate (the framework
+ * re-throws after calling exit when exit doesn't halt execution).
+ *
+ * Tests can still use .toThrow() to assert CLI errors normally.
+ */
+function gokeTestable(name = '', options?: Partial<GokeOptions>) {
+  return goke(name, {
+    ...options,
+    exit: () => {},
+  })
+}
+
+/**
+ * Strip stack trace lines for stable snapshots.
+ * Keeps the error message and help hint, removes all "    at ..." lines
+ * and the blank line before them, since those contain machine-specific paths.
+ */
+function stripStackTrace(text: string): string {
+  return text
+    .split('\n')
+    .filter(line => !line.match(/^\s+at /))
+    .join('\n')
+    .replace(/\n{2,}/g, '\n')
+    .trim()
+}
+
+describe('error formatting', () => {
+  test('unknown option prints formatted error to stderr', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+
+    cli
+      .command('build', 'Build your app')
+      .option('--port <port>', 'Port')
+      .action(() => {})
+
+    try {
+      cli.parse('node bin build --unknown'.split(' '))
+    } catch {}
+
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: Unknown option \`--unknown\`"`)
+  })
+
+  test('missing required option value prints formatted error to stderr', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+
+    cli
+      .command('serve', 'Start server')
+      .option('--port <port>', 'Port')
+      .action(() => {})
+
+    try {
+      cli.parse('node bin serve --port'.split(' '))
+    } catch {}
+
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: option \`--port <port>\` value is missing"`)
+  })
+
+  test('schema coercion error prints formatted error to stderr', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+
+    cli.option('--port <port>', z.number().describe('Port'))
+
+    try {
+      cli.parse('node bin --port abc'.split(' '))
+    } catch {}
+
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: Invalid value for --port: expected number, got "abc""`)
+  })
+
+  test('error includes help hint when help is enabled', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+
+    cli.help()
+
+    cli
+      .command('serve', 'Start server')
+      .option('--port <port>', 'Port')
+      .action(() => {})
+
+    try {
+      cli.parse('node bin serve --port'.split(' '))
+    } catch {}
+
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`
+      "error: option \`--port <port>\` value is missing
+      Run "mycli serve --help" for usage information."
+    `)
+  })
+
+  test('async action error prints formatted error to stderr', async () => {
+    const stderr = createTestOutputStream()
+    let exitCode: number | undefined
+    const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code } })
+
+    cli
+      .command('deploy', 'Deploy app')
+      .action(async () => {
+        throw new Error('connection refused')
+      })
+
+    cli.parse('node bin deploy'.split(' '))
+
+    // Wait for the async rejection to be handled
+    await new Promise(resolve => setTimeout(resolve, 10))
+
+    expect(exitCode).toBe(1)
+    expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: connection refused"`)
+  })
+
+  test('error output includes stack trace', () => {
+    const stderr = createTestOutputStream()
+    const cli = goke('mycli', { stderr, exit: () => {} })
+
+    cli
+      .command('build', 'Build app')
+      .action(() => {})
+
+    try {
+      cli.parse('node bin build --unknown'.split(' '))
+    } catch {}
+
+    // Verify that stderr contains "error:" prefix and a stack trace with "at" lines
+    const text = stderr.text
+    expect(text).toContain('error:')
+    expect(text).toContain('Unknown option `--unknown`')
+    expect(text).toMatch(/at /)
+  })
+})
+
 test('double dashes', () => {
   const cli = goke()
 
@@ -101,7 +237,7 @@ describe('schema-based options', () => {
   })
 
   test('schema throws on invalid number', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('--port <port>', z.number().describe('Port number'))
 
@@ -328,7 +464,7 @@ describe('typical CLI usage examples', () => {
 
 describe('regression: oracle-found issues', () => {
   test('required option with schema still throws when value missing', () => {
-    const cli = goke()
+    const cli = gokeTestable()
     let actionCalled = false
 
     cli
@@ -344,7 +480,7 @@ describe('regression: oracle-found issues', () => {
   })
 
   test('repeated flags with non-array schema throws', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('--tag <tag>', z.string().describe('Tags'))
 
@@ -353,7 +489,7 @@ describe('regression: oracle-found issues', () => {
   })
 
   test('repeated flags with number schema throws', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('--id <id>', z.number().describe('ID'))
 
@@ -535,7 +671,7 @@ describe('edge cases: boolean flags + schema', () => {
   })
 
   test('invalid boolean string with boolean schema throws', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('--flag <flag>', z.boolean().describe('A flag'))
 
@@ -587,7 +723,7 @@ describe('edge cases: empty string values', () => {
   })
 
   test('empty string with number schema throws', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('--port <port>', z.number().describe('Port'))
 
@@ -653,7 +789,7 @@ describe('edge cases: short alias + schema', () => {
   })
 
   test('short alias repeated with non-array schema throws', () => {
-    const cli = goke()
+    const cli = gokeTestable()
 
     cli.option('-p, --port <port>', z.number().describe('Port'))
 
@@ -663,7 +799,7 @@ describe('edge cases: short alias + schema', () => {
 })
 
 test('throw on unknown options', () => {
-  const cli = goke()
+  const cli = gokeTestable()
 
   cli
     .command('build [entry]', 'Build your app')
@@ -834,23 +970,32 @@ describe('space-separated subcommands', () => {
     expect(stripAnsi(output)).toMatchInlineSnapshot(`
       "mycli
 
+
       Usage:
         $ mycli <command> [options]
 
+
       Commands:
         mcp login <url>              Login to MCP server
 
+
         mcp logout                   Logout from MCP server
 
+
         mcp status                   Show connection status
 
+
         git remote add <name> <url>  Add a git remote
 
+
         git remote remove <name>     Remove a git remote
 
+
         build                        Build the project
+
           --watch                    Watch mode
 
+
       Options:
         -h, --help  Display this message
       "
@@ -1100,6 +1245,113 @@ describe('many commands with root command (empty string)', () => {
     expect(stdout.text).toContain('Stream logs for a deployment')
   })
 
+  test('root help with many commands renders examples section after options', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('deploy', { stdout })
+
+    cli
+      .command('', 'Deploy the current project')
+      .option('--env <env>', 'Target environment')
+      .option('--dry-run', 'Preview without deploying')
+      .example('# Deploy to staging first')
+      .example('deploy --env staging --dry-run')
+
+    cli.command('init', 'Initialize a new project')
+    cli.command('login', 'Authenticate with the server')
+    cli.command('logout', 'Clear saved credentials')
+    cli.command('status', 'Show deployment status')
+    cli.command('logs <deploymentId>', 'Stream logs for a deployment')
+
+    cli.help()
+    cli.parse(['node', 'bin', '--help'], { run: false })
+
+    expect(stdout.text).toMatchInlineSnapshot(`
+      "deploy
+
+
+      Usage:
+        $ deploy [options]
+
+
+      Commands:
+        deploy               Deploy the current project
+
+
+        init                 Initialize a new project
+
+
+        login                Authenticate with the server
+
+
+        logout               Clear saved credentials
+
+
+        status               Show deployment status
+
+
+        logs <deploymentId>  Stream logs for a deployment
+
+
+      Options:
+        --env <env>  Target environment
+        --dry-run    Preview without deploying
+        -h, --help   Display this message
+
+
+      Examples:
+      # Deploy to staging first
+      deploy --env staging --dry-run
+      "
+    `)
+  })
+
+  test('subcommand help renders command examples at the end', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('deploy', { stdout, columns: 80 })
+
+    cli.command('', 'Deploy the current project')
+    cli.command('init', 'Initialize a new project')
+    cli.command('login', 'Authenticate with the server')
+
+    cli
+      .command('logs <deploymentId>', 'Stream logs for a deployment')
+      .option('--follow', 'Follow log output')
+      .option('--lines <n>', z.number().default(100).describe('Number of lines'))
+      .example('# Stream last 200 lines for a deployment')
+      .example('deploy logs dep_123 --lines 200')
+      .example('# Keep following new log lines')
+      .example('deploy logs dep_123 --follow')
+
+    cli.help()
+    cli.parse(['node', 'bin', 'logs', '--help'], { run: false })
+
+    expect(stdout.text).toMatchInlineSnapshot(`
+      "deploy
+
+
+      Usage:
+        $ deploy logs <deploymentId>
+
+
+      Options:
+        --follow     Follow log output
+        --lines <n>  Number of lines (default: 100)
+        -h, --help   Display this message
+
+
+      Description:
+        Stream logs for a deployment
+
+
+      Examples:
+      # Stream last 200 lines for a deployment
+      deploy logs dep_123 --lines 200
+      # Keep following new log lines
+      deploy logs dep_123 --follow
+      "
+    `)
+  })
+
   test('root help labels default command with cli name and does not duplicate global options', () => {
     const stdout = createTestOutputStream()
     const cli = goke('deploy', { stdout })
@@ -1118,14 +1370,18 @@ describe('many commands with root command (empty string)', () => {
     expect(stdout.text).toMatchInlineSnapshot(`
       "deploy
 
+
       Usage:
         $ deploy [options]
 
+
       Commands:
         deploy  Deploy the current project
 
+
         status  Show deployment status
 
+
       Options:
         --env <env>  Target environment
         --dry-run    Preview without deploying
@@ -1156,26 +1412,32 @@ describe('many commands with root command (empty string)', () => {
     expect(stdout.text).toMatchInlineSnapshot(`
       "mycli
 
+
       Usage:
         $ mycli <command> [options]
 
+
       Commands:
         notion-search      Perform a semantic search over
                            Notion workspace content and
                            connected integrations with
                            advanced filtering options, date
                            filters, and creator filters.
+
           --query <query>  Natural language query text to
                            search for
           --limit [limit]  Maximum number of results to return
                            (default: 10)
 
+
         notion-fetch       Retrieve a Notion page or database
                            by URL or ID and render the result
                            in enhanced markdown format for
                            terminal output.
+
           --id <id>        Notion URL or UUID to fetch
 
+
       Options:
         -h, --help  Display this message
       "
@@ -1197,20 +1459,28 @@ describe('many commands with root command (empty string)', () => {
     expect(stdout.text).toMatchInlineSnapshot(`
       "gtui
 
+
       Usage:
         $ gtui <command> [options]
 
+
       Commands:
         auth login                                 Authenticate with Google (opens browser)
 
+
         auth logout                                Remove stored credentials
+
           --force                                  Skip confirmation
 
+
         mail list                                  List email threads
+
           --folder [folder]                        Folder to list
 
+
         attachment get <messageId> <attachmentId>  Download an attachment
 
+
       Options:
         -h, --help  Display this message
       "
@@ -1257,14 +1527,18 @@ describe('many commands with root command (empty string)', () => {
       expect(stdout.text).toMatchInlineSnapshot(`
         "mycli
 
+
         Usage:
           $ mycli <command> [options]
 
+
         Commands:
           notion-search      Perform a semantic search over Notion workspace content and connected integrations with advanced filtering options, date filters, and creator filters.
+
             --query <query>  Natural language query text to search for
             --limit [limit]  Maximum number of results to return (default: 10)
 
+
         Options:
           -h, --help  Display this message
         "
@@ -1470,4 +1744,133 @@ describe('schema description and default extraction', () => {
 
     expect(stdout.text).toContain('(default: 3000)')
   })
+
+  test('deprecated options are hidden from help output', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+
+    cli
+      .command('serve', 'Start server')
+      .option('--old <value>', z.string().meta({ deprecated: true, description: 'Old option' }))
+      .option('--new <value>', z.string().describe('Normal option'))
+
+    cli.help()
+    cli.parse(['node', 'bin', 'serve', '--help'], { run: false })
+
+    // Normal option should be visible
+    expect(stdout.text).toContain('--new')
+    expect(stdout.text).toContain('Normal option')
+    // Deprecated option should be hidden
+    expect(stdout.text).not.toContain('--old')
+    expect(stdout.text).not.toContain('Old option')
+  })
+
+  test('deprecated option still works for parsing (just hidden from help)', () => {
+    const cli = gokeTestable('mycli')
+
+    let result: any = {}
+    cli
+      .command('serve', 'Start server')
+      .option('--old <value>', z.string().meta({ deprecated: true, description: 'Old option' }))
+      .action((options) => { result = options })
+
+    cli.parse(['node', 'bin', 'serve', '--old', 'legacy-value'])
+
+    // Deprecated option should still be parsed and usable
+    expect(result.old).toBe('legacy-value')
+  })
+
+  test('deprecated options hidden from global help', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+
+    cli.option('--legacy [value]', z.string().meta({ deprecated: true, description: 'Deprecated global' }))
+    cli.option('--current [value]', z.string().describe('Current option'))
+
+    cli.help()
+    cli.parse(['node', 'bin', '--help'], { run: false })
+
+    expect(stdout.text).toContain('--current')
+    expect(stdout.text).toContain('Current option')
+    expect(stdout.text).not.toContain('--legacy')
+    expect(stdout.text).not.toContain('Deprecated global')
+  })
+})
+
+describe('helpText()', () => {
+  test('returns help string without printing', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+
+    cli.command('serve', 'Start server')
+    cli.option('--port <port>', 'Port number')
+    cli.help()
+    // parse a known command so help is not auto-triggered
+    cli.parse(['node', 'bin', 'serve'], { run: false })
+
+    // reset stdout after parse
+    stdout.lines.length = 0
+
+    const text = stripAnsi(cli.helpText())
+
+    expect(text).toContain('mycli')
+    expect(text).toContain('serve')
+    expect(text).toContain('Start server')
+    expect(text).toContain('--port')
+    // helpText() does not print to stdout
+    expect(stdout.text).toBe('')
+  })
+
+  test('returns same content as outputHelp', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+
+    cli.command('build', 'Build project')
+    cli.option('--watch [watch]', 'Watch mode')
+    cli.help()
+    // parse a known command so help is not auto-triggered
+    cli.parse(['node', 'bin', 'build'], { run: false })
+
+    // reset stdout after parse
+    stdout.lines.length = 0
+
+    const helpTextResult = stripAnsi(cli.helpText())
+    cli.outputHelp()
+    // outputHelp adds a trailing newline via console.log
+    const outputHelpResult = stdout.text.replace(/\n$/, '')
+
+    expect(helpTextResult).toBe(outputHelpResult)
+  })
+
+  test('returns subcommand help when command is matched', () => {
+    const cli = goke('mycli')
+
+    cli.command('deploy <env>', 'Deploy to environment')
+      .option('--force', 'Force deploy')
+
+    cli.help()
+    cli.parse(['node', 'bin', 'deploy', '--help'], { run: false })
+
+    const text = stripAnsi(cli.helpText())
+
+    expect(text).toContain('deploy')
+    expect(text).toContain('--force')
+    expect(text).toContain('Force deploy')
+  })
+
+  test('works without calling parse', () => {
+    const cli = goke('mycli')
+
+    cli.command('test', 'Run tests')
+    cli.option('--coverage', 'Enable coverage')
+    cli.help()
+
+    // helpText() works even without parse
+    const text = stripAnsi(cli.helpText())
+
+    expect(text).toContain('mycli')
+    expect(text).toContain('test')
+    expect(text).toContain('Run tests')
+    expect(text).toContain('--coverage')
+  })
 })