beatrina 0.8.7 → 0.9.43

package/bin/pages.mjs

@@ -0,0 +1,81 @@
+// pages.mjs — a session's notebook page outlives an upgrade until the session restarts.
+//
+// The host serves beatrina_V<kernel_build>.html from beside kernel/ on every GET / (host/main.mjs
+// notebookPage). `npm install -g beatrina@<next>` replaces the package folder wholesale, so the
+// only page on disk is the new version's and a session still running the old one answers GET /
+// with the development index ("Beatrina kernel spike") — verified live 2026-09-16 (docs/launch-menu-plan.md
+// L4). Beatrina's installer kept the outgoing page beside the new one for exactly this reason
+// (tools/app/launch.sh); npm does not, so the `beatrina` command keeps the copy itself:
+//
+//   · before it starts the host, the page it is about to serve is copied ONCE per version into
+//     <R_user_dir(app, "cache")>/pages/ (2.6 MB; a .part file renamed into place, so a half-written
+//     copy is never served), and the host reads that folder as its third location;
+//   · `beatrina stop` and every start prune the pages of versions no live session runs and that are
+//     not the installed one — a cache, so nothing is said about it.
+//
+// Pure: the folder is passed in (host/user-dirs.mjs rUserDir is beside the package, not the checkout —
+// identity.mjs's rule), so the tests drive it with a scratch folder.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const PAGE_RE = /^beatrina_V(.+)\.html$/;
+
+/** The page file a build serves: `beatrina_V<version>.html`. */
+export const pageName = (version) => `beatrina_V${version}.html`;
+
+/** The version a cached page file names, or "" when the name is not a page's. */
+export const pageVersion = (name) => (PAGE_RE.exec(name) || [])[1] || "";
+
+/** Where the kept pages live: `<cache dir of the app>/pages`. `dirOf` is rUserDir. */
+export const pagesDir = (app, dirOf) => path.join(dirOf(app, "cache"), "pages");
+
+/**
+ * Keep a copy of `from` in `dir` under its own name, unless one of the same size is already there.
+ * @returns {{outcome: "kept"|"present"|"absent"|"failed", path: string, detail?: string}}
+ */
+export function keepPage({ from, dir }) {
+  const to = path.join(dir, path.basename(from));
+  let size = -1;
+  try { size = fs.statSync(from).size; } catch { return { outcome: "absent", path: to }; }
+  try { if (fs.statSync(to).size === size) return { outcome: "present", path: to }; } catch { /* not there yet */ }
+  const part = `${to}.part`;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.copyFileSync(from, part);
+    fs.renameSync(part, to);
+    return { outcome: "kept", path: to };
+  } catch (e) {
+    try { fs.rmSync(part, { force: true }); } catch { /* nothing to clear */ }
+    return { outcome: "failed", path: to, detail: e.message };
+  }
+}
+
+/**
+ * Remove every kept page whose version is in neither `keep` nor `installed`. A `.part` left by an
+ * interrupted copy goes too. @returns {string[]} the paths removed
+ */
+export function prunePages({ dir, installed, keep = [] }) {
+  const wanted = new Set([installed, ...keep].filter(Boolean));
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch { return []; }
+  const removed = [];
+  for (const name of names) {
+    const version = pageVersion(name.replace(/\.part$/, ""));
+    if (!version || (wanted.has(version) && !name.endsWith(".part"))) continue;
+    try { fs.unlinkSync(path.join(dir, name)); removed.push(path.join(dir, name)); } catch { /* in use, or gone */ }
+  }
+  return removed;
+}
+
+/**
+ * The versions the kept pages must keep serving: what `beatrina status` rows say each LIVE session
+ * runs. A live row that cannot say its build (an older kernel) keeps everything — pruning on a
+ * guess would take a page from under a running session.
+ * @returns {string[]|null} null when nothing may be pruned
+ */
+export function versionsInUse(rows) {
+  const live = rows.filter((r) => r.live);
+  if (live.some((r) => !r.kernel_build)) return null;
+  return [...new Set(live.map((r) => r.kernel_build))];
+}

package/bin/python-setup.mjs

