goke 6.5.1 → 6.5.2

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>()
+      })
+  })
+})

package/src/goke.ts

@@ -348,6 +348,92 @@ type OptionEntry<RawName extends string, Schema> =
     ? { [K in ExtractOptionName<RawName>]?: InferSchemaOutput<Schema> }
     : { [K in ExtractOptionName<RawName>]: InferSchemaOutput<Schema> }
 
+/**
+ * Infer the raw runtime value shape for an option declared without a schema.
+ *
+ * Required value options (`--port <port>`) always reach actions as strings.
+ * Optional value options (`--host [host]`) can be strings, the sentinel
+ * boolean `true` when passed without a value, or `undefined` when omitted.
+ * Plain flags (`--verbose`) are booleans.
+ */
+type UntypedOptionValue<RawName extends string> =
+  RawName extends `${string}<${string}>` ? string :
+  RawName extends `${string}[${string}]` ? string | boolean | undefined :
+  boolean | undefined
+
+/**
+ * Build the option type entry for a `.option()` call that uses a plain
+ * description (no schema).
+ */
+type UntypedOptionEntry<RawName extends string> =
+  RawName extends `${string}<${string}>`
+    ? { [K in ExtractOptionName<RawName>]: UntypedOptionValue<RawName> }
+    : { [K in ExtractOptionName<RawName>]?: UntypedOptionValue<RawName> }
+
+/**
+ * Tokenize a command raw name by splitting on whitespace.
+ * "mcp getNodeXml <id>" → ["mcp", "getNodeXml", "<id>"]
+ * "" → []
+ */
+type TokenizeName<S extends string, Acc extends readonly string[] = []> =
+  S extends `${infer Head} ${infer Rest}`
+    ? TokenizeName<Rest, [...Acc, Head]>
+    : S extends ''
+      ? Acc
+      : [...Acc, S]
+
+/**
+ * Given a single token, return the corresponding positional arg type or
+ * `never` if the token is not a bracketed arg.
+ *
+ * `<id>`       → string          (required)
+ * `[id]`       → string | undefined (optional)
+ * `<...files>` → string[]        (variadic required)
+ * `[...files]` → string[]        (variadic optional)
+ * Anything else → never (filtered out by ExtractCommandArgs)
+ */
+type TokenToArgType<T extends string> =
+  T extends `<...${string}>` ? string[] :
+  T extends `[...${string}]` ? string[] :
+  T extends `<${string}>` ? string :
+  T extends `[${string}]` ? string | undefined :
+  never
+
+/**
+ * Filter a tokenized command raw name down to the positional arg tokens
+ * and map each to its inferred type.
+ */
+type ExtractCommandArgs<T extends readonly string[]> =
+  T extends readonly [infer Head extends string, ...infer Tail extends string[]]
+    ? [TokenToArgType<Head>] extends [never]
+      ? ExtractCommandArgs<Tail>
+      : [TokenToArgType<Head>, ...ExtractCommandArgs<Tail>]
+    : []
+
+/**
+ * Extract the tuple of positional arg types from a command raw name.
+ *
+ * "mcp getNodeXml <id>"    → [string]
+ * "convert <input> <output>" → [string, string]
+ * "run [script]"           → [string | undefined]
+ * "exec [...args]"         → [string[]]
+ * "deploy"                 → []
+ */
+type ExtractPositionalArgs<RawName extends string> =
+  ExtractCommandArgs<TokenizeName<RawName>>
+
+/**
+ * Build the full argument tuple passed to a command's action callback.
+ *
+ * Format: [...positionalArgs, options, executionContext]
+ *
+ * This matches the runtime behavior in Goke.runMatchedCommand(): the action
+ * is called with positional args from the parsed command, then the parsed
+ * options object, then the injected GokeExecutionContext.
+ */
+type ActionArgs<RawName extends string, Opts> =
+  [...ExtractPositionalArgs<RawName>, Opts, GokeExecutionContext]
+
 interface CommandArg {
   required: boolean
   value: string
@@ -368,7 +454,7 @@ type HelpCallback = (sections: HelpSection[]) => void | HelpSection[]
 
 type CommandExample = ((bin: string) => string) | string
 
-class Command {
+class Command<RawName extends string = string, Opts = {}> {
   options: Option[]
   aliasNames: string[]
   /* Parsed command name */
@@ -383,7 +469,7 @@ class Command {
   _hidden?: boolean
 
   constructor(
-    public rawName: string,
+    public rawName: RawName,
     public description: string,
     public config: CommandConfig = {},
     public cli: Goke<any>
@@ -426,7 +512,9 @@ class Command {
    *
    * The second argument is either a description string or a StandardJSONSchemaV1
    * schema. When a schema is provided, description and default are extracted from
-   * the JSON Schema automatically.
+   * the JSON Schema automatically, and the option's type is tracked on the
+   * Command's `Opts` type parameter so that subsequent `.action()` callbacks
+   * receive a fully-typed options object.
    *
    * @example
    * ```ts
@@ -438,10 +526,16 @@ class Command {
    * ```
    */
   option<
-    RawName extends string,
+    OptionRawName extends string,
     S extends StandardJSONSchemaV1
-  >(rawName: RawName, schema: S): Command & { __opts: OptionEntry<RawName, S> }
-  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
+  >(
+    rawName: OptionRawName,
+    schema: S,
+  ): Command<RawName, Opts & OptionEntry<OptionRawName, S>>
+  option<OptionRawName extends string>(
+    rawName: OptionRawName,
+    description?: string,
+  ): Command<RawName, Opts & UntypedOptionEntry<OptionRawName>>
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
     const option = new Option(rawName, descriptionOrSchema)
     this.options.push(option)
@@ -458,7 +552,24 @@ class Command {
     return this
   }
 
-  action(callback: (...args: any[]) => any) {
+  /**
+   * Register the action callback that runs when this command is matched.
+   *
+   * The callback receives positional args extracted from the command's raw name,
+   * followed by the parsed options object and the injected GokeExecutionContext.
+   *
+   * Positional arg types are inferred from the raw name at the type level:
+   *   `command('convert <input> <output>')` → `(input: string, output: string, options, ctx)`
+   *   `command('run [script]')`              → `(script: string | undefined, options, ctx)`
+   *   `command('exec [...args]')`            → `(args: string[], options, ctx)`
+   *
+   * The options object is typed according to every `.option()` call chained
+   * on this command, plus any global options declared on the parent Goke
+   * instance before `.command()` was called.
+   */
+  action(
+    callback: (...args: ActionArgs<RawName, Opts>) => unknown | Promise<unknown>,
+  ): this {
     this.commandAction = callback
     return this
   }
@@ -919,14 +1030,14 @@ interface ParsedArgv {
   }
 }
 
-class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
+class Goke<Opts = {}> extends EventEmitter {
   /** The program name to display in help and version message */
   name: string
-  commands: Command[]
+  commands: Command<any, any>[]
   /** Middleware functions that run before the matched command action, in registration order */
   middlewares: Array<{ action: (options: any, context: GokeExecutionContext) => void | Promise<void> }>
   globalCommand: GlobalCommand
-  matchedCommand?: Command
+  matchedCommand?: Command<any, any>
   matchedCommandName?: string
   /**
    * Raw CLI arguments
@@ -1056,10 +1167,24 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   }
 
   /**
-   * Add a sub-command
+   * Add a sub-command.
+   *
+   * The returned Command is parameterized by the literal `rawName` (so positional
+   * args can be inferred at the type level) and by this Goke's accumulated global
+   * `Opts` (so global options declared before `.command()` are visible inside
+   * `.action()` callbacks alongside the command's own options).
    */
-  command(rawName: string, description?: string, config?: CommandConfig) {
-    const command = new Command(rawName, description || '', config, this)
+  command<CommandRawName extends string>(
+    rawName: CommandRawName,
+    description?: string,
+    config?: CommandConfig,
+  ): Command<CommandRawName, Opts> {
+    const command = new Command<CommandRawName, Opts>(
+      rawName,
+      description || '',
+      config,
+      this,
+    )
     command.globalCommand = this.globalCommand
     this.commands.push(command)
     return command
@@ -1071,13 +1196,21 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
    * Which is also applied to sub-commands.
    *
    * When a StandardJSONSchemaV1 schema is provided, the return type is narrowed
-   * to include the inferred option type — enabling type-safe `.use()` callbacks.
+   * to include the inferred option type — enabling type-safe `.use()` callbacks
+   * and typed `options` params inside command `.action()` handlers.
+   *
+   * When a plain description string is provided, the option is still tracked on
+   * the Goke's `Opts` type, but with a loose `string | boolean | undefined` value
+   * type (since no coercion schema is available).
    */
   option<
     RawName extends string,
     S extends StandardJSONSchemaV1
   >(rawName: RawName, schema: S): Goke<Opts & OptionEntry<RawName, S>>
-  option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
+  option<RawName extends string>(
+    rawName: RawName,
+    description?: string,
+  ): Goke<Opts & UntypedOptionEntry<RawName>>
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
     const option = new Option(rawName, descriptionOrSchema)
     this.globalCommand.options.push(option)

package/src/runtime-node.ts

@@ -12,7 +12,7 @@ const fs: GokeFs = nodeFs
 
 function openInBrowser(url: string): void {
   if (!process.stdout.isTTY) {
-    process.stderr.write(url + '\n')
+    process.stdout.write(url + '\n')
     return
   }
 
@@ -25,7 +25,7 @@ function openInBrowser(url: string): void {
       execSync(`xdg-open ${JSON.stringify(url)}`, { stdio: 'ignore' })
     }
   } catch {
-    process.stderr.write(url + '\n')
+    process.stdout.write(url + '\n')
   }
 }