@tlockney/cdp-kernel 0.1.1 → 0.3.0

package/dist/celld-target.d.ts

@@ -0,0 +1,39 @@
+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. */
+export declare const PROJECT_KEYS: string[];
+/**
+ * The celld config for the driver: the project's bindings (or none), the
+ * pre-built driver as its one module, and the kernel's token and import.meta
+ * as vars, which the driver hides from cells' `env`.
+ */
+export declare function celldConfig(project: CdpParams | null, { token, meta }: {
+    token: string;
+    meta: {
+        url: string;
+        dirname: string;
+        filename: string;
+    };
+}): CdpParams;
+/**
+ * celld's installer puts it in ~/.local/bin, which a Jupyter server's PATH
+ * often lacks, so look there before falling back to PATH.
+ */
+export declare function findCelld(home?: string): string;
+/** The version in `celld --version`'s output ("celld X.Y.Z"). */
+export declare function celldVersionOf(output: string): string;
+/** The driver, and a project's main, as the single module celld runs. */
+export declare function bundleDriver(runtime: string, projectMain?: string, define?: {
+    [name: string]: string;
+}): Promise<string>;
+/** A free loopback port: celld dev needs a number, and rejects 0. */
+export declare function freePort(): Promise<number>;
+/**
+ * A celld target. In a celld project its bindings come along; a project
+ * that can't load is reported in the first cell, and the driver runs alone.
+ */
+export declare function launchCelld(events: TargetEvents, options?: {
+    cwd?: string;
+    executable?: string;
+}): Promise<WorkerdTarget>;

package/dist/celld-target.js

