@tlockney/cdp-kernel 0.5.0 → 0.6.0

package/README.md

@@ -10,9 +10,19 @@ inspector speaks CDP works too.
 **Website:** <https://cdp-kernel.org/> ·
 **Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
 
+[![Try it on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/tlockney/cdp-kernel/main?urlpath=lab/tree/getting-started.ipynb)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tlockney/cdp-kernel?quickstart=1)
+
+Binder opens JupyterLab with every runtime and the example notebooks,
+nothing installed. A Codespace does the same in VS Code, with the
+repository checked out ([Install › In a container](https://cdp-kernel.org/docs/install#in-a-container)).
+
 This is early software. It passes a conformance suite derived from Deno's
 own Jupyter integration tests on every target, and it's packaged for npm and
 JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet.
+The [support policy](https://cdp-kernel.org/docs/support) says which
+runtime versions and frontends are supported, and what may change before
+1.0.
 
 ## Features
 
@@ -29,7 +39,7 @@ JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet.
 
 ## Install
 
-Node 24+ host, from npm:
+Node 22.18+ host, from npm:
 
 ```sh
 npm install -g @tlockney/cdp-kernel
@@ -43,11 +53,19 @@ deno run -A jsr:@tlockney/cdp-kernel/cli install --runtime deno
 ```
 
 Each install writes a Jupyter kernelspec (`cdp-node`, `cdp-deno`, …). Pick
-it in JupyterLab or VS Code. Linux and macOS are supported; Windows isn't
-yet. See [Install](https://cdp-kernel.org/docs/install)
-for `--deno-compat`, release-day installs on Deno, target runtime
+it in JupyterLab or VS Code. To run notebooks with no Python installed,
+serve JupyterLab with
+[Ganymede](https://ganymede-server.com/docs/workstation). Linux and macOS
+are supported; Windows isn't yet. See
+[Install](https://cdp-kernel.org/docs/install) for `--deno-compat`, release-day installs on Deno, target runtime
 requirements, and installing from a checkout.
 
+JupyterLab with every runtime and the examples, in a container:
+
+```sh
+docker run --rm -p 8888:8888 ghcr.io/tlockney/cdp-kernel
+```
+
 ## Quick start
 
 ```ts
@@ -68,10 +86,13 @@ New to Jupyter? Start with
   [Widgets and comms](https://cdp-kernel.org/docs/widgets),
   [Debugger](https://cdp-kernel.org/docs/debugger)
 - Reference: [Editor types](https://cdp-kernel.org/docs/editor-types),
-  [Known gaps](https://cdp-kernel.org/docs/known-gaps)
+  [Known gaps](https://cdp-kernel.org/docs/known-gaps),
+  [Support policy](https://cdp-kernel.org/docs/support)
 - Internals: [Architecture](https://cdp-kernel.org/docs/architecture),
   [Runtime integrations](https://cdp-kernel.org/docs/integrations)
-- Contributing: [Development](https://cdp-kernel.org/docs/development)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md),
+  [Development](https://cdp-kernel.org/docs/development),
+  [Security policy](SECURITY.md)
 
 The [feasibility study](https://cdp-kernel.org/docs/feasibility-study)
 behind the project covers the design, the alternatives considered (workerd,

package/dist/cdp.d.ts

@@ -33,6 +33,8 @@ export declare class CdpSession {
     static connect(url: string): Promise<CdpSession>;
     on(method: string, listener: (params: CdpParams) => void): void;
     send(method: string, params?: CdpParams): Promise<CdpParams>;
+    /** In-flight calls, oldest first, with how long each has waited: for a state dump (#237). */
+    pendingCalls(): string[];
     /** Reject every in-flight call; their late responses are then ignored. */
     abandonPending(): void;
     close(): void;

package/dist/cdp.js

@@ -69,10 +69,15 @@ export class CdpSession {
             return Promise.reject(new Error("CDP connection closed"));
         const id = ++this.#nextId;
         return new Promise((resolve, reject) => {
-            this.#pending.set(id, { method, resolve, reject });
+            this.#pending.set(id, { method, sent: Date.now(), resolve, reject });
             this.#ws.send(JSON.stringify({ id, method, params }));
         });
     }
+    /** In-flight calls, oldest first, with how long each has waited: for a state dump (#237). */
+    pendingCalls() {
+        const now = Date.now();
+        return [...this.#pending.values()].map((p) => `${p.method} (${now - p.sent} ms)`);
+    }
     /** Reject every in-flight call; their late responses are then ignored. */
     abandonPending() {
         for (const pending of this.#pending.values()) {

package/dist/celld-target.js

@@ -24,7 +24,7 @@ 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 { childPids, killOnExit, reapWith } 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. */
@@ -122,16 +122,10 @@ function channelOf(ws) {
         },
     };
 }
-/** celld dev's own children, which run in their own process groups. */
-function childPids(pid) {
-    try {
-        return execFileSync("pgrep", ["-P", String(pid)], { encoding: "utf8" }).split(/\s+/).filter(Boolean).map(Number);
-    }
-    catch {
-        return []; // none
-    }
-}
-/** Kills celld dev's node, then the supervisor itself. */
+/**
+ * Kills celld dev's own children, which run in their own process groups,
+ * then the supervisor itself.
+ */
 function killTree(child) {
     for (const pid of childPids(child.pid ?? -1)) {
         try {
@@ -222,7 +216,7 @@ class CelldHost {
         killOnExit(child, () => {
             killTree(child);
             removeFiles();
-        });
+        }, { dir: projectConfig === null ? dir : undefined });
         // 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
@@ -262,6 +256,9 @@ class CelldHost {
         })();
         try {
             const host = new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+            // Its server, in its own process group, outlives a SIGKILLed celld dev.
+            for (const pid of childPids(child.pid ?? -1))
+                reapWith(pid, child);
             starting = false;
             early = "";
             return host;

package/dist/children.d.ts

@@ -1,7 +1,29 @@
-import type { ChildProcess } from "node:child_process";
+import { type ChildProcess } from "node:child_process";
+/**
+ * The helper's script. Lines on stdin: `+pid` registers a pid, `-pid`
+ * forgets it (it exited, and the pid may be reused), `d<path>` registers a
+ * directory. In its own session, so a killpg of this process's group (as
+ * Jupyter's kill does) doesn't take it down first.
+ */
+export declare const REAPER_SCRIPT = "trap '' HUP INT\npids=\" \"\ndirs=\"\"\nwhile IFS= read -r line; do\n  case $line in\n    +*) pids=\"$pids${line#?} \" ;;\n    -*) pids=$(printf '%s' \"$pids\" | sed \"s/ ${line#?} / /\") ;;\n    d*) dirs=\"$dirs${line#?}\n\" ;;\n  esac\ndone\nkill -9 $pids 2>/dev/null\nprintf '%s' \"$dirs\" | while IFS= read -r dir; do rm -rf -- \"$dir\"; done\n";
+/**
+ * Kills `pid` if this process dies, until the returned function is called
+ * (when the process is known to have exited: its pid may be reused).
+ */
+export declare function reap(pid: number): () => void;
+/**
+ * Kills `pid`, which isn't this process's child (a runtime's own child in
+ * its own process group), if this process dies while `owner` runs.
+ */
+export declare function reapWith(pid: number, owner: ChildProcess): void;
+/** `pid`'s children whose command line matches `pattern` (pgrep's -f). */
+export declare function childPids(pid: number, pattern?: string): number[];
 /**
  * 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.
+ * and do whatever the child's own exit listener would have done. If this
+ * process is SIGKILLed, the helper kills `child` and removes `dir`.
  */
-export declare function killOnExit(child: ChildProcess, cleanup?: () => void): void;
+export declare function killOnExit(child: ChildProcess, cleanup?: () => void, { dir }?: {
+    dir?: string;
+}): void;

package/dist/children.js

@@ -1,7 +1,15 @@
 // 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).
+//
+// SIGKILL runs no exit hook, so a helper outside this process also knows the
+// runtimes' pids (#240): a detached sh reading this process's pipe, which
+// kills whatever is still registered, and removes the registered temp
+// directories, once the pipe closes. That covers what nothing in a runtime
+// can notice: celld dev and its server, and a Node or Deno runtime stuck in
+// a cell's synchronous loop, where the #219 watchdog never gets to run.
 import process from "node:process";
+import { execFileSync, spawn } from "node:child_process";
 const cleanups = new Set();
 function runAll() {
     for (const cleanup of cleanups) {
@@ -15,12 +23,82 @@ function runAll() {
     cleanups.clear();
 }
 let hooked = false;
+/**
+ * The helper's script. Lines on stdin: `+pid` registers a pid, `-pid`
+ * forgets it (it exited, and the pid may be reused), `d<path>` registers a
+ * directory. In its own session, so a killpg of this process's group (as
+ * Jupyter's kill does) doesn't take it down first.
+ */
+export const REAPER_SCRIPT = `trap '' HUP INT
+pids=" "
+dirs=""
+while IFS= read -r line; do
+  case $line in
+    +*) pids="$pids\${line#?} " ;;
+    -*) pids=$(printf '%s' "$pids" | sed "s/ \${line#?} / /") ;;
+    d*) dirs="$dirs\${line#?}
+" ;;
+  esac
+done
+kill -9 $pids 2>/dev/null
+printf '%s' "$dirs" | while IFS= read -r dir; do rm -rf -- "$dir"; done
+`;
+let reaper;
+/** Sends `line` to the helper, starting it first; a no-op on Windows. */
+function tellReaper(line) {
+    if (reaper === undefined) {
+        reaper = null;
+        if (process.platform === "win32")
+            return;
+        try {
+            const child = spawn("/bin/sh", ["-c", REAPER_SCRIPT], { cwd: "/", detached: true, stdio: ["pipe", "ignore", "ignore"] });
+            child.once("error", () => (reaper = null));
+            child.stdin?.on("error", () => (reaper = null));
+            // Neither the helper nor its pipe keeps this process running.
+            child.unref();
+            child.stdin?.unref?.();
+            reaper = child;
+        }
+        catch {
+            return;
+        }
+    }
+    reaper?.stdin?.write(`${line}\n`);
+}
+/**
+ * Kills `pid` if this process dies, until the returned function is called
+ * (when the process is known to have exited: its pid may be reused).
+ */
+export function reap(pid) {
+    tellReaper(`+${pid}`);
+    return () => tellReaper(`-${pid}`);
+}
+/**
+ * Kills `pid`, which isn't this process's child (a runtime's own child in
+ * its own process group), if this process dies while `owner` runs.
+ */
+export function reapWith(pid, owner) {
+    if (owner.exitCode !== null || owner.signalCode !== null)
+        return;
+    owner.once("exit", reap(pid));
+}
+/** `pid`'s children whose command line matches `pattern` (pgrep's -f). */
+export function childPids(pid, pattern) {
+    try {
+        const args = ["-P", String(pid), ...(pattern === undefined ? [] : ["-f", pattern])];
+        return execFileSync("pgrep", args, { encoding: "utf8" }).split(/\s+/).filter(Boolean).map(Number);
+    }
+    catch {
+        return []; // none, or no pgrep
+    }
+}
 /**
  * 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.
+ * and do whatever the child's own exit listener would have done. If this
+ * process is SIGKILLed, the helper kills `child` and removes `dir`.
  */
-export function killOnExit(child, cleanup = () => child.kill("SIGKILL")) {
+export function killOnExit(child, cleanup = () => child.kill("SIGKILL"), { dir } = {}) {
     if (!hooked) {
         hooked = true;
         process.on("exit", runAll);
@@ -29,4 +107,8 @@ export function killOnExit(child, cleanup = () => child.kill("SIGKILL")) {
         return;
     cleanups.add(cleanup);
     child.once("exit", () => cleanups.delete(cleanup));
+    if (dir !== undefined)
+        tellReaper(`d${dir}`);
+    if (child.pid !== undefined)
+        reapWith(child.pid, child);
 }

package/dist/deno-types.d.ts

@@ -0,0 +1,30 @@
+export type DenoResolution = {
+    kind: "npm";
+    dir: string;
+    subpath: string;
+} | {
+    kind: "remote";
+    path: string;
+};
+export type RunDeno = (args: string[]) => {
+    status: number | null;
+    stdout: string;
+};
+export declare class DenoResolver {
+    #private;
+    /** Where remote modules appear to the language service. */
+    readonly root: string;
+    constructor({ deno, config, root }: {
+        deno?: string;
+        config?: string | null;
+        root: string;
+    }, run?: RunDeno);
+    /** The virtual path for a remote module's URL, e.g. <root>/https/jsr.io/@std/path/1.1.6/mod.ts. */
+    pathFor(url: string): string | null;
+    /** The cached file behind a virtual path, if a lookup has found it. */
+    localFile(path: string): string | undefined;
+    /** Where `specifier` resolves for Deno, from what's already in its cache. */
+    lookup(specifier: string): DenoResolution | null;
+}
+/** `deno types`: declarations for the Deno namespace and its web globals. */
+export declare function denoTypes(run?: RunDeno): string | null;

package/dist/deno-types.js

@@ -0,0 +1,93 @@
+// Types for a Deno target's imports (#275). Deno resolves npm:, jsr:, URLs
+// and its project's import map itself and keeps what it fetched in its own
+// cache, so the language service asks it where a specifier went:
+// `deno info --json` over a one-line module importing it. npm packages map
+// to their directory in Deno's npm cache; remote modules (jsr:, https:)
+// are stored under hashed names without an extension, so the language
+// service sees each under a virtual path built from its URL, which keeps
+// relative imports between them working.
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function runDeno(deno) {
+    return (args) => {
+        const result = spawnSync(deno, args, { encoding: "utf8", timeout: 30_000, maxBuffer: 64 * 1024 * 1024 });
+        return { status: result.status, stdout: result.stdout ?? "" };
+    };
+}
+export class DenoResolver {
+    #run;
+    #config;
+    /** Where remote modules appear to the language service. */
+    root;
+    #lookups = new Map();
+    /** Virtual path -> the cached file holding that URL's module. */
+    #remote = new Map();
+    constructor({ deno = "deno", config = null, root }, run = runDeno(deno)) {
+        this.#run = run;
+        this.#config = config;
+        this.root = root;
+    }
+    /** The virtual path for a remote module's URL, e.g. <root>/https/jsr.io/@std/path/1.1.6/mod.ts. */
+    pathFor(url) {
+        const m = /^(https?):\/\/(.+)$/.exec(url);
+        return m ? join(this.root, m[1], m[2]) : null;
+    }
+    /** The cached file behind a virtual path, if a lookup has found it. */
+    localFile(path) {
+        return this.#remote.get(path);
+    }
+    /** Where `specifier` resolves for Deno, from what's already in its cache. */
+    lookup(specifier) {
+        if (this.#lookups.has(specifier))
+            return this.#lookups.get(specifier) ?? null;
+        const resolution = this.#lookup(specifier);
+        this.#lookups.set(specifier, resolution);
+        return resolution;
+    }
+    #lookup(specifier) {
+        const dir = mkdtempSync(join(tmpdir(), "cdpk-deno-info-"));
+        try {
+            const entry = join(dir, "entry.ts");
+            writeFileSync(entry, `import ${JSON.stringify(specifier)};\n`);
+            const flags = this.#config === null ? ["--node-modules-dir=none"] : ["--config", this.#config];
+            const result = this.#run(["info", "--json", "--no-lock", ...flags, entry]);
+            if (result.status !== 0)
+                return null;
+            return this.#read(JSON.parse(result.stdout));
+        }
+        catch {
+            return null;
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    #read(info) {
+        for (const mod of info.modules) {
+            const path = mod.local === undefined ? null : this.pathFor(mod.specifier);
+            if (path !== null && mod.local !== undefined)
+                this.#remote.set(path, mod.local);
+        }
+        const root = info.modules.find((m) => m.specifier === info.roots[0]);
+        const dep = root?.dependencies?.[0];
+        let target = dep?.code?.specifier ?? dep?.specifier;
+        if (target === undefined)
+            return null;
+        for (let i = 0; i < 10 && info.redirects[target] !== undefined; i++)
+            target = info.redirects[target];
+        const npm = /^npm:\/?((?:@[^/]+\/)?[^/@]+@[^/]+)(\/.*)?$/.exec(target);
+        if (npm) {
+            const dir = info.npmPackages[npm[1]]?.localPath;
+            return dir === undefined ? null : { kind: "npm", dir, subpath: npm[2] ?? "" };
+        }
+        const path = this.pathFor(target);
+        return path !== null && this.#remote.has(path) ? { kind: "remote", path } : null;
+    }
+}
+/** `deno types`: declarations for the Deno namespace and its web globals. */
+export function denoTypes(run = runDeno("deno")) {
+    const result = run(["types"]);
+    return result.status === 0 ? result.stdout : null;
+}

package/dist/kernel.d.ts

@@ -1,4 +1,5 @@
 import { type RuntimeName } from "./target.ts";
+import { type TypeStripper, type TypeStripperName } from "./transform.ts";
 export interface ConnectionInfo {
     ip: string;
     key: string;
@@ -14,8 +15,13 @@ export declare function parseConnectionInfo(json: string): ConnectionInfo;
 export declare class Kernel {
     #private;
     constructor(conn: ConnectionInfo, runtime: RuntimeName, options?: {
-        denoCompat?: boolean; /** Defaults to the process cwd, which Jupyter sets. */
+        denoCompat?: boolean;
+        /** Defaults to the process cwd, which Jupyter sets. */
         notebookDir?: string;
+        /** What strips cells' types; esbuild by default (#238). */
+        typeStrip?: TypeStripperName | TypeStripper;
+        /** Typed completion from TypeScript's language service; on by default (#273). */
+        languageService?: boolean;
     });
     run(): Promise<void>;
 }