Add find_parent_version tool for minimum upgrade-path lookup

[christian-andersson]

Summary

Adds a new find_parent_version MCP tool that answers a single hop of the "minimum upgrade path" question: given chain A -> B -> C -> D and a target D@x.y.z, what is the lowest version of C whose declared range for D includes x.y.z? Callers chain the tool to walk a full upgrade plan.

The motivating use case is dependency systems that pin transitives via the lockfile (Deno, Go modules). In those ecosystems there is no overrides / resolutions escape hatch — updating a transitive D requires lifting every parent in the chain that brought it in. This tool computes the minimal lift one hop at a time, and downstream tooling owns the actual lockfile rewrite or install step.

What landed:

• find_parent_version tool (src/tools/find-parent-version.ts): input { parent: {registry, name}, child: {registry, name}, childVersion, fromParentVersion?, includePrerelease? }. Walks parent versions ascending, returns the first one whose declared range covers childVersion. Status field: found / none-compatible / child-never-declared / error. The algorithm itself is factored into a pure scanForCompatibleParentVersion helper so tests stay offline.
• Registry-client extensions: optional getVersionDependencies(name, version) on RegistryClient. Implemented for npm (reads from the existing cached metadata response — zero extra HTTP calls) and JSR (calls the per-version /dependencies endpoint, which already tags each dep with kind: "jsr"|"npm"). Both return VersionDependency[] with { name, registry, constraint, scope }. npm includes runtime, peer, and optional deps but skips dev — those don't ship.
• Rate-limit handling: a new fetchWithRetry helper in src/utils/http.ts that honors HTTP 429 Retry-After (delta-seconds and HTTP-date forms) with exponential-backoff fallback, capped at 60s with 3 retries by default. Used only on the JSR per-version deps endpoint, since that is the only call site the scan loop can amplify — every other registry fetch in the codebase is one-shot and cached. parseRetryAfter is exported as a pure helper for testability.

Supported registries: npm and JSR as parent. Child can live on either npm or JSR (since JSR packages can declare npm transitives).

Out of scope: multi-hop chain walks (callers chain the single-hop tool themselves), the actual lockfile rewrite or install step, and non-Deno/Go ecosystems where the question is moot because overrides/resolutions exists.

Test plan

• deno fmt --check && deno lint && deno check main.ts && deno test --allow-net --allow-read — all four CI gates pass (206 tests, 12 new).
• From an MCP client, call find_parent_version with a known JSR chain and confirm the result matches manual inspection of the dependency list on jsr.io.
• Same against an npm parent (e.g. a library whose dependencies.foo range tightened in a known release) and confirm the minimum version reported matches the npm changelog.
• Exercise fromParentVersion to confirm it narrows the scan window and produces the expected versionsConsidered count.
• Optional: hammer the JSR endpoint enough to trip a 429 and confirm the retry handler honors Retry-After.

🤖 Generated with Claude Code