feat: devEngines

docs/lib/content/configuring-npm/package-json.md

@@ -1129,6 +1129,32 @@ Like the `os` option, you can also block architectures:
 
 The host architecture is determined by `process.arch`
 
+### devEngines
+
+The `devEngines` field aids engineers working on a codebase to all be using the same tooling.
+
+You can specify a `devEngines` property in your `package.json` which will run before `install`, `ci`, and `run` commands. 
+
+> Note: `engines` and `devEngines` differ in object shape. They also function very differently. `engines` is designed to alert the user when a dependency uses a differening npm or node version that the project it's being used in, whereas `devEngines` is used to alert people interacting with the source code of a project.
+
+The supported keys under the `devEngines` property are `cpu`, `os`, `libc`, `runtime`, and `packageManager`. Each property can be an object or an array of objects. Objects must contain `name`, and optionally can specify `version`, and `onFail`. `onFail` can be `warn`, `error`, or `ignore`, and if left undefined is of the same value as `error`. `npm` will assume that you're running with `node`.
+Here's an example of a project that will fail if the environment is not `node` and `npm`. If you set `runtime.name` or `packageManager.name` to any other string, it will fail within the npm CLI.
+
+```json
+{
+ "devEngines": {
+ "runtime": {
+ "name": "node",
+ "onFail": "error"
+ },
+ "packageManager": {
+ "name": "npm",
+ "onFail": "error"
+ }
+ }
+}
+```
+
 ### private
 
 If you set `"private": true` in your package.json, then npm will refuse to

lib/arborist-cmd.js

@@ -18,6 +18,7 @@ class ArboristCmd extends BaseCommand {
 
  static workspaces = true
  static ignoreImplicitWorkspace = false
+ static checkDevEngines = true
 
  constructor (npm) {
  super(npm)

lib/base-cmd.js

@@ -1,10 +1,12 @@
 const { log } = require('proc-log')
 
 class BaseCommand {
+ // these defaults can be overridden by individual commands
  static workspaces = false
  static ignoreImplicitWorkspace = true
+ static checkDevEngines = false
 
- // these are all overridden by individual commands
+ // these should always be overridden by individual commands
  static name = null
  static description = null
  static params = null
@@ -129,6 +131,63 @@ class BaseCommand {
  }
  }
 
+ // Checks the devEngines entry in the package.json at this.localPrefix
+ async checkDevEngines () {
+ const force = this.npm.flatOptions.force
+
+ const { devEngines } = await require('@npmcli/package-json')
+ .normalize(this.npm.config.localPrefix)
+ .then(p => p.content)
+ .catch(() => ({}))
+
+ if (typeof devEngines === 'undefined') {
+ return
+ }
+
+ const { checkDevEngines, currentEnv } = require('npm-install-checks')
+ const current = currentEnv.devEngines({
+ nodeVersion: this.npm.nodeVersion,
+ npmVersion: this.npm.version,
+ })
+
+ const failures = checkDevEngines(devEngines, current)
+ const warnings = failures.filter(f => f.isWarn)
+ const errors = failures.filter(f => f.isError)
+
+ const genMsg = (failure, i = 0) => {
+ return [...new Set([
+ // eslint-disable-next-line
+ i === 0 ? 'The developer of this package has specified the following through devEngines' : '',
+ `${failure.message}`,
+ `${failure.errors.map(e => e.message).join('\n')}`,
+ ])].filter(v => v).join('\n')
+ }
+
+ [...warnings, ...(force ? errors : [])].forEach((failure, i) => {
+ const message = genMsg(failure, i)
+ log.warn('EBADDEVENGINES', message)
+ log.warn('EBADDEVENGINES', {
+ current: failure.current,
+ required: failure.required,
+ })
+ })
+
+ if (force) {
+ return
+ }
+
+ if (errors.length) {
+ const failure = errors[0]
+ const message = genMsg(failure)
+ throw Object.assign(new Error(message), {
+ engine: failure.engine,
+ code: 'EBADDEVENGINES',
+ current: failure.current,
+ required: failure.required,
+ })
+ }
+ }
+
  async setWorkspaces () {
  const { relative } = require('node:path')
 

lib/commands/run-script.js

@@ -21,6 +21,7 @@ class RunScript extends BaseCommand {
  static workspaces = true
  static ignoreImplicitWorkspace = false
  static isShellout = true
+ static checkDevEngines = true
 
  static async completion (opts, npm) {
  const argv = opts.conf.argv.remain

lib/npm.js

@@ -247,6 +247,10 @@ class Npm {
  execWorkspaces = true
  }
 
+ if (command.checkDevEngines && !this.global) {
+ await command.checkDevEngines()
+ }
+
  return time.start(`command:${cmd}`, () =>
  execWorkspaces ? command.execWorkspaces(args) : command.exec(args))
  }

lib/utils/error-message.js

@@ -200,6 +200,13 @@ const errorMessage = (er, npm) => {
  ].join('\n')])
  break
 
+ case 'EBADDEVENGINES': {
+ const { current, required } = er
+ summary.push(['EBADDEVENGINES', er.message])
+ detail.push(['EBADDEVENGINES', { current, required }])
+ break
+ }
+
  case 'EBADPLATFORM': {
  const actual = er.current
  const expected = { ...er.required }