@tlockney/cdp-kernel 0.2.0 → 0.3.0

package/dist/ws-client.d.ts

@@ -0,0 +1,32 @@
+import { Buffer } from "node:buffer";
+export declare const OP_CONTINUATION = 0;
+export declare const OP_TEXT = 1;
+export declare const OP_CLOSE = 8;
+export declare const OP_PING = 9;
+export declare const OP_PONG = 10;
+export interface Frame {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer;
+}
+/** One frame; clients must mask what they send. */
+export declare function encodeFrame(opcode: number, payload: Buffer, mask?: Buffer | null): Buffer;
+/** Splits a byte stream into frames, holding back a partial one. */
+export declare class FrameDecoder {
+    #private;
+    push(chunk: Buffer): Frame[];
+}
+export declare function acceptKey(key: string): string;
+export interface WsChannel {
+    send(text: string): void;
+    onMessage(listener: (text: string) => void): void;
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export declare function connectUnixWebSocket(socketPath: string, { path, headers }?: {
+    path?: string;
+    headers?: {
+        [name: string]: string;
+    };
+}): Promise<WsChannel>;

package/dist/ws-client.js

@@ -0,0 +1,166 @@
+// A minimal WebSocket client (RFC 6455) over a Unix socket, for the workerd
+// target's session with its driver Worker (#26). The WebSocket that Node
+// and Deno provide can't connect to a Unix socket, and a TCP listener would
+// be reachable by every local process. Text messages only: that's all the
+// session carries.
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import { connect } from "node:net";
+const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export const OP_CONTINUATION = 0x0;
+export const OP_TEXT = 0x1;
+export const OP_CLOSE = 0x8;
+export const OP_PING = 0x9;
+export const OP_PONG = 0xa;
+/** One frame; clients must mask what they send. */
+export function encodeFrame(opcode, payload, mask = randomBytes(4)) {
+    const len = payload.length;
+    const head = len < 126 ? 2 : len < 0x10000 ? 4 : 10;
+    const out = Buffer.alloc(head + (mask ? 4 : 0) + len);
+    out[0] = 0x80 | opcode;
+    const maskBit = mask ? 0x80 : 0;
+    if (len < 126) {
+        out[1] = maskBit | len;
+    }
+    else if (len < 0x10000) {
+        out[1] = maskBit | 126;
+        out.writeUInt16BE(len, 2);
+    }
+    else {
+        out[1] = maskBit | 127;
+        out.writeBigUInt64BE(BigInt(len), 2);
+    }
+    if (mask) {
+        mask.copy(out, head);
+        for (let i = 0; i < len; i++)
+            out[head + 4 + i] = payload[i] ^ mask[i & 3];
+    }
+    else {
+        payload.copy(out, head);
+    }
+    return out;
+}
+/** Splits a byte stream into frames, holding back a partial one. */
+export class FrameDecoder {
+    #buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        const frames = [];
+        for (;;) {
+            const b = this.#buffer;
+            if (b.length < 2)
+                break;
+            const masked = (b[1] & 0x80) !== 0;
+            let len = b[1] & 0x7f;
+            let offset = 2;
+            if (len === 126) {
+                if (b.length < 4)
+                    break;
+                len = b.readUInt16BE(2);
+                offset = 4;
+            }
+            else if (len === 127) {
+                if (b.length < 10)
+                    break;
+                len = Number(b.readBigUInt64BE(2));
+                offset = 10;
+            }
+            const maskAt = offset;
+            if (masked)
+                offset += 4;
+            if (b.length < offset + len)
+                break;
+            const payload = Buffer.from(b.subarray(offset, offset + len));
+            if (masked)
+                for (let i = 0; i < len; i++)
+                    payload[i] ^= b[maskAt + (i & 3)];
+            frames.push({ fin: (b[0] & 0x80) !== 0, opcode: b[0] & 0x0f, payload });
+            this.#buffer = b.subarray(offset + len);
+        }
+        return frames;
+    }
+}
+export function acceptKey(key) {
+    return createHash("sha1").update(key + GUID).digest("base64");
+}
+/** Opens a WebSocket over the Unix socket at `socketPath`. */
+export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } = {}) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ path: socketPath });
+        const key = randomBytes(16).toString("base64");
+        const messageListeners = [];
+        const closeListeners = [];
+        let open = false;
+        let closed = false;
+        let head = Buffer.alloc(0);
+        const decoder = new FrameDecoder();
+        let parts = [];
+        const finish = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (!open)
+                reject(new Error("the WebSocket closed before it opened"));
+            for (const listener of closeListeners)
+                listener();
+        };
+        const write = (opcode, payload) => {
+            if (!closed)
+                socket.write(encodeFrame(opcode, payload));
+        };
+        const channel = {
+            send: (text) => write(OP_TEXT, Buffer.from(text)),
+            onMessage: (listener) => void messageListeners.push(listener),
+            onClose: (listener) => void closeListeners.push(listener),
+            close() {
+                write(OP_CLOSE, Buffer.alloc(0));
+                socket.end();
+            },
+        };
+        const onFrames = (frames) => {
+            for (const frame of frames) {
+                if (frame.opcode === OP_TEXT || frame.opcode === OP_CONTINUATION) {
+                    parts.push(frame.payload);
+                    if (frame.fin) {
+                        const text = Buffer.concat(parts).toString("utf8");
+                        parts = [];
+                        for (const listener of messageListeners)
+                            listener(text);
+                    }
+                }
+                else if (frame.opcode === OP_PING) {
+                    write(OP_PONG, frame.payload);
+                }
+                else if (frame.opcode === OP_CLOSE) {
+                    socket.end();
+                }
+            }
+        };
+        socket.on("data", (chunk) => {
+            if (open)
+                return onFrames(decoder.push(chunk));
+            head = Buffer.concat([head, chunk]);
+            const end = head.indexOf("\r\n\r\n");
+            if (end === -1)
+                return;
+            const response = head.subarray(0, end).toString("latin1");
+            const accept = /^sec-websocket-accept:\s*(\S+)/im.exec(response)?.[1];
+            if (!/^HTTP\/1\.1 101 /.test(response) || accept !== acceptKey(key)) {
+                socket.destroy();
+                reject(new Error(`the WebSocket handshake failed: ${response.split("\r\n")[0]}`));
+                return;
+            }
+            open = true;
+            resolve(channel);
+            onFrames(decoder.push(head.subarray(end + 4)));
+        });
+        socket.on("error", (err) => {
+            if (!open)
+                reject(err);
+        });
+        socket.on("close", finish);
+        const extra = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join("");
+        socket.write(`GET ${path} HTTP/1.1\r\nHost: cdpk\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n` +
+            `Sec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n${extra}\r\n`);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
@@ -8,7 +8,16 @@
     "type": "git",
     "url": "git+https://github.com/tlockney/cdp-kernel.git"
   },
