beatrina 0.8.6 → 0.9.43

package/host/planes/update.mjs

@@ -1,7 +1,7 @@
 // update.mjs — signed product updates: two ops, and a very narrow API.
 //
 // A port of the `update_*` half of spike/serve.R. The updater is a
-// PRODUCT-OWNED SCRIPT injected by the launcher (`CARMAR_UPDATE_SCRIPT`). The
+// PRODUCT-OWNED SCRIPT injected by the launcher (`BEATRINA_UPDATE_SCRIPT`). The
 // browser never supplies a path or a command line: it may name one action from
 // a fixed four-word vocabulary, and the supervisor starts that exact script
 // directly, as an argument vector.
@@ -10,7 +10,7 @@
 // not poll a feed and has no clock of its own — that belongs to the R package's
 // `check_upgrade()`, once a day, at a door the person opened. All this plane
 // can do is read the script's six-field status record and ask it to act, which
-// is why `CARMAR_NO_UPDATE_CHECK=1` holds here trivially: with no script there
+// is why `BEATRINA_NO_UPDATE_CHECK=1` holds here trivially: with no script there
 // is no process, and with a script there is still no feed.
 //
 // Who may ask: page-only in BOTH senses (agentRefused at the seam,
@@ -28,12 +28,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
+import { whichSync } from "../which.mjs";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
 
-const PAGE_ONLY_CLASSES = ["served", "file", "local"];
 const OPS = ["update_status", "update_action"];
 const AGENT_WHY = {
   update_status: "Agents cannot inspect desktop update state.",
-  update_action: "Agents cannot install, defer, or roll back CarmaR.",
+  update_action: "Agents cannot install, defer, or roll back Beatrina.",
 };
 const ACTIONS = ["check", "defer", "install", "rollback"];
 const STATES = ["unknown", "current", "available", "deferred", "installing",
@@ -55,14 +56,6 @@ export function updateRunnerSpec(script, args = [], platform = process.platform)
   return { command: "/bin/sh", args: [script, ...args] };
 }
 
