@tlockney/cdp-kernel 0.3.0 → 0.4.0

package/README.md

@@ -45,7 +45,8 @@ Each install writes a Jupyter kernelspec: `cdp-node`, `cdp-deno`,
 `cdp-node-deno` (Node with the Deno compatibility namespace), `cdp-bun`,
 `cdp-workerd`, or `cdp-celld`. Then pick the kernel in JupyterLab or VS Code.
 
-**From npm** (host runs on Node 24+; Node 26 is what's been tested):
+**From npm** (host runs on Node 24+). CI tests Node 24 and 26 with Deno 2.9
+and the latest 2.x, on Linux and macOS. Windows isn't supported yet.
 
 ```sh
 npm install -g @tlockney/cdp-kernel
@@ -80,10 +81,17 @@ Windows build).
 Deno 2.9+ refuses package versions less than 24 hours old by default
 ([minimum dependency age](https://docs.deno.com/go/minimum-dependency-age)).
 In a release's first day, the install command fails with "blocked by the
-minimum dependency age policy". Wait out the day, or install an earlier
-release. Passing `--min-dep-age=0` gets the install through, but the
-kernelspec doesn't carry the flag, so the kernel still won't launch until
-the release is a day old.
+minimum dependency age policy". Pass `--min-dep-age=0` to the install
+command to get it through:
+
+```sh
+deno run -A --min-dep-age=0 jsr:@tlockney/cdp-kernel/cli install --runtime deno
+```
+
+The kernelspec it writes works on release day too. It relaunches the kernel
+with a dependency cutoff of two days after the release
+(`--min-dep-age=<date>`), so it never resolves anything published after
+that.
 
 **From a checkout**, for working on the kernel itself:
 
@@ -116,7 +124,20 @@ In a cell:
   from the notebook's `node_modules`, `node:` builtins, and `npm:pkg@range`
   or `jsr:@scope/pkg@range`.
   - On Node, `npm:` and `jsr:` install on first use into
-    `~/.cache/cdp-kernel/npm`.
+    `~/.cache/cdp-kernel/npm`. An exact version (`npm:react@19.0.0`) installs
+    exactly that version. A range (`npm:react@19`) is resolved the first
+    time it's imported and stays at that version, even as other packages
+    are installed later. Caches written by cdp-kernel 0.3.0 or earlier
+    recorded ranges, which later installs could re-resolve. Delete
+    `~/.cache/cdp-kernel/npm` to start fresh. `jsr:` works with npm 12,
+    which otherwise refuses JSR's registry tarballs.
+  - **Lockfile** (cdp-kernel 0.4.0 or later). To pin versions, create a `cdp-kernel.lock.json` in the
+    notebook's directory (or above it) containing `{}`. From then on, each
+    `npm:`/`jsr:` range is recorded with the exact version it resolved to,
+    and installed at that version, so the notebook gets the same packages
+    on another machine. Commit it next to the notebook. Deno targets use
+    Deno's own resolution and lock instead. Installs into the shared cache
+    are serialized, so two kernels installing at once can't corrupt it.
   - On Deno they use Deno's global cache, unless the notebook is in a Deno
     project (below).
   - On Bun they install with `bun add` into `~/.cache/cdp-kernel/bun`. Other
@@ -143,6 +164,13 @@ In a cell:
 - `prompt()` and `confirm()` work over the stdin channel, except on
   workerd. Interrupt keeps state, except for a busy cell on Bun or workerd
   (below).
+- **Shift-Tab** shows a tooltip for the name at the cursor: its type, a
+  function's signature (and its source at the second press), a preview, and
+  its properties. Nothing is run to get it. On Node and Deno the value is
+  evaluated with V8's side-effect check (`throwOnSideEffect`), which also
+  guards completion. Bun, workerd and celld look the name up by property,
+  without calling getters. Executed cells are kept for `history_request`
+  (tail, range and search).
 
 ## Bun
 
@@ -248,6 +276,35 @@ all work as on workerd. The differences:
   waits for it to stop gracefully, which a busy cell never allows. So an
   interrupt of a busy cell kills the node, then `celld dev`.
 
+## Debugger
+
+On Node and Deno targets, JupyterLab's visual debugger works: the bug
+button in the notebook toolbar, breakpoints in the cell gutter, the call
+stack, variables and scopes, stepping, pause on exceptions, the debug
+console, and the rich variable viewer. The kernel translates the Jupyter
+debug protocol (DAP over `debug_request`) to V8's `Debugger` domain on the
+session it already holds (`src/debugger.ts`):
+
+- **Cell paths.** Each cell is named as JupyterLab names it: a temp-dir
+  prefix plus the Murmur2 hash of its code (`src/murmur2.ts`, matched
+  against ipykernel's). It's evaluated with that name as its
+  `//# sourceURL`, so breakpoints bind to the cell and frames point back at
+  it.
+- **Lines.** Breakpoint and frame lines go through the cell's source map
+  (`src/sourcemap.ts`), since esbuild rewrites the TypeScript. A breakpoint
+  on a blank or type-only line moves to the next statement.
+- **Nothing runs on its own.** The variable explorer between cells reads
+  the cells' declarations with V8's side-effect check, so a getter never
+  runs. Frames, scopes and the rich viewer evaluate on the paused frame.
+- **Kernelspec.** `metadata.debugger` is set for Node and Deno kernelspecs,
+  which is what JupyterLab checks. Reinstall older kernelspecs to get it.
+
+`CDPK_DEBUG_TRACE=1` logs every debug request, reply and event to the
+Jupyter server's log.
+
+Bun, workerd and celld don't run over an inspector, so they have no
+debugger.
+
 ## Editor types
 
 Cells run untyped, as in `deno jupyter`. Notebook code your editor
@@ -357,12 +414,15 @@ CLI: an installed npm bin, or `deno run -A src/main.ts` to test a Deno host.
 One version number lives in three places: `package.json`, `deno.jsonc` and
 `src/package.ts`. `test/package.test.ts` fails if they disagree. To release:
 
-1. Bump all three, commit, and merge to `main`.
+1. Bump all three, and set `RELEASE_DATE` in `src/package.ts` to today
+   (UTC). Commit, and merge to `main`.
 2. Tag and push: `git tag v0.1.1 && git push origin v0.1.1`.
 
 The `publish` workflow then:
 
-1. Checks that the tag matches the version.
+1. Checks that the tag matches the version, and that `RELEASE_DATE` is
+   today or yesterday. A JSR kernelspec's dependency cutoff comes from that
+   date, so a stale one would block the release it ships in.
 2. Runs the type check, the unit tests, and the e2e suite against the packed
    npm tarball and against a Deno host.
 3. Publishes to JSR (`deno publish`).
@@ -381,15 +441,32 @@ that failed.
 
 - Widgets are anywidget-style (`jupyter.widget`). The classic ipywidgets
   controls (sliders, dropdowns) are Python classes, so they're not available.
-- No `inspect_request` content and no history. Deno has neither.
-- No debugger.
-- `npm:` on Node:
-  - one npm alias per `name@range`;
-  - no lockfile;
-  - peer dependencies resolve by real name from the shared cache.
+- Inspection tooltips show what's found at runtime (type, signature,
+  preview, properties), not TypeScript types or JSDoc. On Bun, workerd and
+  celld, a getter on the path is reported but not called. History is kept
+  for the current kernel session only.
+- The debugger is for Node and Deno targets only. Breakpoints are per line,
+  conditional breakpoints and logpoints aren't supported, variables can't be
+  set from the debugger, and "copy to globals" isn't offered.
+- `npm:` on Node, Bun, workerd and celld:
+  - one npm alias per `name@range` (or exact version, when locked);
+  - the cache is shared by every notebook, so peer dependencies resolve by
+    real name from it;
+  - a project's own `package.json` doesn't decide an `npm:` import's version
+    (bare imports do use its `node_modules`).
 - No type checking. Deno doesn't type-check REPL cells either.
