goke 6.4.0 → 6.5.1

package/dist/picocolors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+type Formatter = (input: unknown) => string;
+interface PicoColors {
+    isColorSupported: boolean;
+    reset: Formatter;
+    bold: Formatter;
+    dim: Formatter;
+    italic: Formatter;
+    underline: Formatter;
+    inverse: Formatter;
+    hidden: Formatter;
+    strikethrough: Formatter;
+    black: Formatter;
+    red: Formatter;
+    green: Formatter;
+    yellow: Formatter;
+    blue: Formatter;
+    magenta: Formatter;
+    cyan: Formatter;
+    white: Formatter;
+    gray: Formatter;
+    bgBlack: Formatter;
+    bgRed: Formatter;
+    bgGreen: Formatter;
+    bgYellow: Formatter;
+    bgBlue: Formatter;
+    bgMagenta: Formatter;
+    bgCyan: Formatter;
+    bgWhite: Formatter;
+    blackBright: Formatter;
+    redBright: Formatter;
+    greenBright: Formatter;
+    yellowBright: Formatter;
+    blueBright: Formatter;
+    magentaBright: Formatter;
+    cyanBright: Formatter;
+    whiteBright: Formatter;
+    bgBlackBright: Formatter;
+    bgRedBright: Formatter;
+    bgGreenBright: Formatter;
+    bgYellowBright: Formatter;
+    bgBlueBright: Formatter;
+    bgMagentaBright: Formatter;
+    bgCyanBright: Formatter;
+    bgWhiteBright: Formatter;
+}
+declare const createColors: (enabled?: boolean) => PicoColors;
+declare const pc: PicoColors;
+export { createColors };
+export type { PicoColors };
+export default pc;
+//# sourceMappingURL=picocolors.d.ts.map

package/dist/picocolors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"picocolors.d.ts","sourceRoot":"","sources":["../src/picocolors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,KAAK,SAAS,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAA;AAE3C,UAAU,UAAU;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;IACf,GAAG,EAAE,SAAS,CAAA;IACd,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,SAAS,CAAA;IAClB,MAAM,EAAE,SAAS,CAAA;IACjB,aAAa,EAAE,SAAS,CAAA;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB,GAAG,EAAE,SAAS,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,SAAS,CAAA;IAClB,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;IACf,OAAO,EAAE,SAAS,CAAA;IAClB,KAAK,EAAE,SAAS,CAAA;IAChB,OAAO,EAAE,SAAS,CAAA;IAClB,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,SAAS,CAAA;IACpB,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,SAAS,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,SAAS,CAAA;IACtB,YAAY,EAAE,SAAS,CAAA;IACvB,UAAU,EAAE,SAAS,CAAA;IACrB,aAAa,EAAE,SAAS,CAAA;IACxB,UAAU,EAAE,SAAS,CAAA;IACrB,WAAW,EAAE,SAAS,CAAA;IACtB,aAAa,EAAE,SAAS,CAAA;IACxB,WAAW,EAAE,SAAS,CAAA;IACtB,aAAa,EAAE,SAAS,CAAA;IACxB,cAAc,EAAE,SAAS,CAAA;IACzB,YAAY,EAAE,SAAS,CAAA;IACvB,eAAe,EAAE,SAAS,CAAA;IAC1B,YAAY,EAAE,SAAS,CAAA;IACvB,aAAa,EAAE,SAAS,CAAA;CACzB;AAkCD,QAAA,MAAM,YAAY,GAAI,iBAA0B,KAAG,UA+ClD,CAAA;AAED,QAAA,MAAM,EAAE,YAAiB,CAAA;AAEzB,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EAAE,UAAU,EAAE,CAAA;AAC1B,eAAe,EAAE,CAAA"}

package/dist/picocolors.js

