@tlockney/cdp-kernel 0.0.0-stage → 0.1.1

package/dist/kernel.js

@@ -0,0 +1,362 @@
+// Jupyter message handling: shell, control, stdin and iopub.
+//
+// Ported from startJupyterKernel in Deno's cli/js/jupyter_kernel.js
+// (v2.9.6), which is Copyright 2018-2026 the Deno authors, MIT license.
+// The thirteen op_jupyter_* calls into Deno's REPL isolate are replaced by
+// a Target driven over CDP (src/target.ts).
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import { randomUUID } from "node:crypto";
+import { decodeMessage, encodeMessage, PROTOCOL_VERSION, verify } from "./wire.js";
+import { PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
+import { Interrupted, Target } from "./target.js";
+import { CellSyntaxError, objectLiteralCandidate, transformCell } from "./transform.js";
+import { checkIsComplete, codePointToUtf16Index, exprAtCursor, utf16ToCodePointIndex } from "./text.js";
+export function parseConnectionInfo(json) {
+    const raw = JSON.parse(json);
+    if (typeof raw !== "object" || raw === null)
+        throw new Error("connection file is not an object");
+    const info = raw;
+    for (const port of ["shell_port", "control_port", "stdin_port", "iopub_port", "hb_port"]) {
+        if (typeof info[port] !== "number")
+            throw new Error(`connection file: missing ${port}`);
+    }
+    if (info.transport !== undefined && info.transport !== "tcp") {
+        throw new Error(`unsupported transport ${info.transport}; only tcp is implemented`);
+    }
+    if (info.signature_scheme !== undefined && info.signature_scheme !== "hmac-sha256" && info.key) {
+        throw new Error(`unsupported signature scheme ${info.signature_scheme}`);
+    }
+    return {
+        ip: info.ip ?? "127.0.0.1",
+        key: info.key ?? "",
+        transport: "tcp",
+        signature_scheme: "hmac-sha256",
+        shell_port: info.shell_port,
+        control_port: info.control_port,
+        stdin_port: info.stdin_port,
+        iopub_port: info.iopub_port,
+        hb_port: info.hb_port,
+    };
+}
+export class Kernel {
+    #conn;
+    #runtime;
+    #denoCompat;
+    #session = randomUUID();
+    #shell;
+    #control;
+    #stdin;
+    #iopub;
+    #target = null;
+    #targetStarting = null;
+    #executionCount = 0;
+    #parent = {};
+    #allowStdin = false;
+    #executing = false;
+    #shuttingDown = false;
+    constructor(conn, runtime, options = {}) {
+        this.#conn = conn;
+        this.#runtime = runtime;
+        this.#denoCompat = options.denoCompat ?? false;
+        startHeartbeat(conn.hb_port, conn.ip);
+        this.#shell = new RouterSocket(conn.shell_port, conn.ip);
+        this.#control = new RouterSocket(conn.control_port, conn.ip);
+        this.#stdin = new RouterSocket(conn.stdin_port, conn.ip);
+        this.#iopub = new PubSocket(conn.iopub_port, conn.ip);
+    }
+    async run() {
+        // Start the runtime eagerly so the first cell doesn't pay for it.
+        this.#ensureTarget().catch((err) => this.#log(`target failed to start: ${err}`));
+        process.on("SIGINT", () => void this.#interrupt());
+        await Promise.all([this.#loop(this.#shell, (m, p) => this.#handleShell(m, p)),
+            this.#loop(this.#control, (m, p) => this.#handleControl(m, p))]);
+    }
+    #log(text) {
+        process.stderr.write(`[cdp-kernel] ${text}\n`);
+    }
+    // --- target lifecycle -----------------------------------------------------
+    #ensureTarget() {
+        if (this.#target)
+            return Promise.resolve(this.#target);
+        this.#targetStarting ??= Target.launch(this.#runtime, this.#targetEvents(), { denoCompat: this.#denoCompat }).then((target) => {
+            this.#target = target;
+            this.#targetStarting = null;
+            return target;
+        }, (err) => {
+            this.#targetStarting = null;
+            throw err;
+        });
+        return this.#targetStarting;
+    }
+    #targetEvents() {
+        return {
+            stream: (name, text) => this.#publish("stream", { name, text }),
+            message: (msg) => void this.#onTargetMessage(msg),
+            exit: (code) => {
+                this.#target = null;
+                if (!this.#shuttingDown) {
+                    this.#publish("stream", { name: "stderr", text: `\n[cdp-kernel] ${this.#runtime} exited (${code}); restarting on next cell\n` });
+                }
+            },
+        };
+    }
+    async #onTargetMessage(msg) {
+        if (msg.kind === "iopub") {
+            this.#publish(msg.msg_type, msg.content, {
+                metadata: msg.metadata,
+                buffers: msg.buffers.map((b) => new Uint8Array(Buffer.from(b, "base64"))),
+            });
+            return;
+        }
+        let value = null;
+        try {
+            value = await this.#requestInput(msg.prompt, msg.password);
+        }
+        finally {
+            // Always answer exactly once so the target's blocking read returns.
+            this.#target?.replyInput(value);
+        }
+    }
+    async #interrupt() {
+        if (this.#target && this.#executing)
+            await this.#target.interrupt();
+    }
+    // --- messaging --------------------------------------------------------------
+    #encode(msgType, content, parentHeader, extra = {}) {
+        return encodeMessage(this.#session, this.#conn.key, msgType, content, { parentHeader, ...extra });
+    }
+    #publish(msgType, content, extra = {}) {
+        this.#iopub.send(this.#encode(msgType, content, extra.parent ?? this.#parent, extra));
+    }
+    #status(state, parent) {
+        this.#publish("status", { execution_state: state }, { parent });
+    }
+    #reply(socket, peer, request, msgType, content) {
+        socket.send(peer, this.#encode(msgType, content, request.header));
+    }
+    async #loop(socket, handle) {
+        while (!this.#shuttingDown) {
+            const { peer, frames } = await socket.recv();
+            try {
+                const msg = decodeMessage(frames);
+                // Unsigned or forged messages are dropped, as in Deno.
+                if (!verify(this.#conn.key, msg.signedParts, msg.sig))
+                    continue;
+                await handle(msg, peer);
+            }
+            catch (err) {
+                this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+            }
+        }
+    }
+    #kernelInfo() {
+        const versions = this.#target?.versions;
+        return {
+            status: "ok",
+            protocol_version: PROTOCOL_VERSION,
+            implementation: "cdp-kernel",
+            implementation_version: "0.1.0",
+            language_info: {
+                name: "typescript",
+                version: "5",
+                mimetype: "text/x.typescript",
+                file_extension: ".ts",
+                pygments_lexer: "typescript",
+                codemirror_mode: "typescript",
+                nbconvert_exporter: "script",
+            },
+            banner: `cdp-kernel on ${this.#runtime} ${versions?.runtime ?? ""} (V8 ${versions?.v8 ?? "?"})`,
+            help_links: [],
+            debugger: false,
+        };
+    }
+    // --- control channel ------------------------------------------------------
+    async #handleControl(msg, peer) {
+        switch (msg.header.msg_type) {
+            case "kernel_info_request":
+                this.#reply(this.#control, peer, msg, "kernel_info_reply", this.#kernelInfo());
+                break;
+            case "interrupt_request":
+                await this.#interrupt();
+                this.#reply(this.#control, peer, msg, "interrupt_reply", { status: "ok" });
+                break;
+            case "shutdown_request": {
+                const restart = msg.content.restart === true;
+                this.#reply(this.#control, peer, msg, "shutdown_reply", { status: "ok", restart });
+                this.#shuttingDown = true;
+                this.#target?.kill();
+                // Frontends spawn a fresh kernel even on restart; exit after the
+                // reply has had a moment to flush (denoland/deno#20556).
+                setTimeout(() => process.exit(0), 100);
+                break;
+            }
+        }
+    }
+    // --- shell channel ----------------------------------------------------------
+    async #handleShell(msg, peer) {
+        const type = msg.header.msg_type;
+        if (type === "execute_request")
+            return this.#execute(msg, peer);
+        this.#status("busy", msg.header);
+        try {
+            switch (type) {
+                case "kernel_info_request":
+                    await this.#ensureTarget().catch(() => null);
+                    this.#reply(this.#shell, peer, msg, "kernel_info_reply", this.#kernelInfo());
+                    break;
+                case "complete_request":
+                    this.#reply(this.#shell, peer, msg, "complete_reply", await this.#complete(msg));
+                    break;
+                case "is_complete_request":
+                    this.#reply(this.#shell, peer, msg, "is_complete_reply", checkIsComplete(String(msg.content.code ?? "")));
+                    break;
+                case "inspect_request":
+                    this.#reply(this.#shell, peer, msg, "inspect_reply", { status: "ok", found: false, data: {}, metadata: {} });
+                    break;
+                case "history_request":
+                    this.#reply(this.#shell, peer, msg, "history_reply", { status: "ok", history: [] });
+                    break;
+                case "comm_info_request":
+                    this.#reply(this.#shell, peer, msg, "comm_info_reply", { status: "ok", comms: {} });
+                    break;
+                case "comm_open":
+                    // No comm targets (widgets) yet: close it straight away, like Deno.
+                    this.#publish("comm_close", { comm_id: msg.content.comm_id ?? "", data: {} }, { parent: msg.header });
+                    break;
+            }
+        }
+        finally {
+            this.#status("idle", msg.header);
+        }
+    }
+    async #complete(msg) {
+        const code = String(msg.content.code ?? "");
+        const cursorCp = typeof msg.content.cursor_pos === "number"
+            ? msg.content.cursor_pos
+            : utf16ToCodePointIndex(code, code.length);
+        const cursor = codePointToUtf16Index(code, cursorCp);
+        const expr = exprAtCursor(code, cursor);
+        const target = await this.#ensureTarget();
+        let matches;
+        let start;
+        const dot = expr.lastIndexOf(".");
+        if (dot !== -1) {
+            const prefix = expr.slice(dot + 1);
+            matches = (await target.propertyNames(expr.slice(0, dot)))
+                .filter((name) => name.startsWith(prefix) && !name.startsWith("Symbol("));
+            start = cursor - prefix.length;
+        }
+        else {
+            const names = new Set([...(await target.propertyNames("globalThis")), ...(await target.lexicalNames())]);
+            matches = [...names].filter((name) => name.startsWith(expr) && !name.startsWith("__cdpk")).sort();
+            start = cursor - expr.length;
+        }
+        return {
+            status: "ok",
+            matches,
+            cursor_start: utf16ToCodePointIndex(code, start),
+            cursor_end: cursorCp,
+            metadata: {},
+        };
+    }
+    async #requestInput(prompt, password) {
+        const parent = this.#parent;
+        if (!this.#allowStdin || typeof parent.msg_id !== "string")
+            return null;
+        if (this.#stdin.peers.size === 0)
+            await new Promise((r) => setTimeout(r, 100));
+        if (this.#stdin.peers.size === 0)
+            return null;
+        this.#stdin.sendAll(this.#encode("input_request", { prompt, password }, parent));
+        for (;;) {
+            const { frames } = await this.#stdin.recv();
+            const reply = decodeMessage(frames);
+            if (!verify(this.#conn.key, reply.signedParts, reply.sig))
+                continue;
+            if (reply.header.msg_type === "input_reply") {
+                return typeof reply.content.value === "string" ? reply.content.value : null;
+            }
+        }
+    }
+    async #evaluateCell(target, code) {
+        // Object-literal wrapping (Deno's evaluate_line_with_object_wrapping):
+        // try `({ ... })` first and fall back to the code as written.
+        const wrapped = objectLiteralCandidate(code);
+        if (wrapped !== null) {
+            try {
+                const result = await target.evaluate(transformCell(wrapped));
+                if (!result.exceptionDetails)
+                    return result;
+            }
+            catch (err) {
+                if (!(err instanceof CellSyntaxError))
+                    throw err;
+            }
+        }
+        return target.evaluate(transformCell(code));
+    }
+    async #execute(msg, peer) {
+        const parent = msg.header;
+        const code = String(msg.content.code ?? "");
+        const silent = msg.content.silent === true;
+        if (!silent && msg.content.store_history !== false)
+            this.#executionCount++;
+        const count = this.#executionCount;
+        this.#parent = parent;
+        this.#allowStdin = msg.content.allow_stdin === true;
+        this.#status("busy", parent);
+        this.#publish("execute_input", { code, execution_count: count });
+        let error = null;
+        this.#executing = true;
+        try {
+            const target = await this.#ensureTarget();
+            const result = await this.#evaluateCell(target, code);
+            if (result.exceptionDetails) {
+                const exception = result.exceptionDetails.exception;
+                const described = exception
+                    ? await target.describeError(exception)
+                    : { name: "Error", message: result.exceptionDetails.text, stack: "" };
+                error = {
+                    ename: described.name || "Error",
+                    evalue: described.message,
+                    traceback: (described.stack || `${described.name}: ${described.message}`).split("\n"),
+                };
+            }
+            else if (!silent && result.result.type !== "undefined") {
+                await target.broadcastResult(count, result.result);
+            }
+            await target.flush();
+        }
+        catch (err) {
+            if (err instanceof CellSyntaxError) {
+                // Deno reports these as an opaque "Execution failed".
+                error = { ename: "SyntaxError", evalue: err.message, traceback: [`SyntaxError: ${err.message}`] };
+            }
+            else if (err instanceof Interrupted) {
+                error = { ename: "Interrupted", evalue: "Execution interrupted", traceback: ["Execution interrupted"] };
+                await this.#target?.flush().catch(() => { });
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                error = { ename: "KernelError", evalue: message, traceback: [message] };
+            }
+        }
+        finally {
+            this.#executing = false;
+        }
+        if (error) {
+            this.#publish("error", error);
+            this.#reply(this.#shell, peer, msg, "execute_reply", { status: "error", execution_count: count, ...error });
+        }
+        else {
+            this.#reply(this.#shell, peer, msg, "execute_reply", {
+                status: "ok",
+                execution_count: count,
+                payload: [],
+                user_expressions: {},
+            });
+        }
+        this.#status("idle", parent);
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// cdp-kernel CLI.
+//   cdp-kernel install [--runtime node|deno] [--deno-compat] [--name NAME] [--display NAME]
+//   cdp-kernel kernel --runtime node|deno [--deno-compat] --conn CONNECTION_FILE
+//   cdp-kernel version
+//
+// --deno-compat (Node only) adds a `Deno` namespace for notebooks written for
+// `deno jupyter`; see runtime/deno-compat.mjs.
+import process from "node:process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { Kernel, parseConnectionInfo } from "./kernel.js";
+import { hostRuntime, kernelArgv, moduleOrigin, VERSION } from "./package.js";
+function isRuntime(value) {
+    return value === "node" || value === "deno";
+}
+function kernelsDir() {
+    if (process.env.JUPYTER_DATA_DIR)
+        return join(process.env.JUPYTER_DATA_DIR, "kernels");
+    if (platform() === "darwin")
+        return join(homedir(), "Library", "Jupyter", "kernels");
+    if (platform() === "win32")
+        return join(process.env.APPDATA ?? homedir(), "jupyter", "kernels");
+    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "jupyter", "kernels");
+}
+function install(runtime, denoCompat, name, display) {
+    const dir = join(kernelsDir(), name);
+    mkdirSync(dir, { recursive: true });
+    const spec = {
+        argv: kernelArgv(hostRuntime(), process.execPath, moduleOrigin(import.meta.url), [
+            "kernel",
+            "--runtime",
+            runtime,
+            ...(denoCompat ? ["--deno-compat"] : []),
+            "--conn",
+            "{connection_file}",
+        ]),
+        display_name: display,
+        language: "typescript",
+        // Interrupts arrive as interrupt_request on the control channel rather
+        // than as SIGINT to this process.
+        interrupt_mode: "message",
+        metadata: { runtime, denoCompat, version: VERSION },
+    };
+    writeFileSync(join(dir, "kernel.json"), JSON.stringify(spec, null, 2) + "\n");
+    console.log(`installed kernelspec ${name} -> ${dir}`);
+}
+const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+        runtime: { type: "string", default: "node" },
+        conn: { type: "string" },
+        name: { type: "string" },
+        display: { type: "string" },
+        "deno-compat": { type: "boolean", default: false },
+    },
+});
+const runtime = values.runtime;
+if (!isRuntime(runtime)) {
+    console.error(`unknown runtime ${runtime}; expected node or deno`);
+    process.exit(2);
+}
+// Deno targets have the real namespace; the shim is for Node.
+const denoCompat = values["deno-compat"] === true && runtime === "node";
+switch (positionals[0]) {
+    case "install": {
+        const suffix = denoCompat ? "-deno" : "";
+        install(runtime, denoCompat, values.name ?? `cdp-${runtime}${suffix}`, values.display ?? `TypeScript (cdp-kernel, ${runtime}${denoCompat ? ", Deno compat" : ""})`);
+        break;
+    }
+    case "kernel": {
+        if (!values.conn) {
+            console.error("kernel: --conn CONNECTION_FILE is required");
+            process.exit(2);
+        }
+        const kernel = new Kernel(parseConnectionInfo(readFileSync(values.conn, "utf8")), runtime, { denoCompat });
+        await kernel.run();
+        break;
+    }
+    case "version":
+        console.log(VERSION);
+        break;
+    default:
+        console.error("usage: cdp-kernel install [--runtime node|deno] [--deno-compat] | kernel --runtime node|deno --conn FILE | version");
+        process.exit(2);
+}

