@tlockney/cdp-kernel 0.2.0 → 0.3.0

package/dist/workerd-target.js

@@ -0,0 +1,450 @@
+// The workerd target (#8). Cells run inside a driver Worker
+// (runtime/workerd-worker.mjs): outside a request workerd has no IoContext,
+// so timers, fetch and randomness throw. The host opens one WebSocket
+// session to the driver and sends every request over it as a JSON message;
+// all of them run in that session request's IoContext, so I/O objects and
+// pending work carry over between cells (#26). Console output, iopub
+// messages and replies come back the same way. Cells are transformed as for
+// Bun (transformCellForEval).
+//
+// Outside a Workers project the host serves the driver on a workerd of its
+// own, behind a Unix socket in a private temporary directory, with a
+// per-launch token (RawWorkerd). In a project it uses the project's
+// Miniflare instead, for its bindings (src/workers-project.ts).
+//
+// workerd can't load modules at runtime beyond its builtins, so whatever
+// else a cell imports is bundled here with esbuild and sent with the cell.
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { execFileSync, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "esbuild";
+import { transformCellForEval } from "./transform.js";
+import { runtimeDir } from "./package.js";
+import { Interrupted, isTargetMessage } from "./target.js";
+import { connectUnixWebSocket } from "./ws-client.js";
+import { findWranglerConfig, startMiniflare } from "./workers-project.js";
+import { ensureInstalled, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
+/** The driver Worker's modules; the first is its main module. */
+export const WORKER_MODULES = ["workerd-worker.mjs", "display.mjs", "comm.mjs", "widget.mjs", "evaluator.mjs"];
+/** See BunTarget: how long an interrupted cell has to show it isn't busy. */
+export const INTERRUPT_GRACE_MS = 500;
+export function restartNote(runtime) {
+    return `[cdp-kernel] ${runtime} was busy and can't be interrupted in place, so it was stopped; ` +
+        "it restarts on the next cell, without the earlier cells' state";
+}
+export const RESTART_NOTE = restartNote("workerd");
+// nodejs_compat is on by default from this compatibility date, and workerd
+// warns when it's also listed.
+const NODEJS_COMPAT_DEFAULT = "2026-08-04";
+const BUILTIN = /^(?:node|cloudflare|workerd):/;
+export function workerdConfig({ socket, compatibilityDate }) {
+    const modules = WORKER_MODULES.map((name) => `(name = ${JSON.stringify(name)}, esModule = embed ${JSON.stringify(name)})`);
+    const flags = compatibilityDate < NODEJS_COMPAT_DEFAULT ? `["nodejs_compat"]` : "[]";
+    return `using Workerd = import "/workerd/workerd.capnp";
+
+const config :Workerd.Config = (
+  services = [
+    (name = "cdpk", worker = .driver),
+    (name = "internet", network = (allow = ["public", "private", "local"], tlsOptions = (trustBrowserCas = true))),
+  ],
+  sockets = [(name = "host", address = ${JSON.stringify(`unix:${socket}`)}, http = (), service = "cdpk")],
+);
+
+const driver :Workerd.Worker = (
+  modules = [
+    ${modules.join(",\n    ")},
+  ],
+  compatibilityDate = ${JSON.stringify(compatibilityDate)},
+  compatibilityFlags = ${flags},
+  globalOutbound = "internet",
+  bindings = [
+    (name = "UNSAFE", unsafeEval = void),
+    (name = "TOKEN", fromEnvironment = "CDPK_TOKEN"),
+    (name = "META", fromEnvironment = "CDPK_META"),
+  ],
+);
+`;
+}
+/**
+ * A Workers project has workerd in its node_modules (wrangler and miniflare
+ * depend on it), so look there first, from the notebook's directory up;
+ * otherwise use the one on PATH.
+ */
+export function findWorkerd(cwd) {
+    for (let dir = cwd;; dir = dirname(dir)) {
+        const bin = join(dir, "node_modules", ".bin", process.platform === "win32" ? "workerd.cmd" : "workerd");
+        if (existsSync(bin))
+            return bin;
+        if (dirname(dir) === dir)
+            return "workerd";
+    }
+}
+/** "workerd 2026-10-15" -> "2026-10-15": the newest date it supports. */
+export function compatibilityDateOf(versionOutput) {
+    const m = /\b(\d{4}-\d{2}-\d{2})\b/.exec(versionOutput);
+    if (!m)
+        throw new Error(`can't read a date from workerd --version: ${versionOutput.trim()}`);
+    return m[1];
+}
+/** The literal specifiers a transformed cell imports, in order. */
+export function importSpecifiers(script) {
+    const found = new Set();
+    for (const m of script.matchAll(/__cdpk\.import\(("(?:[^"\\]|\\.)*")/g)) {
+        const specifier = JSON.parse(m[1]);
+        if (typeof specifier === "string")
+            found.add(specifier);
+    }
+    return [...found];
+}
+const NODE_BUILTINS = builtinModules.filter((name) => !name.startsWith("_"));
+/**
+ * Bundles `specifier`, as imported from `cwd`, into global code whose value
+ * is a promise of the module's namespace. npm: and jsr: install into the
+ * npm cache, as on a Node target. Builtins stay external and are handed to
+ * the bundle as `require` (workerd-worker.mjs's requireFor). A specifier
+ * that can't be bundled becomes code that throws when imported, so the
+ * error appears in the cell.
+ */
+export async function bundleModule(specifier, cwd) {
+    try {
+        let entry = specifier;
+        let resolveDir = cwd;
+        const pkg = specifier.startsWith("npm:")
+            ? parsePackageSpecifier(specifier.slice(4))
+            : specifier.startsWith("jsr:")
+                ? jsrToNpm(specifier.slice(4))
+                : null;
+        if (pkg) {
+            const { dir, alias } = ensureInstalled(pkg);
+            entry = alias + pkg.subpath;
+            resolveDir = dir;
+        }
+        const result = await build({
+            stdin: { contents: `import * as ns from ${JSON.stringify(entry)};\nexport { ns };\n`, resolveDir, loader: "js" },
+            bundle: true,
+            write: false,
+            format: "iife",
+            globalName: "__cdpk_bundle",
+            platform: "browser",
+            // What wrangler resolves for Workers.
+            conditions: ["workerd", "worker", "browser"],
+            mainFields: ["browser", "module", "main"],
+            external: ["node:*", "cloudflare:*", "workerd:*", ...NODE_BUILTINS],
+            target: "esnext",
+            metafile: true,
+            logLevel: "silent",
+        });
+        const externals = new Set();
+        for (const output of Object.values(result.metafile.outputs)) {
+            for (const imported of output.imports)
+                if (imported.external)
+                    externals.add(imported.path);
+        }
+        return `(async () => { const require = await __cdpk.requireFor(${JSON.stringify([...externals])});\n` +
+            `${result.outputFiles[0].text}\nreturn __cdpk_bundle.ns; })()`;
+    }
+    catch (err) {
+        // esbuild's failures carry structured errors; their text reads best.
+        const errors = err.errors;
+        const texts = Array.isArray(errors) ? errors.map((e) => e?.text).filter((t) => typeof t === "string") : [];
+        const message = texts.length > 0 ? texts.join("; ") : err instanceof Error ? err.message : String(err);
+        return `Promise.reject(new TypeError(${JSON.stringify(`Cannot import "${specifier}": ${message}`)}))`;
+    }
+}
+/** Rejects a request whose reply the host no longer waits for. */
+class Abandoned extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** What import.meta says in a cell: the notebook's directory, not workerd's. */
+export function cellMeta(cwd) {
+    const replUrl = new URL("$cdpk$repl.mjs", pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/"));
+    return { url: replUrl.href, dirname: cwd, filename: join(cwd, "$cdpk$repl.mjs") };
+}
+/** The driver on a workerd of its own, behind a Unix socket. */
+export class RawWorkerd {
+    runtime;
+    channel;
+    #child;
+    constructor(child, channel, runtime) {
+        this.#child = child;
+        this.channel = channel;
+        this.runtime = runtime;
+    }
+    static async start(cwd, executable) {
+        const workerd = executable ?? findWorkerd(cwd);
+        const compatibilityDate = compatibilityDateOf(execFileSync(workerd, ["--version"], { encoding: "utf8" }));
+        const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
+        // mkdtemp makes the directory 0700: only this user reaches the socket,
+        // and the token stops anything else running as them by accident.
+        const dir = mkdtempSync(join(tmpdir(), "cdpk-workerd-"));
+        const socket = join(dir, "sock");
+        for (const name of WORKER_MODULES)
+            copyFileSync(join(source, name), join(dir, name));
+        writeFileSync(join(dir, "config.capnp"), workerdConfig({ socket, compatibilityDate }));
+        const token = randomBytes(32).toString("hex");
+        const env = { ...process.env, CDPK_TOKEN: token, CDPK_META: JSON.stringify(cellMeta(cwd)) };
+        // --experimental: the UnsafeEval binding.
+        const child = spawn(workerd, ["serve", "config.capnp", "--experimental"], { cwd: dir, stdio: ["ignore", "pipe", "pipe"], env });
+        child.once("exit", () => rmSync(dir, { recursive: true, force: true }));
+        // Cell output is captured inside the Worker; what workerd itself prints
+        // (its own warnings, errors from background work) goes to the server log.
+        let early = "";
+        const log = (chunk) => {
+            early += chunk.toString();
+            process.stderr.write(`[cdp-kernel workerd] ${chunk}`);
+        };
+        child.stdout?.on("data", log);
+        child.stderr?.on("data", log);
+        const exited = new Promise((_, reject) => {
+            child.once("error", reject);
+            child.once("exit", (code) => reject(new Error(`workerd exited (${code}) before it was ready:\n${early}`)));
+        });
+        exited.catch(() => { });
+        const ready = (async () => {
+            for (let i = 0;; i++) {
+                try {
+                    return await connectUnixWebSocket(socket, { headers: { "x-cdpk-token": token } });
+                }
+                catch (err) {
+                    if (i >= 200)
+                        throw err;
+                    await new Promise((r) => setTimeout(r, 50));
+                }
+            }
+        })();
+        try {
+            return new RawWorkerd(child, await Promise.race([ready, exited]), compatibilityDate);
+        }
+        catch (err) {
+            child.kill();
+            throw err;
+        }
+    }
+    stop(now) {
+        this.#child.kill(now ? "SIGKILL" : "SIGTERM");
+    }
+    onExit(listener) {
+        this.#child.once("exit", listener);
+    }
+}
+export class WorkerdTarget {
+    runtime;
+    versions;
+    notice;
+    transform = transformCellForEval;
+    #host;
+    #cwd;
+    #events;
+    /** Specifiers whose bundle this workerd has been sent. */
+    #sent = new Set();
+    #pending = new Map();
+    /** Requests that interrupt() abandons when the driver can still answer. */
+    #interruptible = new Set();
+    #nextId = 0;
+    #interrupted = false;
+    #stopNote;
+    #exitedOnce = false;
+    constructor(host, cwd, events, runtime) {
+        this.runtime = runtime;
+        this.#host = host;
+        this.versions = { runtime: host.runtime, engine: "V8" };
+        this.#cwd = cwd;
+        this.#events = events;
+        host.channel.onMessage((text) => this.#receive(text));
+        host.channel.onClose(() => this.#exited(null));
+        host.onExit((code) => this.#exited(code));
+    }
+    /**
+     * In a Workers project (a wrangler config at or above `cwd`), the
+     * project's own Miniflare runs the driver with the project's bindings;
+     * otherwise a workerd of its own does (#26).
+     */
+    static async launch(events, options = {}) {
+        const cwd = options.cwd ?? process.cwd();
+        const project = findWranglerConfig(cwd);
+        let host = null;
+        let notice;
+        if (project !== null) {
+            try {
+                host = await startMiniflare(project, cwd);
+            }
+            catch (err) {
+                // Like a broken deno.json (#13): say why in the first cell, and run
+                // without the project.
+                const reason = err instanceof Error ? err.message : String(err);
+                notice = `[cdp-kernel] couldn't load the Workers project at ${project}: ${reason}; running without its bindings`;
+            }
+        }
+        host ??= await RawWorkerd.start(cwd, options.executable);
+        return await WorkerdTarget.open(host, cwd, events, "workerd", notice);
+    }
+    /**
+     * A target over a started host's session. `notice` (a project that
+     * failed to load) is replaced by the bindings when the host has a project.
+     */
+    static async open(host, cwd, events, runtime, notice) {
+        const target = new WorkerdTarget(host, cwd, events, runtime);
+        try {
+            const { v8, bindings, worker } = await target.#request("info");
+            if (typeof v8 === "string" && v8)
+                target.versions.engine = `V8 ${v8}`;
+            if (host.project !== undefined) {
+                const names = Array.isArray(bindings) ? bindings.map(String).sort().join(", ") : "";
+                notice = `[cdp-kernel] Workers project ${host.project}: env has ${names || "no bindings"}` +
+                    (worker === true ? "; worker is its default export" : "");
+            }
+        }
+        catch (err) {
+            target.kill();
+            throw err;
+        }
+        target.notice = notice;
+        return target;
+    }
+    #receive(text) {
+        const msg = JSON.parse(text);
+        if (isRecord(msg) && msg.kind === "stream") {
+            this.#events.stream(msg.name === "stderr" ? "stderr" : "stdout", String(msg.text));
+        }
+        else if (isTargetMessage(msg)) {
+            this.#events.message(msg);
+        }
+        else if (isRecord(msg) && msg.kind === "reply") {
+            const id = Number(msg.id);
+            const pending = this.#pending.get(id);
+            if (!pending)
+                return; // abandoned
+            this.#pending.delete(id);
+            this.#interruptible.delete(id);
+            if (typeof msg.failure === "string")
+                pending.reject(new Error(msg.failure));
+            else
+                pending.resolve(msg);
+        }
+    }
+    #exited(code) {
+        if (this.#exitedOnce)
+            return;
+        this.#exitedOnce = true;
+        // The exit (and its note) is reported before the requests it cut off
+        // fail, so the note lands in the interrupted cell's output.
+        this.#events.exit(code, this.#stopNote);
+        for (const pending of this.#pending.values())
+            pending.reject(new Abandoned(`workerd exited (${code})`));
+        this.#pending.clear();
+    }
+    #request(op, params = {}, interruptible = false) {
+        const id = ++this.#nextId;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve, reject });
+            if (interruptible)
+                this.#interruptible.add(id);
+            try {
+                this.#host.channel.send(JSON.stringify({ id, op, ...params }));
+            }
+            catch {
+                this.#pending.delete(id);
+                reject(new Abandoned("the workerd session is closed"));
+            }
+        });
+    }
+    async #interruptibly(op, params, what) {
+        this.#interrupted = false;
+        try {
+            return await this.#request(op, params, true);
+        }
+        catch (err) {
+            if (err instanceof Abandoned || this.#interrupted)
+                throw new Interrupted(`${what} interrupted`);
+            throw err;
+        }
+    }
+    async evaluate(script) {
+        const modules = {};
+        for (const specifier of importSpecifiers(script)) {
+            if (BUILTIN.test(specifier) || this.#sent.has(specifier))
+                continue;
+            modules[specifier] = await bundleModule(specifier, this.#cwd);
+            // A failed bundle is rebuilt next time, after the user fixes it.
+            if (!modules[specifier].startsWith("Promise.reject("))
+                this.#sent.add(specifier);
+        }
+        return (await this.#interruptibly("eval", { code: script, modules }, "Execution"));
+    }
+    /**
+     * A cell that's waiting on something leaves the driver free: it answers a
+     * ping, and the cell is abandoned with the session intact (its pending
+     * work still runs, as on Bun). A busy cell can't be reached, so workerd is
+     * stopped and restarts on the next cell.
+     */
+    async interrupt() {
+        this.#interrupted = true;
+        const running = [...this.#interruptible];
+        const answered = await Promise.race([
+            this.#request("ping").then(() => true, () => false),
+            new Promise((resolve) => setTimeout(() => resolve(false), INTERRUPT_GRACE_MS)),
+        ]);
+        if (answered) {
+            for (const id of running) {
+                this.#pending.get(id)?.reject(new Abandoned("interrupted"));
+                this.#pending.delete(id);
+                this.#interruptible.delete(id);
+            }
+            return;
+        }
+        this.#stopNote = restartNote(this.runtime);
+        this.#host.stop(true);
+    }
+    /** Output arrives on the session before the reply it precedes. */
+    flush() {
+        return Promise.resolve();
+    }
+    async broadcastResult(executionCount, result) {
+        if (result.objectId === undefined)
+            return;
+        await this.#request("broadcast", { count: executionCount, handle: result.objectId });
+    }
+    async dispatchComm(msgType, content, metadata, buffers) {
+        const reply = await this.#interruptibly("comm", {
+            msgType,
+            content,
+            metadata,
+            buffers: buffers.map((b) => Buffer.from(b).toString("base64")),
+        }, "Comm handler");
+        if (isRecord(reply.error)) {
+            const { name, message, stack } = reply.error;
+            return { error: { name: String(name), message: String(message), stack: String(stack) } };
+        }
+        return { handled: reply.handled === true };
+    }
+    async describeError(exception) {
+        if (exception.objectId === undefined)
+            return { name: "Error", message: exception.description ?? "", stack: "" };
+        const { value } = await this.#request("describe", { handle: exception.objectId });
+        return JSON.parse(typeof value === "string" ? value : '{"name":"Error","message":"","stack":""}');
+    }
+    async propertyNames(expression) {
+        const reply = await this.#request("props", { expr: expression }).catch(() => null);
+        return Array.isArray(reply?.names) ? reply.names.filter((n) => typeof n === "string") : [];
+    }
+    /** None: top-level declarations here are properties of globalThis. */
+    lexicalNames() {
+        return Promise.resolve([]);
+    }
+    /** Never asked for: prompt() in workerd answers null without asking. */
+    replyInput() { }
+    kill() {
+        // workerd's graceful shutdown waits for open connections, the session
+        // included, so close it first.
+        this.#host.channel.close();
+        this.#host.stop(false);
+    }
+}

package/dist/workers-project.d.ts

@@ -0,0 +1,27 @@
+import { type WorkerHost } from "./workerd-target.ts";
+export declare const WRANGLER_CONFIGS: string[];
+/** The nearest wrangler config at or above `cwd`, or null. */
+export declare function findWranglerConfig(cwd: string): string | null;
+/**
+ * The Worker's main module: the project's named exports (Durable Object
+ * classes and the like), the driver's fetch handler as the default, and the
+ * project's own default export as the `worker` global.
+ */
+export declare const PROJECT_MAIN: string;
+/**
+ * The project's flags, plus nodejs_compat, which the driver needs for
+ * node:util, unless the project chose a variant itself. Its date can't say
+ * whether nodejs_compat is implied: an older Miniflare runs an older workerd
+ * than the date names. On a newer one the flag only draws a warning.
+ */
+export declare function compatibilityFlagsFor(flags: string[]): string[];
+/** Packages import Node builtins by bare name too; workerd and celld want node:. */
+export declare function builtinAliases(): {
+    [name: string]: string;
+};
+/** The project's main module as one ES module; builtins stay imports. */
+export declare function bundleProject(main: string, define?: {
+    [name: string]: string;
+}): Promise<string>;
+/** Starts the driver on the project's Miniflare with its bindings. */
+export declare function startMiniflare(configPath: string, cwd: string): Promise<WorkerHost>;

package/dist/workers-project.js

@@ -0,0 +1,195 @@
+// A Workers project's bindings for the workerd target (#26).
+//
+// When the notebook sits in a Workers project (a wrangler config at or above
+// its directory), the driver Worker runs on the project's own Miniflare, the
+// simulator `wrangler dev` uses, so cells get the project's KV, D1, R2,
+// Durable Objects and vars as `env`, and its default export as `worker`.
+// wrangler turns the config into Miniflare options
+// (unstable_getMiniflareWorkerOptions); the project's main module is
+// bundled next to the driver, so its Durable Object classes are exported
+// from the same Worker. Neither wrangler nor Miniflare is a dependency of
+// cdp-kernel: they're loaded from the project, so they match its version.
+import { builtinModules, createRequire } from "node:module";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { build } from "esbuild";
+import { runtimeDir } from "./package.js";
+import { cellMeta, WORKER_MODULES } from "./workerd-target.js";
+export const WRANGLER_CONFIGS = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
+/** The nearest wrangler config at or above `cwd`, or null. */
+export function findWranglerConfig(cwd) {
+    for (let dir = cwd;; dir = dirname(dir)) {
+        for (const name of WRANGLER_CONFIGS) {
+            if (existsSync(join(dir, name)))
+                return join(dir, name);
+        }
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+/**
+ * The Worker's main module: the project's named exports (Durable Object
+ * classes and the like), the driver's fetch handler as the default, and the
+ * project's own default export as the `worker` global.
+ */
+export const PROJECT_MAIN = 'import * as project from "./project.mjs";\n' +
+    'export * from "./project.mjs";\n' +
+    'export { default } from "./workerd-worker.mjs";\n' +
+    "globalThis.worker = project.default;\n";
+/**
+ * The project's flags, plus nodejs_compat, which the driver needs for
+ * node:util, unless the project chose a variant itself. Its date can't say
+ * whether nodejs_compat is implied: an older Miniflare runs an older workerd
+ * than the date names. On a newer one the flag only draws a warning.
+ */
+export function compatibilityFlagsFor(flags) {
+    if (flags.some((f) => /^(?:no_)?nodejs_compat/.test(f)))
+        return flags;
+    return [...flags, "nodejs_compat"];
+}
+const DEFAULT_COMPATIBILITY_DATE = "2026-08-04";
+function isWrangler(value) {
+    return typeof value?.unstable_getMiniflareWorkerOptions === "function";
+}
+function isMiniflareModule(value) {
+    return typeof value?.Miniflare === "function";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Loads wrangler from the project, and the Miniflare that wrangler uses. */
+function loadTooling(configPath) {
+    const fromProject = createRequire(join(dirname(configPath), "package.json"));
+    let wranglerPath;
+    try {
+        wranglerPath = fromProject.resolve("wrangler");
+    }
+    catch {
+        throw new Error("wrangler isn't installed in the project (npm install --save-dev wrangler)");
+    }
+    const fromWrangler = createRequire(wranglerPath);
+    const wrangler = fromWrangler(wranglerPath);
+    const miniflare = fromWrangler("miniflare");
+    if (!isWrangler(wrangler))
+        throw new Error("this wrangler has no unstable_getMiniflareWorkerOptions");
+    if (!isMiniflareModule(miniflare))
+        throw new Error("couldn't load the Miniflare that wrangler uses");
+    const pkg = JSON.parse(readFileSync(fromWrangler.resolve("miniflare/package.json"), "utf8"));
+    const version = isRecord(pkg) && typeof pkg.version === "string" ? pkg.version : "";
+    return { wrangler, miniflare, version };
+}
+const NODE_BUILTINS = builtinModules.filter((name) => !name.startsWith("_") && !name.startsWith("node:"));
+/** Packages import Node builtins by bare name too; workerd and celld want node:. */
+export function builtinAliases() {
+    return Object.fromEntries(NODE_BUILTINS.map((name) => [name, `node:${name}`]));
+}
+/** The project's main module as one ES module; builtins stay imports. */
+export async function bundleProject(main, define = {}) {
+    const result = await build({
+        entryPoints: [main],
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "browser",
+        conditions: ["workerd", "worker", "browser"],
+        mainFields: ["browser", "module", "main"],
+        // Packages import Node builtins by bare name too; workerd wants node:.
+        alias: builtinAliases(),
+        external: ["node:*", "cloudflare:*", "workerd:*"],
+        define,
+        target: "esnext",
+        logLevel: "silent",
+    });
+    return result.outputFiles[0].text;
+}
+/** Miniflare's WebSocket as the session channel. */
+function channelOf(ws) {
+    ws.accept();
+    return {
+        send: (text) => ws.send(text),
+        onMessage: (listener) => ws.addEventListener("message", (event) => listener(String(event.data))),
+        onClose: (listener) => ws.addEventListener("close", listener),
+        close() {
+            try {
+                ws.close();
+            }
+            catch {
+                // Already closed.
+            }
+        },
+    };
+}
+/** The driver on the project's Miniflare. */
+class MiniflareHost {
+    runtime;
+    project;
+    channel;
+    #mf;
+    #exitListeners = [];
+    #stopped = false;
+    constructor(mf, channel, version, project) {
+        this.#mf = mf;
+        this.channel = channel;
+        this.runtime = `miniflare ${version}`.trim();
+        this.project = project;
+    }
+    stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        // dispose() ends workerd even mid-cell.
+        void this.#mf.dispose().catch(() => { }).finally(() => {
+            for (const listener of this.#exitListeners)
+                listener(null);
+        });
+    }
+    onExit(listener) {
+        this.#exitListeners.push(listener);
+    }
+}
+/** Starts the driver on the project's Miniflare with its bindings. */
+export async function startMiniflare(configPath, cwd) {
+    const { wrangler, miniflare, version } = loadTooling(configPath);
+    const projectDir = dirname(configPath);
+    const { workerOptions, main, define } = wrangler.unstable_getMiniflareWorkerOptions(configPath);
+    const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
+    const module = (path, contents) => ({ type: "ESModule", path, contents });
+    const modules = [
+        module("main.mjs", main ? PROJECT_MAIN : 'export { default } from "./workerd-worker.mjs";\n'),
+        ...WORKER_MODULES.map((name) => module(name, readFileSync(join(source, name), "utf8"))),
+        ...(main ? [module("project.mjs", await bundleProject(main, define))] : []),
+    ];
+    const token = randomBytes(32).toString("hex");
+    const date = workerOptions.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE;
+    // Its own state directory, beside `wrangler dev`'s: two runtimes must
+    // never open the same Durable Object.
+    const state = join(projectDir, ".wrangler", "state", "cdp-kernel");
+    const v5 = typeof miniflare.convertV4MiniflareOptions === "function";
+    const options = {
+        ...workerOptions,
+        name: "cdpk",
+        modules,
+        modulesRoot: "/",
+        unsafeEvalBinding: "UNSAFE",
+        compatibilityDate: date,
+        compatibilityFlags: compatibilityFlagsFor(workerOptions.compatibilityFlags ?? []),
+        bindings: { ...workerOptions.bindings, TOKEN: token, META: JSON.stringify(cellMeta(cwd)) },
+        // Miniflare 5 renamed Miniflare 4's defaultPersistRoot.
+        ...(v5 ? { resourcePersistencePath: state } : { defaultPersistRoot: state }),
+    };
+    const mf = new miniflare.Miniflare(v5 && miniflare.convertV4MiniflareOptions ? miniflare.convertV4MiniflareOptions(options) : options);
+    try {
+        await mf.ready;
+        // Miniflare listens on a loopback TCP port; the token is what keeps
+        // other local processes from the driver.
+        const res = await mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } });
+        if (res.status !== 101 || res.webSocket === null)
+            throw new Error(`the driver answered ${res.status}: ${await res.text()}`);
+        return new MiniflareHost(mf, channelOf(res.webSocket), version, configPath);
+    }
+    catch (err) {
+        await mf.dispose().catch(() => { });
+        throw err;
+    }
+}