<!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 -->

Safe Dependency Upgrade

Systematically upgrade dependencies with zero breakage. Detects the project ecosystem, audits for outdated and vulnerable packages, presents a prioritized plan for approval, then executes upgrades one at a time with test verification after each.

Core principle: One upgrade at a time. Test after each. Roll back on failure. Never auto-commit.

Prerequisite check

Detect the project ecosystem by scanning for package manager files:

ls go.mod package.json pyproject.toml Cargo.toml *.csproj 2>/dev/null

If no package manager file is found, report to the user and stop. Mixed projects (e.g., Go backend + Node frontend) are supported — audit and upgrade each ecosystem separately.

Step 1: Audit dependencies

List outdated packages and run vulnerability scanners for each detected ecosystem.

Go:

go list -u -m all 2>/dev/null | grep '\['
govulncheck ./... 2>/dev/null

Node.js:

npm outdated 2>/dev/null
npm audit 2>/dev/null

Python:

pip list --outdated 2>/dev/null
pip-audit 2>/dev/null

Rust:

cargo outdated 2>/dev/null
cargo audit 2>/dev/null

.NET:

dotnet list package --outdated 2>/dev/null
dotnet list package --vulnerable 2>/dev/null

For detailed commands per ecosystem, see references/upgrade-commands.md.

If a vulnerability scanner is not installed, note it in the report but continue with the outdated package list.

Step 2: Categorize and prioritize

For each outdated package, assign a priority:

• CRITICAL — known CVE or security advisory
• HIGH — major version behind or dependency EOL
• MEDIUM — minor version behind
• LOW — patch version behind only

For detailed priority signals and breaking change assessment, see references/priority-matrix.md.

Step 3: Present upgrade plan

Present the prioritized list to the user before any upgrades. Use the plan format in references/report-template.md.

Dependency Upgrade Plan

Ecosystem: Go
Outdated: 5 packages
Vulnerable: 1 package

| # | Package           | Current | Target | Priority |
|---|-------------------|---------|--------|----------|
| 1 | example/vuln-pkg  | v1.2.0  | v1.2.5 | CRITICAL |
| 2 | example/old-pkg   | v2.0.0  | v4.1.0 | HIGH     |
| 3 | example/minor-pkg | v3.1.0  | v3.4.0 | MEDIUM   |

Proceed with upgrades?

Wait for user approval before proceeding. The user may choose to upgrade all, select specific packages, or skip.

Step 4: Upgrade one at a time

For each approved package, in priority order:

1. Research — check changelog or release notes for breaking changes. If crossing a major version, read the migration guide.
2. Upgrade — run the ecosystem-specific upgrade command
3. Update lockfile — go mod tidy, npm install, etc.
4. Run tests — execute the project's test suite
5. If tests pass — move to the next package
6. If tests fail — roll back this upgrade immediately:

# Rollback: restore dependency files from git
git checkout -- <dependency-file> <lockfile>

Report the failure (package, target version, test error) and continue with the remaining packages.

For ecosystem-specific upgrade and rollback commands, see references/upgrade-commands.md.

Step 5: Verify lockfiles

After all upgrades are complete, verify lockfile integrity:

# Go
go mod verify

# Node
npm ci --dry-run

# Rust
cargo build --dry-run

Confirm that lockfiles are updated and consistent with the dependency manifest.

Step 6: Present summary

Present the upgrade results using the template in references/report-template.md. Include:

1. Successfully upgraded — package, from version, to version, test status
2. Failed and rolled back — package, target version, failure reason
3. Skipped — package, reason (user chose to skip, or breaking change needs manual migration)
4. Remaining vulnerabilities — any CVEs not resolved
5. Lockfile status — updated and verified per ecosystem

Do not commit the changes. The user decides when and how to commit. Suggest a commit message:

deps: upgrade X packages (Y security fixes)

Important constraints

• Never auto-commit — upgrading packages changes files, but committing is the user's decision
• Never create branches — leave git operations to the user
• One at a time — upgrading multiple packages simultaneously makes it impossible to identify which upgrade broke tests
• Roll back immediately on failure — do not continue with a broken dependency state
• Report everything — even if the user chose to skip a package, include it in the summary with the reason