package/dist/mod.d.ts

@@ -0,0 +1,23 @@
+/**
+ * cdp-kernel: Deno's Jupyter kernel, extracted to run notebook cells in any
+ * runtime whose inspector speaks the Chrome DevTools Protocol (Node and
+ * Deno today).
+ *
+ * Most people want the CLI (`cdp-kernel install`). This module exposes
+ * the kernel for embedding: give it a parsed connection file and a target
+ * runtime, then await {@link Kernel.run}.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from "node:fs";
+ * import { Kernel, parseConnectionInfo } from "@tlockney/cdp-kernel";
+ *
+ * const conn = parseConnectionInfo(readFileSync("kernel-123.json", "utf8"));
+ * await new Kernel(conn, "node").run();
+ * ```
+ *
+ * @module
+ */
+export { type ConnectionInfo, Kernel, parseConnectionInfo } from "./kernel.ts";
+export type { RuntimeName } from "./target.ts";
+export { VERSION } from "./package.ts";

package/dist/mod.js

@@ -0,0 +1,22 @@
+/**
+ * cdp-kernel: Deno's Jupyter kernel, extracted to run notebook cells in any
+ * runtime whose inspector speaks the Chrome DevTools Protocol (Node and
+ * Deno today).
+ *
+ * Most people want the CLI (`cdp-kernel install`). This module exposes
+ * the kernel for embedding: give it a parsed connection file and a target
+ * runtime, then await {@link Kernel.run}.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from "node:fs";
+ * import { Kernel, parseConnectionInfo } from "@tlockney/cdp-kernel";
+ *
+ * const conn = parseConnectionInfo(readFileSync("kernel-123.json", "utf8"));
+ * await new Kernel(conn, "node").run();
+ * ```
+ *
+ * @module
+ */
+export { Kernel, parseConnectionInfo } from "./kernel.js";
+export { VERSION } from "./package.js";

