fix(patches): validator portability, clearer docs, broader hook trigger

.superpowers/handoff/task-A6-brief.md

@@ -0,0 +1,150 @@
+### Task A6: Wire patched repo into the pak install path
+
+**Files:**
+- Modify: `R/install_helpers.R:333-389` (`run_pak_install_with_mutex`)
+- Modify: `R/install-deps.R:23-75` (`install_pkg_sys_deps`)
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: `prepare_patched_repo()`.
+- Produces: `run_pak_install_with_mutex(local_clone_dir_single, env_vars, patched_repo = NULL)` — prepends `file://<patched_repo>` to `options("repos")` for the install; `install_pkg_sys_deps(package_name, tag, local_clone_dir, platform, aggressive_cleanup = FALSE, patches = NULL, arch = NULL)` — builds the patched repo before installing.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("run_pak_install_with_mutex prepends the patched repo to repos", {
+  seen <- NULL
+  local_mocked_bindings(
+    acquire_pak_mutex = function(...) tempfile(),
+    release_pak_mutex = function(...) invisible(NULL),
+    retry_with_backoff = function(func, ...) func()
+  )
+  local_mocked_bindings(
+    local_install_deps = function(...) {
+      seen <<- getOption("repos")
+      invisible(TRUE)
+    },
+    .package = "pak"
+  )
+
+  run_pak_install_with_mutex(
+    tempfile(), list(), patched_repo = "/tmp/patched"
+  )
+
+  expect_true(any(grepl("file:///tmp/patched", seen)))
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL — `patched_repo` argument not yet accepted / repos not prepended.
+
+- [ ] **Step 3: Edit `run_pak_install_with_mutex` in `R/install_helpers.R`**
+
+Change the signature line:
+
+```r
+run_pak_install_with_mutex <- function(local_clone_dir_single, env_vars) {
+```
+
+to:
+
+```r
+run_pak_install_with_mutex <- function(
+  local_clone_dir_single,
+  env_vars,
+  patched_repo = NULL
+) {
+```
+
+Replace the inner `retry_with_backoff(...)` block (the one wrapping `pak::local_install_deps`) with:
+
+```r
+          retry_with_backoff(function() {
+            withr::with_envvar(env_vars, {
+              repos <- getOption("repos")
+              if (!is.null(patched_repo)) {
+                repos <- c(
+                  patched = sprintf("file://%s", patched_repo),
+                  repos
+                )
+              }
+              withr::with_options(list(repos = repos), {
+                # Default to non-verbose (suppressed messages)
+                suppressMessages(pak::local_install_deps(sprintf(
+                  "%s",
+                  local_clone_dir_single
+                )))
+              })
+            })
+          })
+```
+
+- [ ] **Step 4: Edit `install_pkg_sys_deps` in `R/install-deps.R`**
+
+Change the signature to add `patches` and `arch`:
+
+```r
+install_pkg_sys_deps <- function(
+  package_name,
+  tag,
+  local_clone_dir,
+  platform = platform,
+  aggressive_cleanup = FALSE,
+  patches = NULL,
+  arch = NULL
+) {
+```
+
+Immediately before the `run_pak_install_with_mutex(...)` call, insert:
+
+```r
+  # Build a local repo of patched binaries (if any apply) and serve it to pak.
+  r_minor <- paste(
+    R.version$major,
+    strsplit(R.version$minor, ".", fixed = TRUE)[[1L]][1L],
+    sep = "."
+  )
+  patched_repo <- tryCatch(
+    prepare_patched_repo(patches, platform, arch, r_minor),
+    error = function(e) {
+      log_warn(sprintf("Patch preparation failed: %s", conditionMessage(e)))
+      NULL
+    }
+  )
+```
+
+and change the call from:
+
+```r
+  run_pak_install_with_mutex(
+    local_clone_dir_single,
+    env_vars
+  )
+```
+
+to:
+
+```r
+  run_pak_install_with_mutex(
+    local_clone_dir_single,
+    env_vars,
+    patched_repo = patched_repo
+  )
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add R/install_helpers.R R/install-deps.R tests/testthat/test-patches.R
+git commit -m "feat(patches): serve patched binaries to pak during dep install"
+```
+
+---
+