@tlockney/cdp-kernel 0.4.0 → 0.5.0

package/dist/bun-target.js

@@ -9,9 +9,11 @@ import { Buffer } from "node:buffer";
 import process from "node:process";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
+import { asEvaluateResult } from "./cdp.js";
 import { transformCellForEval } from "./transform.js";
 import { runtimeDir } from "./package.js";
-import { Gates, Interrupted, isTargetMessage, PipeDemux } from "./target.js";
+import { killOnExit } from "./children.js";
+import { Gates, Interrupted, isTargetMessage, parseJson, PipeDemux } from "./target.js";
 /**
  * How long an interrupted target has to answer a ping. A cell waiting on a
  * promise leaves the event loop free, so the answer is near-instant; a busy
@@ -45,6 +47,9 @@ export class BunTarget {
     #gates = new Gates();
     #pending = new Map();
     #nextId = 0;
+    /** Ids of requests interrupt() may cut short: eval and comm. */
+    #interruptibleIds = new Set();
+    #exitedOnce = false;
     #messages = Promise.resolve();
     #interrupted = false;
     #stopNote;
@@ -60,6 +65,7 @@ export class BunTarget {
         const env = { ...process.env, FORCE_COLOR: "1" };
         delete env.NO_COLOR;
         const child = spawn(cmd, args, { cwd: options.cwd, stdio: ["pipe", "pipe", "pipe", "pipe"], env });
+        killOnExit(child);
         const channel = child.stdio[3];
         if (!child.stdout || !child.stderr || !isDuplex(channel)) {
             child.kill();
@@ -97,7 +103,8 @@ export class BunTarget {
         this.#channel.on("data", (chunk) => {
             buffer += chunk;
             for (let nl = buffer.indexOf("\n"); nl !== -1; nl = buffer.indexOf("\n")) {
-                const msg = JSON.parse(buffer.slice(0, nl));
+                // Cells can write here through __cdpk_send too (#122).
+                const msg = parseJson(buffer.slice(0, nl));
                 buffer = buffer.slice(nl + 1);
                 if (isTargetMessage(msg))
                     this.#deliver(msg, events);
@@ -116,12 +123,14 @@ export class BunTarget {
         if (!pending)
             return; // abandoned
         this.#pending.delete(id);
+        this.#interruptibleIds.delete(id);
         if (typeof reply.failure === "string")
             pending.reject(new Error(reply.failure));
         else
             pending.resolve(reply);
     }
     #exited(code, events) {
+        this.#exitedOnce = true;
         this.#gates.openAll();
         this.#stdout.close();
         this.#stderr.close();
@@ -132,6 +141,7 @@ export class BunTarget {
         for (const pending of this.#pending.values())
             pending.reject(new Abandoned(reason));
         this.#pending.clear();
+        this.#interruptibleIds.clear();
     }
     // Binding messages wait until both pipes have caught up to their marker,
     // and are delivered strictly in order (as in Target).
@@ -142,10 +152,15 @@ export class BunTarget {
             this.#gates.open(msg.barrier);
         });
     }
-    #request(op, params = {}) {
+    #request(op, params = {}, interruptible = false) {
+        // Bun is gone; a write to its channel would never be answered.
+        if (this.#exitedOnce)
+            return Promise.reject(new Abandoned("the bun session is closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
             this.#pending.set(id, { resolve, reject });
+            if (interruptible)
+                this.#interruptibleIds.add(id);
             this.#channel.write(JSON.stringify({ id, op, ...params }) + "\n");
         });
     }
@@ -153,7 +168,7 @@ export class BunTarget {
     async #interruptible(op, params, what) {
         this.#interrupted = false;
         try {
-            return await this.#request(op, params);
+            return await this.#request(op, params, true);
         }
         catch (err) {
             if (err instanceof Abandoned || this.#interrupted)
@@ -162,7 +177,7 @@ export class BunTarget {
         }
     }
     async evaluate(script) {
-        return (await this.#interruptible("eval", { code: script }, "Execution"));
+        return asEvaluateResult(await this.#interruptible("eval", { code: script }, "Execution"));
     }
     /**
      * There's no terminateExecution, but a cell that's waiting on a promise
@@ -173,12 +188,19 @@ export class BunTarget {
      */
     async interrupt() {
         this.#interrupted = true;
+        const running = [...this.#interruptibleIds];
         const answered = await Promise.race([
             this.#request("ping").then(() => true, () => false),
             new Promise((resolve) => setTimeout(() => resolve(false), INTERRUPT_GRACE_MS)),
         ]);
         if (answered) {
-            this.#abandonPending("interrupted");
+            // Only the cell or comm handler: a barrier or broadcast request in
+            // flight would otherwise fail as a KernelError (#135).
+            for (const id of running) {
+                this.#pending.get(id)?.reject(new Abandoned("interrupted"));
+                this.#pending.delete(id);
+                this.#interruptibleIds.delete(id);
+            }
             return;
         }
         this.#stopNote = RESTART_NOTE;
@@ -227,8 +249,8 @@ export class BunTarget {
     lexicalNames() {
         return Promise.resolve([]);
     }
-    replyInput(value) {
-        this.#child.stdin?.write(JSON.stringify({ value }) + "\n");
+    replyInput(value, interrupted = false) {
+        this.#child.stdin?.write(JSON.stringify({ value, interrupted }) + "\n");
     }
     kill() {
         this.#child.kill();

package/dist/cdp.d.ts

@@ -29,7 +29,6 @@ export declare class CdpAbandoned extends Error {
 }
 export declare class CdpSession {
     #private;
-    readonly closed: Promise<void>;
     private constructor();
     static connect(url: string): Promise<CdpSession>;
     on(method: string, listener: (params: CdpParams) => void): void;
@@ -38,4 +37,10 @@ export declare class CdpSession {
     abandonPending(): void;
     close(): void;
 }
+export declare function isRecord(value: unknown): value is CdpParams;
+export declare function isRemoteObject(value: unknown): value is RemoteObject;
+/**
+ * A Runtime.evaluate-shaped reply, checked: a value, or exceptionDetails.
+ * The Bun and workerd drivers send no `result` with a thrown exception.
+ */
 export declare function asEvaluateResult(raw: CdpParams): EvaluateResult;

package/dist/cdp.js

@@ -21,7 +21,6 @@ export class CdpSession {
     #nextId = 0;
     #pending = new Map();
     #listeners = new Map();
-    closed;
     constructor(ws) {
         this.#ws = ws;
         ws.addEventListener("message", (event) => {
@@ -43,14 +42,11 @@ export class CdpSession {
                     listener(msg.params);
             }
         });
-        this.closed = new Promise((resolve) => {
-            ws.addEventListener("close", () => {
-                for (const pending of this.#pending.values()) {
-                    pending.reject(new Error("CDP connection closed"));
-                }
-                this.#pending.clear();
-                resolve();
-            });
+        ws.addEventListener("close", () => {
+            for (const pending of this.#pending.values()) {
+                pending.reject(new Error("CDP connection closed"));
+            }
+            this.#pending.clear();
         });
     }
     static async connect(url) {
@@ -67,6 +63,10 @@ export class CdpSession {
         this.#listeners.set(method, list);
     }
     send(method, params = {}) {
+        // send() on a closing or closed socket drops the frame silently, so
+        // nothing would ever settle the call (#133).
+        if (this.#ws.readyState !== WebSocket.OPEN)
+            return Promise.reject(new Error("CDP connection closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
             this.#pending.set(id, { method, resolve, reject });
@@ -84,6 +84,21 @@ export class CdpSession {
         this.#ws.close();
     }
 }
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function isRemoteObject(value) {
+    return isRecord(value) && typeof value.type === "string";
+}
+/**
+ * A Runtime.evaluate-shaped reply, checked: a value, or exceptionDetails.
+ * The Bun and workerd drivers send no `result` with a thrown exception.
+ */
 export function asEvaluateResult(raw) {
-    return raw;
+    const details = raw.exceptionDetails;
+    if (details !== undefined ? !isRecord(details) || typeof details.text !== "string" : !isRemoteObject(raw.result)) {
+        throw new Error(`the target sent a malformed evaluate result: ${JSON.stringify(raw).slice(0, 200)}`);
+    }
+    const result = isRemoteObject(raw.result) ? raw.result : { type: "undefined" };
+    return details === undefined ? { result } : { result, exceptionDetails: details };
 }

package/dist/celld-target.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams } from "./cdp.ts";
+import { type CdpParams } from "./cdp.ts";
 import type { TargetEvents } from "./target.ts";
 import { WorkerdTarget } from "./workerd-target.ts";
 /** The project keys the generated config keeps: bindings and compatibility. */

package/dist/celld-target.js

@@ -21,8 +21,10 @@ import { createServer } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { build } from "esbuild";
+import { isRecord } from "./cdp.js";
 import { parseJsonc } from "./deno-config.js";
 import { runtimeDir } from "./package.js";
+import { killOnExit } from "./children.js";
 import { cellMeta, WorkerdTarget } from "./workerd-target.js";
 import { builtinAliases, findWranglerConfig } from "./workers-project.js";
 /** The project keys the generated config keeps: bindings and compatibility. */
@@ -141,6 +143,8 @@ function killTree(child) {
     }
     child.kill("SIGKILL");
 }
+/** Starts tried when a port is taken (see CelldHost.start). */
+const PORT_ATTEMPTS = 3;
 /** The driver on `celld dev`. */
 class CelldHost {
     runtime;
@@ -153,7 +157,23 @@ class CelldHost {
         this.runtime = runtime;
         this.project = project;
     }
+    /**
+     * celld dev, retried when a port is taken: both its --port (from
+     * freePort) and its node's own listener are picked free and bound later,
+     * so another process can take one in between (#54).
+     */
     static async start(cwd, projectConfig, executable) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await CelldHost.#start(cwd, projectConfig, executable);
+            }
+            catch (err) {
+                if (attempt >= PORT_ATTEMPTS || !(err instanceof Error && /Address already in use/.test(err.message)))
+                    throw err;
+            }
+        }
+    }
+    static async #start(cwd, projectConfig, executable) {
         const celld = executable ?? findCelld();
         const version = celldVersionOf(execFileSync(celld, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }));
         const source = await runtimeDir(new URL("../runtime/", import.meta.url).href);
@@ -163,7 +183,7 @@ class CelldHost {
             if (projectConfig.endsWith(".toml"))
                 throw new Error("celld reads wrangler.jsonc or wrangler.json, not wrangler.toml");
             const parsed = parseJsonc(readFileSync(projectConfig, "utf8"));
-            if (typeof parsed !== "object" || parsed === null)
+            if (!isRecord(parsed) || Array.isArray(parsed))
                 throw new Error(`${projectConfig} is not an object`);
             project = parsed;
             dir = join(dirname(projectConfig), ".celld", "cdp-kernel");
@@ -173,9 +193,14 @@ class CelldHost {
             dir = mkdtempSync(join(tmpdir(), "cdpk-celld-"));
         }
         const main = project && typeof project.main === "string" ? resolve(dirname(projectConfig ?? cwd), project.main) : undefined;
-        const define = project && typeof project.define === "object" && project.define !== null
-            ? project.define
-            : {};
+        const define = {};
+        if (project && isRecord(project.define)) {
+            for (const [name, value] of Object.entries(project.define)) {
+                if (typeof value !== "string")
+                    throw new Error(`define.${name} in ${projectConfig} must be a string`);
+                define[name] = value;
+            }
+        }
         const token = randomBytes(32).toString("hex");
         // 0600: the config carries this launch's token.
         writeFileSync(join(dir, "driver.mjs"), await bundleDriver(source, main, define));
@@ -186,25 +211,35 @@ class CelldHost {
         const child = spawn(celld, ["dev", dir, "--host", "127.0.0.1", "--port", String(port), "--no-watch"], {
             stdio: ["ignore", "pipe", "pipe"],
         });
-        child.once("exit", () => {
+        const removeFiles = () => {
             if (projectConfig === null)
                 rmSync(dir, { recursive: true, force: true });
             else
                 for (const name of ["driver.mjs", "wrangler.jsonc"])
                     rmSync(join(dir, name), { force: true });
+        };
+        child.once("exit", removeFiles);
+        killOnExit(child, () => {
+            killTree(child);
+            removeFiles();
         });
         // Cell output is captured in the driver; celld's own lines go to the
         // server log.
+        // `early` keeps that output for a startup error only, and stops growing
+        // once the session is open.
         let early = "";
+        let starting = true;
         const log = (chunk) => {
-            early += chunk.toString();
+            if (starting)
+                early += chunk.toString();
             process.stderr.write(`[cdp-kernel celld] ${chunk}`);
         };
         child.stdout?.on("data", log);
         child.stderr?.on("data", log);
         const exited = new Promise((_, reject) => {
             child.once("error", reject);
-            child.once("exit", (code) => reject(new Error(`celld exited (${code}) before it was ready:\n${early}`)));
+            // On close, not exit, so its last output is in the message.
+            child.once("close", (code) => reject(new Error(`celld exited (${code}) before it was ready:\n${early}`)));
         });
         exited.catch(() => { });
         const url = `127.0.0.1:${port}/?token=${token}`;
@@ -226,7 +261,10 @@ class CelldHost {
             return channelOf(ws);
         })();
         try {
-            return new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+            const host = new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+            starting = false;
+            early = "";
+            return host;
         }
         catch (err) {
             killTree(child);

package/dist/children.d.ts

@@ -0,0 +1,7 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * Kills `child` if it's still running when this process exits. `cleanup`
+ * replaces the default SIGKILL; it must be synchronous, as exit hooks are,
+ * and do whatever the child's own exit listener would have done.
+ */
+export declare function killOnExit(child: ChildProcess, cleanup?: () => void): void;

package/dist/children.js

@@ -0,0 +1,32 @@
+// Runtimes this process started, killed when it exits however it exits
+// short of SIGKILL: a target left behind keeps running, reparented to pid 1,
+// with whatever temp directory it uses (#127, #218).
+import process from "node:process";
+const cleanups = new Set();
+function runAll() {
+    for (const cleanup of cleanups) {
+        try {
+            cleanup();
+        }
+        catch {
+            // Best effort: the process is exiting.
+        }
+    }
+    cleanups.clear();
+}
+let hooked = false;
+/**
+ * Kills `child` if it's still running when this process exits. `cleanup`
+ * replaces the default SIGKILL; it must be synchronous, as exit hooks are,
+ * and do whatever the child's own exit listener would have done.
+ */
+export function killOnExit(child, cleanup = () => child.kill("SIGKILL")) {
+    if (!hooked) {
+        hooked = true;
+        process.on("exit", runAll);
+    }
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    cleanups.add(cleanup);
+    child.once("exit", () => cleanups.delete(cleanup));
+}

package/dist/debugger.d.ts

@@ -1,4 +1,4 @@
-import type { CdpParams, RemoteObject } from "./cdp.ts";
+import { type CdpParams, type RemoteObject } from "./cdp.ts";
 import { type CellTransformOptions } from "./transform.ts";
 /** What the debugger needs from a CDP target: its session, with the Debugger domain. */
 export interface DebugChannel {

package/dist/debugger.js

@@ -8,13 +8,14 @@
 // as their //# sourceURL, so breakpoints bind and frames point at the cell.
 // Lines go through the cell's source map (src/sourcemap.ts), since esbuild
 // rewrites TypeScript.
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { isRecord, isRemoteObject } from "./cdp.js";
 import { murmur2 } from "./murmur2.js";
-import { transformCellWithLines } from "./transform.js";
+import { SETTLE, transformCellWithLines } from "./transform.js";
 /** ipykernel's seed, so a kernel switch doesn't move JupyterLab's breakpoints. */
 export const HASH_SEED = 0xc70f6907;
 export const THREAD_ID = 1;
@@ -35,9 +36,6 @@ const SCOPE_NAMES = {
     eval: "Eval",
     global: "Globals",
 };
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
 /**
  * CDPK_DEBUG_TRACE=1 logs every debug request, reply and event to stderr
  * (the Jupyter server's log), for diagnosing a frontend.
@@ -48,8 +46,11 @@ function trace(kind, ...parts) {
     const text = parts.map((p) => JSON.stringify(p)).join(" -> ");
     process.stderr.write(`[cdp-kernel debugger] ${kind} ${text.length > 600 ? `${text.slice(0, 600)}…` : text}\n`);
 }
-function isRemoteObject(value) {
-    return isRecord(value) && typeof value.type === "string";
+function isCallFrame(value) {
+    return isRecord(value) && typeof value.callFrameId === "string" && typeof value.functionName === "string" &&
+        isRecord(value.location) && typeof value.location.scriptId === "string" &&
+        typeof value.location.lineNumber === "number" && Array.isArray(value.scopeChain) &&
+        value.scopeChain.every((scope) => isRecord(scope) && typeof scope.type === "string" && isRemoteObject(scope.object));
 }
 /** A DAP value string for a CDP RemoteObject. */
 export function describeRemote(object) {
@@ -88,6 +89,7 @@ export class Debugger {
     #pauseWaiters = [];
     #emit;
     #transformOptions;
+    #cleanupRegistered = false;
     constructor(emit, transformOptions = () => ({})) {
         this.#emit = emit;
         this.#transformOptions = transformOptions;
@@ -330,7 +332,7 @@ export class Debugger {
     }
     // --- stopped state ----------------------------------------------------------
     #onPaused(params) {
-        this.#frames = Array.isArray(params.callFrames) ? params.callFrames : [];
+        this.#frames = Array.isArray(params.callFrames) ? params.callFrames.filter(isCallFrame) : [];
         this.#stopped = true;
         for (const notify of this.#pauseWaiters.splice(0))
             notify();
@@ -453,7 +455,6 @@ export class Debugger {
             const res = await this.#unlessPaused(channel.send("Runtime.evaluate", {
                 expression: name,
                 contextId: channel.contextId,
-                replMode: true,
                 throwOnSideEffect: true,
             }));
             if (res === null)
@@ -470,9 +471,14 @@ export class Debugger {
             throw new Error("no target to debug");
         // While paused, only a frame can evaluate: use the top one if none was named.
         const frame = typeof frameId === "number" ? this.#frames[frameId] : this.#stopped ? this.#frames[0] : undefined;
+        // replMode (for the console's `await`) returns a promise the inspector
+        // holds only weakly: SETTLE closes that window, as for cells (#55). A
+        // side-effect-free lookup can't await, so it uses a plain evaluate.
         const res = frame
             ? await channel.send("Debugger.evaluateOnCallFrame", { callFrameId: frame.callFrameId, expression, throwOnSideEffect: pure })
-            : await channel.send("Runtime.evaluate", { expression, contextId: channel.contextId, replMode: true, throwOnSideEffect: pure });
+            : pure
+                ? await channel.send("Runtime.evaluate", { expression, contextId: channel.contextId, throwOnSideEffect: true })
+                : await channel.send("Runtime.evaluate", { expression: expression + SETTLE, contextId: channel.contextId, replMode: true });
         if (isRecord(res.exceptionDetails)) {
             const exception = res.exceptionDetails.exception;
             throw new Error(exception ? describeRemote(exception) : String(res.exceptionDetails.text ?? "evaluation failed"));
@@ -519,6 +525,11 @@ export class Debugger {
     }
     #writeCell(path, code) {
         try {
+            if (!this.#cleanupRegistered) {
+                // The files only serve this kernel's frontend: remove them with it.
+                process.once("exit", () => rmSync(this.prefix, { recursive: true, force: true }));
+                this.#cleanupRegistered = true;
+            }
             mkdirSync(this.prefix, { recursive: true });
             writeFileSync(path, code);
         }

package/dist/globals.d.ts

@@ -2,9 +2,9 @@
  * Ambient types for notebook cells run by cdp-kernel: the `jupyter` display
  * namespace and the stdin-backed `prompt`/`confirm`.
  *
- * Load it once per project, for example
- * `/// <reference types="@tlockney/cdp-kernel/globals" />` (npm) or
- * `import type {} from "jsr:@tlockney/cdp-kernel/globals";` (Deno).
+ * Load it once per project, for example with
+ * `/// <reference types="@tlockney/cdp-kernel/globals" />`. It ships in the
+ * npm package only: Deno notebooks use `Deno.jupyter`, which Deno types.
  *
  * A custom display is a class with a `[jupyter.$display]()` method returning
  * a media bundle. At runtime that key is `Symbol.for("Jupyter.display")`, but

package/dist/globals.js

@@ -2,9 +2,9 @@
  * Ambient types for notebook cells run by cdp-kernel: the `jupyter` display
  * namespace and the stdin-backed `prompt`/`confirm`.
  *
- * Load it once per project, for example
- * `/// <reference types="@tlockney/cdp-kernel/globals" />` (npm) or
- * `import type {} from "jsr:@tlockney/cdp-kernel/globals";` (Deno).
+ * Load it once per project, for example with
+ * `/// <reference types="@tlockney/cdp-kernel/globals" />`. It ships in the
+ * npm package only: Deno notebooks use `Deno.jupyter`, which Deno types.
  *
  * A custom display is a class with a `[jupyter.$display]()` method returning
  * a media bundle. At runtime that key is `Symbol.for("Jupyter.display")`, but