create-merlin-brain 5.3.8 → 5.4.1

package/dist/server/server.js

@@ -3,6 +3,7 @@
  * AI-powered codebase intelligence for coding agents
  * https://merlin.build
  */
+// merlin:allow-large-file: MCP server single-entry-point — all tool registrations must live here for SDK compatibility; split deferred to a future refactor phase
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -13,6 +14,7 @@ import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { VERSION } from './version.js';
+import { startGuardian, stopGuardian } from './session-guardian.js';
 import { registerProjectTools } from './tools/project.js';
 import { registerBehaviorTools } from './tools/behaviors.js';
 import { registerVerificationTools } from './tools/verification.js';
@@ -53,6 +55,23 @@ function loadSavedConfig() {
     }
     return null;
 }
+/**
+ * Resolve the Merlin auth token for cloud sync.
+ * Prefers process.env.MERLIN_API_KEY (the real key source — client.ts uses it).
+ * Falls back to apiKey stored in ~/.merlin/config.json for callers that need
+ * an explicit token string (e.g. registerLiteTools, registerConfigSyncTools).
+ */
+function getAuthToken() {
+    try {
+        if (process.env.MERLIN_API_KEY)
+            return process.env.MERLIN_API_KEY;
+        const c = loadSavedConfig();
+        return c?.apiKey ?? null;
+    }
+    catch {
+        return process.env.MERLIN_API_KEY ?? null;
+    }
+}
 /** Create and configure the MCP server */
 export function createServer() {
     const server = new McpServer({
@@ -64,18 +83,45 @@ export function createServer() {
     // Intercept every tool response to ensure the ⟡🔮 badge is present.
     // This guarantees Merlin's visual identity on EVERY touchpoint without
     // patching 80+ individual tool handlers.
+    //
+    // SDK-version note: this monkey-patches the deprecated server.tool() API.
+    // If the MCP SDK is upgraded to a version that changes how tool handlers are
+    // registered, this patch may silently stop working and must be revisited.
+    //
+    // IMPORTANT: _badgeWrap must NOT call recordToolCall(). Each tool handler
+    // already records exactly once via coachWrap(), wrapResponse(), or a direct
+    // call. Adding it here would double-count every tool invocation and corrupt
+    // drift detection.
     const _origTool = server.tool.bind(server);
     const _badgeWrap = (handler) => {
         return async function (...handlerArgs) {
-            const result = await handler.apply(this, handlerArgs);
-            if (result?.content) {
-                for (const block of result.content) {
-                    if (block.type === 'text' && block.text && typeof block.text === 'string') {
-                        if (!block.text.includes('⟡🔮')) {
-                            block.text = `⟡🔮 MERLIN ›\n\n${block.text}`;
-                        }
-                    }
-                }
+            let result;
+            try {
+                result = await handler.apply(this, handlerArgs);
+            }
+            catch (err) {
+                console.error('[merlin] tool handler threw:', err);
+                throw err;
+            }
+            // Guard: skip only when there is no text content to badge.
+            // NOTE: error results ARE badged too — "badge on EVERY action" is the
+            // brand contract (CLAUDE.md); Merlin must stay visible even on failures.
+            const r = result;
+            if (!r || !Array.isArray(r.content) || r.content.length === 0) {
+                return result;
+            }
+            const firstTextIdx = r.content.findIndex((b) => b.type === 'text' && typeof b.text === 'string');
+            if (firstTextIdx === -1) {
+                return result;
+            }
+            const firstBlock = r.content[firstTextIdx];
+            if (firstBlock.text && !firstBlock.text.includes('⟡🔮')) {
+                // Build a new content array — do NOT mutate in place to stay safe for
+                // structured/outputSchema responses that may share references
+                const newContent = r.content.map((b, i) => i === firstTextIdx
+                    ? { ...b, text: `⟡🔮 MERLIN ›\n\n${b.text}` }
+                    : b);
+                return { ...r, content: newContent };
             }
             return result;
         };
@@ -98,7 +144,11 @@ export function createServer() {
     // Cache for resolved repo IDs to avoid repeated git/API calls
     // Key: url or 'auto' for auto-detected, Value: { repoId, expiresAt }
     const repoIdCache = new Map();
-    const REPO_ID_CACHE_TTL = 5 * 60 * 1000; // 5 minutes - repo ID won't change mid-session
+    const REPO_ID_CACHE_TTL = 5 * 60 * 1000; // 5 minutes — positive hits; repo ID won't change mid-session
+    const REPO_ID_NEGATIVE_TTL = 10 * 1000; // 10 seconds — negative hits; short so a freshly-connected repo isn't stuck
+    // In-flight dedup: coalesce concurrent resolveRepoId calls for the same key
+    // Prevents multiple parallel cold-cache lookups from all hitting the API simultaneously
+    const resolveRepoIdPending = new Map();
     // Cache the detected repo root path (full absolute path) for file operations
     // This is crucial for Claude Code's Glob tool to work with paths containing spaces
     let cachedRepoRootPath = null;
@@ -111,6 +161,27 @@ export function createServer() {
     // Helper to resolve repo ID from URL or use session-selected repo
     // Also caches the repo root path for use with file operations
     async function resolveRepoId(repoUrl) {
+        const dedupKey = repoUrl ?? 'auto';
+        // Fast-path: return cached result without acquiring the pending lock
+        if (!repoUrl && selectedRepoId)
+            return selectedRepoId;
+        const earlyHit = repoIdCache.get(dedupKey);
+        if (earlyHit && Date.now() < earlyHit.expiresAt)
+            return earlyHit.repoId;
+        // Coalesce concurrent in-flight requests for the same key
+        const inflight = resolveRepoIdPending.get(dedupKey);
+        if (inflight)
+            return inflight;
+        const promise = resolveRepoIdInner(repoUrl);
+        resolveRepoIdPending.set(dedupKey, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            resolveRepoIdPending.delete(dedupKey);
+        }
+    }
+    async function resolveRepoIdInner(repoUrl) {
         // If explicit URL provided, use it
         if (repoUrl) {
             const cacheKey = repoUrl;
@@ -120,7 +191,8 @@ export function createServer() {
             }
             const repo = await client.findRepoByUrl(repoUrl);
             const repoId = repo?.id || null;
-            repoIdCache.set(cacheKey, { repoId, expiresAt: Date.now() + REPO_ID_CACHE_TTL });
+            const ttl = repoId ? REPO_ID_CACHE_TTL : REPO_ID_NEGATIVE_TTL;
+            repoIdCache.set(cacheKey, { repoId, expiresAt: Date.now() + ttl });
             return repoId;
         }
         // If session has a selected repo, use it (takes precedence over auto-detect)
@@ -148,14 +220,15 @@ export function createServer() {
         }
         const detected = await detectRepository();
         if (!detected) {
-            repoIdCache.set(cacheKey, { repoId: null, expiresAt: Date.now() + 60000 });
+            repoIdCache.set(cacheKey, { repoId: null, expiresAt: Date.now() + REPO_ID_NEGATIVE_TTL });
             return null;
         }
         // Cache the repo root path - CRITICAL for paths with spaces
         cachedRepoRootPath = detected.rootDir;
         const repo = await client.findRepoByUrl(detected.url);
         const repoId = repo?.id || null;
-        repoIdCache.set(cacheKey, { repoId, expiresAt: Date.now() + REPO_ID_CACHE_TTL });
+        const autoTtl = repoId ? REPO_ID_CACHE_TTL : REPO_ID_NEGATIVE_TTL;
+        repoIdCache.set(cacheKey, { repoId, expiresAt: Date.now() + autoTtl });
         return repoId;
     }
     // Helper to get the full absolute repo root path
@@ -458,10 +531,6 @@ export function createServer() {
                 const liteClient = await getOrInitLiteClient(repoRoot);
                 if (liteClient) {
                     // Use Lite mode! Get local data + try cloud enhancement in parallel
-                    const getAuthToken = async () => {
-                        const config = loadSavedConfig();
-                        return config?.apiKey || null;
-                    };
                     const [howTo, files, conventions, upgradeMsg, liteExport] = await Promise.all([
                         liteClient.getHowTo(task),
                         liteClient.getFiles({ purpose: task }),
@@ -471,7 +540,7 @@ export function createServer() {
                     ]);
                     // Try cloud enhancement in parallel (non-blocking, 8s timeout)
                     const detected = await detectRepository(repoRoot);
-                    const cloudResult = await enhanceFromCloud(task, { files: liteExport.files, conventions: liteExport.conventions, overview: liteExport.manifest }, detected?.url, getAuthToken);
+                    const cloudResult = await enhanceFromCloud(task, { files: liteExport.files, conventions: liteExport.conventions, overview: liteExport.manifest }, detected?.url, async () => getAuthToken());
                     let context = `# Context for: ${task}\n\n`;
                     const modeLabel = cloudResult?.enhanced
                         ? '⟡🔮 MERLIN Lite + Cloud Enhanced'
@@ -2588,14 +2657,26 @@ export function createServer() {
         description: 'List of all analyzed repositories',
         mimeType: 'application/json',
     }, async () => {
-        const repos = await client.getRepositories();
-        return {
-            contents: [{
-                    uri: 'merlin://repos',
-                    mimeType: 'application/json',
-                    text: JSON.stringify(repos, null, 2),
-                }],
-        };
+        try {
+            const repos = await client.getRepositories();
+            return {
+                contents: [{
+                        uri: 'merlin://repos',
+                        mimeType: 'application/json',
+                        text: JSON.stringify(repos, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            console.error('[merlin] resource repos error:', err);
+            return {
+                contents: [{
+                        uri: 'merlin://repos',
+                        mimeType: 'application/json',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : 'Failed to fetch repositories' }),
+                    }],
+            };
+        }
     });
     // ============================================================
     // PROJECT MANAGEMENT TOOLS
@@ -2750,11 +2831,7 @@ export function createServer() {
         registerLiteTools({
             server,
             getRepoRootPath,
-            getAuthToken: async () => {
-                // Get token from saved config
-                const config = loadSavedConfig();
-                return config?.apiKey || null;
-            },
+            getAuthToken: async () => getAuthToken(),
         });
     } // end free: registerLiteTools
     // ============================================================
@@ -2771,10 +2848,7 @@ export function createServer() {
         // ============================================================
         registerConfigSyncTools({
             server,
-            getAuthToken: async () => {
-                const config = loadSavedConfig();
-                return config?.apiKey || null;
-            },
+            getAuthToken: async () => getAuthToken(),
         });
     } // end cloud: registerConfigSyncTools
     // ============================================================
@@ -2856,16 +2930,31 @@ export async function startServer() {
     await server.connect(transport);
     // Log to stderr (stdout is used for MCP protocol)
     console.error('Merlin MCP server started');
+    // ── Global error boundary — log and keep the server alive ─────────
+    // Without these, an uncaught async error in a tool handler would silently
+    // crash the process. These handlers log the problem and continue running
+    // so the session is not destroyed by a single misbehaving tool.
+    process.on('uncaughtException', (err) => {
+        console.error('[merlin] uncaughtException', err);
+    });
+    process.on('unhandledRejection', (reason) => {
+        console.error('[merlin] unhandledRejection', reason);
+    });
     // ── Start Guardian HTTP sidecar (non-blocking) ────────────────────
     // Enables hooks to query MCP session state via localhost HTTP.
     // Starts on a random port, writes port file for hooks to discover.
-    import('./session-guardian.js').then(({ startGuardian }) => {
-        startGuardian().catch(err => {
-            console.error(`Merlin Guardian: failed to start (non-fatal): ${err.message}`);
-        });
-    }).catch(() => {
-        console.error('Merlin Guardian: module load failed (non-fatal)');
+    // The guardian's own SIGTERM/SIGHUP/exit self-registrations have been
+    // removed; the exit paths below call stopGuardian() (statically imported,
+    // synchronous, idempotent) so the port file is always cleaned up before exit.
+    startGuardian().catch((err) => {
+        console.error(`Merlin Guardian: failed to start (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
     });
+    // Final safety net: clean up the guardian on ANY process exit path
+    // (covers paths that call process.exit directly). Idempotent.
+    process.on('exit', () => { try {
+        stopGuardian();
+    }
+    catch { /* ignore */ } });
     // ── Lifecycle: exit when parent (Claude Code) disconnects ──────────
     // Without these handlers, merlin-brain becomes a zombie process when
     // Claude Code closes the session. Over time, dozens of orphaned
@@ -2874,11 +2963,24 @@ export async function startServer() {
     // When Claude Code exits, stdin gets closed → the 'end' event fires.
     process.stdin.on('end', () => {
         console.error('Merlin MCP server: stdin closed (parent disconnected), exiting.');
+        try {
+            stopGuardian();
+        }
+        catch { /* ignore */ }
         process.exit(0);
     });
-    // Handle SIGTERM/SIGHUP gracefully (sent by OS or Claude Code on shutdown)
+    // Handle SIGTERM/SIGHUP gracefully (sent by OS or Claude Code on shutdown).
+    // stopGuardian() is called first so the .guardian-port file is removed
+    // before exit — a stale port file would confuse the next session startup.
     const gracefulExit = (signal) => {
         console.error(`Merlin MCP server: received ${signal}, exiting.`);
+        // Synchronous guardian cleanup — stopGuardian is statically imported and
+        // idempotent, so the .guardian-port file is always removed BEFORE exit.
+        // (A dynamic import().then() here would never drain before process.exit.)
+        try {
+            stopGuardian();
+        }
+        catch { /* guardian may not have started — safe */ }
         process.exit(0);
     };
     process.on('SIGTERM', () => gracefulExit('SIGTERM'));
@@ -2887,6 +2989,10 @@ export async function startServer() {
     process.stdout.on('error', (err) => {
         if (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED') {
             console.error('Merlin MCP server: stdout broken pipe, exiting.');
+            try {
+                stopGuardian();
+            }
+            catch { /* ignore */ }
             process.exit(0);
         }
     });