goke 6.3.2 → 6.5.0

package/README.md

@@ -15,6 +15,7 @@
 - **Yet so powerful**. Enable features like default command, git-like subcommands, validation for required arguments and options, variadic arguments, dot-nested options, automated help message generation and so on.
 - **Space-separated subcommands**: Support multi-word commands like `mcp login`, `git remote add`.
 - **Schema-based type coercion**: Use Zod, Valibot, ArkType, or plain JSON Schema for automatic type coercion and TypeScript type inference. Description and default values are extracted from the schema automatically.
+- **Injected execution context**: Prefer `{ fs, console, process }` in actions and middleware for portable storage, output, and runtime metadata across Node.js, tests, and JustBash.
 - **Type-safe middleware**: Register `.use()` callbacks that run before commands with full type inference from global options.
 - **Developer friendly**. Written in TypeScript.
 
@@ -43,8 +44,8 @@ cli.option(
 )
 cli.option('--name <name>', 'Provide your name')
 
-cli.command('lint [...files]', 'Lint files').action((files, options) => {
-  console.log(files, options)
+cli.command('lint [...files]', 'Lint files').action((files, options, { console, process }) => {
+  console.log(files, options, process.cwd)
 })
 
 cli
@@ -52,8 +53,8 @@ cli
   .option('--minify', 'Minify output')
   .example('build src/index.ts')
   .example('build src/index.ts --minify')
-  .action(async (entry, options) => { // options is type safe! no need to type it
-    console.log(entry, options)
+  .action(async (entry, options, { console, process }) => { // options is type safe! no need to type it
+    console.log(entry, options, process.env.NODE_ENV)
   })
 
 cli.example((bin) => `${bin} lint src/**/*.ts`)
@@ -132,8 +133,8 @@ cli
   .option('--channel <name>', 'Target channel: stable, beta, alpha')
   .option('--notes-file <path>', 'Markdown file used as release notes')
   .option('--dry-run', 'Preview every step without publishing')
-  .action((version, options) => {
-    console.log('release', version, options)
+  .action((version, options, { console, process }) => {
+    console.log('release', version, options, process.cwd)
   })
 
 cli
@@ -158,8 +159,8 @@ cli
   .option('--target <migration>', 'Apply up to a specific migration id')
   .option('--dry-run', 'Print plan only, do not execute SQL')
   .option('--verbose', 'Show each executed statement')
-  .action((options) => {
-    console.log('migrate', options)
+  .action((options, { console, process }) => {
+    console.log('migrate', options, process.stdin)
   })
 
 cli.help()
@@ -298,39 +299,39 @@ cli
     z.string().default('production').describe('Target environment'),
   )
   .option('--dry-run', 'Preview without deploying')
-  .action((options) => {
-    console.log(`Deploying to ${options.env}...`)
+  .action((options, { console, process }) => {
+    console.log(`Deploying to ${options.env} from ${process.cwd}...`)
   })
 
 // Subcommands
 cli
   .command('init', 'Initialize a new project')
   .option('--template <template>', 'Project template')
-  .action((options) => {
-    console.log('Initializing project...')
+  .action((options, { console, process }) => {
+    console.log('Initializing project in', process.cwd)
   })
 
-cli.command('login', 'Authenticate with the server').action(() => {
-  console.log('Opening browser for login...')
+cli.command('login', 'Authenticate with the server').action((options, { console, process }) => {
+  console.log('Opening browser for login from', process.cwd)
 })
 
-cli.command('logout', 'Clear saved credentials').action(() => {
-  console.log('Logged out')
+cli.command('logout', 'Clear saved credentials').action((options, { console, process }) => {
+  console.log('Logged out', process.env.USER)
 })
 
 cli
   .command('status', 'Show deployment status')
   .option('--json', 'Output as JSON')
-  .action((options) => {
-    console.log('Fetching status...')
+  .action((options, { console, process }) => {
+    console.log('Fetching status from', process.cwd)
   })
 
 cli
   .command('logs <deploymentId>', 'Stream logs for a deployment')
   .option('--follow', 'Follow log output')
   .option('--lines <n>', z.number().default(100).describe('Number of lines'))
-  .action((deploymentId, options) => {
-    console.log(`Streaming logs for ${deploymentId}...`)
+  .action((deploymentId, options, { console, process }) => {
+    console.log(`Streaming logs for ${deploymentId} from ${process.cwd}...`)
   })
 
 cli.help()
@@ -351,8 +352,72 @@ deploy --help                   # shows all commands
 
 Global options are defined on the CLI instance and apply to all commands. Use `.use()` to register middleware that runs before any command action — useful for reacting to global options like setting up logging, initializing state, or configuring services.
 
+Prefer the injected `{ fs, console, process }` argument over global `console`, `process.exit`, or direct `node:fs/promises` imports. It keeps commands easier to test and lets the same command code run inside alternate runtimes like JustBash.
+
+`process.cwd`, `process.stdin`, and `process.env` come from the active runtime:
+
+- In normal Node.js runs, `process.cwd` and `process.env` reflect the host process, while `process.stdin` defaults to an empty string unless you inject it yourself.
+- In JustBash runs, those same fields are populated from the sandbox execution context.
+
 Middleware runs in registration order, after option parsing and validation, but before the matched command's `.action()` callback.
 
+### Filesystem Access
+
+The injected `fs` object is the recommended way to read or write CLI state.
+
+- In normal Node.js runs, `fs` defaults to `node:fs/promises`
+- In JustBash runs, `goke` swaps in a compatible adapter over the JustBash virtual filesystem
+
+This makes storage-style commands work in both environments without branching on runtime details.
+
+```ts
+cli
+  .command('login', 'Save auth token')
+  .option('--token <token>', z.string().describe('Auth token'))
+  .action(async (options, { fs, console, process }) => {
+    await fs.mkdir('.mycli', { recursive: true })
+    await fs.writeFile('.mycli/auth.json', JSON.stringify({ token: options.token }), 'utf8')
+    console.log('saved credentials in', process.cwd)
+  })
+
+cli
+  .command('whoami', 'Read saved auth token')
+  .action(async (options, { fs, console, process }) => {
+    const auth = await fs.readFile('.mycli/auth.json', 'utf8')
+    console.log(auth, process.env.USER)
+  })
+```
+
+Prefer injected `fs` for CLI storage instead of importing `node:fs/promises` directly inside actions. That keeps the command portable to JustBash and easier to test.
+
+`goke` also exports the runtime types, so helper functions can use dependency injection without reaching for globals:
+
+```ts
+import { goke } from 'goke'
+import type { GokeFs, GokeProcess } from 'goke'
+
+async function saveAuthToken(args: {
+  fs: GokeFs
+  process: GokeProcess
+  token: string
+}) {
+  await args.fs.mkdir('.mycli', { recursive: true })
+  await args.fs.writeFile('.mycli/auth.json', JSON.stringify({
+    token,
+    cwd: args.process.cwd,
+  }), 'utf8')
+}
+
+const cli = goke('mycli')
+
+cli
+  .command('login <token>', 'Save auth token')
+  .action(async (token, options, { fs, process, console }) => {
+    await saveAuthToken({ fs, process, token })
+    console.log('saved credentials')
+  })
+```
+
 ```ts
 import { goke } from 'goke'
 import { z } from 'zod'
@@ -362,25 +427,25 @@ const cli = goke('mycli')
 cli
   .option('--verbose', z.boolean().default(false).describe('Enable verbose logging'))
   .option('--api-url [url]', z.string().default('https://api.example.com').describe('API base URL'))
-  .use((options) => {
+  .use((options, { console, process }) => {
     // options.verbose and options.apiUrl are fully typed here
     if (options.verbose) {
-      process.env.LOG_LEVEL = 'debug'
+      console.log('verbose mode enabled in', process.cwd)
     }
   })
 
 cli
   .command('deploy <env>', 'Deploy to an environment')
   .option('--dry-run', 'Preview without deploying')
-  .action((env, options) => {
+  .action((env, options, { console, process }) => {
     // options includes both command options (dryRun) and global options (verbose, apiUrl)
-    console.log(`Deploying to ${env} via ${options.apiUrl}`)
+    console.log(`Deploying to ${env} via ${options.apiUrl} from ${process.cwd}`)
   })
 
 cli
   .command('status', 'Show deployment status')
-  .action((options) => {
-    console.log('Checking status...')
+  .action((options, { console, process }) => {
+    console.log('Checking status...', process.stdin)
   })
 
 cli.help()
@@ -392,14 +457,19 @@ Type safety is positional — each `.use()` callback only sees options declared
 ```ts
 cli
   .option('--verbose', z.boolean().default(false).describe('Verbose'))
-  .use((options) => {
+  .use((options, { process }) => {
     options.verbose   // boolean — typed
+    process.argv      // string[] — typed
+    process.cwd       // string — typed
+    process.env       // Record<string, string> — typed
+    process.stdin     // string — typed
     options.port      // TypeScript error — not declared yet
   })
   .option('--port <port>', z.number().describe('Port'))
-  .use((options) => {
+  .use((options, { console, process }) => {
     options.verbose   // boolean — still visible
     options.port      // number — now visible
+    console.error('ready', process.cwd)
   })
 ```
 
@@ -408,9 +478,10 @@ Middleware supports async functions. If any middleware is async, the remaining m
 ```ts
 cli
   .option('--token <token>', z.string().describe('API token'))
-  .use(async (options) => {
+  .use(async (options, { console, process }) => {
     const client = await connectToApi(options.token)
     globalState.client = client
+    console.log('connected', process.env.NODE_ENV)
   })
 ```
 
@@ -426,8 +497,8 @@ const cli = goke()
 cli
   .command('rm <dir>', 'Remove a dir')
   .option('-r, --recursive', 'Remove recursively')
-  .action((dir, options) => {
-    console.log('remove ' + dir + (options.recursive ? ' recursively' : ''))
+  .action((dir, options, { console, process }) => {
+    console.log('remove ' + dir + (options.recursive ? ' recursively' : ''), process.cwd)
   })
 
 cli.help()
@@ -444,18 +515,18 @@ import { goke } from 'goke'
 
 const cli = goke('mycli')
 
-cli.command('mcp login <url>', 'Login to MCP server').action((url) => {
-  console.log('Logging in to', url)
+cli.command('mcp login <url>', 'Login to MCP server').action((url, options, { console, process }) => {
+  console.log('Logging in to', url, 'from', process.cwd)
 })
 
-cli.command('mcp logout', 'Logout from MCP server').action(() => {
-  console.log('Logged out')
+cli.command('mcp logout', 'Logout from MCP server').action((options, { console, process }) => {
+  console.log('Logged out', process.env.USER)
 })
 
 cli
   .command('git remote add <name> <url>', 'Add a git remote')
-  .action((name, url) => {
-    console.log('Adding remote', name, url)
+  .action((name, url, options, { console, process }) => {
+    console.log('Adding remote', name, url, 'from', process.cwd)
   })
 
 cli.help()
@@ -479,9 +550,9 @@ cli
   .option('--workers <workers>', z.int().describe('Worker count'))
   .option('--tags <tag>', z.array(z.string()).describe('Tags (repeatable)'))
   .option('--verbose', 'Verbose output')
-  .action((options) => {
+  .action((options, { console, process }) => {
     // options.port is number, options.host is string, etc.
-    console.log(options)
+    console.log(options, process.env.NODE_ENV)
   })
 
 cli.parse()
@@ -510,9 +581,9 @@ cli
   .option('--old-port <port>', z.number().meta({ deprecated: true, description: 'Use --port instead' }))
   // Current option: visible in help
   .option('--port <port>', z.number().describe('Port number'))
-  .action((options) => {
+  .action((options, { console, process }) => {
     const port = options.port ?? options.oldPort
-    console.log('Starting on port', port)
+    console.log('Starting on port', port, 'from', process.cwd)
   })
 
 cli.help()
@@ -548,10 +619,10 @@ The last argument of a command can be variadic. To make an argument variadic you
 cli
   .command('build <entry> [...otherFiles]', 'Build your app')
   .option('--foo', 'Foo option')
-  .action((entry, otherFiles, options) => {
+  .action((entry, otherFiles, options, { console, process }) => {
     console.log(entry)
     console.log(otherFiles)
-    console.log(options)
+    console.log(options, process.stdin)
   })
 ```
 
@@ -606,8 +677,8 @@ cli
   .command('build', 'desc')
   .option('--env <env>', 'Set envs')
   .example('--env.API_SECRET xxx')
-  .action((options) => {
-    console.log(options)
+  .action((options, { console, process }) => {
+    console.log(options, process.env.API_SECRET)
   })
 ```
 
@@ -619,9 +690,9 @@ Register a command that will be used when no other command is matched.
 cli
   .command('[...files]', 'Build files')
   .option('--minimize', 'Minimize output')
-  .action((files, options) => {
+  .action((files, options, { console, process }) => {
     console.log(files)
-    console.log(options.minimize)
+    console.log(options.minimize, process.cwd)
   })
 ```
 
@@ -634,11 +705,46 @@ try {
   cli.parse(process.argv, { run: false })
   await cli.runMatchedCommand()
 } catch (error) {
-  console.error(error.stack)
+  const message = error instanceof Error ? error.stack : String(error)
+  process.stderr.write(String(message) + '\n')
   process.exit(1)
 }
 ```
 
+### Testing with mocked console and exit
+
+Because goke derives its injected `{ fs, console, process }` from the CLI's configured runtime dependencies, tests can override them directly and assert on the calls.
+
+```ts
+import { describe, expect, test, vi } from 'vitest'
+import { goke, GokeProcessExit } from 'goke'
+
+describe('deploy command', () => {
+  test('writes output and exits with injected mocks', () => {
+    const stdout = { write: vi.fn<(data: string) => void>() }
+    const stderr = { write: vi.fn<(data: string) => void>() }
+    const exit = vi.fn<(code: number) => void>()
+
+    const cli = goke('acme', { stdout, stderr, exit })
+
+    cli
+      .command('deploy', 'Deploy the project')
+      .action((options, { console, process }) => {
+        console.log('deploying')
+        process.exit(2)
+      })
+
+    expect(() => {
+      cli.parse(['node', 'acme', 'deploy'], { run: true })
+    }).toThrow(GokeProcessExit)
+
+    expect(stdout.write).toHaveBeenCalledWith('deploying\n')
+    expect(exit).toHaveBeenCalledWith(2)
+    expect(stderr.write).not.toHaveBeenCalled()
+  })
+})
+```
+
 ### With TypeScript
 
 ```ts
@@ -659,11 +765,11 @@ cli
   .command('serve <entry>', 'Start the app')
   .option('--port <port>', z.number().default(3000).describe('Port number'))
   .option('--watch', 'Watch files')
-  .action((entry, options) => {
+  .action((entry, options, { console, process }) => {
     // entry: string
     // options.port: number
     // options.watch: boolean
-    console.log(entry, options.port, options.watch)
+    console.log(entry, options.port, options.watch, process.cwd)
   })
 ```
 
@@ -677,6 +783,33 @@ import { openInBrowser } from 'goke'
 openInBrowser('https://example.com/dashboard')
 ```
 
+### Expose a goke CLI to JustBash
+
+Use `cli.createJustBashCommand()` to expose a goke CLI as a single JustBash custom command. JustBash command names are single-token executables, but the goke CLI behind them can still use multi-word subcommands like `child commandwithspaces`.
+
+```ts
+import { goke } from 'goke'
+import { z } from 'zod'
+import { Bash } from 'just-bash'
+
+const cli = goke('parent')
+
+cli
+  .command('child commandwithspaces', 'Run nested command')
+  .option('--name <name>', z.string().describe('Name'))
+  .action((options, { console, process }) => {
+    console.log(`hello ${options.name} from ${process.cwd}`)
+  })
+
+const bash = new Bash({
+  customCommands: [await cli.createJustBashCommand()],
+})
+
+await bash.exec('parent child commandwithspaces --name Tommy')
+```
+
+Prefer the injected `{ fs, console, process }` helpers in command implementations so the same command code works cleanly both in the regular CLI runtime and through the JustBash bridge. The injected `fs` defaults to Node `fs/promises`, and `process.cwd` / `process.env` / `process.stdin` reflect host values in Node but sandbox values inside `createJustBashCommand()`.
+
 ## References
 
 ### CLI Instance
@@ -712,9 +845,9 @@ Add a global option. The second argument is either:
 
 #### cli.use(callback)
 
-- Type: `(callback: (options: Opts) => void | Promise<void>) => CLI`
+- Type: `(callback: (options: Opts, { fs, console, process }) => void | Promise<void>) => CLI`
 
-Register a middleware function that runs before the matched command action. Middleware runs in registration order, after option parsing and validation. The callback receives the parsed global options, typed according to all `.option()` calls that precede the `.use()` in the chain.
+Register a middleware function that runs before the matched command action. Middleware runs in registration order, after option parsing and validation. The callback receives the parsed global options, typed according to all `.option()` calls that precede the `.use()` in the chain, plus an injected `{ fs, console, process }` helper object.
 
 #### cli.parse(argv?)
 
@@ -768,6 +901,8 @@ Basically the same as `cli.option` but this adds the option to specific command.
 
 - Type: `(callback: ActionCallback) => Command`
 
+Command callbacks receive positional args first, then parsed options, then an injected `{ fs, console, process }` object. Prefer those injected helpers over global `console`, `process.exit`, and direct `node:fs/promises` imports so commands stay easier to test and can run inside alternate runtimes like JustBash.
+
 #### command.alias(name)
 
 - Type: `(name: string) => Command`
@@ -798,7 +933,7 @@ cli.on('command:!', () => {
 })
 
 cli.on('command:*', () => {
-  console.error('Invalid command: %s', cli.args.join(' '))
+  process.stderr.write(`Invalid command: ${cli.args.join(' ')}\n`)
   process.exit(1)
 })
 ```

package/dist/__test__/index.test.js

@@ -2,6 +2,9 @@ import { describe, test, expect } from 'vitest';
 import goke, { createConsole } from '../index.js';
 import { coerceBySchema } from '../coerce.js';
 import { z } from 'zod';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 const ANSI_RE = /\x1B\[[0-9;]*m/g;
 const stripAnsi = (text) => text.replace(ANSI_RE, '');
 /**
@@ -129,6 +132,83 @@ describe('error formatting', () => {
         expect(text).toMatch(/at /);
     });
 });
+describe('injected fs', () => {
+    test('command actions can use the default node fs for cli storage', async () => {
+        const stdout = createTestOutputStream();
+        const cli = gokeTestable('mycli', { stdout });
+        const originalCwd = process.cwd();
+        const tempDir = await mkdtemp(join(tmpdir(), 'goke-fs-'));
+        try {
+            process.chdir(tempDir);
+            cli
+                .command('login', 'Persist login state')
+                .option('--token <token>', z.string().describe('Token'))
+                .action(async (options, { fs, console }) => {
+                await fs.mkdir('.mycli', { recursive: true });
+                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.runMatchedCommand();
+            expect(stdout.text).toBe('saved credentials\n');
+            expect(await readFile(join(tempDir, '.mycli/auth.json'), 'utf8')).toBe('{"token":"abc123"}');
+        }
+        finally {
+            process.chdir(originalCwd);
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+});
+describe('injected process context', () => {
+    test('command actions receive host cwd, env, and stdin defaults', async () => {
+        const stdout = createTestOutputStream();
+        const cli = gokeTestable('mycli', { stdout });
+        const originalCwd = process.cwd();
+        const originalEnv = process.env.GOKE_TEST_TOKEN;
+        const tempDir = await mkdtemp(join(tmpdir(), 'goke-process-'));
+        try {
+            process.chdir(tempDir);
+            process.env.GOKE_TEST_TOKEN = 'abc123';
+            cli
+                .command('context', 'Inspect process context')
+                .action((options, { console, process }) => {
+                console.log(JSON.stringify({
+                    cwd: process.cwd,
+                    stdin: process.stdin,
+                    token: process.env.GOKE_TEST_TOKEN,
+                }));
+            });
+            cli.parse(['node', 'bin', 'context'], { run: false });
+            await cli.runMatchedCommand();
+            expect(stdout.text).toBe(`${JSON.stringify({ cwd: process.cwd(), stdin: '', token: 'abc123' })}\n`);
+        }
+        finally {
+            process.chdir(originalCwd);
+            if (originalEnv === undefined) {
+                delete process.env.GOKE_TEST_TOKEN;
+            }
+            else {
+                process.env.GOKE_TEST_TOKEN = originalEnv;
+            }
+            await rm(tempDir, { recursive: true, force: true });
+        }
+    });
+    test('custom injected env stays mutable inside command actions', async () => {
+        const stdout = createTestOutputStream();
+        const env = { TOKEN: 'before' };
+        const cli = gokeTestable('mycli', { env, stdout });
+        cli
+            .command('context', 'Mutate process env')
+            .action((options, { console, process }) => {
+            process.env.TOKEN = 'after';
+            console.log(process.env.TOKEN);
+        });
+        cli.parse(['node', 'bin', 'context'], { run: false });
+        await cli.runMatchedCommand();
+        expect(stdout.text).toBe('after\n');
+        expect(env.TOKEN).toBe('after');
+    });
+});
 test('double dashes', () => {
     const cli = goke();
     const { args, options } = cli.parse([

package/dist/__test__/just-bash.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for injected execution context, clone isolation, and the JustBash bridge.
+ */
+export {};
+//# sourceMappingURL=just-bash.test.d.ts.map

package/dist/__test__/just-bash.test.d.ts.map

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