Support additional package repositories

README.md

@@ -47,6 +47,7 @@ ir render report.qmd --to html
 ir preview report.qmd
 ir run --with cli -e 'cli::cli_alert_success("works")'
 ir run --with BiocGenerics -e 'library(BiocGenerics)'
+ir run --repo https://r-xla.r-universe.dev --with r-xla/anvl -e 'library(anvl)'
 ir run --r-version 4.3 script.R
 ir run --exclude-newer 2024-02-01 script.R
 rx btw --help
@@ -57,6 +58,9 @@ ir cache dir
 
 Bioconductor packages use their bare package names.
 pak selects the Bioconductor release compatible with the selected R.
+`--repo` adds a CRAN-like package repository, such as R-universe, before the defaults.
+For Git repositories, use a pak package ref such as `github::owner/repo` with `--with` or `--from`.
+`--exclude-newer` dates the default repositories; explicit repositories remain live.
 
 ## Install
 

docs/cache.qmd

@@ -8,19 +8,20 @@ Rust owns the cache root and passes it to the resolver R session as `IR_CACHE_DI
 This lets warm resolution-cache hits return without launching R while keeping resolver output in the same cache tree.
 Installed tools use the same resolver cache for tooling and markers, but their package libraries are materialised under the durable tool store instead of `IR_CACHE_DIR`.
 
-Resolution requests for ordinary registry refs are keyed by declared packages, resolution source, selected R executable, and runtime selectors such as `R_ARCH` and `R_HOME`.
+Resolution requests for ordinary registry refs are keyed by declared packages, ordered repositories, resolution source, selected R executable, and runtime selectors such as `R_ARCH` and `R_HOME`.
 If the same request was already resolved, `ir` reuses the cached library before launching the resolver R session, so pak is not invoked again.
 Latest resolution records a Unix timestamp inside the cache marker; markers older than `IR_LATEST_RESOLUTION_MAX_AGE_SECONDS` are refreshed in place, so newly published versions are picked up without accumulating one marker per refresh window.
 The default max age is 86400 seconds (24 hours).
 Snapshot resolution uses the `exclude-newer` date in the key because the default CRAN and Bioconductor PPM repository states are immutable.
+Because additional repositories remain live, resolutions that use `repos` or `--repo` retain the latest-resolution expiry even when `exclude-newer` is set.
 Python environments use separate cache markers that record the resolved Python executable path.
 If the recorded Python path no longer exists, `ir` resolves the Python environment again.
 
 Non-standard refs skip the resolution-marker cache.
 Each run asks pak to resolve them again, so branch heads, URLs, and local paths are not hidden behind a warm resolution marker.
 
 Cache-backed materialised libraries are content-addressed by the install refs passed to `renv::use()`, R version, and platform.
-Scripts or tools that resolve to the same install refs share one library.
+With additional repositories, the key also includes the ordered repositories and pak's artifact checksums, commit hashes, or source URLs, so a same-version rebuild does not reuse a stale library.
 Source refs are still passed to `renv::use()` on each run so renv can refresh source installs; renv may reuse its own package cache when the source has not changed.
 Installed tool libraries use the same content-addressing under `IR_TOOL_STORE_DIR`.
 

docs/config.qmd

@@ -71,7 +71,7 @@ Package snapshot date precedence for `ir run`, `ir render`, and `ir preview` is
 `IR_EXCLUDE_NEWER` is ignored when `--exclude-newer` is supplied.
 Set `--exclude-newer` or `IR_EXCLUDE_NEWER` to an empty string to override frontmatter `exclude-newer` and resolve latest packages.
 Future snapshot dates also resolve latest packages.
-`exclude-newer` dates the default CRAN and Bioconductor repositories with PPM snapshots.
+`exclude-newer` dates the default CRAN and Bioconductor repositories with PPM snapshots; additional repositories remain live and may contain newer packages.
 When Python metadata is present, the selected `exclude-newer` value is also used during Python environment resolution unless `--python-exclude-newer` or frontmatter `python-exclude-newer` is set.
 Set `python-exclude-newer` to `null`, or set `--python-exclude-newer` or frontmatter `python-exclude-newer` to an empty string, to resolve latest Python packages while keeping `exclude-newer` for R.
 R selection precedence is command line, then environment, then frontmatter `r-version`.

docs/quarto.qmd

@@ -44,6 +44,9 @@ $ ir render report.R
 
 The `ir.packages` value follows the same rules as script `packages`: use a YAML sequence where each entry is one package ref, or omit it, set it to `[]`, or set it to `null` for no dependencies.
 Bioconductor packages use their bare package names; pak selects the release compatible with the selected R.
+`ir.repos` is a YAML sequence of CRAN-like package repositories.
+Repeatable `--repo` values come before `ir.repos` and the default repositories.
+See [Package repositories](run.qmd#package-repositories) for package refs and snapshot behavior.
 
 `ir` resolves the document packages into the same cached library model used for scripts, then launches `quarto render`.
 Arguments after the source path are passed to `quarto render`.

docs/run.qmd

@@ -36,6 +36,7 @@ $ ./script.R
 The script frontmatter supports:
 
 - `packages`: package refs resolved with pak.
+- `repos`: additional R package repositories.
 - `r-version`: an optional R version requirement selected from installed versions reported by rig. Requirements that can match more than one R minor select released versions; use `devel` to select R-devel explicitly.
 - `python-packages`: optional Python package specs resolved with reticulate's uv environment helper.
 - `python-version`: an optional Python version requirement.
@@ -61,15 +62,31 @@ Local packages may be written as `local::path`, as a bare file-system path in pa
 Omit `packages`, use `packages: []`, or use `packages: null` when no package refs are needed.
 Unknown keys are ignored after YAML parsing, so future metadata such as `sys-reqs` can be present before `ir` supports it.
 
-## Bioconductor packages
+## Package repositories
 
-Bioconductor packages use their bare package names.
-pak selects the Bioconductor release compatible with the selected R.
+`repos` is a YAML sequence of CRAN-like repository specs accepted by pak, such as R-universe.
+For Git repositories, use a pak package ref under `packages` or with `--with`.
+
+```r
+#!/usr/bin/env -S ir run
+#| packages:
+#|   - r-xla/anvl
+#| repos:
+#|   - https://r-xla.r-universe.dev
+
+library(anvl)
+```
+
+Repeatable `--repo` values come before frontmatter `repos` and the default repositories.
 
 ```console
 $ ir run --with BiocGenerics -e 'library(BiocGenerics)'
