@damurka/jovian 0.1.0 → 0.1.2

package/README.md

@@ -9,11 +9,11 @@ import { SessionManager } from '@damurka/jovian';
 
 const manager = new SessionManager();
 
-const r = await manager.createSession({ kernelType: 'r', rHome: process.env.R_HOME, workingDirectory: '/projects/analysis' });
+const r = await manager.createSession({ kernelType: 'r', workingDirectory: '/projects/analysis' });
 const result = await r.execute('x <- 1:10; mean(x)');
 console.log(result.success, result.output);
 
-const py = await manager.createSession({ kernelType: 'python', pythonHome: '/path/to/python' });
+const py = await manager.createSession({ kernelType: 'python' });
 console.log((await py.execute('sum(range(1, 11))')).success);
 
 await manager.stopAll();
@@ -36,17 +36,13 @@ The pieces are named after moons of Jupiter:
 npm install @damurka/jovian
 ```
 
-The package ships **prebuilt** `themisto`, `elara` and `carpo` binaries — no compiler, CMake or vcpkg — for **Windows x64** (`win32-x64`), **Linux x64** (`linux-x64`) and **macOS on Apple Silicon** (`darwin-arm64`); Intel Macs and Linux on ARM are not published yet, so build from source there and point `JOVIAN_NATIVE_DIR` at `dist/native/Release`. npm installs the matching `@damurka/jovian-<os>-<cpu>` package automatically as an optional dependency, so do not install with `--omit=optional` / `--no-optional`. Node.js ≥ 22.4 is required (ES modules; global `fetch` and `WebSocket`).
+The package ships **prebuilt** `themisto`, `elara` and `carpo` binaries — no compiler, CMake or vcpkg — for **Windows x64**, **Linux x64 and arm64**, and **macOS x64 (Intel) and arm64 (Apple Silicon)**. Windows on ARM and 32-bit ARM Linux are not supported (there is no ARM64 R for Windows yet); build from source elsewhere and point `JOVIAN_NATIVE_DIR` at `dist/native/Release`. npm installs the matching `@damurka/jovian-<os>-<cpu>` package automatically as an optional dependency, so do not install with `--omit=optional` / `--no-optional`. Node.js ≥ 22.13 is required. The package is an ES module: use `import` (in a project with `"type": "module"`, or `.mjs`/`.mts` files), or `require()` it from CommonJS on Node 22.13+.
 
 What you must already have on the machine:
 
-- **R** (4.2 or newer; a build with a shared library, which the CRAN/Posit binaries and distribution packages are) for R sessions. Pass its location as `rHome` (`R RHOME` prints it). The `hera` R package that every R session needs ships inside the npm package and is installed into R on a session's first start, which needs the `remotes` package and `hera`'s CRAN dependencies (`cli`, `evaluate`, `glue`, `IRdisplay`, `jsonlite`, `R6`, `repr`, `rlang`):
+- **R** (4.2 or newer; a build with a shared library, which the CRAN/Posit binaries and distribution packages are) for R sessions. If `rHome` is not passed, it is found from `$R_HOME`, then `R RHOME` (R on `PATH`), then the Windows registry; pass `rHome` to choose a specific installation. You do not need to install any R packages yourself. The `hera` R package every R session needs ships inside the npm package, and before the **first** R session the library installs it, together with its CRAN dependencies (`cli`, `evaluate`, `glue`, `IRdisplay`, `jsonlite`, `R6`, `repr`, `rlang` and what they need), into your R library. Nothing else (not even `remotes`) has to be installed first. This needs an internet connection, takes about 20 seconds where CRAN has binaries (Windows, macOS) and a few minutes on Linux, where packages are compiled from source and need a compiler (Ubuntu: `sudo apt install build-essential`). It happens once; later sessions start straight away. A package that is installed but cannot be loaded (Debian/Ubuntu `r-cran-*` packages built for an older R fail with `undefined symbol: SETLENGTH`) is reinstalled from CRAN into your own library. If it cannot finish, `createSession()` rejects with R's own reason. Set `JOVIAN_SKIP_R_SETUP=1` to skip this step and manage the packages yourself.
 
-  ```r
-  install.packages(c("remotes", "cli", "evaluate", "glue", "IRdisplay", "jsonlite", "R6", "repr", "rlang"))
-  ```
-
-- **Python 3** with its shared library (optional, for Python sessions); pass `pythonHome` (`python3 -c "import sys; print(sys.prefix)"`).
+- **Python 3** with its shared library (optional, for Python sessions); if `pythonHome` is not passed, it is found from `$PYTHONHOME`, then the first `python3` / `python` on `PATH` (its `sys.base_prefix`); pass `pythonHome` to choose one.
 - **Linux:** `libuuid` (`libuuid1`, present on nearly every system) and a glibc at least as new as the one the binaries were built against (Ubuntu 24.04's, 2.39). On an older distribution, [build from source](#requirements).
 - **macOS:** 14 or newer.
 - **Windows:** the [Microsoft Visual C++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist) (x64, 2015–2022) — the binaries use the dynamic C++ runtime; most machines already have it.
@@ -117,9 +113,9 @@ Jovian builds C++ (Adrastea, Elara, Carpo, Themisto) and TypeScript. R and Pytho
 | Variable | Used by | Meaning |
 |---|---|---|
 | `VCPKG_ROOT` | build | vcpkg checkout; used by `npm run build` and the CMake presets. |
-| `R_HOME` | runtime, tests, examples | R installation to use when `rHome` is not passed. `R RHOME` is used as a fallback by the tests and the playground. |
+| `R_HOME` | runtime, tests, examples | R installation to use when `rHome` is not passed; otherwise the library asks `R RHOME`. |
 | `R_PATH`, `R_LIBS` | examples, playground | Passed as `rPath` / `rLibs`. |
-| `PYTHONHOME` | runtime, tests | Python installation prefix when `pythonHome` is not passed. |
+| `PYTHONHOME` | runtime, tests | Python installation prefix when `pythonHome` is not passed; otherwise the library asks `python3` / `python` for its `sys.base_prefix`. |
 | `JOVIAN_NATIVE_DIR` | `lib/` | Directory holding `themisto`, `elara` and `carpo`. Default: the installed `@damurka/jovian-<os>-<cpu>` package, else `dist/native/Release` in a source checkout. Use it to run against a *copy* of the binaries (Windows will not let you overwrite a running `.exe`). |
 | `ELARA_HERA_SRC` | Elara | Set for you from the `heraSrcPath` option: where Elara installs `hera` from if it is missing or older than the source. |
 

package/docs/api/README.md

@@ -21,9 +21,18 @@ import {
 Creates sessions and owns the one shared supervisor process (`themisto`) they all talk to. The supervisor is spawned lazily on the first `createSession()` and killed by `stopAll()` / `killAll()` (and, as a safety net, when the Node process exits).
 
 ```typescript
