@4da/mcp-server 6.0.2 → 6.2.0

package/dist/live/release-metadata.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-release registry metadata, normalised across npm and crates.io.
+ * Per-release registry metadata, normalised across npm, crates.io, PyPI and Go.
  *
  * `dependency_check` judges ONE proposed version against the one installed
  * (or, for a new dependency, against the previous release on the same line).
@@ -9,8 +9,11 @@
  * raw responses into this shape so the signal logic never sees a registry's
  * wire format.
  *
- * Privacy: every request behind this shape carries the package NAME only.
- * Versions are selected locally from the full release list.
+ * Privacy: every npm, crates.io and PyPI request behind this shape carries
+ * the package NAME only; versions are selected locally from the full release
+ * list. The Go module proxy lists versions without dates, so a Go release's
+ * date is read from its own `/@v/<version>.info` (the proxy `go get` itself
+ * downloads from), for the versions being judged only.
  */
 /**
  * Publish trust of one release.
@@ -27,17 +30,23 @@ export interface ReleaseRecord {
     trust: TrustLevel;
     /** Human label for the trust evidence, e.g. "trusted publisher (github)". */
     trustEvidence: string;
-    /** npm: install-time lifecycle scripts declared (preinstall/install/postinstall, or a gypfile). Null for crates. */
+    /** npm: install-time lifecycle scripts declared (preinstall/install/postinstall, or a gypfile). Null elsewhere. */
     installScripts: string[] | null;
     /** npm deprecation message, or null. */
     deprecated: string | null;
-    /** crates.io: yanked. npm: unpublished (listed in `time` but gone from `versions`). */
-    withdrawn: "yanked" | "unpublished" | null;
-    /** Runtime dependency NAMES (npm dependencies + optionalDependencies; crates normal + build). Null when unknown. */
+    /**
+     * crates.io / PyPI: yanked (PyPI: every file of the release). npm: unpublished
+     * (listed in `time` but gone from `versions`). Go: retracted by a `retract`
+     * directive in the module's latest go.mod.
+     */
+    withdrawn: "yanked" | "unpublished" | "retracted" | null;
+    /** Runtime dependency NAMES (npm dependencies + optionalDependencies; crates normal + build). Null when unknown or not read (PyPI, Go). */
     dependencies: string[] | null;
 }
+/** The registries dependency_check reads. */
+export type CheckEcosystem = "npm" | "crates.io" | "PyPI" | "Go";
 export interface PackageReleaseIndex {
-    ecosystem: "npm" | "crates.io";
+    ecosystem: CheckEcosystem;
     name: string;
     /** When the package itself was first published, or null. */
     createdAt: string | null;

package/dist/live/release-metadata.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Per-release registry metadata, normalised across npm and crates.io.
+ * Per-release registry metadata, normalised across npm, crates.io, PyPI and Go.
  *
  * `dependency_check` judges ONE proposed version against the one installed
  * (or, for a new dependency, against the previous release on the same line).
@@ -10,7 +10,10 @@
  * raw responses into this shape so the signal logic never sees a registry's
  * wire format.
  *
- * Privacy: every request behind this shape carries the package NAME only.
- * Versions are selected locally from the full release list.
+ * Privacy: every npm, crates.io and PyPI request behind this shape carries
+ * the package NAME only; versions are selected locally from the full release
+ * list. The Go module proxy lists versions without dates, so a Go release's
+ * date is read from its own `/@v/<version>.info` (the proxy `go get` itself
+ * downloads from), for the versions being judged only.
  */
 export {};

package/dist/live/resolution.d.ts

@@ -33,8 +33,18 @@ export interface GroupResolution {
     /** The full lockfile set plus drift entries (vulnerability scanning). */
     audit: ResolvedDependency[];
     drift: InstallDriftRecord[];
-    /** The file the versions were read from, or null when the group resolved from nothing. */
+    /** The (first) file the versions were read from, or null when the group resolved from nothing. */
     source: ResolutionSourceRecord | null;
+    /** Every file read, `source` first (Python merges its lockfiles and requirement files). */
+    sources: ResolutionSourceRecord[];
+    /**
+     * Set when no lockfile pins this group's versions: the manifest and how many
+     * of its dependencies are declared ranges, which are not sent to OSV.
+     */
+    unresolved: {
+        manifest: string;
+        ranges: number;
+    } | null;
     signatures: Map<string, FileSignature>;
     resolvedAt: string;
 }

package/dist/live/resolution.js

@@ -30,11 +30,20 @@ export function resolveGroup(group) {
         ...(manifest ? [manifest] : []),
     ]);
     const read = resolveVersionSource(group.dir, ecosystem);
