Add interactive REPL, ref cloudflare/workers-sdk#1263

Adds a `--repl` flag to start an interactive REPL. Allows any other
option to be passed alongside, and automatically loads bindings from
`wrangler.toml` files too. Specifying a script is optional when
`--repl` is enabled.

Author: mrbbot

packages/cli-parser/test/help.spec.ts

@@ -48,6 +48,7 @@ Core Options:
  -V, --verbose               Enable verbose logging                    [boolean]
      --(no-)update-check     Enable update checker (enabled by         [boolean]
                              default)
+     --repl                  Enable interactive REPL                   [boolean]
      --root                  Path to resolve files relative to          [string]
      --mount                 Mount additional named      [array:NAME=PATH[@ENV]]
                              workers

packages/core/src/index.ts

@@ -828,19 +828,21 @@ export class MiniflareCore<
 
     // Log bundle size and warning if too big
     // noinspection JSObjectNullOrUndefined
-    this.#ctx.log.info(
-      `Worker reloaded!${
-        res?.bundleSize !== undefined ? ` (${formatSize(res.bundleSize)})` : ""
-      }`
-    );
-    // TODO (someday): compress asynchronously
-    // noinspection JSObjectNullOrUndefined
-    if (res?.bundleSize !== undefined && res.bundleSize > 1_048_576) {
-      this.#ctx.log.warn(
-        "Worker's uncompressed size exceeds the 1MiB limit! " +
-          "Note that your worker will be compressed during upload " +
-          "so you may still be able to deploy it."
+    if (res) {
+      this.#ctx.log.info(
+        `Worker reloaded!${
+          res.bundleSize !== undefined ? ` (${formatSize(res.bundleSize)})` : ""
+        }`
       );
+      // TODO (someday): compress asynchronously
+      // noinspection JSObjectNullOrUndefined
+      if (res.bundleSize !== undefined && res.bundleSize > 1_048_576) {
+        this.#ctx.log.warn(
+          "Worker's uncompressed size exceeds the 1MiB limit! " +
+            "Note that your worker will be compressed during upload " +
+            "so you may still be able to deploy it."
+        );
+      }
     }
 
     // Update watched paths if watching

packages/core/src/plugins/core.ts

@@ -104,6 +104,7 @@ export interface CoreOptions {
   debug?: boolean;
   verbose?: boolean;
   updateCheck?: boolean;
+  repl?: boolean;
   // Replaced in MiniflareCoreOptions with something plugins-specific
   mounts?: Record<string, string | CoreOptions | BindingsOptions>;
   name?: string;
@@ -286,6 +287,12 @@ export class CorePlugin extends Plugin<CoreOptions> implements CoreOptions {
   })
   updateCheck?: boolean;
 
+  @Option({
+    type: OptionType.BOOLEAN,
+    description: "Enable interactive REPL",
+  })
+  repl?: boolean;
+
   @Option({
     type: OptionType.STRING,
     name: "root",

packages/core/test/index.mounts.spec.ts

@@ -418,7 +418,6 @@ test("MiniflareCore: dispose: disposes of mounts too", async (t) => {
     [LogLevel.INFO, "Worker reloaded! (2B)"],
     [LogLevel.DEBUG, "Mount Routes: <none>"],
     [LogLevel.DEBUG, "Reloading worker..."],
-    [LogLevel.INFO, "Worker reloaded!"],
   ]);
 
   log.logs = [];

packages/core/test/index.spec.ts

@@ -808,7 +808,6 @@ test("MiniflareCore: #watcherCallback: re-runs setup for plugins' changed paths"
     [LogLevel.DEBUG, "Reloading worker..."],
     [LogLevel.INFO, "beforeReload"],
     [LogLevel.INFO, "reload"],
-    [LogLevel.INFO, "Worker reloaded!"],
   ]);
 
   // Update test2 contents, expecting TestPlugin setup to run
@@ -822,7 +821,6 @@ test("MiniflareCore: #watcherCallback: re-runs setup for plugins' changed paths"
     [LogLevel.DEBUG, "Reloading worker..."],
     [LogLevel.INFO, "beforeReload"],
     [LogLevel.INFO, "reload"],
-    [LogLevel.INFO, "Worker reloaded!"],
   ]);
 });
 test("MiniflareCore: #watcherCallback: re-runs setup for script-providing plugins if any beforeSetup ran", async (t) => {
@@ -959,7 +957,6 @@ test("MiniflareCore: setOptions: updates options and reloads worker", async (t)
     [LogLevel.INFO, "beforeReload"],
     [LogLevel.VERBOSE, "- reload(TestPlugin)"],
     [LogLevel.INFO, "reload"],
-    [LogLevel.INFO, "Worker reloaded!"],
   ];
   t.deepEqual(log.logs, expectedLogs);
 });