@@ -0,0 +1,78 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+import { process } from '#runtime';
+const argv = process.argv || [];
+const env = process.env || {};
+const isColorSupported = !(!!env.NO_COLOR || argv.includes('--no-color'))
+    && (!!env.FORCE_COLOR
+        || argv.includes('--color')
+        || process.platform === 'win32'
+        || (process.stdout.isTTY && env.TERM !== 'dumb')
+        || !!env.CI);
+const replaceClose = (string, close, replace, index) => {
+    let result = '';
+    let cursor = 0;
+    do {
+        result += string.substring(cursor, index) + replace;
+        cursor = index + close.length;
+        index = string.indexOf(close, cursor);
+    } while (~index);
+    return result + string.substring(cursor);
+};
+const formatter = (open, close, replace = open) => (input) => {
+    const string = String(input);
+    const index = string.indexOf(close, open.length);
+    return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
+};
+const createColors = (enabled = isColorSupported) => {
+    const f = enabled ? formatter : () => String;
+    return {
+        isColorSupported: enabled,
+        reset: f('\x1b[0m', '\x1b[0m'),
+        bold: f('\x1b[1m', '\x1b[22m', '\x1b[22m\x1b[1m'),
+        dim: f('\x1b[2m', '\x1b[22m', '\x1b[22m\x1b[2m'),
+        italic: f('\x1b[3m', '\x1b[23m'),
+        underline: f('\x1b[4m', '\x1b[24m'),
+        inverse: f('\x1b[7m', '\x1b[27m'),
+        hidden: f('\x1b[8m', '\x1b[28m'),
+        strikethrough: f('\x1b[9m', '\x1b[29m'),
+        black: f('\x1b[30m', '\x1b[39m'),
+        red: f('\x1b[31m', '\x1b[39m'),
+        green: f('\x1b[32m', '\x1b[39m'),
+        yellow: f('\x1b[33m', '\x1b[39m'),
+        blue: f('\x1b[34m', '\x1b[39m'),
+        magenta: f('\x1b[35m', '\x1b[39m'),
+        cyan: f('\x1b[36m', '\x1b[39m'),
+        white: f('\x1b[37m', '\x1b[39m'),
+        gray: f('\x1b[90m', '\x1b[39m'),
+        bgBlack: f('\x1b[40m', '\x1b[49m'),
+        bgRed: f('\x1b[41m', '\x1b[49m'),
+        bgGreen: f('\x1b[42m', '\x1b[49m'),
+        bgYellow: f('\x1b[43m', '\x1b[49m'),
+        bgBlue: f('\x1b[44m', '\x1b[49m'),
+        bgMagenta: f('\x1b[45m', '\x1b[49m'),
+        bgCyan: f('\x1b[46m', '\x1b[49m'),
+        bgWhite: f('\x1b[47m', '\x1b[49m'),
+        blackBright: f('\x1b[90m', '\x1b[39m'),
+        redBright: f('\x1b[91m', '\x1b[39m'),
+        greenBright: f('\x1b[92m', '\x1b[39m'),
+        yellowBright: f('\x1b[93m', '\x1b[39m'),
+        blueBright: f('\x1b[94m', '\x1b[39m'),
+        magentaBright: f('\x1b[95m', '\x1b[39m'),
+        cyanBright: f('\x1b[96m', '\x1b[39m'),
+        whiteBright: f('\x1b[97m', '\x1b[39m'),
+        bgBlackBright: f('\x1b[100m', '\x1b[49m'),
+        bgRedBright: f('\x1b[101m', '\x1b[49m'),
+        bgGreenBright: f('\x1b[102m', '\x1b[49m'),
+        bgYellowBright: f('\x1b[103m', '\x1b[49m'),
+        bgBlueBright: f('\x1b[104m', '\x1b[49m'),
+        bgMagentaBright: f('\x1b[105m', '\x1b[49m'),
+        bgCyanBright: f('\x1b[106m', '\x1b[49m'),
+        bgWhiteBright: f('\x1b[107m', '\x1b[49m'),
+    };
+};
+const pc = createColors();
+export { createColors };
+export default pc;

package/dist/runtime-browser.d.ts

@@ -1,6 +1,7 @@
 /**
  * Browser-safe runtime stubs for goke core.
  */
