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,11 @@ 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>, evaluates the script
+  first, then enters the REPL. 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

@@ -661,7 +661,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,44 @@
+// 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 injects the user's `-e` script as a JSON string literal here
+// (data, not code — a syntax error or unterminated token in `-e` cannot bleed
+// into this bootstrap). Read and clear it before any user code runs.
+declare const __BUN_EVAL_SCRIPT__: string | undefined;
+const evalScript: string | undefined = typeof __BUN_EVAL_SCRIPT__ === "string" ? __BUN_EVAL_SCRIPT__ : undefined;
+
+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.',
+  );
+
+  // `node -i -e`: an -e error is fatal (uncaught, exit 1), not caught by the
+  // REPL. Runs before REPL.start so the shim's process-wide capture callback
+  // isn't installed yet; `var`/`function` still land on globalThis.
+  if (evalScript !== undefined) {
+    require("node:vm").runInThisContext(evalScript, { filename: "[eval]", displayErrors: true });
+  }
+
+  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();
+    });
+  });
+}

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;

src/js/internal/readline/emitKeypressEvents.js

@@ -0,0 +1,94 @@
+// Ported from Node.js v26.3.0 lib/internal/readline/emitKeypressEvents.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 { SafeStringIterator, Symbol } = primordials;
+
+const { charLengthAt, CSI, emitKeys } = require("internal/readline/utils");
+const { kSawKeyPress } = require("internal/readline/interface");
+
+const { clearTimeout, setTimeout } = require("node:timers");
+const { kEscape } = CSI;
+
+const { StringDecoder } = require("node:string_decoder");
+
+const KEYPRESS_DECODER = Symbol("keypress-decoder");
+const ESCAPE_DECODER = Symbol("escape-decoder");
+
+// GNU readline library - keyseq-timeout is 500ms (default)
+const ESCAPE_CODE_TIMEOUT = 500;
+
+/**
+ * accepts a readable Stream instance and makes it emit "keypress" events
+ */
+
+function emitKeypressEvents(stream, iface = {}) {
+  if (stream[KEYPRESS_DECODER]) return;
+
+  stream[KEYPRESS_DECODER] = new StringDecoder("utf8");
+
+  stream[ESCAPE_DECODER] = emitKeys(stream);
+  stream[ESCAPE_DECODER].next();
+
+  const triggerEscape = () => stream[ESCAPE_DECODER].next("");
+  const { escapeCodeTimeout = ESCAPE_CODE_TIMEOUT } = iface;
+  let timeoutId;
+
+  function onData(input) {
+    if (stream.listenerCount("keypress") > 0) {
+      const string = stream[KEYPRESS_DECODER].write(input);
+      if (string) {
+        clearTimeout(timeoutId);
+
+        // This supports characters of length 2.
+        iface[kSawKeyPress] = charLengthAt(string, 0) === string.length;
+        iface.isCompletionEnabled = false;
+
+        let length = 0;
+        for (const character of new SafeStringIterator(string)) {
+          length += character.length;
+          if (length === string.length) {
+            iface.isCompletionEnabled = true;
+          }
+
+          try {
+            stream[ESCAPE_DECODER].next(character);
+            // Escape letter at the tail position
+            if (length === string.length && character === kEscape) {
+              timeoutId = setTimeout(triggerEscape, escapeCodeTimeout);
+            }
+          } catch (err) {
+            // If the generator throws (it could happen in the `keypress`
+            // event), we need to restart it.
+            stream[ESCAPE_DECODER] = emitKeys(stream);
+            stream[ESCAPE_DECODER].next();
+            throw err;
+          }
+        }
+      }
+    } else {
+      // Nobody's watching anyway
+      stream.removeListener("data", onData);
+      stream.on("newListener", onNewListener);
+    }
+  }
+
+  function onNewListener(event) {
+    if (event === "keypress") {
+      stream.on("data", onData);
+      stream.removeListener("newListener", onNewListener);
+    }
+  }
+
+  if (stream.listenerCount("keypress") > 0) {
+    stream.on("data", onData);
+  } else {
+    stream.on("newListener", onNewListener);
+  }
+}
+
+__node_module__.exports = emitKeypressEvents;
+
+export default __node_module__.exports;