super-dsh 0.1.12-a → 0.3.0

package/node_modules/better-dsh/lib/kernel-bridge.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""stdio <-> ZeroMQ bridge for the DASHR REPL.
+
+The host (Node/TS) owns the kernel lifecycle but must not link a native ZMQ
+binding: `zeromq` was a hard npm dependency whose install script compiles C++
+inside the consumer's install transaction (and whose top-level import killed
+the whole plugin when the binding was missing). This process is the only ZMQ
+speaker on the host side; it speaks JSON lines on stdio to Node.
+
+    Node  ──stdio JSON lines──►  kernel-bridge.py  ──pyzmq/jupyter_client──►  ipykernel
+
+Requirements come from the kernel's own environment: `jupyter_client` and
+`pyzmq` are transitive dependencies of the `ipykernel` we provision (see
+`kernel-env.ts`), so nothing extra is fetched from any package manager.
+
+Protocol
+--------
+stdin (one JSON object per line)::
+
+    {"op":"send","channel":"shell"|"control","header":{...},"content":{...}}
+    {"op":"interrupt"}
+    {"op":"shutdown"}
+
+stdout (one JSON object per line)::
+
+    {"ev":"ready"}
+    {"ev":"msg","channel":"shell"|"iopub"|"control"|"stdin","msg":{...}}
+    {"ev":"fatal","message":"..."}
+
+The caller-supplied `header` is passed to `Session.msg` verbatim, so the
+message id the host generated is the id on the wire — parent-matching and
+request/response correlation stay exactly as they were on the raw-socket path.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import sys
+import threading
+
+CHANNELS = ("iopub", "shell", "control", "stdin")
+POLL_SECONDS = 0.2
+
+# Protocol output goes to the real stdout; anything a library prints must never
+# corrupt the byte stream the host parses, so sys.stdout is repointed to stderr.
+_PROTOCOL_OUT = sys.stdout
+sys.stdout = sys.stderr
+
+_write_lock = threading.Lock()
+
+
+def emit(payload: dict) -> None:
+    """Write one protocol line, atomically across the pump threads."""
+    # `default=str`: jupyter_client hands back parsed values (a header `date`
+    # arrives as `datetime`, for instance) that are not JSON-native; the host
+    # only reads msg_id/msg_type/content, so stringifying the rest is lossless
+    # for its purposes and keeps one pump thread from dying on a header field.
+    line = json.dumps(payload, ensure_ascii=False, default=str)
+    with _write_lock:
+        _PROTOCOL_OUT.write(line + "\n")
+        _PROTOCOL_OUT.flush()
+
+
+def _clean(value: object) -> object:
+    """Strip binary buffers: this protocol carries JSON only."""
+    if isinstance(value, dict):
+        return {key: _clean(item) for key, item in value.items() if key != "buffers"}
+    if isinstance(value, (list, tuple)):
+        return [_clean(item) for item in value]
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return value
+
+
+def pump(client, name: str, stop: threading.Event) -> None:
+    """Relay one client channel onto stdout until `stop` is set."""
+    channel = getattr(client, f"{name}_channel")
+    while not stop.is_set():
+        try:
+            message = channel.get_msg(timeout=POLL_SECONDS)
+        except queue.Empty:
+            continue
+        except Exception as error:  # channel torn down, or the socket died
+            if not stop.is_set():
+                emit({"ev": "fatal", "channel": name, "message": f"{type(error).__name__}: {error}"})
+        try:
+            emit({
+                "ev": "msg",
+                "channel": name,
+                "msg": {
+                    "header": message.get("header") or {},
+                    "parent_header": message.get("parent_header") or {},
+                    "content": _clean(message.get("content") or {}),
+                    "metadata": _clean(message.get("metadata") or {}),
+                },
+            })
+        except Exception as error:  # never let one message kill a channel pump
+            sys.stderr.write(f"kernel-bridge: cannot relay {name} message: {type(error).__name__}: {error}\n")
+            sys.stderr.flush()
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        emit({"ev": "fatal", "message": "usage: kernel-bridge.py <connection-file>"})
+        return 2
+
+    try:
+        from jupyter_client import BlockingKernelClient
+    except Exception as error:  # the kernel environment is incomplete
+        emit({"ev": "fatal", "message": f"jupyter_client unavailable: {type(error).__name__}: {error}"})
+        return 3
+
+    try:
+        client = BlockingKernelClient(connection_file=sys.argv[1])
+        client.load_connection_file()
+        client.start_channels()
+    except Exception as error:
+        emit({"ev": "fatal", "message": f"cannot connect to the kernel: {type(error).__name__}: {error}"})
+        return 4
+
+    stop = threading.Event()
+    for name in CHANNELS:
+        threading.Thread(target=pump, args=(client, name, stop), name=f"pump-{name}", daemon=True).start()
+
+    emit({"ev": "ready"})
+
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                request = json.loads(line)
+            except Exception:
+                continue
+            op = request.get("op")
+            if op == "send":
+                channel_name = request.get("channel")
+                if channel_name not in ("shell", "control"):
+                    emit({"ev": "fatal", "message": f"unknown send channel {channel_name!r}"})
+                    continue
+                channel = getattr(client, f"{channel_name}_channel")
+                try:
+                    header = request.get("header") or None
+                    message = client.session.msg(
+                        header["msg_type"] if header else "comm_msg",
+                        content=request.get("content") or {},
+                        header=header,
+                    )
+                    channel.send(message)
+                except Exception as error:
+                    emit({"ev": "fatal", "channel": channel_name, "message": f"send failed: {type(error).__name__}: {error}"})
+            elif op == "interrupt":
+                try:
+                    client.interrupt_kernel()
+                except Exception as error:
+                    emit({"ev": "fatal", "message": f"interrupt failed: {type(error).__name__}: {error}"})
+            elif op == "shutdown":
+                break
+    except (KeyboardInterrupt, BrokenPipeError):
+        pass
+    finally:
+        stop.set()
+        try:
+            client.stop_channels()
+        except Exception:
+            pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/node_modules/better-dsh/lib/kernel-env-D8UOWeji.js

