goke 6.10.0 → 6.12.0

package/dist/__test__/index.test.js

@@ -47,7 +47,7 @@ function stripStackTrace(text) {
         .trim();
 }
 describe('error formatting', () => {
-    test('unknown option prints formatted error to stderr', () => {
+    test('unknown option prints formatted error to stderr', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli
@@ -55,12 +55,12 @@ describe('error formatting', () => {
             .option('--port <port>', 'Port')
             .action(() => { });
         try {
-            cli.parse('node bin build --unknown'.split(' '));
+            await cli.parse('node bin build --unknown'.split(' '));
         }
         catch { }
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: Unknown option \`--unknown\`"`);
     });
-    test('missing required option value prints formatted error to stderr', () => {
+    test('missing required option value prints formatted error to stderr', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli
@@ -68,22 +68,22 @@ describe('error formatting', () => {
             .option('--port <port>', 'Port')
             .action(() => { });
         try {
-            cli.parse('node bin serve --port'.split(' '));
+            await cli.parse('node bin serve --port'.split(' '));
         }
         catch { }
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: option \`--port <port>\` value is missing"`);
     });
-    test('schema coercion error prints formatted error to stderr', () => {
+    test('schema coercion error prints formatted error to stderr', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli.option('--port <port>', z.number().describe('Port'));
         try {
-            cli.parse('node bin --port abc'.split(' '));
+            await cli.parse('node bin --port abc'.split(' '));
         }
         catch { }
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: Invalid value for --port: expected number, got "abc""`);
     });
-    test('error includes help hint when help is enabled', () => {
+    test('error includes help hint when help is enabled', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli.help();
@@ -92,7 +92,7 @@ describe('error formatting', () => {
             .option('--port <port>', 'Port')
             .action(() => { });
         try {
-            cli.parse('node bin serve --port'.split(' '));
+            await cli.parse('node bin serve --port'.split(' '));
         }
         catch { }
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`
@@ -109,20 +109,20 @@ describe('error formatting', () => {
             .action(async () => {
             throw new Error('connection refused');
         });
-        cli.parse('node bin deploy'.split(' '));
+        await cli.parse('node bin deploy'.split(' '));
         // Wait for the async rejection to be handled
         await new Promise(resolve => setTimeout(resolve, 10));
         expect(exitCode).toBe(1);
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: connection refused"`);
     });
-    test('error output includes stack trace', () => {
+    test('error output includes stack trace', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli
             .command('build', 'Build app')
             .action(() => { });
         try {
-            cli.parse('node bin build --unknown'.split(' '));
+            await cli.parse('node bin build --unknown'.split(' '));
         }
         catch { }
         // Verify that stderr contains "error:" prefix and a stack trace with "at" lines
@@ -133,7 +133,7 @@ describe('error formatting', () => {
     });
 });
 describe('anonymous action naming', () => {
-    test('inline anonymous function gets named after the command', () => {
+    test('inline anonymous function gets named after the command', async () => {
         const cli = gokeTestable('mycli');
         const cmd = cli.command('deploy', 'Deploy app');
         // Inline arrow functions passed directly to .action() have no name,
@@ -141,20 +141,20 @@ describe('anonymous action naming', () => {
         cmd.action(() => { });
         expect(cmd.commandAction.name).toBe('command:deploy');
     });
-    test('inline anonymous function on multi-word command gets full name', () => {
+    test('inline anonymous function on multi-word command gets full name', async () => {
         const cli = gokeTestable('mycli');
         const cmd = cli.command('db migrate', 'Run migrations');
         cmd.action(() => { });
         expect(cmd.commandAction.name).toBe('command:db migrate');
     });
-    test('named function keeps its original name', () => {
+    test('named function keeps its original name', async () => {
         const cli = gokeTestable('mycli');
         const cmd = cli.command('build', 'Build app');
         function myBuildAction() { }
         cmd.action(myBuildAction);
         expect(cmd.commandAction.name).toBe('myBuildAction');
     });
-    test('default command action gets "command:default" name', () => {
+    test('default command action gets "command:default" name', async () => {
         const cli = gokeTestable('mycli');
         const cmd = cli.command('', 'Default command');
         cmd.action(() => { });
@@ -162,6 +162,18 @@ describe('anonymous action naming', () => {
     });
 });
 describe('injected fs', () => {
+    test('parse waits for async command actions before resolving', async () => {
+        const stdout = createTestOutputStream();
+        const cli = gokeTestable('mycli', { stdout });
+        cli
+            .command('deploy', 'Deploy app')
+            .action(async (options, { console }) => {
+            await new Promise(resolve => setTimeout(resolve, 10));
+            console.log('deploy complete');
+        });
+        await cli.parse(['node', 'bin', 'deploy']);
+        expect(stdout.text).toBe('deploy complete\n');
+    });
     test('command actions can use the default node fs for cli storage', async () => {
         const stdout = createTestOutputStream();
         const cli = gokeTestable('mycli', { stdout });
@@ -177,7 +189,7 @@ describe('injected fs', () => {
                 await fs.writeFile('.mycli/auth.json', JSON.stringify({ token: options.token }), 'utf8');
                 console.log('saved credentials');
             });
-            cli.parse(['node', 'bin', 'login', '--token', 'abc123'], { run: false });
+            await cli.parse(['node', 'bin', 'login', '--token', 'abc123'], { run: false });
             await cli.runMatchedCommand();
             expect(stdout.text).toBe('saved credentials\n');
             expect(await readFile(join(tempDir, '.mycli/auth.json'), 'utf8')).toBe('{"token":"abc123"}');
@@ -207,7 +219,7 @@ describe('injected process context', () => {
                     token: process.env.GOKE_TEST_TOKEN,
                 }));
             });
-            cli.parse(['node', 'bin', 'context'], { run: false });
+            await cli.parse(['node', 'bin', 'context'], { run: false });
             await cli.runMatchedCommand();
             expect(stdout.text).toBe(`${JSON.stringify({ cwd: process.cwd(), stdin: '', token: 'abc123' })}\n`);
         }
@@ -232,15 +244,15 @@ describe('injected process context', () => {
             process.env.TOKEN = 'after';
             console.log(process.env.TOKEN);
         });
-        cli.parse(['node', 'bin', 'context'], { run: false });
+        await cli.parse(['node', 'bin', 'context'], { run: false });
         await cli.runMatchedCommand();
         expect(stdout.text).toBe('after\n');
         expect(env.TOKEN).toBe('after');
     });
 });
-test('double dashes', () => {
+test('double dashes', async () => {
     const cli = goke();
-    const { args, options } = cli.parse([
+    const { args, options } = await cli.parse([
         'node',
         'bin',
         'foo',
@@ -252,80 +264,80 @@ test('double dashes', () => {
     expect(args).toEqual(['foo', 'bar']);
     expect(options['--']).toEqual(['npm', 'test']);
 });
-test('dot-nested options', () => {
+test('dot-nested options', async () => {
     const cli = goke();
     cli
         .option('--externals <external>', 'Add externals')
         .option('--scale [level]', 'Scaling level');
-    const { options: options1 } = cli.parse(`node bin --externals.env.prod production --scale`.split(' '));
+    const { options: options1 } = await cli.parse(`node bin --externals.env.prod production --scale`.split(' '));
     expect(options1.externals).toEqual({ env: { prod: 'production' } });
     // 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', () => {
+    test('schema coerces string to number', async () => {
         const cli = goke();
         cli.option('--port <port>', z.number().describe('Port number'));
-        const { options } = cli.parse('node bin --port 3000'.split(' '));
+        const { options } = await cli.parse('node bin --port 3000'.split(' '));
         expect(options.port).toBe(3000);
         expect(typeof options.port).toBe('number');
     });
-    test('schema preserves string (no auto-conversion to number)', () => {
+    test('schema preserves string (no auto-conversion to number)', async () => {
         const cli = goke();
         cli.option('--id <id>', z.string().describe('ID'));
-        const { options } = cli.parse('node bin --id 00123'.split(' '));
+        const { options } = await cli.parse('node bin --id 00123'.split(' '));
         expect(options.id).toBe('00123');
         expect(typeof options.id).toBe('string');
     });
-    test('schema coerces string to integer', () => {
+    test('schema coerces string to integer', async () => {
         const cli = goke();
         cli.option('--count <count>', z.int().describe('Count'));
-        const { options } = cli.parse('node bin --count 42'.split(' '));
+        const { options } = await cli.parse('node bin --count 42'.split(' '));
         expect(options.count).toBe(42);
     });
-    test('schema parses JSON object', () => {
+    test('schema parses JSON object', async () => {
         const cli = goke();
         cli.option('--config <config>', z.looseObject({}).describe('Config'));
-        const { options } = cli.parse(['node', 'bin', '--config', '{"a":1}']);
+        const { options } = await cli.parse(['node', 'bin', '--config', '{"a":1}']);
         expect(options.config).toEqual({ a: 1 });
     });
-    test('schema parses JSON array', () => {
+    test('schema parses JSON array', async () => {
         const cli = goke();
         cli.option('--items <items>', z.array(z.unknown()).describe('Items'));
-        const { options } = cli.parse(['node', 'bin', '--items', '[1,2,3]']);
+        const { options } = await cli.parse(['node', 'bin', '--items', '[1,2,3]']);
         expect(options.items).toEqual([1, 2, 3]);
     });
-    test('schema throws on invalid number', () => {
+    test('schema throws on invalid number', async () => {
         const cli = gokeTestable();
         cli.option('--port <port>', z.number().describe('Port number'));
-        expect(() => cli.parse('node bin --port abc'.split(' ')))
-            .toThrow('expected number, got "abc"');
+        await expect(cli.parse('node bin --port abc'.split(' ')))
+            .rejects.toThrow('expected number, got "abc"');
     });
-    test('schema with union type ["number", "string"]', () => {
+    test('schema with union type ["number", "string"]', async () => {
         const cli = goke();
         cli.option('--val <val>', z.union([z.number(), z.string()]).describe('Value'));
-        const { options: opts1 } = cli.parse('node bin --val 123'.split(' '));
+        const { options: opts1 } = await cli.parse('node bin --val 123'.split(' '));
         expect(opts1.val).toBe(123);
-        const { options: opts2 } = cli.parse('node bin --val abc'.split(' '));
+        const { options: opts2 } = await cli.parse('node bin --val abc'.split(' '));
         expect(opts2.val).toBe('abc');
     });
-    test('options without schema keep values as strings', () => {
+    test('options without schema keep values as strings', async () => {
         const cli = goke();
         cli.option('--port <port>', 'Port number');
         // Without schema, mri no longer auto-converts — value stays as string.
         // Use a schema to get typed values.
-        const { options } = cli.parse('node bin --port 3000'.split(' '));
+        const { options } = await cli.parse('node bin --port 3000'.split(' '));
         expect(options.port).toBe('3000');
         expect(typeof options.port).toBe('string');
     });
-    test('schema with default value', () => {
+    test('schema with default value', async () => {
         const cli = goke();
         cli.option('--port [port]', z.number().default(8080).describe('Port number'));
-        const { options } = cli.parse('node bin'.split(' '));
+        const { options } = await cli.parse('node bin'.split(' '));
         expect(options.port).toBe(8080);
     });
-    test('schema on subcommand options', () => {
+    test('schema on subcommand options', async () => {
         const cli = goke();
         let result = {};
         cli
@@ -335,66 +347,66 @@ describe('schema-based options', () => {
             .action((options) => {
             result = options;
         });
-        cli.parse('node bin serve --port 3000 --host localhost'.split(' '), { run: true });
+        await cli.parse('node bin serve --port 3000 --host localhost'.split(' '), { run: true });
         expect(result.port).toBe(3000);
         expect(result.host).toBe('localhost');
     });
 });
 describe('no-schema behavior (mri no longer auto-converts)', () => {
-    test('numeric string stays as string without schema', () => {
+    test('numeric string stays as string without schema', async () => {
         const cli = goke();
         cli.option('--port <port>', 'Port');
-        const { options } = cli.parse('node bin --port 3000'.split(' '));
+        const { options } = await cli.parse('node bin --port 3000'.split(' '));
         expect(options.port).toBe('3000');
     });
-    test('leading zeros preserved without schema', () => {
+    test('leading zeros preserved without schema', async () => {
         const cli = goke();
         cli.option('--id <id>', 'ID');
-        const { options } = cli.parse('node bin --id 00123'.split(' '));
+        const { options } = await cli.parse('node bin --id 00123'.split(' '));
         expect(options.id).toBe('00123');
     });
-    test('phone number preserved without schema', () => {
+    test('phone number preserved without schema', async () => {
         const cli = goke();
         cli.option('--phone <phone>', 'Phone');
-        const { options } = cli.parse('node bin --phone +1234567890'.split(' '));
+        const { options } = await cli.parse('node bin --phone +1234567890'.split(' '));
         expect(options.phone).toBe('+1234567890');
     });
-    test('boolean flags still work without schema', () => {
+    test('boolean flags still work without schema', async () => {
         const cli = goke();
         cli.option('--verbose', 'Verbose');
-        const { options } = cli.parse('node bin --verbose'.split(' '));
+        const { options } = await cli.parse('node bin --verbose'.split(' '));
         expect(options.verbose).toBe(true);
     });
-    test('optional value flag returns empty string when no value given', () => {
+    test('optional value flag returns empty string when no value given', async () => {
         // 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(' '));
+        const { options } = await cli.parse('node bin --format'.split(' '));
         expect(options.format).toBe('');
     });
-    test('optional value flag returns string when value given', () => {
+    test('optional value flag returns string when value given', async () => {
         const cli = goke();
         cli.option('--format [fmt]', 'Format');
-        const { options } = cli.parse('node bin --format json'.split(' '));
+        const { options } = await cli.parse('node bin --format json'.split(' '));
         expect(options.format).toBe('json');
     });
-    test('hex string stays as string without schema', () => {
+    test('hex string stays as string without schema', async () => {
         const cli = goke();
         cli.option('--color <color>', 'Color');
-        const { options } = cli.parse('node bin --color 0xff00ff'.split(' '));
+        const { options } = await cli.parse('node bin --color 0xff00ff'.split(' '));
         expect(options.color).toBe('0xff00ff');
     });
-    test('scientific notation stays as string without schema', () => {
+    test('scientific notation stays as string without schema', async () => {
         const cli = goke();
         cli.option('--val <val>', 'Value');
-        const { options } = cli.parse('node bin --val 1e10'.split(' '));
+        const { options } = await cli.parse('node bin --val 1e10'.split(' '));
         expect(options.val).toBe('1e10');
     });
 });
 describe('typical CLI usage examples', () => {
-    test('web server CLI with typed options', () => {
+    test('web server CLI with typed options', async () => {
         const cli = goke('myserver');
         let config = {};
         cli
@@ -405,7 +417,7 @@ describe('typical CLI usage examples', () => {
             .option('--cors', 'Enable CORS')
             .option('--log', 'Enable logging')
             .action((options) => { config = options; });
-        cli.parse('node bin start --port 8080 --host 0.0.0.0 --workers 4 --cors'.split(' '), { run: true });
+        await cli.parse('node bin start --port 8080 --host 0.0.0.0 --workers 4 --cors'.split(' '), { run: true });
         expect(config.port).toBe(8080);
         expect(typeof config.port).toBe('number');
         expect(config.host).toBe('0.0.0.0');
@@ -413,7 +425,7 @@ describe('typical CLI usage examples', () => {
         expect(typeof config.workers).toBe('number');
         expect(config.cors).toBe(true);
     });
-    test('web server CLI with defaults (no args)', () => {
+    test('web server CLI with defaults (no args)', async () => {
         const cli = goke('myserver');
         let config = {};
         cli
@@ -421,11 +433,11 @@ describe('typical CLI usage examples', () => {
             .option('--port [port]', z.number().default(3000).describe('Port'))
             .option('--host [host]', z.string().default('localhost').describe('Host'))
             .action((options) => { config = options; });
-        cli.parse('node bin start'.split(' '), { run: true });
+        await cli.parse('node bin start'.split(' '), { run: true });
         expect(config.port).toBe(3000);
         expect(config.host).toBe('localhost');
     });
-    test('database CLI with JSON config option', () => {
+    test('database CLI with JSON config option', async () => {
         const cli = goke('dbcli');
         let config = {};
         cli
@@ -433,11 +445,11 @@ describe('typical CLI usage examples', () => {
             .option('--connection <conn>', z.object({ host: z.string(), port: z.number() }).describe('Connection config (JSON)'))
             .option('--dry-run', 'Preview without executing')
             .action((options) => { config = options; });
-        cli.parse(['node', 'bin', 'migrate', '--connection', '{"host":"localhost","port":5432}', '--dry-run'], { run: true });
+        await cli.parse(['node', 'bin', 'migrate', '--connection', '{"host":"localhost","port":5432}', '--dry-run'], { run: true });
         expect(config.connection).toEqual({ host: 'localhost', port: 5432 });
         expect(config.dryRun).toBe(true);
     });
-    test('file processing CLI with positional args + typed options', () => {
+    test('file processing CLI with positional args + typed options', async () => {
         const cli = goke('fileproc');
         let result = {};
         cli
@@ -447,14 +459,14 @@ describe('typical CLI usage examples', () => {
             .action((input, output, options) => {
             result = { input, output, ...options };
         });
-        cli.parse('node bin convert photo.bmp photo.jpg --quality 85 --format jpg'.split(' '), { run: true });
+        await cli.parse('node bin convert photo.bmp photo.jpg --quality 85 --format jpg'.split(' '), { run: true });
         expect(result.input).toBe('photo.bmp');
         expect(result.output).toBe('photo.jpg');
         expect(result.quality).toBe(85);
         expect(typeof result.quality).toBe('number');
         expect(result.format).toBe('jpg');
     });
-    test('API client CLI preserving string IDs', () => {
+    test('API client CLI preserving string IDs', async () => {
         const cli = goke('apicli');
         let result = {};
         cli
@@ -464,22 +476,22 @@ describe('typical CLI usage examples', () => {
             result = { userId, ...options };
         });
         // userId "00123" should NOT be coerced to number 123
-        cli.parse(['node', 'bin', 'get-user', '00123', '--fields', '["name","email"]'], { run: true });
+        await cli.parse(['node', 'bin', 'get-user', '00123', '--fields', '["name","email"]'], { run: true });
         expect(result.userId).toBe('00123');
         expect(result.fields).toEqual(['name', 'email']);
     });
-    test('nullable option with union type', () => {
+    test('nullable option with union type', async () => {
         const cli = goke();
         cli.option('--timeout <timeout>', z.nullable(z.number()).describe('Timeout'));
-        const { options: opts1 } = cli.parse('node bin --timeout 5000'.split(' '));
+        const { options: opts1 } = await cli.parse('node bin --timeout 5000'.split(' '));
         expect(opts1.timeout).toBe(5000);
         // Empty string coerces to null for null type
-        const { options: opts2 } = cli.parse(['node', 'bin', '--timeout', '']);
+        const { options: opts2 } = await cli.parse(['node', 'bin', '--timeout', '']);
         expect(opts2.timeout).toBe(null);
     });
 });
 describe('regression: oracle-found issues', () => {
-    test('required option with schema still throws when value missing', () => {
+    test('required option with schema still throws when value missing', async () => {
         const cli = gokeTestable();
         let actionCalled = false;
         cli
@@ -487,99 +499,98 @@ describe('regression: oracle-found issues', () => {
             .option('--port <port>', z.number().describe('Port'))
             .action(() => { actionCalled = true; });
         // --port without a value should throw "value is missing"
-        expect(() => {
-            cli.parse('node bin serve --port'.split(' '), { run: true });
-        }).toThrow('value is missing');
+        await expect(cli.parse('node bin serve --port'.split(' '), { run: true }))
+            .rejects.toThrow('value is missing');
         expect(actionCalled).toBe(false);
     });
-    test('repeated flags with non-array schema throws', () => {
+    test('repeated flags with non-array schema throws', async () => {
         const cli = gokeTestable();
         cli.option('--tag <tag>', z.string().describe('Tags'));
-        expect(() => cli.parse('node bin --tag foo --tag bar'.split(' ')))
-            .toThrow('does not accept multiple values');
+        await expect(cli.parse('node bin --tag foo --tag bar'.split(' ')))
+            .rejects.toThrow('does not accept multiple values');
     });
-    test('repeated flags with number schema throws', () => {
+    test('repeated flags with number schema throws', async () => {
         const cli = gokeTestable();
         cli.option('--id <id>', z.number().describe('ID'));
-        expect(() => cli.parse('node bin --id 1 --id 2'.split(' ')))
-            .toThrow('does not accept multiple values');
+        await expect(cli.parse('node bin --id 1 --id 2'.split(' ')))
+            .rejects.toThrow('does not accept multiple values');
     });
-    test('repeated flags with array schema collects values', () => {
+    test('repeated flags with array schema collects values', async () => {
         const cli = goke();
         cli.option('--tag <tag>', z.array(z.string()).describe('Tags'));
-        const { options } = cli.parse('node bin --tag foo --tag bar'.split(' '));
+        const { options } = await cli.parse('node bin --tag foo --tag bar'.split(' '));
         expect(options.tag).toEqual(['foo', 'bar']);
     });
-    test('repeated flags with array+items schema coerces each element', () => {
+    test('repeated flags with array+items schema coerces each element', async () => {
         const cli = goke();
         cli.option('--id <id>', z.array(z.number()).describe('IDs'));
-        const { options } = cli.parse('node bin --id 1 --id 2 --id 3'.split(' '));
+        const { options } = await cli.parse('node bin --id 1 --id 2 --id 3'.split(' '));
         expect(options.id).toEqual([1, 2, 3]);
     });
-    test('single value with array schema wraps in array', () => {
+    test('single value with array schema wraps in array', async () => {
         const cli = goke();
         cli.option('--tag <tag>', z.array(z.string()).describe('Tags'));
-        const { options } = cli.parse('node bin --tag foo'.split(' '));
+        const { options } = await cli.parse('node bin --tag foo'.split(' '));
         expect(options.tag).toEqual(['foo']);
     });
-    test('single value with array+number items schema wraps and coerces', () => {
+    test('single value with array+number items schema wraps and coerces', async () => {
         const cli = goke();
         cli.option('--id <id>', z.array(z.number()).describe('IDs'));
-        const { options } = cli.parse('node bin --id 42'.split(' '));
+        const { options } = await cli.parse('node bin --id 42'.split(' '));
         expect(options.id).toEqual([42]);
     });
-    test('JSON array string with array schema parses correctly', () => {
+    test('JSON array string with array schema parses correctly', async () => {
         const cli = goke();
         cli.option('--ids <ids>', z.array(z.number()).describe('IDs'));
-        const { options } = cli.parse(['node', 'bin', '--ids', '[1,2,3]']);
+        const { options } = await cli.parse(['node', 'bin', '--ids', '[1,2,3]']);
         expect(options.ids).toEqual([1, 2, 3]);
     });
-    test('repeated flags without schema still produce array (no schema = no restriction)', () => {
+    test('repeated flags without schema still produce array (no schema = no restriction)', async () => {
         const cli = goke();
         cli.option('--tag <tag>', 'Tags');
-        const { options } = cli.parse('node bin --tag foo --tag bar'.split(' '));
+        const { options } = await cli.parse('node bin --tag foo --tag bar'.split(' '));
         expect(options.tag).toEqual(['foo', 'bar']);
     });
-    test('repeated optional value option without schema produces array', () => {
+    test('repeated optional value option without schema produces array', async () => {
         const cli = goke();
         cli.option('--tag [tag]', 'Tags');
-        const { options } = cli.parse('node bin --tag foo --tag bar'.split(' '));
+        const { options } = await cli.parse('node bin --tag foo --tag bar'.split(' '));
         expect(options.tag).toEqual(['foo', 'bar']);
     });
-    test('repeated alias option without schema produces array', () => {
+    test('repeated alias option without schema produces array', async () => {
         const cli = goke();
         cli.option('-t, --tag <tag>', 'Tags');
-        const { options } = cli.parse('node bin -t foo -t bar -t baz'.split(' '));
+        const { options } = await cli.parse('node bin -t foo -t bar -t baz'.split(' '));
         expect(options.tag).toEqual(['foo', 'bar', 'baz']);
         expect(options.t).toEqual(['foo', 'bar', 'baz']);
     });
-    test('repeated option without schema on subcommand produces array', () => {
+    test('repeated option without schema on subcommand produces array', async () => {
         const cli = goke();
         let result = {};
         cli
             .command('build', 'Build')
             .option('--exclude <path>', 'Paths to exclude')
             .action((options) => { result = options; });
-        cli.parse('node bin build --exclude node_modules --exclude dist --exclude .git'.split(' '), { run: true });
+        await cli.parse('node bin build --exclude node_modules --exclude dist --exclude .git'.split(' '), { run: true });
         expect(result.exclude).toEqual(['node_modules', 'dist', '.git']);
     });
-    test('single value without schema stays as string (not wrapped in array)', () => {
+    test('single value without schema stays as string (not wrapped in array)', async () => {
         const cli = goke();
         cli.option('--tag <tag>', 'Tags');
-        const { options } = cli.parse('node bin --tag foo'.split(' '));
+        const { options } = await cli.parse('node bin --tag foo'.split(' '));
         expect(options.tag).toBe('foo');
     });
-    test('const null coercion works', () => {
+    test('const null coercion works', async () => {
         expect(coerceBySchema('', { const: null }, 'val')).toBe(null);
     });
-    test('optional value option with schema returns undefined when no value given', () => {
+    test('optional value option with schema returns undefined when no value given', async () => {
         const cli = goke();
         cli.option('--count [count]', z.number().describe('Count'));
         // --count without value → schema expects number, none given → undefined
-        const { options } = cli.parse('node bin --count'.split(' '));
+        const { options } = await cli.parse('node bin --count'.split(' '));
         expect(options.count).toBe(undefined);
     });
-    test('optional value option without schema normalizes bare flag to empty string', () => {
+    test('optional value option without schema normalizes bare flag to empty string', async () => {
         const cli = goke();
         cli.option('--count [count]', 'Count');
         // Untyped optional-value flags uniformly expose `string | undefined`:
@@ -588,25 +599,25 @@ describe('regression: oracle-found issues', () => {
         //   - (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(' '));
+        const { options } = await cli.parse('node bin --count'.split(' '));
         expect(options.count).toBe('');
     });
-    test('optional value option with schema coerces when value given', () => {
+    test('optional value option with schema coerces when value given', async () => {
         const cli = goke();
         cli.option('--count [count]', z.number().describe('Count'));
-        const { options } = cli.parse('node bin --count 42'.split(' '));
+        const { options } = await cli.parse('node bin --count 42'.split(' '));
         expect(options.count).toBe(42);
     });
-    test('optional value option with schema default returns default when omitted', () => {
+    test('optional value option with schema default returns default when omitted', async () => {
         // `z.number().default(30)` has input `number | undefined` → output `number`,
         // so goke marks this option as effectively required and must surface the
         // default value at runtime when the flag is omitted.
         const cli = goke();
         cli.option('--limit [n]', z.number().default(30).describe('Max items'));
-        const { options } = cli.parse('node bin'.split(' '));
+        const { options } = await cli.parse('node bin'.split(' '));
         expect(options.limit).toBe(30);
     });
-    test('optional value option with schema default returns default when passed bare', () => {
+    test('optional value option with schema default returns default when passed bare', async () => {
         // Bare `--limit` is mri's "flag present, no value" sentinel. Without a
         // default, goke replaces it with `undefined`. With a default, goke must
         // preserve the preset default value instead of clobbering it, so the
@@ -614,16 +625,16 @@ describe('regression: oracle-found issues', () => {
         // holds for all three input states: omitted, bare, and with-value.
         const cli = goke();
         cli.option('--limit [n]', z.number().default(30).describe('Max items'));
-        const { options } = cli.parse('node bin --limit'.split(' '));
+        const { options } = await cli.parse('node bin --limit'.split(' '));
         expect(options.limit).toBe(30);
     });
-    test('optional value option with schema default coerces explicit value', () => {
+    test('optional value option with schema default coerces explicit value', async () => {
         const cli = goke();
         cli.option('--limit [n]', z.number().default(30).describe('Max items'));
-        const { options } = cli.parse('node bin --limit 5'.split(' '));
+        const { options } = await cli.parse('node bin --limit 5'.split(' '));
         expect(options.limit).toBe(5);
     });
-    test('multiple optional options with defaults all preserve their defaults', () => {
+    test('multiple optional options with defaults all preserve their defaults', async () => {
         // Regression test for the runtime-overwrite bug: when several schema-backed
         // optional flags have defaults, passing one bare should not clobber the
         // others, and the bare one should keep its own default.
@@ -632,200 +643,199 @@ describe('regression: oracle-found issues', () => {
             .option('--limit [n]', z.number().default(30))
             .option('--sort [mode]', z.enum(['asc', 'desc']).default('asc'))
             .option('--host [host]', z.string().default('localhost'));
-        const { options } = cli.parse('node bin --sort'.split(' '));
+        const { options } = await cli.parse('node bin --sort'.split(' '));
         expect(options.limit).toBe(30);
         expect(options.sort).toBe('asc');
         expect(options.host).toBe('localhost');
     });
-    test('alias + schema coercion works', () => {
+    test('alias + schema coercion works', async () => {
         const cli = goke();
         cli.option('-p, --port <port>', z.number().describe('Port'));
-        const { options } = cli.parse('node bin -p 3000'.split(' '));
+        const { options } = await cli.parse('node bin -p 3000'.split(' '));
         expect(options.port).toBe(3000);
         expect(options.p).toBe(3000);
     });
-    test('union type ["array", "null"] with repeated flags', () => {
+    test('union type ["array", "null"] with repeated flags', async () => {
         const cli = goke();
         cli.option('--tags <tags>', z.nullable(z.array(z.string())).describe('Tags'));
-        const { options } = cli.parse('node bin --tags foo --tags bar'.split(' '));
+        const { options } = await cli.parse('node bin --tags foo --tags bar'.split(' '));
         expect(options.tags).toEqual(['foo', 'bar']);
     });
 });
 describe('edge cases: schema + defaults interaction', () => {
-    test('default value from schema is used when option not passed', () => {
+    test('default value from schema is used when option not passed', async () => {
         const cli = goke();
         cli.option('--port [port]', z.number().default(8080).describe('Port'));
-        const { options } = cli.parse('node bin'.split(' '));
+        const { options } = await cli.parse('node bin'.split(' '));
         expect(options.port).toBe(8080);
     });
-    test('default value is used when option not passed, schema value when passed', () => {
+    test('default value is used when option not passed, schema value when passed', async () => {
         const cli = goke();
         cli.option('--port [port]', z.number().default(8080).describe('Port'));
-        const { options: opts1 } = cli.parse('node bin'.split(' '));
+        const { options: opts1 } = await cli.parse('node bin'.split(' '));
         expect(opts1.port).toBe(8080);
-        const { options: opts2 } = cli.parse('node bin --port 3000'.split(' '));
+        const { options: opts2 } = await cli.parse('node bin --port 3000'.split(' '));
         expect(opts2.port).toBe(3000);
     });
-    test('optional value + default + schema: three-way interaction', () => {
+    test('optional value + default + schema: three-way interaction', async () => {
         const cli = goke();
         cli.option('--count [count]', z.number().default(10).describe('Count'));
         // Not passed at all → default
-        const { options: opts1 } = cli.parse('node bin'.split(' '));
+        const { options: opts1 } = await cli.parse('node bin'.split(' '));
         expect(opts1.count).toBe(10);
         // Passed with value → coerced
-        const { options: opts2 } = cli.parse('node bin --count 42'.split(' '));
+        const { options: opts2 } = await cli.parse('node bin --count 42'.split(' '));
         expect(opts2.count).toBe(42);
         // Passed without value → default preserved. Before goke 6.7.0 this test
         // expected `undefined` because the bare-flag sentinel overwrote the
         // preset default. With the HasSchemaDefault type inference, the runtime
         // must keep the default so that the type-level promise ("options.count
         // is always a number") holds for all three input states.
-        const { options: opts3 } = cli.parse('node bin --count'.split(' '));
+        const { options: opts3 } = await cli.parse('node bin --count'.split(' '));
         expect(opts3.count).toBe(10);
     });
 });
 describe('edge cases: boolean flags + schema', () => {
-    test('boolean flag (no brackets) with number schema — mri returns boolean', () => {
+    test('boolean flag (no brackets) with number schema — mri returns boolean', async () => {
         const cli = goke();
         // This is a questionable usage: boolean flag + number schema
         // mri returns true/false for boolean flags, schema tries to coerce boolean→number
         cli.option('--verbose', z.number().describe('Verbose'));
-        const { options } = cli.parse('node bin --verbose'.split(' '));
+        const { options } = await cli.parse('node bin --verbose'.split(' '));
         // Boolean true → coerced to 1 by number schema
         expect(options.verbose).toBe(1);
     });
-    test('boolean string value with boolean schema on value option', () => {
+    test('boolean string value with boolean schema on value option', async () => {
         const cli = goke();
         cli.option('--flag <flag>', z.boolean().describe('A flag'));
-        const { options: opts1 } = cli.parse('node bin --flag true'.split(' '));
+        const { options: opts1 } = await cli.parse('node bin --flag true'.split(' '));
         expect(opts1.flag).toBe(true);
-        const { options: opts2 } = cli.parse('node bin --flag false'.split(' '));
+        const { options: opts2 } = await cli.parse('node bin --flag false'.split(' '));
         expect(opts2.flag).toBe(false);
     });
-    test('invalid boolean string with boolean schema throws', () => {
+    test('invalid boolean string with boolean schema throws', async () => {
         const cli = gokeTestable();
         cli.option('--flag <flag>', z.boolean().describe('A flag'));
-        expect(() => cli.parse('node bin --flag yes'.split(' ')))
-            .toThrow('expected true or false');
+        await expect(cli.parse('node bin --flag yes'.split(' ')))
+            .rejects.toThrow('expected true or false');
     });
 });
 describe('edge cases: dot-nested options + schema', () => {
-    test('dot-nested option with number schema coerces value', () => {
+    test('dot-nested option with number schema coerces value', async () => {
         const cli = goke();
         cli.option('--config.port <port>', z.number().describe('Port'));
-        const { options } = cli.parse('node bin --config.port 3000'.split(' '));
+        const { options } = await cli.parse('node bin --config.port 3000'.split(' '));
         expect(options.config).toEqual({ port: 3000 });
     });
-    test('dot-nested default uses nested object shape', () => {
+    test('dot-nested default uses nested object shape', async () => {
         const cli = goke();
         cli.option('--config.port [port]', z.number().default(8080).describe('Port'));
-        const { options } = cli.parse('node bin'.split(' '));
+        const { options } = await cli.parse('node bin'.split(' '));
         expect(options.config).toEqual({ port: 8080 });
     });
 });
 describe('edge cases: kebab-case + schema', () => {
-    test('kebab-case option coerced via schema and accessible as camelCase', () => {
+    test('kebab-case option coerced via schema and accessible as camelCase', async () => {
         const cli = goke();
         cli.option('--max-retries <count>', z.number().describe('Max retries'));
-        const { options } = cli.parse('node bin --max-retries 5'.split(' '));
+        const { options } = await cli.parse('node bin --max-retries 5'.split(' '));
         expect(options.maxRetries).toBe(5);
         expect(typeof options.maxRetries).toBe('number');
     });
 });
 describe('edge cases: empty string values', () => {
-    test('empty string with string schema stays empty string', () => {
+    test('empty string with string schema stays empty string', async () => {
         const cli = goke();
         cli.option('--name <name>', z.string().describe('Name'));
-        const { options } = cli.parse(['node', 'bin', '--name', '']);
+        const { options } = await cli.parse(['node', 'bin', '--name', '']);
         expect(options.name).toBe('');
     });
-    test('empty string with number schema throws', () => {
+    test('empty string with number schema throws', async () => {
         const cli = gokeTestable();
         cli.option('--port <port>', z.number().describe('Port'));
-        expect(() => cli.parse(['node', 'bin', '--port', '']))
-            .toThrow('expected number, got empty string');
+        await expect(cli.parse(['node', 'bin', '--port', '']))
+            .rejects.toThrow('expected number, got empty string');
     });
-    test('empty string with nullable number schema returns null', () => {
+    test('empty string with nullable number schema returns null', async () => {
         const cli = goke();
         cli.option('--timeout <timeout>', z.nullable(z.number()).describe('Timeout'));
-        const { options } = cli.parse(['node', 'bin', '--timeout', '']);
+        const { options } = await cli.parse(['node', 'bin', '--timeout', '']);
         expect(options.timeout).toBe(null);
     });
 });
 describe('edge cases: global options with schema in subcommands', () => {
-    test('global option schema applies to subcommand parsing', () => {
+    test('global option schema applies to subcommand parsing', async () => {
         const cli = goke();
         let result = {};
         cli.option('--port <port>', z.number().describe('Port'));
         cli
             .command('serve', 'Start server')
             .action((options) => { result = options; });
-        cli.parse('node bin serve --port 3000'.split(' '), { run: true });
+        await cli.parse('node bin serve --port 3000'.split(' '), { run: true });
         expect(result.port).toBe(3000);
         expect(typeof result.port).toBe('number');
     });
 });
 describe('edge cases: short alias + schema', () => {
-    test('short alias repeated with array schema', () => {
+    test('short alias repeated with array schema', async () => {
         const cli = goke();
         cli.option('-t, --tag <tag>', z.array(z.string()).describe('Tags'));
-        const { options } = cli.parse('node bin -t foo -t bar'.split(' '));
+        const { options } = await cli.parse('node bin -t foo -t bar'.split(' '));
         expect(options.tag).toEqual(['foo', 'bar']);
         expect(options.t).toEqual(['foo', 'bar']);
     });
-    test('short alias single value with array schema wraps', () => {
+    test('short alias single value with array schema wraps', async () => {
         const cli = goke();
         cli.option('-t, --tag <tag>', z.array(z.string()).describe('Tags'));
-        const { options } = cli.parse('node bin -t foo'.split(' '));
+        const { options } = await cli.parse('node bin -t foo'.split(' '));
         expect(options.tag).toEqual(['foo']);
     });
-    test('short alias with number schema coerces', () => {
+    test('short alias with number schema coerces', async () => {
         const cli = goke();
         cli.option('-p, --port <port>', z.number().describe('Port'));
-        const { options } = cli.parse('node bin -p 8080'.split(' '));
+        const { options } = await cli.parse('node bin -p 8080'.split(' '));
         expect(options.port).toBe(8080);
         expect(options.p).toBe(8080);
     });
-    test('short alias repeated with non-array schema throws', () => {
+    test('short alias repeated with non-array schema throws', async () => {
         const cli = gokeTestable();
         cli.option('-p, --port <port>', z.number().describe('Port'));
-        expect(() => cli.parse('node bin -p 3000 -p 4000'.split(' ')))
-            .toThrow('does not accept multiple values');
+        await expect(cli.parse('node bin -p 3000 -p 4000'.split(' ')))
+            .rejects.toThrow('does not accept multiple values');
     });
 });
-test('throw on unknown options', () => {
+test('throw on unknown options', async () => {
     const cli = gokeTestable();
     cli
         .command('build [entry]', 'Build your app')
         .option('--foo-bar', 'foo bar')
         .option('--aB', 'ab')
         .action(() => { });
-    expect(() => {
-        cli.parse(`node bin build app.js --fooBar --a-b --xx`.split(' '));
-    }).toThrowError('Unknown option `--xx`');
+    await expect(cli.parse(`node bin build app.js --fooBar --a-b --xx`.split(' ')))
+        .rejects.toThrowError('Unknown option `--xx`');
 });
 describe('space-separated subcommands', () => {
-    test('basic subcommand matching', () => {
+    test('basic subcommand matching', async () => {
         const cli = goke();
         let matched = '';
         cli.command('mcp login', 'Login to MCP').action(() => {
             matched = 'mcp login';
         });
-        cli.parse(['node', 'bin', 'mcp', 'login'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', 'login'], { run: true });
         expect(matched).toBe('mcp login');
         expect(cli.matchedCommandName).toBe('mcp login');
     });
-    test('subcommand with positional args', () => {
+    test('subcommand with positional args', async () => {
         const cli = goke();
         let receivedId = '';
         cli.command('mcp getNodeXml <id>', 'Get XML for a node').action((id) => {
             receivedId = id;
         });
-        cli.parse(['node', 'bin', 'mcp', 'getNodeXml', '123'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', 'getNodeXml', '123'], { run: true });
         expect(receivedId).toBe('123');
         expect(cli.matchedCommandName).toBe('mcp getNodeXml');
     });
-    test('subcommand with options', () => {
+    test('subcommand with options', async () => {
         const cli = goke();
         let result = {};
         cli
@@ -834,12 +844,12 @@ describe('space-separated subcommands', () => {
             .action((id, options) => {
             result = { id, format: options.format };
         });
-        cli.parse(['node', 'bin', 'mcp', 'export', 'abc', '--format', 'json'], {
+        await cli.parse(['node', 'bin', 'mcp', 'export', 'abc', '--format', 'json'], {
             run: true,
         });
         expect(result).toEqual({ id: 'abc', format: 'json' });
     });
-    test('greedy matching - longer commands match first', () => {
+    test('greedy matching - longer commands match first', async () => {
         const cli = goke();
         let matched = '';
         cli.command('mcp', 'MCP base command').action(() => {
@@ -848,30 +858,30 @@ describe('space-separated subcommands', () => {
         cli.command('mcp login', 'Login to MCP').action(() => {
             matched = 'mcp login';
         });
-        cli.parse(['node', 'bin', 'mcp', 'login'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', 'login'], { run: true });
         expect(matched).toBe('mcp login');
     });
-    test('three-level subcommand', () => {
+    test('three-level subcommand', async () => {
         const cli = goke();
         let matched = '';
         cli.command('git remote add', 'Add a remote').action(() => {
             matched = 'git remote add';
         });
-        cli.parse(['node', 'bin', 'git', 'remote', 'add'], { run: true });
+        await cli.parse(['node', 'bin', 'git', 'remote', 'add'], { run: true });
         expect(matched).toBe('git remote add');
         expect(cli.matchedCommandName).toBe('git remote add');
     });
-    test('single-word commands still work (backward compatibility)', () => {
+    test('single-word commands still work (backward compatibility)', async () => {
         const cli = goke();
         let matched = '';
         cli.command('build', 'Build the project').action(() => {
             matched = 'build';
         });
-        cli.parse(['node', 'bin', 'build'], { run: true });
+        await cli.parse(['node', 'bin', 'build'], { run: true });
         expect(matched).toBe('build');
         expect(cli.matchedCommandName).toBe('build');
     });
-    test('subcommand does not match when args are insufficient', () => {
+    test('subcommand does not match when args are insufficient', async () => {
         const cli = goke();
         let matched = '';
         cli.command('mcp login', 'Login to MCP').action(() => {
@@ -880,10 +890,10 @@ describe('space-separated subcommands', () => {
         cli.command('mcp', 'MCP base').action(() => {
             matched = 'mcp base';
         });
-        cli.parse(['node', 'bin', 'mcp'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp'], { run: true });
         expect(matched).toBe('mcp base');
     });
-    test('default command should not match if args are prefix of another command', () => {
+    test('default command should not match if args are prefix of another command', async () => {
         const cli = goke();
         let matched = '';
         cli.command('mcp login', 'Login to MCP').action(() => {
@@ -892,11 +902,11 @@ describe('space-separated subcommands', () => {
         cli.command('', 'Default command').action(() => {
             matched = 'default';
         });
-        cli.parse(['node', 'bin', 'mcp'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp'], { run: true });
         expect(matched).toBe('');
         expect(cli.matchedCommand).toBeUndefined();
     });
-    test('default command should match when args do not prefix any command', () => {
+    test('default command should match when args do not prefix any command', async () => {
         const cli = goke();
         let matched = '';
         let receivedArg = '';
@@ -907,11 +917,11 @@ describe('space-separated subcommands', () => {
             matched = 'default';
             receivedArg = file;
         });
-        cli.parse(['node', 'bin', 'foo'], { run: true });
+        await cli.parse(['node', 'bin', 'foo'], { run: true });
         expect(matched).toBe('default');
         expect(receivedArg).toBe('foo');
     });
-    test('help output with subcommands', () => {
+    test('help output with subcommands', async () => {
         let output = '';
         const cli = goke('mycli', {
             stdout: { write(data) { output += data; } },
@@ -924,7 +934,7 @@ describe('space-separated subcommands', () => {
         cli.command('build', 'Build the project').option('--watch', 'Watch mode');
         cli.help();
         // parse with --help triggers outputHelp() internally, which writes to our captured stdout
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stripAnsi(output)).toMatchInlineSnapshot(`
       "mycli
 
@@ -959,7 +969,7 @@ describe('space-separated subcommands', () => {
       "
     `);
     });
-    test('unknown subcommand shows filtered help for prefix', () => {
+    test('unknown subcommand shows filtered help for prefix', async () => {
         let output = '';
         const cli = goke('mycli', {
             stdout: { write(data) { output += data; } },
@@ -970,7 +980,7 @@ describe('space-separated subcommands', () => {
         cli.command('build', 'Build project');
         cli.help();
         // User types "mcp nonexistent" - should show help for mcp commands
-        cli.parse(['node', 'bin', 'mcp', 'nonexistent'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', 'nonexistent'], { run: true });
         expect(cli.matchedCommand).toBeUndefined();
         const normalizedOutput = stripAnsi(output);
         expect(normalizedOutput).toContain('Unknown command: mcp nonexistent');
@@ -980,7 +990,7 @@ describe('space-separated subcommands', () => {
         expect(normalizedOutput).toContain('mcp status');
         expect(normalizedOutput).not.toContain('build');
     });
-    test('unknown command without prefix does not show filtered help', () => {
+    test('unknown command without prefix does not show filtered help', async () => {
         let output = '';
         const cli = goke('mycli', {
             stdout: { write(data) { output += data; } },
@@ -989,11 +999,11 @@ describe('space-separated subcommands', () => {
         cli.command('build', 'Build project');
         cli.help();
         // User types "foo" - no commands start with "foo"
-        cli.parse(['node', 'bin', 'foo'], { run: true });
+        await cli.parse(['node', 'bin', 'foo'], { run: true });
         // Should not show filtered help since "foo" is not a prefix of any command
         expect(stripAnsi(output)).not.toContain('Available "foo" commands');
     });
-    test('unknown command without prefix outputs root help', () => {
+    test('unknown command without prefix outputs root help', async () => {
         let output = '';
         const cli = goke('mycli', {
             stdout: { write(data) { output += data; } },
@@ -1002,26 +1012,80 @@ describe('space-separated subcommands', () => {
         cli.command('build', 'Build project');
         cli.help();
         // User types an unknown command that does not match any prefix group
-        cli.parse(['node', 'bin', 'something'], { run: true });
+        await cli.parse(['node', 'bin', 'something'], { run: true });
         expect(cli.matchedCommand).toBeUndefined();
         expect(stripAnsi(output)).toContain('Usage:');
         expect(stripAnsi(output)).toContain('$ mycli <command> [options]');
         expect(stripAnsi(output)).toContain('mcp login');
         expect(stripAnsi(output)).toContain('build');
     });
-    test('no args without default command outputs root help', () => {
+    test('no args without default command outputs root help', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('mcp login', 'Login to MCP');
         cli.command('build', 'Build project');
         cli.help();
-        cli.parse(['node', 'bin'], { run: true });
+        await cli.parse(['node', 'bin'], { run: true });
         expect(stdout.text).toContain('Usage:');
         expect(stdout.text).toContain('$ mycli <command> [options]');
         expect(stdout.text).toContain('mcp login');
         expect(stdout.text).toContain('build');
     });
-    test('prefix --help shows filtered help for matching command group', () => {
+    test('default command with no args rejects unknown positional args', async () => {
+        const stdout = createTestOutputStream();
+        let defaultRan = false;
+        let unknownFired = false;
+        const cli = gokeTestable('playwriter', { stdout });
+        cli.command('', 'Start the MCP server').action(async () => { defaultRan = true; });
+        cli.command('session new', 'Create session').action(() => { });
+        cli.help();
+        cli.on('command:*', () => { unknownFired = true; });
+        await cli.parse(['node', 'bin', 'run'], { run: true });
+        expect(defaultRan).toBe(false);
+        expect(unknownFired).toBe(true);
+        expect(cli.matchedCommand).toBeUndefined();
+    });
+    test('default command with no args still runs when no args passed', async () => {
+        let defaultRan = false;
+        const cli = gokeTestable('playwriter');
+        cli.command('', 'Start the MCP server').action(async () => { defaultRan = true; });
+        cli.command('session new', 'Create session').action(() => { });
+        await cli.parse(['node', 'bin'], { run: true });
+        expect(defaultRan).toBe(true);
+    });
+    test('default command with no args still works with -- separator', async () => {
+        let defaultRan = false;
+        let receivedOptions = null;
+        const cli = gokeTestable('playwriter');
+        cli.command('', 'Start the MCP server').action(async (options) => {
+            defaultRan = true;
+            receivedOptions = options;
+        });
+        await cli.parse(['node', 'bin', '--', 'extra', 'args'], { run: true });
+        expect(defaultRan).toBe(true);
+        expect(receivedOptions['--']).toEqual(['extra', 'args']);
+    });
+    test('default command WITH positional args still accepts args', async () => {
+        let receivedScript;
+        const cli = gokeTestable('runner');
+        cli.command('[script]', 'Run a script').action(async (script) => {
+            receivedScript = script;
+        });
+        await cli.parse(['node', 'bin', 'deploy'], { run: true });
+        expect(receivedScript).toBe('deploy');
+    });
+    test('default command rejects unknown nonexistent command', async () => {
+        let defaultRan = false;
+        let unknownFired = false;
+        const cli = gokeTestable('mycli');
+        cli.command('', 'Default').action(async () => { defaultRan = true; });
+        cli.command('build', 'Build').action(() => { });
+        cli.on('command:*', () => { unknownFired = true; });
+        await cli.parse(['node', 'bin', 'nonexistent'], { run: true });
+        expect(defaultRan).toBe(false);
+        expect(unknownFired).toBe(true);
+    });
+    test('prefix --help shows filtered help for matching command group', async () => {
         let output = '';
         const cli = goke('mycli', {
             stdout: { write(data) { output += data; } },
@@ -1031,7 +1095,7 @@ describe('space-separated subcommands', () => {
         cli.command('mcp status', 'Show status');
         cli.command('build', 'Build project');
         cli.help();
-        cli.parse(['node', 'bin', 'mcp', '--help'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', '--help'], { run: true });
         const normalizedOutput = stripAnsi(output);
         expect(normalizedOutput).toMatchInlineSnapshot(`
       "mycli
@@ -1048,7 +1112,7 @@ describe('space-separated subcommands', () => {
     });
 });
 describe('many commands with root command (empty string)', () => {
-    test('root command runs when no subcommand given', () => {
+    test('root command runs when no subcommand given', async () => {
         const cli = goke('deploy');
         let matched = '';
         cli.command('', 'Deploy the current project').action(() => {
@@ -1060,10 +1124,10 @@ describe('many commands with root command (empty string)', () => {
         cli.command('login', 'Authenticate').action(() => {
             matched = 'login';
         });
-        cli.parse(['node', 'bin'], { run: true });
+        await cli.parse(['node', 'bin'], { run: true });
         expect(matched).toBe('root');
     });
-    test('root command receives options', () => {
+    test('root command receives options', async () => {
         const cli = goke('deploy');
         let result = {};
         cli
@@ -1075,11 +1139,11 @@ describe('many commands with root command (empty string)', () => {
         });
         cli.command('init', 'Initialize project').action(() => { });
         cli.command('login', 'Authenticate').action(() => { });
-        cli.parse(['node', 'bin', '--env', 'staging', '--dry-run'], { run: true });
+        await cli.parse(['node', 'bin', '--env', 'staging', '--dry-run'], { run: true });
         expect(result.env).toBe('staging');
         expect(result.dryRun).toBe(true);
     });
-    test('root command uses defaults when no options given', () => {
+    test('root command uses defaults when no options given', async () => {
         const cli = goke('deploy');
         let result = {};
         cli
@@ -1089,10 +1153,10 @@ describe('many commands with root command (empty string)', () => {
             result = options;
         });
         cli.command('init', 'Initialize project').action(() => { });
-        cli.parse(['node', 'bin'], { run: true });
+        await cli.parse(['node', 'bin'], { run: true });
         expect(result.env).toBe('production');
     });
-    test('subcommands take priority over root command', () => {
+    test('subcommands take priority over root command', async () => {
         const cli = goke('deploy');
         let matched = '';
         cli.command('', 'Deploy the current project').action(() => {
@@ -1107,10 +1171,10 @@ describe('many commands with root command (empty string)', () => {
         cli.command('status', 'Show status').action(() => {
             matched = 'status';
         });
-        cli.parse(['node', 'bin', 'status'], { run: true });
+        await cli.parse(['node', 'bin', 'status'], { run: true });
         expect(matched).toBe('status');
     });
-    test('subcommand with args works alongside root command', () => {
+    test('subcommand with args works alongside root command', async () => {
         const cli = goke('deploy');
         let rootCalled = false;
         let logsResult = {};
@@ -1124,13 +1188,13 @@ describe('many commands with root command (empty string)', () => {
             .action((deploymentId, options) => {
             logsResult = { deploymentId, ...options };
         });
-        cli.parse(['node', 'bin', 'logs', 'abc123', '--follow', '--lines', '50'], { run: true });
+        await cli.parse(['node', 'bin', 'logs', 'abc123', '--follow', '--lines', '50'], { run: true });
         expect(rootCalled).toBe(false);
         expect(logsResult.deploymentId).toBe('abc123');
         expect(logsResult.follow).toBe(true);
         expect(logsResult.lines).toBe(50);
     });
-    test('help shows root and all subcommands', () => {
+    test('help shows root and all subcommands', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('deploy', { stdout });
         cli
@@ -1142,7 +1206,7 @@ describe('many commands with root command (empty string)', () => {
         cli.command('status', 'Show deployment status');
         cli.command('logs <deploymentId>', 'Stream logs for a deployment');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toContain('init');
         expect(stdout.text).toContain('login');
         expect(stdout.text).toContain('logout');
@@ -1151,7 +1215,7 @@ describe('many commands with root command (empty string)', () => {
         expect(stdout.text).toContain('Initialize a new project');
         expect(stdout.text).toContain('Stream logs for a deployment');
     });
-    test('root help with many commands renders examples section after options', () => {
+    test('root help with many commands renders examples section after options', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('deploy', { stdout });
         cli
@@ -1166,7 +1230,7 @@ describe('many commands with root command (empty string)', () => {
         cli.command('status', 'Show deployment status');
         cli.command('logs <deploymentId>', 'Stream logs for a deployment');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toMatchInlineSnapshot(`
       "deploy
 
@@ -1206,7 +1270,7 @@ describe('many commands with root command (empty string)', () => {
       "
     `);
     });
-    test('subcommand help renders command examples at the end', () => {
+    test('subcommand help renders command examples at the end', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('deploy', { stdout, columns: 80 });
         cli.command('', 'Deploy the current project');
@@ -1221,7 +1285,7 @@ describe('many commands with root command (empty string)', () => {
             .example('# Keep following new log lines')
             .example('deploy logs dep_123 --follow');
         cli.help();
-        cli.parse(['node', 'bin', 'logs', '--help'], { run: false });
+        await cli.parse(['node', 'bin', 'logs', '--help'], { run: false });
         expect(stdout.text).toMatchInlineSnapshot(`
       "deploy
 
@@ -1248,7 +1312,7 @@ describe('many commands with root command (empty string)', () => {
       "
     `);
     });
-    test('root help labels default command with cli name and does not duplicate global options', () => {
+    test('root help labels default command with cli name and does not duplicate global options', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('deploy', { stdout });
         cli.option('--env <env>', 'Target environment');
@@ -1258,7 +1322,7 @@ describe('many commands with root command (empty string)', () => {
             .option('--dry-run', 'Preview without deploying');
         cli.command('status', 'Show deployment status');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toMatchInlineSnapshot(`
       "deploy
 
@@ -1281,7 +1345,7 @@ describe('many commands with root command (empty string)', () => {
       "
     `);
     });
-    test('root help wraps long command descriptions snapshot', () => {
+    test('root help wraps long command descriptions snapshot', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout, columns: 56 });
         cli.command('notion-search', 'Perform a semantic search over Notion workspace content and connected integrations with advanced filtering options, date filters, and creator filters.')
@@ -1289,7 +1353,7 @@ describe('many commands with root command (empty string)', () => {
             .option('--limit [limit]', z.number().default(10).describe('Maximum number of results to return'));
         cli.command('notion-fetch', 'Retrieve a Notion page or database by URL or ID and render the result in enhanced markdown format for terminal output.').option('--id <id>', 'Notion URL or UUID to fetch');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toMatchInlineSnapshot(`
       "mycli
 
@@ -1324,7 +1388,7 @@ describe('many commands with root command (empty string)', () => {
       "
     `);
     });
-    test('root help aligns command descriptions with mixed command lengths', () => {
+    test('root help aligns command descriptions with mixed command lengths', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('gtui', { stdout, columns: 120 });
         cli.command('auth login', 'Authenticate with Google (opens browser)');
@@ -1332,7 +1396,7 @@ describe('many commands with root command (empty string)', () => {
         cli.command('mail list', 'List email threads').option('--folder [folder]', 'Folder to list');
         cli.command('attachment get <messageId> <attachmentId>', 'Download an attachment');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toMatchInlineSnapshot(`
       "gtui
 
@@ -1363,16 +1427,16 @@ describe('many commands with root command (empty string)', () => {
       "
     `);
     });
-    test('root help wraps all multi-line description lines', () => {
+    test('root help wraps all multi-line description lines', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout, columns: 64 });
         cli.command('notion-create', 'Create a new page.\n  {"title":"Example"}\n  {"done":true}');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toContain('{"title":"Example"}');
         expect(stdout.text).toContain('{"done":true}');
     });
-    test('root help snapshot when columns is undefined (no wrapping fallback)', () => {
+    test('root help snapshot when columns is undefined (no wrapping fallback)', async () => {
         const stdout = createTestOutputStream();
         const originalColumns = process.stdout.columns;
         Object.defineProperty(process.stdout, 'columns', {
@@ -1385,7 +1449,7 @@ describe('many commands with root command (empty string)', () => {
                 .option('--query <query>', 'Natural language query text to search for')
                 .option('--limit [limit]', z.number().default(10).describe('Maximum number of results to return'));
             cli.help();
-            cli.parse(['node', 'bin', '--help'], { run: false });
+            await cli.parse(['node', 'bin', '--help'], { run: false });
             expect(stdout.text).toMatchInlineSnapshot(`
         "mycli
 
@@ -1413,7 +1477,7 @@ describe('many commands with root command (empty string)', () => {
             });
         }
     });
-    test('many subcommands all resolve correctly', () => {
+    test('many subcommands all resolve correctly', async () => {
         const cli = goke('deploy');
         let matched = '';
         cli.command('', 'Root').action(() => { matched = 'root'; });
@@ -1425,63 +1489,63 @@ describe('many commands with root command (empty string)', () => {
         cli.command('rollback <id>', 'Rollback').action(() => { matched = 'rollback'; });
         cli.command('config set <key> <value>', 'Set config').action(() => { matched = 'config set'; });
         // Test each command resolves to the right one
-        cli.parse(['node', 'bin'], { run: true });
+        await cli.parse(['node', 'bin'], { run: true });
         expect(matched).toBe('root');
         matched = '';
-        cli.parse(['node', 'bin', 'init'], { run: true });
+        await cli.parse(['node', 'bin', 'init'], { run: true });
         expect(matched).toBe('init');
         matched = '';
-        cli.parse(['node', 'bin', 'login'], { run: true });
+        await cli.parse(['node', 'bin', 'login'], { run: true });
         expect(matched).toBe('login');
         matched = '';
-        cli.parse(['node', 'bin', 'logout'], { run: true });
+        await cli.parse(['node', 'bin', 'logout'], { run: true });
         expect(matched).toBe('logout');
         matched = '';
-        cli.parse(['node', 'bin', 'status'], { run: true });
+        await cli.parse(['node', 'bin', 'status'], { run: true });
         expect(matched).toBe('status');
         matched = '';
-        cli.parse(['node', 'bin', 'logs', 'dep-123'], { run: true });
+        await cli.parse(['node', 'bin', 'logs', 'dep-123'], { run: true });
         expect(matched).toBe('logs');
         matched = '';
-        cli.parse(['node', 'bin', 'rollback', 'dep-456'], { run: true });
+        await cli.parse(['node', 'bin', 'rollback', 'dep-456'], { run: true });
         expect(matched).toBe('rollback');
         matched = '';
-        cli.parse(['node', 'bin', 'config', 'set', 'region', 'us-east-1'], { run: true });
+        await cli.parse(['node', 'bin', 'config', 'set', 'region', 'us-east-1'], { run: true });
         expect(matched).toBe('config set');
     });
 });
 describe('stdout/stderr/argv injection', () => {
-    test('stdout captures help output', () => {
+    test('stdout captures help output', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('serve', 'Start server');
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         cli.outputHelp();
         expect(stdout.text).toContain('mycli');
         expect(stdout.text).toContain('serve');
         expect(stdout.text).toContain('Start server');
     });
-    test('stdout captures version output', () => {
+    test('stdout captures version output', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.version('1.2.3');
-        cli.parse(['node', 'bin', '--version'], { run: false });
+        await cli.parse(['node', 'bin', '--version'], { run: false });
         cli.outputVersion();
         expect(stdout.text).toContain('mycli/1.2.3');
     });
-    test('stdout captures prefix help for unknown subcommands', () => {
+    test('stdout captures prefix help for unknown subcommands', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('mcp login', 'Login to MCP');
         cli.command('mcp logout', 'Logout from MCP');
         cli.help();
-        cli.parse(['node', 'bin', 'mcp', 'nonexistent'], { run: true });
+        await cli.parse(['node', 'bin', 'mcp', 'nonexistent'], { run: true });
         expect(stdout.text).toContain('Unknown command: mcp nonexistent');
         expect(stdout.text).toContain('mcp login');
         expect(stdout.text).toContain('mcp logout');
     });
-    test('stderr is separate from stdout', () => {
+    test('stderr is separate from stdout', async () => {
         const stdout = createTestOutputStream();
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stdout, stderr });
@@ -1490,7 +1554,7 @@ describe('stdout/stderr/argv injection', () => {
         expect(stdout.text).toBe('hello stdout\n');
         expect(stderr.text).toBe('hello stderr\n');
     });
-    test('argv option is used as default in parse()', () => {
+    test('argv option is used as default in parse()', async () => {
         const cli = goke('mycli', {
             argv: ['node', 'bin', 'serve', '--port', '3000'],
         });
@@ -1500,10 +1564,10 @@ describe('stdout/stderr/argv injection', () => {
             .option('--port <port>', z.number().describe('Port'))
             .action((options) => { result = options; });
         // parse() without args uses the injected argv
-        cli.parse();
+        await cli.parse();
         expect(result.port).toBe(3000);
     });
-    test('parse(customArgv) overrides injected argv', () => {
+    test('parse(customArgv) overrides injected argv', async () => {
         const cli = goke('mycli', {
             argv: ['node', 'bin', 'serve', '--port', '3000'],
         });
@@ -1513,16 +1577,16 @@ describe('stdout/stderr/argv injection', () => {
             .option('--port <port>', z.number().describe('Port'))
             .action((options) => { result = options; });
         // Explicit argv overrides the default
-        cli.parse(['node', 'bin', 'serve', '--port', '8080']);
+        await cli.parse(['node', 'bin', 'serve', '--port', '8080']);
         expect(result.port).toBe(8080);
     });
-    test('default behavior without options uses process.stdout', () => {
+    test('default behavior without options uses process.stdout', async () => {
         const cli = goke('mycli');
         // stdout/stderr should be process.stdout/process.stderr by default
         expect(cli.stdout).toBe(process.stdout);
         expect(cli.stderr).toBe(process.stderr);
     });
-    test('createConsole routes log to stdout and error to stderr', () => {
+    test('createConsole routes log to stdout and error to stderr', async () => {
         const stdout = createTestOutputStream();
         const stderr = createTestOutputStream();
         const con = createConsole(stdout, stderr);
@@ -1531,7 +1595,7 @@ describe('stdout/stderr/argv injection', () => {
         expect(stdout.text).toBe('msg1 msg2\n');
         expect(stderr.text).toBe('err1 err2\n');
     });
-    test('createConsole log with no args writes empty line', () => {
+    test('createConsole log with no args writes empty line', async () => {
         const stdout = createTestOutputStream();
         const stderr = createTestOutputStream();
         const con = createConsole(stdout, stderr);
@@ -1540,27 +1604,27 @@ describe('stdout/stderr/argv injection', () => {
     });
 });
 describe('schema description and default extraction', () => {
-    test('description is extracted from schema and shown in help', () => {
+    test('description is extracted from schema and shown in help', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli
             .command('serve', 'Start server')
             .option('--port <port>', z.number().describe('Port to listen on'));
         cli.help();
-        cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
+        await cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
         expect(stdout.text).toContain('Port to listen on');
     });
-    test('default is extracted from schema and shown in help', () => {
+    test('default is extracted from schema and shown in help', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli
             .command('serve', 'Start server')
             .option('--port [port]', z.number().default(3000).describe('Port'));
         cli.help();
-        cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
+        await cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
         expect(stdout.text).toContain('(default: 3000)');
     });
-    test('deprecated options are hidden from help output', () => {
+    test('deprecated options are hidden from help output', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli
@@ -1568,7 +1632,7 @@ describe('schema description and default extraction', () => {
             .option('--old <value>', z.string().meta({ deprecated: true, description: 'Old option' }))
             .option('--new <value>', z.string().describe('Normal option'));
         cli.help();
-        cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
+        await cli.parse(['node', 'bin', 'serve', '--help'], { run: false });
         // Normal option should be visible
         expect(stdout.text).toContain('--new');
         expect(stdout.text).toContain('Normal option');
@@ -1576,42 +1640,42 @@ describe('schema description and default extraction', () => {
         expect(stdout.text).not.toContain('--old');
         expect(stdout.text).not.toContain('Old option');
     });
-    test('deprecated option still works for parsing (just hidden from help)', () => {
+    test('deprecated option still works for parsing (just hidden from help)', async () => {
         const cli = gokeTestable('mycli');
         let result = {};
         cli
             .command('serve', 'Start server')
             .option('--old <value>', z.string().meta({ deprecated: true, description: 'Old option' }))
             .action((options) => { result = options; });
-        cli.parse(['node', 'bin', 'serve', '--old', 'legacy-value']);
+        await cli.parse(['node', 'bin', 'serve', '--old', 'legacy-value']);
         // Deprecated option should still be parsed and usable
         expect(result.old).toBe('legacy-value');
     });
-    test('deprecated options hidden from global help', () => {
+    test('deprecated options hidden from global help', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.option('--legacy [value]', z.string().meta({ deprecated: true, description: 'Deprecated global' }));
         cli.option('--current [value]', z.string().describe('Current option'));
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toContain('--current');
         expect(stdout.text).toContain('Current option');
         expect(stdout.text).not.toContain('--legacy');
         expect(stdout.text).not.toContain('Deprecated global');
     });
-    test('hidden commands are not shown in help output', () => {
+    test('hidden commands are not shown in help output', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('visible', 'A visible command');
         cli.command('secret', 'A hidden command').hidden();
         cli.help();
-        cli.parse(['node', 'bin', '--help'], { run: false });
+        await cli.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toContain('visible');
         expect(stdout.text).toContain('A visible command');
         expect(stdout.text).not.toContain('secret');
         expect(stdout.text).not.toContain('A hidden command');
     });
-    test('hidden command still parses and runs', () => {
+    test('hidden command still parses and runs', async () => {
         const cli = gokeTestable('mycli');
         let result = {};
         cli
@@ -1619,19 +1683,19 @@ describe('schema description and default extraction', () => {
             .hidden()
             .option('--value <v>', z.string().describe('some value'))
             .action((options) => { result = options; });
-        cli.parse(['node', 'bin', 'secret', '--value', 'hello']);
+        await cli.parse(['node', 'bin', 'secret', '--value', 'hello']);
         expect(result.value).toBe('hello');
     });
 });
 describe('helpText()', () => {
-    test('returns help string without printing', () => {
+    test('returns help string without printing', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('serve', 'Start server');
         cli.option('--port <port>', 'Port number');
         cli.help();
         // parse a known command so help is not auto-triggered
-        cli.parse(['node', 'bin', 'serve'], { run: false });
+        await cli.parse(['node', 'bin', 'serve'], { run: false });
         // reset stdout after parse
         stdout.lines.length = 0;
         const text = stripAnsi(cli.helpText());
@@ -1642,14 +1706,14 @@ describe('helpText()', () => {
         // helpText() does not print to stdout
         expect(stdout.text).toBe('');
     });
-    test('returns same content as outputHelp', () => {
+    test('returns same content as outputHelp', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         cli.command('build', 'Build project');
         cli.option('--watch [watch]', 'Watch mode');
         cli.help();
         // parse a known command so help is not auto-triggered
-        cli.parse(['node', 'bin', 'build'], { run: false });
+        await cli.parse(['node', 'bin', 'build'], { run: false });
         // reset stdout after parse
         stdout.lines.length = 0;
         const helpTextResult = stripAnsi(cli.helpText());
@@ -1658,18 +1722,18 @@ describe('helpText()', () => {
         const outputHelpResult = stdout.text.replace(/\n$/, '');
         expect(helpTextResult).toBe(outputHelpResult);
     });
-    test('returns subcommand help when command is matched', () => {
+    test('returns subcommand help when command is matched', async () => {
         const cli = goke('mycli');
         cli.command('deploy <env>', 'Deploy to environment')
             .option('--force', 'Force deploy');
         cli.help();
-        cli.parse(['node', 'bin', 'deploy', '--help'], { run: false });
+        await cli.parse(['node', 'bin', 'deploy', '--help'], { run: false });
         const text = stripAnsi(cli.helpText());
         expect(text).toContain('deploy');
         expect(text).toContain('--force');
         expect(text).toContain('Force deploy');
     });
-    test('works without calling parse', () => {
+    test('works without calling parse', async () => {
         const cli = goke('mycli');
         cli.command('test', 'Run tests');
         cli.option('--coverage', 'Enable coverage');
@@ -1683,7 +1747,7 @@ describe('helpText()', () => {
     });
 });
 describe('middleware', () => {
-    test('middleware runs before command action', () => {
+    test('middleware runs before command action', async () => {
         const cli = goke('mycli');
         const order = [];
         cli
@@ -1696,10 +1760,10 @@ describe('middleware', () => {
             .action(() => {
             order.push('action');
         });
-        cli.parse(['node', 'bin', 'build'], { run: true });
+        await cli.parse(['node', 'bin', 'build'], { run: true });
         expect(order).toEqual(['middleware', 'action']);
     });
-    test('multiple middleware run in registration order', () => {
+    test('multiple middleware run in registration order', async () => {
         const cli = goke('mycli');
         const order = [];
         cli
@@ -1709,10 +1773,10 @@ describe('middleware', () => {
         cli
             .command('deploy', 'Deploy')
             .action(() => { order.push('action'); });
-        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        await cli.parse(['node', 'bin', 'deploy'], { run: true });
         expect(order).toEqual(['mw1', 'mw2', 'mw3', 'action']);
     });
-    test('middleware receives parsed global options', () => {
+    test('middleware receives parsed global options', async () => {
         const cli = goke('mycli');
         let received = null;
         cli
@@ -1723,10 +1787,10 @@ describe('middleware', () => {
         cli
             .command('build', 'Build')
             .action(() => { });
-        cli.parse(['node', 'bin', 'build', '--verbose'], { run: true });
+        await cli.parse(['node', 'bin', 'build', '--verbose'], { run: true });
         expect(received.verbose).toBe(true);
     });
-    test('middleware receives schema-coerced global options', () => {
+    test('middleware receives schema-coerced global options', async () => {
         const cli = goke('mycli');
         let received = null;
         cli
@@ -1737,7 +1801,7 @@ describe('middleware', () => {
         cli
             .command('serve', 'Serve')
             .action(() => { });
-        cli.parse(['node', 'bin', 'serve', '--port', '3000'], { run: true });
+        await cli.parse(['node', 'bin', 'serve', '--port', '3000'], { run: true });
         expect(received.port).toBe(3000);
         expect(typeof received.port).toBe('number');
     });
@@ -1751,7 +1815,7 @@ describe('middleware', () => {
         cli
             .command('run', 'Run')
             .action(() => { order.push('action'); });
-        cli.parse(['node', 'bin', 'run'], { run: true });
+        await cli.parse(['node', 'bin', 'run'], { run: true });
         // Wait for async chain to complete
         await new Promise((r) => setTimeout(r, 50));
         expect(order).toEqual(['async-mw', 'action']);
@@ -1766,22 +1830,22 @@ describe('middleware', () => {
         cli
             .command('deploy', 'Deploy')
             .action(() => { });
-        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        await cli.parse(['node', 'bin', 'deploy'], { run: true });
         await new Promise((r) => setTimeout(r, 10));
         expect(exitCode).toBe(1);
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware failed"`);
     });
-    test('middleware does not run with { run: false }', () => {
+    test('middleware does not run with { run: false }', async () => {
         const cli = goke('mycli');
         let middlewareCalled = false;
         cli.use(() => { middlewareCalled = true; });
         cli
             .command('build', 'Build')
             .action(() => { });
-        cli.parse(['node', 'bin', 'build'], { run: false });
+        await cli.parse(['node', 'bin', 'build'], { run: false });
         expect(middlewareCalled).toBe(false);
     });
-    test('middleware does not run for help', () => {
+    test('middleware does not run for help', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         let middlewareCalled = false;
@@ -1790,10 +1854,10 @@ describe('middleware', () => {
         cli
             .command('build', 'Build')
             .action(() => { });
-        cli.parse(['node', 'bin', '--help'], { run: true });
+        await cli.parse(['node', 'bin', '--help'], { run: true });
         expect(middlewareCalled).toBe(false);
     });
-    test('middleware does not run when no command matched', () => {
+    test('middleware does not run when no command matched', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout });
         let middlewareCalled = false;
@@ -1802,20 +1866,20 @@ describe('middleware', () => {
         cli
             .command('build', 'Build')
             .action(() => { });
-        cli.parse(['node', 'bin', 'nonexistent'], { run: true });
+        await cli.parse(['node', 'bin', 'nonexistent'], { run: true });
         expect(middlewareCalled).toBe(false);
     });
-    test('middleware runs for default command', () => {
+    test('middleware runs for default command', async () => {
         const cli = goke('mycli');
         const order = [];
         cli.use(() => { order.push('mw'); });
         cli
             .command('', 'Default')
             .action(() => { order.push('action'); });
-        cli.parse(['node', 'bin'], { run: true });
+        await cli.parse(['node', 'bin'], { run: true });
         expect(order).toEqual(['mw', 'action']);
     });
-    test('sync middleware error is caught and formatted', () => {
+    test('sync middleware error is caught and formatted', async () => {
         const stderr = createTestOutputStream();
         let exitCode;
         const cli = goke('mycli', { stderr, exit: (code) => { exitCode = code; } });
@@ -1825,11 +1889,11 @@ describe('middleware', () => {
         cli
             .command('deploy', 'Deploy')
             .action(() => { });
-        cli.parse(['node', 'bin', 'deploy'], { run: true });
+        await cli.parse(['node', 'bin', 'deploy'], { run: true });
         expect(exitCode).toBe(1);
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: middleware exploded"`);
     });
-    test('sync middleware error short-circuits command action', () => {
+    test('sync middleware error short-circuits command action', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         let actionCalled = false;
@@ -1839,7 +1903,7 @@ describe('middleware', () => {
         cli
             .command('build', 'Build')
             .action(() => { actionCalled = true; });
-        cli.parse(['node', 'bin', 'build'], { run: true });
+        await cli.parse(['node', 'bin', 'build'], { run: true });
         expect(actionCalled).toBe(false);
     });
     test('mixed sync and async middleware chain correctly', async () => {
@@ -1855,13 +1919,13 @@ describe('middleware', () => {
         cli
             .command('run', 'Run')
             .action(() => { order.push('action'); });
-        cli.parse(['node', 'bin', 'run'], { run: true });
+        await cli.parse(['node', 'bin', 'run'], { run: true });
         await new Promise((r) => setTimeout(r, 50));
         expect(order).toEqual(['sync1', 'async', 'sync2', 'action']);
     });
 });
 describe('use() with sub-CLI composition', () => {
-    test('basic composition: sub-CLI command runs via parent', () => {
+    test('basic composition: sub-CLI command runs via parent', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let matched = '';
@@ -1869,10 +1933,10 @@ describe('use() with sub-CLI composition', () => {
             .command('deploy', 'Deploy the app')
             .action(() => { matched = 'deploy'; });
         parent.use(sub);
-        parent.parse(['node', 'bin', 'deploy'], { run: true });
+        await parent.parse(['node', 'bin', 'deploy'], { run: true });
         expect(matched).toBe('deploy');
     });
-    test('multiple sub-CLIs composed together', () => {
+    test('multiple sub-CLIs composed together', async () => {
         const parent = goke('mycli');
         const subA = goke();
         const subB = goke();
@@ -1880,13 +1944,13 @@ describe('use() with sub-CLI composition', () => {
         subA.command('login', 'Login').action(() => { matched = 'login'; });
         subB.command('deploy', 'Deploy').action(() => { matched = 'deploy'; });
         parent.use(subA).use(subB);
-        parent.parse(['node', 'bin', 'login'], { run: true });
+        await parent.parse(['node', 'bin', 'login'], { run: true });
         expect(matched).toBe('login');
         matched = '';
-        parent.parse(['node', 'bin', 'deploy'], { run: true });
+        await parent.parse(['node', 'bin', 'deploy'], { run: true });
         expect(matched).toBe('deploy');
     });
-    test('sub-CLI command with options and schema coercion', () => {
+    test('sub-CLI command with options and schema coercion', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let result = {};
@@ -1896,12 +1960,12 @@ describe('use() with sub-CLI composition', () => {
             .option('--host <host>', z.string().describe('Host'))
             .action((options) => { result = options; });
         parent.use(sub);
-        parent.parse('node bin serve --port 3000 --host localhost'.split(' '), { run: true });
+        await parent.parse('node bin serve --port 3000 --host localhost'.split(' '), { run: true });
         expect(result.port).toBe(3000);
         expect(typeof result.port).toBe('number');
         expect(result.host).toBe('localhost');
     });
-    test('sub-CLI command with positional args', () => {
+    test('sub-CLI command with positional args', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let receivedId = '';
@@ -1909,23 +1973,23 @@ describe('use() with sub-CLI composition', () => {
             .command('get <id>', 'Get a resource')
             .action((id) => { receivedId = id; });
         parent.use(sub);
-        parent.parse(['node', 'bin', 'get', 'abc123'], { run: true });
+        await parent.parse(['node', 'bin', 'get', 'abc123'], { run: true });
         expect(receivedId).toBe('abc123');
     });
-    test('sub-CLI with multi-word commands', () => {
+    test('sub-CLI with multi-word commands', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let matched = '';
         sub.command('mcp login', 'Login to MCP').action(() => { matched = 'mcp login'; });
         sub.command('mcp logout', 'Logout from MCP').action(() => { matched = 'mcp logout'; });
         parent.use(sub);
-        parent.parse(['node', 'bin', 'mcp', 'login'], { run: true });
+        await parent.parse(['node', 'bin', 'mcp', 'login'], { run: true });
         expect(matched).toBe('mcp login');
         matched = '';
-        parent.parse(['node', 'bin', 'mcp', 'logout'], { run: true });
+        await parent.parse(['node', 'bin', 'mcp', 'logout'], { run: true });
         expect(matched).toBe('mcp logout');
     });
-    test('help output includes composed commands', () => {
+    test('help output includes composed commands', async () => {
         const stdout = createTestOutputStream();
         const parent = goke('mycli', { stdout });
         const sub = goke();
@@ -1934,12 +1998,12 @@ describe('use() with sub-CLI composition', () => {
         parent.command('init', 'Initialize project');
         parent.use(sub);
         parent.help();
-        parent.parse(['node', 'bin', '--help'], { run: false });
+        await parent.parse(['node', 'bin', '--help'], { run: false });
         expect(stdout.text).toContain('init');
         expect(stdout.text).toContain('selfhost');
         expect(stdout.text).toContain('Set up on your own workspace');
     });
-    test('sub-CLI middlewares are NOT copied to parent', () => {
+    test('sub-CLI middlewares are NOT copied to parent', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let subMiddlewareCalled = false;
@@ -1948,11 +2012,11 @@ describe('use() with sub-CLI composition', () => {
         sub.command('deploy', 'Deploy').action(() => { order.push('deploy'); });
         parent.use(() => { order.push('parent-mw'); });
         parent.use(sub);
-        parent.parse(['node', 'bin', 'deploy'], { run: true });
+        await parent.parse(['node', 'bin', 'deploy'], { run: true });
         expect(subMiddlewareCalled).toBe(false);
         expect(order).toEqual(['parent-mw', 'deploy']);
     });
-    test('parent global options are available to composed commands', () => {
+    test('parent global options are available to composed commands', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let result = {};
@@ -1962,11 +2026,11 @@ describe('use() with sub-CLI composition', () => {
             .option('--target <target>', 'Build target')
             .action((options) => { result = options; });
         parent.use(sub);
-        parent.parse('node bin build --verbose --target production'.split(' '), { run: true });
+        await parent.parse('node bin build --verbose --target production'.split(' '), { run: true });
         expect(result.verbose).toBe(true);
         expect(result.target).toBe('production');
     });
-    test('composed commands coexist with inline commands', () => {
+    test('composed commands coexist with inline commands', async () => {
         const parent = goke('mycli');
         const sub = goke();
         let matched = '';
@@ -1974,18 +2038,18 @@ describe('use() with sub-CLI composition', () => {
         sub.command('deploy', 'Deploy').action(() => { matched = 'deploy'; });
         sub.command('rollback', 'Rollback').action(() => { matched = 'rollback'; });
         parent.use(sub);
-        parent.parse(['node', 'bin', 'init'], { run: true });
+        await parent.parse(['node', 'bin', 'init'], { run: true });
         expect(matched).toBe('init');
         matched = '';
-        parent.parse(['node', 'bin', 'deploy'], { run: true });
+        await parent.parse(['node', 'bin', 'deploy'], { run: true });
         expect(matched).toBe('deploy');
         matched = '';
-        parent.parse(['node', 'bin', 'rollback'], { run: true });
+        await parent.parse(['node', 'bin', 'rollback'], { run: true });
         expect(matched).toBe('rollback');
     });
 });
 describe('getAction()', () => {
-    test('returns the action callable with correct behavior', () => {
+    test('returns the action callable with correct behavior', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout, exit: () => { } });
         const cmd = cli
@@ -1999,7 +2063,7 @@ describe('getAction()', () => {
         action({ env: 'staging', '--': [] }, ctx);
         expect(stdout.text).toBe('Deploying to staging\n');
     });
-    test('works with positional args', () => {
+    test('works with positional args', async () => {
         const stdout = createTestOutputStream();
         const cli = goke('mycli', { stdout, exit: () => { } });
         const cmd = cli
@@ -2013,7 +2077,7 @@ describe('getAction()', () => {
         action('abc123', { format: 'json', '--': [] }, ctx);
         expect(stdout.text).toBe('abc123:json\n');
     });
-    test('throws when no action is registered', () => {
+    test('throws when no action is registered', async () => {
         const cli = goke('mycli');
         const cmd = cli.command('noop', 'No action');
         expect(() => cmd.getAction()).toThrow(/No action registered/);