feat: add run-script workspaces

- Add workspaces-related configs:
  - workspace: list of workspaces names/dir to filter for
  - workspaces: boolean value to enable/disable workspaces awareness
  - adds the proposed note in the docs of each of the commands
    that are not affected by these configs.
- Add workspaces support to `npm run-script`
  - add ability to serially run lifecycle scripts in workspaces
  - add ability to list scripts for all workspaces
  - add colors to `npm run` (no args) output

Relates to: npm/rfcs#117
Fixes: npm/statusboard#276
Fixes: npm/statusboard#283
Fixes: npm/statusboard#284
Fixes: npm/statusboard#285
Fixes: npm/statusboard#286

PR-URL: #2864
Credit: @ruyadorno
Close: #2864
Reviewed-by: @wraithgar

docs/content/commands/npm-adduser.md

@@ -12,6 +12,8 @@ npm adduser [--registry=url] [--scope=@orgname] [--always-auth] [--auth-type=leg
 aliases: login, add-user
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Create or verify a user named `<username>` in the specified registry, and

docs/content/commands/npm-bin.md

@@ -10,6 +10,8 @@ description: Display npm bin folder
 npm bin [-g|--global]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Print the folder where npm will install executables.

docs/content/commands/npm-cache.md

@@ -18,6 +18,8 @@ aliases: npm cache clear, npm cache rm
 npm cache verify
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Used to add, list, or clean the npm cache folder.

docs/content/commands/npm-completion.md

@@ -10,6 +10,8 @@ description: Tab Completion for npm
 source <(npm completion)
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Enables tab-completion in all npm commands.

docs/content/commands/npm-config.md

@@ -18,6 +18,8 @@ npm get [<key> [<key> ...]]
 alias: c
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 npm gets its config settings from the command line, environment

docs/content/commands/npm-deprecate.md

@@ -10,6 +10,8 @@ description: Deprecate a version of a package
 npm deprecate <pkg>[@<version range>] <message>
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 This command will update the npm registry entry for a package, providing a

docs/content/commands/npm-doctor.md

@@ -10,6 +10,8 @@ description: Check your npm environment
 npm doctor
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 `npm doctor` runs a set of checks to ensure that your npm installation has

docs/content/commands/npm-edit.md

@@ -10,6 +10,8 @@ description: Edit an installed package
 npm edit <pkg>
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Selects a dependency in the current project and opens the package folder in

docs/content/commands/npm-explore.md

@@ -10,6 +10,8 @@ description: Browse an installed package
 npm explore <pkg> [ -- <command>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Spawn a subshell in the directory of the installed package specified.

docs/content/commands/npm-help-search.md

@@ -10,6 +10,8 @@ description: Search npm help documentation
 npm help-search <text>
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 This command will search the npm markdown documentation files for the terms

docs/content/commands/npm-help.md

@@ -10,6 +10,8 @@ description: Get help on npm
 npm help <term> [<terms..>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 If supplied a topic, then show the appropriate documentation page.

docs/content/commands/npm-hook.md

@@ -13,6 +13,8 @@ npm hook update <id> <url> [secret]
 npm hook rm <id>
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Allows you to manage [npm

docs/content/commands/npm-logout.md

@@ -10,6 +10,8 @@ description: Log out of the registry
 npm logout [--registry=<url>] [--scope=<@scope>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 When logged into a registry that supports token-based authentication, tell

docs/content/commands/npm-org.md

@@ -12,6 +12,8 @@ npm org rm <orgname> <username>
 npm org ls <orgname> [<username>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Example
 
 Add a new developer to an org:

docs/content/commands/npm-owner.md

@@ -14,6 +14,8 @@ npm owner ls [<@scope>/]<pkg>
 aliases: author
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Manage ownership of published packages.

docs/content/commands/npm-ping.md

@@ -10,6 +10,8 @@ description: Ping npm registry
 npm ping [--registry <registry>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Ping the configured or given npm registry and verify authentication.

docs/content/commands/npm-prefix.md

@@ -10,6 +10,8 @@ description: Display prefix
 npm prefix [-g]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Print the local prefix to standard output. This is the closest parent directory

docs/content/commands/npm-profile.md

@@ -14,6 +14,8 @@ npm profile enable-2fa [auth-and-writes|auth-only]
 npm profile disable-2fa
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Change your profile information on the registry.  Note that this command

docs/content/commands/npm-run-script.md

@@ -8,6 +8,8 @@ description: Run arbitrary package scripts
 
 ```bash
 npm run-script <command> [--if-present] [--silent] [-- <args>]
+npm run-script <command> [--workspace=<workspace-name>]
+npm run-script <command> [--workspaces]
 
 aliases: run, rum, urn
 ```
@@ -78,6 +80,65 @@ If you try to run a script without having a `node_modules` directory and it
 fails, you will be given a warning to run `npm install`, just in case you've
 forgotten.
 
+### Workspaces support
+
+You may use the `workspace` or `workspaces` configs in order to run an
+arbitrary command from a package's `"scripts"` object in the context of the
+specified workspaces. If no `"command"` is provided, it will list the available
+scripts for each of these configured workspaces.
+
+Given a project with configured workspaces, e.g:
+
+```
+.
++-- package.json
+`-- packages
+   +-- a
+   |   `-- package.json
+   +-- b
+   |   `-- package.json
+   `-- c
+       `-- package.json
+```
+
+Assuming the workspace configuration is properly set up at the root level
+`package.json` file. e.g:
+
+```
+{
+    "workspaces": [ "./packages/*" ]
+}
+```
+
+And that each of the configured workspaces has a configured `test` script,
+we can run tests in all of them using the `workspaces` config:
+
+```
+npm test --workspaces
+```
+
+#### Filtering workspaces
+
+It's also possible to run a script in a single workspace using the `workspace`
+config along with a name or directory path:
+
+```
+npm test --workspace=a
+```
+
+The `workspace` config can also be specified multiple times in order to run a
+specific script in the context of multiple workspaces. When defining values for
+the `workspace` config in the command line, it also possible to use `-w` as a
+shorthand, e.g:
+
+```
+npm test -w a -w b
+```
+
+This last command will run `test` in both `./packages/a` and `./packages/b`
+packages.
+
+
 ### Configuration
 
 #### if-present
@@ -111,6 +172,30 @@ to `/bin/sh` on Unix, defaults to `env.comspec` or `cmd.exe` on Windows.
 
 You can use the `--silent` flag to prevent showing `npm ERR!` output on error.
 
+#### workspace
+
+* Alias: `-w`
+* Type: Array
+* Default: `[]`
+
+Enable running scripts in the context of workspaces while also filtering by
+the provided names or paths provided.
+
+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
+children workspaces)
+
+#### workspaces
+
+* Alias: `-ws`
+* Type: Boolean
+* Default: `false`
+
+Run scripts in the context of all configured workspaces for the current
+project.
+
 ### See Also
 
 * [npm scripts](/using-npm/scripts)

docs/content/commands/npm-search.md

@@ -12,6 +12,8 @@ npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms .
 aliases: s, se, find
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Search the registry for packages matching the search terms. `npm search`

docs/content/commands/npm-shrinkwrap.md

@@ -10,6 +10,8 @@ description: Lock down dependency versions for publication
 npm shrinkwrap
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 This command repurposes `package-lock.json` into a publishable

docs/content/commands/npm-star.md

@@ -10,6 +10,8 @@ description: Mark your favorite packages
 npm star [<pkg>...]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 "Starring" a package means that you have some interest in it.  It's

docs/content/commands/npm-stars.md

@@ -9,6 +9,8 @@ description: View packages marked as favorites
 npm stars [<user>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 If you have starred a lot of neat things and want to find them again

docs/content/commands/npm-team.md

@@ -16,6 +16,8 @@ npm team rm <scope:team> <user>
 npm team ls <scope>|<scope:team>
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Used to manage teams in organizations, and change team memberships. Does not

docs/content/commands/npm-token.md

@@ -9,7 +9,9 @@ description: Manage your authentication tokens
   npm token list [--json|--parseable]
   npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16]
   npm token revoke <id|token>
-  ```
+```
+
+Note: This command is unaware of workspaces.
 
 ### Description
 

docs/content/commands/npm-unstar.md

@@ -10,6 +10,8 @@ description: Remove an item from your favorite packages
 npm unstar [<pkg>...]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 "Unstarring" a package is the opposite of [`npm star`](/commands/npm-star),

docs/content/commands/npm-whoami.md

@@ -10,6 +10,8 @@ description: Display npm username
 npm whoami [--registry <registry>]
 ```
 
+Note: This command is unaware of workspaces.
+
 ### Description
 
 Print the `username` config to standard output.

docs/content/using-npm/workspaces.md

@@ -88,8 +88,54 @@ This demonstrates how the nature of `node_modules` resolution allows for
 in such a way that is also easy to [publish](/commands/npm-publish) these
 nested workspaces to be consumed elsewhere.
 
+### Running commands in the context of workspaces
+
+You man use the `workspace` configuration option to run commands in the context
+of a configured workspace.
+
+Following is a quick example on how to use the `npm run` command in the context
+of nested workspaces. For a project containing multiple workspaces, e.g:
+
+```
+.
++-- package.json
+`-- packages
+   +-- a
+   |   `-- package.json
+   `-- b
+       `-- package.json
+```
+
+By running a command using the `workspace` option, it's possible to run the
+given command in the context of that specific workspace. e.g:
+
+```
+npm run test --workspace=a
+```
+
+This will run the `test` script defined within the
+`./packages/a/package.json` file.
+
+Please note that you can also specify this argument multiple times in the
+command-line in order to target multiple workspaces, e.g:
+
+```
+npm run test --workspace=a --workspace=b
+```
+
+It's also possible to use the `workspaces` (plural) configuration option to
+enable the same behavior but running that command in the context of **all**
+configured workspaces. e.g:
+
+```
+npm run test --workspaces
+```
+
+Will run the `test` script in both `./packages/a` and `./packages/b`.
+
 ### See also
 
 * [npm install](/commands/npm-install)
 * [npm publish](/commands/npm-publish)
+* [npm run-script](/commands/npm-run-script)