@nimbus-sh/worker 0.1.5 → 0.1.6

package/dist/runtime/ruby-runner.d.ts

@@ -11,9 +11,7 @@
  *
  * Out of v1:
  *   - REPL mode (`ruby` with no args)
- *   - require_relative for non-bundled files (basic require for
- *     stdlib works since stdlib is wasi-vfs-packed inside the wasm)
- *   - gems, bundler
+ *   - native extension gems
  *   - js-runtime bindings (gem "js") — those imports are stubbed
  *     and will raise NotImplementedError if Ruby code tries to use
  *     them
@@ -57,5 +55,5 @@ export declare function makeRubyRunnerFactory(deps: {
  * stderr capture buffers, and invokes rb-eval-string-protect with a
  * wrapper that captures SystemExit to extract the exit code.
  */
-export declare const RUBY_RUNNER_PREAMBLE_TAIL = "\n// \u2500\u2500 BEGIN: ruby-runner preamble (Ruby 3.3.4, Nimbus v1) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n// Capture buffers shared across the bootstrap and per-call paths. The\n// preamble's WASI imports route fd_write stdout/stderr into these via\n// __wasiMakeImports({stdoutWrite, stderrWrite}). Per-call __rubyRun\n// slices from these to isolate output per invocation.\nglobalThis.__nimbusRubyStdout = globalThis.__nimbusRubyStdout || [];\nglobalThis.__nimbusRubyStderr = globalThis.__nimbusRubyStderr || [];\n\n// \u2500\u2500 Canonical-ABI resource Slab \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Pyodide-style minimal resource manager. Ruby's rb-abi-guest.js uses\n// these 4 functions for resource_drop / resource_new / resource_get /\n// resource_clone, but the wasm itself only imports 3:\n//   resource_drop_js-abi-value, resource_new_rb-abi-value, resource_get_rb-abi-value\nclass __NimbusRubySlab {\n  constructor() { this._map = new Map(); this._next = 1; }\n  insert(obj) { const id = this._next++; this._map.set(id, obj); return id; }\n  get(id) { return this._map.get(id); }\n  remove(id) { const v = this._map.get(id); this._map.delete(id); return v; }\n}\n\n// \u2500\u2500 Bootstrap promise: runs at child-facet module-init time \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Mirrors pyodide v2's __pyodideBootstrap pattern. The synchronous\n// portion (WebAssembly.instantiate + _initialize + ruby-init-loadpath\n// + ruby-init) all completes before the first await \u2014 so it executes\n// in module-init CSP context where workerd permits wasm code-gen\n// from the LOADER-provided Module.\nglobalThis.__rubyBootstrap = (async function nimbusRubyBootstrap() {\n  const wasmTable = globalThis.__NIMBUS_WASM || {};\n  const rubyMod = wasmTable['ruby+stdlib.wasm'];\n  if (!rubyMod) {\n    return { ok: false, error: '__NIMBUS_WASM missing ruby+stdlib.wasm' };\n  }\n\n  // WASI init \u2014 empty preopens initially. Per-call __rubyRun can mount\n  // a cwd preopen if needed (for ruby <file.rb> reading via WASI).\n  // For v1 (-e mode) we just need stdout/stderr capture + a minimal\n  // FS so Ruby's stdlib init (which probes /tmp + $HOME) doesn't crash.\n  __wasiInitFS({\n    root: '',\n    preopens: [\n      // Preopen / so Ruby can resolve all FS paths through WASI.\n      // Ruby's __wasi_vfs_rt_init mounts its packed stdlib under /usr\n      // inside the wasm's internal VFS \u2014 these preopens are for the\n      // OUTER (host-visible) FS that wasi_snapshot_preview1 exposes.\n      { wasiPath: '/',        vfsPath: '' },\n      { wasiPath: '/tmp',     vfsPath: 'tmp' },\n      { wasiPath: '/home',    vfsPath: 'home' },\n    ],\n    files: {},\n    dirs: ['tmp', 'home'],\n  });\n\n  // Initial argv/env (bootstrap defaults). Per-call __rubyRun re-\n  // initializes WASI with the actual user argv/env before evaluating\n  // user code.\n  let memRef = null;\n  const wasi = __wasiMakeImports({\n    argv: ['ruby'],\n    env: { HOME: '/home/ruby', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },\n    getMemory: () => memRef,\n    stdoutWrite: (s) => { globalThis.__nimbusRubyStdout.push(s); },\n    stderrWrite: (s) => { globalThis.__nimbusRubyStderr.push(s); },\n  });\n\n  // canonical_abi imports \u2014 3 resource lifecycle fns. The Slab is\n  // shared across the lifetime of the facet (single call, then the\n  // facet is reaped).\n  const rbValueSlab = new __NimbusRubySlab();\n  const jsValueSlab = new __NimbusRubySlab();\n  const canonical_abi = {\n    'resource_drop_js-abi-value': (i) => { jsValueSlab.remove(i); },\n    'resource_new_rb-abi-value': (i) => rbValueSlab.insert({ _wasm_val: i }),\n    'resource_get_rb-abi-value': (i) => {\n      const r = rbValueSlab.get(i);\n      return r ? r._wasm_val : 0;\n    },\n  };\n\n  // rb-js-abi-host imports \u2014 21 fns. Ruby only calls these when user\n  // code interacts with JS (gem \"js\"). For v1 (puts \"hi\") none fire.\n  // We stub each to throw a clear error so any future user code that\n  // needs JS interop gets a recognizable diagnostic instead of a\n  // wasm trap.\n  const _stub = (name) => () => { throw new Error('ruby-runner v1: rb-js-abi-host.' + name + ' not implemented (gem \"js\" not supported)'); };\n  const rb_js_abi_host = {\n    rb_wasm_throw_prohibit_rewind_exception: () => {\n      // This one CAN fire from Ruby internals (Fiber rewind guard).\n      // Make it a no-op so Ruby's continuation machinery proceeds.\n    },\n    'eval-js: func(code: string) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('eval-js'),\n    'is-js: func(value: handle<js-abi-value>) -> bool': _stub('is-js'),\n    'instance-of: func(value: handle<js-abi-value>, klass: handle<js-abi-value>) -> bool': _stub('instance-of'),\n    'global-this: func() -> handle<js-abi-value>': _stub('global-this'),\n    'int-to-js-number: func(value: s32) -> handle<js-abi-value>': _stub('int-to-js-number'),\n    'float-to-js-number: func(value: float64) -> handle<js-abi-value>': _stub('float-to-js-number'),\n    'string-to-js-string: func(value: string) -> handle<js-abi-value>': _stub('string-to-js-string'),\n    'bool-to-js-bool: func(value: bool) -> handle<js-abi-value>': _stub('bool-to-js-bool'),\n    'proc-to-js-function: func(value: u32) -> handle<js-abi-value>': _stub('proc-to-js-function'),\n    'rb-object-to-js-rb-value: func(raw-rb-abi-value: u32) -> handle<js-abi-value>': _stub('rb-object-to-js-rb-value'),\n    'js-value-to-string: func(value: handle<js-abi-value>) -> string': _stub('js-value-to-string'),\n    'js-value-to-integer: func(value: handle<js-abi-value>) -> variant { as-float(float64), bignum(string) }': _stub('js-value-to-integer'),\n    'export-js-value-to-host: func(value: handle<js-abi-value>) -> ()': _stub('export-js-value-to-host'),\n    'import-js-value-from-host: func() -> handle<js-abi-value>': _stub('import-js-value-from-host'),\n    'js-value-typeof: func(value: handle<js-abi-value>) -> string': _stub('js-value-typeof'),\n    'js-value-equal: func(lhs: handle<js-abi-value>, rhs: handle<js-abi-value>) -> bool': _stub('js-value-equal'),\n    'js-value-strictly-equal: func(lhs: handle<js-abi-value>, rhs: handle<js-abi-value>) -> bool': _stub('js-value-strictly-equal'),\n    'reflect-apply: func(target: handle<js-abi-value>, this-argument: handle<js-abi-value>, arguments: list<handle<js-abi-value>>) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-apply'),\n    'reflect-get: func(target: handle<js-abi-value>, property-key: string) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-get'),\n    'reflect-set: func(target: handle<js-abi-value>, property-key: string, value: handle<js-abi-value>) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-set'),\n  };\n\n  const imports = {\n    wasi_snapshot_preview1: wasi.wasiImport,\n    canonical_abi,\n    'rb-js-abi-host': rb_js_abi_host,\n  };\n\n  let instance;\n  try {\n    const result = await WebAssembly.instantiate(rubyMod, imports);\n    instance = (result instanceof WebAssembly.Instance ? result : result.instance);\n  } catch (e) {\n    return { ok: false, error: 'WebAssembly.instantiate failed: ' + (e && e.message), stack: e && e.stack };\n  }\n  memRef = instance.exports.memory;\n\n  // \u2500\u2500 Ruby bootstrap sequence \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // Order matters (per ruby.wasm DefaultRubyVM):\n  //   1. _initialize (reactor entry; runs static initializers)\n  //   2. __wasi_vfs_rt_init (mount packed stdlib at the wasi-vfs's\n  //      internal FS \u2014 needed for require to find Ruby's *.rb files)\n  //   3. ruby-init([progName])  \u2014 initialize VM with argv[0]\n  //   4. ruby-init-loadpath()   \u2014 set $LOAD_PATH from packed stdlib\n  try {\n    if (typeof instance.exports._initialize === 'function') {\n      instance.exports._initialize();\n    }\n    if (typeof instance.exports.__wasi_vfs_rt_init === 'function') {\n      instance.exports.__wasi_vfs_rt_init();\n    }\n  } catch (e) {\n    return { ok: false, error: '_initialize/wasi_vfs_rt_init failed: ' + (e && e.message), stack: e && e.stack };\n  }\n\n  // Locate the canonical Ruby ABI exports. Names embed the WIT\n  // signature literal (e.g. 'ruby-init: func(args: list<string>) -> ()')\n  // because rb-abi-guest is wit-bindgen-generated.\n  const rubyInit = instance.exports['ruby-init: func(args: list<string>) -> ()'];\n  const rubyInitLoadpath = instance.exports['ruby-init-loadpath: func() -> ()'];\n  const rbEvalStringProtect = instance.exports['rb-eval-string-protect: func(str: string) -> tuple<handle<rb-abi-value>, s32>'];\n  const rubyShowVersion = instance.exports['ruby-show-version: func() -> ()'];\n  const cabiRealloc = instance.exports.cabi_realloc;\n  if (!rubyInit || !rubyInitLoadpath || !rbEvalStringProtect || !cabiRealloc) {\n    return { ok: false, error: 'Required Ruby ABI exports missing (ruby-init/init-loadpath/eval-string-protect/cabi_realloc)' };\n  }\n\n  // Encode a list<string> argument for ruby-init. WIT canonical-ABI\n  // shape: caller allocates list buffer; each element is (ptr, len).\n  // Strings are UTF-8 encoded into separately-allocated buffers.\n  function writeListString(strings) {\n    const memory = instance.exports.memory;\n    const enc = new TextEncoder();\n    const len = strings.length;\n    const listBufPtr = cabiRealloc(0, 0, 4, len * 8);  // align=4, size=len*8\n    const encoded = strings.map((s) => enc.encode(s));\n    for (let i = 0; i < len; i++) {\n      const bytes = encoded[i];\n      const strPtr = cabiRealloc(0, 0, 1, bytes.length);\n      new Uint8Array(memory.buffer).set(bytes, strPtr);\n      const dv = new DataView(memory.buffer);\n      dv.setUint32(listBufPtr + i * 8 + 0, strPtr, true);\n      dv.setUint32(listBufPtr + i * 8 + 4, bytes.length, true);\n    }\n    return { ptr: listBufPtr, len };\n  }\n\n  function writeString(s) {\n    const memory = instance.exports.memory;\n    const enc = new TextEncoder();\n    const bytes = enc.encode(s);\n    const ptr = cabiRealloc(0, 0, 1, bytes.length);\n    new Uint8Array(memory.buffer).set(bytes, ptr);\n    return { ptr, len: bytes.length };\n  }\n\n  // NOTE: We DO NOT call ruby-init or ruby-init-loadpath here. Both\n  // invoke CPython-like random-seed initialization (random_get via\n  // wasi_snapshot_preview1.random_get), which workerd blocks in the\n  // global-scope (module-init) context. Same constraint that bit us\n  // for Pyodide v2 P21. The per-call __rubyRun runs them at request-\n  // handler time where crypto.getRandomValues is permitted.\n  //\n  // _initialize and __wasi_vfs_rt_init are safe at module-init because\n  // they only do static initialization (no entropy reads).\n\n  return {\n    ok: true,\n    instance,\n    wasi,\n    rubyInit,\n    rubyInitLoadpath,\n    rbEvalStringProtect,\n    rubyShowVersion,\n    writeListString,\n    writeString,\n    rubyInitialized: false,  // mutated to true by __rubyRun on first call\n  };\n})();\n\n// \u2500\u2500 Per-call entry point \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Invoked from the LOADER child facet's execute() (which calls the\n// serialized facetFn that does globalThis.__rubyRun(args)).\n//\n// At this point the bootstrap promise has resolved (since it's\n// awaited inside the child facet's module-init context \u2014 the\n// instantiate finishes before the request handler runs). We:\n//   1. Update Ruby's $0 / $PROGRAM_NAME / ARGV via rb-eval-string-protect\n//   2. Wrap the user code in a begin/rescue SystemExit/StandardError\n//      handler so we can extract exit code without losing stdout\n//   3. Read stdout/stderr buffers and slice from the per-call start\nglobalThis.__rubyRun = async function __rubyRun(args) {\n  const stdoutStart = globalThis.__nimbusRubyStdout.length;\n  const stderrStart = globalThis.__nimbusRubyStderr.length;\n\n  const boot = await globalThis.__rubyBootstrap;\n  if (!boot.ok) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'ruby bootstrap failed: ' + (boot.error || 'unknown') + (boot.stack ? ' [stack=' + boot.stack + ']' : ''),\n    };\n  }\n\n  // First call into __rubyRun: complete Ruby VM init (ruby-init +\n  // ruby-init-loadpath) now that we're in request-handler context\n  // where crypto.getRandomValues is permitted. Subsequent calls skip.\n  if (!boot.rubyInitialized) {\n    try {\n      const initArgs = boot.writeListString(['ruby', '-e_=0']);\n      boot.rubyInit(initArgs.ptr, initArgs.len);\n      boot.rubyInitLoadpath();\n      boot.rubyInitialized = true;\n    } catch (e) {\n      return {\n        exitCode: 1,\n        stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n        stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n        error: 'ruby-init / ruby-init-loadpath failed at request time: ' + (e && e.message),\n      };\n    }\n  }\n\n  // Wrapper code: set $0/$PROGRAM_NAME/ARGV/ENV, run user code,\n  // capture SystemExit. We embed the user code as a Ruby string\n  // literal via JSON.stringify (Ruby's double-quote strings accept\n  // \\n \\t etc which JSON also emits \u2014 safe round-trip).\n  //\n  // The wrapper sets __NIMBUS_RUBY_EXIT to the desired exit code so\n  // we can read it via a second rb-eval-string-protect call. Failing\n  // SystemExit (raise) ends up with __NIMBUS_RUBY_EXIT = 1 + stderr\n  // message.\n  const userCodeRb = JSON.stringify(args.userCode);\n  const argvRb = JSON.stringify(args.rbArgv.slice(1));  // exclude argv[0]\n  const envRb = JSON.stringify(args.userEnv || {});\n  const progNameRb = JSON.stringify(args.progName);\n\n  // STAGED execution: we split the prelude (stdout sync + ARGV/ENV/$0\n  // setup) from the user-code eval. The prelude has no failure modes\n  // we care about; user-code is wrapped in begin/rescue for SystemExit\n  // and Exception. If the wrapper itself trips a syntax/runtime error,\n  // we surface it via the __NIMBUS_RUBY_DIAG side channel.\n  // Build env list as string-keyed Ruby hash via the rocket-syntax.\n  // Ruby treats colon-style hash literals as Symbol-keyed; we need\n  // String keys so ENV[k] = v works without TypeError.\n  const envEntries = Object.entries(args.userEnv || {})\n    .map(([k, v]) => JSON.stringify(k) + ' => ' + JSON.stringify(v))\n    .join(', ');\n  const envHashRb = '{' + envEntries + '}';\n\n  const preludeRb = [\n    // Reset exit state FIRST so partial prelude failures still\n    // surface a clean exit code (previously: exit 7 left $__nimbus_exit\n    // = 7 \u2192 next call's prelude could fail before resetting \u2192 second\n    // exit 0 returned 7).\n    '$__nimbus_exit = 0',\n    '$stdout.sync = true',\n    '$stderr.sync = true',\n    '$0 = ' + progNameRb,\n    '$PROGRAM_NAME = ' + progNameRb,\n    'ARGV.replace(' + argvRb + ')',\n    envHashRb + '.each_pair { |k, v| ENV[k] = v }',\n  ].join('; ');\n\n  const userWrapper = [\n    'begin',\n    '  ' + 'eval(' + userCodeRb + ', TOPLEVEL_BINDING, ' + progNameRb + ', 1)',\n    'rescue SystemExit => e',\n    '  $__nimbus_exit = e.status',\n    'rescue Exception => e',\n    '  $stderr.write(e.full_message(highlight: false, order: :top))',\n    '  $__nimbus_exit = 1',\n    'ensure',\n    '  $stdout.flush rescue nil',\n    '  $stderr.flush rescue nil',\n    'end',\n  ].join(\"\\n\");\n\n  const memory = boot.instance.exports.memory;\n\n  function callEvalStringProtect(rubyCode) {\n    const enc = new TextEncoder();\n    const bytes = enc.encode(rubyCode);\n    const cabiRealloc = boot.instance.exports.cabi_realloc;\n    const codePtr = cabiRealloc(0, 0, 1, bytes.length);\n    new Uint8Array(memory.buffer).set(bytes, codePtr);\n    const retPtr = boot.rbEvalStringProtect(codePtr, bytes.length);\n    // Return is a tuple: (rb-abi-value handle u32, status s32) \u2014 8 bytes\n    const dv = new DataView(memory.buffer);\n    const handle = dv.getUint32(retPtr + 0, true);\n    const status = dv.getInt32(retPtr + 4, true);\n    return { handle, status };\n  }\n\n  // Stage 1: run the prelude (sync flags, ARGV, ENV, $0/$PROGRAM_NAME).\n  let preludeStatus;\n  try {\n    preludeStatus = callEvalStringProtect(preludeRb);\n  } catch (e) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'ruby prelude threw: ' + (e && e.message),\n    };\n  }\n  if (preludeStatus && preludeStatus.status !== 0) {\n    globalThis.__nimbusRubyStderr.push('[ruby-runner-diag] prelude returned non-zero status: ' + preludeStatus.status + '\\n');\n  }\n\n  // Stage 2: run user code wrapped for SystemExit/Exception capture.\n  let evalStatus;\n  try {\n    evalStatus = callEvalStringProtect(userWrapper);\n  } catch (e) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'rb-eval-string-protect threw: ' + (e && e.message),\n    };\n  }\n  if (evalStatus && evalStatus.status !== 0) {\n    globalThis.__nimbusRubyStderr.push('[ruby-runner-diag] user wrapper returned non-zero status: ' + evalStatus.status + '\\n');\n  }\n\n  // Read $__nimbus_exit by evaluating it and inspecting the result\n  // via Ruby's puts (captured into stderr). Simpler: call exit through\n  // rb-eval-string-protect and parse the status code from there.\n  //\n  // Actually rbEvalStringProtect already returns a status (second\n  // tuple element). When the wrapper completes normally, status is 0\n  // and we read $__nimbus_exit. We use a follow-up eval that prints\n  // the exit code to a sentinel marker on stderr we can scrape, but\n  // a cleaner approach: have the wrapper's last expression BE the\n  // exit code (so it's the return value of eval).\n  //\n  // Re-do: eval $__nimbus_exit and read it from a marker line we\n  // emit to a side channel \u2014 easiest is to call $stdout via a unique\n  // marker that we then strip from output.\n  const NIMBUS_EXIT_MARKER = '__NIMBUS_RUBY_EXIT_';\n  let exitCode = 0;\n  try {\n    // Print the marker + exit code to stderr (a side channel separate\n    // from user-visible stdout). We strip it before returning.\n    callEvalStringProtect(\n      '$stderr.write(' + JSON.stringify(NIMBUS_EXIT_MARKER) + ' + $__nimbus_exit.to_s + \"\\\\n\")'\n    );\n    // Scrape the marker from stderr buffer \u2014 using ONLY this call's\n    // slice (from stderrStart). The same facet can be reused across\n    // multiple __rubyRun invocations (loader-pool dedup by tag), so\n    // a previous call's marker would otherwise be matched first.\n    const callStderr = globalThis.__nimbusRubyStderr.slice(stderrStart).join('');\n    // Match the LAST marker in this slice (the one our just-completed\n    // call emitted; if the user wrapper also emitted writes, the\n    // marker is appended after them).\n    const markerRe = new RegExp(NIMBUS_EXIT_MARKER + '(-?\\\\d+)', 'g');\n    let lastMatch = null;\n    let mit;\n    while ((mit = markerRe.exec(callStderr)) !== null) lastMatch = mit;\n    if (lastMatch) exitCode = parseInt(lastMatch[1], 10);\n  } catch (e) {\n    // Failure to read exit code \u2192 assume 0 if no errors observed.\n    exitCode = 0;\n  }\n\n  // Slice + scrub the marker from stderr output before returning.\n  const stdoutOut = globalThis.__nimbusRubyStdout.slice(stdoutStart).join('');\n  let stderrOut = globalThis.__nimbusRubyStderr.slice(stderrStart).join('');\n  stderrOut = stderrOut.replace(new RegExp(NIMBUS_EXIT_MARKER + '-?\\\\d+\\\\n?', 'g'), '');\n\n  return {\n    exitCode: exitCode,\n    stdout: stdoutOut,\n    stderr: stderrOut,\n  };\n};\n\n// \u2500\u2500 END: ruby-runner preamble \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n";
+export declare const RUBY_RUNNER_PREAMBLE_TAIL = "\n// \u2500\u2500 BEGIN: ruby-runner preamble (Ruby 3.3.4, Nimbus v1) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n// Capture buffers shared across the bootstrap and per-call paths. The\n// preamble's WASI imports route fd_write stdout/stderr into these via\n// __wasiMakeImports({stdoutWrite, stderrWrite}). Per-call __rubyRun\n// slices from these to isolate output per invocation.\nglobalThis.__nimbusRubyStdout = globalThis.__nimbusRubyStdout || [];\nglobalThis.__nimbusRubyStderr = globalThis.__nimbusRubyStderr || [];\n\nfunction __nimbusInstallRubyFsSnapshot(snapshot) {\n  const dirs = new Set(['tmp', 'home']);\n  const files = {};\n  for (const dir of (snapshot && snapshot.dirs) || []) dirs.add(String(dir).replace(/^\\/+/, '').replace(/\\/+$/, ''));\n  for (const [path, b64] of Object.entries((snapshot && snapshot.files) || {})) {\n    files[String(path).replace(/^\\/+/, '')] = b64;\n  }\n  __wasiInitFS({\n    root: '',\n    preopens: [\n      { wasiPath: '/',     vfsPath: '' },\n      { wasiPath: '/tmp',  vfsPath: 'tmp' },\n      { wasiPath: '/home', vfsPath: 'home' },\n    ],\n    files,\n    dirs: Array.from(dirs).filter(Boolean),\n  });\n}\n\n// \u2500\u2500 Canonical-ABI resource Slab \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Pyodide-style minimal resource manager. Ruby's rb-abi-guest.js uses\n// these 4 functions for resource_drop / resource_new / resource_get /\n// resource_clone, but the wasm itself only imports 3:\n//   resource_drop_js-abi-value, resource_new_rb-abi-value, resource_get_rb-abi-value\nclass __NimbusRubySlab {\n  constructor() { this._map = new Map(); this._next = 1; }\n  insert(obj) { const id = this._next++; this._map.set(id, obj); return id; }\n  get(id) { return this._map.get(id); }\n  remove(id) { const v = this._map.get(id); this._map.delete(id); return v; }\n}\n\n// \u2500\u2500 Bootstrap promise: runs at child-facet module-init time \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Mirrors pyodide v2's __pyodideBootstrap pattern. The synchronous\n// portion (WebAssembly.instantiate + _initialize + ruby-init-loadpath\n// + ruby-init) all completes before the first await \u2014 so it executes\n// in module-init CSP context where workerd permits wasm code-gen\n// from the LOADER-provided Module.\nglobalThis.__rubyBootstrap = (async function nimbusRubyBootstrap() {\n  const wasmTable = globalThis.__NIMBUS_WASM || {};\n  const rubyMod = wasmTable['ruby+stdlib.wasm'];\n  if (!rubyMod) {\n    return { ok: false, error: '__NIMBUS_WASM missing ruby+stdlib.wasm' };\n  }\n\n  // WASI init \u2014 empty preopens initially. Per-call __rubyRun can mount\n  // a cwd preopen if needed (for ruby <file.rb> reading via WASI).\n  // For v1 (-e mode) we just need stdout/stderr capture + a minimal\n  // FS so Ruby's stdlib init (which probes /tmp + $HOME) doesn't crash.\n  __wasiInitFS({\n    root: '',\n    preopens: [\n      // Preopen / so Ruby can resolve all FS paths through WASI.\n      // Ruby's __wasi_vfs_rt_init mounts its packed stdlib under /usr\n      // inside the wasm's internal VFS \u2014 these preopens are for the\n      // OUTER (host-visible) FS that wasi_snapshot_preview1 exposes.\n      { wasiPath: '/',        vfsPath: '' },\n      { wasiPath: '/tmp',     vfsPath: 'tmp' },\n      { wasiPath: '/home',    vfsPath: 'home' },\n    ],\n    files: {},\n    dirs: ['tmp', 'home'],\n  });\n\n  // Initial argv/env (bootstrap defaults). Per-call __rubyRun re-\n  // initializes WASI with the actual user argv/env before evaluating\n  // user code.\n  let memRef = null;\n  const wasi = __wasiMakeImports({\n    argv: ['ruby'],\n    env: { HOME: '/home/ruby', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' },\n    getMemory: () => memRef,\n    stdoutWrite: (s) => { globalThis.__nimbusRubyStdout.push(s); },\n    stderrWrite: (s) => { globalThis.__nimbusRubyStderr.push(s); },\n  });\n\n  // canonical_abi imports \u2014 3 resource lifecycle fns. The Slab is\n  // shared across the lifetime of the facet (single call, then the\n  // facet is reaped).\n  const rbValueSlab = new __NimbusRubySlab();\n  const jsValueSlab = new __NimbusRubySlab();\n  const canonical_abi = {\n    'resource_drop_js-abi-value': (i) => { jsValueSlab.remove(i); },\n    'resource_new_rb-abi-value': (i) => rbValueSlab.insert({ _wasm_val: i }),\n    'resource_get_rb-abi-value': (i) => {\n      const r = rbValueSlab.get(i);\n      return r ? r._wasm_val : 0;\n    },\n  };\n\n  // rb-js-abi-host imports \u2014 21 fns. Ruby only calls these when user\n  // code interacts with JS (gem \"js\"). For v1 (puts \"hi\") none fire.\n  // We stub each to throw a clear error so any future user code that\n  // needs JS interop gets a recognizable diagnostic instead of a\n  // wasm trap.\n  const _stub = (name) => () => { throw new Error('ruby-runner v1: rb-js-abi-host.' + name + ' not implemented (gem \"js\" not supported)'); };\n  const rb_js_abi_host = {\n    rb_wasm_throw_prohibit_rewind_exception: () => {\n      // This one CAN fire from Ruby internals (Fiber rewind guard).\n      // Make it a no-op so Ruby's continuation machinery proceeds.\n    },\n    'eval-js: func(code: string) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('eval-js'),\n    'is-js: func(value: handle<js-abi-value>) -> bool': _stub('is-js'),\n    'instance-of: func(value: handle<js-abi-value>, klass: handle<js-abi-value>) -> bool': _stub('instance-of'),\n    'global-this: func() -> handle<js-abi-value>': _stub('global-this'),\n    'int-to-js-number: func(value: s32) -> handle<js-abi-value>': _stub('int-to-js-number'),\n    'float-to-js-number: func(value: float64) -> handle<js-abi-value>': _stub('float-to-js-number'),\n    'string-to-js-string: func(value: string) -> handle<js-abi-value>': _stub('string-to-js-string'),\n    'bool-to-js-bool: func(value: bool) -> handle<js-abi-value>': _stub('bool-to-js-bool'),\n    'proc-to-js-function: func(value: u32) -> handle<js-abi-value>': _stub('proc-to-js-function'),\n    'rb-object-to-js-rb-value: func(raw-rb-abi-value: u32) -> handle<js-abi-value>': _stub('rb-object-to-js-rb-value'),\n    'js-value-to-string: func(value: handle<js-abi-value>) -> string': _stub('js-value-to-string'),\n    'js-value-to-integer: func(value: handle<js-abi-value>) -> variant { as-float(float64), bignum(string) }': _stub('js-value-to-integer'),\n    'export-js-value-to-host: func(value: handle<js-abi-value>) -> ()': _stub('export-js-value-to-host'),\n    'import-js-value-from-host: func() -> handle<js-abi-value>': _stub('import-js-value-from-host'),\n    'js-value-typeof: func(value: handle<js-abi-value>) -> string': _stub('js-value-typeof'),\n    'js-value-equal: func(lhs: handle<js-abi-value>, rhs: handle<js-abi-value>) -> bool': _stub('js-value-equal'),\n    'js-value-strictly-equal: func(lhs: handle<js-abi-value>, rhs: handle<js-abi-value>) -> bool': _stub('js-value-strictly-equal'),\n    'reflect-apply: func(target: handle<js-abi-value>, this-argument: handle<js-abi-value>, arguments: list<handle<js-abi-value>>) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-apply'),\n    'reflect-get: func(target: handle<js-abi-value>, property-key: string) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-get'),\n    'reflect-set: func(target: handle<js-abi-value>, property-key: string, value: handle<js-abi-value>) -> variant { success(handle<js-abi-value>), failure(handle<js-abi-value>) }': _stub('reflect-set'),\n  };\n\n  const imports = {\n    wasi_snapshot_preview1: wasi.wasiImport,\n    canonical_abi,\n    'rb-js-abi-host': rb_js_abi_host,\n  };\n\n  let instance;\n  try {\n    const result = await WebAssembly.instantiate(rubyMod, imports);\n    instance = (result instanceof WebAssembly.Instance ? result : result.instance);\n  } catch (e) {\n    return { ok: false, error: 'WebAssembly.instantiate failed: ' + (e && e.message), stack: e && e.stack };\n  }\n  memRef = instance.exports.memory;\n\n  // \u2500\u2500 Ruby bootstrap sequence \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // Order matters (per ruby.wasm DefaultRubyVM):\n  //   1. _initialize (reactor entry; runs static initializers)\n  //   2. __wasi_vfs_rt_init (mount packed stdlib at the wasi-vfs's\n  //      internal FS \u2014 needed for require to find Ruby's *.rb files)\n  //   3. ruby-init([progName])  \u2014 initialize VM with argv[0]\n  //   4. ruby-init-loadpath()   \u2014 set $LOAD_PATH from packed stdlib\n  try {\n    if (typeof instance.exports._initialize === 'function') {\n      instance.exports._initialize();\n    }\n    if (typeof instance.exports.__wasi_vfs_rt_init === 'function') {\n      instance.exports.__wasi_vfs_rt_init();\n    }\n  } catch (e) {\n    return { ok: false, error: '_initialize/wasi_vfs_rt_init failed: ' + (e && e.message), stack: e && e.stack };\n  }\n\n  // Locate the canonical Ruby ABI exports. Names embed the WIT\n  // signature literal (e.g. 'ruby-init: func(args: list<string>) -> ()')\n  // because rb-abi-guest is wit-bindgen-generated.\n  const rubyInit = instance.exports['ruby-init: func(args: list<string>) -> ()'];\n  const rubyInitLoadpath = instance.exports['ruby-init-loadpath: func() -> ()'];\n  const rbEvalStringProtect = instance.exports['rb-eval-string-protect: func(str: string) -> tuple<handle<rb-abi-value>, s32>'];\n  const rubyShowVersion = instance.exports['ruby-show-version: func() -> ()'];\n  const cabiRealloc = instance.exports.cabi_realloc;\n  if (!rubyInit || !rubyInitLoadpath || !rbEvalStringProtect || !cabiRealloc) {\n    return { ok: false, error: 'Required Ruby ABI exports missing (ruby-init/init-loadpath/eval-string-protect/cabi_realloc)' };\n  }\n\n  // Encode a list<string> argument for ruby-init. WIT canonical-ABI\n  // shape: caller allocates list buffer; each element is (ptr, len).\n  // Strings are UTF-8 encoded into separately-allocated buffers.\n  function writeListString(strings) {\n    const memory = instance.exports.memory;\n    const enc = new TextEncoder();\n    const len = strings.length;\n    const listBufPtr = cabiRealloc(0, 0, 4, len * 8);  // align=4, size=len*8\n    const encoded = strings.map((s) => enc.encode(s));\n    for (let i = 0; i < len; i++) {\n      const bytes = encoded[i];\n      const strPtr = cabiRealloc(0, 0, 1, bytes.length);\n      new Uint8Array(memory.buffer).set(bytes, strPtr);\n      const dv = new DataView(memory.buffer);\n      dv.setUint32(listBufPtr + i * 8 + 0, strPtr, true);\n      dv.setUint32(listBufPtr + i * 8 + 4, bytes.length, true);\n    }\n    return { ptr: listBufPtr, len };\n  }\n\n  function writeString(s) {\n    const memory = instance.exports.memory;\n    const enc = new TextEncoder();\n    const bytes = enc.encode(s);\n    const ptr = cabiRealloc(0, 0, 1, bytes.length);\n    new Uint8Array(memory.buffer).set(bytes, ptr);\n    return { ptr, len: bytes.length };\n  }\n\n  // NOTE: We DO NOT call ruby-init or ruby-init-loadpath here. Both\n  // invoke CPython-like random-seed initialization (random_get via\n  // wasi_snapshot_preview1.random_get), which workerd blocks in the\n  // global-scope (module-init) context. Same constraint that bit us\n  // for Pyodide v2 P21. The per-call __rubyRun runs them at request-\n  // handler time where crypto.getRandomValues is permitted.\n  //\n  // _initialize and __wasi_vfs_rt_init are safe at module-init because\n  // they only do static initialization (no entropy reads).\n\n  return {\n    ok: true,\n    instance,\n    wasi,\n    rubyInit,\n    rubyInitLoadpath,\n    rbEvalStringProtect,\n    rubyShowVersion,\n    writeListString,\n    writeString,\n    rubyInitialized: false,  // mutated to true by __rubyRun on first call\n  };\n})();\n\n// \u2500\u2500 Per-call entry point \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Invoked from the LOADER child facet's execute() (which calls the\n// serialized facetFn that does globalThis.__rubyRun(args)).\n//\n// At this point the bootstrap promise has resolved (since it's\n// awaited inside the child facet's module-init context \u2014 the\n// instantiate finishes before the request handler runs). We:\n//   1. Update Ruby's $0 / $PROGRAM_NAME / ARGV via rb-eval-string-protect\n//   2. Wrap the user code in a begin/rescue SystemExit/StandardError\n//      handler so we can extract exit code without losing stdout\n//   3. Read stdout/stderr buffers and slice from the per-call start\nglobalThis.__rubyRun = async function __rubyRun(args) {\n  const stdoutStart = globalThis.__nimbusRubyStdout.length;\n  const stderrStart = globalThis.__nimbusRubyStderr.length;\n\n  const boot = await globalThis.__rubyBootstrap;\n  if (!boot.ok) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'ruby bootstrap failed: ' + (boot.error || 'unknown') + (boot.stack ? ' [stack=' + boot.stack + ']' : ''),\n    };\n  }\n\n  try {\n    __nimbusInstallRubyFsSnapshot(args.fsSnapshot);\n  } catch (e) {\n    globalThis.__nimbusRubyStderr.push('[ruby-runner] VFS mount failed: ' + (e && e.message) + '\\n');\n  }\n\n  // First call into __rubyRun: complete Ruby VM init (ruby-init +\n  // ruby-init-loadpath) now that we're in request-handler context\n  // where crypto.getRandomValues is permitted. Subsequent calls skip.\n  if (!boot.rubyInitialized) {\n    try {\n      const initArgs = boot.writeListString(['ruby', '-e_=0']);\n      boot.rubyInit(initArgs.ptr, initArgs.len);\n      boot.rubyInitLoadpath();\n      boot.rubyInitialized = true;\n    } catch (e) {\n      return {\n        exitCode: 1,\n        stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n        stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n        error: 'ruby-init / ruby-init-loadpath failed at request time: ' + (e && e.message),\n      };\n    }\n  }\n\n  function rubyStringLiteral(value) {\n    const s = String(value ?? '');\n    let out = \"'\";\n    for (let i = 0; i < s.length; i++) {\n      const ch = s[i];\n      if (ch === \"\\\\\") out += \"\\\\\\\\\";\n      else if (ch === \"'\") out += \"\\\\'\";\n      else out += ch;\n    }\n    return out + \"'\";\n  }\n\n  function rubyArrayLiteral(values) {\n    return '[' + (values || []).map((v) => rubyStringLiteral(v)).join(', ') + ']';\n  }\n\n  function rubyHashLiteral(obj) {\n    return '{' + Object.entries(obj || {})\n      .map(([k, v]) => rubyStringLiteral(k) + ' => ' + rubyStringLiteral(v))\n      .join(', ') + '}';\n  }\n\n  // Wrapper code: set $0/$PROGRAM_NAME/ARGV/ENV, run user code,\n  // capture SystemExit. User-controlled strings are emitted as Ruby\n  // single-quoted literals so Ruby interpolation inside source text is\n  // preserved for the user's eval, not consumed by this wrapper.\n  //\n  // The wrapper sets __NIMBUS_RUBY_EXIT to the desired exit code so\n  // we can read it via a second rb-eval-string-protect call. Failing\n  // SystemExit (raise) ends up with __NIMBUS_RUBY_EXIT = 1 + stderr\n  // message.\n  const userCodeRb = rubyStringLiteral(args.userCode);\n  const argvRb = rubyArrayLiteral(args.rbArgv.slice(1));  // exclude argv[0]\n  const progNameRb = rubyStringLiteral(args.progName);\n\n  // STAGED execution: we split the prelude (stdout sync + ARGV/ENV/$0\n  // setup) from the user-code eval. The prelude has no failure modes\n  // we care about; user-code is wrapped in begin/rescue for SystemExit\n  // and Exception. If the wrapper itself trips a syntax/runtime error,\n  // we surface it via the __NIMBUS_RUBY_DIAG side channel.\n  // Build env list as string-keyed Ruby hash via the rocket-syntax.\n  // Ruby treats colon-style hash literals as Symbol-keyed; we need\n  // String keys so ENV[k] = v works without TypeError.\n  const envHashRb = rubyHashLiteral(args.userEnv || {});\n  const cwdRb = rubyStringLiteral(args.cwd || '/home/user');\n\n  const preludeRb = [\n    // Reset exit state FIRST so partial prelude failures still\n    // surface a clean exit code (previously: exit 7 left $__nimbus_exit\n    // = 7 \u2192 next call's prelude could fail before resetting \u2192 second\n    // exit 0 returned 7).\n    '$__nimbus_exit = 0',\n    '$stdout.sync = true',\n    '$stderr.sync = true',\n    '$0 = ' + progNameRb,\n    '$PROGRAM_NAME = ' + progNameRb,\n    'ARGV.replace(' + argvRb + ')',\n    envHashRb + '.each_pair { |k, v| ENV[k] = v }',\n    'ENV[\"HOME\"] ||= \"/home/user\"',\n    'ENV[\"GEM_HOME\"] ||= File.join(ENV[\"HOME\"], \".gem\")',\n    'ENV[\"GEM_PATH\"] ||= ENV[\"GEM_HOME\"]',\n    'begin; Dir.mkdir(ENV[\"GEM_HOME\"]) unless Dir.exist?(ENV[\"GEM_HOME\"]); rescue Exception; end',\n    'begin; Dir.chdir(' + cwdRb + '); rescue Exception; end',\n    'begin; $LOAD_PATH.unshift(Dir.pwd) unless $LOAD_PATH.include?(Dir.pwd); rescue Exception; end',\n    'begin; (ENV[\"NIMBUS_GEM_LIBS\"] || \"\").split(\":\").reverse_each { |p| $LOAD_PATH.unshift(p) if p && p != \"\" && !$LOAD_PATH.include?(p) }; rescue Exception; end',\n  ].join('; ');\n\n  const userWrapper = [\n    'begin',\n    '  ' + 'eval(' + userCodeRb + ', TOPLEVEL_BINDING, ' + progNameRb + ', 1)',\n    'rescue SystemExit => e',\n    '  $__nimbus_exit = e.status',\n    'rescue Exception => e',\n    '  $stderr.write(e.full_message(highlight: false, order: :top))',\n    '  $__nimbus_exit = 1',\n    'ensure',\n    '  $stdout.flush rescue nil',\n    '  $stderr.flush rescue nil',\n    'end',\n  ].join(\"\\n\");\n\n  const memory = boot.instance.exports.memory;\n\n  function callEvalStringProtect(rubyCode) {\n    const enc = new TextEncoder();\n    const bytes = enc.encode(rubyCode);\n    const cabiRealloc = boot.instance.exports.cabi_realloc;\n    const codePtr = cabiRealloc(0, 0, 1, bytes.length);\n    new Uint8Array(memory.buffer).set(bytes, codePtr);\n    const retPtr = boot.rbEvalStringProtect(codePtr, bytes.length);\n    // Return is a tuple: (rb-abi-value handle u32, status s32) \u2014 8 bytes\n    const dv = new DataView(memory.buffer);\n    const handle = dv.getUint32(retPtr + 0, true);\n    const status = dv.getInt32(retPtr + 4, true);\n    return { handle, status };\n  }\n\n  // Stage 1: run the prelude (sync flags, ARGV, ENV, $0/$PROGRAM_NAME).\n  let preludeStatus;\n  try {\n    preludeStatus = callEvalStringProtect(preludeRb);\n  } catch (e) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'ruby prelude threw: ' + (e && e.message),\n    };\n  }\n  if (preludeStatus && preludeStatus.status !== 0) {\n    globalThis.__nimbusRubyStderr.push('[ruby-runner-diag] prelude returned non-zero status: ' + preludeStatus.status + '\\n');\n  }\n\n  // Stage 2: run user code wrapped for SystemExit/Exception capture.\n  let evalStatus;\n  try {\n    evalStatus = callEvalStringProtect(userWrapper);\n  } catch (e) {\n    return {\n      exitCode: 1,\n      stdout: globalThis.__nimbusRubyStdout.slice(stdoutStart).join(''),\n      stderr: globalThis.__nimbusRubyStderr.slice(stderrStart).join(''),\n      error: 'rb-eval-string-protect threw: ' + (e && e.message),\n    };\n  }\n  if (evalStatus && evalStatus.status !== 0) {\n    globalThis.__nimbusRubyStderr.push('[ruby-runner-diag] user wrapper returned non-zero status: ' + evalStatus.status + '\\n');\n  }\n\n  // Read $__nimbus_exit by evaluating it and inspecting the result\n  // via Ruby's puts (captured into stderr). Simpler: call exit through\n  // rb-eval-string-protect and parse the status code from there.\n  //\n  // Actually rbEvalStringProtect already returns a status (second\n  // tuple element). When the wrapper completes normally, status is 0\n  // and we read $__nimbus_exit. We use a follow-up eval that prints\n  // the exit code to a sentinel marker on stderr we can scrape, but\n  // a cleaner approach: have the wrapper's last expression BE the\n  // exit code (so it's the return value of eval).\n  //\n  // Re-do: eval $__nimbus_exit and read it from a marker line we\n  // emit to a side channel \u2014 easiest is to call $stdout via a unique\n  // marker that we then strip from output.\n  const NIMBUS_EXIT_MARKER = '__NIMBUS_RUBY_EXIT_';\n  let exitCode = 0;\n  try {\n    // Print the marker + exit code to stderr (a side channel separate\n    // from user-visible stdout). We strip it before returning.\n    callEvalStringProtect(\n      '$stderr.write(' + JSON.stringify(NIMBUS_EXIT_MARKER) + ' + $__nimbus_exit.to_s + \"\\\\n\")'\n    );\n    // Scrape the marker from stderr buffer \u2014 using ONLY this call's\n    // slice (from stderrStart). The same facet can be reused across\n    // multiple __rubyRun invocations (loader-pool dedup by tag), so\n    // a previous call's marker would otherwise be matched first.\n    const callStderr = globalThis.__nimbusRubyStderr.slice(stderrStart).join('');\n    // Match the LAST marker in this slice (the one our just-completed\n    // call emitted; if the user wrapper also emitted writes, the\n    // marker is appended after them).\n    const markerRe = new RegExp(NIMBUS_EXIT_MARKER + '(-?\\\\d+)', 'g');\n    let lastMatch = null;\n    let mit;\n    while ((mit = markerRe.exec(callStderr)) !== null) lastMatch = mit;\n    if (lastMatch) exitCode = parseInt(lastMatch[1], 10);\n  } catch (e) {\n    // Failure to read exit code \u2192 assume 0 if no errors observed.\n    exitCode = 0;\n  }\n\n  // Slice + scrub the marker from stderr output before returning.\n  const stdoutOut = globalThis.__nimbusRubyStdout.slice(stdoutStart).join('');\n  let stderrOut = globalThis.__nimbusRubyStderr.slice(stderrStart).join('');\n  stderrOut = stderrOut.replace(new RegExp(NIMBUS_EXIT_MARKER + '-?\\\\d+\\\\n?', 'g'), '');\n\n  return {\n    exitCode: exitCode,\n    stdout: stdoutOut,\n    stderr: stderrOut,\n    fsDiff: (typeof __wasiSnapshotFS === 'function' ? __wasiSnapshotFS() : null),\n  };\n};\n\n// \u2500\u2500 END: ruby-runner preamble \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n";
 //# sourceMappingURL=ruby-runner.d.ts.map

package/dist/runtime/ruby-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ruby-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/ruby-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAoGhC;AAyND;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,y4oBA6ZrC,CAAC"}
+{"version":3,"file":"ruby-runner.d.ts","sourceRoot":"","sources":["../../src/runtime/ruby-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAczD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;CAChB,GAAG,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAC7F,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,MAAM,CAAC,CAkJhC;AA0bD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,w4sBAidrC,CAAC"}

package/dist/runtime/ruby-runner.js

@@ -11,9 +11,7 @@
  *
  * Out of v1:
  *   - REPL mode (`ruby` with no args)
- *   - require_relative for non-bundled files (basic require for
- *     stdlib works since stdlib is wasi-vfs-packed inside the wasm)
- *   - gems, bundler
+ *   - native extension gems
  *   - js-runtime bindings (gem "js") — those imports are stubbed
  *     and will raise NotImplementedError if Ruby code tries to use
  *     them
@@ -35,6 +33,10 @@
  *     canonical_abi_drop_rb-abi-value, memory.
  */
 import { WASI_INSTANCE_PREAMBLE_SRC } from './wasi-instance.js';
+import { flushVfsDiff, snapshotVfs } from './vfs-snapshot.js';
+import { createLiveStaticServerCode, parsePort } from './static-server.js';
+import { resolveVfsPath } from '../vfs/path.js';
+import { defaultGemHome, installRubyBundle, installRubyGems, installedGemLibRoots, parseRubyGemRequirements, } from './ruby-gems.js';
 /**
  * Build the ruby-runner factory. Called once at session init; the
  * returned factory binds the manifest + install root for each
@@ -42,28 +44,43 @@ import { WASI_INSTANCE_PREAMBLE_SRC } from './wasi-instance.js';
  */
 export function makeRubyRunnerFactory(deps) {
     const { facetMgr, vfs } = deps;
-    return function rubyRunnerFactory(manifest, installRoot, binName, _binKind) {
+    return function rubyRunnerFactory(manifest, installRoot, binName, binKind) {
         const findFile = (rel) => {
             const entry = manifest.files.find((f) => f.path === rel);
             return entry ? `${installRoot}/${entry.path}` : null;
         };
         const wasmVfs = findFile('share/ruby/ruby+stdlib.wasm');
+        let fsSnapshotCache = null;
         return async function rubyBinHandler(ctx) {
             const argv = ctx.args || [];
             const cwd = ctx.cwd || '/home/user';
+            const packageCommand = await maybeHandleRubyPackageCommand(binKind, binName, argv, cwd, vfs, ctx);
+            if (packageCommand.handled)
+                return packageCommand.exitCode;
+            const toolInvocation = buildRubyToolInvocation(binKind, binName, argv);
+            if (toolInvocation.error) {
+                ctx.stderr.write(`${binName}: ${toolInvocation.error}\n`);
+                return toolInvocation.exitCode;
+            }
             // --version / --help fast paths (no wasm boot).
-            if (argv.includes('--version') || argv.includes('-v')) {
-                // 3.3.x — ruby.wasm 2.9.3-2.9.4 ships Ruby 3.3.4 per upstream
-                // release notes. The string format matches `ruby --version`
-                // shape (parsed by tooling like rbenv).
-                ctx.stdout.write(`ruby 3.3.4 (2024-04-23 revision wasm) [wasm32-wasi]\n`);
+            if (toolInvocation.mode !== 'tool' && (argv.includes('--version') || argv.includes('-v'))) {
+                ctx.stdout.write(`ruby 3.3.3 (ruby.wasm, Nimbus runtime) [wasm32-wasi]\n`);
                 return 0;
             }
-            if (argv.includes('--help') || argv.includes('-h')) {
+            if (toolInvocation.mode !== 'tool' && (argv.includes('--help') || argv.includes('-h'))) {
                 ctx.stdout.write(`Usage: ${binName} [switches] [--] [programfile] [arguments]\n`);
-                ctx.stdout.write(`Nimbus Ruby 3.3.4 runtime (ruby.wasm 2.9.3-2.9.4).\n`);
-                ctx.stdout.write(`Supported v1: -e <code>, <file.rb>, -r <lib>\n`);
-                ctx.stdout.write(`Not supported: REPL (no args), gem, bundler, js-runtime\n`);
+                ctx.stdout.write(`Nimbus Ruby runtime (ruby.wasm).\n`);
+                ctx.stdout.write(`Supported: -e <code>, <file.rb>, -r <lib>, VFS-backed require_relative and file IO\n`);
+                ctx.stdout.write(`Ruby socket/native gem install support is not available in this ruby.wasm build.\n`);
+                return 0;
+            }
+            const staticServer = parseRubyHttpd(argv, cwd);
+            if (staticServer) {
+                const code = createLiveStaticServerCode(staticServer.root);
+                const command = `${binName} -run -e httpd ${staticServer.root} -p ${staticServer.port}`;
+                const spawned = facetMgr.spawn(code, command, staticServer.root, { port: staticServer.port });
+                ctx.stdout.write(`Serving HTTP on 0.0.0.0 port ${staticServer.port} from /${staticServer.root}\n`);
+                ctx.stdout.write(`[nimbus] started: pid=${spawned.pid} cmd="${command}" port=${staticServer.port}\n`);
                 return 0;
             }
             // Resolve install bytes.
@@ -73,7 +90,16 @@ export function makeRubyRunnerFactory(deps) {
             }
             const wasmBytes = vfs.readFile(wasmVfs);
             // Parse argv.
-            const parsed = parseRubyArgv(argv);
+            const parsed = toolInvocation.mode === 'tool'
+                ? {
+                    mode: 'inline',
+                    inlineCode: toolInvocation.code,
+                    scriptPath: '',
+                    scriptArgs: [],
+                    requires: [],
+                    exitCode: 0,
+                }
+                : parseRubyArgv(argv);
             if (parsed.error) {
                 ctx.stderr.write(`${binName}: ${parsed.error}\n`);
                 return parsed.exitCode;
@@ -100,7 +126,7 @@ export function makeRubyRunnerFactory(deps) {
                     ctx.stderr.write(`${binName}: ${parsed.scriptPath}: ${e?.message || e}\n`);
                     return 1;
                 }
-                progName = parsed.scriptPath;
+                progName = '/' + absPath;
                 rbArgv = [parsed.scriptPath, ...parsed.scriptArgs];
             }
             // -r flags add prelude `require '<lib>'` lines (stdlib only).
@@ -111,13 +137,30 @@ export function makeRubyRunnerFactory(deps) {
             const userEnv = { ...(ctx.env || {}) };
             if (!userEnv.HOME)
                 userEnv.HOME = '/home/ruby';
+            if (userEnv.HOME === '/home/ruby')
+                userEnv.HOME = '/home/user';
             if (!userEnv.LANG)
                 userEnv.LANG = 'C.UTF-8';
+            userEnv.GEM_HOME ||= '/' + defaultGemHome();
+            userEnv.GEM_PATH ||= userEnv.GEM_HOME;
+            userEnv.NIMBUS_GEM_LIBS = installedGemLibRoots(vfs, defaultGemHome()).join(':');
             // Ruby looks for charset hints via these vars; set sensible
             // defaults so puts of non-ASCII strings doesn't trip on the
             // wasi default of "ASCII-8BIT".
             if (!userEnv.LC_ALL)
                 userEnv.LC_ALL = 'C.UTF-8';
+            const revision = typeof vfs.revision === 'function' ? vfs.revision() : Date.now();
+            let fsSnapshot = fsSnapshotCache && fsSnapshotCache.cwd === cwd && fsSnapshotCache.revision === revision
+                ? fsSnapshotCache.result
+                : null;
+            if (!fsSnapshot) {
+                fsSnapshot = snapshotVfs(vfs, cwd, { extraRoots: [defaultGemHome()] });
+                fsSnapshotCache = { cwd, revision, result: fsSnapshot };
+            }
+            if ('error' in fsSnapshot) {
+                ctx.stderr.write(`${binName}: ${fsSnapshot.error}\n`);
+                return 1;
+            }
             // Dispatch the facet.
             const result = await dispatchRubyFacet(facetMgr, {
                 wasmBytes,
@@ -125,11 +168,15 @@ export function makeRubyRunnerFactory(deps) {
                 rbArgv,
                 userEnv,
                 progName,
+                cwd,
+                fsSnapshot: fsSnapshot.snapshot,
             });
             if (result.stdout)
                 ctx.stdout.write(result.stdout);
             if (result.stderr)
                 ctx.stderr.write(result.stderr);
+            if (result.fsDiff)
+                flushVfsDiff(vfs, result.fsDiff);
             if (result.error) {
                 ctx.stderr.write(`${binName}: ${result.error}\n`);
                 return 1;
@@ -138,6 +185,211 @@ export function makeRubyRunnerFactory(deps) {
         };
     };
 }
+async function maybeHandleRubyPackageCommand(binKind, binName, argv, cwd, vfs, ctx) {
+    const isGem = binKind === 'gem' || binName === 'gem';
+    const isBundle = binKind === 'bundle' || binName === 'bundle' || binName === 'bundler';
+    if (isGem && argv[0] === 'install') {
+        const parsed = parseGemInstallArgs(argv.slice(1));
+        if (parsed.error) {
+            ctx.stderr.write(`gem install: ${parsed.error}\n`);
+            return { handled: true, exitCode: 2 };
+        }
+        try {
+            const report = await installRubyGems(vfs, parsed.requests, { gemHome: defaultGemHome(), includeDependencies: true });
+            for (const name of report.installed)
+                ctx.stdout.write(`Successfully installed ${name}\n`);
+            for (const name of report.alreadyInstalled)
+                ctx.stdout.write(`${name} is already installed\n`);
+            ctx.stdout.write(`${report.installed.length + report.alreadyInstalled.length} gem(s) processed\n`);
+            return { handled: true, exitCode: 0 };
+        }
+        catch (e) {
+            ctx.stderr.write(`gem install: ${e?.message || e}\n`);
+            return { handled: true, exitCode: 1 };
+        }
+    }
+    if (isBundle && argv[0] === 'install') {
+        try {
+            const { requests, report, lockfilePath } = await installRubyBundle(vfs, cwd, { gemHome: defaultGemHome() });
+            for (const name of report.installed)
+                ctx.stdout.write(`Successfully installed ${name}\n`);
+            for (const name of report.alreadyInstalled)
+                ctx.stdout.write(`${name} is already installed\n`);
+            ctx.stdout.write(`Bundle complete! ${requests.length} Gemfile dependency(s), ${report.installed.length + report.alreadyInstalled.length} gem(s) now installed.\n`);
+            ctx.stdout.write(`Bundled lockfile written to /${lockfilePath}\n`);
+            return { handled: true, exitCode: 0 };
+        }
+        catch (e) {
+            ctx.stderr.write(`bundle install: ${e?.message || e}\n`);
+            return { handled: true, exitCode: 1 };
+        }
+    }
+    return { handled: false, exitCode: 0 };
+}
+function parseGemInstallArgs(argv) {
+    const names = [];
+    let versionRequirement = null;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-v' || arg === '--version') {
+            const version = argv[i + 1];
+            if (!version)
+                return { requests: [], error: `${arg}: missing version` };
+            versionRequirement = version;
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--version=')) {
+            versionRequirement = arg.slice('--version='.length);
+            continue;
+        }
+        if (arg === '--no-document' || arg === '--no-doc' || arg === '--user-install') {
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { requests: [], error: `option '${arg}' is not supported in Nimbus yet` };
+        }
+        names.push(arg);
+    }
+    const requirements = versionRequirement ? parseRubyGemRequirements(versionRequirement) : [];
+    const requests = names.map((name) => ({ name, requirements }));
+    if (requests.length === 0)
+        return { requests, error: 'missing gem name' };
+    return { requests };
+}
+function buildRubyToolInvocation(binKind, binName, argv) {
+    const isGem = binKind === 'gem' || binName === 'gem';
+    const isBundle = binKind === 'bundle' || binName === 'bundle' || binName === 'bundler';
+    if (!isGem && !isBundle)
+        return { mode: 'none', code: '', exitCode: 0 };
+    if (isGem) {
+        if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+            return {
+                mode: 'tool',
+                code: [
+                    'puts "Usage: gem --version"',
+                    'puts "       gem env"',
+                    'puts "       gem install <name>  # installs pure Ruby gems through Nimbus RubyGems"',
+                ].join('\n'),
+                exitCode: 0,
+            };
+        }
+        if (argv.includes('--version') || argv[0] === '-v') {
+            return { mode: 'tool', code: 'require "rubygems"; puts Gem::VERSION', exitCode: 0 };
+        }
+        if (argv[0] === 'env') {
+            return {
+                mode: 'tool',
+                code: [
+                    'require "rubygems"',
+                    'puts "RubyGems #{Gem::VERSION}"',
+                    'puts "Ruby #{RUBY_VERSION} (#{RUBY_PLATFORM})"',
+                    'puts "GEM_HOME=#{ENV["GEM_HOME"] || File.join(ENV["HOME"], ".gem")}"',
+                    'puts "GEM_PATH=#{ENV["GEM_PATH"] || ENV["GEM_HOME"]}"',
+                ].join('\n'),
+                exitCode: 0,
+            };
+        }
+        if (argv[0] === 'install') {
+            return {
+                mode: 'none',
+                code: '',
+                error: 'gem install command was not handled by Nimbus RubyGems',
+                exitCode: 1,
+            };
+        }
+        return {
+            mode: 'none',
+            code: '',
+            error: `gem subcommand '${argv[0]}' is not supported yet`,
+            exitCode: 2,
+        };
+    }
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        return {
+            mode: 'tool',
+            code: [
+                'puts "Usage: bundle --version"',
+                'puts "       bundle install  # installs compatible pure Ruby gems through Nimbus RubyGems"',
+            ].join('\n'),
+            exitCode: 0,
+        };
+    }
+    if (argv.includes('--version') || argv[0] === '-v') {
+        return {
+            mode: 'tool',
+            code: [
+                'begin',
+                '  require "bundler"',
+                '  puts "Bundler #{Bundler::VERSION}"',
+                'rescue LoadError',
+                '  warn "Bundler is not bundled in this ruby.wasm runtime"',
+                '  exit 127',
+                'end',
+            ].join('\n'),
+            exitCode: 0,
+        };
+    }
+    if (argv[0] === 'install') {
+        return {
+            mode: 'none',
+            code: '',
+            error: 'bundle install command was not handled by Nimbus RubyGems',
+            exitCode: 1,
+        };
+    }
+    return {
+        mode: 'none',
+        code: '',
+        error: `bundle subcommand '${argv[0]}' is not supported yet`,
+        exitCode: 2,
+    };
+}
+function parseRubyHttpd(argv, cwd) {
+    let requiresUn = false;
+    let hasHttpdEval = false;
+    let afterEval = -1;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-run' || arg === '-r' && argv[i + 1] === 'un') {
+            requiresUn = true;
+            if (arg === '-r')
+                i++;
+            continue;
+        }
+        if (arg === '-e' && argv[i + 1] === 'httpd') {
+            hasHttpdEval = true;
+            afterEval = i + 2;
+            i++;
+            continue;
+        }
+        if (arg === '-ehttpd') {
+            hasHttpdEval = true;
+            afterEval = i + 1;
+            continue;
+        }
+    }
+    if (!requiresUn || !hasHttpdEval)
+        return null;
+    let port = 8080;
+    let directory = '.';
+    for (let i = Math.max(afterEval, 0); i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-p' || arg === '--port') {
+            port = parsePort(argv[i + 1], port);
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--port=')) {
+            port = parsePort(arg.slice('--port='.length), port);
+            continue;
+        }
+        if (!arg.startsWith('-') && directory === '.') {
+            directory = arg;
+        }
+    }
+    return { port, root: resolveVfsPath(directory, cwd) };
+}
 function parseRubyArgv(argv) {
     // Ruby's CLI is rich; v1 handles -e, -r, and positional script.
     const requires = [];
@@ -213,14 +465,6 @@ function parseRubyArgv(argv) {
     return { mode: 'inline', inlineCode: '', scriptPath: '', scriptArgs: [],
         requires, exitCode: 2, error: "REPL not supported in v1. Use 'ruby -e \"code\"' or 'ruby script.rb'." };
 }
-function resolveVfsPath(rel, cwd) {
-    const cwdN = cwd.replace(/^\/+/, '').replace(/\/+$/, '');
-    if (rel.startsWith('/'))
-        return rel.replace(/^\/+/, '');
-    if (rel === '.')
-        return cwdN;
-    return `${cwdN}/${rel}`;
-}
 async function dispatchRubyFacet(facetMgr, args) {
     const toAB = (u8) => u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
     // The Ruby preamble runs the entire bootstrap at child-facet module-
@@ -252,6 +496,8 @@ async function dispatchRubyFacet(facetMgr, args) {
             rbArgv: inArgs.rbArgv,
             userEnv: inArgs.userEnv,
             progName: inArgs.progName,
+            cwd: inArgs.cwd,
+            fsSnapshot: inArgs.fsSnapshot,
         });
     };
     try {
@@ -260,6 +506,8 @@ async function dispatchRubyFacet(facetMgr, args) {
             rbArgv: args.rbArgv,
             userEnv: args.userEnv,
             progName: args.progName,
+            cwd: args.cwd,
+            fsSnapshot: args.fsSnapshot,
         }, {
             wasmModules: {
                 'ruby+stdlib.wasm': toAB(args.wasmBytes),
@@ -271,6 +519,7 @@ async function dispatchRubyFacet(facetMgr, args) {
             stdout: result.stdout || '',
             stderr: result.stderr || '',
             error: result.error,
+            fsDiff: result.fsDiff,
         };
     }
     catch (e) {
@@ -330,6 +579,25 @@ export const RUBY_RUNNER_PREAMBLE_TAIL = `
 globalThis.__nimbusRubyStdout = globalThis.__nimbusRubyStdout || [];
 globalThis.__nimbusRubyStderr = globalThis.__nimbusRubyStderr || [];
 
+function __nimbusInstallRubyFsSnapshot(snapshot) {
+  const dirs = new Set(['tmp', 'home']);
+  const files = {};
+  for (const dir of (snapshot && snapshot.dirs) || []) dirs.add(String(dir).replace(/^\\/+/, '').replace(/\\/+$/, ''));
+  for (const [path, b64] of Object.entries((snapshot && snapshot.files) || {})) {
+    files[String(path).replace(/^\\/+/, '')] = b64;
+  }
+  __wasiInitFS({
+    root: '',
+    preopens: [
+      { wasiPath: '/',     vfsPath: '' },
+      { wasiPath: '/tmp',  vfsPath: 'tmp' },
+      { wasiPath: '/home', vfsPath: 'home' },
+    ],
+    files,
+    dirs: Array.from(dirs).filter(Boolean),
+  });
+}
+
 // ── Canonical-ABI resource Slab ────────────────────────────────────
 // Pyodide-style minimal resource manager. Ruby's rb-abi-guest.js uses
 // these 4 functions for resource_drop / resource_new / resource_get /
@@ -558,6 +826,12 @@ globalThis.__rubyRun = async function __rubyRun(args) {
     };
   }
 
+  try {
+    __nimbusInstallRubyFsSnapshot(args.fsSnapshot);
+  } catch (e) {
+    globalThis.__nimbusRubyStderr.push('[ruby-runner] VFS mount failed: ' + (e && e.message) + '\\n');
+  }
+
   // First call into __rubyRun: complete Ruby VM init (ruby-init +
   // ruby-init-loadpath) now that we're in request-handler context
   // where crypto.getRandomValues is permitted. Subsequent calls skip.
@@ -577,19 +851,40 @@ globalThis.__rubyRun = async function __rubyRun(args) {
     }
   }
 
+  function rubyStringLiteral(value) {
+    const s = String(value ?? '');
+    let out = "'";
+    for (let i = 0; i < s.length; i++) {
+      const ch = s[i];
+      if (ch === "\\\\") out += "\\\\\\\\";
+      else if (ch === "'") out += "\\\\'";
+      else out += ch;
+    }
+    return out + "'";
+  }
+
+  function rubyArrayLiteral(values) {
+    return '[' + (values || []).map((v) => rubyStringLiteral(v)).join(', ') + ']';
+  }
+
+  function rubyHashLiteral(obj) {
+    return '{' + Object.entries(obj || {})
+      .map(([k, v]) => rubyStringLiteral(k) + ' => ' + rubyStringLiteral(v))
+      .join(', ') + '}';
+  }
+
   // Wrapper code: set $0/$PROGRAM_NAME/ARGV/ENV, run user code,
-  // capture SystemExit. We embed the user code as a Ruby string
-  // literal via JSON.stringify (Ruby's double-quote strings accept
-  // \\n \\t etc which JSON also emits — safe round-trip).
+  // capture SystemExit. User-controlled strings are emitted as Ruby
+  // single-quoted literals so Ruby interpolation inside source text is
+  // preserved for the user's eval, not consumed by this wrapper.
   //
   // The wrapper sets __NIMBUS_RUBY_EXIT to the desired exit code so
   // we can read it via a second rb-eval-string-protect call. Failing
   // SystemExit (raise) ends up with __NIMBUS_RUBY_EXIT = 1 + stderr
   // message.
-  const userCodeRb = JSON.stringify(args.userCode);
-  const argvRb = JSON.stringify(args.rbArgv.slice(1));  // exclude argv[0]
-  const envRb = JSON.stringify(args.userEnv || {});
-  const progNameRb = JSON.stringify(args.progName);
+  const userCodeRb = rubyStringLiteral(args.userCode);
+  const argvRb = rubyArrayLiteral(args.rbArgv.slice(1));  // exclude argv[0]
+  const progNameRb = rubyStringLiteral(args.progName);
 
   // STAGED execution: we split the prelude (stdout sync + ARGV/ENV/$0
   // setup) from the user-code eval. The prelude has no failure modes
@@ -599,10 +894,8 @@ globalThis.__rubyRun = async function __rubyRun(args) {
   // Build env list as string-keyed Ruby hash via the rocket-syntax.
   // Ruby treats colon-style hash literals as Symbol-keyed; we need
   // String keys so ENV[k] = v works without TypeError.
-  const envEntries = Object.entries(args.userEnv || {})
-    .map(([k, v]) => JSON.stringify(k) + ' => ' + JSON.stringify(v))
-    .join(', ');
-  const envHashRb = '{' + envEntries + '}';
+  const envHashRb = rubyHashLiteral(args.userEnv || {});
+  const cwdRb = rubyStringLiteral(args.cwd || '/home/user');
 
   const preludeRb = [
     // Reset exit state FIRST so partial prelude failures still
@@ -616,6 +909,13 @@ globalThis.__rubyRun = async function __rubyRun(args) {
     '$PROGRAM_NAME = ' + progNameRb,
     'ARGV.replace(' + argvRb + ')',
     envHashRb + '.each_pair { |k, v| ENV[k] = v }',
+    'ENV["HOME"] ||= "/home/user"',
+    'ENV["GEM_HOME"] ||= File.join(ENV["HOME"], ".gem")',
+    'ENV["GEM_PATH"] ||= ENV["GEM_HOME"]',
+    'begin; Dir.mkdir(ENV["GEM_HOME"]) unless Dir.exist?(ENV["GEM_HOME"]); rescue Exception; end',
+    'begin; Dir.chdir(' + cwdRb + '); rescue Exception; end',
+    'begin; $LOAD_PATH.unshift(Dir.pwd) unless $LOAD_PATH.include?(Dir.pwd); rescue Exception; end',
+    'begin; (ENV["NIMBUS_GEM_LIBS"] || "").split(":").reverse_each { |p| $LOAD_PATH.unshift(p) if p && p != "" && !$LOAD_PATH.include?(p) }; rescue Exception; end',
   ].join('; ');
 
   const userWrapper = [
@@ -729,6 +1029,7 @@ globalThis.__rubyRun = async function __rubyRun(args) {
     exitCode: exitCode,
     stdout: stdoutOut,
     stderr: stderrOut,
+    fsDiff: (typeof __wasiSnapshotFS === 'function' ? __wasiSnapshotFS() : null),
   };
 };