@@ -0,0 +1,207 @@
+// python-setup.mjs — `beatrina python setup`: the interpreter Beatrina manages.
+//
+// Discovery (host/engine-python.mjs detectPython) can only find a Python that
+// already has ipykernel, and on most machines none does — the interpreter is
+// there, the kernel package is not, and the Python engine silently sits out.
+// This command builds the answer discovery looks for FIRST: a virtual
+// environment at `~/.beatrina/python`, created from the best system Python
+// 3.9 or newer the ladder itself would consider, with ipykernel installed
+// (and pandas + matplotlib unless --minimal). Idempotent: an existing, working
+// environment is kept and only the packages are (re)installed, which pip
+// answers with "Requirement already satisfied".
+//
+// Every step is said as it happens, the final line is the interpreter's path,
+// and the one refusal is one sentence. No host import: like cli.mjs this file
+// is tested in the source tree, where `../host/` does not exist; the caller
+// hands in the ladder's candidates.
+
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** The oldest Python `beatrina python setup` will build from. ipykernel 6.x/7.x need 3.9+. */
+export const MIN_PYTHON = Object.freeze([3, 9]);
+/** What the kernel needs; what a notebook usually wants on top. */
+export const MINIMAL_PACKAGES = Object.freeze(["ipykernel"]);
+export const DEFAULT_PACKAGES = Object.freeze(["ipykernel", "pandas", "matplotlib"]);
+/** How long asking a candidate what it is may take. */
+export const DESCRIBE_TIMEOUT_MS = 8000;
+
+/** Where the managed environment lives: `~/.beatrina/python`. */
+export function managedPythonDir(home) {
+  return path.join(home, ".beatrina", "python");
+}
+
+/**
+ * The interpreter inside the managed venv. The same spelling as
+ * host/engine-python.mjs `venvInterpreter` — `bin/python3`, or
+ * `Scripts\python.exe` on Windows — restated here so this file needs no host import.
+ */
+export function managedInterpreter(home, platform = process.platform) {
+  const dir = managedPythonDir(home);
+  return platform === "win32" ? path.win32.join(dir, "Scripts", "python.exe") : path.join(dir, "bin", "python3");
+}
+
+/** "3.14.4" → [3, 14, 4]; anything unparseable → null. */
+export function parseVersion(text) {
+  const m = String(text ?? "").trim().match(/^(\d+)\.(\d+)(?:\.(\d+))?/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)] : null;
+}
+
+/** Is `version` (a string or a triple) at least MIN_PYTHON? */
+export function meetsMinimum(version) {
+  const v = Array.isArray(version) ? version : parseVersion(version);
+  if (!v) return false;
+  return v[0] > MIN_PYTHON[0] || (v[0] === MIN_PYTHON[0] && v[1] >= MIN_PYTHON[1]);
+}
+
+const DESCRIBE_SCRIPT = "import json,sys\n"
+  + "out={'version':'.'.join(str(x) for x in sys.version_info[:3]),'executable':sys.executable,"
+  + "'base':sys.prefix==getattr(sys,'base_prefix',sys.prefix),'venv_ok':True,'has_kernel':True}\n"
+  + "for m in ('venv','ensurepip'):\n"
+  + "    try:\n        __import__(m)\n    except Exception:\n        out['venv_ok']=False\n"
+  + "for m in ('ipykernel','jupyter_client'):\n"
+  + "    try:\n        __import__(m)\n    except Exception:\n        out['has_kernel']=False\n"
+  + "print(json.dumps(out))\n";
+
+/**
+ * Ask one interpreter what it is: its version, whether it is a base install
+ * (not itself a venv), whether it can make a venv, whether it already has the
+ * kernel. `null` when it does not answer.
+ * @returns {{version: string, executable: string, base: boolean, venv_ok: boolean, has_kernel: boolean}|null}
+ */
+export function describePython(bin, { timeoutMs = DESCRIBE_TIMEOUT_MS } = {}) {
+  const r = spawnSync(bin, ["-c", DESCRIBE_SCRIPT], { encoding: "utf8", timeout: timeoutMs });
+  if (r.error || r.status !== 0) return null;
+  try { return JSON.parse(String(r.stdout).trim().split("\n").pop()); } catch { return null; }
+}
+
+/** Is `file` inside `dir`? */
+function within(file, dir) {
+  const rel = path.relative(dir, file);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Pick the Python to build the environment from.
+ *
+ * The ladder's own candidates, in the ladder's order, minus the managed
+ * environments themselves (an environment cannot be built from the one being
+ * built). Each existing candidate is asked what it is; the first BASE install
+ * of 3.9+ that can make a venv wins, and failing that the first venv of 3.9+
+ * that can — a venv's `python -m venv` builds from its base interpreter, so
+ * that still works, it is just a less direct answer.
+ *
+ * @param {object} opts
+ * @param {Array<{path: string, why: string}>} opts.candidates from host/engine-python.mjs pythonCandidates
+ * @param {string} opts.home
+ * @param {(bin: string) => object|null} [opts.describe]
+ * @param {(p: string) => boolean} [opts.exists]
+ * @returns {{chosen: {path: string, why: string, version: string}|null, considered: Array<object>}}
+ */
+export function chooseBasePython({ candidates, home, describe = describePython, exists = (p) => fs.existsSync(p) }) {
+  const managed = [path.join(home, ".beatrina", "python")];
+  const considered = [];
+  const usable = [];
+  for (const c of candidates) {
+    if (managed.some((dir) => within(c.path, dir))) continue;
+    if (!exists(c.path)) continue;
+    const info = describe(c.path);
+    if (!info) { considered.push({ ...c, detail: "did not answer" }); continue; }
+    const ok = meetsMinimum(info.version) && info.venv_ok;
+    considered.push({ ...c, version: info.version, base: Boolean(info.base), ok,
+      detail: !meetsMinimum(info.version) ? `${info.version}, older than ${MIN_PYTHON.join(".")}` : !info.venv_ok ? `${info.version}, no venv module` : info.version });
+    if (ok) usable.push({ path: c.path, why: c.why, version: info.version, base: Boolean(info.base) });
+    // A candidate list is a PATH of dozens of directories; ten answers is a search.
+    if (considered.length >= 12) break;
+  }
+  const chosen = usable.find((u) => u.base) || usable[0] || null;
+  return { chosen: chosen ? { path: chosen.path, why: chosen.why, version: chosen.version } : null, considered };
+}
+
+/** The one sentence said when nothing can be built from. */
+export const NO_PYTHON_REFUSAL = `No Python ${MIN_PYTHON.join(".")} or newer with the venv module was found on this machine; `
+  + "install Python from https://www.python.org/downloads/ and run `beatrina python setup` again.";
+
+/** Run a program, handing every output line to `log`; resolves to its exit status. */
+export function runLogged(bin, args, { log = console.log, env = process.env, cwd } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { env, cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let rest = { out: "", err: "" };
+    const feed = (key) => (chunk) => {
+      rest[key] += String(chunk);
+      const lines = rest[key].split(/\r?\n/);
+      rest[key] = lines.pop();
+      for (const line of lines) if (line.trim()) log(`    ${line}`);
+    };
+    child.stdout.on("data", feed("out"));
+    child.stderr.on("data", feed("err"));
+    child.on("error", (e) => { log(`    ${e.message}`); resolve(127); });
+    child.on("close", (code) => {
+      for (const key of ["out", "err"]) if (rest[key].trim()) log(`    ${rest[key]}`);
+      resolve(code ?? 1);
+    });
+  });
+}
+
+/**
+ * Create or refresh `~/.beatrina/python`.
+ *
+ * @param {object} opts
+ * @param {string} opts.home                 the user's home (HOME; tests point it at a scratch dir)
+ * @param {Array<{path: string, why: string}>} opts.candidates the ladder's candidates for this env
+ * @param {boolean} [opts.minimal]           ipykernel only
+ * @param {(line: string) => void} [opts.log]
+ * @param {Record<string, string|undefined>} [opts.env] the environment for the child processes
+ * @param {string} [opts.platform]
+ * @param {typeof describePython} [opts.describe]
+ * @param {typeof runLogged} [opts.run]
+ * @param {(p: string) => boolean} [opts.exists]   which candidates exist (tests)
+ * @returns {Promise<{ok: true, interpreter: string, version: string, created: boolean, packages: string[]}
+ *   | {ok: false, refusal: string}>}
+ */
+export async function setupManagedPython({ home, candidates, minimal = false, log = console.log, env = process.env,
+  platform = process.platform, describe = describePython, run = runLogged, exists = (p) => fs.existsSync(p) } = {}) {
+  if (!home) return { ok: false, refusal: "beatrina python setup needs a home directory (HOME is unset)." };
+  const dir = managedPythonDir(home);
+  const interpreter = managedInterpreter(home, platform);
+  const packages = [...(minimal ? MINIMAL_PACKAGES : DEFAULT_PACKAGES)];
+  // Python's own variables would aim the new environment at another install.
+  const childEnv = Object.fromEntries(Object.entries(env).filter(([k]) => !/^(PYTHONHOME|PYTHONPATH|PYTHONSTARTUP|PYTHONEXECUTABLE|VIRTUAL_ENV)$/.test(k)));
+
+  log(`Looking for a Python ${MIN_PYTHON.join(".")} or newer to build from…`);
+  const { chosen, considered } = chooseBasePython({ candidates, home, describe, exists });
+  for (const c of considered) log(`    ${c.ok ? "usable" : "not usable"}: ${c.path} — ${c.detail} (${c.why})`);
+  if (!chosen) return { ok: false, refusal: NO_PYTHON_REFUSAL };
+  log(`Using Python ${chosen.version} at ${chosen.path} (${chosen.why}).`);
+
+  let created = false;
+  const existing = fs.existsSync(interpreter) ? describe(interpreter) : null;
+  if (existing) {
+    log(`${dir} exists (Python ${existing.version}) — keeping it.`);
+  } else {
+    const rebuild = fs.existsSync(dir);
+    log(rebuild ? `${dir} exists but its interpreter does not answer — rebuilding it…` : `Creating the virtual environment at ${dir}…`);
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    const status = await run(chosen.path, ["-m", "venv", ...(rebuild ? ["--clear"] : []), dir], { log, env: childEnv });
+    if (status !== 0 || !fs.existsSync(interpreter)) {
+      return { ok: false, refusal: `python -m venv ${dir} failed (exit ${status}); the messages above say why.` };
+    }
+    created = true;
+  }
+
+  log(`Installing ${packages.join(", ")} into it (pip)…`);
+  const pipStatus = await run(interpreter, ["-m", "pip", "install", "--upgrade", "--disable-pip-version-check", ...packages], { log, env: childEnv });
+  if (pipStatus !== 0) {
+    return { ok: false, refusal: `pip could not install ${packages.join(", ")} (exit ${pipStatus}) — the messages above say why, usually no network; `
+      + `${dir} is kept, run \`beatrina python setup\` again when it is back.` };
+  }
+
+  const after = describe(interpreter);
+  if (!after || !after.has_kernel) {
+    return { ok: false, refusal: `${interpreter} still cannot import ipykernel after the install; the messages above say why.` };
+  }
+  log(`Python for Beatrina: ${interpreter} (Python ${after.version}, ${packages.join(", ")}).`);
+  log("Beatrina looks here first from now on; `beatrina doctor` shows it.");
+  return { ok: true, interpreter, version: after.version, created, packages };
+}

