@damurka/jovian 0.1.0 → 0.1.1

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();
@@ -40,13 +40,9 @@ The package ships **prebuilt** `themisto`, `elara` and `carpo` binaries — no c
 
 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/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/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

@@ -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.
 

package/docs/troubleshooting.md

@@ -35,7 +35,11 @@ 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. |
+| `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/session/r-setup.d.ts

@@ -0,0 +1,46 @@
+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;
+}
+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,207 @@
+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 = "")
+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()) {
+    say("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()))
+}
+
+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) {
+        fail("could not install these R packages: ", paste(still_missing, collapse = ", "),
+             " -- on Linux they are compiled from source, which needs a compiler (Ubuntu: sudo apt install build-essential)",
+             if (length(warnings_seen)) paste0(" | ", substr(paste(unique(warnings_seen), collapse = " | "), 1, 400)) else "")
+    }
+}
+
+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.info(`R setup: ${line.slice('JOVIAN_R_SETUP: '.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

package/lib/session/runtimes.js

@@ -0,0 +1,80 @@
+import { execFileSync } from 'node:child_process';
+const runCommand = (command, args) => {
+    try {
+        const output = execFileSync(command, args, {
+            encoding: 'utf8',
+            timeout: 10_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true
+        });
+        const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        return lines[lines.length - 1];
+    }
+    catch {
+        return undefined;
+    }
+};
+const defaultContext = () => ({ run: runCommand, env: process.env, platform: process.platform });
+/**
+ * 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 function discoverRHome(context = defaultContext()) {
+    if (context.env.R_HOME)
+        return context.env.R_HOME;
+    const fromR = context.run('R', ['RHOME']);
+    if (fromR)
+        return fromR;
+    if (context.platform === 'win32') {
+        for (const hive of ['HKLM', 'HKCU']) {
+            const line = context.run('reg', ['query', `${hive}\\SOFTWARE\\R-core\\R`, '/v', 'InstallPath']);
+            const match = line?.match(/InstallPath\s+REG_SZ\s+(.+)$/);
+            if (match?.[1])
+                return match[1].trim();
+        }
+    }
+    return 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 function discoverPythonHome(context = defaultContext()) {
+    if (context.env.PYTHONHOME)
+        return context.env.PYTHONHOME;
+    const script = 'import sys; print(sys.base_prefix)';
+    const candidates = [
+        ['python3', ['-c', script]],
+        ['python', ['-c', script]]
+    ];
+    if (context.platform === 'win32')
+        candidates.push(['py', ['-3', '-c', script]]);
+    for (const [command, args] of candidates) {
+        const home = context.run(command, args);
+        if (home)
+            return home;
+    }
+    return 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 function withDiscoveredRuntime(options, context = defaultContext()) {
+    if (options.kernelType === 'python') {
+        if (options.pythonHome)
+            return options;
+        const pythonHome = discoverPythonHome(context);
+        return pythonHome ? { ...options, pythonHome } : options;
+    }
+    if (options.rHome)
+        return options;
+    const rHome = discoverRHome(context);
+    return rHome ? { ...options, rHome } : options;
+}
+//# sourceMappingURL=runtimes.js.map

package/lib/session/session-manager.d.ts

@@ -122,7 +122,7 @@ export declare class Session extends EventEmitter {
      * execute() timed out) first.
      */
     interrupt(options?: {
-        timeout?: number;
+        timeout?: number | undefined;
     }): Promise<boolean>;
     /**
      * The latest iopub `status` the kernel reported ('busy' while it is
@@ -145,7 +145,7 @@ export declare class Session extends EventEmitter {
      * shutdown_request (stop()/restart()) -- the supervisor rejects those.
      */
     request<T = any>(msgType: string, content?: Record<string, unknown>, options?: {
-        timeout?: number;
+        timeout?: number | undefined;
     }): Promise<T>;
     private trackExecutionState;
     private routeComm;
@@ -209,11 +209,12 @@ export declare class Session extends EventEmitter {
     kill(): void;
 }
 export declare class SessionManager {
+    private readonly logger;
     private readonly supervisor;
     private readonly sessions;
     private exitHandlerRegistered;
     /** Creates a new R session in its own OS process and waits for it to be ready. */
-    createSession(options?: EngineOptions): Promise<Session>;
+    createSession(requested?: EngineOptions): Promise<Session>;
     /** Gracefully stops every session managed by this instance. */
     stopAll(): Promise<void>;
     /**

package/lib/session/session-manager.js

@@ -12,6 +12,9 @@ import { ErrorHandler } from '../handlers/error-handler.js';
 import { DisplayHandler } from '../handlers/display-handler.js';
 import { findFreePort, waitForPort } from '../utils/network.js';
 import { SupervisorClient } from './supervisor-client.js';
+import { withDiscoveredRuntime } from './runtimes.js';
+import { ensureRPackages } from './r-setup.js';
+import { bundledHeraSource } from './native-paths.js';
 import { Comm } from './comm.js';
 const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
 // How long stop() waits for the kernel's shutdown_reply after the
@@ -213,7 +216,7 @@ export class Session extends EventEmitter {
         // The supervisor replaces a session's options wholesale, so send the
         // merge -- a restart that only switches rHome must keep the
         // workingDirectory, rLibs, ... the session was created with.
-        const mergedOptions = options ? { ...this.currentOptions, ...options } : undefined;
+        const mergedOptions = options ? withDiscoveredRuntime({ ...this.currentOptions, ...options }) : undefined;
         // Reassigned synchronously, before awaiting anything below, so a
         // concurrent execute()/createShiny() call that reads this.readyPromise
         // while the restart is still in flight waits for the new connection
@@ -222,6 +225,8 @@ export class Session extends EventEmitter {
         const shutdownReply = this.watchFor('shutdown_reply');
         this.readyPromise = (async () => {
             try {
+                if (mergedOptions)
+                    await ensureRPackages(mergedOptions, this.logger);
                 await this.supervisor.restartSession(this.info, mergedOptions);
                 if (mergedOptions) {
                     this.currentOptions = mergedOptions;
@@ -776,11 +781,17 @@ export class Session extends EventEmitter {
     }
 }
 export class SessionManager {
-    supervisor = new SupervisorClient(new Logger());
+    logger = new Logger();
+    supervisor = new SupervisorClient(this.logger);
     sessions = new Set();
     exitHandlerRegistered = false;
     /** Creates a new R session in its own OS process and waits for it to be ready. */
-    async createSession(options = {}) {
+    async createSession(requested = {}) {
+        // Finds R / Python when rHome / pythonHome were not given (see runtimes.ts).
+        // An installed package brings its own copy of hera (none in a source checkout).
+        const options = withDiscoveredRuntime(requested.heraSrcPath ? requested : { ...requested, heraSrcPath: bundledHeraSource() });
+        // First R session only: installs hera and what it needs (see r-setup.ts).
+        await ensureRPackages(options, this.logger);
         const info = await this.supervisor.createSession(options);
         const session = new Session(info, options, this.supervisor);
         this.sessions.add(session);

package/lib/types/engine.d.ts

@@ -9,12 +9,13 @@ export interface EngineOptions {
      * supervisor actually uses (native/src/themisto/session_registry.cpp's
      * SessionOptions::kernelType) and which kernel executable it spawns.
      */
-    kernelType?: 'r' | 'python';
-    rHome?: string;
-    rPath?: string;
-    rLibs?: string;
+    kernelType?: 'r' | 'python' | undefined;
+    /** R installation (`R RHOME`). Found from $R_HOME, `R RHOME` or the Windows registry when omitted. */
+    rHome?: string | undefined;
+    rPath?: string | undefined;
+    rLibs?: string | undefined;
     /** Directory containing the pandoc binary, for bundled R installs that don't ship it on PATH. */
-    pandocPath?: string;
+    pandocPath?: string | undefined;
     /**
      * Source directory of the 'hera' R package (packages/hera in this repo).
      * When set, Elara installs it via remotes::install_local() if it is
@@ -23,13 +24,13 @@ export interface EngineOptions {
      * already installed in the library -- install or update it with
      * `npm run hera:install`.
      */
-    heraSrcPath?: string;
-    /** Only used when kernelType is 'python' -- Carpo's equivalent of rHome. */
-    pythonHome?: string;
+    heraSrcPath?: string | undefined;
+    /** Only used when kernelType is 'python' -- Carpo's equivalent of rHome. Found from $PYTHONHOME or `python3`/`python` on PATH when omitted. */
+    pythonHome?: string | undefined;
     /** Only used when kernelType is 'python' -- Carpo's equivalent of rPath. */
-    pythonPath?: string;
+    pythonPath?: string | undefined;
     /** Only used when kernelType is 'python' -- not yet consulted by Carpo itself (see carpo::EnvironmentConfig). */
-    venvPath?: string;
+    venvPath?: string | undefined;
     /**
      * Directory the kernel process starts in -- what `getwd()` (R) /
      * `os.getcwd()` (Python) report and what relative paths resolve against.
@@ -37,44 +38,44 @@ export interface EngineOptions {
      * (i.e. the calling process's), which is rarely what you want for a
      * notebook/project: set it to the project or document folder.
      */
-    workingDirectory?: string;
-    queueSize?: number;
-    enableLogging?: boolean;
-    enableMetrics?: boolean;
-    logger?: LoggerFunction;
+    workingDirectory?: string | undefined;
+    queueSize?: number | undefined;
+    enableLogging?: boolean | undefined;
+    enableMetrics?: boolean | undefined;
+    logger?: LoggerFunction | undefined;
 }
 export type EngineState = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
 export interface ExecutionOptions {
-    silent?: boolean;
-    storeHistory?: boolean;
-    allowStdin?: boolean;
+    silent?: boolean | undefined;
+    storeHistory?: boolean | undefined;
+    allowStdin?: boolean | undefined;
     /**
      * When this execution fails, abort every execute() still waiting behind
      * it in the queue instead of running them (Jupyter's stop_on_error) --
      * their results come back with `aborted: true` and nothing having run.
      * Also forwarded to the kernel in the execute_request itself.
      */
-    stopOnError?: boolean;
+    stopOnError?: boolean | undefined;
     /**
      * Expressions to evaluate in the kernel right after the code runs, as
      * {name: expression} (Jupyter's user_expressions). Only evaluated when
      * the code succeeded; each result -- or its own error -- comes back in
      * `ExecutionResult.userExpressions` under the same name.
      */
-    userExpressions?: Record<string, string>;
+    userExpressions?: Record<string, string> | undefined;
     /**
      * Milliseconds to wait for the execution to finish before giving up
      * (default 30000; 0 = no timeout, for calls meant to run indefinitely
      * such as a Shiny app).
      */
-    timeout?: number;
+    timeout?: number | undefined;
     /**
      * When the timeout fires, also send the kernel an interrupt (default
      * true) so it stops the code instead of carrying on with work no one is
      * waiting for -- which would otherwise block everything queued behind it.
      * Set false to leave the kernel running after a timeout.
      */
-    interruptOnTimeout?: boolean;
+    interruptOnTimeout?: boolean | undefined;
 }
 /** One evaluated user expression: its rich value, or the error evaluating it raised. */
 export type UserExpressionResult = {
@@ -131,19 +132,19 @@ export interface ExecutionHistoryEntry {
  */
 export interface KernelHistoryOptions {
     /** Defaults to 'tail' -- the n most recent executions. */
-    histAccessType?: 'tail' | 'range' | 'search';
+    histAccessType?: 'tail' | 'range' | 'search' | undefined;
     /** Include each entry's output alongside its input. Defaults to false -- the kernel doesn't actually record output today either way, so this currently only ever comes back empty. */
-    output?: boolean;
-    raw?: boolean;
+    output?: boolean | undefined;
+    raw?: boolean | undefined;
     /** Max entries to return ('tail'/'search'). Defaults to 100. */
-    n?: number;
+    n?: number | undefined;
     /** 'range' only. */
-    session?: number;
-    start?: number;
-    stop?: number;
+    session?: number | undefined;
+    start?: number | undefined;
+    stop?: number | undefined;
     /** 'search' only -- a glob pattern (*, ?). */
-    pattern?: string;
-    unique?: boolean;
+    pattern?: string | undefined;
+    unique?: boolean | undefined;
 }
 /**
  * One entry from a real history_reply: [session, line_number, input], or
@@ -179,13 +180,13 @@ export interface ShinyAppOptions {
     /** Directory containing the Shiny app (server.R/ui.R or app.R). */
     appDir: string;
     /** Defaults to an OS-assigned free port. */
-    port?: number;
+    port?: number | undefined;
     /** Defaults to '127.0.0.1'. */
-    host?: string;
+    host?: string | undefined;
     /** Defaults to false -- the caller decides how/where to display the app. */
-    launchBrowser?: boolean;
+    launchBrowser?: boolean | undefined;
     /** Max time to wait for the app to start accepting connections, in ms. Defaults to 10000. */
-    readyTimeout?: number;
+    readyTimeout?: number | undefined;
     /**
      * Environment variables to set (via Sys.setenv()) in the R session
      * before launching the app -- e.g. rmncah's app.R reads
@@ -195,7 +196,7 @@ export interface ShinyAppOptions {
      * that reads them after runApp() starts, since Sys.setenv() itself runs
      * synchronously right before it in the same execute() call.
      */
-    env?: Record<string, string>;
+    env?: Record<string, string> | undefined;
 }
 export interface ShinyAppHandle {
     host: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damurka/jovian",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "author": "David Kariuki",
   "repository": {
@@ -50,8 +50,8 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@damurka/jovian-win32-x64": "0.1.0",
-    "@damurka/jovian-linux-x64": "0.1.0",
-    "@damurka/jovian-darwin-arm64": "0.1.0"
+    "@damurka/jovian-win32-x64": "0.1.1",
+    "@damurka/jovian-linux-x64": "0.1.1",
+    "@damurka/jovian-darwin-arm64": "0.1.1"
   }
 }

package/packages/hera/DESCRIPTION

@@ -26,4 +26,4 @@ Imports:
 URL: https://github.com/damurka/jovian
 BugReports: https://github.com/damurka/jovian/issues
 Config/roxygen2/version: 8.0.0
-Config/jovian/release: 0.1.0
+Config/jovian/release: 0.1.1