pm/node: honor XDG_DATA_HOME for the shim dirs on a fresh install

[colinhacks]

A fresh install now uses $XDG_DATA_HOME/nub/<leaf> when that variable is set. An existing ~/.nub/<leaf> always wins: relocating an installed shim dir would leave the profile's PATH line naming the old path, so a bare npm would silently keep running pre-upgrade binaries.

Three consumers assumed a fixed path and are fixed with it:

• invoked_as_persistent_node_shim — a mismatch would have made the global node AUGMENT every node process.
• which_node's recursion guard — a mismatch would have let nub resolve its own shim as the real node.
• Removal — unshimming an XDG install from a shell without the variable orphaned the binaries.

Closes #750

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nub	Error		Aug 19, 2026 11:23pm

[pullfrog]

Important

The resolution rule and the in-crate consumers look right, but the enumeration of consumers is incomplete: the three installer/upgrade shim refreshers outside nub-core still look only in ~/.nub/shims, and nub node unshim did not get the sweep-aware reporting nub pm unshim got.

Reviewed changes — the full diff at 2b2b3df (4 files, 1 commit), plus the out-of-diff consumers of shim_dir() / node_shim_dir() across install.sh, install.ps1, npm/nub/postinstall.js, cli.rs and the shim test suites.

• resolve_shim_dir seam — new pm::shim::resolve_shim_dir(home, xdg_data, leaf) returns $XDG_DATA_HOME/nub/<leaf> only when the legacy ~/.nub/<leaf> does not exist on disk, so XDG governs a fresh install and never relocates an installed one.
• Shape-based node-shim identification — invoked_as_persistent_node_shim swaps exact canonical-path equality for is_node_shim_dir_shape (a node-shim leaf under a nub/.nub parent), and which_node_in adds the same predicate alongside its existing exact-path guard.
• Sweeping removal — shim_dirs_for_removal returns three candidates (legacy, current XDG, XDG spec default, deduped); remove_shims changes from Result<bool> to Result<Vec<PathBuf>> and run_pm_unshim names each dir it removed plus warns when a PATH block was stripped with nothing found.
• Dual PATH blocks — new *_BLOCK_XDG descriptors, with dir_marker widened from .nub/shims to nub/shims so one descriptor's strip_block removes either line.

⚠️ The installer and postinstall shim refreshers still look only in ~/.nub/shims

Three upgrade channels re-link the PM shims after swapping the nub binary, and all three hardcode the legacy path and bail silently when it is absent. A user whose shims live under $XDG_DATA_HOME gets no refresh at all, so npm/pnpm/yarn keep executing the pre-upgrade inode with no error — the failure install.sh:207-209 itself calls "worse than any loud breakage". Their comments also cite shim_dir() as the authority for the fixed path, which this PR makes false.

Technical details

# Installer shim refreshers are not XDG-aware

## Affected sites
- `install.sh:217` and `site/public/install.sh:217` — `local shim_dir="$HOME/.nub/shims"`, then `[[ -d "$shim_dir" ]] || return 0`. The curl channel silently skips an XDG install.
- `install.ps1:136` and `site/public/install.ps1:136` — `$shimDir = "$env:USERPROFILE\.nub\shims"`, then `if (-not (Test-Path …)) { return }`. Same on the irm channel. `xdg_data_home()` (`crates/nub-core/src/pm/shim.rs:441`) has no Windows gate, so a Windows user with the variable set reaches the XDG branch.
- `npm/nub/postinstall.js:94` — `path.join(os.homedir(), ".nub", "shims")`, then a `readdirSync` whose ENOENT catch returns. Same on `npm i -g @nubjs/nub`.
- Stale comments asserting the path is fixed: `install.sh:214-215`, `install.ps1:130-132`, `npm/nub/postinstall.js:6,67,102,168`.
- Also stale for the same reason, functionally harmless: `crates/nub-core/src/pm/shim.rs:1258-1259` ("since `~/.nub/shims` is a fixed, possibly-symlinked dir").

Not affected, for the record: `relink_shims_after_selfowned` and `shim_relink_reminder`
(`crates/nub-cli/src/cli.rs:10704,10723`) call `shim_dir()`/`node_shim_dir()` and inherit XDG-awareness.
So `nub upgrade`'s self-owned channel is fine; only the three external refreshers are not.

