Support additional package repositories

README.md

@@ -32,7 +32,7 @@ Full documentation: <https://r-lib.github.io/ir/>
 
 - **The file explains itself.** R and Python package requirements live in the script or document, not in a separate setup note.
 - **Fast by design.** `ir` keeps package setup direct and reuses cached resolutions and libraries when the same requirements are seen again.
-- **Reproducibility is explicit.** Use frontmatter `r-version`, `--r-version`, or `IR_R_VERSION` to select R by version. Use `--rscript` or `IR_RSCRIPT` only when you need a machine-local Rscript override. Use `--exclude-newer`, `IR_EXCLUDE_NEWER`, or frontmatter `exclude-newer` to resolve packages as of a specific date. Without another R selector, the date selects the latest R minor released by then. When `r-version` can match more than one R minor, the date limits selection to minor versions released by then.
+- **Reproducibility is explicit.** Use frontmatter `r-version`, `--r-version`, or `IR_R_VERSION` to select R by version. Use `--rscript` or `IR_RSCRIPT` only when you need a machine-local Rscript override. Use `--exclude-newer`, `IR_EXCLUDE_NEWER`, or frontmatter `exclude-newer` to resolve the default PPM repository as of a specific date. Without another R selector, the date selects the latest R minor released by then. When `r-version` can match more than one R minor, the date limits selection to minor versions released by then.
 - **It works with normal R habits.** Forward `Rscript` options, render or preview Quarto documents, evaluate inline expressions, or use `--with` for one-off packages.
 - **Package tools are easy to try.** Run package executables with `rx`, or install persistent launchers backed by a durable tool store.
 
@@ -46,6 +46,7 @@ ir run --vanilla script.R
 ir render report.qmd --to html
 ir preview report.qmd
 ir run --with cli -e 'cli::cli_alert_success("works")'
+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

docs/cache.qmd

@@ -8,19 +8,22 @@ 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 that repository state is immutable.
+Snapshot resolution without additional repositories uses the `exclude-newer` date in the key because the default PPM repository state is immutable.
+Additional repositories are used as provided and may change, so 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.
+Cache-backed materialised libraries are content-addressed by the install refs passed to `renv::use()`, the resolved artifact identities reported by pak, ordered repositories, R version, and platform.
+Artifact identities use repository SHA-256 or MD5 checksums when available, resolved source commit hashes, and source URLs as a fallback.
+After a resolution marker expires, a repository package rebuilt under the same name and version therefore receives a new library when its advertised checksum changes.
+Scripts or tools that resolve to the same package artifacts share one 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,6 +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` applies to the default PPM repository; repositories supplied with `repos` or `--repo` are used as provided 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/index.qmd

@@ -28,7 +28,7 @@ transitive dependencies.
 
 - Declare package requirements in script frontmatter and run the file directly with `ir run`.
 - Resolve packages once, then reuse content-addressed cached libraries on later runs.
-- Pin CRAN resolution to a Posit Package Manager snapshot with `--exclude-newer`, `IR_EXCLUDE_NEWER`, or frontmatter `exclude-newer`.
+- Pin the default CRAN resolution to a Posit Package Manager snapshot with `--exclude-newer`, `IR_EXCLUDE_NEWER`, or frontmatter `exclude-newer`.
 - Select R with `--rscript`, `--r-version`, environment variables, frontmatter `r-version`, or `exclude-newer`. When `r-version` can match more than one R minor, `exclude-newer` limits the choice to minor versions released by the snapshot date.
 - Evaluate inline expressions with `ir run -e` and add command-line packages with `--with`.
 - Render or preview Quarto documents and Quarto-formatted R scripts through `ir render` or `ir preview`, using the same package metadata model with `rmarkdown` seeded automatically for the knitr engine.

docs/quarto.qmd

@@ -43,6 +43,8 @@ $ 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.
+`ir.repos` is a YAML sequence of package repository specs.
+Repeatable `--repo` values come first, followed by `ir.repos`, then the default repository.
 
 `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`.
@@ -64,6 +66,8 @@ An empty `--exclude-newer` or `IR_EXCLUDE_NEWER` overrides frontmatter `ir.exclu
 Future snapshot dates also resolve latest packages.
 When `r-version` can match more than one R minor, the snapshot date limits selection to minor versions released by that date.
 An exact R version or explicit Rscript selection remains authoritative.
+`exclude-newer` applies to the default PPM repository only.
+Repositories supplied through `ir.repos` or `--repo` remain live and may contain newer packages.
 
 When `ir` selects an R executable by `--rscript`, `IR_RSCRIPT`, `--r-version`, `IR_R_VERSION`, frontmatter `ir.r-version`, or date-only `exclude-newer`, it sets `QUARTO_R` so Quarto renders with that R.
 Frontmatter `ir.rscript` is rejected.

docs/run.qmd

@@ -36,6 +36,7 @@ $ ./script.R
 The script frontmatter supports:
 
 - `packages`: package refs resolved with pak.
+- `repos`: optional package repository specs used before the default repository.
 - `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,6 +62,32 @@ 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.
 
+## Package repositories
+
+Use `repos` when a package or one of its dependencies is published outside CRAN:
+
+```r
+#!/usr/bin/env -S ir run
+#| packages:
+#|   - r-xla/anvl
+#| repos:
+#|   - https://r-xla.r-universe.dev
+
+library(anvl)
+```
+
+`repos` must be a YAML sequence of repository specs accepted by pak.
+Repositories supplied with repeatable `--repo` options are placed first, followed by frontmatter `repos`, then the default CRAN or PPM repository.
+Repeated repository specs are removed while preserving that order.
+
+```console
+$ ir run --repo https://r-xla.r-universe.dev --with r-xla/anvl -e 'library(anvl)'
+```
+
+`exclude-newer` selects a dated snapshot for the default PPM repository.
+Repositories supplied through `repos` or `--repo` are used as provided and may contain newer packages.
+Because those repositories may change, resolutions that use them expire like latest-package resolutions even when `exclude-newer` is set.
+
 ## Python environments
 
 Use `python-packages` or `python-version` to ask `ir run` for a Python environment before launching the script.

docs/tools.qmd

@@ -31,6 +31,7 @@ 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
 ```
@@ -88,14 +89,15 @@ $ 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 that were used at install time.
 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.