beatrina 0.8.6

package/bin/failsafe.mjs

@@ -0,0 +1,74 @@
+// failsafe.mjs — start the Node host, and the R supervisor when the host cannot start
+// (docs/beatrina-next-plan.md Stage 4, kept by decision 2026-09-15).
+//
+// The host runs as a CHILD of the command so its failure can be seen: a session is up when the host
+// prints its `{"url": …}` line. Three things count as "the host could not start" and bring up the
+// failsafe: it exits before announcing, it does not announce within the deadline (it is then ended
+// by its PID), or BEATRINA_FORCE_FAILSAFE=1 says to skip it. A host that REFUSES to start — a port
+// that must not move, a policy that forbids something — is not a failure of the host: the R
+// supervisor would refuse the same thing, so that refusal is reported and nothing else starts.
+//
+// The failsafe is the retired R supervisor (retired/r-supervisor/spike/serve.R and the R modules
+// only it loads), staged in the package as failsafe/ and assembled at start into a scratch folder
+// beside a copy of kernel/ and the page, the layout serve.R finds its files in. It is told why it
+// is running (BEATRINA_FAILSAFE_REASON), which its /health repeats and the page shows.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+export const FAILSAFE_R_PACKAGES = Object.freeze(["httpuv", "processx"]);
+const REFUSAL = /refuses to start/;
+
+/** Why a host that exited before announcing did so, from the tail of what it printed. */
+export function exitReason(code, signal, stderrTail) {
+  const lines = String(stderrTail || "").split("\n").map((l) => l.trim()).filter(Boolean);
+  const said = lines.find((l) => /failed to start:/.test(l)) || lines.find((l) => /^[A-Za-z]*Error\b.*:/.test(l)) || lines.at(-1) || "";
+  const how = signal ? `was ended by ${signal}` : `exited with status ${code}`;
+  return `the Node host ${how} before it started${said ? ` (${said.replace(/^Beatrina failed to start:\s*/, "").slice(0, 200)})` : ""}`;
+}
+
+/**
+ * Run a supervisor child, mirroring its output, until it announces its URL, exits, or misses the deadline.
+ * @returns {Promise<{announced: true, child: import("node:child_process").ChildProcess} | {announced: false, refused: boolean, reason: string, code: number|null}>}
+ */
+export function runUntilAnnounced({ cmd, args, env, deadlineMs, spawnImpl = spawn, out = process.stdout, err = process.stderr }) {
+  return new Promise((resolve) => {
+    const child = spawnImpl(cmd, args, { env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const settle = (value) => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
+    child.stdout.on("data", (d) => {
+      out.write(d);
+      if (!settled) { stdout += d; if (/"url"\s*:/.test(stdout)) settle({ announced: true, child }); }
+    });
+    child.stderr.on("data", (d) => { err.write(d); if (!settled) stderr = (stderr + d).slice(-8000); });
+    child.on("error", (e) => settle({ announced: false, refused: false, reason: `the Node host could not be started (${e.message})`, code: null }));
+    child.on("exit", (code, signal) => settle({ announced: false, refused: REFUSAL.test(stderr), reason: exitReason(code, signal, stderr), code }));
+    const timer = setTimeout(() => {
+      settle({ announced: false, refused: false, reason: `the Node host did not start within ${Math.round(deadlineMs / 1000)} seconds`, code: null });
+      try { child.kill("SIGTERM"); } catch { /* gone */ }
+      setTimeout(() => { try { if (child.exitCode == null) child.kill("SIGKILL"); } catch { /* gone */ } }, 3000).unref();
+    }, deadlineMs);
+  });
+}
+
+/** Assemble the R supervisor's folder: <scratch>/kernel = kernel/ + failsafe/, the page beside it. */
+export function stageFailsafe(root, scratchParent = os.tmpdir()) {
+  const failsafe = path.join(root, "failsafe");
+  if (!fs.existsSync(path.join(failsafe, "serve.R"))) throw new Error(`this package carries no failsafe (${failsafe}/serve.R is missing)`);
+  const stage = fs.mkdtempSync(path.join(scratchParent, "beatrina-failsafe-"));
+  fs.cpSync(path.join(root, "kernel"), path.join(stage, "kernel"), { recursive: true });
+  for (const f of fs.readdirSync(failsafe)) fs.copyFileSync(path.join(failsafe, f), path.join(stage, "kernel", f));
+  for (const page of fs.readdirSync(root).filter((f) => /^carmar_V.*\.html$/.test(f))) fs.copyFileSync(path.join(root, page), path.join(stage, page));
+  return { stage, serve: path.join(stage, "kernel", "serve.R") };
+}
+
+/** Relay the stop signals a terminal or `kill` sends to the supervisor child, and exit with its status. */
+export function followChild(child, { onExit = (code) => process.exit(code) } = {}) {
+  const relay = (sig) => () => { try { child.kill(sig); } catch { /* gone */ } };
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, relay(sig));
+  child.on("exit", (code, signal) => onExit(code ?? (signal ? 1 : 0)));
+}

package/bin/identity.mjs

@@ -0,0 +1,45 @@
+// identity.mjs — whose folders a Beatrina session keeps its state in, and the one-time move from
+// the name it had before (Beatrix).
+//
+// The host keys R_user_dir(<app>, data|config|cache) on BEATRIX_APP_ID (host/user-dirs.mjs).
+// Beatrina is "beatrina". Anything a Beatrix build left under R/beatrix is moved across ONCE, the
+// first time a session starts: a folder is renamed only when the new one does not exist yet, so a
+// second start moves nothing and existing Beatrina data is never overwritten. When both exist the
+// old one is left where it is and said so — merging two histories by guess is not a move.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const APP_ID = "beatrina";
+export const LEGACY_APP_ID = "beatrix";
+export const WHICH = Object.freeze(["data", "config", "cache"]);
+
+/**
+ * Move R/beatrix → R/beatrina for each of data, config and cache. `dirOf` is host/user-dirs.mjs
+ * rUserDir (passed in: this module is imported from the checkout too, where ../host does not exist).
+ * @returns {{which: string, from: string, to: string, outcome: "moved"|"absent"|"kept-both"|"failed", detail?: string}[]}
+ */
+export function migrateAppData({ from = LEGACY_APP_ID, to = APP_ID, dirOf }) {
+  return WHICH.map((which) => {
+    const src = dirOf(from, which);
+    const dst = dirOf(to, which);
+    const row = { which, from: src, to: dst };
+    if (!fs.existsSync(src)) return { ...row, outcome: "absent" };
+    if (fs.existsSync(dst)) return { ...row, outcome: "kept-both" };
+    try {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      fs.renameSync(src, dst);
+      return { ...row, outcome: "moved" };
+    } catch (e) {
+      return { ...row, outcome: "failed", detail: e.message };
+    }
+  });
+}
+
+/** What to say about a migration, one line per folder that did something worth saying. */
+export function describeMigration(rows) {
+  return rows.flatMap((r) => r.outcome === "moved" ? [`Moved your Beatrix ${r.which} to ${r.to}.`]
+    : r.outcome === "kept-both" ? [`Both ${r.from} and ${r.to} exist; Beatrina uses ${r.to} and left the old folder untouched.`]
+      : r.outcome === "failed" ? [`Could not move ${r.from} to ${r.to} (${r.detail}); Beatrina starts with ${r.to} and the old folder is untouched.`]
+        : []);
+}

package/bin/prova-post.mjs

@@ -0,0 +1,51 @@
+// prova-post.mjs — send one JUnit report to Prova as a finished run (the sequence of
+// prova/reporters/post-junit.mjs, carried inside the package so `beatrina check` needs nothing else).
+//
+//   POST /runs  →  POST /runs/:id/import/junit  →  POST /runs/:id/finish
+//
+// A failed import marks the run abandoned, so Prova never shows a half-filled run as finished.
+
+import os from "node:os";
+import { spawnSync } from "node:child_process";
+
+export const OS_NAMES = Object.freeze({ darwin: "macos", win32: "windows", linux: "linux" });
+
+/** R's version, asked of R. null when R cannot say. */
+export function rVersionOf(rscript) {
+  const out = spawnSync(rscript, ["--version"], { encoding: "utf8", timeout: 15000 });
+  return /version (\d+\.\d+\.\d+)/.exec(`${out.stdout || ""}${out.stderr || ""}`)?.[1] ?? null;
+}
+
+/** The run body for one check on this machine. */
+export function runBody({ product = "beatrina", build, rVersion, pythonVersion = null, label, platform = process.platform }) {
+  const attributes = { node_version: process.version, ...(rVersion ? { r_version: rVersion } : {}), ...(pythonVersion ? { python_version: pythonVersion } : {}) };
+  return {
+    product, build, producer: "runner", label, host: os.hostname(),
+    environment: { os: OS_NAMES[platform] ?? platform, os_version: os.release(), arch: process.arch, browser: "", attributes },
+  };
+}
+
+export async function postJunitRun({ url, token, body, xml, fetchImpl = fetch }) {
+  const base = `${String(url).replace(/\/+$/, "").replace(/\/api\/v1$/, "")}/api/v1`;
+  const call = async (method, p, { json, raw, type } = {}) => {
+    const headers = { Authorization: `Bearer ${token}` };
+    let payload;
+    if (raw !== undefined) { payload = raw; headers["Content-Type"] = type; } else if (json !== undefined) { payload = JSON.stringify(json); headers["Content-Type"] = "application/json"; }
+    let res;
+    try { res = await fetchImpl(`${base}${p}`, { method, headers, body: payload, signal: AbortSignal.timeout(30000) }); } catch (e) { throw new Error(`${method} ${p} could not reach ${base} (${e.cause?.code || e.message})`); }
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* not JSON */ }
+    if (!res.ok) throw new Error(`${method} ${p} → HTTP ${res.status} ${parsed?.error || text.slice(0, 200)}`);
+    return parsed;
+  };
+  const run = await call("POST", "/runs", { json: body });
+  try {
+    await call("POST", `/runs/${run.run_id}/import/junit`, { raw: xml, type: "application/xml" });
+  } catch (e) {
+    await call("POST", `/runs/${run.run_id}/finish`, { json: { state: "abandoned" } }).catch(() => {});
+    throw e;
+  }
+  const finished = await call("POST", `/runs/${run.run_id}/finish`, { json: { state: "finished" } });
+  return { runId: run.run_id, counts: finished?.counts, url: `${base.replace(/\/api\/v1$/, "")}/runs/${run.run_id}` };
+}

