goke 6.5.0 → 6.5.2

package/README.md

@@ -2,22 +2,52 @@
     <br/>
     <br/>
     <h3>goke</h3>
-    <p>simple, type safe, elegant command line framework. CAC replacement</p>
+    <p>Build CLIs like you'd build an API. Type-safe, chainable, zero dependencies.</p>
     <br/>
     <br/>
 </div>
 
+goke is a TypeScript CLI framework with a [Hono](https://hono.dev)-like API. You chain `.use()` for middleware and `.command()` for routes — the same mental model as a REST API, applied to the terminal.
+
+```ts
+import { goke } from 'goke'
+import { z } from 'zod'
+
+const cli = goke('deploy')
+
+// middleware — runs before every command
+cli
+  .option('--env <env>', z.enum(['staging', 'production']).default('staging').describe('Target environment'))
+  .use((options, { console }) => {
+    console.log(`Environment: ${options.env}`)
+  })
+
+// commands — like route handlers
+cli
+  .command('up', 'Deploy the app')
+  .option('--dry-run', 'Preview without deploying')
+  .action((options, { console, process }) => {
+    console.log(`Deploying from ${process.cwd}`)
+  })
+
+cli
+  .command('logs <deploymentId>', 'Stream logs')
+  .option('--lines <n>', z.number().default(100).describe('Lines to tail'))
+  .action((id, options) => streamLogs(id, options.lines))
+
+cli.help()
+cli.parse()
+```
 
 ## Features
 
-- **Super light-weight**: No dependency, just a single file.
-- **Easy to learn**. There are only 5 APIs you need to learn for building simple CLIs: `cli.option` `cli.use` `cli.version` `cli.help` `cli.parse`.
-- **Yet so powerful**. Enable features like default command, git-like subcommands, validation for required arguments and options, variadic arguments, dot-nested options, automated help message generation and so on.
-- **Space-separated subcommands**: Support multi-word commands like `mcp login`, `git remote add`.
-- **Schema-based type coercion**: Use Zod, Valibot, ArkType, or plain JSON Schema for automatic type coercion and TypeScript type inference. Description and default values are extracted from the schema automatically.
-- **Injected execution context**: Prefer `{ fs, console, process }` in actions and middleware for portable storage, output, and runtime metadata across Node.js, tests, and JustBash.
-- **Type-safe middleware**: Register `.use()` callbacks that run before commands with full type inference from global options.
-- **Developer friendly**. Written in TypeScript.
+- **Hono-like chaining** — `.use()` for middleware, `.command()` for handlers. Build a CLI the same way you'd design a REST API.
+- **Zod type safety** — pass a Zod schema to `.option()` and get automatic coercion, TypeScript inference, and help text for free. Works with Valibot, ArkType, or any Standard Schema library.
+- **MCP server in 2 lines** — expose your entire CLI as an MCP server with `createMcpAction({ cli })`. Every command becomes a tool, ready for Claude Desktop, Cursor, VS Code, and [any MCP client](https://github.com/supermemoryai/install-mcp#supported-clients).
+- **JustBash support** — `cli.createJustBashCommand()` exposes your CLI as a sandboxed JustBash command. Same action code, no changes needed.
+- **Space-separated subcommands** — `git remote add`, `mcp login`, `db migrate` — multi-word commands work out of the box.
+- **Injected `{ fs, console, process }`** — commands receive a portable runtime context. Swap it in tests, or let JustBash replace it with a sandbox. No global side effects.
+- **Zero dependencies** — single file, no runtime deps.
 
 ## Install
 
@@ -25,6 +55,14 @@
 npm install goke
 ```
 
+## Install skill for AI agents
+
+```bash
+npx -y skills add remorses/goke
+```
+
+This installs the repository skill for AI coding agents. In this repo the shipped skill lives at `skills/goke/SKILL.md`.
+
 ## Usage
 
 ### Simple Parsing
@@ -390,6 +428,22 @@ cli
 
 Prefer injected `fs` for CLI storage instead of importing `node:fs/promises` directly inside actions. That keeps the command portable to JustBash and easier to test.
 
+### Path handling
+
+Use relative paths with injected `fs` for routine CLI storage paths. When a helper needs to resolve from the current directory, pass injected `process.cwd` into that helper and resolve from there.
+
+```ts
+await fs.mkdir('.mycli', { recursive: true })
+await fs.writeFile('.mycli/auth.json', json, 'utf8')
+console.log('running from', process.cwd)
+```
+
+Why this works:
+
+- In normal Node.js runs, relative paths resolve against the host cwd.
+- In JustBash runs, the same relative paths resolve against the sandbox cwd.
+- `process.cwd` mirrors that runtime-specific cwd in both environments.
+
 `goke` also exports the runtime types, so helper functions can use dependency injection without reaching for globals:
 
 ```ts
@@ -810,6 +864,78 @@ await bash.exec('parent child commandwithspaces --name Tommy')
 
 Prefer the injected `{ fs, console, process }` helpers in command implementations so the same command code works cleanly both in the regular CLI runtime and through the JustBash bridge. The injected `fs` defaults to Node `fs/promises`, and `process.cwd` / `process.env` / `process.stdin` reflect host values in Node but sandbox values inside `createJustBashCommand()`.
 
+### Test with real JustBash
+
+When a command reads or writes files, test it through real `just-bash` using the existing app CLI. Do not define the CLI inside the test body.
+
+```ts
+import { describe, expect, test } from 'vitest'
+import { Bash, InMemoryFs } from 'just-bash'
+import { cli } from '../src/cli'
+
+describe('login command', () => {
+  test('writes auth state through the sandbox fs', async () => {
+    const virtualFs = new InMemoryFs()
+    await virtualFs.mkdir('/project', { recursive: true })
+
+    const bash = new Bash({
+      fs: virtualFs,
+      cwd: '/project',
+      customCommands: [await cli.createJustBashCommand()],
+    })
+
+    const result = await bash.exec('parent login --token Tommy')
+
+    expect(result.stdout).toBe('saved credentials\n')
+    expect(await virtualFs.readFile('/project/.mycli/auth.json', 'utf8')).toBe(
+      '{"token":"Tommy","cwd":"/project"}',
+    )
+  })
+})
+```
+
+This is the recommended compatibility test whenever a CLI touches storage: run the same CLI once in normal tests and once through real `just-bash`.
+
+### Exposing your CLI as a skill
+
+If you build a CLI with goke, keep the skill minimal and point agents to the CLI help output. Put detailed usage in the CLI code and README, not in a duplicated skill file.
+
+````markdown
+<!-- skills/acme/SKILL.md -->
+---
+name: acme
+description: >
+  acme is a deployment CLI. Always run `acme --help` before using it
+  to discover available commands, options, and usage examples.
+---
+
+# acme
+
+Always run `acme --help` before using this CLI.
+For subcommand details: `acme <command> --help`
+````
+
+## Contributor Notes
+
+### Rules
+
+1. Use schema-based options for typed values.
+2. Do not repeat defaults in `.describe(...)` when using `.default()`.
+3. Do not manually type action callback arguments; let goke infer them.
+4. Prefer injected `{ fs, console, process }` over global `console`, `process.exit`, or direct `node:fs/promises` imports.
+5. Use implicit cwd with injected `fs` for CLI storage. When a helper needs current-cwd semantics, pass `process.cwd` from the injected context into that helper.
+6. Define the CLI in app code and import that same CLI in tests; do not construct a separate CLI inside compatibility tests.
+
+### Version
+
+Import `package.json` and use its version field so the CLI stays in sync automatically:
+
+```ts
+import pkg from './package.json' with { type: 'json' }
+
+cli.version(pkg.version)
+```
+
 ## References
 
 ### CLI Instance
@@ -867,6 +993,26 @@ Register a middleware function that runs before the matched command action. Midd
 
 Print the help message to stdout.
 
+#### cli.clone(options?)
+
+- Type: `(options?: GokeOptions) => Goke`
+
+Create a deep copy of the CLI instance with all commands, options, middleware, and event listeners. Override any `GokeOptions` (stdout, stderr, cwd, env, fs, argv, columns, exit) in the clone without affecting the original. Primarily useful in tests to run multiple isolated parses from the same CLI definition:
+
+```ts
+const cli = goke('mycli')
+cli.command('build', 'Build project').action((options, { console }) => {
+  console.log('building')
+})
+cli.help()
+
+// In tests: override streams without touching the original CLI
+const stdout = { write: vi.fn<(data: string) => void>() }
+const isolated = cli.clone({ stdout })
+isolated.parse(['node', 'mycli', 'build'])
+expect(stdout.write).toHaveBeenCalledWith('building\n')
+```
+
 #### cli.helpText()
 
 - Type: `() => string`
@@ -911,6 +1057,21 @@ Command callbacks receive positional args first, then parsed options, then an in
 
 - Type: `() => Command`
 
+#### command.hidden()
+
+- Type: `() => Command`
+
+Hide a command from the help output listing. The command still matches and runs when invoked directly — only the help display is suppressed. Useful for internal, deprecated, or experimental commands you don't want to advertise.
+
+```ts
+cli
+  .command('internal-reset', 'Reset internal state')
+  .hidden()
+  .action((options, { console }) => {
+    console.log('reset done')
+  })
+```
+
 #### command.example(example)
 
 - Type: `(example: CommandExample) => Command`
@@ -919,6 +1080,12 @@ Command callbacks receive positional args first, then parsed options, then an in
 
 - Type: `(text: string) => Command`
 
+#### command.helpText()
+
+- Type: `() => string`
+
+Return the formatted help string for this specific command without printing it. Useful for tests or embedding help text programmatically.
+
 ### Events
 
 Listen to commands:

package/dist/__test__/readme-examples.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Smoke tests that keep README examples and documented APIs executable.
+ */
+export {};
+//# sourceMappingURL=readme-examples.test.d.ts.map

package/dist/__test__/readme-examples.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme-examples.test.d.ts","sourceRoot":"","sources":["../../src/__test__/readme-examples.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__test__/readme-examples.test.js

@@ -0,0 +1,169 @@
+/**
+ * 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';
+const ANSI_RE = /\x1B\[[0-9;]*m/g;
+const stripAnsi = (text) => text.replace(ANSI_RE, '');
+function createTestOutputStream() {
+    const lines = [];
+    return {
+        lines,
+        get text() { return stripAnsi(lines.join('')); },
+        write(data) { lines.push(data); },
+    };
+}
+function gokeTestable(name = '', options) {
+    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) => {
+            stdout += String(chunk);
+            return true;
+        });
+        process.stderr.write = ((chunk) => {
+            stderr += String(chunk);
+            return true;
+        });
+        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/dist/__test__/types.test-d.js

@@ -1,11 +1,14 @@
 /**
  * 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 goke from '../index.js';
 describe('type-level: ExtractOptionName', () => {
     test('extracts name from --name <value>', () => {
@@ -117,3 +120,237 @@ 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();
+        });
+    });
+    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();
+            expectTypeOf(options).toEqualTypeOf();
+            expectTypeOf(ctx).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(output).toEqualTypeOf();
+            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();
+            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();
+            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();
+            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();
+            expectTypeOf(options).toEqualTypeOf();
+        });
+    });
+    test('default command with one positional arg', () => {
+        goke('test')
+            .command('<file>', 'Default command')
+            .action((file, options) => {
+            expectTypeOf(file).toEqualTypeOf();
+            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();
+            expectTypeOf(cc).toEqualTypeOf();
+            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();
+            expectTypeOf(ctx).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(options.host).toEqualTypeOf();
+            // Boolean flag is optional (no <...> brackets)
+            expectTypeOf(options.verbose).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(options.count).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(options.myLongFlag).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(output).toEqualTypeOf();
+            expectTypeOf(options.quality).toEqualTypeOf();
+            expectTypeOf(options.format).toEqualTypeOf();
+            expectTypeOf(ctx).toEqualTypeOf();
+        });
+    });
+    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();
+            // Command-local option
+            expectTypeOf(options.port).toEqualTypeOf();
+        });
+    });
+    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();
+        });
+    });
+    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();
+            expectTypeOf(options.verbose).toEqualTypeOf();
+        });
+    });
+    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();
+            // @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();
+            expectTypeOf(options).toEqualTypeOf();
+            expectTypeOf(ctx).toEqualTypeOf();
+            // 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();
+        });
+        // 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();
+            expectTypeOf(options.port).toEqualTypeOf();
+            expectTypeOf(options.watch).toEqualTypeOf();
+            expectTypeOf(console.log).toBeFunction();
+            expectTypeOf(process.cwd).toEqualTypeOf();
+        });
+    });
+    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();
+            expectTypeOf(options.apiUrl).toEqualTypeOf();
+            expectTypeOf(process.stdin).toEqualTypeOf();
+        })
+            .command('deploy <env>', 'Deploy to an environment')
+            .option('--dry-run', 'Preview without deploying')
+            .action((env, options, ctx) => {
+            expectTypeOf(env).toEqualTypeOf();
+            expectTypeOf(options.verbose).toEqualTypeOf();
+            expectTypeOf(options.apiUrl).toEqualTypeOf();
+            expectTypeOf(options.dryRun).toEqualTypeOf();
+            expectTypeOf(ctx).toEqualTypeOf();
+        });
+    });
+});