@tlockney/cdp-kernel 0.5.0 → 0.6.0

package/dist/port-holder.js

@@ -0,0 +1,105 @@
+// Who holds a local TCP port, for the error when a connection-file port
+// stays taken past the startup retry (#257). Linux only: it reads
+// /proc/net/tcp{,6} and matches socket inodes against /proc/<pid>/fd.
+import { readdirSync, readFileSync, readlinkSync } from "node:fs";
+const STATES = {
+    "01": "ESTABLISHED",
+    "02": "SYN_SENT",
+    "03": "SYN_RECV",
+    "04": "FIN_WAIT1",
+    "05": "FIN_WAIT2",
+    "06": "TIME_WAIT",
+    "07": "CLOSE",
+    "08": "CLOSE_WAIT",
+    "09": "LAST_ACK",
+    "0A": "LISTEN",
+    "0B": "CLOSING",
+};
+/** The sockets in a /proc/net/tcp table whose local port is `port`. */
+export function socketsOnPort(table, port) {
+    const found = [];
+    for (const line of table.split("\n").slice(1)) {
+        const fields = line.trim().split(/\s+/);
+        if (fields.length < 10)
+            continue;
+        const [, local, remote, state] = fields;
+        if (parseInt(local.slice(local.lastIndexOf(":") + 1), 16) !== port)
+            continue;
+        found.push({ remote, state: STATES[state] ?? state, inode: fields[9] });
+    }
+    return found;
+}
+function describePid(pid) {
+    let cmdline = "?";
+    let ppid = "?";
+    try {
+        cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0").filter(Boolean).join(" ");
+    }
+    catch {
+        // Exited since.
+    }
+    try {
+        // The command name in parentheses may hold spaces; ppid is the second field after it.
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        ppid = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1];
+    }
+    catch {
+        // Exited since.
+    }
+    return `pid ${pid} (ppid ${ppid}): ${cmdline}`;
+}
+/**
+ * One line per socket on `port`: its state, remote end and owning process,
+ * or an empty list when it can't be told (not Linux, or nothing found).
+ */
+export function portHolders(port) {
+    const sockets = [];
+    for (const table of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+        try {
+            sockets.push(...socketsOnPort(readFileSync(table, "utf8"), port));
+        }
+        catch {
+            // No /proc, or no IPv6.
+        }
+    }
+    if (sockets.length === 0)
+        return [];
+    const owners = new Map();
+    const wanted = new Set(sockets.map((s) => `socket:[${s.inode}]`));
+    let pids = [];
+    try {
+        pids = readdirSync("/proc").filter((name) => /^\d+$/.test(name));
+    }
+    catch {
+        // Leave owners unknown.
+    }
+    for (const pid of pids) {
+        let fds;
+        try {
+            fds = readdirSync(`/proc/${pid}/fd`);
+        }
+        catch {
+            continue; // Another user's, or exited.
+        }
+        for (const fd of fds) {
+            let link;
+            try {
+                link = readlinkSync(`/proc/${pid}/fd/${fd}`);
+            }
+            catch {
+                continue;
+            }
+            if (!wanted.has(link))
+                continue;
+            const list = owners.get(link) ?? [];
+            if (!list.includes(pid))
+                list.push(pid);
+            owners.set(link, list);
+        }
+    }
+    return sockets.map((s) => {
+        const pidsOf = owners.get(`socket:[${s.inode}]`) ?? [];
+        const who = pidsOf.length > 0 ? pidsOf.map(describePid).join("; ") : s.inode === "0" ? "no process" : "owner not visible";
+        return `${s.state} to ${s.remote}, ${who}`;
+    });
+}

package/dist/sourcemap.d.ts

