goke 6.3.2 → 6.5.0

package/src/goke.ts

@@ -10,11 +10,13 @@
  * - Utility functions: string helpers, bracket parsing, dot-prop access
  */
 
-import { EventEmitter } from 'events'
 import pc from 'picocolors'
 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 type { GokeFs } from './goke-fs.js'
+import { EventEmitter, fs as runtimeFs, openInBrowser, process } from '#runtime'
 
 // ─── Node.js platform constants ───
 
@@ -209,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
@@ -290,6 +293,10 @@ class Option {
       this.isBoolean = true
     }
   }
+
+  clone() {
+    return new Option(this.rawName, this.schema ?? this.description)
+  }
 }
 
 // ─── Command ───
@@ -766,6 +773,24 @@ class GlobalCommand extends Command {
   }
 }
 
+const cloneCommandInto = (source: Command, cli: Goke<any>) => {
+  const target = source instanceof GlobalCommand
+    ? new GlobalCommand(cli)
+    : new Command(source.rawName, source.description, { ...source.config }, cli)
+
+  target.aliasNames = [...source.aliasNames]
+  target.usageText = source.usageText
+  target.versionNumber = source.versionNumber
+  target.examples = [...source.examples]
+  target.helpCallback = source.helpCallback
+  target.commandAction = source.commandAction
+  target._hidden = source._hidden
+  target.options = source.options.map((option) => option.clone())
+  target.globalCommand = cli.globalCommand
+
+  return target
+}
+
 // ─── I/O interfaces ───
 
 /**
@@ -784,12 +809,48 @@ interface GokeOutputStream {
 interface GokeConsole {
   log(...args: unknown[]): void
   error(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  info(...args: unknown[]): void
+}
+
+interface GokeProcess {
+  argv: string[]
+  cwd: string
+  env: Record<string, string | undefined>
+  stdin: string
+  stdout: GokeOutputStream
+  stderr: GokeOutputStream
+  exit(code: number): never | void
+}
+
+interface GokeExecutionContext {
+  console: GokeConsole
+  fs: GokeFs
+  process: GokeProcess
+}
+
+class GokeProcessExit extends Error {
+  code: number
+
+  constructor(code: number) {
+    super(`process.exit(${code})`)
+    this.name = 'GokeProcessExit'
+    this.code = code
+  }
 }
 
 /**
  * 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 */
@@ -820,6 +881,12 @@ function createConsole(stdout: GokeOutputStream, stderr: GokeOutputStream): Goke
     error(...args: unknown[]) {
       stderr.write(args.map(String).join(' ') + '\n')
     },
+    warn(...args: unknown[]) {
+      stderr.write(args.map(String).join(' ') + '\n')
+    },
+    info(...args: unknown[]) {
+      stdout.write(args.map(String).join(' ') + '\n')
+    },
   }
 }
 
@@ -857,7 +924,7 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
   name: string
   commands: Command[]
   /** Middleware functions that run before the matched command action, in registration order */
-  middlewares: Array<{ action: (options: any) => void | Promise<void> }>
+  middlewares: Array<{ action: (options: any, context: GokeExecutionContext) => void | Promise<void> }>
   globalCommand: GlobalCommand
   matchedCommand?: Command
   matchedCommandName?: string
@@ -877,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 */
@@ -902,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)
@@ -912,6 +991,60 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
     this.globalCommand.usage('<command> [options]')
   }
 
+  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,
+      columns: options?.columns ?? this.columns,
+      exit: options?.exit ?? this.exit,
+    })
+
+    cloned.showHelpOnExit = this.showHelpOnExit
+    cloned.showVersionOnExit = this.showVersionOnExit
+    cloned.globalCommand = cloneCommandInto(this.globalCommand, cloned) as GlobalCommand
+    cloned.commands = this.commands.map((command) => cloneCommandInto(command, cloned))
+    for (const command of cloned.commands) {
+      command.globalCommand = cloned.globalCommand
+    }
+    cloned.middlewares = this.middlewares.map((middleware) => ({ action: middleware.action }))
+
+    for (const eventName of this.eventNames()) {
+      for (const listener of this.listeners(eventName)) {
+        cloned.on(eventName, listener)
+      }
+    }
+
+    return cloned
+  }
+
+  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) => {
+          this.exit(code)
+          throw new GokeProcessExit(code)
+        },
+      },
+    }
+  }
+
+  async createJustBashCommand(options?: { name?: string }) {
+    return createJustBashCommandBridge(this, options)
+  }
+
   /**
    * Add a global usage text.
    *
@@ -946,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
   }
 
@@ -958,20 +1092,21 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
    * options (e.g. setting up logging, initializing state).
    *
    * The callback receives the parsed options object, typed according to all
-   * `.option()` calls that precede this `.use()` in the chain.
+   * `.option()` calls that precede this `.use()` in the chain, plus an injected
+   * execution context with `{ console, process }` for portable output and exits.
    *
    * @example
    * ```ts
    * cli
    *   .option('--verbose', z.boolean().default(false).describe('Verbose'))
-   *   .use((options) => {
+   *   .use((options, { console }) => {
    *     if (options.verbose) {
-   *       process.env.LOG_LEVEL = 'debug'
+   *       console.log('verbose mode enabled')
    *     }
    *   })
    * ```
    */
