feat(pkg-intel): add package_vulnerabilities (pkg vulns + MCP)

[jlitola]

Summary

Adds the package_vulnerabilities MCP tool and githits pkg vulns CLI command behind the existing code_navigation capability gate. Both surfaces share a single request builder, envelope builder, and error classifier; a parity test asserts toEqual JSON across the two surfaces for every service-sourced fixture.

Surface

• githits pkg vulns <spec> — CLI listing known CVE / OSV advisories with severity, affected ranges, fix versions, and upgrade paths. Supports @version in the spec (unlike pkg info), plus --severity low|medium|high|critical (uppercase tolerated), --include-withdrawn, --verbose, --json.
• package_vulnerabilities — MCP tool with the same lean envelope. Permissive Zod schema, validation in-handler via buildPackageVulnerabilitiesParams. Advertised in the MCP server-level instructions under the package-tools section, gated on packageIntelligenceService.

The zero-vulns happy path renders as a single-line summary body (No known vulnerabilities.) to keep agent token usage minimal on the common case.

Design choices

• Server-side filtering. --severity maps to a CVSS float on the wire; --include-withdrawn passes through. The backend returns a filter-aware vulnerabilityCount, so summary.total reflects whatever survived the filter. No client-side filtering, no dual-summary block.
• Partitioning bySeverity buckets. Every returned advisory lands in exactly one of malware / critical / high / medium / low / unrated. The client-side guarantee is MALWARE + crit + high + medium + low + unrated = advisories.length, so the header breakdown always reconciles with the total — even on RUSTSEC / PYSEC where unbanded advisories are common.
• Canonical versions only. Tag-style refs with a leading v (e.g. v4.18.0) are rejected client-side with INVALID_ARGUMENT before the backend call. The v prefix is a git-tag convention, not a canonical version on any supported registry; proper ecosystem-aware version parsing belongs in the backend, not in ad hoc CLI normalisation rules.
• Typed VERSION_NOT_FOUND. When the backend emits extensions.code = "VERSION_NOT_FOUND" with structured fields, the classifier surfaces details: { package, requestedVersion, availableVersions[] }. The CLI terminal error expands this into package: / requested: / available: detail lines so users see the mistake and the alternatives. A narrow message-string fallback promotes generic BackendErrors with matching text to the typed error while the backend catches up; it's guarded to only fire when no graphqlCode is present, so real server faults never have their retryability flipped.
• Registry coverage. Only npm, PyPI, Hex, and Crates have vulnerability data. The other five known registries are rejected client-side with pkg vulns only supports npm, pypi, hex, and crates. Got: ${registry}. before the backend call.
• Malware marker. Advisories with isMalicious: true render with a red/bold MALWARE column (optionally combined as MALWARE · crit when both flags are set) and sort to the top of the advisory list regardless of CVSS score. The malware count in the breakdown line is always coloured red.
• Shared helper scope. The envelope builder is shared between CLI --json and MCP content[0].text; the terminal formatter is CLI-only (MCP always emits JSON). Documented in mcp-cli-parity.md.

Terminal UX refinements

• latest affected is the only yellow token in the summary line; latest clean stays plain so it doesn't read as a caution.
• Unrated advisories render with a dim unrated label in the severity gutter rather than an empty column.
• Affected-range lists adapt to terminal width: 4 entries on narrow (≤119 cols), 6 on standard-wide (120–159), 8 on ultrawide (≥160). The remainder collapses into a dim … (+N more; use -v) hint. Verbose shows every range. JSON is never truncated — machine consumers get the full list.
• Upgrade options are de-duplicated and sorted ascending by semver-ish comparison (pre-releases rank below their matching base release), so the footer presents the minimum-churn upgrade first.
• Literal No summary available placeholders from upstream are stripped from both the JSON envelope and the terminal row — absence of summary is the signal.

Tests

• bun test — 810 pass, 0 fail, 1784 expect() calls.
• bun run typecheck / bun run build / bun run lint — clean.
• Parity fixtures: happy, zero-vulns, filtered success, versioned-match, v-prefixed (rejected client-side), versioned real-diff, NOT_FOUND, VERSION_NOT_FOUND with structured details, BACKEND_ERROR, plus INVALID_ARGUMENT fixtures for unsupported registry and invalid severity label.
• Live-verified against production pkgseer across npm, PyPI, Crates, Hex, scoped-npm, and MCP stdio.

Test plan

• bun test passes
• bun run typecheck clean
• bun run build clean
• bun run lint clean
• pkg vulns scenarios smoked against a token with code_navigation capability (happy, zero-vulns, version pin, malware fixture, severity filter, withdrawn toggle, tag-style rejection, scoped-npm name, registry rejection)
• MCP tools/list shows package_vulnerabilities under an open-gate token, absent under a gate-closed token
• MCP server-level instructions include the package_vulnerabilities bullet under an open-gate token
• pkg vulns --help renders under an open-gate token