## Required outcome
- Each of the three refreshers resolves the shim dir the same way `resolve_shim_dir` does — legacy wins if
  present, else `${XDG_DATA_HOME:-$HOME/.local/share}/nub/shims` — including the lock file that sits beside it
  (`$HOME/.nub/shims.lock` today, which must move with the dir or the lock protocol stops serializing against
  the Rust `ShimLock`).
- The "the shim dir is `~/.nub/shims` regardless of `NUB_INSTALL_DIR`" comments are corrected in all four
  installer copies.

## Open questions for the human
- `install.ps1` targets Windows, where XDG is not a platform convention. Is honoring `XDG_DATA_HOME` on Windows
  intended at all? If not, gating `xdg_data_home()` to non-Windows would remove this leg entirely and shrink
  the surface.

⚠️ nub node unshim did not get the sweep-aware reporting nub pm unshim got

remove_node_shim now sweeps every candidate dir, but run_node_unshim still prints node_shim_dir() — the dir that resolves now — so removing ~/.local/share/nub/node-shim from a shell without XDG_DATA_HOME reports removed /home/you/.nub/node-shim, naming a path that was never touched. The orphan warning added to run_pm_unshim has no counterpart either, so the custom-XDG-unset case reports a clean removal while the node hardlink stays on disk.

Technical details

# `run_node_unshim` reports a path the sweep may not have removed

## Affected sites
- `crates/nub-cli/src/cli.rs:10224-10245` — `run_node_unshim` calls `shim::node_shim_dir()?` for its message,
  then `shim::remove_node_shim()?` which returns only `(bool, Vec<PathBuf>)`. The `bool` cannot say WHICH of the
  three candidates existed.
- `crates/nub-core/src/node/shim.rs:173-190` — `remove_node_shim` collapses the sweep into `existed |= …`,
  discarding the removed paths.

## Required outcome
- `nub node unshim` names the directory (or directories) it actually removed, exactly as `run_pm_unshim` now does.
- The "a PATH block was stripped but no shim dir was found" warning added at `cli.rs:10118-10128` fires for the
  node shim too — that case is identical for both families.

## Suggested approach
Change `remove_node_shim` to return `(Vec<PathBuf>, Vec<PathBuf>)` (removed dirs, changed profiles), mirroring
`pm::shim::remove_shims`, and lift the shared reporting into one helper so the two verbs cannot drift again.

ℹ️ Four shim tests now read the ambient XDG_DATA_HOME

resolve_shim_dir picks the XDG path whenever the variable is set and the legacy dir does not yet exist, and every one of these tests starts from a freshly created empty home. None of them clears the variable, so they pass only because GitHub runners do not export it — on a developer box or container that does, they fail. This is the hermetic-test rule in AGENTS.md, and the diff introduced the dependency.

Technical details

# Shim tests depend on the ambient environment

## Affected sites
- `crates/nub-core/src/node/shim.rs:210-217` — `node_shim_dir_is_under_the_install_surface_not_the_cache`
  asserts `dir.ends_with(".nub/node-shim")` against the REAL home and REAL environment. This one is in a file
  the diff already edits.
- `crates/nub-cli/tests/pm_shim.rs:553,900` — assert `home.join(".nub/shims")`. The `run` helper
  (`pm_shim.rs:84-98`) removes only three `npm_*` vars; no `env_clear`.
- `crates/nub-cli/tests/node_shim.rs:58,97` — assert `home.join(".nub/node-shim")`. The `nub` helper
  (`node_shim.rs:40-55`) sets only `HOME` and `SHELL`.

## Required outcome
- Every test that asserts a shim path is deterministic regardless of the launching shell's `XDG_DATA_HOME`:
  either clear it in the spawn helpers, or set it explicitly and assert the path the test intends.
- The `node/shim.rs` unit test asserts through `resolve_shim_dir` with explicit arguments rather than through
  the environment-reading `node_shim_dir()`.
- Ideally one test covers the fresh-XDG install end to end, since that is the behavior this PR adds and no
  integration test exercises it today.

ℹ️ Nitpicks

