@softerist/heuristic-mcp 3.0.17 → 3.1.0

package/lib/ignore-patterns.js

@@ -1,8 +1,8 @@
-// Comprehensive ignore patterns based on industry best practices
-// Researched from gitignore templates and development community standards
+
+
 
 export const IGNORE_PATTERNS = {
-  // JavaScript/Node.js
+  
   javascript: [
     '**/node_modules/**',
     '**/.next/**',
@@ -26,7 +26,7 @@ export const IGNORE_PATTERNS = {
     '**/yarn.lock',
   ],
 
-  // Python
+  
   python: [
     '**/__pycache__/**',
     '**/*.pyc',
@@ -59,7 +59,7 @@ export const IGNORE_PATTERNS = {
     '**/.ruff_cache/**',
   ],
 
-  // Java/Maven
+  
   java: [
     '**/target/**',
     '**/.gradle/**',
@@ -79,7 +79,7 @@ export const IGNORE_PATTERNS = {
     '**/*.ear',
   ],
 
-  // Android
+  
   android: [
     '**/.gradle/**',
     '**/build/**',
@@ -98,7 +98,7 @@ export const IGNORE_PATTERNS = {
     '**/.navigation/**',
   ],
 
-  // iOS/Swift
+  
   ios: [
     '**/Pods/**',
     '**/DerivedData/**',
@@ -119,19 +119,19 @@ export const IGNORE_PATTERNS = {
     '**/*.ipa',
   ],
 
-  // Go
+  
   go: ['**/vendor/**', '**/bin/**', '**/pkg/**', '**/*.exe', '**/*.test', '**/*.prof'],
 
-  // PHP
+  
   php: ['**/vendor/**', '**/composer.phar', '**/composer.lock', '**/.phpunit.result.cache'],
 
-  // Rust
+  
   rust: ['**/target/**', '**/Cargo.lock', '**/*.rs.bk'],
 
-  // Ruby
+  
   ruby: ['**/vendor/bundle/**', '**/.bundle/**', '**/Gemfile.lock', '**/.byebug_history'],
 
-  // .NET/C#
+  
   dotnet: [
     '**/bin/**',
     '**/obj/**',
@@ -142,21 +142,21 @@ export const IGNORE_PATTERNS = {
     '**/node_modules/**',
   ],
 
-  // Common (IDE, OS, Build tools)
+  
   common: [
-    // Version control
+    
     '**/.git/**',
     '**/.svn/**',
     '**/.hg/**',
     '**/.bzr/**',
 
-    // OS files
+    
     '**/.DS_Store',
     '**/Thumbs.db',
     '**/desktop.ini',
     '**/$RECYCLE.BIN/**',
 
-    // Backup files
+    
     '**/*.bak',
     '**/*.backup',
     '**/*~',
@@ -166,16 +166,16 @@ export const IGNORE_PATTERNS = {
     '**/#*#',
     '**/.#*',
 
-    // Lock files (editor/runtime, not package managers)
+    
     '**/*.lock',
     '**/.~lock*',
 
-    // Logs
+    
     '**/*.log',
     '**/logs/**',
     '**/*.log.*',
 
-    // IDEs and Editors
+    
     '**/.vscode/**',
     '**/.idea/**',
     '**/.sublime-project',
@@ -191,19 +191,19 @@ export const IGNORE_PATTERNS = {
     '**/*.tmproject',
     '**/tmtags',
 
-    // Vim
+    
     '**/*~',
     '**/*.swp',
     '**/*.swo',
     '**/.*.sw?',
     '**/Session.vim',
 
-    // Emacs
+    
     '**/*~',
     '**/#*#',
     '**/.#*',
 
-    // Environment files (secrets)
+    
     '**/.env',
     '**/.env.local',
     '**/.env.*.local',
@@ -220,21 +220,21 @@ export const IGNORE_PATTERNS = {
     '**/*.p12',
     '**/*.pfx',
 
-    // Temporary files
+    
     '**/tmp/**',
     '**/temp/**',
     '**/*.tmp',
     '**/*.temp',
     '**/.cache/**',
 
-    // Session & runtime
+    
     '**/.sass-cache/**',
     '**/connect.lock',
     '**/*.pid',
     '**/*.seed',
     '**/*.pid.lock',
 
-    // Coverage & test output
+    
     '**/coverage/**',
     '**/.nyc_output/**',
     '**/test-results/**',
@@ -242,61 +242,61 @@ export const IGNORE_PATTERNS = {
     '**/*.coverage',
     '**/htmlcov/**',
 
-    // Documentation builds
+    
     '**/docs/_build/**',
     '**/site/**',
 
-    // Misc
+    
     '**/*.orig',
     '**/core',
     '**/*.core',
   ],
 };
 
-// Map marker files to project types
+
 export const FILE_TYPE_MAP = {
-  // JavaScript/Node
+  
   'package.json': 'javascript',
   'package-lock.json': 'javascript',
   'yarn.lock': 'javascript',
   'pnpm-lock.yaml': 'javascript',
 
-  // Python
+  
   'requirements.txt': 'python',
   Pipfile: 'python',
   'pyproject.toml': 'python',
   'setup.py': 'python',
 
-  // Android
+  
   'build.gradle': 'android',
   'build.gradle.kts': 'android',
   'settings.gradle': 'android',
 
-  // Java
+  
   'pom.xml': 'java',
 
-  // iOS
+  
   Podfile: 'ios',
   'Package.swift': 'ios',
 
-  // Go
+  
   'go.mod': 'go',
 
-  // PHP
+  
   'composer.json': 'php',
 
-  // Rust
+  
   'Cargo.toml': 'rust',
 
-  // Ruby
+  
   Gemfile: 'ruby',
 
-  // .NET
+  
   '*.csproj': 'dotnet',
   '*.sln': 'dotnet',
 };
 
-// Directories to skip during project detection (recursion)
+
 export const SKIP_DIRECTORIES = [
   'node_modules',
   'dist',

package/lib/json-writer.js

@@ -20,29 +20,9 @@ function onceDrainOrError(stream) {
   });
 }
 
-/**
- * Streaming JSON array writer optimized for:
- * - TypedArray vectors streamed (no per-item vector allocation)
- * - backpressure safety
- * - configurable float rounding + flush threshold
- * - compact mode when indent === '' (no forced newlines)
- * - safe cleanup on failure (abort)
- * - optional native TypedArray.join(',') fast-path when rounding is disabled
- */
+
 export class StreamingJsonWriter {
-  /**
-   * @param {string} filePath
-   * @param {object} [opts]
-   * @param {number} [opts.highWaterMark] Stream internal buffer size.
-   * @param {number|null} [opts.floatDigits] Round floats to N digits. null disables rounding.
-   * @param {number} [opts.flushChars] Flush threshold for the internal string buffer.
-   * @param {string} [opts.indent] Indent prefix per item ("" for compact, "  " for pretty).
-   * @param {boolean} [opts.assumeFinite] Skip NaN/Infinity checks (unsafe if false data).
-   * @param {boolean} [opts.checkFinite] If set, overrides assumeFinite (true = check, false = skip).
-   * @param {boolean} [opts.noMutation] Avoid temporary mutation when stripping vector.
-   * @param {number} [opts.joinThreshold] Max elements to use single join() string.
-   * @param {number} [opts.joinChunkSize] Elements per join() chunk when chunking.
-   */
+  
   constructor(
     filePath,
     {
@@ -78,7 +58,7 @@ export class StreamingJsonWriter {
     this.first = true;
     this._streamError = null;
 
-    // Formatter + fast-path flag
+    
     this._useJoinFastPath = floatDigits === null;
 
     if (!this._useJoinFastPath) {
@@ -129,17 +109,14 @@ export class StreamingJsonWriter {
     this.first = true;
   }
 
-  /**
-   * Best-effort early shutdown (use in catch/finally blocks).
-   * Destroys the stream to avoid fd leaks when writeEnd() is not reached.
-   */
+  
   abort(err) {
     if (!this.stream) return;
     try {
       this._streamError = err || this._streamError || new Error('StreamingJsonWriter aborted');
       this.stream.destroy(this._streamError);
     } catch {
-      // ignore
+      
     } finally {
       this.stream = null;
     }
@@ -214,7 +191,7 @@ export class StreamingJsonWriter {
         try {
           item.vector = vec;
         } catch {
-          // ignore
+          
         }
       }
     }
@@ -234,11 +211,7 @@ export class StreamingJsonWriter {
     }
   }
 
-  /**
-   * Core write method.
-   * Returns null on synchronous success (fast path).
-   * Returns a Promise only when backpressure is hit (slow path).
-   */
+  
   _writeRaw(str) {
     if (this._streamError) throw this._streamError;
 

package/lib/logging.js

@@ -12,7 +12,7 @@ const originalConsole = {
 };
 
 export function enableStderrOnlyLogging() {
-  // Keep MCP stdout clean by routing all console output to stderr.
+  
   const redirect = (...args) => originalConsole.error(...args);
   // eslint-disable-next-line no-console
   console.log = redirect;
@@ -36,7 +36,7 @@ export async function setupFileLogging(config) {
     const writeLine = (level, args) => {
       if (!logStream) return;
       const message = util.format(...args);
-      // Skip empty lines (spacers) in log files
+      
       if (!message.trim()) return;
 
       const timestamp = new Date().toISOString();
@@ -53,7 +53,7 @@ export async function setupFileLogging(config) {
       const originalError = originalConsole.error;
       // eslint-disable-next-line no-console
       console[method] = (...args) => {
-        // Always send to original stderr to avoid MCP protocol pollution on stdout
+        
         originalError(...args);
         writeLine(level, args);
       };
@@ -89,25 +89,11 @@ export async function ensureLogDirectory(config) {
   return logPath;
 }
 
-// ============================================================================
-// Error Handling Utilities
-// ============================================================================
-
-/*
- * Error handling patterns used in this codebase:
- * 
- * SILENT_EXPECTED: Empty catch for expected failures (file not found, cleanup)
- *   Use for: fs.stat on optional files, cleanup on exit, optional features
- * 
- * LOG_AND_CONTINUE: Warn but continue execution
- *   Use for: Non-critical features, fallback scenarios
- * 
- * LOG_AND_RETHROW: Log context then propagate to caller  
- *   Use for: Fatal errors that caller must handle
- * 
- * VERBOSE_ONLY: Only log when verbose mode is enabled
- *   Use for: Performance diagnostics, debug information
- */
+
+
+
+
+
 export const ERROR_PATTERNS = {
   SILENT_EXPECTED: 'silent_expected',
   LOG_AND_CONTINUE: 'log_and_continue',
@@ -115,11 +101,7 @@ export const ERROR_PATTERNS = {
   VERBOSE_ONLY: 'verbose_only',
 };
 
-/**
- * Log message only when verbose mode is enabled.
- * @param {object|boolean} configOrVerbose - Config object with verbose property, or boolean
- * @param  {...any} args - Arguments to log
- */
+
 export function logVerbose(configOrVerbose, ...args) {
   const isVerbose = typeof configOrVerbose === 'boolean' 
     ? configOrVerbose 
@@ -129,15 +111,7 @@ export function logVerbose(configOrVerbose, ...args) {
   }
 }
 
-/**
- * Log a recoverable error with consistent formatting.
- * Use when the error is non-fatal and execution can continue.
- * @param {string} context - Where the error occurred
- * @param {Error} error - The caught error
- * @param {object} options - Optional configuration
- * @param {boolean} options.verbose - If true, log full stack trace
- * @param {string} options.fallbackAction - Description of fallback behavior
- */
+
 export function logRecoverableError(context, error, options = {}) {
   const message = error?.message || String(error);
   const prefix = `[${context}]`;
@@ -153,12 +127,7 @@ export function logRecoverableError(context, error, options = {}) {
   }
 }
 
-/**
- * Check if an error is expected and should be silently ignored.
- * @param {Error} error - The caught error
- * @param {string[]} expectedCodes - Expected error codes
- * @returns {boolean} True if error matches an expected code
- */
+
 export function isExpectedError(error, expectedCodes = ['ENOENT', 'ENOTDIR']) {
   return error && typeof error.code === 'string' && expectedCodes.includes(error.code);
 }

package/lib/onnx-backend.js

@@ -4,7 +4,7 @@ import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const IS_TEST_ENV = process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
 
-// Try to load onnxruntime-node, fallback to null if not available (e.g., Node v25+)
+
 let ort = null;
 let ortLoadError = null;
 try {
@@ -30,18 +30,18 @@ try {
   expectedOrtVersion = null;
 }
 
-// Try to import executionProviders for configuration
+
 let executionProviders = null;
 let ONNX = null;
 if (!IS_TEST_ENV) {
   try {
-    // Avoid Vite import-analysis on deep import by using an indirect dynamic import.
+    
     const dynamicImport = new Function('specifier', 'return import(specifier)');
     const backend = await dynamicImport('@huggingface/transformers/src/backends/onnx.js');
     executionProviders = backend.executionProviders;
     ONNX = backend.ONNX;
   } catch {
-    // Not available in all transformers.js versions
+    
   }
 }
 

package/lib/path-utils.js

@@ -1,28 +1,15 @@
-/**
- * Centralized path normalization utilities for cross-platform consistency.
- * Addresses Issue #13 from code review: inconsistent path normalization.
- */
+
 
 import path from 'path';
 
-/**
- * Normalize a file path for consistent comparison.
- * Converts backslashes to forward slashes and lowercases on Windows.
- * @param {string} value - Path to normalize
- * @returns {string} Normalized path suitable for comparison
- */
+
 export function normalizePath(value) {
   if (typeof value !== 'string') return '';
   const normalized = value.replace(/\\/g, '/');
   return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
 
-/**
- * Check if a target path is inside a base directory.
- * @param {string} basePath - Base directory path
- * @param {string} targetPath - Path to check
- * @returns {boolean} True if targetPath is inside basePath
- */
+
 export function isPathInside(basePath, targetPath) {
   const normalizedBase = normalizePath(basePath);
   const normalizedTarget = normalizePath(targetPath);
@@ -30,11 +17,7 @@ export function isPathInside(basePath, targetPath) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
-/**
- * Normalize a path for use as a cache key or map lookup.
- * @param {string} filePath - Path to normalize
- * @returns {string} Normalized path key
- */
+
 export function normalizePathKey(filePath) {
   return normalizePath(filePath);
 }

package/lib/project-detector.js

@@ -12,7 +12,7 @@ export class ProjectDetector {
     const maxDepth = typeof options.maxDepth === 'number' ? options.maxDepth : 2;
     const startDepth = typeof options.startDepth === 'number' ? options.startDepth : 0;
     const markerFiles = Object.keys(FILE_TYPE_MAP);
-    const discoveredTypes = new Map(); // type -> first marker found
+    const discoveredTypes = new Map(); 
 
     const checkDir = async (dir, depth) => {
       if (depth > maxDepth) return;
@@ -38,7 +38,7 @@ export class ProjectDetector {
         }
       }
 
-      // Recurse into subdirectories
+      
       if (depth < maxDepth) {
         for (const item of items) {
           if (item.isDirectory()) {
@@ -71,7 +71,7 @@ export class ProjectDetector {
       }
     }
 
-    // Remove duplicates
+    
     return [...new Set(patterns)];
   }
 

package/lib/server-lifecycle.js

@@ -1,7 +1,8 @@
-import fs from 'fs/promises';
-import fsSync from 'fs';
-import path from 'path';
-import os from 'os';
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import os from 'os';
+import { setTimeout as delay } from 'timers/promises';
 
 function isTestEnv() {
   return process.env.VITEST === 'true' || process.env.NODE_ENV === 'test';
@@ -27,10 +28,10 @@ export async function setupPidFile({
     try {
       await fs.mkdir(cacheDirectory, { recursive: true });
     } catch {
-      // ignore mkdir errors and attempt to write anyway
+      
     }
   }
-  // Clean up stale PID file if present
+  
   try {
     const raw = await fs.readFile(pidPath, 'utf-8');
     const existingPid = parseInt(String(raw).trim(), 10);
@@ -38,7 +39,7 @@ export async function setupPidFile({
       await fs.unlink(pidPath).catch(() => {});
     }
   } catch {
-    // ignore missing/invalid pid file
+    
   }
   try {
     await fs.writeFile(pidPath, `${process.pid}`, 'utf-8');
@@ -51,7 +52,7 @@ export async function setupPidFile({
     try {
       fsSync.unlinkSync(pidPath);
     } catch {
-      // ignore
+      
     }
   };
 
@@ -69,7 +70,7 @@ function isProcessRunning(pid) {
     process.kill(pid, 0);
     return true;
   } catch (err) {
-    // On Windows, EPERM can happen even if process exists.
+    
     if (err && err.code === 'EPERM') {
       return true;
     }
@@ -137,7 +138,7 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
         fsSync.unlinkSync(lockPath);
       }
     } catch {
-      // ignore cleanup errors
+      
     }
   };
 
@@ -148,7 +149,7 @@ export async function acquireWorkspaceLock({ cacheDirectory, workspaceDir = null
   return { acquired: true, lockPath };
 }
 
-export async function releaseWorkspaceLock({ cacheDirectory } = {}) {
+export async function releaseWorkspaceLock({ cacheDirectory } = {}) {
   if (!cacheDirectory || isTestEnv()) {
     return;
   }
@@ -159,7 +160,100 @@ export async function releaseWorkspaceLock({ cacheDirectory } = {}) {
     if (current && current.pid === process.pid) {
       await fs.unlink(lockPath).catch(() => {});
     }
-  } catch {
-    // ignore release errors
-  }
-}
+  } catch {
+    
+  }
+}
+
+async function terminateProcess(pid, { graceMs = 1500 } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (!isProcessRunning(pid)) return true;
+
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    
+  }
+
+  const pollCount = Math.max(1, Math.ceil(graceMs / 100));
+  for (let i = 0; i < pollCount; i++) {
+    if (!isProcessRunning(pid)) return true;
+    await delay(100);
+  }
+
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    
+  }
+
+  await delay(100);
+  return !isProcessRunning(pid);
+}
+
+export async function stopOtherHeuristicServers({
+  globalCacheRoot = null,
+  currentCacheDirectory = null,
+} = {}) {
+  if (isTestEnv() || !globalCacheRoot) {
+    return { killed: [], failed: [] };
+  }
+
+  const normalizeForCompare = (value) => {
+    if (!value) return '';
+    const resolved = path.resolve(value);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  };
+  const currentCacheDirResolved = normalizeForCompare(currentCacheDirectory);
+
+  let dirEntries = [];
+  try {
+    dirEntries = await fs.readdir(globalCacheRoot, { withFileTypes: true });
+  } catch {
+    return { killed: [], failed: [] };
+  }
+
+  const lockOwners = [];
+  for (const entry of dirEntries) {
+    if (!entry.isDirectory()) continue;
+    const cacheDirectory = path.join(globalCacheRoot, entry.name);
+    if (currentCacheDirResolved && normalizeForCompare(cacheDirectory) === currentCacheDirResolved) {
+      continue;
+    }
+
+    const lockPath = path.join(cacheDirectory, 'server.lock.json');
+    let lock = null;
+    try {
+      lock = JSON.parse(await fs.readFile(lockPath, 'utf-8'));
+    } catch {
+      continue;
+    }
+
+    const pid = Number(lock?.pid);
+    if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+
+    if (!isProcessRunning(pid)) {
+      await fs.unlink(lockPath).catch(() => {});
+      continue;
+    }
+
+    lockOwners.push({
+      pid,
+      workspace: typeof lock?.workspace === 'string' ? lock.workspace : null,
+      cacheDirectory,
+    });
+  }
+
+  const killed = [];
+  const failed = [];
+  for (const owner of lockOwners) {
+    const terminated = await terminateProcess(owner.pid);
+    if (terminated) {
+      killed.push(owner);
+    } else {
+      failed.push(owner);
+    }
+  }
+
+  return { killed, failed };
+}