magector 2.14.0 → 2.14.1

package/README.md

@@ -1204,6 +1204,67 @@ gantt
 
 ---
 
+## Troubleshooting
+
+All MCP server activity is logged to `.magector/magector.log` in the Magento project root. The log persists across MCP restarts and uses the format:
+
+```
+[2026-04-12T18:30:00.000Z] [LEVEL] message
+```
+
+### Log Levels
+
+| Level | Meaning |
+|-------|---------|
+| `INFO` | Normal operations: startup config, tool completion, search fallbacks, enrichment progress |
+| `WARN` | Recoverable issues: slow grep queries (>5s), missing enrichment.db, file read errors, serve process disconnects |
+| `ERR` | Failures: semgrep crashes, transaction rollbacks, serve process errors, tool execution errors |
+| `REQ` | Every tool call with full input parameters (JSON) |
+| `RES` | Tool completion with elapsed time in milliseconds |
+| `QUERY` | Rust serve process queries (search, feedback) |
+| `CACHE` | Search cache hits |
+| `INDEX` | Background reindex progress |
+| `SERVE` | Rust serve process stderr (watcher events, model loading) |
+| `FATAL` | Server startup failures |
+
+### Common Diagnostic Commands
+
+```bash
+# Recent errors
+grep '\[ERR\]\|\[FATAL\]' .magector/magector.log | tail -20
+
+# Tool timing (find slow tools)
+grep '\[RES\]' .magector/magector.log | tail -20
+
+# Enrichment/null-risk analysis
+grep 'enrich:\|null_risks:' .magector/magector.log | tail -20
+
+# AST search (semgrep) issues
+grep 'ast_search:' .magector/magector.log | tail -20
+
+# Batch query breakdown (per-tool timing)
+grep 'batch\[' .magector/magector.log | tail -20
+
+# Slow grep queries
+grep 'grep: slow\|grep: timed' .magector/magento.log | tail -20
+
+# Full startup sequence
+grep 'server starting\|Config:\|primary\|Serve process' .magector/magector.log | tail -30
+```
+
+### What Gets Logged (v2.14+)
+
+Every tool call logs `[REQ]` with input parameters and `[RES]` with elapsed time. Additionally:
+
+- **`magento_ast_search`** — semgrep pattern, target path, execution time, result count, semgrep errors
+- **`magento_enrich`** — file count, progress every 10k files, read errors, transaction failures, final summary
+- **`magento_find_null_risks`** — query parameters, result count, query timing, missing DB warnings
+- **`magento_batch`** — query list on entry, per-sub-tool timing and errors
+- **`magento_grep`** — slow query warnings (>5s), timeout detection
+- **`magento_read`** — file-not-found with error codes, failed method extractions
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "2.14.0",
+  "version": "2.14.1",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -33,10 +33,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "2.14.0",
-    "@magector/cli-linux-x64": "2.14.0",
-    "@magector/cli-linux-arm64": "2.14.0",
-    "@magector/cli-win32-x64": "2.14.0"
+    "@magector/cli-darwin-arm64": "2.14.1",
+    "@magector/cli-linux-x64": "2.14.1",
+    "@magector/cli-linux-arm64": "2.14.1",
+    "@magector/cli-win32-x64": "2.14.1"
   },
   "keywords": [
     "magento",

package/src/mcp-server.js

@@ -149,6 +149,44 @@ const SOCK_PATH = path.join(config.magentoRoot, '.magector', 'serve.sock');
 const FORMAT_CACHE_PATH = path.join(config.magentoRoot, '.magector', 'format-ok.json');
 const PRIMARY_LOCK_PATH = path.join(config.magentoRoot, '.magector', 'primary.lock');
 
+/**
+ * Expand brace patterns in include globs for GNU grep compatibility.
+ * GNU grep --include does NOT support brace expansion (that's a shell feature).
+ * Transforms "*.{php,xml,graphqls}" → ["*.php", "*.xml", "*.graphqls"]
+ * Also handles comma-separated patterns: "*.php, *.xml" → ["*.php", "*.xml"]
+ * And mixed: "*.{php,xml}, *.phtml" → ["*.php", "*.xml", "*.phtml"]
+ */
+function expandIncludePattern(include) {
+  // Split on commas NOT inside braces
+  const parts = [];
+  let depth = 0, current = '';
+  for (const ch of include) {
+    if (ch === '{') depth++;
+    if (ch === '}') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(current.trim());
+      current = '';
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) parts.push(current.trim());
+  // Expand brace patterns in each part
+  const patterns = [];
+  const braceRegex = /^(.*?)\{([^}]+)\}(.*)$/;
+  for (const part of parts) {
+    const m = part.match(braceRegex);
+    if (m) {
+      for (const alt of m[2].split(',').map(a => a.trim())) {
+        patterns.push(m[1] + alt + m[3]);
+      }
+    } else {
+      patterns.push(part);
+    }
+  }
+  return patterns;
+}
+
 /**
  * Try to acquire the primary lock (O_EXCL = atomic create-or-fail).
  * Returns true if we are the primary instance, false if another instance holds the lock.
@@ -6421,7 +6459,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const gArgs = batchFilesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
                 if (a.ignoreCase) gArgs.push('-i');
                 if (!batchFilesOnly && batchCtx > 0) gArgs.push('-C', String(batchCtx));
-                for (const pat of include.split(',').map(p => p.trim())) gArgs.push('--include=' + pat);
+                for (const pat of expandIncludePattern(include)) gArgs.push('--include=' + pat);
                 gArgs.push('--', a.pattern, searchPath);
                 let out;
                 try {
@@ -6489,8 +6527,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const grepArgs = filesOnly ? ['-rl', '-E'] : ['-rn', '-E'];
         if (args.ignoreCase) grepArgs.push('-i');
         if (!filesOnly && ctxLines > 0) grepArgs.push('-C', String(ctxLines));
-        // Support multiple include patterns (e.g., "*.{php,xml}")
-        for (const pat of include.split(',').map(p => p.trim())) {
+        for (const pat of expandIncludePattern(include)) {
           grepArgs.push('--include=' + pat);
         }
         grepArgs.push('--', args.pattern, searchPath);