@softerist/heuristic-mcp 3.2.4 → 3.2.5

package/features/hybrid-search.js

@@ -336,7 +336,7 @@ export class HybridSearch {
             for (let k = 0; k < queryWordCount; k++) {
               if (lowerContent.includes(queryWords[k])) matchedWords++;
             }
-            chunk.score += (matchedWords / queryWordCount) * 0.3;
+            chunk.score += (matchedWords / queryWordCount) * PARTIAL_MATCH_BOOST;
           }
 
           if (chunk.content === undefined) {

package/features/index-codebase.js

@@ -2769,7 +2769,13 @@ export class CodebaseIndexer {
         lastCheckpointIntervalMs: checkpointIntervalMs,
         lastCheckpointSaves: checkpointSaveCount,
       });
-      await this.cache.save({ throwOnError: true });
+      try {
+        await this.cache.save({ throwOnError: true });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[Indexer] Final cache save failed after embedding pass: ${message}`);
+        throw error;
+      }
 
       this.sendProgress(
         100,

package/index.js

@@ -16,9 +16,6 @@ async function getTransformers() {
     if (transformersModule?.env) {
       transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
     }
-    if (transformersModule?.env) {
-      transformersModule.env.cacheDir = path.join(getGlobalCacheDir(), 'xenova');
-    }
   }
   return transformersModule;
 }
@@ -79,6 +76,13 @@ import {
 } from './lib/constants.js';
 const PID_FILE_NAME = '.heuristic-mcp.pid';
 
+function isTestRuntime() {
+  return (
+    process.env.VITEST === 'true' ||
+    process.env.NODE_ENV === 'test'
+  );
+}
+
 async function readLogTail(logPath, maxLines = 2000) {
   const data = await fs.readFile(logPath, 'utf-8');
   if (!data) return [];
@@ -134,6 +138,36 @@ async function printMemorySnapshot(workspaceDir) {
   return true;
 }
 
+async function flushLogsSafely(options) {
+  if (typeof flushLogs !== 'function') {
+    console.warn('[Logs] flushLogs helper is unavailable; skipping log flush.');
+    return;
+  }
+
+  try {
+    await flushLogs(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[Logs] Failed to flush logs: ${message}`);
+  }
+}
+
+function assertCacheContract(cacheInstance) {
+  const requiredMethods = [
+    'load',
+    'save',
+    'consumeAutoReindex',
+    'clearInMemoryState',
+    'getStoreSize',
+  ];
+  const missing = requiredMethods.filter((name) => typeof cacheInstance?.[name] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      `[Server] Cache implementation contract violation: missing method(s): ${missing.join(', ')}`
+    );
+  }
+}
+
 let embedder = null;
 let unloadMainEmbedder = null;
 let cache = null;
@@ -150,6 +184,9 @@ let setWorkspaceFeatureInstance = null;
 let autoWorkspaceSwitchPromise = null;
 let rootsCapabilitySupported = null;
 let rootsProbeInFlight = null;
