@4da/mcp-server 5.0.3 → 6.0.0

package/dist/live/index.js

@@ -12,12 +12,20 @@ import { LiveCache } from "./cache.js";
 import { RateLimiter, DEFAULT_RATE_LIMITS } from "./rate-limiter.js";
 import { OsvScanner } from "./osv-scanner.js";
 import { HNFetcher } from "./hn-fetcher.js";
-import { resolveAuditVersions, resolveVersions } from "./version-resolver.js";
 import { NpmRegistry } from "./npm-registry.js";
 import { CratesRegistry } from "./crates-registry.js";
 import { PyPIRegistry } from "./pypi-registry.js";
 import { GoRegistry } from "./go-registry.js";
+import { NpmPackumentReader } from "./npm-packument.js";
+import { CratesVersionsReader } from "./crates-versions.js";
+import { fetchRegistryHealthFor } from "./registry-health.js";
+import { commonPathRoot, dedupeDependencies, emptyVulnResult } from "./dependency-set.js";
+import { groupIsStale, resolveGroup } from "./resolution.js";
+import { applyInstanceDevScope } from "./dev-scope.js";
+/** Minimum gap between vulnerability warmup attempts after an offline result. */
+const WARMUP_RETRY_MS = 60_000;
 export class LiveIntelligence {
+    db;
     cache;
     rateLimiter;
     osvScanner;
@@ -26,14 +34,47 @@ export class LiveIntelligence {
     cratesRegistry;
     pypiRegistry;
     goRegistry;
+    npmPackuments;
+    cratesVersions;
     enabled;
     lastVulnScan = null;
+    /** Whether the stored scan included direct devDependencies. */
+    lastVulnScanIncludesDev = false;
+    /**
+     * Order of scan REQUESTS. A scan's result is stored only if no later request
+     * has stored one already: the init warmup (runtime scope) used to finish
+     * after an agent's `include_dev` scan and replace it, so `upgrade_planner`
+     * read a scan without the dev dependencies the agent had just scanned and
+     * sent node-fetch 2.6.0 to the ESM-only 3.3.2 with no advisories (2 of 6
+     * runs, 2026-10-03 pre-publish verification).
+     */
+    scanRequests = 0;
+    storedScanRequest = 0;
     lastHeadlines = [];
     resolvedDeps = [];
     auditDeps = [];
     initialized = false;
     projectRoot = null;
+    /** One entry per resolution group: its inputs, result, and the file signatures that say when it went stale. */
+    groupResults = [];
+    /** When the dependency set in use was assembled: at init, or at the last re-resolution. */
+    resolvedAt = null;
+    /**
+     * Bumped by every re-resolution. A scan started under an older generation
+     * describes a dependency set that no longer exists: it may still be handed
+     * to the call that asked for it, but it is never stored or served later.
+     */
+    generation = 0;
+    /**
+     * The background vulnerability scan started at server init. Tools that need
+     * scan data before answering (`what_should_i_know`) await this through
+     * `ensureVulnerabilities` instead of reading the cache and finding it empty.
+     */
+    warmup = null;
+    /** When the last warmup came back offline; gates the retry so an offline host is not re-probed on every call. */
+    warmupFailedAt = null;
     constructor(db) {
+        this.db = db;
         this.enabled = process.env.FOURDA_OFFLINE !== "true";
         this.cache = new LiveCache(db);
         this.rateLimiter = new RateLimiter(DEFAULT_RATE_LIMITS);
@@ -43,16 +84,15 @@ export class LiveIntelligence {
         this.cratesRegistry = new CratesRegistry(this.cache, this.rateLimiter);
         this.pypiRegistry = new PyPIRegistry(this.cache, this.rateLimiter);
         this.goRegistry = new GoRegistry(this.cache, this.rateLimiter);
+        this.npmPackuments = new NpmPackumentReader(this.cache, this.rateLimiter);
+        this.cratesVersions = new CratesVersionsReader(this.cache, this.rateLimiter);
     }
     /**
      * Initialize with project data. Call once after project scan.
      * @deprecated Use initFromMultiEcosystem for correct per-ecosystem resolution.
      */
     initFromProject(projectPath, deps, devDeps, language) {
-        this.resolvedDeps = resolveVersions(projectPath, deps, devDeps, language);
-        this.auditDeps = resolveAuditVersions(projectPath, deps, devDeps, language);
-        this.projectRoot = projectPath;
-        this.initialized = true;
+        this.applyGroups([{ dir: projectPath, language, deps, devDeps, targets: {} }], projectPath);
     }
     /**
      * Initialize with per-ecosystem project data. Resolves versions per language
@@ -60,16 +100,22 @@ export class LiveIntelligence {
      * Call once after project scan.
      */
     initFromMultiEcosystem(projectPath, depsByEcosystem, depTargets = {}) {
-        const allResolved = [];
-        const allAudit = [];
-        for (const [language, { deps, devDeps }] of Object.entries(depsByEcosystem)) {
-            allResolved.push(...resolveVersions(projectPath, deps, devDeps, language, depTargets));
-            allAudit.push(...resolveAuditVersions(projectPath, deps, devDeps, language, depTargets));
-        }
-        this.resolvedDeps = dedupeDependencies(allResolved);
-        this.auditDeps = dedupeDependencies(allAudit);
-        this.projectRoot = projectPath;
-        this.initialized = true;
+        const groups = Object.entries(depsByEcosystem).map(([language, { deps, devDeps }]) => ({
+            dir: projectPath,
+            language,
+            deps,
+            devDeps,
+            targets: depTargets,
+        }));
+        this.applyGroups(groups, projectPath);
+    }
+    /**
+     * Initialize from every independently-locked project under `root` (see
+     * project-tree.ts): each group resolves from its own directory and keeps
+     * its manifest's platform targets; `root` is the reported project root.
+     */
+    initFromProjectTree(root, groups) {
+        this.applyGroups(groups, root);
     }
     /**
      * Initialize from dependency groups that each carry their own resolution
@@ -82,17 +128,67 @@ export class LiveIntelligence {
      * is scanned once.
      */
     initFromDependencyGroups(groups) {
-        const allResolved = [];
-        const allAudit = [];
-        for (const { dir, language, deps, devDeps } of groups) {
-            allResolved.push(...resolveVersions(dir, deps, devDeps, language));
-            allAudit.push(...resolveAuditVersions(dir, deps, devDeps, language));
-        }
-        this.resolvedDeps = dedupeDependencies(allResolved);
-        this.auditDeps = dedupeDependencies(allAudit);
-        this.projectRoot = commonPathRoot(groups.map((g) => g.dir));
+        // Each resolver stamps `sourceDirs: [dir]` at the point of resolution, so
+        // the dedupe can union provenance instead of discarding it.
+        this.applyGroups(groups.map((g) => ({ ...g, targets: {} })), commonPathRoot(groups.map((g) => g.dir)));
+    }
+    applyGroups(groups, projectRoot) {
+        this.groupResults = groups.map(resolveGroup);
+        this.rebuildDependencySet();
+        this.projectRoot = projectRoot;
         this.initialized = true;
     }
+    rebuildDependencySet() {
+        this.resolvedDeps = dedupeDependencies(this.groupResults.flatMap((r) => r.resolved));
+        this.auditDeps = dedupeDependencies(this.groupResults.flatMap((r) => r.audit));
+        this.resolvedAt = new Date().toISOString();
+    }
+    /**
+     * Re-resolve every group whose inputs changed since they were read (a
+     * lockfile rewritten, created or deleted; the fallback manifest; for npm,
+     * the node_modules install state), and drop every answer that described the
+     * old set: the stored scan and the warmup. Returns true when anything was
+     * re-resolved. Stat calls only, so it is cheap enough for the top of every
+     * tool call. A process that started before a `git pull` no longer answers
+     * for the dependency set it saw at startup.
+     */
+    refreshIfLockfilesChanged() {
+        if (!this.initialized || this.groupResults.length === 0)
+            return false;
+        let changed = false;
+        this.groupResults = this.groupResults.map((result) => {
+            if (!groupIsStale(result))
+                return result;
+            changed = true;
+            return resolveGroup(result.group);
+        });
+        if (!changed)
+            return false;
+        this.rebuildDependencySet();
+        this.generation++;
+        this.lastVulnScan = null;
+        this.warmup = null;
+        this.warmupFailedAt = null;
+        return true;
+    }
+    /** When the dependency set in use was resolved, and from which files. Null before init. */
+    getResolutionProvenance() {
+        if (!this.initialized || !this.resolvedAt)
+            return null;
+        const seen = new Set();
+        const sources = [];
+        for (const result of this.groupResults) {
+            if (!result.source || seen.has(result.source.path))
+                continue;
+            seen.add(result.source.path);
+            sources.push(result.source);
+        }
+        return { resolvedAt: this.resolvedAt, sources };
+    }
+    /** npm direct dependencies whose installed copy differs from the lockfile, per manifest directory. */
+    getInstallDrift() {
+        return this.groupResults.flatMap((r) => r.drift);
+    }
     /**
      * Root directory the dependency set was resolved from, or null before init.
      * For multi-manifest (grouped) init this is the deepest common ancestor of
@@ -104,31 +200,147 @@ export class LiveIntelligence {
     }
     /**
      * Run vulnerability scan (returns cached if fresh, fetches otherwise).
+     *
+     * Without `includeDev`, only DIRECT devDependencies are left out (the
+     * documented contract). A transitive stays in whatever its scope: an
+     * unknown scope must not be hidden, and a known dev-only one is graded
+     * down by the shared severity rule, not dropped.
      */
     async scanVulnerabilities(projectPath, options) {
         if (!this.enabled) {
             return emptyVulnResult(projectPath, true);
         }
-        const deps = options?.includeDev
+        const scoped = options?.includeDev
             ? this.auditDeps
-            : this.auditDeps.filter((d) => !d.isDev);
+            : this.auditDeps.filter((d) => !(d.isDirect && d.isDev));
+        // Read at scan time, not init time: the app rewrites its inventory on
+        // every rescan, and the freshest determination is the one to grade by.
+        const deps = applyInstanceDevScope(this.db, scoped);
         if (deps.length === 0) {
             return emptyVulnResult(projectPath, false);
         }
         if (options?.forceRefresh) {
             this.cache.invalidateSource("osv");
         }
+        const generation = this.generation;
+        const request = ++this.scanRequests;
         try {
-            this.lastVulnScan = await this.osvScanner.scan(deps, projectPath);
-            return this.lastVulnScan;
+            const result = await this.osvScanner.scan(deps, projectPath);
+            if (generation === this.generation && request > this.storedScanRequest) {
+                this.lastVulnScan = result;
+                this.lastVulnScanIncludesDev = options?.includeDev ?? false;
+                this.storedScanRequest = request;
+            }
+            return result;
         }
         catch {
             // Network failure — return last known or empty
-            if (this.lastVulnScan)
+            if (generation === this.generation && this.lastVulnScan) {
                 return { ...this.lastVulnScan, offline: true, cached: true };
+            }
             return emptyVulnResult(projectPath, true);
         }
     }
+    /**
+     * Start the vulnerability scan in the background without blocking startup.
+     * Never rejects: a failed scan resolves to an empty OFFLINE result so the
+     * warmup can be awaited by anyone. Idempotent while a warmup is in flight.
+     *
+     * Before this existed, full-database mode initialised the dependency set
+     * and warmed headlines but never scanned, so `lastVulnScan` stayed null
+     * until some tool happened to call `vulnerability_scan` — and the first
+     * `what_should_i_know` of a session read an empty cache and reported
+     * "safe_to_delegate" for a task naming a package with an open advisory.
+     */
+    startVulnerabilityWarmup(projectPath) {
+        if (this.warmup)
+            return;
+        this.warmupFailedAt = null;
+        this.warmup = this.scanVulnerabilities(projectPath).catch(() => emptyVulnResult(projectPath, true));
+    }
+    /**
+     * A usable vulnerability scan, or null. Re-resolves first when a lockfile
+     * changed. Returns the stored scan when one exists, otherwise awaits the
+     * warmup (starting one if none is running) for at most `timeoutMs`. Null
+     * means the scan is not available: disabled, still running past the
+     * deadline, finished offline (an offline scan makes no clean-dependency
+     * claims, so it cannot support a "safe" verdict), or overtaken by a
+     * re-resolution while it ran. Never throws. A timed-out warmup keeps running
+     * so a later call can use it.
+     */
+    async ensureVulnerabilities(projectPath, timeoutMs, options) {
+        if (!this.enabled)
+            return null;
+        this.refreshIfLockfilesChanged();
+        const wantDev = options?.includeDev ?? false;
+        if (this.lastVulnScan && !this.lastVulnScan.offline && (!wantDev || this.lastVulnScanIncludesDev)) {
+            return this.lastVulnScan;
+        }
+        // A caller that needs direct devDependencies covered (a briefing whose task
+        // names a dev dependency) cannot use the runtime-scope warmup: it reported
+        // "vulnerabilities: []" for node-fetch 2.6.0, which has two advisories
+        // (2026-10-03 pre-publish verification). Scan at the wider scope, bounded.
+        if (wantDev)
+            return this.awaitScan(this.scanVulnerabilities(projectPath, { includeDev: true }), timeoutMs);
+        if (!this.warmup) {
+            if (this.warmupFailedAt !== null && Date.now() - this.warmupFailedAt < WARMUP_RETRY_MS) {
+                return null;
+            }
+            this.startVulnerabilityWarmup(projectPath);
+        }
+        const pending = this.warmup;
+        if (!pending)
+            return null;
+        const generation = this.generation;
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), Math.max(0, timeoutMs));
+        });
+        try {
+            const settled = await Promise.race([pending, deadline]);
+            if (settled === null)
+                return null; // still scanning; keep the warmup alive
+            // Re-resolved while waiting: that scan describes a set that no longer exists.
+            if (generation !== this.generation)
+                return null;
+            const result = this.lastVulnScan ?? settled;
+            if (result.offline) {
+                // Failed or rate-limited: allow a fresh attempt after the backoff.
+                this.warmup = null;
+                this.warmupFailedAt = Date.now();
+                return null;
+            }
+            return result;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /** A scan's result within `timeoutMs`, or null when it times out, comes back offline, or is overtaken by a re-resolution. */
+    async awaitScan(pending, timeoutMs) {
+        const generation = this.generation;
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), Math.max(0, timeoutMs));
+        });
+        try {
+            const settled = await Promise.race([pending, deadline]);
+            if (settled === null || generation !== this.generation || settled.offline)
+                return null;
+            return settled;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
     /**
      * Fetch relevant headlines for the user's tech stack.
      */
@@ -149,6 +361,10 @@ export class LiveIntelligence {
     getVulnerabilities() {
         return this.lastVulnScan;
     }
+    /** Whether the stored scan covered direct devDependencies (false when there is none). */
+    lastScanIncludesDev() {
+        return this.lastVulnScan !== null && this.lastVulnScanIncludesDev;
+    }
     /**
      * Get last headlines (from cache/memory, no network).
      */
@@ -171,63 +387,29 @@ export class LiveIntelligence {
         return this.initialized;
     }
     async fetchRegistryHealth(deps) {
-        if (!this.enabled) {
-            return deps.map((d) => ({
-                name: d.name, ecosystem: d.ecosystem, currentVersion: d.version,
-                latestVersion: null, latestStableVersion: null, versionsBehind: null,
-                deprecated: false, deprecationMessage: null, lastPublished: null,
-                license: null, weeklyDownloads: null, isDev: d.isDev, fetchError: "Offline mode",
-            }));
+        // Registries are read at call time (not captured at construction) so a
+        // test can substitute one.
+        return fetchRegistryHealthFor(deps, { npm: this.npmRegistry, crates: this.cratesRegistry, pypi: this.pypiRegistry, go: this.goRegistry }, this.enabled);
+    }
+    /** Per-release registry readers for dependency_check (name-only requests). */
+    getReleaseSources() {
+        return { npm: this.npmPackuments, "crates.io": this.cratesVersions };
+    }
+    /**
+     * OSV advisories for explicit (ecosystem, name, version) triples that need
+     * not be in the project, e.g. a version an agent is about to install. Same
+     * scanner, cache and rate limit as vulnerability_scan; never touches the
+     * stored project scan. Disabled or failed yields an `offline` result.
+     */
+    async queryAdvisories(deps) {
+        if (!this.enabled)
+            return emptyVulnResult("dependency_check", true);
+        try {
+            return await this.osvScanner.scan(deps, "dependency_check");
         }
-        const registryForEcosystem = (eco) => {
-            switch (eco) {
-                case "npm": return this.npmRegistry;
-                case "crates.io": return this.cratesRegistry;
-                case "PyPI": return this.pypiRegistry;
-                case "Go": return this.goRegistry;
-                default: return null;
-            }
-        };
-        const results = await Promise.all(deps.map(async (dep) => {
-            const registry = registryForEcosystem(dep.ecosystem);
-            if (!registry) {
-                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: `No registry fetcher for ${dep.ecosystem}`,
-                };
-            }
-            try {
-                return await registry.getPackageInfo(dep.name, dep.version, dep.isDev);
-            }
-            catch {
-                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: "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 this.npmRegistry.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
-            }
+        catch {
+            return emptyVulnResult("dependency_check", true);
         }
-        return results;
     }
     getStatus() {
         return {
@@ -240,58 +422,3 @@ export class LiveIntelligence {
         };
     }
 }
-/**
- * Deepest common ancestor of a set of directories (segment-wise, both slash
- * styles). Null for an empty set; a single dir is its own root.
- */
-function commonPathRoot(dirs) {
-    if (dirs.length === 0)
-        return null;
-    const split = (p) => p.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
-    let common = split(dirs[0]);
-    for (const dir of dirs.slice(1)) {
-        const parts = split(dir);
-        let i = 0;
-        while (i < common.length && i < parts.length && common[i].toLowerCase() === parts[i].toLowerCase())
-            i++;
-        common = common.slice(0, i);
-        if (common.length === 0)
-            break;
-    }
-    return common.length > 0 ? common.join("/") : null;
-}
-function dedupeDependencies(deps) {
-    const unique = new Map();
-    for (const dep of deps) {
-        const key = `${dep.ecosystem}\0${dep.name}\0${dep.version ?? ""}`;
-        const existing = unique.get(key);
-        if (existing) {
-            existing.isDirect ||= dep.isDirect;
-            existing.devScopeKnown &&= dep.devScopeKnown;
-            existing.isDev = existing.devScopeKnown && existing.isDev && dep.isDev;
-            // A crate reachable via ANY active path is active; keep a target label if present.
-            existing.platformActive ||= dep.platformActive;
-            existing.target = existing.target ?? dep.target;
-        }
-        else {
-            unique.set(key, { ...dep });
-        }
-    }
-    return [...unique.values()];
-}
-function emptyVulnResult(projectPath, offline) {
-    return {
-        scannedAt: new Date().toISOString(),
-        projectPath,
-        ecosystemsScanned: [],
-        totalScanned: 0,
-        totalVulnerable: 0,
-        platformInactiveVulnerable: 0,
-        bySeverity: { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 },
-        vulnerabilities: [],
-        cleanCount: 0,
-        scanDurationMs: 0,
-        cached: false,
-        offline,
-    };
-}

package/dist/live/install-state.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Install drift: what node_modules holds versus what the lockfile pins.
+ *
+ * Measured 2026-09-10: mcp-4da-server/pnpm-lock.yaml pinned hono 4.13.5 (PR
+ * #632, the fix for CVE-2026-84363/-84364/-84365) while
+ * mcp-4da-server/node_modules/hono held 4.13.1 for 25 days, because
+ * activation ran `pnpm install` only at the repo root. Every 4DA surface
+ * reported hono fixed, because every surface read the lockfile. A lockfile
+ * says what SHOULD be installed; only node_modules says what IS, and the
+ * installed copy is the one that runs.
+ */
+import { type FileSignature } from "./file-signature.js";
+import type { InstallDriftRecord, InstallFixCommand, ResolvedDependency } from "./types.js";
+/** The reinstall command for the lockfile a directory resolved from, or null for a non-npm file. */
+export declare function installFixFor(lockfilePath: string): InstallFixCommand | null;
+/**
+ * `<d>/node_modules/<name>/package.json` for the nearest `d` in the lookup
+ * chain that has it (scoped names included), or null. This is the copy
+ * Node's resolver would load from `dir`.
+ */
+export declare function findInstalledManifest(dir: string, name: string, chain?: string[]): string | null;
+/** The installed version of `name` as seen from `dir`, or null when not installed or unreadable. Never throws. */
+export declare function readInstalledVersion(dir: string, name: string): string | null;
+export interface InstallCheck {
+    /** The direct deps with `installedVersion` filled in; a new array, inputs untouched. */
+    resolved: ResolvedDependency[];
+    /** One record per direct dep whose installed copy differs from its lockfile version. */
+    drift: InstallDriftRecord[];
+    /** Audit entries for installed versions the lockfile does not pin, flagged `installDriftOf`. */
+    driftAuditDeps: ResolvedDependency[];
+    /** Signatures, taken BEFORE reading, of every file whose change means the install state moved. */
+    signatures: Map<string, FileSignature>;
+}
+/**
+ * Compare each npm direct dependency's lockfile version with node_modules.
+ *
+ * Skipped entirely when `dir` has no node_modules of its own: a checkout that
+ * was never installed has no installed copy to disagree with the lockfile,
+ * and borrowing a parent project's node_modules would compare against a
+ * different project's install. The node_modules path is still tracked, so an
+ * install that creates it is noticed.
+ */
+export declare function checkInstallState(dir: string, resolved: ResolvedDependency[], lockfilePath: string): InstallCheck;