-  "keywords": ["jupyter", "kernel", "typescript", "notebook", "deno", "node", "cdp", "devtools-protocol"],
+  "keywords": [
+    "jupyter",
+    "kernel",
+    "typescript",
+    "notebook",
+    "deno",
+    "node",
+    "cdp",
+    "devtools-protocol"
+  ],
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -44,6 +53,9 @@
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
+    "install:bun": "node src/main.ts install --runtime bun",
+    "install:workerd": "node src/main.ts install --runtime workerd",
+    "install:celld": "node src/main.ts install --runtime celld",
     "prepack": "npm run build",
     "test": "node --test test/*.test.ts",
     "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
@@ -56,6 +68,8 @@
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "workerd": "1.20261015.1",
+    "wrangler": "4.151.0"
   }
 }

package/runtime/bootstrap.mjs

@@ -4,14 +4,17 @@
 // then drives it over CDP. Everything the host needs from inside the
 // runtime lives on globalThis.__cdpk; output to the host goes through the
 // `__cdpk_send` CDP binding (Runtime.addBinding) plus plain stdout/stderr.
+// Bun is launched as `bun runtime/bootstrap.mjs` and driven over a pipe
+// instead; see bun-channel.mjs.
 //
-// Plain JavaScript on purpose: the same file must load unmodified in Node
-// and in Deno.
+// Plain JavaScript on purpose: the same file must load unmodified in Node,
+// Deno and Bun.
 
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJupyter } from "./display.mjs";
 
 const isDeno = typeof globalThis.Deno?.version?.deno === "string";
+const isBun = typeof globalThis.Bun?.version === "string";
 const ENC = new TextEncoder();
 
 const cwd = isDeno ? Deno.cwd() : process.cwd();