package/bin/sessions.mjs

@@ -0,0 +1,95 @@
+// 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
+// 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
+// for its port to go quiet, and only then — if it is still up — ends its process by the PID its own
+// /health reports. A left-behind record is removed. Nothing is ever killed by name or pattern.
+
+import fs from "node:fs";
+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");
+const APPS = new Set([APP_ID, LEGACY_APP_ID]);
+
+async function health(port, timeoutMs = 1500) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    return res.ok ? await res.json() : null;
+  } catch { return null; }
+}
+
+// A port can be reused by another session after a crash: live means THIS session answers. The
+// record's `started` and /health's `started` are the same boot instant (host/main.mjs bootAt).
+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);
+    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 };
+  }));
+  return rows.filter(Boolean).sort((a, b) => a.port - b.port);
+}
+
+/** The status table as lines. */
+export function formatSessions(rows, now = Date.now()) {
+  if (!rows.length) return ["No Beatrina session is running."];
+  const age = (iso) => {
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    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 || "—"])];
+  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("  "));
+}
+
+const waitUntil = async (test, ms) => {
+  const end = Date.now() + ms;
+  while (Date.now() < end) { if (await test()) return true; await new Promise((r) => setTimeout(r, 150)); }
+  return test();
+};
+
+/** Stop one session. @returns {{port:number, outcome:"stopped"|"killed"|"removed-stale"|"failed", detail?:string}} */
+export async function stopSession(row, { graceMs = 10000, killImpl = process.kill } = {}) {
+  if (!row.live) {
+    try { fs.unlinkSync(row.record); } catch { /* already gone */ }
+    return { port: row.port, outcome: "removed-stale" };
+  }
+  try {
+    await fetch(`http://127.0.0.1:${row.port}/shutdown`, { method: "POST", signal: AbortSignal.timeout(3000) });
+  } catch { /* it may close the connection as it goes */ }
+  if (await waitUntil(async () => !(await health(row.port, 800)), graceMs)) return { port: row.port, outcome: "stopped" };
+  const h = await health(row.port);
+  if (!h) return { port: row.port, outcome: "stopped" };
+  if (!sameSession(h, { host: "beatrix", started: row.started }) || !Number.isInteger(row.pid)) return { port: row.port, outcome: "failed", detail: "it did not stop, and the process on that port could not be confirmed as this session, so nothing was killed" };
+  try { killImpl(row.pid, "SIGTERM"); } catch (e) { return { port: row.port, outcome: "failed", detail: e.message }; }
+  if (await waitUntil(async () => !(await health(row.port, 800)), 5000)) return { port: row.port, outcome: "killed" };
+  return { port: row.port, outcome: "failed", detail: `process ${row.pid} did not end` };
+}
+
+/** Which sessions a `stop` names: --port, --all, or the only one running. */
+export function chooseToStop(rows, { port = "", all = false } = {}) {
+  if (port) {
+    const hit = rows.filter((r) => String(r.port) === String(port));
+    return hit.length ? { rows: hit } : { error: `No Beatrina session on port ${port}.` };
+  }
+  if (all) return { rows };
+  const live = rows.filter((r) => r.live);
+  const stale = rows.filter((r) => !r.live);
+  if (live.length > 1) return { error: `${live.length} Beatrina sessions are running (ports ${live.map((r) => r.port).join(", ")}). Name one with --port, or use --all.` };
+  return { rows: [...live, ...stale] };
+}

