feat: npm pkg

Implements `npm pkg get|set|delete` support. It enables retrieving and
modifying values in a `package.json` file of any given project.

Included are the implementation based on npm/rfcs#402
along with extensive tests and user documentation.

Relates to: npm/rfcs#402
Fixes: npm/statusboard#368

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

docs/content/commands/npm-audit.md

@@ -232,6 +232,7 @@ mistakes, unnecessary performance degradation, and malicious input.
 * Allow unpublishing all versions of a published package.
 * Allow conflicting peerDependencies to be installed in the root project.
 * Implicitly set `--yes` during `npm init`.
+* Allow clobbering existing values in `npm pkg`
 
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!
@@ -243,6 +244,9 @@ recommended that you do not use this option!
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `package-lock-only`

docs/content/commands/npm-config.md

@@ -104,6 +104,9 @@ global config.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `global`

docs/content/commands/npm-explain.md

@@ -63,6 +63,9 @@ node_modules/nyc/node_modules/find-up
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `workspace`

docs/content/commands/npm-fund.md

@@ -73,6 +73,9 @@ test-workspaces-fund@1.0.0
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `browser`

docs/content/commands/npm-init.md

@@ -175,6 +175,7 @@ mistakes, unnecessary performance degradation, and malicious input.
 * Allow unpublishing all versions of a published package.
 * Allow conflicting peerDependencies to be installed in the root project.
 * Implicitly set `--yes` during `npm init`.
+* Allow clobbering existing values in `npm pkg`
 
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!

docs/content/commands/npm-ls.md

@@ -91,6 +91,9 @@ upon by the current project.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `long`

docs/content/commands/npm-org.md

@@ -87,6 +87,9 @@ password, npm will prompt on the command line for one.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `parseable`

docs/content/commands/npm-outdated.md

@@ -104,6 +104,9 @@ upon by the current project.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `long`

docs/content/commands/npm-pack.md

@@ -34,6 +34,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `pack-destination`

docs/content/commands/npm-pkg.md

