@tlockney/cdp-kernel 0.5.0 → 0.7.0

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-api.d.ts

@@ -0,0 +1,80 @@
+import type { CdpParams, EvaluateResult, RemoteObject } from "./cdp.ts";
+import type { DebugChannel } from "./debugger.ts";
+import type { CellTransformOptions } from "./transform.ts";
+/** Targets driven over CDP. */
+export type CdpRuntime = "node" | "deno";
+/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
+export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
+/** Every target: the runtimes a kernelspec names, and the browser's Worker (src/browser/). */
+export type TargetRuntime = RuntimeName | "browser";
+/** What the kernel needs from a target runtime. */
+export interface KernelTarget {
+    readonly runtime: TargetRuntime;
+    readonly versions: {
+        runtime: string;
+        engine: string;
+    };
+    /** Shown once, in the first cell: e.g. which project's bindings loaded. */
+    readonly notice?: string;
+    /** Turns a cell into the script evaluate() takes. */
+    transform(code: string, options: CellTransformOptions): string;
+    /** Runs a transformed cell. Rejects with Interrupted after interrupt(). */
+    evaluate(script: string): Promise<EvaluateResult>;
+    interrupt(): Promise<void>;
+    /** Resolves once all output and messages sent so far have been delivered. */
+    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[]>;
+    lexicalNames(): Promise<string[]>;
+    /** inspect_request (#10): text describing a dotted path's value, without running anything. */
+    inspect(path: string, detail: number): Promise<string | null>;
+    /** The Debugger domain, on targets driven over CDP (#18). */
+    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;
+}
+/** Messages the bootstrap sends: message records on stdout, or Bun's channel. */
+export type TargetMessage = {
+    kind: "iopub";
+    msg_type: string;
+    content: CdpParams;
+    metadata: CdpParams;
+    buffers: string[];
+    barrier: number;
+} | {
+    kind: "input_request";
+    prompt: string;
+    password: boolean;
+    barrier: number;
+};
+/** The parsed value, or undefined for text that isn't JSON. */
+export declare function parseJson(text: string): unknown;
+export declare function isTargetMessage(value: unknown): value is TargetMessage;
+export interface TargetEvents {
+    stream(name: "stdout" | "stderr", text: string): void;
+    message(msg: TargetMessage): void;
+    /** `note` says why, when the target was stopped on purpose. */
+    exit(code: number | null, note?: string): void;
+}
+export declare class Interrupted extends Error {
+    name: string;
+}

package/dist/target-api.js

@@ -0,0 +1,22 @@
+// What the kernel needs from a target runtime, and what a target sends
+// back: the part of src/target.ts with no Node imports, so the kernel's
+// message handling (src/kernel-core.ts) also loads in a browser.
+/** The parsed value, or undefined for text that isn't JSON. */
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isTargetMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    return (kind === "iopub" || kind === "input_request") &&
+        typeof value.barrier === "number";
+}
+export class Interrupted extends Error {
+    name = "Interrupted";
+}

package/dist/target.d.ts

@@ -1,51 +1,9 @@
 import { type CdpParams, type EvaluateResult, type RemoteObject } from "./cdp.ts";
-import { type CellTransformOptions, transformCell } from "./transform.ts";
+import { transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
-/** Targets driven over CDP. */
-export type CdpRuntime = "node" | "deno";
-/** Bun, workerd and celld have their own backends: src/bun-target.ts, src/workerd-target.ts, src/celld-target.ts. */
-export type RuntimeName = CdpRuntime | "bun" | "workerd" | "celld";
-/** What the kernel needs from a target runtime. */
-export interface KernelTarget {
-    readonly runtime: RuntimeName;
-    readonly versions: {
-        runtime: string;
-        engine: string;
-    };
-    /** Shown once, in the first cell: e.g. which project's bindings loaded. */
-    readonly notice?: string;
-    /** Turns a cell into the script evaluate() takes. */
-    transform(code: string, options: CellTransformOptions): string;
-    /** Runs a transformed cell. Rejects with Interrupted after interrupt(). */
-    evaluate(script: string): Promise<EvaluateResult>;
-    interrupt(): Promise<void>;
-    /** Resolves once all output and messages sent so far have been delivered. */
-    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[]>;
-    lexicalNames(): Promise<string[]>;
-    /** inspect_request (#10): text describing a dotted path's value, without running anything. */
-    inspect(path: string, detail: number): Promise<string | null>;
-    /** The Debugger domain, on targets driven over CDP (#18). */
-    readonly debug?: DebugChannel;
-    /** Answers the target's pending prompt; `interrupted` makes it throw instead (#121). */
-    replyInput(value: string | null, interrupted?: boolean): void;
-    kill(): void;
-}
+import { type CdpRuntime, Interrupted, isTargetMessage, type KernelTarget, parseJson, type TargetEvents, type TargetMessage } from "./target-api.ts";
+export { Interrupted, isTargetMessage, parseJson };
+export type { CdpRuntime, KernelTarget, RuntimeName, TargetEvents, TargetMessage } from "./target-api.ts";
 export interface LaunchOptions {
     /** Runtime binary; defaults to `deno`, or `node` (this one when hosted by Node). */
     executable?: string;
@@ -64,37 +22,32 @@ 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. */
-export type TargetMessage = {
-    kind: "iopub";
-    msg_type: string;
-    content: CdpParams;
-    metadata: CdpParams;
-    buffers: string[];
-    barrier: number;
-} | {
-    kind: "input_request";
-    prompt: string;
-    password: boolean;
-    barrier: number;
-};
-/** The parsed value, or undefined for text that isn't JSON. */
-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;
 }
@@ -118,15 +71,6 @@ export declare class Gates {
     open(n: number): void;
     openAll(): void;
 }
-export interface TargetEvents {
-    stream(name: "stdout" | "stderr", text: string): void;
-    message(msg: TargetMessage): void;
-    /** `note` says why, when the target was stopped on purpose. */
-    exit(code: number | null, note?: string): void;
-}
-export declare class Interrupted extends Error {
-    name: string;
-}
 export declare class Target implements KernelTarget {
     #private;
     readonly runtime: CdpRuntime;
@@ -145,10 +89,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