@tlockney/cdp-kernel 0.5.0 → 0.6.0

package/dist/main.js

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
 // cdp-kernel CLI.
-//   cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--name NAME] [--display NAME]
-//   cdp-kernel kernel --runtime node|deno|bun|workerd|celld [--deno-compat] --conn CONNECTION_FILE
+//   cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--type-strip esbuild|sucrase] [--no-language-service] [--name NAME] [--display NAME]
+//   cdp-kernel kernel --runtime node|deno|bun|workerd|celld [--deno-compat] [--type-strip esbuild|sucrase] [--no-language-service] --conn CONNECTION_FILE
+//   cdp-kernel list
+//   cdp-kernel uninstall [NAME...] [--name NAME] [--all]
 //   cdp-kernel version
 //
 // --deno-compat (Node only) adds a `Deno` namespace for notebooks written for
-// `deno jupyter`; see runtime/deno-compat.mjs.
+// `deno jupyter`; see runtime/deno-compat.mjs. --type-strip picks what
+// removes cells' types (src/transform.ts). --no-language-service turns off
+// typed completion (src/language-service.ts), which costs about 150 MB
+// while in use.
 import process from "node:process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { Kernel, parseConnectionInfo } from "./kernel.js";
+import { isTypeStripperName } from "./transform.js";
 import { hostRuntime, kernelArgv, moduleOrigin, VERSION } from "./package.js";
 function isRuntime(value) {
     return value === "node" || value === "deno" || value === "bun" || value === "workerd" || value === "celld";
@@ -25,7 +31,7 @@ function kernelsDir() {
         return join(process.env.APPDATA ?? homedir(), "jupyter", "kernels");
     return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "jupyter", "kernels");
 }
