@4da/mcp-server 5.0.4 → 6.0.0

package/dist/live/version-compare.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Version ordering per ecosystem, for advisory ranges and fix selection.
+ *
+ * `compareSemver` reads MAJOR.MINOR.PATCH and calls anything else "equal".
+ * That is wrong outside npm and crates.io, and it was wrong in practice
+ * (measured 2026-10-02 against pip-audit and osv-scanner):
+ * - PyPI versions are PEP 440, not semver. `5.1` and `4.2` are ordinary
+ *   releases; read as "equal" to everything, django 3.2.0 was sent to the 5.1
+ *   line's fix (5.1.1) instead of its own line's (3.2.25 / 4.2.16).
+ * - Go versions carry a `v`, OSV's Go ranges do not, and pseudo-versions
+ *   (`v0.0.0-20200622213623-75b288015ac9`) order as semver prereleases.
+ *
+ * `0` is OSV's "since the beginning" bound and orders below every version.
+ */
+import { compareSemver, parseSemver } from "./semver-utils.js";
+import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
+const PEP440 = /^v?(?:(\d+)!)?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|c|rc|pre|preview)[-_.]?(\d*))?(?:(?:[-_.]?(?:post|rev|r)[-_.]?(\d*))|-(\d+))?(?:[-_.]?dev[-_.]?(\d*))?(?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?$/i;
+export function parsePep440(version) {
+    const m = PEP440.exec(version.trim());
+    if (!m)
+        return null;
+    const preRank = { a: 0, alpha: 0, b: 1, beta: 1, c: 2, rc: 2, pre: 2, preview: 2 };
+    return {
+        epoch: m[1] ? Number(m[1]) : 0,
+        release: m[2].split(".").map(Number),
+        pre: m[3] ? [preRank[m[3].toLowerCase()], m[4] ? Number(m[4]) : 0] : null,
+        post: m[5] !== undefined ? (m[5] ? Number(m[5]) : 0) : m[6] !== undefined ? Number(m[6]) : null,
+        dev: m[7] !== undefined ? (m[7] ? Number(m[7]) : 0) : null,
+    };
+}
+export function comparePep440(a, b) {
+    if (a.epoch !== b.epoch)
+        return a.epoch > b.epoch ? 1 : -1;
+    const len = Math.max(a.release.length, b.release.length);
+    for (let i = 0; i < len; i++) {
+        const x = a.release[i] ?? 0;
+        const y = b.release[i] ?? 0;
+        if (x !== y)
+            return x > y ? 1 : -1;
+    }
+    // PEP 440's sort key within one release:
+    //   X.devN < X.aN.devM < X.aN < X.aN.postM < X.bN < X.rcN < X < X.postN.devM < X.postN
+    // pre: a/b/rc rank, a dev-only release below every pre-release, a final above;
+    // then post (none lowest); then dev (none highest).
+    const key = (v) => [
+        v.pre ? v.pre[0] : v.post === null && v.dev !== null ? -1 : 3,
+        v.pre ? v.pre[1] : 0,
+        v.post === null ? -1 : v.post,
+        v.dev === null ? Number.POSITIVE_INFINITY : v.dev,
+    ];
+    const ka = key(a);
+    const kb = key(b);
+    for (let i = 0; i < ka.length; i++) {
+        if (ka[i] !== kb[i])
+            return ka[i] > kb[i] ? 1 : -1;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+const stripGoV = (v) => v.replace(/^v(?=\d)/, "");
+/** Whether `version` is readable for this ecosystem's ordering. */
+export function isComparable(version, ecosystem) {
+    if (version === "0")
+        return true;
+    switch (ecosystem) {
+        case "PyPI":
+            return parsePep440(version) !== null;
+        case "Go":
+            return parseSemverPrecedence(stripGoV(version)) !== null;
+        case "npm":
+        case "crates.io":
+            return parseSemverPrecedence(version) !== null;
+        default:
+            return parseSemver(version) !== null;
+    }
+}
+/**
+ * Order two versions of one ecosystem: 1, -1, or 0 for equal OR unreadable
+ * (the same contract as compareSemver, so an unreadable bound never decides).
+ */
+export function compareVersions(a, b, ecosystem) {
+    if (a === b)
+        return 0;
+    if (a === "0")
+        return isComparable(b, ecosystem) ? -1 : 0;
+    if (b === "0")
+        return isComparable(a, ecosystem) ? 1 : 0;
+    switch (ecosystem) {
+        case "PyPI": {
+            const pa = parsePep440(a);
+            const pb = parsePep440(b);
+            return pa && pb ? comparePep440(pa, pb) : 0;
+        }
+        case "Go":
+            return compareVersionPrecedence(stripGoV(a), stripGoV(b)) ?? 0;
+        case "npm":
+        case "crates.io":
+            return compareVersionPrecedence(a, b) ?? compareSemver(a, b);
+        default:
+            return compareSemver(a, b);
+    }
+}
+/** Highest of `versions` in this ecosystem's order, or null when empty. */
+export function maxVersion(versions, ecosystem) {
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((max, v) => (compareVersions(v, max, ecosystem) > 0 ? v : max), versions[0]);
+}
+/** Package-name equality as the ecosystem's registry defines it. */
+export function samePackageName(a, b, ecosystem) {
+    if (a === b)
+        return true;
+    if (ecosystem === "PyPI") {
+        const n = (s) => s.toLowerCase().replace(/[-_.]+/g, "-");
+        return n(a) === n(b);
+    }
+    if (ecosystem === "crates.io") {
+        const n = (s) => s.toLowerCase().replace(/_/g, "-");
+        return n(a) === n(b);
+    }
+    return false;
+}
+/** Whether a user-typed package name (`package` parameters) names this dependency: registry rules, then case-insensitive. */
+export function namesPackage(query, name, ecosystem) {
+    const q = query.trim();
+    return samePackageName(q, name, ecosystem) || q.toLowerCase() === name.toLowerCase();
+}

package/dist/live/version-resolver.d.ts

@@ -3,9 +3,12 @@
  *
  * Extracts exact dependency versions from lock files.
  * Priority: lock file (exact) > manifest (range/specifier).
- * Uses only Node.js built-ins — no external parsers.
+ * Uses only Node.js built-ins — no external parsers. The per-ecosystem
+ * parsers live in lockfile-parsers.ts, which also reports which file each
+ * resolution read from.
  */
 import type { OsvEcosystem, ResolvedDependency } from "./types.js";
+import { type PackageInstance } from "./lockfile-parsers.js";
 /**
  * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
  *
@@ -18,8 +21,18 @@ import type { OsvEcosystem, ResolvedDependency } from "./types.js";
  */
 export declare function mapEcosystem(language: string): OsvEcosystem;
 export declare function resolveVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
+/** `resolveVersions` over a version map the caller already read from `cwd`. */
+export declare function resolveVersionsFrom(cwd: string, deps: string[], devDeps: string[], ecosystem: OsvEcosystem, versionMap: Map<string, string>, targets?: Record<string, string>): ResolvedDependency[];
 /**
  * Resolve the complete lockfile package set for vulnerability scanning.
  * Direct dependency health and upgrade planning continue to use resolveVersions.
  */
 export declare function resolveAuditVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
+/**
+ * `resolveAuditVersions` over a version map the caller already read. `direct`
+ * lets the caller pass direct entries it has already enriched (install state)
+ * so the audit set carries the same objects' context. `instances` is every
+ * installed copy the lockfile holds; without it the version map (one copy per
+ * name) is all there is.
+ */
+export declare function resolveAuditVersionsFrom(cwd: string, deps: string[], devDeps: string[], ecosystem: OsvEcosystem, versionMap: Map<string, string>, targets?: Record<string, string>, direct?: ResolvedDependency[], instances?: PackageInstance[]): ResolvedDependency[];

package/dist/live/version-resolver.js

@@ -4,11 +4,14 @@
  *
  * Extracts exact dependency versions from lock files.
  * Priority: lock file (exact) > manifest (range/specifier).
- * Uses only Node.js built-ins — no external parsers.
+ * Uses only Node.js built-ins — no external parsers. The per-ecosystem
+ * parsers live in lockfile-parsers.ts, which also reports which file each
+ * resolution read from.
  */
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { targetActiveOnHost } from "./platform.js";
+import { activeCratesForHost, hostTriple } from "./cargo-platform.js";
+import { resolveVersionSource } from "./lockfile-parsers.js";
+import { normalizePythonName } from "./lockfile-parsers-pygo.js";
 // Alias -> OSV ecosystem. Mirrors the desktop app's canonical
 // `Ecosystem::parse` (src-tauri/src/ecosystem.rs) so both sides recognize the
 // SAME aliases — they previously drifted (the Rust side knew csharp/dart/php
@@ -62,12 +65,35 @@ const ECOSYSTEM_MAP = {
 export function mapEcosystem(language) {
     return ECOSYSTEM_MAP[language.trim().toLowerCase()] || "npm";
 }
+/**
+ * crates.io treats `-` and `_` as one namespace (you cannot publish both
+ * `http-body-util` and `http_body_util`), but the two spellings reach this
+ * resolver from different sources: Cargo.lock records the publisher's canonical
+ * name while ACE's import scraper reports the IMPORT identifier, which is
+ * always underscored. An exact-match lookup then fails for the import spelling
+ * and the same crate surfaces twice — once versioned, once `version: null`
+ * (observed live 2026-08-30: http_body_util, async_trait, tower_http,
+ * ed25519_dalek, ts_rs, proc_macro2, victauri_test, all null beside their
+ * hyphenated versioned twins). Resolve via the spelling the lock file actually
+ * uses and RETURN that spelling, so downstream dedupe merges the variants.
+ */
+function canonicalCrateName(name, versionMap) {
+    if (versionMap.has(name))
+        return name;
+    const swapped = name.includes("_") ? name.replace(/_/g, "-") : name.replace(/-/g, "_");
+    return versionMap.has(swapped) ? swapped : name;
+}
 export function resolveVersions(cwd, deps, devDeps, language, targets = {}) {
     const ecosystem = mapEcosystem(language);
+    const versionMap = resolveVersionSource(cwd, ecosystem).versions;
+    return resolveVersionsFrom(cwd, deps, devDeps, ecosystem, versionMap, targets);
+}
+/** `resolveVersions` over a version map the caller already read from `cwd`. */
+export function resolveVersionsFrom(cwd, deps, devDeps, ecosystem, versionMap, targets = {}) {
     const results = [];
-    const versionMap = resolveVersionMap(cwd, ecosystem);
-    const build = (name, isDev) => {
-        const target = targets[name] ?? null;
+    const build = (rawName, isDev) => {
+        const name = ecosystem === "crates.io" ? canonicalCrateName(rawName, versionMap) : rawName;
+        const target = targets[rawName] ?? targets[name] ?? null;
         return {
             name,
             version: versionMap.get(normalizePackageName(name, ecosystem)) || null,
@@ -77,6 +103,9 @@ export function resolveVersions(cwd, deps, devDeps, language, targets = {}) {
             devScopeKnown: true,
             target,
             platformActive: targetActiveOnHost(target),
+            // Provenance recorded at the point of resolution: this version came from
+            // THIS manifest directory's lock file, not from "the project" generally.
+            sourceDirs: [cwd],
         };
     };
     for (const name of deps)
@@ -91,27 +120,71 @@ export function resolveVersions(cwd, deps, devDeps, language, targets = {}) {
  */
 export function resolveAuditVersions(cwd, deps, devDeps, language, targets = {}) {
     const ecosystem = mapEcosystem(language);
-    const direct = resolveVersions(cwd, deps, devDeps, language, targets);
-    const versionMap = resolveVersionMap(cwd, ecosystem);
-    const directNames = new Set(deps.map((name) => normalizePackageName(name, ecosystem)));
-    const devNames = new Set(devDeps.map((name) => normalizePackageName(name, ecosystem)));
+    const read = resolveVersionSource(cwd, ecosystem);
+    return resolveAuditVersionsFrom(cwd, deps, devDeps, ecosystem, read.versions, targets, undefined, read.instances);
+}
+/**
+ * `resolveAuditVersions` over a version map the caller already read. `direct`
+ * lets the caller pass direct entries it has already enriched (install state)
+ * so the audit set carries the same objects' context. `instances` is every
+ * installed copy the lockfile holds; without it the version map (one copy per
+ * name) is all there is.
+ */
+export function resolveAuditVersionsFrom(cwd, deps, devDeps, ecosystem, versionMap, targets = {}, direct = resolveVersionsFrom(cwd, deps, devDeps, ecosystem, versionMap, targets), instances = [...versionMap].map(([name, version]) => ({ name, version }))) {
+    // Canonicalize the same way resolveVersions does, so a dep declared under its
+    // import spelling still marks the lock file's canonical entry as direct.
+    const canonical = (name) => normalizePackageName(ecosystem === "crates.io" ? canonicalCrateName(name, versionMap) : name, ecosystem);
+    const directNames = new Set(deps.map(canonical));
+    const devNames = new Set(devDeps.map(canonical));
     const seen = new Set(direct.map((dep) => dependencyKey(dep)));
     const results = [...direct];
-    for (const [name, version] of versionMap) {
+    // Cargo.lock is target-agnostic, so a Windows lockfile still lists the whole
+    // Linux GTK3 stack Tauri pulls in. `[target.'cfg(...)']` parsing only ever
+    // covered DIRECT gated deps, and that cluster is entirely transitive — which
+    // is why nine unreachable crates were reported while the scan claimed to be
+    // platform-filtered. Ask cargo to resolve the graph for this host instead.
+    // `null` means cargo could not answer; every crate then stays active, because
+    // "unknown" must never silently hide a real advisory.
+    //
+    // THE SHARED PREDICATE — keep in step with the app's
+    // `src-tauri/src/platform_filter.rs`, which documents it in full:
+    //
+    //   a crate that is not RESOLVED FOR THE HOST is platform-inactive
+    //
+    // Two independent facts can make that true, and both are recorded because
+    // the copy differs: (1) the manifest gates it behind a `cfg(...)` for a
+    // target this machine is not — `targetActiveOnHost(declaredTarget)`, the
+    // app's `project_dependencies.target_cfg`; (2) cargo builds it for no
+    // target/feature combination here — `builtOnHost`, the app's
+    // `user_dependencies.target_cfg = 'lockfile-only'` (schema 122). Neither
+    // fact alone is the whole picture: (1) covers only DIRECT deps, and (2) is
+    // the only one that can see a transitive.
+    const hostCrates = ecosystem === "crates.io" ? activeCratesForHost(cwd) : null;
+    const triple = hostCrates ? hostTriple() : null;
+    for (const { name, version, dev } of instances) {
         const normalized = normalizePackageName(name, ecosystem);
-        const isDirect = directNames.has(normalized) || devNames.has(normalized);
-        // Transitive deps from the lockfile carry no per-dep target info (Cargo.lock
-        // doesn't encode it), so they are treated as unconditionally active.
-        const target = targets[name] ?? null;
+        // Direct only for the copy a manifest dependency resolves to; another
+        // installed version of the same name is somebody else's transitive.
+        const isDirect = (directNames.has(normalized) || devNames.has(normalized)) && versionMap.get(name) === version;
+        const declaredTarget = targets[name] ?? null;
+        const builtOnHost = hostCrates ? hostCrates.has(name) : true;
+        // Prefer the manifest's own cfg() spec when it has one — it is the more
+        // precise, human-readable explanation. Fall back to naming the triple the
+        // crate is absent from.
+        const target = declaredTarget ?? (builtOnHost || !triple ? null : `not built for ${triple}`);
         const candidate = {
             name,
             version,
             ecosystem,
-            isDev: devNames.has(normalized),
+            // A direct dependency's scope is its manifest section; a transitive's is
+            // whatever the lockfile recorded for that copy (npm `dev`, pnpm 5/6
+            // `dev`, Pipfile `develop`, poetry `category`), else unknown.
+            isDev: isDirect ? devNames.has(normalized) : dev === true,
             isDirect,
-            devScopeKnown: isDirect,
+            devScopeKnown: isDirect || dev !== undefined,
             target,
-            platformActive: targetActiveOnHost(target),
+            platformActive: targetActiveOnHost(declaredTarget) && builtOnHost,
+            sourceDirs: [cwd],
         };
         const key = dependencyKey(candidate);
         if (!seen.has(key)) {
@@ -121,293 +194,10 @@ export function resolveAuditVersions(cwd, deps, devDeps, language, targets = {})
     }
     return results;
 }
-function resolveVersionMap(cwd, ecosystem) {
-    const resolvers = {
-        npm: () => resolveNpm(cwd),
-        "crates.io": () => resolveRust(cwd),
-        PyPI: () => resolvePython(cwd),
-        Go: () => resolveGo(cwd),
-    };
-    return resolvers[ecosystem]?.() || new Map();
-}
 function normalizePackageName(name, ecosystem) {
-    return ecosystem === "PyPI" ? name.toLowerCase() : name;
+    // PEP 503: the lockfile readers store Python names normalised the same way.
+    return ecosystem === "PyPI" ? normalizePythonName(name) : name;
 }
 function dependencyKey(dep) {
     return `${dep.ecosystem}\0${normalizePackageName(dep.name, dep.ecosystem)}\0${dep.version ?? ""}`;
 }
-// =============================================================================
-// npm: package-lock.json > pnpm-lock.yaml > yarn.lock > package.json ranges
-// =============================================================================
-function resolveNpm(cwd) {
-    const versions = new Map();
-    // Try package-lock.json first (npm)
-    const lockPath = path.join(cwd, "package-lock.json");
-    if (fs.existsSync(lockPath)) {
-        try {
-            const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
-            // v2/v3 format: packages["node_modules/name"].version
-            if (lock.packages) {
-                for (const [key, value] of Object.entries(lock.packages)) {
-                    const name = packageNameFromNodeModulesPath(key);
-                    if (name && value.version) {
-                        versions.set(name, value.version);
-                    }
-                }
-            }
-            // v1 format fallback: dependencies.name.version
-            if (versions.size === 0 && lock.dependencies) {
-                for (const [name, value] of Object.entries(lock.dependencies)) {
-                    if (value.version) {
-                        versions.set(name, value.version);
-                    }
-                }
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // Try pnpm-lock.yaml (line-by-line, no YAML parser)
-    const pnpmLockPath = path.join(cwd, "pnpm-lock.yaml");
-    if (fs.existsSync(pnpmLockPath)) {
-        try {
-            const content = fs.readFileSync(pnpmLockPath, "utf-8");
-            // pnpm v9 importers format: dependency name on one line, version on the next
-            // Example:
-            //   '@modelcontextprotocol/sdk':
-            //     specifier: ^1.10.0
-            //     version: 1.26.0(zod@4.3.6)
-            const lines = content.split("\n");
-            let currentPkg = null;
-            for (const line of lines) {
-                // Match dependency name (with or without quotes, scoped packages)
-                const pkgMatch = line.match(/^\s{4,8}'?(@?[^':]+)'?:\s*$/);
-                if (pkgMatch) {
-                    currentPkg = pkgMatch[1].trim();
-                    continue;
-                }
-                // Match version line under a dependency
-                if (currentPkg) {
-                    const versionMatch = line.match(/^\s+version:\s+['"]?(\d+\.\d+[^('"\s]*)['"]?/);
-                    if (versionMatch) {
-                        versions.set(currentPkg, versionMatch[1]);
-                        currentPkg = null;
-                        continue;
-                    }
-                    // specifier line — skip, wait for version
-                    if (line.match(/^\s+specifier:/))
-                        continue;
-                    // Any other line resets current package context
-                    if (!line.match(/^\s/))
-                        currentPkg = null;
-                }
-            }
-            // Also parse package/snapshot keys. Requiring a numeric version after
-            // the separator handles scoped packages without splitting at their
-            // leading `@` (for example '@scope/pkg@1.2.3').
-            const pkgRegex = /^\s{2}'?(.+?)@(\d+[^:('"]*)[^:]*'?:\s*$/gm;
-            let match;
-            while ((match = pkgRegex.exec(content)) !== null) {
-                const name = match[1].replace(/^\//, "").trim();
-                const version = match[2].trim().replace(/['":]/g, "");
-                if (name && version && /^\d/.test(version) && !versions.has(name)) {
-                    versions.set(name, version);
-                }
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // Try yarn.lock
-    const yarnLockPath = path.join(cwd, "yarn.lock");
-    if (fs.existsSync(yarnLockPath)) {
-        try {
-            const content = fs.readFileSync(yarnLockPath, "utf-8");
-            // Format: "name@range":\n  version "x.y.z"
-            const blocks = content.split(/\n(?=\S)/);
-            for (const block of blocks) {
-                const headerMatch = block.match(/^"?([^@\s"]+)@/);
-                const versionMatch = block.match(/^\s+version\s+"([^"]+)"/m);
-                if (headerMatch && versionMatch) {
-                    versions.set(headerMatch[1], versionMatch[1]);
-                }
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // Fallback: extract version ranges from package.json
-    const pkgPath = path.join(cwd, "package.json");
-    if (fs.existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-            for (const [name, spec] of Object.entries(allDeps)) {
-                const version = extractVersionFromSpec(spec);
-                if (version)
-                    versions.set(name, version);
-            }
-        }
-        catch { /* skip */ }
-    }
-    return versions;
-}
-function packageNameFromNodeModulesPath(lockPath) {
-    const marker = "node_modules/";
-    const index = lockPath.lastIndexOf(marker);
-    return index === -1 ? "" : lockPath.slice(index + marker.length);
-}
-// =============================================================================
-// Rust: Cargo.lock
-// =============================================================================
-function resolveRust(cwd) {
-    const versions = new Map();
-    const lockPath = path.join(cwd, "Cargo.lock");
-    if (!fs.existsSync(lockPath)) {
-        // Fallback: parse Cargo.toml version strings
-        return resolveRustFromManifest(cwd);
-    }
-    try {
-        const content = fs.readFileSync(lockPath, "utf-8");
-        // [[package]]\nname = "serde"\nversion = "1.0.193"
-        const packageRegex = /\[\[package\]\]\s*\nname\s*=\s*"([^"]+)"\s*\nversion\s*=\s*"([^"]+)"/g;
-        let match;
-        while ((match = packageRegex.exec(content)) !== null) {
-            versions.set(match[1], match[2]);
-        }
-    }
-    catch { /* skip */ }
-    return versions;
-}
-function resolveRustFromManifest(cwd) {
-    const versions = new Map();
-    const cargoPath = path.join(cwd, "Cargo.toml");
-    if (!fs.existsSync(cargoPath))
-        return versions;
-    try {
-        const content = fs.readFileSync(cargoPath, "utf-8");
-        // name = "1.0" or name = { version = "1.0", ... }
-        const depRegex = /^([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]+)"|.*?version\s*=\s*"([^"]+)")/gm;
-        let match;
-        while ((match = depRegex.exec(content)) !== null) {
-            const name = match[1];
-            const version = match[2] || match[3];
-            if (version && /^\d/.test(version)) {
-                versions.set(name, version);
-            }
-        }
-    }
-    catch { /* skip */ }
-    return versions;
-}
-// =============================================================================
-// Python: poetry.lock > Pipfile.lock > requirements.txt
-// =============================================================================
-function resolvePython(cwd) {
-    const versions = new Map();
-    // poetry.lock
-    const poetryLock = path.join(cwd, "poetry.lock");
-    if (fs.existsSync(poetryLock)) {
-        try {
-            const content = fs.readFileSync(poetryLock, "utf-8");
-            const packageRegex = /\[\[package\]\]\s*\nname\s*=\s*"([^"]+)"\s*\nversion\s*=\s*"([^"]+)"/g;
-            let match;
-            while ((match = packageRegex.exec(content)) !== null) {
-                versions.set(match[1].toLowerCase(), match[2]);
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // Pipfile.lock
-    const pipfileLock = path.join(cwd, "Pipfile.lock");
-    if (fs.existsSync(pipfileLock)) {
-        try {
-            const lock = JSON.parse(fs.readFileSync(pipfileLock, "utf-8"));
-            const sections = [lock.default, lock.develop].filter(Boolean);
-            for (const section of sections) {
-                for (const [name, info] of Object.entries(section)) {
-                    const version = info.version;
-                    if (version) {
-                        versions.set(name.toLowerCase(), version.replace(/^==/, ""));
-                    }
-                }
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // requirements.txt pinned versions
-    const reqPath = path.join(cwd, "requirements.txt");
-    if (fs.existsSync(reqPath)) {
-        try {
-            const content = fs.readFileSync(reqPath, "utf-8");
-            for (const line of content.split("\n")) {
-                const match = line.trim().match(/^([a-zA-Z0-9_-]+)\s*==\s*(.+)/);
-                if (match) {
-                    versions.set(match[1].toLowerCase(), match[2].trim());
-                }
-            }
-        }
-        catch { /* skip */ }
-    }
-    return versions;
-}
-// =============================================================================
-// Go: go.sum > go.mod
-// =============================================================================
-function resolveGo(cwd) {
-    const versions = new Map();
-    // go.sum has exact versions
-    const goSumPath = path.join(cwd, "go.sum");
-    if (fs.existsSync(goSumPath)) {
-        try {
-            const content = fs.readFileSync(goSumPath, "utf-8");
-            for (const line of content.split("\n")) {
-                const match = line.match(/^(\S+)\s+(v[\d.]+)/);
-                if (match) {
-                    versions.set(match[1], match[2]);
-                }
-            }
-            if (versions.size > 0)
-                return versions;
-        }
-        catch { /* fall through */ }
-    }
-    // Fallback: go.mod require block
-    const goModPath = path.join(cwd, "go.mod");
-    if (fs.existsSync(goModPath)) {
-        try {
-            const content = fs.readFileSync(goModPath, "utf-8");
-            const requireMatch = content.match(/require\s*\(([\s\S]*?)\)/);
-            if (requireMatch) {
-                for (const line of requireMatch[1].split("\n")) {
-                    const match = line.trim().match(/^(\S+)\s+(v[\d.]+)/);
-                    if (match) {
-                        versions.set(match[1], match[2]);
-                    }
-                }
-            }
-        }
-        catch { /* skip */ }
-    }
-    return versions;
-}
-// =============================================================================
-// Helpers
-// =============================================================================
-/**
- * Extract a usable version from an npm version specifier.
- * "^4.18.2" -> "4.18.2", "~1.0.0" -> "1.0.0", ">=2.0.0" -> "2.0.0"
- */
-function extractVersionFromSpec(spec) {
-    if (!spec)
-        return null;
-    const match = spec.match(/(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
-    return match ? match[1] : null;
-}

package/dist/native-bindings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * better-sqlite3's native module: a real check and an actionable fix.
+ *
+ * `import("better-sqlite3")` succeeds even when the compiled module is
+ * missing; the failure comes at the first `new Database()`. Measured
+ * 2026-10-03 on node:24-bookworm-slim with npm 12.2.0, which blocks
+ * dependency install scripts not covered by `allowScripts`: `npm install`
+ * (local or -g) left no better_sqlite3.node, `--doctor` still reported the
+ * bindings as loaded, and every tool failed with "Could not locate the
+ * bindings file" and no hint why. `npx @4da/mcp-server` was unaffected.
+ */
+import type BetterSqlite3 from "better-sqlite3";
+export declare const NATIVE_BINDING_FIX: string;
+/** Errors that mean the compiled module is absent or built for another Node/platform. */
+export declare function isNativeBindingError(err: unknown): boolean;
+/** The first line of a native-binding error, with the fix appended. */
+export declare function nativeBindingMessage(err: unknown): string;
+/** Null when an in-memory database opens; otherwise why not, with the fix. */
+export declare function checkNativeBindings(Database: typeof BetterSqlite3): string | null;

package/dist/native-bindings.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * better-sqlite3's native module: a real check and an actionable fix.
+ *
+ * `import("better-sqlite3")` succeeds even when the compiled module is
+ * missing; the failure comes at the first `new Database()`. Measured
+ * 2026-10-03 on node:24-bookworm-slim with npm 12.2.0, which blocks
+ * dependency install scripts not covered by `allowScripts`: `npm install`
+ * (local or -g) left no better_sqlite3.node, `--doctor` still reported the
+ * bindings as loaded, and every tool failed with "Could not locate the
+ * bindings file" and no hint why. `npx @4da/mcp-server` was unaffected.
+ */
+// Each remedy measured on npm 12.2.0 (node:24-bookworm-slim), 2026-10-03.
+export const NATIVE_BINDING_FIX = "npm 12+ blocks dependency install scripts unless allowed. With npx: allow it once with " +
+    "`npm config set allow-scripts=better-sqlite3 --location=user` (or run `npx --allow-scripts=better-sqlite3 @4da/mcp-server`), " +
+    "then clear the npx cache (`npx clear-npx-cache`, or delete the _npx folder in your npm cache). " +
+    "In an npm install: `npm install-scripts approve better-sqlite3`, then `npm rebuild better-sqlite3`. " +
+    "Without a prebuilt binary for your platform the rebuild needs a C++ toolchain " +
+    "(macOS: xcode-select --install; Debian/Ubuntu: apt install build-essential python3; Windows: Visual Studio Build Tools).";
+/** Errors that mean the compiled module is absent or built for another Node/platform. */
+export function isNativeBindingError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /bindings file|better_sqlite3\.node|NODE_MODULE_VERSION|compiled against a different Node\.js version|invalid ELF header|not a valid Win32 application/i.test(msg);
+}
+/** The first line of a native-binding error, with the fix appended. */
+export function nativeBindingMessage(err) {
+    const first = (err instanceof Error ? err.message : String(err)).split("\n")[0].replace(/\s*Tried:\s*$/, "").trim();
+    return `better-sqlite3's native module is not usable (${first}). ${NATIVE_BINDING_FIX}`;
+}
+/** Null when an in-memory database opens; otherwise why not, with the fix. */
+export function checkNativeBindings(Database) {
+    try {
+        new Database(":memory:").close();
+        return null;
+    }
+    catch (err) {
+        return nativeBindingMessage(err);
+    }
+}