deps: add corepack

Corepack provides shims for Yarn and pnpm in order to soften the
developer experience when working on Node projects.

Refs: https://github.com/nodejs/node/issues/15244
Refs: https://github.com/nodejs/TSC/issues/904

PR-URL: https://github.com/nodejs/node/pull/39608
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

3 files changed, 164 insertions, 0 deletions

diff --git a/doc/api/corepack.md b/doc/api/corepack.md
new file mode 100644
index 00000000000..1e30256b491
--- /dev/null
+++ b/doc/api/corepack.md
@@ -0,0 +1,119 @@
+# Corepack
+
+<!-- introduced_in=REPLACEME -->
+<!-- type=misc -->
+
+> Stability: 1 - Experimental
+
+_[Corepack][]_ is an experimental tool to help with
+managing versions of your package managers. It exposes binary proxies for
+each [supported package manager][] that, when called, will identify whatever
+package manager is configured for the current project, transparently install
+it if needed, and finally run it without requiring explicit user interactions.
+
+This feature simplifies two core workflows:
+
+* It eases new contributor onboarding, since they won't have to follow
+  system-specific installation processes anymore just to have the package
+  manager you want them to.
+
+* It allows you to ensure that everyone in your team will use exactly the
+  package manager version you intend them to, without them having to
+  manually synchronize it each time you need to make an update.
+
+## Workflows
+
+### Enabling the feature
+
+Due to its experimental status, Corepack currently needs to be explicitly
+enabled to have any effect. To do that simply run [`corepack enable`][], which
+will set up the symlinks in your environment, next to the `node` binary
+(and overwrite the existing symlinks if necessary).
+
+From this point forward, any call to the [supported binaries][] will work
+without further setup. Should you experience a problem, just run
+[`corepack disable`][] to remove the proxies from your system (and consider
+opening up an issue on the [Corepack repository][] to let us know).
+
+### Configuring a package
+
+The Corepack proxies will find the closest [`package.json`][] file in your
+current directory hierarchy to extract its [`"packageManager"`][] property.
+
+If the value corresponds to a [supported package manager][], Corepack will make
+sure that all calls to the relevant binaries are run against the requested
+version, downloading it on demand if needed, and aborting if it cannot be
+successfully retrieved.
+
+### Upgrading the global versions
+
+When running outside of an existing project (for example when running
+`yarn init`), Corepack will by default use predefined versions roughly
+corresponding to the latest stable releases from each tool. Those versions can
+be easily overriden by running the [`corepack prepare`][] command along with the
+package manager version you wish to set:
+
+```bash
+corepack prepare yarn@x.y.z --activate
+```
+
+### Offline workflow
+
+Many production environments don't have network access. Since Corepack
+usually downloads the package manager releases straight from their registries,
+it can conflict with such environments. To avoid that happening, call the
+[`corepack prepare`][] command while you still have network access (typically at
+the same time you're preparing your deploy image). This will ensure that the
+required package managers are available even without network access.
+
+The `prepare` command has [various flags][], consult the detailed
+[Corepack documentation][] for more information on the matter.
+
+## Supported package managers
+
+The following binaries are provided through Corepack:
+
+| Package manager | Binary names   |
+| --------------- | -------------- |
+| [Yarn][]        | `yarn`, `yarnpkg` |
+| [pnpm][]        | `pnpm`, `pnpx` |
+
+## Common questions
+
+### How does Corepack currently interact with npm?
+
+While Corepack could easily support npm like any other package manager, its
+shims aren't currently enabled by default. This has a few consequences:
+
+* It's always possible to run a `npm` command within a project configured to
+be used with another package manager, since Corepack cannot intercept it.
+
+* While `npm` is a valid option in the [`"packageManager"`][] property, the
+lack of shim will cause the global npm to be used.
+
+### Running `npm install -g yarn` doesn't work
+
+npm prevents accidentally overriding the Corepack binaries when doing a global
+install. To avoid this problem, consider one of the following options:
+
+* Don't run this command anymore; Corepack will provide the package manager
+binaries anyway and will ensure that the requested versions are always
+available, so installing the package managers explicitly isn't needed anymore.
+
+* Add the `--force` to `npm install`; this will tell npm that it's fine to
+override binaries, but you'll erase the Corepack ones in the process (should
+that happen, run [`corepack enable`][] again to add them back).
+
+[Corepack]: https://github.com/nodejs/corepack
+[Corepack documentation]: https://github.com/nodejs/corepack#readme
+[Corepack repository]: https://github.com/nodejs/corepack
+[Yarn]: https://yarnpkg.com
+[`"packageManager"`]: packages.md#packages_packagemanager
+[`corepack disable`]: https://github.com/nodejs/corepack#corepack-disable--name
+[`corepack enable`]: https://github.com/nodejs/corepack#corepack-enable--name
+[`corepack prepare`]: https://github.com/nodejs/corepack#corepack-prepare--nameversion
+[`package.json`]: packages.md#packages_node_js_package_json_field_definitions
+[pnpm]: https://pnpm.js.org
+[supported binaries]: #corepack_supported_package_managers
+[supported package manager]: #corepack_supported_package_managers
+[various flags]: https://github.com/nodejs/corepack#utility-commands
diff --git a/doc/api/index.md b/doc/api/index.md
index 448f6d599fc..8ea274ec47e 100644
--- a/doc/api/index.md
+++ b/doc/api/index.md
@@ -21,6 +21,7 @@
 * [Cluster](cluster.md)
 * [Command-line options](cli.md)
 * [Console](console.md)
