goke 6.5.0 → 6.5.2

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

@@ -0,0 +1,225 @@
+/**
+ * Smoke tests that keep README examples and documented APIs executable.
+ */
+
+import { describe, expect, test } from 'vitest'
+import { z } from 'zod'
+import goke, { openInBrowser } from '../index.js'
+import type { GokeOptions, GokeOutputStream } from '../index.js'
+
+const ANSI_RE = /\x1B\[[0-9;]*m/g
+
+const stripAnsi = (text: string) => text.replace(ANSI_RE, '')
+
+function createTestOutputStream(): GokeOutputStream & { lines: string[]; readonly text: string } {
+  const lines: string[] = []
+  return {
+    lines,
+    get text() { return stripAnsi(lines.join('')) },
+    write(data: string) { lines.push(data) },
+  }
+}
+
+function gokeTestable(name = '', options?: Partial<GokeOptions>) {
+  return goke(name, {
+    ...options,
+    exit: () => {},
+  })
+}
+
+describe('README smoke tests', () => {
+  test('intro example runs middleware and both command forms', async () => {
+    const stdout = createTestOutputStream()
+    const cli = gokeTestable('deploy', { stdout })
+
+    cli
+      .option('--env <env>', z.enum(['staging', 'production']).default('staging').describe('Target environment'))
+      .use((options, { console }) => {
+        console.log(`Environment: ${options.env}`)
+      })
+
+    cli
+      .command('up', 'Deploy the app')
+      .option('--dry-run', 'Preview without deploying')
+      .action((options, { console, process }) => {
+        console.log(`Deploying from ${process.cwd} dryRun=${String(options.dryRun)}`)
+      })
+
+    cli
+      .command('logs <deploymentId>', 'Stream logs')
+      .option('--lines <n>', z.number().default(100).describe('Lines to tail'))
+      .action((deploymentId, options, { console }) => {
+        console.log(`logs ${deploymentId} ${options.lines}`)
+      })
+
+    cli.parse(['node', 'bin', '--env', 'production', 'up', '--dry-run'], { run: false })
+    await cli.runMatchedCommand()
+
+    expect(stdout.text).toBe(
+      `Environment: production\nDeploying from ${process.cwd()} dryRun=true\n`,
+    )
+
+    stdout.lines.length = 0
+
+    cli.parse(['node', 'bin', 'logs', 'dep_123'], { run: false })
+    await cli.runMatchedCommand()
+
+    expect(stdout.text).toBe('Environment: staging\nlogs dep_123 100\n')
+  })
+
+  test('simple parsing example stays executable and keeps examples in help output', async () => {
+    const stdout = createTestOutputStream()
+    const cli = gokeTestable('mycli', { stdout })
+
+    cli.option(
+      '--type [type]',
+      z.string().default('node').describe('Choose a project type'),
+    )
+    cli.option('--name <name>', 'Provide your name')
+
+    cli.command('lint [...files]', 'Lint files').action((files, options, { console, process }) => {
+      console.log(JSON.stringify({ files, options, cwd: process.cwd }))
+    })
+
+    cli
+      .command('build [entry]', 'Build your app')
+      .option('--minify', 'Minify output')
+      .example('build src/index.ts')
+      .example('build src/index.ts --minify')
+      .action(async (entry, options, { console, process }) => {
+        console.log(JSON.stringify({ entry, options, nodeEnv: process.env.NODE_ENV }))
+      })
+
+    cli.example((bin) => `${bin} lint src/**/*.ts`)
+    cli.help()
+    cli.version('0.0.0')
+
+    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.runMatchedCommand()
+
+    expect(stdout.text).toBe(
+      `${JSON.stringify({
+        entry: 'src/index.ts',
+        options: {
+          '--': [],
+          type: 'bun',
+          name: 'Tommy',
+          minify: true,
+        },
+        nodeEnv: process.env.NODE_ENV,
+      })}\n`,
+    )
+  })
+
+  test('many-commands README example runs root and nested commands', async () => {
+    const stdout = createTestOutputStream()
+    const cli = gokeTestable('deploy', { stdout })
+
+    cli
+      .command('', 'Deploy the current project')
+      .option('--env <env>', z.string().default('production').describe('Target environment'))
+      .option('--dry-run', 'Preview without deploying')
+      .action((options, { console, process }) => {
+        console.log(`Deploying to ${options.env} from ${process.cwd} dryRun=${String(options.dryRun)}`)
+      })
+
+    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'))
+      .action((deploymentId, options, { console, process }) => {
+        console.log(
+          `Streaming logs for ${deploymentId} from ${process.cwd} follow=${String(options.follow)} lines=${options.lines}`,
+        )
+      })
+
+    cli.parse(['node', 'bin', '--env', 'staging', '--dry-run'], { run: false })
+    await cli.runMatchedCommand()
+
+    expect(stdout.text).toBe(
+      `Deploying to staging from ${process.cwd()} dryRun=true\n`,
+    )
+
+    stdout.lines.length = 0
+
+    cli.parse(['node', 'bin', 'logs', 'abc123', '--follow'], { run: false })
+    await cli.runMatchedCommand()
+
+    expect(stdout.text).toBe(
+      `Streaming logs for abc123 from ${process.cwd()} follow=true lines=100\n`,
+    )
+  })
+})
+
+describe('documented command APIs', () => {
+  test('alias runs the same command through a short name', () => {
+    const cli = gokeTestable('mycli')
+    let seen = ''
+
+    cli.command('install', 'Install packages').alias('i').action(() => {
+      seen = 'install'
+    })
+
+    cli.parse(['node', 'bin', 'i'], { run: true })
+
+    expect(seen).toBe('install')
+  })
+
+  test('command helpText returns command-specific help without printing', () => {
+    const stdout = createTestOutputStream()
+    const cli = goke('mycli', { stdout })
+
+    const command = cli
+      .command('deploy <env>', 'Deploy to an environment')
+      .option('--dry-run', 'Preview without deploying')
+      .example('# Deploy safely first')
+      .example('mycli deploy staging --dry-run')
+
+    cli.help()
+
+    const help = stripAnsi(command.helpText())
+
+    expect(help).toContain('$ mycli deploy <env>')
+    expect(help).toContain('--dry-run')
+    expect(help).toContain('Deploy safely first')
+    expect(stdout.text).toBe('')
+  })
+
+  test('openInBrowser prints the URL to stdout in non-tty environments', () => {
+    const url = 'https://example.com/dashboard'
+    const originalStdoutWrite = process.stdout.write
+    const originalStderrWrite = process.stderr.write
+    const originalIsTTY = process.stdout.isTTY
+    let stdout = ''
+    let stderr = ''
+
+    Object.defineProperty(process.stdout, 'isTTY', {
+      configurable: true,
+      value: false,
+    })
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdout += String(chunk)
+      return true
+    }) as typeof process.stdout.write
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderr += String(chunk)
+      return true
+    }) as typeof process.stderr.write
+
+    try {
+      openInBrowser(url)
+    } finally {
+      process.stdout.write = originalStdoutWrite
+      process.stderr.write = originalStderrWrite
+      Object.defineProperty(process.stdout, 'isTTY', {
+        configurable: true,
+        value: originalIsTTY,
+      })
+    }
+
+    expect(stdout).toBe(`${url}\n`)
+    expect(stderr).toBe('')
+  })
+})

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

