feat: native dependency patching (npm patch add/commit/update/ls/rm) (#9439)

Implements native dependency patching per [RFC
#862](npm/rfcs#862): a first-class way to apply
small, local modifications to an installed dependency and have them
re-applied automatically on every install, with no external tooling or
postinstall scripts.

Patches are declared in a new `patchedDependencies` field of the root
`package.json`, stored as plain unified diffs under `patches/`, and
recorded with a content hash in `package-lock.json`. Because the patch
is applied during the install itself, it works for transitive
dependencies, across every `install-strategy`, and is **not** disabled
by `--ignore-scripts`.

## The `npm patch` command

A new command with five subcommands (and a bare `npm patch <pkg>`
shorthand for `add`):

- **`npm patch add <pkg>[@<version>]`** — extracts a clean copy of the
resolved registry tarball into a temp directory outside `node_modules`
and prints the path to edit. Ambiguous when multiple versions are
installed; the error lists the exact selectors to retry with.
- **`npm patch commit <edit-dir>`** — diffs the edited directory against
a fresh copy of the original tarball, writes
`<patches-dir>/<name>@<version>.patch`, adds the `patchedDependencies`
entry, and reifies to apply the patch and record its integrity in the
lockfile. `package.json` is excluded from the diff — Arborist resolves
the pre-patch manifest, so a patched manifest would change
resolution-affecting fields on disk without being honored (silent
partial application); `commit` warns when an edit only touches it.
- **`npm patch update <pkg>[@<old-version>] [--to <new-version>]`** —
rebases an existing patch onto a new version. It reads the target from
`--to` or the lockfile, 3-way-merges the existing patch onto the new
tarball in a throwaway git repo, and rewrites `package.json` +
`package-lock.json` **without touching `node_modules`** (so it works
from a failed-install state). On conflict it leaves an edit dir with
`<<<<<<<` markers, finalized by `npm patch commit`. Exact selectors are
renamed; range/name-only selectors gain a new exact entry and keep the
old one while it still wins another installed node.
- **`npm patch ls`** — lists registered patches and how many installed
nodes each matches (flagging overlapping range selectors that conflict
on a node).
- **`npm patch rm <pkg>[@<version>]`** — removes the matching entries,
deletes the patch file when no other entry references it, and reifies to
revert the files.

## Install-time apply pipeline

Patch resolution and application live in Arborist so every install path
honors them:

- **`resolvePatchedDependencies`** resolves the root
`patchedDependencies` map against the ideal tree, attaching
`node.patched = { path, integrity }` to each matched node. Selector
precedence is exact > range-subset > name-only, with ambiguous
overlapping ranges surfaced as a hard error.
- **reify** applies the diff after extraction and records the patched
integrity in the lockfile. `diff.js` forces re-extraction when a node's
patch integrity changes, and re-extracts to revert when a
previously-patched node loses its selector (`patchRemoved`).
- **`install-strategy=linked`** is supported via a content-addressed
side-store: the store key is suffixed with the patch identity (`+patch`)
so a patched and unpatched copy of the same version coexist without
collision. A failed patch under linked strategy is always a hard error
(the side-store cannot represent unpatched contents at a patched key
without later installs silently trusting it).

## Lockfile

Patches require `lockfileVersion: 4` so that older npm clients abort
rather than silently installing unpatched code. When any node is
patched, npm writes version 4 and **warns** if this upgrades a lower
pinned `lockfile-version` (the safety gate cannot be honored otherwise).
`npm ci` revalidates each patch's existence and integrity against the
lockfile before installing.

## Failure modes

By default any patch problem is a hard error that aborts the install: a
patch that fails to apply, a registered patch that matches no installed
package, a missing patch file, or a patch whose hash does not match the
lockfile. Two **CLI-only** relax flags cover one-off cases —
`--allow-unused-patches` and `--ignore-patch-failures` — and are
rejected in `npm ci` and when set anywhere other than the command line.

## Non-registry dependencies

Patches need a stable registry tarball as their baseline, so a
dependency reached through a non-registry consumer edge (`file:`,
`git:`, `http(s):`) is rejected with `EPATCHNONREGISTRY`, both by `npm
patch add` and at install time. The check is edge-based (the consuming
spec's type), not node-based, so it does not falsely reject edgeless
nodes such as linked-store entries or extraneous installs, which are
still registry deps. `npm:` registry aliases are correctly classified as
registry deps and are supported by the install engine; the `npm patch
add <alias>` ergonomics will land in a fast-follow.

## Publish / pack

`patchedDependencies` is stripped from the published **registry
manifest** (libnpmpublish) so the field never leaks to the packument.
Stripping it from the **tarball's own `package.json`** and excluding the
`patches/` directory from the tarball is a coordinated follow-up in
`pacote` + `npm-packlist` (those packages own the packed file list and
the manifest written into the tarball, neither editable from the CLI) —
see Follow-up work.

## Other surfaces

- `npm ls` annotates patched dependencies in its output.
- New config: `patches-dir`, `edit-dir`, `ignore-existing`,
`keep-edit-dir`, plus the two relax flags.
- New `npm-patch` man page and nav entry.

## Tests

Unit and integration coverage for every subcommand (including `update`'s
clean rebase, conflict→commit, and selector-rename/range-fork paths),
the apply pipeline, selector matching, linked-strategy apply/removal,
lockfile validation, publish stripping, and the relax flags. Arborist
and CLI suites pass at 100% coverage.

## Follow-up work

A few additive pieces are deliberately deferred — nothing in this PR
depends on them.

- **Tarball-side strip for publish/pack** — stripping
`patchedDependencies` from the tarball's own `package.json` and
excluding the `patches/` directory from the published tarball. This
can't be done in the CLI: the tarball's file list and manifest come from
`pacote` (packs the raw on-disk files) and `npm-packlist`, so it needs
coordinated changes there. Raised in the RFC review; the
registry-manifest strip in this PR already prevents the field from being
honored or appearing in the packument.

- **`npm patch add <alias>` ergonomics for `npm:` registry aliases** —
the install engine already treats `npm:` aliases as registry
dependencies and applies a hand-written `<alias>@<version>` selector
correctly today. What remains is the `add`/`commit` convenience:
resolving the alias to its real `name@version` tarball as the baseline
and keying the written selector on the alias name. Currently `npm patch
add <alias>` resolves the alias name as a real package and fails.

- **Binary files** — patches are unified text diffs, so binary files
(images, wasm, native addons) cannot be patched. This is a limitation of
the whole feature (shared with `patch-package`), not a regression; a
binary-aware path could be added later.

## References

Implements npm/rfcs#862

Author: manzoorwanijk

DEPENDENCIES.md

@@ -540,6 +540,7 @@ graph LR;
   npmcli-arborist-->bin-links;
   npmcli-arborist-->cacache;
   npmcli-arborist-->common-ancestor-path;
+  npmcli-arborist-->diff;
   npmcli-arborist-->gar-promise-retry["@gar/promise-retry"];
   npmcli-arborist-->hosted-git-info;
   npmcli-arborist-->isaacs-string-locale-compare["@isaacs/string-locale-compare"];

docs/lib/content/commands/npm-patch.md

@@ -0,0 +1,69 @@
+---
+title: npm-patch
+section: 1
+description: Apply local patches to installed dependencies
+---
+
+### Synopsis
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS -->
+
+### Description
+
+`npm patch` lets you apply small, local modifications to an installed
+dependency and have them re-applied automatically on every install. Patches
+are declared in the `patchedDependencies` field of your root `package.json`,
+stored as plain unified diffs under the `patches/` directory, and recorded with
+a content hash in `package-lock.json`.
+
+Because patches are applied during the install itself, they work regardless of
+`install-strategy`, apply to transitive dependencies, and are **not** disabled
+by `--ignore-scripts`.
+
+The bare form `npm patch <pkg>` is shorthand for `npm patch add <pkg>`. A
+package literally named like a subcommand must use the explicit form, e.g.
+`npm patch add add`.
+
+* `npm patch add <pkg>[@<version>]`
+
+    Prepares a package for editing. npm extracts a clean copy of the resolved
+    package tarball into a temporary directory outside `node_modules` and prints
+    its path. Edit the files there, then run `npm patch commit`.
+
+    If more than one version of `<pkg>` is installed, re-run with an exact
+    selector such as `npm patch add lodash@4.17.21`.
+
+* `npm patch commit <edit-dir>`
+
+    Diffs the edited directory against a clean copy of the original tarball,
+    writes the unified diff to `<patches-dir>/<name>@<version>.patch`, adds the
+    entry to `patchedDependencies`, and updates `package-lock.json`.
+
+* `npm patch ls`
+
+    Lists registered patches and how many installed nodes each one matches.
+
+* `npm patch rm <pkg>[@<version>]`
+
+    Removes the matching entries from `patchedDependencies`, deletes the patch
+    file when no other entry references it, and updates `package-lock.json`. If
+    `<version>` is omitted, all entries for `<pkg>` are removed.
+
+### Failure modes
+
+By default any patch problem is a hard error that aborts the install: a patch
+that fails to apply, a registered patch that matches no installed package, a
+missing patch file, or a patch whose hash does not match the lockfile.
+
+Two CLI-only flags relax this for one-off cases: `--allow-unused-patches` and
+`--ignore-patch-failures`.
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS -->
+## See Also
+
+* [npm install](/commands/npm-install)
+* [npm ci](/commands/npm-ci)
+* [package-lock.json](/configuring-npm/package-lock-json)
+* [config](/commands/npm-config)

docs/lib/content/nav.yml

@@ -120,6 +120,9 @@
   - title: npm pack
     url: /commands/npm-pack
     description: Create a tarball from a package
+  - title: npm patch
+    url: /commands/npm-patch
+    description: Apply local patches to installed dependencies
   - title: npm ping
     url: /commands/npm-ping
     description: Ping npm registry

lib/commands/audit.js

@@ -4,6 +4,7 @@ const auditError = require('../utils/audit-error.js')
 const { log, output } = require('proc-log')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const VerifySignatures = require('../utils/verify-signatures.js')
 
 class Audit extends ArboristWorkspaceCmd {
@@ -62,6 +63,8 @@ class Audit extends ArboristWorkspaceCmd {
     const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const opts = {
       ...this.npm.flatOptions,
+      // audit fix reifies, so honor the cli-only patch relax flags
+      ...patchRelaxOpts(this.npm.config),
       audit: true,
       path: this.npm.prefix,
       reporter,

lib/commands/ci.js

@@ -44,6 +44,15 @@ class CI extends ArboristWorkspaceCmd {
       })
     }
 
+    // npm ci is always strict about patches; the relax flags are not accepted
+    for (const flag of ['allow-unused-patches', 'ignore-patch-failures']) {
+      if (this.npm.config.find(flag) === 'cli') {
+        throw Object.assign(new Error(`The --${flag} flag is not allowed with \`npm ci\`.`), {
+          code: 'ECIPATCHFLAG',
+        })
+      }
+    }
+
     const dryRun = this.npm.config.get('dry-run')
     const ignoreScripts = this.npm.config.get('ignore-scripts')
     const where = this.npm.prefix

lib/commands/dedupe.js

@@ -1,5 +1,6 @@
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 // dedupe duplicated packages, or find them in the tree
@@ -47,6 +48,7 @@ class Dedupe extends ArboristWorkspaceCmd {
       save: false,
       workspaces: this.workspaceNames,
       allowScripts: allowScriptsPolicy,
+      ...patchRelaxOpts(this.npm.config),
     }
     const arb = new Arborist(opts)
     await arb.dedupe(opts)

lib/commands/install.js

@@ -7,6 +7,7 @@ const checks = require('npm-install-checks')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
 const strictAllowScriptsPreflight = require('../utils/strict-allow-scripts-preflight.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Install extends ArboristWorkspaceCmd {
@@ -152,6 +153,8 @@ class Install extends ArboristWorkspaceCmd {
       add: args,
       workspaces: this.workspaceNames,
       allowScripts: allowScriptsPolicy,
+      // patch relax flags are honored only when passed on the command line
+      ...patchRelaxOpts(this.npm.config),
     }
 
     // Root lifecycle scripts only run for a bare `npm install` in a local project. `preinstall` runs *before* Arborist touches the filesystem so that scripts can bootstrap the environment (e.g. set up private-registry auth, generate files consumed during resolution) before dependencies are fetched or unpacked. The remaining scripts run after reify as they did before.

lib/commands/link.js

@@ -5,6 +5,7 @@ const pkgJson = require('@npmcli/package-json')
 const semver = require('semver')
 const reifyFinish = require('../utils/reify-finish.js')
 const resolveAllowScripts = require('../utils/resolve-allow-scripts.js')
+const { patchRelaxOpts } = require('../utils/cli-only-flag.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 
 class Link extends ArboristWorkspaceCmd {
@@ -70,6 +71,7 @@ class Link extends ArboristWorkspaceCmd {
     const Arborist = require('@npmcli/arborist')
     const globalOpts = {
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       Arborist,
       path: globalTop,
       global: true,
@@ -119,6 +121,7 @@ class Link extends ArboristWorkspaceCmd {
     const { policy: allowScriptsPolicy } = await resolveAllowScripts(this.npm)
     const localArb = new Arborist({
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       prune: false,
       path: this.npm.prefix,
       save,
@@ -145,6 +148,7 @@ class Link extends ArboristWorkspaceCmd {
     const Arborist = require('@npmcli/arborist')
     const arb = new Arborist({
       ...this.npm.flatOptions,
+      ...patchRelaxOpts(this.npm.config),
       Arborist,
       path: globalTop,
       global: true,

lib/commands/ls.js

@@ -333,6 +333,11 @@ const getHumanOutputItem = (node, { args, chalk, global, long }) => {
         ? ' ' + chalk.dim('overridden')
         : ''
     ) +
+    (
+      node.patched
+        ? ' ' + chalk.cyan(`[patched: ${node.patched.path}]`)
+        : ''
+    ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
     (node.isLink ? ` -> ${relativePrefix}${targetLocation}` : '') +
     (long ? `\n${node.package.description || ''}` : '')
@@ -389,6 +394,10 @@ const getJsonOutputItem = (node, { global, long }) => {
     item.invalid = node[_invalid]
   }
 
+  if (node.patched) {
+    item.patched = node.patched.path
+  }
+
   if (node[_missing] && !isOptional(node)) {
     item.required = node[_required]
     item.missing = true