@4da/mcp-server 6.1.0 → 6.2.0

package/dist/live/upgrade-go.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Go modules for `upgrade_impact`, from the module proxy (proxy.golang.org):
+ * `/@v/list` for the tagged versions, `/@v/<version>.info` for a release's
+ * time and VCS origin, and `/@v/<version>.zip` as the archive a changelog is
+ * read from (the zip holds the module's files under `<module>@<version>/`).
+ *
+ * Major versions 2 and up are DIFFERENT modules: `github.com/jackc/pgx/v5`
+ * is not a newer release of `github.com/jackc/pgx/v4`, and the proxy lists
+ * each path's own versions only. `goMajorPath` gives the path a major lives
+ * at, so an upgrade across majors is read from the target module and the
+ * report can say that every import path changes.
+ *
+ * `.info` carries `Origin` (VCS URL, the tag's ref, the module's subdirectory
+ * in a multi-module repository) for versions the proxy fetched recently.
+ * That, not a guess from the import path, names the GitHub repository and tag
+ * for the opt-in release-notes fallback: `go.uber.org/zap` lives at
+ * github.com/uber-go/zap, and aws-sdk-go-v2's `service/s3` tags its releases
+ * `service/s3/v1.50.0`.
+ */
+const GO_PROXY = "https://proxy.golang.org";
+const GO_TIMEOUT_MS = 15_000;
+/** `.info` reads per call: one per release crossed, newest first, then dates are left null. */
+const MAX_INFO_READS = 40;
+/** A module path: a dotted host, then path elements (case kept; the proxy escapes capitals). */
+export const GO_MODULE = /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}(?:\/[A-Za-z0-9._~+-]+)+$|^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/;
+/** Proxy escaping: each capital letter becomes `!` + lowercase. */
+export function escapeGoPath(path) {
+    return path.replace(/[A-Z]/g, (c) => `!${c.toLowerCase()}`);
+}
+/** The major version a module path carries: `/v5` -> 5, `gopkg.in/yaml.v3` -> 3, none -> null (0 or 1). */
+export function goPathMajor(path) {
+    const m = /\/v(\d+)$/.exec(path) ?? (/^gopkg\.in\//.test(path) ? /\.v(\d+)$/.exec(path) : null);
+    return m ? Number(m[1]) : null;
+}
+/** The module path without its major suffix. */
+export function goBasePath(path) {
+    if (/^gopkg\.in\//.test(path))
+        return path.replace(/\.v\d+$/, "");
+    return path.replace(/\/v\d+$/, "");
+}
+/** The path major `major` lives at: none for 0 and 1, `/vN` (or gopkg.in's `.vN`) from 2. */
+export function goMajorPath(path, major) {
+    const base = goBasePath(path);
+    if (/^gopkg\.in\//.test(path))
+        return `${base}.v${major}`;
+    return major >= 2 ? `${base}/v${major}` : base;
+}
+export function goVersionMajor(version) {
+    const m = /^v?(\d+)\./.exec(version.trim());
+    return m ? Number(m[1]) : null;
+}
+/** GitHub repository from a module path: `github.com/<owner>/<repo>/...`. */
+export function githubRepoOfGoPath(path) {
+    const m = /^github\.com\/([\w.-]+)\/([\w.-]+)/.exec(path);
+    return m ? `https://github.com/${m[1]}/${m[2]}` : null;
+}
+export async function goInfo(net, module, version) {
+    const res = await net.fetch(`${GO_PROXY}/${escapeGoPath(module)}/@v/${escapeGoPath(version)}.info`, {}, GO_TIMEOUT_MS);
+    if (!res.ok)
+        return null;
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadGoIndex(net, module) {
+    const base = `${GO_PROXY}/${escapeGoPath(module)}/@v/list`;
+    const res = await net.fetch(base, {}, GO_TIMEOUT_MS);
+    // The proxy answers 404 and 410 for a path it cannot resolve.
+    if (res.status === 404 || res.status === 410)
+        return null;
+    if (!res.ok)
+        throw new Error(`Go module proxy HTTP ${res.status} for ${module}`);
+    const listed = (await res.text())
+        .split("\n")
+        .map((v) => v.trim())
+        .filter((v) => /^v\d+\.\d+\.\d+/.test(v));
+    let versions = listed.map((version) => ({ version, published: null }));
+    if (versions.length === 0) {
+        // An untagged module: the proxy's @latest is a pseudo-version.
+        const latest = await net.fetch(`${GO_PROXY}/${escapeGoPath(module)}/@latest`, {}, GO_TIMEOUT_MS);
+        if (!latest.ok)
+            return null;
+        const info = (await latest.json());
+        if (!info.Version)
+            return null;
+        versions = [{ version: info.Version, published: info.Time ?? null }];
+    }
+    return { name: module, ecosystem: "Go", versions, repository: githubRepoOfGoPath(module) };
+}
+/**
+ * Publish times for the versions an upgrade crosses (newest first, at most
+ * MAX_INFO_READS), and the target's VCS origin. Missing `.info` leaves a null date.
+ */
+export async function enrichGoVersions(net, module, versions, target, budget = MAX_INFO_READS) {
+    const rest = [...versions].reverse().filter((v) => v !== target && !v.published);
+    const wanted = (target ? [target, ...rest] : rest).slice(0, budget);
+    let origin = null;
+    await Promise.all(wanted.map(async (v) => {
+        const info = await goInfo(net, module, v.version).catch(() => null);
+        if (info?.Time && !v.published)
+            v.published = info.Time;
+        if (v === target && info?.Origin)
+            origin = info.Origin;
+    }));
+    return { origin };
+}
+/**
+ * The tag prefix a module's releases carry: `service/s3` for
+ * `refs/tags/service/s3/v1.50.0`, "" for a module at the repository root.
+ * From the proxy's recorded ref when there is one; otherwise from a
+ * github.com path (the elements after owner/repo, minus a `/vN` suffix,
+ * which a major-version subdirectory does not put in its tags).
+ */
+export function goTagPrefix(module, version, origin) {
+    const ref = origin?.Ref?.replace(/^refs\/tags\//, "");
+    if (ref && ref.endsWith(version))
+        return ref.slice(0, ref.length - version.length).replace(/\/$/, "");
+    if (origin?.Subdir !== undefined)
+        return origin.Subdir.replace(/(?:^|\/)v\d+$/, "");
+    const m = /^github\.com\/[\w.-]+\/[\w.-]+\/(.+)$/.exec(goBasePath(module));
+    return m ? m[1] : "";
+}
+/** The proxy's zip of one module version. */
+export function goZipUrl(module, version) {
+    return `${GO_PROXY}/${escapeGoPath(module)}/@v/${escapeGoPath(version)}.zip`;
+}

package/dist/live/upgrade-pypi.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PyPI for `upgrade_impact`: the version index from the PyPI JSON API
+ * (`https://pypi.org/pypi/<name>/json`), each release's sdist as the archive
+ * its changelog is read from (files.pythonhosted.org, PyPI's own file host),
+ * and the links the project itself publishes in `project_urls`.
+ *
+ * Versions are PEP 440, not semver (`2.0`, `3.0.0rc1`, `1.0.post1`), so they
+ * are ordered with version-compare.ts's PEP 440 comparator. A release's
+ * publish time is its earliest file upload; it is yanked when every file is.
+ *
+ * `project_urls` is metadata, not a changelog: a "Changelog" link usually
+ * points at an HTML docs page this server does not parse (it is reported as
+ * the release-notes URL). Only a link to a raw changelog FILE on GitHub can be
+ * read, and only when the GitHub fallback is enabled (github-releases.ts).
+ */
+import type { RegistryIndex, UpgradeNet } from "./upgrade-sources.js";
+interface PyPIFile {
+    url?: string;
+    packagetype?: string;
+    filename?: string;
+    upload_time_iso_8601?: string;
+    yanked?: boolean;
+    yanked_reason?: string | null;
+}
+interface PyPIProject {
+    info?: {
+        name?: string;
+        home_page?: string | null;
+        project_urls?: Record<string, string> | null;
+    };
+    releases?: Record<string, PyPIFile[]>;
+}
+/** PEP 503 normalised name: lowercase, runs of `-`, `_`, `.` read as one `-`. */
+export declare function normalizePypiName(name: string): string;
+/** PEP 508 distribution name. */
+export declare const PYPI_NAME: RegExp;
+/** The project's source repository from `project_urls` / `home_page`: a GitHub URL first, then any https one. */
+export declare function pypiRepository(info: PyPIProject["info"]): string | null;
+/** Links the project labels as its changelog / release notes, in `project_urls` order. */
+export declare function pypiChangelogLinks(info: PyPIProject["info"]): string[];
+export declare function loadPypiIndex(net: UpgradeNet, name: string): Promise<RegistryIndex | null>;
+export {};

package/dist/live/upgrade-pypi.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * PyPI for `upgrade_impact`: the version index from the PyPI JSON API
+ * (`https://pypi.org/pypi/<name>/json`), each release's sdist as the archive
+ * its changelog is read from (files.pythonhosted.org, PyPI's own file host),
+ * and the links the project itself publishes in `project_urls`.
+ *
+ * Versions are PEP 440, not semver (`2.0`, `3.0.0rc1`, `1.0.post1`), so they
+ * are ordered with version-compare.ts's PEP 440 comparator. A release's
+ * publish time is its earliest file upload; it is yanked when every file is.
+ *
+ * `project_urls` is metadata, not a changelog: a "Changelog" link usually
+ * points at an HTML docs page this server does not parse (it is reported as
+ * the release-notes URL). Only a link to a raw changelog FILE on GitHub can be
+ * read, and only when the GitHub fallback is enabled (github-releases.ts).
+ */
+import { parsePep440 } from "./version-compare.js";
+const PYPI_TIMEOUT_MS = 30_000;
+/** PEP 503 normalised name: lowercase, runs of `-`, `_`, `.` read as one `-`. */
+export function normalizePypiName(name) {
+    return name.toLowerCase().replace(/[-_.]+/g, "-");
+}
+/** PEP 508 distribution name. */
+export const PYPI_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,198}[A-Za-z0-9])?$/;
+/** The sdist to read a changelog from: a `.tar.gz` first, then a `.zip`. */
+function pickSdist(files) {
+    const sdists = files.filter((f) => f.packagetype === "sdist" && typeof f.url === "string");
+    return (sdists.find((f) => /\.tar\.gz$/i.test(f.url)) ?? sdists.find((f) => /\.zip$/i.test(f.url)))?.url;
+}
+const REPO_KEY = /^(?:source(?: code)?|repository|repo|code|github|git|homepage|home|project)$/i;
+const CHANGELOG_KEY = /change ?log|changes|release ?notes|releases|history|news|what'?s ?new/i;
+/** The project's source repository from `project_urls` / `home_page`: a GitHub URL first, then any https one. */
+export function pypiRepository(info) {
+    const urls = Object.entries(info?.project_urls ?? {}).filter(([, v]) => typeof v === "string");
+    const github = (v) => /^https?:\/\/(?:www\.)?github\.com\/[\w.-]+\/[\w.-]+/i.test(v);
+    const keyed = urls.filter(([k]) => REPO_KEY.test(k.trim()));
+    const pick = keyed.find(([, v]) => github(v))?.[1] ??
+        urls.find(([, v]) => github(v))?.[1] ??
+        (info?.home_page && github(info.home_page) ? info.home_page : null) ??
+        keyed.find(([, v]) => /^https:\/\//i.test(v))?.[1] ??
+        null;
+    return pick;
+}
+/** Links the project labels as its changelog / release notes, in `project_urls` order. */
+export function pypiChangelogLinks(info) {
+    return Object.entries(info?.project_urls ?? {})
+        .filter(([k, v]) => typeof v === "string" && CHANGELOG_KEY.test(k) && /^https:\/\//i.test(v))
+        .map(([, v]) => v);
+}
+export async function loadPypiIndex(net, name) {
+    const url = `https://pypi.org/pypi/${encodeURIComponent(normalizePypiName(name))}/json`;
+    const res = await net.fetch(url, { headers: { Accept: "application/json" } }, PYPI_TIMEOUT_MS);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`PyPI HTTP ${res.status} for ${name}`);
+    const doc = (await res.json());
+    if (!doc.releases || typeof doc.releases !== "object")
+        throw new Error(`PyPI returned no release list for ${name}`);
+    const versions = [];
+    for (const [version, files] of Object.entries(doc.releases)) {
+        if (!parsePep440(version))
+            continue;
+        const list = Array.isArray(files) ? files : [];
+        const times = list.map((f) => f.upload_time_iso_8601).filter((t) => typeof t === "string").sort();
+        const entry = { version, published: times[0] ?? null };
+        if (list.length > 0 && list.every((f) => f.yanked)) {
+            entry.yanked = true;
+            const reason = list.find((f) => f.yanked_reason)?.yanked_reason;
+            if (reason)
+                entry.deprecated = `yanked: ${reason}`;
+        }
+        const sdist = pickSdist(list);
+        if (sdist)
+            entry.tarball = sdist;
+        versions.push(entry);
+    }
+    return {
+        name: doc.info?.name ?? name,
+        ecosystem: "PyPI",
+        versions,
+        repository: pypiRepository(doc.info),
+        changelogLinks: pypiChangelogLinks(doc.info),
+    };
+}

package/dist/live/upgrade-sources.d.ts

@@ -2,14 +2,16 @@
  * Network sources for `upgrade_impact`: registry version index, the target
  * version's changelog (read from its registry archive) and OSV advisories.
  *
- * Privacy rule (Decision 1, option A): the only hosts contacted are the
- * package's own registry (registry.npmjs.org; crates.io + static.crates.io)
- * and api.osv.dev. A changelog is never fetched from GitHub or a docs site,
- * even when the archive ships none — the report then hands the agent a
- * `release_notes_url` built from registry metadata, and the agent decides
- * whether to fetch it. Every request goes through `UpgradeNet`, which records
- * the host so `_meta.sources` is a fact, not a claim, and which tests replace
- * with a fake fetch.
+ * Privacy rule (Decision 1, option A): by default the only hosts contacted
+ * are the package's own registry (registry.npmjs.org; crates.io +
+ * static.crates.io; pypi.org + files.pythonhosted.org; proxy.golang.org) and
+ * api.osv.dev. A changelog is read from GitHub only when the user opts in
+ * (Decision 1, option B: FOURDA_GITHUB_CHANGELOG, github-releases.ts) and the
+ * archive has none for the range; otherwise the report hands the agent a
+ * `release_notes_url` built from registry metadata and says how to enable the
+ * fallback. Every request goes through `UpgradeNet`, which records the host
+ * so `_meta.sources` is a fact, not a claim, and which tests replace with a
+ * fake fetch.
  *
  * Request budget per call: index (1) + archive (1) + OSV for from/to (2) = 4,
  * each cached (index 6 h, parsed changelog 7 d, OSV 1 h). The npm packument
@@ -17,8 +19,17 @@
  * is cached — never the raw document.
  */
 import { type FetchFn } from "./package-archive.js";
-import { type ChangelogSection } from "./changelog.js";
-export type UpgradeEcosystem = "npm" | "crates.io";
+import { type ChangelogSection, type VersionOrder } from "./changelog.js";
+export type UpgradeEcosystem = "npm" | "crates.io" | "PyPI" | "Go";
+export declare const UPGRADE_ECOSYSTEMS: readonly UpgradeEcosystem[];
+/** Version order for an ecosystem: semver precedence (npm, crates.io, Go without its `v`), PEP 440 (PyPI). Null = unreadable. */
+export declare function versionOrder(ecosystem: UpgradeEcosystem): VersionOrder;
+/** Readable as a version in this ecosystem. */
+export declare function isReadableVersion(version: string, ecosystem: UpgradeEcosystem): boolean;
+/** A prerelease in this ecosystem's own terms (PEP 440 `a`/`b`/`rc`/`.dev`; semver `-x`; a Go pseudo-version). */
+export declare function isPrerelease(version: string, ecosystem: UpgradeEcosystem): boolean;
+/** Package-name identity: crates.io folds `-`/`_`, PyPI normalises per PEP 503, npm and Go are exact. */
+export declare function sameUpgradeName(a: string, b: string, ecosystem: string): boolean;
 /** crates.io refuses API requests without a descriptive User-Agent. */
 export declare const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
 export interface PublishedVersion {
@@ -26,7 +37,7 @@ export interface PublishedVersion {
     published: string | null;
     deprecated?: string;
     yanked?: boolean;
-    /** Archive URL (npm `dist.tarball`); crates archives are derived from name + version. */
+    /** Archive URL (npm `dist.tarball`, PyPI sdist); crates and Go archives are derived from name + version. */
     tarball?: string;
 }
 export interface RegistryIndex {
@@ -35,12 +46,18 @@ export interface RegistryIndex {
     ecosystem: UpgradeEcosystem;
     versions: PublishedVersion[];
     repository: string | null;
+    /** Links the project itself labels as its changelog (PyPI `project_urls`). */
+    changelogLinks?: string[];
 }
 export interface ChangelogResult {
     found: boolean;
     file?: string;
     sections?: ChangelogSection[];
     reason?: string;
+    /** Where the sections came from: the registry archive (default), or the opt-in GitHub fallback. */
+    source?: "archive" | "github-releases" | "github-file";
+    /** The page or API the GitHub fallback read. */
+    url?: string;
 }
 /** The cache surface used here; `LiveCache` satisfies it. */
 export interface UpgradeCache {

package/dist/live/upgrade-sources.js

@@ -3,14 +3,16 @@
  * Network sources for `upgrade_impact`: registry version index, the target
  * version's changelog (read from its registry archive) and OSV advisories.
  *
- * Privacy rule (Decision 1, option A): the only hosts contacted are the
- * package's own registry (registry.npmjs.org; crates.io + static.crates.io)
- * and api.osv.dev. A changelog is never fetched from GitHub or a docs site,
- * even when the archive ships none — the report then hands the agent a
- * `release_notes_url` built from registry metadata, and the agent decides
- * whether to fetch it. Every request goes through `UpgradeNet`, which records
- * the host so `_meta.sources` is a fact, not a claim, and which tests replace
- * with a fake fetch.
+ * Privacy rule (Decision 1, option A): by default the only hosts contacted
+ * are the package's own registry (registry.npmjs.org; crates.io +
+ * static.crates.io; pypi.org + files.pythonhosted.org; proxy.golang.org) and
+ * api.osv.dev. A changelog is read from GitHub only when the user opts in
+ * (Decision 1, option B: FOURDA_GITHUB_CHANGELOG, github-releases.ts) and the
+ * archive has none for the range; otherwise the report hands the agent a
+ * `release_notes_url` built from registry metadata and says how to enable the
+ * fallback. Every request goes through `UpgradeNet`, which records the host
+ * so `_meta.sources` is a fact, not a claim, and which tests replace with a
+ * fake fetch.
  *
  * Request budget per call: index (1) + archive (1) + OSV for from/to (2) = 4,
  * each cached (index 6 h, parsed changelog 7 d, OSV 1 h). The npm packument
@@ -18,8 +20,40 @@
  * is cached — never the raw document.
  */
 import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
-import { ArchiveError, defaultFetch, fetchArchiveRootFiles } from "./package-archive.js";
+import { ArchiveError, defaultFetch, fetchArchiveBytes, readRootTextFiles } from "./package-archive.js";
 import { CHANGELOG_PARSER_VERSION, findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
+import { compareVersions, isComparable } from "./version-compare.js";
+import { isPrereleaseVersion } from "./osv-ranges.js";
+import { looksLikeZip, readZipRootTextFiles } from "./zip-archive.js";
+import { loadPypiIndex, normalizePypiName, PYPI_NAME } from "./upgrade-pypi.js";
+import { GO_MODULE, goZipUrl, loadGoIndex } from "./upgrade-go.js";
+export const UPGRADE_ECOSYSTEMS = ["npm", "crates.io", "PyPI", "Go"];
+/** Version order for an ecosystem: semver precedence (npm, crates.io, Go without its `v`), PEP 440 (PyPI). Null = unreadable. */
+export function versionOrder(ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return compareVersionPrecedence;
+    return (a, b) => (isComparable(a, ecosystem) && isComparable(b, ecosystem) ? compareVersions(a, b, ecosystem) : null);
+}
+/** Readable as a version in this ecosystem. */
+export function isReadableVersion(version, ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return parseSemverPrecedence(version) !== null;
+    return version !== "0" && isComparable(version, ecosystem);
+}
+/** A prerelease in this ecosystem's own terms (PEP 440 `a`/`b`/`rc`/`.dev`; semver `-x`; a Go pseudo-version). */
+export function isPrerelease(version, ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return (parseSemverPrecedence(version)?.prerelease.length ?? 0) > 0;
+    return isPrereleaseVersion(version, ecosystem);
+}
+/** Package-name identity: crates.io folds `-`/`_`, PyPI normalises per PEP 503, npm and Go are exact. */
+export function sameUpgradeName(a, b, ecosystem) {
+    if (ecosystem === "crates.io")
+        return a.replace(/-/g, "_") === b.replace(/-/g, "_");
+    if (ecosystem === "PyPI")
+        return normalizePypiName(a) === normalizePypiName(b);
+    return a === b;
+}
 /** crates.io refuses API requests without a descriptive User-Agent. */
 export const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
 const INDEX_TTL = 6 * 3600;
@@ -42,7 +76,16 @@ export function createUpgradeNet(cache, fetchFn = defaultFetch) {
 const NPM_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
 const CRATE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 export function isValidPackageName(name, ecosystem) {
-    return ecosystem === "npm" ? NPM_NAME.test(name) && name.length <= 214 : CRATE_NAME.test(name);
+    switch (ecosystem) {
+        case "npm":
+            return NPM_NAME.test(name) && name.length <= 214;
+        case "crates.io":
+            return CRATE_NAME.test(name);
+        case "PyPI":
+            return PYPI_NAME.test(name);
+        case "Go":
+            return GO_MODULE.test(name) && name.length <= 300 && !name.split("/").some((p) => p === "." || p === "..");
+    }
 }
 async function cached(net, key, ttl, load) {
     const hit = net.cache?.get(key);
@@ -99,21 +142,36 @@ async function loadCratesIndex(net, name) {
 }
 /** Registry index with versions in ascending precedence order (unreadable versions dropped). Null = unknown package. */
 export async function getRegistryIndex(net, ecosystem, name) {
-    const key = `upgrade-impact:index:${ecosystem}:${ecosystem === "crates.io" ? name.replace(/-/g, "_") : name}`;
-    const index = await cached(net, key, INDEX_TTL, () => ecosystem === "npm" ? loadNpmIndex(net, name) : loadCratesIndex(net, name));
+    const keyName = ecosystem === "crates.io" ? name.replace(/-/g, "_") : ecosystem === "PyPI" ? normalizePypiName(name) : name;
+    const key = `upgrade-impact:index:${ecosystem}:${keyName}`;
+    const index = await cached(net, key, INDEX_TTL, () => {
+        switch (ecosystem) {
+            case "npm":
+                return loadNpmIndex(net, name);
+            case "crates.io":
+                return loadCratesIndex(net, name);
+            case "PyPI":
+                return loadPypiIndex(net, name);
+            case "Go":
+                return loadGoIndex(net, name);
+        }
+    });
     if (!index)
         return null;
+    const order = versionOrder(ecosystem);
     const versions = index.versions
-        .filter((v) => parseSemverPrecedence(v.version) !== null)
-        .sort((a, b) => compareVersionPrecedence(a.version, b.version) ?? 0);
+        .filter((v) => isReadableVersion(v.version, ecosystem))
+        .sort((a, b) => order(a.version, b.version) ?? 0);
     return { ...index, versions };
 }
-const ARCHIVE_HOSTS = new Set(["registry.npmjs.org", "static.crates.io"]);
+const ARCHIVE_HOSTS = new Set(["registry.npmjs.org", "static.crates.io", "files.pythonhosted.org", "proxy.golang.org"]);
 /** The registry archive URL for one version, or null when it is not on the package's own registry. */
 export function archiveUrl(index, version) {
     const url = index.ecosystem === "crates.io"
         ? `https://static.crates.io/crates/${index.name}/${index.name}-${version.version}.crate`
-        : version.tarball;
+        : index.ecosystem === "Go"
+            ? goZipUrl(index.name, version.version)
+            : version.tarball;
     if (!url)
         return null;
     try {
@@ -132,7 +190,12 @@ export function changelogCacheKey(ecosystem, name, version) {
 export async function getChangelog(net, index, version) {
     const url = archiveUrl(index, version);
     if (!url) {
-        return { found: false, reason: "the version's archive is not hosted on the package's own registry" };
+        return {
+            found: false,
+            reason: index.ecosystem === "PyPI" && !version.tarball
+                ? `${version.version} has no source distribution on PyPI (wheels only), so there is no archive changelog to read`
+                : "the version's archive is not hosted on the package's own registry",
+        };
     }
     // The parser version is in the key: a parser fix must not wait out the 7-day TTL.
     const key = changelogCacheKey(index.ecosystem, index.name, version.version);
@@ -142,7 +205,11 @@ export async function getChangelog(net, index, version) {
     const headers = index.ecosystem === "crates.io" ? { "User-Agent": CRATES_USER_AGENT } : {};
     let files;
     try {
-        files = await fetchArchiveRootFiles(url, isChangelogName, net.fetch, headers);
+        const bytes = await fetchArchiveBytes(url, net.fetch, headers);
+        // A Go module zip holds its files under `<module>@<version>/`; a zip sdist and every tar one directory deep.
+        files = looksLikeZip(bytes)
+            ? readZipRootTextFiles(bytes, isChangelogName, index.ecosystem === "Go" ? `${index.name}@${version.version}/` : null)
+            : readRootTextFiles(bytes, isChangelogName);
     }
     catch (err) {
         const result = { found: false, reason: `could not read the ${version.version} archive: ${err.message}` };
@@ -158,7 +225,7 @@ export async function getChangelog(net, index, version) {
         ? { found: false, reason: `the ${version.version} archive ships no changelog file` }
         : sections.length === 0
             ? { found: false, file, reason: `${file} has no version headings this parser recognises` }
-            : { found: true, file, sections };
+            : { found: true, file, sections, source: "archive" };
     net.cache?.set(key, result, CACHE_SOURCE, CHANGELOG_TTL);
     return result;
 }

package/dist/live/zip-archive.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zip archive reader for `upgrade_impact`, Node built-ins only.
+ *
+ * Go module zips (proxy.golang.org `/@v/<version>.zip`) and the occasional
+ * PyPI `.zip` sdist are zip files, not gzip tars. The job is the same as
+ * package-archive.ts's: pull a few root-level text files (the changelog) out
+ * of a third-party archive without trusting it. Only the central directory
+ * is read, so a file's declared sizes come from one place; stored (0) and
+ * deflate (8) entries are read, everything else (zip64, encryption, other
+ * methods) is skipped rather than guessed at. Each inflate is capped at
+ * MAX_FILE_BYTES, so a zip bomb stops at the cap.
+ */
+/** True when the buffer starts like a zip archive (a local file header). */
+export declare function looksLikeZip(buf: Buffer): boolean;
+/**
+ * Text files directly under `root` (a path prefix such as
+ * `github.com/foo/bar@v1.2.3/`; "" for every top-level file of a one-directory
+ * archive) whose basename `accept` approves. When `root` is null, files one
+ * directory deep are read, as the tar reader does. Oversized, binary and
+ * unreadable entries are skipped.
+ */
+export declare function readZipRootTextFiles(buf: Buffer, accept: (basename: string) => boolean, root?: string | null): Map<string, string>;

package/dist/live/zip-archive.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Zip archive reader for `upgrade_impact`, Node built-ins only.
+ *
+ * Go module zips (proxy.golang.org `/@v/<version>.zip`) and the occasional
+ * PyPI `.zip` sdist are zip files, not gzip tars. The job is the same as
+ * package-archive.ts's: pull a few root-level text files (the changelog) out
+ * of a third-party archive without trusting it. Only the central directory
+ * is read, so a file's declared sizes come from one place; stored (0) and
+ * deflate (8) entries are read, everything else (zip64, encryption, other
+ * methods) is skipped rather than guessed at. Each inflate is capped at
+ * MAX_FILE_BYTES, so a zip bomb stops at the cap.
+ */
+import { inflateRawSync } from "node:zlib";
+import { ArchiveError, MAX_COMPRESSED_BYTES, MAX_FILE_BYTES } from "./package-archive.js";
+const EOCD_SIG = 0x06054b50;
+const CDH_SIG = 0x02014b50;
+const LFH_SIG = 0x04034b50;
+/** The end-of-central-directory record is 22 bytes plus a comment of at most 65,535. */
+const EOCD_SEARCH = 22 + 0xffff;
+const MAX_ENTRIES = 200_000;
+/** True when the buffer starts like a zip archive (a local file header). */
+export function looksLikeZip(buf) {
+    return buf.length >= 4 && buf.readUInt32LE(0) === LFH_SIG;
+}
+function findEocd(buf) {
+    const stop = Math.max(0, buf.length - EOCD_SEARCH);
+    for (let i = buf.length - 22; i >= stop; i--) {
+        if (buf.readUInt32LE(i) === EOCD_SIG)
+            return i;
+    }
+    throw new ArchiveError("not a zip archive (no end-of-central-directory record)");
+}
+/**
+ * Text files directly under `root` (a path prefix such as
+ * `github.com/foo/bar@v1.2.3/`; "" for every top-level file of a one-directory
+ * archive) whose basename `accept` approves. When `root` is null, files one
+ * directory deep are read, as the tar reader does. Oversized, binary and
+ * unreadable entries are skipped.
+ */
+export function readZipRootTextFiles(buf, accept, root = null) {
+    if (buf.length > MAX_COMPRESSED_BYTES) {
+        throw new ArchiveError(`archive is ${buf.length} bytes compressed (cap ${MAX_COMPRESSED_BYTES})`);
+    }
+    if (buf.length < 22)
+        throw new ArchiveError("not a zip archive (too short)");
+    const eocd = findEocd(buf);
+    const count = buf.readUInt16LE(eocd + 10);
+    const cdSize = buf.readUInt32LE(eocd + 12);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    if (cdOffset === 0xffffffff || count === 0xffff)
+        throw new ArchiveError("zip64 archives are not read");
+    if (cdOffset + cdSize > buf.length || count > MAX_ENTRIES)
+        throw new ArchiveError("corrupt zip central directory");
+    const files = new Map();
+    let p = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (p + 46 > buf.length || buf.readUInt32LE(p) !== CDH_SIG)
+            throw new ArchiveError("corrupt zip central directory entry");
+        const flags = buf.readUInt16LE(p + 8);
+        const method = buf.readUInt16LE(p + 10);
+        const compressed = buf.readUInt32LE(p + 20);
+        const size = buf.readUInt32LE(p + 24);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const local = buf.readUInt32LE(p + 42);
+        const name = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");
+        p += 46 + nameLen + extraLen + commentLen;
+        if (name.endsWith("/") || !isRootFile(name, root) || !accept(name.split("/").pop() ?? ""))
+            continue;
+        if (flags & 0x1 || (method !== 0 && method !== 8) || size > MAX_FILE_BYTES)
+            continue;
+        if (local + 30 > buf.length || buf.readUInt32LE(local) !== LFH_SIG)
+            continue;
+        const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+        if (start + compressed > buf.length)
+            continue;
+        const raw = buf.subarray(start, start + compressed);
+        let data;
+        try {
+            data = method === 0 ? Buffer.from(raw) : inflateRawSync(raw, { maxOutputLength: MAX_FILE_BYTES });
+        }
+        catch {
+            continue;
+        }
+        if (data.includes(0))
+            continue;
+        files.set(name, data.toString("utf8"));
+    }
+    return files;
+}
+function isRootFile(name, root) {
+    if (root !== null)
+        return name.startsWith(root) && !name.slice(root.length).includes("/") && name.length > root.length;
+    const parts = name.split("/").filter(Boolean);
+    return parts.length > 0 && parts.length <= 2;
+}

package/dist/schema-registry.js

@@ -31,7 +31,7 @@ const WRITE_LOCAL = { readOnlyHint: false, openWorldHint: false, destructiveHint
 export const TOOL_REGISTRY = {
     // --- Dependency Security (standalone) ---
     vulnerability_scan: {
-        summary: "Scan this project's lockfiles (npm/pnpm/yarn/bun, Cargo, Python, Go) for known OSV.dev vulnerabilities, transitives included, with fix versions and where each is pinned; `package` for one dep. Call when the user asks about security, vulnerabilities or CVEs, or before recommending a dependency.",
+        summary: "Scan this project's lockfiles (npm/pnpm/yarn/bun, Cargo, Python, Go) for OSV.dev vulnerabilities in installed versions, transitives included, with fix versions and where each is pinned; `package` for one dep. Call when asked about security or CVEs. To vet a version first: dependency_check.",
         definition: vulnerabilityScanTool,
         category: "security",
         tags: ["security", "vulnerabilities", "cve", "dependencies", "osv"],
@@ -55,7 +55,7 @@ export const TOOL_REGISTRY = {
         annotations: { title: "Upgrade planner", ...READ_NETWORK },
     },
     upgrade_impact: {
-        summary: "What changes between the installed version of ONE dependency and a target version: changelog entries per release, breaking changes, deprecations, security fixes, and the files in this project that import it. Call before upgrading or bumping a dependency.",
+        summary: "What changes between the installed version of ONE dependency and a target: changelog per release, breaking changes, deprecations, security fixes, and this project's files that import it. Call before upgrading or bumping a dependency.",
         definition: upgradeImpactTool,
         category: "security",
         tags: ["upgrade", "changelog", "breaking-changes", "migration", "release-notes"],
@@ -63,7 +63,7 @@ export const TOOL_REGISTRY = {
         annotations: { title: "Upgrade impact", ...READ_NETWORK },
     },
     dependency_check: {
-        summary: "Verdict (proceed/wait/review/avoid/unknown) with evidence for adding a dependency or bumping one to a version. Call BEFORE you add a package or apply any version bump.",
+        summary: "Is a dependency version safe to write? Verdict on an exact version, or safe releases in a constraint (\"7.x\", \"~=3.1\"); npm, crates.io, PyPI, Go. Call BEFORE writing any version to a manifest: add, pin, upgrade, bump, downgrade.",
         definition: dependencyCheckTool,
         category: "security",
         tags: ["dependencies", "supply-chain", "pre-install", "upgrade", "versions"],