# formulas/upgrade-dependency.toml — Upgrade a package dependency

name        = "upgrade-dependency"
description = "Upgrade {{package}} to {{to_version}}"
version     = 1

[vars.package]
description = "Package name to upgrade (e.g. viem, serde, forge-std)"
required    = true

[vars.ecosystem]
description = "Package ecosystem: npm, cargo, or forge"
required    = true

[vars.from_version]
description = "Current version (e.g. 1.2.3) — used for changelog lookup"
required    = false
default     = "current"

[vars.to_version]
description = "Target version (e.g. 2.0.0) — leave blank for latest"
required    = false
default     = "latest"

[[steps]]
id          = "check-current"
title       = "Check current {{package}} version and changelog"
description = """
Identify the installed version of {{package}} in the lockfile or manifest.
Look up the changelog or release notes between {{from_version}} and {{to_version}}.
Note any breaking changes, deprecations, or migration steps required.
"""

[[steps]]
id          = "upgrade"
title       = "Run upgrade for {{ecosystem}}"
description = """
Run the appropriate upgrade command for ecosystem={{ecosystem}}:

- npm:   npm install {{package}}@{{to_version}} (or @latest)
- cargo: cargo update -p {{package}} [--precise {{to_version}}]
         Or bump version in Cargo.toml, then: cargo build
- forge: forge update {{package}}
         (Use forge install only if reinstalling from scratch after manually
          editing the commit hash in .gitmodules or lib/)

Confirm the lockfile / manifest now reflects {{to_version}}.
"""
needs       = ["check-current"]

[[steps]]
id          = "fix-breaking-changes"
title       = "Apply migration steps for breaking changes"
description = """
Based on the changelog reviewed in check-current, apply any required changes:
- Rename renamed APIs or types
- Update import paths if they moved
- Adjust call sites for signature changes
- Remove usage of deprecated symbols

If no breaking changes were noted, verify a quick build still passes.
"""
needs       = ["upgrade"]

[[steps]]
id          = "run-tests"
title       = "Run tests and verify"
description = """
Run the full test suite appropriate for ecosystem={{ecosystem}}:

- npm:   npm test (or the project's test script)
- cargo: cargo test
- forge: forge test

Confirm all tests pass. Fix any compilation errors or test failures introduced
by the upgrade before declaring this done.
"""
needs       = ["fix-breaking-changes"]