fix: drop prefer-offline from .npmrc to avoid stale-cache ETARGET

[davedittrich]

prefer-offline bypasses staleness checks on cached registry metadata, so npm resolves against a packument that can predate versions the lockfile requires. With esbuild pinned to ^0.28.1 (overrides, #2493) and a cache topping out at 0.27.2, npm install fails:

npm error code ETARGET
npm error notarget No matching version found for esbuild@^0.28.1

The failure is silent and machine-dependent: it only reproduces on clones whose cache went stale before the pin landed, so CI stays green while contributors hit a hard install error.

What

Removes prefer-offline=true from .npmrc.

Why

prefer-offline bypasses staleness checks on cached registry metadata — npm only
reaches the network for packuments it is missing entirely, never to revalidate one
it already has. That means a clone can resolve dependencies against a cached view
of the registry that predates versions the lockfile requires.

This is currently reachable on main. #2493 pinned esbuild to ^0.28.1 via
overrides. On a machine whose cached esbuild packument predates that release,
npm install fails outright:

npm error code ETARGET
npm error notarget No matching version found for esbuild@^0.28.1.

Reproduced locally, where the cached packument topped out at 0.27.2:

$ npm view esbuild version # in-repo, prefer-offline on
0.27.2
$ npm view esbuild version --prefer-offline=false # actual registry
0.28.1

Two things make this worth fixing rather than papering over:

• It is invisible to CI. Runners start with a cold cache, so they always fetch
  fresh metadata and always pass. Only contributors with an aged cache hit it.
• It corrupts npm audit fix. With stale metadata npm cannot see the fixed
  releases, so it proposes downgrades instead — on this repo
  npm audit fix --force offered to take eslint 9 → 4, jest 30 → 25, and
  markdownlint-cli2 0.19 → 0.12.

The comment describes the flag as an install-performance tweak. The speed gain is
small, and it is paid for with non-reproducible resolution.

How

• Delete prefer-offline=true and its comment from .npmrc
• Leave legacy-peer-deps=true untouched

Testing

With the flag removed, npm install resolves esbuild@0.28.1 cleanly on the
previously-failing machine. Verified against main at bb45db4a:
npm run docs:build succeeds, and test:refs, test:install, test:urls,
test:channels, test:renderer, test:skills all pass.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f155e64-37a1-46f8-8b35-1d32866797a1

📥 Commits

Reviewing files that changed from the base of the PR and between bb45db4 and dcc8423.

📒 Files selected for processing (1)

• .npmrc

💤 Files with no reviewable changes (1)

• .npmrc

---

📝 Walkthrough

Walkthrough

The .npmrc configuration removes the offline installation preference and enables legacy peer dependency handling.

Changes

npm install configuration

Layer / File(s)	Summary
Peer dependency install setting .npmrc	Replaces prefer-offline=true with legacy-peer-deps=true and updates the related comment.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• bmad-code-org/BMAD-METHOD#1531: Removes the same offline npm preference while retaining legacy peer dependency handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the main change: removing prefer-offline from .npmrc to avoid stale-cache ETARGET failures.
Description check	✅ Passed	The description directly matches the changeset and explains the rationale, impact, and testing for removing prefer-offline.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}