-const manager = new SessionManager();
+const manager = new SessionManager();                          // quiet
+const verbose = new SessionManager({ logLevel: 'debug' });     // everything, plus the kernels' own output
 ```
 
+**Logging.** The library is quiet by default: it prints only one-time setup notices (the install of the R packages on the first R session), warnings and errors. A kernel that fails to start reports its own error in the exception's message (`Kernel output: …`). To see more:
+
+| Option / variable | Effect |
+|---|---|
+| `logLevel: 'trace' \| 'debug' \| 'info' \| 'notice' \| 'warn' \| 'error' \| 'silent'` (or env `JOVIAN_LOG_LEVEL`) | What the built-in console logger prints: this level and above. Default `'notice'`. `'debug'` and `'trace'` also print the kernels' start-up output. |
+| `logger: (level, message, data?) => void` | Receives **every** message (do your own filtering) instead of the console. A session's own `logger` option takes precedence for that session. |
+| `kernelOutput: boolean` (or env `JOVIAN_KERNEL_OUTPUT=1`) | Print the kernels' own `[elara]` / `[carpo]` start-up output to stderr as it happens. Default off (on for `debug`/`trace`). |
+
 | Member | Description |
 |---|---|
 | `createSession(options?: EngineOptions): Promise<Session>` | Spawns a kernel process (per `options.kernelType`), waits until it has registered and the session's WebSocket is ready, and resolves with the `Session`. Rejects with the supervisor's message if the kernel could not start: `workingDirectory does not exist or is not a directory: …`, `no kernel executable is configured for kernelType 'python' …`, or — when the kernel process itself failed (R or Python not found, …) — `Kernel process exited before it could register -- check its stderr output for the actual error.` The *actual* R/Python error is printed on stderr with an `[elara]` / `[carpo]` prefix (see [Troubleshooting](../troubleshooting.md)). |

package/docs/api/types.md

@@ -9,12 +9,12 @@ Passed to `SessionManager.createSession()`; also `Partial<EngineOptions>` to `Se
 | Field | Type | Default | Meaning |
 |---|---|---|---|
 | `kernelType` | `'r'` \| `'python'` | `'r'` | Which kernel the session runs. Selects which of the fields below apply and which executable (`elara` / `carpo`) is spawned. |
