@4da/mcp-server 5.0.4 → 6.0.1

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

@@ -0,0 +1,49 @@
+/**
+ * Registry package archive reader (gzip tar), Node built-ins only.
+ *
+ * `upgrade_impact` reads the changelog a package ships INSIDE its own registry
+ * archive (npm `.tgz`, crates.io `.crate`). That keeps the privacy contract
+ * simple: the only host contacted is the package's own registry, which the
+ * agent was going to download from anyway — never GitHub or a docs site.
+ *
+ * Why a hand-rolled tar reader: adding `tar` as a dependency for the one job
+ * of pulling a few root-level text files would grow the published server's
+ * supply chain for no gain. The subset handled here is what real registry
+ * archives use: ustar headers with the `prefix` field, PAX `x` headers
+ * (`path=` for names over 100 bytes — npm's packer emits these) and GNU `L`
+ * long names (older cargo / GNU tar). Everything else is skipped, not guessed.
+ *
+ * Hard caps, because the archive is third-party input: compressed ≤ 20 MB
+ * (Content-Length AND bytes actually read — a server can lie about the
+ * former), uncompressed ≤ 80 MB (zlib `maxOutputLength`, so a gzip bomb stops
+ * inflating at the cap instead of exhausting memory), single file ≤ 2 MB.
+ */
+export declare const MAX_COMPRESSED_BYTES: number;
+export declare const MAX_UNCOMPRESSED_BYTES: number;
+export declare const MAX_FILE_BYTES: number;
+/** The fetch signature archive and registry readers go through, so tests can inject one. */
+export type FetchFn = (url: string, init?: RequestInit, timeoutMs?: number) => Promise<Response>;
+export declare const defaultFetch: FetchFn;
+/** Raised for every refusal (cap exceeded, corrupt archive) with a message fit for tool output. */
+export declare class ArchiveError extends Error {
+}
+interface TarEntry {
+    path: string;
+    type: string;
+    data: Buffer;
+}
+/** PAX records are `"<len> <key>=<value>\n"`, where len counts the whole record in BYTES. */
+export declare function parsePaxHeaders(data: Buffer): Record<string, string>;
+/** Walk an uncompressed tar buffer, yielding regular-file entries with their resolved names. */
+export declare function iterateTar(tar: Buffer): Generator<TarEntry>;
+/**
+ * Root-level text files from a gzip tar whose basename `accept` approves.
+ * "Root-level" = at most one directory deep, because registry archives wrap
+ * everything in a single top directory (`package/`, `<name>-<version>/`).
+ * Keys are the archive paths as stored. Oversized or binary (NUL-containing)
+ * files are skipped.
+ */
+export declare function readRootTextFiles(gz: Buffer, accept: (basename: string) => boolean): Map<string, string>;
+/** Download a registry archive (size-capped) and return the accepted root-level text files. */
+export declare function fetchArchiveRootFiles(url: string, accept: (basename: string) => boolean, fetchFn?: FetchFn, headers?: Record<string, string>): Promise<Map<string, string>>;
+export {};