-  use(callback: (options: Opts) => void | Promise<void>): this {
+  use(callback: (options: Opts, context: GokeExecutionContext) => void | Promise<void>): this {
     this.middlewares.push({ action: callback })
     return this
   }
@@ -1376,6 +1511,7 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
 
   runMatchedCommand() {
     const { args, options, matchedCommand: command } = this
+    const executionContext = this.createExecutionContext()
 
     if (!command || !command.commandAction) return
 
@@ -1400,6 +1536,7 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
       }
     })
     actionArgs.push(options)
+    actionArgs.push(executionContext)
 
     const executeAction = () => command.commandAction!.apply(this, actionArgs)
 
@@ -1419,62 +1556,53 @@ class Goke<Opts extends Record<string, any> = {}> extends EventEmitter {
 
     for (const mw of this.middlewares) {
       if (asyncChain) {
-        asyncChain = asyncChain.then(() => mw.action(options))
+        asyncChain = asyncChain.then(() => mw.action(options, executionContext))
       } else {
         try {
-          const mwResult = mw.action(options)
+          const mwResult = mw.action(options, executionContext)
           if (isPromiseLike(mwResult)) {
             asyncChain = mwResult as Promise<any>
           }
         } catch (err) {
+          if (err instanceof GokeProcessExit) {
+            throw err
+          }
           handleAsyncError(err)
           return
         }
       }
     }
 
-    const result = asyncChain
-      ? asyncChain.then(executeAction)
-      : executeAction()
-
-    // If the result is a promise, catch async errors
-    if (isPromiseLike(result)) {
-      (result as Promise<any>).catch(handleAsyncError)
+    const catchAsyncError = (err: unknown) => {
+      if (err instanceof GokeProcessExit) {
+        throw err
+      }
+      handleAsyncError(err)
     }
 
-    return result
-  }
-}
-
-// ─── openInBrowser ───
+    if (asyncChain) {
+      return asyncChain
+        .then(executeAction)
+        .catch(catchAsyncError)
+    }
 
-/**
- * Open a URL in the default browser.
- * In non-TTY environments (CI, piped output, agents), prints the URL to stdout instead.
- */
-function openInBrowser(url: string): void {
-  if (!process.stdout.isTTY) {
-    console.error(url)
-    return
-  }
-  const { execSync } = require('child_process') as typeof import('child_process')
-  const platform = process.platform
-  try {
-    if (platform === 'darwin') {
-      execSync(`open ${JSON.stringify(url)}`, { stdio: 'ignore' })
-    } else if (platform === 'win32') {
-      execSync(`start "" ${JSON.stringify(url)}`, { stdio: 'ignore' })
-    } else {
-      execSync(`xdg-open ${JSON.stringify(url)}`, { stdio: 'ignore' })
+    try {
+      const result = executeAction()
+      return isPromiseLike(result)
+        ? (result as Promise<any>).catch(catchAsyncError)
+        : result
+    } catch (err) {
+      if (err instanceof GokeProcessExit) {
+        throw err
+      }
+      handleAsyncError(err)
+      return
     }
-  } catch {
-    // fallback: print the URL if open fails
-    console.error(url)
   }
 }
 
 // ─── Exports ───
 
-export type { GokeOutputStream, GokeConsole, GokeOptions }
-export { createConsole, Command, openInBrowser }
+export type { GokeOutputStream, GokeConsole, GokeOptions, GokeProcess, GokeExecutionContext, GokeFs }
+export { createConsole, Command, GokeProcessExit, openInBrowser }
 export default Goke

package/src/index.ts

@@ -10,7 +10,7 @@ const goke = (name = '', options?: GokeOptions) => new Goke(name, options)
 
 export default goke
 export { goke, Goke, Command }
-export { createConsole, openInBrowser } from "./goke.js"
-export type { GokeOutputStream, GokeConsole, GokeOptions } from "./goke.js"
+export { createConsole, GokeProcessExit, openInBrowser } 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

@@ -0,0 +1,275 @@
+/**
+ * Runtime adapter that exposes a goke CLI as a JustBash-compatible custom command.
+ *
+ * Structural types here are based on JustBash source definitions:
+ * - https://github.com/vercel-labs/just-bash/blob/main/src/custom-commands.ts
+ * - 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
+  stderr: string
+  exitCode: number
+}
+
+interface JustBashCommand {
+  name: string
+  trusted: true
+  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 {
+    get text() {
+      return chunks.join('')
+    },
+    write(data: string) {
+      chunks.push(data)
+    },
+  }
+}
+
+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 }
+): JustBashCommand {
+  const name = options?.name ?? cli.name
+
+  if (!name) {
+    throw new Error('createJustBashCommand() requires the CLI to have a name')
+  }
+
+  if (name.split(/\s+/).length > 1) {
+    throw new Error('JustBash custom command names must be a single token')
+  }
+
+  return {
+    name,
+    trusted: true,
+    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,
+        exit: (code) => {
+          throw new GokeProcessExit(code)
+        },
+      })
+
+      cloned.name = name
+
+      try {
+        cloned.parse(argv, { run: false })
+        await cloned.runMatchedCommand()
+        return {
+          stdout: stdout.text,
+          stderr: stderr.text,
+          exitCode: 0,
+        }
+      } catch (error) {
+        if (error instanceof GokeProcessExit) {
+          return {
+            stdout: stdout.text,
+            stderr: stderr.text,
+            exitCode: error.code,
+          }
+        }
+        throw error
+      }
+    },
+  }
+}
+
+export type { JustBashCommand, JustBashExecResult }