@tlockney/cdp-kernel 0.4.0 → 0.6.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.d.ts

@@ -3,7 +3,7 @@ import { type CellTransformOptions, transformCell } from "./transform.ts";
 import type { DebugChannel } from "./debugger.ts";
 /** Targets driven over CDP. */
 export type CdpRuntime = "node" | "deno";
-/** Bun and workerd have their own backends: src/bun-target.ts, src/workerd-target.ts. */
+/** 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 {
@@ -42,7 +42,12 @@ export interface KernelTarget {
     inspect(path: string, detail: number): Promise<string | null>;
     /** The Debugger domain, on targets driven over CDP (#18). */
     readonly debug?: DebugChannel;
-    replyInput(value: string | null): void;
+    /** 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 {
@@ -56,7 +61,14 @@ export declare function launchCommand(runtime: CdpRuntime, bootstrap: string, {
     cmd: string;
     args: string[];
 };
-/** Messages the bootstrap sends through the CDP binding. */
+/**
+ * The esbuild binary this host's esbuild runs, for a Node target to compile
+ * imported TypeScript Node can't strip (#73); null when it can't be found.
+ * Resolved from esbuild's own location, so it's found in a node_modules
+ * 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: message records on stdout, or Bun's channel. */
 export type TargetMessage = {
     kind: "iopub";
     msg_type: string;
@@ -70,24 +82,51 @@ export type TargetMessage = {
     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;
 }
+/**
+ * Removes the runtime's own stderr lines (see INSPECTOR_CHATTER) and passes
+ * everything else on. A chatter line can arrive split across chunks, so a
+ * trailing partial line that could still turn out to be one is held back
+ * until its newline arrives; any other partial line passes straight through.
+ */
+export declare class StderrFilter {
+    #private;
+    constructor(runtime: CdpRuntime, emit: (text: string) => void);
+    push(chunk: string): void;
+    /** Releases a held partial line (the process died). */
+    flush(): void;
+}
 /** Promises keyed by barrier number, resolvable before or after first use. */
 export declare class Gates {
     #private;
@@ -118,13 +157,22 @@ export declare class Target implements KernelTarget {
         executable?: string;
         denoCompat?: boolean;
         denoConfig?: string;
+        startTimeoutMs?: number;
     }): 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
@@ -133,6 +181,10 @@ export declare class Target implements KernelTarget {
      * evaluate is abandoned here and the session stays usable.
      */
     interrupt(): Promise<void>;
+    /**
+     * For synchronous functions. With awaitPromise the inspector would wrap
+     * even a plain return value in a promise it holds only weakly (#55).
+     */
     callFunctionOn(functionDeclaration: string, args: CdpParams[]): Promise<CdpParams>;
     /** The broadcastResult step of Deno's execute flow (jupyter/mod.rs). */
     broadcastResult(executionCount: number, result: RemoteObject): Promise<void>;
@@ -158,6 +210,6 @@ export declare class Target implements KernelTarget {
     propertyNames(expression: string): Promise<string[]>;
     inspect(path: string, detail: number): Promise<string | null>;
     lexicalNames(): Promise<string[]>;
-    replyInput(value: string | null): void;
+    replyInput(value: string | null, interrupted?: boolean): void;
     kill(): void;
 }