upgrade-packages

name	upgrade-packages
description	Upgrades all project dependencies to latest compatible versions. Use when the user says "upgrade packages", "update deps", "bump dependencies", or "upgrade dependencies".
argument-hint	[--check-only] [--major] [specific-package-name]

Upgrade Packages

Upgrade all project dependencies to their latest compatible versions across all languages in the repo.

Arguments

• --check-only — List outdated packages without upgrading. Stop after Step 2.
• --major — Include major version bumps (breaking changes). Without this flag, stay within semver-compatible ranges.
• Any other argument is treated as a specific package name to upgrade (instead of all packages).

Step 1 — Detect Package Managers

Scan the repo for these package ecosystems:

Marker File	Ecosystem	Location
Cargo.toml (workspace)	Rust (cargo)	Repo root
package.json / package-lock.json	Node.js (npm)	src/editors/vscode/
*.csproj / *.fsproj / .config/dotnet/common.props	C#/F# (.NET / NuGet)	src/sidecars/SharpLsp.Sidecars.sln

Step 2 — List Outdated Packages

Run the appropriate command to list what's outdated BEFORE upgrading anything. Show the user what will change.

Rust (cargo)

cargo outdated --root-deps-only --workspace
cargo update --dry-run

If cargo-outdated is not installed: cargo install cargo-outdated

Read the docs: https://doc.rust-lang.org/cargo/commands/cargo-update.html

Node.js (npm)

npm outdated --prefix src/editors/vscode

Read the docs: https://docs.npmjs.com/cli/v10/commands/npm-update

C#/.NET (NuGet)

dotnet list src/sidecars/SharpLsp.Sidecars.sln package --outdated

For transitive dependencies too: dotnet list src/sidecars/SharpLsp.Sidecars.sln package --outdated --include-transitive

Read the docs: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-list-package

If --check-only was passed, stop here and report the outdated list.

Step 3 — Read the official upgrade docs

Before running any upgrade command, you MUST fetch and read the official documentation URL listed above for the detected package manager. Use WebFetch to retrieve the page. This ensures you use the correct flags and understand the behavior. Do not guess at flags or options from memory.

For any package with a major version bump (when --major is passed), also check the package's changelog or release notes for breaking changes before upgrading.

Step 4 — Run Upgrades

If a specific package name was given as an argument, upgrade only that package.

Rust

cargo update                          # semver-compatible updates
# --major flag:
cargo update --breaking               # major version bumps (cargo 1.84+)

For workspace members, run from workspace root.

Node.js (npm)

npm update --prefix src/editors/vscode                        # semver-compatible
# --major flag:
npx npm-check-updates -u --packageFile src/editors/vscode/package.json && npm install --prefix src/editors/vscode

C#/.NET (NuGet)

dotnet outdated --upgrade src/sidecars/SharpLsp.Sidecars.sln

If dotnet-outdated tool is not installed: dotnet tool install -g dotnet-outdated-tool

Read the docs: https://github.com/dotnet-outdated/dotnet-outdated

Shared NuGet package versions live in .config/dotnet/common.props — check there first and update centrally when possible, rather than editing individual .csproj/.fsproj files.

Step 5 — Verify the upgrade

After upgrading, run the full CI pipeline:

make ci

If tests fail:

1. Read the failure output carefully
2. Check the changelog / migration guide for the upgraded packages (fetch the release notes URL if available)
3. Fix breaking changes in the code
4. Re-run make ci
5. If stuck after 3 attempts on the same failure, report it to the user with the error details and the package that caused it

Step 6 — Report

Provide a summary:

• Packages upgraded (old version -> new version)
• Packages skipped (and why, e.g., major version bump without --major flag)
• Build/test result after upgrade
• Any breaking changes that were fixed
• Any packages that could not be upgraded (with error details)

Rules

• Always list outdated packages first before upgrading anything
• Always read the official docs for the package manager before running upgrade commands
• Always run make ci after upgrading to catch breakage immediately
• Never remove packages unless they were explicitly deprecated and replaced
• Never downgrade packages unless rolling back a broken upgrade
• Never modify lockfiles manually (Cargo.lock, package-lock.json) — let the package manager regenerate them
• Keep Cargo.lock changes in the same commit as Cargo.toml changes
• Keep package-lock.json changes in the same commit as package.json changes
• .config/dotnet/common.props is the source of truth for shared .NET package versions — update there first
• If stuck after 3 attempts, revert and report — do not loop forever
• Commit nothing — leave changes in the working tree for the user to review