beatrina 0.8.6

package/LICENSE

@@ -0,0 +1,92 @@
+# Carm Research License v1.4
+
+Copyright (c) 2025–2026 Professor Mohammed Saqr, PhD. All rights reserved.
+https://saqr.me | saqr@saqr.me
+
+This License applies to Carm and all associated products, libraries, tools, and components in the Carm ecosystem (collectively, the "Software").
+
+## DEFINITIONS
+
+"Non-commercial use" means use that is not intended for or directed toward commercial advantage or monetary compensation. It includes academic research, teaching and classroom use, personal learning, student coursework, and use by non-profit organizations and NGOs.
+
+Research and teaching carried out at an academic or non-profit institution is non-commercial regardless of how it is funded. Public grants, charitable funding, institutional funding, industry-sponsored or collaboratively funded projects, and industry-sponsored doctoral work all remain within this grant, and nothing here depends on whether or when the results are published.
+
+Use is commercial, and requires a paid license, where the Software is used by or on behalf of a for-profit entity for its own business purposes, is incorporated into a product or service offered for a fee, or is used to deliver paid consulting or contract work. Where the character of a particular use is unclear, contact the copyright holder.
+
+## GRANT FOR RESEARCH AND EDUCATION
+
+Permission is hereby granted, free of charge, to use, copy, and distribute the Software for non-commercial purposes.
+
+This grant is subject to the following conditions: (1) this License, the copyright notice, and the third-party notices required under THIRD-PARTY COMPONENTS shall be included in all copies of the Software; (2) attribution must be provided as set out in ATTRIBUTION AND CITATION below; and (3) the Software may not be sublicensed, resold, or offered as a service without written permission from the copyright holder.
+
+All outputs produced by the Software, including notebooks, reports, tables, charts, exports, and statistical results, are the user's own and may be freely shared, published, distributed, or otherwise used without restriction. The user assumes sole responsibility for the accuracy, interpretation, use, and distribution of such outputs.
+
+The copyright holder makes no representation regarding the correctness, completeness, reproducibility, or suitability of any analyses performed using the Software. Users are solely responsible for validating all results before publication, regulatory submission, clinical use, or other consequential decisions.
+
+## PAID LICENSE REQUIRED
+
+A separate paid license is required for any commercial use, including use in commercial products or services, consulting or contract work that generates revenue, and use by for-profit organizations for their own business purposes.
+
+For the avoidance of doubt, research and teaching at an academic or non-profit institution does not require a paid license by reason of its funding source. Industry-sponsored, collaboratively funded, and jointly funded academic projects fall within the free grant.
+
+Embedding, repurposing, or integrating the Software or its components into other software, platforms, or products requires explicit written approval from the copyright holder, whether or not the resulting work is distributed commercially.
+
+## INTELLECTUAL PROPERTY
+
+The Software, including its source code, algorithms, architecture, design, and documentation, is and shall remain the sole property of Professor Mohammed Saqr, subject only to the rights of third parties in the components identified under THIRD-PARTY COMPONENTS. No rights, title, or interest are transferred except the limited license granted herein.
+
+Reverse engineering, decompilation, disassembly, translation, modification, circumvention of technical protection measures, or any other attempt to derive, reconstruct, or extract the source code, algorithms, architecture, or underlying implementation of the Software is prohibited, except to the extent such restriction is prohibited by applicable law.
+
+Creating derivative works based on the Software, and extracting or reusing any portion of the Software — including individual functions, algorithms, numerical constants, coefficients, or parameter values — in any other software, library, or service, is prohibited without written permission, except to the extent such restriction is prohibited by applicable law.
+
+## MACHINE LEARNING AND AUTOMATED PROCESSING
+
+The Software and its source code may not be used to train, fine-tune, or evaluate machine-learning models, nor incorporated into any dataset assembled for that purpose, without written permission from the copyright holder.
+
+This restriction applies to the Software itself. It does not apply to outputs the user generates by running the Software on the user's own data, which remain governed by the GRANT FOR RESEARCH AND EDUCATION above.
+
+## THIRD-PARTY COMPONENTS
+
+The Software incorporates third-party open-source components that remain the property of their respective authors and are licensed under their own terms. Those terms are reproduced in the distributed artifacts, and nothing in this License limits the rights granted, or the obligations imposed, by them.
+
+As of this version, the distributed CarmNote artifacts incorporate D3.js (https://d3js.org), licensed under the ISC License, Copyright 2010–2026 Mike Bostock and Copyright 2018–2021 Observable, Inc.
+
+## ATTRIBUTION AND CITATION
+
+Any publication or report presenting results generated by the Software must acknowledge it as: "Analysis performed using Carm (https://saqr.me)".
+
+Where the work makes substantive use of CarmNote, the following citation should also be included:
+
+Saqr, M., & Lopez-Pernas, S. (2026). CarmNote: A Portable, Reproducible, Single-File Computational Software Purely in JavaScript. The 26th International Symposium on Computers in Education (SIIE 2026).
+
+## TERMINATION
+
+This License terminates automatically upon violation of its terms. Upon termination, the user must cease all use and destroy all copies.
+
+The DEFINITIONS, INTELLECTUAL PROPERTY, MACHINE LEARNING AND AUTOMATED PROCESSING, THIRD-PARTY COMPONENTS, DISCLAIMER, SEVERABILITY, and GOVERNING LAW sections survive termination of this License.
+
+## AMENDMENTS
+
+The copyright holder reserves the right to amend the terms of this License. Any such amendments shall apply prospectively to copies of the Software obtained or updated after the effective date of the amendment. Prior versions shall remain governed by the License terms in effect at the time of acquisition.
+
+## DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, OR BUSINESS INTERRUPTION, ARISING FROM OR RELATED TO THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE COPYRIGHT HOLDER HAS NO OBLIGATION TO PROVIDE SUPPORT, MAINTENANCE, OR UPDATES.
+
+The Software is under active development and continuous improvement. Features, functionality, interfaces, algorithms, and documentation may be added, modified, improved, or discontinued without notice, and some functionality may be experimental or subject to change. Users are responsible for validating the suitability and accuracy of the Software and any results produced for their intended use.
+
+## SEVERABILITY
+
+If any provision of this License is held invalid or unenforceable in any jurisdiction, that provision shall be modified to the minimum extent necessary to make it enforceable, or severed if modification is not possible. The remaining provisions shall continue in full force and effect, and the invalidity of a provision in one jurisdiction shall not affect its validity in any other.
+
+## GOVERNING LAW
+
+This License is governed by the laws of Finland, excluding its conflict-of-laws rules and the United Nations Convention on Contracts for the International Sale of Goods. The courts of Finland shall have exclusive jurisdiction over any dispute arising under it, without prejudice to any mandatory consumer or statutory protections available to the user under the law of their place of residence.
+
+## CONTACT
+
+For paid licensing, institutional agreements, or inquiries:
+
+Professor Mohammed Saqr, PhD
+https://saqr.me
+saqr@saqr.me

package/NOTICES

@@ -0,0 +1,72 @@
+Beatrina — third-party components
+=================================
+
+Beatrina is distributed under the Carm Research License v1.4 (LICENSE). That licence's
+THIRD-PARTY COMPONENTS section says the components below remain their authors' property under
+their own terms, reproduced here; nothing in the licence limits the rights they grant or the
+obligations they impose. This file is the npm package's counterpart of the R package's AUTHORS
+and LICENSE.note, and records what the package ACTUALLY carries.
+
+What is Beatrina's own
+----------------------
+
+The host (host/), the engines (engines/), the kernel scripts (kernel/), the failsafe supervisor
+(failsafe/), the command (bin/), the acceptance check (check/) and the notebook page
+(carmar_V<version>.html) are written by Mohammed Saqr. The page is one self-contained file built
+from one JavaScript source tree by one author; the notebook shell inside it was written for the
+carmnote-core project (same author) and vendored into this tree on 2026-09-10. No third-party
+JavaScript library is bundled into the page: this was checked at packaging time by inspecting the
+built file for library banners and API surfaces, and the D3.js notice in the licence's
+THIRD-PARTY COMPONENTS section applies to CarmNote artifacts, not to this page, which carries no D3.
+
+Data files from other authors, shipped in this package
+------------------------------------------------------
+
+kernel/plugins/csl/<id>/<id>.csl — six Citation Style Language styles that pandoc reads to format
+citations: APA Style 7th edition (apa), Chicago Manual of Style 18th edition author-date
+(chicago-author-date), Cite Them Right 12th edition Harvard (harvard-cite-them-right), IEEE
+Reference Guide (ieee), MLA Handbook 9th edition (modern-language-association), Nature (nature).
+From the CSL project's style repository, github.com/citation-style-language/styles, licensed
+Creative Commons Attribution-ShareAlike 3.0 (creativecommons.org/licenses/by-sa/3.0/); each file
+names its own authors in its <info> block and carries its <rights> element unchanged. They are
+data, not code, shipped unmodified beside a plugin.json manifest recording each file's SHA-256.
+
+kernel/examples/tna-complete-tutorial.Rmd — the complete tutorial vignette of the tna R package
+(github.com/sonsoleslp/tna, revision 5c08ec9), copied unmodified: MIT License, Copyright (c)
+2025-2026 tna authors. The full licence text is beside it in kernel/examples/NOTICE.md. It is a
+document a person may open; nothing loads or runs it by itself.
+
+Colour values taken from another project
+----------------------------------------
+
+The page carries 34 editor colour palettes whose colour VALUES are taken from the Ace editor's
+theme stylesheets as the RStudio IDE ships them: Ace editor themes, BSD-3-Clause, Copyright (c)
+2010, Ajax.org B.V. (github.com/ajaxorg/ace, src/theme/). No Ace code is included — the palettes
+are data, one object of CSS custom properties per theme, with text colours adjusted where needed
+to reach 4.5:1 contrast. The theme names are the ones RStudio uses so a person can find the one
+they know.
+
+Fetched by npm at install time, not shipped
+-------------------------------------------
+
+node-pty (github.com/microsoft/node-pty), MIT License, Copyright (c) 2012-2015 Christopher
+Jeffrey and Copyright (c) 2016 The xterm.js authors — an OPTIONAL dependency: npm installs its
+prebuilt binary where one exists and the terminal pane runs on pipes where it does not. Its
+licence text arrives with it under node_modules/node-pty/LICENSE.
+
+Fetched by the page at runtime, on the user's request, not shipped
+------------------------------------------------------------------
+
+en_US spelling data — SCOWL (Kevin Atkinson), via the dictionary-en 4.0.0 npm package, fetched
+from cdn.jsdelivr.net when the user turns spell checking on.
+
+@mlc-ai/web-llm 0.2.84 — Apache-2.0, fetched from cdn.jsdelivr.net when the user chooses the
+in-browser (WebGPU) AI provider.
+
+What the engines run on
+-----------------------
+
+The R engine runs the user's own R and needs the CRAN packages jsonlite, knitr and evaluate in the
+user's library (offered for installation on first run; never shipped). The Python engine
+(engines/python) imports only the Python standard library. The JavaScript engine runs on the Node
+that runs Beatrina. None of those runtimes or packages is part of this package.

package/README.md

@@ -0,0 +1,124 @@
+# Beatrina
+
+Beatrina is a modern, powerful, feature-rich integrated development environment (IDE) for R, Python, and JavaScript.
+
+It provides a unified environment for interactive computing, scientific programming, data analysis, and reproducible research. Beatrina runs locally on your computer, providing direct access to your code, computational environment, data, and installed packages.
+
+Beatrina supports R, Python, and JavaScript notebooks, with computation performed locally on your machine.
+
+## Installation
+
+Beatrina requires Node.js 22 or later and R.
+
+```sh
+npm install -g beatrina
+beatrina
+```
+
+On first launch, Beatrina checks for the required R packages:
+
+- jsonlite
+- knitr
+- evaluate
+
+If any are missing, Beatrina offers to install them.
+
+## Command-Line Interface
+
+```sh
+beatrina doctor
+```
+
+Reports the detected development environment, including Node.js, R, required R packages, Python, and the latest Beatrina version available through npm.
+
+```sh
+beatrina status
+```
+
+Displays active Beatrina sessions.
+
+```sh
+beatrina stop
+```
+
+Stops the active Beatrina session.
+
+```sh
+beatrina shortcut
+```
+
+Creates an application icon and configures Open With integration for `.qmd` and `.Rmd` files.
+
+```sh
+beatrina check
+```
+
+Runs the Beatrina acceptance checks on the current machine.
+
+```sh
+beatrina upgrade
+```
+
+Installs the latest version of Beatrina from npm.
+
+```sh
+beatrina --version
+```
+
+Displays the installed Beatrina version.
+
+## Upgrading
+
+When Beatrina starts, it periodically checks npm for a newer version and reports its availability in the terminal and in the notebook.
+
+The available update information can also be found in the notebook under:
+
+- Info → Build
+- Tools ▾ → Doctor
+
+To upgrade:
+
+```sh
+beatrina upgrade
+```
+
+or:
+
+```sh
+npm install -g beatrina@latest
+```
+
+Running sessions continue with the version they were started with. Restart the session from:
+
+- Session ▾ → Restart
+
+or restart Beatrina from the terminal:
+
+```sh
+beatrina stop
+beatrina
+```
+
+Your documents, R packages, and settings are preserved during an upgrade.
+
+To disable the periodic update check:
+
+```sh
+BEATRINA_NO_UPDATE_CHECK=1
+```
+
+## Uninstallation
+
+```sh
+npm uninstall -g beatrina
+```
+
+## License
+
+Beatrina is distributed under the Carm Research License v1.4, provided in the LICENSE file.
+
+The license permits free use for research, teaching, and personal learning. Commercial use requires a paid license.
+
+For commercial licensing, visit https://saqr.me or contact saqr@saqr.me.
+
+The NOTICES file lists the third-party components included with Beatrina and their respective license terms.

package/bin/beatrina.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// beatrina — start a session from the command line (npm install -g beatrina).
+//
+// The host runs in THIS process, in the foreground, as a CLI tool does: Ctrl+C
+// stops the session. Before it starts, three things are checked and said in
+// words: Node is new enough, R is there, and R has the packages the worker needs
+// (asked once, installed from CRAN into the user's own library on yes).
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { USAGE, ask, installRPackages, missingRPackages, parseArgs, REQUIRED_R_PACKAGES } from "./cli.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+const fail = (msg) => { console.error(`beatrina: ${msg}`); process.exit(1); };
+
+let args;
+try { args = parseArgs(process.argv.slice(2)); } catch (e) { fail(e.message); }
+if (args.help) { console.log(USAGE); process.exit(0); }
+if (args.version) { console.log(pkg.version); process.exit(0); }
+
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22) fail(`Beatrina needs Node.js 22 or newer; this is ${process.version}. Update Node from https://nodejs.org.`);
+
+const { APP_ID, describeMigration, migrateAppData } = await import("./identity.mjs");
+
+if (args.command === "status" || args.command === "stop") {
+  const { chooseToStop, formatSessions, listSessions, stopSession } = await import("./sessions.mjs");
+  const rows = await listSessions();
+  if (args.command === "status") {
+    for (const line of formatSessions(rows)) console.log(line);
+    process.exit(0);
+  }
+  const chosen = chooseToStop(rows, { port: args.port, all: args.all });
+  if (chosen.error) fail(chosen.error);
+  if (!chosen.rows.length) { console.log("No Beatrina session is running."); process.exit(0); }
+  let failed = 0;
+  for (const row of chosen.rows) {
+    const done = await stopSession(row);
+    const said = { stopped: `Stopped the session on port ${row.port}.`, killed: `The session on port ${row.port} did not answer the request to stop; its process ${row.pid} was ended.`,
+      "removed-stale": `Removed the record of a session on port ${row.port} that was no longer running.`, failed: `Could not stop the session on port ${row.port}: ${done.detail}` }[done.outcome];
+    if (done.outcome === "failed") { failed += 1; console.error(said); } else console.log(said);
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+if (args.command === "upgrade") {
+  // The explicit door (upgrade.mjs): npm's work, so R is not needed for it.
+  const { runUpgrade } = await import("./upgrade.mjs");
+  const { listSessions } = await import("./sessions.mjs");
+  process.exit(await runUpgrade({ current: pkg.version, listSessions }));
+}
+
+const { detectRscript } = await import("../host/engine-r.mjs");
+const { detectPython } = await import("../host/engine-python.mjs");
+const rscript = detectRscript(process.env.CARMAR_RSCRIPT || "");
+
+if (args.command === "doctor") {
+  const rows = [["Beatrina", `${pkg.version} (${root})`], ["Node.js", `${process.version} at ${process.execPath}`]];
+  {
+    // Whether npm has a newer Beatrina: asked here because doctor IS the question (the once-a-day
+    // check at start is update-check.mjs); switched off by the same variables as that check.
+    const { compareVersions, fetchLatest, updateCheckOff } = await import("./update-check.mjs");
+    const off = updateCheckOff(process.env);
+    const latest = off ? null : await fetchLatest({ timeoutMs: 3000 });
+    rows.push(["npm registry", off ? "the update check is switched off"
+      : !latest ? "not reached — is this machine online?"
+        : compareVersions(latest, pkg.version) > 0 ? `Beatrina ${latest} is available (this is ${pkg.version}) — run: beatrina upgrade`
+          : `${pkg.version} is the newest`]);
+  }
+  if (!rscript) rows.push(["R", "NOT FOUND — install R from https://cran.r-project.org"]);
+  else {
+    rows.push(["R", rscript]);
+    let missing = [];
+    try { missing = missingRPackages(rscript); } catch (e) { missing = [`(${e.message})`]; }
+    rows.push(["R packages", missing.length ? `missing: ${missing.join(", ")} — run beatrina, which offers to install them` : `${REQUIRED_R_PACKAGES.join(", ")}: installed`]);
+  }
+  const py = await detectPython(process.env);
+  rows.push(["Python (optional)", py.available ? `${py.version} at ${py.path}` : py.detail]);
+  let pty = "not installed — the terminal pane runs line programs only";
+  try { await import("node-pty"); pty = "installed — full terminal"; } catch { /* optional */ }
+  rows.push(["node-pty (optional)", pty]);
+  const width = Math.max(...rows.map((r) => r[0].length));
+  for (const [k, v] of rows) console.log(`${k.padEnd(width)}  ${v}`);
+  process.exit(rscript ? 0 : 1);
+}
+
+if (args.command === "check") {
+  // The acceptance check (tools/beatrina/acceptance.mjs, staged as check/) against THIS package's host.
+  if (!rscript) fail("the check needs R and none was found. Install R from https://cran.r-project.org.");
+  const os = await import("node:os");
+  const { spawn } = await import("node:child_process");
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "beatrina-check-"));
+  // BEATRINA_CHECK_JUNIT keeps the report where the caller wants it (fordist/beatrina-windows-check.ps1).
+  const junit = process.env.BEATRINA_CHECK_JUNIT || path.join(scratch, "acceptance.xml");
+  const code = await new Promise((resolve) => {
+    const child = spawn(process.execPath, [path.join(root, "check", "acceptance.mjs"), `--host=${path.join(root, "host", "main.mjs")}`, `--junit=${junit}`],
+      { stdio: "inherit", env: { ...process.env, CARMAR_RSCRIPT: rscript } });
+    child.on("exit", (c) => resolve(c ?? 1));
+    child.on("error", () => resolve(1));
+  });
+  const url = args.prova || process.env.PROVA_URL || "";
+  const token = args.token || process.env.PROVA_TOKEN || "";
+  if (url && token && fs.existsSync(junit)) {
+    const { postJunitRun, rVersionOf, runBody } = await import("./prova-post.mjs");
+    let build = { version: pkg.version, commit: "", dirty: false };
+    try { build = { ...build, ...JSON.parse(fs.readFileSync(path.join(root, "build-info.json"), "utf8")) }; } catch { /* a package without one */ }
+    try {
+      const sent = await postJunitRun({ url, token, xml: fs.readFileSync(junit), body: runBody({ build, rVersion: rVersionOf(rscript), label: `beatrina check on ${process.platform}` }) });
+      console.log(`Sent to Prova: run ${sent.runId} — pass ${sent.counts?.pass ?? "?"} fail ${sent.counts?.fail ?? "?"} skip ${sent.counts?.skip ?? "?"} → ${sent.url}`);
+    } catch (e) { console.error(`beatrina: the results were not sent to Prova: ${e.message}`); }
+  } else if (url || token) console.error("beatrina: to send results to Prova give both --prova <url> and --token <token>.");
+  fs.rmSync(scratch, { recursive: true, force: true });
+  process.exit(code);
+}
+
+if (args.command === "shortcut") {
+  const { makeShortcut } = await import("./shortcut.mjs");
+  try {
+    const made = makeShortcut({ cli: fileURLToPath(import.meta.url), dir: args.dir, port: args.port, makeDefault: args.makeDefault, noOpen: !args.open });
+    for (const line of made.said) console.log(line);
+    process.exit(0);
+  } catch (e) { fail(`the shortcut could not be made: ${e.message}`); }
+}
+
+// Launched from the icon or a double-clicked document: no terminal to talk to.
+// A running Beatrina session takes the file; otherwise one starts in the
+// background, and anything that goes wrong is said in a dialog.
+if (args.fromApp) {
+  const { liveSession } = await import("./shortcut.mjs");
+  const { spawn, spawnSync } = await import("node:child_process");
+  const alert = (msg) => {
+    if (process.platform === "darwin") spawnSync("osascript", ["-e", `display alert "Beatrina" message ${JSON.stringify(msg)}`]);
+    else if (process.platform === "win32") spawnSync("powershell.exe", ["-NoProfile", "-Command", `Add-Type -AssemblyName PresentationFramework; [System.Windows.MessageBox]::Show(${JSON.stringify(msg).replace(/^"|"$/g, "'")}, 'Beatrina')`]);
+    else console.error(msg);
+  };
+  const file = args.file ? path.resolve(args.file) : "";
+  const live = await liveSession({ app: process.env.BEATRIX_APP_ID || APP_ID, port: args.port });
+  if (live) {
+    let delivered = "none";
+    if (file) {
+      try {
+        const res = await fetch(`http://127.0.0.1:${live.port}/open?file=${encodeURIComponent(file)}`, { signal: AbortSignal.timeout(5000) });
+        delivered = res.ok ? (await res.json()).delivered : "refused";
+      } catch { delivered = "refused"; }
+    }
+    // A page already shows the session: the document went there. No page (the
+    // browser was closed): open the session's notebook, which collects it.
+    if (delivered !== "page" && args.open && live.file) {
+      // BEATRINA_OPENER substitutes the program that opens it (test/beatrina-sessions.test.mjs).
+      const opener = process.env.BEATRINA_OPENER ? [process.env.BEATRINA_OPENER, [live.file]]
+        : process.platform === "darwin" ? ["open", [live.file]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", live.file]] : ["xdg-open", [live.file]];
+      spawnSync(opener[0], opener[1]);
+    }
+    if (delivered === "refused") alert(`The running Beatrina session could not open ${file}.`);
+    process.exit(0);
+  }
+  if (!rscript) { alert("Beatrina needs R. Install R from https://cran.r-project.org, then open Beatrina again."); process.exit(1); }
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...(file ? [file] : []), "--yes",
+    ...(args.port ? ["--port", args.port] : []), ...(args.open ? [] : ["--no-open"])], { detached: true, stdio: "ignore", windowsHide: true });
+  child.unref();
+  process.exit(0);
+}
+
+if (!rscript) fail("Beatrina needs R and none was found. Install R from https://cran.r-project.org, or set CARMAR_RSCRIPT to your Rscript.");
+let missing;
+try { missing = missingRPackages(rscript); } catch (e) { fail(e.message); }
+if (missing.length) {
+  const yes = args.yes || process.env.BEATRIX_YES === "1" ? true
+    : await ask(`R is missing ${missing.join(", ")}, which Beatrina needs. Install from CRAN now?`);
+  if (yes === null) fail(`R is missing ${missing.join(", ")}. Run beatrina in a terminal to be asked, or run: beatrina --yes`);
+  if (!yes) fail(`Beatrina cannot start without ${missing.join(", ")}.`);
+  if (!installRPackages(rscript, missing)) fail(`installing ${missing.join(", ")} failed; the messages above say why.`);
+}
+
+// Beatrina's own data folders and port, unless the caller chose otherwise. Data a Beatrix build
+// left under R/beatrix moves across once (identity.mjs).
+if (!process.env.BEATRIX_APP_ID) {
+  process.env.BEATRIX_APP_ID = APP_ID;
+  const { rUserDir } = await import("../host/user-dirs.mjs");
+  for (const line of describeMigration(migrateAppData({ dirOf: rUserDir }))) console.error(`beatrina: ${line}`);
+}
+process.env.CARMAR_RSCRIPT = rscript;
+if (args.port) process.env.CARMAR_PORT = args.port;
+else process.env.CARMAR_PORT ||= "4848";
+if (args.file) {
+  const file = path.resolve(args.file);
+  if (!fs.existsSync(file)) fail(`no such file: ${file}`);
+  process.env.CARMAR_OPEN_FILE = file;
+}
+const open = args.open && process.env.BEATRIX_NO_OPEN !== "1";
+// Once a day: is a newer Beatrina on the registry? Said, never acted on, and never waited for.
+{
+  const { checkForUpdate, updateRecordFile } = await import("./update-check.mjs");
+  checkForUpdate({ current: pkg.version, stateFile: updateRecordFile(APP_ID) })
+    .then((said) => { if (said) console.error(`beatrina: ${said}`); }).catch(() => {});
+}
+const { FAILSAFE_R_PACKAGES, followChild, runUntilAnnounced, stageFailsafe } = await import("./failsafe.mjs");
+const forced = process.env.BEATRINA_FORCE_FAILSAFE === "1";
+const deadlineS = Number(process.env.BEATRINA_HOST_DEADLINE || 60);
+let started = forced
+  ? { announced: false, refused: false, reason: "BEATRINA_FORCE_FAILSAFE=1 asked for it", code: null }
+  : await runUntilAnnounced({ cmd: process.execPath, args: [path.join(root, "host", "main.mjs"), ...(open ? ["--open"] : [])], env: process.env,
+    deadlineMs: (Number.isFinite(deadlineS) && deadlineS > 0 ? deadlineS : 60) * 1000 });
+if (started.announced) followChild(started.child);
+else {
+  if (started.refused) process.exit(started.code ?? 2);
+  // The failsafe: the R supervisor, with the reason said here and on the page.
+  console.error(`beatrina: ${started.reason}. Starting the R supervisor instead (failsafe mode).`);
+  let needed;
+  try { needed = missingRPackages(rscript, FAILSAFE_R_PACKAGES); } catch (e) { fail(e.message); }
+  if (needed.length) {
+    const yes = args.yes || process.env.BEATRIX_YES === "1" ? true : await ask(`The failsafe needs the R packages ${needed.join(", ")}. Install from CRAN now?`);
+    if (!yes || !installRPackages(rscript, needed)) fail(`Beatrina could not start: ${started.reason}, and the failsafe needs ${needed.join(", ")}.`);
+  }
+  let staged;
+  try { staged = stageFailsafe(root); } catch (e) { fail(`Beatrina could not start: ${started.reason}, and ${e.message}.`); }
+  started = await runUntilAnnounced({ cmd: rscript, args: [staged.serve, ...(open ? ["--open"] : [])],
+    env: { ...process.env, BEATRINA_FAILSAFE_REASON: started.reason }, deadlineMs: 120000 });
+  if (!started.announced) fail(`the failsafe did not start either: ${started.reason.replace("the Node host", "the R supervisor")}.`);
+  followChild(started.child, { onExit: (code) => { fs.rmSync(staged.stage, { recursive: true, force: true }); process.exit(code); } });
+}

