node:repl: replace the stub with Node v26.3.0's REPL — v26 readline stack, acorn recoverable-parse + top-level await, completion, history, --interactive (82 vendored upstream tests)

.prettierignore

@@ -25,3 +25,17 @@ docs/bundler/minifier.mdx
 # `_`/`*` differently every pass), so autofix.ci ping-pongs commits forever.
 # Not authored by hand; no value in normalizing it.
 docs/.rust-rewrite-verified-claims.md
+
+# Verbatim ports from Node.js v26.3.0 (lib/) — keep close to upstream
+# (mirrors the oxlint.json ignore block for the same files)
+src/js/node/repl.js
+src/js/node/readline.js
+src/js/node/readline.promises.js
+src/js/internal/repl.js
+src/js/internal/readline
+src/js/internal/repl/history.js
+src/js/internal/repl/utils.js
+src/js/internal/repl/completion.js
+src/js/internal/repl/await.js
+src/js/internal/repl/acorn.js
+src/js/internal/repl/acorn-walk.js

LICENSE.md

@@ -54,6 +54,8 @@ For compatibility reasons, the following packages are embedded into Bun's binary
 
 | Package | License |
 |---------|---------|
+| [`acorn`](https://github.com/acornjs/acorn) | MIT |
+| [`acorn-walk`](https://github.com/acornjs/acorn) | MIT |
 | [`assert`](https://npmjs.com/package/assert) | MIT |
 | [`browserify-zlib`](https://npmjs.com/package/browserify-zlib) | MIT |
 | [`buffer`](https://npmjs.com/package/buffer) | MIT |

docs/project/license.mdx

@@ -50,6 +50,8 @@ For compatibility, Bun embeds the following packages into its binary and injects
 
 | Package                                                                  | License |
 | ------------------------------------------------------------------------ | ------- |
+| [`acorn`](https://github.com/acornjs/acorn)                              | MIT     |
+| [`acorn-walk`](https://github.com/acornjs/acorn)                         | MIT     |
 | [`assert`](https://npmjs.com/package/assert)                             | MIT     |
 | [`browserify-zlib`](https://npmjs.com/package/browserify-zlib)           | MIT     |
 | [`buffer`](https://npmjs.com/package/buffer)                             | MIT     |

docs/runtime/nodejs-compat.mdx

@@ -169,7 +169,7 @@ This page is updated regularly and reflects the latest version of Bun's compatib
 
 ### [`node:repl`](https://nodejs.org/api/repl.html)
 
-🔴 Not implemented.
+🟡 Mostly implemented. `bun --interactive` starts a Node.js-compatible REPL. Result previews (which need V8's inspector-based side-effect-free eval), tab-completion of `let`/`const`/`class` bindings in `useGlobal: true` mode, and some V8-specific error-message wording differ.
 
 ### [`node:sqlite`](https://nodejs.org/api/sqlite.html)
 

docs/snippets/cli/run.mdx

@@ -62,6 +62,13 @@ bun run <file or script>
   Control the shell used for <code>package.json</code> scripts. Supports either <code>bun</code> or <code>system</code>
 </ParamField>
 
+<ParamField path="--interactive" type="boolean">
+  Open the Node.js-compatible REPL (<code>node:repl</code>). When combined with <code>-e</code>, starts the REPL and
+  then evaluates the script. Under <code>--interactive</code>, <code>-e</code> is raw JavaScript (matching{" "}
+  <code>node -i -e</code>); use <code>bun repl</code> for TypeScript. Distinct from <code>bun repl</code>, which is
+  Bun's native REPL.
+</ParamField>
+
 <ParamField path="--smol" type="boolean">
   Use less memory, but run garbage collection more often
 </ParamField>

oxlint.json

@@ -44,6 +44,19 @@
     "bench/react-hello-world/*.js",
     "bun.lock",
 
+    // Verbatim ports from Node.js v26.3.0 (lib/) — keep close to upstream
+    "src/js/node/repl.js",
+    "src/js/node/readline.js",
+    "src/js/node/readline.promises.js",
+    "src/js/internal/repl.js",
+    "src/js/internal/readline/**",
+    "src/js/internal/repl/history.js",
+    "src/js/internal/repl/utils.js",
+    "src/js/internal/repl/completion.js",
+    "src/js/internal/repl/await.js",
+    "src/js/internal/repl/acorn.js",
+    "src/js/internal/repl/acorn-walk.js",
+
     "test/js/node/**/parallel/**",
     "test/js/node/test/fixtures", // full of JS with intentional syntax errors
     "test/snippets/**",

scripts/build/flags.ts

@@ -633,7 +633,7 @@ export const bunOnlyFlags: Flag[] = [
     flag: ["-fconstexpr-steps=6000000", "-fconstexpr-depth=54"],
     when: c => c.unix,
     lang: "cxx",
-    desc: "Raise constexpr limits (JSC uses heavy constexpr; the embedded module registry literals are large)",
+    desc: "Raise constexpr limits (JSC uses heavy constexpr; under ASSERT_ENABLED, ASCIILiteral::fromLiteralUnsafe constexpr-validates the largest embedded builtin source in InternalModuleRegistryConstants.h char by char)",
   },
   {
     flag: ["-fno-pic", "-fno-pie"],

src/codegen/bundle-modules.ts

@@ -141,6 +141,15 @@ for (let i = 0; i < nativeStartIndex; i++) {
       true,
       x => requireTransformer(x, moduleList[i]),
     );
+    // Guard rail: builtin-parser.ts's regex-position heuristic only recognises
+    // `/` as regex-start after `[(,=;:{]|return|=>`; a regex whose body has `)`
+    // or `}` in any other position silently truncates. Fail loudly here.
+    if (processed.rest.trim() !== "") {
+      throw new Error(
+        `sliceSourceCode truncated ${moduleList[i]} — likely a regex literal in a position builtin-parser.ts doesn't recognise. ` +
+          `Leftover starts: ${processed.rest.slice(0, 80)}`,
+      );
+    }
     let fileToTranspile = `// GENERATED TEMP FILE - DO NOT EDIT
 // Sourced from src/js/${moduleList[i]}
 ${importStatements.join("\n")}

src/js/eval/node-repl.ts

@@ -0,0 +1,90 @@
+// Entry script for `bun --interactive` (`-i` is taken by `--install=fallback`): starts the Node.js-compatible
+// REPL (the ported node:repl) the way Node's internal/main/repl.js does. This
+// file runs as a regular entrypoint (not a builtin), so it reaches
+// createInternalRepl via a Symbol.for hook on node:repl and never re-implements
+// the NODE_REPL_* env parsing that internal/repl.js already owns.
+
+// exec_node_repl stashes the user's `-e` bytes on `process._eval` (undefined
+// when no `-e`), so no source splicing — a syntax error or unterminated
+// token in `-e` cannot bleed into this bootstrap.
+const evalScript: string | undefined = (process as { _eval?: string })._eval;
+
+const ext = process.env.NODE_REPL_EXTERNAL_MODULE;
+if (ext) {
+  // Node loads this in place of the built-in REPL (lib/internal/main/repl.js).
+  require(require("node:path").resolve(ext));
+} else {
+  const REPL = require("node:repl");
+  const createInternalRepl = (REPL as Record<symbol, Function>)[Symbol.for("bun.repl.createInternalRepl")];
+
+  console.log(
+    `Welcome to Bun v${(globalThis as any).Bun.version} (Node.js-compatible REPL, node:repl ${process.version}).\n` +
+      'Type ".help" for more information.',
+  );
+
+  createInternalRepl(process.env, (err: Error | null, replServer: any) => {
+    if (err) throw err;
+
+    replServer.on("exit", () => {
+      if (replServer.historyManager?.isFlushing) {
+        replServer.once("flushHistory", () => process.exit());
+        return;
+      }
+      process.exit();
+    });
+  });
+
+  // `node -i -e`: node evaluates AFTER createInternalRepl (which starts the
+  // REPL synchronously), so the REPL's globals are already in place.
+  if (evalScript !== undefined) {
+    evalWithNodeBindings(evalScript);
+  }
+}
+
+// Mirrors node's runScriptInContext: it does NOT wrap the body as a CJS
+// module — it publishes the bindings onto the global and runs the body in
+// global scope, so `var`/`function` still land on globalThis while
+// require/module/exports/__dirname/__filename resolve.
+function evalWithNodeBindings(code: string) {
+  const Module = require("node:module");
+  // process.cwd() throws when the working directory has been deleted; node's
+  // evalScript uses tryGetCwd() here, falling back to the executable's dir.
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = require("node:path").dirname(process.execPath);
+  }
+  const name = "[eval]";
+
+  const mod = new Module(name);
+  mod.filename = require("node:path").join(cwd, name);
+  mod.paths = Module._nodeModulePaths(cwd);
+
+  const global_ = globalThis as any;
+  const origModule = global_.module;
+  global_.module = mod;
+  global_.exports = mod.exports;
+  // node's wrapper is compiled as `${name}-wrapper`, so its __dirname is
+  // dirname("[eval]-wrapper") === "." — decoupled from module.filename, which
+  // stays the cwd-joined path used for require resolution.
+  global_.__dirname = ".";
+  global_.__filename = name;
+  global_.require = Module.createRequire(mod.filename);
+
+  try {
+    require("node:vm").runInThisContext(code, { filename: name, displayErrors: true });
+  } catch (e) {
+    // An -e error is fatal in node even with the REPL up. Report and exit here
+    // rather than rethrowing: the REPL is already live, so an uncaught throw
+    // races its EOF-driven exit and the process can leave 0 with the error
+    // unreported (empty stdin loses that race every time).
+    try {
+      process.setUncaughtExceptionCaptureCallback(null);
+    } catch {}
+    console.error(e);
+    process.exit(1);
+  } finally {
+    if (origModule !== undefined) global_.module = origModule;
+  }
+}

src/js/internal/readline/callbacks.js

@@ -0,0 +1,122 @@
+// Ported from Node.js v26.3.0 lib/internal/readline/callbacks.js for Bun's node:repl.
+// Attribution: derived from Node.js, MIT licensed (Node.js contributors).
+// prettier-ignore
+const primordials = require("internal/repl/node-primordials");
+var __node_module__ = { exports: {} };
+
+const { NumberIsNaN } = primordials;
+
+const {
+  codes: { ERR_INVALID_ARG_VALUE, ERR_INVALID_CURSOR_POS },
+} = require("internal/repl/node-errors");
+
+const { validateFunction } = require("internal/validators");
+const { CSI } = require("internal/readline/utils");
+
+const { kClearLine, kClearScreenDown, kClearToLineBeginning, kClearToLineEnd } = CSI;
+
+/**
+ * moves the cursor to the x and y coordinate on the given stream
+ */
+
+function cursorTo(stream, x, y, callback) {
+  if (callback !== undefined) {
+    validateFunction(callback, "callback");
+  }
+
+  if (typeof y === "function") {
+    callback = y;
+    y = undefined;
+  }
+
+  if (NumberIsNaN(x)) throw new ERR_INVALID_ARG_VALUE("x", x);
+  if (NumberIsNaN(y)) throw new ERR_INVALID_ARG_VALUE("y", y);
+
+  if (stream == null || (typeof x !== "number" && typeof y !== "number")) {
+    if (typeof callback === "function") process.nextTick(callback, null);
+    return true;
+  }
+
+  if (typeof x !== "number") throw new ERR_INVALID_CURSOR_POS();
+
+  const data = typeof y !== "number" ? CSI`${x + 1}G` : CSI`${y + 1};${x + 1}H`;
+  return stream.write(data, callback);
+}
+
+/**
+ * moves the cursor relative to its current location
+ */
+
+function moveCursor(stream, dx, dy, callback) {
+  if (callback !== undefined) {
+    validateFunction(callback, "callback");
+  }
+
+  if (stream == null || !(dx || dy)) {
+    if (typeof callback === "function") process.nextTick(callback, null);
+    return true;
+  }
+
+  let data = "";
+
+  if (dx < 0) {
+    data += CSI`${-dx}D`;
+  } else if (dx > 0) {
+    data += CSI`${dx}C`;
+  }
+
+  if (dy < 0) {
+    data += CSI`${-dy}A`;
+  } else if (dy > 0) {
+    data += CSI`${dy}B`;
+  }
+
+  return stream.write(data, callback);
+}
+
+/**
+ * clears the current line the cursor is on:
+ *   -1 for left of the cursor
+ *   +1 for right of the cursor
+ *    0 for the entire line
+ */
+
+function clearLine(stream, dir, callback) {
+  if (callback !== undefined) {
+    validateFunction(callback, "callback");
+  }
+
+  if (stream === null || stream === undefined) {
+    if (typeof callback === "function") process.nextTick(callback, null);
+    return true;
+  }
+
+  const type = dir < 0 ? kClearToLineBeginning : dir > 0 ? kClearToLineEnd : kClearLine;
+  return stream.write(type, callback);
+}
+
+/**
+ * clears the screen from the current position of the cursor down
+ */
+
+function clearScreenDown(stream, callback) {
+  if (callback !== undefined) {
+    validateFunction(callback, "callback");
+  }
+
+  if (stream === null || stream === undefined) {
+    if (typeof callback === "function") process.nextTick(callback, null);
+    return true;
+  }
+
+  return stream.write(kClearScreenDown, callback);
+}
+
+__node_module__.exports = {
+  clearLine,
+  clearScreenDown,
+  cursorTo,
+  moveCursor,
+};
+
+export default __node_module__.exports;