Add workspaces support to reify/rebuild commands

This adds `--workspace` support to:

- audit (including audit fix)
- ci
- dedupe
- find-dupes
- install
- install-ci-test
- install-test
- prune
- rebuild
- uninstall
- update

Also addresses missing error handling case, identified by @timoxley.
https://github.com/npm/cli/pull/3227#discussion_r631024491

PR-URL: https://github.com/npm/cli/pull/3227
Credit: @isaacs
Close: #3227
Reviewed-by: @ruyadorno

9 files changed, 288 insertions, 0 deletions

diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md
index 27c4d9725..0771d897d 100644
--- a/docs/content/commands/npm-audit.md
+++ b/docs/content/commands/npm-audit.md
@@ -271,6 +271,38 @@ it will be included.
 If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
 variable will be set to `'production'` for all lifecycle scripts.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md
index e870ad269..fbccc4105 100644
--- a/docs/content/commands/npm-dedupe.md
+++ b/docs/content/commands/npm-dedupe.md
@@ -202,6 +202,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-find-dupes.md b/docs/content/commands/npm-find-dupes.md
index 933c76e2f..28281d567 100644
--- a/docs/content/commands/npm-find-dupes.md
+++ b/docs/content/commands/npm-find-dupes.md
@@ -132,6 +132,38 @@ When "true" displays the message at the end of each `npm install`
 acknowledging the number of dependencies looking for funding. See [`npm
 fund`](/commands/npm-fund) for details.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md
index 1adf6490f..deefbd96b 100644
--- a/docs/content/commands/npm-install-test.md
+++ b/docs/content/commands/npm-install-test.md
@@ -187,6 +187,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md
index 9e61cf726..e5091e660 100644
--- a/docs/content/commands/npm-install.md
+++ b/docs/content/commands/npm-install.md
@@ -571,6 +571,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### Algorithm
diff --git a/docs/content/commands/npm-prune.md b/docs/content/commands/npm-prune.md
index 288901932..ecb6bdcd6 100644
--- a/docs/content/commands/npm-prune.md
+++ b/docs/content/commands/npm-prune.md
@@ -77,6 +77,38 @@ Whether or not to output JSON data, rather than the normal output.
 
 Not supported by all npm commands.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md
index 144dd7b09..49c822d73 100644
--- a/docs/content/commands/npm-rebuild.md
+++ b/docs/content/commands/npm-rebuild.md
@@ -66,6 +66,38 @@ Note that commands explicitly intended to run a particular script, such as
 will still run their intended script if `ignore-scripts` is set, but they
 will *not* run any pre- or post-scripts.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-uninstall.md b/docs/content/commands/npm-uninstall.md
index cffb9bdb5..b6ba31393 100644
--- a/docs/content/commands/npm-uninstall.md
+++ b/docs/content/commands/npm-uninstall.md
@@ -68,6 +68,38 @@ Save installed packages to a package.json file as dependencies.
 When used with the `npm rm` command, removes the dependency from
 package.json.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md
index 044b1a82d..4c9271c66 100644
--- a/docs/content/commands/npm-update.md
+++ b/docs/content/commands/npm-update.md
@@ -258,6 +258,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either:
+
+* Workspace names
+* Path to a workspace directory
+* Path to a parent workspace directory (will result to selecting all of the
+  nested workspaces)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also