@nimbus-sh/worker 0.1.0

package/dist/runtime/router-basename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * router-basename.ts — Auto-inject React Router `basename` for the /preview/
+ * base path so `<NavLink to="/docs">` lands at `/preview/docs` with no
+ * additional config in the user's source.
+ *
+ * Applied at VFS serve time inside vite-dev-server.ts `serveTransformed()`,
+ * BEFORE esbuild's TS/JSX transform (source is easier to regex on).
+ *
+ * Patterns handled:
+ *   A. createBrowserRouter(routes)                    → inject { basename }
+ *   B. createBrowserRouter(routes, { ... })           → merge if no basename
+ *   C. <BrowserRouter ...>                            → add basename attr
+ *   D. <BrowserRouter basename="x">                   → leave alone
+ *
+ * Never overrides user-set values. Opt-out:
+ *   - Explicit basename in source (per pattern)
+ *   - Comment `// nimbus-no-basename` anywhere in the file
+ *   - `nimbusInjectBasename: false` in vite.config.ts (plumbed by caller)
+ *
+ * Scope guard: only transforms likely router entry files (main.tsx, index.tsx,
+ * App.tsx, root.tsx, router.tsx). node_modules is excluded by the caller.
+ */
+/**
+ * Should this VFS path be considered for router-basename injection?
+ * Fast filter before we pay for regex scans on the file body.
+ */
+export declare function shouldProcessForRouter(vfsPath: string): boolean;
+/**
+ * Inject a `basename` into React Router `createBrowserRouter` / <BrowserRouter>
+ * calls in the source, unless the user has set one or opted out.
+ *
+ * Returns the transformed source. Always safe — if no pattern matches,
+ * returns the input unchanged.
+ */
+export declare function injectRouterBasename(src: string, basePath: string): string;
+//# sourceMappingURL=router-basename.d.ts.map

package/dist/runtime/router-basename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-basename.d.ts","sourceRoot":"","sources":["../../src/runtime/router-basename.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA6BH;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwE1E"}

package/dist/runtime/router-basename.js

