@4da/mcp-server 5.0.4 → 6.0.0

package/dist/tools/vulnerability-scan.js

@@ -5,18 +5,28 @@
  * Scans project dependencies for known vulnerabilities using OSV.dev.
  * Zero configuration — auto-detects stack from manifest files.
  * Returns CVEs, severity, fix versions across npm, Rust, Python, Go.
+ * Output shaping lives in vulnerability-scan-format.ts.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { LiveIntelligence } from "../live/index.js";
-import { scanCurrentProject } from "../project-scanner.js";
-import { hostTarget } from "../live/platform.js";
-import { maxSemver } from "../live/semver-utils.js";
+import { scanProjectTree, treeResolutionGroups } from "../project-tree.js";
+import { isMaintenanceNotice } from "../live/maintenance.js";
+import { namesPackage } from "../live/version-compare.js";
+import { emptyAnswerNote, packagePresence } from "./package-presence.js";
+import { conciseScanResult } from "./vulnerability-scan-concise.js";
+import { formatScanResult } from "./vulnerability-scan-format.js";
+// The predicate lives in live/maintenance.ts so every scan consumer shares
+// one definition; re-exported here, with the formatters, for existing importers.
+export { isMaintenanceNotice };
+export { collapseAliases, platformFilterNote, relativeDir } from "./vulnerability-scan-format.js";
 export const vulnerabilityScanTool = {
     name: "vulnerability_scan",
     description: "Scan project dependencies for known vulnerabilities (CVEs) using OSV.dev. " +
         "Returns severity, fix versions, and upgrade recommendations for npm, Rust, Python, and Go. " +
-        "Zero config — scans the complete resolvable lockfile package set, including transitives. " +
+        "Zero config — scans the complete resolvable lockfile package set, including transitives, and for npm also the version node_modules actually holds when it differs from the lockfile (install_drift). " +
+        "`severity` is the scope-adjusted grade the 4DA app presents; `advisory_severity` keeps the advisory's own tier. " +
+        "`_meta.cached` (= `_meta.osv_cached`) refers to the OSV advisory lookup, not to dependency resolution: versions are re-read whenever a lockfile changes, and `_meta.resolution` says from which files and when. " +
         "Privacy: only sends package names and versions (public manifest data).",
     inputSchema: {
         type: "object",
@@ -28,7 +38,7 @@ export const vulnerabilityScanTool = {
             severity_filter: {
                 type: "string",
                 enum: ["critical", "high", "medium", "low"],
-                description: "Only show vulnerabilities at or above this severity level.",
+                description: "Only show vulnerabilities whose presented severity is at or above this level.",
             },
             include_dev: {
                 type: "boolean",
@@ -36,18 +46,20 @@ export const vulnerabilityScanTool = {
             },
             force_refresh: {
                 type: "boolean",
-                description: "Ignore cache and fetch fresh data from OSV.dev. Default: false.",
+                description: "Ignore the OSV advisory cache and fetch fresh advisory data from OSV.dev (dependency versions are re-read on every lockfile change regardless). Default: false.",
+            },
+            package: {
+                type: "string",
+                description: "Only this package (any ecosystem, every installed copy, transitives included), with a `package_note` saying what the lockfiles hold for it. Use it to ask about one dependency instead of reading the whole report.",
+            },
+            response_format: {
+                type: "string",
+                enum: ["concise", "detailed"],
+                description: "concise (default): one row per vulnerable package version (worst severity, the version that fixes all its advisories, advisory count and first ids, where it is pinned), the 40 most severe and 25 recommendations, with counts of anything left out. detailed: one row per advisory with references, plus platform-inactive advisories, maintenance notices, install drift and resolution provenance.",
             },
         },
     },
 };
-const SEVERITY_ORDER = {
-    critical: 4,
-    high: 3,
-    medium: 2,
-    low: 1,
-    unknown: 0,
-};
 export async function executeVulnerabilityScan(db, params, liveIntelligence) {
     if (!liveIntelligence || !liveIntelligence.isEnabled()) {
         return {
@@ -57,12 +69,27 @@ export async function executeVulnerabilityScan(db, params, liveIntelligence) {
             hint: "4DA queries OSV.dev with your dependency names and versions (public manifest data). No personal data is transmitted.",
         };
     }
-    const projectPath = params.project_path || process.cwd();
+    // The project the server was started for (FOURDA_PROJECT_DIR, else cwd) —
+    // not process.cwd(), which under Claude Desktop is the app's own directory.
+    const defaultRoot = liveIntelligence.getProjectRoot() ?? process.cwd();
+    const projectPath = params.project_path ? path.resolve(params.project_path) : defaultRoot;
+    if (params.project_path && !isDirectory(projectPath)) {
+        return {
+            error: `project_path "${params.project_path}" is not a directory on this machine. Pass the absolute path of a project root, or omit it to scan ${defaultRoot}.`,
+        };
+    }
     let scanner = liveIntelligence;
-    if (normalizedPath(projectPath) !== normalizedPath(process.cwd())) {
-        const scan = scanCurrentProject(projectPath);
+    let reResolvedThisCall = false;
+    if (normalizedPath(projectPath) !== normalizedPath(defaultRoot)) {
+        // Every independently-locked project under the requested root, as at startup.
         scanner = new LiveIntelligence(db.getRawDb());
-        scanner.initFromMultiEcosystem(projectPath, scan.depsByEcosystem, scan.depTargets);
+        scanner.initFromProjectTree(projectPath, treeResolutionGroups(scanProjectTree(projectPath)));
+    }
+    else {
+        // A long-lived server must not answer from the versions it read at
+        // startup (2026-09-10: one reported hono 4.13.3 after the lockfile said
+        // 4.13.5). Stat calls only; re-resolves when a lockfile changed.
+        reResolvedThisCall = liveIntelligence.refreshIfLockfilesChanged();
     }
     if (!scanner.isInitialized()) {
         return {
@@ -71,27 +98,58 @@ export async function executeVulnerabilityScan(db, params, liveIntelligence) {
             message: "No project dependencies detected. Ensure manifest files (package.json, Cargo.toml, etc.) exist in your project.",
         };
     }
-    const result = await scanner.scanVulnerabilities(projectPath, {
-        includeDev: params.include_dev || false,
+    const includeDev = params.include_dev || false;
+    const scanned = await scanner.scanVulnerabilities(projectPath, {
+        includeDev,
         forceRefresh: params.force_refresh || false,
     });
-    if (result.totalScanned === 0 && !result.offline) {
-        const hint = diagnoseMissingVersions(projectPath);
-        return {
-            ...formatResult(result, params.severity_filter),
-            note: hint,
-        };
+    // One package's findings without the whole report. In the 2026-10-03 agent
+    // eval, asking about one transitive meant `response_format: "detailed"` on
+    // nodegoat: 225k characters, refused by the host and grepped from a file.
+    const only = params.package?.trim();
+    const result = only
+        ? { ...scanned, vulnerabilities: scanned.vulnerabilities.filter((v) => namesPackage(only, v.package, v.ecosystem)) }
+        : scanned;
+    const drift = scanner.getInstallDrift();
+    const full = formatScanResult(result, params.severity_filter, {
+        resolution: scanner.getResolutionProvenance(),
+        reResolvedThisCall,
+        drift: only ? drift.filter((r) => namesPackage(only, r.package, "npm")) : drift,
+        includeDev,
+    });
+    const formatted = params.response_format === "detailed" ? full : conciseScanResult(full);
+    const withNote = only ? { ...formatted, package_note: packageNote(only, scanner, result, includeDev) } : formatted;
+    if (scanned.totalScanned === 0 && !scanned.offline) {
+        return { ...withNote, note: diagnoseMissingVersions(projectPath) };
+    }
+    return withNote;
+}
+/** What the lockfiles hold for `query`, so "no findings" is never confused with "not a dependency". */
+function packageNote(query, scanner, result, includeDev) {
+    if (result.vulnerabilities.length > 0) {
+        const p = packagePresence(query, scanner);
+        return `${p.name ?? query} ${p.versions.join(", ")} (${p.scope ?? "in the scan"}): findings below.`;
     }
-    return formatResult(result, params.severity_filter);
+    const checked = result.offline ? "OSV was unreachable, so its advisories are unverified" : "no known advisories";
+    return `${emptyAnswerNote(query, scanner, includeDev, checked)}.`;
 }
 function normalizedPath(value) {
     return path.resolve(value).replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
 }
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function diagnoseMissingVersions(projectPath) {
     const lockFiles = {
         "package-lock.json": "npm install",
         "pnpm-lock.yaml": "pnpm install",
         "yarn.lock": "yarn install",
+        "bun.lock": "bun install",
         "Cargo.lock": "cargo build",
         "poetry.lock": "poetry install",
         "Pipfile.lock": "pipenv install",
@@ -114,102 +172,3 @@ function diagnoseMissingVersions(projectPath) {
     }
     return "Lock file found but no dependency versions could be resolved. The lock file format may be unsupported or corrupted.";
 }
-function formatResult(result, severityFilter) {
-    let vulns = result.vulnerabilities;
-    // Apply severity filter
-    if (severityFilter) {
-        const minOrder = SEVERITY_ORDER[severityFilter] || 0;
-        vulns = vulns.filter((v) => (SEVERITY_ORDER[v.severity] || 0) >= minOrder);
-    }
-    // Sort: critical first, then high, etc.
-    vulns.sort((a, b) => (SEVERITY_ORDER[b.severity] || 0) - (SEVERITY_ORDER[a.severity] || 0));
-    // Relevance split: advisories on deps NOT active on the host platform are not
-    // actionable for this user (e.g. a Linux-only crate's CVE shown to a Windows
-    // dev). Keep them, but separated and labeled so they don't pollute the signal.
-    const active = vulns.filter((v) => v.platformActive !== false);
-    const inactive = vulns.filter((v) => v.platformActive === false);
-    // Recommendations are derived from platform-active vulns only.
-    const recommendations = [];
-    const byPackage = new Map();
-    for (const v of active) {
-        if (!byPackage.has(v.package))
-            byPackage.set(v.package, []);
-        byPackage.get(v.package).push(v);
-    }
-    for (const [pkg, pkgVulns] of byPackage) {
-        const highest = pkgVulns[0];
-        const breakdown = severityBreakdown(pkgVulns);
-        // Target the HIGHEST published fix so the upgrade resolves every fixable CVE,
-        // not just the first one. (The old code picked the first fix version, which
-        // could leave higher-version-gated CVEs unfixed while claiming to fix them.)
-        const target = maxSemver(pkgVulns.map((v) => v.fixedVersion).filter((v) => Boolean(v)));
-        const total = pkgVulns.length;
-        const fixable = pkgVulns.filter((v) => v.fixedVersion).length;
-        if (target) {
-            const scope = fixable === total
-                ? `${total} CVE${total > 1 ? "s" : ""}`
-                : `${fixable} of ${total} CVEs (${total - fixable} with no published fix)`;
-            recommendations.push(`Upgrade ${pkg} ${highest.currentVersion} \u2192 ${target} \u2014 resolves ${scope} [${breakdown}]`);
-        }
-        else {
-            recommendations.push(`Review ${pkg} ${highest.currentVersion} \u2014 ${total} known vulnerabilit${total > 1 ? "ies" : "y"} [${breakdown}], no fix version published`);
-        }
-    }
-    const host = hostTarget();
-    const activePackages = new Set(active.map((v) => v.package)).size;
-    return {
-        scan_time: result.scannedAt,
-        project: result.projectPath.split(/[/\\]/).pop() || result.projectPath,
-        host_platform: `${host.os}/${host.arch}`,
-        ecosystems_scanned: result.ecosystemsScanned,
-        total_dependencies_scanned: result.totalScanned,
-        total_vulnerable_packages: activePackages,
-        platform_inactive_packages: result.platformInactiveVulnerable,
-        by_severity: result.bySeverity,
-        vulnerabilities: active.map(formatVuln),
-        // Advisories suppressed from the main list because the affected crate is not
-        // built on this host (e.g. cfg(not(windows)) deps on Windows). Surfaced for
-        // cross-platform builds, clearly labeled with the gating target.
-        platform_inactive_vulnerabilities: inactive.map(formatVuln),
-        recommendations,
-        clean_dependencies: result.cleanCount,
-        scan_duration_ms: result.scanDurationMs,
-        _meta: {
-            source: "osv.dev",
-            cached: result.cached,
-            offline: result.offline,
-            privacy: "Only package names and versions were sent (public manifest data)",
-            relevance: "Advisories are filtered to the host platform; inactive-target advisories are listed separately.",
-        },
-    };
-}
-/** "1 critical, 3 high, 2 medium" — severity-ordered, omitting empty buckets. */
-function severityBreakdown(vulns) {
-    const counts = {};
-    for (const v of vulns)
-        counts[v.severity] = (counts[v.severity] || 0) + 1;
-    return ["critical", "high", "medium", "low", "unknown"]
-        .filter((s) => counts[s])
-        .map((s) => `${counts[s]} ${s}`)
-        .join(", ");
-}
-function formatVuln(v) {
-    return {
-        package: v.package,
-        current_version: v.currentVersion,
-        ecosystem: v.ecosystem,
-        is_dev: v.isDev,
-        is_direct: v.isDirect ?? null,
-        dev_scope_known: v.devScopeKnown ?? false,
-        target: v.target,
-        platform_active: v.platformActive,
-        vuln_id: v.vulnId,
-        aliases: v.aliases,
-        severity: v.severity,
-        cvss_score: v.cvssScore,
-        summary: v.summary,
-        fixed_version: v.fixedVersion,
-        published: v.published,
-        references: v.references,
-    };
-}

package/dist/tools/what-should-i-know.d.ts

@@ -1,14 +1,27 @@
 /**
  * what_should_i_know tool
  *
- * Pre-task intelligence briefing for AI coding agents. Synthesizes:
- * - Live vulnerability data + actionable signals
- * - Decision windows (time-bounded opportunities)
- * - Ecosystem news (HN headlines relevant to tech stack)
+ * Pre-task briefing for AI coding agents, built from the task outward:
+ * - the dependencies the task names, with their installed versions, the
+ *   version-confirmed vulnerabilities on those versions, releases since, and
+ *   how far the requested upgrade jumps;
+ * - this project's other version-confirmed findings, counted separately;
+ * - recorded decisions and decision windows relevant to the task;
+ * - a delegation verdict that ONLY version-confirmed evidence about the task
+ *   (or install drift actually running) can raise.
  *
- * Filters everything for relevance to the described task and involved files.
+ * Measured 2026-10-01 (live), the old briefing for "bump fastembed 5 -> 7":
+ * eleven advisories, none about fastembed — an arXiv dataset paper, three
+ * OpenAI-company news items matched to the `openai` npm package of another
+ * project, Angular and russh CVEs no project uses — and `human_only`, because
+ * any high "security" keyword match anywhere forced it. Feed classifications
+ * were ~5-15% precise as security alerts (154 in 14 days; the relevance judge
+ * accepted 10). They no longer decide anything here.
  */
 import type { FourDADatabase } from "../db.js";
+import type { LiveIntelligence } from "../live/index.js";
+import { advisoriesFor, judgedReadingFor, releasesFor } from "./briefing-task-scope.js";
+import { type WisdomEntry, type WisdomRecallMode } from "./briefing-wisdom.js";
 export interface WhatShouldIKnowParams {
     task: string;
     files?: string[];
@@ -19,6 +32,10 @@ interface Advisory {
     priority: string;
     action: string;
     url: string | null;
+    /** `task`: about a dependency this task names. `project`: elsewhere in this project. */
+    scope: "task" | "project";
+    /** True when matched against the installed version (OSV scan); false for an advisory feed row naming the package. */
+    version_confirmed: boolean;
 }
 interface DecisionWindow {
     id: number;
@@ -26,33 +43,83 @@ interface DecisionWindow {
     description: string | null;
     urgency: number;
 }
-interface WisdomEntry {
-    type: string;
-    subject: string;
-    detail: string;
+/** What the briefing knows about one dependency the task names. */
+interface TaskDependency {
+    package: string;
+    ecosystem: string;
+    installed: string[];
+    direct: boolean;
+    dev_only: boolean;
+    requested: {
+        from: string | null;
+        to: string | null;
+    };
+    /** Major versions the requested upgrade crosses, when both ends are known. */
+    majors_crossed: number | null;
+    vulnerabilities: ReturnType<typeof advisoriesFor>;
+    /** Registry releases newer than the installed version that the 4DA feed recorded (desktop app only). */
+    newer_releases: ReturnType<typeof releasesFor>;
+    next_step: string;
 }
-interface EcosystemNewsItem {
-    title: string;
-    url: string | null;
-    points: number;
-    relevance_reason: string;
+/**
+ * "unknown" is the verdict when the vulnerability scan could not be consulted:
+ * the briefing has not reviewed the task, which is a different claim from
+ * "reviewed and found nothing". "safe_to_delegate" is only ever emitted over a
+ * ready scan.
+ */
+export type DelegationLevel = "safe_to_delegate" | "review_needed" | "human_only" | "unknown";
+/**
+ * Whether the live vulnerability scan backed this briefing.
+ * - ready:       a completed, online scan was consulted
+ * - unavailable: live intelligence is on but the scan is still running past
+ *                the wait budget, finished offline, or covered no resolvable
+ *                dependency versions
+ * - disabled:    no live intelligence (FOURDA_OFFLINE, or not initialised)
+ */
+export type ScanStatus = "ready" | "unavailable" | "disabled";
+/** What backed the briefing's vulnerability claims, and how current it is. */
+export interface BriefingScan {
+    status: ScanStatus;
+    /** When the scan the briefing read ran, or null when none backed it. */
+    scanned_at: string | null;
+    /** When the dependency versions it covers were read from the lockfiles. */
+    resolved_at: string | null;
+    /** True when this call noticed a changed lockfile and re-resolved first. */
+    re_resolved_this_call: boolean;
 }
-type DelegationLevel = "safe_to_delegate" | "review_needed" | "human_only";
-interface WhatShouldIKnowResult {
+export interface WhatShouldIKnowResult {
     task: string;
     files: string[];
+    task_dependencies: TaskDependency[];
     advisories: Advisory[];
     decision_windows: DecisionWindow[];
     relevant_wisdom: WisdomEntry[];
-    ecosystem_news: EcosystemNewsItem[];
+    decision_conflicts: Array<{
+        technology: string;
+        decision_id: number;
+        reason: string;
+    }>;
+    related_reading: ReturnType<typeof judgedReadingFor>;
     delegation_assessment: {
         level: DelegationLevel;
         reason: string;
     };
+    /** Kept for existing callers; `scan.status` carries the same value. */
+    scan_status: ScanStatus;
+    scan: BriefingScan;
     summary: string;
     /** How relevant_wisdom was retrieved: "hybrid" when an embedding provider is active. */
-    wisdom_recall_mode: "hybrid" | "ranked_lexical";
+    wisdom_recall_mode: WisdomRecallMode;
+    _meta: {
+        untrusted_text: string;
+    };
 }
+/**
+ * The slice of the live layer the briefing reads; a stub suffices in tests.
+ * Re-resolution, provenance and the dependency lists are optional so a
+ * minimal stub still works (no dependencies means no task packages).
+ */
+export type BriefingLiveIntel = Pick<LiveIntelligence, "ensureVulnerabilities" | "isEnabled" | "getProjectRoot"> & Partial<Pick<LiveIntelligence, "refreshIfLockfilesChanged" | "getResolutionProvenance" | "getResolvedDeps" | "getAuditDeps" | "getVulnerabilities" | "getHeadlines">>;
 export declare const whatShouldIKnowTool: {
     name: string;
     description: string;
@@ -74,5 +141,5 @@ export declare const whatShouldIKnowTool: {
         required: string[];
     };
 };
-export declare function executeWhatShouldIKnow(db: FourDADatabase, params: WhatShouldIKnowParams): WhatShouldIKnowResult | Promise<WhatShouldIKnowResult>;
+export declare function executeWhatShouldIKnow(db: FourDADatabase, params: WhatShouldIKnowParams, liveIntel?: BriefingLiveIntel | null): Promise<WhatShouldIKnowResult>;
 export {};