feat: .npm-extension transformManifest for imperative manifest repairs

docs/lib/build.js

@@ -107,6 +107,7 @@ const generateNav = async (contentPath, navPath) => {
     '/configuring-npm/npmrc',
     '/configuring-npm/package-json',
     '/configuring-npm/package-lock-json',
+    '/configuring-npm/npm-extension',
   ]
 
   // Hardcoded order for using-npm section (only urls - title/description come from frontmatter)

docs/lib/content/configuring-npm/npm-extension.md

@@ -0,0 +1,90 @@
+---
+title: .npm-extension
+section: 5
+description: Imperative, root-owned manifest repairs
+---
+
+### Description
+
+A root-owned `.npm-extension.mjs` or `.npm-extension.cjs` file lets a project imperatively repair the manifests of third-party dependencies before npm resolves the dependency tree. It exports a `transformManifest(pkg, context)` function that receives a candidate dependency manifest and returns the effective manifest npm should use.
+
+`.npm-extension` is the imperative counterpart to the declarative [`packageExtensions`](/configuring-npm/package-json#packageextensions) field, and runs in the same pre-resolution phase, **before** `packageExtensions`. Prefer `packageExtensions` for simple, data-only repairs; reach for `.npm-extension` when you need comments and links explaining a repair, conditional logic, repeated repairs expressed as code, deletion or range rewrites, stale-repair guards, or a policy location outside `package.json`.
+
+### Example
+
+```js
+// .npm-extension.mjs
+export function transformManifest (pkg, context) {
+  if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
+    pkg.dependencies = { ...pkg.dependencies, bar: '^2.0.0' }
+    context.log(`added bar to ${pkg.name}@${pkg.version}`)
+  }
+  return pkg
+}
+```
+
+The `.cjs` form uses CommonJS exports instead:
+
+```js
+// .npm-extension.cjs
+module.exports = {
+  transformManifest (pkg, context) {
+    return pkg
+  },
+}
+```
+
+### The `transformManifest` function
+
+`transformManifest(pkg, context)` receives a deeply isolated copy of a candidate dependency manifest. It may mutate and return that copy, or return a new manifest object. It **must** return a manifest object synchronously; returning `null`, `undefined`, a primitive, an array, or a promise fails the install.
+
+The `context` argument is intentionally small:
+
+* `context.log(message)` writes an npm debug log message.
+* `context.root` is the absolute path to the project root.
+* `context.extensionPoint` is the string `"transformManifest"`.
+
+npm provides no registry, fetch, lockfile, or extraction helpers. Keep the extension file self-contained or limited to Node builtins; npm does not guarantee that project dependencies are available when the file is loaded.
+
+### Supported mutations
+
+Only the four resolution-affecting fields may change:
+
+* `dependencies`
+* `optionalDependencies`
+* `peerDependencies`
+* `peerDependenciesMeta`
+
+Within those fields you may add, replace, or delete entries. Changing any other field (such as `scripts`, `bin`, `engines`, `os`, `cpu`, `exports`, or `main`) is rejected, and the install fails with an error naming `.npm-extension` and the package being processed. The package tarball and the installed `node_modules/<pkg>/package.json` are never rewritten.
+
+### Discovery and `extension-file`
+
+npm looks for a single `.npm-extension.mjs` or `.npm-extension.cjs` at the project root (the workspace root in a workspace project). Having both files present is an error. A `.npm-extension` file in a dependency or in a non-root workspace is ignored; a non-root workspace file produces a warning.
+
+The [`extension-file`](/using-npm/config#extension-file) config selects a different project-local file. It must resolve inside the project root and use a `.mjs` or `.cjs` extension, and it is honored only from project config or the command line — never from user, global, or builtin config.
+
+### Interaction with `packageExtensions` and `overrides`
+
+When both are present, `transformManifest` runs first and `packageExtensions` is applied to its output. Avoid targeting the same package with both unless you intend to rely on that ordering. `overrides` still controls the final resolution target of any edge, including edges created by `transformManifest`.
+
+### Lockfile and `npm ci`
+
+A lockfile influenced by `.npm-extension` records an `npmExtensionHash` (a digest of the selected file's bytes and module format) on its root entry, and minimal `npmExtensionApplied` provenance on each affected package entry. Extension state requires `lockfileVersion: 4`.
+
+Changing the file's contents makes `npm install` re-resolve the affected packages. `npm ci` does **not** import or execute `.npm-extension`; it verifies the recorded hash against the file and reifies the locked graph, failing if the file and lockfile disagree (or if one has extension state and the other does not).
+
+The hash proves only that the install uses the same extension file bytes that generated the lockfile. It does not make arbitrary JavaScript deterministic: extension output that depends on environment variables, the network, the clock, or files imported by the extension can still produce non-reproducible installs. Treat `.npm-extension` as trusted, deterministic project code, and only enable it in repositories you trust.
+
+### Disabling
+
+Set [`ignore-extension`](/using-npm/config#ignore-extension) to skip importing and executing `.npm-extension`. [`ignore-scripts`](/using-npm/config#ignore-scripts) implies `ignore-extension`, since both disable root-owned install-time code. `npm ci` still verifies the file hash even when execution is disabled.
+
+### Publishing
+
+`.npm-extension.mjs` and `.npm-extension.cjs` are project configuration, not package contents. npm excludes the root file from the package tarball produced by `npm pack` and `npm publish`, even when the package's `files` list would include it, so a public package can keep `.npm-extension` in its repository for local use without publishing it.
+
+### See also
+
+* [package.json `packageExtensions`](/configuring-npm/package-json#packageextensions)
+* [package-lock.json](/configuring-npm/package-lock-json)
+* [config](/using-npm/config)

docs/lib/content/nav.yml

@@ -232,6 +232,9 @@
   - title: package-lock.json
     url: /configuring-npm/package-lock-json
     description: A manifestation of the manifest
+  - title: .npm-extension
+    url: /configuring-npm/npm-extension
+    description: Imperative, root-owned manifest repairs
 - title: Using npm
   shortName: Using
   url: /using-npm

lib/commands/ci.js

@@ -6,7 +6,7 @@ const fs = require('node:fs/promises')
 const path = require('node:path')
 const { log, time } = require('proc-log')
 const validateLockfile = require('../utils/validate-lockfile.js')
-const { validatePackageExtensions } = require('../utils/validate-lockfile.js')
+const { validatePackageExtensions, validateNpmExtension } = require('../utils/validate-lockfile.js')
 const ArboristWorkspaceCmd = require('../arborist-cmd.js')
 const getWorkspaces = require('../utils/get-workspaces.js')
 
@@ -66,6 +66,9 @@ class CI extends ArboristWorkspaceCmd {
       save: false, // npm ci should never modify the lockfile or package.json
       workspaces: this.workspaceNames,
       allowScripts: allowScriptsPolicy,
+      // npm ci reifies the locked graph, which already carries extension-influenced edges, so it must never import or execute .npm-extension.
+      // The extension file hash is still validated below, independent of execution.
+      ignoreExtension: true,
     }
 
     // generate an inventory from the virtual tree in the lockfile
@@ -92,6 +95,16 @@ class CI extends ArboristWorkspaceCmd {
     const errors = validateLockfile(virtualInventory, arb.idealTree.inventory)
     // Verifies that the root packageExtensions state matches the lockfile and is still consistent with the locked tree.
     errors.push(...validatePackageExtensions(virtualArb.virtualTree, arb.idealTree))
+    // Verifies that the root .npm-extension file matches the lockfile hash.
+    // The hash comes from discovering the file (no import or execution), so this holds even under ignore-extension/ignore-scripts.
+    const { NpmExtension } = require('@npmcli/arborist')
+    let fileHash = null
+    try {
+      fileHash = new NpmExtension({ root: where, extensionFile: opts.extensionFile }).hash
+    } catch (err) {
+      errors.push(`Invalid: ${err.message}`)
+    }
+    errors.push(...validateNpmExtension(virtualArb.virtualTree, fileHash))
     if (errors.length) {
       throw this.usageError(
         '`npm ci` can only install packages when your package.json and package-lock.json are in sync. ' +

lib/commands/ls.js

@@ -278,8 +278,8 @@ const augmentItemWithIncludeMetadata = (node, item) => {
   return item
 }
 
-// Render a node's packageExtensions provenance as a short "field.name" list, empty when none.
-const formatPackageExtensions = (applied) => {
+// Render a manifest-extension provenance object as a short "field.name" list, empty when none.
+const formatExtensionApplied = (applied) => {
   if (!applied) {
     return ''
   }
@@ -354,8 +354,13 @@ const getHumanOutputItem = (node, { args, chalk, global, long }) => {
         : ''
     ) +
     (
-      formatPackageExtensions(node.packageExtensionsApplied)
-        ? ' ' + chalk.dim(`packageExtensions: ${formatPackageExtensions(node.packageExtensionsApplied)}`)
+      formatExtensionApplied(node.packageExtensionsApplied)
+        ? ' ' + chalk.dim(`packageExtensions: ${formatExtensionApplied(node.packageExtensionsApplied)}`)
+        : ''
+    ) +
+    (
+      formatExtensionApplied(node.npmExtensionApplied)
+        ? ' ' + chalk.dim(`.npm-extension: ${formatExtensionApplied(node.npmExtensionApplied)}`)
         : ''
     ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
@@ -386,6 +391,10 @@ const getJsonOutputItem = (node, { global, long }) => {
     item.packageExtensionsApplied = node.packageExtensionsApplied
   }
 
+  if (node.npmExtensionApplied) {
+    item.npmExtensionApplied = node.npmExtensionApplied
+  }
+
   item[_name] = node.name
 
   // special formatting for top-level package name

lib/utils/explain-dep.js

@@ -76,7 +76,7 @@ const explainDependents = ({ dependents }, depth, chalk, seen) => {
 }
 
 const explainEdge = (
-  { name, type, bundled, from, spec, rawSpec, overridden, packageExtensions },
+  { name, type, bundled, from, spec, rawSpec, overridden, packageExtensions, npmExtension },
   depth, chalk, seen = new Set()
 ) => {
   let dep = type === 'workspace'
@@ -93,9 +93,14 @@ const explainEdge = (
     ? chalk.dim(` (added by packageExtensions["${packageExtensions.selector}"].${packageExtensions.field}.${name})`)
     : ''
 
+  // note an edge created or changed by a root .npm-extension repair
+  const npmExtMsg = npmExtension
+    ? chalk.dim(` (changed by .npm-extension ${npmExtension.extensionPoint} ${npmExtension.field}.${name})`)
+    : ''
+
   return (type === 'prod' ? '' : `${colorType(type, chalk)} `) +
     (bundled ? `${colorType('bundled', chalk)} ` : '') +
-    `${dep}${fromMsg}${extMsg}`
+    `${dep}${fromMsg}${extMsg}${npmExtMsg}`
 }
 
 const explainFrom = (from, depth, chalk, seen) => {

lib/utils/validate-lockfile.js

@@ -98,5 +98,33 @@ function validatePackageExtensions (virtualTree, idealTree) {
   return errors
 }
 
+// validates that the .npm-extension state recorded in the lockfile still matches the selected extension file.
+// Validation is hash-based: arbitrary code has no selector to re-check, so a matching hash is trusted and a mismatch fails.
+// fileHash is computed from the on-disk file (discovery only, no execution), so this holds even under ignore-extension/ignore-scripts.
+// The lockfile carries extension state if it records a root hash or any per-package npmExtensionApplied provenance.
+// Returns an array of human-readable error strings, empty when valid.
+function validateNpmExtension (virtualTree, fileHash) {
+  const lockHash = virtualTree?.meta?.npmExtensionHash || null
+  const hasProvenance = !!virtualTree &&
+    [...virtualTree.inventory.values()].some(node => node.npmExtensionApplied)
+  fileHash = fileHash || null
+
+  if (fileHash) {
+    if (!lockHash) {
+      return ['Missing: .npm-extension state from lock file']
+    }
+    if (lockHash !== fileHash) {
+      return ['Invalid: .npm-extension file does not match the lock file']
+    }
+    return []
+  }
+  // no extension file present
+  if (lockHash || hasProvenance) {
+    return ['Invalid: lock file records .npm-extension state but no .npm-extension file is present']
+  }
+  return []
+}
+
 module.exports = validateLockfile
 module.exports.validatePackageExtensions = validatePackageExtensions
+module.exports.validateNpmExtension = validateNpmExtension

tap-snapshots/test/lib/commands/config.js.test.cjs

@@ -58,6 +58,7 @@ exports[`test/lib/commands/config.js TAP config list --json > output matches sna
   "expect-result-count": null,
   "expect-results": null,
   "expires": null,
+  "extension-file": null,
   "fetch-retries": 2,
   "fetch-retry-factor": 10,
   "fetch-retry-maxtimeout": 60000,
@@ -76,6 +77,7 @@ exports[`test/lib/commands/config.js TAP config list --json > output matches sna
   "heading": "npm",
   "https-proxy": null,
   "if-present": false,
+  "ignore-extension": false,
   "ignore-scripts": false,
   "include": [],
   "include-staged": false,
@@ -254,6 +256,7 @@ engine-strict = false
 expect-result-count = null
 expect-results = null
 expires = null
+extension-file = null
 fetch-retries = 2
 fetch-retry-factor = 10
 fetch-retry-maxtimeout = 60000
@@ -273,6 +276,7 @@ heading = "npm"
 https-proxy = null
 if-present = false
 ignore-existing = false
+ignore-extension = false
 ignore-patch-failures = false
 ignore-scripts = false
 include = []

tap-snapshots/test/lib/commands/ls.js.test.cjs

@@ -315,6 +315,12 @@ test-npm-ls@1.0.0 {CWD}/prefix
   \`-- dog@2.0.0
 `
 
+exports[`test/lib/commands/ls.js TAP ls .npm-extension dep > human output annotates the transformed node 1`] = `
+test-npm-extension@1.0.0 {CWD}/prefix
+\`-- foo@1.0.0 .npm-extension: dependencies.bar
+  \`-- bar@1.0.0
+`
+
 exports[`test/lib/commands/ls.js TAP ls broken resolved field > should NOT print git refs in output tree 1`] = `
 npm-broken-resolved-field-test@1.0.0 {CWD}/prefix
 \`-- a@1.0.1

tap-snapshots/test/lib/docs.js.test.cjs

@@ -759,6 +759,19 @@ expiration.
 
 
 
+#### \`extension-file\`
+
+* Default: null
+* Type: null or Path
+
+Path to a project-local npm extension file to load instead of discovering
+\`.npm-extension.mjs\` / \`.npm-extension.cjs\` at the project root. Must
+resolve inside the project root and use a \`.mjs\` or \`.cjs\` extension. Only
+honored from project config or the command line, never from user, global, or
+builtin config.
+
+
+
 #### \`fetch-retries\`
 
 * Default: 2
@@ -983,6 +996,18 @@ fresh.
 
 
 
+#### \`ignore-extension\`
+
+* Default: false
+* Type: Boolean
+
+If true, npm does not import or execute a root \`.npm-extension.mjs\` /
+\`.npm-extension.cjs\` file (or one selected via \`extension-file\`).
+\`ignore-scripts\` implies \`ignore-extension\`, since both disable root-owned
+install-time code.
+
+
+
 #### \`ignore-patch-failures\`
 
 * Default: false
@@ -1008,6 +1033,9 @@ Note that commands explicitly intended to run a particular script, such as
 run their intended script if \`ignore-scripts\` is set, but they will *not*
 run any pre- or post-scripts.
 
+Setting \`ignore-scripts\` also disables \`.npm-extension\` execution, as if
+\`ignore-extension\` were set.
+
 
 
 #### \`include\`
@@ -2580,6 +2608,7 @@ Array [
   "expect-result-count",
   "expect-results",
   "expires",
+  "extension-file",
   "fetch-retries",
   "fetch-retry-factor",
   "fetch-retry-maxtimeout",
@@ -2598,6 +2627,7 @@ Array [
   "heading",
   "https-proxy",
   "if-present",
+  "ignore-extension",
   "ignore-scripts",
   "include",
   "include-staged",
@@ -2771,6 +2801,7 @@ Array [
   "editor",
   "engine-strict",
   "expires",
+  "extension-file",
   "fetch-retries",
   "fetch-retry-factor",
   "fetch-retry-maxtimeout",
@@ -2789,6 +2820,7 @@ Array [
   "heading",
   "https-proxy",
   "if-present",
+  "ignore-extension",
   "ignore-scripts",
   "include",
   "include-staged",
@@ -2966,6 +2998,7 @@ Object {
   "editor": "{EDITOR}",
   "engineStrict": false,
   "expires": null,
+  "extensionFile": null,
   "force": false,
   "foregroundScripts": false,
   "formatPackageLock": true,
@@ -2978,6 +3011,7 @@ Object {
   "heading": "npm",
   "httpsProxy": null,
   "ifPresent": false,
+  "ignoreExtension": false,
   "ignoreScripts": false,
   "includeAttestations": false,
   "includeStaged": false,