• site/content/docs/pm/pm-shim.mdx:10,16 and site/content/docs/node.mdx:182,184,190,194 still present ~/.nub/shims and ~/.nub/node-shim as the unconditional location. AGENTS.md treats the docs update as part of a user-facing behavior change.
• crates/nub-core/src/node/discovery.rs:867-872 — the doc comment for which_node_in still says "Two recursion guards" and describes the persistent one as skipped "by CANONICAL-PATH equality"; there are three now, and the third is the shape check.
• crates/nub-core/src/node/discovery.rs:883 — dir.canonicalize() moved out of the short-circuited &&, so it now runs for every PATH entry even when persistent_shim is None. Necessary for the shape check and cheap, but worth knowing it is one extra stat per PATH entry per node resolution.
• .github/workflows/verify-install.yml:136 hardcodes $env:USERPROFILE\.nub\shims, so the reinstall-relinks check can never catch the install.ps1 gap above.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Important

The three installer refreshers and nub node unshim now match the resolution rule, and the function splits are behavior-preserving. But the new installer leg ships with no test, and the harness case that covers the old one can now write outside its sandbox. The four inline threads from the previous review are unaddressed and still open.

Reviewed changes — the delta since 2b2b3df (commit b09ab74), plus the out-of-diff machinery it depends on: ShimLock::acquire, tests/installer/run.sh, cache_dir / nub_data_dir, and the Windows test and CI legs.

• Installer refreshers made XDG-aware — install.sh, site/public/install.sh and npm/nub/postinstall.js split into a caller plus a per-directory worker, refreshing ~/.nub/shims and ${XDG_DATA_HOME:-$HOME/.local/share}/nub/shims, whichever exist, rather than reimplementing resolve_shim_dir.
• Sweep-aware nub node unshim — remove_node_shim returns (Vec<PathBuf>, Vec<PathBuf>), so the verb names the directories the sweep actually cleared and warns when a PATH block was stripped with nothing removed.
• xdg_data_home() gated to non-Windows — returns None under cfg(windows), pinning every Windows shim dir to %USERPROFILE%\.nub\shims, with the contract spelled out in both install.ps1 copies.
• Test hermeticity — pm_shim.rs's run and node_shim.rs's nub clear XDG_DATA_HOME, and the node/shim.rs unit test asserts through resolve_shim_dir with explicit arguments instead of the real environment.
• New recursion-guard test — which_node_skips_an_xdg_shim_dir_the_caller_could_not_name exercises the shape guard with persistent_shim: None and adds a negative control for a node-shim directory outside a nub root.

⚠️ The new installer XDG leg is untested, and the harness case covering the old one can now escape its sandbox

tests/installer/run.sh:247-282 is the only test of refresh_pm_shims, it runs in CI (verify-install.yml:285), and it exercises the legacy directory alone — so the leg this commit adds has no coverage on the channel where a miss is silent staleness. The same case sandboxes HOME but not XDG_DATA_HOME, and ${XDG_DATA_HOME:-$HOME/.local/share} is expanded by install.sh at run time: on a box that exports the variable to an absolute path outside the sandbox with a real nub/shims dir under it, the harness now ln -fs the developer's live npm/yarn shims onto the binary it just downloaded into a temp dir that trap clean EXIT deletes. Before this commit the refresher could only ever touch $HOME/.nub/shims, which was always inside the sandbox.

Technical details

# The installer harness neither covers nor contains the new XDG refresh leg

## Affected sites
- `tests/installer/run.sh:247-282` — `reinstall re-links existing PM shims and creates no new ones`.
  `export HOME=$(mksandboxdir)` at line 251 is the only environment isolation; no `XDG_DATA_HOME` handling.
  Every assertion (lines 269-280) names `$HOME/.nub/shims`, so the second candidate is never observed.
- `install.sh:225` and `site/public/install.sh:225` — the loop that introduces the out-of-sandbox candidate.
- `.github/workflows/verify-install.yml:285` — runs the harness. GitHub-hosted runners do not export
  `XDG_DATA_HOME`, so the gap is latent in CI rather than red.

## Required outcome
- The harness cannot write outside `$test_sandbox_dir` regardless of the invoking shell's environment.
- The XDG refresh leg is exercised: an existing `<xdg>/nub/shims` is re-linked to the new inode, the
  refresh-only contract still holds there (the four un-opted-in names must not appear), and no
  `<xdg>/nub/shims.lock` is left behind.

