@4da/mcp-server 5.0.3 → 6.0.0

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;
+}

package/dist/live/severity-scope.d.ts

@@ -0,0 +1,57 @@
+/**
+ * One severity rule for every surface (AD-046).
+ *
+ * The desktop app grades an advisory by where the vulnerable package sits in
+ * the dependency graph, and every 4DA surface presents that one grade. This
+ * module is the MCP server's copy of the rule. Its Rust twin is
+ * `osv::identity::scope_adjusted_urgency` (src-tauri/src/osv/identity.rs):
+ * change one, change both, or the MCP server and the app disagree about the
+ * same advisory again.
+ *
+ * Measured 2026-09-10: `vulnerability_scan` graded `sandbox@3.1.2` (a
+ * transitive of paddle-webhook, dev/runtime scope unknown) CRITICAL
+ * (`by_severity.critical: 1`, and the briefing read "CRITICAL: Sandbox
+ * Breakout") while the app graded the same advisory High.
+ *
+ * The rule, applied in this order:
+ *   (a) transitive-only clamps critical to high;
+ *   (b) dev-only drops ONE level: critical to high, high to medium, medium to
+ *       low; low stays low.
+ * `unknown` stays `unknown` through both steps. Unknown dev scope is not dev:
+ * no discount without evidence. The advisory's own tier is never discarded;
+ * surfaces carry it beside the presented grade as `advisory_severity`.
+ */
+import type { VulnerabilityEntry } from "./types.js";
+export type SeverityTier = VulnerabilityEntry["severity"];
+export interface DependencyScope {
+    isDirect: boolean;
+    isDev: boolean;
+    devScopeKnown: boolean;
+}
+/** Ordering for sorts and "at or above" filters; unknown ranks lowest. */
+export declare const SEVERITY_RANK: Record<SeverityTier, number>;
+/**
+ * THE rule. Twin of the Rust `osv::identity::scope_adjusted_urgency`.
+ *
+ * direct runtime critical -> critical; transitive runtime critical -> high;
+ * direct dev critical -> high; transitive dev critical -> medium;
+ * direct dev high -> medium; transitive dev high -> medium;
+ * transitive runtime high -> high.
+ */
+export declare function scopeAdjustedSeverity(advisory: SeverityTier, scope: DependencyScope): SeverityTier;
+type ScopedEntry = Pick<VulnerabilityEntry, "severity" | "isDirect" | "isDev" | "devScopeKnown">;
+/**
+ * The grade a surface presents for one scan entry. A missing `isDirect`
+ * (never produced today; defensive for foreign cache rows) is treated as
+ * direct, and a missing `devScopeKnown` as unknown: both mean no discount.
+ */
+export declare function presentedSeverity(v: ScopedEntry): SeverityTier;
+/**
+ * Why the presented grade differs from the advisory's own tier, in words, or
+ * null when it does not differ.
+ */
+export declare function scopeAdjustmentReason(v: ScopedEntry): string | null;
+export type SeverityCounts = Record<SeverityTier, number>;
+/** Count entries per tier, using whichever tier function the caller names. */
+export declare function countBySeverity<T>(entries: T[], tierOf: (entry: T) => SeverityTier): SeverityCounts;
+export {};