+    const readFiles = read.source ? [read.source, ...(read.extraSources ?? [])] : [];
     // The manifest only matters when the resolver fell back to it; editing a
     // script in package.json must not throw away a scan of an unchanged lockfile.
-    if (manifest && read.kind === "lockfile")
+    if (manifest && !readFiles.includes(manifest))
         signatures.delete(manifest);
     let resolved = resolveVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets);
+    // No lockfile: a ranged dependency's version is the range's floor, a label.
+    const ranges = read.kind === "declared_ranges" ? read.ranges ?? new Map() : null;
+    if (ranges && ranges.size > 0) {
+        resolved = resolved.map((dep) => {
+            const declaredRange = ranges.get(dep.name);
+            return declaredRange ? { ...dep, declaredRange } : dep;
+        });
+    }
     let drift = [];
     let driftAudit = [];
     // Only a lockfile pins exact versions; comparing node_modules against a
@@ -50,11 +59,12 @@ export function resolveGroup(group) {
     const audit = [
         ...resolveAuditVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets, resolved, read.instances),
         ...driftAudit,
-    ];
-    const source = read.source && read.kind
-        ? { path: read.source, kind: read.kind, mtimeMs: signatureMtime(signatures.get(read.source)) }
-        : null;
-    return { group, resolved, audit, drift, source, signatures, resolvedAt };
+    ].filter((dep) => !dep.declaredRange);
+    const sources = read.kind
+        ? readFiles.map((file) => ({ path: file, kind: read.kind, mtimeMs: signatureMtime(signatures.get(file)) }))
+        : [];
+    const unresolved = ranges && ranges.size > 0 && read.source ? { manifest: read.source, ranges: ranges.size } : null;
+    return { group, resolved, audit, drift, source: sources[0] ?? null, sources, unresolved, signatures, resolvedAt };
 }
 /** True when any file the resolution depended on changed, appeared, or vanished. */
 export function groupIsStale(result) {

package/dist/live/semver-utils.d.ts

@@ -1,5 +1,13 @@
 import type { SemverDistance } from "./types.js";
 export declare function parseSemver(version: string): [number, number, number] | null;
+/**
+ * How far `current` is behind `latest`. `label` is the kind of bump, by the
+ * caret rules npm and Cargo apply: below 1.0 a minor bump is breaking (^0.8.6
+ * does not admit 0.9.0) and below 0.1 a patch bump is too (^0.0.3 is =0.0.3),
+ * so both are labelled "major", the same as upgrade_impact and dependency_check.
+ * Until 6.0.2 sqlx 0.8 -> 0.9 and reqwest 0.12 -> 0.13 were labelled "minor".
+ * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
+ */
 export declare function computeSemverDistance(current: string, latest: string): SemverDistance | null;
 export declare function isPreRelease(version: string): boolean;
 /**

package/dist/live/semver-utils.js

@@ -5,6 +5,14 @@ export function parseSemver(version) {
         return null;
     return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
 }
+/**
+ * How far `current` is behind `latest`. `label` is the kind of bump, by the
+ * caret rules npm and Cargo apply: below 1.0 a minor bump is breaking (^0.8.6
+ * does not admit 0.9.0) and below 0.1 a patch bump is too (^0.0.3 is =0.0.3),
+ * so both are labelled "major", the same as upgrade_impact and dependency_check.
+ * Until 6.0.2 sqlx 0.8 -> 0.9 and reqwest 0.12 -> 0.13 were labelled "minor".
+ * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
+ */
 export function computeSemverDistance(current, latest) {
     const c = parseSemver(current);
     const l = parseSemver(latest);
@@ -17,9 +25,9 @@ export function computeSemverDistance(current, latest) {
     if (major > 0)
         label = "major";
     else if (minor > 0)
-        label = "minor";
+        label = c[0] === 0 ? "major" : "minor";
     else if (patch > 0)
-        label = "patch";
+        label = c[0] === 0 && c[1] === 0 ? "major" : "patch";
     return { major: Math.max(0, major), minor: Math.max(0, minor), patch: Math.max(0, patch), label };
 }
 export function isPreRelease(version) {

package/dist/live/types.d.ts

@@ -37,6 +37,12 @@ export interface ResolvedDependency {
     installDriftOf?: string;
     /** On drift entries: the command that reinstalls from the lockfile. */
     installFix?: InstallFixCommand;
+    /**
+     * Set when no lockfile pins this dependency: the requirement the manifest
+     * declares ("^1.2.0"). `version` is then that range's floor, NOT an
+     * installed version, and the dependency is never sent to OSV as if it were.
+     */
+    declaredRange?: string;
 }
 /**
  * One npm direct dependency whose installed copy differs from its lockfile.
@@ -54,7 +60,8 @@ export interface InstallDriftRecord {
 export interface ResolutionSourceRecord {
     /** Absolute path. */
     path: string;
-    kind: "lockfile" | "manifest";
+    /** lockfile = exact versions; manifest = exact requirement pins; declared_ranges = no lockfile, range floors only. */
+    kind: "lockfile" | "manifest" | "declared_ranges";
     /** Modification time when it was read, or null if it vanished since. */
     mtimeMs: number | null;
 }
@@ -88,8 +95,12 @@ export interface OsvVulnerability {
             events: Array<{
                 introduced?: string;
                 fixed?: string;
+                last_affected?: string;
+                limit?: string;
             }>;
         }>;
+        /** Versions listed explicitly, in addition to (or instead of) the ranges. */
+        versions?: string[];
     }>;
     references?: Array<{
         type: string;
@@ -191,6 +202,11 @@ export interface RegistryPackageInfo {
     weeklyDownloads: number | null;
     isDev: boolean;
     fetchError: string | null;
+    /**
+     * No lockfile: the declared requirement ("^1.2.0"); `currentVersion` is then
+     * its floor, not an installed version.
+     */
+    declaredRange?: string;
     /**
      * The version node_modules actually holds, present only when it differs
      * from `currentVersion` (the lockfile's). Several differing installs across

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

@@ -0,0 +1,62 @@
+/**
+ * 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`.
+ */
+import type { PublishedVersion, RegistryIndex, UpgradeNet } from "./upgrade-sources.js";
+/** A module path: a dotted host, then path elements (case kept; the proxy escapes capitals). */
+export declare const GO_MODULE: RegExp;
+/** Proxy escaping: each capital letter becomes `!` + lowercase. */
+export declare function escapeGoPath(path: string): string;
+export interface GoInfo {
+    Version?: string;
+    Time?: string;
+    Origin?: {
+        VCS?: string;
+        URL?: string;
+        Subdir?: string;
+        Ref?: string;
+    };
+}
+/** The major version a module path carries: `/v5` -> 5, `gopkg.in/yaml.v3` -> 3, none -> null (0 or 1). */
+export declare function goPathMajor(path: string): number | null;
+/** The module path without its major suffix. */
+export declare function goBasePath(path: string): string;
+/** The path major `major` lives at: none for 0 and 1, `/vN` (or gopkg.in's `.vN`) from 2. */
+export declare function goMajorPath(path: string, major: number): string;
+export declare function goVersionMajor(version: string): number | null;
+/** GitHub repository from a module path: `github.com/<owner>/<repo>/...`. */
+export declare function githubRepoOfGoPath(path: string): string | null;
+export declare function goInfo(net: UpgradeNet, module: string, version: string): Promise<GoInfo | null>;
+export declare function loadGoIndex(net: UpgradeNet, module: string): Promise<RegistryIndex | null>;
+/**
+ * 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 declare function enrichGoVersions(net: UpgradeNet, module: string, versions: PublishedVersion[], target: PublishedVersion | null, budget?: number): Promise<{
+    origin: GoInfo["Origin"] | null;
+}>;
+/**
+ * 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 declare function goTagPrefix(module: string, version: string, origin: GoInfo["Origin"] | null): string;
+/** The proxy's zip of one module version. */
+export declare function goZipUrl(module: string, version: string): string;

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 {
@@ -59,6 +76,8 @@ export declare function isValidPackageName(name: string, ecosystem: UpgradeEcosy
 export declare function getRegistryIndex(net: UpgradeNet, ecosystem: UpgradeEcosystem, name: string): Promise<RegistryIndex | null>;
 /** The registry archive URL for one version, or null when it is not on the package's own registry. */
 export declare function archiveUrl(index: RegistryIndex, version: PublishedVersion): string | null;
+/** Cache key of one version's parsed changelog; it carries CHANGELOG_PARSER_VERSION. */
+export declare function changelogCacheKey(ecosystem: string, name: string, version: string): string;
 /** Parsed changelog shipped inside one version's archive (cached 7 days per version). */
 export declare function getChangelog(net: UpgradeNet, index: RegistryIndex, version: PublishedVersion): Promise<ChangelogResult>;
 /** OSV advisory ids affecting one version, or null when OSV could not be reached. */