@tlockney/cdp-kernel 0.4.0 → 0.5.0

package/runtime/bootstrap.mjs

@@ -55,7 +55,12 @@ function barrier(gated = false) {
 function send(payload) {
   const binding = globalThis.__cdpk_send;
   if (typeof binding !== "function") return; // host not attached yet
-  binding(JSON.stringify({ ...payload, barrier: barrier(true) }));
+  // Serialize before writing the marker: if the payload can't be
+  // serialized (a BigInt, a cycle), the error reaches the cell without a
+  // gated marker the host would wait on forever (#129). `payload` always
+  // has a `kind`, so `body` is never "{}".
+  const body = JSON.stringify(payload);
+  binding(`{"barrier":${barrier(true)},${body.slice(1)}`);
 }
 
 const jupyter = createJupyter({
@@ -72,6 +77,13 @@ const jupyter = createJupyter({
     const line = readStdinLine();
     if (line === null) return null;
     const reply = JSON.parse(line);
+    if (reply.interrupted === true) {
+      // Interrupted while waiting for the answer: unwind the cell, as
+      // KeyboardInterrupt does in Python's input() (#121).
+      const err = new Error("Execution interrupted");
+      err.name = "Interrupted";
+      throw err;
+    }
     return typeof reply.value === "string" ? reply.value : null;
   },
 });
@@ -131,6 +143,24 @@ function bunResolve(specifier) {
   return Bun.resolveSync(specifier, cwd);
 }
 
+// The inspector holds a promise it awaits (callFunctionOn with awaitPromise)
+// only weakly until its then-callback runs, so a GC after the promise
+// settles but before that callback fails the call with "Promise was
+// collected" (#55). hold() keeps the promise until a macrotask after it
+// settles, by which time the inspector's callback has run.
+const held = new Set();
+function hold(value) {
+  const promise = Promise.resolve(value);
+  held.add(promise);
+  const release = () => setTimeout(() => held.delete(promise), 0);
+  promise.then(release, release);
+  return promise;
+}
+
+// Adds the cause to an error from a Deno member the --deno-compat shim
+// lacks (#172); the identity everywhere else.
+let explainError = (text) => text;
+
 globalThis.__cdpk = {
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
   tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
@@ -149,6 +179,7 @@ globalThis.__cdpk = {
     resolve: (specifier) => new URL(specifier, replUrl).href,
   },
   barrier,
+  hold,
   // inspect_request (#10). CDP targets find the value with
   // throwOnSideEffect and describe it here; Bun resolves the path here
   // too, by descriptor, so nothing runs.
@@ -171,7 +202,9 @@ globalThis.__cdpk = {
   },
   describeError(value) {
     if (value instanceof Error) {
-      return JSON.stringify({ name: value.name, message: value.message, stack: value.stack ?? "" });
+      const message = explainError(value.message);
+      const stack = stackOf(value).replace(value.message, () => message);
+      return JSON.stringify({ name: value.name, message, stack });
     }
     return JSON.stringify({ name: "Error", message: inspect(value), stack: "" });
   },
@@ -184,26 +217,48 @@ globalThis.confirm = jupyter.confirm;
 if (isDeno) {
   // Existing Deno notebooks use Deno.jupyter, but outside `deno jupyter`
   // that is a non-configurable getter that throws. The global binding
-  // itself is configurable, so swap in a proxy that answers `jupyter` and
-  // forwards everything else to the real namespace.
+  // itself is configurable, so swap in an object with its own `jupyter`
+  // that inherits everything else from the real namespace. Not a Proxy:
+  // completion can't list a Proxy's properties, and Shift-Tab's
+  // side-effect-free evaluation can't read through one (#132). So
+  // Object.keys(Deno) and console.log(Deno) show only `jupyter`, and
+  // Deno's functions are called with `this` set to this object (they
+  // don't use it).
   const real = globalThis.Deno;
   const descriptor = Object.getOwnPropertyDescriptor(globalThis, "Deno");
-  const proxy = new Proxy(real, {
-    get: (target, key) => (key === "jupyter" ? jupyter.namespace : Reflect.get(target, key, target)),
+  const shim = Object.create(real, {
+    jupyter: { value: jupyter.namespace, enumerable: true, configurable: true, writable: true },
   });
-  Object.defineProperty(globalThis, "Deno", { ...descriptor, value: proxy });
+  Object.defineProperty(globalThis, "Deno", { ...descriptor, value: shim });
 } else if (process.env.CDPK_DENO_COMPAT === "1" && globalThis.Deno === undefined) {
   // Opt-in (install --deno-compat): a Deno namespace for notebooks written
   // against `deno jupyter`. See runtime/deno-compat.mjs for the trade-off.
   // Absolute URL: the resolve hook re-parents this module's relative
   // imports to the notebook directory.
-  const { createDenoShim } = await import(new URL("./deno-compat.mjs", import.meta.url).href);
-  globalThis.Deno = createDenoShim({ jupyter: jupyter.namespace });
+  const { createDenoShim, explainMissing } = await import(new URL("./deno-compat.mjs", import.meta.url).href);
+  const shim = createDenoShim({ jupyter: jupyter.namespace });
+  globalThis.Deno = shim;
+  explainError = (text) => explainMissing(text, shim);
+}
+
+/**
+ * An error's stack, with its first line naming the error. Bun now and then
+ * (about one throw in twenty, #216) records a stack whose first line is a
+ * bare "Error", though name and message are set; the frames are right, so
+ * only the header is rebuilt.
+ */
+function stackOf(err) {
+  const stack = err.stack;
+  if (typeof stack !== "string") return "";
+  const nl = stack.indexOf("\n");
+  const first = nl === -1 ? stack : stack.slice(0, nl);
+  if (first !== "Error" || !err.message) return stack;
+  return `${err.name}: ${err.message}${nl === -1 ? "" : stack.slice(nl)}`;
 }
 
 // An error thrown later by a cell's timer or promise must not kill the kernel.
 function reportUncaught(kind, err) {
-  writeErr(`${kind}: ${err instanceof Error ? (err.stack ?? err.message) : inspect(err)}\n`);
+  writeErr(`${kind}: ${explainError(err instanceof Error ? (stackOf(err) || err.message) : inspect(err))}\n`);
 }
 if (isDeno) {
   globalThis.addEventListener("unhandledrejection", (e) => {
@@ -222,6 +277,29 @@ if (isDeno) {
 // Keep the event loop alive between cells.
 setInterval(() => {}, 1 << 30);
 
+// A host killed by SIGKILL can't stop its runtime, and nothing visible to
+// JS here changes when its inspector sessions drop, so watch for the host
+// itself going: reparented, or no longer there (#219). Bun exits on its
+// channel's EOF instead.
+if (!isBun) {
+  // Held here, so a cell that reassigns them can't break the watch.
+  const proc = process;
+  const exit = process.exit.bind(process);
+  const host = proc.ppid;
+  const hostGone = () => {
+    if (proc.ppid !== host) return true;
+    try {
+      proc.kill(host, 0);
+      return false;
+    } catch (err) {
+      return err?.code === "ESRCH";
+    }
+  };
+  setInterval(() => {
+    if (hostGone()) exit(1);
+  }, 2000);
+}
+
 if (isBun) {
   const { startChannel } = await import("./bun-channel.mjs");
   const { createHandler } = await import("./evaluator.mjs");
@@ -245,6 +323,14 @@ async function platform() {
   const util = await import("node:util");
   const fs = await import("node:fs");
   const buf = Buffer.alloc(1);
+  // Node writes to a pipe without blocking and queues what doesn't fit for
+  // the event loop to flush. input() blocks the main thread in readSync, so
+  // queued output, and the input_request's barrier marker after it, would
+  // never reach the host (#131). Blocking writes finish before readSync
+  // starts, as Node already does on Windows. Bun has no _handle and needs
+  // its own fix (#180).
+  if (isBun) await syncBunOutput();
+  else for (const stream of [process.stdout, process.stderr]) stream._handle?.setBlocking?.(true);
   return {
     inspect: (v) => util.inspect(v, { colors: true, depth: 4 }),
     inspectPlain: (v) => util.inspect(v, { colors: false, depth: 2 }),
@@ -265,6 +351,31 @@ async function platform() {
   };
 }
 
+// Bun makes stdout and stderr non-blocking once process.stdout or
+// process.stderr exists, and then queues what doesn't fit in the pipe for
+// its event loop, console.log's output included. input() blocks the main
+// thread in readSync, so queued output, and the input_request's barrier
+// marker after it, would never reach the host (#180). Here every write
+// finishes before it returns: process.stdout.write and process.stderr.write
+// write through, and console is Node's Console over them, so console output
+// is formatted as on Node.
+async function syncBunOutput() {
+  const { writeAll } = await import("./bun-channel.mjs");
+  const { Console } = await import("node:console");
+  for (const [stream, fd] of [[process.stdout, 1], [process.stderr, 2]]) {
+    stream.write = (chunk, encoding, callback) => {
+      if (typeof encoding === "function") [callback, encoding] = [encoding, undefined];
+      writeAll(fd, typeof chunk === "string" ? Buffer.from(chunk, encoding) : chunk);
+      if (callback) process.nextTick(callback);
+      return true;
+    };
+  }
+  const sync = new Console({ stdout: process.stdout, stderr: process.stderr, colorMode: true });
+  for (const key of Object.keys(console)) {
+    if (typeof sync[key] === "function") console[key] = sync[key].bind(sync);
+  }
+}
+
 function readLine(nextByte) {
   const bytes = [];
   for (;;) {

package/runtime/bun-channel.d.mts

@@ -1,3 +1,6 @@
 import type { Handler } from "./evaluator.mjs";
 
 export function startChannel(handle: Handler, ready: { [key: string]: unknown }, fd?: number): void;
+
+/** Writes all of `text` to `fd` before returning, even if the fd is non-blocking. */
+export function writeAll(fd: number, text: string | Uint8Array): void;

package/runtime/bun-channel.mjs

@@ -14,8 +14,8 @@ 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);
+export function writeAll(fd, text) {
+  const bytes = typeof text === "string" ? Buffer.from(text) : Buffer.from(text.buffer, text.byteOffset, text.byteLength);
   for (let offset = 0; offset < bytes.length;) {
     try {
       offset += fs.writeSync(fd, bytes, offset);

package/runtime/comm.mjs

@@ -89,7 +89,17 @@ export function createComms(send, newId = () => crypto.randomUUID()) {
     if (msgType === "comm_open") {
       const handler = targets.get(content.target_name);
       if (!handler) return false;
-      await handler(track(content.comm_id, content.target_name), msg);
+      const comm = track(content.comm_id, content.target_name);
+      try {
+        await handler(comm, msg);
+      } catch (err) {
+        // The host answers a failed comm_open with comm_close, so the comm
+        // is gone on the frontend: drop it here too, without running close
+        // handlers or sending anything (#137).
+        comm.closed = true;
+        forget(comm.id);
+        throw err;
+      }
       return true;
     }
     const comm = comms.get(content.comm_id);

package/runtime/deno-compat.d.mts

@@ -114,3 +114,5 @@ export interface DenoShim {
 
 export function denoError<E>(err: E): E | NotFound | AlreadyExists | PermissionDenied | IsADirectory | NotADirectory;
 export function createDenoShim(options: { jupyter: unknown }): DenoShim;
+/** Adds the cause to "Deno.x is not a function" when `shim` lacks `x`. */
+export function explainMissing(message: string, shim: object): string;

package/runtime/deno-compat.mjs

@@ -7,7 +7,8 @@
 // shim installed they take their Deno code paths, which may call APIs not
 // covered here (Deno.serve, Deno.Command, Deno.openKv, permissions...).
 // Uncovered APIs are simply absent rather than throwing on access, so
-// feature checks like `typeof Deno.serve === "function"` still work.
+// feature checks like `typeof Deno.serve === "function"` still work. The
+// error from calling one says so instead (explainMissing, #172).
 
 import fs from "node:fs";
 import fsp from "node:fs/promises";
@@ -100,6 +101,18 @@ const writeFlag = (options) => (options?.append ? "a" : options?.createNew ? "wx
 const OS_NAMES = { darwin: "darwin", linux: "linux", win32: "windows", freebsd: "freebsd" };
 const ARCH_NAMES = { arm64: "aarch64", x64: "x86_64" };
 
+const MEMBERS_DOC = "https://cdp-kernel.org/docs/jupyter-api#notebooks-written-for-deno";
+
+/**
+ * Adds the cause to V8's "Deno.serve is not a function" when `shim` lacks
+ * that member (#172), or returns `message` unchanged.
+ */
+export function explainMissing(message, shim) {
+  return message.replace(/\b(Deno\.([\w$]+)) is not a (?:function|constructor)\b/, (all, expr, name) =>
+    name in shim ? all : `${all}: ${expr} is not implemented by cdp-kernel's --deno-compat namespace (see ${MEMBERS_DOC})`
+  );
+}
+
 export function createDenoShim({ jupyter }) {
   return {
     jupyter,

package/runtime/display.mjs

@@ -180,7 +180,14 @@ export function createJupyter(host) {
   }
 
   function image(obj) {
-    if (typeof obj === "string") obj = host.readFile(obj);
+    if (typeof obj === "string") {
+      // As Deno does: a path that can't be read gets the TypeError below.
+      try {
+        obj = host.readFile(obj);
+      } catch {
+        // fall through
+      }
+    }
     if (isJpg(obj)) return { [$display]: () => ({ "image/jpeg": host.base64(obj) }) };
     if (isPng(obj)) return { [$display]: () => ({ "image/png": host.base64(obj) }) };
     throw new TypeError(

package/runtime/node-hooks.d.mts

@@ -8,12 +8,24 @@ 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";
+/** Where `installer` keeps its packages: $XDG_CACHE_HOME/cdp-kernel/<installer>, or CDPK_CACHE_DIR for npm. */
+export function cacheDirPath(
+  installer: Installer,
+  env?: { [name: string]: string | undefined },
+  home?: string,
+): string;
 export function installCommand(
   installer: Installer,
   alias: string,
   name: string,
   range: string,
 ): { cmd: string; args: string[]; env?: { [name: string]: string } };
+/** How to spawn an install command; on Windows, npm runs through cmd.exe. */
+export function spawnCommand(
+  cmd: string,
+  args: string[],
+  platform?: string,
+): { cmd: string; args: string[]; shell: boolean };
 /** Runs an install; `env` is added to the process environment. */
 export type InstallRunner = (
   cmd: string,
@@ -26,6 +38,15 @@ export function ensureInstalled(
   installer?: Installer,
   options?: { lockFile?: string | null; run?: InstallRunner },
 ): { dir: string; alias: string };
+/** ensureInstalled without blocking the event loop; `run` may return a promise. */
+export function ensureInstalledAsync(
+  pkg: { name: string; range: string },
+  installer?: Installer,
+  options?: {
+    lockFile?: string | null;
+    run?: (...args: Parameters<InstallRunner>) => ReturnType<InstallRunner> | Promise<ReturnType<InstallRunner>>;
+  },
+): Promise<{ dir: string; alias: string }>;
 
 export const LOCK_FILE: string;
 export interface Lock {
@@ -36,4 +57,25 @@ export function findLockFile(dir: string): string | null;
 export function readLock(path: string): Lock;
 export function writeLock(path: string, lock: Lock): void;
 export function withInstallLock<T>(dir: string, fn: () => T, options?: { timeoutMs?: number }): T;
+export function withInstallLockAsync<T>(dir: string, fn: () => T | Promise<T>, options?: { timeoutMs?: number }): Promise<T>;
+/** Compiles one TypeScript or JSX file with the esbuild binary at `binary`; `run` is replaceable in tests. */
+export function compileTypeScript(
+  source: string,
+  filename: string,
+  binary: string,
+  run?: (cmd: string, args: string[], options: object) => { status: number | null; stdout: string; stderr: string; error?: Error },
+  loader?: "ts" | "tsx" | "jsx",
+): string;
+export interface LoadResult {
+  format?: string | null;
+  source?: string | ArrayBuffer | ArrayBufferView | null;
+  shortCircuit?: boolean;
+}
+/** The load hook: Node's own result unless its type stripping would reject the file; .tsx/.jsx always compiled. */
+export function loadTypeScript(
+  url: string,
+  context: object,
+  nextLoad: (url: string, context: object) => LoadResult,
+  binary: string | undefined,
+): LoadResult;
 export function installNodeResolveHooks(urls: { shimUrl: string; replUrl: string }): void;