@4da/mcp-server 6.0.1 → 6.1.0

package/dist/live/upgrade-sources.js

@@ -19,7 +19,7 @@
  */
 import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
 import { ArchiveError, defaultFetch, fetchArchiveRootFiles } from "./package-archive.js";
-import { findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
+import { CHANGELOG_PARSER_VERSION, findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
 /** crates.io refuses API requests without a descriptive User-Agent. */
 export const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
 const INDEX_TTL = 6 * 3600;
@@ -124,13 +124,18 @@ export function archiveUrl(index, version) {
         return null;
     }
 }
+/** Cache key of one version's parsed changelog; it carries CHANGELOG_PARSER_VERSION. */
+export function changelogCacheKey(ecosystem, name, version) {
+    return `upgrade-impact:changelog:p${CHANGELOG_PARSER_VERSION}:${ecosystem}:${name}:${version}`;
+}
 /** Parsed changelog shipped inside one version's archive (cached 7 days per version). */
 export async function getChangelog(net, index, version) {
     const url = archiveUrl(index, version);
     if (!url) {
         return { found: false, reason: "the version's archive is not hosted on the package's own registry" };
     }
-    const key = `upgrade-impact:changelog:${index.ecosystem}:${index.name}:${version.version}`;
+    // The parser version is in the key: a parser fix must not wait out the 7-day TTL.
+    const key = changelogCacheKey(index.ecosystem, index.name, version.version);
     const hit = net.cache?.get(key);
     if (hit)
         return hit;

package/dist/memory-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a decision, agent memory or feedback record is written.
+ *
+ * Reads go through the database's main connection (read-only for the desktop
+ * app's database). A write into one of the app-owned tables the tools exist to
+ * write goes through FourDADatabase.writerFor: the app's own table via a
+ * separate write connection, or, when the app's schema lacks the table or a
+ * column, the server's store with a note. A stand-in object without writerFor
+ * (some tests hand tools a minimal double) writes to its own connection.
+ */
+import type { AppWritableTable, FourDADatabase, WriteTarget } from "./db.js";
+export declare function writerOf(db: FourDADatabase, table: AppWritableTable, columns: readonly string[]): WriteTarget;
+/** `_meta` for a tool result when the record could not go where it normally goes. */
+export declare function writeMeta(target: WriteTarget): {
+    _meta?: {
+        written_to: string;
+        note: string;
+    };
+};

package/dist/memory-store.js

@@ -0,0 +1,8 @@
+export function writerOf(db, table, columns) {
+    const writerFor = db.writerFor;
+    return typeof writerFor === "function" ? writerFor.call(db, table, columns) : { raw: db.getRawDb(), target: "database" };
+}
+/** `_meta` for a tool result when the record could not go where it normally goes. */
+export function writeMeta(target) {
+    return target.note ? { _meta: { written_to: target.target, note: target.note } } : {};
+}

package/dist/native-bindings.d.ts

@@ -8,12 +8,17 @@
  * (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.
+ *
+ * Since 6.1.0 the server uses Node's built-in node:sqlite when the runtime
+ * has it (sqlite-driver.ts), so this matters only on Node 22.0-22.12, where
+ * better-sqlite3 is the one driver.
  */
-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;
+export declare function checkNativeBindings(Database: new (file: string) => {
+    close(): unknown;
+}): string | null;

package/dist/native-bindings.js

@@ -9,6 +9,10 @@
  * (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.
+ *
+ * Since 6.1.0 the server uses Node's built-in node:sqlite when the runtime
+ * has it (sqlite-driver.ts), so this matters only on Node 22.0-22.12, where
+ * better-sqlite3 is the one driver.
  */
 // 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 " +

package/dist/project-tree.d.ts

@@ -9,23 +9,65 @@
  * app does not have this problem — it records each dependency's own manifest
  * directory — so this is the standalone counterpart of that inventory.
  *
- * A directory joins when it holds a lockfile (or go.mod / requirements.txt,
- * which carry exact versions themselves). Workspace members that share their
- * root's lockfile are covered by the root. Bounded: depth 2 below the root,
- * at most 64 projects, and directories that hold installed code, build
- * output, test fixtures or tool worktrees are skipped.
+ * A directory joins when it holds a lockfile (or go.mod / a requirements
+ * file, which carry exact versions themselves). Workspace members that share
+ * their root's lockfile are covered by the root. Directories that hold
+ * installed code, build output, test fixtures or tool worktrees are skipped.
+ *
+ * Bounded (MAX_DEPTH levels below the root, MAX_PROJECTS projects), and the
+ * bound is never silent. langchain keeps 108 lockfiles up to three levels
+ * down; the old bounds (depth 2, 64 projects) read 64 and dropped 44 with no
+ * trace in any answer (2026-10-10). Past a bound the walk keeps going without
+ * scanning, up to MAX_WALK_DIRS directories, so `discovery` can name every
+ * lockfile that was left out and say why.
  */
 import { type ProjectScanResult } from "./project-scanner.js";
+/**
+ * Measured on langchain (108 lockfiles, up to 3 levels down; 2026-10-10):
+ * the walk plus every project scan takes about 2 s. Depth 4 covers it with a
+ * level to spare; 256 projects is 2.4x its count.
+ */
+export declare const MAX_DEPTH = 4;
+export declare const MAX_PROJECTS = 256;
 export interface ProjectTreeEntry {
     dir: string;
     scan: ProjectScanResult;
 }
+/** What the walk left out, so an answer can say it is partial. */
+export interface TreeDiscovery {
+    /** Projects scanned (the root included). */
+    projects: number;
+    maxDepth: number;
+    maxProjects: number;
+    /** Lockfiles found but not scanned, relative to the root (the first MAX_LISTED_SKIPS). */
+    skipped: Array<{
+        path: string;
+        reason: "depth" | "project_limit";
+    }>;
+    /** Every lockfile found but not scanned (`skipped` may list fewer). */
+    skippedCount: number;
+    /** True when the walk itself stopped at MAX_WALK_DIRS: lockfiles beyond it were not even counted. */
+    walkTruncated: boolean;
+}
+/** Python requirement files: requirements.txt, requirements-dev.txt, dev_requirements.txt, _test_minimum_requirements.txt. */
+export declare function isRequirementsFileName(name: string): boolean;
+/** The lockfiles (and exact-pin files) that make a directory a project, by name. */
+export declare function lockfilesIn(dir: string, listing?: string[]): string[];
 /**
  * The root (always) and every locked project below it, each with its own
- * scan. Directories and lockfiles the repository's .gitignore excludes are not
- * part of the project and are skipped (gitignore.ts).
+ * scan, plus what the bounds left out. Directories and lockfiles the
+ * repository's .gitignore excludes are not part of the project and are
+ * skipped (gitignore.ts); they are not reported as left out either.
  */
-export declare function scanProjectTree(root: string): ProjectTreeEntry[];
+export declare function scanProjectTree(root: string, limits?: {
+    maxDepth: number;
+    maxProjects: number;
+}): {
+    entries: ProjectTreeEntry[];
+    discovery: TreeDiscovery;
+};
+/** One sentence for an answer, or null when nothing was left out. */
+export declare function discoveryNote(discovery: TreeDiscovery | null): string | null;
 /**
  * Resolution groups for the live layer: one per (project directory, ecosystem).
  * A lockfile whose manifest declared nothing the scanner could read still gets

package/dist/project-tree.js

@@ -10,11 +10,17 @@
  * app does not have this problem — it records each dependency's own manifest
  * directory — so this is the standalone counterpart of that inventory.
  *
- * A directory joins when it holds a lockfile (or go.mod / requirements.txt,
- * which carry exact versions themselves). Workspace members that share their
- * root's lockfile are covered by the root. Bounded: depth 2 below the root,
- * at most 64 projects, and directories that hold installed code, build
- * output, test fixtures or tool worktrees are skipped.
+ * A directory joins when it holds a lockfile (or go.mod / a requirements
+ * file, which carry exact versions themselves). Workspace members that share
+ * their root's lockfile are covered by the root. Directories that hold
+ * installed code, build output, test fixtures or tool worktrees are skipped.
+ *
+ * Bounded (MAX_DEPTH levels below the root, MAX_PROJECTS projects), and the
+ * bound is never silent. langchain keeps 108 lockfiles up to three levels
+ * down; the old bounds (depth 2, 64 projects) read 64 and dropped 44 with no
+ * trace in any answer (2026-10-10). Past a bound the walk keeps going without
+ * scanning, up to MAX_WALK_DIRS directories, so `discovery` can name every
+ * lockfile that was left out and say why.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -29,60 +35,143 @@ const LOCK_MARKERS = [
     "Cargo.lock",
     "poetry.lock",
     "uv.lock",
+    "pdm.lock",
     "Pipfile.lock",
     "go.mod",
-    "requirements.txt",
 ];
 const SKIP_DIRS = new Set([
     "node_modules", "target", ".git", "dist", "build", "out", "vendor", ".venv", "venv",
     "__pycache__", ".next", ".nuxt", "coverage", ".claude", ".codex", ".cursor", "fixtures",
     "__fixtures__", "testdata", "test-fixtures", "__tests__", ".turbo", ".cache", ".pnpm-store",
 ]);
-const MAX_DEPTH = 2;
-const MAX_PROJECTS = 64;
+/**
+ * Measured on langchain (108 lockfiles, up to 3 levels down; 2026-10-10):
+ * the walk plus every project scan takes about 2 s. Depth 4 covers it with a
+ * level to spare; 256 projects is 2.4x its count.
+ */
+export const MAX_DEPTH = 4;
+export const MAX_PROJECTS = 256;
+/** Directories visited in total, scanned or not: the hard cap on the walk itself. */
+const MAX_WALK_DIRS = 20_000;
+/** Lockfile paths listed in `discovery.skipped`; the count covers the rest. */
+const MAX_LISTED_SKIPS = 50;
+/** Python requirement files: requirements.txt, requirements-dev.txt, dev_requirements.txt, _test_minimum_requirements.txt. */
+export function isRequirementsFileName(name) {
+    return /requirements[\w.-]*\.txt$/i.test(name);
+}
+/** The lockfiles (and exact-pin files) that make a directory a project, by name. */
+export function lockfilesIn(dir, listing) {
+    let names;
+    try {
+        names = listing ?? fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const found = names.filter((n) => LOCK_MARKERS.includes(n) || isRequirementsFileName(n));
+    // pip-compile-multi and similar keep the pins in a requirements/ folder (superset: requirements/base.txt).
+    if (names.includes("requirements")) {
+        try {
+            for (const n of fs.readdirSync(path.join(dir, "requirements")))
+                if (/\.txt$/i.test(n))
+                    found.push(`requirements/${n}`);
+        }
+        catch {
+            // a file named "requirements"
+        }
+    }
+    return found;
+}
 /**
  * The root (always) and every locked project below it, each with its own
- * scan. Directories and lockfiles the repository's .gitignore excludes are not
- * part of the project and are skipped (gitignore.ts).
+ * scan, plus what the bounds left out. Directories and lockfiles the
+ * repository's .gitignore excludes are not part of the project and are
+ * skipped (gitignore.ts); they are not reported as left out either.
  */
-export function scanProjectTree(root) {
+export function scanProjectTree(root, limits = { maxDepth: MAX_DEPTH, maxProjects: MAX_PROJECTS }) {
     const entries = [{ dir: root, scan: scanCurrentProject(root) }];
     const ignore = new IgnoreRules(root);
-    const walk = (dir, rel, depth) => {
-        if (depth > MAX_DEPTH || entries.length >= MAX_PROJECTS)
-            return;
-        ignore.load(rel);
-        let children;
+    const skipped = [];
+    let skippedCount = 0;
+    let visited = 0;
+    let walkTruncated = false;
+    // One directory listing per directory: it decides both whether the
+    // directory is a project and which children to descend into.
+    const listing = (dir) => {
         try {
-            children = fs.readdirSync(dir, { withFileTypes: true });
+            return fs.readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            return;
+            return null;
         }
+    };
+    const walk = (dir, rel, depth, children) => {
         for (const child of children) {
-            if (entries.length >= MAX_PROJECTS)
-                return;
             if (!child.isDirectory() || SKIP_DIRS.has(child.name) || child.name.startsWith("."))
                 continue;
+            if (++visited > MAX_WALK_DIRS) {
+                walkTruncated = true;
+                return;
+            }
             const childRel = rel ? `${rel}/${child.name}` : child.name;
             if (ignore.ignores(childRel, true))
                 continue;
             const sub = path.join(dir, child.name);
-            ignore.load(childRel);
-            const locked = LOCK_MARKERS.some((marker) => fs.existsSync(path.join(sub, marker)) && !ignore.ignores(`${childRel}/${marker}`, false));
-            if (locked)
-                entries.push({ dir: sub, scan: scanCurrentProject(sub) });
-            walk(sub, childRel, depth + 1);
+            const grandchildren = listing(sub);
+            if (!grandchildren)
+                continue;
+            // A .gitignore is only read where one exists.
+            if (grandchildren.some((g) => g.name === ".gitignore"))
+                ignore.load(childRel);
+            const names = grandchildren.map((g) => g.name);
+            const locks = lockfilesIn(sub, names).filter((name) => !ignore.ignores(`${childRel}/${name}`, false));
+            if (locks.length > 0) {
+                const reason = depth > limits.maxDepth ? "depth" : entries.length >= limits.maxProjects ? "project_limit" : null;
+                if (reason === null) {
+                    entries.push({ dir: sub, scan: scanCurrentProject(sub) });
+                }
+                else {
+                    skippedCount += locks.length;
+                    for (const name of locks)
+                        if (skipped.length < MAX_LISTED_SKIPS)
+                            skipped.push({ path: `${childRel}/${name}`, reason });
+                }
+            }
+            walk(sub, childRel, depth + 1, grandchildren);
+            if (walkTruncated)
+                return;
         }
     };
-    walk(root, "", 1);
-    return entries;
+    walk(root, "", 1, listing(root) ?? []);
+    return {
+        entries,
+        discovery: { projects: entries.length, maxDepth: limits.maxDepth, maxProjects: limits.maxProjects, skipped, skippedCount, walkTruncated },
+    };
+}
+/** One sentence for an answer, or null when nothing was left out. */
+export function discoveryNote(discovery) {
+    if (!discovery || (discovery.skippedCount === 0 && !discovery.walkTruncated))
+        return null;
+    const parts = [];
+    if (discovery.skippedCount > 0) {
+        const depth = discovery.skipped.some((s) => s.reason === "depth");
+        const limit = discovery.skipped.some((s) => s.reason === "project_limit");
+        const why = [
+            depth ? `deeper than ${discovery.maxDepth} levels` : null,
+            limit ? `past the ${discovery.maxProjects}-project limit` : null,
+        ].filter(Boolean).join(" or ");
+        const listed = discovery.skipped.slice(0, 5).map((s) => s.path).join(", ");
+        parts.push(`${discovery.skippedCount} lockfile${discovery.skippedCount === 1 ? " was" : "s were"} found but NOT scanned (${why}): ${listed}${discovery.skippedCount > 5 ? ", ..." : ""}; pass project_path to scan one of them`);
+    }
+    if (discovery.walkTruncated)
+        parts.push(`the directory walk stopped after ${MAX_WALK_DIRS} directories, so lockfiles beyond that were not counted`);
+    return `Partial scan: ${parts.join("; ")}.`;
 }
 /** Lockfiles that make an ecosystem scannable in a directory even when no direct dependency was parsed. */
 const LOCKS_BY_LANGUAGE = {
     npm: ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"],
     rust: ["Cargo.lock"],
-    python: ["poetry.lock", "uv.lock", "Pipfile.lock", "requirements.txt"],
+    python: ["poetry.lock", "uv.lock", "pdm.lock", "Pipfile.lock"],
     go: ["go.mod"],
 };
 /**
@@ -94,8 +183,11 @@ const LOCKS_BY_LANGUAGE = {
 export function treeResolutionGroups(entries) {
     return entries.flatMap(({ dir, scan }) => {
         const byLanguage = { ...scan.depsByEcosystem };
+        const present = lockfilesIn(dir);
+        const pins = present.some((n) => isRequirementsFileName(n) || n.startsWith("requirements/"));
         for (const [language, locks] of Object.entries(LOCKS_BY_LANGUAGE)) {
-            if (!byLanguage[language] && locks.some((lock) => fs.existsSync(path.join(dir, lock)))) {
+            const pinned = language === "python" && pins;
+            if (!byLanguage[language] && (pinned || locks.some((lock) => present.includes(lock)))) {
                 byLanguage[language] = { deps: [], devDeps: [] };
             }
         }

package/dist/schema-registry.js

@@ -47,7 +47,7 @@ export const TOOL_REGISTRY = {
         annotations: { title: "Dependency health", ...READ_NETWORK },
     },
     upgrade_planner: {
-        summary: "Prioritized upgrade plan: the 4DA app's work order when computed (per-line targets, manifest vs lockfile fix), else the smallest version that fixes each vulnerability from the lockfiles. Call when the user asks what to upgrade.",
+        summary: "Prioritized upgrade plan for one project (project_path): the 4DA app's work order when computed (per-line targets, manifest vs lockfile fix), else the smallest version that fixes each vulnerability. Call when the user asks what to upgrade.",
         definition: upgradePlannerTool,
         category: "security",
         tags: ["upgrade", "dependencies", "recommendations", "versions"],
@@ -72,7 +72,7 @@ export const TOOL_REGISTRY = {
     },
     // --- Intelligence (mixed) ---
     what_should_i_know: {
-        summary: "Pre-task briefing scoped to the task: the dependencies it touches, their installed versions, version-confirmed vulnerabilities, releases since, your recorded decisions, and a delegation verdict. Call BEFORE starting a non-trivial task, especially one that changes dependencies.",
+        summary: "Pre-task briefing for a task in one project: the dependencies and package families it names, installed versions, confirmed vulnerabilities, releases since, your decisions, a delegation verdict. Call BEFORE a non-trivial task, especially one that changes dependencies.",
         definition: whatShouldIKnowTool,
         category: "intelligence",
         tags: ["briefing", "advisories", "pre-task", "delegation"],

package/dist/setup.d.ts

@@ -6,12 +6,85 @@
  * the user can start using 4DA tools immediately after install.
  *
  * Usage:
- *   npx @4da/mcp-server --setup
- *   4da-mcp-setup
+ *   npx @4da/mcp-server --setup [--dry-run]
+ *   4da-mcp-setup [--dry-run]
  *   pnpm run setup
+ *
+ * Audited 2026-10-05: three of the four editors were configured in files the
+ * editor never reads (`~/.vscode/mcp.json`, `~/.windsurf/mcp.json`, and
+ * `mcpServers` in a project's `.claude/settings.json`), and any config file
+ * that failed `JSON.parse` (VS Code's `mcp.json` is JSONC: comments and
+ * trailing commas are legal) was replaced by `{}` plus our entry, deleting
+ * every other server the user had. Each path below cites the doc it was
+ * checked against, and a file that cannot be parsed is never written.
+ */
+/** The Claude Code command printed instead of editing `~/.claude.json`. */
+export declare const CLAUDE_CODE_COMMAND = "claude mcp add --scope user 4da -- npx @4da/mcp-server";
+/** Where the paths are resolved: injected so tests can stand in any platform. */
+export interface SetupContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}
+export declare function currentContext(): SetupContext;
+/** An editor whose MCP config file this setup writes. */
+export interface EditorTarget {
+    name: string;
+    /** Config file the server entry goes into. */
+    configPath: string;
+    /** Directory whose existence means the editor is installed. */
+    detectDir: string;
+    /** Top-level key holding the servers: VS Code uses `servers`, the rest `mcpServers`. */
+    key: "mcpServers" | "servers";
+    /** The value written under `<key>["4da"]`. */
+    entry: Record<string, unknown>;
+    /** Where the path and key were verified. */
+    docs: string;
+}
+/**
+ * Every editor this setup can write, with its config path on `ctx.platform`.
+ * Pure: nothing is read from disk here.
+ */
+export declare function editorTargets(ctx?: SetupContext): EditorTarget[];
+/**
+ * Claude Code keeps user- and local-scope servers in `~/.claude.json`
+ * (`$CLAUDE_CONFIG_DIR/.claude.json` when set), a file it rewrites itself and
+ * that also holds the sign-in session and per-project state. Setup never
+ * edits it: it prints the `claude mcp add` command, which does.
+ * https://code.claude.com/docs/en/mcp
+ */
+export declare function claudeCodeConfigPath(ctx?: SetupContext): string;
+export type PlanAction = "create" | "update" | "unchanged" | "refuse";
+export interface ConfigPlan {
+    action: PlanAction;
+    /** The full new file content for create/update. */
+    content?: string;
+    /** Why a file is refused, for the user. */
+    reason?: string;
+}
+/**
+ * Decide what writing `entry` under `<key>["4da"]` does to a config file whose
+ * current text is `existing` (null when it does not exist).
+ *
+ * The file is parsed as JSONC (comments and trailing commas allowed) and
+ * edited in place with `jsonc-parser`'s `modify`, so other servers, other keys,
+ * comments and formatting all survive. A file that does not parse is refused,
+ * never replaced. An existing `4da` entry keeps its other fields (`env`, say);
+ * only the fields setup owns are set.
+ */
+export declare function planConfig(existing: string | null, key: string, entry: Record<string, unknown>): ConfigPlan;
+/**
+ * Write `content` to `filePath`: back up an existing file first, then write a
+ * temp file beside it and rename it over the original, so an interrupted run
+ * leaves either the old file or the new one, never half of one. A symlinked
+ * config (a dotfiles repo) is written through to its target.
+ * @returns The backup path, when one was made.
  */
+export declare function writeConfigAtomic(filePath: string, content: string): string | null;
+type Log = (line: string) => void;
 /**
  * Run the setup wizard: detect editors and write MCP configurations.
  * @param dryRun If true, only report what would be written without modifying files.
  */
-export declare function runSetup(dryRun?: boolean): void;
+export declare function runSetup(dryRun?: boolean, ctx?: SetupContext, log?: Log): void;
+export {};