package/bin/shortcut.mjs

@@ -0,0 +1,151 @@
+// shortcut.mjs — `beatrina shortcut`: an icon to double-click, and .qmd/.Rmd files that open in Beatrina.
+//
+// After `npm install -g beatrina`, one `beatrina shortcut` makes Beatrina an
+// ordinary desktop app:
+//   · macOS  — ~/Applications/Beatrina.app (an AppleScript applet: no terminal
+//     window), declaring .qmd and .Rmd so Finder's "Open With" offers it, and
+//     registered with Launch Services;
+//   · Windows — a Start-menu shortcut and "Open with" entries for .qmd/.Rmd under
+//     HKCU (no administrator), launched through wscript so no console appears;
+//   · Linux  — a .desktop launcher with the Quarto/R Markdown MIME types.
+// It becomes the DEFAULT app for .qmd only with --default: that changes a choice
+// the user made (RStudio usually holds it), so it is never done by surprise.
+// Windows 10+ keeps the default in a protected UserChoice key no program may
+// set, so there --default says how to choose it instead.
+//
+// Every launch runs `beatrina --from-app [file]`: hand the file to a running
+// Beatrina session if there is one, otherwise start one in the background.
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const BUNDLE_ID = "me.saqr.beatrina";
+export const DOC_TYPES = Object.freeze([
+  { ext: "qmd", name: "Quarto document", mime: "text/x-quarto-markdown" },
+  { ext: "Rmd", name: "R Markdown document", mime: "text/x-r-markdown" },
+]);
+
+const q = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;           // POSIX single-quote
+const asString = (s) => `"${String(s).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/** The AppleScript applet's source. `launch` is the shell command prefix. */
+export function appleScriptSource(launch) {
+  return `on run
+\tdo shell script ${asString(`${launch} --from-app > /dev/null 2>&1 &`)}
+end run
+
+on open theItems
+\trepeat with anItem in theItems
+\t\tdo shell script ${asString(launch)} & " --from-app " & quoted form of (POSIX path of anItem) & " > /dev/null 2>&1 &"
+\tend repeat
+end open
+`;
+}
+
+/** The document types an Info.plist declares, as plutil-insertable XML. */
+export function documentTypesXml() {
+  return `<array>${DOC_TYPES.map((t) => `<dict><key>CFBundleTypeName</key><string>${t.name}</string>`
+    + `<key>CFBundleTypeRole</key><string>Editor</string><key>LSHandlerRank</key><string>Alternate</string>`
+    + `<key>CFBundleTypeExtensions</key><array><string>${t.ext}</string><string>${t.ext.toLowerCase()}</string></array></dict>`).join("")}</array>`;
+}
+
+/** How to start Beatrina from an icon: this Node, this command, and any baked options. */
+export function launchCommand({ node = process.execPath, cli, port = "", noOpen = false }) {
+  return `${q(node)} ${q(cli)}${port ? ` --port ${port}` : ""}${noOpen ? " --no-open" : ""}`;
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", ...opts });
+  if (r.status !== 0) throw new Error(`${cmd} ${args.slice(0, 2).join(" ")} failed: ${(r.stderr || r.stdout || "").trim().split("\n").pop()}`);
+  return r.stdout;
+}
+
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+
+function macShortcut({ cli, dir, port, makeDefault, noOpen }) {
+  const app = path.join(dir || path.join(os.homedir(), "Applications"), "Beatrina.app");
+  fs.mkdirSync(path.dirname(app), { recursive: true });
+  fs.rmSync(app, { recursive: true, force: true });
+  const src = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-app-")), "Beatrina.applescript");
+  fs.writeFileSync(src, appleScriptSource(launchCommand({ cli, port, noOpen })));
+  run("osacompile", ["-o", app, src]);
+  const plist = path.join(app, "Contents", "Info.plist");
+  run("plutil", ["-replace", "CFBundleIdentifier", "-string", BUNDLE_ID, plist]);
+  run("plutil", ["-replace", "CFBundleName", "-string", "Beatrina", plist]);
+  run("plutil", ["-replace", "CFBundleDocumentTypes", "-xml", documentTypesXml(), plist]);
+  run("codesign", ["--force", "--sign", "-", app]);        // the plist changed after osacompile signed it
+  if (fs.existsSync(LSREGISTER)) run(LSREGISTER, ["-f", app]);
+  const said = [`Beatrina.app is in ${path.dirname(app)}. Double-click it, or right-click a .qmd and choose Open With ▸ Beatrina.`];
+  if (makeDefault) {
+    const js = `ObjC.import("CoreServices");
+      const exts = ${JSON.stringify(DOC_TYPES.map((t) => t.ext))};
+      exts.map((ext) => { const uti = $.UTTypeCreatePreferredIdentifierForTag($.kUTTagClassFilenameExtension, $(ext), $()).js;
+        return ext + "=" + $.LSSetDefaultRoleHandlerForContentType($(uti), $.kLSRolesAll, $(${JSON.stringify(BUNDLE_ID)})); }).join(" ");`;
+    const out = run("osascript", ["-l", "JavaScript", "-e", js]).trim();
+    said.push(`Beatrina is now the default app for .qmd and .Rmd (${out}).`);
+  }
+  return { app, said };
+}
+
+function windowsShortcut({ cli, port, makeDefault }) {
+  const data = path.join(process.env.LOCALAPPDATA || os.homedir(), "Beatrina");
+  fs.mkdirSync(data, { recursive: true });
+  const vbs = path.join(data, "beatrina-launch.vbs");
+  // wscript runs node with no console window; the file argument, if any, is passed through.
+  fs.writeFileSync(vbs, `Set sh = CreateObject("WScript.Shell")\r\nargs = ""\r\nIf WScript.Arguments.Count > 0 Then args = " """ & WScript.Arguments(0) & """"\r\n`
+    + `sh.Run """${process.execPath}"" ""${cli}""${port ? ` --port ${port}` : ""} --from-app" & args, 0, False\r\n`);
+  const wscript = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "wscript.exe");
+  const menu = path.join(process.env.APPDATA || os.homedir(), "Microsoft", "Windows", "Start Menu", "Programs", "Beatrina.lnk");
+  const ps = `$s = (New-Object -ComObject WScript.Shell).CreateShortcut('${menu.replace(/'/g, "''")}'); $s.TargetPath = '${wscript}'; `
+    + `$s.Arguments = '"${vbs.replace(/'/g, "''")}"'; $s.Description = 'Beatrina notebooks'; $s.Save()`;
+  run("powershell.exe", ["-NoProfile", "-Command", ps]);
+  for (const t of DOC_TYPES) {
+    const prog = `Beatrina.${t.ext}`;
+    run("reg.exe", ["add", `HKCU\\Software\\Classes\\${prog}\\shell\\open\\command`, "/ve", "/d", `"${wscript}" "${vbs}" "%1"`, "/f"]);
+    run("reg.exe", ["add", `HKCU\\Software\\Classes\\${prog}`, "/ve", "/d", t.name, "/f"]);
+    run("reg.exe", ["add", `HKCU\\Software\\Classes\\.${t.ext}\\OpenWithProgids`, "/v", prog, "/d", "", "/f"]);
+  }
+  const said = ["Beatrina is in the Start menu, and .qmd/.Rmd files list it under Open with."];
+  if (makeDefault) said.push("Windows lets only you choose the default app: right-click a .qmd ▸ Open with ▸ Choose another app ▸ Beatrina ▸ Always.");
+  return { app: menu, said };
+}
+
+function linuxShortcut({ cli, port, makeDefault }) {
+  const apps = path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"), "applications");
+  fs.mkdirSync(apps, { recursive: true });
+  const desktop = path.join(apps, "beatrina.desktop");
+  fs.writeFileSync(desktop, `[Desktop Entry]\nType=Application\nName=Beatrina\nComment=R, Python and JavaScript notebooks\n`
+    + `Exec=${launchCommand({ cli, port })} --from-app %f\nTerminal=false\nMimeType=${DOC_TYPES.map((t) => t.mime).join(";")};\nCategories=Development;Science;\n`);
+  spawnSync("update-desktop-database", [apps]);
+  const said = [`Beatrina is in your applications menu (${desktop}).`];
+  if (makeDefault) {
+    for (const t of DOC_TYPES) spawnSync("xdg-mime", ["default", "beatrina.desktop", t.mime]);
+    said.push("Beatrina is now the default for Quarto and R Markdown files.");
+  }
+  return { app: desktop, said };
+}
+
+/** Make the icon (and, with makeDefault, the default .qmd app). */
+export function makeShortcut({ cli, dir = "", port = "", makeDefault = false, noOpen = false, platform = process.platform }) {
+  if (platform === "darwin") return macShortcut({ cli, dir, port, makeDefault, noOpen });
+  if (platform === "win32") return windowsShortcut({ cli, port, makeDefault });
+  return linuxShortcut({ cli, port, makeDefault });
+}
+
+/** A running session of this app (runtime records + a live /health), or null. */
+export async function liveSession({ app = "beatrina", runtimeDir = process.env.CARMAR_RUNTIME_DIR || path.join(os.homedir(), ".carmar", "run"), port = "" } = {}) {
+  let names = [];
+  try { names = fs.readdirSync(runtimeDir).filter((n) => /^kernel-\d+\.json$/.test(n)); } catch { return null; }
+  for (const name of names) {
+    let rec;
+    try { rec = JSON.parse(fs.readFileSync(path.join(runtimeDir, name), "utf8")); } catch { continue; }
+    if (rec.app !== app || (port && String(rec.port) !== String(port))) continue;
+    try {
+      const res = await fetch(`http://127.0.0.1:${rec.port}/health`, { signal: AbortSignal.timeout(1500) });
+      if (res.ok) return rec;
+    } catch { /* a record the session left behind */ }
+  }
+  return null;
+}