package/dist/package.d.ts

@@ -0,0 +1,29 @@
+/** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
+export declare const VERSION = "0.1.1";
+export declare const RUNTIME_FILES: readonly ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export type HostRuntime = "node" | "deno";
+export declare function hostRuntime(): HostRuntime;
+/** Where the CLI module was loaded from. */
+export type Origin = {
+    kind: "file";
+    path: string;
+} | {
+    kind: "jsr";
+    specifier: string;
+} | {
+    kind: "remote";
+    url: string;
+};
+/** `moduleUrl` is the CLI's import.meta.url. */
+export declare function moduleOrigin(moduleUrl: string): Origin;
+/** The command a kernelspec runs to start this kernel. */
+export declare function kernelArgv(host: HostRuntime, execPath: string, origin: Origin, args: string[]): string[];
+export declare function cacheRoot(): string;
+export type FetchText = (url: string) => Promise<string>;
+/**
+ * A local directory holding runtime/*.mjs. `baseUrl` is the runtime/
+ * directory's URL relative to the calling module. A file: URL is used in
+ * place; anything else is copied once into a cache keyed by version and
+ * URL.
+ */
+export declare function runtimeDir(baseUrl: string, cache?: string, get?: FetchText): Promise<string>;

package/dist/package.js

@@ -0,0 +1,95 @@
+// How cdp-kernel was installed, and what follows from it.
+//
+// It ships three ways: an npm package run by Node (compiled dist/), a JSR
+// package run by Deno (TypeScript fetched from https://jsr.io), and a local
+// checkout run by either. Two things depend on which:
+//   - the kernelspec argv that relaunches the kernel, and
+//   - where the target runtime loads runtime/*.mjs from. A Node target can't
+//     import its bootstrap from an https URL, so a JSR install copies those
+//     files into a local cache first.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+/** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
+export const VERSION = "0.1.1";
+export const RUNTIME_FILES = ["bootstrap.mjs", "display.mjs", "node-hooks.mjs", "deno-compat.mjs"];
+export function hostRuntime() {
+    return process.versions.deno === undefined ? "node" : "deno";
+}
+const JSR_URL = /^https:\/\/jsr\.io\/(@[^/]+\/[^/]+)\/([^/]+)\//;
+/** `moduleUrl` is the CLI's import.meta.url. */
+export function moduleOrigin(moduleUrl) {
+    if (moduleUrl.startsWith("file:"))
+        return { kind: "file", path: fileURLToPath(moduleUrl) };
+    const jsr = JSR_URL.exec(moduleUrl);
+    // Pin the exact version so an installed kernelspec keeps running the
+    // release it was installed from.
+    if (jsr)
+        return { kind: "jsr", specifier: `jsr:${jsr[1]}@${jsr[2]}/cli` };
+    return { kind: "remote", url: moduleUrl };
+}
+/** The command a kernelspec runs to start this kernel. */
+export function kernelArgv(host, execPath, origin, args) {
+    if (origin.kind === "remote") {
+        throw new Error(`cdp-kernel was loaded from ${origin.url}; install it from npm or JSR, or run a local checkout`);
+    }
+    if (host === "node") {
+        if (origin.kind !== "file")
+            throw new Error("a JSR install must be run with Deno");
+        return [execPath, origin.path, ...args];
+    }
+    // Deno: a checkout needs its deno.jsonc import map; a JSR package brings
+    // its own, so skip whatever config the notebook's directory has.
+    const flags = origin.kind === "jsr" ? ["--no-config", "--no-lock"] : ["--no-lock"];
+    const entry = origin.kind === "jsr" ? origin.specifier : origin.path;
+    return [execPath, "run", "--allow-all", ...flags, entry, ...args];
+}
+export function cacheRoot() {
+    const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(base, "cdp-kernel");
+}
+async function fetchText(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`fetching ${url}: ${res.status} ${res.statusText}`);
+    return await res.text();
+}
+/**
+ * A local directory holding runtime/*.mjs. `baseUrl` is the runtime/
+ * directory's URL relative to the calling module. A file: URL is used in
+ * place; anything else is copied once into a cache keyed by version and
+ * URL.
+ */
+export async function runtimeDir(baseUrl, cache = cacheRoot(), get = fetchText) {
+    if (baseUrl.startsWith("file:"))
+        return fileURLToPath(baseUrl);
+    const key = createHash("sha256").update(baseUrl).digest("hex").slice(0, 12);
+    const dir = join(cache, "runtime", `${VERSION}-${key}`);
+    if (RUNTIME_FILES.every((name) => existsSync(join(dir, name))))
+        return dir;
+    // Fill a sibling directory, then rename, so a half-copied cache is never
+    // picked up by the check above.
+    const staging = `${dir}.${process.pid}.tmp`;
+    mkdirSync(staging, { recursive: true });
+    try {
+        for (const name of RUNTIME_FILES) {
+            writeFileSync(join(staging, name), await get(new URL(name, baseUrl).href));
+        }
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        throw err;
+    }
+    try {
+        renameSync(staging, dir);
+    }
+    catch (err) {
+        // Another kernel finished first; theirs is complete.
+        if (!RUNTIME_FILES.every((name) => existsSync(join(dir, name))))
+            throw err;
+    }
+    return dir;
+}