feat: prepare upm support and fail cleanly on unknown package managers

[iiio2]

🔗 Linked issue

antfu-collective/package-manager-detector#80

📚 Description

This PR prepares support for upm as a package manager. The CLI's detection and install commands come from package-manager-detector, and upm support there is still in review in the linked PR. So this PR does two things that are safe to merge now.

1. Only offer package managers the detector can run. upm is added to the list, which is then filtered down to the agents package-manager-detector has commands for. With the current 1.8.0, upm is filtered out, so nothing changes for users: no new --packageManager value, and help and docs stay the same. Once the detector ships upm, it shows up in nuxt init, nuxt module add and --packageManager without further code changes.

2. Fail cleanly on an unknown package manager. resolveCommand throws (not returns null) for an agent the detector doesn't know, and getInstallCommand used ! on its result. runInstall and runDedupe now check the agent first and return a failure result (Installing dependencies is not supported for …), the same way runDedupe already reported an unsupported dedupe.

Tests:

• Every entry in packageManagerNames resolves install, add and uninstall, so the list can't drift from the detector.
• runInstall and runDedupe report an unknown agent as a failure.
• upm detection from upm.lock and getLockFiles('upm'). These are skipped until the detector supports upm.

I also ran the suite against a local build of the detector PR. The upm tests pass, and the only other changes are that pnpm docs:generate and the help.spec.ts snapshots gain upm. Those, plus the version bump, will be the follow-up once the detector is released.

Checked locally: tsc --noEmit, eslint, pnpm test:docs and all 1905 non-e2e tests pass.

🤖 Generated with Claude Code

[pkg-pr-new]

• nuxt-cli-playground

  npm i https://pkg.pr.new/create-nuxt@1583
  

  npm i https://pkg.pr.new/nuxi@1583
  

  npm i https://pkg.pr.new/@nuxt/cli@1583
  

commit: caafda3

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 51300af0-0054-4ee4-9b92-6c32f46f1abe

📥 Commits

Reviewing files that changed from the base of the PR and between eabcb01 and caafda3.

📒 Files selected for processing (4)

• packages/nuxt-cli/src/utils/install.ts
• packages/nuxt-cli/src/utils/package-managers.ts
• packages/nuxt-cli/test/unit/utils/install.spec.ts
• packages/nuxt-cli/test/unit/utils/package-managers.spec.ts

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

The package manager list now includes preferred names only when package-manager-detector provides commands for them. Install and dedupe command resolution now checks whether the detected agent is supported. When an install command is unavailable, runInstall returns a failed result. Tests cover unsupported agents, command resolution, and conditional upm detection and lock-file ownership.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to caafd

No merge-blocking issue is established; the change is ready for normal checks.

Architecture Summary

Architecture risk: 🟡 Medium · up to caafd

The change affects 1 system.

Changed systems: packages/nuxt-cli

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — packages/nuxt-cli (library) was modified; 4 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in packages/nuxt-cli/src/utils/install.ts: The package-manager-detector type import now includes Agent and Command alongside DetectResult.
• observed — Modified behavior in packages/nuxt-cli/src/utils/install.ts: The commands import now includes COMMANDS for checking supported agents.
• observed — Modified behavior in packages/nuxt-cli/src/utils/install.ts: Adds resolveAgentCommand, which calls resolveCommand only when agent is an own key of COMMANDS; otherwise it returns null.
• observed — Modified behavior in packages/nuxt-cli/src/utils/install.ts: getInstallCommand now uses the guarded resolver for both install and add/uninstall commands, returning null for an unsupported agent instead of asserting that resolution succeeds.

Reliability and maintainability

• inferred — Risk-relevant change factors for packages/nuxt-cli: blast_radius_1; blast_radius_2; blast_radius_3; direct_dependents_1; direct_dependents_2

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the planned upm support and clean failure handling for unknown package managers. It matches the changeset and includes relevant testing details.
Title check	✅ Passed	The title accurately summarizes both primary changes: preparing upm support and handling unknown package managers without throwing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

CLI benchmark

@nuxt/cli v4.0.0-alpha.1 (baseline) vs v4.0.0-alpha.1 (this PR)

Metric	baseline v4.0.0-alpha.1	head v4.0.0-alpha.1	Delta
nuxt --version wall time (median)	91 ms	88 ms	-3.1%
nuxt --help wall time (median)	149 ms	149 ms	-0.5%
nuxt dev --help wall time (median)	104 ms	104 ms	-0.1%
nuxt --version modules loaded	37	37	0.0%
nuxt --help modules loaded	145	145	0.0%
nuxt dev --help modules loaded	63	63	0.0%
Installed node_modules	2.43 MB	2.43 MB	+0.0%
Published tarball (packed)	241.1 kB	241.3 kB	+0.1%