package/bin/update-check.mjs

@@ -0,0 +1,55 @@
+// update-check.mjs — say when a newer Beatrina is on the npm registry; never update anything
+// (docs/beatrina-next-plan.md Stage 3). `beatrina upgrade` (upgrade.mjs) is the explicit door.
+//
+// At most once a day per user (the last check is recorded in a small JSON file, which the host reads
+// back to put `update_available` on /health — host/update-record.mjs), with a short timeout, and never
+// in the way: a registry that cannot be reached, an unpublished package (404) or a garbled answer all
+// mean "nothing to say". BEATRINA_NO_UPDATE_CHECK=1 or CARMAR_NO_UPDATE_CHECK=1 turns it off (the
+// battery runner sets the second). BEATRINA_REGISTRY points at another registry (tests).
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// host/update-record.mjs is the ONE definition of the record and of version order. It sits beside this
+// package (bin/../host) and, in the checkout the tests import from, three levels up — the two layouts
+// identity.mjs meets by having rUserDir passed in; here the module is found instead, so the command
+// and the host cannot drift apart on what "newer" means.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const hostDir = [path.resolve(here, "..", "host"), path.resolve(here, "..", "..", "..", "host")]
+  .find((d) => fs.existsSync(path.join(d, "update-record.mjs")));
+if (!hostDir) throw new Error("update-check.mjs: host/update-record.mjs is neither beside this package nor in the checkout");
+export const { compareVersions, updateAvailable, updateCheckOff, updateRecordFile } = await import(pathToFileURL(path.join(hostDir, "update-record.mjs")).href);
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The registry's `latest` version of beatrina, or null (unreachable, unpublished, garbled). */
+export async function fetchLatest({ env = process.env, fetchImpl = fetch, timeoutMs = 1500 } = {}) {
+  const registry = (env.BEATRINA_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "");
+  try {
+    const res = await fetchImpl(`${registry}/beatrina/latest`, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: "application/json" } });
+    if (!res.ok) return null;
+    const version = (await res.json())?.version;
+    return typeof version === "string" && /^\d+\.\d+\.\d+/.test(version) ? version : null;
+  } catch { return null; }
+}
+
+/** The one sentence a newer version earns, with the door. */
+export const updateNotice = (latest, current) => `Beatrina ${latest} is available (this is ${current}). To upgrade: beatrina upgrade`;
+
+/**
+ * @returns {Promise<string|null>} the sentence to print, or null
+ */
+export async function checkForUpdate({ current, stateFile, env = process.env, now = Date.now(), fetchImpl = fetch, timeoutMs = 1500 }) {
+  if (updateCheckOff(env)) return null;
+  let state = {};
+  try { state = JSON.parse(fs.readFileSync(stateFile, "utf8")); } catch { /* first check */ }
+  if (Number.isFinite(state.checked_at) && now - state.checked_at < DAY_MS) return null;
+  const latest = await fetchLatest({ env, fetchImpl, timeoutMs });
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+    fs.writeFileSync(stateFile, JSON.stringify({ checked_at: now, latest }), { mode: 0o600 });
+  } catch { /* a notice is not worth an error */ }
+  if (!latest || compareVersions(latest, current) <= 0) return null;
+  return updateNotice(latest, current);
+}

