CLI documentation update from CI

content/cli/v10/commands/npm-audit.mdx

@@ -307,7 +307,7 @@ Dependency types specified in `--include` will not be omitted, regardless of the
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-ci.mdx

@@ -149,7 +149,7 @@ When such an override is performed, a warning is printed, explaining the conflic
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-install-ci-test.mdx

@@ -109,7 +109,7 @@ When such an override is performed, a warning is printed, explaining the conflic
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-install-test.mdx

@@ -163,7 +163,7 @@ For `list` this means the output will be based on the tree described by the `pac
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-install.mdx

@@ -446,7 +446,7 @@ For `list` this means the output will be based on the tree described by the `pac
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-ls.mdx

@@ -52,7 +52,7 @@ Note: to get a "bottoms up" view of why a given package is included in the tree
 Positional arguments are `name@version-range` identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will _also_ show the paths to the specified packages. For example, running `npm ls promzard` in npm's source tree will show:
 
 ```bash
-npm@10.4.0 /path/to/npm
+npm@10.5.0 /path/to/npm
 └─┬ init-package-json@0.0.4
   └── promzard@0.1.5
 ```

content/cli/v10/commands/npm-prune.mdx

@@ -103,7 +103,7 @@ Not supported by all npm commands.
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-query.mdx

@@ -166,9 +166,19 @@ npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
   ...
 ```
 
-### Package lock only mode
+### Expecting a certain number of results
 
-If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded. This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
+One common use of `npm query` is to make sure there is only one version of a certain dependency in your tree. This is especially common for ecosystems like that rely on `typescript` where having state split across two different but identically-named packages causes bugs. You can use the `--expect-results` or `--expect-result-count` in your setup to ensure that npm will exit with an exit code if your tree doesn't look like you want it to.
+
+```sh
+$ npm query '#react' --expect-result-count=1
+```
+
+Perhaps you want to quickly check if there are any production dependencies that could be updated:
+
+```sh
+$ npm query ':root>:outdated(in-range).prod' --no-expect-results
+```
 
 ### Package lock only mode
 
@@ -239,6 +249,24 @@ For `update` this means only the `package-lock.json` will be updated, instead of
 
 For `list` this means the output will be based on the tree described by the `package-lock.json`, rather than the contents of `node_modules`.
 
+#### `expect-results`
+
+- Default: null
+- Type: null or Boolean
+
+Tells npm whether or not to expect results from the command. Can be either true (expect some results) or false (expect no results).
+
+This config can not be used with: `expect-result-count`
+
+#### `expect-result-count`
+
+- Default: null
+- Type: null or Number
+
+Tells to expect a specific number of results from the command.
+
+This config can not be used with: `expect-results`
+
 ## See Also
 
 - [dependency selectors](/cli/v10/using-npm/dependency-selectors)

content/cli/v10/commands/npm-rebuild.mdx

@@ -93,7 +93,7 @@ Set to false to have it not do this. This can be used to work around the fact th
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-run-script.mdx

@@ -192,7 +192,7 @@ Note that commands explicitly intended to run a particular script, such as `npm
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm-update.mdx

@@ -248,7 +248,7 @@ If set to false, then ignore `package-lock.json` files when installing. This wil
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/commands/npm.mdx

@@ -31,7 +31,7 @@ Note: This command is unaware of workspaces.
 
 ### Version
 
-10.4.0
+10.5.0
 
 ### Description
 

content/cli/v10/using-npm/changelog.mdx

@@ -15,6 +15,54 @@ redirect_from:
   - /using-npm/changelog
 ---
 
