@tlockney/cdp-kernel 0.4.0 → 0.6.0

package/runtime/bootstrap.mjs

@@ -2,8 +2,8 @@
 //   node --inspect=127.0.0.1:0 runtime/bootstrap.mjs
 //   deno run -A --inspect=127.0.0.1:0 runtime/bootstrap.mjs
 // 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.
+// runtime lives on globalThis.__cdpk; output to the host goes over plain
+// stdout/stderr, with messages as records on stdout (see send below).
 // Bun is launched as `bun runtime/bootstrap.mjs` and driven over a pipe
 // instead; see bun-channel.mjs.
 //
@@ -27,7 +27,7 @@ const cwdUrl = pathToFileURL(cwd.endsWith("/") ? cwd : cwd + "/");
 // Stand-in referrer for cell code, like Deno's ./$deno$jupyter_repl.mts.
 const replUrl = new URL("$cdpk$repl.mjs", cwdUrl);
 
-const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdinLine } = await platform();
+const { inspect, inspectPlain, readFile, writeOut, writeErr, readStdin } = await platform();
 
 function base64(bytes) {
   let binary = "";
@@ -38,11 +38,12 @@ function base64(bytes) {
 }
 
 // --- Output ordering ----------------------------------------------------
-// stdout/stderr reach the host over pipes; display messages over the
-// WebSocket. To keep them in order, every binding message is preceded by a
-// numbered marker written to both pipes. The host holds the message until
-// both pipes have delivered that marker, and a gated marker ("m") holds
-// later pipe output until the message has gone out.
+// stdout/stderr reach the host over pipes, and so do messages: as records
+// on stdout on Node and Deno, over Bun's channel on Bun. Every message has
+// a number; stderr gets a gated marker ("m") with it, and stdout the record
+// (Bun: a gated marker on both pipes). The host holds the message until
+// both pipes have reached that number, and holds later pipe output until
+// the message has gone out.
 let barrierSeq = 0;
 function barrier(gated = false) {
   const n = ++barrierSeq;
@@ -52,10 +53,32 @@ function barrier(gated = false) {
   return n;
 }
 
+// Node and Deno: messages were a CDP binding's events, but an event just
+// before an evaluate's reply delays the reply ~40 ms (#271). A record is
+// the message's JSON, which holds no raw ESC, between "\x1b[cdpk:<" and
+// "\x1b]". Cells can call this too; the host drops what isn't a message
+// (#122).
+let attached = false;
+function sendRecord(text) {
+  text = String(text);
+  if (attached && !text.includes("\x1b")) writeOut(`\x1b[cdpk:<${text}\x1b]`);
+}
+if (!isBun) globalThis.__cdpk_send = sendRecord;
+
 function send(payload) {
-  const binding = globalThis.__cdpk_send;
-  if (typeof binding !== "function") return; // host not attached yet
-  binding(JSON.stringify({ ...payload, barrier: barrier(true) }));
+  if (isBun ? typeof globalThis.__cdpk_send !== "function" : !attached) return; // host not attached yet
+  // 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);
+  if (isBun) {
+    globalThis.__cdpk_send(`{"barrier":${barrier(true)},${body.slice(1)}`);
+    return;
+  }
+  const n = ++barrierSeq;
+  writeErr(`\x1b[cdpk:${n}m]\x1b`);
+  sendRecord(`{"barrier":${n},${body.slice(1)}`);
 }
 
 const jupyter = createJupyter({
@@ -69,9 +92,16 @@ const jupyter = createJupyter({
   // stdin for its JSON-line reply.
   input(prompt, password) {
     send({ kind: "input_request", prompt, password });
-    const line = readStdinLine();
+    const line = readInputReply();
     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,9 +161,37 @@ 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;
+}
+
+// Yields one macrotask. Code the inspector dispatches calls this, and Node
+// and Deno dispatch a message that arrives while JavaScript runs from a V8
+// interrupt, which can land inside their timer code. A setTimeout there can
+// create a timer list while the timer heap is mid-update, and the heap then
+// loses it: every later setTimeout of that duration never fires (#237).
+// setImmediate only appends to a linked list.
+const yieldTask = () => new Promise((resolve) => setImmediate(resolve));
+
+// 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 = {
+  // The host calls this once it reads message records (Node and Deno).
+  attach: () => void (attached = true),
   // Cell code awaits this first; see PRELUDE in src/transform.ts.
-  tick: () => new Promise((resolve) => setTimeout(resolve, 0)),
+  tick: yieldTask,
   // Node: the resolve hook re-parents these imports. Deno would resolve
   // relative paths against this file, so denoImport does it here.
   import: (specifier, options) =>
@@ -149,6 +207,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.
@@ -165,13 +224,24 @@ globalThis.__cdpk = {
   // Frontend comm messages (#9), from the host's shell channel. Handlers
   // run after one macrotask, like cells, so interrupt can reach them.
   async commDispatch(msgType, content, metadata, buffers64) {
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await yieldTask();
     const buffers = buffers64.map((b) => Uint8Array.from(atob(b), (c) => c.charCodeAt(0)));
     return await jupyter.commDispatch(msgType, content, metadata, buffers);
   },
+  // The same, for a message the host wrote to stdin (Node and Deno). A
+  // value passed as a CDP call argument is compiled as source, and V8's
+  // compilation cache keeps that source until the heap nears its limit, so
+  // each message's data would stay in memory (#287). Read before the first
+  // await, so messages are taken in the order the host wrote them.
+  commDispatchFromStdin() {
+    const { msgType, content, metadata, buffers } = readCommRecord();
+    return globalThis.__cdpk.commDispatch(msgType, content, metadata, buffers);
+  },
   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 +254,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 +314,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");
@@ -230,47 +345,123 @@ if (isBun) {
   });
 }
 
+function writeAllSync(stream, bytes) {
+  while (bytes.length > 0) bytes = bytes.subarray(stream.writeSync(bytes));
+}
+
 async function platform() {
   if (isDeno) {
-    const stdinBuf = new Uint8Array(1);
     return {
       inspect: (v) => Deno.inspect(v, { colors: true, depth: 4 }),
       inspectPlain: (v) => Deno.inspect(v, { colors: false, depth: 2 }),
       readFile: (p) => Deno.readFileSync(p),
-      writeOut: (s) => Deno.stdout.writeSync(ENC.encode(s)),
-      writeErr: (s) => Deno.stderr.writeSync(ENC.encode(s)),
-      readStdinLine: () => readLine(() => (Deno.stdin.readSync(stdinBuf) ? stdinBuf[0] : null)),
+      // writeSync can write part of the buffer; a record must go out whole.
+      writeOut: (s) => writeAllSync(Deno.stdout, ENC.encode(s)),
+      writeErr: (s) => writeAllSync(Deno.stderr, ENC.encode(s)),
+      readStdin: (bytes) => Deno.stdin.readSync(bytes) ?? 0,
     };
   }
   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 }),
     readFile: (p) => fs.readFileSync(p),
-    writeOut: (s) => process.stdout.write(s),
-    writeErr: (s) => process.stderr.write(s),
-    readStdinLine: () =>
-      readLine(() => {
-        for (;;) {
-          try {
-            return fs.readSync(0, buf, 0, 1, null) === 1 ? buf[0] : null;
-          } catch (err) {
-            if (err.code !== "EAGAIN") throw err;
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
-          }
+    // Bound now: a cell or library that patches process.stdout.write to
+    // capture output must not swallow message records (#271).
+    writeOut: process.stdout.write.bind(process.stdout),
+    writeErr: process.stderr.write.bind(process.stderr),
+    readStdin: (bytes) => {
+      for (;;) {
+        try {
+          return fs.readSync(0, bytes, 0, bytes.length, null);
+        } catch (err) {
+          if (err.code !== "EAGAIN") throw err;
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
         }
-      }),
+      }
+    },
   };
 }
 
-function readLine(nextByte) {
+// 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);
+  }
+}
+
+// The host writes two kinds of record to stdin, both read synchronously: a
+// prompt's reply, as one JSON line, and a frontend comm message (#287), as
+// a `comm <length>` line followed by that many bytes of JSON.
+const COMM_HEADER = /^comm (\d+)$/;
+
+/** `n` bytes from stdin, or null if it ends first. */
+function readExactly(n) {
+  const bytes = new Uint8Array(n);
+  for (let at = 0; at < n;) {
+    const got = readStdin(bytes.subarray(at));
+    if (!got) return null;
+    at += got;
+  }
+  return bytes;
+}
+
+function readLine() {
   const bytes = [];
   for (;;) {
-    const byte = nextByte();
+    const byte = readExactly(1)?.[0] ?? null;
     if (byte === null) return bytes.length ? new TextDecoder().decode(new Uint8Array(bytes)) : null;
     if (byte === 0x0a) return new TextDecoder().decode(new Uint8Array(bytes));
     bytes.push(byte);
   }
 }
+
+/** The next prompt reply's line, past any comm record left unread. */
+function readInputReply() {
+  for (;;) {
+    const line = readLine();
+    const comm = line === null ? null : COMM_HEADER.exec(line);
+    if (comm === null) return line;
+    readExactly(Number(comm[1]));
+  }
+}
+
+/** The next comm message, past any prompt reply left unread. */
+function readCommRecord() {
+  for (;;) {
+    const line = readLine();
+    if (line === null) throw new Error("stdin closed before a comm message arrived");
+    const comm = COMM_HEADER.exec(line);
+    if (comm === null) continue;
+    const body = readExactly(Number(comm[1]));
+    if (body === null) throw new Error("stdin closed in the middle of a comm message");
+    return JSON.parse(new TextDecoder().decode(body));
+  }
+}

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/introspect.mjs

@@ -77,7 +77,7 @@ function safeSource(fn) {
 function propertyNames(value) {
   if ((typeof value !== "object" && typeof value !== "function") || value === null) return [];
   try {
-    // A function's own internals aren't worth listing; older V8 (Node 24)
+    // A function's own internals aren't worth listing; older V8 (Node 22 and 24)
     // also gives sloppy-mode functions own `arguments` and `caller`.
     const internal = ["length", "name", "prototype", "arguments", "caller"];
     return Object.getOwnPropertyNames(value).filter((n) => !(typeof value === "function" && internal.includes(n)));

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,21 @@ 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 }>;
+/** Where a package is installed in the cache, or null; never installs. */
+export function installedPackageDir(
+  pkg: { name: string; range: string },
+  installer?: Installer,
+  options?: { lockFile?: string | null },
+): { dir: string; alias: string } | null;
 
 export const LOCK_FILE: string;
 export interface Lock {
@@ -36,4 +63,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;