packages/core/test/plugins/core.spec.ts

@@ -54,6 +54,8 @@ test("CorePlugin: parses options from argv", (t) => {
     "--watch",
     "--debug",
     "--verbose",
+    "--no-update-check",
+    "--repl",
     "--root",
     "root",
     "--mount",
@@ -91,6 +93,8 @@ test("CorePlugin: parses options from argv", (t) => {
     watch: true,
     debug: true,
     verbose: true,
+    updateCheck: false,
+    repl: true,
     rootPath: "root",
     mounts: {
       api: {
@@ -194,6 +198,7 @@ test("CorePlugin: parses options from wrangler config", async (t) => {
     debug: undefined,
     verbose: undefined,
     updateCheck: false,
+    repl: undefined,
     rootPath: undefined,
     mounts: {
       api: {

packages/miniflare/src/api.ts

@@ -64,6 +64,7 @@ export type MiniflareOptions = Omit<
 > & {
   log?: Log;
   sourceMap?: boolean;
+  scriptRequired?: boolean;
 };
 
 export class Miniflare extends MiniflareCore<Plugins> {
@@ -84,7 +85,7 @@ export class Miniflare extends MiniflareCore<Plugins> {
         log: options?.log ?? new NoOpLog(),
         storageFactory,
         scriptRunner: new VMScriptRunner(),
-        scriptRequired: true,
+        scriptRequired: options?.scriptRequired ?? true,
       },
       options
     );

packages/miniflare/src/cli.ts

@@ -5,6 +5,7 @@ import type { Options } from "@miniflare/shared";
 import { red } from "kleur/colors";
 import type { MiniflareOptions } from "miniflare";
 import open from "open";
+import { startREPL } from "./repl";
 import { updateCheck } from "./updater";
 
 function suppressWarnings() {
@@ -89,12 +90,27 @@ async function main() {
   mfOptions.sourceMap = true;
   // Catch and log unhandled rejections as opposed to crashing
   mfOptions.logUnhandledRejections = true;
+  if (mfOptions.repl) {
+    // Allow REPL to be started without a script
+    mfOptions.scriptRequired = false;
+    // Disable file watching in REPL
+    mfOptions.watch = false;
+    // Allow async I/O in REPL without request context
+    mfOptions.globalAsyncIO = true;
+    mfOptions.globalTimers = true;
+    mfOptions.globalRandom = true;
+  }
 
   const mf = new Miniflare(mfOptions);
   try {
-    // Start Miniflare development server
-    await mf.startServer();
-    await mf.startScheduler();
+    if (mfOptions.repl) {
+      // Start Miniflare REPL
+      await startREPL(mf);
+    } else {
+      // Start Miniflare development server
+      await mf.startServer();
+      await mf.startScheduler();
+    }
   } catch (e: any) {
     mf.log.error(e);
     process.exitCode = 1;

packages/miniflare/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./api";
 export * from "./storage";
+export * from "./repl";
 export * from "./updater";
 export { Log, LogLevel } from "@miniflare/shared";
 export { Request, Response } from "@miniflare/core";

packages/miniflare/src/repl.ts

@@ -0,0 +1,25 @@
+import repl from "repl";
+import vm from "vm";
+import { CorePluginSignatures, MiniflareCore } from "@miniflare/core";
+
+interface MutableContextREPLServer extends repl.REPLServer {
+  context: vm.Context;
+}
+
+export async function startREPL<Plugins extends CorePluginSignatures>(
+  mf: MiniflareCore<Plugins>
+): Promise<void> {
+  // Get global scope and bindings
+  const globalScope = await mf.getGlobalScope();
+  const bindings = await mf.getBindings();
+
+  // Create custom context
+  const context = vm.createContext(globalScope, {
+    codeGeneration: { strings: false, wasm: false },
+  });
+  // Assign `env` as a global variable so people can use module worker's syntax
+  context.env = bindings;
+
+  // Start the REPL with the custom context
+  (repl.start() as MutableContextREPLServer).context = context;
+}