feat: Pins the package manager as it's used for the first time

[arcanis]

Once Corepack is enabled, someone restarting their container without having pinned the version of the package manager in packageManager may use different package manager versions pre-restart and post-restart, due to Corepack always defaulting on the highest release when the package manager isn't pinned (this was strongly requested in #93).

However, we want this "dynamic" selection to be slightly tuned down so it only affects projects as they are created - once a project is created or accessed for the first time, the package manager version should remain the same until the user decides otherwise. People in #399 seemed to agree this was the right behaviour, and I don't have very strong objections on that.

This diff implements this logic by checking whether the command is being run inside an arbitrary folder (NoProject), or a project folder whose package.json doesn't contain the packageManager field (NoSpec). In this last case, we write in the package.json the spec string for the package manager we'd have selected. No special handling is done to differentiate read commands (--version) from write commands (install), as I'm not certain this distinction is useful in practice.

Fixes #399; cc @mcollina

[mcollina]

This is a significant win.
Having a config or env variable to "skip" this behavior might be useful (the case where a dev uses a different package manager than the one listed in package.json)

As it might be slightly surprising to users, I think it might be better to write a message to stdout that a packageManager field was added to package.json, and to run corepack XX to update.

[mcollina]

lgtm

[aduh95]

Can we, like the download prompt, make it default to 1 only when using the non-corepack binaries? For the same reason that, because it output stuff to stderr, it could break automation. (i.e. by default, yarn install would add packageManager field if absent, corepack yarn install would not)

[arcanis]

Can we, like the download prompt, make it default to 1 only when using the non-corepack binaries?

I'd prefer to avoid branching the behaviour too much between corepack yarn and raw yarn. I don't expect corepack yarn to be a common case, so the inconsistency doesn't feel worth it (compared to people just having to set the env variable if they really wish to avoid this write).

[styfle]

Suggested change

	field (which you can easily set through `corepack use [name]@[version]`), as
	field (which you can set through `corepack use [name]@[version]`), as

[aduh95]

Can we, like the download prompt, make it default to 1 only when using the non-corepack binaries?

I'd prefer to avoid branching the behaviour too much between corepack yarn and raw yarn. I don't expect corepack yarn to be a common case, so the inconsistency doesn't feel worth it (compared to people just having to set the env variable if they really wish to avoid this write).

Fair enough.

Maybe it doesn't have to be in this PR, but I think it'd be valuable to have a way to ask Corepack to hard fail instead setting the file silently – I would like to enable that on my CI runs, so we can detect if a package.json is missing the field.

[simonhaenisch]

@arcanis wondering if it makes sense that this feature gets similar behavior as COREPACK_ENABLE_DOWNLOAD_PROMPT (#360) to be disabled in non-interactive shells/CI by default? see

https://github.com/nodejs/corepack/pull/360/files#diff-f40bfea195fed9476186ef5bef59fff20a01e341513d8233ec399cfda410ebc0R19

[jakebailey]

I use corepack for everything, but this behavior is pretty annoying (now that I'm using Node 22 with this change) since I can't go into other people's projects without modifying their package.jsons. I see COREPACK_ENABLE_AUTO_PIN=0 should undo this, but it was super surprising when I just happened to be in someone else's repo, did npx ... and then got packageManager set.

[aduh95]

It definitely should not happen when using npx – but maybe what you call with npx is itself calling npm …? Could you open a new issue with a repro so we can investigate?

[jakebailey]

In my case, it was just npx tsc (I believe). I will file an issue when I get a chance.