package/bin/runtime-dirs.mjs

@@ -0,0 +1,27 @@
+// runtime-dirs.mjs — where a session's runtime record is written and read, for the CLI.
+// beatrina-names: keep-file — this module reads the older directory and variable on purpose.
+//
+// The rule is host/runtime-dir.mjs's, restated: this module is imported from the checkout
+// too (test/beatrina-sessions, test/npm-shortcut), where `../host` does not exist — the same
+// reason identity.mjs takes `dirOf` as a parameter. test/runtime-dirs.test.mjs pins that the
+// two modules answer identically, so the restatement cannot drift.
+//
+//   write:  ~/.beatrina/run
+//   read:   ~/.beatrina/run, then ~/.carmar/run (a session an older build started)
+//   an explicit BEATRINA_RUNTIME_DIR (or the old CARMAR_RUNTIME_DIR) is read ALONE, so a test's
+//   scratch directory never sees the user's real sessions.
+
+import os from "node:os";
+import path from "node:path";
+
+const explicitDir = (env) => String(env.BEATRINA_RUNTIME_DIR ?? env.CARMAR_RUNTIME_DIR ?? "").trim();
+
+/** @returns {{write: string, read: string[], explicit: boolean}} */
+export function runtimeDirs(env = process.env, home = os.homedir()) {
+  const explicit = explicitDir(env);
+  if (explicit) return { write: explicit, read: [explicit], explicit: true };
+  const current = path.join(home, ".beatrina", "run");
+  return { write: current, read: [current, path.join(home, ".carmar", "run")], explicit: false };
+}
+export const runtimeWriteDir = (env = process.env, home = os.homedir()) => runtimeDirs(env, home).write;
+export const runtimeReadDirs = (env = process.env, home = os.homedir()) => runtimeDirs(env, home).read;