@@ -1,12 +1,16 @@
 /**
  * Type-level tests for schema-based option inference.
  * These tests verify that TypeScript infers the correct types from
- * option names (template literals) and StandardJSONSchemaV1 schemas.
+ * option names (template literals) and StandardJSONSchemaV1 schemas,
+ * and that `.action()` callbacks receive fully-typed positional args
+ * and options objects.
  *
  * These use expectTypeOf from vitest for compile-time type assertions.
  */
 import { describe, test, expectTypeOf } from 'vitest'
+import { z } from 'zod'
 import type { StandardTypedV1, StandardJSONSchemaV1 } from '../coerce.js'
+import type { GokeExecutionContext } from '../goke.js'
 import goke from '../index.js'
 
 // ─── Import type helpers from Command.ts ───
@@ -167,3 +171,260 @@ describe('type-level: middleware use() callback inference', () => {
       })
   })
 })
+
+describe('type-level: command() .action() positional args inference', () => {
+  test('command with no args → action receives only (options, ctx)', () => {
+    goke('test')
+      .command('deploy', 'Deploy the app')
+      .action((options, ctx) => {
+        expectTypeOf(options).toEqualTypeOf<{}>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+      })
+  })
+
+  test('command with one required arg → action receives (arg, options, ctx)', () => {
+    goke('test')
+      .command('get <id>', 'Fetch a resource by id')
+      .action((id, options, ctx) => {
+        expectTypeOf(id).toEqualTypeOf<string>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+      })
+  })
+
+  test('command with two required args → action receives both as strings', () => {
+    goke('test')
+      .command('convert <input> <output>', 'Convert file formats')
+      .action((input, output, options) => {
+        expectTypeOf(input).toEqualTypeOf<string>()
+        expectTypeOf(output).toEqualTypeOf<string>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('command with optional arg → arg type includes undefined', () => {
+    goke('test')
+      .command('run [script]', 'Run a script')
+      .action((script, options) => {
+        expectTypeOf(script).toEqualTypeOf<string | undefined>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('command with variadic required arg → arg is string[]', () => {
+    goke('test')
+      .command('exec <...args>', 'Run a binary with args')
+      .action((args, options) => {
+        expectTypeOf(args).toEqualTypeOf<string[]>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('command with variadic optional arg → arg is string[]', () => {
+    goke('test')
+      .command('run [...rest]', 'Variadic optional')
+      .action((rest, options) => {
+        expectTypeOf(rest).toEqualTypeOf<string[]>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('multi-word command with required arg', () => {
+    goke('test')
+      .command('mcp getNodeXml <id>', 'Get XML for a node')
+      .action((id, options) => {
+        expectTypeOf(id).toEqualTypeOf<string>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('default command with one positional arg', () => {
+    goke('test')
+      .command('<file>', 'Default command')
+      .action((file, options) => {
+        expectTypeOf(file).toEqualTypeOf<string>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+
+  test('mixed required and optional positional args', () => {
+    goke('test')
+      .command('send <to> [cc]', 'Send a message')
+      .action((to, cc, options) => {
+        expectTypeOf(to).toEqualTypeOf<string>()
+        expectTypeOf(cc).toEqualTypeOf<string | undefined>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+      })
+  })
+})
+
+describe('type-level: command() .action() option inference', () => {
+  test('single schema-based option is visible on options param', () => {
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .action((options, ctx) => {
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+      })
+  })
+
+  test('multiple schema-based options are accumulated', () => {
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .option('--host <host>', z.string())
+      .option('--verbose', z.boolean())
+      .action((options) => {
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+        expectTypeOf(options.host).toEqualTypeOf<string>()
+        // Boolean flag is optional (no <...> brackets)
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+      })
+  })
+
+  test('required vs optional option shape', () => {
+    goke('test')
+      .command('cmd', 'Command')
+      .option('--name <name>', z.string())
+      .option('--count [count]', z.number())
+      .action((options) => {
+        expectTypeOf(options.name).toEqualTypeOf<string>()
+        expectTypeOf(options.count).toEqualTypeOf<number | undefined>()
+      })
+  })
+
+  test('camelCase conversion for kebab-case option names', () => {
+    goke('test')
+      .command('build', 'Build')
+      .option('--out-dir <dir>', z.string())
+      .option('--my-long-flag <val>', z.string())
+      .action((options) => {
+        expectTypeOf(options.outDir).toEqualTypeOf<string>()
+        expectTypeOf(options.myLongFlag).toEqualTypeOf<string>()
+      })
+  })
+
+  test('options combined with positional args', () => {
+    goke('test')
+      .command('convert <input> <output>', 'Convert file format')
+      .option('--quality <quality>', z.number())
+      .option('--format <format>', z.enum(['png', 'jpg', 'webp']))
+      .action((input, output, options, ctx) => {
+        expectTypeOf(input).toEqualTypeOf<string>()
+        expectTypeOf(output).toEqualTypeOf<string>()
+        expectTypeOf(options.quality).toEqualTypeOf<number>()
+        expectTypeOf(options.format).toEqualTypeOf<'png' | 'jpg' | 'webp'>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+      })
+  })
+
+  test('global options from Goke are visible inside command actions', () => {
+    goke('test')
+      .option('--verbose', z.boolean())
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .action((options) => {
+        // Global option from cli.option()
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        // Command-local option
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+      })
+  })
+
+  test('untyped option (string description) produces loose value type', () => {
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', 'Port number')
+      .action((options) => {
+        // Without a schema the runtime still guarantees required value options are strings.
+        expectTypeOf(options.port).toEqualTypeOf<string>()
+      })
+  })
+
+  test('untyped optional value options keep raw mri sentinel shapes', () => {
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--host [host]', 'Optional host override')
+      .option('--verbose', 'Verbose output')
+      .action((options) => {
+        expectTypeOf(options.host).toEqualTypeOf<string | boolean | undefined>()
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+      })
+  })
+
+  test('accessing a non-existent option in action is a type error', () => {
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .action((options) => {
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+        // @ts-expect-error nonExistent was never declared
+        options.nonExistent
+      })
+  })
+
+  test('accessing a non-existent positional arg in action is a type error', () => {
+    goke('test')
+      .command('get <id>', 'Fetch resource')
+      .action((id, options, ctx, ...rest) => {
+        expectTypeOf(id).toEqualTypeOf<string>()
+        expectTypeOf(options).toEqualTypeOf<{}>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+        // No more positional slots — rest should be empty
+        expectTypeOf(rest).toEqualTypeOf<[]>()
+      })
+  })
+
+  test('action callback can omit trailing params (fewer-args is valid)', () => {
+    // Dropping context is fine
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .action((options) => {
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+      })
+
+    // Dropping everything is fine
+    goke('test')
+      .command('serve', 'Start server')
+      .option('--port <port>', z.number())
+      .action(() => {})
+  })
+})
+
+describe('type-level: README TypeScript examples', () => {
+  test('README TypeScript example infers positional args and typed options', () => {
+    goke('my-program')
+      .command('serve <entry>', 'Start the app')
+      .option('--port <port>', z.number().default(3000).describe('Port number'))
+      .option('--watch', 'Watch files')
+      .action((entry, options, { console, process }) => {
+        expectTypeOf(entry).toEqualTypeOf<string>()
+        expectTypeOf(options.port).toEqualTypeOf<number>()
+        expectTypeOf(options.watch).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(console.log).toBeFunction()
+        expectTypeOf(process.cwd).toEqualTypeOf<string>()
+      })
+  })
+
+  test('README global options and middleware example stays typed end-to-end', () => {
+    goke('mycli')
+      .option('--verbose', z.boolean().default(false).describe('Enable verbose logging'))
+      .option('--api-url [url]', z.string().default('https://api.example.com').describe('API base URL'))
+      .use((options, { process }) => {
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(options.apiUrl).toEqualTypeOf<string | undefined>()
+        expectTypeOf(process.stdin).toEqualTypeOf<string>()
+      })
+      .command('deploy <env>', 'Deploy to an environment')
+      .option('--dry-run', 'Preview without deploying')
+      .action((env, options, ctx) => {
+        expectTypeOf(env).toEqualTypeOf<string>()
+        expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(options.apiUrl).toEqualTypeOf<string | undefined>()
+        expectTypeOf(options.dryRun).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(ctx).toEqualTypeOf<GokeExecutionContext>()
+      })
+  })
+})