@@ -9,8 +9,13 @@ export declare function generatedToOriginalLines(mappings: string): number[];
 /** Both directions between the lines of a cell and of its script (0-based). */
 export declare class LineMap {
     #private;
-    /** `offset`: lines the script adds before esbuild's output (the prelude). */
-    constructor(mappings: string, offset?: number);
+    /**
+     * `offset`: lines the script adds before esbuild's output (the prelude).
+     * `generated`: that output. A stripper that keeps lines blanks a
+     * type-only line in place and still maps it; with the output given, a
+     * blank line counts as unmapped, so a breakpoint there moves down (#239).
+     */
+    constructor(mappings: string, offset?: number, generated?: string);
     /** The cell line a script line came from: its own mapping, or the nearest one above. */
     toOriginal(generated: number): number;
     /**

package/dist/sourcemap.js

@@ -52,9 +52,15 @@ export function generatedToOriginalLines(mappings) {
 export class LineMap {
     #toOriginal;
     #toGenerated = new Map();
-    /** `offset`: lines the script adds before esbuild's output (the prelude). */
-    constructor(mappings, offset = 0) {
-        const fromEsbuild = generatedToOriginalLines(mappings);
+    /**
+     * `offset`: lines the script adds before esbuild's output (the prelude).
+     * `generated`: that output. A stripper that keeps lines blanks a
+     * type-only line in place and still maps it; with the output given, a
+     * blank line counts as unmapped, so a breakpoint there moves down (#239).
+     */
+    constructor(mappings, offset = 0, generated) {
+        const blank = generated?.split("\n").map((line) => line.trim() === "");
+        const fromEsbuild = generatedToOriginalLines(mappings).map((original, line) => blank?.[line] ? -1 : original);
         this.#toOriginal = [...Array(offset).fill(-1), ...fromEsbuild];
         this.#toOriginal.forEach((original, generated) => {
             if (original !== -1 && !this.#toGenerated.has(original))

package/dist/strip-esbuild.d.ts

@@ -0,0 +1,2 @@
+import { type TypeStripper } from "./transform.ts";
+export declare const stripTypes: TypeStripper;

package/dist/strip-esbuild.js

@@ -0,0 +1,44 @@
+// The default type stripper: esbuild. Loaded by loadTypeStripper (see
+// src/transform.ts) only when a kernel uses it, so a host that can't run
+// esbuild's native binary never imports it (#238).
+import { transformSync } from "esbuild";
+import { CellSyntaxError } from "./transform.js";
+function jsxSettings(jsx) {
+    if (jsx?.mode === "automatic") {
+        return { jsx: "automatic", jsxImportSource: jsx.importSource, jsxDev: jsx.development };
+    }
+    return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
+}
+export const stripTypes = (code, options, sourcemap) => {
+    const compilerOptions = {
+        verbatimModuleSyntax: true,
+        ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
+    };
+    // Like Deno: prefer TSX, fall back to TS for `<T>x` assertions.
+    let firstError;
+    for (const loader of ["tsx", "ts"]) {
+        try {
+            const result = transformSync(code, {
+                loader,
+                target: "esnext",
+                // Neither acorn nor V8 parses standard (TC39) decorators or
+                // `accessor` yet, so esbuild lowers them (#142).
+                supported: { decorators: false },
+                ...jsxSettings(options.jsx),
+                tsconfigRaw: { compilerOptions },
+                logLevel: "silent",
+                ...(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;
+        }
+    }
+    const message = firstError instanceof Error ? firstError.message : String(firstError);
+    throw new CellSyntaxError(message.replace(/^Transform failed with \d+ errors?:\n/, ""));
+};

package/dist/strip-sucrase.d.ts

@@ -0,0 +1,2 @@
+import { type TypeStripper } from "./transform.ts";
+export declare const stripTypes: TypeStripper;

package/dist/strip-sucrase.js

@@ -0,0 +1,78 @@
+// A type stripper in plain JavaScript, for a kernel host that can't run
+// esbuild's native binary or WebAssembly (#234). sucrase is an optional
+// dependency, imported only when a kernel picks it (see loadTypeStripper).
+//
+// sucrase removes types without parsing them fully or lowering anything,
+// and keeps every line where it was. What it leaves alone, a cell can't
+// use: decorators and `accessor` fields (which acorn and V8 don't parse
+// yet, #142) and namespaces with values (which it drops), so those are
+// rejected here with a clear error.
+import { parse } from "acorn";
+import { transform } from "sucrase";
+import { CellSyntaxError } from "./transform.js";
+const FILE = "cell.tsx";
+function jsxSettings(options) {
+    const jsx = options.jsx;
+    if (jsx?.mode === "automatic") {
+        return { jsxRuntime: "automatic", jsxImportSource: jsx.importSource, production: !jsx.development };
+    }
+    return {
+        jsxRuntime: "classic",
+        jsxPragma: jsx?.factory ?? "React.createElement",
+        jsxFragmentPragma: jsx?.fragment ?? "React.Fragment",
+        production: true,
+    };
+}
+// A namespace that isn't `declare`d: sucrase drops it, values and all.
+const NAMESPACE = /^[ \t]*(?:export\s+)?(?:namespace|module)\s+[\w$.]+\s*\{/m;
+/** A clearer error than acorn's for syntax sucrase leaves in the output. */
+function unsupported(js) {
+    if (!js.includes("@") && !js.includes("accessor"))
+        return null;
+    try {
+        parse(js, { ecmaVersion: "latest", sourceType: "module", allowAwaitOutsideFunction: true });
+        return null;
+    }
+    catch (err) {
+        const pos = err.pos;
+        if (typeof pos !== "number")
+            return null;
+        if (js[pos] === "@")
+            return "decorators are not supported with the sucrase type stripper";
+        if (/\baccessor\s*$/.test(js.slice(0, pos)))
+            return "accessor fields are not supported with the sucrase type stripper";
+        return null;
+    }
+}
+export const stripTypes = (code, options, sourcemap) => {
+    if (NAMESPACE.test(code)) {
+        throw new CellSyntaxError("namespaces are not supported with the sucrase type stripper; use declare namespace for types only");
+    }
+    // Like the esbuild stripper: prefer TSX, fall back to TS for `<T>x`
+    // assertions.
+    let firstError;
+    for (const transforms of [["typescript", "jsx"], ["typescript"]]) {
+        try {
+            const result = transform(code, {
+                transforms: [...transforms],
+                ...jsxSettings(options),
+                // As verbatimModuleSyntax: only `import type` goes.
+                keepUnusedImports: true,
+                disableESTransforms: true,
+                filePath: FILE,
+                ...(sourcemap ? { sourceMapOptions: { compiledFilename: FILE } } : {}),
+            });
+            const reason = unsupported(result.code);
+            if (reason !== null)
+                throw new CellSyntaxError(reason);
+            return { code: result.code, mappings: result.sourceMap?.mappings ?? "" };
+        }
+        catch (err) {
+            if (err instanceof CellSyntaxError)
+                throw err;
+            firstError ??= err;
+        }
+    }
+    const message = firstError instanceof Error ? firstError.message : String(firstError);
+    throw new CellSyntaxError(message.replace(`Error transforming ${FILE}: `, ""));
+};

package/dist/target.d.ts

@@ -44,6 +44,10 @@ export interface KernelTarget {
     readonly debug?: DebugChannel;
     /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
     replyInput(value: string | null, interrupted?: boolean): void;
+    /** What the host waits on, for a kernel that has stopped answering (#237). */
+    diagnose?(): Promise<CdpParams>;
+    /** Lets go of the last cell's result and error, once they are shown (#286). */
+    releaseResults?(): Promise<void>;
     kill(): void;
 }
 export interface LaunchOptions {
@@ -64,7 +68,7 @@ export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, {
  * install and in Deno's npm cache alike.
  */
 export declare function esbuildBinary(resolve?: (specifier: string) => string, platform?: string, arch?: string): string | null;
-/** Messages the bootstrap sends through the CDP binding. */
+/** Messages the bootstrap sends: message records on stdout, or Bun's channel. */
 export type TargetMessage = {
     kind: "iopub";
     msg_type: string;
@@ -83,18 +87,30 @@ export declare function parseJson(text: string): unknown;
 export declare function isTargetMessage(value: unknown): value is TargetMessage;
 /**
  * Splits one output pipe into text and barrier markers, and releases them
- * in order. A gated marker (one that announces a binding message) pauses
+ * in order. A gated marker (one that announces a message) pauses
  * the pipe until `gate(n)` resolves, i.e. until that message has been
  * delivered, so later output can't overtake it. A possible partial marker
  * at the end of a chunk is held back until the next chunk decides it.
+ *
+ * With `onMessage`, the pipe also carries message records. A record stands
+ * where its gated marker would, and pauses the pipe the same way.
  */
 export declare class PipeDemux {
     #private;
     readonly onText: (text: string) => void;
     readonly gate: (n: number) => Promise<void>;
-    constructor(onText: (text: string) => void, gate?: (n: number) => Promise<void>);
+    readonly onMessage: ((msg: TargetMessage) => void) | null;
+    constructor(onText: (text: string) => void, gate?: (n: number) => Promise<void>, onMessage?: ((msg: TargetMessage) => void) | null);
     push(chunk: string): void;
     waitFor(n: number): Promise<void>;
+    /** Where the pipe stands, for a state dump (#237). */
+    state(): {
+        reached: number;
+        waitingFor: number[];
+        gatedOn: number | null;
+        queued: number;
+        held: number;
+    };
     /** Release everything (the process died). */
     close(): void;
 }
@@ -145,10 +161,18 @@ export declare class Target implements KernelTarget {
     }): Promise<Target>;
     /** The Debugger domain on this target's session, for src/debugger.ts. */
     get debug(): DebugChannel;
+    /**
+     * What the host is waiting on, whether the runtime still evaluates, runs
+     * immediates and runs timers, and where its JavaScript is if it is
+     * running any, for a kernel that has stopped answering (#237). The probes
+     * go over the control session, which no cell holds.
+     */
+    diagnose(): Promise<CdpParams>;
     /** Resolves once all output and messages sent so far have been delivered. */
     flush(): Promise<void>;
     /** Runs transformed cell code. Rejects with Interrupted after interrupt(). */
     evaluate(script: string): Promise<EvaluateResult>;
+    releaseResults(): Promise<void>;
     /**
      * Deno calls IsolateHandle::terminate_execution from another thread. The
      * CDP equivalent is Runtime.terminateExecution, sent on a second session