+## [10.5.0](https://github.com/npm/cli/compare/v10.4.0...v10.5.0) (2024-02-28)
+
+### Features
+
+- [`2366edc`](https://github.com/npm/cli/commit/2366edcaf2b32b5d1c6a7c03184c59eef0e08eae) [#7218](https://github.com/npm/cli/pull/7218) query: add :vuln pseudo selector (@wraithgar)
+- [`4f3ddbb`](https://github.com/npm/cli/commit/4f3ddbbe88df7c94d1e06e660928a962e973f332) [#5966](https://github.com/npm/cli/pull/5966) add --expect-entries to `npm query` (@wraithgar)
+
+### Bug Fixes
+
+- [`818957c`](https://github.com/npm/cli/commit/818957c0f88c859bf3ea90ff440ec5d9d9e990b9) [#7158](https://github.com/npm/cli/pull/7158) pack, publish: default foreground-scripts to true (#7158) (@ljharb)
+- [`d04111d`](https://github.com/npm/cli/commit/d04111d48ca59fce27909712b328fe5cfc4d016d) [#7197](https://github.com/npm/cli/pull/7197) view: filter out invalid semver (#7197) (@wraithgar)
+- [`b0a3ba0`](https://github.com/npm/cli/commit/b0a3ba0b99ce5920722244f1ccb8b830826abef4) [#7195](https://github.com/npm/cli/pull/7195) prevent adding invalid dist-tag (#7195) (@wraithgar)
+
+### Documentation
+
+- [`c4741fe`](https://github.com/npm/cli/commit/c4741fee8b4e6cdca90c6773385ff710c8b3f7f5) [#7254](https://github.com/npm/cli/pull/7254) Remove additional example and comments about uninstall script (#7254) (@rveerd)
+- [`686a622`](https://github.com/npm/cli/commit/686a622480d32eabf2d69982e422ba3dcd8a6f7c) [#7247](https://github.com/npm/cli/pull/7247) scope: update example command to work in windows (#7247) (@robertobasile84)
+- [`95b5057`](https://github.com/npm/cli/commit/95b505738a73ba740227a41b8c7c87013af5acaf) [#5966](https://github.com/npm/cli/pull/5966) clarify in-range and out-of-range in dependency selectors (@wraithgar)
+- [`5b7184f`](https://github.com/npm/cli/commit/5b7184f3aaf5a9ca58418b6d029616088964ed0a) [#7190](https://github.com/npm/cli/pull/7190) workspaces: fix grammar (#7190) (@alekstech)
+- [`0dd03f9`](https://github.com/npm/cli/commit/0dd03f9450e0cf57fa85ad2ef74b5a54f3c775a9) [#7182](https://github.com/npm/cli/pull/7182) fix typos (#7182) (@GoodDaisy)
+
+### Dependencies
+
+- [`16d4c9f`](https://github.com/npm/cli/commit/16d4c9f0e48a18719f1461460504a4228f8f663d) [#7218](https://github.com/npm/cli/pull/7218) `@npmcli/query@3.1.0`
+- [`06247d1`](https://github.com/npm/cli/commit/06247d18fd3573d48b220512e84f87eaab06210a) [#7242](https://github.com/npm/cli/pull/7242) `spdx-license-ids@3.0.17`
+- [`79d1e0b`](https://github.com/npm/cli/commit/79d1e0bc9f781b02af876f0615595976958ca410) [#7242](https://github.com/npm/cli/pull/7242) `spdx-exceptions@2.5.0`
+- [`67e853a`](https://github.com/npm/cli/commit/67e853a507ab31af5b82fd3fcbcb2fe2f18cad5d) [#7242](https://github.com/npm/cli/pull/7242) `socks@2.8.0`
+- [`4c9fe4b`](https://github.com/npm/cli/commit/4c9fe4be4df39960cfadef2ca07465c90d9ee414) [#7242](https://github.com/npm/cli/pull/7242) `lru-cache@10.2.0`
+- [`4a50c5a`](https://github.com/npm/cli/commit/4a50c5adaa0f28a8e9f6433c34b0eedfc73885a1) [#7242](https://github.com/npm/cli/pull/7242) `https-proxy-agent@7.0.4`
+- [`ed3f254`](https://github.com/npm/cli/commit/ed3f254a09d8f0da49e927e8b7fbd81c1232208e) [#7242](https://github.com/npm/cli/pull/7242) `http-proxy-agent@7.0.2`
+- [`8ec4fd5`](https://github.com/npm/cli/commit/8ec4fd541be937a965e685ad4dbbfb57ae3b2462) [#7242](https://github.com/npm/cli/pull/7242) `hasown@2.0.1`
+- [`98b1189`](https://github.com/npm/cli/commit/98b11894b770065979c8fefb87861c156ad0c895) [#7242](https://github.com/npm/cli/pull/7242) `@npmcli/agent@2.2.1`
+- [`dafa903`](https://github.com/npm/cli/commit/dafa903fe9083343fd17bdd3a5acc6f9acc8f356) [#7242](https://github.com/npm/cli/pull/7242) `sigstore@2.2.2`
+- [`d0bcb76`](https://github.com/npm/cli/commit/d0bcb76bd635eefcb1fae39e831e227a1852ef68) [#7242](https://github.com/npm/cli/pull/7242) `diff@5.2.0`
+- [`a13808e`](https://github.com/npm/cli/commit/a13808e2e8ed0507e12ad27f8b212e5b0b6ccae8) [#7242](https://github.com/npm/cli/pull/7242) `semver@7.6.0`
+- [`d6521ac`](https://github.com/npm/cli/commit/d6521ac9c43ccf909ff4d1564dffa0f07e260503) [#7242](https://github.com/npm/cli/pull/7242) `@sigstore/tuf@2.3.1`
+- [`43cac2f`](https://github.com/npm/cli/commit/43cac2f990aefca283d49e26ff83ba5d6fb28313) [#7242](https://github.com/npm/cli/pull/7242) `ip@2.0.1`
+- [workspace](https://github.com/npm/cli/releases/tag/arborist-v7.4.0): `@npmcli/arborist@7.4.0`
+- [workspace](https://github.com/npm/cli/releases/tag/config-v8.2.0): `@npmcli/config@8.2.0`
+- [workspace](https://github.com/npm/cli/releases/tag/libnpmdiff-v6.0.7): `libnpmdiff@6.0.7`
+- [workspace](https://github.com/npm/cli/releases/tag/libnpmexec-v7.0.8): `libnpmexec@7.0.8`
+- [workspace](https://github.com/npm/cli/releases/tag/libnpmfund-v5.0.5): `libnpmfund@5.0.5`
+- [workspace](https://github.com/npm/cli/releases/tag/libnpmpack-v6.0.7): `libnpmpack@6.0.7`
+
+### Chores
+
+- [`d6bc684`](https://github.com/npm/cli/commit/d6bc6840edce1957c0ea0ed618819cbfe23fa611) [#7242](https://github.com/npm/cli/pull/7242) update devDependencies in lockfile (@wraithgar)
+
 ## [10.4.0](https://github.com/npm/cli/compare/v10.3.0...v10.4.0) (2024-01-24)
 
 ### Features

content/cli/v10/using-npm/config.mdx

@@ -371,6 +371,24 @@ If set to true, then npm will stubbornly refuse to install (or even consider ins
 
 This can be overridden by setting the `--force` flag.
 
+#### `expect-result-count`
+
+- Default: null
+- Type: null or Number
+
+Tells to expect a specific number of results from the command.
+
+This config can not be used with: `expect-results`
+
+#### `expect-results`
+
+- Default: null
+- Type: null or Boolean
+
+Tells npm whether or not to expect results from the command. Can be either true (expect some results) or false (expect no results).
+
+This config can not be used with: `expect-result-count`
+
 #### `fetch-retries`
 
 - Default: 2
@@ -431,7 +449,7 @@ If you don't have a clear idea of what you want to do, it is strongly recommende
 
 #### `foreground-scripts`
 
-- Default: false
+- Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
 - Type: Boolean
 
 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.

content/cli/v10/using-npm/dependency-selectors.mdx

@@ -26,7 +26,7 @@ The [`npm query`](/cli/v10/commands/npm-query) command exposes a new dependency
 - Unlocks the ability to answer complex, multi-faceted questions about dependencies, their relationships & associative metadata
 - Consolidates redundant logic of similar query commands in `npm` (ex. `npm fund`, `npm ls`, `npm outdated`, `npm audit` ...)
 
-### Dependency Selector Syntax `v1.0.0`
+### Dependency Selector Syntax
 
 #### Overview:
 
@@ -76,6 +76,7 @@ The [`npm query`](/cli/v10/commands/npm-query) command exposes a new dependency
 - `:path(<path>)` [glob](https://www.npmjs.com/package/glob) matching based on dependencies path relative to the project
 - `:type(<type>)` [based on currently recognized types](https://github.com/npm/npm-package-arg#result-object)
 - `:outdated(<type>)` when a dependency is outdated
+- `:vuln(<selector>)` when a dependency has a known vulnerability
 
 ##### `:semver(<spec>, [selector], [function])`
 
@@ -98,8 +99,8 @@ Some examples:
 The `:outdated` pseudo selector retrieves data from the registry and returns information about which of your dependencies are outdated. The type parameter may be one of the following:
 
 - `any` (default) a version exists that is greater than the current one
-- `in-range` a version exists that is greater than the current one, and satisfies at least one if its dependents
-- `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its dependents
+- `in-range` a version exists that is greater than the current one, and satisfies at least one if its parent's dependencies
+- `out-of-range` a version exists that is greater than the current one, does not satisfy at least one of its parent's dependencies
 - `major` a version exists that is a semver major greater than the current one
 - `minor` a version exists that is a semver minor greater than the current one
 - `patch` a version exists that is a semver patch greater than the current one
@@ -113,14 +114,29 @@ In addition to the filtering performed by the pseudo selector, some extra data i
 Some examples:
 
 - `:root > :outdated(major)` returns every direct dependency that has a new semver major release
-- `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its edges in
+- `.prod:outdated(in-range)` returns production dependencies that have a new release that satisfies at least one of its parent's dependencies
+
+##### `:vuln`
+
+The `:vuln` pseudo selector retrieves data from the registry and returns information about which if your dependencies has a known vulnerability. Only dependencies whose current version matches a vulnerability will be returned. For example if you have `semver@7.6.0` in your tree, a vulnerability for `semver` which affects versions `<=6.3.1` will not match.
+
+You can also filter results by certain attributes in advisories. Currently that includes `severity` and `cwe`. Note that severity filtering is done per severity, it does not include severities "higher" or "lower" than the one specified.
+
+In addition to the filtering performed by the pseudo selector, info about each relevant advisory will be added to the `queryContext` attribute of each node under the `advisories` attribute.
+
+Some examples:
+
+- `:root > .prod:vuln` returns direct production dependencies with any known vulnerability
+- `:vuln([severity=high])` returns only dependencies with a vulnerability with a `high` severity.
+- `:vuln([severity=high],[severity=moderate])` returns only dependencies with a vulnerability with a `high` or `moderate` severity.
+- `:vuln([cwe=1333])` returns only dependencies with a vulnerability that includes CWE-1333 (ReDoS)
 
 #### [Attribute Selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
 
 The attribute selector evaluates the key/value pairs in `package.json` if they are `String`s.
 
 - `[]` attribute selector (ie. existence of attribute)
-- `[attribute=value]` attribute value is equivalant...
+- `[attribute=value]` attribute value is equivalent...
 - `[attribute~=value]` attribute value contains word...
 - `[attribute*=value]` attribute value contains string...
 - `[attribute|=value]` attribute value is equal to or starts with...

content/cli/v10/using-npm/scope.mdx

@@ -111,7 +111,7 @@ Scopes have a many-to-one relationship with registries: one registry can host mu
 You can also associate a scope with a registry using `npm config`:
 
 ```bash
-npm config set @myco:registry http://reg.example.com
+npm config set @myco:registry=http://reg.example.com
 ```
 
 Once a scope is associated with a registry, any `npm install` for a package with that scope will request packages from that registry instead. Any `npm publish` for a package name that contains the scope will be published to that registry instead.

content/cli/v10/using-npm/scripts.mdx

@@ -267,13 +267,12 @@ For example, if your package.json contains this:
 {
   "scripts": {
     "install": "scripts/install.js",
-    "postinstall": "scripts/install.js",
-    "uninstall": "scripts/uninstall.js"
+    "postinstall": "scripts/install.js"
   }
 }
 ```
 
-then `scripts/install.js` will be called for the install and post-install stages of the lifecycle, and `scripts/uninstall.js` will be called when the package is uninstalled. Since `scripts/install.js` is running for two different phases, it would be wise in this case to look at the `npm_lifecycle_event` environment variable.
+then `scripts/install.js` will be called for the install and post-install stages of the lifecycle. Since `scripts/install.js` is running for two different phases, it would be wise in this case to look at the `npm_lifecycle_event` environment variable.
 
 If you want to run a make command, you can do so. This works just fine:
 
@@ -297,7 +296,7 @@ Note that these script files don't have to be Node.js or even JavaScript program
 
 ### Best Practices
 
-- Don't exit with a non-zero error code unless you _really_ mean it. Except for uninstall scripts, this will cause the npm action to fail, and potentially be rolled back. If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully.
+- Don't exit with a non-zero error code unless you _really_ mean it. If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully.
 - Try not to use scripts to do what npm can do for you. Read through [`package.json`](/cli/v10/configuring-npm/package-json) to see all the things that you can specify and enable by simply describing your package appropriately. In general, this will lead to a more robust and consistent state.
 - Inspect the env to determine where to put things. For instance, if the `npm_config_binroot` environment variable is set to `/home/user/bin`, then don't try to install executables into `/usr/local/bin`. The user probably set it up that way for a reason.
 - Don't prefix your script commands with "sudo". If root permissions are required for some reason, then it'll fail with that error, and the user will sudo the npm command in question.