+import type { GokeFs } from './goke-fs.js';
 type Listener = (...args: any[]) => void;
 declare class EventEmitter {
     #private;
@@ -12,6 +13,8 @@ declare class EventEmitter {
 declare const process: {
     argv: string[];
     arch: string;
+    cwd(): string;
+    env: Record<string, string | undefined>;
     platform: string;
     version: string;
     stdout: {
@@ -26,6 +29,7 @@ declare const process: {
     };
     exit(code: number): never;
 };
+declare const fs: GokeFs;
 declare function openInBrowser(_url: string): void;
-export { EventEmitter, openInBrowser, process };
+export { EventEmitter, fs, openInBrowser, process };
 //# sourceMappingURL=runtime-browser.d.ts.map

package/dist/runtime-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-browser.d.ts","sourceRoot":"","sources":["../src/runtime-browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,KAAK,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;AAExC,cAAM,YAAY;;IAGhB,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,QAAQ;IAOjD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAS/C,UAAU;IAIV,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAGrC;AAQD,QAAA,MAAM,OAAO;UACC,MAAM,EAAE;;;;;;;qBAJP,MAAM;;;;;qBAAN,MAAM;;eAUR,MAAM,GAAG,KAAK;CAK1B,CAAA;AAED,iBAAS,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,CAAA"}
+{"version":3,"file":"runtime-browser.d.ts","sourceRoot":"","sources":["../src/runtime-browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,KAAK,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;AAExC,cAAM,YAAY;;IAGhB,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,QAAQ;IAOjD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE;IAS/C,UAAU;IAIV,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAGrC;AAQD,QAAA,MAAM,OAAO;UACC,MAAM,EAAE;;;SAKQ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;;;;;;qBATjD,MAAM;;;;;qBAAN,MAAM;;eAcR,MAAM,GAAG,KAAK;CAK1B,CAAA;AAcD,QAAA,MAAM,EAAE,EAAE,MAcT,CAAA;AAED,iBAAS,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzC;AAED,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,CAAA"}

package/dist/runtime-browser.js

@@ -33,6 +33,10 @@ const createOutputStream = () => ({
 const process = {
     argv: [],
     arch: 'browser',
+    cwd() {
+        return '/';
+    },
+    env: Object.create(null),
     platform: 'browser',
     version: 'browser',
     stdout: createOutputStream(),
@@ -41,7 +45,30 @@ const process = {
         throw new Error(`process.exit(${code}) is not available in the browser runtime. Pass a custom exit handler to goke(...).`);
     },
 };
+function createBrowserFsError(methodName) {
+    return new Error(`fs.${methodName}() is not available in the browser runtime. Pass a custom fs implementation to goke(...).`);
+}
+function createUnsupportedFsMethod(methodName) {
+    return (async () => {
+        throw createBrowserFsError(methodName);
+    });
+}
+const fs = {
+    appendFile: createUnsupportedFsMethod('appendFile'),
+    chmod: createUnsupportedFsMethod('chmod'),
+    copyFile: createUnsupportedFsMethod('copyFile'),
+    link: createUnsupportedFsMethod('link'),
+    mkdir: createUnsupportedFsMethod('mkdir'),
+    readFile: createUnsupportedFsMethod('readFile'),
+    readlink: createUnsupportedFsMethod('readlink'),
+    realpath: createUnsupportedFsMethod('realpath'),
+    rename: createUnsupportedFsMethod('rename'),
+    rm: createUnsupportedFsMethod('rm'),
+    symlink: createUnsupportedFsMethod('symlink'),
+    utimes: createUnsupportedFsMethod('utimes'),
+    writeFile: createUnsupportedFsMethod('writeFile'),
+};
 function openInBrowser(_url) {
     // Browser builds should decide how to surface URLs themselves.
 }
-export { EventEmitter, openInBrowser, process };
+export { EventEmitter, fs, openInBrowser, process };

package/dist/runtime-node.d.ts

@@ -2,7 +2,9 @@
  * Node.js runtime bindings for goke core.
  */
 import { EventEmitter } from 'events';
+import type { GokeFs } from './goke-fs.js';
 declare const process: NodeJS.Process;
+declare const fs: GokeFs;
 declare function openInBrowser(url: string): void;
-export { EventEmitter, openInBrowser, process };
+export { EventEmitter, fs, openInBrowser, process };
 //# sourceMappingURL=runtime-node.d.ts.map

package/dist/runtime-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-node.d.ts","sourceRoot":"","sources":["../src/runtime-node.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAErC,QAAA,MAAM,OAAO,gBAAqB,CAAA;AAElC,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiBxC;AAED,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,CAAA"}
+{"version":3,"file":"runtime-node.d.ts","sourceRoot":"","sources":["../src/runtime-node.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAErC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,QAAA,MAAM,OAAO,gBAAqB,CAAA;AAClC,QAAA,MAAM,EAAE,EAAE,MAAe,CAAA;AAEzB,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiBxC;AAED,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,CAAA"}

package/dist/runtime-node.js

@@ -3,7 +3,9 @@
  */
 import { execSync } from 'child_process';
 import { EventEmitter } from 'events';
+import * as nodeFs from 'node:fs/promises';
 const process = globalThis.process;
+const fs = nodeFs;
 function openInBrowser(url) {
     if (!process.stdout.isTTY) {
         process.stderr.write(url + '\n');
@@ -24,4 +26,4 @@ function openInBrowser(url) {
         process.stderr.write(url + '\n');
     }
 }
-export { EventEmitter, openInBrowser, process };
+export { EventEmitter, fs, openInBrowser, process };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.4.0",
+  "version": "6.5.1",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {
@@ -48,13 +48,12 @@
     "dist",
     "src"
   ],
-  "dependencies": {
-    "picocolors": "^1.1.1"
-  },
+  "dependencies": {},
   "author": "remorses, egoist <0x142857@gmail.com>",
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^25.2.2",
+    "just-bash": "^2.14.0",
     "typescript": "^5.9.3",
     "vitest": "^3.1.0",
     "zod": "^4.3.6"

package/src/__test__/index.test.ts

@@ -3,6 +3,9 @@ import goke, { createConsole } from '../index.js'
 import type { GokeOutputStream, GokeOptions } 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
 
@@ -157,6 +160,96 @@ describe('error formatting', () => {
   })
 })
 
+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: Record<string, string | undefined> = { 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()
 

package/src/__test__/just-bash.test.ts

@@ -72,7 +72,7 @@ describe('clone', () => {
 
     cli.command('build', 'Build').action(() => {})
 
-    const cloned = (cli as any).clone({ exit: () => {} })
+    const cloned = cli.clone({ exit: () => {} })
 
     cloned.parse(['node', 'bin', 'build'], { run: false })
 
@@ -93,7 +93,7 @@ describe('createJustBashCommand', () => {
         console.log(`hello ${options.name}`)
       })
 
-    const customCommand = await (cli as any).createJustBashCommand()
+    const customCommand = await cli.createJustBashCommand()
     const result = await customCommand.execute(['child', 'commandwithspaces', '--name', 'Tommy'])
 
     expect(result).toEqual({
@@ -103,6 +103,174 @@ describe('createJustBashCommand', () => {
     })
   })
 
+  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<string, string>([['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')
 
@@ -112,7 +280,7 @@ describe('createJustBashCommand', () => {
         process.exit(7)
       })
 
-    const customCommand = await (cli as any).createJustBashCommand()
+    const customCommand = await cli.createJustBashCommand()
     const result = await customCommand.execute(['fail'])
 
     expect(result).toEqual({

package/src/__test__/types.test-d.ts

@@ -119,10 +119,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<number>()
         expectTypeOf(options.host).toEqualTypeOf<string>()
+        expectTypeOf(fs.mkdir).toBeFunction()
         expectTypeOf(process.argv).toEqualTypeOf<string[]>()
+        expectTypeOf(process.cwd).toEqualTypeOf<string>()
+        expectTypeOf(process.env).toEqualTypeOf<Record<string, string | undefined>>()
+        expectTypeOf(process.stdin).toEqualTypeOf<string>()
         expectTypeOf(process.stdout.write).toEqualTypeOf<(data: string) => void>()
         expectTypeOf(console.log).toBeFunction()
       })
@@ -134,8 +138,9 @@ describe('type-level: middleware use() callback inference', () => {
 
     goke('test')
       .option('--verbose', schema1)
-      .use((options, { process }) => {
+      .use((options, { fs, process }) => {
         expectTypeOf(options.verbose).toEqualTypeOf<boolean | undefined>()
+        expectTypeOf(fs.writeFile).toBeFunction()
         expectTypeOf(process.exit).toEqualTypeOf<(code: number) => void>()
         // @ts-expect-error port is not declared yet
         options.port
@@ -154,7 +159,8 @@ describe('type-level: middleware use() callback inference', () => {
 
     goke('test')
       .option('--port <port>', schema)
-      .use((options, { process }) => {
+      .use((options, { fs, process }) => {
+        expectTypeOf(fs.readFile).toBeFunction()
         expectTypeOf(process.stderr.write).toEqualTypeOf<(data: string) => void>()
         // @ts-expect-error nonExistent was never defined
         options.nonExistent

package/src/goke-fs.ts

@@ -0,0 +1,26 @@
+/**
+ * Node-like filesystem types used by injected goke execution contexts.
+ */
+
+import type { MakeDirectoryOptions, Mode, PathLike, RmOptions, TimeLike } from 'node:fs'
+
+type GokeFsFileContent = string | NodeJS.ArrayBufferView
+type GokeFsEncodingOption = BufferEncoding | { encoding?: BufferEncoding | null }
+
+interface GokeFs {
+  appendFile(path: PathLike, data: GokeFsFileContent, options?: GokeFsEncodingOption): Promise<void>
+  chmod(path: PathLike, mode: Mode): Promise<void>
+  copyFile(src: PathLike, dest: PathLike): Promise<void>
+  link(existingPath: PathLike, newPath: PathLike): Promise<void>
+  mkdir(path: PathLike, options?: MakeDirectoryOptions): Promise<string | undefined>
+  readFile(path: PathLike, options?: GokeFsEncodingOption): Promise<string | Uint8Array>
+  readlink(path: PathLike): Promise<string>
+  realpath(path: PathLike): Promise<string>
+  rename(oldPath: PathLike, newPath: PathLike): Promise<void>
+  rm(path: PathLike, options?: RmOptions): Promise<void>
+  symlink(target: PathLike, path: PathLike): Promise<void>
+  utimes(path: PathLike, atime: TimeLike, mtime: TimeLike): Promise<void>
+  writeFile(path: PathLike, data: GokeFsFileContent, options?: GokeFsEncodingOption): Promise<void>
+}
+
+export type { GokeFs, GokeFsEncodingOption, GokeFsFileContent }