+$ ir run --repo https://r-xla.r-universe.dev --with r-xla/anvl -e 'library(anvl)'
 ```
 
+Bioconductor packages use bare names; pak selects the release compatible with the selected R.
+`exclude-newer` dates the default CRAN and Bioconductor repositories, while `repos` and `--repo` remain live.
+
 ## Python environments
 
 Use `python-packages` or `python-version` to ask `ir run` for a Python environment before launching the script.

docs/tools.qmd

@@ -31,12 +31,14 @@ Tool runs support the same dependency and R selection flags as script runs:
 $ rx --with cli --from btw btw
 $ rx -w cli --from btw btw
 $ rx --from 'btw>=0.1.0' btw
+$ rx --repo https://example.r-universe.dev --from owner/pkg tool
 $ rx --r-version 4.5 --from btw btw
 $ rx --rscript /path/to/Rscript --from btw btw
 ```
 
 Package refs use pak syntax.
 Quote refs when the shell would otherwise interpret characters such as `>`.
+`--repo` adds CRAN-like package repositories; use pak package refs with `--from` or `--with` for Git repositories.
 
 ## Write package tools
 
@@ -88,14 +90,16 @@ $ ir tool install github::r-lib/Rapp
 $ ir tool install --bin-dir ~/.local/bin btw
 $ ir tool install --force btw
 $ ir tool install --with cli --r-version 4.5 btw
+$ ir tool install --repo https://example.r-universe.dev owner/pkg
 $ ir tool install --rscript /path/to/Rscript btw
 ```
 
 The tool store is configured with `IR_TOOL_STORE_DIR`.
 By default, it is `$XDG_DATA_HOME/ir/tools` or `~/.local/share/ir/tools` on Unix and macOS, and `%LOCALAPPDATA%\Programs\R\ir\tools` or `%USERPROFILE%\AppData\Local\Programs\R\ir\tools` on Windows.
 Installed tool libraries are persistent state, so `ir cache clean` does not remove them.
 
-Generated launchers keep the same resolved package ref, `--with` package additions, and R selection that were used at install time.
+Generated launchers keep the same resolved package ref, `--with` package additions, `--repo` repositories, and R selection used at install time.
+Recovery commands embedded in launchers omit HTTP repository userinfo, query strings, and fragments so they do not persist repository credentials.
 They set `R_LIBS` to the resolved library and `R_LIBS_USER=NULL`.
 Nested `#| launcher:` metadata is included in generated launchers.
 If there is no `launcher.name`, top-level `#| name:` is used for the launcher name when present.