## Suggested approach
Add `export XDG_DATA_HOME=$(mksandboxdir xdg)` beside the existing `export HOME` in that case — this both
contains the run and gives the new leg a directory to act on — then duplicate the case's shim setup and its
four assertion groups against `$XDG_DATA_HOME/nub/shims`. The other harnesses in this repo already sandbox
the variable this way (`tests/daily-driver/run.sh:50`, `tests/conformance/run.sh:63`).

ℹ️ Nitpicks

• npm/nub/postinstall.js:6, :67 and :115 still describe the shim directory and its lock as unconditionally ~/.nub/shims; only the log line at :181 was updated to name the directory it acted on.
• crates/nub-cli/tests/pm_shim.rs:130-142 — run_with_timeout did not get the env_remove("XDG_DATA_HOME") its sibling run did. Its one caller (empty_path_entry_with_cwd_at_the_shim_does_not_loop) asserts no shim path, so this is latent rather than broken, but the two spawn helpers in the same file now disagree about hermeticity.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No new issues in this delta — one stale doc comment inline.

The three first-round threads this commit targets are genuinely fixed, and the new installer case is real coverage rather than theatre: install.sh rm -rfs and re-extracts bin/, so bin/nub gets a new inode while the surviving hardlinks keep the old one alive, and the -ef assertions go red without the XDG sweep. Four inline threads from the earlier rounds are still open and unreplied; the one describing behavior rather than doc text is the unshim sweep materializing an empty ~/.local/share/nub/.

Reviewed changes — the delta since b09ab74 (commit 61bcd28), plus the machinery it turns on: fish's combiner and command-substitution semantics, install.sh's reinstall path, and the current state of every open thread.

• Restored the exact-path compare in invoked_as_persistent_node_shim — it now tries canonical equality against node_shim_dir() first and falls back to is_node_shim_dir_shape, so a ~/.nub symlinked to a differently-named target is recognized again without losing the XDG-unset case.
• Replaced fish's set -q with a quoted test -n in both XDG fish_lines, so an exported-but-empty XDG_DATA_HOME takes the default branch instead of putting /nub/shims on PATH.
• Rewrote the remove_shims doc so its single Returns sentence describes the Vec<PathBuf> rather than the removed bool.
• Contained and covered the installer harness — the pre-existing case pins XDG_DATA_HOME inside its sandbox, and a new reinstall re-links PM shims under XDG_DATA_HOME case exercises the fresh-install shape: re-link to the new inode, the four un-opted-in names stay absent, no <xdg>/nub/shims.lock survives, and ~/.nub/shims is not conjured into existence.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No new issues in this delta — the guard is correct; its test is the one thing inline.

The if !dir.exists() { continue; } added to both sweeps does what the open thread asked: remove_shims_from is reached only from these two loops (plus tests), it already mapped NotFound to Ok(false), and ShimLock serializes writers — so skipping an absent candidate before the lock changes nothing except that ShimLock::acquire's create_dir_all(parent) no longer materializes ~/.local/share/nub/. That thread is resolved. Three inline threads from the earlier rounds are still open and unreplied, all describing doc text or test strength rather than behavior.

Reviewed changes — the delta since 61bcd28 (commit 5d2d224), plus the machinery it turns on: ShimLock::acquire, every caller of remove_shims_from, and the sibling unit tests that assert the removal seam's idempotence.

• Skipped absent candidates in both removal sweeps — remove_shims and remove_node_shim now continue past a candidate directory that does not exist, so an unshim can no longer create the very root it was searching for.
• Added a no-litter regression test — removing_shims_never_creates_a_root_that_was_not_there asserts the XDG root, the XDG spec default and the legacy root are all absent after a sweep over a pristine home.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No new issues in this delta. Not approving only because four inline threads from earlier rounds are still open.

The hoist does exactly what the open thread asked, and the test is now a genuine positive control rather than a re-implementation of the guard: with the early return deleted, ShimLock::acquire's create_dir_all(parent) materializes <home>/.nub, <home>/xdg-data/nub and <home>/.local/share/nub, and all three !root.exists() assertions go red. remove_shims_from has no callers outside the two sweeps and the unit tests, it already mapped NotFound to Ok(false), and an absent directory has no writer to serialize against — so returning before the lock changes nothing else.

