@tlockney/cdp-kernel 0.2.0 → 0.4.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/debugger.d.ts

@@ -0,0 +1,42 @@
+import type { CdpParams, 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 {
+    send(method: string, params?: CdpParams): Promise<CdpParams>;
+    on(method: string, listener: (params: CdpParams) => void): void;
+    /** The execution context cells run in. */
+    readonly contextId: number;
+    /** Enumerable globals the runtime had before any cell ran. */
+    readonly baselineGlobals: ReadonlySet<string>;
+}
+export type DapMessage = {
+    [key: string]: unknown;
+};
+/** ipykernel's seed, so a kernel switch doesn't move JupyterLab's breakpoints. */
+export declare const HASH_SEED = 3339675911;
+export declare const THREAD_ID = 1;
+/** A DAP value string for a CDP RemoteObject. */
+export declare function describeRemote(object: RemoteObject): string;
+export declare class Debugger {
+    #private;
+    readonly prefix: string;
+    readonly suffix = ".ts";
+    constructor(emit: (event: DapMessage) => void, transformOptions?: () => CellTransformOptions);
+    get started(): boolean;
+    get stopped(): boolean;
+    /** A cell's path, as JupyterLab computes it for the same code. */
+    pathFor(code: string): string;
+    /**
+     * The target to debug: called with each target the kernel launches. A
+     * restarted target gets the session's breakpoints again.
+     */
+    attachTarget(channel: DebugChannel | null): Promise<void>;
+    /**
+     * The script for a cell while debugging: transformed with its line map
+     * kept, and named for its path. `source` is what actually runs (the cell,
+     * or the cell wrapped as an object literal); the path comes from `code`,
+     * the cell as the frontend sent it.
+     */
+    cellScript(code: string, source: string): string;
+    handle(request: DapMessage): Promise<DapMessage>;
+}