goke 6.5.1 → 6.6.0

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 runtime dependencies** — install `goke` without pulling extra runtime packages into your CLI.
 
 ## Install
 

package/dist/__test__/index.test.js

@@ -230,7 +230,9 @@ test('dot-nested options', () => {
         .option('--scale [level]', 'Scaling level');
     const { options: options1 } = cli.parse(`node bin --externals.env.prod production --scale`.split(' '));
     expect(options1.externals).toEqual({ env: { prod: 'production' } });
-    expect(options1.scale).toEqual(true);
+    // Bare `--scale` normalizes to `''` (new uniform string-or-undefined shape
+    // for untyped optional-value flags).
+    expect(options1.scale).toEqual('');
 });
 describe('schema-based options', () => {
     test('schema coerces string to number', () => {
@@ -334,11 +336,14 @@ describe('no-schema behavior (mri no longer auto-converts)', () => {
         const { options } = cli.parse('node bin --verbose'.split(' '));
         expect(options.verbose).toBe(true);
     });
-    test('optional value flag returns true when no value given', () => {
+    test('optional value flag returns empty string when no value given', () => {
+        // Bare `--format` is normalized from the mri `true` sentinel to `''` so
+        // callers see a uniform `string | undefined` shape. `''` still lets them
+        // distinguish "flag present but no value" from "flag omitted entirely".
         const cli = goke();
         cli.option('--format [fmt]', 'Format');
         const { options } = cli.parse('node bin --format'.split(' '));
-        expect(options.format).toBe(true);
+        expect(options.format).toBe('');
     });
     test('optional value flag returns string when value given', () => {
         const cli = goke();
@@ -545,12 +550,17 @@ describe('regression: oracle-found issues', () => {
         const { options } = cli.parse('node bin --count'.split(' '));
         expect(options.count).toBe(undefined);
     });
-    test('optional value option without schema preserves true sentinel', () => {
+    test('optional value option without schema normalizes bare flag to empty string', () => {
         const cli = goke();
         cli.option('--count [count]', 'Count');
-        // Without schema, original goke behavior: true means "flag present"
+        // Untyped optional-value flags uniformly expose `string | undefined`:
+        //   - `--count`       → ''          (flag present, no value)
+        //   - `--count 42`    → '42'        (flag present, with value)
+        //   - (omitted)       → undefined   (flag absent)
+        // This lets callers use a single `typeof options.count === 'string'`
+        // check and distinguish the three cases via `=== ''` if they need to.
         const { options } = cli.parse('node bin --count'.split(' '));
-        expect(options.count).toBe(true);
+        expect(options.count).toBe('');
     });
     test('optional value option with schema coerces when value given', () => {
         const cli = goke();

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,241 @@ 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 surface as string | undefined', () => {
+        goke('test')
+            .command('serve', 'Start server')
+            .option('--host [host]', 'Optional host override')
+            .option('--verbose', 'Verbose output')
+            .action((options) => {
+            // `[value]` options always resolve to `string | undefined`:
+            //   - omitted           → undefined
+            //   - `--host`          → ''  (flag present, no value)
+            //   - `--host example`  → 'example'
+            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();
+        });
+    });
+});