Reviewed changes — the delta since 5d2d224 (commit fd093ea), plus the machinery it moves: ShimLock::acquire, every caller of remove_shims_from, and the sibling removal tests in pm/shim.rs and node/shim.rs that assert the seam's idempotence.

• Centralized the no-litter guard — the !dir.exists() early return moved from the two sweep loops into remove_shims_from, ahead of ShimLock::acquire, so remove_shims and remove_node_shim can no longer drift apart on the contract.
• Made the regression test exercise the real seam — removing_shims_never_creates_a_root_that_was_not_there now calls remove_shims_from unconditionally for every candidate and asserts both the false return and the absence of all three roots, replacing the caller-side exists() check and the dead if dir.exists() branch it used to carry.

Worth recording for a future reader: Path::exists() rather than try_exists()? is the right call in a sweep over speculative candidates. It swallows a stat error and skips that candidate, where try_exists()? would abort the whole unshim because one root nobody ever installed into could not be stat'd.

Still open and unreplied, all doc text or test strength rather than behavior: the pm_shim_block "can never disagree" doc, the xdg_data_home() Windows rationale, the weakened node_shim_dir_is_under_the_install_surface_not_the_cache, and the invoked_as_persistent_node_shim paragraph that 61bcd28 made false (that one carries a ready suggestion block).

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No blocking issues in this delta — all four open threads are genuinely closed and now resolved. One overclaiming comment inline, plus a user-facing string this doc-correction pass missed.

Reviewed changes — the delta since fd093ea (commit dd7177d), plus the sources its new claims rest on: node::discovery::cache_dir, pm_engine::nub_data_dir_from, and the restored body of invoked_as_persistent_node_shim.

• Corrected the xdg_data_home() Windows rationale — the gate is now justified by the install.ps1 cross-language contract instead of a cache_dir precedent that said the opposite. Both new neighbour claims check out: discovery.rs:986 reads XDG_CACHE_HOME before the cfg(windows) split at :990, and pm_engine/mod.rs:2825 reads XDG_DATA_HOME before its windows branch at :2828.
• Rewrote the invoked_as_persistent_node_shim doc — it now states that both the exact node_shim_dir compare and the shape fallback are load-bearing, and names the case each one covers, matching the body restored in 61bcd28.
• Scoped pm_shim_block's guarantee to install time — the doc records that ${XDG_DATA_HOME:-$HOME/.local/share} is re-expanded at every shell startup, so the written line can silently stop naming the installed directory, and what pinning it would cost.
• Restored the subject of node_shim_dir_is_under_the_install_surface_not_the_cache — it calls the real node_shim_dir() again and asserts it is not under the real cache_dir(). Repointing the shim dir at the cache root now makes dir.starts_with(&cache) fire, which the previous resolve_shim_dir("/home/probe", …) form could not.

ℹ️ nub pm --help still tells the user the shims go in ~/.nub/shims

This commit swept the shim-dir docs but not the one the user actually sees: cli.rs:9160 prints shim link npm/pnpm/yarn shims into ~/.nub/shims, which is wrong for exactly the fresh XDG installs this PR adds. Emitted output outranks a doc comment here, and the docs pages flagged in the first round are still in the same state.

Technical details

# User-facing surfaces still present the shim dir as unconditional

## Affected sites
- `crates/nub-cli/src/cli.rs:9160` — the `nub pm --help` body: `shim  link npm/pnpm/yarn shims
  into ~/.nub/shims (re-run after `nub upgrade`)`. Printed output, not a doc comment.
- `site/content/docs/pm/pm-shim.mdx:10,16` and `site/content/docs/node.mdx:182,184,190,194` — still
  present `~/.nub/shims` / `~/.nub/node-shim` as the location. `AGENTS.md` treats the
  `site/content/docs/` update as part of a user-facing behavior change.

## Required outcome
- The help string and the two docs pages describe the resolution rule the code implements: legacy
  `~/.nub/<leaf>` when it already exists, `$XDG_DATA_HOME/nub/<leaf>` on a fresh install with the
  variable set, and unix-only for the XDG half.

ℹ️ Nitpicks

