@tlockney/cdp-kernel 0.2.0 → 0.3.0

package/dist/transform.js

@@ -16,7 +16,7 @@
 // callback was not specified").
 import { transformSync } from "esbuild";
 import { parse } from "acorn";
-import { full } from "acorn-walk";
+import { full, recursive } from "acorn-walk";
 export const SHIM = "__cdpk";
 // Each cell first yields one macrotask. User code then runs as an ordinary
 // task instead of nested inside the inspector's dispatch of Runtime.evaluate,
@@ -80,11 +80,9 @@ function rewriteImport(code, node, index) {
     });
     return `var ${ns} = ${load}; var ${bindings.join(", ")};`;
 }
-/** Rewrites module-only syntax in plain JavaScript into script syntax. */
-export function rewriteModuleSyntax(js) {
-    let program;
+function parseCell(js) {
     try {
-        program = parse(js, {
+        return parse(js, {
             ecmaVersion: "latest",
             sourceType: "module",
             allowAwaitOutsideFunction: true,
@@ -94,6 +92,10 @@ export function rewriteModuleSyntax(js) {
     catch (err) {
         throw new CellSyntaxError(err instanceof Error ? err.message : String(err));
     }
+}
+/** Rewrites module-only syntax in plain JavaScript into script syntax. */
+export function rewriteModuleSyntax(js) {
+    const program = parseCell(js);
     const edits = [];
     let importIndex = 0;
     full(program, (node) => {
@@ -136,15 +138,142 @@ export function rewriteModuleSyntax(js) {
     });
     // Nested edits can't occur (imports/exports are top level, import()'s
     // keyword edit doesn't overlap its arguments), so apply back to front.
-    edits.sort((a, b) => b.start - a.start);
+    return applyEdits(js, edits);
+}
+function applyEdits(js, edits) {
+    // Back to front; at a shared start, a replacement goes before an insertion.
+    edits.sort((a, b) => b.start - a.start || b.end - a.end);
     let out = js;
     for (const edit of edits)
         out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
     return out;
 }
+/** Adds the names a binding pattern declares. */
+function patternNames(pattern, names) {
+    switch (pattern.type) {
+        case "Identifier":
+            names.add(pattern.name);
+            break;
+        case "ObjectPattern":
+            for (const prop of pattern.properties)
+                patternNames(prop.type === "Property" ? prop.value : prop, names);
+            break;
+        case "ArrayPattern":
+            for (const element of pattern.elements)
+                if (element)
+                    patternNames(element, names);
+            break;
+        case "RestElement":
+            patternNames(pattern.argument, names);
+            break;
+        case "AssignmentPattern":
+            patternNames(pattern.left, names);
+            break;
+    }
+}
+/**
+ * Makes a cell's declarations global without replMode, the tslab/IJavascript
+ * technique: the cell runs inside an async function (for top-level await),
+ * and every name it declares at the top level is declared with `var` in the
+ * surrounding script, which a global-code eval turns into a property of
+ * globalThis. Inside the function the declarations become assignments to
+ * those globals:
+ *   const { a } = o; class K {}  ->  var a, K;
+ *                                    (async () => { ({ a } = o); K = class K {}; })()
+ * So later cells, and closures from this one, all see one binding. A `var`
+ * in a top-level block or loop head is global too, as in a script; block
+ * scoped and function-local declarations stay where they are. Functions
+ * keep their in-cell hoisting and are copied to globalThis on entry.
+ *
+ * A trailing expression statement becomes `return [value]`; the box keeps a
+ * promise from being awaited, so the cell's result is the promise itself, as
+ * in Deno.
+ */
+function hoistForEval(js) {
+    const program = parseCell(js);
+    const names = new Set();
+    const functions = [];
+    const edits = [];
+    const src = (node) => js.slice(node.start, node.end);
+    const replace = (node, text) => edits.push({ start: node.start, end: node.end, text });
+    // A declarator without an initializer resets the name, except under var,
+    // where redeclaring keeps the value.
+    const assignments = (decl) => decl.declarations.flatMap((d) => {
+        patternNames(d.id, names);
+        if (d.init)
+            return [`${src(d.id)} = ${src(d.init)}`];
+        return decl.kind === "var" ? [] : [`${src(d.id)} = undefined`];
+    });
+    const statement = (decl) => {
+        const parts = assignments(decl);
+        replace(decl, parts.length > 0 ? `(${parts.join(", ")});` : ";");
+    };
+    const isVar = (node) => node?.type === "VariableDeclaration" && node.kind === "var";
+    const loopHead = (left) => {
+        if (!isVar(left))
+            return;
+        const id = left.declarations[0].id;
+        patternNames(id, names);
+        replace(left, src(id));
+    };
+    // Expressions can't hold statements outside a function or class, so only
+    // statement bodies are walked.
+    const nestedVars = (node) => recursive(node, null, {
+        Function() { },
+        Class() { },
+        VariableDeclaration(decl) {
+            if (decl.kind === "var")
+                statement(decl);
+        },
+        ForStatement(loop, state, walk) {
+            if (isVar(loop.init))
+                replace(loop.init, assignments(loop.init).join(", "));
+            walk(loop.body, state);
+        },
+        ForInStatement(loop, state, walk) {
+            loopHead(loop.left);
+            walk(loop.body, state);
+        },
+        ForOfStatement(loop, state, walk) {
+            loopHead(loop.left);
+            walk(loop.body, state);
+        },
+    });
+    program.body.forEach((stmt, i) => {
+        if (stmt.type === "VariableDeclaration" && (stmt.kind === "var" || stmt.kind === "let" || stmt.kind === "const")) {
+            statement(stmt);
+        }
+        else if (stmt.type === "FunctionDeclaration") {
+            names.add(stmt.id.name);
+            functions.push(stmt.id.name);
+        }
+        else if (stmt.type === "ClassDeclaration") {
+            names.add(stmt.id.name);
+            edits.push({ start: stmt.start, end: stmt.start, text: `${stmt.id.name} = ` });
+            edits.push({ start: stmt.end, end: stmt.end, text: ";" });
+        }
+        else if (stmt.type === "ExpressionStatement" && i === program.body.length - 1) {
+            replace(stmt, `return [${src(stmt.expression)}];`);
+        }
+        else {
+            nestedVars(stmt);
+        }
+    });
+    const declare = names.size > 0 ? `var ${[...names].join(", ")};\n` : "";
+    const publish = functions.map((name) => ` globalThis.${name} = ${name};`).join("");
+    return `${declare}(async () => { 'use strict';${publish}\n${applyEdits(js, edits)}\n})()`;
+}
 export function transformCell(code, options = {}) {
     return PRELUDE + rewriteModuleSyntax(stripTypes(code, options));
 }
+/**
+ * Like transformCell, for a target that evaluates cells itself, as global
+ * code (an indirect eval), instead of through the inspector's replMode: see
+ * hoistForEval. The script's value is a promise of the boxed result.
+ */
+export function transformCellForEval(code, options = {}) {
+    return hoistForEval(rewriteModuleSyntax(stripTypes(code, options)));
+}
 /**
  * Deno treats a cell like `{ "a": 1 }` as an object literal rather than a
  * block, as browser consoles do. Returns the wrapped form to try first, or

package/dist/workerd-target.d.ts

@@ -0,0 +1,123 @@
+import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+import { transformCellForEval } from "./transform.ts";
+import { type KernelTarget, type TargetEvents } from "./target.ts";
+import { type WsChannel } from "./ws-client.ts";
+/** The driver Worker's modules; the first is its main module. */
+export declare const WORKER_MODULES: string[];
+/** See BunTarget: how long an interrupted cell has to show it isn't busy. */
+export declare const INTERRUPT_GRACE_MS = 500;
+export declare function restartNote(runtime: string): string;
+export declare const RESTART_NOTE: string;
+export declare function workerdConfig({ socket, compatibilityDate }: {
+    socket: string;
+    compatibilityDate: string;
+}): string;
+/**
+ * A Workers project has workerd in its node_modules (wrangler and miniflare
+ * depend on it), so look there first, from the notebook's directory up;
+ * otherwise use the one on PATH.
+ */
+export declare function findWorkerd(cwd: string): string;
+/** "workerd 2026-10-15" -> "2026-10-15": the newest date it supports. */
+export declare function compatibilityDateOf(versionOutput: string): string;
+/** The literal specifiers a transformed cell imports, in order. */
+export declare function importSpecifiers(script: string): string[];
+/**
+ * Bundles `specifier`, as imported from `cwd`, into global code whose value
+ * is a promise of the module's namespace. npm: and jsr: install into the
+ * npm cache, as on a Node target. Builtins stay external and are handed to
+ * the bundle as `require` (workerd-worker.mjs's requireFor). A specifier
+ * that can't be bundled becomes code that throws when imported, so the
+ * error appears in the cell.
+ */
+export declare function bundleModule(specifier: string, cwd: string): Promise<string>;
+/** What import.meta says in a cell: the notebook's directory, not workerd's. */
+export declare function cellMeta(cwd: string): {
+    url: string;
+    dirname: string;
+    filename: string;
+};
+/**
+ * How the target reaches its driver Worker: a workerd of its own
+ * (RawWorkerd, below), or a Workers project's Miniflare
+ * (src/workers-project.ts), which adds the project's bindings.
+ */
+export interface WorkerHost {
+    /** The runtime's name for the banner: workerd's date, or Miniflare's version. */
+    readonly runtime: string;
+    /** The wrangler config whose bindings the driver has, if any. */
+    readonly project?: string;
+    /** The open session with the driver. */
+    readonly channel: WsChannel;
+    /** Stops the runtime; `now` even while a cell is busy. */
+    stop(now: boolean): void;
+    onExit(listener: (code: number | null) => void): void;
+}
+/** The driver on a workerd of its own, behind a Unix socket. */
+export declare class RawWorkerd implements WorkerHost {
+    #private;
+    readonly runtime: string;
+    readonly channel: WsChannel;
+    private constructor();
+    static start(cwd: string, executable?: string): Promise<RawWorkerd>;
+    stop(now: boolean): void;
+    onExit(listener: (code: number | null) => void): void;
+}
+/** A runtime that runs the driver Worker: workerd, or celld (src/celld-target.ts). */
+export type WorkersRuntime = "workerd" | "celld";
+export declare class WorkerdTarget implements KernelTarget {
+    #private;
+    readonly runtime: WorkersRuntime;
+    readonly versions: {
+        runtime: string;
+        engine: string;
+    };
+    notice: string | undefined;
+    readonly transform: typeof transformCellForEval;
+    private constructor();
+    /**
+     * In a Workers project (a wrangler config at or above `cwd`), the
+     * project's own Miniflare runs the driver with the project's bindings;
+     * otherwise a workerd of its own does (#26).
+     */
+    static launch(events: TargetEvents, options?: {
+        cwd?: string;
+        executable?: string;
+    }): Promise<WorkerdTarget>;
+    /**
+     * A target over a started host's session. `notice` (a project that
+     * failed to load) is replaced by the bindings when the host has a project.
+     */
+    static open(host: WorkerHost, cwd: string, events: TargetEvents, runtime: WorkersRuntime, notice?: string): Promise<WorkerdTarget>;
+    evaluate(script: string): Promise<EvaluateResult>;
+    /**
+     * A cell that's waiting on something leaves the driver free: it answers a
+     * ping, and the cell is abandoned with the session intact (its pending
+     * work still runs, as on Bun). A busy cell can't be reached, so workerd is
+     * stopped and restarts on the next cell.
+     */
+    interrupt(): Promise<void>;
+    /** Output arrives on the session before the reply it precedes. */
+    flush(): Promise<void>;
+    broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
+    dispatchComm(msgType: string, content: CdpParams, metadata: CdpParams, buffers: Uint8Array[]): Promise<{
+        handled: boolean;
+    } | {
+        error: {
+            name: string;
+            message: string;
+            stack: string;
+        };
+    }>;
+    describeError(exception: RemoteObject): Promise<{
+        name: string;
+        message: string;
+        stack: string;
+    }>;
+    propertyNames(expression: string): Promise<string[]>;
+    /** None: top-level declarations here are properties of globalThis. */
+    lexicalNames(): Promise<string[]>;
+    /** Never asked for: prompt() in workerd answers null without asking. */
+    replyInput(): void;
+    kill(): void;
+}