feat(setup): report package-manager confidence and stop guessing silently

[ffantl-ld]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions

Related issues

Steps 1–3 of the package-manager selection design. Stacked on #782, which owns PackageManagerFor. The wizard picker (step 4) is a follow-up.

Describe the solution you've provided

• Split package-manager signals into what a project declares and what it merely implies, and report a definite/ambiguous verdict. Detection previously always returned a manager, so a project that never said which one it used got pip or npm presented as fact.
• Recognise signals that were previously read as pip/npm: the corepack packageManager field (which outranks lockfiles, being the most explicit statement a project can make), poetry.lock, Pipfile.lock, package-lock.json, npm-shrinkwrap.json, and [tool.pdm].
• Record [tool.hatch] as a signal we cannot act on — hatch has no dependency-add command — so a hatch project stays ambiguous instead of silently falling through to pip.
• setup install reads the project when --package-manager is omitted, rather than defaulting to pip/npm whatever the lockfiles say. On an ambiguous project it fails with the candidate list instead of choosing for the user.
• setup detect reports the verdict, and its JSON adds package_manager_candidates with the command each would run and whether it is installed.

Describe alternatives you've considered

• Improving detection signals only, without a confidence verdict. Rejected: a repo with both yarn.lock and package-lock.json has no correct guess, and today detectNodePM returns yarn purely because it checks first. No amount of signal tuning fixes a project that contradicts itself.
• Letting installed tooling decide — auto-selecting when exactly one candidate is on PATH. Rejected: having pnpm installed says nothing about whether this repo uses it, and it would give two developers different answers for the same project. Installed state orders the list and nothing more.
• Guessing with a low-confidence marker in setup install rather than failing. Rejected: these subcommands are the documented engine for external agents, and a silent wrong manager is worse than an error.

Additional context

PackageManagerCandidates is deliberately not on DetectResult. installed describes the machine rather than the project, so keeping it out leaves detection deterministic and its tests machine-independent; the detect command adds candidates to its own JSON payload for callers that need them.

Installed tracks the executable the resolved command actually runs, not the candidate label — the pip candidate reports installed when only pip3 exists, because its command is pip3 install.

DetectResult.PackageManager is still whatever the language detector produced. Those detectors know about managers this model does not, such as maven versus gradle.

Testing approaches

• go test ./... passes.
• Confidence tests over definite shapes (corepack with and without a version, corepack beating a conflicting lockfile, single lockfiles, [tool.uv], [tool.pdm], Gemfile) and ambiguous ones (conflicting lockfiles, bare package.json, PEP 621 pyproject.toml only, requirements.txt only, hatch, gemspec without a Gemfile).
• A test pinning that installed state cannot change the verdict: with only pnpm on a stubbed PATH, a bare package.json stays ambiguous and the name stays npm.
• TestFileDetector_ProjectShapes clears the confidence fields before comparing, since those shapes assert language/SDK/entry point and confidence has its own tests.
• Verified with a built binary on the four cases that were previously silently wrong: corepack pnpm@9.1.0 → pnpm (was npm); yarn.lock + package-lock.json → flagged uncertain naming both (was silently yarn); [tool.pdm] → pdm (was pip); [tool.hatch] → uncertain (was pip). setup install fails on the conflicting project and resolves uv add in a uv.lock project where it previously ran pip3 install.

---

Note

Overview
Stops treating a conventional default (npm/pip) as fact. Detection now returns a definite or ambiguous package-manager verdict, and setup install uses that instead of guessing.

Detection reads declared vs implied signals: corepack packageManager (exact semver only, outranks lockfiles), extra lockfiles (package-lock.json, poetry.lock, pdm.lock, etc.), and parsed [tool.*] tables in pyproject.toml. Conflicting or missing signals, hatch-only projects, and invalid corepack specs stay ambiguous. Installed tools never decide the verdict.

setup detect surfaces uncertainty in plaintext and, for JSON, adds package_manager_candidates (command + installed) only when ambiguous. setup install without --package-manager auto-selects a definite manager (stderr note about the old npm/pip default) and errors on ambiguous projects with a candidate list.

Also adds pdm add install support and maps corepack “bad packageManager spec” failures to a recoverable reason instead of a dead-end error.

^{Reviewed by Cursor Bugbot for commit 04662ac. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d56b2d7. Configure here.}