package/dist/live/severity-scope.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * One severity rule for every surface (AD-046).
+ *
+ * The desktop app grades an advisory by where the vulnerable package sits in
+ * the dependency graph, and every 4DA surface presents that one grade. This
+ * module is the MCP server's copy of the rule. Its Rust twin is
+ * `osv::identity::scope_adjusted_urgency` (src-tauri/src/osv/identity.rs):
+ * change one, change both, or the MCP server and the app disagree about the
+ * same advisory again.
+ *
+ * Measured 2026-09-10: `vulnerability_scan` graded `sandbox@3.1.2` (a
+ * transitive of paddle-webhook, dev/runtime scope unknown) CRITICAL
+ * (`by_severity.critical: 1`, and the briefing read "CRITICAL: Sandbox
+ * Breakout") while the app graded the same advisory High.
+ *
+ * The rule, applied in this order:
+ *   (a) transitive-only clamps critical to high;
+ *   (b) dev-only drops ONE level: critical to high, high to medium, medium to
+ *       low; low stays low.
+ * `unknown` stays `unknown` through both steps. Unknown dev scope is not dev:
+ * no discount without evidence. The advisory's own tier is never discarded;
+ * surfaces carry it beside the presented grade as `advisory_severity`.
+ */
+const ONE_LEVEL_DOWN = {
+    critical: "high",
+    high: "medium",
+    medium: "low",
+    low: "low",
+    unknown: "unknown",
+};
+/** Ordering for sorts and "at or above" filters; unknown ranks lowest. */
+export const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    unknown: 0,
+};
+/**
+ * THE rule. Twin of the Rust `osv::identity::scope_adjusted_urgency`.
+ *
+ * direct runtime critical -> critical; transitive runtime critical -> high;
+ * direct dev critical -> high; transitive dev critical -> medium;
+ * direct dev high -> medium; transitive dev high -> medium;
+ * transitive runtime high -> high.
+ */
+export function scopeAdjustedSeverity(advisory, scope) {
+    let tier = advisory;
+    if (!scope.isDirect && tier === "critical")
+        tier = "high";
+    if (scope.devScopeKnown && scope.isDev)
+        tier = ONE_LEVEL_DOWN[tier];
+    return tier;
+}
+/**
+ * The grade a surface presents for one scan entry. A missing `isDirect`
+ * (never produced today; defensive for foreign cache rows) is treated as
+ * direct, and a missing `devScopeKnown` as unknown: both mean no discount.
+ */
+export function presentedSeverity(v) {
+    return scopeAdjustedSeverity(v.severity, {
+        isDirect: v.isDirect !== false,
+        isDev: v.isDev === true,
+        devScopeKnown: v.devScopeKnown === true,
+    });
+}
+/**
+ * Why the presented grade differs from the advisory's own tier, in words, or
+ * null when it does not differ.
+ */
+export function scopeAdjustmentReason(v) {
+    if (presentedSeverity(v) === v.severity)
+        return null;
+    const transitive = v.isDirect === false;
+    const dev = v.devScopeKnown === true && v.isDev === true;
+    if (transitive && dev)
+        return "transitive, dev-only dependency";
+    if (dev)
+        return "dev-only dependency";
+    return "transitive-only dependency";
+}
+/** Count entries per tier, using whichever tier function the caller names. */
+export function countBySeverity(entries, tierOf) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+    for (const entry of entries)
+        counts[tierOf(entry)]++;
+    return counts;
+}

package/dist/live/types.d.ts

@@ -1,4 +1,6 @@
 export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist" | "Pub";
