feat: add init workspaces

Add workspaces support to `npm init`

- Fixes `npm exec` respecting `script-shell` option value
- Refactored `lib/exec.js` into `libnpmexec`
- Updates init-package-json@2.0.3
- Added ability to create a new workspace using the -w config

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

4 files changed, 114 insertions, 11 deletions

diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
index 6666d30e8..2364da32c 100644
--- a/docs/content/commands/npm-exec.md
+++ b/docs/content/commands/npm-exec.md
@@ -291,3 +291,4 @@ project.
 * [npm restart](/commands/npm-restart)
 * [npm stop](/commands/npm-stop)
 * [npm config](/commands/npm-config)
+* [npm workspaces](/using-npm/workspaces)
diff --git a/docs/content/commands/npm-init.md b/docs/content/commands/npm-init.md
index 4b0b8c4c4..8288034a3 100644
--- a/docs/content/commands/npm-init.md
+++ b/docs/content/commands/npm-init.md
@@ -8,8 +8,9 @@ description: Create a package.json file
 
 ```bash
 npm init [--force|-f|--yes|-y|--scope]
-npm init <@scope> (same as `npx <@scope>/create`)
-npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)
+npm init <@scope> (same as `npm exec <@scope>/create`)
+npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`)
+npm init [-w <dir>] [args...]
 ```
 
 ### Description
@@ -18,19 +19,16 @@ npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)
 package.
 
 `initializer` in this case is an npm package named `create-<initializer>`,
-which will be installed by [`npx`](https://npm.im/npx), and then have its
+which will be installed by [`npm-exec`](/commands/npm-exec), and then have its
 main bin executed -- presumably creating or updating `package.json` and
 running any other initialization-related operations.
 
-The init command is transformed to a corresponding `npx` operation as
+The init command is transformed to a corresponding `npm exec` operation as
 follows:
 
-* `npm init foo` -> `npx create-foo`
-* `npm init @usr/foo` -> `npx @usr/create-foo`
-* `npm init @usr` -> `npx @usr/create`
-
-Any additional options will be passed directly to the command, so `npm init
-foo -- --hello` will map to `npx create-foo --hello`.
+* `npm init foo` -> `npm exec create-foo`
+* `npm init @usr/foo` -> `npm exec @usr/create-foo`
+* `npm init @usr` -> `npm exec @usr/create`
 
 If the initializer is omitted (by just calling `npm init`), init will fall
 back to legacy init behavior. It will ask you a bunch of questions, and
@@ -40,6 +38,18 @@ strictly additive, so it will keep any fields and values that were already
 set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If
 you pass `--scope`, it will create a scoped package.
 
+#### Forwarding additional options
+
+Any additional options will be passed directly to the command, so `npm init
+foo -- --hello` will map to `npm exec -- create-foo --hello`.
+
+To better illustrate how options are forwarded, here's a more evolved
+example showing options passed to both the **npm cli** and a create package,
+both following commands are equivalent:
+
+- `npm init foo -y --registry=<url> -- --hello -a`
+- `npm exec -y --registry=<url> -- create-foo --hello -a`
+
 ### Examples
 
 Create a new React-based project using
@@ -71,6 +81,68 @@ Generate it without having it ask any questions:
 $ npm init -y
 ```
 
+### Workspaces support
+
+It's possible to create a new workspace within your project by using the
+`workspace` config option. When using `npm init -w <dir>` the cli will
+create the folders and boilerplate expected while also adding a reference
+to your project `package.json` `"workspaces": []` property in order to make
+sure that new generated **workspace** is properly set up as such.
+
+Given a project with no workspaces, e.g:
+
+```
+.
++-- package.json
+```
+
+You may generate a new workspace using the legacy init:
+
+```bash
+$ npm init -w packages/a
+```
+
+That will generate a new folder and `package.json` file, while also updating
+your top-level `package.json` to add the reference to this new workspace:
+
+```
+.
++-- package.json
+`-- packages
+   `-- a
+       `-- package.json
+```
+
+The workspaces init also supports the `npm init <initializer> -w <dir>`
+syntax, following the same set of rules explained earlier in the initial
+**Description** section of this page. Similar to the previous example of
+creating a new React-based project using
+[`create-react-app`](https://npm.im/create-react-app), the following syntax
+will make sure to create the new react app as a nested **workspace** within your
+project and configure your `package.json` to recognize it as such:
+
+```bash
+npm init -w packages/my-react-app react-app .
+```
+
+This will make sure to generate your react app as expected, one important
+consideration to have in mind is that `npm exec` is going to be run in the
+context of the newly created folder for that workspace, and that's the reason
+why in this example the initializer uses the initializer name followed with a
+dot to represent the current directory in that context, e.g: `react-app .`:
+
+```
+.
++-- package.json
+`-- packages
+   +-- a
+   |   `-- package.json
+   `-- my-react-app
+       +-- README
+       +-- package.json
+       `-- ...
+```
+
 ### A note on caching
 
 The npm cli utilizes its internal package cache when using the package
@@ -93,6 +165,33 @@ requested from the server. To force full offline mode, use `offline`.
 Forces full offline mode. Any packages not locally cached will result in
 an error.
 
+#### workspace
+
+* Alias: `-w`
+* Type: Array
+* Default: `[]`
+
+Enable running `npm init` in the context of workspaces, creating any missing
+folders, generating files and adding/updating the `"workspaces"` property of
+the project `package.json`.
+
+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 `npm init` in the context of all configured workspaces for the
+current project.
+
 ### See Also
 
 * [init-package-json module](http://npm.im/init-package-json)
@@ -100,3 +199,4 @@ an error.
 * [npm version](/commands/npm-version)
 * [npm scope](/using-npm/scope)
 * [npm exec](/commands/npm-exec)
+* [npm workspaces](/using-npm/workspaces)
diff --git a/docs/content/commands/npm-run-script.md b/docs/content/commands/npm-run-script.md
index 028f8eb15..6786312e0 100644
--- a/docs/content/commands/npm-run-script.md
+++ b/docs/content/commands/npm-run-script.md
@@ -204,3 +204,4 @@ project.
 * [npm restart](/commands/npm-restart)
 * [npm stop](/commands/npm-stop)
 * [npm config](/commands/npm-config)
+* [npm workspaces](/using-npm/workspaces)
diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index b2e8baf01..1a70c29f9 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -1087,7 +1087,8 @@ installation of packages specified according to the pattern
 * Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
 * Type: null or String
 
-The shell to use for scripts run with the `npm run` command.
+The shell to use for scripts run with the `npm exec`, `npm run` and
+`npm init <pkg>` commands.
 
 #### `searchexclude`