@softerist/heuristic-mcp 3.1.0 → 3.2.0

package/index.js

@@ -37,11 +37,11 @@ const require = createRequire(import.meta.url);
 const packageJson = require('./package.json');
 
 import { loadConfig, getGlobalCacheDir, isNonProjectDirectory } from './lib/config.js';
-import { clearStaleCaches } from './lib/cache-utils.js';
-import { enableStderrOnlyLogging, setupFileLogging, getLogFilePath } from './lib/logging.js';
-import { parseArgs, printHelp } from './lib/cli.js';
-import { clearCache } from './lib/cache-ops.js';
-import { logMemory, startMemoryLogger } from './lib/memory-logger.js';
+import { clearStaleCaches } from './lib/cache-utils.js';
+import { enableStderrOnlyLogging, setupFileLogging, getLogFilePath, flushLogs } from './lib/logging.js';
+import { parseArgs, printHelp } from './lib/cli.js';
+import { clearCache } from './lib/cache-ops.js';
+import { logMemory, startMemoryLogger } from './lib/memory-logger.js';
 import {
   registerSignalHandlers,
   setupPidFile,
@@ -181,6 +181,59 @@ function isToolResponseError(result) {
       entry.text.trim().toLowerCase().startsWith('error:')
   );
 }
+
+function formatCrashDetail(detail) {
+  if (detail instanceof Error) {
+    return detail.stack || detail.message || String(detail);
+  }
+  if (typeof detail === 'string') {
+    return detail;
+  }
+  try {
+    return JSON.stringify(detail);
+  } catch {
+    return String(detail);
+  }
+}
+
+function isCrashShutdownReason(reason) {
+  const normalized = String(reason || '').toLowerCase();
+  return normalized.includes('uncaughtexception') || normalized.includes('unhandledrejection');
+}
+
+function registerProcessDiagnostics({ isServerMode, requestShutdown, getShutdownReason }) {
+  if (!isServerMode) return;
+
+  process.on('beforeExit', (code) => {
+    const reason = getShutdownReason() || 'natural';
+    console.info(`[Server] Process beforeExit (code=${code}, reason=${reason}).`);
+  });
+
+  process.on('exit', (code) => {
+    const reason = getShutdownReason() || 'natural';
+    console.info(`[Server] Process exit (code=${code}, reason=${reason}).`);
+  });
+
+  let fatalHandled = false;
+  const handleFatalError = (reason, detail) => {
+    if (fatalHandled) return;
+    fatalHandled = true;
+    console.error(`[Server] Fatal ${reason}: ${formatCrashDetail(detail)}`);
+    requestShutdown(reason);
+    const forceExitTimer = setTimeout(() => {
+      console.error(`[Server] Forced exit after fatal ${reason}.`);
+      process.exit(1);
+    }, 5000);
+    forceExitTimer.unref?.();
+  };
+
+  process.on('uncaughtException', (err) => {
+    handleFatalError('uncaughtException', err);
+  });
+  process.on('unhandledRejection', (reason) => {
+    handleFatalError('unhandledRejection', reason);
+  });
+}
 
 async function resolveWorkspaceFromEnvValue(rawValue) {
   if (!rawValue || rawValue.includes('${')) return null;
@@ -1158,7 +1211,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 
 
-export async function main(argv = process.argv) {
+export async function main(argv = process.argv) {
   const parsed = parseArgs(argv);
   const {
     isServerMode,
@@ -1180,17 +1233,24 @@ export async function main(argv = process.argv) {
     unknownFlags,
   } = parsed;
 
-  let shutdownRequested = false;
-  const requestShutdown = (reason) => {
-    if (shutdownRequested) return;
-    shutdownRequested = true;
-    console.info(`[Server] Shutdown requested (${reason}).`);
-    void gracefulShutdown(reason);
-  };
-
-  if (isServerMode && !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test')) {
-    enableStderrOnlyLogging();
-  }
+  let shutdownRequested = false;
+  let shutdownReason = 'natural';
+  const requestShutdown = (reason) => {
+    if (shutdownRequested) return;
+    shutdownRequested = true;
+    shutdownReason = String(reason || 'unknown');
+    console.info(`[Server] Shutdown requested (${reason}).`);
+    void gracefulShutdown(reason);
+  };
+  registerProcessDiagnostics({
+    isServerMode,
+    requestShutdown,
+    getShutdownReason: () => shutdownReason,
+  });
+
+  if (isServerMode && !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test')) {
+    enableStderrOnlyLogging();
+  }
   if (wantsVersion) {
     console.info(packageJson.version);
     process.exit(0);
@@ -1400,8 +1460,9 @@ export async function main(argv = process.argv) {
 
 
 
-async function gracefulShutdown(signal) {
-  console.info(`[Server] Received ${signal}, shutting down gracefully...`);
+async function gracefulShutdown(signal) {
+  console.info(`[Server] Received ${signal}, shutting down gracefully...`);
+  const exitCode = isCrashShutdownReason(signal) ? 1 : 0;
 
   const cleanupTasks = [];
 
@@ -1443,13 +1504,14 @@ async function gracefulShutdown(signal) {
     }
   }
 
-  await Promise.allSettled(cleanupTasks);
-  console.info('[Server] Goodbye!');
-
-  
-  
-  setTimeout(() => process.exit(0), 100);
-}
+  await Promise.allSettled(cleanupTasks);
+  console.info('[Server] Goodbye!');
+  await flushLogs({ close: true, timeoutMs: 1500 }).catch(() => {});
+
+  
+  
+  setTimeout(() => process.exit(exitCode), 100);
+}
 
 const isMain =
   process.argv[1] &&
@@ -1459,6 +1521,10 @@ const isMain =
     path.basename(process.argv[1]) === 'index.js') &&
   !(process.env.VITEST === 'true' || process.env.NODE_ENV === 'test');
 
-if (isMain) {
-  main().catch(console.error);
-}
+if (isMain) {
+  main().catch(async (err) => {
+    console.error(err);
+    await flushLogs({ close: true, timeoutMs: 500 }).catch(() => {});
+    process.exit(1);
+  });
+}

package/lib/logging.js

@@ -24,7 +24,7 @@ export function enableStderrOnlyLogging() {
   console.info = redirect;
 }
 
-export async function setupFileLogging(config) {
+export async function setupFileLogging(config) {
   if (process.env.VITEST === 'true' || process.env.NODE_ENV === 'test') {
     return null;
   }
@@ -68,16 +68,51 @@ export async function setupFileLogging(config) {
       originalConsole.error(`[Logs] Failed to write log file: ${err.message}`);
     });
 
-    process.on('exit', () => {
-      if (logStream) logStream.end();
-    });
+    process.on('exit', () => {
+      if (logStream) logStream.end();
+    });
 
     return logPath;
   } catch (err) {
     originalConsole.error(`[Logs] Failed to initialize log file: ${err.message}`);
     return null;
-  }
-}
+  }
+}
+
+export async function flushLogs({ close = true, timeoutMs = 1000 } = {}) {
+  if (!logStream) return;
+
+  const stream = logStream;
+  await new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      if (close && logStream === stream) {
+        logStream = null;
+      }
+      resolve();
+    };
+
+    const timer = setTimeout(finish, timeoutMs);
+    timer.unref?.();
+
+    const onFinished = () => {
+      clearTimeout(timer);
+      finish();
+    };
+
+    try {
+      if (close) {
+        stream.end(onFinished);
+      } else {
+        stream.write('', onFinished);
+      }
+    } catch {
+      onFinished();
+    }
+  });
+}
 
 export function getLogFilePath(config) {
   return path.join(config.cacheDirectory, 'logs', 'server.log');

package/lib/server-lifecycle.js

@@ -78,7 +78,7 @@ function isProcessRunning(pid) {
   }
 }
 
