beatrina 0.9.43 → 1.0.0

package/host/server.mjs

@@ -82,6 +82,13 @@ export const SAFE_HEADERS = Object.freeze({
 const scalarChr = (x) => typeof x === "string" && x.length > 0;
 const enc = (obj) => JSON.stringify(obj);
 
+/**
+ * The version of the `host-ready` handshake (plans/getting_rid_of_R.md K2). A
+ * page reads `host_protocol` to know which fields it may rely on; it never
+ * replaces `protocol`, which is the worker wire's and gates compatibility.
+ */
+export const HOST_READY_PROTOCOL = 1;
+
 /** Bytes no caller can predict — the OS CSPRNG, never Math.random. */
 export function secureToken(n = 32) {
   const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
@@ -91,6 +98,38 @@ export function secureToken(n = 32) {
   return out;
 }
 
+/**
+ * INSTALL AS AN APP (a Progressive Web App), for whoever wants it: the browser
+ * offers "Install Beatrina Note" (Chrome, Edge) or File ▸ Add to Dock (Safari) and
+ * the page opens in a window of its own — the same page, from the same host,
+ * locally or from a server. Added to the SERVED page only, like the session
+ * stamp: the file on disk is unchanged, so a notebook double-clicked from Finder
+ * behaves exactly as before. The page's CSP admits `manifest-src 'self'` and
+ * nothing more for it — no service worker; Chromium reports the page
+ * installable without one (test/pwa.browser.mjs).
+ */
+export const PWA_HEAD = '<link rel="manifest" href="/manifest.webmanifest">'
+  + '<link rel="icon" type="image/png" sizes="192x192" href="/pwa/icon-192.png">'
+  + '<link rel="apple-touch-icon" href="/pwa/icon-192.png">'
+  + '<meta name="theme-color" content="#1f2937">';
+
+/** The manifest the installed app is made from; `start_url` is the page this host serves. */
+export function pwaManifest(app = "beatrina") {
+  // "Beatrina Note": the page installed from the browser, told apart from Beatrina, the desktop
+  // window (`beatrina app`), in the Dock, the Start menu and the app list.
+  const name = app && app !== "beatrina" ? `${app} Note` : "Beatrina Note";
+  return JSON.stringify({
+    name, short_name: name, description: "A Quarto writer that also runs R, Python and JavaScript.",
+    id: "/", start_url: "/", scope: "/", display: "standalone",
+    background_color: "#ffffff", theme_color: "#1f2937",
+    icons: [
+      { src: "/pwa/icon-192.png", sizes: "192x192", type: "image/png", purpose: "any" },
+      { src: "/pwa/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any" },
+    ],
+  });
+}
+const PWA_ICONS = Object.freeze({ "/pwa/icon-192.png": "icon-192.png", "/pwa/icon-512.png": "icon-512.png" });
+
 /**
  * Stamp the served HTML with this session's identity, once per load — and, for a product other
  * than Beatrina (`app`, BEATRIX_APP_ID: "beatrina"), with which product served it, so the page's
@@ -100,7 +139,7 @@ export function secureToken(n = 32) {
  */
 export function stampSession(html, stamp, app = "") {
   const product = String(app || "").replace(/[^A-Za-z0-9.]/g, "");
-  const meta = `<meta name="beatrina-session" content="${stamp}">${product && product !== "beatrina" ? `<meta name="beatrina-app" content="${product}">` : ""}`;
+  const meta = `<meta name="beatrina-session" content="${stamp}">${product && product !== "beatrina" ? `<meta name="beatrina-app" content="${product}">` : ""}${PWA_HEAD}`;
   let m = html.match(/<head\b[^>]*>/);
   if (!m) m = html.match(/<html\b[^>]*>/);
   if (!m) return meta + html;
@@ -153,6 +192,33 @@ export function createHostServer(opts) {
     } catch { return payload; }
   };
   plane.on("broadcast", (payload) => { const out = strandedNotice(payload); sockets.forEach((r) => r.ws.send(out)); });
+
+  // ── host-ready: the HOST's readiness, independent of every engine (K2) ────
+  // Sent to every socket on open, BEFORE any engine's frame, and again when an
+  // engine's row changes. It carries the host's own verbs — the ones planes
+  // answer with no engine at all (files, journal, settings, …) — so a page
+  // with no R still learns that it may save and recover. It is DISCLOSURE:
+  // who may call a verb is still decided per frame below (gatewayCommands,
+  // AGENT_REFUSED, PAGE_ONLY_CLASSES), never by what this frame lists (K2c).
+  // R's legacy `ready` keeps carrying the same verbs while R runs, so a page
+  // older than this frame still connects to a host that has R (K2).
+  const hostReadyFrame = () => {
+    const newerOnNpm = opts.updateAvailable ? opts.updateAvailable() : null;
+    return enc({
+      type: "host-ready", host_protocol: HOST_READY_PROTOCOL, host: "beatrix", app: opts.app || "beatrina",
+      protocol: opts.protocol, kernel_build: opts.kernelBuild,
+      installed_build: typeof opts.installedBuild === "function" ? opts.installedBuild() : null,
+      ...(newerOnNpm ? { update_available: newerOnNpm } : {}),
+      commands: gatewayCommands(["session_restart", ...commands], gatewayMode),
+      capabilities,
+      // The routing default for a request that names no engine — NOT a
+      // primary: nothing waits for it (K2).
+      default_engine: plane.primaryName || null,
+      engines: typeof plane.engineNames !== "undefined" ? plane.engineNames : [],
+      engine_status: typeof plane.engineRows === "function" ? plane.engineRows() : [],
+    });
+  };
+  plane.on("engines-changed", () => { const out = hostReadyFrame(); sockets.forEach((r) => r.ws.send(out)); });
   // A restore's report is about every object in the session: pages only, never an agent or a native client.
   plane.on("broadcast-pages", (payload) => sockets.filter((r) => PAGE_ONLY_CLASSES.includes(r.class) && r.role === "page").forEach((r) => r.ws.send(payload)));
 
@@ -267,7 +333,9 @@ export function createHostServer(opts) {
       // CORS is granted HERE AND ONLY HERE, so a file page probing for its
       // kernel can read the answer. Booleans and versions only.
       return respond(res, 200, "application/json", enc({
-        ok: true, worker: plane.alive, pending_open: state.pendingOpen != null,
+        // `host_ready`: this host speaks the host-ready handshake, so a probing page need not
+        // wait for `worker` — which is only "R is running", and false forever with no R.
+        ok: true, host_ready: HOST_READY_PROTOCOL, worker: plane.alive, pending_open: state.pendingOpen != null,
         r: rVersion(), started: startedSeconds, protocol: opts.protocol,
         kernel_build: opts.kernelBuild, installed_build: opts.installedBuild(),
         pages: pageRecs().length,
@@ -300,6 +368,17 @@ export function createHostServer(opts) {
     for (const pl of planes) {
       if (typeof pl.http === "function" && pl.http(req, res, pathname, ctx) === true) return undefined;
     }
+    if (pathname === "/manifest.webmanifest") {
+      return respond(res, 200, "application/manifest+json", pwaManifest(opts.app || "beatrina"));
+    }
+    if (Object.prototype.hasOwnProperty.call(PWA_ICONS, pathname)) {
+      // host/pwa beside the kernel directory's parent — the host's own root, in a
+      // checkout and in the npm package alike (never import.meta: host/main.mjs PACKAGING).
+      const icon = path.join(opts.here, "..", "host", "pwa", PWA_ICONS[pathname]);
+      let bytes;
+      try { bytes = fs.readFileSync(icon); } catch { return respond(res, 404, "text/plain", "not found"); }
+      return respond(res, 200, "image/png", bytes);
+    }
     if (pathname === "/" || pathname === "/spike") {
       const page = pathname === "/spike" ? path.join(opts.here, "index.html") : (opts.pagePath() || path.join(opts.here, "index.html"));
       let html;
@@ -333,6 +412,8 @@ export function createHostServer(opts) {
       ws.onPong(() => { rec.lastSeen = Date.now(); });
       state.everConnected = true;
       audit("socket-open", { sockets: sockets.length, class: rec.class, user: rec.user });
+      // The host first: the page may save, recover and edit on this alone.
+      ws.send(hostReadyFrame());
       // The engine announced itself long before this page connected; replay
       // it — and every other engine that has since started, each under its own
       // `engine-ready` (host/engine-pool.mjs replay()).

package/host/worker-plane.mjs

@@ -324,9 +324,15 @@ export class WorkerPlane extends EventEmitter {
     this.audit("restart", { keep: keepTokenOk(resume) });
     this.failRoutes(`${this.label} was restarted — this request was abandoned.`);
     this.expectedExit = true;
+    // Not ready from THIS moment, not after the old process is gone: a command
+    // that arrives while the old engine is being stopped would otherwise be
+    // queued on it and wiped by resetSession() below with no reply at all. With
+    // `hello` cleared the pool holds it until the fresh engine's ready
+    // (EnginePool.whenEngineReady) — measured by test/stop.test.mjs, whose probe
+    // landed in exactly that window once host-ready moved R's ready off frame 0.
+    this.hello = null;
     if (this.engine) await this.engine.stop(1000);
     this.resetSession();
-    this.hello = null;
     this.recovering = false;
     this.restartAttempts = 0;
     this.gaveUp = false;

package/kernel/check/acceptance.mjs

@@ -12,6 +12,10 @@
 //   kept · readline() · file ops and completion while R is busy · Force Stop ·
 //   the terminal · Python and JavaScript chunks when those engines exist.
 //
+// WITH NO R (plans/getting_rid_of_R.md Stage 2) the host is still judged —
+// startup, the document (save, open, list), the terminal, the other engines —
+// and every R area is reported SKIP with the reason, never counted as a pass.
+//
 // Usage
 //   node tools/beatrina/acceptance.mjs                         # this checkout's host
 //   node tools/beatrina/acceptance.mjs --installed             # the installed beatrina package's host
@@ -61,17 +65,44 @@ if (!session.announced) {
   record("startup", "the supervisor announces a URL", "fail", session.log().split("\n").slice(-6).join(" | "));
   await shutdown(1);
 }
-const { frames, until, ready, page } = session;
-if (!ready) { record("startup", "R announces ready", "fail", session.log().slice(-400)); await shutdown(1); }
-record("startup", `R ready (${ready.r || "?"}, worker mode ${ready.mode || "?"})`, "pass", "", session.startupMs, { r: ready.r, mode: ready.mode });
+const { frames, until, ready, page, hostReady, noR } = session;
+if (!ready && !noR) { record("startup", "R announces ready", "fail", session.log().slice(-400)); await shutdown(1); }
+if (noR) {
+  record("startup", "the host is ready with no R (host-ready)", hostReady ? "pass" : "fail", "", session.startupMs);
+  record("startup", "R", "skip", `R is not available: ${noR}. Every R area below is skipped, not passed.`);
+} else {
+  record("startup", `R ready (${ready.r || "?"}, worker mode ${ready.mode || "?"})`, "pass", "", session.startupMs, { r: ready.r, mode: ready.mode });
+}
+/** An R area runs only when R does; otherwise it is ONE skip line with the reason. */
+const wantR = (area) => {
+  if (!want(area)) return false;
+  if (noR) { record(area, `${area} (needs R)`, "skip", noR); return false; }
+  return true;
+};
 
 let seq = 0;
 const text = (id) => session.text(id);
 const run = (source, opts = {}) => session.run(source, opts);
-const engines = Array.isArray(ready.engines) ? ready.engines : ["r"];
+const announced = ready || hostReady;
+const engines = Array.isArray(announced.engines) ? announced.engines : ["r"];
+
+// ── the document: what a person does with no engine at all ──────────────────
+if (want("document")) {
+  const doc = path.join(scratch, "chapter.qmd");
+  const body = "---\ntitle: Acceptance\n---\n\n# Method\n\nWords, saved by the host [@key].\n";
+  const w = await session.ask("writefile", { path: doc, text: body });
+  record("document", "Save writes a .qmd", w.reply && !w.reply.error && fs.readFileSync(doc, "utf8") === body ? "pass" : "fail",
+    w.reply ? (w.reply.error || "") : "no reply", w.ms);
+  const rd = await session.ask("readfile", { path: doc });
+  record("document", "Open reads it back, byte for byte", rd.reply && rd.reply.text === body ? "pass" : "fail",
+    rd.reply ? (rd.reply.error || "") : "no reply", rd.ms);
+  const ls = await session.ask("files", { path: scratch });
+  record("document", "the file browser lists it", ls.reply && !ls.reply.error && JSON.stringify(ls.reply).includes("chapter.qmd") ? "pass" : "fail",
+    ls.reply ? (ls.reply.error || "") : "no reply", ls.ms);
+}
 
 // ── run ──────────────────────────────────────────────────────────────────────
-if (want("run")) {
+if (wantR("run")) {
   const r = await run('keep <- 42; cat("keep=", keep, "\\n")');
   record("run", "a chunk runs and prints", r.done?.status === "ok" && /keep= 42/.test(r.out()) ? "pass" : "fail", r.out().trim(), r.ms);
   const warm = [];
@@ -109,7 +140,7 @@ async function stopCase(label, source, { engine, probe, expect, after = 900, kee
   record("stop", `${label}: interrupted with the session kept, ${REPEAT - misses.length}/${REPEAT}`, misses.length ? "fail" : "pass",
     summary, lat.length ? median(lat) : null, { series: lat, misses: misses.length, repeat: REPEAT });
 }
-if (want("stop")) {
+if (wantR("stop")) {
   const probe = 'cat("keep=", exists("keep") && keep == 42, "\\n")';
   await run("keep <- 42");
   const keep = "keep <- 42";
@@ -119,7 +150,7 @@ if (want("stop")) {
 }
 
 // ── readline ─────────────────────────────────────────────────────────────────
-if (want("readline")) {
+if (wantR("readline")) {
   const id = `r${++seq}`;
   const from = frames.length;
   page.send({ type: "exec", id, source: 'ans <- readline("Your name: "); cat("hello", ans, "\\n")' });
@@ -135,7 +166,7 @@ if (want("readline")) {
 
 // ── while busy ───────────────────────────────────────────────────────────────
 const ask = (type, payload, ms) => session.ask(type, payload, ms);
-if (want("busy")) {
+if (wantR("busy")) {
   fs.writeFileSync(path.join(scratch, "note.txt"), "hello");
   const id = `b${++seq}`;
   const from = frames.length;
@@ -160,7 +191,7 @@ if (want("busy")) {
 }
 
 // ── force stop ───────────────────────────────────────────────────────────────
-if (want("force")) {
+if (wantR("force")) {
   await run("keep <- 42");
   const id = `f${++seq}`;
   const from = frames.length;
@@ -179,7 +210,7 @@ if (want("force")) {
 // R dies under a running chunk (kill -9, as a segfault or the OOM killer would):
 // the chunk must END with a sentence, the page must be told, and a fresh R must
 // answer — never a spinner that waits for a process that is gone.
-if (want("crash")) {
+if (wantR("crash")) {
   const probe = await run('cat("pid=", Sys.getpid(), "\\n")');
   const pid = Number((probe.out().match(/pid= (\d+)/) || [])[1]);
   const id = `c${++seq}`;
@@ -211,7 +242,7 @@ function rssKb(pid) {
   const v = Number(String(r.stdout).trim());
   return Number.isFinite(v) && v > 0 ? v : null;
 }
-if (want("memory")) {
+if (wantR("memory")) {
   const rounds = Math.max(4, Number(argv.memoryRounds || 8));
   const samples = [];
   await run("df <- data.frame(id = seq_len(5000), x = rnorm(5000), g = sample(letters, 5000, TRUE))");
@@ -251,7 +282,7 @@ for (const [engine, setup, probe, sleeper] of [
   ["js", "globalThis.keepJs = 42; console.log('js keep', keepJs)", "console.log('js keep', keepJs)", "for (let i = 0; i < 1e13; i++) {}\nconsole.log('after-stop')"],
 ]) {
   if (!want(engine)) continue;
-  const row = Array.isArray(ready.engine_status) ? ready.engine_status.find((e) => e.engine === engine) : null;
+  const row = Array.isArray(announced.engine_status) ? announced.engine_status.find((e) => e.engine === engine) : null;
   if (!engines.includes(engine)) { record(engine, `${engine} chunks`, "skip", row ? row.detail || "engine not available" : "this host has no such engine"); continue; }
   const first = await run(setup, { engine, ms: 120000 });
   record(engine, `a ${engine} chunk runs (first run starts the engine)`, first.done?.status === "ok" && /keep 42/.test(first.out()) ? "pass" : "fail", first.out().trim() || first.done?.message || "", first.ms);