-- Results are formatted with `util.inspect` on Node, so they look slightly
-  different from Deno's `Deno.inspect`.
+- Results are formatted by each runtime's own inspector: `util.inspect` on
+  Node, Bun, workerd and celld, and `Deno.inspect` on Deno. On a fixture of
+  30 typical values, 23 format identically on Node and Deno. The rest
+  differ in two ways:
+  - strings are quoted `'…'` on Node and `"…"` on Deno, wherever they
+    appear;
+  - a displayed `Error`'s stack also lists Node's own module-loader frames.
+
+  That's deliberate: each runtime's users see the format they expect, and
+  Node's inspector has no quote-style option, short of porting Deno's
+  formatter. `test/formatting.test.ts` runs both runtimes on the fixture
+  and fails if a new kind of difference appears (#17).
 - WebGPU texture and buffer display is dropped.
 - On Bun:
   - Interrupting a busy cell restarts Bun and loses state. An awaiting cell

package/dist/bun-target.d.ts

@@ -51,6 +51,8 @@ export declare class BunTarget implements KernelTarget {
         stack: string;
     }>;
     propertyNames(expression: string): Promise<string[]>;
+    /** Resolved by property descriptor in the target, so nothing runs (#10). */
+    inspect(path: string, detail: number): Promise<string | null>;
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames(): Promise<string[]>;
     replyInput(value: string | null): void;

package/dist/bun-target.js

@@ -218,6 +218,11 @@ export class BunTarget {
         const reply = await this.#request("props", { expr: expression }).catch(() => null);
         return Array.isArray(reply?.names) ? reply.names.filter((n) => typeof n === "string") : [];
     }
+    /** Resolved by property descriptor in the target, so nothing runs (#10). */
+    async inspect(path, detail) {
+        const reply = await this.#request("inspect", { path, detail }).catch(() => null);
+        return typeof reply?.text === "string" ? reply.text : null;
+    }
     /** None: top-level declarations here are properties of globalThis. */
     lexicalNames() {
         return Promise.resolve([]);

package/dist/debugger.d.ts

@@ -0,0 +1,42 @@
+import type { CdpParams, RemoteObject } from "./cdp.ts";
+import { type CellTransformOptions } from "./transform.ts";
+/** What the debugger needs from a CDP target: its session, with the Debugger domain. */
+export interface DebugChannel {
+    send(method: string, params?: CdpParams): Promise<CdpParams>;
+    on(method: string, listener: (params: CdpParams) => void): void;
+    /** The execution context cells run in. */
+    readonly contextId: number;
+    /** Enumerable globals the runtime had before any cell ran. */
+    readonly baselineGlobals: ReadonlySet<string>;
+}
+export type DapMessage = {
+    [key: string]: unknown;
+};
+/** ipykernel's seed, so a kernel switch doesn't move JupyterLab's breakpoints. */
+export declare const HASH_SEED = 3339675911;
+export declare const THREAD_ID = 1;
+/** A DAP value string for a CDP RemoteObject. */
+export declare function describeRemote(object: RemoteObject): string;
+export declare class Debugger {
+    #private;
+    readonly prefix: string;
+    readonly suffix = ".ts";
+    constructor(emit: (event: DapMessage) => void, transformOptions?: () => CellTransformOptions);
+    get started(): boolean;
+    get stopped(): boolean;
+    /** A cell's path, as JupyterLab computes it for the same code. */
+    pathFor(code: string): string;
+    /**
+     * The target to debug: called with each target the kernel launches. A
+     * restarted target gets the session's breakpoints again.
+     */
+    attachTarget(channel: DebugChannel | null): Promise<void>;
+    /**
+     * The script for a cell while debugging: transformed with its line map
+     * kept, and named for its path. `source` is what actually runs (the cell,
+     * or the cell wrapped as an object literal); the path comes from `code`,
+     * the cell as the frontend sent it.
+     */
+    cellScript(code: string, source: string): string;
+    handle(request: DapMessage): Promise<DapMessage>;
+}