goke 6.4.0 → 6.5.0

package/README.md

@@ -15,7 +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 `{ console, process }` in actions and middleware for portable output, simpler tests, and alternate runtimes like JustBash.
+- **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.
 
@@ -44,8 +44,8 @@ cli.option(
 )
 cli.option('--name <name>', 'Provide your name')
 
-cli.command('lint [...files]', 'Lint files').action((files, options, { console }) => {
-  console.log(files, options)
+cli.command('lint [...files]', 'Lint files').action((files, options, { console, process }) => {
+  console.log(files, options, process.cwd)
 })
 
 cli
@@ -53,8 +53,8 @@ cli
   .option('--minify', 'Minify output')
   .example('build src/index.ts')
   .example('build src/index.ts --minify')
-  .action(async (entry, options, { console }) => { // 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`)
@@ -133,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 }) => {
-    console.log('release', version, options)
+  .action((version, options, { console, process }) => {
+    console.log('release', version, options, process.cwd)
   })
 
 cli
@@ -159,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 }) => {
-    console.log('migrate', options)
+  .action((options, { console, process }) => {
+    console.log('migrate', options, process.stdin)
   })
 
 cli.help()
@@ -299,39 +299,39 @@ cli
     z.string().default('production').describe('Target environment'),
   )
   .option('--dry-run', 'Preview without deploying')
-  .action((options, { console }) => {
-    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 }) => {
-    console.log('Initializing project...')
+  .action((options, { console, process }) => {
+    console.log('Initializing project in', process.cwd)
   })
 
-cli.command('login', 'Authenticate with the server').action((options, { console }) => {
-  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((options, { console }) => {
-  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 }) => {
-    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 }) => {
-    console.log(`Streaming logs for ${deploymentId}...`)
+  .action((deploymentId, options, { console, process }) => {
+    console.log(`Streaming logs for ${deploymentId} from ${process.cwd}...`)
   })
 
 cli.help()
@@ -352,10 +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 `{ console, process }` argument over global `console` and `process.exit`. It keeps commands easier to test and lets the same command code run inside alternate runtimes like JustBash.
+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'
@@ -365,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, { console }) => {
+  .use((options, { console, process }) => {
     // options.verbose and options.apiUrl are fully typed here
     if (options.verbose) {
-      console.log('verbose mode enabled')
+      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, { console }) => {
+  .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 }) => {
-    console.log('Checking status...')
+  .action((options, { console, process }) => {
+    console.log('Checking status...', process.stdin)
   })
 
 cli.help()
@@ -398,13 +460,16 @@ cli
   .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, { console }) => {
+  .use((options, { console, process }) => {
     options.verbose   // boolean — still visible
     options.port      // number — now visible
-    console.error('ready')
+    console.error('ready', process.cwd)
   })
 ```
 
@@ -413,10 +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, { console }) => {
+  .use(async (options, { console, process }) => {
     const client = await connectToApi(options.token)
     globalState.client = client
-    console.log('connected')
+    console.log('connected', process.env.NODE_ENV)
   })
 ```
 
@@ -432,8 +497,8 @@ const cli = goke()
 cli
   .command('rm <dir>', 'Remove a dir')
   .option('-r, --recursive', 'Remove recursively')
-  .action((dir, options, { console }) => {
-    console.log('remove ' + dir + (options.recursive ? ' recursively' : ''))
+  .action((dir, options, { console, process }) => {
+    console.log('remove ' + dir + (options.recursive ? ' recursively' : ''), process.cwd)
   })
 
 cli.help()
@@ -450,18 +515,18 @@ import { goke } from 'goke'
 
 const cli = goke('mycli')
 
-cli.command('mcp login <url>', 'Login to MCP server').action((url, options, { console }) => {
-  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((options, { console }) => {
-  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, options, { console }) => {
-    console.log('Adding remote', name, url)
+  .action((name, url, options, { console, process }) => {
+    console.log('Adding remote', name, url, 'from', process.cwd)
   })
 
 cli.help()
@@ -485,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, { console }) => {
+  .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()
@@ -516,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, { console }) => {
+  .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()
@@ -554,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, { console }) => {
+  .action((entry, otherFiles, options, { console, process }) => {
     console.log(entry)
     console.log(otherFiles)
-    console.log(options)
+    console.log(options, process.stdin)
   })
 ```
 
@@ -612,8 +677,8 @@ cli
   .command('build', 'desc')
   .option('--env <env>', 'Set envs')
   .example('--env.API_SECRET xxx')
-  .action((options, { console }) => {
-    console.log(options)
+  .action((options, { console, process }) => {
+    console.log(options, process.env.API_SECRET)
   })
 ```
 
@@ -625,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, { console }) => {
+  .action((files, options, { console, process }) => {
     console.log(files)
-    console.log(options.minimize)
+    console.log(options.minimize, process.cwd)
   })
 ```
 
@@ -648,7 +713,7 @@ try {
 
 ### Testing with mocked console and exit
 
-Because goke derives its injected `{ console, process }` from the CLI's configured output streams and `exit` function, tests can override them directly and assert on the calls.
+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'
@@ -700,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, { console }) => {
+  .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)
   })
 ```
 
@@ -732,8 +797,8 @@ const cli = goke('parent')
 cli
   .command('child commandwithspaces', 'Run nested command')
   .option('--name <name>', z.string().describe('Name'))
-  .action((options, { console }) => {
-    console.log(`hello ${options.name}`)
+  .action((options, { console, process }) => {
+    console.log(`hello ${options.name} from ${process.cwd}`)
   })
 
 const bash = new Bash({
@@ -743,7 +808,7 @@ const bash = new Bash({
 await bash.exec('parent child commandwithspaces --name Tommy')
 ```
 
-Prefer the injected `{ console, process }` helpers in command implementations so the same command code works cleanly both in the regular CLI runtime and through the JustBash bridge.
+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
 
@@ -780,9 +845,9 @@ Add a global option. The second argument is either:
 
 #### cli.use(callback)
 
-- Type: `(callback: (options: Opts, { console, process }) => 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, plus an injected `{ console, process }` helper object.
+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?)
 
@@ -836,7 +901,7 @@ 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 `{ console, process }` object. Prefer those injected helpers over global `console` and `process.exit` so commands stay easier to test and can run inside alternate runtimes like JustBash.
+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)
 

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.js

@@ -79,6 +79,134 @@ describe('createJustBashCommand', () => {
             exitCode: 0,
         });
     });
+    test('works through real just-bash exec with a goke custom command', async () => {
+        const { Bash } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        cli
+            .command('child commandwithspaces', 'Run nested command')
+            .option('--name <name>', z.string().describe('Name'))
+            .action((options, { console }) => {
+            console.log(`hello ${options.name}`);
+        });
+        const bash = new Bash({
+            customCommands: [await cli.createJustBashCommand()],
+        });
+        const result = await bash.exec('parent child commandwithspaces --name Tommy');
+        expect(result.stdout).toBe('hello Tommy\n');
+        expect(result.stderr).toBe('');
+        expect(result.exitCode).toBe(0);
+    });
+    test('maps injected fs to the just-bash virtual filesystem', async () => {
+        const { Bash } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        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');
+        });
+        const bash = new Bash({
+            customCommands: [await cli.createJustBashCommand()],
+        });
+        const loginResult = await bash.exec('mkdir project && cd project && parent login --token Tommy');
+        const catResult = await bash.exec('cd project && cat .mycli/auth.json');
+        expect(loginResult.stdout).toBe('saved credentials\n');
+        expect(loginResult.stderr).toBe('');
+        expect(loginResult.exitCode).toBe(0);
+        expect(catResult.stdout).toBe('{"token":"Tommy"}');
+        expect(catResult.stderr).toBe('');
+        expect(catResult.exitCode).toBe(0);
+    });
+    test('real just-bash exec passes the configured in-memory fs to the goke command', async () => {
+        const { Bash, InMemoryFs } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        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');
+        });
+        const virtualFs = new InMemoryFs();
+        await virtualFs.mkdir('/project', { recursive: true });
+        const bash = new Bash({
+            fs: virtualFs,
+            cwd: '/project',
+            customCommands: [await cli.createJustBashCommand()],
+        });
+        const result = await bash.exec('parent login --token Tommy');
+        expect(result.stdout).toBe('saved credentials\n');
+        expect(result.stderr).toBe('');
+        expect(result.exitCode).toBe(0);
+        expect(await virtualFs.readFile('/project/.mycli/auth.json', 'utf8')).toBe('{"token":"Tommy"}');
+    });
+    test('real just-bash exec passes sandbox cwd, stdin, and env through process context', async () => {
+        const { Bash, InMemoryFs } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        cli
+            .command('context', 'Inspect process context')
+            .action((options, { console, process }) => {
+            console.log(JSON.stringify({
+                cwd: process.cwd,
+                stdin: process.stdin,
+                token: process.env.TOKEN,
+            }));
+        });
+        const virtualFs = new InMemoryFs();
+        await virtualFs.mkdir('/project', { recursive: true });
+        const bash = new Bash({
+            fs: virtualFs,
+            cwd: '/project',
+            env: { TOKEN: 'Tommy' },
+            customCommands: [await cli.createJustBashCommand()],
+        });
+        const result = await bash.exec('parent context', { stdin: 'hello from stdin' });
+        expect(result.stdout).toBe(`${JSON.stringify({ cwd: '/project', stdin: 'hello from stdin', token: 'Tommy' })}\n`);
+        expect(result.stderr).toBe('');
+        expect(result.exitCode).toBe(0);
+    });
+    test('explicit just-bash context exposes a mutable env object backed by the sandbox env', async () => {
+        const { InMemoryFs } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        cli
+            .command('mutate-env', 'Mutate sandbox env')
+            .action((options, { console, process }) => {
+            process.env.TOKEN = 'updated';
+            console.log(process.env.TOKEN);
+        });
+        const virtualFs = new InMemoryFs();
+        await virtualFs.mkdir('/project', { recursive: true });
+        const env = new Map([['TOKEN', 'before']]);
+        const customCommand = await cli.createJustBashCommand();
+        const result = await customCommand.execute(['mutate-env'], { fs: virtualFs, cwd: '/project', env, stdin: '' });
+        expect(result.stdout).toBe('updated\n');
+        expect(result.stderr).toBe('');
+        expect(result.exitCode).toBe(0);
+        expect(env.get('TOKEN')).toBe('updated');
+    });
+    test('accepts an explicit just-bash fs context when executing the custom command', async () => {
+        const { InMemoryFs } = await import('just-bash');
+        const cli = gokeTestable('parent');
+        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');
+        });
+        const customCommand = await cli.createJustBashCommand();
+        const virtualFs = new InMemoryFs();
+        await virtualFs.mkdir('/project', { recursive: true });
+        const result = await customCommand.execute(['login', '--token', 'Tommy'], { fs: virtualFs, cwd: '/project', env: new Map(), stdin: '' });
+        expect(result.stdout).toBe('saved credentials\n');
+        expect(result.stderr).toBe('');
+        expect(result.exitCode).toBe(0);
+        expect(await virtualFs.readFile('/project/.mycli/auth.json', 'utf8')).toBe('{"token":"Tommy"}');
+    });
     test('maps injected process.exit to a command exit code', async () => {
         const cli = gokeTestable('parent');
         cli

package/dist/__test__/types.test-d.js

@@ -73,10 +73,14 @@ describe('type-level: middleware use() callback inference', () => {
         goke('test')
             .option('--port <port>', schema1)
             .option('--host <host>', schema2)
-            .use((options, { console, process }) => {
+            .use((options, { console, fs, process }) => {
             expectTypeOf(options.port).toEqualTypeOf();
             expectTypeOf(options.host).toEqualTypeOf();
+            expectTypeOf(fs.mkdir).toBeFunction();
             expectTypeOf(process.argv).toEqualTypeOf();
+            expectTypeOf(process.cwd).toEqualTypeOf();
+            expectTypeOf(process.env).toEqualTypeOf();
+            expectTypeOf(process.stdin).toEqualTypeOf();
             expectTypeOf(process.stdout.write).toEqualTypeOf();
             expectTypeOf(console.log).toBeFunction();
         });
@@ -86,8 +90,9 @@ describe('type-level: middleware use() callback inference', () => {
         const schema2 = {};
         goke('test')
             .option('--verbose', schema1)
-            .use((options, { process }) => {
+            .use((options, { fs, process }) => {
             expectTypeOf(options.verbose).toEqualTypeOf();
+            expectTypeOf(fs.writeFile).toBeFunction();
             expectTypeOf(process.exit).toEqualTypeOf();
             // @ts-expect-error port is not declared yet
             options.port;
@@ -104,7 +109,8 @@ describe('type-level: middleware use() callback inference', () => {
         const schema = {};
         goke('test')
             .option('--port <port>', schema)
-            .use((options, { process }) => {
+            .use((options, { fs, process }) => {
+            expectTypeOf(fs.readFile).toBeFunction();
             expectTypeOf(process.stderr.write).toEqualTypeOf();
             // @ts-expect-error nonExistent was never defined
             options.nonExistent;