magector 1.7.1 → 2.1.0

package/src/mcp-server.js

@@ -16,7 +16,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 import { execFileSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
-import { existsSync, statSync, unlinkSync, appendFileSync, writeFileSync, readFileSync, mkdirSync } from 'fs';
+import { existsSync, statSync, unlinkSync, copyFileSync, renameSync, appendFileSync, writeFileSync, readFileSync, mkdirSync } from 'fs';
 import { stat } from 'fs/promises';
 import { glob } from 'glob';
 import path from 'path';
@@ -217,8 +217,9 @@ function checkDbFormat() {
 }
 
 /**
- * Start a background re-index process. Logs to .magector/magector.log.
- * MCP tools return an informative error while this is running.
+ * Start a background re-index process that builds to a temporary path.
+ * The old DB remains in place so search tools keep working during rebuild.
+ * On completion, the new index is swapped in atomically (old → .bak, new → current).
  */
 function startBackgroundReindex() {
   if (reindexInProgress) return;
@@ -229,30 +230,25 @@ function startBackgroundReindex() {
     return;
   }
 
-  reindexInProgress = true;
+  const tempDbPath = config.dbPath + '.new';
 
-  // Do NOT delete existing DB — the new indexer saves incrementally,
-  // so a partial index is better than no index. The Rust binary handles
-  // format incompatibility internally by clearing and rebuilding.
-  const hadExistingDb = existsSync(config.dbPath);
-  if (hadExistingDb) {
-    try {
-      const fstat = statSync(config.dbPath);
-      logToFile('WARN', `Existing DB (${(fstat.size / 1024).toFixed(0)} KB) will be overwritten by re-index.`);
-    } catch {}
-    try { unlinkSync(config.dbPath); } catch {}
+  // Clean up leftover temp DB from a previous failed reindex
+  if (existsSync(tempDbPath)) {
+    try { unlinkSync(tempDbPath); } catch {}
   }
 
-  logToFile('WARN', `Database format incompatible. Starting background re-index.`);
+  reindexInProgress = true;
+
+  const hadExistingDb = existsSync(config.dbPath);
+  logToFile('WARN', `Starting background re-index to temp path. Old DB ${hadExistingDb ? 'preserved for queries' : 'not found'}.`);
   console.error(`Database format incompatible. Starting background re-index (log: ${LOG_PATH})`);
 
   const reindexArgs = [
     'index',
     '-m', config.magentoRoot,
-    '-d', config.dbPath,
+    '-d', tempDbPath,
     '-c', config.modelCache
   ];
-  // Pass thread limit if configured
   const threads = process.env.MAGECTOR_THREADS;
   if (threads) {
     reindexArgs.push('--threads', threads);
@@ -267,7 +263,6 @@ function startBackgroundReindex() {
     env: rustEnv,
   });
 
-  // Pipe reindex stdout/stderr to log file (strip ANSI codes)
   reindexProcess.stdout.on('data', (d) => {
     const text = d.toString().replace(/\x1b\[[0-9;]*m/g, '').trim();
     if (text) logToFile('INDEX', text);
@@ -281,12 +276,27 @@ function startBackgroundReindex() {
     reindexInProgress = false;
     reindexProcess = null;
     if (code === 0) {
+      // Atomic swap: old → .bak, new → current
+      try {
+        if (existsSync(config.dbPath)) {
+          const backupPath = config.dbPath + '.bak';
+          if (existsSync(backupPath)) { try { unlinkSync(backupPath); } catch {} }
+          renameSync(config.dbPath, backupPath);
+          logToFile('INFO', 'Old DB moved to .bak');
+        }
+        renameSync(tempDbPath, config.dbPath);
+        logToFile('INFO', 'New index swapped into place.');
+      } catch (e) {
+        logToFile('ERR', `Failed to swap index: ${e.message}`);
+      }
       logToFile('INFO', 'Background re-index completed. Restarting serve process.');
       console.error('Background re-index completed. Restarting serve process.');
       if (serveProcess) serveProcess.kill();
       searchCache.clear();
       startServeProcess();
     } else {
+      // Clean up failed temp DB
+      try { if (existsSync(tempDbPath)) unlinkSync(tempDbPath); } catch {}
       logToFile('ERR', `Background re-index failed (exit code ${code})`);
       console.error(`Background re-index failed (exit code ${code}). Check ${LOG_PATH}`);
     }
@@ -552,13 +562,21 @@ function rustIndex(magentoRoot) {
   if (existsSync(descDbPath)) {
     indexArgs.push('--descriptions-db', descDbPath);
   }
-  const indexTimeout = parseInt(process.env.MAGECTOR_INDEX_TIMEOUT, 10) || 1800000;
+  // Default 4 hours, matching cli.js/init.js. Previously 1800000 (30 min),
+  // which was too short for ~80K-file enterprise Magento installs under CPU
+  // constraint and caused silent re-index loops via the MCP auto-index path.
+  const indexTimeout = parseInt(process.env.MAGECTOR_INDEX_TIMEOUT, 10) || 14400000;
   try {
     const result = execFileSync(config.rustBinary, indexArgs, { encoding: 'utf-8', timeout: indexTimeout, stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
     return result;
   } catch (err) {
     if (err.message && err.message.includes('ETIMEDOUT')) {
-      throw new Error(`Indexing timed out after ${indexTimeout / 1000}s. Set MAGECTOR_INDEX_TIMEOUT=3600000 (or higher) in your environment to increase the limit.`);
+      throw new Error(
+        `Indexing timed out after ${indexTimeout / 1000}s. Partial progress was saved ` +
+        `to disk — the next indexing run will auto-resume from the last checkpoint. ` +
+        `To raise the timeout further, set MAGECTOR_INDEX_TIMEOUT (milliseconds) in the ` +
+        `MCP server env, e.g. MAGECTOR_INDEX_TIMEOUT=28800000 for 8 hours.`
+      );
     }
     throw err;
   }
@@ -993,12 +1011,738 @@ function formatSearchResults(results) {
   return JSON.stringify({ results: formatted, count: formatted.length });
 }
 
+// ─── DI Dependency Tracing ─────────────────────────────────────
+
+/**
+ * Parse all di.xml files to build a dependency graph for a given class/interface.
+ * Returns preferences, plugins, virtualTypes, and argument overrides.
+ */
+async function traceDependency(className, direction = 'both') {
+  const root = config.magentoRoot;
+  const diFiles = await glob('**/etc/**/di.xml', { cwd: root, absolute: true, nodir: true });
+  const classLower = className.toLowerCase();
+  const classShort = className.split('\\').pop().toLowerCase();
+
+  const result = {
+    className,
+    preferences: [],
+    plugins: [],
+    virtualTypes: [],
+    argumentOverrides: [],
+    totalDiFiles: diFiles.length
+  };
+
+  for (const diFile of diFiles) {
+    let content;
+    try {
+      content = readFileSync(diFile, 'utf-8');
+    } catch { continue; }
+
+    const relativePath = diFile.replace(root + '/', '');
+
+    if (direction === 'resolve' || direction === 'both') {
+      // Find preferences: <preference for="ClassName" type="Implementation"/>
+      const prefRegex = /<preference\s+for="([^"]+)"\s+type="([^"]+)"\s*\/?>/g;
+      let match;
+      while ((match = prefRegex.exec(content)) !== null) {
+        const forClass = match[1];
+        if (forClass.toLowerCase().includes(classLower) || forClass.toLowerCase().includes(classShort)) {
+          result.preferences.push({
+            for: forClass,
+            type: match[2],
+            file: relativePath
+          });
+        }
+      }
+
+      // Find virtualTypes: <virtualType name="..." type="ClassName"/>
+      const vtRegex = /<virtualType\s+name="([^"]+)"[^>]*type="([^"]+)"[^>]*\/?>/g;
+      while ((match = vtRegex.exec(content)) !== null) {
+        const vtType = match[2];
+        if (vtType.toLowerCase().includes(classLower) || vtType.toLowerCase().includes(classShort)) {
+          result.virtualTypes.push({
+            name: match[1],
+            type: vtType,
+            file: relativePath
+          });
+        }
+      }
+    }
+
+    if (direction === 'dependents' || direction === 'both') {
+      // Find plugins targeting this class: <type name="ClassName"><plugin ... type="PluginClass"/></type>
+      const typeBlockRegex = /<type\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/type>/g;
+      let typeMatch;
+      while ((typeMatch = typeBlockRegex.exec(content)) !== null) {
+        const typeName = typeMatch[1];
+        const typeBlock = typeMatch[2];
+        if (typeName.toLowerCase().includes(classLower) || typeName.toLowerCase().includes(classShort)) {
+          const pluginRegex = /<plugin\s+name="([^"]+)"[^>]*type="([^"]+)"[^>]*\/?>/g;
+          let pMatch;
+          while ((pMatch = pluginRegex.exec(typeBlock)) !== null) {
+            result.plugins.push({
+              target: typeName,
+              pluginName: pMatch[1],
+              pluginClass: pMatch[2],
+              file: relativePath
+            });
+          }
+
+          // Find argument overrides
+          const argRegex = /<argument\s+name="([^"]+)"[^>]*xsi:type="([^"]+)"[^>]*>([^<]*)<\/argument>/g;
+          let aMatch;
+          while ((aMatch = argRegex.exec(typeBlock)) !== null) {
+            result.argumentOverrides.push({
+              target: typeName,
+              argumentName: aMatch[1],
+              argumentType: aMatch[2],
+              value: aMatch[3].trim().slice(0, 200),
+              file: relativePath
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+// ─── Error Message Parser ─────────────────────────────────────
+
+const ERROR_PATTERNS = [
+  {
+    pattern: /Cannot instantiate interface\s+([\w\\]+)/i,
+    type: 'missing_preference',
+    extract: (m) => ({ interface: m[1] }),
+    suggestion: (ctx) => `Interface ${ctx.interface} has no di.xml preference. Add <preference for="${ctx.interface}" type="ConcreteClass"/> in etc/di.xml`
+  },
+  {
+    pattern: /Class\s+([\w\\]+)\s+does not exist/i,
+    type: 'missing_class',
+    extract: (m) => ({ class: m[1] }),
+    suggestion: (ctx) => `Class ${ctx.class} not found. Check namespace, autoload (composer dump-autoload), and module registration.`
+  },
+  {
+    pattern: /Plugin class\s+([\w\\]+)\s+doesn't exist/i,
+    type: 'missing_plugin',
+    extract: (m) => ({ plugin: m[1] }),
+    suggestion: (ctx) => `Plugin class ${ctx.plugin} declared in di.xml but PHP file missing. Check namespace and file path.`
+  },
+  {
+    pattern: /Area code is not set/i,
+    type: 'area_code_not_set',
+    extract: () => ({}),
+    suggestion: () => 'Area code must be set before object manager usage. In CLI commands, use $state->setAreaCode(Area::AREA_GLOBAL) in execute().'
+  },
+  {
+    pattern: /Circular dependency:\s*([\w\\,\s]+)/i,
+    type: 'circular_dependency',
+    extract: (m) => ({ classes: m[1] }),
+    suggestion: (ctx) => `Circular DI dependency between: ${ctx.classes}. Break the cycle with Proxy class or Factory.`
+  },
+  {
+    pattern: /(\d+)\s+plugins\s+.*sortOrder.*conflict/i,
+    type: 'plugin_sort_conflict',
+    extract: (m) => ({ count: m[1] }),
+    suggestion: (ctx) => `${ctx.count} plugins have conflicting sortOrder values. Check di.xml for duplicate sortOrder on the same type.`
+  },
+  {
+    pattern: /Undefined index:\s+(\w+)\s+in\s+([\w\/\-.]+\.phtml)/i,
+    type: 'template_undefined_index',
+    extract: (m) => ({ index: m[1], template: m[2] }),
+    suggestion: (ctx) => `Template ${ctx.template} accesses undefined variable '${ctx.index}'. Check the Block class getData() or assign in layout XML.`
+  },
+  {
+    pattern: /SQLSTATE\[(\w+)\].*Table '[\w.]*\.(\w+)' doesn't exist/i,
+    type: 'missing_table',
+    extract: (m) => ({ sqlState: m[1], table: m[2] }),
+    suggestion: (ctx) => `Table '${ctx.table}' missing. Run setup:upgrade or check db_schema.xml. May need to regenerate declarative schema whitelist.`
+  },
+  {
+    pattern: /There are no commands defined in the "(\w+(?::\w+)*)" namespace/i,
+    type: 'missing_cli_command',
+    extract: (m) => ({ namespace: m[1] }),
+    suggestion: (ctx) => `CLI command namespace '${ctx.namespace}' not registered. Check module's etc/di.xml for Magento\\Framework\\Console\\CommandListInterface argument.`
+  },
+  {
+    pattern: /Invalid method\s+([\w\\]+)::(before|after|around)(\w+)/i,
+    type: 'invalid_plugin_method',
+    extract: (m) => ({ class: m[1], type: m[2], method: m[3] }),
+    suggestion: (ctx) => `Plugin method ${ctx.type}${ctx.method} in ${ctx.class} doesn't match any public method on the target class. Check method name spelling.`
+  }
+];
+
+/**
+ * Parse an error message and find relevant source files.
+ */
+async function parseError(errorText) {
+  const result = {
+    errorType: 'unknown',
+    parsed: {},
+    suggestion: null,
+    relatedFiles: [],
+    stackTrace: []
+  };
+
+  // Try to match against known patterns
+  for (const errPattern of ERROR_PATTERNS) {
+    const match = errorText.match(errPattern.pattern);
+    if (match) {
+      result.errorType = errPattern.type;
+      result.parsed = errPattern.extract(match);
+      result.suggestion = errPattern.suggestion(result.parsed);
+      break;
+    }
+  }
+
+  // Extract class names from error text for file search
+  const classNames = [...errorText.matchAll(/([\w\\]{2,}(?:\\[\w]+)+)/g)].map(m => m[1]);
+  const uniqueClasses = [...new Set(classNames)];
+
+  // Extract stack trace file paths
+  const stackFiles = [...errorText.matchAll(/#\d+\s+([\w\/\-.]+\.php)(?:\((\d+)\))?/g)];
+  result.stackTrace = stackFiles.map(m => ({
+    file: m[1],
+    line: m[2] ? parseInt(m[2]) : null
+  }));
+
+  // Search for related files using semantic search and class names
+  for (const cls of uniqueClasses.slice(0, 5)) {
+    const shortName = cls.split('\\').pop();
+    try {
+      const raw = await rustSearchAsync(shortName, 5);
+      const results = raw.map(normalizeResult).filter(r =>
+        r.className?.includes(shortName) || r.path?.toLowerCase().includes(shortName.toLowerCase())
+      );
+      for (const r of results.slice(0, 3)) {
+        if (!result.relatedFiles.some(f => f.path === r.path)) {
+          result.relatedFiles.push({ path: r.path, className: r.className, score: r.score });
+        }
+      }
+    } catch { /* search may fail if index not ready */ }
+  }
+
+  // For missing_preference errors, also trace DI
+  if (result.errorType === 'missing_preference' && result.parsed.interface) {
+    try {
+      const diTrace = await traceDependency(result.parsed.interface, 'resolve');
+      if (diTrace.preferences.length > 0) {
+        result.existingPreferences = diTrace.preferences;
+        result.suggestion += ` Found ${diTrace.preferences.length} existing preference(s) — check area-specific di.xml overrides.`;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return result;
+}
+
+// ─── Performance Profiling ─────────────────────────────────────
+
+const SUBSYSTEM_QUERIES = {
+  checkout_totals: {
+    searches: [
+      'quote totals collector plugin',
+      'TotalsCollector TotalsCollectorList',
+      'checkout totals calculation',
+      'quote address collect totals'
+    ],
+    pathFilters: ['/Model/Quote/', '/Plugin/', 'totals', 'collector'],
+    eventPatterns: ['sales_quote_collect_totals']
+  },
+  order_place: {
+    searches: [
+      'order place submit plugin',
+      'sales order place after observer',
+      'order management submit',
+      'payment place order'
+    ],
+    pathFilters: ['/Order/', '/Plugin/', '/Observer/', 'payment'],
+    eventPatterns: ['sales_order_place_after', 'checkout_submit_all_after']
+  },
+  product_save: {
+    searches: [
+      'product save plugin afterSave',
+      'catalog product save observer',
+      'product repository save',
+      'product save reindex'
+    ],
+    pathFilters: ['/Product/', '/Plugin/', '/Observer/', 'catalog'],
+    eventPatterns: ['catalog_product_save_after', 'catalog_product_save_before']
+  },
+  cart_add: {
+    searches: [
+      'add product to cart quote plugin',
+      'cart add product stock validation',
+      'quote addProduct beforeAddProduct',
+      'checkout cart add observer'
+    ],
+    pathFilters: ['/Cart/', '/Quote/', '/Plugin/', 'inventory', 'stock'],
+    eventPatterns: ['checkout_cart_add_product_complete', 'checkout_cart_product_add_after']
+  },
+  customer_login: {
+    searches: [
+      'customer login authenticate plugin',
+      'customer session login observer',
+      'customer account authenticate',
+      'customer login after event'
+    ],
+    pathFilters: ['/Customer/', '/Plugin/', '/Observer/', 'session', 'auth'],
+    eventPatterns: ['customer_login', 'customer_session_init']
+  },
+  catalog_reindex: {
+    searches: [
+      'catalog product indexer reindex',
+      'flat table indexer catalog',
+      'price indexer product',
+      'category product indexer'
+    ],
+    pathFilters: ['/Indexer/', '/Model/', 'catalog', 'price', 'flat'],
+    eventPatterns: ['catalog_product_reindex', 'catalogsearch_reset_search_result']
+  }
+};
+
+/**
+ * Profile a Magento subsystem for performance bottlenecks.
+ */
+async function profilePerformance(subsystem, threshold = 0) {
+  const configSub = SUBSYSTEM_QUERIES[subsystem];
+  if (!configSub) {
+    // Fallback: use subsystem name as search query
+    const fallbackSearches = [subsystem.replace(/_/g, ' ') + ' plugin', subsystem.replace(/_/g, ' ') + ' observer'];
+    const raw = [];
+    for (const q of fallbackSearches) {
+      try {
+        const r = await rustSearchAsync(q, 20);
+        raw.push(...r);
+      } catch { /* ignore */ }
+    }
+    const results = raw.map(normalizeResult);
+    const unique = [];
+    const seen = new Set();
+    for (const r of results) {
+      if (r.path && !seen.has(r.path)) {
+        seen.add(r.path);
+        unique.push(r);
+      }
+    }
+    return { subsystem, files: unique.slice(0, 20), plugins: [], observers: [], collectors: [] };
+  }
+
+  // Run all searches in parallel
+  const searchPromises = configSub.searches.map(q => rustSearchAsync(q, 20).catch(() => []));
+  const eventPromises = (configSub.eventPatterns || []).map(e =>
+    rustSearchAsync(`event ${e} observer`, 15).catch(() => [])
+  );
+  const allResults = await Promise.all([...searchPromises, ...eventPromises]);
+  const rawAll = allResults.flat();
+
+  // Normalize and deduplicate
+  const seen = new Set();
+  const allFiles = [];
+  for (const r of rawAll) {
+    const n = normalizeResult(r);
+    if (n.path && !seen.has(n.path)) {
+      seen.add(n.path);
+      allFiles.push(n);
+    }
+  }
+
+  // Categorize
+  const plugins = allFiles.filter(r => r.isPlugin || r.path?.includes('/Plugin/'));
+  const observers = allFiles.filter(r => r.isObserver || r.path?.includes('/Observer/') || r.path?.includes('events.xml'));
+  const collectors = allFiles.filter(r =>
+    configSub.pathFilters.some(f => r.path?.includes(f))
+  );
+
+  // Try to get complexity for PHP files
+  const phpFiles = allFiles.filter(r => r.path?.endsWith('.php')).slice(0, 30);
+  let complexityData = [];
+  if (phpFiles.length > 0) {
+    try {
+      const absPaths = phpFiles
+        .map(r => path.join(config.magentoRoot, r.path))
+        .filter(p => existsSync(p));
+      if (absPaths.length > 0) {
+        complexityData = await analyzeComplexity(absPaths);
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // Merge complexity into results
+  const filesWithComplexity = allFiles.map(r => {
+    const absPath = path.join(config.magentoRoot, r.path || '');
+    const cx = complexityData.find(c => c.file === absPath);
+    return {
+      ...r,
+      complexity: cx?.cyclomaticComplexity || 0,
+      complexityRating: cx?.rating || 'unknown',
+      functions: cx?.functions || 0,
+      lines: cx?.lines || 0
+    };
+  });
+
+  // Sort by complexity descending, filter by threshold
+  const sorted = filesWithComplexity
+    .filter(r => r.complexity >= threshold)
+    .sort((a, b) => b.complexity - a.complexity);
+
+  return {
+    subsystem,
+    totalFiles: allFiles.length,
+    files: sorted.slice(0, 30),
+    plugins: plugins.slice(0, 15),
+    observers: observers.slice(0, 15),
+    collectors: collectors.slice(0, 15)
+  };
+}
+
+// ─── BM25 Text Scoring ──────────────────────────────────────────
+// Simple BM25 scoring to complement vector similarity on exact class/method names.
+
+function bm25Score(queryTerms, text, k1 = 1.2, b = 0.75) {
+  if (!text || !queryTerms.length) return 0;
+  const words = text.toLowerCase().split(/[\W_]+/).filter(Boolean);
+  const docLen = words.length;
+  const avgDocLen = 200;
+  let score = 0;
+  for (const term of queryTerms) {
+    const termLower = term.toLowerCase();
+    const tf = words.filter(w => w === termLower).length;
+    if (tf === 0) continue;
+    const numerator = tf * (k1 + 1);
+    const denominator = tf + k1 * (1 - b + b * (docLen / avgDocLen));
+    score += numerator / denominator;
+  }
+  return score;
+}
+
+/**
+ * Hybrid rerank: combine vector score with BM25 text score.
+ * @param {Array} results - normalized search results
+ * @param {string} query - original query string
+ * @param {number} bm25Weight - weight for BM25 component (default 0.3)
+ */
+function hybridRerank(results, query, bm25Weight = 0.3) {
+  if (!results.length || !query) return results;
+  const queryTerms = query.toLowerCase().split(/[\s_\\]+/).filter(t => t.length > 2);
+  if (!queryTerms.length) return results;
+
+  return results.map(r => {
+    const textScore = bm25Score(queryTerms, (r.searchText || '') + ' ' + (r.className || '') + ' ' + (r.path || ''));
+    // Normalize BM25 score relative to max possible
+    const bonus = Math.min(textScore * bm25Weight, 1.0);
+    return { ...r, score: (r.score || 0) + bonus, bm25: textScore };
+  }).sort((a, b) => b.score - a.score);
+}
+
+// ─── Query Expansion ────────────────────────────────────────────
+// Expand queries with Magento domain synonyms for better recall.
+
+const MAGENTO_SYNONYMS = {
+  plugin: ['interceptor', 'around method', 'before after'],
+  preference: ['di override', 'rewrite', 'di.xml for type'],
+  observer: ['event listener', 'event handler', 'events.xml'],
+  model: ['entity', 'resource model'],
+  block: ['view block', 'template block'],
+  controller: ['action class', 'execute method', 'route handler'],
+  cron: ['scheduled task', 'crontab.xml'],
+  api: ['rest endpoint', 'webapi', 'service contract'],
+  layout: ['xml layout', 'handle', 'container', 'reference block'],
+  checkout: ['cart', 'quote', 'totals collection'],
+  order: ['sales order', 'order placement', 'order submit'],
+  product: ['catalog product', 'product entity'],
+  customer: ['customer entity', 'customer account'],
+  indexer: ['reindex', 'flat table', 'price index'],
+  payment: ['payment method', 'payment gateway', 'payment information'],
+  shipping: ['carrier', 'shipping method', 'delivery'],
+  stock: ['inventory', 'salable quantity', 'source item'],
+};
+
+function expandQuery(query) {
+  const terms = query.toLowerCase().split(/\s+/);
+  const expanded = [query]; // keep original query as-is
+  for (const term of terms) {
+    const synonyms = MAGENTO_SYNONYMS[term];
+    if (synonyms) {
+      expanded.push(...synonyms);
+    }
+  }
+  return expanded.join(' ');
+}
+
+// ─── Module Filtering ───────────────────────────────────────────
+// Filter search results by vendor/module namespace pattern.
+
+function filterByModule(results, moduleFilter) {
+  if (!moduleFilter) return results;
+  const patterns = Array.isArray(moduleFilter) ? moduleFilter : [moduleFilter];
+  return results.filter(r => {
+    const mod = r.module || '';
+    const filePath = r.path || '';
+    return patterns.some(pat => {
+      if (pat.includes('*')) {
+        const regex = new RegExp('^' + pat.replace(/\*/g, '.*') + '$', 'i');
+        return regex.test(mod) || regex.test(filePath);
+      }
+      return mod.toLowerCase().includes(pat.toLowerCase()) ||
+             filePath.toLowerCase().includes(pat.toLowerCase());
+    });
+  });
+}
+
+// ─── Layout XML Search ──────────────────────────────────────────
+
+async function findLayout(query, handle) {
+  const root = config.magentoRoot;
+  const layoutFiles = await glob('**/view/**/layout/**/*.xml', { cwd: root, absolute: true, nodir: true });
+  const queryLower = (query || '').toLowerCase();
+  const handleLower = (handle || '').toLowerCase();
+
+  const results = [];
+
+  for (const file of layoutFiles) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    const relativePath = file.replace(root + '/', '');
+    const fileName = path.basename(file, '.xml');
+
+    const handleMatch = handleLower && fileName.toLowerCase().includes(handleLower);
+    const contentMatch = queryLower && content.toLowerCase().includes(queryLower);
+
+    if (!handleMatch && !contentMatch) continue;
+
+    const blocks = [];
+    const blockRegex = /<block\s+[^>]*(?:class|name)="([^"]+)"[^>]*/g;
+    let m;
+    while ((m = blockRegex.exec(content)) !== null) blocks.push(m[1]);
+
+    const containers = [];
+    const containerRegex = /<(?:container|referenceContainer)\s+[^>]*name="([^"]+)"[^>]*/g;
+    while ((m = containerRegex.exec(content)) !== null) containers.push(m[1]);
+
+    const refBlocks = [];
+    const refBlockRegex = /<referenceBlock\s+[^>]*name="([^"]+)"[^>]*/g;
+    while ((m = refBlockRegex.exec(content)) !== null) refBlocks.push(m[1]);
+
+    results.push({
+      path: relativePath,
+      handle: fileName,
+      blocks: [...new Set(blocks)],
+      containers: [...new Set(containers)],
+      referenceBlocks: [...new Set(refBlocks)],
+      score: (handleMatch ? 1.0 : 0) + (contentMatch ? 0.5 : 0)
+    });
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}
+
+// ─── Impact Analysis ────────────────────────────────────────────
+
+async function analyzeImpact(className) {
+  const root = config.magentoRoot;
+  const shortName = className.split('\\').pop();
+
+  const references = {
+    className,
+    useStatements: [],
+    diXmlReferences: [],
+    instantiations: [],
+    typeHints: [],
+    total: 0
+  };
+
+  // Use vector search to find candidate files (much faster than globbing all PHP)
+  const rawSearch = await rustSearchAsync(`${shortName} ${className}`, 50).catch(() => []);
+  const raw = Array.isArray(rawSearch) ? rawSearch : [];
+  const relatedPaths = raw.map(r => normalizeResult(r)).filter(r => r.path);
+
+  // Check DI references via xml parsing
+  const diTrace = await traceDependency(className, 'both');
+  references.diXmlReferences = [
+    ...diTrace.preferences.map(p => ({ type: 'preference', file: p.file, detail: `${p.for} → ${p.type}` })),
+    ...diTrace.plugins.map(p => ({ type: 'plugin', file: p.file, detail: `${p.pluginName}: ${p.pluginClass}` })),
+    ...diTrace.virtualTypes.map(v => ({ type: 'virtualType', file: v.file, detail: `${v.name} extends ${v.type}` })),
+    ...diTrace.argumentOverrides.map(a => ({ type: 'argument', file: a.file, detail: `${a.target}.${a.argumentName}` }))
+  ];
+
+  // Check PHP files for direct references
+  for (const r of relatedPaths.slice(0, 40)) {
+    const absPath = path.join(root, r.path);
+    if (!existsSync(absPath) || !r.path.endsWith('.php')) continue;
+    let content;
+    try { content = readFileSync(absPath, 'utf-8'); } catch { continue; }
+
+    const hasUse = content.includes(`use ${className}`) || content.includes(`\\${className}`);
+    if (hasUse) {
+      references.useStatements.push({ file: r.path, className: r.className });
+    }
+    if (content.includes(`new ${shortName}(`) || content.includes(`new \\${className}(`)) {
+      references.instantiations.push({ file: r.path, className: r.className });
+    }
+    if (content.includes(`@var ${shortName}`) || content.includes(`@param ${shortName}`) ||
+        content.match(new RegExp(`:\\s*${shortName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`))) {
+      references.typeHints.push({ file: r.path, className: r.className });
+    }
+  }
+
+  references.total = references.useStatements.length + references.diXmlReferences.length +
+                     references.instantiations.length + references.typeHints.length;
+
+  return references;
+}
+
+// ─── Event Flow Tracing ─────────────────────────────────────────
+
+async function traceEventFlow(eventName) {
+  const root = config.magentoRoot;
+
+  const result = {
+    eventName,
+    dispatchers: [],
+    observers: [],
+    observerDetails: []
+  };
+
+  // 1. Parse all events.xml for observer declarations
+  const eventsFiles = await glob('**/etc/**/events.xml', { cwd: root, absolute: true, nodir: true });
+  const escapedEvent = eventName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  for (const file of eventsFiles) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    const relativePath = file.replace(root + '/', '');
+
+    const eventBlockRegex = new RegExp(`<event\\s+name="${escapedEvent}"[^>]*>([\\s\\S]*?)<\\/event>`, 'g');
+    let eventMatch;
+    while ((eventMatch = eventBlockRegex.exec(content)) !== null) {
+      const block = eventMatch[1];
+      const obsRegex = /<observer\s+[^>]*name="([^"]+)"[^>]*instance="([^"]+)"[^>]*(?:method="([^"]+)")?[^>]*\/?>/g;
+      let obsMatch;
+      while ((obsMatch = obsRegex.exec(block)) !== null) {
+        result.observers.push({
+          name: obsMatch[1],
+          instance: obsMatch[2],
+          method: obsMatch[3] || 'execute',
+          file: relativePath
+        });
+      }
+    }
+  }
+
+  // 2. Find dispatch() calls via vector search
+  try {
+    const dispatchSearch = await rustSearchAsync(`dispatch ${eventName} eventManager`, 20);
+    const dispatchRaw = Array.isArray(dispatchSearch) ? dispatchSearch : [];
+    const dispatchers = dispatchRaw.map(normalizeResult).filter(r =>
+      r.searchText?.includes(eventName) || r.path?.endsWith('.php')
+    );
+    result.dispatchers = dispatchers.slice(0, 10).map(r => ({
+      path: r.path,
+      className: r.className,
+      snippet: (r.searchText || '').slice(0, 200)
+    }));
+  } catch { /* index may not be ready */ }
+
+  // 3. Resolve observer PHP classes
+  for (const obs of result.observers.slice(0, 10)) {
+    const shortName = obs.instance.split('\\').pop();
+    try {
+      const obsSearch = await rustSearchAsync(shortName, 5);
+      const obsRaw = Array.isArray(obsSearch) ? obsSearch : [];
+      const matches = obsRaw.map(normalizeResult).filter(r =>
+        r.className?.includes(shortName)
+      );
+      if (matches[0]) {
+        result.observerDetails.push({
+          name: obs.name,
+          instance: obs.instance,
+          path: matches[0].path,
+          methods: matches[0].methods || []
+        });
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return result;
+}
+
+// ─── Test Finder ────────────────────────────────────────────────
+
+async function findTests(className, methodName) {
+  const root = config.magentoRoot;
+  const shortName = className.split('\\').pop();
+
+  const result = {
+    className,
+    tests: []
+  };
+
+  // Find test files by name pattern
+  const testPatterns = [
+    `**/*${shortName}Test.php`,
+    `**/*${shortName}*Test.php`,
+    `**/Test/**/*${shortName}*.php`,
+  ];
+
+  const testFiles = new Set();
+  for (const pattern of testPatterns) {
+    try {
+      const found = await glob(pattern, { cwd: root, absolute: true, nodir: true });
+      for (const f of found) testFiles.add(f);
+    } catch { /* glob failure non-fatal */ }
+  }
+
+  // Also search via vector search
+  try {
+    const query = methodName
+      ? `test ${shortName} ${methodName} PHPUnit`
+      : `test ${shortName} PHPUnit`;
+    const rawSearch = await rustSearchAsync(query, 20);
+    const rawArr = Array.isArray(rawSearch) ? rawSearch : [];
+    for (const r of rawArr.map(normalizeResult)) {
+      if (r.path?.toLowerCase().includes('test')) {
+        testFiles.add(path.join(root, r.path));
+      }
+    }
+  } catch { /* index may not be ready */ }
+
+  // Read each test file and extract info
+  for (const file of [...testFiles].slice(0, 20)) {
+    let content;
+    try { content = readFileSync(file, 'utf-8'); } catch { continue; }
+    const relativePath = file.replace(root + '/', '');
+
+    if (!content.includes(shortName)) continue;
+
+    const testMethods = [];
+    const methodRegex = /(?:public\s+)?function\s+(test\w+)\s*\(/g;
+    let m;
+    while ((m = methodRegex.exec(content)) !== null) testMethods.push(m[1]);
+
+    const coversAnnotation = content.includes('@covers') && content.includes(shortName);
+    const hasMock = content.includes('getMock') || content.includes('createMock') ||
+                    content.includes('MockObject');
+
+    result.tests.push({
+      path: relativePath,
+      testMethods,
+      coversAnnotation,
+      hasMock,
+      referencesClass: content.includes(shortName)
+    });
+  }
+
+  return result;
+}
+
 // ─── MCP Server ─────────────────────────────────────────────────
 
 const server = new Server(
   {
     name: 'magector',
-    version: '1.0.0'
+    version: '2.1.0'
   },
   {
     capabilities: {
@@ -1025,6 +1769,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'Maximum results to return (default: 10, max: 100)',
             default: 10
           },
+          moduleFilter: {
+            type: 'string',
+            description: 'Filter results by vendor/module pattern. Supports wildcards. Examples: "Vendor_*" to show only custom modules, "Magento_Catalog" for specific module. Omit to search all modules.'
+          },
+          expand: {
+            type: 'boolean',
+            description: 'Enable query expansion with Magento domain synonyms for better recall (default: true)',
+            default: true
+          },
         },
         required: ['query']
       }
@@ -1362,6 +2115,122 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['entryPoint']
       }
     },
+    {
+      name: 'magento_trace_dependency',
+      description: 'Trace dependency injection graph for a PHP class or interface. Parses di.xml files across all modules to find: preferences (interface→implementation), plugins (interceptors), virtualTypes, and constructor argument overrides. Use this to understand how Magento resolves a class at runtime — especially useful for "Cannot instantiate interface" errors.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          className: {
+            type: 'string',
+            description: 'Full or partial PHP class/interface name to trace. Examples: "ProductRepositoryInterface", "CartManagementInterface", "LoggerInterface", "StoreManagerInterface"'
+          },
+          direction: {
+            type: 'string',
+            enum: ['resolve', 'dependents', 'both'],
+            description: '"resolve" finds what implements/replaces this class (preferences, virtualTypes). "dependents" finds what depends on this class (plugins, type arguments). "both" does both. Default: both.',
+            default: 'both'
+          }
+        },
+        required: ['className']
+      }
+    },
+    {
+      name: 'magento_error_parser',
+      description: 'Parse a Magento error message or stack trace and map it to relevant source files and root causes. Understands common Magento error patterns: DI instantiation failures, missing class/interface, plugin sort conflicts, area code not set, undefined index in templates, and more. Provides actionable file paths and fix suggestions.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          error: {
+            type: 'string',
+            description: 'Full error message, exception message, or stack trace from Magento. Can include PHP fatal errors, uncaught exceptions, or log entries.'
+          }
+        },
+        required: ['error']
+      }
+    },
+    {
+      name: 'magento_performance_profile',
+      description: 'Profile a Magento subsystem for performance bottlenecks. Scans for all plugins, observers, and collectors registered on a critical path (e.g., checkout totals, order placement, product save). Returns files sorted by complexity score to identify likely performance hotspots.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          subsystem: {
+            type: 'string',
+            description: 'Magento subsystem to profile. Examples: "checkout_totals", "order_place", "product_save", "cart_add", "customer_login", "catalog_reindex"'
+          },
+          threshold: {
+            type: 'number',
+            description: 'Minimum complexity score to include in results (default: 0). Set higher (e.g., 5) to focus on complex files only.',
+            default: 0
+          }
+        },
+        required: ['subsystem']
+      }
+    },
+    {
+      name: 'magento_find_layout',
+      description: 'Find layout XML files — handles, blocks, containers, and referenceBlock/referenceContainer declarations. Parses view/*/layout/*.xml files across all modules. Use to understand page structure and block assignments.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Search term to find in layout XML content. Examples: "product.info", "checkout.cart", "minicart", "breadcrumbs", "page.main.title"'
+          },
+          handle: {
+            type: 'string',
+            description: 'Layout handle name (file name without .xml). Examples: "catalog_product_view", "checkout_index_index", "default", "customer_account"'
+          }
+        }
+      }
+    },
+    {
+      name: 'magento_impact_analysis',
+      description: 'Analyze the impact of changing a PHP class — finds all files that reference it via use statements, DI configuration, instantiation, and type hints. Combines DI XML tracing with PHP source analysis to map cross-module dependencies.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          className: {
+            type: 'string',
+            description: 'Full or partial PHP class/interface name. Examples: "ProductRepository", "CartManagementInterface", "StoreManagerInterface"'
+          }
+        },
+        required: ['className']
+      }
+    },
+    {
+      name: 'magento_find_event_flow',
+      description: 'Trace complete event flow chain: find where an event is dispatched, list all observers registered in events.xml, and resolve observer PHP classes. Shows the full dispatch → observer → handler chain for any Magento event.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          eventName: {
+            type: 'string',
+            description: 'Magento event name. Examples: "sales_order_place_after", "checkout_cart_add_product_complete", "catalog_product_save_after", "customer_login", "controller_action_predispatch"'
+          }
+        },
+        required: ['eventName']
+      }
+    },
+    {
+      name: 'magento_find_test',
+      description: 'Find PHPUnit test files for a given PHP class or method. Searches Test/ directories for test classes, @covers annotations, mock references, and class name matches. Helps identify test coverage for refactoring.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          className: {
+            type: 'string',
+            description: 'PHP class name to find tests for. Examples: "ProductRepository", "CartManagement", "OrderService"'
+          },
+          methodName: {
+            type: 'string',
+            description: 'Optional method name to narrow test search. Examples: "save", "getById", "execute"'
+          }
+        },
+        required: ['className']
+      }
+    },
   ]
 }));
 
