@4da/mcp-server 6.0.0 → 6.0.2

package/dist/db.js

@@ -8,8 +8,6 @@
 import path from "path";
 import * as fs from "fs";
 import * as os from "os";
-import { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
 import { checkNativeBindings, isNativeBindingError, nativeBindingMessage } from "./native-bindings.js";
 let Database;
 try {
@@ -23,38 +21,37 @@ catch (err) {
 export function nativeBindingProblem() {
     return checkNativeBindings(Database);
 }
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
  * Resolve the database path by checking multiple locations in priority order:
  * 1. FOURDA_DB_PATH env var
- * 2. data/4da.db relative to cwd (development)
- * 3. data/4da.db relative to project root (mcp-4da-server is inside project root)
- * 4. Platform-specific Tauri app data dirs (production)
- * 5. Final fallback: data/4da.db relative to cwd
+ * 2. data/4da.db relative to cwd: the desktop app's development database,
+ *    when the server is started in a checkout of the app's repository
+ * 3. The deployed desktop app's database (desktopAppDbPaths)
+ * 4. Otherwise the standalone database (standaloneDbPath), created on first use
+ *
+ * Until 6.0.2 a step between 2 and 3 looked for data/4da.db two directories
+ * above this file, which found the app's database while this server was the
+ * app repository's mcp-4da-server/ folder. Since the server moved to its own
+ * repository (6.0.1) that resolves to node_modules/@4da/ or to the folder
+ * holding a clone, never to an app database, so it was removed.
  */
 function getDefaultDbPath() {
     // 1. Environment variable (highest priority)
     if (process.env.FOURDA_DB_PATH) {
         return process.env.FOURDA_DB_PATH;
     }
-    // 2. Relative to cwd (development)
+    // 2. Relative to cwd (the app repository's development database)
     const cwdPath = path.resolve(process.cwd(), "data", "4da.db");
     if (fs.existsSync(cwdPath)) {
         return cwdPath;
     }
-    // 3. Relative to project root (mcp-4da-server is inside project root)
-    const projectRootPath = path.resolve(__dirname, "..", "..", "data", "4da.db");
-    if (fs.existsSync(projectRootPath)) {
-        return projectRootPath;
-    }
-    // 4. The desktop app's own database, where the deployed app keeps it.
+    // 3. The desktop app's own database, where the deployed app keeps it.
     for (const appDataPath of desktopAppDbPaths()) {
         if (fs.existsSync(appDataPath))
             return appDataPath;
     }
-    // 5. No desktop database: the standalone database, in the user's data dir.
+    // 4. No desktop database: the standalone database, in the user's data dir.
     return standaloneDbPath();
 }
 /**
@@ -104,6 +101,38 @@ export function standaloneDbPath() {
             : process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
     return path.join(base, "4da-mcp", "standalone.db");
 }
+/**
+ * Whether an error says the database file itself is unreadable: not SQLite at
+ * all, or damaged. better-sqlite3 reports these as SQLITE_NOTADB ("file is not
+ * a database") and SQLITE_CORRUPT ("database disk image is malformed").
+ */
+export function isUnreadableDbError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_NOTADB" || code === "SQLITE_CORRUPT")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /file is not a database|database disk image is malformed/i.test(message);
+}
+/**
+ * What to tell the user about an unreadable database. Every tool call used to
+ * answer with the bare SQLite text ("file is not a database"), with no way
+ * out. Nothing is deleted or moved automatically: the desktop app's database
+ * can be the user's whole corpus, and the standalone one holds their recorded
+ * decisions and agent memory.
+ */
+export function unreadableDbMessage(absolutePath, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const isStandaloneFile = path.resolve(absolutePath) === path.resolve(standaloneDbPath());
+    const remedy = isStandaloneFile
+        ? "It is this server's standalone database: move it aside (keep it if it holds decisions or agent " +
+            "memory you want) and the next call creates a new one."
+        : process.env.FOURDA_DB_PATH
+            ? "FOURDA_DB_PATH points at it: point it at a valid 4DA database, or unset it to use the default."
+            : "If it is the 4DA desktop app's database, start the app, which checks its database on startup. " +
+                "Do not delete it: it may be your only copy of the app's data.";
+    return (`The 4DA database at ${absolutePath} cannot be read (${detail}): the file is damaged or is not ` +
+        `a SQLite database. ${remedy} Run \`npx @4da/mcp-server --doctor\` for details.`);
+}
 /** Marker table written into every standalone database. */
 const STANDALONE_MARKER = "mcp_standalone";
 /**
@@ -200,6 +229,8 @@ export const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, p
 export class FourDADatabase {
     db;
     _isStandalone = false;
+    /** Absolute path of the open database file. */
+    dbPath;
     constructor(dbPath) {
         const resolvedPath = dbPath || getDefaultDbPath();
         // Resolve path - if relative, resolve from cwd
@@ -214,15 +245,29 @@ export class FourDADatabase {
                 fs.mkdirSync(dir, { recursive: true });
             }
         }
+        let opened = null;
         try {
-            this.db = new Database(absolutePath, { readonly: false }); // Need write for feedback
-            this.db.pragma("journal_mode = WAL");
+            opened = new Database(absolutePath, { readonly: false }); // Need write for feedback
+            opened.pragma("journal_mode = WAL");
         }
         catch (error) {
+            // Close the handle a failed pragma leaves open: every tool call retries
+            // the open, and on Windows each leaked handle also keeps the file locked
+            // against the move-aside the message below suggests.
+            try {
+                opened?.close();
+            }
+            catch {
+                // Nothing to close when the open itself failed.
+            }
             throw new Error(isNativeBindingError(error)
                 ? nativeBindingMessage(error)
-                : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+                : isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        this.db = opened;
+        this.dbPath = absolutePath;
         // Standalone mode: create schema for a brand-new database, and recognise
         // an existing standalone database as one on every later session.
         if (isNew) {
@@ -302,8 +347,10 @@ export class FourDADatabase {
                 if (integrityStatus !== "ok") {
                     return {
                         valid: false,
-                        error: `Database integrity check failed: ${integrityStatus}. `
-                            + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
+                        // It used to say "Try deleting data/4da.db": a path that is not
+                        // where the app keeps its database, and advice that destroys the
+                        // user's only copy of it.
+                        error: unreadableDbMessage(absolutePath, new Error(`integrity check failed: ${integrityStatus}`)),
                     };
                 }
             }
@@ -322,8 +369,9 @@ export class FourDADatabase {
         catch (error) {
             return {
                 valid: false,
-                error: `Failed to open database at ${absolutePath}: `
-                    + (error instanceof Error ? error.message : String(error)),
+                error: isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open database at ${absolutePath}: ` + (error instanceof Error ? error.message : String(error)),
             };
         }
         finally {
@@ -668,17 +716,6 @@ export class FourDADatabase {
       );
       CREATE INDEX IF NOT EXISTS idx_advantage_period ON advantage_score(period, computed_at);
 
-      -- Agent feedback — queried by record_agent_feedback, get_agent_feedback_stats
-      CREATE TABLE IF NOT EXISTS agent_feedback (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        item_id TEXT NOT NULL,
-        outcome TEXT NOT NULL,
-        context TEXT,
-        session_task TEXT,
-        recorded_at TEXT DEFAULT (datetime('now'))
-      );
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_item ON agent_feedback(item_id);
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
     `);
     }
     /**
@@ -1097,17 +1134,6 @@ export class FourDADatabase {
             .sort((a, b) => b.relevance_score - a.relevance_score)
             .slice(0, limit);
     }
-    /**
-     * Get a single source item by ID and type
-     */
-    getSourceItem(itemId, sourceType) {
-        const stmt = this.db.prepare(`
-      SELECT id, source_type, source_id, url, title, content, content_hash, created_at, last_seen
-      FROM source_items
-      WHERE id = ? AND source_type = ?
-    `);
-        return stmt.get(itemId, sourceType) || null;
-    }
     /**
      * Look up persisted necessity scores for an item (written by Rust analysis pipeline).
      * Returns defaults (0.0/null) if no necessity data exists yet.
@@ -1205,99 +1231,6 @@ export class FourDADatabase {
         return context;
     }
     // ===========================================================================
-    // Relevance Explanation
-    // ===========================================================================
-    /**
-     * Explain why an item was considered relevant
-     */
-    explainRelevance(itemId, sourceType) {
-        const item = this.getSourceItem(itemId, sourceType);
-        if (!item) {
-            return null;
-        }
-        const context = this.getUserContext(true, true);
-        const itemTopics = this.extractTopics(item.title + " " + item.content);
-        // Compute matching elements
-        const matchingInterests = context.interests
-            .filter((i) => itemTopics.some((t) => this.topicMatches(t, i.topic)))
-            .map((i) => i.topic);
-        const matchingTech = context.tech_stack.filter((tech) => itemTopics.some((t) => this.topicMatches(t, tech)));
-        const matchingTopics = context.ace?.active_topics
-            .filter((at) => itemTopics.some((t) => this.topicMatches(t, at.topic)))
-            .map((at) => at.topic) || [];
-        const matchingAffinities = context.learned?.topic_affinities
-            .filter((ta) => ta.affinity_score > 0 && itemTopics.some((t) => this.topicMatches(t, ta.topic)))
-            .map((ta) => ta.topic) || [];
-        // Compute score breakdown
-        const staticScore = matchingInterests.length * 0.3 +
-            matchingTech.length * 0.2 +
-            (context.domains.some((d) => itemTopics.some((t) => this.topicMatches(t, d)))
-                ? 0.15
-                : 0);
-        const aceScore = context.ace
-            ? matchingTopics.length * 0.1 +
-                context.ace.detected_tech.filter((dt) => itemTopics.some((t) => this.topicMatches(t, dt.name))).length *
-                    0.05
-            : 0;
-        // Learned affinity score DEMOTED in v19 (AD-029) — must mirror
-        // computeRelevanceScore so the explanation matches what actually
-        // scored (the two previously diverged on the anti-penalty weight too:
-        // scorer used *0.3, this explanation used *0.5).
-        const learnedScore = 0;
-        // Anti-penalty from user-authored exclusions only (learned anti-topics
-        // demoted with the rest of the behavioral stack, AD-029).
-        let antiPenalty = 0;
-        for (const exclusion of context.exclusions) {
-            if (itemTopics.some((t) => this.topicMatches(t, exclusion))) {
-                antiPenalty = 1.0; // Hard exclusion
-                break;
-            }
-        }
-        const finalScore = Math.max(0, Math.min(1, staticScore + aceScore + learnedScore - antiPenalty));
-        const scoreBreakdown = {
-            embedding_similarity: null, // Not computing embedding similarity in MCP server
-            static_match_score: Math.round(staticScore * 100) / 100,
-            ace_match_score: Math.round(aceScore * 100) / 100,
-            learned_affinity_score: Math.round(learnedScore * 100) / 100,
-            anti_penalty: Math.round(antiPenalty * 100) / 100,
-            final_score: Math.round(finalScore * 100) / 100,
-        };
-        const matchingContext = {
-            matching_interests: matchingInterests,
-            matching_tech: matchingTech,
-            matching_topics: matchingTopics,
-            matching_affinities: matchingAffinities,
-        };
-        // Generate human-readable explanation
-        const explanationParts = [];
-        if (matchingInterests.length > 0) {
-            explanationParts.push(`Matches your interests: ${matchingInterests.slice(0, 3).join(", ")}`);
-        }
-        if (matchingTech.length > 0) {
-            explanationParts.push(`Related to your tech stack: ${matchingTech.slice(0, 3).join(", ")}`);
-        }
-        if (matchingTopics.length > 0) {
-            explanationParts.push(`Relevant to recent work: ${matchingTopics.slice(0, 3).join(", ")}`);
-        }
-        if (matchingAffinities.length > 0) {
-            explanationParts.push(`You've shown interest in: ${matchingAffinities.slice(0, 3).join(", ")}`);
-        }
-        if (antiPenalty > 0) {
-            explanationParts.push(`Score reduced due to excluded topics`);
-        }
-        const explanation = explanationParts.length > 0
-            ? explanationParts.join(". ") + "."
-            : "No specific matches found - may be based on general relevance.";
-        return {
-            item_id: itemId,
-            source_type: sourceType,
-            title: item.title,
-            score_breakdown: scoreBreakdown,
-            matching_context: matchingContext,
-            explanation,
-        };
-    }
-    // ===========================================================================
     // Feedback
     // ===========================================================================
     /**
@@ -1392,160 +1325,6 @@ export class FourDADatabase {
     `);
     }
     // ===========================================================================
-    // Agent Feedback
-    // ===========================================================================
-    /**
-     * Ensure the agent_feedback table exists.
-     * Called on first use so existing databases (created before this feature)
-     * get the table added without requiring a migration.
-     */
-    ensureAgentFeedbackTable() {
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS agent_feedback (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        item_id TEXT NOT NULL,
-        outcome TEXT NOT NULL,
-        context TEXT,
-        session_task TEXT,
-        recorded_at TEXT DEFAULT (datetime('now'))
-      );
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_item ON agent_feedback(item_id);
-      CREATE INDEX IF NOT EXISTS idx_agent_feedback_outcome ON agent_feedback(outcome);
-    `);
-    }
-    /**
-     * Record agent feedback on recommended content items
-     */
-    recordAgentFeedback(itemIds, outcome, context, sessionTask) {
-        this.ensureAgentFeedbackTable();
-        const validOutcomes = ["used", "rejected", "partially_used"];
-        if (!validOutcomes.includes(outcome)) {
-            return {
-                success: false,
-                message: `Invalid outcome: ${outcome}. Valid outcomes: ${validOutcomes.join(", ")}`,
-                recorded_count: 0,
-            };
-        }
-        if (!itemIds || itemIds.length === 0) {
-            return {
-                success: false,
-                message: "item_ids must contain at least one item ID",
-                recorded_count: 0,
-            };
-        }
-        try {
-            const stmt = this.db.prepare(`
-        INSERT INTO agent_feedback (item_id, outcome, context, session_task)
-        VALUES (?, ?, ?, ?)
-      `);
-            const insertMany = this.db.transaction((ids) => {
-                let count = 0;
-                for (const id of ids) {
-                    stmt.run(id, outcome, context || null, sessionTask || null);
-                    count++;
-                }
-                return count;
-            });
-            const count = insertMany(itemIds);
-            return {
-                success: true,
-                message: `Recorded ${outcome} feedback for ${count} item(s)`,
-                recorded_count: count,
-            };
-        }
-        catch (error) {
-            return {
-                success: false,
-                message: `Failed to record agent feedback: ${error instanceof Error ? error.message : String(error)}`,
-                recorded_count: 0,
-            };
-        }
-    }
-    /**
-     * Get agent feedback statistics for the given period
-     */
-    getAgentFeedbackStats(days = 30) {
-        this.ensureAgentFeedbackTable();
-        const cutoff = `datetime('now', '-${Math.max(1, Math.min(365, days))} days')`;
-        // Outcome totals
-        const outcomeRows = this.db
-            .prepare(`SELECT outcome, COUNT(*) as cnt
-         FROM agent_feedback
-         WHERE recorded_at >= ${cutoff}
-         GROUP BY outcome`)
-            .all();
-        const outcomes = { used: 0, rejected: 0, partially_used: 0, total: 0 };
-        for (const row of outcomeRows) {
-            if (row.outcome === "used")
-                outcomes.used = row.cnt;
-            else if (row.outcome === "rejected")
-                outcomes.rejected = row.cnt;
-            else if (row.outcome === "partially_used")
-                outcomes.partially_used = row.cnt;
-            outcomes.total += row.cnt;
-        }
-        // By source type — join with source_items to get source_type
-        const sourceRows = this.db
-            .prepare(`SELECT COALESCE(si.source_type, 'unknown') as source_type, af.outcome, COUNT(*) as cnt
-         FROM agent_feedback af
-         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
-         WHERE af.recorded_at >= ${cutoff}
-         GROUP BY source_type, af.outcome
-         ORDER BY cnt DESC`)
-            .all();
-        // Aggregate source rows into per-source stats
-        const sourceMap = new Map();
-        for (const row of sourceRows) {
-            if (!sourceMap.has(row.source_type)) {
-                sourceMap.set(row.source_type, { used: 0, rejected: 0, partially_used: 0, total: 0 });
-            }
-            const entry = sourceMap.get(row.source_type);
-            if (row.outcome === "used")
-                entry.used += row.cnt;
-            else if (row.outcome === "rejected")
-                entry.rejected += row.cnt;
-            else if (row.outcome === "partially_used")
-                entry.partially_used += row.cnt;
-            entry.total += row.cnt;
-        }
-        const bySource = Array.from(sourceMap.entries()).map(([source_type, stats]) => ({
-            source_type,
-            ...stats,
-            usefulness_rate: stats.total > 0 ? (stats.used + stats.partially_used * 0.5) / stats.total : 0,
-        }));
-        // Top used items
-        const topItems = this.db
-            .prepare(`SELECT
-           af.item_id,
-           si.title,
-           si.source_type,
-           SUM(CASE WHEN af.outcome = 'used' THEN 1 ELSE 0 END) as used_count,
-           SUM(CASE WHEN af.outcome = 'rejected' THEN 1 ELSE 0 END) as rejected_count
-         FROM agent_feedback af
-         LEFT JOIN source_items si ON CAST(af.item_id AS INTEGER) = si.id
-         WHERE af.recorded_at >= ${cutoff}
-         GROUP BY af.item_id
-         HAVING used_count > 0
-         ORDER BY used_count DESC
-         LIMIT 10`)
-            .all();
-        // Recent feedback entries
-        const recentFeedback = this.db
-            .prepare(`SELECT item_id, outcome, context, session_task, recorded_at
-         FROM agent_feedback
-         WHERE recorded_at >= ${cutoff}
-         ORDER BY recorded_at DESC
-         LIMIT 20`)
-            .all();
-        return {
-            period_days: days,
-            outcomes,
-            by_source: bySource,
-            top_used_items: topItems,
-            recent_feedback: recentFeedback,
-        };
-    }
-    // ===========================================================================
     // Helper Methods
     // ===========================================================================
     /**

package/dist/index.js

@@ -68,7 +68,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
 // =============================================================================
@@ -376,7 +376,14 @@ export function buildServer() {
             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 +448,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 +471,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

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 {};