feat: add init workspaces

Add workspaces support to `npm init`

- Refactored `lib/exec.js` into `libnpmexec`
- Updates [email protected]
- Added ability to create a new workspace using the -w config

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)

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,19 @@ 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`
+* `npm init foo` -> `npm exec create-foo`
+* `npm init @usr/foo` -> `npm exec @usr/create-foo`
+* `npm init @usr` -> `npm exec @usr/create`
 
 Any additional options will be passed directly to the command, so `npm init
-foo -- --hello` will map to `npx create-foo --hello`.
+foo -- --hello` will map to `npm exec -- create-foo --hello`.
 
 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
@@ -71,6 +72,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
@@ -100,3 +163,4 @@ an error.
 * [npm version](/commands/npm-version)
 * [npm scope](/using-npm/scope)
 * [npm exec](/commands/npm-exec)
+* [npm workspaces](/using-npm/workspaces)

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)