fix(upgrade): improve CLI usability for monorepos and CI

[jacekradko]

Summary

• Parent directory traversal for package manager detection: detectPackageManager() now walks up the directory tree to find lockfiles and the packageManager field in package.json (Corepack), fixing detection in monorepo subdirectories
• pnpm workspace root -w flag: getInstallCommand() and getUninstallCommand() automatically add -w when the target directory contains pnpm-workspace.yaml, preventing "Running this command will add the dependency to the workspace root" errors
• Resolve catalog: protocol versions: getSdkVersion() now resolves catalog: version specifiers by parsing pnpm-workspace.yaml catalogs, enabling automatic version detection without requiring --release
• Actionable non-interactive error messages: SDK detection and version detection failures now include complete example commands showing the exact flags needed
• Codemod error file-level reporting: Passes verbose: 0 to jscodeshift so error-level logging (file paths + error messages) is printed instead of being swallowed; uses spinner.error() when errors occur

Test plan

• All 246 tests pass (15 new tests added)
• pnpm build succeeds
• Manual test: run npx @clerk/upgrade --sdk=nextjs --dir=<monorepo-subdirectory> and verify package manager is detected from parent
• Manual test: run in a project using catalog: protocol and verify version is resolved
• Manual test: run in non-interactive mode without --sdk and verify error shows example command

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for resolving dependency versions from pnpm workspace catalogs

• Improvements

  • Enhanced package manager detection to recognize workspace roots and traverse directory trees
  • CLI now provides actionable example commands when SDK or version detection fails in CI environments
  • Improved codemod error reporting with more granular success/error distinction

[changeset-bot]

⚠️ No Changeset found

Latest commit: 90a9822

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Skipped		Feb 18, 2026 3:23am

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7874

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7874

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7874

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7874

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7874

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7874

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7874

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7874

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7874

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7874

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@7874

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7874

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7874

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7874

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7874

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7874

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7874

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7874

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7874

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7874

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7874

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7874

commit: 90a9822

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

This pull request enhances the Clerk upgrade tool to support pnpm catalog dependency resolution and improves user guidance. Key changes include: adding test fixtures for Next.js with catalog dependencies; implementing catalog version resolution by parsing pnpm-workspace.yaml files; enhancing package manager detection to traverse parent directories and support pnpm workspaces with -w flag handling; updating CLI error messages with actionable examples for non-interactive mode; refining codemod result reporting to distinguish error and success states; and expanding test coverage for new functionality across SDK detection and CLI scenarios.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'fix(upgrade): improve CLI usability for monorepos and CI' directly reflects the main objectives: enhanced package manager detection, workspace handling, and better error messaging for both monorepo and CI scenarios.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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