@@ -0,0 +1,310 @@
+/**
+ * router-basename.ts — Auto-inject React Router `basename` for the /preview/
+ * base path so `<NavLink to="/docs">` lands at `/preview/docs` with no
+ * additional config in the user's source.
+ *
+ * Applied at VFS serve time inside vite-dev-server.ts `serveTransformed()`,
+ * BEFORE esbuild's TS/JSX transform (source is easier to regex on).
+ *
+ * Patterns handled:
+ *   A. createBrowserRouter(routes)                    → inject { basename }
+ *   B. createBrowserRouter(routes, { ... })           → merge if no basename
+ *   C. <BrowserRouter ...>                            → add basename attr
+ *   D. <BrowserRouter basename="x">                   → leave alone
+ *
+ * Never overrides user-set values. Opt-out:
+ *   - Explicit basename in source (per pattern)
+ *   - Comment `// nimbus-no-basename` anywhere in the file
+ *   - `nimbusInjectBasename: false` in vite.config.ts (plumbed by caller)
+ *
+ * Scope guard: only transforms likely router entry files (main.tsx, index.tsx,
+ * App.tsx, root.tsx, router.tsx). node_modules is excluded by the caller.
+ */
+/**
+ * Opt-out comment pattern. Matches a line-leading `//` comment containing the
+ * directive. Intentionally strict so that mere mentions of the directive in
+ * quoted strings, JSX text, or long-form comments do not accidentally disable
+ * injection (e.g., docstrings that reference the opt-out won't opt out).
+ *
+ * Examples that trigger opt-out:
+ *   // nimbus-no-basename
+ *   //   nimbus-no-basename
+ *   // nimbus-no-basename — disables auto-inject here
+ *
+ * Examples that DO NOT trigger (by design):
+ *   const s = "// nimbus-no-basename";          // string literal
+ *   // add the comment "// nimbus-no-basename"  // quoted inside comment
+ */
+const OPT_OUT_RE = /^[ \t]*\/\/[ \t]*nimbus-no-basename\b/m;
+/** Files that are likely router entries. Path is the VFS path. */
+const ENTRY_PATTERNS = [
+    /(?:^|\/)main\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)index\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)App\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)root\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)router(?:\.config)?\.(tsx|ts|jsx|js|mjs)$/i,
+    /(?:^|\/)routes\.(tsx|ts|jsx|js|mjs)$/i,
+];
+/**
+ * Should this VFS path be considered for router-basename injection?
+ * Fast filter before we pay for regex scans on the file body.
+ */
+export function shouldProcessForRouter(vfsPath) {
+    if (!vfsPath)
+        return false;
+    // Never touch vendored code — our seed/user code lives under src/, not node_modules.
+    if (vfsPath.includes('/node_modules/'))
+        return false;
+    if (vfsPath.startsWith('node_modules/'))
+        return false;
+    const normalized = '/' + vfsPath.replace(/^\/+/, '');
+    return ENTRY_PATTERNS.some((re) => re.test(normalized));
+}
+/**
+ * Inject a `basename` into React Router `createBrowserRouter` / <BrowserRouter>
+ * calls in the source, unless the user has set one or opted out.
+ *
+ * Returns the transformed source. Always safe — if no pattern matches,
+ * returns the input unchanged.
+ */
+export function injectRouterBasename(src, basePath) {
+    // Fast short-circuits
+    if (!src || src.length === 0)
+        return src;
+    if (OPT_OUT_RE.test(src))
+        return src;
+    // Only scan further if the source MENTIONS the relevant router APIs.
+    // Using substring checks (not regex) to keep the fast path cheap.
+    const mentionsFactory = src.indexOf('createBrowserRouter') !== -1;
+    const mentionsComponent = src.indexOf('BrowserRouter') !== -1;
+    if (!mentionsFactory && !mentionsComponent)
+        return src;
+    const basenameLiteral = JSON.stringify(basePath);
+    let out = src;
+    // ── Pattern B first: createBrowserRouter(routes, { ...options })
+    // Handled first so Pattern A (single-arg) doesn't accidentally gobble the
+    // second-arg object. Non-greedy body match to stop at the first balanced-
+    // looking `}` — good enough for typical hand-written code.
+    //
+    // Matches:
+    //   createBrowserRouter(routes, {})
+    //   createBrowserRouter(routes, { future: { ... } })
+    //   createBrowserRouter([...], {\n  basename: '/x',\n})
+    //
+    // Multi-line safe because we use [\s\S].
+    out = out.replace(/\bcreateBrowserRouter\s*\(\s*([\s\S]*?)\s*,\s*\{([\s\S]*?)\}\s*\)/g, (match, routes, opts) => {
+        // Balance check: if `routes` contains unmatched parens, our regex ate too much.
+        if (!isBalanced(routes))
+            return match;
+        if (/\bbasename\s*:/.test(opts))
+            return match; // user set basename
+        // Trim opts to make formatting tidy; add leading space for readability.
+        const trimmedOpts = opts.replace(/^[\s,]*/, '').replace(/[\s,]*$/, '');
+        const body = trimmedOpts
+            ? `basename: ${basenameLiteral}, ${trimmedOpts}`
+            : `basename: ${basenameLiteral}`;
+        return `createBrowserRouter(${routes}, { ${body} })`;
+    });
+    // ── Pattern A: createBrowserRouter(routes)   — single-arg form
+    // Must NOT match calls that already have a second arg (handled by B above).
+    // Detect "single arg" by looking at the char right after the first balanced-
+    // looking close — if it's `)`, no second arg.
+    //
+    // We implement this manually rather than with a clever regex: scan for
+    // `createBrowserRouter(`, find the matching close paren, and check whether
+    // a comma (at depth 0) exists between them.
+    out = scanAndReplaceCreateBrowserRouterSingleArg(out, basenameLiteral);
+    // ── Pattern C: <BrowserRouter ...>  and  <BrowserRouter />
+    // Adds `basename="/preview"` if not already present. Opening tag only.
+    //
+    // Matches (examples):
+    //   <BrowserRouter>             attrs="", end=">"
+    //   <BrowserRouter />           attrs="", end=" />"
+    //   <BrowserRouter window={w}>  attrs=" window={w}", end=">"
+    //   <BrowserRouter\n  x={y}\n>  attrs="\n  x={y}\n", end=">"
+    //
+    // The regex keeps `attrs` non-empty only when real attribute chars
+    // exist; bare whitespace before `/>` ends up in `end` so we preserve
+    // the user's original whitespace style.
+    out = out.replace(/<BrowserRouter((?:\s+[^>\/\s][^>]*?)?)(\s*\/?\s*>)/g, (match, attrs, end) => {
+        if (attrs && /\bbasename\s*=/.test(attrs))
+            return match;
+        // Inject basename AFTER the attribute block (before `end`'s leading
+        // whitespace). `attrs` is either empty or starts with whitespace.
+        return `<BrowserRouter${attrs} basename=${basenameLiteral}${end}`;
+    });
+    return out;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────
+/** Check that parens + brackets + braces in `s` are balanced. */
+function isBalanced(s) {
+    let p = 0, b = 0, c = 0;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === '(')
+            p++;
+        else if (ch === ')')
+            p--;
+        else if (ch === '[')
+            b++;
+        else if (ch === ']')
+            b--;
+        else if (ch === '{')
+            c++;
+        else if (ch === '}')
+            c--;
+        if (p < 0 || b < 0 || c < 0)
+            return false;
+    }
+    return p === 0 && b === 0 && c === 0;
+}
+/**
+ * Find every `createBrowserRouter(ARGS)` where ARGS at depth-0 contains no
+ * comma (i.e. exactly one argument), and replace with
+ * `createBrowserRouter(ARGS, { basename: "..." })`.
+ *
+ * Skips any call whose argument list has a second (or more) comma-separated
+ * top-level item, since Pattern B handled those.
+ */
+function scanAndReplaceCreateBrowserRouterSingleArg(src, basenameLiteral) {
+    const needle = 'createBrowserRouter';
+    let out = '';
+    let i = 0;
+    while (i < src.length) {
+        const hit = src.indexOf(needle, i);
+        if (hit < 0) {
+            out += src.slice(i);
+            break;
+        }
+        // Ensure this is a standalone identifier (not "myCreateBrowserRouter" or
+        // "createBrowserRouterFoo"). Check the chars immediately before and after.
+        const before = hit > 0 ? src[hit - 1] : '';
+        const after = src[hit + needle.length];
+        const isIdentChar = (c) => /[\w$]/.test(c);
+        if (isIdentChar(before) || isIdentChar(after)) {
+            out += src.slice(i, hit + needle.length);
+            i = hit + needle.length;
+            continue;
+        }
+        // Skip optional whitespace, then require `(`.
+        let j = hit + needle.length;
+        while (j < src.length && /\s/.test(src[j]))
+            j++;
+        if (src[j] !== '(') {
+            out += src.slice(i, j);
+            i = j;
+            continue;
+        }
+        // Find matching `)` at depth 0 of this `(`, tracking nested parens,
+        // brackets, braces, and string/template-literal bodies. Also note if a
+        // depth-0 `,` exists (→ multi-arg form, skip; Pattern B handled it).
+        const parenStart = j;
+        let depthP = 1, depthB = 0, depthC = 0;
+        let hasTopLevelComma = false;
+        let k = parenStart + 1;
+        let strQuote = null;
+        let inLineComment = false;
+        let inBlockComment = false;
+        let inTemplate = false;
+        // Note: we skip template-literal interpolation depth tracking for simplicity.
+        // If a user embeds `createBrowserRouter(...)` inside a template literal, we
+        // just leave it alone (rare pattern).
+        while (k < src.length) {
+            const ch = src[k];
+            const nx = src[k + 1];
+            if (inLineComment) {
+                if (ch === '\n')
+                    inLineComment = false;
+                k++;
+                continue;
+            }
+            if (inBlockComment) {
+                if (ch === '*' && nx === '/') {
+                    inBlockComment = false;
+                    k += 2;
+                    continue;
+                }
+                k++;
+                continue;
+            }
+            if (strQuote) {
+                if (ch === '\\') {
+                    k += 2;
+                    continue;
+                }
+                if (ch === strQuote)
+                    strQuote = null;
+                k++;
+                continue;
+            }
+            if (inTemplate) {
+                if (ch === '\\') {
+                    k += 2;
+                    continue;
+                }
+                if (ch === '`')
+                    inTemplate = false;
+                k++;
+                continue;
+            }
+            if (ch === '/' && nx === '/') {
+                inLineComment = true;
+                k += 2;
+                continue;
+            }
+            if (ch === '/' && nx === '*') {
+                inBlockComment = true;
+                k += 2;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                strQuote = ch;
+                k++;
+                continue;
+            }
+            if (ch === '`') {
+                inTemplate = true;
+                k++;
+                continue;
+            }
+            if (ch === '(')
+                depthP++;
+            else if (ch === ')') {
+                depthP--;
+                if (depthP === 0 && depthB === 0 && depthC === 0)
+                    break;
+            }
+            else if (ch === '[')
+                depthB++;
+            else if (ch === ']')
+                depthB--;
+            else if (ch === '{')
+                depthC++;
+            else if (ch === '}')
+                depthC--;
+            else if (ch === ',' && depthP === 1 && depthB === 0 && depthC === 0) {
+                hasTopLevelComma = true;
+            }
+            k++;
+        }
+        if (depthP !== 0) {
+            // Unbalanced — can't reason about this call. Emit as-is.
+            out += src.slice(i, k);
+            i = k;
+            continue;
+        }
+        const parenEnd = k; // index of the matching `)`
+        if (hasTopLevelComma) {
+            // Multi-arg — Pattern B already processed it (or refused to). Skip.
+            out += src.slice(i, parenEnd + 1);
+            i = parenEnd + 1;
+            continue;
+        }
+        // Single-arg form — inject `, { basename: "..." }` before the `)`.
+        out += src.slice(i, parenEnd);
+        out += `, { basename: ${basenameLiteral} }`;
+        out += ')';
+        i = parenEnd + 1;
+    }
+    return out;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * ruby-repl.ts — Ruby REPL adapter.
+ *
+ * Mirrors python-repl.ts pattern: a long-lived child-facet holds the
+ * Ruby VM (instantiated once at facet module-init via the ruby-runner
+ * preamble) and per-push calls go through __rubyRun with a generated
+ * line wrapper.
+ *
+ * Approach to result-handling + incomplete detection:
+ *   - The wrapper Ruby code captures the LAST line as an expression
+ *     where possible (via Kernel#eval at TOPLEVEL_BINDING) and writes
+ *     `inspect`'d result to stdout if non-nil.
+ *   - SyntaxError-incomplete detection: try Ripper.sexp(src); if nil,
+ *     the source has an unterminated construct and we signal
+ *     'incomplete'. Ripper ships with ruby.wasm 2.9.x stdlib.
+ *     Fallback: if Ripper is unavailable, parse the SyntaxError
+ *     message for "unexpected end-of-input" / "unterminated" patterns.
+ *   - SystemExit: rescue and return exit_code.
+ *
+ * Architecture aligned with master plan §1 A5 (~280 LOC).
+ *
+ * NOT supported in v1 (deferred):
+ *   - Top-level Ractor / Fiber.yield at the REPL.
+ *   - Ctrl-C mid-execution.
+ *   - irb history pickling.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import type { FacetManager } from '../facets/manager.js';
+import type { WebSocketTerminal } from '../facets/ws-terminal.js';
+export interface RubyReplDeps {
+    facetMgr: FacetManager;
+    vfs: SqliteVFS;
+    terminal: WebSocketTerminal;
+    /** Per-user-VFS install dir for the ruby blob. */
+    installRoot: string;
+}
+/**
+ * Top-level wrapper: builds a Ruby REPL adapter, drives a ReplSession
+ * to completion, returns the exit code. Called from the ruby factory's
+ * wrapper in init.ts when `ruby` is invoked with no args.
+ */
+export declare function runRubyRepl(deps: RubyReplDeps): Promise<number>;
+//# sourceMappingURL=ruby-repl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ruby-repl.d.ts","sourceRoot":"","sources":["../../src/runtime/ruby-repl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,SAAS,CAAC;IACf,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAuND;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE"}

package/dist/runtime/ruby-repl.js

@@ -0,0 +1,229 @@
+/**
+ * ruby-repl.ts — Ruby REPL adapter.
+ *
+ * Mirrors python-repl.ts pattern: a long-lived child-facet holds the
+ * Ruby VM (instantiated once at facet module-init via the ruby-runner
+ * preamble) and per-push calls go through __rubyRun with a generated
+ * line wrapper.
+ *
+ * Approach to result-handling + incomplete detection:
+ *   - The wrapper Ruby code captures the LAST line as an expression
+ *     where possible (via Kernel#eval at TOPLEVEL_BINDING) and writes
+ *     `inspect`'d result to stdout if non-nil.
+ *   - SyntaxError-incomplete detection: try Ripper.sexp(src); if nil,
+ *     the source has an unterminated construct and we signal
+ *     'incomplete'. Ripper ships with ruby.wasm 2.9.x stdlib.
+ *     Fallback: if Ripper is unavailable, parse the SyntaxError
+ *     message for "unexpected end-of-input" / "unterminated" patterns.
+ *   - SystemExit: rescue and return exit_code.
+ *
+ * Architecture aligned with master plan §1 A5 (~280 LOC).
+ *
+ * NOT supported in v1 (deferred):
+ *   - Top-level Ractor / Fiber.yield at the REPL.
+ *   - Ctrl-C mid-execution.
+ *   - irb history pickling.
+ */
+import { ReplSession } from './repl-session.js';
+import { WASI_INSTANCE_PREAMBLE_SRC } from './wasi-instance.js';
+import { RUBY_RUNNER_PREAMBLE_TAIL } from './ruby-runner.js';
+class RubyReplAdapter {
+    pool = null;
+    deps;
+    wasmBytesAB = null;
+    ps1 = 'irb> ';
+    ps2 = 'irb* ';
+    constructor(deps) {
+        this.deps = deps;
+    }
+    banner() {
+        return ('Ruby 3.3.4 (Nimbus / ruby.wasm 2.9.x)\r\n' +
+            'Type "exit" or press Ctrl-D to exit.\r\n');
+    }
+    async push(source) {
+        // Special-case exit literally for cheaper response.
+        const trimmed = source.trim();
+        if (trimmed === 'exit' || trimmed === 'quit' || trimmed === 'exit()') {
+            return { kind: 'exit', exitCode: 0 };
+        }
+        try {
+            await this.ensurePool();
+        }
+        catch (e) {
+            return { kind: 'error', stderr: `[ruby-repl] bootstrap failed: ${e?.message || e}\n` };
+        }
+        // Build the wrapper Ruby code. We:
+        //   1. Use Ripper.sexp(source) to test for incomplete input. nil → incomplete.
+        //   2. Wrap the eval in begin/rescue. Catch SystemExit, capture status.
+        //   3. eval(src, TOPLEVEL_BINDING) — preserves user-defined ivars/locals
+        //      at the top-level binding across REPL submits.
+        //   4. If the eval returned a non-nil result, print "=> #{result.inspect}\n"
+        //      mimicking irb's display convention.
+        //
+        // The src is encoded as base64 to avoid string-escape hazards on
+        // multi-line input (heredocs, embedded quotes, unicode).
+        // Pass source via a base64-encoded literal to avoid string-escape
+        // hazards on multi-line input. The driver:
+        //   - Tries Ripper.sexp for incomplete-detection if available
+        //     (ruby.wasm stdlib may not include ripper). Fall back to a
+        //     SyntaxError-message heuristic.
+        //   - eval(source, TOPLEVEL_BINDING) preserves user-defined vars
+        //     across submits.
+        //   - irb-style `=> result.inspect` for non-nil result.
+        //   - SystemExit → exit with status.
+        //   - Other exceptions → write to $stderr and continue.
+        const srcB64 = btoa(unescape(encodeURIComponent(source)));
+        const driver = [
+            'require "base64"',
+            '__nimbus_src = Base64.decode64("' + srcB64 + '")',
+            '__nimbus_incomplete = false',
+            'begin',
+            '  require "ripper"',
+            '  __nimbus_incomplete = true if Ripper.sexp(__nimbus_src).nil?',
+            'rescue LoadError',
+            '  # ripper unavailable; rely on SyntaxError-message fallback',
+            'end',
+            'if __nimbus_incomplete',
+            '  $stdout.print "__NIMBUS_INCOMPLETE__"',
+            'else',
+            '  begin',
+            '    __nimbus_result = eval(__nimbus_src, TOPLEVEL_BINDING)',
+            '    unless __nimbus_result.nil?',
+            '      $stdout.print "=> "',
+            '      $stdout.puts __nimbus_result.inspect',
+            '    end',
+            '  rescue SystemExit => __nimbus_se',
+            '    Kernel.exit(__nimbus_se.status)',
+            '  rescue SyntaxError => __nimbus_syn',
+            '    msg = __nimbus_syn.message.to_s',
+            '    if msg =~ /unexpected end-of-input|unterminated/',
+            '      $stdout.print "__NIMBUS_INCOMPLETE__"',
+            '    else',
+            '      $stderr.puts "SyntaxError: " + msg',
+            '    end',
+            '  rescue Exception => __nimbus_exc',
+            '    $stderr.puts __nimbus_exc.class.to_s + ": " + __nimbus_exc.message.to_s',
+            '  end',
+            'end',
+        ].join('\n');
+        let result;
+        try {
+            result = await this.submitFacetFn(driver);
+        }
+        catch (e) {
+            return { kind: 'error', stderr: `[ruby-repl] dispatch failed: ${e?.message || e}\n` };
+        }
+        // Sentinel handling: if stdout ends with __NIMBUS_INCOMPLETE__ marker,
+        // signal incomplete.
+        if (result.stdout && result.stdout.includes('__NIMBUS_INCOMPLETE__')) {
+            return { kind: 'incomplete' };
+        }
+        // Non-zero exit code from Ruby = user called exit / process aborted.
+        if (result.exitCode !== 0 && result.exitCode !== undefined) {
+            return {
+                kind: 'exit',
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+        }
+        return { kind: 'output', stdout: result.stdout || '', stderr: result.stderr || '' };
+    }
+    async close() {
+        if (this.pool) {
+            try {
+                this.pool.dispose?.();
+            }
+            catch { /* fail-soft */ }
+            this.pool = null;
+        }
+    }
+    async ensurePool() {
+        if (this.pool)
+            return;
+        const { vfs, installRoot, facetMgr } = this.deps;
+        const wasmPath = `${installRoot}/share/ruby/ruby+stdlib.wasm`;
+        if (!vfs.exists(wasmPath)) {
+            throw new Error(`ruby+stdlib.wasm missing at ${wasmPath} (run 'nimbus install ruby')`);
+        }
+        const wasmBytes = vfs.readFile(wasmPath);
+        this.wasmBytesAB = toAB(wasmBytes);
+        // Compose the same preamble ruby-runner uses. WASI_INSTANCE_PREAMBLE_SRC
+        // + FinalizationRegistry shim + RUBY_RUNNER_PREAMBLE_TAIL.
+        const preamble = [
+            '// ── WASI shim preamble ──',
+            WASI_INSTANCE_PREAMBLE_SRC,
+            '',
+            '// ── FinalizationRegistry shim ──',
+            'if (typeof globalThis.FinalizationRegistry === "undefined") {',
+            '  globalThis.FinalizationRegistry = class FinalizationRegistry {',
+            '    constructor(_cleanup) {}',
+            '    register(_target, _heldValue, _token) {}',
+            '    unregister(_token) {}',
+            '  };',
+            '}',
+            '',
+            RUBY_RUNNER_PREAMBLE_TAIL,
+        ].join('\n');
+        const { NimbusLoaderPool } = await import('../loaders/loader-pool.js');
+        const env = facetMgr.env;
+        const ctx = facetMgr.ctx;
+        this.pool = new NimbusLoaderPool(env, ctx, {
+            tag: 'ruby-repl',
+            concurrency: 1,
+            omitSupervisor: true,
+            preamble,
+        });
+    }
+    async submitFacetFn(userCode) {
+        const wasmModules = { 'ruby+stdlib.wasm': this.wasmBytesAB };
+        return await this.pool.submit(rubyReplStepFacetFn, { userCode }, {
+            wasmModules,
+            timeoutMs: 60_000,
+        });
+    }
+}
+/**
+ * Facet-side function. Self-contained — serialized via fn.toString();
+ * no closure captures, no class refs, no bare 'this' word.
+ *
+ * Calls globalThis.__rubyRun (installed by RUBY_RUNNER_PREAMBLE_TAIL)
+ * with the user code wrapped by the driver above.
+ */
+function rubyReplStepFacetFn(args) {
+    const g = globalThis;
+    return (async function () {
+        const fn = g.__rubyRun;
+        if (typeof fn !== 'function') {
+            return {
+                stdout: '', stderr: '', exitCode: 127,
+                error: 'ruby-repl preamble missing: __rubyRun not in scope',
+            };
+        }
+        const r = await fn({
+            userCode: args.userCode,
+            rbArgv: ['ruby', '-e', args.userCode],
+            userEnv: { HOME: '/home/user' },
+            progName: 'ruby',
+        });
+        return {
+            stdout: r.stdout || '',
+            stderr: r.stderr || '',
+            exitCode: typeof r.exitCode === 'number' ? r.exitCode : 0,
+            error: r.error,
+        };
+    })();
+}
+function toAB(u8) {
+    return u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+}
+/**
+ * Top-level wrapper: builds a Ruby REPL adapter, drives a ReplSession
+ * to completion, returns the exit code. Called from the ruby factory's
+ * wrapper in init.ts when `ruby` is invoked with no args.
+ */
+export async function runRubyRepl(deps) {
+    const adapter = new RubyReplAdapter(deps);
+    const session = new ReplSession(adapter, deps.terminal);
+    return await session.run();
+}