-| `rHome` | string | — | R installation (`R_HOME`). Required to run R sessions unless `R_HOME` is discoverable by the kernel's environment — pass it explicitly. |
+| `rHome` | string | discovered | R installation (`R RHOME`). When omitted it is found from `$R_HOME`, then `R RHOME` (R on PATH), then the Windows registry; pass it to pick a specific installation. |
 | `rPath` | string | `<rHome>/bin/x64` (Windows) | Directory containing `R.dll`; put on the kernel's `PATH`. |
 | `rLibs` | string | — | Extra library path (`R_LIBS`, `R_LIBS_USER`, and `R_LIBS_SITE` on Windows); where `hera` is looked up and installed. |
 | `pandocPath` | string | — | Directory with a `pandoc` binary, for bundled R installs that do not ship it on `PATH` (`RSTUDIO_PANDOC`). |
 | `heraSrcPath` | string | — | Source directory of the `hera` package. If set, Elara installs it (`remotes::install_local`, needs `remotes`) when it is missing or older than the source. **There is no built-in default**: if `hera` is not installed and this is unset, R code cannot run (see [Troubleshooting](../troubleshooting.md#hera-is-not-installed)). |
-| `pythonHome` | string | — | Python installation prefix (`PYTHONHOME`). Its shared library is loaded from here. |
+| `pythonHome` | string | discovered | Python installation prefix (`PYTHONHOME`). Its shared library is loaded from here. When omitted it is found from `$PYTHONHOME`, then `python3` / `python` on PATH (`sys.base_prefix`). |
 | `pythonPath` | string | — | Extra `PYTHONPATH`. |
 | `venvPath` | string | — | A venv whose `site-packages` is added to `sys.path`. `pythonHome` must still point at the *base* install. |
 | `workingDirectory` | string | supervisor's cwd | Directory the kernel process starts in (`getwd()` / `os.getcwd()`); relative paths resolve against it. Must exist, or `createSession()` rejects with `workingDirectory does not exist or is not a directory: <path>`. Kept across `restart()`. |

package/docs/development.md

@@ -88,8 +88,8 @@ The npm packages are built and published by `.github/workflows/release.yml` from
 
 ## Debugging
 
-- **Kernel logs.** Everything a kernel prints (`[R Interpreter] …`, `[carpo] …`, and anything R/Python writes outside an execution) appears on the *supervisor's* stderr, which `lib/` forwards to your process's stderr, prefixed `[elara]` / `[carpo]`. That is the first place to look when a session fails to start.
-- **Library logs.** Pass `logger` to `createSession()` (or read the default console output): `trace` shows queueing, request ids and timeouts.
+- **Kernel logs.** Everything a kernel prints (`[R Interpreter] …`, `[carpo] …`, and anything R/Python writes outside an execution) appears on the *supervisor's* stderr, prefixed `[elara]` / `[carpo]`. `lib/` keeps it quiet by default (and puts the relevant lines in the error when a kernel fails to start); set `JOVIAN_LOG_LEVEL=debug` (or `JOVIAN_KERNEL_OUTPUT=1`, or `new SessionManager({ kernelOutput: true })`) to forward it to your stderr. That is the first place to look when a session fails to start.
+- **Library logs.** Quiet by default; `JOVIAN_LOG_LEVEL=trace` (or `new SessionManager({ logLevel: 'trace' })`) shows queueing, request ids and timeouts, and `logger` receives every message.
 - **Run a kernel by hand.** Generate a kernelspec (`npm run jupyter:kernelspec`) and start it from `jupyter console --kernel elara`, or run `elara -f <connection-file> --r-home …` yourself — no supervisor involved.
 - **Talk to the supervisor directly.** Start `themisto` (it prints `{"type":"supervisorReady","httpPort":…,"wsPort":…}`) and use `curl` against [its HTTP API](protocol.md#2-themistos-http-api) and any WebSocket client against `ws://127.0.0.1:<wsPort>/sessions/<id>/messages`.
 - **One native test.** `dist/native/Release/session_registry_test.exe --gtest_filter=*Interrupt*` (kernel log noise goes to the same stdout; filter with `grep -v "^\[elara\]"`).

package/docs/getting-started.md

@@ -55,7 +55,7 @@ import { SessionManager } from './dist/lib/index.js';
 const manager = new SessionManager();
 const session = await manager.createSession({
     kernelType: 'r',
-    rHome: process.env.R_HOME,                // e.g. "C:/Program Files/R/R-4.6.0" or the output of `R RHOME`
+    rHome: process.env.R_HOME,                // optional: found from $R_HOME / `R RHOME` / the Windows registry when omitted
     rPath: process.env.R_PATH,                // Windows only: e.g. "C:/Program Files/R/R-4.6.0/bin/x64"
     workingDirectory: process.cwd(),          // where getwd() will point
 });
@@ -78,7 +78,7 @@ await manager.stopAll();                                  // always: it also end
 ```javascript
 const py = await manager.createSession({
     kernelType: 'python',
-    pythonHome: process.env.PYTHONHOME,       // the prefix that contains libpython — python -c "import sys; print(sys.base_prefix)"
+    pythonHome: process.env.PYTHONHOME,       // optional: found from $PYTHONHOME / python3 / python when omitted (the prefix containing libpython)
     workingDirectory: process.cwd(),
 });
 py.on('error', () => {});

package/docs/releasing.md

@@ -1,12 +1,12 @@
 # Releasing
 
-Jovian is published to npm as four packages under the `@damurka` scope (Windows x64, Linux x64 and macOS arm64; see [Adding a platform](#adding-a-platform) for the others):
+Jovian is published to npm as six packages under the `@damurka` scope, one library and five platform packages (Windows x64, Linux x64 and arm64, macOS x64 and arm64; see [Platforms that are not supported](#platforms-that-are-not-supported)):
 
 | Package | Contents |
 |---|---|
 | `@damurka/jovian` | The compiled TypeScript library, the `hera` R package, docs. Lists the platform packages below as `optionalDependencies`. This is the one users install. |
 | `@damurka/jovian-win32-x64` | `themisto.exe`, `elara.exe`, `carpo.exe` and the DLLs they need. |
-| `@damurka/jovian-linux-x64`, `-darwin-arm64` | `themisto`, `elara`, `carpo`. |
+| `@damurka/jovian-linux-x64`, `-linux-arm64`, `-darwin-x64`, `-darwin-arm64` | `themisto`, `elara`, `carpo`. |
 
 Each platform package declares `os` and `cpu`, so npm installs only the one that matches the machine. At run time the library finds the binaries in that package (see [`lib/session/native-paths.ts`](../lib/session/native-paths.ts): `JOVIAN_NATIVE_DIR`, then the platform package, then a source checkout's `dist/native/Release`). All four packages are published at the **same version**; the main package pins the platform packages to it.
 
@@ -15,10 +15,25 @@ The repository's own `package.json` is `"private": true` — it is the developme
 ## One-time setup
 
 1. **The scope.** `@damurka` must be a user or organization you can publish to on npmjs.com. If you use a different scope, change it in two places — `SCOPE` in `scripts/release.mjs` and `PACKAGE_SCOPE` in `lib/session/native-paths.ts` (a unit test fails if they differ) — plus the names in `README.md`, `docs/`, and the tarball globs in `.github/workflows/release.yml`.
-2. **A token.** On npmjs.com create an *automation* access token (or a granular token with read/write on the `@damurka` packages) and add it to the GitHub repository as the secret **`NPM_TOKEN`** (Settings → Secrets and variables → Actions). If your account enforces 2FA for publishing, the token must be of the automation kind, which bypasses the prompt.
+2. **A token.** On npmjs.com create an *automation* access token (or a granular token with read/write on the `@damurka` packages) and add it to the GitHub repository as the secret **`NPM_TOKEN`** (Settings → Secrets and variables → Actions). Staging needs no 2FA and works with any token type (npm also offers stage-only tokens, which cannot publish directly); the 2FA happens when you approve. A token that still asks for a one-time password on a direct `npm publish` fails in CI with `EOTP`.
 3. Scoped packages are private by default on npm; the packages carry `publishConfig.access: public`, and the workflow passes `--access public`.
 4. The workflow publishes with **provenance** (`--provenance`, needs the `id-token: write` permission it declares), which requires the GitHub repository to be public.
 
+## The first release is published by hand
+
+npm's staged publishing (below) only works for a package that **already exists** on the registry; a first-time publish of a new package cannot be staged. So the very first version (`0.1.0`) is published from your machine, where npm can ask for your 2FA code:
+
+```bash
+npm login
+# the tarballs CI built and smoke-tested (download them from the Release run's artifacts, or `gh run download <run-id>`):
+npm publish ./tarballs-win32-x64/damurka-jovian-win32-x64-0.1.0.tgz --access public
+npm publish ./tarballs-linux-x64/damurka-jovian-linux-x64-0.1.0.tgz --access public
+npm publish ./tarballs-darwin-arm64/damurka-jovian-darwin-arm64-0.1.0.tgz --access public
+npm publish ./tarballs-linux-x64/damurka-jovian-0.1.0.tgz --access public   # last: it depends on the three above
+```
+
+The main package goes last so nothing depends on a version that is not there yet. This first version carries no provenance badge. From the next version on, use the workflow.
+
 ## Cutting a release
 
 1. Make sure `main` is green on CI.
@@ -31,7 +46,8 @@ The repository's own `package.json` is `"private": true` — it is the developme
    ```
 
 4. `release.yml` runs. For each platform it builds the native binaries in Release, compiles the library, stages both packages, packs them, and **smoke-tests the packed tarballs**: `scripts/release-smoke.mjs` installs the platform tarball and the main tarball into an empty project (outside the repository, with an empty R library so the bundled `hera` has to install from the package) and starts a real R kernel and a real Python kernel from them.
-5. Only if every platform passed does the `publish` job run: the platform packages first, then the main package (so nothing ever depends on a version that is not there yet).
+5. Only if every platform passed does the `publish` job run. It **stages** the packages with `npm stage publish` (npm requires this for CI; needs npm ≥ 11.15, which the job installs), platform packages first, then the main package. Nothing is public yet.
+6. **Approve them**, with 2FA, in the same order: `npm stage list` shows the queue, `npm stage approve <stage-id>` publishes one (or approve on npmjs.com). Approve the main package last. `npm stage reject <stage-id>` discards one.
 
 A version with a hyphen (`v0.2.0-rc.1`) is published under the `next` dist-tag, so it does not become what `npm install` picks by default.
 
@@ -53,20 +69,26 @@ node scripts/release-smoke.mjs --dir dist/release/tarballs --python
 
 Nothing there publishes. Publishing by hand is `npm publish <tarball> --access public`, platform packages first.
 
-## Adding a platform
+## Platforms that are not supported
+
+A platform is published only when there is a real R for it to pair with and a runner that can build and smoke-test it end to end.
+
+- **Windows on ARM (`win32-arm64`).** R for Windows on ARM64 is experimental and not on CRAN (no binary packages either), so there is no R for a native ARM64 kernel to load. People on Windows on ARM run x64 R under emulation, which would need the x64 kernel, but npm installs the x64 package only on x64 CPUs. Not supported until R for Windows on ARM64 is released.
+- **32-bit ARM Linux (`linux-armhf`).** GitHub's hosted runners cannot run 32-bit ARM code (the arm64 machines lack AArch32), so it can only be built by cross-compiling and tested under QEMU emulation, which is not set up.
 
-Only the platforms that have been built and smoke-tested end to end are published (Windows x64, Ubuntu x64 and macOS arm64, the three the CI matrix covers). To add `linux-arm64` or `darwin-x64`:
+Their users get `jovian: there are no prebuilt kernels for <os>-<cpu>` and can build from source and set `JOVIAN_NATIVE_DIR`.
+
+## Adding a platform
 
 1. Add the target to `TARGETS` in `scripts/release.mjs` and to `SUPPORTED_PLATFORMS` in `lib/session/native-paths.ts` (a unit test fails if they differ).
-2. Add it to the build matrix in `.github/workflows/release.yml` (`ubuntu-24.04-arm`, `macos-15-intel`); the job `env` already sets `MACOSX_DEPLOYMENT_TARGET: '14.0'` for macOS.
+2. Add it to the build matrix in `.github/workflows/release.yml`.
 3. Run the workflow by hand (a dry run) and fix what the smoke test finds before tagging a release.
-
-Until a platform is added, its users get `jovian: there are no prebuilt kernels for <os>-<cpu>` and can build from source and set `JOVIAN_NATIVE_DIR`.
+4. A new platform is a **new package on npm**, and npm cannot stage the first version of a package: publish it by hand once (see [The first release is published by hand](#the-first-release-is-published-by-hand)) before the main package that depends on it is approved. The workflow prints a warning naming each such package and does not fail.
 
 ## Things to know
 
 - **hera upgrades.** npm resets file modification times, so the kernel's usual "is the hera source newer than the installed one" check cannot fire for an npm install. The staged `hera` `DESCRIPTION` is stamped with `Config/jovian/release: <version>`, and the kernel reinstalls `hera` when that stamp differs from the installed copy's. Users therefore get the matching `hera` after upgrading the package, once.
-- **Linux binaries and glibc.** They are built on `ubuntu-24.04` (glibc 2.39) and run on any distribution with at least that glibc. Building on an older image would widen compatibility; a `linux-arm64` build would use `ubuntu-24.04-arm`.
+- **Linux binaries and glibc.** They are built on `ubuntu-24.04` (glibc 2.39) and run on any distribution with at least that glibc. Building on an older image would widen compatibility; the `linux-arm64` build runs on `ubuntu-24.04-arm`.
 - **macOS.** The build sets `MACOSX_DEPLOYMENT_TARGET=14.0`. The binaries are not code-signed or notarized; binaries installed through npm are not quarantined by Gatekeeper, so this works, but bundling them into a downloaded `.app` would require signing.
 - **Windows.** The DLLs come from vcpkg's `x64-windows` triplet and are copied next to the executables; the binaries link the dynamic Visual C++ runtime (`MSVCP140.dll`, `VCRUNTIME140.dll`, checked with `dumpbin /dependents`), which is **not** bundled: users need the "Microsoft Visual C++ Redistributable" (x64, 2015–2022), and the README's Install section says so. Bundling the runtime DLLs into the package, or linking the runtime statically, would remove that requirement.
 - **Executable bit.** npm does not reliably preserve it; the library `chmod`s the kernels before starting them.

package/docs/troubleshooting.md

@@ -21,13 +21,13 @@ Messages below are quoted from the code. **First habit:** a kernel that fails to
 | Message | Meaning and fix |
 |---|---|
 | `jovian: the kernel binaries were not found. Expected the '@damurka/jovian-<os>-<cpu>' package …` | The platform package was not installed: it is an optional dependency, so `npm install --omit=optional` / `--no-optional` skips it (reinstall without the flag), or a lockfile made on another OS omitted it (`npm install` on this OS). In a source checkout: run `npm run build`, or set `$JOVIAN_NATIVE_DIR`. |
-| `jovian: there are no prebuilt kernels for <os>-<cpu> (supported: …)` | Prebuilt packages exist for `win32-x64`, `linux-x64` and `darwin-arm64` only (Intel Macs and Linux on ARM are not published yet). Elsewhere, [build from source](../README.md#requirements) and set `$JOVIAN_NATIVE_DIR` to `dist/native/Release`. |
+| `jovian: there are no prebuilt kernels for <os>-<cpu> (supported: …)` | Prebuilt packages exist for `win32-x64`, `linux-x64`, `linux-arm64`, `darwin-x64` and `darwin-arm64` only (Windows on ARM and 32-bit ARM Linux are not supported). Elsewhere, [build from source](../README.md#requirements) and set `$JOVIAN_NATIVE_DIR` to `dist/native/Release`. |
 | `version 'GLIBC_2.xx' not found` on Linux | The prebuilt Linux binaries need a glibc at least as new as the one they were built with (Ubuntu 24.04: 2.39). Build from source on the older system. |
 | `Supervisor process exited before it was ready (code 1)` | `themisto` refused to start — typically `[themisto] FATAL: kernel executable not found at … (pass --kernel-exe to override)`: `elara` is missing next to `themisto`. |
 | `no kernel executable is configured for kernelType 'python' …` | `carpo` was not built (or not found beside `themisto`). It is built by default; check `dist/native/Release/carpo[.exe]` and Themisto's `[themisto] NOTE: no Python kernel executable found` line. R sessions are unaffected. |
 | `workingDirectory does not exist or is not a directory: <path>` | Create the directory first, or fix the path. |
-| `Kernel process exited before it could register -- check its stderr output for the actual error.` | The kernel crashed at start-up. See the R / Python sections below and read the `[elara]` / `[carpo]` lines. |
-| `Did not receive kernel configuration within 60s -- the kernel process is still running but never registered. Check its stderr output for what it's doing.` | The kernel started but hung before registering — e.g. R blocked loading packages, a very slow disk, or a security product scanning the process. The stderr shows how far it got. |
+| `Kernel process exited before it could register -- check its stderr output for the actual error.` | The kernel crashed at start-up. The exception's message ends with `Kernel output:` and the kernel's own error lines; for the full output run with `JOVIAN_LOG_LEVEL=debug` (or `new SessionManager({ kernelOutput: true })`). See the R / Python sections below. |
+| `Did not receive kernel configuration within 60s -- the kernel process is still running but never registered. Check its stderr output for what it's doing.` | The kernel started but hung before registering — e.g. R blocked loading packages, a very slow disk, or a security product scanning the process. Run with `JOVIAN_LOG_LEVEL=debug` to print the kernel's output and see how far it got. |
 | `WebSocket connection to session <id> failed` / `Session <id> closed before it was ready` | The supervisor accepted the session but the WebSocket could not be established/kept — usually the supervisor died. Look for its exit. |
 
 ### R
@@ -35,7 +35,12 @@ Messages below are quoted from the code. **First habit:** a kernel that fails to
 | Symptom | Cause / fix |
 |---|---|
 | `Could not load R.dll (…). Is R installed? Checked PATH and R_HOME=… Install R from https://cran.r-project.org, or make sure R_HOME/the R bin directory is configured correctly.` | Windows: `rHome` wrong, or `rPath` (the folder containing `R.dll`, normally `<R_HOME>\bin\x64`) is not right. |
-| `R_HOME is not set -- elara needs a working R installation to run. …` | Linux/macOS: pass `rHome` (find it with `R RHOME`). |
+| `R_HOME is not set -- elara needs a working R installation to run. …` | The library could not find R (it tries `$R_HOME`, `R RHOME`, and on Windows the registry): put R on `PATH` or pass `rHome` (`R RHOME` prints it). |
+| `No libpython3.*.so* … was found under '/lib' … Is Python installed at ''?` | The library could not find Python (it tries `$PYTHONHOME`, then `python3`/`python` on `PATH`): install Python 3 (`sudo apt install python3`) or pass `pythonHome`. |
+| `Could not set up the R packages the kernel needs: …` | The one-time install of `hera` and its dependencies (see the README's Install section) failed; the text after the colon is R's own reason (no internet access to CRAN, no compiler on Linux, a library that cannot be written to). Fix that and call `createSession()` again; it retries. `JOVIAN_SKIP_R_SETUP=1` skips the step. |
+| `ERROR: failed to lock directory '<library>' for modifying. Try removing '<library>/00LOCK-<pkg>'` | An earlier install of that package was interrupted (Ctrl+C, a kill, a timeout) and left its lock folder, which makes R refuse every later install of it. The automatic setup removes locks older than 5 minutes itself; to clear one now: `rm -rf <library>/00LOCK-*` (Windows: delete the `00LOCK-*` folder), then run again. |
+| `unable to load shared object '/usr/lib/R/site-library/<pkg>/libs/<pkg>.so': undefined symbol: SETLENGTH` (or another `undefined symbol`) | Only when the automatic setup is skipped or you install by hand. Debian/Ubuntu: a package installed with `apt` (`r-cran-*`, in `/usr/lib/R/site-library`) was built for an older R than yours (the automatic setup reinstalls these itself). Reinstall it, and everything it needs, from CRAN into your own library, which R searches first. Needs a compiler (`sudo apt install build-essential`):<br>`wanted <- c("remotes","cli","evaluate","glue","IRdisplay","jsonlite","R6","repr","rlang")`<br>`all <- unique(c(wanted, unlist(tools::package_dependencies(wanted, db = available.packages(), recursive = TRUE), use.names = FALSE)))`<br>`ip <- installed.packages(); install.packages(setdiff(all, rownames(ip)[!is.na(ip[, "Priority"])]), repos = "https://cloud.r-project.org")` |
+| `WARNING: 'hera' package could not be loaded (status: install_failed: …)` | Elara could not install the bundled `hera` R package; the text after `install_failed:` is R's own reason. Usually one of `hera`'s CRAN dependencies is missing or cannot be built (install them first: `install.packages(c("remotes", "cli", "evaluate", "glue", "IRdisplay", "jsonlite", "R6", "repr", "rlang"))`), or the R library is not writable. To see the full output run `R CMD INSTALL node_modules/@damurka/jovian/packages/hera`. |
 | `Could not load …/lib/libR.so (…). Is R installed at '…'? If this R was built from source, it needs to have been configured with --enable-R-shlib, or no libR.so exists at all` | Use a distribution/CRAN R, or rebuild R with `--enable-R-shlib`. |
 | No `libR.dylib` on macOS | Point `rHome` at the framework's `Resources` directory (what `R RHOME` prints). |
 

package/lib/execution/execution-queue.js

@@ -141,7 +141,7 @@ export class ExecutionQueue {
                 break;
             case 'error':
                 pending.output.push(message);
-                this.logger?.error(`Execution ${message.parentMsgId} reported an R error`, { evalue: message.content?.evalue });
+                this.logger?.debug(`Execution ${message.parentMsgId} reported an R error`, { evalue: message.content?.evalue });
                 if (pending.stopOnError) {
                     this.abortQueued();
                 }

package/lib/session/native-paths.d.ts

@@ -7,7 +7,7 @@ export declare const PACKAGE_NAME = "@damurka/jovian";
  * the main package only where it matches (each declares `os`/`cpu`). These are
  * the platforms that get a package.
  */
-export declare const SUPPORTED_PLATFORMS: readonly ['win32-x64', 'linux-x64', 'darwin-arm64'];
+export declare const SUPPORTED_PLATFORMS: readonly ['win32-x64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'];
 export declare function platformPackageName(platform?: string, arch?: string): string | undefined;
 export interface NativeLocation {
     /** Directory holding themisto, elara and carpo. */

package/lib/session/native-paths.js

@@ -11,7 +11,7 @@ export const PACKAGE_NAME = `${PACKAGE_SCOPE}/jovian`;
  * the main package only where it matches (each declares `os`/`cpu`). These are
  * the platforms that get a package.
  */
-export const SUPPORTED_PLATFORMS = ['win32-x64', 'linux-x64', 'darwin-arm64'];
+export const SUPPORTED_PLATFORMS = ['win32-x64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'];
 export function platformPackageName(platform = process.platform, arch = process.arch) {
     const key = `${platform}-${arch}`;
     return SUPPORTED_PLATFORMS.includes(key) ? `${PACKAGE_NAME}-${key}` : undefined;

package/lib/session/r-setup.d.ts

@@ -0,0 +1,47 @@
+import type { EngineOptions } from '../types/index.js';
+/**
+ * Runs once, before the first R session, when the library was given a copy of
+ * the 'hera' R package (always the case for an npm install): makes sure hera
+ * and everything it needs are installed, so a person who has just installed R
+ * has nothing to do by hand.
+ *
+ * It is a separate step, not part of the kernel's start-up, because the
+ * supervisor gives a kernel 60 seconds to register and installing a dozen
+ * packages (compiling some, on Linux) takes longer. A kernel started after
+ * this finds hera already there.
+ *
+ * Only what is missing is installed, into the first writable library, and
+ * nothing is installed at all when hera is already current. A package that is
+ * installed but cannot be loaded (Debian/Ubuntu `r-cran-*` packages built for
+ * an older R fail with "undefined symbol: SETLENGTH") counts as missing and is
+ * reinstalled from CRAN into the user's own library, which R searches first.
+ */
+export declare const R_SETUP_SCRIPT: string;
+export interface SetupLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    notice(message: string): void;
+}
+export interface SetupProcessOutcome {
+    code: number | null;
+    timedOut: boolean;
+}
+export interface SetupDeps {
+    env: NodeJS.ProcessEnv;
+    platform: string;
+    exists: (path: string) => boolean;
+    /** Runs `rscript scriptFile ...args`, reporting each stdout/stderr line. */
+    run: (rscript: string, scriptFile: string, args: string[], env: NodeJS.ProcessEnv, onLine: (line: string) => void, timeoutMs: number) => Promise<SetupProcessOutcome>;
+    timeoutMs: number;
+}
+export declare function rscriptPath(rHome: string, deps?: Pick<SetupDeps, 'platform' | 'exists'>): string | undefined;
+/**
+ * Makes sure hera and its dependencies are installed for this R (see the
+ * comment on R_SETUP_SCRIPT). Resolves immediately when there is nothing to
+ * do: a Python session, no bundled hera (a source checkout), no R found, or
+ * JOVIAN_SKIP_R_SETUP set. Concurrent calls for the same R share one run, and
+ * a run that succeeded is not repeated by this process. Rejects with R's own
+ * explanation when the packages could not be installed.
+ */
+export declare function ensureRPackages(options: EngineOptions, logger: SetupLogger, deps?: SetupDeps): Promise<void>;
+//# sourceMappingURL=r-setup.d.ts.map

package/lib/session/r-setup.js

@@ -0,0 +1,238 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+/**
+ * Runs once, before the first R session, when the library was given a copy of
+ * the 'hera' R package (always the case for an npm install): makes sure hera
+ * and everything it needs are installed, so a person who has just installed R
+ * has nothing to do by hand.
+ *
+ * It is a separate step, not part of the kernel's start-up, because the
+ * supervisor gives a kernel 60 seconds to register and installing a dozen
+ * packages (compiling some, on Linux) takes longer. A kernel started after
+ * this finds hera already there.
+ *
+ * Only what is missing is installed, into the first writable library, and
+ * nothing is installed at all when hera is already current. A package that is
+ * installed but cannot be loaded (Debian/Ubuntu `r-cran-*` packages built for
+ * an older R fail with "undefined symbol: SETLENGTH") counts as missing and is
+ * reinstalled from CRAN into the user's own library, which R searches first.
+ */
+export const R_SETUP_SCRIPT = String.raw `
+src <- commandArgs(trailingOnly = TRUE)[1]
+say <- function(...) cat("JOVIAN_R_SETUP: ", ..., "\n", sep = "")
+note <- function(...) cat("JOVIAN_R_SETUP_INFO: ", ..., "\n", sep = "")
+fail <- function(...) {
+    cat("JOVIAN_R_SETUP_ERROR: ", ..., "\n", sep = "")
+    quit(save = "no", status = 1)
+}
+field <- function(path, name) {
+    value <- tryCatch(read.dcf(path, fields = name)[1, 1], error = function(e) NA_character_)
+    if (is.na(value)) NA_character_ else value
+}
+stamp_wanted <- field(file.path(src, "DESCRIPTION"), "Config/jovian/release")
+
+hera_current <- function() {
+    installed <- tryCatch(find.package("hera", quiet = TRUE), error = function(e) character(0))
+    if (!length(installed)) return(FALSE)
+    if (!is.na(stamp_wanted) && !identical(field(file.path(installed, "DESCRIPTION"), "Config/jovian/release"), stamp_wanted)) return(FALSE)
+    suppressWarnings(suppressMessages(requireNamespace("hera", quietly = TRUE)))
+}
+if (hera_current()) {
+    note("hera is already installed")
+    quit(save = "no", status = 0)
+}
+
+repos <- getOption("repos")
+if (is.null(repos) || is.na(repos["CRAN"]) || identical(unname(repos["CRAN"]), "@CRAN@")) {
+    options(repos = c(CRAN = "https://cloud.r-project.org"))
+}
+
+is_writable <- function(path) dir.exists(path) && file.access(path, 2) == 0
+lib <- Filter(is_writable, .libPaths())[1]
+if (is.na(lib)) {
+    lib <- Sys.getenv("R_LIBS_USER")
+    if (!nzchar(lib)) lib <- file.path(Sys.getenv("HOME"), "R", "library")
+    dir.create(lib, recursive = TRUE, showWarnings = FALSE)
+    .libPaths(c(lib, .libPaths()))
+}
+
+for (lock in Sys.glob(file.path(lib, "00LOCK-*"))) {
+    # An install that was killed (Ctrl+C, a timeout) leaves its lock behind, and
+    # every later install of that package is refused until it is removed.
+    if (difftime(Sys.time(), file.info(lock)$mtime, units = "mins") > 5) {
+        say("removing a stale lock left by an interrupted install: ", lock)
+        unlink(lock, recursive = TRUE)
+    }
+}
+
+ip <- installed.packages()
+base_packages <- rownames(ip)[!is.na(ip[, "Priority"])]
+fields <- tryCatch(read.dcf(file.path(src, "DESCRIPTION"), fields = c("Depends", "Imports", "LinkingTo")), error = function(e) NULL)
+direct <- unique(trimws(sub("[(].*$", "", unlist(strsplit(paste(stats::na.omit(as.vector(fields)), collapse = ","), ",")))))
+direct <- setdiff(direct[nzchar(direct)], c("R", base_packages))
+
+available <- tryCatch(suppressWarnings(available.packages()), error = function(e) NULL)
+wanted <- direct
+if (!is.null(available) && nrow(available) > 0) {
+    everything <- tools::package_dependencies(direct, db = available, recursive = TRUE)
+    wanted <- setdiff(unique(c(direct, unlist(everything, use.names = FALSE))), base_packages)
+}
+
+usable <- function(package) suppressWarnings(suppressMessages(requireNamespace(package, quietly = TRUE)))
+missing <- wanted[!vapply(wanted, usable, logical(1))]
+warnings_seen <- character()
+collect <- function(expr) withCallingHandlers(expr, warning = function(w) {
+    warnings_seen <<- c(warnings_seen, conditionMessage(w))
+    invokeRestart("muffleWarning")
+})
+
+if (length(missing) > 0) {
+    if (is.null(available) || nrow(available) == 0) {
+        fail("these R packages are needed but not installed: ", paste(missing, collapse = ", "),
+             " -- and CRAN could not be reached to install them (check the internet connection)")
+    }
+    say("installing ", length(missing), " R package(s) from CRAN into ", lib, " (first run only): ", paste(missing, collapse = ", "))
+    tryCatch(collect(utils::install.packages(missing, lib = lib, repos = getOption("repos"), quiet = TRUE)),
+             error = function(e) fail("installing R packages failed: ", conditionMessage(e)))
+    still_missing <- missing[!vapply(missing, usable, logical(1))]
+    if (length(still_missing) > 0) {
+        # The warnings only say "non-zero exit status". Packages that need
+        # another one that failed fail too, so re-run the install of the ones
+        # that do not, on their own, and report what R and the compiler said.
+        needs <- tryCatch(tools::package_dependencies(still_missing, db = available, recursive = FALSE), error = function(e) list())
+        roots <- still_missing[vapply(still_missing, function(p) !any(needs[[p]] %in% still_missing), logical(1))]
+        reasons <- character()
+        for (p in utils::head(roots, 2)) {
+            why <- tryCatch({
+                tarball <- utils::download.packages(p, destdir = tempdir(), repos = getOption("repos"), type = "source", quiet = TRUE)[1, 2]
+                out <- suppressWarnings(system2(file.path(R.home("bin"), "R"), c("CMD", "INSTALL", paste0("--library=", shQuote(lib)), shQuote(tarball)), stdout = TRUE, stderr = TRUE))
+                if (is.null(attr(out, "status")) || identical(attr(out, "status"), 0L)) {
+                    "it installed when retried on its own, so the failure may be temporary: try again"
+                } else {
+                    important <- grep("error|ERROR|undefined|fatal|cannot|not found|No such file|Killed", out, value = TRUE)
+                    substr(gsub("[[:space:]]+", " ", paste(utils::tail(if (length(important)) important else out, 5), collapse = " ; ")), 1, 700)
+                }
+            }, error = function(e) conditionMessage(e))
+            reasons <- c(reasons, paste0(p, ": ", why))
+        }
+        fail("could not install these R packages: ", paste(still_missing, collapse = ", "),
+             if (length(reasons)) paste0(" -- ", paste(reasons, collapse = " | ")) else "",
+             " (on Linux packages are compiled from source and need a compiler: sudo apt install build-essential)")
+    }
+}
+
+say("installing hera into ", lib)
+tryCatch(collect(utils::install.packages(src, repos = NULL, type = "source", lib = lib, quiet = TRUE)),
+         error = function(e) NULL)
+if (!hera_current()) {
+    output <- tryCatch(
+        suppressWarnings(system2(file.path(R.home("bin"), "R"), c("CMD", "INSTALL", paste0("--library=", shQuote(lib)), shQuote(src)), stdout = TRUE, stderr = TRUE)),
+        error = function(e) conditionMessage(e))
+    lines <- grep("ERROR|error|not available|cannot|denied|failed", output, value = TRUE)
+    reason <- paste(utils::tail(if (length(lines)) lines else output, 6), collapse = " | ")
+    fail("hera could not be installed: ", substr(gsub("[[:space:]]+", " ", reason), 1, 800))
+}
+say("done")
+`;
+const runRscript = async (rscript, scriptFile, args, env, onLine, timeoutMs) => {
+    const child = spawn(rscript, [scriptFile, ...args], { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    for (const stream of [child.stdout, child.stderr]) {
+        createInterface({ input: stream }).on('line', onLine);
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+    }, timeoutMs);
+    return new Promise((resolve, reject) => {
+        child.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.once('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, timedOut });
+        });
+    });
+};
+const defaultDeps = () => ({
+    env: process.env,
+    platform: process.platform,
+    exists: existsSync,
+    run: runRscript,
+    timeoutMs: 30 * 60 * 1000
+});
+export function rscriptPath(rHome, deps = defaultDeps()) {
+    const name = deps.platform === 'win32' ? 'Rscript.exe' : 'Rscript';
+    const candidates = [join(rHome, 'bin', name)];
+    if (deps.platform === 'win32')
+        candidates.push(join(rHome, 'bin', 'x64', name));
+    return candidates.find((candidate) => deps.exists(candidate));
+}
+const inFlight = new Map();
+/**
+ * Makes sure hera and its dependencies are installed for this R (see the
+ * comment on R_SETUP_SCRIPT). Resolves immediately when there is nothing to
+ * do: a Python session, no bundled hera (a source checkout), no R found, or
+ * JOVIAN_SKIP_R_SETUP set. Concurrent calls for the same R share one run, and
+ * a run that succeeded is not repeated by this process. Rejects with R's own
+ * explanation when the packages could not be installed.
+ */
+export function ensureRPackages(options, logger, deps = defaultDeps()) {
+    const { rHome, heraSrcPath } = options;
+    if (options.kernelType === 'python' || !rHome || !heraSrcPath)
+        return Promise.resolve();
+    if (deps.env.JOVIAN_SKIP_R_SETUP)
+        return Promise.resolve();
+    const rscript = rscriptPath(rHome, deps);
+    if (!rscript) {
+        logger.debug(`No Rscript under ${rHome}; leaving the R packages to the kernel`);
+        return Promise.resolve();
+    }
+    const key = [rHome, heraSrcPath, options.rLibs ?? ''].join('|');
+    let pending = inFlight.get(key);
+    if (!pending) {
+        pending = setUp(rscript, heraSrcPath, options.rLibs, logger, deps).catch((error) => {
+            inFlight.delete(key);
+            throw error;
+        });
+        inFlight.set(key, pending);
+    }
+    return pending;
+}
+async function setUp(rscript, heraSrcPath, rLibs, logger, deps) {
+    const directory = await mkdtemp(join(tmpdir(), 'jovian-r-setup-'));
+    try {
+        const scriptFile = join(directory, 'setup.R');
+        await writeFile(scriptFile, R_SETUP_SCRIPT);
+        const env = { ...deps.env, ...(rLibs ? { R_LIBS: rLibs } : {}) };
+        let failure;
+        const otherOutput = [];
+        const onLine = (line) => {
+            if (line.startsWith('JOVIAN_R_SETUP_ERROR: '))
+                failure = line.slice('JOVIAN_R_SETUP_ERROR: '.length);
+            else if (line.startsWith('JOVIAN_R_SETUP: '))
+                logger.notice(`R setup: ${line.slice('JOVIAN_R_SETUP: '.length)}`);
+            else if (line.startsWith('JOVIAN_R_SETUP_INFO: '))
+                logger.info(`R setup: ${line.slice('JOVIAN_R_SETUP_INFO: '.length)}`);
+            else if (line.trim())
+                otherOutput.push(line.trim());
+        };
+        const outcome = await deps.run(rscript, scriptFile, [heraSrcPath], env, onLine, deps.timeoutMs);
+        if (outcome.timedOut) {
+            throw new Error(`Setting up the R packages the kernel needs took longer than ${Math.round(deps.timeoutMs / 60000)} minutes and was stopped.`);
+        }
+        if (outcome.code !== 0) {
+            const unexplained = `Rscript exited with code ${outcome.code}${otherOutput.length ? `: ${otherOutput.slice(-5).join(' | ')}` : ''}`;
+            throw new Error(`Could not set up the R packages the kernel needs: ${failure ?? unexplained}`);
+        }
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=r-setup.js.map

package/lib/session/runtimes.d.ts

@@ -0,0 +1,29 @@
+import type { EngineOptions } from '../types/index.js';
+/** Runs a command and returns its last non-empty stdout line, or undefined if it failed or printed nothing. */
+export type Runner = (command: string, args: string[]) => string | undefined;
+export interface DiscoveryContext {
+    run: Runner;
+    env: Record<string, string | undefined>;
+    platform: string;
+}
+/**
+ * Where R lives, when the caller did not say: $R_HOME, else what `R RHOME`
+ * prints (R's own answer, valid on every platform, if R is on PATH), else on
+ * Windows the install path R's installer records in the registry.
+ */
+export declare function discoverRHome(context?: DiscoveryContext): string | undefined;
+/**
+ * Which Python to embed, when the caller did not say: $PYTHONHOME, else the
+ * installation prefix of the first python on PATH. sys.base_prefix, not
+ * sys.prefix: inside a virtual environment the latter is the venv, which has
+ * no libpython to load.
+ */
+export declare function discoverPythonHome(context?: DiscoveryContext): string | undefined;
+/**
+ * The options with rHome (R sessions) or pythonHome (Python sessions) filled
+ * in when the caller left them out and the runtime could be found. Anything
+ * the caller passed is kept as it is; if nothing is found the field stays
+ * unset, and the kernel reports what it could not find.
+ */
+export declare function withDiscoveredRuntime(options: EngineOptions, context?: DiscoveryContext): EngineOptions;
+//# sourceMappingURL=runtimes.d.ts.map