package/dist/live/package-archive.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Registry package archive reader (gzip tar), Node built-ins only.
+ *
+ * `upgrade_impact` reads the changelog a package ships INSIDE its own registry
+ * archive (npm `.tgz`, crates.io `.crate`). That keeps the privacy contract
+ * simple: the only host contacted is the package's own registry, which the
+ * agent was going to download from anyway — never GitHub or a docs site.
+ *
+ * Why a hand-rolled tar reader: adding `tar` as a dependency for the one job
+ * of pulling a few root-level text files would grow the published server's
+ * supply chain for no gain. The subset handled here is what real registry
+ * archives use: ustar headers with the `prefix` field, PAX `x` headers
+ * (`path=` for names over 100 bytes — npm's packer emits these) and GNU `L`
+ * long names (older cargo / GNU tar). Everything else is skipped, not guessed.
+ *
+ * Hard caps, because the archive is third-party input: compressed ≤ 20 MB
+ * (Content-Length AND bytes actually read — a server can lie about the
+ * former), uncompressed ≤ 80 MB (zlib `maxOutputLength`, so a gzip bomb stops
+ * inflating at the cap instead of exhausting memory), single file ≤ 2 MB.
+ */
+import { gunzipSync } from "node:zlib";
+import { fetchWithTimeout } from "./http-utils.js";
+export const MAX_COMPRESSED_BYTES = 20 * 1024 * 1024;
+export const MAX_UNCOMPRESSED_BYTES = 80 * 1024 * 1024;
+export const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const BLOCK = 512;
+const ARCHIVE_TIMEOUT_MS = 30_000;
+export const defaultFetch = (url, init, timeoutMs) => fetchWithTimeout(url, init ?? {}, timeoutMs);
+/** Raised for every refusal (cap exceeded, corrupt archive) with a message fit for tool output. */
+export class ArchiveError extends Error {
+}
+function readString(buf, start, length) {
+    const slice = buf.subarray(start, start + length);
+    const nul = slice.indexOf(0);
+    return slice.subarray(0, nul === -1 ? slice.length : nul).toString("utf8");
+}
+function readOctal(buf, start, length) {
+    if (buf[start] & 0x80) {
+        // GNU base-256 size: only needed for entries ≥ 8 GB, far over every cap here.
+        throw new ArchiveError("tar entry uses a base-256 size field (entry too large)");
+    }
+    const text = readString(buf, start, length).trim();
+    if (text === "")
+        return 0;
+    if (!/^[0-7]+$/.test(text))
+        throw new ArchiveError(`corrupt tar header: size field "${text}"`);
+    return parseInt(text, 8);
+}
+function checksumMatches(header) {
+    const stored = readString(header, 148, 8).trim();
+    if (!/^[0-7]+$/.test(stored))
+        return false;
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++)
+        sum += i >= 148 && i < 156 ? 0x20 : header[i];
+    return sum === parseInt(stored, 8);
+}
+/** PAX records are `"<len> <key>=<value>\n"`, where len counts the whole record in BYTES. */
+export function parsePaxHeaders(data) {
+    const out = {};
+    let pos = 0;
+    while (pos < data.length) {
+        const space = data.indexOf(0x20, pos);
+        if (space === -1)
+            break;
+        const len = Number(data.subarray(pos, space).toString("ascii"));
+        if (!Number.isInteger(len) || len <= 0 || pos + len > data.length)
+            break;
+        const record = data.subarray(space + 1, pos + len).toString("utf8").replace(/\n$/, "");
+        const eq = record.indexOf("=");
+        if (eq > 0)
+            out[record.slice(0, eq)] = record.slice(eq + 1);
+        pos += len;
+    }
+    return out;
+}
+/** Walk an uncompressed tar buffer, yielding regular-file entries with their resolved names. */
+export function* iterateTar(tar) {
+    let offset = 0;
+    let paxPath = null;
+    let gnuLongName = null;
+    while (offset + BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK);
+        if (header.every((b) => b === 0))
+            return; // end-of-archive marker
+        if (!checksumMatches(header))
+            throw new ArchiveError("corrupt tar header: checksum mismatch");
+        const size = readOctal(header, 124, 12);
+        const type = String.fromCharCode(header[156] || 0x30); // NUL typeflag = regular file
+        const dataStart = offset + BLOCK;
+        if (dataStart + size > tar.length)
+            throw new ArchiveError("truncated tar entry");
+        const data = tar.subarray(dataStart, dataStart + size);
+        offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+        if (type === "x") {
+            paxPath = parsePaxHeaders(data).path ?? null;
+            continue;
+        }
+        if (type === "L") {
+            gnuLongName = readString(data, 0, data.length);
+            continue;
+        }
+        if (type === "g" || type === "K")
+            continue; // global PAX / GNU long link: no effect on names here
+        const name = readString(header, 0, 100);
+        const magic = readString(header, 257, 6);
+        const prefix = magic.startsWith("ustar") ? readString(header, 345, 155) : "";
+        const path = paxPath ?? gnuLongName ?? (prefix ? `${prefix}/${name}` : name);
+        paxPath = null;
+        gnuLongName = null;
+        yield { path, type, data };
+    }
+}
+/** Path segments with `./` and empty segments removed. */
+function segments(path) {
+    return path.split("/").filter((s) => s !== "" && s !== ".");
+}
+/**
+ * Root-level text files from a gzip tar whose basename `accept` approves.
+ * "Root-level" = at most one directory deep, because registry archives wrap
+ * everything in a single top directory (`package/`, `<name>-<version>/`).
+ * Keys are the archive paths as stored. Oversized or binary (NUL-containing)
+ * files are skipped.
+ */
+export function readRootTextFiles(gz, accept) {
+    if (gz.length > MAX_COMPRESSED_BYTES) {
+        throw new ArchiveError(`archive is ${gz.length} bytes compressed (cap ${MAX_COMPRESSED_BYTES})`);
+    }
+    let tar;
+    try {
+        tar = gunzipSync(gz, { maxOutputLength: MAX_UNCOMPRESSED_BYTES });
+    }
+    catch (err) {
+        if (err instanceof RangeError || err.code === "ERR_BUFFER_TOO_LARGE") {
+            throw new ArchiveError(`archive exceeds ${MAX_UNCOMPRESSED_BYTES} bytes uncompressed`);
+        }
+        throw new ArchiveError(`archive is not valid gzip: ${err.message}`);
+    }
+    const files = new Map();
+    for (const entry of iterateTar(tar)) {
+        if (entry.type !== "0" && entry.type !== "7")
+            continue;
+        const parts = segments(entry.path);
+        if (parts.length === 0 || parts.length > 2)
+            continue;
+        if (!accept(parts[parts.length - 1]))
+            continue;
+        if (entry.data.length > MAX_FILE_BYTES || entry.data.includes(0))
+            continue;
+        files.set(entry.path, entry.data.toString("utf8"));
+    }
+    return files;
+}
+/** Read a response body, refusing at `cap` bytes instead of buffering whatever the server sends. */
+async function readCapped(response, cap) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > cap) {
+        throw new ArchiveError(`archive is ${declared} bytes compressed (cap ${cap})`);
+    }
+    if (!response.body)
+        return Buffer.from(await response.arrayBuffer());
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel().catch(() => undefined);
+            throw new ArchiveError(`archive exceeds ${cap} bytes compressed`);
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+}
+/** Download a registry archive (size-capped) and return the accepted root-level text files. */
+export async function fetchArchiveRootFiles(url, accept, fetchFn = defaultFetch, headers = {}) {
+    const response = await fetchFn(url, { headers }, ARCHIVE_TIMEOUT_MS);
+    if (!response.ok)
+        throw new ArchiveError(`archive download failed: HTTP ${response.status}`);
+    const gz = await readCapped(response, MAX_COMPRESSED_BYTES);
+    return readRootTextFiles(gz, accept);
+}