@@ -0,0 +1,195 @@
+import { execFile } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync } from "node:fs";
+import { promisify } from "node:util";
+
+//#region src/kernel-env.ts
+const execFileAsync = promisify(execFile);
+/** The installed package root (where `lib/` and `src/` live): the default home of the managed venv. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** The config value meaning "no explicit interpreter — auto-manage a venv". */
+const AUTO_PYTHON_SENTINEL = "python3";
+/** Preferred CPython version for a managed venv. */
+const DEFAULT_KERNEL_PYTHON_VERSION = "3.11";
+/** Pinned, tested `ipykernel` version (2026-09-02 tested value; upgrade = explicit change + regression). */
+const IPYKERNEL_VERSION = "7.3.0";
+/** Pinned, tested `dill` version. */
+const DILL_VERSION = "0.4.1";
+/** A probe that never imports user modules and reports exactly what we need. */
+const PROBE_CODE = [
+	"import json, sys",
+	"r = {\"version\": sys.version.split()[0], \"ipykernel\": False, \"dill\": False}",
+	"try:",
+	"    import ipykernel  # noqa: F401",
+	"    r[\"ipykernel\"] = True",
+	"except Exception:",
+	"    pass",
+	"try:",
+	"    import dill  # noqa: F401",
+	"    r[\"dill\"] = True",
+	"except Exception:",
+	"    pass",
+	"print(json.dumps(r))"
+].join("\n");
+async function probePython(python) {
+	try {
+		const { stdout } = await execFileAsync(python, ["-c", PROBE_CODE], { timeout: 15e3 });
+		const parsed = JSON.parse(stdout.trim());
+		return {
+			version: typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "unknown",
+			ipykernel: parsed.ipykernel === true,
+			dill: parsed.dill === true
+		};
+	} catch {
+		return null;
+	}
+}
+/** The venv interpreter path for this platform. */
+function venvPythonPath(venvDir) {
+	return process.platform === "win32" ? join(venvDir, "Scripts", "python.exe") : join(venvDir, "bin", "python");
+}
+async function commandExists(cmd) {
+	try {
+		await execFileAsync(cmd, ["--version"], { timeout: 1e4 });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Tool-cache env for uv: caches live NEXT TO the venv (plugin territory), so a read-only home can never block provisioning. */
+function uvToolEnv(venvDir) {
+	const cacheDir = join(dirname(venvDir), ".uv-cache");
+	return {
+		...process.env,
+		UV_CACHE_DIR: cacheDir,
+		UV_PYTHON_INSTALL_DIR: join(cacheDir, "python"),
+		UV_LINK_MODE: "copy"
+	};
+}
+/** uv venv arguments (pure; unit-tested). */
+function uvVenvArgs(venvDir, pythonVersion) {
+	return [
+		"venv",
+		venvDir,
+		"--python",
+		pythonVersion
+	];
+}
+/** python3 -m venv fallback arguments (pure; cache-free by construction). */
+function venvFallbackArgs(venvDir) {
+	return [
+		"-m",
+		"venv",
+		venvDir
+	];
+}
+/** uv pip install arguments with pinned versions (pure; unit-tested). */
+function uvInstallArgs(python) {
+	return [
+		"pip",
+		"install",
+		"--python",
+		python,
+		"--quiet",
+		`ipykernel==${IPYKERNEL_VERSION}`,
+		`dill==${DILL_VERSION}`
+	];
+}
+/** pip install arguments with pinned versions for the venv interpreter (pure). */
+function pipInstallArgs() {
+	return [
+		"-m",
+		"pip",
+		"install",
+		"--quiet",
+		"--disable-pip-version-check",
+		`ipykernel==${IPYKERNEL_VERSION}`,
+		`dill==${DILL_VERSION}`
+	];
+}
+/** Create the venv (when absent) and return its interpreter path. */
+async function createVenv(venvDir, pythonVersion) {
+	const python = venvPythonPath(venvDir);
+	if (existsSync(python)) return python;
+	if (await commandExists("uv")) {
+		mkdirSync(join(dirname(venvDir), ".uv-cache"), { recursive: true });
+		await execFileAsync("uv", uvVenvArgs(venvDir, pythonVersion), {
+			timeout: 12e4,
+			env: uvToolEnv(venvDir)
+		});
+	} else await execFileAsync("python3", venvFallbackArgs(venvDir), { timeout: 12e4 });
+	return python;
+}
+/** Install pinned `ipykernel` + `dill` into the venv interpreter. */
+async function installDeps(python, venvDir) {
+	if (await commandExists("uv")) await execFileAsync("uv", uvInstallArgs(python), {
+		timeout: 18e4,
+		env: uvToolEnv(venvDir)
+	});
+	else await execFileAsync(python, pipInstallArgs(), { timeout: 18e4 });
+}
+/** Provision (or repair) the managed venv so it has `ipykernel` + `dill`. */
+async function ensureVenv(venvDir, pythonVersion, log) {
+	const python = venvPythonPath(venvDir);
+	const existing = existsSync(python) ? await probePython(python) : null;
+	if (existing?.ipykernel === true && existing.dill === true) return python;
+	await createVenv(venvDir, pythonVersion);
+	if (!existsSync(python)) throw new Error(`dashr-repl: managed kernel venv was not created at ${venvDir} (no interpreter at ${python})`);
+	log?.("info", `dashr-repl: provisioning kernel venv at ${venvDir} (ipykernel + dill)`);
+	await installDeps(python, venvDir);
+	return python;
+}
+/**
+* Resolve the kernel interpreter, provisioning a managed venv when no
+* explicit interpreter is configured. Throws when the resolved interpreter
+* cannot run `ipykernel`; a missing `dill` only disables snapshots (warned).
+*/
+async function resolveKernelEnv(options = {}) {
+	const log = options.log;
+	const explicit = options.python !== void 0 && options.python !== "" && options.python !== AUTO_PYTHON_SENTINEL ? options.python : void 0;
+	if (explicit !== void 0) {
+		const probe$1 = await probePython(explicit);
+		if (probe$1 === null) throw new Error(`dashr-repl: kernel python ${JSON.stringify(explicit)} could not be executed — check the path`);
+		if (!probe$1.ipykernel) throw new Error(`dashr-repl: kernel python ${JSON.stringify(explicit)} has no ipykernel — install it (pip install ipykernel) or set python to a managed venv`);
+		if (!probe$1.dill) log?.("warn", `dashr-repl: kernel python ${JSON.stringify(explicit)} has no dill — namespace snapshots are DISABLED (install it: pip install dill)`);
+		return {
+			python: explicit,
+			managed: false,
+			venvDir: void 0,
+			dill: probe$1.dill,
+			ipykernel: true,
+			version: probe$1.version
+		};
+	}
+	const venvDir = options.venvDir ?? join(PACKAGE_ROOT, ".venv-kernel");
+	const python = venvPythonPath(venvDir);
+	if (options.autoInstall === false) {
+		const probe$1 = await probePython(python);
+		if (probe$1 === null || !probe$1.ipykernel) throw new Error(`dashr-repl: managed kernel venv is missing or incomplete at ${venvDir} — run 'npm run kernel:venv' in the dashr package, or set kernelAutoInstall: true (or python to a prepared interpreter)`);
+		if (!probe$1.dill) log?.("warn", `dashr-repl: kernel venv at ${venvDir} has no dill — namespace snapshots are DISABLED (run 'npm run kernel:venv' to reinstall)`);
+		return {
+			python,
+			managed: true,
+			venvDir,
+			dill: probe$1.dill,
+			ipykernel: true,
+			version: probe$1.version
+		};
+	}
+	const resolved = await ensureVenv(venvDir, options.pythonVersion ?? DEFAULT_KERNEL_PYTHON_VERSION, log);
+	const probe = await probePython(resolved);
+	if (probe === null || !probe.ipykernel) throw new Error(`dashr-repl: managed kernel venv at ${venvDir} still has no ipykernel after provisioning — check uv/python3-venv availability and retry`);
+	if (!probe.dill) log?.("warn", `dashr-repl: managed kernel venv at ${venvDir} has no dill after provisioning — namespace snapshots are DISABLED`);
+	return {
+		python: resolved,
+		managed: true,
+		venvDir,
+		dill: probe.dill,
+		ipykernel: true,
+		version: probe.version
+	};
+}
+
+//#endregion
+export { PACKAGE_ROOT as a, uvInstallArgs as c, venvFallbackArgs as d, IPYKERNEL_VERSION as i, uvToolEnv as l, DEFAULT_KERNEL_PYTHON_VERSION as n, pipInstallArgs as o, DILL_VERSION as r, resolveKernelEnv as s, AUTO_PYTHON_SENTINEL as t, uvVenvArgs as u };

package/node_modules/better-dsh/lib/kernel-env.d.ts

@@ -0,0 +1,80 @@
+//#region src/kernel-env.d.ts
+/**
+ * Kernel environment resolution and provisioning.
+ *
+ * The runtime OWNS the interpreter it spawns: it never trusts a bare
+ * `python3` on the PATH, because that interpreter may lack `ipykernel`
+ * (hard failure — the kernel cannot start) or `dill` (snapshot capability —
+ * silently degrading to no snapshots). Instead it resolves one of two
+ * environments:
+ *
+ * - **Explicit** — `config.python` names a real interpreter (a path, or any
+ *   name other than the bare-`python3` sentinel the default/patch produce).
+ *   It is probed, and a missing `ipykernel` is a loud error while a missing
+ *   `dill` is a loud warning (snapshots disabled).
+ * - **Managed** — no explicit interpreter: the runtime provisions a venv
+ *   UNDER THE PACKAGE (`<packageRoot>/.venv-kernel`, or `config.kernelEnvDir`)
+ *   with `ipykernel` + `dill`, installing it on first use when
+ *   `config.kernelAutoInstall` is on. The venv lives beside the package, NOT
+ *   in `/tmp` (the pre-v0.1.9 dangling-symlink failure mode), so it survives
+ *   the host's tmp reaper and the process restart.
+ *
+ * Provisioning uses `uv` when available (fast, can fetch the pinned CPython
+ * version), falling back to `python3 -m venv` + `ensurepip`. It is idempotent:
+ * a complete venv is reused untouched; a partial one is repaired.
+ * @module dashr/kernel-env
+ */
+/** The installed package root (where `lib/` and `src/` live): the default home of the managed venv. */
+declare const PACKAGE_ROOT: string;
+/** The config value meaning "no explicit interpreter — auto-manage a venv". */
+declare const AUTO_PYTHON_SENTINEL = "python3";
+/** Preferred CPython version for a managed venv. */
+declare const DEFAULT_KERNEL_PYTHON_VERSION = "3.11";
+/** Pinned, tested `ipykernel` version (2026-09-02 tested value; upgrade = explicit change + regression). */
+declare const IPYKERNEL_VERSION = "7.3.0";
+/** Pinned, tested `dill` version. */
+declare const DILL_VERSION = "0.4.1";
+interface KernelEnv {
+  /** Absolute path to the interpreter to spawn (`-m ipykernel_launcher`). */
+  python: string;
+  /** True when this runtime provisioned a venv (vs an explicit interpreter). */
+  managed: boolean;
+  /** The managed venv root, when {@link managed}. */
+  venvDir: string | undefined;
+  /** True when `dill` is importable — snapshot capability is available. */
+  dill: boolean;
+  /** True when `ipykernel` is importable (a hard requirement). */
+  ipykernel: boolean;
+  /** The interpreter's reported version, e.g. `3.11.15`. */
+  version: string;
+}
+interface ResolveKernelEnvOptions {
+  /** `config.python`; the bare sentinel (or absent) selects a managed venv. */
+  python?: string;
+  /** Managed venv directory; defaults to `<packageRoot>/.venv-kernel`. */
+  venvDir?: string;
+  /** Preferred CPython version for the managed venv. */
+  pythonVersion?: string;
+  /** Provision the managed venv when missing/incomplete (default true). */
+  autoInstall?: boolean;
+  /** Logger callback (info on provisioning, warn on degraded snapshot). */
+  log?: (level: 'info' | 'warn', message: string) => void;
+}
+/** Tool-cache env for uv: caches live NEXT TO the venv (plugin territory), so a read-only home can never block provisioning. */
+declare function uvToolEnv(venvDir: string): NodeJS.ProcessEnv;
+/** uv venv arguments (pure; unit-tested). */
+declare function uvVenvArgs(venvDir: string, pythonVersion: string): string[];
+/** python3 -m venv fallback arguments (pure; cache-free by construction). */
+declare function venvFallbackArgs(venvDir: string): string[];
+/** uv pip install arguments with pinned versions (pure; unit-tested). */
+declare function uvInstallArgs(python: string): string[];
+/** pip install arguments with pinned versions for the venv interpreter (pure). */
+declare function pipInstallArgs(): string[];
+/**
+ * Resolve the kernel interpreter, provisioning a managed venv when no
+ * explicit interpreter is configured. Throws when the resolved interpreter
+ * cannot run `ipykernel`; a missing `dill` only disables snapshots (warned).
+ */
+declare function resolveKernelEnv(options?: ResolveKernelEnvOptions): Promise<KernelEnv>;
+//#endregion
+export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, KernelEnv, PACKAGE_ROOT, ResolveKernelEnvOptions, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };

package/node_modules/better-dsh/lib/kernel-env.js

@@ -0,0 +1,3 @@
+import { a as PACKAGE_ROOT, c as uvInstallArgs, d as venvFallbackArgs, i as IPYKERNEL_VERSION, l as uvToolEnv, n as DEFAULT_KERNEL_PYTHON_VERSION, o as pipInstallArgs, r as DILL_VERSION, s as resolveKernelEnv, t as AUTO_PYTHON_SENTINEL, u as uvVenvArgs } from "./kernel-env-D8UOWeji.js";
+
+export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, PACKAGE_ROOT, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };