beatrina 0.8.6

package/host/windows-runtime.mjs

@@ -0,0 +1,145 @@
+// windows-runtime.mjs — what a Windows machine needs that no POSIX one does.
+//
+// Beyza's first Windows run (2026-09-15) and a reading of the host found four
+// places where the host was quietly POSIX-shaped, each with a Windows answer
+// that already exists in the R world:
+//
+//   · WHERE R IS. A Windows R lives in `C:\Program Files\R\R-4.x.y\bin` and the
+//     installer does not put it on PATH, so a PATH search finds nothing on a
+//     default machine. R_HOME, then Program Files, then the per-user install.
+//
+//   · AN INTERACTIVE R. `R --interactive` is a shell script on Unix; Windows
+//     has no such flag. `Rterm.exe --ess` asserts interactive use with a piped
+//     stdin — it is what ESS has driven on Windows for twenty years — so
+//     `readline()`, `menu()` and `browser()` work there instead of returning "".
+//
+//   · STOP. Node's `proc.kill("SIGINT")` on Windows TERMINATES the process
+//     (Node's documentation: every signal but a few is ignored, and those kill
+//     "forcefully and abruptly"). So Stop was Force Stop there, and the session
+//     was lost. Windows interrupts a console program with a console control
+//     event, which only a process attached to the SAME console can send.
+//     processx ships exactly that program, `interrupt.exe <pid> c`
+//     (processx/src/tools/interrupt.c: FreeConsole → AttachConsole(pid) →
+//     ignore Ctrl+C itself → GenerateConsoleCtrlEvent(CTRL_C_EVENT, 0)), and
+//     processx is already a dependency of the carmar package, so the helper is
+//     on every machine that installed it. For the event to reach the worker
+//     and not the host, the worker needs a console of its own: it is spawned
+//     with `windowsHide` (CREATE_NO_WINDOW), the flag processx uses too.
+//
+//   · FORCE STOP. `proc.kill()` ends the worker and orphans what it started
+//     (a `system()` child keeps running). `taskkill /T /F` ends the tree, as
+//     host/planes/jobs.mjs already does for a job.
+//
+// Every function takes the platform, the environment and the file system as
+// arguments, so the Windows branches are exercised on any machine
+// (test/windows-runtime.test.mjs). What that test cannot prove is what
+// Windows DOES with them; tools/beatrina/acceptance.mjs is the check that runs
+// on the real machine.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const defaultFs = {
+  exists: (p) => { try { return fs.existsSync(p); } catch { return false; } },
+  readdir: (p) => { try { return fs.readdirSync(p); } catch { return []; } },
+};
+
+/** Numeric sort key for `R-4.5.2` / `4.5` directory names (newest first). */
+function versionKey(name) {
+  const m = String(name).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  return m ? Number(m[1]) * 1e6 + Number(m[2]) * 1e3 + Number(m[3] || 0) : -1;
+}
+const newestFirst = (names) => [...names].sort((a, b) => versionKey(b) - versionKey(a));
+
+/**
+ * Every Rscript.exe worth trying on Windows, in preference order, each with
+ * the reason it was considered.
+ * @returns {Array<{path: string, why: string}>}
+ */
+export function windowsRscriptCandidates(env = process.env, io = defaultFs) {
+  const w = path.win32;
+  const out = [];
+  const add = (p, why) => { if (p && !out.some((c) => c.path === p)) out.push({ path: p, why }); };
+  if (env.R_HOME) add(w.join(env.R_HOME, "bin", "Rscript.exe"), "R_HOME");
+  const roots = [
+    [env.ProgramW6432 || env.ProgramFiles || "C:\\Program Files", "Program Files"],
+    [env["ProgramFiles(x86)"] || "", "Program Files (x86)"],
+    [env.LOCALAPPDATA ? w.join(env.LOCALAPPDATA, "Programs") : "", "a per-user install"],
+  ];
+  for (const [root, why] of roots) {
+    if (!root) continue;
+    const base = w.join(root, "R");
+    for (const dir of newestFirst(io.readdir(base).filter((d) => /^R-\d/.test(d)))) {
+      add(w.join(base, dir, "bin", "Rscript.exe"), `${why} (${dir})`);
+    }
+  }
+  for (const dir of String(env.PATH || env.Path || "").split(";")) {
+    if (dir) add(w.join(dir, "Rscript.exe"), "PATH");
+  }
+  return out;
+}
+
+/** The first Windows Rscript.exe that exists, or "". */
+export function detectWindowsRscript(env = process.env, io = defaultFs) {
+  const hit = windowsRscriptCandidates(env, io).find((c) => io.exists(c.path));
+  return hit ? hit.path : "";
+}
+
+/**
+ * Rterm.exe beside an Rscript.exe. `bin\Rscript.exe` is a launcher; the
+ * console program lives in `bin\x64\` (and in `bin\` itself in some layouts).
+ */
+export function detectRterm(rscript, io = defaultFs) {
+  if (!rscript) return "";
+  const w = path.win32;
+  const dir = w.dirname(rscript);
+  const cands = [w.join(dir, "x64", "Rterm.exe"), w.join(dir, "Rterm.exe")];
+  return cands.find((p) => io.exists(p)) || "";
+}
+
+/**
+ * The arguments that make Rterm an interactive worker with a piped stdin —
+ * the Windows twin of `R --interactive --no-echo …`.
+ */
+export const RTERM_INTERACTIVE_ARGS = Object.freeze(["--ess", "--no-echo", "--no-save", "--no-restore", "--no-site-file"]);
+
+/**
+ * Where processx's `interrupt.exe` is. `CARMAR_WIN_INTERRUPT` first (the R
+ * launcher sets it from `system.file(package = "processx")`, which knows every
+ * library path), then a helper shipped beside the host, then the libraries a
+ * default install writes to: the R installation's own, R_LIBS_USER, and
+ * `%LOCALAPPDATA%\R\win-library\<x.y>`.
+ * @returns {string} a path, or "" when none exists
+ */
+export function findInterruptTool({ env = process.env, rscript = "", hostRoot = "", io = defaultFs } = {}) {
+  const w = path.win32;
+  const tail = ["processx", "bin", "x64", "interrupt.exe"];
+  const cands = [];
+  if (env.CARMAR_WIN_INTERRUPT) cands.push(env.CARMAR_WIN_INTERRUPT);
+  if (hostRoot) cands.push(w.join(hostRoot, "bin", "interrupt.exe"));
+  if (rscript) cands.push(w.join(w.dirname(w.dirname(rscript)), "library", ...tail));
+  if (env.R_HOME) cands.push(w.join(env.R_HOME, "library", ...tail));
+  for (const lib of String(env.R_LIBS_USER || "").split(";")) if (lib) cands.push(w.join(lib, ...tail));
+  for (const lib of String(env.R_LIBS || "").split(";")) if (lib) cands.push(w.join(lib, ...tail));
+  if (env.LOCALAPPDATA) {
+    const base = w.join(env.LOCALAPPDATA, "R", "win-library");
+    for (const v of newestFirst(io.readdir(base))) cands.push(w.join(base, v, ...tail));
+  }
+  return cands.find((p) => io.exists(p)) || "";
+}
+
+/** How to interrupt `pid` with the helper: Ctrl+C, the event R treats as a user break. */
+export function windowsInterruptPlan(pid, tool) {
+  if (!tool || !pid) return null;
+  return { bin: tool, args: [String(pid), "c"] };
+}
+
+/** How to end a process and everything it started. */
+export function windowsKillPlan(pid) {
+  return { bin: "taskkill", args: ["/T", "/F", "/PID", String(pid)] };
+}
+
+/** The sentence a Windows Stop says when there is no helper to send the event. */
+export const NO_INTERRUPT_TOOL = "Stop cannot interrupt R on this Windows computer: processx's interrupt helper "
+  + "(interrupt.exe) was not found. The chunk keeps running. Reinstall processx (install.packages(\"processx\")), "
+  + "or use Force Stop, which restarts R and loses the session's variables.";