goke 6.4.0 → 6.5.1

package/src/goke.ts

@@ -10,12 +10,13 @@
  * - Utility functions: string helpers, bracket parsing, dot-prop access
  */
 
-import pc from 'picocolors'
+import pc from './picocolors.js'
 import mri from "./mri.js"
 import { GokeError, coerceBySchema, extractJsonSchema, extractSchemaMetadata, isStandardSchema } from "./coerce.js"
 import type { StandardJSONSchemaV1 } from "./coerce.js"
 import { createJustBashCommand as createJustBashCommandBridge } from './just-bash.js'
-import { EventEmitter, openInBrowser, process } from '#runtime'
+import type { GokeFs } from './goke-fs.js'
+import { EventEmitter, fs as runtimeFs, openInBrowser, process } from '#runtime'
 
 // ─── Node.js platform constants ───
 
@@ -210,7 +211,8 @@ const getFileName = (input: string) => {
 const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
   value != null
   && (typeof value === 'object' || typeof value === 'function')
-  && typeof (value as any).then === 'function'
+  && 'then' in value
+  && typeof value.then === 'function'
 
 const camelcaseOptionName = (name: string) => {
   // Camelcase the option name
@@ -813,6 +815,9 @@ interface GokeConsole {
 
 interface GokeProcess {
   argv: string[]
+  cwd: string
+  env: Record<string, string | undefined>
+  stdin: string
   stdout: GokeOutputStream
   stderr: GokeOutputStream
   exit(code: number): never | void
@@ -820,6 +825,7 @@ interface GokeProcess {
 
 interface GokeExecutionContext {
   console: GokeConsole
+  fs: GokeFs
   process: GokeProcess
 }
 
@@ -837,6 +843,14 @@ class GokeProcessExit extends Error {
  * Options for configuring a Goke CLI instance.
  */
 interface GokeOptions {
+  /** Custom cwd value exposed through the injected process context. */
+  cwd?: string
+  /** Custom environment exposed through the injected process context. */
+  env?: Record<string, string | undefined>
+  /** Custom fs implementation. Defaults to node:fs/promises in Node runtimes. */
+  fs?: GokeFs
+  /** Custom stdin content exposed through the injected process context. */
+  stdin?: string
   /** Custom stdout stream. Defaults to process.stdout */
   stdout?: GokeOutputStream
   /** Custom stderr stream. Defaults to process.stderr */
@@ -930,6 +944,14 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   showHelpOnExit?: boolean
   showVersionOnExit?: boolean
 
+  /** Working directory exposed through the injected process context. */
+  readonly cwd?: string
+  /** Environment exposed through the injected process context. */
+  readonly env?: Record<string, string | undefined>
+  /** Output stream for normal output (help, version, etc.) */
+  readonly fs: GokeFs
+  /** Standard input exposed through the injected process context. */
+  readonly stdin?: string
   /** Output stream for normal output (help, version, etc.) */
   readonly stdout: GokeOutputStream
   /** Output stream for error output */
@@ -955,6 +977,10 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
     this.rawArgs = []
     this.args = []
     this.options = {}
+    this.cwd = options?.cwd
+    this.env = options?.env
+    this.fs = options?.fs ?? runtimeFs
+    this.stdin = options?.stdin
     this.stdout = options?.stdout ?? process.stdout
     this.stderr = options?.stderr ?? process.stderr
     this.console = createConsole(this.stdout, this.stderr)
@@ -967,6 +993,10 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
 
   clone(options?: GokeOptions) {
     const cloned = new Goke<Opts>(this.name, {
+      cwd: options?.cwd ?? this.cwd,
+      env: options?.env ?? this.env,
+      fs: options?.fs ?? this.fs,
+      stdin: options?.stdin ?? this.stdin,
       stdout: options?.stdout ?? this.stdout,
       stderr: options?.stderr ?? this.stderr,
       argv: options?.argv ?? this.#defaultArgv,
@@ -995,8 +1025,12 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   private createExecutionContext(argv = this.rawArgs): GokeExecutionContext {
     return {
       console: this.console,
+      fs: this.fs,
       process: {
         argv,
+        cwd: this.cwd ?? process.cwd(),
+        env: this.env ?? process.env,
+        stdin: this.stdin ?? '',
         stdout: this.stdout,
         stderr: this.stderr,
         exit: (code: number) => {
@@ -1045,7 +1079,8 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   >(rawName: RawName, schema: S): Goke<Opts & OptionEntry<RawName, S>>
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): this
   option(rawName: string, descriptionOrSchema?: string | StandardJSONSchemaV1): any {
-    this.globalCommand.option(rawName, descriptionOrSchema as any)
+    const option = new Option(rawName, descriptionOrSchema)
+    this.globalCommand.options.push(option)
     return this
   }
 
@@ -1568,6 +1603,6 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
 
 // ─── Exports ───
 
-export type { GokeOutputStream, GokeConsole, GokeOptions, GokeProcess, GokeExecutionContext }
+export type { GokeOutputStream, GokeConsole, GokeOptions, GokeProcess, GokeExecutionContext, GokeFs }
 export { createConsole, Command, GokeProcessExit, openInBrowser }
 export default Goke

package/src/index.ts

@@ -11,6 +11,6 @@ const goke = (name = '', options?: GokeOptions) => new Goke(name, options)
 export default goke
 export { goke, Goke, Command }
 export { createConsole, GokeProcessExit, openInBrowser } from "./goke.js"
-export type { GokeOutputStream, GokeConsole, GokeExecutionContext, GokeOptions, GokeProcess } from "./goke.js"
+export type { GokeOutputStream, GokeConsole, GokeExecutionContext, GokeFs, GokeOptions, GokeProcess } from "./goke.js"
 export type { StandardTypedV1, StandardJSONSchemaV1, JsonSchema } from "./coerce.js"
 export { GokeError, coerceBySchema, extractJsonSchema, wrapJsonSchema, isStandardSchema, extractSchemaMetadata } from "./coerce.js"

package/src/just-bash.ts

@@ -6,8 +6,13 @@
  * - https://github.com/vercel-labs/just-bash/blob/main/src/types.ts
  */
 
+import { Buffer } from 'node:buffer'
+import { fileURLToPath } from 'node:url'
+import type { PathLike } from 'node:fs'
+import type { CommandContext, IFileSystem } from 'just-bash'
 import Goke, { GokeProcessExit } from './goke.js'
 import type { GokeOutputStream } from './goke.js'
+import type { GokeFs, GokeFsEncodingOption, GokeFsFileContent } from './goke-fs.js'
 
 interface JustBashExecResult {
   stdout: string
@@ -18,9 +23,12 @@ interface JustBashExecResult {
 interface JustBashCommand {
   name: string
   trusted: true
-  execute(args: string[]): Promise<JustBashExecResult>
+  execute(args: string[], context?: JustBashExecutionContext): Promise<JustBashExecResult>
 }
 
+type JustBashExecutionContext = Pick<CommandContext, 'cwd' | 'env' | 'fs' | 'stdin'>
+type JustBashEncoding = 'utf8' | 'utf-8' | 'ascii' | 'binary' | 'base64' | 'hex' | 'latin1'
+
 function createTextCaptureStream(): GokeOutputStream & { readonly text: string } {
   const chunks: string[] = []
   return {
@@ -33,6 +41,179 @@ function createTextCaptureStream(): GokeOutputStream & { readonly text: string }
   }
 }
 
+const resolveJustBashPath = (fs: IFileSystem, cwd: string, path: PathLike) => {
+  if (path instanceof URL) {
+    return fileURLToPath(path)
+  }
+  return fs.resolvePath(cwd, path.toString())
+}
+
+const getEncoding = (options?: GokeFsEncodingOption) => {
+  if (typeof options === 'string' || options == null) {
+    return options
+  }
+  return options.encoding
+}
+
+const toJustBashEncoding = (encoding?: BufferEncoding | null): JustBashEncoding | null | undefined => {
+  if (encoding == null) {
+    return encoding
+  }
+
+  switch (encoding) {
+    case 'utf8':
+    case 'utf-8':
+    case 'ascii':
+    case 'binary':
+    case 'base64':
+    case 'hex':
+    case 'latin1':
+      return encoding
+    default:
+      throw new Error(`Encoding ${encoding} is not supported by the JustBash fs adapter`)
+  }
+}
+
+const toJustBashContent = (content: GokeFsFileContent) => {
+  if (typeof content === 'string' || content instanceof Uint8Array) {
+    return content
+  }
+  return new Uint8Array(content.buffer, content.byteOffset, content.byteLength)
+}
+
+const toDate = (value: Date | string | number) => {
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) {
+    throw new Error(`Invalid time value: ${String(value)}`)
+  }
+  return date
+}
+
+function createJustBashEnvProxy(env: Map<string, string>): Record<string, string | undefined> {
+  return new Proxy(Object.create(null) as Record<string, string | undefined>, {
+    deleteProperty(_target, property) {
+      if (typeof property === 'string') {
+        env.delete(property)
+      }
+      return true
+    },
+    get(_target, property) {
+      if (typeof property !== 'string') return undefined
+      return env.get(property)
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      if (typeof property !== 'string') return undefined
+      const value = env.get(property)
+      if (value === undefined) return undefined
+      return {
+        configurable: true,
+        enumerable: true,
+        value,
+        writable: true,
+      }
+    },
+    has(_target, property) {
+      return typeof property === 'string' && env.has(property)
+    },
+    ownKeys() {
+      return [...env.keys()]
+    },
+    set(_target, property, value) {
+      if (typeof property === 'string') {
+        if (value === undefined) {
+          env.delete(property)
+        } else {
+          env.set(property, String(value))
+        }
+      }
+      return true
+    },
+  })
+}
+
+function createJustBashFs(fs: IFileSystem, cwd: string): GokeFs {
+  const readFile: GokeFs['readFile'] = async (path, options) => {
+    const resolvedPath = resolveJustBashPath(fs, cwd, path)
+    const encoding = toJustBashEncoding(getEncoding(options))
+    if (encoding == null) {
+      return Buffer.from(await fs.readFileBuffer(resolvedPath))
+    }
+    return fs.readFile(resolvedPath, encoding)
+  }
+
+  const writeFile: GokeFs['writeFile'] = async (path, content, options) => {
+    const resolvedPath = resolveJustBashPath(fs, cwd, path)
+    const encoding = toJustBashEncoding(getEncoding(options)) ?? undefined
+    await fs.writeFile(resolvedPath, toJustBashContent(content), encoding)
+  }
+
+  const appendFile: GokeFs['appendFile'] = async (path, content, options) => {
+    const resolvedPath = resolveJustBashPath(fs, cwd, path)
+    const encoding = toJustBashEncoding(getEncoding(options)) ?? undefined
+    await fs.appendFile(resolvedPath, toJustBashContent(content), encoding)
+  }
+
+  const mkdir: GokeFs['mkdir'] = async (path, options) => {
+    await fs.mkdir(resolveJustBashPath(fs, cwd, path), { recursive: typeof options === 'object' ? options.recursive : undefined })
+    return undefined
+  }
+
+  const rm: GokeFs['rm'] = async (path, options) => {
+    await fs.rm(resolveJustBashPath(fs, cwd, path), {
+      recursive: options?.recursive,
+      force: options?.force,
+    })
+  }
+
+  const rename: GokeFs['rename'] = async (oldPath, newPath) => {
+    await fs.mv(resolveJustBashPath(fs, cwd, oldPath), resolveJustBashPath(fs, cwd, newPath))
+  }
+
+  const copyFile: GokeFs['copyFile'] = async (src, dest) => {
+    await fs.cp(resolveJustBashPath(fs, cwd, src), resolveJustBashPath(fs, cwd, dest))
+  }
+
+  const chmod: GokeFs['chmod'] = async (path, mode) => {
+    await fs.chmod(resolveJustBashPath(fs, cwd, path), Number(mode))
+  }
+
+  const link: GokeFs['link'] = async (existingPath, newPath) => {
+    await fs.link(resolveJustBashPath(fs, cwd, existingPath), resolveJustBashPath(fs, cwd, newPath))
+  }
+
+  const readlink: GokeFs['readlink'] = async (path) => {
+    return fs.readlink(resolveJustBashPath(fs, cwd, path))
+  }
+
+  const realpath: GokeFs['realpath'] = async (path) => {
+    return fs.realpath(resolveJustBashPath(fs, cwd, path))
+  }
+
+  const symlink: GokeFs['symlink'] = async (target, path) => {
+    await fs.symlink(target.toString(), resolveJustBashPath(fs, cwd, path))
+  }
+
+  const utimes: GokeFs['utimes'] = async (path, atime, mtime) => {
+    await fs.utimes(resolveJustBashPath(fs, cwd, path), toDate(atime), toDate(mtime))
+  }
+
+  return {
+    appendFile,
+    chmod,
+    copyFile,
+    link,
+    mkdir,
+    readFile,
+    readlink,
+    realpath,
+    rename,
+    rm,
+    symlink,
+    utimes,
+    writeFile,
+  }
+}
+
 export function createJustBashCommand(
   cli: Goke<any>,
   options?: { name?: string }
@@ -50,11 +231,15 @@ export function createJustBashCommand(
   return {
     name,
     trusted: true,
-    async execute(args: string[]) {
+    async execute(args: string[], context?: JustBashExecutionContext) {
       const stdout = createTextCaptureStream()
       const stderr = createTextCaptureStream()
       const argv = ['node', name, ...args]
       const cloned = cli.clone({
+        cwd: context?.cwd,
+        env: context ? createJustBashEnvProxy(context.env) : cli.env,
+        fs: context ? createJustBashFs(context.fs, context.cwd) : cli.fs,
+        stdin: context?.stdin,
         stdout,
         stderr,
         argv,

package/src/picocolors.ts

@@ -0,0 +1,140 @@
+/**
+ * Vendored from picocolors by Alexey Raspopov (MIT license).
+ * Source: https://github.com/alexeyraspopov/picocolors/blob/main/picocolors.js
+ */
+
+import { process } from '#runtime'
+
+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
+}
+
+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: string, close: string, replace: string, index: number) => {
+  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: string, close: string, replace = open): Formatter =>
+  (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): PicoColors => {
+  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 type { PicoColors }
+export default pc

package/src/runtime-browser.ts

@@ -2,6 +2,8 @@
  * Browser-safe runtime stubs for goke core.
  */
 
+import type { GokeFs } from './goke-fs.js'
+
 type Listener = (...args: any[]) => void
 
 class EventEmitter {
@@ -41,6 +43,10 @@ const createOutputStream = () => ({
 const process = {
   argv: [] as string[],
   arch: 'browser',
+  cwd() {
+    return '/'
+  },
+  env: Object.create(null) as Record<string, string | undefined>,
   platform: 'browser',
   version: 'browser',
   stdout: createOutputStream(),
@@ -52,8 +58,36 @@ const process = {
   },
 }
 
+function createBrowserFsError(methodName: string) {
+  return new Error(
+    `fs.${methodName}() is not available in the browser runtime. Pass a custom fs implementation to goke(...).`
+  )
+}
+
+function createUnsupportedFsMethod<T>(methodName: string): T {
+  return (async () => {
+    throw createBrowserFsError(methodName)
+  }) as T
+}
+
+const fs: GokeFs = {
+  appendFile: createUnsupportedFsMethod<GokeFs['appendFile']>('appendFile'),
+  chmod: createUnsupportedFsMethod<GokeFs['chmod']>('chmod'),
+  copyFile: createUnsupportedFsMethod<GokeFs['copyFile']>('copyFile'),
+  link: createUnsupportedFsMethod<GokeFs['link']>('link'),
+  mkdir: createUnsupportedFsMethod<GokeFs['mkdir']>('mkdir'),
+  readFile: createUnsupportedFsMethod<GokeFs['readFile']>('readFile'),
+  readlink: createUnsupportedFsMethod<GokeFs['readlink']>('readlink'),
+  realpath: createUnsupportedFsMethod<GokeFs['realpath']>('realpath'),
+  rename: createUnsupportedFsMethod<GokeFs['rename']>('rename'),
+  rm: createUnsupportedFsMethod<GokeFs['rm']>('rm'),
+  symlink: createUnsupportedFsMethod<GokeFs['symlink']>('symlink'),
+  utimes: createUnsupportedFsMethod<GokeFs['utimes']>('utimes'),
+  writeFile: createUnsupportedFsMethod<GokeFs['writeFile']>('writeFile'),
+}
+
 function openInBrowser(_url: string): void {
   // Browser builds should decide how to surface URLs themselves.
 }
 
-export { EventEmitter, openInBrowser, process }
+export { EventEmitter, fs, openInBrowser, process }

package/src/runtime-node.ts

@@ -4,8 +4,11 @@
 
 import { execSync } from 'child_process'
 import { EventEmitter } from 'events'
+import * as nodeFs from 'node:fs/promises'
+import type { GokeFs } from './goke-fs.js'
 
 const process = globalThis.process
+const fs: GokeFs = nodeFs
 
 function openInBrowser(url: string): void {
   if (!process.stdout.isTTY) {
@@ -26,4 +29,4 @@ function openInBrowser(url: string): void {
   }
 }
 
-export { EventEmitter, openInBrowser, process }
+export { EventEmitter, fs, openInBrowser, process }