-function whichSync(name) {
-  for (const dir of String(process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
-    const cand = path.join(dir, name);
-    try { fs.accessSync(cand, fs.constants.X_OK); return cand; } catch { /* next */ }
-  }
-  return "";
-}
-
 // eslint-disable-next-line no-control-regex
 const updateText = (x, max = 240) => String(x ?? "").replace(/[\x00-\x1f\x7f]/g, " ").slice(0, max).trim();
 const updateVersion = (x) => {
@@ -74,7 +67,7 @@ export function createPlane({ env, audit }) {
   const job = { proc: null, action: "", started: 0 };
 
   const scriptPath = (deployment) => {
-    const script = env("CARMAR_UPDATE_SCRIPT", "").trim();
+    const script = env("BEATRINA_UPDATE_SCRIPT", "").trim();
     if (deployment.loopback !== true || !script || !fs.existsSync(script)) return "";
     const real = fs.realpathSync(script);
     return updateRunnerSpec(real) ? real : "";

package/host/plugin-store.mjs

@@ -9,8 +9,8 @@
 //
 // Three layers, searched in order, exactly as .libPaths() is:
 //
-//   user     R_user_dir("carmar","data")/plugins/<kind>/<id>/   the ONLY layer written
-//   system   $CARMAR_PLUGIN_DIR/<kind>/<id>/                     an administrator's, read-only
+//   user     R_user_dir("beatrina","data")/plugins/<kind>/<id>/   the ONLY layer written
+//   system   $BEATRINA_PLUGIN_DIR/<kind>/<id>/                     an administrator's, read-only
 //   shipped  <kernel>/plugins/<kind>/<id>/                       the bundle's, read-only
 //
 // The first OK copy of an id wins. A BROKEN copy never wins: integrity is
@@ -32,15 +32,20 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { appId } from "./user-dirs.mjs";
+import { appId, rUserDir } from "./user-dirs.mjs";
 
 export const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 export const PLUGIN_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export const PLUGIN_MANIFEST = "plugin.json";
 export const PLUGIN_MANIFEST_MAX_BYTES = 65536;
 export const PLUGIN_FETCH_TIMEOUT_S = 20;
-export const PLUGIN_POLICY_DEFAULT_FILE = "/etc/carmar/plugin-policy.json";
-export const PLUGIN_SYSTEM_DEFAULT_DIR = "/etc/carmar/plugins";
+export const PLUGIN_POLICY_DEFAULT_FILE = "/etc/beatrina/plugin-policy.json";
+export const PLUGIN_SYSTEM_DEFAULT_DIR = "/etc/beatrina/plugins";
+// Where an administrator deployed them for Beatrina 0.8.x: read when the current path is absent.
+// beatrina-names: keep-start
+const LEGACY_PLUGIN_POLICY_FILE = "/etc/carmar/plugin-policy.json";
+const LEGACY_PLUGIN_SYSTEM_DIR = "/etc/carmar/plugins";
+// beatrina-names: keep-end
 
 /** A CROSS-LANGUAGE CONTRACT with `EDITOR_TOKENS` in lib/editor-themes.js. */
 export const THEME_TOKENS = Object.freeze([
@@ -130,8 +135,8 @@ export function cslLooksLikeStyle(file) {
 }
 
 /** The registry a `csl` install fetches by name from. Env-driven, as in R. */
-export const cslIndexUrl = (env) => env("CARMAR_CSL_INDEX_URL", "https://www.zotero.org/styles-files/styles.json");
-export const cslStyleBase = (env) => env("CARMAR_CSL_STYLE_BASE", "https://www.zotero.org/styles/");
+export const cslIndexUrl = (env) => env("BEATRINA_CSL_INDEX_URL", "https://www.zotero.org/styles-files/styles.json");
+export const cslStyleBase = (env) => env("BEATRINA_CSL_STYLE_BASE", "https://www.zotero.org/styles/");
 
 /* ── the kinds table ──────────────────────────────────────────────────────
  *
@@ -288,37 +293,12 @@ export function urlHost(url) {
   return m[0].replace(/^https?:\/\//, "").replace(/:[0-9]+$/, "").toLowerCase();
 }
 
-/**
- * `tools::R_user_dir(pkg, which)`, in JavaScript.
- *
- * The whole plugin store, the CSL index cache and every test that relocates
- * them turn on this function agreeing with R's, so it is a transcription of
- * R 4.5's source rather than a guess: the env var, then XDG, then the
- * platform's own place, then `R/<package>` under it.
- */
-export function rUserDir(pkg, which, env) {
-  const home = os.homedir();
-  const win = process.platform === "win32";
-  const mac = process.platform === "darwin";
-  let p = "";
-  if (which === "data") {
-    p = env("R_USER_DATA_DIR") || env("XDG_DATA_HOME")
-      || (win ? path.join(env("APPDATA"), "R", "data")
-        : mac ? path.join(home, "Library", "Application Support", "org.R-project.R")
-          : path.join(home, ".local", "share"));
-  } else if (which === "cache") {
-    p = env("R_USER_CACHE_DIR") || env("XDG_CACHE_HOME")
-      || (win ? path.join(env("LOCALAPPDATA"), "R", "cache")
-        : mac ? path.join(home, "Library", "Caches", "org.R-project.R")
-          : path.join(home, ".cache"));
-  } else {
-    p = env("R_USER_CONFIG_DIR") || env("XDG_CONFIG_HOME")
-      || (win ? path.join(env("APPDATA"), "R", "config")
-        : mac ? path.join(home, "Library", "Preferences", "org.R-project.R")
-          : path.join(home, ".config"));
-  }
-  return path.join(p, "R", pkg);
-}
+// rUserDir is IMPORTED. Both copies described themselves as faithful
+// transcriptions of R 4.5's tools::R_user_dir, and they had already diverged on
+// the fall-through branch — this one answered "config" where the other answered
+// "cache" for an unrecognised `which`. Two transcriptions of one R function that
+// already disagree is the definition of drift, and host/user-dirs.mjs explains
+// at length why the host must not invent a second layout.
 
 /* ── the administrator's policy ──────────────────────────────────────────── */
 
@@ -333,7 +313,7 @@ export function rUserDir(pkg, which, env) {
  *   network:boolean, kinds:string[], unknown:string[], note:string,
  *   system_dir:string, errors:string[]}}
  */
-export function carmarPluginPolicy(env, {
+export function beatrinaPluginPolicy(env, {
   defaultFile = PLUGIN_POLICY_DEFAULT_FILE, defaultDir = PLUGIN_SYSTEM_DEFAULT_DIR,
 } = {}) {
   const kinds_table = pluginKinds(env);
@@ -344,19 +324,22 @@ export function carmarPluginPolicy(env, {
   let sourcesRaw = null;
   let kindsRaw = null;
   let note = "";
-  let systemDir = env("CARMAR_PLUGIN_DIR", "").trim();
+  let systemDir = env("BEATRINA_PLUGIN_DIR", "").trim();
   if (!systemDir && defaultDir && dirExists(defaultDir)) systemDir = defaultDir;
+  // The older deployment path counts only for the default, never for a caller's own.
+  if (!systemDir && defaultDir === PLUGIN_SYSTEM_DEFAULT_DIR && dirExists(LEGACY_PLUGIN_SYSTEM_DIR)) systemDir = LEGACY_PLUGIN_SYSTEM_DIR;
 
-  let file = env("CARMAR_PLUGIN_POLICY", "").trim();
+  let file = env("BEATRINA_PLUGIN_POLICY", "").trim();
   if (!file && defaultFile && fileExists(defaultFile)) file = defaultFile;
+  if (!file && defaultFile === PLUGIN_POLICY_DEFAULT_FILE && fileExists(LEGACY_PLUGIN_POLICY_FILE)) file = LEGACY_PLUGIN_POLICY_FILE;
   if (file) {
     source = file;
     if (!fileExists(file)) {
-      errors.push(`CARMAR_PLUGIN_POLICY names a file that does not exist: ${file}`);
+      errors.push(`BEATRINA_PLUGIN_POLICY names a file that does not exist: ${file}`);
     } else {
       let doc = null;
       try { doc = JSON.parse(fs.readFileSync(file, "utf8")); }
-      catch (e) { errors.push(`CARMAR_PLUGIN_POLICY is not valid JSON: ${e.message}`); }
+      catch (e) { errors.push(`BEATRINA_PLUGIN_POLICY is not valid JSON: ${e.message}`); }
       if (doc && typeof doc === "object") {
         install = String(doc.install ?? "").trim();
         if (doc.sources != null) sourcesRaw = [].concat(doc.sources).map(String);
@@ -367,9 +350,9 @@ export function carmarPluginPolicy(env, {
       }
     }
   } else {
-    if (env("CARMAR_PLUGIN_INSTALL", "")) { source = "env"; install = env("CARMAR_PLUGIN_INSTALL", "").trim(); }
-    if (env("CARMAR_PLUGIN_SOURCES", "")) { source = "env"; sourcesRaw = policySplit(env("CARMAR_PLUGIN_SOURCES", "")); }
-    if (env("CARMAR_PLUGIN_KINDS", "")) { source = "env"; kindsRaw = policySplit(env("CARMAR_PLUGIN_KINDS", "")); }
+    if (env("BEATRINA_PLUGIN_INSTALL", "")) { source = "env"; install = env("BEATRINA_PLUGIN_INSTALL", "").trim(); }
+    if (env("BEATRINA_PLUGIN_SOURCES", "")) { source = "env"; sourcesRaw = policySplit(env("BEATRINA_PLUGIN_SOURCES", "")); }
+    if (env("BEATRINA_PLUGIN_KINDS", "")) { source = "env"; kindsRaw = policySplit(env("BEATRINA_PLUGIN_KINDS", "")); }
   }
 
   if (!install) install = "user";
@@ -432,11 +415,11 @@ export function pluginDefaultHosts(env) {
 /** The sentence shown when the policy refuses something. */
 export function pluginPolicyReason(policy, what = "install") {
   const base = {
-    install: "This CarmaR is configured so that plugins are not installed by users; the set is fixed by the deployment.",
-    network: "This CarmaR is configured to fetch no plugins from the network; a plugin arrives as a file.",
-    host: `This CarmaR is configured to fetch plugins only from: ${policy.sources.join(", ")}.`,
-    kind: "This CarmaR is configured without that plugin kind.",
-  }[what] || "This CarmaR's plugin policy refuses that.";
+    install: "This Beatrina is configured so that plugins are not installed by users; the set is fixed by the deployment.",
+    network: "This Beatrina is configured to fetch no plugins from the network; a plugin arrives as a file.",
+    host: `This Beatrina is configured to fetch plugins only from: ${policy.sources.join(", ")}.`,
+    kind: "This Beatrina is configured without that plugin kind.",
+  }[what] || "This Beatrina's plugin policy refuses that.";
   return policy.note ? `${base} ${policy.note}` : base;
 }
 
@@ -833,6 +816,6 @@ export function pluginPolicyDisclosure(here, policy, env) {
 /** ONE policy per host process, as serve.R has ONE `plugin_policy`. */
 let cachedPolicy = null;
 export function pluginPolicyOnce(env, opts) {
-  if (!cachedPolicy) cachedPolicy = carmarPluginPolicy(env, opts);
+  if (!cachedPolicy) cachedPolicy = beatrinaPluginPolicy(env, opts);
   return cachedPolicy;
 }

package/host/recent-documents.mjs

@@ -0,0 +1,124 @@
+// recent-documents.mjs — the rules of the machine's list of documents this
+// person opened, with no file system in them.
+//
+// One record per document: `{name, path, when}` — the name a row shows, the
+// ABSOLUTE path a reopen reads, and the millisecond clock of the last time it
+// was opened or saved. Newest first, one row per path, twenty deep.
+//
+// These rules are the page's (lib/recent-files.js), written a second time in
+// the host, and test/recent-documents.test.mjs pins the two equal on the same
+// inputs. The page keeps a cache of the list in its origin's storage and hands
+// it over once per connection (`merge`), so a page and a host that disagreed
+// about what a valid row is, or which of two rows of one path wins, would
+// merge into a list neither of them wrote. Keep the two files in step.
+//
+// Pure: every function takes a list and returns a new one; `now` is a
+// parameter so a test can pin what the clock does.
+
+export const RECENT_DOCUMENTS_MAX = 20;
+const PATH_MAX = 4096;
+const NAME_MAX = 255;
+
+// A POSIX root, a Windows drive (`C:\` or `C:/`) or a UNC share. The kernel
+// hands the page resolved absolute paths, so a relative one is a row that was
+// never openable — a picker's bare filename, a typo — and is dropped.
+const ABSOLUTE_PATH = /^(\/|[A-Za-z]:[\\/]|\\\\)/;
+
+const baseName = (p) => String(p || "").replace(/[\\/]+$/, "").split(/[\\/]/).pop();
+
+/**
+ * One record as the list keeps it, or null when it could not be reopened.
+ *
+ * The path must be absolute, printable and bounded; the name is trimmed,
+ * stripped of line breaks and bounded, and falls back to the path's last
+ * segment; `when` is a positive millisecond clock, else `now`.
+ *
+ * @param {*} entry
+ * @param {number} [now]
+ * @returns {{name:string, path:string, when:number}|null}
+ */
+export function cleanRecentDocument(entry, now = Date.now()) {
+  if (!entry || typeof entry !== "object") return null;
+  const path = typeof entry.path === "string" ? entry.path : "";
+  if (!path || path.length > PATH_MAX || /[\r\n\0]/.test(path) || !ABSOLUTE_PATH.test(path)) return null;
+  const rawName = typeof entry.name === "string" ? entry.name.replace(/[\r\n\0]/g, " ").trim() : "";
+  const name = (rawName || baseName(path) || path).slice(0, NAME_MAX);
+  const clock = Number(entry.when);
+  const when = Number.isFinite(clock) && clock > 0 ? Math.floor(clock) : now;
+  return { name, path, when };
+}
+
+/**
+ * The list as it is kept: invalid rows dropped, one row per path — the one
+ * with the newest `when` wins, and on a tie the one that came FIRST — newest
+ * first, capped at RECENT_DOCUMENTS_MAX.
+ *
+ * The tie rule is what makes `note` deterministic: a row just noted is put in
+ * front with the clock's value, and two notes within one millisecond keep
+ * their order rather than being re-sorted by path. The sort is stable, so
+ * rows of one `when` keep the order they arrived in.
+ *
+ * @param {Array} list
+ * @param {number} [now]
+ * @returns {Array<{name:string, path:string, when:number}>}
+ */
+export function cleanRecentDocuments(list, now = Date.now()) {
+  const byPath = new Map();
+  (Array.isArray(list) ? list : []).forEach((raw) => {
+    const row = cleanRecentDocument(raw, now);
+    if (!row) return;
+    const have = byPath.get(row.path);
+    if (!have || row.when > have.when) byPath.set(row.path, row);
+  });
+  return [...byPath.values()].sort((a, b) => b.when - a.when).slice(0, RECENT_DOCUMENTS_MAX);
+}
+
+/** How many rows of `list` `cleanRecentDocuments` would drop as unopenable. */
+export function countUnopenable(list, now = Date.now()) {
+  return (Array.isArray(list) ? list : []).filter((raw) => !cleanRecentDocument(raw, now)).length;
+}
+
+/**
+ * Remember a document: it goes to the top, stamped `now`, and any older row
+ * of the same path goes.
+ *
+ * @param {Array} list
+ * @param {{name?:string, path:string}} document
+ * @param {number} [now]
+ */
+export function noteRecentDocument(list, document, now = Date.now()) {
+  const row = cleanRecentDocument({ ...(document || {}), when: now }, now);
+  if (!row) return cleanRecentDocuments(list, now);
+  return cleanRecentDocuments([row, ...(Array.isArray(list) ? list : [])], now);
+}
+
+/**
+ * Drop one path. Clearing the whole list was the only deletion once, so a
+ * document that had moved could be removed only by throwing away the others.
+ *
+ * @param {Array} list
+ * @param {string} path
+ * @param {number} [now]
+ */
+export function forgetRecentDocument(list, path, now = Date.now()) {
+  const gone = String(path || "");
+  return cleanRecentDocuments(list, now).filter((row) => row.path !== gone);
+}
+
+/**
+ * Two lists as one: every path of either, the newer row of each, newest
+ * first, capped. `a` comes first so that on a tie of `when` its row wins —
+ * the host passes the machine's list as `a` and a page's cache as `b`.
+ *
+ * @param {Array} a
+ * @param {Array} b
+ * @param {number} [now]
+ */
+export function mergeRecentDocuments(a, b, now = Date.now()) {
+  return cleanRecentDocuments([...(Array.isArray(a) ? a : []), ...(Array.isArray(b) ? b : [])], now);
+}
+
+export default {
+  RECENT_DOCUMENTS_MAX, cleanRecentDocument, cleanRecentDocuments, countUnopenable,
+  noteRecentDocument, forgetRecentDocument, mergeRecentDocuments,
+};

package/host/runtime-dir.mjs

@@ -0,0 +1,47 @@
+// runtime-dir.mjs — where a running kernel leaves its `kernel-<port>.json`.
+// beatrina-names: keep-file — this module reads the older directory on purpose.
+//
+// The product's runtime directory is `~/.beatrina/run` (`BEATRINA_RUNTIME_DIR`
+// names another; `CARMAR_RUNTIME_DIR` is still accepted, host/env-names.mjs).
+// Until 2026-09-16 it was `~/.carmar/run`, and a kernel started by an older
+// launcher, or one still running from before the rename, wrote its record
+// THERE. So the two questions have two answers:
+//
+//   · WRITE goes to one directory: the explicit one, else `~/.beatrina/run`.
+//   · READ (the Sessions pane, `beatrina status`/`stop`, the MCP bridge's
+//     discovery) covers both, the current first, so a session is never lost
+//     to the rename. An EXPLICIT directory is read alone: a test that
+//     relocates the records must not see the user's real sessions.
+//
+// It is deliberately not keyed on the app id (host/user-dirs.mjs says why: it
+// is how every tool finds every running kernel).
+
+import os from "node:os";
+import path from "node:path";
+import { readEnv } from "./env-names.mjs";
+
+export const RUNTIME_DIR_CURRENT = [".beatrina", "run"];
+export const RUNTIME_DIR_LEGACY = [".carmar", "run"];
+
+/**
+ * @param {Record<string,string|undefined>|((name: string, unset?: string) => string)} [env]
+ *   process.env, or a `Sys.getenv`-style getter
+ * @param {string} [home]
+ * @returns {{write: string, read: string[], explicit: boolean}}
+ */
+export function runtimeDirs(env = process.env, home = os.homedir()) {
+  const explicit = readEnv(env, "RUNTIME_DIR").trim();
+  if (explicit) return { write: explicit, read: [explicit], explicit: true };
+  const current = path.join(home, ...RUNTIME_DIR_CURRENT);
+  return { write: current, read: [current, path.join(home, ...RUNTIME_DIR_LEGACY)], explicit: false };
+}
+
+/** The one directory a new record is written to. */
+export function runtimeWriteDir(env = process.env, home = os.homedir()) {
+  return runtimeDirs(env, home).write;
+}
+
+/** Every directory a record may be read from, current first. */
+export function runtimeReadDirs(env = process.env, home = os.homedir()) {
+  return runtimeDirs(env, home).read;
+}