@4da/mcp-server 6.0.1 → 6.1.0

package/dist/index.js

@@ -51,7 +51,8 @@ import { validateToolArgs } from "./tool-args.js";
 // Tool registry: listing, schema resources, category metadata
 import { getCategoryManifest, getSchemaResources, getSlimToolList, getToolSchemaDocument, hasToolSchema, TOOL_REGISTRY, } from "./schema-registry.js";
 // Map-based tool dispatch (replaces per-tool imports + switch statement)
-import { dispatchTool } from "./tool-dispatch.js";
+import { DATABASE_FREE_TOOLS, dispatchTool } from "./tool-dispatch.js";
+import { SqliteUnavailableError, sqliteDriverStatus } from "./sqlite-driver.js";
 import { getPrompt, listPrompts } from "./prompts.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -68,7 +69,7 @@ const SERVER_VERSION = (() => {
         return "0.0.0";
     }
 })();
-import { createDatabase, DEPENDENCY_GROUP_QUERY, FourDADatabase } from "./db.js";
+import { createDatabase, DEPENDENCY_GROUP_QUERY, FourDADatabase, isUnreadableDbError, unreadableDbMessage, } from "./db.js";
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -107,7 +108,7 @@ function getDatabase() {
             const cwd = resolveProjectDir();
             // The root and every independently-locked project below it
             // (project-tree.ts): a repo root's own lockfile is often not the only one.
-            const tree = scanProjectTree(cwd);
+            const { entries: tree, discovery } = scanProjectTree(cwd);
             const scan = tree[0].scan;
             db.populateFromScan(scan);
             const groups = treeResolutionGroups(tree);
@@ -121,7 +122,7 @@ function getDatabase() {
                 // Initialize live intelligence with per-ecosystem resolved versions
                 // (targets carry platform-gated dep info so advisories can be flagged
                 // platform-relevant for the host).
-                liveIntel.initFromProjectTree(cwd, groups);
+                liveIntel.initFromProjectTree(cwd, groups, discovery);
                 if (liveIntel.isEnabled()) {
                     console.error(`[4DA]   Live intelligence: enabled (OSV.dev)`);
                     // The vulnerability scan goes through the warmup so a briefing that
@@ -206,6 +207,39 @@ function getDatabase() {
     }
     return db;
 }
+/**
+ * No SQLite driver is usable (Node < 22.13 and better-sqlite3's native module
+ * unbuilt): the live layer alone, from a project scan and an in-memory cache,
+ * so the dependency tools (DATABASE_FREE_TOOLS) still answer. Every other
+ * tool returns the driver error, which says how to fix it.
+ */
+function initWithoutDatabase() {
+    if (liveIntel)
+        return;
+    liveIntel = new LiveIntelligence(null);
+    setLiveIntelligence(liveIntel);
+    const cwd = resolveProjectDir();
+    const { entries, discovery } = scanProjectTree(cwd);
+    const groups = treeResolutionGroups(entries);
+    console.error(`[4DA] No SQLite driver: the dependency tools run without a database (${cwd}).`);
+    if (groups.length === 0)
+        return;
+    liveIntel.initFromProjectTree(cwd, groups, discovery);
+    if (liveIntel.isEnabled())
+        liveIntel.startVulnerabilityWarmup(cwd);
+}
+/** The database for a tool call; null only for a database-free tool when no SQLite driver is usable. */
+function databaseFor(tool) {
+    try {
+        return getDatabase();
+    }
+    catch (error) {
+        if (!(error instanceof SqliteUnavailableError) || !DATABASE_FREE_TOOLS.has(tool))
+            throw error;
+        initWithoutDatabase();
+        return null;
+    }
+}
 /** Standalone vs desktop-app database, decided once by the cheap probe (no scan, no resolution). */
 let standaloneMode = null;
 function isStandaloneMode() {
@@ -372,11 +406,18 @@ export function buildServer() {
             }
         }
         try {
-            const database = getDatabase();
+            const database = databaseFor(name);
             return await dispatchTool(name, database, args);
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
+            // A database that turns out damaged mid-session (SQLITE_CORRUPT on a
+            // page the open did not touch) gets the same guidance as one that
+            // fails to open, instead of the bare SQLite text.
+            const errorMessage = db && isUnreadableDbError(error)
+                ? unreadableDbMessage(db.dbPath, error)
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
             return {
                 content: [
                     {
@@ -441,6 +482,7 @@ async function main() {
                         refused unless MCP_AUTH_SECRET is set; authentication
                         is then mandatory for every request.
     --setup             Detect editors and write MCP config
+    --dry-run           With --setup: print each file and entry, write nothing
     --doctor            Validate database, bindings, and LLM providers
 
   Environment:
@@ -463,7 +505,7 @@ async function main() {
     }
     // Setup command: configure editors
     if (args.includes("--setup") || args.includes("setup")) {
-        runSetup();
+        runSetup(args.includes("--dry-run"));
         return;
     }
     // Doctor command: validate installation health
@@ -509,6 +551,11 @@ async function main() {
     // -------------------------------------------------------------------------
     const dbPath = process.env.FOURDA_DB_PATH || undefined;
     const validation = FourDADatabase.validateDatabase(dbPath);
+    const sqlite = sqliteDriverStatus();
+    if (!sqlite.driver) {
+        console.error(`[4DA] ${sqlite.problem}`);
+        console.error(`  Dependency tools (${[...DATABASE_FREE_TOOLS].join(", ")}) still run, without a database.`);
+    }
     if (validation.valid) {
         console.error(`[4DA] Database validated — ${validation.tables?.length ?? 0} tables found`);
     }

package/dist/live/cache.d.ts

@@ -1,7 +1,29 @@
-import type Database from "better-sqlite3";
+import { type SqliteDatabase } from "../sqlite-driver.js";
+/**
+ * The server's own cache file (serverCacheDbPath(), `cache.db`), opened once
+ * per process. Falls back to an in-memory database when the file cannot be
+ * created (a read-only home directory): the server then runs uncached on disk
+ * rather than failing. Null when no SQLite driver is usable at all
+ * (sqlite-driver.ts); LiveCache then keeps entries in a Map for the session.
+ */
+export declare function getServerCacheDb(): SqliteDatabase | null;
+/** Close the shared cache connection (tests; the next getServerCacheDb() reopens it). */
+export declare function closeServerCacheDb(): void;
+/**
+ * Registry, OSV and changelog responses with a TTL.
+ *
+ * The cache never lives in the desktop app's database. A read-only connection
+ * (the app's `4da.db`, see FourDADatabase) is replaced by the server's own
+ * cache file; until 6.0.2 the server created a `live_cache` table inside the
+ * app's database and filled it.
+ */
 export declare class LiveCache {
     private db;
-    constructor(db: Database.Database);
+    /** Without any SQLite driver: entries for this session only, keyed like the table. */
+    private memory;
+    constructor(db: SqliteDatabase | null);
+    /** The Map store's equivalent of datetime('now') comparisons. */
+    private live;
     private ensureTable;
     get<T>(key: string): T | null;
     getStale<T>(key: string): {
@@ -9,6 +31,13 @@ export declare class LiveCache {
         fetchedAt: string;
     } | null;
     set(key: string, data: unknown, source: string, ttlSeconds: number): void;
+    /**
+     * Many entries in ONE transaction. A scan caches one row per dependency;
+     * as separate autocommits each paid its own WAL commit, and superset's
+     * 4,516 rows took about 40 s of a 55 s cold scan whose network part ended
+     * at 12 s (2026-10-10).
+     */
+    setMany(entries: Array<[key: string, data: unknown]>, source: string, ttlSeconds: number): void;
     purgeExpired(): number;
     invalidateSource(source: string): void;
     invalidateAll(): void;

package/dist/live/cache.js

@@ -1,12 +1,70 @@
 // SPDX-License-Identifier: Apache-2.0
+import fs from "node:fs";
+import path from "node:path";
+import { openDatabase, sqliteDriverStatus } from "../sqlite-driver.js";
+import { serverCacheDbPath } from "../db.js";
+let serverCache = null;
+/**
+ * The server's own cache file (serverCacheDbPath(), `cache.db`), opened once
+ * per process. Falls back to an in-memory database when the file cannot be
+ * created (a read-only home directory): the server then runs uncached on disk
+ * rather than failing. Null when no SQLite driver is usable at all
+ * (sqlite-driver.ts); LiveCache then keeps entries in a Map for the session.
+ */
+export function getServerCacheDb() {
+    if (serverCache?.open)
+        return serverCache;
+    if (!sqliteDriverStatus().driver)
+        return null;
+    const file = serverCacheDbPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        serverCache = openDatabase(file);
+        serverCache.pragma("journal_mode = WAL");
+        // A cache, not a record: in WAL mode NORMAL never corrupts the file, and
+        // a crash can only lose the last few writes, which are refetched.
+        serverCache.pragma("synchronous = NORMAL");
+    }
+    catch (error) {
+        console.error(`[4da] cannot open the cache at ${file} (${error instanceof Error ? error.message : String(error)}); caching in memory for this session`);
+        serverCache = openDatabase(":memory:");
+    }
+    return serverCache;
+}
+/** Close the shared cache connection (tests; the next getServerCacheDb() reopens it). */
+export function closeServerCacheDb() {
+    if (serverCache?.open)
+        serverCache.close();
+    serverCache = null;
+}
+/**
+ * Registry, OSV and changelog responses with a TTL.
+ *
+ * The cache never lives in the desktop app's database. A read-only connection
+ * (the app's `4da.db`, see FourDADatabase) is replaced by the server's own
+ * cache file; until 6.0.2 the server created a `live_cache` table inside the
+ * app's database and filled it.
+ */
 export class LiveCache {
     db;
+    /** Without any SQLite driver: entries for this session only, keyed like the table. */
+    memory = null;
     constructor(db) {
-        this.db = db;
+        this.db = !db || db.readonly ? getServerCacheDb() : db;
+        if (!this.db) {
+            this.memory = new Map();
+            return;
+        }
         this.ensureTable();
         this.purgeExpired();
     }
+    /** The Map store's equivalent of datetime('now') comparisons. */
+    live(row) {
+        return Date.parse(row.expires_at) > Date.now();
+    }
     ensureTable() {
+        if (!this.db)
+            return;
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS live_cache (
         cache_key TEXT PRIMARY KEY,
@@ -20,6 +78,10 @@ export class LiveCache {
     `);
     }
     get(key) {
+        if (this.memory) {
+            const hit = this.memory.get(key);
+            return hit && this.live(hit) ? JSON.parse(hit.data) : null;
+        }
         const row = this.db.prepare("SELECT data FROM live_cache WHERE cache_key = ? AND expires_at > datetime('now')").get(key);
         if (!row)
             return null;
@@ -31,6 +93,10 @@ export class LiveCache {
         }
     }
     getStale(key) {
+        if (this.memory) {
+            const hit = this.memory.get(key);
+            return hit ? { data: JSON.parse(hit.data), fetchedAt: hit.fetched_at } : null;
+        }
         const row = this.db.prepare("SELECT data, fetched_at FROM live_cache WHERE cache_key = ?").get(key);
         if (!row)
             return null;
@@ -42,19 +108,65 @@ export class LiveCache {
         }
     }
     set(key, data, source, ttlSeconds) {
+        if (this.memory) {
+            const now = Date.now();
+            const iso = (ms) => new Date(ms).toISOString();
+            this.memory.set(key, { cache_key: key, data: JSON.stringify(data), source, fetched_at: iso(now), expires_at: iso(now + ttlSeconds * 1000) });
+            return;
+        }
         this.db.prepare(`
       INSERT OR REPLACE INTO live_cache (cache_key, data, source, fetched_at, expires_at)
       VALUES (?, ?, ?, datetime('now'), datetime('now', '+' || ? || ' seconds'))
     `).run(key, JSON.stringify(data), source, ttlSeconds);
     }
+    /**
+     * Many entries in ONE transaction. A scan caches one row per dependency;
+     * as separate autocommits each paid its own WAL commit, and superset's
+     * 4,516 rows took about 40 s of a 55 s cold scan whose network part ended
+     * at 12 s (2026-10-10).
+     */
+    setMany(entries, source, ttlSeconds) {
+        if (entries.length === 0)
+            return;
+        if (this.memory) {
+            for (const [key, data] of entries)
+                this.set(key, data, source, ttlSeconds);
+            return;
+        }
+        const insert = this.db.prepare(`
+      INSERT OR REPLACE INTO live_cache (cache_key, data, source, fetched_at, expires_at)
+      VALUES (?, ?, ?, datetime('now'), datetime('now', '+' || ? || ' seconds'))
+    `);
+        this.db.transaction(() => {
+            for (const [key, data] of entries)
+                insert.run(key, JSON.stringify(data), source, ttlSeconds);
+        })();
+    }
     purgeExpired() {
+        if (this.memory) {
+            let purged = 0;
+            for (const [key, row] of this.memory)
+                if (!this.live(row) && this.memory.delete(key))
+                    purged++;
+            return purged;
+        }
         const result = this.db.prepare("DELETE FROM live_cache WHERE expires_at <= datetime('now')").run();
         return result.changes;
     }
     invalidateSource(source) {
+        if (this.memory) {
+            for (const [key, row] of this.memory)
+                if (row.source === source)
+                    this.memory.delete(key);
+            return;
+        }
         this.db.prepare("DELETE FROM live_cache WHERE source = ?").run(source);
     }
     invalidateAll() {
+        if (this.memory) {
+            this.memory.clear();
+            return;
+        }
         this.db.prepare("DELETE FROM live_cache").run();
     }
 }

package/dist/live/changelog-classify.js

@@ -171,7 +171,10 @@ const ADDITIVE_HEADING = /^\W*(?:added|adds|new|new features?|features?|enhancem
 export function classifyHeading(heading) {
     if (/(?<!-)\bbreaking\b|⚠|incompatib|migration|\bmajor changes?\b/i.test(heading))
         return "breaking";
-    if (/\bremov(?:e|ed|als?)\b|\bapi changes?\b/i.test(heading))
+    // "Removed", "Removals", "Deprecated and Removed", "API changes": a category.
+    // "`Cargo.lock` Removed from Tracking" (sqlx 0.9.0) is a news item about the
+    // repository, and its three paragraphs were flagged breaking.
+    if (/(?:^\W*|(?:\band|[&/,])\s*)remov(?:e|ed|als?)\b|\bapi changes?\b/i.test(heading))
         return "removal";
     if (/security|vulnerab/i.test(heading))
         return "security";

package/dist/live/changelog.d.ts

@@ -17,6 +17,13 @@
  * reference definitions are skipped: they are examples and URLs, not changes.
  */
 import { type EntryKind } from "./changelog-classify.js";
+/**
+ * Version of the parser AND classifier output. A parsed changelog is cached
+ * for 7 days per package version, so a fix to either one stays invisible
+ * for a week unless this changes: bump it with every change to parseChangelog
+ * or changelog-classify.ts that can alter a section or an entry's kind.
+ */
+export declare const CHANGELOG_PARSER_VERSION = 2;
 export interface ChangelogEntry {
     kind: EntryKind;
     text: string;
@@ -26,6 +33,14 @@ export interface ChangelogEntry {
      * under actix-web's "Removed" reads as harmless, to an agent and to a rater alike.
      */
     under?: string;
+    /**
+     * Bullets nested under this entry (feature lists, "Breaking change: ..."
+     * notes). They belong to the entry, not beside it: sqlx 0.9.0's Breaking
+     * section has 23 top-level bullets, and counting every nested one reported
+     * "83 entries flagged breaking" (2026-10-07). A nested bullet that is more
+     * severe than its parent raises the parent's kind.
+     */
+    details?: string[];
 }
 export interface ChangelogSection {
     version: string;

package/dist/live/changelog.js

@@ -19,6 +19,13 @@
  */
 import { compareVersionPrecedence } from "./semver-precedence.js";
 import { classifyEntry, classifyHeading, sanitizeEntry } from "./changelog-classify.js";
+/**
+ * Version of the parser AND classifier output. A parsed changelog is cached
+ * for 7 days per package version, so a fix to either one stays invisible
+ * for a week unless this changes: bump it with every change to parseChangelog
+ * or changelog-classify.ts that can alter a section or an entry's kind.
+ */
+export const CHANGELOG_PARSER_VERSION = 2;
 const NAME_STEMS = ["changelog", "changes", "history", "releases", "release-notes", "release_notes", "releasenotes", "news"];
 const NAME_EXTS = ["", ".md", ".markdown", ".txt", ".rst"];
 /** True for a root-level basename that names a changelog (case-insensitive). */
@@ -71,7 +78,14 @@ function extractDate(text) {
  * heading. Exported for tests.
  */
 export function parseVersionHeading(raw) {
-    const text = raw.trim().replace(/^\*\*|\*\*$/g, "");
+    // Inline HTML is markup, not heading text: stripe writes
+    // `## <a id="23-0-0"></a>23.0.0 - 2026-09-30`, and until 6.0.2 no stripe
+    // release was found (changelog.found: false, 2026-10-07).
+    const text = raw
+        .replace(/<\/?[A-Za-z][^<>]*>/g, " ")
+        .trim()
+        .replace(/^\*\*|\*\*$/g, "")
+        .trim();
     const m = HEADING.exec(text);
     if (!m)
         return null;
@@ -105,17 +119,37 @@ const PLAIN_LABEL = /^\s{0,3}([A-Za-z⚠][\w /&,'()⚠️-]{1,58}?)\s*:\s*$/;
 const HTML_LAYOUT = /^<\/?(?:details|summary|div|p|br|hr|img|picture|source|table|tr|td|th|thead|tbody|center|sup|sub)\b/i;
 /** A bullet that is only a label: "remove:", "**Breaking**:", "deps:". */
 const LABEL_BULLET = /^\W*([A-Za-z][\w -]{0,30}?)\W*:\W*$/;
+const KIND_SEVERITY = { breaking: 3, security: 2, deprecation: 1, change: 0 };
+/** Nested lines kept per entry, and the length of each. */
+const MAX_DETAILS = 12;
+const MAX_DETAIL_CHARS = 200;
 function flush(state) {
-    if (state.pending && state.current) {
-        const text = sanitizeEntry(state.pending.text);
-        const under = state.pending.under;
-        // Layout markup is not a change: actix-web 4 wraps pre-release notes in
-        // `<details> <summary>...</summary>`, and both lines were counted as removals.
-        if (text && !HTML_LAYOUT.test(text)) {
-            state.current.entries.push({ kind: classifyEntry(text, state.pending.context), text, ...(under ? { under } : {}) });
-        }
-    }
+    const pending = state.pending;
     state.pending = null;
+    if (!pending || !state.current)
+        return;
+    const text = sanitizeEntry(pending.text);
+    // Layout markup is not a change: actix-web 4 wraps pre-release notes in
+    // `<details> <summary>...</summary>`, and both lines were counted as removals.
+    if (!text || HTML_LAYOUT.test(text))
+        return;
+    const kind = classifyEntry(text, pending.context);
+    if (pending.into) {
+        const parent = pending.into;
+        const details = (parent.details ??= []);
+        if (details.length < MAX_DETAILS)
+            details.push(sanitizeEntry(pending.text, MAX_DETAIL_CHARS));
+        // "Breaking change: adds a DB type parameter" under a plain "fix: RawSql
+        // lifetime issues" bullet makes the entry breaking.
+        if (KIND_SEVERITY[kind] > KIND_SEVERITY[parent.kind])
+            parent.kind = kind;
+        return;
+    }
+    const under = pending.under;
+    const entry = { kind, text, ...(under ? { under } : {}) };
+    state.current.entries.push(entry);
+    if (pending.outer)
+        state.parentEntry = entry;
 }
 /**
  * Headings that name a kind of change (keep-a-changelog and conventional-commit
@@ -135,6 +169,7 @@ function openSection(state, heading, level) {
     state.parentIndent = null;
     state.headingText = null;
     state.parentText = null;
+    state.parentEntry = null;
 }
 /** A heading or parent bullet as context text: emphasis and code marks dropped, one line, at most 80 characters. */
 function contextText(raw) {
@@ -156,6 +191,8 @@ function addLine(state, line) {
             if (label) {
                 state.parentKind = classifyHeading(label[1]) ?? state.headingKind;
                 state.parentText = contextText(label[1]);
+                // A label's children are entries of their own, under the label.
+                state.parentEntry = null;
                 return;
             }
             // A breaking bullet lends "breaking" to its sub-points (date-fns 3.0: "**BREAKING**: Functions
@@ -167,7 +204,9 @@ function addLine(state, line) {
         }
         const context = !outer && state.parentKind ? state.parentKind : state.headingKind;
         const under = !outer && state.parentText ? state.parentText : state.headingText;
-        state.pending = { text, context, indent, under };
+        if (outer)
+            state.parentEntry = null;
+        state.pending = { text, context, indent, under, outer, into: outer ? null : state.parentEntry };
         return;
     }
     if (line.trim() === "") {
@@ -182,7 +221,21 @@ function addLine(state, line) {
         state.pending.text += ` ${line.trim()}`; // wrapped paragraph line
         return;
     }
+    // An indented paragraph after a blank line continues the list item above it
+    // (stripe 23.0.0: "* ⚠️ Remove ErrorType export", blank, "  Remove the ErrorType
+    // interface ..."): a detail of that entry, not an entry of its own.
+    if (!state.pending && state.parentEntry && /^\s{2,}\S/.test(line)) {
+        state.pending = {
+            text: line.trim(),
+            context: state.parentKind ?? state.headingKind,
+            indent: -2,
+            under: state.headingText,
+            into: state.parentEntry,
+        };
+        return;
+    }
     flush(state);
+    state.parentEntry = null;
     state.pending = { text: line, context: state.headingKind, indent: -1, under: state.headingText };
 }
 /** Parse a changelog into version sections, in document order (usually newest first). */
@@ -198,6 +251,7 @@ export function parseChangelog(text) {
         headingText: null,
         parentText: null,
         pending: null,
+        parentEntry: null,
     };
     let inFence = false;
     let inComment = false;
@@ -244,6 +298,7 @@ export function parseChangelog(text) {
                 state.parentKind = null;
                 state.parentIndent = null;
                 state.parentText = null;
+                state.parentEntry = null;
             }
             continue;
         }
@@ -288,6 +343,7 @@ export function parseChangelog(text) {
             state.parentKind = null;
             state.parentIndent = null;
             state.parentText = null;
+            state.parentEntry = null;
             continue;
         }
         if (state.current)

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

@@ -13,7 +13,7 @@
  * claim a certainty the app itself does not have. The grade would not change
  * (unknown and runtime both get no discount), but `dev_scope_known` would lie.
  */
-import type Database from "better-sqlite3";
+import type { SqliteDatabase } from "../sqlite-driver.js";
 import type { ResolvedDependency } from "./types.js";
 /**
  * A project path in the app's storage form: forward slashes, lowercased on
@@ -29,4 +29,4 @@ export declare function canonicalStoragePath(p: string): string;
  * dependencies are untouched: their manifest already says. Returns new
  * objects; never throws; a database without the table changes nothing.
  */
-export declare function applyInstanceDevScope(db: Database.Database | null, deps: ResolvedDependency[]): ResolvedDependency[];
+export declare function applyInstanceDevScope(db: SqliteDatabase | null, deps: ResolvedDependency[]): ResolvedDependency[];

package/dist/live/fix-paths.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Fix paths for vulnerable dependencies: WHICH version to move to, and HOW.
+ *
+ * Two defects found by the fix-path oracle (2026-10-10, 19 public repos;
+ * each recommendation applied in a copy, re-resolved, re-scanned):
+ *
+ * 1. The target could itself be vulnerable. It was the highest fix among the
+ *    advisories that affect the installed version, so an advisory the
+ *    installed version predates was never consulted: openssl 0.10.38 was sent
+ *    to 0.10.79, which GHSA-phqj-4mhp-q6mq affects (0.10.50 up to 0.10.80).
+ *    Now: the smallest published version at or above every per-advisory fix
+ *    that NO advisory of the package affects (osv-ranges.ts).
+ * 2. Every transitive finding was "waiting on upstream", 3 wrong out of 3:
+ *    minimist 1.2.5 (npm), braces 3.0.2 (pnpm) and mio 0.8.0 (Cargo) all had
+ *    parents whose declared requirement already admitted the fix, and a
+ *    lockfile refresh fixed each one. Now: the parents' requirements are
+ *    read (from the lockfile, or from the parent's registry metadata for
+ *    pnpm and Cargo) and a refresh is recommended when they all admit a
+ *    clean version.
+ *
+ * Network: api.osv.dev (one /v1/query per vulnerable package) and the
+ * package's own registry; package names and versions only. Every lookup is
+ * cached, and any failure degrades to the old answer, never to a guess.
+ */
+import type { LiveCache } from "./cache.js";
+import type { RateLimiter } from "./rate-limiter.js";
+import { type AdvisoryRanges, type CleanTarget } from "./osv-ranges.js";
+import { type LockfileFormat } from "./lockfile-parents.js";
+import type { OsvEcosystem } from "./types.js";
+export interface CrateDepReq {
+    req: string;
+    optional: boolean;
+}
+export interface CratesSparse {
+    /** Versions not yanked. */
+    versions: string[];
+    /** version -> dependency crate name -> requirements (one per target/kind entry; dev-dependencies left out). */
+    reqs: Record<string, Record<string, CrateDepReq[]>>;
+}
+export declare class FixPathSources {
+    private cache;
+    private rateLimiter;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter);
+    /** Every non-withdrawn OSV advisory for a package, as ranges; null when OSV could not be read. */
+    packageAdvisories(ecosystem: OsvEcosystem, name: string): Promise<AdvisoryRanges[] | null>;
+    /** Published, installable versions (not yanked); null when the registry could not be read or is not supported. */
+    publishedVersions(ecosystem: OsvEcosystem, name: string): Promise<string[] | null>;
+    /**
+     * The requirements `parent@parentVersion` declares on `dep`, from the
+     * registry: npm (pnpm lockfiles record none) and crates.io (Cargo.lock
+     * records none). Null when unknown; [] when the parent declares none.
+     */
+    parentRequirements(ecosystem: OsvEcosystem, parent: string, parentVersion: string, dep: string): Promise<string[] | null>;
+    private npmVersions;
+    /** A crate's sparse-index record: versions and per-version dependency requirements. */
+    cratesSparse(name: string): Promise<CratesSparse | null>;
+    private pypiVersions;
+    private goVersions;
+}
+export type FixTargetResult = CleanTarget;
+/** The minimal clean target for one installed copy, or null when the advisories could not be read. */
+export declare function cleanFixTarget(sources: FixPathSources, ecosystem: OsvEcosystem, name: string, perAdvisoryFixes: string[]): Promise<FixTargetResult | null>;
+/**
+ * Verified targets for many installed copies at once, within a time budget:
+ * the copies that could not be checked in time (or offline) are simply
+ * absent from the result, and the caller says so. Keyed by `key`.
+ */
+export declare function verifyFixTargets(sources: FixPathSources | null, items: Array<{
+    key: string;
+    ecosystem: OsvEcosystem;
+    name: string;
+    fixes: string[];
+}>, budgetMs: number, concurrency?: number): Promise<Map<string, CleanTarget>>;
+/** One clause for a target that is not the highest per-advisory fix, or null when it is. */
+export declare function targetNote(clean: CleanTarget): string | null;
+export interface RefreshVerdict {
+    /** True when every parent's requirement already admits a clean version. */
+    refreshFixes: boolean;
+    format: LockfileFormat;
+    /** The command, run in the lockfile's directory. */
+    command: string;
+    /** Parent requirements that do NOT admit a clean version (why it is waiting on upstream). */
+    blocking: Array<{
+        parent: string;
+        parentVersion: string | null;
+        requirement: string;
+    }>;
+    /** The version a refresh resolves to, when the registry's version list was read. */
+    resolvesTo: string | null;
+}
+/** The refresh command for one lockfile format. */
+export declare function refreshCommand(format: LockfileFormat, name: string, installed: string, target: string): string;
+/**
+ * Whether refreshing `lockfile` moves `name@installed` to a clean version
+ * without any parent changing its declared requirement. Null when the
+ * lockfile or a requirement cannot be read (the caller keeps "waiting on
+ * upstream", the conservative answer).
+ */
+export declare function refreshVerdict(sources: FixPathSources, ecosystem: OsvEcosystem, lockfile: string, name: string, installed: string, target: string, advisories: AdvisoryRanges[] | null, published: string[] | null): Promise<RefreshVerdict | null>;
+/**
+ * The locked crates `cargo update -p name@installed --precise target` cannot
+ * move by itself, as `crate@lockedVersion` specs to update first; null when it
+ * cannot be worked out (a registry read failed, or the walk is too large).
+ *
+ * Measured on nushell (2026-10-10): `cargo update -p openssl@0.10.38
+ * --precise 0.10.80` fails. 0.10.80 needs openssl-macros 0.1.1 -> syn 2 ->
+ * quote ^1.0.25, and quote 1.0.15 is locked by rstest, outside openssl's own
+ * dependency tree, so cargo keeps it and reports a conflict. `cargo update -p
+ * quote` first, then the precise update, works. Crates in the installed
+ * version's own tree may move with it (openssl-sys did) and are not listed.
+ *
+ * The walk follows the target's normal and build dependencies (optional ones
+ * only when the crate is already in the lockfile): a requirement a locked copy
+ * satisfies is reused; one whose compatibility line holds a locked copy that
+ * does not satisfy it names that copy; anything else is a new crate, walked
+ * at its newest matching version.
+ */
+export declare function cargoPrecisePrerequisites(sources: FixPathSources, lockContent: string, name: string, installed: string, target: string): Promise<string[] | null>;