package/bin/upgrade.mjs

@@ -0,0 +1,76 @@
+// upgrade.mjs — `beatrina upgrade`: install the newest Beatrina from npm, on request, and say what
+// keeps running on the old one.
+//
+// Beatrina never updates itself (update-check.mjs only SAYS a newer version exists). Typing
+// `beatrina upgrade` is the request: it asks the registry which version is newest, runs
+// `npm install -g beatrina@<that>` through the npm that owns this Node — the one beside
+// process.execPath, so a machine with two Nodes upgrades the copy that is running — and then names
+// every session still on the old version, because an installed file is not a running process: a
+// session keeps the version it started on until it restarts (Session ▾ ▸ Restart in the notebook, or
+// `beatrina stop` then `beatrina`). Already newest: nothing is run. Registry unreachable: said, exit 1,
+// nothing is run. BEATRINA_NPM substitutes the npm program (tests); BEATRINA_REGISTRY the registry.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { compareVersions, fetchLatest } from "./update-check.mjs";
+
+/** The npm that owns this Node: beside process.execPath, else `npm` on PATH; BEATRINA_NPM overrides. */
+export function npmProgram({ env = process.env, execPath = process.execPath, platform = process.platform } = {}) {
+  if (env.BEATRINA_NPM) return env.BEATRINA_NPM;
+  const name = platform === "win32" ? "npm.cmd" : "npm";
+  const beside = path.join(path.dirname(execPath), name);
+  return fs.existsSync(beside) ? beside : name;
+}
+
+/**
+ * What an upgrade should do, as data — pure, so it can be tested without npm.
+ *
+ * @param {{current: string, latest: string|null, sessions?: {port: number, live: boolean}[]}} o
+ * @returns {{action: "install"|"current"|"unknown", target?: string, said: string[], afterwards?: string[]}}
+ */
+export function upgradePlan({ current, latest, sessions = [] }) {
+  if (!latest) {
+    return { action: "unknown", said: ["The npm registry could not be reached, so whether a newer Beatrina exists is not known. "
+      + "Try again when online, or run: npm install -g beatrina@latest"] };
+  }
+  if (compareVersions(latest, current) <= 0) return { action: "current", said: [`Beatrina ${current} is the newest on npm; nothing to do.`] };
+  const live = sessions.filter((s) => s.live);
+  return {
+    action: "install", target: latest,
+    said: [`Beatrina ${latest} is on npm; this is ${current}. Installing it: npm install -g beatrina@${latest}`],
+    afterwards: afterUpgrade({ from: current, to: latest, live }),
+  };
+}
+
+/** What to say once the files are installed: which sessions still run the old version, and the doors out. */
+export function afterUpgrade({ from, to, live }) {
+  const lines = [`Beatrina ${to} is installed.`];
+  if (!live.length) lines.push(`The next beatrina starts on ${to}.`);
+  else {
+    const ports = live.map((s) => s.port).join(", ");
+    lines.push(`${live.length === 1 ? "A session is" : `${live.length} sessions are`} still running on ${from} (port${live.length === 1 ? "" : "s"} ${ports}). `
+      + `In the notebook, Session ▾ ▸ Restart into ${to}; or: beatrina stop, then beatrina.`);
+  }
+  return lines;
+}
+
+/**
+ * The command. Returns the exit code.
+ *
+ * @param {{current: string, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, listSessions?: () => Promise<object[]>, log?: (s: string) => void, err?: (s: string) => void}} o
+ */
+export async function runUpgrade({ current, env = process.env, fetchImpl = fetch, listSessions = async () => [], log = console.log, err = console.error }) {
+  const latest = await fetchLatest({ env, fetchImpl, timeoutMs: 5000 });
+  const sessions = await listSessions();
+  const plan = upgradePlan({ current, latest, sessions });
+  for (const line of plan.said) log(line);
+  if (plan.action === "current") return 0;
+  if (plan.action !== "install") return 1;
+  const npm = npmProgram({ env });
+  const r = spawnSync(npm, ["install", "-g", `beatrina@${plan.target}`], { stdio: "inherit", env, shell: process.platform === "win32" });
+  if (r.error) { err(`beatrina: npm could not be run (${npm}): ${r.error.message}`); return 1; }
+  if (r.status !== 0) { err(`beatrina: npm install failed (exit ${r.status}); the messages above say why. Nothing changed unless npm says it did.`); return r.status ?? 1; }
+  for (const line of plan.afterwards) log(line);
+  return 0;
+}

package/build-info.json

@@ -0,0 +1 @@
+{"version":"0.8.6","commit":"eb036e63b7b3f0e0e1f696d357d701d43235ce6c","dirty":false}