fix!: run root preinstall before reify

[owlstronaut]

BREAKING CHANGE: root `preinstall` now runs before dependencies are installed.

Summary

Moves the root preinstall script back to its documented position: before dependencies are installed. Restores behavior that shipped through npm 6 and was unintentionally broken in npm 7 when Arborist took over reify.

Fixes #2660.

The bug

The scripts docs have always said preinstall runs "before the package is installed." Since npm 7, the root package.json's preinstall has actually run after arb.reify() i.e. after every dependency has been resolved, fetched, and unpacked. Arborist explicitly excludes the project root from its rebuild queue (reify.js:1234, !diff.ideal.isProjectRoot), and lib/commands/install.js appended preinstall to the post-reify lifecycle loop along with install, postinstall, prepublish, preprepare, prepare, postprepare. npm ci has the same shape.

Net effect: there is currently no way to run a script at the root before dependencies hit disk. Projects that want to bootstrap auth, generate files consumed during resolution, or gate installs behind a precondition have had no supported hook for five years.

The fix

Split the root lifecycle loop in two:

1. preinstall runs via a small helper before arb.reify().
2. install, postinstall, prepublish, preprepare, prepare, postprepare run after reify, as they did before.

Same split applied to npm ci.

Why now, and why not wait for a lifecycle redesign

This has history:

• Aug 2020 - [BUG] Preinstall script runs after installing dependencies #2660 filed by @ljharb.
• Feb 2021 - fix(preinstall): run preinstall before reify #2713 opened by @wraithgar with essentially this same code change, then self-closed as "too breaking without broader design work."
• Jul 2021 - cli team meeting decided to revert preinstall ordering in the next major.
• 2021 - RFC #403 (preunpack) and RFC #437 (preinstall revert) opened. Neither progressed. RFC 403's preunpack hook was rejected in triage as not solving the actual bug.
• 2021–2025 - Tracker went cold.
• Feb 2026 - feat: add preunpack lifecycle script that runs before installation #8972 opened implementing the rejected RFC 403 preunpack approach. Close but not the right fix.

A comprehensive lifecycle redesign is still the right long-term project and has clearly not happened in five years. Gating the revert on it was reasonable in 2021; but has proven that continuing to gate on it in 2026 just means users keep hitting a bug the docs promise doesn't exist. npm 12 is the right window to ship the scoped revert and decouple it from a future lifecycle rewrite.

The code change here is functionally the same as #2713 The differences are: it also patches npm ci, updates the docs to match reality, adds regression tests, and ships in a major (npm 12) rather than being blocked on a design gate that no longer has owners.

Closes / supersedes

When this lands:

• Closes [BUG] Preinstall script runs after installing dependencies #2660
• Closes feat: add preunpack lifecycle script that runs before installation #8972 (supersedes the preunpack approach)
• Closes RFC: Add preunpack life cycle script rfcs#403 (supersedes — preunpack not needed)
• Resolves RFC: Robust Lifecycle Scripts rfcs#437 (the scoped revert it proposed)