@@ -77,7 +80,7 @@ function resolveRelative(specifier) {
   return /^\.{0,2}\//.test(specifier) ? new URL(specifier, replUrl).href : specifier;
 }
 
-if (!isDeno) {
+if (!isDeno && !isBun) {
   // Deno resolves npm:/jsr: natively; Node gets a resolve hook that adds
   // them and re-parents cell imports to the notebook's directory.
   const { installNodeResolveHooks } = await import("./node-hooks.mjs");
@@ -108,12 +111,36 @@ async function denoImport(specifier, options) {
   }
 }
 
+// Bun has neither npm: nor jsr:, and would resolve a bare name from this
+// file's directory. npm:/jsr: install into a per-user cache as on Node
+// (with `bun add`); anything else bare resolves from the notebook's
+// directory, so its node_modules, or Bun's auto-install, supplies it.
+const packages = isBun ? await import("./node-hooks.mjs") : null;
+
+function bunResolve(specifier) {
+  let pkg = null;
+  if (specifier.startsWith("npm:")) pkg = packages.parsePackageSpecifier(specifier.slice(4));
+  else if (specifier.startsWith("jsr:")) pkg = packages.jsrToNpm(specifier.slice(4));
+  if (pkg) {
+    const { dir, alias } = packages.ensureInstalled(pkg, "bun");
+    return Bun.resolveSync(alias + pkg.subpath, dir);
+  }
+  // Relative, absolute, or a URL scheme such as node:, bun: or file:.
+  if (/^(?:\.{0,2}\/|[a-z][a-z0-9+.-]*:)/i.test(specifier)) return resolveRelative(specifier);
+  return Bun.resolveSync(specifier, cwd);
+}
+
 globalThis.__cdpk = {
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
   tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
   // Node: the resolve hook re-parents these imports. Deno would resolve
   // relative paths against this file, so denoImport does it here.
-  import: (specifier, options) => (isDeno ? denoImport(specifier, options) : import(specifier, options)),
+  import: (specifier, options) =>
+    isDeno
+      ? denoImport(specifier, options)
+      : isBun
+      ? import(bunResolve(specifier), options)
+      : import(specifier, options),
   meta: {
     url: replUrl.href,
     dirname: cwd,
@@ -182,6 +209,14 @@ if (isDeno) {
 // Keep the event loop alive between cells.
 setInterval(() => {}, 1 << 30);
 
+if (isBun) {
+  const { startChannel } = await import("./bun-channel.mjs");
+  const { createHandler } = await import("./evaluator.mjs");
+  startChannel(createHandler(globalThis.__cdpk), {
+    versions: { runtime: Bun.version, engine: `JavaScriptCore (WebKit ${process.versions.webkit.slice(0, 12)})` },
+  });
+}
+
 async function platform() {
   if (isDeno) {
     const stdinBuf = new Uint8Array(1);

package/runtime/bun-channel.d.mts

@@ -0,0 +1,3 @@
+import type { Handler } from "./evaluator.mjs";
+
+export function startChannel(handle: Handler, ready: { [key: string]: unknown }, fd?: number): void;

package/runtime/bun-channel.mjs

@@ -0,0 +1,58 @@
+// The Bun target's side of the host connection (#7), in place of CDP.
+//
+// Bun's --inspect speaks the WebKit Inspector Protocol, which has no
+// replMode, Runtime.addBinding or Runtime.terminateExecution, so the host
+// doesn't drive Bun over an inspector. It sends requests as JSON lines over
+// fd 3, a pipe only the host holds (there is no port to discover), and the
+// cells are evaluated here, in-process, by evaluator.mjs. Replies, and the
+// iopub messages that the CDP binding carries for other targets, go back the
+// same way. stdout and stderr stay ordinary pipes, ordered against those
+// messages by bootstrap.mjs's barrier markers.
+
+import fs from "node:fs";
+
+const CHANNEL_FD = 3;
+
+/** Synchronous, like a CDP binding call, so output order is kept. */
+function writeAll(fd, text) {
+  const bytes = Buffer.from(text);
+  for (let offset = 0; offset < bytes.length;) {
+    try {
+      offset += fs.writeSync(fd, bytes, offset);
+    } catch (err) {
+      // The reader's side of the pipe is full; the fd may be non-blocking.
+      if (err.code !== "EAGAIN") throw err;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+    }
+  }
+}
+
+/**
+ * Serves `handle` (see evaluator.mjs) over fd 3 and installs
+ * globalThis.__cdpk_send, the function bootstrap.mjs sends iopub messages
+ * through. `ready` is sent first, once the target can take requests.
+ */
+export function startChannel(handle, ready, fd = CHANNEL_FD) {
+  const send = (message) => writeAll(fd, JSON.stringify(message) + "\n");
+  Object.defineProperty(globalThis, "__cdpk_send", {
+    value: (payload) => writeAll(fd, payload + "\n"),
+    enumerable: false,
+  });
+
+  let buffer = "";
+  const input = fs.createReadStream(null, { fd, autoClose: false, encoding: "utf8" });
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
+      const request = JSON.parse(buffer.slice(0, nl));
+      buffer = buffer.slice(nl + 1);
+      handle(request).then(
+        (reply) => send({ kind: "reply", id: request.id, ...reply }),
+        (err) => send({ kind: "reply", id: request.id, failure: String(err?.stack ?? err) }),
+      );
+    }
+  });
+  // The host is gone; don't linger as an orphan.
+  input.on("end", () => process.exit(0));
+  send({ kind: "ready", ...ready });
+}

package/runtime/evaluator.d.mts

@@ -0,0 +1,18 @@
+/** The parts of globalThis.__cdpk the evaluator calls. */
+export interface EvaluatorShim {
+  broadcastResult(executionCount: number, value: unknown): void | Promise<void>;
+  describeError(value: unknown): string;
+  commDispatch(msgType: string, content: object, metadata: object, buffers64: string[]): Promise<unknown>;
+  barrier(): number;
+}
+
+/** A request from the host: an `op` plus its parameters. */
+export interface EvaluatorRequest {
+  op: string;
+  [key: string]: unknown;
+}
+
+export type Handler = (request: EvaluatorRequest) => Promise<{ [key: string]: unknown }>;
+
+export function propertyNames(value: unknown): string[];
+export function createHandler(shim: EvaluatorShim, evaluate?: (code: string) => unknown): Handler;

package/runtime/evaluator.mjs

@@ -0,0 +1,83 @@
+// The in-process evaluator behind the targets that don't use CDP: Bun (#7),
+// over a pipe (bun-channel.mjs), and workerd (#8), inside a request
+// (workerd-worker.mjs). Cells arrive as global code from
+// src/transform.ts's transformCellForEval, whose value is a promise of the
+// boxed result. Requests and replies mirror the CDP calls the kernel makes
+// of the other targets.
+//
+// No imports: this file must load in every target.
+
+/** Own and inherited property names, as Runtime.getProperties lists them. */
+export function propertyNames(value) {
+  if (value === null || value === undefined) return [];
+  const names = new Set();
+  for (let o = Object(value); o !== null; o = Object.getPrototypeOf(o)) {
+    for (const name of Object.getOwnPropertyNames(o)) names.add(name);
+  }
+  return [...names];
+}
+
+/**
+ * Answers the host's requests. `shim` is globalThis.__cdpk; `evaluate` runs
+ * global code. Values the host refers to later (a result to display, an
+ * error to describe) stay here under a handle, the stand-in for a CDP
+ * objectId.
+ */
+export function createHandler(shim, evaluate = (code) => (0, eval)(code)) {
+  const handles = new Map();
+  let nextHandle = 0;
+  const remote = (value) => {
+    const objectId = `h${++nextHandle}`;
+    handles.set(objectId, value);
+    return { type: value === null ? "object" : typeof value, objectId };
+  };
+  const take = (objectId) => {
+    const value = handles.get(objectId);
+    handles.delete(objectId);
+    return value;
+  };
+
+  return async function handle(request) {
+    switch (request.op) {
+      case "ping":
+        return {};
+      case "eval": {
+        // The host uses a result's handle before its next cell.
+        handles.clear();
+        try {
+          const box = await evaluate(request.code);
+          return { result: box === undefined ? { type: "undefined" } : remote(box[0]) };
+        } catch (err) {
+          return {
+            exceptionDetails: { text: "Uncaught", lineNumber: 0, columnNumber: 0, exception: remote(err) },
+          };
+        }
+      }
+      case "broadcast":
+        await shim.broadcastResult(request.count, take(request.handle));
+        return {};
+      case "describe":
+        return { value: shim.describeError(take(request.handle)) };
+      case "comm":
+        try {
+          const handled = await shim.commDispatch(request.msgType, request.content, request.metadata, request.buffers);
+          return { handled: handled === true };
+        } catch (err) {
+          return { error: JSON.parse(shim.describeError(err)) };
+        }
+      case "props": {
+        let value;
+        try {
+          value = evaluate(`(${request.expr})`);
+        } catch {
+          return { names: [] };
+        }
+        return { names: propertyNames(value) };
+      }
+      case "barrier":
+        return { value: shim.barrier() };
+      default:
+        throw new Error(`unknown request ${JSON.stringify(request.op)}`);
+    }
+  };
+}

package/runtime/node-hooks.d.mts

@@ -7,4 +7,15 @@ export interface PackageSpecifier {
 export function parsePackageSpecifier(spec: string): PackageSpecifier;
 export function jsrToNpm(spec: string): PackageSpecifier;
 export function aliasFor(name: string, range: string): string;
+export type Installer = "npm" | "bun";
+export function installCommand(
+  installer: Installer,
+  alias: string,
+  name: string,
+  range: string,
+): { cmd: string; args: string[] };
+export function ensureInstalled(
+  pkg: { name: string; range: string },
+  installer?: Installer,
+): { dir: string; alias: string };
 export function installNodeResolveHooks(urls: { shimUrl: string; replUrl: string }): void;

package/runtime/node-hooks.mjs

@@ -11,7 +11,9 @@
 // Uses module.registerHooks (synchronous, in-thread; Node >= 23.5), so the
 // install can run with spawnSync inside resolve.
 
-import { registerHooks } from "node:module";
+// Not a named import: Bun, which loads this file for its npm:/jsr: helpers,
+// has no registerHooks, and a missing named export fails at link time.
+import module from "node:module";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -41,8 +43,12 @@ export function aliasFor(name, range) {
   return `cdpk-${digest}`;
 }
 
-function cacheDir() {
-  const dir = process.env.CDPK_CACHE_DIR ?? join(homedir(), ".cache", "cdp-kernel", "npm");
+// Each installer keeps its own cache, so npm's and Bun's lockfiles never
+// meet; both read the @jsr registry from .npmrc.
+function cacheDir(installer) {
+  const dir = installer === "npm"
+    ? process.env.CDPK_CACHE_DIR ?? join(homedir(), ".cache", "cdp-kernel", "npm")
+    : join(homedir(), ".cache", "cdp-kernel", installer);
   if (!existsSync(join(dir, "package.json"))) {
     mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, "package.json"), '{ "private": true }\n');
@@ -51,24 +57,30 @@ function cacheDir() {
   return dir;
 }
 
-function ensureInstalled({ name, range }) {
-  const dir = cacheDir();
+/** The command that installs name@range under `alias` with `installer`. */
+export function installCommand(installer, alias, name, range) {
+  const spec = `${alias}@npm:${name}@${range}`;
+  // The Bun target runs this inside Bun, so it uses its own binary.
+  if (installer === "bun") return { cmd: process.execPath, args: ["add", "--silent", spec] };
+  return { cmd: "npm", args: ["install", "--no-audit", "--no-fund", "--loglevel=error", spec] };
+}
+
+/** Installs a package into the installer's cache unless it's there already. */
+export function ensureInstalled({ name, range }, installer = "npm") {
+  const dir = cacheDir(installer);
   const alias = aliasFor(name, range);
   if (!existsSync(join(dir, "node_modules", alias, "package.json"))) {
-    const result = spawnSync(
-      "npm",
-      ["install", "--no-audit", "--no-fund", "--loglevel=error", `${alias}@npm:${name}@${range}`],
-      { cwd: dir, encoding: "utf8" },
-    );
+    const { cmd, args } = installCommand(installer, alias, name, range);
+    const result = spawnSync(cmd, args, { cwd: dir, encoding: "utf8" });
     if (result.status !== 0) {
-      throw new Error(`npm install ${name}@${range} failed:\n${result.stderr || result.error}`);
+      throw new Error(`${installer} install ${name}@${range} failed:\n${result.stderr || result.error}`);
     }
   }
   return { dir, alias };
 }
 
 export function installNodeResolveHooks({ shimUrl, replUrl }) {
-  registerHooks({
+  module.registerHooks({
     resolve(specifier, context, nextResolve) {
       let pkg = null;
       if (specifier.startsWith("npm:")) pkg = parsePackageSpecifier(specifier.slice(4));