+/** The reinstall command that brings node_modules back in line with a directory's lockfile. */
+export type InstallFixCommand = "pnpm install" | "npm ci" | "yarn install" | "bun install";
 export interface ResolvedDependency {
     name: string;
     version: string | null;
@@ -10,6 +12,56 @@ export interface ResolvedDependency {
     target: string | null;
     /** False when `target` is not active on the host platform (advisory is not relevant). */
     platformActive: boolean;
+    /**
+     * Manifest directories this exact (ecosystem, name, version) resolved from.
+     *
+     * A scan root can span several independent workspaces — `src-tauri/`,
+     * `relay/`, `victauri-gauntlet/` all sit under one repo and pin their own
+     * versions. Without this, dedupe collapsed them and the report named a
+     * vulnerable version with no way to say WHICH workspace pinned it, so a
+     * patched primary crate looked vulnerable because a sibling lagged.
+     */
+    sourceDirs: string[];
+    /**
+     * npm DIRECT deps resolved from a lockfile only: the version node_modules
+     * actually holds (walking up for hoisted workspaces), or null when it is not
+     * installed or unreadable. Undefined when the check did not run (another
+     * ecosystem, no node_modules, or versions read from a manifest).
+     */
+    installedVersion?: string | null;
+    /**
+     * Set on the extra audit entry that asks OSV about an INSTALLED version the
+     * lockfile does not pin: the lockfile's version of the same package. The
+     * entry exists so `vulnerable_installed` is OSV's answer, not a guess.
+     */
+    installDriftOf?: string;
+    /** On drift entries: the command that reinstalls from the lockfile. */
+    installFix?: InstallFixCommand;
+}
+/**
+ * One npm direct dependency whose installed copy differs from its lockfile.
+ * `dir` is the manifest directory, spelled as the resolution group spells it.
+ */
+export interface InstallDriftRecord {
+    package: string;
+    dir: string;
+    lockfileVersion: string;
+    installedVersion: string;
+    fix: InstallFixCommand;
+    isDev: boolean;
+}
+/** A file one resolution group read its versions from. */
+export interface ResolutionSourceRecord {
+    /** Absolute path. */
+    path: string;
+    kind: "lockfile" | "manifest";
+    /** Modification time when it was read, or null if it vanished since. */
+    mtimeMs: number | null;
+}
+/** When the dependency set in use was assembled, and from which files. */
+export interface ResolutionProvenance {
+    resolvedAt: string;
+    sources: ResolutionSourceRecord[];
 }
 /**
  * An OSV record. The `/v1/querybatch` endpoint returns only `{ id, modified }`
@@ -71,6 +123,19 @@ export interface VulnerabilityEntry {
     target: string | null;
     /** False when the affected dep is not active on the host platform. */
     platformActive: boolean;
+    /**
+     * Manifest directories that pin this vulnerable version. Answers the first
+     * question a reader asks — *which project do I go fix?* — which a flat
+     * package-name list cannot.
+     */
+    sourceDirs: string[];
+    /**
+     * Set when this row is about an INSTALLED version the lockfile does not pin
+     * (node_modules drift): the lockfile's version of the same package.
+     */
+    installDriftOf?: string;
+    /** On drift rows: the command that reinstalls from the lockfile. */
+    installFix?: InstallFixCommand;
 }
 export interface VulnerabilityScanResult {
     scannedAt: string;
@@ -126,6 +191,12 @@ export interface RegistryPackageInfo {
     weeklyDownloads: number | null;
     isDev: boolean;
     fetchError: string | null;
+    /**
+     * The version node_modules actually holds, present only when it differs
+     * from `currentVersion` (the lockfile's). Several differing installs across
+     * workspaces are listed comma-separated.
+     */
+    installedVersion?: string;
 }
 export interface SemverDistance {
     major: number;
@@ -140,7 +211,19 @@ export interface DependencyHealthResult {
     totalDeps: number;
     outdatedCount: number;
     deprecatedCount: number;
+    /**
+     * Distinct packages with an advisory that is built on this host and is not a
+     * maintenance notice — the same set `vulnerability_scan` reports as
+     * `total_vulnerable_packages`, so the two tools agree over one scan.
+     */
     vulnerableCount: number;
+    /**
+     * Every advisory row the scan returned, before the platform and maintenance
+     * splits and before alias collapsing. Present so nothing is hidden by the
+     * `vulnerableCount` filter: the difference is platform-inactive packages and
+     * unmaintained-dependency notices.
+     */
+    advisoryCount: number;
     healthScore: number;
     dependencies: RegistryPackageInfo[];
     vulnerabilitySummary: {

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

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ *
+ * 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
+ * is large (vite's is ~39 MB, measured 2026-10-02), so only a reduced index
+ * 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";
+/** 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 {
+    version: string;
+    published: string | null;
+    deprecated?: string;
+    yanked?: boolean;
+    /** Archive URL (npm `dist.tarball`); crates archives are derived from name + version. */
+    tarball?: string;
+}
+export interface RegistryIndex {
+    /** The registry's canonical spelling (crates.io folds `-`/`_`). */
+    name: string;
+    ecosystem: UpgradeEcosystem;
+    versions: PublishedVersion[];
+    repository: string | null;
+}
+export interface ChangelogResult {
+    found: boolean;
+    file?: string;
+    sections?: ChangelogSection[];
+    reason?: string;
+}
+/** The cache surface used here; `LiveCache` satisfies it. */
+export interface UpgradeCache {
+    get<T>(key: string): T | null;
+    set(key: string, data: unknown, source: string, ttlSeconds: number): void;
+}
+/** Network + cache seam. `contacted` collects every host actually requested. */
+export interface UpgradeNet {
+    fetch: FetchFn;
+    cache: UpgradeCache | null;
+    contacted: Set<string>;
+}
+export declare function createUpgradeNet(cache: UpgradeCache | null, fetchFn?: FetchFn): UpgradeNet;
+export declare function isValidPackageName(name: string, ecosystem: UpgradeEcosystem): boolean;
+/** Registry index with versions in ascending precedence order (unreadable versions dropped). Null = unknown package. */
+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;
+/** 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. */
+export declare function getOsvAdvisories(net: UpgradeNet, ecosystem: UpgradeEcosystem, name: string, version: string): Promise<string[] | null>;
+/**
+ * Release-notes page derived from the registry's own `repository` field: a
+ * GitHub repo becomes `https://github.com/<owner>/<repo>/releases`; any other
+ * https repository URL is returned as-is; anything else is null.
+ */
+export declare function releaseNotesUrl(repository: string | null): string | null;