+* [Corepack](corepack.md)
 * [Crypto](crypto.md)
 * [Debugger](debugger.md)
 * [Deprecated APIs](deprecations.md)
diff --git a/doc/api/packages.md b/doc/api/packages.md
index 0278b649087..09acf5a5490 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -156,6 +156,21 @@ For completeness there is also `--input-type=commonjs`, for explicitly running
 string input as CommonJS. This is the default behavior if `--input-type` is
 unspecified.
 
+## Determining package manager
+
+> Stability: 1 - Experimental
+
+While all Node.js projects are expected to be installable by all package
+managers once published, their development teams are often required to use one
+specific package manager. To make this process easier, Node.js ships with a
+tool called [Corepack][] that aims to make all package managers transparently
+available in your environment - provided you have Node.js installed.
+
+By default Corepack won't enforce any specific package manager and will use
+the generic "Last Known Good" versions associated with each Node.js release,
+but you can improve this experience by setting the [`"packageManager"`][] field
+in your project's `package.json`.
+
 ## Package entry points
 
 In a package’s `package.json` file, two fields can define entry points for a
@@ -1008,6 +1023,8 @@ The following fields in `package.json` files are used in Node.js:
   by package managers as the name of the package.
 * [`"main"`][] - The default module when loading the package, if exports is not
   specified, and in versions of Node.js prior to the introduction of exports.
+* [`"packageManager"`][] - The package manager recommended when contributing to
+  the package. Leveraged by the [Corepack][] shims.
 * [`"type"`][] - The package type determining whether to load `.js` files as
   CommonJS or ES modules.
 * [`"exports"`][] - Package exports and conditional exports. When present,
@@ -1067,6 +1084,30 @@ require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.
 When a package has an [`"exports"`][] field, this will take precedence over the
 `"main"` field when importing the package by name.
 
+### `"packageManager"`
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+```json
+{
+  "packageManager": "<package manager name>@<version>"
+}
+```
+
+The `"packageManager"` field defines which package manager is expected to be
+used when working on the current project. It can set to any of the
+[supported package managers][], and will ensure that your teams use the exact
+same package manager versions without having to install anything else than
+Node.js.
+
+This field is currently experimental and needs to be opted-in; check the
+[Corepack][] page for details about the procedure.
+
 ### `"type"`
 <!-- YAML
 added: v12.0.0
@@ -1199,6 +1240,7 @@ This field defines [subpath imports][] for the current package.
 [Babel]: https://babeljs.io/
 [CommonJS]: modules.md
 [Conditional exports]: #packages_conditional_exports
+[Corepack]: corepack.md
 [ES module]: esm.md
 [ES modules]: esm.md
 [Node.js documentation for this section]: https://github.com/nodejs/node/blob/HEAD/doc/api/packages.md#conditions-definitions
@@ -1206,6 +1248,7 @@ This field defines [subpath imports][] for the current package.
 [`"imports"`]: #packages_imports
 [`"main"`]: #packages_main
 [`"name"`]: #packages_name
+[`"packageManager"`]: #packages_packagemanager
 [`"type"`]: #packages_type
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#errors_err_package_path_not_exported
 [`esm`]: https://github.com/standard-things/esm#readme
@@ -1215,5 +1258,6 @@ This field defines [subpath imports][] for the current package.
 [subpath exports]: #packages_subpath_exports
 [subpath imports]: #packages_subpath_imports
 [subpath patterns]: #packages_subpath_patterns
+[supported package managers]: corepack.md#corepack_supported_package_managers
 [the dual CommonJS/ES module packages section]: #packages_dual_commonjs_es_module_packages
 [the full specifier path]: esm.md#esm_mandatory_file_extensions