---
title: "Getting Started with courieR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with courieR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

courieR syncs installed R packages between R versions on the same machine. You can migrate from an old version to a new one, keep two versions in parity, or selectively push packages in either direction — all from a point-and-click dashboard or from the R console.

## Installation

Install courieR on any R version you want to work from (it does not need to be installed on every version it manages):

```{r}
remotes::install_github("lennon-li/courieR")
```

## Step 1 — Discover Your R Installations

`find_routes()` scans the system and returns a data frame of every R version it can find:

```{r}
library(courieR)

routes <- find_routes()
routes[, c("version", "rscript_path", "is_current")]
#>   version                                           rscript_path is_current
#> 1   4.6.0         C:/Program Files/R/R-4.6.0/bin/x64/Rscript.exe       TRUE
#> 2   4.5.2         C:/Program Files/R/R-4.5.2/bin/x64/Rscript.exe      FALSE
#> 3   4.5.2  C:/Users/you/AppData/Local/Programs/R/R-4.5.2/bin/...      FALSE
#> 4   4.5.1  C:/Users/you/AppData/Local/Programs/R/R-4.5.1/bin/...      FALSE
#> 5   4.1.1              C:/Users/you/Documents/R/R-4.1.1/bin/...      FALSE
```

`is_current = TRUE` marks the R you are running right now.

### What gets detected

On **Windows**, `find_routes()` checks the HKLM registry (admin installs), the HKCU registry (non-admin installs via the standard CRAN installer), `%ProgramFiles%\R`, `%LOCALAPPDATA%\Programs\R`, `%USERPROFILE%\Documents\R`, and any versions managed by [rig](https://github.com/r-lib/rig).

On **macOS**, it checks the system R framework (`/Library/Frameworks/R.framework`), the user framework (`~/Library/Frameworks/R.framework`), Homebrew (`/opt/homebrew/opt/r` and `/usr/local/opt/r`), and rig-managed versions.

On **Linux**, it checks `/opt/R` (rig system-wide), `~/.local/share/rig/R` (rig user-local), conda environments, and the system `Rscript` on `$PATH`.

To include a non-standard path, pass it explicitly:

```{r}
routes <- find_routes(search_paths = "/opt/custom-r/bin/Rscript")
```

## Step 2a — Use the Dashboard (Recommended)

```{r}
open_hub()
```

The dashboard opens in your browser. At the top, a header bar lists every detected R installation; the two you select are highlighted in amber (A) and teal (B).

### Sync tab

The **Sync** tab is the main workflow:

1. **Select first installation** — choose your "A" R from the dropdown
2. **Select second installation** — choose your "B" R
3. Click **Compare** — a summary strip appears above the table showing how many packages are identical, missing from one side, or at different versions
4. Review the comparison table (filterable, 50 rows by default)
5. Click one of the three sync buttons:
   - **Copy A → B** — installs or upgrades into B every package that A has at a newer or equal version
   - **Copy B → A** — the reverse
   - **Two-Way Sync** — brings both installations to full parity

### Advanced tab

The **Advanced** tab gives lower-level access:

- **Packages** — full package list for any selected R, with version and source
- **Delivery Receipt** — results of the last sync operation
- **Details** — currently selected source and destination paths
- **Manifest** — raw package manifest export

## Step 2b — Use the CLI

Prefer code? `ship()` does the same thing programmatically:

```{r}
# always do a dry run first
result <- ship(
  source_path = routes$rscript_path[2],   # old R
  target_path = routes$rscript_path[1],   # new R (current)
  dry_run = TRUE
)
print(result$plan)
```

When you are happy with the plan, run for real. Pass `upgrade = TRUE` to also update packages that are present but at an older version (this is what the Sync tab does automatically):

```{r}
result <- ship(
  source_path = routes$rscript_path[2],
  target_path = routes$rscript_path[1],
  upgrade = TRUE
)

# check for any errors
result$results[result$results$status == "error", ]
```

## Inspecting Libraries Manually

`manifest()` lists packages for any R version. `inventory()` compares two manifests:

```{r}
a_pkgs <- manifest(rscript_path = routes$rscript_path[1])
b_pkgs <- manifest(rscript_path = routes$rscript_path[2])

comp <- inventory(a_pkgs, b_pkgs)
nrow(comp$missing)    # packages in A but not in B
nrow(comp$outdated)   # packages where A has a newer version than B
```

## Tips

- courieR skips base and recommended packages — only user-installed packages are migrated
- If a package fails to install, check `result$results` for the error message
- CRAN packages are reinstalled fresh from CRAN; packages installed from other sources (GitHub, Bioconductor) are detected and sourced via pak
- The Sync tab comparison table supports column-level filtering — use the filter boxes under each header to narrow to specific packages or statuses