• crates/nub-core/src/node/shim.rs:5 (module doc) and crates/nub-core/src/pm/shim.rs:7 still name the dedicated dir as ~/.nub/node-shim / ~/.nub/shims with no XDG qualifier — same for cli.rs:10132 and :10220. Internal only, unlike the help string above.
• remove_shims_from's doc (pm/shim.rs:707) still reads "[remove_shims] with an explicit dir (the testable body)", which stopped being literally true at b09ab74 when remove_shims became a sweep over three candidates.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

ℹ️ No blocking issues in this delta — the user-facing gap is closed and every claim checks out. One over-broad test guard inline.

Reviewed changes — the delta since dd7177d (commit e8a72b0), plus the surfaces it claims to have swept: every ~/.nub/shims / ~/.nub/node-shim string under crates/, site/ and README.md, resolve_shim_dir, cache_dir, and the CI workflows' XDG environment.

• Dropped the fixed path from nub pm --help — the line now reads link npm/pnpm/yarn shims onto PATH, which is true under either root. The string has no other occurrence in the repo, so no test asserted the old wording.
• Documented the resolution rule on both docs pages — pm-shim.mdx:10 and node.mdx:190 now state legacy-wins plus the unix-only XDG fresh-install case, matching resolve_shim_dir exactly. The remaining ~/.nub/… strings on those pages are console-output examples and are correct as the default case.
• Corrected two internal doc comments — the node::shim module header names the XDG alternative and points at resolve_shim_dir; remove_shims_from no longer calls itself "remove_shims with an explicit dir", which stopped being true once removal became a sweep.
• Softened the cache-containment test's hermeticity claim — the comment now names the collapsed-roots layout instead of asserting it cannot happen, and the containment check is skipped there rather than failing. xdg_data_home is pub(crate) and cache_dir is pub, so both references resolve from the test module.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes — the delta since e8a72b0 (commit 1420c8c), a single hunk in the node/shim.rs cache-containment test, plus the predicate's behavior against cache_dir, resolve_shim_dir and the legacy layout.

• Narrowed the cache-containment skip to the layout it excuses — user_collapsed_the_roots is now dir.starts_with(&data) && dir.starts_with(&cache), replacing the root-vs-root comparison.

The new form is tighter than the suggestion it answers. The second conjunct is literally the assertion's failure condition, so the skip can only ever suppress a failure that would genuinely fire, and the first conjunct confines it to an XDG-derived directory. Both false-skip directions from the previous form are closed: a data root merely ancestral to the cache (XDG_DATA_HOME=$HOME with the default ~/.cache/nub) no longer matches, and a legacy ~/.nub/node-shim cannot be skipped, since cache_dir always appends nub and no ordinary XDG_CACHE_HOME makes ~/.nub/node-shim a descendant of <XDG_CACHE_HOME>/nub. The comment above it names both directions accurately.