@@ -0,0 +1,238 @@
+---
+title: npm-pkg
+section: 1
+description: Manages your package.json
+---
+
+### Synopsis
+
+```bash
+npm pkg get [<field> [.<subfield> ...]]
+npm pkg set <field>=<value> [.<subfield>=<value> ...]
+npm pkg delete <field> [.<subfield> ...]
+```
+
+### Description
+
+A command that automates the management of `package.json` files.
+`npm pkg` provide 3 different sub commands that allow you to modify or retrieve
+values for given object keys in your `packge.json`.
+
+The syntax to retrieve and set fields is a dot separated representation of
+the nested object properties to be found within your `package.json`, it's the
+same notation used in [`npm view`](/commands/npm-view) to retrieve information
+from the registry manifest, below you can find more examples on how to use it.
+
+Returned values are always in **json** format.
+
+* `npm pkg get <field>`
+
+    Retrieves a value `key`, defined in your `package.json` file.
+
+    For example, in order to retrieve the name of the current package, you
+    can run:
+
+    ```bash
+    npm pkg get name
+    ```
+
+    It's also possible to retrieve multiple values at once:
+
+    ```bash
+    npm pkg get name version
+    ```
+
+    You can view child fields by separating them with a period. To retrieve
+    the value of a test `script` value, you would run the following command:
+
+    ```bash
+    npm pkg get scripts.test
+    ```
+
+    For fields that are arrays, requesting a non-numeric field will return
+    all of the values from the objects in the list. For example, to get all
+    the contributor emails for a package, you would run:
+
+    ```bash
+    npm pkg get contributors.email
+    ```
+
+    You may also use numeric indices in square braces to specifically select
+    an item in an array field. To just get the email address of the first
+    contributor in the list, you can run:
+
+    ```bash
+    npm pkg get contributors[0].email
+    ```
+
+* `npm pkg set <field>=<value>`
+
+    Sets a `value` in your `package.json` based on the `field` value. When
+    saving to your `package.json` file the same set of rules used during
+    `npm install` and other cli commands that touches the `package.json` file
+    are used, making sure to respect the existing indentation and possibly
+    applying some validation prior to saving values to the file.
+
+    The same syntax used to retrieve values from your package can also be used
+    to define new properties or overriding existing ones, below are some
+    examples of how the dot separated syntax can be used to edit your
+    `package.json` file.
+
+    Defining a new bin named `mynewcommand` in your `package.json` that points
+    to a file `cli.js`:
+
+    ```bash
+    npm pkg set bin.mynewcommand=cli.js
+    ```
+
+    Setting multiple fields at once is also possible:
+
+    ```bash
+    npm pkg set description='Awesome package' engines.node='>=10'
+    ```
+
+    It's also possible to add to array values, for example to add a new
+    contributor entry:
+
+    ```bash
+    npm pkg set contributors[0].name='Foo' contributors[0].email='foo@bar.ca'
+    ```
+
+    It's also possible to parse values as json prior to saving them to your
+    `package.json` file, for example in order to set a `"private": true`
+    property:
+
+    ```bash
+    npm pkg set private=true --json
+    ```
+
+    It also enables saving values as numbers:
+
+    ```bash
+    npm pkg set tap.timeout=60 --json
+    ```
+
+* `npm pkg delete <key>`
+
+    Deletes a `key` from your `package.json`
+
+    The same syntax used to set values from your package can also be used
+    to remove existing ones. For example, in order to remove a script named
+    build:
+
+    ```bash
+    npm pkg delete scripts.build
+    ```
+
+### Workspaces support
+
+You can set/get/delete items across your configured workspaces by using the
+`workspace` or `workspaces` config options.
+
+For example, setting a `funding` value across all configured workspaces
+of a project:
+
+```bash
+npm pkg set funding=https://example.com --ws
+```
+
+When using `npm pkg get` to retrieve info from your configured workspaces, the
+returned result will be in a json format in which top level keys are the
+names of each workspace, the values of these keys will be the result values
+returned from each of the configured workspaces, e.g:
+
+```
+npm pkg get name version --ws
+{
+  "a": {
+    "name": "a",
+    "version": "1.0.0"
+  },
+  "b": {
+    "name": "b",
+    "version": "1.0.0"
+  }
+}
+```
+
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `force`
+
+* Default: false
+* Type: Boolean
+
+Removes various protections against unfortunate side effects, common
+mistakes, unnecessary performance degradation, and malicious input.
+
+* Allow clobbering non-npm files in global installs.
+* Allow the `npm version` command to work on an unclean git repository.
+* Allow deleting the cache folder with `npm cache clean`.
+* Allow installing packages that have an `engines` declaration requiring a
+  different version of npm.
+* Allow installing packages that have an `engines` declaration requiring a
+  different version of `node`, even if `--engine-strict` is enabled.
+* Allow `npm audit fix` to install modules outside your stated dependency
+  range (including SemVer-major changes).
+* Allow unpublishing all versions of a published package.
+* Allow conflicting peerDependencies to be installed in the root project.
+* Implicitly set `--yes` during `npm init`.
+* Allow clobbering existing values in `npm pkg`
+
+If you don't have a clear idea of what you want to do, it is strongly
+recommended that you do not use this option!
+
+#### `json`
+
+* Default: false
+* Type: Boolean
+
+Whether or not to output JSON data, rather than the normal output.
+
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
+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
+
+* [npm install](/commands/npm-install)
+* [npm init](/commands/npm-init)
+* [npm config](/commands/npm-config)
+* [npm set-script](/commands/npm-set-script)
+* [workspaces](/using-npm/workspaces)

docs/content/commands/npm-profile.md

@@ -91,6 +91,9 @@ The base URL of the npm registry.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `parseable`

docs/content/commands/npm-prune.md

@@ -75,6 +75,9 @@ Note: This is NOT honored by other network related commands, eg `dist-tags`,
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `workspace`

docs/content/commands/npm-search.md

@@ -55,6 +55,9 @@ Show extended information in `ls`, `search`, and `help-search`.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `color`

docs/content/commands/npm-team.md

@@ -138,6 +138,9 @@ Output parseable results from commands that write to standard output. For
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

docs/content/commands/npm-unpublish.md

@@ -82,6 +82,7 @@ mistakes, unnecessary performance degradation, and malicious input.
 * Allow unpublishing all versions of a published package.
 * Allow conflicting peerDependencies to be installed in the root project.
 * Implicitly set `--yes` during `npm init`.
+* Allow clobbering existing values in `npm pkg`
 
 If you don't have a clear idea of what you want to do, it is strongly
 recommended that you do not use this option!

docs/content/commands/npm-version.md

@@ -47,6 +47,9 @@ Tag the commit when using the `npm version` command.
 
 Whether or not to output JSON data, rather than the normal output.
 
+* In `npm pkg set` it enables parsing set values with JSON.parse() before
+  saving them to your `package.json`.
+
 Not supported by all npm commands.
 
 #### `preid`