@@ -1370,13 +2239,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const reqStart = Date.now();
   logToFile('REQ', `${name}(${JSON.stringify(args || {})})`);
 
-  // Block search tools while re-indexing is in progress
-  if (reindexInProgress && name !== 'magento_stats' && name !== 'magento_analyze_diff' && name !== 'magento_complexity') {
-    logToFile('REQ', `${name} → blocked (re-indexing in progress)`);
+  // Block search tools only when re-indexing AND no usable old DB exists.
+  // If old DB is preserved, searches keep running against it during rebuild.
+  const indexFreeTools = ['magento_stats', 'magento_analyze_diff', 'magento_complexity',
+    'magento_trace_dependency', 'magento_error_parser', 'magento_find_layout',
+    'magento_impact_analysis', 'magento_find_event_flow', 'magento_find_test'];
+  const hasUsableDb = existsSync(config.dbPath) && (() => { try { return statSync(config.dbPath).size > 100; } catch { return false; } })();
+  if (reindexInProgress && !hasUsableDb && !indexFreeTools.includes(name)) {
+    logToFile('REQ', `${name} → blocked (re-indexing, no usable DB)`);
     return {
       content: [{
         type: 'text',
-        text: 'Re-indexing in progress. The database format was incompatible and is being rebuilt automatically. Check .magector/magector.log for progress. Search tools will be available once re-indexing completes.'
+        text: 'Re-indexing in progress and no previous index available. Check .magector/magector.log for progress. Search tools will be available once re-indexing completes.'
       }],
       isError: true,
     };
@@ -1390,15 +2264,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (name) {
       case 'magento_search': {
-        const raw = await rustSearchAsync(args.query, args.limit || 10);
+        const searchQuery = args.expand !== false ? expandQuery(args.query) : args.query;
+        const raw = await rustSearchAsync(searchQuery, Math.max(args.limit || 10, 30));
         const arr = Array.isArray(raw) ? raw : [];
-        const results = arr.map(normalizeResult);
+        let results = arr.map(normalizeResult);
+        // Hybrid BM25 rerank for better exact-match handling
+        results = hybridRerank(results, args.query);
+        // Apply module filter if specified
+        if (args.moduleFilter) {
+          results = filterByModule(results, args.moduleFilter);
+        }
         // SONA: record search with results for follow-up tracking
         sessionTracker.recordToolCall(name, args || {}, arr);
         return {
           content: [{
             type: 'text',
-            text: formatSearchResults(results)
+            text: formatSearchResults(results.slice(0, args.limit || 10))
           }]
         };
       }
@@ -1926,7 +2807,262 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case 'magento_trace_dependency': {
+        const diResult = await traceDependency(args.className, args.direction || 'both');
 
+        let text = `## DI Dependency Trace: ${args.className}\n\n`;
+        text += `Scanned ${diResult.totalDiFiles} di.xml files.\n\n`;
+
+        if (diResult.preferences.length > 0) {
+          text += `### Preferences (${diResult.preferences.length})\n`;
+          for (const p of diResult.preferences) {
+            text += `- \`${p.for}\` → \`${p.type}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.plugins.length > 0) {
+          text += `### Plugins (${diResult.plugins.length})\n`;
+          for (const p of diResult.plugins) {
+            text += `- \`${p.pluginName}\`: \`${p.pluginClass}\` on \`${p.target}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.virtualTypes.length > 0) {
+          text += `### Virtual Types (${diResult.virtualTypes.length})\n`;
+          for (const v of diResult.virtualTypes) {
+            text += `- \`${v.name}\` extends \`${v.type}\` (${v.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.argumentOverrides.length > 0) {
+          text += `### Argument Overrides (${diResult.argumentOverrides.length})\n`;
+          for (const a of diResult.argumentOverrides) {
+            text += `- \`${a.target}\`.${a.argumentName} (${a.argumentType}) = ${a.value} (${a.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (diResult.preferences.length === 0 && diResult.plugins.length === 0 &&
+            diResult.virtualTypes.length === 0 && diResult.argumentOverrides.length === 0) {
+          text += '_No DI configuration found for this class. It may use default Magento auto-resolution or be configured under a different name._\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_error_parser': {
+        const errorResult = await parseError(args.error);
+
+        let text = `## Error Analysis\n\n`;
+        text += `**Type:** ${errorResult.errorType}\n`;
+        if (errorResult.suggestion) {
+          text += `**Suggestion:** ${errorResult.suggestion}\n`;
+        }
+        text += '\n';
+
+        if (Object.keys(errorResult.parsed).length > 0) {
+          text += `### Parsed Details\n`;
+          for (const [key, value] of Object.entries(errorResult.parsed)) {
+            text += `- **${key}:** \`${value}\`\n`;
+          }
+          text += '\n';
+        }
+
+        if (errorResult.existingPreferences?.length > 0) {
+          text += `### Existing Preferences\n`;
+          for (const p of errorResult.existingPreferences) {
+            text += `- \`${p.for}\` → \`${p.type}\` (${p.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (errorResult.relatedFiles.length > 0) {
+          text += `### Related Files\n`;
+          for (const f of errorResult.relatedFiles) {
+            text += `- \`${f.path}\`${f.className ? ` (${f.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (errorResult.stackTrace.length > 0) {
+          text += `### Stack Trace Files\n`;
+          for (const s of errorResult.stackTrace) {
+            text += `- ${s.file}${s.line ? `:${s.line}` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_performance_profile': {
+        const profileResult = await profilePerformance(args.subsystem, args.threshold || 0);
+
+        let text = `## Performance Profile: ${profileResult.subsystem}\n\n`;
+        text += `Found ${profileResult.totalFiles || profileResult.files?.length || 0} related files.\n\n`;
+
+        const knownSubsystems = Object.keys(SUBSYSTEM_QUERIES);
+        if (!SUBSYSTEM_QUERIES[args.subsystem]) {
+          text += `_Custom subsystem — used generic search. Known subsystems: ${knownSubsystems.join(', ')}_\n\n`;
+        }
+
+        if (profileResult.plugins?.length > 0) {
+          text += `### Plugins (${profileResult.plugins.length})\n`;
+          for (const p of profileResult.plugins) {
+            text += `- \`${p.path}\`${p.className ? ` (${p.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (profileResult.observers?.length > 0) {
+          text += `### Observers (${profileResult.observers.length})\n`;
+          for (const o of profileResult.observers) {
+            text += `- \`${o.path}\`${o.className ? ` (${o.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (profileResult.files?.length > 0) {
+          text += `### Files by Complexity\n`;
+          text += '| File | Complexity | Rating | Functions | Lines |\n';
+          text += '|------|-----------|--------|-----------|-------|\n';
+          for (const f of profileResult.files.filter(f => f.complexity > 0).slice(0, 20)) {
+            text += `| ${f.path} | ${f.complexity} | ${f.complexityRating} | ${f.functions} | ${f.lines} |\n`;
+          }
+          text += '\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_layout': {
+        if (!args.query && !args.handle) {
+          return { content: [{ type: 'text', text: 'Provide at least one of: query or handle.' }], isError: true };
+        }
+        const layouts = await findLayout(args.query, args.handle);
+        if (layouts.length === 0) {
+          return { content: [{ type: 'text', text: 'No layout XML files found matching the query.' }] };
+        }
+        let text = `## Layout XML Results (${layouts.length} files)\n\n`;
+        for (const l of layouts.slice(0, 20)) {
+          text += `### ${l.handle} — \`${l.path}\`\n`;
+          if (l.blocks.length > 0) text += `  Blocks: ${l.blocks.slice(0, 10).map(b => '`' + b + '`').join(', ')}\n`;
+          if (l.containers.length > 0) text += `  Containers: ${l.containers.slice(0, 10).map(c => '`' + c + '`').join(', ')}\n`;
+          if (l.referenceBlocks.length > 0) text += `  Ref blocks: ${l.referenceBlocks.slice(0, 10).map(b => '`' + b + '`').join(', ')}\n`;
+          text += '\n';
+        }
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_impact_analysis': {
+        const impact = await analyzeImpact(args.className);
+
+        let text = `## Impact Analysis: ${impact.className}\n\n`;
+        text += `**Total references:** ${impact.total}\n\n`;
+
+        if (impact.useStatements.length > 0) {
+          text += `### Use Statements (${impact.useStatements.length})\n`;
+          for (const u of impact.useStatements) {
+            text += `- \`${u.file}\`${u.className ? ` (${u.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (impact.diXmlReferences.length > 0) {
+          text += `### DI XML References (${impact.diXmlReferences.length})\n`;
+          for (const d of impact.diXmlReferences) {
+            text += `- [${d.type}] ${d.detail} (\`${d.file}\`)\n`;
+          }
+          text += '\n';
+        }
+
+        if (impact.instantiations.length > 0) {
+          text += `### Direct Instantiations (${impact.instantiations.length})\n`;
+          for (const i of impact.instantiations) {
+            text += `- \`${i.file}\`${i.className ? ` (${i.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (impact.typeHints.length > 0) {
+          text += `### Type Hints / PHPDoc (${impact.typeHints.length})\n`;
+          for (const t of impact.typeHints) {
+            text += `- \`${t.file}\`${t.className ? ` (${t.className})` : ''}\n`;
+          }
+          text += '\n';
+        }
+
+        if (impact.total === 0) {
+          text += '_No references found. The class may be referenced under a different name or alias._\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_event_flow': {
+        const flow = await traceEventFlow(args.eventName);
+
+        let text = `## Event Flow: ${flow.eventName}\n\n`;
+
+        if (flow.dispatchers.length > 0) {
+          text += `### Dispatchers (${flow.dispatchers.length})\n`;
+          for (const d of flow.dispatchers) {
+            text += `- \`${d.path}\`${d.className ? ` (${d.className})` : ''}\n`;
+            if (d.snippet) text += `  _${d.snippet.slice(0, 150)}_\n`;
+          }
+          text += '\n';
+        }
+
+        if (flow.observers.length > 0) {
+          text += `### Observers (${flow.observers.length})\n`;
+          for (const o of flow.observers) {
+            text += `- **${o.name}**: \`${o.instance}::${o.method}\` (${o.file})\n`;
+          }
+          text += '\n';
+        }
+
+        if (flow.observerDetails.length > 0) {
+          text += `### Observer Class Details\n`;
+          for (const od of flow.observerDetails) {
+            text += `- **${od.name}** → \`${od.path}\``;
+            if (od.methods.length > 0) text += ` [methods: ${od.methods.join(', ')}]`;
+            text += '\n';
+          }
+          text += '\n';
+        }
+
+        if (flow.observers.length === 0 && flow.dispatchers.length === 0) {
+          text += '_No observers or dispatchers found for this event._\n';
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
+
+      case 'magento_find_test': {
+        const testResult = await findTests(args.className, args.methodName);
+
+        let text = `## Tests for: ${testResult.className}\n\n`;
+
+        if (testResult.tests.length === 0) {
+          text += '_No test files found for this class._\n';
+        } else {
+          text += `Found ${testResult.tests.length} test file(s).\n\n`;
+          for (const t of testResult.tests) {
+            text += `### \`${t.path}\`\n`;
+            if (t.coversAnnotation) text += '  Has @covers annotation\n';
+            if (t.hasMock) text += '  Uses mocking\n';
+            if (t.testMethods.length > 0) {
+              text += `  Test methods: ${t.testMethods.slice(0, 15).join(', ')}\n`;
+            }
+            text += '\n';
+          }
+        }
+
+        return { content: [{ type: 'text', text }] };
+      }
 
       default:
         return {
@@ -2006,11 +3142,12 @@ async function main() {
     startBackgroundReindex();
   }
 
-  // Try to start persistent Rust serve process for fast queries
-  if (!reindexInProgress) {
+  // Start persistent Rust serve process for fast queries.
+  // During reindex, start if old DB exists so searches keep working.
+  const canStartServe = !reindexInProgress || (existsSync(config.dbPath) && (() => { try { return statSync(config.dbPath).size > 100; } catch { return false; } })());
+  if (canStartServe) {
     try {
       startServeProcess();
-      // Wait for the serve process to load ONNX model + HNSW index (up to 15s)
       if (serveReadyPromise) {
         const ready = await Promise.race([
           serveReadyPromise,