-export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null } = {}) {
+export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null } = {}) {
   if (!cacheDirectory || isTestEnv()) {
     return { acquired: true, lockPath: null };
   }
@@ -86,23 +86,38 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
   await fs.mkdir(cacheDirectory, { recursive: true });
   const lockPath = path.join(cacheDirectory, 'server.lock.json');
 
-  const readLock = async () => {
+  const readLock = async () => {
     try {
       const raw = await fs.readFile(lockPath, 'utf-8');
       return JSON.parse(raw);
     } catch {
       return null;
     }
-  };
-
-  const existing = await readLock();
-  if (existing && Number.isInteger(existing.pid) && isProcessRunning(existing.pid)) {
-    return { acquired: false, lockPath, ownerPid: existing.pid, owner: existing };
-  }
-
-  if (existing) {
-    await fs.unlink(lockPath).catch(() => {});
-  }
+  };
+
+  const removeStaleLock = async (lockData) => {
+    const stalePid =
+      lockData && Number.isInteger(Number(lockData.pid)) ? Number(lockData.pid) : null;
+    const staleWorkspace =
+      typeof lockData?.workspace === 'string' && lockData.workspace.trim().length > 0
+        ? lockData.workspace
+        : null;
+    const stalePidLabel = stalePid ? `pid ${stalePid}` : 'unknown pid';
+    const staleWorkspaceLabel = staleWorkspace ? `, workspace "${staleWorkspace}"` : '';
+    console.warn(
+      `[Server] Detected stale workspace lock (${stalePidLabel}${staleWorkspaceLabel}) at ${lockPath}; removing stale lock and continuing startup.`
+    );
+    await fs.unlink(lockPath).catch(() => {});
+  };
+
+  const existing = await readLock();
+  if (existing && Number.isInteger(existing.pid) && isProcessRunning(existing.pid)) {
+    return { acquired: false, lockPath, ownerPid: existing.pid, owner: existing };
+  }
+
+  if (existing) {
+    await removeStaleLock(existing);
+  }
 
   const payload = {
     pid: process.pid,
@@ -119,14 +134,18 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
       await handle.close();
     }
   } catch (err) {
-    if (err && err.code === 'EEXIST') {
-      const current = await readLock();
-      if (current && Number.isInteger(current.pid) && isProcessRunning(current.pid)) {
-        return { acquired: false, lockPath, ownerPid: current.pid, owner: current };
-      }
-      await fs.unlink(lockPath).catch(() => {});
-      return acquireWorkspaceLock({ cacheDirectory, workspaceDir });
-    }
+    if (err && err.code === 'EEXIST') {
+      const current = await readLock();
+      if (current && Number.isInteger(current.pid) && isProcessRunning(current.pid)) {
+        return { acquired: false, lockPath, ownerPid: current.pid, owner: current };
+      }
+      if (current) {
+        await removeStaleLock(current);
+      } else {
+        await fs.unlink(lockPath).catch(() => {});
+      }
+      return acquireWorkspaceLock({ cacheDirectory, workspaceDir });
+    }
     throw err;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softerist/heuristic-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "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",