@@ -0,0 +1,274 @@
+// The celld target (#25). celld (denoland/celld) runs Workers and Durable
+// Objects on its own storage; like workerd it has no I/O outside a request,
+// so it runs the same driver Worker (runtime/workerd-worker.mjs) over the
+// same WebSocket session (src/workerd-target.ts). The differences:
+//   - celld has no UnsafeEval binding and doesn't need one: the driver uses
+//     a plain global eval.
+//   - It listens only on TCP, so the session is a loopback WebSocket opened
+//     with a per-launch token (in the query string: the host's built-in
+//     WebSocket can't set headers).
+//   - It takes one module, so the host bundles the driver (and a project's
+//     main) with esbuild and hands celld the result with `no_bundle`.
+// In a celld project (a wrangler.jsonc or wrangler.json at or above the
+// notebook), its bindings come along: the generated config copies them, and
+// lives in the project's .celld/cdp-kernel, so state stays beside, not in,
+// `celld dev`'s own.
+import process from "node:process";
+import { execFileSync, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { build } from "esbuild";
+import { parseJsonc } from "./deno-config.js";
+import { runtimeDir } from "./package.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. */
+export const PROJECT_KEYS = [
+    "compatibility_date",
+    "compatibility_flags",
+    "durable_objects",
+    "migrations",
+    "vars",
+    "d1_databases",
+    "kv_namespaces",
+    "r2_buckets",
+    "queues",
+    "workflows",
+    "services",
+    "worker_loaders",
+];
+/**
+ * The celld config for the driver: the project's bindings (or none), the
+ * pre-built driver as its one module, and the kernel's token and import.meta
+ * as vars, which the driver hides from cells' `env`.
+ */
+export function celldConfig(project, { token, meta }) {
+    const config = { name: "cdpk", main: "driver.mjs", no_bundle: true, compatibility_date: "2026-09-01" };
+    for (const key of PROJECT_KEYS)
+        if (project && project[key] !== undefined)
+            config[key] = project[key];
+    const vars = project && typeof project.vars === "object" && project.vars !== null ? project.vars : {};
+    config.vars = { ...vars, TOKEN: token, META: JSON.stringify(meta) };
+    return config;
+}
+/**
+ * celld's installer puts it in ~/.local/bin, which a Jupyter server's PATH
+ * often lacks, so look there before falling back to PATH.
+ */
+export function findCelld(home = homedir()) {
+    const installed = join(home, ".local", "bin", "celld");
+    return existsSync(installed) ? installed : "celld";
+}
+/** The version in `celld --version`'s output ("celld X.Y.Z"). */
+export function celldVersionOf(output) {
+    return /\bcelld (\d+\.\d+\.\d+\S*)/.exec(output)?.[1] ?? "";
+}
+/** The driver, and a project's main, as the single module celld runs. */
+export async function bundleDriver(runtime, projectMain, define = {}) {
+    const driver = JSON.stringify(join(runtime, "workerd-worker.mjs"));
+    const contents = projectMain === undefined ? `export { default } from ${driver};\n` : [
+        `import * as project from ${JSON.stringify(projectMain)};`,
+        `export * from ${JSON.stringify(projectMain)};`,
+        `export { default } from ${driver};`,
+        "globalThis.worker = project.default;",
+        "",
+    ].join("\n");
+    const result = await build({
+        stdin: { contents, resolveDir: runtime, loader: "js" },
+        bundle: true,
+        write: false,
+        format: "esm",
+        platform: "browser",
+        conditions: ["workerd", "worker", "browser"],
+        mainFields: ["browser", "module", "main"],
+        alias: builtinAliases(),
+        external: ["node:*", "cloudflare:*"],
+        define,
+        target: "es2024",
+        logLevel: "silent",
+    });
+    return result.outputFiles[0].text;
+}
+/** A free loopback port: celld dev needs a number, and rejects 0. */
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+/** The host's built-in WebSocket as the session channel. */
+function channelOf(ws) {
+    return {
+        send: (text) => ws.send(text),
+        onMessage: (listener) => ws.addEventListener("message", (event) => listener(String(event.data))),
+        onClose: (listener) => ws.addEventListener("close", () => listener()),
+        close() {
+            try {
+                ws.close();
+            }
+            catch {
+                // Already closed.
+            }
+        },
+    };
+}
+/** 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. */
+function killTree(child) {
+    for (const pid of childPids(child.pid ?? -1)) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // Gone already.
+        }
+    }
+    child.kill("SIGKILL");
+}
+/** The driver on `celld dev`. */
+class CelldHost {
+    runtime;
+    project;
+    channel;
+    #child;
+    constructor(child, channel, runtime, project) {
+        this.#child = child;
+        this.channel = channel;
+        this.runtime = runtime;
+        this.project = project;
+    }
+    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);
+        let project = null;
+        let dir;
+        if (projectConfig !== null) {
+            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)
+                throw new Error(`${projectConfig} is not an object`);
+            project = parsed;
+            dir = join(dirname(projectConfig), ".celld", "cdp-kernel");
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        else {
+            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 token = randomBytes(32).toString("hex");
+        // 0600: the config carries this launch's token.
+        writeFileSync(join(dir, "driver.mjs"), await bundleDriver(source, main, define));
+        writeFileSync(join(dir, "wrangler.jsonc"), JSON.stringify(celldConfig(project, { token, meta: cellMeta(cwd) }), null, 2), {
+            mode: 0o600,
+        });
+        const port = await freePort();
+        const child = spawn(celld, ["dev", dir, "--host", "127.0.0.1", "--port", String(port), "--no-watch"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.once("exit", () => {
+            if (projectConfig === null)
+                rmSync(dir, { recursive: true, force: true });
+            else
+                for (const name of ["driver.mjs", "wrangler.jsonc"])
+                    rmSync(join(dir, name), { force: true });
+        });
+        // Cell output is captured in the driver; celld's own lines go to the
+        // server log.
+        let early = "";
+        const log = (chunk) => {
+            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}`)));
+        });
+        exited.catch(() => { });
+        const url = `127.0.0.1:${port}/?token=${token}`;
+        const ready = (async () => {
+            // The driver answers 426 to a plain request once celld serves it.
+            for (let i = 0;; i++) {
+                const status = await fetch(`http://${url}`).then((r) => r.status, () => 0);
+                if (status === 426)
+                    break;
+                if (i >= 600)
+                    throw new Error(`celld never served the driver (last status ${status}):\n${early}`);
+                await new Promise((r) => setTimeout(r, 50));
+            }
+            const ws = new WebSocket(`ws://${url}`);
+            await new Promise((resolve, reject) => {
+                ws.addEventListener("open", () => resolve(), { once: true });
+                ws.addEventListener("error", () => reject(new Error("the session WebSocket didn't open")), { once: true });
+            });
+            return channelOf(ws);
+        })();
+        try {
+            return new CelldHost(child, await Promise.race([ready, exited]), `celld ${version}`.trim(), projectConfig ?? undefined);
+        }
+        catch (err) {
+            killTree(child);
+            throw err;
+        }
+    }
+    /**
+     * celld dev's graceful stop waits for the app, which a busy cell never
+     * lets go, and its node runs in its own process group. So a forced stop
+     * kills the node, then the supervisor; a graceful one falls back to that.
+     */
+    stop(now) {
+        if (now)
+            return killTree(this.#child);
+        this.#child.kill("SIGTERM");
+        setTimeout(() => {
+            if (this.#child.exitCode === null && this.#child.signalCode === null)
+                killTree(this.#child);
+        }, 3000).unref();
+    }
+    onExit(listener) {
+        this.#child.once("exit", listener);
+    }
+}
+/**
+ * A celld target. In a celld project its bindings come along; a project
+ * that can't load is reported in the first cell, and the driver runs alone.
+ */
+export async function launchCelld(events, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const project = findWranglerConfig(cwd);
+    let host = null;
+    let notice;
+    if (project !== null) {
+        try {
+            host = await CelldHost.start(cwd, project, options.executable);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            notice = `[cdp-kernel] couldn't load the celld project at ${project}: ${reason}; running without its bindings`;
+        }
+    }
+    host ??= await CelldHost.start(cwd, null, options.executable);
+    return await WorkerdTarget.open(host, cwd, events, "celld", notice);
+}

package/dist/deno-config.d.ts

@@ -0,0 +1,20 @@
+import type { CellTransformOptions, JsxOptions } from "./transform.ts";
+export type { CellTransformOptions, JsxOptions };
+/** Deno looks for these, in this order, in each directory. */
+export declare const DENO_CONFIG_NAMES: readonly ["deno.json", "deno.jsonc"];
+/** The nearest deno.json(c) at or above `startDir`, as Deno resolves it. */
+export declare function findDenoConfig(startDir: string): string | null;
+/**
+ * Parses JSON with comments and trailing commas (deno.jsonc). Comments and
+ * trailing commas are removed outside strings, then the rest goes to
+ * JSON.parse, so errors are JSON.parse's SyntaxErrors.
+ */
+export declare function parseJsonc(text: string): unknown;
+/** Maps a deno.json's compilerOptions onto the cell transformer's options. */
+export declare function transformOptionsFromConfig(config: unknown): CellTransformOptions;
+export interface DenoProject {
+    configPath: string;
+    transform: CellTransformOptions;
+}
+/** The Deno project a notebook directory belongs to, if any. */
+export declare function loadDenoProject(notebookDir: string): DenoProject | null;

package/dist/deno-config.js

@@ -0,0 +1,130 @@
+// A notebook's Deno project config, for Deno targets.
+//
+// `deno jupyter` honours the project's deno.json: its import map,
+// nodeModulesDir and JSX/decorator compilerOptions. Here those come from two
+// places: the target runtime gets `--config <path>` (import map, npm
+// resolution), and the host's cell transformer gets the compiler options,
+// because cells are transpiled by esbuild in the host, not by Deno.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Deno looks for these, in this order, in each directory. */
+export const DENO_CONFIG_NAMES = ["deno.json", "deno.jsonc"];
+/** The nearest deno.json(c) at or above `startDir`, as Deno resolves it. */
+export function findDenoConfig(startDir) {
+    for (let dir = startDir;; dir = dirname(dir)) {
+        for (const name of DENO_CONFIG_NAMES) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        if (dirname(dir) === dir)
+            return null;
+    }
+}
+/**
+ * Parses JSON with comments and trailing commas (deno.jsonc). Comments and
+ * trailing commas are removed outside strings, then the rest goes to
+ * JSON.parse, so errors are JSON.parse's SyntaxErrors.
+ */
+export function parseJsonc(text) {
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            const start = i++;
+            while (i < text.length && text[i] !== '"')
+                i += text[i] === "\\" ? 2 : 1;
+            out += text.slice(start, ++i);
+        }
+        else if (ch === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+        }
+        else if (ch === "/" && text[i + 1] === "*") {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? text.length : end + 2;
+        }
+        else {
+            out += ch;
+            i++;
+        }
+    }
+    return JSON.parse(stripTrailingCommas(out));
+}
+/** Drops commas that only whitespace separates from a closing } or ]. */
+function stripTrailingCommas(json) {
+    // Walks strings intact for the same reason as above: a string can
+    // legitimately contain ",}".
+    let out = "";
+    for (let i = 0; i < json.length; i++) {
+        const ch = json[i];
+        if (ch === '"') {
+            const start = i++;
+            while (i < json.length && json[i] !== '"')
+                i += json[i] === "\\" ? 2 : 1;
+            out += json.slice(start, i + 1);
+            continue;
+        }
+        if (ch === ",") {
+            let j = i + 1;
+            while (j < json.length && /\s/.test(json[j]))
+                j++;
+            if (json[j] === "}" || json[j] === "]")
+                continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+function stringField(obj, key) {
+    const value = obj[key];
+    return typeof value === "string" ? value : undefined;
+}
+/** Maps a deno.json's compilerOptions onto the cell transformer's options. */
+export function transformOptionsFromConfig(config) {
+    if (typeof config !== "object" || config === null)
+        return {};
+    const compilerOptions = config.compilerOptions;
+    if (typeof compilerOptions !== "object" || compilerOptions === null)
+        return {};
+    const opts = compilerOptions;
+    const result = {};
+    const jsx = stringField(opts, "jsx");
+    if (jsx === "react-jsx" || jsx === "react-jsxdev" || jsx === "precompile") {
+        // precompile is Deno's server-side optimisation of the automatic
+        // runtime; for a notebook cell the automatic runtime is equivalent.
+        const importSource = stringField(opts, "jsxImportSource");
+        result.jsx = { mode: "automatic", development: jsx === "react-jsxdev" };
+        if (importSource !== undefined)
+            result.jsx.importSource = importSource;
+    }
+    else if (jsx === "react") {
+        const factory = stringField(opts, "jsxFactory");
+        const fragment = stringField(opts, "jsxFragmentFactory");
+        const classic = { mode: "classic" };
+        if (factory !== undefined)
+            classic.factory = factory;
+        if (fragment !== undefined)
+            classic.fragment = fragment;
+        result.jsx = classic;
+    }
+    if (opts.experimentalDecorators === true)
+        result.experimentalDecorators = true;
+    return result;
+}
+/** The Deno project a notebook directory belongs to, if any. */
+export function loadDenoProject(notebookDir) {
+    const configPath = findDenoConfig(notebookDir);
+    if (configPath === null)
+        return null;
+    let config;
+    try {
+        config = parseJsonc(readFileSync(configPath, "utf8"));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`cannot read Deno config ${configPath}: ${reason}`);
+    }
+    return { configPath, transform: transformOptionsFromConfig(config) };
+}

package/dist/globals-deno-compat.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ambient `Deno` namespace for Node notebooks run with `--deno-compat`
+ * (kernelspec `cdp-node-deno`), on top of the `jupyter` globals.
+ *
+ * Opt-in and separate from `./globals` because on a real Deno target, or
+ * with Deno's own types loaded, `Deno` is already declared.
+ *
+ * @module
+ */
+import type { DenoShim } from "../runtime/deno-compat.mjs";
+import type { JupyterNamespace } from "./globals.ts";
+export type { DenoShim };
+declare global {
+    /**
+     * The subset of Deno's namespace the compatibility shim implements on Node.
+     * APIs outside it (`Deno.serve`, `Deno.Command`, ...) are absent at runtime.
+     */
+    var Deno: Omit<DenoShim, "jupyter"> & {
+        jupyter: JupyterNamespace;
+    };
+}

package/dist/globals-deno-compat.js

@@ -0,0 +1,10 @@
+/**
+ * Ambient `Deno` namespace for Node notebooks run with `--deno-compat`
+ * (kernelspec `cdp-node-deno`), on top of the `jupyter` globals.
+ *
+ * Opt-in and separate from `./globals` because on a real Deno target, or
+ * with Deno's own types loaded, `Deno` is already declared.
+ *
+ * @module
+ */
+export {};

package/dist/globals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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).
+ *
+ * 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
+ * only `jupyter.$display` carries the precise type.
+ *
+ * @module
+ */
+import type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle } from "../runtime/display.mjs";
+export type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle };
+/** Options for the notebook's `prompt()`. */
+export interface PromptOptions {
+    /** Ask the frontend to hide what is typed. */
+    password?: boolean;
+}
+declare global {
+    /**
+     * The notebook display API: `display`, `md`/`html`/`svg` templates,
+     * `image`, `format`, `broadcast`. The same object as `Deno.jupyter` in
+     * `deno jupyter`.
+     */
+    var jupyter: JupyterNamespace;
+    /**
+     * Ask the frontend for a line of input over the Jupyter stdin channel.
+     * Returns `null` when the frontend didn't allow input for this cell.
+     */
+    function prompt(message?: string, defaultValue?: string, options?: PromptOptions): string | null;
+    /** Ask a yes/no question over the Jupyter stdin channel. */
+    function confirm(message?: string): boolean;
+}

package/dist/globals.js

@@ -0,0 +1,15 @@
+/**
+ * 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).
+ *
+ * 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
+ * only `jupyter.$display` carries the precise type.
+ *
+ * @module
+ */
+export {};

package/dist/kernel.d.ts

@@ -14,7 +14,8 @@ export declare function parseConnectionInfo(json: string): ConnectionInfo;
 export declare class Kernel {
     #private;
     constructor(conn: ConnectionInfo, runtime: RuntimeName, options?: {
-        denoCompat?: boolean;
+        denoCompat?: boolean; /** Defaults to the process cwd, which Jupyter sets. */
+        notebookDir?: string;
     });
     run(): Promise<void>;
 }