package/bin/cli.mjs

@@ -0,0 +1,80 @@
+// cli.mjs — the `beatrina` command's decisions, kept apart from starting the host so they can be tested.
+
+import { spawnSync } from "node:child_process";
+import readline from "node:readline";
+
+/** The R packages the worker cannot run without (spike/worker.R, knitr-run.R). */
+export const REQUIRED_R_PACKAGES = Object.freeze(["jsonlite", "knitr", "evaluate"]);
+
+export const USAGE = `beatrina — R, Python and JavaScript notebooks on your own computer
+
+  beatrina [file]     start a session and open the notebook (Ctrl+C stops it)
+  beatrina status     list running sessions: port, process, uptime, document
+  beatrina stop       stop the running session (--port <n> for one of several, --all for every one)
+  beatrina doctor     show what Beatrina found: Node, R, R packages, Python, and whether npm has a newer Beatrina
+  beatrina check      run the acceptance check on this machine (a private session on a spare port);
+                      --prova <url> --token <t> (or PROVA_URL / PROVA_TOKEN) sends the results to Prova
+  beatrina shortcut   add a Beatrina icon, and "Open With ▸ Beatrina" for .qmd and .Rmd files
+                      (--default also makes it the default app for them)
+  beatrina upgrade    install the newest Beatrina from npm (npm install -g beatrina@latest);
+                      a session already running keeps this version until it restarts
+
+  --port <n>          port for the session (default 4848)
+  --no-open           do not open a browser
+  --yes               install missing R packages without asking
+  --version, --help`;
+
+export const COMMANDS = Object.freeze(["doctor", "shortcut", "status", "stop", "check", "upgrade"]);
+
+/** Parse the command line. */
+export function parseArgs(argv) {
+  const out = { command: "run", file: "", port: "", open: true, yes: false, help: false, version: false, fromApp: false, makeDefault: false, dir: "", all: false, prova: "", token: "" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--version" || a === "-v") out.version = true;
+    else if (a === "--no-open") out.open = false;
+    else if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--port") out.port = argv[++i] || "";
+    else if (a.startsWith("--port=")) out.port = a.slice(7);
+    else if (COMMANDS.includes(a) && out.command === "run" && !out.file) out.command = a;
+    else if (a === "--all") out.all = true;
+    else if (a === "--prova") out.prova = argv[++i] || "";
+    else if (a === "--token") out.token = argv[++i] || "";
+    else if (a === "--from-app") out.fromApp = true;
+    else if (a === "--default") out.makeDefault = true;
+    else if (a === "--dir") out.dir = argv[++i] || "";
+    else if (a.startsWith("-")) throw new Error(`unknown option ${a}\n\n${USAGE}`);
+    else if (!out.file) out.file = a;
+    else throw new Error(`one file at a time\n\n${USAGE}`);
+  }
+  if (out.port && !/^\d{2,5}$/.test(out.port)) throw new Error(`--port must be a number, not ${JSON.stringify(out.port)}`);
+  if (out.all && out.command !== "stop") throw new Error(`--all belongs to beatrina stop\n\n${USAGE}`);
+  if ((out.prova || out.token) && out.command !== "check") throw new Error(`--prova and --token belong to beatrina check\n\n${USAGE}`);
+  if (out.file && (out.command === "status" || out.command === "stop" || out.command === "check" || out.command === "upgrade")) throw new Error(`beatrina ${out.command} takes no file\n\n${USAGE}`);
+  return out;
+}
+
+/** Which of `packages` this R cannot load. Asked of R itself, never guessed. */
+export function missingRPackages(rscript, packages = REQUIRED_R_PACKAGES) {
+  const code = `p <- c(${packages.map((x) => JSON.stringify(x)).join(", ")}); cat(p[!vapply(p, requireNamespace, logical(1), quietly = TRUE)], sep = "\\n")`;
+  const r = spawnSync(rscript, ["-e", code], { encoding: "utf8", timeout: 60000 });
+  if (r.status !== 0) throw new Error(`R could not be asked which packages it has: ${String(r.stderr).trim().split("\n").pop()}`);
+  return String(r.stdout).split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+/** Install packages into the user's own R library (created if needed), from CRAN. */
+export function installRPackages(rscript, packages) {
+  const code = `lib <- Sys.getenv("R_LIBS_USER"); dir.create(lib, recursive = TRUE, showWarnings = FALSE); `
+    + `.libPaths(c(lib, .libPaths())); install.packages(c(${packages.map((x) => JSON.stringify(x)).join(", ")}), lib = lib, repos = "https://cloud.r-project.org")`;
+  return spawnSync(rscript, ["-e", code], { stdio: "inherit", timeout: 1800000 }).status === 0;
+}
+
+/** Ask a yes/no question on a terminal. Anything but n/no is yes. No terminal → null (the caller explains). */
+export async function ask(question, { input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY) return null;
+  const rl = readline.createInterface({ input, output });
+  const answer = await new Promise((resolve) => rl.question(`${question} [Y/n] `, resolve));
+  rl.close();
+  return !/^\s*n/i.test(answer);
+}