@npmcli/config 10.4.1 → 10.4.3

package/README.md

@@ -2,53 +2,42 @@
 
 Configuration management for the npm cli.
 
-This module is the spiritual descendant of
-[`npmconf`](http://npm.im/npmconf), and the code that once lived in npm's
+This module is the spiritual descendant of [`npmconf`](http://npm.im/npmconf), and the code that once lived in npm's
 `lib/config/` folder.
 
-It does the management of configuration files that npm uses, but
-importantly, does _not_ define all the configuration defaults or types, as
-those parts make more sense to live within the npm CLI itself.
+It does the management of configuration files that npm uses, but importantly, does _not_ define all the configuration defaults or types, as those parts make more sense to live within the npm CLI itself.
 
 The only exceptions:
 
-- The `prefix` config value has some special semantics, setting the local
-  prefix if specified on the CLI options and not in global mode, or the
-  global prefix otherwise.
-- The `project` config file is loaded based on the local prefix (which can
-  only be set by the CLI config options, and otherwise defaults to a walk
-  up the folder tree to the first parent containing a `node_modules`
-  folder, `package.json` file, or `package-lock.json` file.)
+- The `prefix` config value has some special semantics, setting the local prefix if specified on the CLI options and not in global mode, or the global prefix otherwise.
+- The `project` config file is loaded based on the local prefix (which can only be set by the CLI config options, and otherwise defaults to a walk up the folder tree to the first parent containing a `node_modules` folder, `package.json` file, or `package-lock.json` file.)
 - The `userconfig` value, as set by the environment and CLI (defaulting to
   `~/.npmrc`, is used to load user configs.
 - The `globalconfig` value, as set by the environment, CLI, and
-  `userconfig` file (defaulting to `$PREFIX/etc/npmrc`) is used to load
-  global configs.
-- A `builtin` config, read from a `npmrc` file in the root of the npm
-  project itself, overrides all defaults.
+  `userconfig` file (defaulting to `$PREFIX/etc/npmrc`) is used to load global configs.
+- A `builtin` config, read from a `npmrc` file in the root of the npm project itself, overrides all defaults.
 
 The resulting hierarchy of configs:
 
-- CLI switches.  eg `--some-key=some-value` on the command line.  These are
-  parsed by [`nopt`](http://npm.im/nopt), which is not a great choice, but
-  it's the one that npm has used forever, and changing it will be
-  difficult.
-- Environment variables.  eg `npm_config_some_key=some_value` in the
-  environment.  There is no way at this time to modify this prefix.
-- INI-formatted project configs.  eg `some-key = some-value` in the
-  `localPrefix` folder (ie, the `cwd`, or its nearest parent that contains
-  either a `node_modules` folder or `package.json` file.)
-- INI-formatted userconfig file.  eg `some-key = some-value` in `~/.npmrc`.
+- CLI switches.
+  eg `--some-key=some-value` on the command line.
+  These are parsed by [`nopt`](http://npm.im/nopt), which is not a great choice, but it's the one that npm has used forever, and changing it will be difficult.
+- Environment variables.
+  eg `npm_config_some_key=some_value` in the environment.
+  There is no way at this time to modify this prefix.
+- INI-formatted project configs.
+  eg `some-key = some-value` in the
+  `localPrefix` folder (ie, the `cwd`, or its nearest parent that contains either a `node_modules` folder or `package.json` file.)
+- INI-formatted userconfig file.
+  eg `some-key = some-value` in `~/.npmrc`.
   The `userconfig` config value can be overridden by the `cli`, `env`, or
   `project` configs to change this value.
-- INI-formatted globalconfig file.  eg `some-key = some-value` in
-  the `globalPrefix` folder, which is inferred by looking at the location
-  of the node executable, or the `prefix` setting in the `cli`, `env`,
-  `project`, or `userconfig`.  The `globalconfig` value at any of those
-  levels can override this.
-- INI-formatted builtin config file.  eg `some-key = some-value` in
-  `/usr/local/lib/node_modules/npm/npmrc`.  This is not configurable, and
-  is determined by looking in the `npmPath` folder.
+- INI-formatted globalconfig file.
+  eg `some-key = some-value` in the `globalPrefix` folder, which is inferred by looking at the location of the node executable, or the `prefix` setting in the `cli`, `env`, `project`, or `userconfig`.
+  The `globalconfig` value at any of those levels can override this.
+- INI-formatted builtin config file.
+  eg `some-key = some-value` in `/usr/local/lib/node_modules/npm/npmrc`.
+  This is not configurable, and is determined by looking in the `npmPath` folder.
 - Default values (passed in by npm when it loads this module).
 
 ## USAGE
@@ -65,7 +54,7 @@ const conf = new Config({
   flatten,
   // optional, defaults to process.argv
   // argv: [] <- if you are using this package in your own cli
-  //             and dont want to have colliding argv
+  //             and don't want to have colliding argv
   argv: process.argv,
   // optional, defaults to process.env
   env: process.env,
@@ -103,57 +92,50 @@ const Config = require('@npmcli/config')
 
 ### static `Config.typeDefs`
 
-The type definitions passed to `nopt` for CLI option parsing and known
-configuration validation.
+The type definitions passed to `nopt` for CLI option parsing and known configuration validation.
 
 ### constructor `new Config(options)`
 
 Options:
 
-- `types` Types of all known config values.  Note that some are effectively
-  given semantic value in the config loading process itself.
-- `shorthands` An object mapping a shorthand value to an array of CLI
-  arguments that replace it.
+- `types` Types of all known config values.
+Note that some are effectively given semantic value in the config loading process itself.
+- `shorthands` An object mapping a shorthand value to an array of CLI arguments that replace it.
 - `defaults` Default values for each of the known configuration keys.
   These should be defined for all configs given a type, and must be valid.
-- `npmPath` The path to the `npm` module, for loading the `builtin` config
-  file.
+- `npmPath` The path to the `npm` module, for loading the `builtin` config file.
 - `cwd` Optional, defaults to `process.cwd()`, used for inferring the
   `localPrefix` and loading the `project` config.
-- `platform` Optional, defaults to `process.platform`.  Used when inferring
-  the `globalPrefix` from the `execPath`, since this is done diferently on
-  Windows.
-- `execPath` Optional, defaults to `process.execPath`.  Used to infer the
+- `platform` Optional, defaults to `process.platform`.
+Used when inferring the `globalPrefix` from the `execPath`, since this is done differently on Windows.
+- `execPath` Optional, defaults to `process.execPath`.
+Used to infer the
   `globalPrefix`.
-- `env` Optional, defaults to `process.env`.  Source of the environment
-  variables for configuration.
-- `argv` Optional, defaults to `process.argv`.  Source of the CLI options
-  used for configuration.
+- `env` Optional, defaults to `process.env`.
+Source of the environment variables for configuration.
+- `argv` Optional, defaults to `process.argv`.
+Source of the CLI options used for configuration.
 
 Returns a `config` object, which is not yet loaded.
 
 Fields:
 
-- `config.globalPrefix` The prefix for `global` operations.  Set by the
+- `config.globalPrefix` The prefix for `global` operations.
+Set by the
   `prefix` config value, or defaults based on the location of the
   `execPath` option.
-- `config.localPrefix` The prefix for `local` operations.  Set by the
-  `prefix` config value on the CLI only, or defaults to either the `cwd` or
-  its nearest ancestor containing a `node_modules` folder or `package.json`
-  file.
-- `config.sources` A read-only `Map` of the file (or a comment, if no file
-  found, or relevant) to the config level loaded from that source.
-- `config.data` A `Map` of config level to `ConfigData` objects.  These
-  objects should not be modified directly under any circumstances.
+- `config.localPrefix` The prefix for `local` operations.
+Set by the
+  `prefix` config value on the CLI only, or defaults to either the `cwd` or its nearest ancestor containing a `node_modules` folder or `package.json` file.
+- `config.sources` A read-only `Map` of the file (or a comment, if no file found, or relevant) to the config level loaded from that source.
+- `config.data` A `Map` of config level to `ConfigData` objects.
+These objects should not be modified directly under any circumstances.
   - `source` The source where this data was loaded from.
-  - `raw` The raw data used to generate this config data, as it was parsed
-    initially from the environment, config file, or CLI options.
-  - `data` The data object reflecting the inheritance of configs up to this
-    point in the chain.
-  - `loadError` Any errors encountered that prevented the loading of this
-    config data.
-- `config.list` A list sorted in priority of all the config data objects in
-  the prototype chain.  `config.list[0]` is the `cli` level,
+  - `raw` The raw data used to generate this config data, as it was parsed initially from the environment, config file, or CLI options.
+  - `data` The data object reflecting the inheritance of configs up to this point in the chain.
+  - `loadError` Any errors encountered that prevented the loading of this config data.
+- `config.list` A list sorted in priority of all the config data objects in the prototype chain.
+`config.list[0]` is the `cli` level,
   `config.list[1]` is the `env` level, and so on.
 - `cwd` The `cwd` param
 - `env` The `env` param
@@ -166,21 +148,17 @@ Fields:
 - `npmPath` The `npmPath` param
 - `globalPrefix` The effective `globalPrefix`
 - `localPrefix` The effective `localPrefix`
-- `prefix` If `config.get('global')` is true, then `globalPrefix`,
-  otherwise `localPrefix`
-- `home` The user's home directory, found by looking at `env.HOME` or
-  calling `os.homedir()`.
+- `prefix` If `config.get('global')` is true, then `globalPrefix`, otherwise `localPrefix`
+- `home` The user's home directory, found by looking at `env.HOME` or calling `os.homedir()`.
 - `loaded` A boolean indicating whether or not configs are loaded
 - `valid` A getter that returns `true` if all the config objects are valid.
-  Any data objects that have been modified with `config.set(...)` will be
-  re-evaluated when `config.valid` is read.
+  Any data objects that have been modified with `config.set(...)` will be re-evaluated when `config.valid` is read.
 
 ### `config.load()`
 
 Load configuration from the various sources of information.
 
-Returns a `Promise` that resolves when configuration is loaded, and fails
-if a fatal error is encountered.
+Returns a `Promise` that resolves when configuration is loaded, and fails if a fatal error is encountered.
 
 ### `config.find(key)`
 
@@ -196,8 +174,7 @@ Load the given key from the config stack.
 
 ### `config.set(key, value, where = 'cli')`
 
-Set the key to the specified value, at the specified level in the config
-stack.
+Set the key to the specified value, at the specified level in the config stack.
 
 ### `config.delete(key, where = 'cli')`
 
@@ -205,12 +182,9 @@ Delete the configuration key from the specified level in the config stack.
 
 ### `config.validate(where)`
 
-Verify that all known configuration options are set to valid values, and
-log a warning if they are invalid.
+Verify that all known configuration options are set to valid values, and log a warning if they are invalid.
 
-Invalid auth options will cause this method to throw an error with a `code`
-property of `ERR_INVALID_AUTH`, and a `problems` property listing the specific
-concerns with the current configuration.
+Invalid auth options will cause this method to throw an error with a `code` property of `ERR_INVALID_AUTH`, and a `problems` property listing the specific concerns with the current configuration.
 
 If `where` is not set, then all config objects are validated.
 
@@ -222,30 +196,24 @@ Note that it's usually enough (and more efficient) to just check
 
 ### `config.repair(problems)`
 
-Accept an optional array of problems (as thrown by `config.validate()`) and
-perform the necessary steps to resolve them. If no problems are provided,
-this method will call `config.validate()` internally to retrieve them.
+Accept an optional array of problems (as thrown by `config.validate()`) and perform the necessary steps to resolve them.
+If no problems are provided, this method will call `config.validate()` internally to retrieve them.
 
 Note that you must `await config.save('user')` in order to persist the changes.
 
 ### `config.isDefault(key)`
 
-Returns `true` if the value is coming directly from the
-default definitions, if the current value for the key config is
-coming from any other source, returns `false`.
+Returns `true` if the value is coming directly from the default definitions, if the current value for the key config is coming from any other source, returns `false`.
 
 This method can be used for avoiding or tweaking default values, e.g:
 
->  Given a global default definition of foo='foo' it's possible to read that
->  value such as:
+>  Given a global default definition of foo='foo' it's possible to read that value such as:
 >
 >  ```js
 >     const save = config.get('foo')
 >  ```
 >
->  Now in a different place of your app it's possible to avoid using the `foo`
->  default value, by checking to see if the current config value is currently
->  one that was defined by the default definitions:
+>  Now in a different place of your app it's possible to avoid using the `foo` default value, by checking to see if the current config value is currently one that was defined by the default definitions:
 >
 >  ```js
 >     const save = config.isDefault('foo') ? 'bar' : config.get('foo')
@@ -253,5 +221,6 @@ This method can be used for avoiding or tweaking default values, e.g:
 
 ### `config.save(where)`
 
-Save the config file specified by the `where` param.  Must be one of
+Save the config file specified by the `where` param.
+Must be one of
 `project`, `user`, `global`, `builtin`.

package/lib/definitions/definition.js

@@ -34,7 +34,7 @@ const {
 class Definition {
   constructor (key, def) {
     this.key = key
-    // if it's set falsey, don't export it, otherwise we do by default
+    // if it's set falsey, don't export it; otherwise, we do by default
     this.envExport = true
     Object.assign(this, def)
     this.validate()
@@ -83,7 +83,7 @@ This value is not exported to the environment for child processes.
 `
     const deprecated = !this.deprecated ? '' : `* DEPRECATED: ${unindent(this.deprecated)}\n`
     /* eslint-disable-next-line max-len */
-    const exclusive = !this.exclusive ? '' : `\nThis config can not be used with: \`${this.exclusive.join('`, `')}\``
+    const exclusive = !this.exclusive ? '' : `\nThis config cannot be used with: \`${this.exclusive.join('`, `')}\``
     return wrapAll(`#### \`${this.key}\`
 
 * Default: ${unindent(this.defaultDescription)}

package/lib/definitions/definitions.js

@@ -158,7 +158,7 @@ const definitions = {
     If you do not want your scoped package to be publicly viewable (and
     installable) set \`--access=restricted\`.
 
-    Unscoped packages can not be set to \`restricted\`.
+    Unscoped packages cannot be set to \`restricted\`.
 
     Note: This defaults to not changing the current access level for existing
     packages.  Specifying a value of \`restricted\` or \`public\` during
@@ -274,6 +274,16 @@ const definitions = {
     `,
     flatten,
   }),
+  'bypass-2fa': new Definition('bypass-2fa', {
+    default: false,
+    type: Boolean,
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      setting this to true will allow the token to bypass two-factor
+      authentication. This is useful for automation and CI/CD workflows.
+    `,
+    flatten,
+  }),
   ca: new Definition('ca', {
     default: null,
     type: [null, String, Array],
@@ -462,7 +472,7 @@ const definitions = {
   depth: new Definition('depth', {
     default: null,
     defaultDescription: `
-      \`Infinity\` if \`--all\` is set, otherwise \`0\`
+      \`Infinity\` if \`--all\` is set; otherwise, \`0\`
     `,
     type: [null, Number],
     description: `
@@ -624,6 +634,16 @@ const definitions = {
       Can be either true (expect some results) or false (expect no results).
     `,
   }),
+  expires: new Definition('expires', {
+    default: null,
+    type: [null, Number],
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      this sets the expiration in days. If not specified, the server
+      will determine the default expiration.
+    `,
+    flatten,
+  }),
   'fetch-retries': new Definition('fetch-retries', {
     default: 2,
     type: Number,
@@ -1205,7 +1225,7 @@ const definitions = {
     default: null,
     type: [null, 1, 2, 3, '1', '2', '3'],
     defaultDescription: `
-      Version 3 if no lockfile, auto-converting v1 lockfiles to v3, otherwise
+      Version 3 if no lockfile, auto-converting v1 lockfiles to v3; otherwise,
       maintain current lockfile version.`,
     description: `
       Set the lockfile format version to be used in package-lock.json and
@@ -1281,6 +1301,16 @@ const definitions = {
       Show extended information in \`ls\`, \`search\`, and \`help-search\`.
     `,
   }),
+  name: new Definition('name', {
+    default: null,
+    type: [null, String],
+    hint: '<name>',
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      this sets the name/description for the token.
+    `,
+    flatten,
+  }),
   maxsockets: new Definition('maxsockets', {
     default: 15,
     type: Number,
@@ -1304,7 +1334,13 @@ const definitions = {
     flatten,
   }),
   'node-gyp': new Definition('node-gyp', {
-    default: require.resolve('node-gyp/bin/node-gyp.js'),
+    default: (() => {
+      try {
+        return require.resolve('node-gyp/bin/node-gyp.js')
+      } catch {
+        return ''
+      }
+    })(),
     defaultDescription: `
       The path to the node-gyp bin that ships with npm
     `,
@@ -1356,8 +1392,8 @@ const definitions = {
   omit: new Definition('omit', {
     default: process.env.NODE_ENV === 'production' ? ['dev'] : [],
     defaultDescription: `
-      'dev' if the \`NODE_ENV\` environment variable is set to 'production',
-      otherwise empty.
+      'dev' if the \`NODE_ENV\` environment variable is set to 'production';
+      otherwise, empty.
     `,
     type: [Array, 'dev', 'optional', 'peer'],
     description: `
@@ -1403,6 +1439,17 @@ const definitions = {
       definitions.omit.flatten('omit', obj, flatOptions)
     },
   }),
+  orgs: new Definition('orgs', {
+    default: null,
+    type: [null, String, Array],
+    hint: '<org1,org2>',
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      this limits the token access to specific organizations. Provide
+      a comma-separated list of organization names.
+    `,
+    flatten,
+  }),
   optional: new Definition('optional', {
     default: null,
     type: [null, Boolean],
@@ -1499,6 +1546,17 @@ const definitions = {
     `,
     flatten,
   }),
+  packages: new Definition('packages', {
+    default: [],
+    type: [null, String, Array],
+    hint: '<pkg1,pkg2>',
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      this limits the token access to specific packages. Provide
+      a comma-separated list of package names.
+    `,
+    flatten,
+  }),
   parseable: new Definition('parseable', {
     default: false,
     type: Boolean,
@@ -1894,6 +1952,64 @@ const definitions = {
       flatOptions.projectScope = scope
     },
   }),
+  scopes: new Definition('scopes', {
+    default: null,
+    type: [null, String, Array],
+    hint: '<@scope1,@scope2>',
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      this limits the token access to specific scopes. Provide
+      a comma-separated list of scope names (with or without @ prefix).
+    `,
+    flatten,
+  }),
+  'packages-all': new Definition('packages-all', {
+    default: false,
+    type: Boolean,
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      grants the token access to all packages instead of limiting to
+      specific packages.
+    `,
+    flatten,
+  }),
+  'packages-and-scopes-permission': new Definition('packages-and-scopes-permission', {
+    default: null,
+    type: [null, 'read-only', 'read-write', 'no-access'],
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      sets the permission level for packages and scopes. Options are
+      "read-only", "read-write", or "no-access".
+    `,
+    flatten,
+  }),
+  'orgs-permission': new Definition('orgs-permission', {
+    default: null,
+    type: [null, 'read-only', 'read-write', 'no-access'],
+    description: `
+      When creating a Granular Access Token with \`npm token create\`,
+      sets the permission level for organizations. Options are
+      "read-only", "read-write", or "no-access".
+    `,
+    flatten,
+  }),
+  password: new Definition('password', {
+    default: null,
+    type: [null, String],
+    description: `
+      Password for authentication. Can be provided via command line when
+      creating tokens, though it's generally safer to be prompted for it.
+    `,
+    flatten,
+  }),
+  'token-description': new Definition('token-description', {
+    default: null,
+    type: [null, String],
+    description: `
+      Description text for the token when using \`npm token create\`.
+    `,
+    flatten,
+  }),
   'script-shell': new Definition('script-shell', {
     default: null,
     defaultDescription: `

package/lib/index.js

@@ -281,7 +281,7 @@ class Config {
     }
 
     try {
-      // This does not have an actual definition because this is not user defineable
+      // This does not have an actual definition because this is not user definable
       defaultsObject['npm-version'] = require(join(this.npmPath, 'package.json')).version
     } catch {
       // in some weird state where the passed in npmPath does not have a package.json
@@ -589,7 +589,7 @@ class Config {
           if (this.definitions[key]?.exclusive) {
             for (const exclusive of this.definitions[key].exclusive) {
               if (!this.isDefault(exclusive)) {
-                throw new TypeError(`--${key} can not be provided when using --${exclusive}`)
+                throw new TypeError(`--${key} cannot be provided when using --${exclusive}`)
               }
             }
           }
@@ -672,7 +672,7 @@ class Config {
     // if we're in the ~ directory, and there happens to be a node_modules
     // folder (which is not TOO uncommon, it turns out), then we can end
     // up loading the "project" config where the "userconfig" will be,
-    // which causes some calamaties.  So, we only load project config if
+    // which causes some calamities.  So, we only load project config if
     // it doesn't match what the userconfig will be.
     if (projectFile !== this.#get('userconfig')) {
       return this.#loadFile(projectFile, 'project')

package/lib/set-envs.js

@@ -97,7 +97,7 @@ const setEnvs = (config) => {
     env.EDITOR = cliConf.editor
   }
 
-  // note: this doesn't afect the *current* node process, of course, since
+  // note: this doesn't affect the *current* node process, of course, since
   // it's already started, but it does affect the options passed to scripts.
   if (cliConf['node-options']) {
     env.NODE_OPTIONS = cliConf['node-options']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npmcli/config",
-  "version": "10.4.1",
+  "version": "10.4.3",
   "files": [
     "bin/",
     "lib/"
@@ -40,9 +40,9 @@
     "@npmcli/map-workspaces": "^5.0.0",
     "@npmcli/package-json": "^7.0.0",
     "ci-info": "^4.0.0",
-    "ini": "^5.0.0",
+    "ini": "^6.0.0",
     "nopt": "^8.1.0",
-    "proc-log": "^5.0.0",
+    "proc-log": "^6.0.0",
     "semver": "^7.3.5",
     "walk-up-path": "^4.0.0"
   },