That was the last open thread on this PR; it is replied to and resolved.

  ^{｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

Important

The one-rule collapse is the right call and the migration path is sound. But ungating XDG_DATA_HOME on Windows — which this commit does deliberately — opened a fourth root, %LOCALAPPDATA%\nub\<leaf>, that neither the removal sweep nor the passthrough guard can reach. install.ps1 already sweeps both Windows roots; the Rust side and postinstall.js pick one.

Reviewed changes — the delta since 1420c8c (commit 5287636), plus the machinery the reversal turns on: every consumer of resolve_shim_dir, ShimLock's sibling-lock protocol across all four language copies, nub_passthrough_target's re-exec decision, and which candidate roots tests/installer/run.sh actually exercises.

• One unconditional resolution rule — resolve_shim_dir is now $XDG_DATA_HOME/nub/<leaf> → %LOCALAPPDATA%\nub\<leaf> on Windows → ~/.local/share/nub/<leaf>, with no "keep an existing ~/.nub/<leaf>" branch. That deletes the dual PATH-block descriptors, the widened strip marker and pm_shim_block(home)/node_shim_block(home) — a large simplification, and grep finds no dangling reference to any removed symbol under crates/.
• ~/.nub/<leaf> demoted to pre-move — migrate_legacy_shim_dir clears it on the install path, and run_pm_shim_install/run_node_shim_install both strip the stale PATH block before re-adding it, so a migrating user is not left blockless.
• xdg_data_home() ungated on Windows — the #[cfg(windows)] -> None gate added two commits ago is gone, and the rationale cites pnpm's getDataDir and corepack reading their XDG variable above the platform branch. The precedent checks out.
• Installer copies stay in lockstep — install.sh and site/public/install.sh are byte-identical, as are the two install.ps1 copies (verified by diff, both clean). All four writers compute the lock as <dir>.lock, matching ShimLock::acquire, so the cross-language protocol still serializes under the relocated roots.

The new installer case is real coverage rather than theatre: install.sh replaces bin/nub with a fresh inode, so the -ef assertions in reinstall re-links PM shims at the live XDG location go red without the XDG leg, and it checks the lock cleanup and the no-conjure contract on top. The nub_from_a_shim_dir_defers_to_the_official_binary rework likewise discriminates for the pre-move path — the old sibling-derived target yielded <xdg>/nub/bin/nub, so it fails without nub_install_bin_dir().

ℹ️ Doc comments in cli.rs still name the old fixed path

This commit swept the shim-dir prose in pm/shim.rs, node/shim.rs and both .mdx pages, but five doc comments in cli.rs still present ~/.nub/… as the unconditional location, and none sits inside a diff hunk so they cannot be anchored inline:

• crates/nub-cli/src/cli.rs:579 — the PmShim variant doc, "via a ~/.nub/shims hardlink".
• crates/nub-cli/src/cli.rs:3276 — "the PERSISTENT global node shim (nub node shim, ~/.nub/node-shim)".
• crates/nub-cli/src/cli.rs:9980 — run_pm_shim_install's doc, "hardlink the running nub under the six PM names in ~/.nub/shims".
• crates/nub-cli/src/cli.rs:10150 — run_node_shim_install's doc, "as node in ~/.nub/node-shim".
• crates/nub-cli/src/cli.rs:10252 — run_node_unshim's doc, "delete ~/.nub/node-shim".

Internal only — the bodies all call shim_dir()/node_shim_dir() and behave correctly.

ℹ️ The PR body describes the design this commit reversed

The body still explains the superseded rule, that an existing ~/.nub/<leaf> always wins so XDG governs only a fresh install. The change is now a one-way relocation with a migration step, which is a breaking change for every user who already ran nub pm shim — their shims move and the old PATH line is rewritten. Worth saying so in the body and the title, since "honor XDG_DATA_HOME for the shim dirs on a fresh install" no longer describes what lands.

ℹ️ Coverage the reversal leaves open

• No test drives nub_passthrough_target from the live XDG shim dir, which is the case nub_install_bin_dir() was introduced for. The one test covers the pre-move dir.
• Both tests/installer/run.sh cases export XDG_DATA_HOME — the first pins it to $HOME/.local/share for containment, the second to $HOME/xdg-data. Nothing exercises the variable being unset, which is the branch most fresh unix installs will take.
• The Windows leg of verify-install.yml seeds and asserts only %USERPROFILE%\.nub\shims, so the Windows resolution this commit added — both the %LOCALAPPDATA% default and the newly-ungated XDG branch — has no CI coverage at all. The PowerShell logic reads correctly, but that is inspection, not a passing test.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[pullfrog]

%LOCALAPPDATA%\nub\<leaf> is not a candidate here, and after this commit it is a root the tool genuinely installs into.

The sweep reaches it only through resolve_shim_dir at line 418, which returns it only when xdg_data is None. So on Windows with XDG_DATA_HOME set at unshim time, the three candidates are <xdg>/nub/shims, ~/.nub/shims and ~/.local/share/nub/shims — and shims installed by any earlier run, or from any shell that did not export the variable, sit untouched at %LOCALAPPDATA%.

This is the exact asymmetry the doc above already argues against. Line 426 pushes the XDG default unconditionally, precisely so a custom XDG_DATA_HOME cannot hide an install made without it; the Windows platform default needs the same treatment, and unlike the custom-XDG case the doc names as unknowable, this path is fully knowable — the process can read %LOCALAPPDATA% right now.

Two things make it worse than a cosmetic leak. run_pm_unshim's "a PATH block was removed but no shims directory was found" warning (cli.rs:10139) cannot fire on Windows: run_pm_shim_install returns at cli.rs:10061 before add_path_block(), so changed is always empty there. The user gets "<xdg>/nub/shims was already gone" and a clean exit while six shim hardlinks remain on PATH. And install.ps1:145-148 already sweeps both Windows roots (if/if, not if/elseif) with a comment explaining why — so the installer and the uninstaller now disagree about how many places shims can live.

The suggestion keeps a cfg!(windows) guard so nothing changes on unix, where LOCALAPPDATA is only ever set under Wine or a stray export.

Suggested change

	for candidate in [
	// The PRE-MOVE location. An unshim has to clean up an install made before
	// the shim dir moved, or those binaries stay on disk forever with their
	// PATH line stripped.
	legacy_shim_dir(home, leaf),
	// The XDG default, for a custom XDG_DATA_HOME that was set at install and
	// is unset now — the resolution above cannot name that path.
	home.join(".local").join("share").join("nub").join(leaf),
	] {
	for candidate in [
	// The PRE-MOVE location. An unshim has to clean up an install made before
	// the shim dir moved, or those binaries stay on disk forever with their
	// PATH line stripped.
	Some(legacy_shim_dir(home, leaf)),
	// The XDG default, for a custom XDG_DATA_HOME that was set at install and
	// is unset now — the resolution above cannot name that path.
	Some(home.join(".local").join("share").join("nub").join(leaf)),
	// The Windows default, for the mirror case: an install made without
	// XDG_DATA_HOME, unshimmed from a shell that exports it. Unlike the
	// custom-XDG case above this path IS knowable, and install.ps1 already
	// refreshes both Windows roots.
	local_app_data
	.filter(|_| cfg!(windows))
	.map(|l| l.join("nub").join(leaf)),
	]
	.into_iter()
	.flatten()
	{

[pullfrog]

Same gap as the removal sweep, one layer more damaging: is_a_shim_dir is built from shim_dir() — re-resolved now — and the pre-move dir, with no %LOCALAPPDATA% candidate.

So a Windows shim installed at %LOCALAPPDATA%\nub\shims and later invoked from a shell that exports XDG_DATA_HOME matches neither entry. is_a_shim_dir is false, the function returns None, and the shim runs its own stale bytes rather than deferring to ~/.nub/bin/nub. That is precisely the failure the doc at lines 1400-1411 describes — nub upgrade reports success while nub -v shows the old version — reintroduced through a different door.

Adding local_app_data().filter(|_| cfg!(windows)).map(|l| l.join("nub").join(SHIMS_LEAF)) to the array closes it, and pairs with the fix on shim_dirs_for_removal above. Worth noting the general shape: any function that has to answer "is this one of our shim dirs?" needs the full candidate set rather than the live resolution — that is now two of them, so a shared shim_dir_candidates() helper would keep the two from drifting again.

[pullfrog]

This else if makes the npm channel the odd one out. install.ps1:145-148 builds its root list with two independent ifs, so a Windows box with XDG_DATA_HOME set refreshes <xdg>\nub\shims and %LOCALAPPDATA%\nub\shims; here the else if means setting the variable silently drops the %LOCALAPPDATA% root from the sweep.

The consequence is the one the comment block directly above calls out by name: shims left pointing at the pre-upgrade inode, executing old bytes with no error. refreshShimsIn already skips an absent directory, so pushing both roots costs nothing when only one exists.

const roots = [];
if (process.env.XDG_DATA_HOME) {
  roots.push(process.env.XDG_DATA_HOME);
}
if (process.platform === "win32" && process.env.LOCALAPPDATA) {
  roots.push(process.env.LOCALAPPDATA);
}
if (roots.length === 0) {
  roots.push(path.join(home, ".local", "share"));
}

Mirroring install.ps1 is the cheaper direction than teaching install.ps1 to narrow, since the refresher is best-effort and an extra skipped directory is free.

[pullfrog]

This states two of the three branches — $XDG_DATA_HOME/nub/node-shim and the ~/.local/share default — but omits %LOCALAPPDATA%\nub\node-shim, which resolve_shim_dir returns on Windows and which nub node shim reaches through the same call.

pm-shim.mdx:10 in this same commit states all three, so the two pages now describe the same rule differently. Matching that sentence's phrasing would settle it: "$XDG_DATA_HOME/nub/node-shim when that variable is set, %LOCALAPPDATA%\nub\node-shim on Windows, and ~/.local/share/nub/node-shim otherwise".