+let lastRootsProbeTime = 0;
+let keepAliveTimer = null;
+const ROOTS_PROBE_COOLDOWN_MS = 2000;
 const WORKSPACE_BOUND_TOOL_NAMES = new Set([
   'a_semantic_search',
   'b_index_codebase',
@@ -202,6 +239,10 @@ function formatCrashDetail(detail) {
   }
 }
 
+function isBrokenPipeError(detail) {
+  return Boolean(detail && typeof detail === 'object' && detail.code === 'EPIPE');
+}
+
 function isCrashShutdownReason(reason) {
   const normalized = String(reason || '').toLowerCase();
   return normalized.includes('uncaughtexception') || normalized.includes('unhandledrejection');
@@ -223,6 +264,10 @@ function registerProcessDiagnostics({ isServerMode, requestShutdown, getShutdown
   let fatalHandled = false;
   const handleFatalError = (reason, detail) => {
     if (fatalHandled) return;
+    if (isBrokenPipeError(detail)) {
+      requestShutdown('stdio-epipe');
+      return;
+    }
     fatalHandled = true;
     console.error(`[Server] Fatal ${reason}: ${formatCrashDetail(detail)}`);
     requestShutdown(reason);
@@ -460,7 +505,9 @@ async function maybeAutoSwitchWorkspaceToPath(
 
   if (autoWorkspaceSwitchPromise) {
     await autoWorkspaceSwitchPromise;
-    return;
+    const currentNow = normalizePathForCompare(config.searchDirectory);
+    const targetNow = normalizePathForCompare(targetWorkspacePath);
+    if (targetNow === currentNow) return;
   }
 
   autoWorkspaceSwitchPromise = (async () => {
@@ -494,6 +541,9 @@ async function maybeAutoSwitchWorkspaceFromRoots(request) {
   if (rootsProbeInFlight) {
     return await rootsProbeInFlight;
   }
+  const now = Date.now();
+  if (now - lastRootsProbeTime < ROOTS_PROBE_COOLDOWN_MS) return null;
+  lastRootsProbeTime = now;
 
   rootsProbeInFlight = (async () => {
     const rootWorkspace = await detectWorkspaceFromRoots({ quiet: true });
@@ -566,7 +616,7 @@ async function initialize(workspaceDir) {
     }
   }
 
-  const isTest = Boolean(process.env.VITEST || process.env.VITEST_WORKER_ID);
+  const isTest = isTestRuntime();
   if (config.enableExplicitGc && typeof global.gc !== 'function' && !isTest) {
     console.warn(
       '[Server] enableExplicitGc=true but this process was not started with --expose-gc; continuing with explicit GC disabled.'
@@ -820,6 +870,7 @@ async function initialize(workspaceDir) {
   }
 
   cache = new EmbeddingsCache(config);
+  assertCacheContract(cache);
   console.info(`[Server] Cache directory: ${config.cacheDirectory}`);
 
   indexer = new CodebaseIndexer(embedder, cache, config, server);
@@ -936,7 +987,8 @@ async function initialize(workspaceDir) {
           context: 'loading cache in secondary read-only mode',
           canReindex: false,
         });
-        if (cache.getStoreSize() === 0) {
+        const storeSize = cache.getStoreSize();
+        if (storeSize === 0) {
           await tryAutoAttachWorkspaceCache('secondary-empty-cache', { canReindex: false });
         }
         if (config.verbose) {
@@ -1219,7 +1271,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (config.unloadModelAfterSearch && searchTools.includes(toolDef.name)) {
         setImmediate(async () => {
           if (typeof unloadMainEmbedder === 'function') {
-            await unloadMainEmbedder();
+            try {
+              await unloadMainEmbedder();
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              console.warn(`[Server] Post-search model unload failed: ${message}`);
+            }
           }
         });
       }
@@ -1270,13 +1327,14 @@ export async function main(argv = process.argv) {
     console.info(`[Server] Shutdown requested (${reason}).`);
     void gracefulShutdown(reason);
   };
+  const isTestEnv = isTestRuntime();
   registerProcessDiagnostics({
     isServerMode,
     requestShutdown,
     getShutdownReason: () => shutdownReason,
   });
 
-  if (isServerMode && !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test')) {
+  if (isServerMode && !isTestEnv) {
     enableStderrOnlyLogging();
   }
   if (wantsVersion) {
@@ -1403,29 +1461,31 @@ export async function main(argv = process.argv) {
 
   registerSignalHandlers(requestShutdown);
 
-  const detectedRootPromise = new Promise((resolve) => {
-    const HANDSHAKE_TIMEOUT_MS = 1000;
-    let settled = false;
-    const resolveOnce = (value) => {
-      if (settled) return;
-      settled = true;
-      resolve(value);
-    };
+  const detectedRootPromise = isTestEnv
+    ? Promise.resolve(null)
+    : new Promise((resolve) => {
+        const HANDSHAKE_TIMEOUT_MS = 1000;
+        let settled = false;
+        const resolveOnce = (value) => {
+          if (settled) return;
+          settled = true;
+          resolve(value);
+        };
 
-    const timer = setTimeout(() => {
-      console.warn(
-        `[Server] MCP handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms, proceeding without roots.`
-      );
-      resolveOnce(null);
-    }, HANDSHAKE_TIMEOUT_MS);
-
-    server.oninitialized = async () => {
-      clearTimeout(timer);
-      console.info('[Server] MCP handshake complete.');
-      const root = await detectWorkspaceFromRoots();
-      resolveOnce(root);
-    };
-  });
+        const timer = setTimeout(() => {
+          console.warn(
+            `[Server] MCP handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms, proceeding without roots.`
+          );
+          resolveOnce(null);
+        }, HANDSHAKE_TIMEOUT_MS);
+
+        server.oninitialized = async () => {
+          clearTimeout(timer);
+          console.info('[Server] MCP handshake complete.');
+          const root = await detectWorkspaceFromRoots();
+          resolveOnce(root);
+        };
+      });
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -1438,6 +1498,11 @@ export async function main(argv = process.argv) {
         requestShutdown('stdout-epipe');
       }
     });
+    process.stderr?.on?.('error', (err) => {
+      if (err?.code === 'EPIPE') {
+        requestShutdown('stderr-epipe');
+      }
+    });
   }
 
   const detectedRoot = await detectedRootPromise;
@@ -1461,13 +1526,16 @@ export async function main(argv = process.argv) {
 
   console.info('[Server] Heuristic MCP server started.');
 
-  void startBackgroundTasks().catch((err) => {
+  const backgroundTaskPromise = startBackgroundTasks().catch((err) => {
     console.error(`[Server] Background task error: ${err.message}`);
   });
+  if (isTestEnv) {
+    await backgroundTaskPromise;
+  }
   // Keep-Alive mechanism: ensure the process stays alive even if StdioServerTransport
   // temporarily loses its active handle status or during complex async chains.
-  if (isServerMode) {
-    setInterval(() => {
+  if (isServerMode && !isTestEnv && !keepAliveTimer) {
+    keepAliveTimer = setInterval(() => {
       // Logic to keep event loop active.
       // We don't need to do anything, just the presence of the timer is enough.
     }, SERVER_KEEP_ALIVE_INTERVAL_MS);
@@ -1480,6 +1548,11 @@ async function gracefulShutdown(signal) {
   console.info(`[Server] Received ${signal}, shutting down gracefully...`);
   const exitCode = isCrashShutdownReason(signal) ? 1 : 0;
 
+  if (keepAliveTimer) {
+    clearInterval(keepAliveTimer);
+    keepAliveTimer = null;
+  }
+
   const cleanupTasks = [];
 
   if (indexer && indexer.watcher) {
@@ -1516,7 +1589,7 @@ async function gracefulShutdown(signal) {
 
   await Promise.allSettled(cleanupTasks);
   console.info('[Server] Goodbye!');
-  await flushLogs({ close: true, timeoutMs: 1500 }).catch(() => {});
+  await flushLogsSafely({ close: true, timeoutMs: 1500 });
 
   setTimeout(() => process.exit(exitCode), 100);
 }
@@ -1525,14 +1598,13 @@ const isMain =
   process.argv[1] &&
   (path.resolve(process.argv[1]).toLowerCase() === fileURLToPath(import.meta.url).toLowerCase() ||
     process.argv[1].endsWith('heuristic-mcp') ||
-    process.argv[1].endsWith('heuristic-mcp.js') ||
-    path.basename(process.argv[1]) === 'index.js') &&
+    process.argv[1].endsWith('heuristic-mcp.js')) &&
   !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test');
 
 if (isMain) {
   main().catch(async (err) => {
     console.error(err);
-    await flushLogs({ close: true, timeoutMs: 500 }).catch(() => {});
+    await flushLogsSafely({ close: true, timeoutMs: 500 });
     process.exit(1);
   });
 }

package/lib/logging.js

@@ -4,6 +4,7 @@ import path from 'path';
 import util from 'util';
 
 let logStream = null;
+let stderrWritable = true;
 const originalConsole = {
   log: console.info,
   warn: console.warn,
@@ -11,8 +12,25 @@ const originalConsole = {
   info: console.info,
 };
 
+function isBrokenPipeError(error) {
+  return Boolean(error && typeof error === 'object' && error.code === 'EPIPE');
+}
+
+function writeToOriginalStderr(...args) {
+  if (!stderrWritable) return;
+  try {
+    originalConsole.error(...args);
+  } catch (error) {
+    if (isBrokenPipeError(error)) {
+      stderrWritable = false;
+      return;
+    }
+    throw error;
+  }
+}
+
 export function enableStderrOnlyLogging() {
-  const redirect = (...args) => originalConsole.error(...args);
+  const redirect = (...args) => writeToOriginalStderr(...args);
   // eslint-disable-next-line no-console
   console.log = redirect;
   console.info = redirect;
@@ -49,10 +67,9 @@ export async function setupFileLogging(config) {
     };
 
     const wrap = (method, level) => {
-      const originalError = originalConsole.error;
       // eslint-disable-next-line no-console
       console[method] = (...args) => {
-        originalError(...args);
+        writeToOriginalStderr(...args);
         writeLine(level, args);
       };
     };
@@ -63,7 +80,7 @@ export async function setupFileLogging(config) {
     wrap('info', 'INFO');
 
     logStream.on('error', (err) => {
-      originalConsole.error(`[Logs] Failed to write log file: ${err.message}`);
+      writeToOriginalStderr(`[Logs] Failed to write log file: ${err.message}`);
     });
 
     process.on('exit', () => {
@@ -72,7 +89,7 @@ export async function setupFileLogging(config) {
 
     return logPath;
   } catch (err) {
-    originalConsole.error(`[Logs] Failed to initialize log file: ${err.message}`);
+    writeToOriginalStderr(`[Logs] Failed to initialize log file: ${err.message}`);
     return null;
   }
 }

package/lib/server-lifecycle.js

@@ -4,10 +4,51 @@ import path from 'path';
 import os from 'os';
 import { setTimeout as delay } from 'timers/promises';
 
+const pidFilesToCleanup = new Set();
+const workspaceLocksToCleanup = new Set();
+let pidExitCleanupRegistered = false;
+let workspaceLockExitCleanupRegistered = false;
+
 function isTestEnv() {
   return process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
 }
 
+function cleanupPidFilesOnExit() {
+  for (const pidPath of pidFilesToCleanup) {
+    try {
+      fsSync.unlinkSync(pidPath);
+    } catch {}
+  }
+}
+
+function registerPidFileCleanup(pidPath) {
+  if (!pidPath) return;
+  pidFilesToCleanup.add(pidPath);
+  if (pidExitCleanupRegistered) return;
+  process.on('exit', cleanupPidFilesOnExit);
+  pidExitCleanupRegistered = true;
+}
+
+function cleanupWorkspaceLocksOnExit() {
+  for (const lockPath of workspaceLocksToCleanup) {
+    try {
+      const raw = fsSync.readFileSync(lockPath, 'utf-8');
+      const current = JSON.parse(raw);
+      if (current && current.pid === process.pid) {
+        fsSync.unlinkSync(lockPath);
+      }
+    } catch {}
+  }
+}
+
+function registerWorkspaceLockCleanup(lockPath) {
+  if (!lockPath) return;
+  workspaceLocksToCleanup.add(lockPath);
+  if (workspaceLockExitCleanupRegistered) return;
+  process.on('exit', cleanupWorkspaceLocksOnExit);
+  workspaceLockExitCleanupRegistered = true;
+}
+
 function getPidFilePath({ pidFileName, cacheDirectory }) {
   if (cacheDirectory) {
     return path.join(cacheDirectory, pidFileName);
@@ -44,13 +85,7 @@ export async function setupPidFile({
     return null;
   }
 
-  const cleanup = () => {
-    try {
-      fsSync.unlinkSync(pidPath);
-    } catch {}
-  };
-
-  process.on('exit', cleanup);
+  registerPidFileCleanup(pidPath);
   return pidPath;
 }
 
@@ -71,7 +106,8 @@ function isProcessRunning(pid) {
   }
 }
 
-export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null } = {}) {
+export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null, _retryCount = 0 } = {}) {
+  const MAX_LOCK_RETRIES = 3;
   if (!cacheDirectory || isTestEnv()) {
     return { acquired: true, lockPath: null };
   }
@@ -137,24 +173,16 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
       } else {
         await fs.unlink(lockPath).catch(() => {});
       }
-      return acquireWorkspaceLock({ cacheDirectory, workspaceDir });
+      if (_retryCount >= MAX_LOCK_RETRIES) {
+        console.warn(`[Server] Lock acquisition failed after ${MAX_LOCK_RETRIES} retries; starting in secondary mode.`);
+        return { acquired: false, lockPath, ownerPid: null };
+      }
+      return acquireWorkspaceLock({ cacheDirectory, workspaceDir, _retryCount: _retryCount + 1 });
     }
     throw err;
   }
 
-  const cleanup = () => {
-    try {
-      const raw = fsSync.readFileSync(lockPath, 'utf-8');
-      const current = JSON.parse(raw);
-      if (current && current.pid === process.pid) {
-        fsSync.unlinkSync(lockPath);
-      }
-    } catch {}
-  };
-
-  process.on('exit', cleanup);
-  process.on('SIGINT', cleanup);
-  process.on('SIGTERM', cleanup);
+  registerWorkspaceLockCleanup(lockPath);
 
   return { acquired: true, lockPath };
 }
@@ -169,6 +197,7 @@ export async function releaseWorkspaceLock({ cacheDirectory } = {}) {
     const current = JSON.parse(raw);
     if (current && current.pid === process.pid) {
       await fs.unlink(lockPath).catch(() => {});
+      workspaceLocksToCleanup.delete(lockPath);
     }
   } catch {}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "3.2.4",
+  "version": "3.2.5",
   "description": "An enhanced MCP server providing intelligent semantic code search with find-similar-code, recency ranking, and improved chunking. Fork of smart-coding-mcp.",
   "type": "module",
   "main": "index.js",