package/dist/live/pypi-registry.js

@@ -21,7 +21,9 @@ export class PyPIRegistry {
     }
     async getPackageInfo(name, currentVersion, isDev) {
         const normalizedName = name.toLowerCase().replace(/_/g, "-");
-        const cacheKey = `pypi-reg:${name.toLowerCase()}`;
+        // Keyed by the installed version too: the cached answer carries currentVersion
+        // and its distance, so a name-only key served one project's answer to another.
+        const cacheKey = `pypi-reg:${name.toLowerCase()}@${currentVersion ?? ""}:${isDev ? 1 : 0}`;
         const cached = this.cache.get(cacheKey);
         if (cached !== null)
             return cached;

package/dist/live/registry-health.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Registry health lookups for resolved dependencies (moved out of
+ * live/index.ts unchanged, so the coordinator stays within its size limit).
+ */
+import type { NpmRegistry } from "./npm-registry.js";
+import type { CratesRegistry } from "./crates-registry.js";
+import type { PyPIRegistry } from "./pypi-registry.js";
+import type { GoRegistry } from "./go-registry.js";
+import type { RegistryPackageInfo, ResolvedDependency } from "./types.js";
+export interface Registries {
+    npm: NpmRegistry;
+    crates: CratesRegistry;
+    pypi: PyPIRegistry;
+    go: GoRegistry;
+}
+export declare function fetchRegistryHealthFor(deps: ResolvedDependency[], registries: Registries, enabled: boolean): Promise<RegistryPackageInfo[]>;

package/dist/live/registry-health.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Registry health lookups for resolved dependencies (moved out of
+ * live/index.ts unchanged, so the coordinator stays within its size limit).
+ */
+import { computeSemverDistance } from "./semver-utils.js";
+function unavailable(dep, fetchError) {
+    return {
+        name: dep.name, ecosystem: dep.ecosystem, currentVersion: dep.version,
+        latestVersion: null, latestStableVersion: null, versionsBehind: null,
+        deprecated: false, deprecationMessage: null, lastPublished: null,
+        license: null, weeklyDownloads: null, isDev: dep.isDev, fetchError,
+    };
+}
+export async function fetchRegistryHealthFor(deps, registries, enabled) {
+    if (!enabled)
+        return deps.map((d) => unavailable(d, "Offline mode"));
+    const registryForEcosystem = (eco) => {
+        switch (eco) {
+            case "npm": return registries.npm;
+            case "crates.io": return registries.crates;
+            case "PyPI": return registries.pypi;
+            case "Go": return registries.go;
+            default: return null;
+        }
+    };
+    const results = await Promise.all(deps.map(async (dep) => {
+        const registry = registryForEcosystem(dep.ecosystem);
+        if (!registry)
+            return unavailable(dep, `No registry fetcher for ${dep.ecosystem}`);
+        try {
+            const info = await registry.getPackageInfo(dep.name, dep.version, dep.isDev);
+            return restampRegistryContext(info, dep);
+        }
+        catch {
+            return unavailable(dep, "Registry fetch failed");
+        }
+    }));
+    // Bulk fetch npm downloads for npm deps
+    const npmDeps = deps.filter((d) => d.ecosystem === "npm");
+    if (npmDeps.length > 0) {
+        try {
+            const downloads = await registries.npm.getBulkDownloads(npmDeps.map((d) => d.name));
+            for (const result of results) {
+                if (result.ecosystem === "npm" && downloads.has(result.name)) {
+                    result.weeklyDownloads = downloads.get(result.name) || null;
+                }
+            }
+        }
+        catch {
+            // Downloads are nice-to-have, not critical
+        }
+    }
+    return results;
+}
+/**
+ * Registry caches key by package NAME, but the cached record embeds the
+ * QUERYING dependency's `currentVersion`, `versionsBehind`, and `isDev`. Two
+ * instances of one package at different versions (better-sqlite3 11.10.0 and
+ * 12.11.1 across workspaces) therefore both came back wearing the first
+ * instance's version — the upgrade planner then showed two identical rows and
+ * lost the older instance entirely. Registry facts (latest version,
+ * deprecation, downloads) are per-package and cacheable; the per-instance
+ * fields are re-stamped here from the dep actually being asked about.
+ */
+function restampRegistryContext(info, dep) {
+    const latest = info.latestStableVersion || info.latestVersion;
+    return {
+        ...info,
+        currentVersion: dep.version,
+        isDev: dep.isDev,
+        versionsBehind: dep.version && latest ? computeSemverDistance(dep.version, latest) : null,
+    };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Per-release registry metadata, normalised across npm and crates.io.
+ *
+ * `dependency_check` judges ONE proposed version against the one installed
+ * (or, for a new dependency, against the previous release on the same line).
+ * That needs facts the version-freshness readers never kept: when each release
+ * was published, who/what published it, whether it runs install scripts, and
+ * which runtime dependencies it pulls in. Both registry readers project their
+ * 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.
+ */
+/**
+ * Publish trust of one release.
+ * 2 = published by a registry-verified trusted publisher (npm
+ *     `_npmUser.trustedPublisher`, crates.io `trustpub_data`).
+ * 1 = carries a provenance attestation (npm `dist.attestations`).
+ * 0 = neither: a token / hand publish.
+ */
+export type TrustLevel = 0 | 1 | 2;
+export interface ReleaseRecord {
+    version: string;
+    /** ISO publish time, or null when the registry does not say. */
+    publishedAt: string | null;
+    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. */
+    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. */
+    dependencies: string[] | null;
+}
+export interface PackageReleaseIndex {
+    ecosystem: "npm" | "crates.io";
+    name: string;
+    /** When the package itself was first published, or null. */
+    createdAt: string | null;
+    releases: Record<string, ReleaseRecord>;
+}
+/** The outcome of one registry read: data, a definite "no such package", or "could not reach it". */
+export type RegistryLookup<T> = {
+    status: "ok";
+    data: T;
+} | {
+    status: "not_found";
+    detail: string;
+} | {
+    status: "unreachable";
+    detail: string;
+};
+/** What dependency_check needs from a registry. Live readers and test fakes both implement it. */
+export interface ReleaseMetadataSource {
+    /**
+     * The package's release index. `wanted` names the versions the caller is
+     * about to read; a reader that pages (crates.io) may stop once it has them
+     * and the release just below `wanted[0]` on its line.
+     */
+    getReleases(name: string, wanted: string[]): Promise<RegistryLookup<PackageReleaseIndex>>;
+    /** When a package was first published (for a newly introduced transitive dependency). */
+    getCreatedAt(name: string): Promise<RegistryLookup<string | null>>;
+}

package/dist/live/release-metadata.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-release registry metadata, normalised across npm and crates.io.
+ *
+ * `dependency_check` judges ONE proposed version against the one installed
+ * (or, for a new dependency, against the previous release on the same line).
+ * That needs facts the version-freshness readers never kept: when each release
+ * was published, who/what published it, whether it runs install scripts, and
+ * which runtime dependencies it pulls in. Both registry readers project their
+ * 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.
+ */
+export {};

package/dist/live/resolution.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Dependency resolution that knows when it has gone stale.
+ *
+ * Measured 2026-09-10: three `node ./mcp-4da-server/dist/index.js` processes
+ * were live and two had started before the pull that brought hono 4.13.5.
+ * `vulnerability_scan` from one of them reported hono 4.13.3 (the lockfile
+ * value when it started) with `_meta.cached: false`. The live layer resolved
+ * versions once at init and never again, and `cached` described only the OSV
+ * lookup, so nothing in the answer could reveal that it was stale.
+ *
+ * A group records every file its resolution depended on as a stat signature:
+ * each lockfile candidate (present or absent, so one appearing or vanishing
+ * counts), the manifest when the resolver fell back to it, and for npm the
+ * node_modules install state. Signatures are taken BEFORE reading, so a write
+ * that lands mid-read still registers as a change. `resolveGroup` depends
+ * only on its inputs and the filesystem, so the SAME resolution can be re-run
+ * when a signature moves. Stat calls only: no timers, no watchers.
+ */
+import { type FileSignature } from "./file-signature.js";
+import type { InstallDriftRecord, ResolutionSourceRecord, ResolvedDependency } from "./types.js";
+/** The inputs of one resolution, kept so the same resolution can be re-run. */
+export interface ResolutionGroup {
+    dir: string;
+    language: string;
+    deps: string[];
+    devDeps: string[];
+    targets: Record<string, string>;
+}
+export interface GroupResolution {
+    group: ResolutionGroup;
+    /** Direct dependencies (dependency health, upgrade planning). */
+    resolved: ResolvedDependency[];
+    /** 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. */
+    source: ResolutionSourceRecord | null;
+    signatures: Map<string, FileSignature>;
+    resolvedAt: string;
+}
+export declare function resolveGroup(group: ResolutionGroup): GroupResolution;
+/** True when any file the resolution depended on changed, appeared, or vanished. */
+export declare function groupIsStale(result: GroupResolution): boolean;

package/dist/live/resolution.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Dependency resolution that knows when it has gone stale.
+ *
+ * Measured 2026-09-10: three `node ./mcp-4da-server/dist/index.js` processes
+ * were live and two had started before the pull that brought hono 4.13.5.
+ * `vulnerability_scan` from one of them reported hono 4.13.3 (the lockfile
+ * value when it started) with `_meta.cached: false`. The live layer resolved
+ * versions once at init and never again, and `cached` described only the OSV
+ * lookup, so nothing in the answer could reveal that it was stale.
+ *
+ * A group records every file its resolution depended on as a stat signature:
+ * each lockfile candidate (present or absent, so one appearing or vanishing
+ * counts), the manifest when the resolver fell back to it, and for npm the
+ * node_modules install state. Signatures are taken BEFORE reading, so a write
+ * that lands mid-read still registers as a change. `resolveGroup` depends
+ * only on its inputs and the filesystem, so the SAME resolution can be re-run
+ * when a signature moves. Stat calls only: no timers, no watchers.
+ */
+import { anySignatureChanged, signatureMap, signatureMtime } from "./file-signature.js";
+import { checkInstallState } from "./install-state.js";
+import { lockfileCandidates, manifestCandidate, resolveVersionSource } from "./lockfile-parsers.js";
+import { mapEcosystem, resolveAuditVersionsFrom, resolveVersionsFrom } from "./version-resolver.js";
+export function resolveGroup(group) {
+    const resolvedAt = new Date().toISOString();
+    const ecosystem = mapEcosystem(group.language);
+    const manifest = manifestCandidate(group.dir, ecosystem);
+    const signatures = signatureMap([
+        ...lockfileCandidates(group.dir, ecosystem),
+        ...(manifest ? [manifest] : []),
+    ]);
+    const read = resolveVersionSource(group.dir, ecosystem);
+    // 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")
+        signatures.delete(manifest);
+    let resolved = resolveVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets);
+    let drift = [];
+    let driftAudit = [];
+    // Only a lockfile pins exact versions; comparing node_modules against a
+    // manifest's specifier floor would report drift that is not there.
+    if (ecosystem === "npm" && read.kind === "lockfile" && read.source) {
+        const install = checkInstallState(group.dir, resolved, read.source);
+        resolved = install.resolved;
+        drift = install.drift;
+        driftAudit = install.driftAuditDeps;
+        for (const [file, signature] of install.signatures)
+            signatures.set(file, signature);
+    }
+    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 };
+}
+/** True when any file the resolution depended on changed, appeared, or vanished. */
+export function groupIsStale(result) {
+    return anySignatureChanged(result.signatures);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Semantic-version PRECEDENCE (semver.org section 11) for advisory range checks.
+ *
+ * `compareSemver` compares MAJOR.MINOR.PATCH only. That is the right tool for
+ * picking the highest of several fix versions and the wrong one for deciding
+ * whether an install sits inside an advisory range: it reads `5.0.0-rc.1` and
+ * `5.0.0-rc.2` as EQUAL, so an install at 5.0.0-rc.1 was judged outside
+ * `[5.0.0-beta.1, 5.0.0-rc.2)` — a range GHSA-82fw-gwwq-j7x9 really stores for
+ * vitest. Range checks use this comparator; `compareSemver` keeps its
+ * behaviour for its other callers.
+ *
+ * Parsing follows the Rust reference (`src-tauri/src/osv/matching.rs`
+ * `parse_version`, built on the `semver` crate): a leading `v` is dropped,
+ * `MAJOR.MINOR` reads as `MAJOR.MINOR.0`, and anything else that is not
+ * strict semver is unreadable (null) rather than guessed at.
+ */
+/** A parsed version, ordered by semver precedence. */
+export interface SemverPrecedence {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers; empty for a release. */
+    prerelease: string[];
+}
+/** Parse a version for precedence comparison, or null when it is not readable semver. */
+export declare function parseSemverPrecedence(version: string): SemverPrecedence | null;
+/** Semver precedence: 1 if a > b, -1 if a < b, 0 if equal. Build metadata is ignored. */
+export declare function comparePrecedence(a: SemverPrecedence, b: SemverPrecedence): number;
+/** Precedence of two version strings, or null when either is unreadable. */
+export declare function compareVersionPrecedence(a: string, b: string): number | null;

package/dist/live/semver-precedence.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Semantic-version PRECEDENCE (semver.org section 11) for advisory range checks.
+ *
+ * `compareSemver` compares MAJOR.MINOR.PATCH only. That is the right tool for
+ * picking the highest of several fix versions and the wrong one for deciding
+ * whether an install sits inside an advisory range: it reads `5.0.0-rc.1` and
+ * `5.0.0-rc.2` as EQUAL, so an install at 5.0.0-rc.1 was judged outside
+ * `[5.0.0-beta.1, 5.0.0-rc.2)` — a range GHSA-82fw-gwwq-j7x9 really stores for
+ * vitest. Range checks use this comparator; `compareSemver` keeps its
+ * behaviour for its other callers.
+ *
+ * Parsing follows the Rust reference (`src-tauri/src/osv/matching.rs`
+ * `parse_version`, built on the `semver` crate): a leading `v` is dropped,
+ * `MAJOR.MINOR` reads as `MAJOR.MINOR.0`, and anything else that is not
+ * strict semver is unreadable (null) rather than guessed at.
+ */
+const IDENT = "[0-9A-Za-z-]+";
+const STRICT = new RegExp(`^(\\d+)\\.(\\d+)\\.(\\d+)(?:-(${IDENT}(?:\\.${IDENT})*))?(?:\\+${IDENT}(?:\\.${IDENT})*)?$`);
+const TWO_PART = /^(\d+)\.(\d+)$/;
+/** Parse a version for precedence comparison, or null when it is not readable semver. */
+export function parseSemverPrecedence(version) {
+    const v = version.trim().replace(/^v+/, "");
+    const strict = STRICT.exec(v);
+    if (strict) {
+        return {
+            major: Number(strict[1]),
+            minor: Number(strict[2]),
+            patch: Number(strict[3]),
+            prerelease: strict[4] ? strict[4].split(".") : [],
+        };
+    }
+    const two = TWO_PART.exec(v);
+    return two ? { major: Number(two[1]), minor: Number(two[2]), patch: 0, prerelease: [] } : null;
+}
+/**
+ * Prerelease identifiers: numeric ones compare numerically and rank below
+ * alphanumeric ones; alphanumeric ones compare in ASCII order.
+ */
+function compareIdentifier(a, b) {
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+        // Compared as digit strings: an identifier may exceed Number's safe range.
+        const x = a.replace(/^0+(?=\d)/, "");
+        const y = b.replace(/^0+(?=\d)/, "");
+        if (x.length !== y.length)
+            return x.length > y.length ? 1 : -1;
+        return x === y ? 0 : x > y ? 1 : -1;
+    }
+    if (aNumeric)
+        return -1;
+    if (bNumeric)
+        return 1;
+    return a === b ? 0 : a > b ? 1 : -1;
+}
+/** Semver precedence: 1 if a > b, -1 if a < b, 0 if equal. Build metadata is ignored. */
+export function comparePrecedence(a, b) {
+    if (a.major !== b.major)
+        return a.major > b.major ? 1 : -1;
+    if (a.minor !== b.minor)
+        return a.minor > b.minor ? 1 : -1;
+    if (a.patch !== b.patch)
+        return a.patch > b.patch ? 1 : -1;
+    // A release outranks every prerelease of the same MAJOR.MINOR.PATCH.
+    if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+        return Math.sign(b.prerelease.length - a.prerelease.length);
+    }
+    const shared = Math.min(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < shared; i++) {
+        const cmp = compareIdentifier(a.prerelease[i], b.prerelease[i]);
+        if (cmp !== 0)
+            return cmp;
+    }
+    // A longer identifier list outranks its own prefix (1.0.0-alpha < 1.0.0-alpha.1).
+    return Math.sign(a.prerelease.length - b.prerelease.length);
+}
+/** Precedence of two version strings, or null when either is unreadable. */
+export function compareVersionPrecedence(a, b) {
+    const pa = parseSemverPrecedence(a);
+    const pb = parseSemverPrecedence(b);
+    return pa && pb ? comparePrecedence(pa, pb) : null;
+}