@tlockney/cdp-kernel 0.2.0 → 0.4.0

package/dist/target.js

@@ -6,7 +6,7 @@ import process from "node:process";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
 import { asEvaluateResult, CdpAbandoned, CdpSession } from "./cdp.js";
-import { SHIM } from "./transform.js";
+import { SHIM, transformCell } from "./transform.js";
 import { hostRuntime, isInsideNodeModules, runtimeDir } from "./package.js";
 const BINDING = "__cdpk_send";
 const MARKER_RE = /\x1b\[cdpk:(\d+)(m?)\]\x1b/;
@@ -41,7 +41,7 @@ export function launchCommand(runtime, bootstrap, { executable, denoConfig } = {
     const node = hostRuntime() === "node" ? process.execPath : "node";
     return { cmd: executable ?? node, args: [...inspect, bootstrap] };
 }
-function isTargetMessage(value) {
+export function isTargetMessage(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const kind = value.kind;
@@ -140,7 +140,7 @@ export class PipeDemux {
     }
 }
 /** Promises keyed by barrier number, resolvable before or after first use. */
-class Gates {
+export class Gates {
     #map = new Map();
     #entry(n) {
         let entry = this.#map.get(n);
@@ -169,6 +169,7 @@ export class Interrupted extends Error {
 }
 export class Target {
     runtime;
+    transform = transformCell;
     #child;
     #shell;
     #control;
@@ -178,6 +179,8 @@ export class Target {
     #contextId;
     #messages = Promise.resolve();
     #interrupted = false;
+    #paused = false;
+    #baselineGlobals = new Set();
     versions;
     constructor(runtime, child, shell, control, stdout, stderr, gates, contextId, versions) {
         this.runtime = runtime;
@@ -253,7 +256,7 @@ export class Target {
         await shell.send("Runtime.enable");
         await shell.send("Runtime.addBinding", { name: BINDING });
         const contextId = await contextReady;
-        const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", v8: "" });
+        const target = new Target(runtime, child, shell, control, stdout, stderr, gates, contextId, { runtime: "", engine: "" });
         shell.on("Runtime.bindingCalled", (params) => {
             if (params.name !== BINDING || typeof params.payload !== "string")
                 return;
@@ -268,10 +271,28 @@ export class Target {
                 break;
             await new Promise((r) => setTimeout(r, 25));
         }
-        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, v8: Deno.version.v8 } : { runtime: process.versions.node, v8: process.versions.v8 })`);
+        const versions = await target.#evaluateRaw(`JSON.stringify(typeof Deno !== "undefined" ? { runtime: Deno.version.deno, engine: "V8 " + Deno.version.v8 } : { runtime: process.versions.node, engine: "V8 " + process.versions.v8 })`);
         Object.assign(target.versions, JSON.parse(String(versions.result.value)));
+        // The runtime's own enumerable globals, before any cell: the debugger's
+        // variable views show only what cells added (#18).
+        const globals = asEvaluateResult(await shell.send("Runtime.evaluate", { expression: "Object.keys(globalThis)", contextId, returnByValue: true }));
+        const names = globals.result.value;
+        if (Array.isArray(names))
+            for (const name of names)
+                target.#baselineGlobals.add(String(name));
+        shell.on("Debugger.paused", () => (target.#paused = true));
+        shell.on("Debugger.resumed", () => (target.#paused = false));
         return target;
     }
+    /** The Debugger domain on this target's session, for src/debugger.ts. */
+    get debug() {
+        return {
+            send: (method, params = {}) => this.#shell.send(method, params),
+            on: (method, listener) => this.#shell.on(method, listener),
+            contextId: this.#contextId,
+            baselineGlobals: this.#baselineGlobals,
+        };
+    }
     // Binding messages wait until both pipes have caught up to their marker,
     // and are delivered strictly in order.
     #deliver(msg, events) {
@@ -314,6 +335,9 @@ export class Target {
      */
     async interrupt() {
         this.#interrupted = true;
+        // A paused isolate runs nothing to terminate: let it go first (#18).
+        if (this.#paused)
+            await this.#shell.send("Debugger.resume").catch(() => { });
         await this.#control.send("Runtime.terminateExecution");
         this.#shell.abandonPending();
     }
@@ -380,8 +404,18 @@ export class Target {
         const value = res.result?.value;
         return JSON.parse(typeof value === "string" ? value : '{"name":"Error","message":"","stack":""}');
     }
+    /**
+     * Evaluates without side effects: V8 throws instead of running anything
+     * that would change state (a call, a getter that writes), so completing
+     * or inspecting `obj.` never runs user code (#10).
+     */
+    #evaluatePure(expression) {
+        return this.#shell
+            .send("Runtime.evaluate", { expression, contextId: this.#contextId, replMode: true, throwOnSideEffect: true })
+            .then(asEvaluateResult, () => null);
+    }
     async propertyNames(expression) {
-        const evaluated = await this.#evaluateRaw(`(${expression})`).catch(() => null);
+        const evaluated = await this.#evaluatePure(`(${expression})`);
         const objectId = evaluated?.result.objectId;
         if (!objectId || evaluated?.exceptionDetails)
             return [];
@@ -389,6 +423,23 @@ export class Target {
         const list = props.result;
         return (list ?? []).map((p) => p.name);
     }
+    async inspect(path, detail) {
+        const found = await this.#evaluatePure(path);
+        if (!found || found.exceptionDetails)
+            return null;
+        const value = found.result;
+        const arg = value.objectId
+            ? { objectId: value.objectId }
+            : value.unserializableValue !== undefined
+                ? { unserializableValue: value.unserializableValue }
+                : { value: value.value };
+        const res = await this.callFunctionOn(`function (v, d) { return globalThis.${SHIM}.describeForInspect(v, d); }`, [
+            arg,
+            { value: detail },
+        ]);
+        const text = res.result?.value;
+        return typeof text === "string" ? text : null;
+    }
     async lexicalNames() {
         const res = await this.#shell.send("Runtime.globalLexicalScopeNames", { executionContextId: this.#contextId });
         return res.names ?? [];

package/dist/text.d.ts

@@ -10,5 +10,11 @@ export type IsCompleteReply = {
 export declare function checkIsComplete(code: string): IsCompleteReply;
 /** The dotted expression ending at the cursor, e.g. "Math.fl". */
 export declare function exprAtCursor(code: string, cursor: number): string;
+/**
+ * The dotted name an inspect_request means (#10): the one the cursor is in
+ * or just after, or, right after "name(" while typing a call, that callee.
+ * Null when it isn't a plain path; nothing else is evaluated.
+ */
+export declare function inspectTarget(code: string, cursor: number): string | null;
 export declare function codePointToUtf16Index(str: string, cpOffset: number): number;
 export declare function utf16ToCodePointIndex(str: string, utf16Offset: number): number;

package/dist/text.js

@@ -51,6 +51,23 @@ export function exprAtCursor(code, cursor) {
     const m = /[\w$.]+$/.exec(code.slice(0, cursor));
     return m ? m[0] : "";
 }
+/**
+ * The dotted name an inspect_request means (#10): the one the cursor is in
+ * or just after, or, right after "name(" while typing a call, that callee.
+ * Null when it isn't a plain path; nothing else is evaluated.
+ */
+export function inspectTarget(code, cursor) {
+    let end = cursor;
+    // Inside a call's parentheses with nothing typed yet: "add(|".
+    const before = code.slice(0, cursor);
+    const call = /([\w$.]+)\(\s*$/.exec(before);
+    if (call)
+        end = cursor - (before.length - before.lastIndexOf("(", cursor));
+    const head = /[\w$.]*$/.exec(code.slice(0, end))?.[0] ?? "";
+    const tail = call ? "" : (/^[\w$]*/.exec(code.slice(end))?.[0] ?? "");
+    const path = (head + tail).replace(/\.$/, "");
+    return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(path) ? path : null;
+}
 // Jupyter measures cursor_pos in Unicode codepoints; JS strings index UTF-16
 // code units (denoland/deno#22771).
 export function codePointToUtf16Index(str, cpOffset) {

package/dist/transform.d.ts

@@ -1,3 +1,4 @@
+import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
 export declare class CellSyntaxError extends Error {
     name: string;
@@ -23,6 +24,21 @@ export interface CellTransformOptions {
 /** Rewrites module-only syntax in plain JavaScript into script syntax. */
 export declare function rewriteModuleSyntax(js: string): string;
 export declare function transformCell(code: string, options?: CellTransformOptions): string;
+/**
+ * transformCell, plus the map between the cell's lines and the script's,
+ * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
+ * script's lines are esbuild's, after the prelude's one.
+ */
+export declare function transformCellWithLines(code: string, options?: CellTransformOptions): {
+    script: string;
+    lines: LineMap;
+};
+/**
+ * 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 declare function transformCellForEval(code: string, options?: CellTransformOptions): string;
 /**
  * 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/transform.js

@@ -16,7 +16,8 @@
 // callback was not specified").
 import { transformSync } from "esbuild";
 import { parse } from "acorn";
-import { full } from "acorn-walk";
+import { full, recursive } from "acorn-walk";
+import { LineMap } from "./sourcemap.js";
 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,
@@ -33,7 +34,8 @@ function jsxSettings(jsx) {
     }
     return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
 }
-function stripTypes(code, options) {
+/** esbuild's output, with its source map's `mappings` when asked for. */
+function stripTypesMapped(code, options, sourcemap) {
     const compilerOptions = {
         verbatimModuleSyntax: true,
         ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
@@ -42,13 +44,19 @@ function stripTypes(code, options) {
     let firstError;
     for (const loader of ["tsx", "ts"]) {
         try {
-            return transformSync(code, {
+            const result = transformSync(code, {
                 loader,
                 target: "esnext",
                 ...jsxSettings(options.jsx),
                 tsconfigRaw: { compilerOptions },
                 logLevel: "silent",
-            }).code;
+                ...(sourcemap ? { sourcemap: "external" } : {}),
+            });
+            const map = sourcemap ? JSON.parse(result.map) : null;
+            const mappings = typeof map?.mappings === "string"
+                ? map.mappings
+                : "";
+            return { code: result.code, mappings };
         }
         catch (err) {
             firstError ??= err;
@@ -57,6 +65,9 @@ function stripTypes(code, options) {
     const message = firstError instanceof Error ? firstError.message : String(firstError);
     throw new CellSyntaxError(message.replace(/^Transform failed with \d+ errors?:\n/, ""));
 }
+function stripTypes(code, options) {
+    return stripTypesMapped(code, options, false).code;
+}
 function importedName(spec) {
     const imported = spec.imported;
     if (!imported)
@@ -80,11 +91,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 +103,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 +149,164 @@ 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 newlines(text) {
+    let count = 0;
+    for (const char of text)
+        if (char === "\n")
+            count++;
+    return count;
+}
+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);
+    for (const edit of edits) {
+        // Keep every later line where it was, so a cell's lines still map to
+        // esbuild's (the debugger relies on it, #18): a multi-line import
+        // rewritten to one line is padded with the newlines it replaced.
+        const lost = newlines(js.slice(edit.start, edit.end)) - newlines(edit.text);
+        const text = lost > 0 ? edit.text + "\n".repeat(lost) : edit.text;
+        out = out.slice(0, edit.start) + 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));
 }
+/**
+ * transformCell, plus the map between the cell's lines and the script's,
+ * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
+ * script's lines are esbuild's, after the prelude's one.
+ */
+export function transformCellWithLines(code, options = {}) {
+    const stripped = stripTypesMapped(code, options, true);
+    return { script: PRELUDE + rewriteModuleSyntax(stripped.code), lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
+}
+/**
+ * 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,125 @@
+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[]>;
+    /** Resolved by property descriptor in the driver, so nothing runs (#10). */
+    inspect(path: string, detail: number): Promise<string | null>;
+    /** 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;
+}