-function install(runtime, denoCompat, name, display) {
+function install(runtime, denoCompat, typeStrip, languageService, name, display) {
     const dir = join(kernelsDir(), name);
     mkdirSync(dir, { recursive: true });
     const spec = {
@@ -34,6 +40,8 @@ function install(runtime, denoCompat, name, display) {
             "--runtime",
             runtime,
             ...(denoCompat ? ["--deno-compat"] : []),
+            ...(typeStrip !== "esbuild" ? ["--type-strip", typeStrip] : []),
+            ...(languageService ? [] : ["--no-language-service"]),
             "--conn",
             "{connection_file}",
         ]),
@@ -49,6 +57,77 @@ function install(runtime, denoCompat, name, display) {
     writeFileSync(join(dir, "kernel.json"), JSON.stringify(spec, null, 2) + "\n");
     console.log(`installed kernelspec ${name} -> ${dir}`);
 }
+// A kernelspec this package wrote: install() always records the runtime in
+// metadata and passes the connection file to the kernel subcommand. Other
+// kernels' specs in the same directory are left alone.
+function readOwnSpec(name) {
+    const dir = join(kernelsDir(), name);
+    let spec;
+    try {
+        spec = JSON.parse(readFileSync(join(dir, "kernel.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const argv = Array.isArray(spec.argv) ? spec.argv : [];
+    const runtime = spec.metadata?.runtime;
+    if (!isRuntime(runtime) || !argv.includes("kernel") || !argv.includes("{connection_file}"))
+        return undefined;
+    const version = typeof spec.metadata?.version === "string" ? spec.metadata.version : undefined;
+    return { name, dir, runtime, version };
+}
+function installedSpecs() {
+    const root = kernelsDir();
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => readOwnSpec(entry.name))
+        .filter((spec) => spec !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function list() {
+    const specs = installedSpecs();
+    if (specs.length === 0) {
+        console.log(`no cdp-kernel kernelspecs in ${kernelsDir()}`);
+        return;
+    }
+    const width = Math.max(...specs.map((s) => s.name.length));
+    for (const s of specs) {
+        console.log(`${s.name.padEnd(width)}  ${s.runtime.padEnd(7)}  ${(s.version ?? "-").padEnd(7)}  ${s.dir}`);
+    }
+}
+// Jupyter's kernel names; anything else could point outside the kernels
+// directory.
+const KERNEL_NAME = /^[A-Za-z0-9._-]+$/;
+function uninstall(names, all) {
+    if (all)
+        names = installedSpecs().map((s) => s.name);
+    else if (names.length === 0) {
+        console.error("uninstall: name the kernelspecs to remove, or pass --all. Installed:");
+        list();
+        process.exit(2);
+    }
+    let failed = false;
+    for (const name of names) {
+        const valid = KERNEL_NAME.test(name) && name !== "." && name !== "..";
+        const spec = valid ? readOwnSpec(name) : undefined;
+        if (!spec) {
+            const exists = valid && existsSync(join(kernelsDir(), name));
+            console.error(exists
+                ? `uninstall: ${name} wasn't installed by cdp-kernel; leaving it (use jupyter kernelspec remove)`
+                : `uninstall: no kernelspec ${name} in ${kernelsDir()}`);
+            failed = true;
+            continue;
+        }
+        rmSync(spec.dir, { recursive: true, force: true });
+        console.log(`removed kernelspec ${name} (${spec.dir})`);
+    }
+    if (all && names.length === 0)
+        console.log(`no cdp-kernel kernelspecs in ${kernelsDir()}`);
+    if (failed)
+        process.exit(1);
+}
 const { positionals, values } = parseArgs({
     allowPositionals: true,
     options: {
@@ -56,7 +135,10 @@ const { positionals, values } = parseArgs({
         conn: { type: "string" },
         name: { type: "string" },
         display: { type: "string" },
+        all: { type: "boolean", default: false },
         "deno-compat": { type: "boolean", default: false },
+        "type-strip": { type: "string", default: "esbuild" },
+        "no-language-service": { type: "boolean", default: false },
     },
 });
 const runtime = values.runtime;
@@ -64,12 +146,18 @@ if (!isRuntime(runtime)) {
     console.error(`unknown runtime ${runtime}; expected node, deno, bun, workerd or celld`);
     process.exit(2);
 }
+const typeStrip = values["type-strip"];
+if (!isTypeStripperName(typeStrip)) {
+    console.error(`unknown type stripper ${typeStrip}; expected esbuild or sucrase`);
+    process.exit(2);
+}
+const languageService = values["no-language-service"] !== true;
 // Deno targets have the real namespace; the shim is for Node.
 const denoCompat = values["deno-compat"] === true && runtime === "node";
 switch (positionals[0]) {
     case "install": {
         const suffix = denoCompat ? "-deno" : "";
-        install(runtime, denoCompat, values.name ?? `cdp-${runtime}${suffix}`, values.display ?? `TypeScript (cdp-kernel, ${runtime}${denoCompat ? ", Deno compat" : ""})`);
+        install(runtime, denoCompat, typeStrip, languageService, values.name ?? `cdp-${runtime}${suffix}`, values.display ?? `TypeScript (cdp-kernel, ${runtime}${denoCompat ? ", Deno compat" : ""})`);
         break;
     }
     case "kernel": {
@@ -77,14 +165,20 @@ switch (positionals[0]) {
             console.error("kernel: --conn CONNECTION_FILE is required");
             process.exit(2);
         }
-        const kernel = new Kernel(parseConnectionInfo(readFileSync(values.conn, "utf8")), runtime, { denoCompat });
+        const kernel = new Kernel(parseConnectionInfo(readFileSync(values.conn, "utf8")), runtime, { denoCompat, typeStrip, languageService });
         await kernel.run();
         break;
     }
+    case "list":
+        list();
+        break;
+    case "uninstall":
+        uninstall([...positionals.slice(1), ...(values.name ? [values.name] : [])], values.all === true);
+        break;
     case "version":
         console.log(VERSION);
         break;
     default:
-        console.error("usage: cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] | kernel --runtime node|deno|bun|workerd|celld --conn FILE | version");
+        console.error("usage: cdp-kernel install [--runtime node|deno|bun|workerd|celld] [--deno-compat] [--type-strip esbuild|sucrase] [--no-language-service] | list | uninstall [NAME...] [--all] | kernel --runtime node|deno|bun|workerd|celld --conn FILE | version");
         process.exit(2);
 }

package/dist/mod.d.ts

@@ -22,4 +22,5 @@
  */
 export { type ConnectionInfo, Kernel, parseConnectionInfo } from "./kernel.ts";
 export type { RuntimeName } from "./target.ts";
+export { CellSyntaxError, type CellTransformOptions, type JsxOptions, type TypeStripper } from "./transform.ts";
 export { VERSION } from "./package.ts";

package/dist/mod.js

@@ -21,4 +21,5 @@
  * @module
  */
 export { Kernel, parseConnectionInfo } from "./kernel.js";
+export { CellSyntaxError } from "./transform.js";
 export { VERSION } from "./package.js";

package/dist/notebook-types.d.ts

@@ -0,0 +1,62 @@
+import type TS from "typescript";
+import type { DenoResolver } from "./deno-types.ts";
+export interface NotebookTypesOptions {
+    notebookDir: string;
+    /**
+     * The installer cache npm: and jsr: imports resolve from: where the
+     * target installs them (Bun's own for Bun, npm's for the rest). Null for
+     * Deno targets, which resolve them natively (see `deno`).
+     */
+    npmCache: "npm" | "bun" | null;
+    /**
+     * For Deno targets: where Deno put what the executed cells imported
+     * (npm:, jsr:, URLs, the project's import map).
+     */
+    deno?: DenoResolver;
+    /** compilerOptions.types: type packages found from the notebook's directory. */
+    types: string[];
+    /** Declaration files every cell sees, e.g. runtime types. */
+    typeFiles: string[];
+    /** Declarations for the kernel's own globals (jupyter, prompt, confirm). */
+    globals: string;
+}
+export interface CompletionEntry {
+    name: string;
+    /** TypeScript's ScriptElementKind: "method", "property", "const", ... */
+    kind: string;
+}
+export interface CompletionResult {
+    /** Where the completed name starts in the cell, as a UTF-16 index. */
+    start: number;
+    entries: CompletionEntry[];
+}
+export declare class NotebookTypes {
+    #private;
+    constructor(ts: typeof TS, options: NotebookTypesOptions);
+    /** An executed cell: its declarations are in scope for later ones. */
+    addCell(code: string): void;
+    /** The runtime restarted and lost its state. */
+    reset(): void;
+    /** Adds declaration files, e.g. runtime types installed after startup. */
+    addTypeFiles(files: string[]): void;
+    /** Adds a declaration file held in memory, e.g. the output of `deno types`. */
+    addVirtualTypeFile(name: string, text: string): void;
+    /** Adds type packages (compilerOptions.types) that resolve from the notebook. */
+    addTypeNames(names: string[]): void;
+    /** Whether a type package (compilerOptions.types) resolves from the notebook. */
+    resolvesTypes(name: string): boolean;
+    /** Completions at `cursor` (a UTF-16 index) in `code`, the cell being edited. */
+    complete(code: string, cursor: number): CompletionResult;
+    /**
+     * The type, signature and JSDoc of the name at `cursor`: the one the
+     * cursor is in or just after, or, right after "name(", that callee.
+     */
+    quickInfo(code: string, cursor: number): string | null;
+}
+/**
+ * Declarations for the names the kernel adds to every target, as in
+ * src/globals.ts. `display` is runtime/display.mjs's path; its sibling
+ * display.d.mts types `jupyter`. Without it (a kernel run from JSR, whose
+ * runtime files aren't local), `jupyter` is untyped.
+ */
+export declare function kernelGlobals(display: string | null): string;

package/dist/notebook-types.js

@@ -0,0 +1,310 @@
+// TypeScript's language service over a notebook (#263): completion from
+// declared types, where the runtime only knows values. Runs in a worker
+// (src/language-service-worker.ts); see probes/ts-language-service.md for
+// the design and its measurements.
+//
+// The service sees one virtual file, never written to disk, in the
+// notebook's directory (so relative imports resolve from there): the cells
+// executed so far, then the cell being edited. REPL cells redeclare names
+// all the time (`const x = 1`, later `const x = "s"`), which in one file is
+// an error that keeps the first type, so a declaration is dropped from the
+// history when a later cell, or the one being edited, declares all of its
+// names again.
+import { join } from "node:path";
+import { findLockFile, installedPackageDir, jsrToNpm, parsePackageSpecifier } from "../runtime/node-hooks.mjs";
+// The document is a module, so top-level await in a cell isn't an error.
+const PREFIX = "export {};\n";
+export class NotebookTypes {
+    #ts;
+    #options;
+    #file;
+    #globalsFile;
+    #service;
+    #compilerOptions;
+    #resolutionCache;
+    /** ts.sys, plus the remote modules a Deno target fetched (virtual paths). */
+    #resolutionHost;
+    #cells = [];
+    /** Specifiers executed cells imported: the target has fetched them. */
+    #imported = new Set();
+    /** Declaration files that exist only in memory, e.g. `deno types`. */
+    #virtualTypes = new Map();
+    #typeFiles;
+    #text = PREFIX;
+    #version = 0;
+    #projectVersion = 0;
+    constructor(ts, options) {
+        this.#ts = ts;
+        this.#options = options;
+        this.#typeFiles = [...options.typeFiles];
+        this.#file = join(options.notebookDir, "__cdpk_notebook__.ts");
+        this.#globalsFile = join(options.notebookDir, "__cdpk_globals__.d.ts");
+        this.#compilerOptions = {
+            target: ts.ScriptTarget.ESNext,
+            module: ts.ModuleKind.Preserve,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+            allowImportingTsExtensions: true,
+            allowJs: true,
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            lib: ["lib.esnext.d.ts"],
+            types: options.types,
+        };
+        const deno = options.deno;
+        this.#resolutionHost = {
+            ...ts.sys,
+            fileExists: (f) => deno?.localFile(f) !== undefined || ts.sys.fileExists(f),
+            readFile: (f) => {
+                const local = deno?.localFile(f);
+                return ts.sys.readFile(local ?? f);
+            },
+            directoryExists: (d) => (deno !== undefined && d.startsWith(deno.root)) || ts.sys.directoryExists(d),
+            getCurrentDirectory: () => options.notebookDir,
+        };
+        const host = this.#host();
+        this.#resolutionCache = ts.createModuleResolutionCache(options.notebookDir, (f) => f, this.#compilerOptions);
+        this.#service = ts.createLanguageService(host, ts.createDocumentRegistry());
+    }
+    /** An executed cell: its declarations are in scope for later ones. */
+    addCell(code) {
+        this.#cells.push({ code, statements: this.#statements(code) });
+        const ts = this.#ts;
+        const sf = ts.createSourceFile("cell.ts", code, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
+        for (const stmt of sf.statements) {
+            if ((ts.isImportDeclaration(stmt) || ts.isExportDeclaration(stmt)) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+                this.#imported.add(stmt.moduleSpecifier.text);
+            }
+        }
+    }
+    /** The runtime restarted and lost its state. */
+    reset() {
+        this.#cells.length = 0;
+    }
+    /** Adds declaration files, e.g. runtime types installed after startup. */
+    addTypeFiles(files) {
+        this.#typeFiles.push(...files.filter((f) => !this.#typeFiles.includes(f)));
+        this.#projectVersion++;
+    }
+    /** Adds a declaration file held in memory, e.g. the output of `deno types`. */
+    addVirtualTypeFile(name, text) {
+        this.#virtualTypes.set(join(this.#options.notebookDir, name), text);
+        this.#projectVersion++;
+    }
+    /** Adds type packages (compilerOptions.types) that resolve from the notebook. */
+    addTypeNames(names) {
+        const current = this.#compilerOptions.types ?? [];
+        // A new object: the service compares options by identity first.
+        this.#compilerOptions = { ...this.#compilerOptions, types: [...current, ...names.filter((n) => !current.includes(n))] };
+        this.#projectVersion++;
+    }
+    /** Whether a type package (compilerOptions.types) resolves from the notebook. */
+    resolvesTypes(name) {
+        // Default type roots are found up from the current directory.
+        const host = { ...this.#ts.sys, getCurrentDirectory: () => this.#options.notebookDir };
+        const resolved = this.#ts.resolveTypeReferenceDirective(name, this.#file, this.#compilerOptions, host);
+        return resolved.resolvedTypeReferenceDirective !== undefined;
+    }
+    /** Completions at `cursor` (a UTF-16 index) in `code`, the cell being edited. */
+    complete(code, cursor) {
+        const offset = this.#setDocument(code);
+        const prefix = /[\w$]*$/.exec(code.slice(0, cursor))?.[0] ?? "";
+        const info = this.#service.getCompletionsAtPosition(this.#file, offset + cursor, {
+            includeCompletionsForModuleExports: false,
+            includeCompletionsWithInsertText: true,
+        });
+        const ts = this.#ts;
+        const entries = (info?.entries ?? [])
+            .filter((e) => e.kind !== ts.ScriptElementKind.keyword &&
+            // Entries that would edit more than the name (`?.x`, `["a-b"]`).
+            e.insertText === undefined && e.replacementSpan === undefined &&
+            e.name.startsWith(prefix) && !e.name.startsWith("__cdpk"))
+            .sort((a, b) => (a.sortText < b.sortText ? -1 : a.sortText > b.sortText ? 1 : a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+            .map((e) => ({ name: e.name, kind: e.kind }));
+        return { start: cursor - prefix.length, entries };
+    }
+    /**
+     * The type, signature and JSDoc of the name at `cursor`: the one the
+     * cursor is in or just after, or, right after "name(", that callee.
+     */
+    quickInfo(code, cursor) {
+        const offset = this.#setDocument(code);
+        const before = code.slice(0, cursor);
+        const call = /[\w$]\(\s*$/.exec(before);
+        // The name's last character when the cursor is just past it.
+        const position = call ? call.index : /[\w$]/.test(code[cursor - 1] ?? "") ? cursor - 1 : cursor;
+        const info = this.#service.getQuickInfoAtPosition(this.#file, offset + position);
+        if (info === undefined)
+            return null;
+        const ts = this.#ts;
+        // An imported name's "import x" line repeats the cell; alone, the import
+        // didn't resolve. "any" alone is what an undeclared name gets, e.g. a
+        // global a library set at runtime.
+        const display = ts.displayPartsToString(info.displayParts).split("\n").filter((l) => !/^import [\w$]+$/.test(l)).join("\n");
+        if (display === "" || display === "any")
+            return null;
+        const lines = [display];
+        const docs = ts.displayPartsToString(info.documentation);
+        if (docs !== "")
+            lines.push(docs);
+        for (const tag of info.tags ?? []) {
+            const text = ts.displayPartsToString(tag.text);
+            lines.push(`@${tag.name}${text === "" ? "" : ` ${text}`}`);
+        }
+        return lines.join("\n");
+    }
+    /** Sets the virtual file to the history plus `code`; returns where `code` starts. */
+    #setDocument(code) {
+        const history = this.#history(new Set(this.#statements(code).flatMap((s) => s.names)));
+        const text = `${PREFIX}${history}\n`;
+        this.#text = text + code;
+        this.#version++;
+        return text.length;
+    }
+    /** The executed cells, minus declarations a later cell (or `seen`) makes again. */
+    #history(seen) {
+        const kept = [];
+        for (let i = this.#cells.length - 1; i >= 0; i--) {
+            const { code, statements } = this.#cells[i];
+            let text = code;
+            // Back to front, so earlier offsets stay valid.
+            for (let j = statements.length - 1; j >= 0; j--) {
+                const { start, end, names } = statements[j];
+                if (names.length > 0 && names.every((n) => seen.has(n)))
+                    text = text.slice(0, start) + text.slice(end);
+            }
+            for (const s of statements)
+                for (const n of s.names)
+                    seen.add(n);
+            kept.push(text);
+        }
+        return kept.reverse().join("\n");
+    }
+    #statements(code) {
+        const ts = this.#ts;
+        const sf = ts.createSourceFile("cell.ts", code, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TS);
+        return sf.statements.map((stmt) => ({ start: stmt.pos, end: stmt.end, names: this.#declaredNames(stmt) }));
+    }
+    #declaredNames(stmt) {
+        const ts = this.#ts;
+        const bound = (name) => ts.isIdentifier(name)
+            ? [name.text]
+            : name.elements.flatMap((e) => (ts.isOmittedExpression(e) ? [] : bound(e.name)));
+        if (ts.isVariableStatement(stmt))
+            return stmt.declarationList.declarations.flatMap((d) => bound(d.name));
+        if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt) || ts.isInterfaceDeclaration(stmt) ||
+            ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt)) && stmt.name) {
+            return [stmt.name.text];
+        }
+        if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+            const clause = stmt.importClause;
+            const names = clause.name ? [clause.name.text] : [];
+            const bindings = clause.namedBindings;
+            if (bindings && ts.isNamedImports(bindings))
+                names.push(...bindings.elements.map((e) => e.name.text));
+            if (bindings && ts.isNamespaceImport(bindings))
+                names.push(bindings.name.text);
+            return names;
+        }
+        return [];
+    }
+    /** Where an npm:/jsr: import is installed in the kernel's npm cache, if it is. */
+    #cachedPackage(specifier) {
+        try {
+            const pkg = specifier.startsWith("npm:")
+                ? parsePackageSpecifier(specifier.slice(4))
+                : jsrToNpm(specifier.slice(4));
+            const installer = this.#options.npmCache ?? "npm";
+            const installed = installedPackageDir(pkg, installer, { lockFile: findLockFile(this.#options.notebookDir) });
+            return installed === null ? null : { ...installed, subpath: pkg.subpath };
+        }
+        catch {
+            return null;
+        }
+    }
+    #resolve(name, containingFile) {
+        const ts = this.#ts;
+        const deno = this.#options.deno;
+        // Only what an executed cell imported (or a fetched module imports):
+        // looking a specifier up never makes Deno fetch something new.
+        if (deno !== undefined && !/^(?:\.{0,2}\/|node:)/.test(name) && (this.#imported.has(name) || containingFile.startsWith(deno.root))) {
+            const found = deno.lookup(name);
+            if (found?.kind === "npm") {
+                return ts.resolveModuleName(join(found.dir, found.subpath), containingFile, this.#compilerOptions, this.#resolutionHost, this.#resolutionCache);
+            }
+            const extension = found?.kind === "remote" ? extensionOf(ts, found.path) : undefined;
+            if (found?.kind === "remote" && extension !== undefined) {
+                return { resolvedModule: { resolvedFileName: found.path, extension, isExternalLibraryImport: false } };
+            }
+        }
+        if (this.#options.npmCache !== null && /^(?:npm|jsr):/.test(name)) {
+            const cached = this.#cachedPackage(name);
+            // Resolved as its alias from the cache directory, so package.json
+            // "exports" and "types" apply as for any package.
+            if (cached !== null) {
+                const from = join(cached.dir, "__cdpk__.ts");
+                return ts.resolveModuleName(cached.alias + cached.subpath, from, this.#compilerOptions, this.#resolutionHost, this.#resolutionCache);
+            }
+        }
+        return ts.resolveModuleName(name, containingFile, this.#compilerOptions, this.#resolutionHost, this.#resolutionCache);
+    }
+    #host() {
+        const ts = this.#ts;
+        const file = this.#file;
+        const globalsFile = this.#globalsFile;
+        const deno = this.#options.deno;
+        const virtual = (f) => {
+            if (f === file)
+                return this.#text;
+            if (f === globalsFile)
+                return this.#options.globals;
+            const local = deno?.localFile(f);
+            return local !== undefined ? ts.sys.readFile(local) : this.#virtualTypes.get(f);
+        };
+        return {
+            getCompilationSettings: () => this.#compilerOptions,
+            getProjectVersion: () => `${this.#projectVersion}.${this.#version}`,
+            getScriptFileNames: () => [file, globalsFile, ...this.#virtualTypes.keys(), ...this.#typeFiles],
+            getScriptVersion: (f) => (f === file ? String(this.#version) : "0"),
+            getScriptSnapshot: (f) => {
+                const text = virtual(f) ?? ts.sys.readFile(f);
+                return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+            },
+            getCurrentDirectory: () => this.#options.notebookDir,
+            getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+            fileExists: (f) => f === file || f === globalsFile || this.#virtualTypes.has(f) || deno?.localFile(f) !== undefined || ts.sys.fileExists(f),
+            readFile: (f) => virtual(f) ?? ts.sys.readFile(f),
+            readDirectory: ts.sys.readDirectory,
+            directoryExists: ts.sys.directoryExists,
+            getDirectories: ts.sys.getDirectories,
+            resolveModuleNameLiterals: (literals, containingFile) => literals.map((literal) => this.#resolve(literal.text, containingFile)),
+        };
+    }
+}
+/** The extension TypeScript should load a remote module's path as, if it's one it can. */
+function extensionOf(ts, path) {
+    for (const ext of [ts.Extension.Dts, ts.Extension.Dmts, ts.Extension.Ts, ts.Extension.Mts, ts.Extension.Tsx, ts.Extension.Js, ts.Extension.Mjs, ts.Extension.Jsx]) {
+        if (path.endsWith(ext))
+            return ext;
+    }
+    return undefined;
+}
+/**
+ * Declarations for the names the kernel adds to every target, as in
+ * src/globals.ts. `display` is runtime/display.mjs's path; its sibling
+ * display.d.mts types `jupyter`. Without it (a kernel run from JSR, whose
+ * runtime files aren't local), `jupyter` is untyped.
+ */
+export function kernelGlobals(display) {
+    const jupyter = display === null ? "any" : `import(${JSON.stringify(display)}).JupyterNamespace`;
+    return `declare global {
+  /** The notebook display API: display, md/html/svg templates, image, format, broadcast. */
+  var jupyter: ${jupyter};
+  /** Asks the frontend for a line of input. Null when the frontend didn't allow input for this cell. */
+  function prompt(message?: string, defaultValue?: string, options?: { password?: boolean }): string | null;
+  /** Asks a yes/no question over the Jupyter stdin channel. */
+  function confirm(message?: string): boolean;
+}
+export {};
+`;
+}

package/dist/package.d.ts

@@ -1,11 +1,11 @@
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export declare const RELEASE_DATE = "2026-10-16";
+export declare const RELEASE_DATE = "2026-10-18";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It

package/dist/package.js

@@ -14,13 +14,13 @@ import { join, sep } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 /** Kept equal to package.json and deno.jsonc by test/package.test.ts. */
-export const VERSION = "0.5.0";
+export const VERSION = "0.6.0";
 /**
  * The UTC day this version was released, set with VERSION. The publish
  * workflow refuses a tag unless it's today or yesterday, so it can't go
  * stale: see dependencyCutoff.
  */
-export const RELEASE_DATE = "2026-10-16";
+export const RELEASE_DATE = "2026-10-18";
 /**
  * Deno blocks packages less than 24 hours old (minimum dependency age), so
  * a kernelspec relaunching a release from JSR would fail on release day. It

package/dist/parent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Calls `onGone` once the parent named by JPY_PARENT_PID has exited: its pid
+ * is gone, or this process was reparented. A no-op when the variable is
+ * unset, so a kernel started by hand keeps running; and on Windows, where
+ * ipykernel's variable is a handle, not a pid. A pid that doesn't exist at
+ * start (the server is in another pid namespace) is ignored, leaving only
+ * the reparenting check.
+ */
+export declare function watchParent(onGone: () => void, { env, intervalMs }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    intervalMs?: number | undefined;
+}): () => void;

package/dist/parent.js

@@ -0,0 +1,39 @@
+// The server that started the kernel, watched so a server that dies without
+// shutting the kernel down (SIGKILL, a crash) doesn't leave it running with
+// its runtime and ports (#254). jupyter_server and Ganymede put their pid in
+// JPY_PARENT_PID; ipykernel's ParentPollerUnix polls for the same thing.
+import process from "node:process";
+function exists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: it exists, under another user.
+        return err.code === "EPERM";
+    }
+}
+/**
+ * Calls `onGone` once the parent named by JPY_PARENT_PID has exited: its pid
+ * is gone, or this process was reparented. A no-op when the variable is
+ * unset, so a kernel started by hand keeps running; and on Windows, where
+ * ipykernel's variable is a handle, not a pid. A pid that doesn't exist at
+ * start (the server is in another pid namespace) is ignored, leaving only
+ * the reparenting check.
+ */
+export function watchParent(onGone, { env = process.env, intervalMs = 1000 } = {}) {
+    const parent = Number(env.JPY_PARENT_PID);
+    if (process.platform === "win32" || !Number.isInteger(parent) || parent <= 1)
+        return () => { };
+    const ppid = process.ppid;
+    const checkPid = exists(parent);
+    const timer = setInterval(() => {
+        if (process.ppid === ppid && (!checkPid || exists(parent)))
+            return;
+        clearInterval(timer);
+        onGone();
+    }, intervalMs);
+    // The kernel's sockets keep it running; this mustn't.
+    timer.unref();
+    return () => clearInterval(timer);
+}

package/dist/port-holder.d.ts

@@ -0,0 +1,13 @@
+export interface PortSocket {
+    /** The remote end as hex `address:port`, as /proc prints it. */
+    remote: string;
+    state: string;
+    inode: string;
+}
+/** The sockets in a /proc/net/tcp table whose local port is `port`. */
+export declare function socketsOnPort(table: string, port: number): PortSocket[];
+/**
+ * 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 declare function portHolders(port: number): string[];