Full report

@nuxt/cli v4.0.0-alpha.1 (baseline) vs v4.0.0-alpha.1 (head)

Setting	Value
Baseline	ref:eabcb017c3cc1346b1e9743cd14221391635c248 (v4.0.0-alpha.1)
Head	local packages/nuxt-cli at d4e9dbc (v4.0.0-alpha.1)
Node	v24.21.0
OS	Linux 6.17.0 (kernel 6.17.0-1022-azure)
CPU	AMD EPYC 7763 64-Core Processor x 4
Memory	15.6 GB
Load average at start	0.85, 0.27, 0.09
Run started	2026-09-29T15:34:15.830Z

Cold CLI startup

Median of 15 interleaved runs per command, one warmup discarded.

Command	baseline v4.0.0-alpha.1 median	head v4.0.0-alpha.1 median	Delta	baseline v4.0.0-alpha.1 min / p95	head v4.0.0-alpha.1 min / p95
nuxt --version	91 ms	88 ms	-3.1%	87 ms / 96 ms	85 ms / 94 ms
nuxt --version (first output byte)	85 ms	83 ms	-1.9%	81 ms / 89 ms	80 ms / 88 ms
nuxt --help	149 ms	149 ms	-0.5%	140 ms / 155 ms	143 ms / 153 ms
nuxt --help (first output byte)	144 ms	143 ms	-0.2%	134 ms / 149 ms	137 ms / 147 ms
nuxt dev --help	104 ms	104 ms	-0.1%	99 ms / 113 ms	100 ms / 107 ms
nuxt dev --help (first output byte)	99 ms	98 ms	-1.0%	94 ms / 108 ms	95 ms / 102 ms
nuxt <unknown-command> (no-op)	157 ms	159 ms	+1.7%	150 ms / 161 ms	150 ms / 164 ms
nuxt <unknown-command> (no-op) (first output byte)	151 ms	153 ms	+1.3%	144 ms / 155 ms	144 ms / 158 ms

Module load cost

Counted with a module.registerHooks load hook, compile cache disabled. Counts every JS module actually evaluated on that code path (built-ins excluded, native addons excluded).

Command	baseline v4.0.0-alpha.1 modules	head v4.0.0-alpha.1 modules	Delta	baseline v4.0.0-alpha.1 source bytes	head v4.0.0-alpha.1 source bytes	Delta
nuxt --version	37	37	0.0%	297.6 kB	297.6 kB	0.0%
nuxt --help	145	145	0.0%	957.7 kB	958.4 kB	+0.1%
nuxt dev --help	63	63	0.0%	455.1 kB	455.1 kB	0.0%

Install footprint and published tarball

Each version installed on its own into an empty project with nothing but @nuxt/cli as a dependency, so the tree is exactly the CLI and its transitive dependencies. npm cache is warm and the registry is only consulted for metadata, so install wall time is indicative, not a network benchmark.

Metric	baseline v4.0.0-alpha.1	head v4.0.0-alpha.1	Delta
Direct dependencies of @nuxt/cli	23	23	0.0%
Packages in the installed tree (unique name@version)	39	39	0.0%
Unique package names	39	39	0.0%
Package directories on disk (cross-check)	32	32	0.0%
Installed node_modules on disk	2.43 MB	2.43 MB	+0.0%
Installed files	434	434	0.0%
Install wall time (warm npm cache, median of 3)	1.30 s	1.29 s	-0.4%
Published tarball (packed)	241.1 kB	241.3 kB	+0.1%
Published tarball (unpacked)	781.6 kB	782.3 kB	+0.1%
Files in tarball	99	99	0.0%

Interleaved runs on a shared runner: trust the deltas, not the absolute timings. The dev, restart and build suites run locally via pnpm bench:cli.

[codspeed]

Merging this PR will not alter performance

✅ 2 untouched benchmarks

---

_{Comparing iiio2:feat/upm (caafda3) with main (eabcb01)}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@eabcb01). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1583   +/-   ##
=======================================
  Coverage        ?   83.17%           
=======================================
  Files           ?      174           
  Lines           ?    11442           
  Branches        ?     3288           
=======================================
  Hits            ?     9517           
  Misses          ?     1625           
  Partials        ?      300           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[danielroe]

thank you 🙏

but we'll wait for support in package-manager-detector rather than reimplementing here

also, can i remind you that we have a policy that pr descriptions and comments should be written by a person and not an llm? ❤️

[iiio2]

I see. Ok. Thanks @danielroe