package/bin/sessions.mjs

@@ -1,6 +1,6 @@
 // sessions.mjs — `beatrina status` and `beatrina stop`.
 //
-// A running session writes ~/.carmar/run/kernel-<port>.json (host/main.mjs, 0600) and removes it on a
+// A running session writes ~/.beatrina/run/kernel-<port>.json (host/main.mjs, 0600) and removes it on a
 // clean exit. A record whose /health does not answer is one a session left behind (a crash, a closed
 // laptop). Status lists both kinds and says which is which; stop asks a live session to shut down
 // through POST /shutdown (the same door Session ▸ Quit uses; loopback, no Origin = this user), waits
@@ -12,8 +12,14 @@ import os from "node:os";
 import path from "node:path";
 import { APP_ID, LEGACY_APP_ID } from "./identity.mjs";
 
-// Where host/main.mjs writes its records; CARMAR_RUNTIME_DIR relocates it (tests), as it does for the host.
-export const runtimeDir = (env = process.env) => env.CARMAR_RUNTIME_DIR || path.join(os.homedir(), ".carmar", "run");
+// beatrina-names: keep-start
+// Where host/main.mjs writes its records (~/.beatrina/run since 2026-09-17; ~/.carmar/run before, still
+// READ so a session started by older code or the pip package's legacy scan is not lost). An explicit
+// BEATRINA_RUNTIME_DIR / CARMAR_RUNTIME_DIR relocates it (tests), as it does for the host.
+// beatrina-names: keep-end
+import { runtimeReadDirs, runtimeWriteDir } from "./runtime-dirs.mjs";
+export const runtimeDir = (env = process.env) => runtimeWriteDir(env);
+export const runtimeDirsToRead = (env = process.env) => runtimeReadDirs(env);
 const APPS = new Set([APP_ID, LEGACY_APP_ID]);
 
 async function health(port, timeoutMs = 1500) {
@@ -29,21 +35,35 @@ export const sameSession = (h, rec) => Boolean(h && h.host === rec.host
   && Number.isFinite(Number(h.started)) && Math.abs(Number(h.started) * 1000 - Date.parse(rec.started)) < 1000);
 
 /** Every Beatrina session this user has a record of, live or left behind, by port. */
-export async function listSessions({ dir = runtimeDir(), apps = APPS } = {}) {
-  let names = [];
-  try { names = fs.readdirSync(dir).filter((n) => /^kernel-\d+\.json$/.test(n)); } catch { return []; }
-  const rows = await Promise.all(names.map(async (name) => {
-    const record = path.join(dir, name);
+export async function listSessions({ dir = null, dirs = dir ? [dir] : runtimeDirsToRead(), apps = APPS } = {}) {
+  // Current directory first; a port seen there hides the same port in a legacy directory.
+  const records = new Map();
+  for (const d of dirs) {
+    let names = [];
+    try { names = fs.readdirSync(d).filter((n) => /^kernel-\d+\.json$/.test(n)); } catch { continue; }
+    for (const name of names) if (!records.has(name)) records.set(name, path.join(d, name));
+  }
+  const rows = await Promise.all([...records.values()].map(async (record) => {
     let rec;
     try { rec = JSON.parse(fs.readFileSync(record, "utf8")); } catch { return null; }
     if (!apps.has(rec.app)) return null;
     const h = await health(rec.port);
     const live = sameSession(h, rec);
-    return { port: Number(rec.port), pid: rec.pid, started: rec.started || "", document: rec.document || "", url: rec.url || "", file: rec.file || "", app: rec.app, live, record };
+    // `documents` is the session's own label of what it holds ("a.qmd + 1 more", host/main.mjs
+    // onSessionDocuments); `document` is what it was started with. `kernel_build` / `installed_build`
+    // are /health's, present only while the session answers: which version it runs, and which is on
+    // disk beside it — a session outlives an upgrade until it restarts.
+    return { port: Number(rec.port), pid: rec.pid, started: rec.started || "", document: rec.document || "", documents: rec.documents || "",
+      title: rec.title || "", url: rec.url || "", file: rec.file || "", app: rec.app, host: rec.host || "", live, record,
+      kernel_build: live && typeof h.kernel_build === "string" ? h.kernel_build : "",
+      installed_build: live && typeof h.installed_build === "string" ? h.installed_build : "" };
   }));
   return rows.filter(Boolean).sort((a, b) => a.port - b.port);
 }
 
+/** What a row is called by: the session's own documents label when it has one, else what it was started with. */
+export const documentLabel = (r) => r.documents || r.document || "";
+
 /** The status table as lines. */
 export function formatSessions(rows, now = Date.now()) {
   if (!rows.length) return ["No Beatrina session is running."];
@@ -52,7 +72,7 @@ export function formatSessions(rows, now = Date.now()) {
     return Number.isFinite(s) ? (s < 90 ? `${s}s` : s < 5400 ? `${Math.round(s / 60)}m` : `${(s / 3600).toFixed(1)}h`) : "?";
   };
   const table = [["PORT", "PID", "UP", "STATE", "DOCUMENT"],
-    ...rows.map((r) => [String(r.port), String(r.pid ?? ""), r.started ? age(r.started) : "?", r.live ? "running" : "not answering (left behind)", r.document || "—"])];
+    ...rows.map((r) => [String(r.port), String(r.pid ?? ""), r.started ? age(r.started) : "?", r.live ? "running" : "not answering (left behind)", documentLabel(r) || "—"])];
   const widths = table[0].map((_, i) => Math.max(...table.map((row) => row[i].length)));
   return table.map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i]))).join("  "));
 }