magector 1.5.0 → 1.5.2

package/README.md

@@ -66,23 +66,27 @@ The result: your AI assistant calls one MCP tool and gets ranked, pattern-enrich
 ## Architecture
 
 ```mermaid
-flowchart TD
-  subgraph rust ["Rust Core"]
-    A["AST Parser · PHP + JS"]
-    B["Pattern Detection · 20+"]
-    B2["Description Enrichment"]
-    C["ONNX Embedder · 384d"]
-    D["HNSW + Reranking"]
-    A --> B --> B2 --> C --> D
-  end
+flowchart LR
   subgraph node ["Node.js Layer"]
-    E["MCP Server · 21 tools"]
-    F["Persistent Serve"]
-    G["CLI · init/index/search/describe"]
-    E --> F
+    direction TB
+    G["CLI<br/>init · index · search · describe"]
+    E["MCP Server<br/>21 tools · LRU cache"]
+    F["Persistent Serve Process"]
     G --> F
+    E --> F
+  end
+
+  F -->|"stdin/stdout JSON"| rust
+
+  subgraph rust ["Rust Core"]
+    direction TB
+    A["AST Parser<br/>PHP · JS · XML"]
+    B["Pattern Detection<br/>20+ Magento patterns"]
+    B2["Description Enrichment<br/>LLM-powered di.xml summaries"]
+    C["ONNX Embedder<br/>all-MiniLM-L6-v2 · 384d"]
+    D["HNSW Vector Search<br/>hybrid reranking · SONA"]
+    A --> B --> B2 --> C --> D
   end
-  node -->|stdin/stdout JSON| rust
 
   style rust fill:#f4a460,color:#000
   style node fill:#68b684,color:#000
@@ -91,29 +95,28 @@ flowchart TD
 ### Indexing Pipeline
 
 ```mermaid
-flowchart TD
-  A[Source File] --> B[AST Parser]
-  B --> C[Pattern Detection]
-  C --> D[Text Enrichment]
-  D --> D2{Description DB?}
-  D2 -->|Yes| D3["Prepend Description"]
-  D2 -->|No| E[ONNX Embedding]
+flowchart LR
+  A["Source File"] --> B["AST Parser"]
+  B --> C["Pattern Detection"]
+  C --> D["Text Enrichment"]
+  D --> D2{"Descriptions DB?"}
+  D2 -->|Yes| D3["Prepend LLM Description"]
+  D2 -->|No| E["ONNX Embedding"]
   D3 --> E
-  E --> F[(HNSW Index)]
-  A --> G[Metadata]
-  G --> F
+  E --> F[("HNSW Index")]
+  A --> G["Metadata"] --> F
 ```
 
 ### Search Pipeline
 
 ```mermaid
-flowchart TD
-  Q[Query] --> E1[Synonym Enrichment]
-  E1 --> E2[ONNX Embedding]
-  E2 --> H[HNSW Search]
-  H --> R[Hybrid Reranking]
-  R --> SA[SONA Adjustment + MicroLoRA]
-  SA --> J[Structured JSON]
+flowchart LR
+  Q["Query"] --> E1["Synonym Enrichment"]
+  E1 --> E2["ONNX Embedding"]
+  E2 --> H["HNSW Search"]
+  H --> R["Hybrid Reranking"]
+  R --> SA["SONA Adjustment"]
+  SA --> J["Structured JSON"]
 ```
 
 ### Components
@@ -148,13 +151,14 @@ npx magector init
 This single command handles the entire setup:
 
 ```mermaid
-flowchart TD
-  A["npx magector init"] --> B[Verify Project]
-  B --> C[Download Model]
-  C --> D[Index Codebase]
-  D --> E[Detect IDE]
-  E --> F[Write Config]
-  F --> G[Update .gitignore]
+flowchart LR
+  A["npx magector init"] --> B["Verify<br/>Project"]
+  B --> C["Download<br/>ONNX Model"]
+  C --> D["Index<br/>Codebase"]
+  D --> E["Detect IDE<br/>Cursor · Claude Code"]
+  E --> E2["API Key<br/>(optional)"]
+  E2 --> F["Write MCP<br/>Config"]
+  F --> G["Update<br/>.gitignore"]
 ```
 
 ### 2. Search
@@ -304,7 +308,7 @@ npx magector mcp                # Start MCP server
 npx magector help               # Show help
 ```
 
-The `describe` command requires `ANTHROPIC_API_KEY`. After running `describe`, the next `index` automatically picks up the descriptions DB and embeds them into the vectors.
+The `describe` command and `magento_describe` MCP tool require an Anthropic API key. During `npx magector init`, you are prompted to paste your key (optional). If provided, it is stored in the MCP config file as the `ANTHROPIC_API_KEY` environment variable so the MCP server can use it automatically. You can also set it manually later by adding `"ANTHROPIC_API_KEY": "sk-..."` to the `env` section in `.mcp.json` or `~/.cursor/mcp.json`.
 
 ### Environment Variables
 
@@ -405,7 +409,7 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 Each tool description includes "See also" hints to help AI clients chain tools effectively:
 
 ```mermaid
-graph TD
+graph LR
   cls["find_class"] --> plg["find_plugin"]
   cls --> prf["find_preference"]
   cls --> mtd["find_method"]
@@ -635,20 +639,16 @@ Magector scans every `.php`, `.js`, `.xml`, `.phtml`, and `.graphqls` file in a
 The MCP server spawns a persistent Rust process (`magector-core serve`) that keeps the ONNX model and HNSW index loaded in memory. Queries are sent as JSON over stdin and responses returned via stdout -- eliminating the ~2.6s cold-start overhead of loading the model per query. Falls back to single-shot `execFileSync` if the serve process is unavailable.
 
 ```mermaid
-flowchart TD
+flowchart LR
   subgraph startup ["Startup (once)"]
-    S1[Load Model] --> S2[Load Index]
-    S2 --> S3[Ready Signal]
+    S1["Load Model"] --> S2["Load Index"] --> S3["Ready Signal"]
   end
+  startup --> query
   subgraph query ["Per Query (10-45ms)"]
-    Q1[stdin JSON] --> Q2[Embed]
-    Q2 --> Q3[HNSW Search]
-    Q3 --> Q4[Rerank]
-    Q4 --> Q5[stdout JSON]
+    Q1["stdin JSON"] --> Q2["Embed"] --> Q3["HNSW Search"] --> Q4["Rerank"] --> Q5["stdout JSON"]
   end
-  startup --> query
   subgraph fallback ["Fallback"]
-    F1[execFileSync ~2.6s]
+    F1["execFileSync ~2.6s"]
   end
 
   style startup fill:#e8f4e8,color:#000
@@ -663,17 +663,12 @@ When the serve process is started with `--magento-root`, a background thread pol
 Since `hnsw_rs` does not support point deletion, Magector uses a **tombstone** strategy: old vectors for modified/deleted files are marked as tombstoned and filtered out of search results. New vectors are appended. When tombstoned entries exceed 20% of total vectors, the HNSW graph is automatically rebuilt (compacted) to reclaim memory and restore search performance.
 
 ```mermaid
-flowchart TD
-  W1[Sleep 60s] --> W2[Scan Filesystem]
-  W2 --> W3{Changes?}
+flowchart LR
+  W1["Sleep 60s"] --> W2["Scan Filesystem"] --> W3{"Changes?"}
   W3 -->|No| W1
-  W3 -->|Yes| W4[Tombstone Old Vectors]
-  W4 --> W5[Parse + Embed New Files]
-  W5 --> W6[Append to HNSW]
-  W6 --> W7{Tombstone > 20%?}
-  W7 -->|Yes| W8[Compact / Rebuild HNSW]
-  W7 -->|No| W9[Save to Disk]
-  W8 --> W9
+  W3 -->|Yes| W4["Tombstone Old Vectors"] --> W5["Parse + Embed New Files"] --> W6["Append to HNSW"] --> W7{"Tombstone > 20%?"}
+  W7 -->|Yes| W8["Compact / Rebuild HNSW"] --> W9["Save to Disk"]
+  W7 -->|No| W9
   W9 --> W1
 
   style W4 fill:#f4e8e8,color:#000

package/package.json

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

package/src/cli.js

@@ -11,6 +11,7 @@ import path from 'path';
 import { resolveBinary } from './binary.js';
 import { ensureModels, resolveModels } from './model.js';
 import { init, setup } from './init.js';
+import { checkForUpdate } from './update.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -192,6 +193,9 @@ async function runDescribe(targetPath) {
 }
 
 async function main() {
+  // Auto-update: check npm for newer version, re-exec if found
+  await checkForUpdate(command, args);
+
   switch (command) {
     case 'init':
       await init(args[1]);

package/src/init.js

@@ -3,13 +3,29 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
 import { execFileSync } from 'child_process';
+import { createInterface } from 'readline';
 import { homedir } from 'os';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { resolveBinary } from './binary.js';
 import { ensureModels } from './model.js';
 import { CURSOR_RULES_MDC } from './templates/cursor-rules-mdc.js';
 import { CLAUDE_MD } from './templates/claude-md.js';
 
+/**
+ * Prompt the user for input. Returns empty string if stdin is not a TTY.
+ */
+function askQuestion(question) {
+  if (!process.stdin.isTTY) return Promise.resolve('');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 /**
  * Detect if the given path is a Magento 2 project root.
  */
@@ -51,14 +67,18 @@ function detectIDEs(projectPath) {
 /**
  * Write MCP server configuration for the given IDE(s).
  */
-function writeMcpConfig(projectPath, ides, dbPath) {
+function writeMcpConfig(projectPath, ides, dbPath, { anthropicApiKey } = {}) {
+  const env = {
+    MAGENTO_ROOT: projectPath,
+    MAGECTOR_DB: dbPath
+  };
+  if (anthropicApiKey) {
+    env.ANTHROPIC_API_KEY = anthropicApiKey;
+  }
   const mcpEntry = {
     command: 'npx',
     args: ['-y', 'magector@latest', 'mcp'],
-    env: {
-      MAGENTO_ROOT: projectPath,
-      MAGECTOR_DB: dbPath
-    }
+    env
   };
 
   const written = [];
@@ -184,7 +204,9 @@ export async function init(projectPath) {
   mkdirSync(path.join(projectPath, '.magector'), { recursive: true });
   const dbPath = path.join(projectPath, '.magector', 'index.db');
 
-  console.log('\nMagector Init\n');
+  const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+  const version = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf-8')).version : 'dev';
+  console.log(`\nMagector Init v${version}\n`);
 
   // 1. Verify Magento project
   console.log('Checking Magento project...');
@@ -248,23 +270,32 @@ export async function init(projectPath) {
   if (ideNames.length === 0) ideNames.push('Cursor', 'Claude Code');
   console.log(`  Detected: ${ideNames.join(' + ') || 'none (configuring both)'}`);
 
-  // 6. Write MCP config
+  // 6. Optional: Anthropic API key for LLM description enrichment
+  let anthropicApiKey = '';
+  anthropicApiKey = await askQuestion('\nAnthropic API key (optional, enables LLM enrichment — press Enter to skip): ');
+  if (anthropicApiKey) {
+    console.log('  API key will be stored in MCP config.');
+  } else {
+    console.log('  Skipped. You can add ANTHROPIC_API_KEY to MCP config later.');
+  }
+
+  // 7. Write MCP config
   console.log('\nWriting MCP config...');
-  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath);
+  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath, { anthropicApiKey });
   mcpFiles.forEach(f => console.log(`  ${f}`));
 
-  // 7. Write rules
+  // 8. Write rules
   console.log('\nWriting IDE rules...');
   const rulesFiles = writeRules(projectPath, ides);
   rulesFiles.forEach(f => console.log(`  ${f}`));
 
-  // 8. Update .gitignore
+  // 9. Update .gitignore
   const giUpdated = updateGitignore(projectPath);
   if (giUpdated) {
     console.log('\nUpdated .gitignore with .magector/');
   }
 
-  // 9. Get stats and print summary
+  // 10. Get stats and print summary
   let vectorCount = '?';
   try {
     const statsOutput = execFileSync(binary, ['stats', '-d', dbPath], {
@@ -303,7 +334,14 @@ export async function setup(projectPath) {
 
   console.log(`Detected: ${ideNames.join(' + ')}`);
 
-  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath);
+  let anthropicApiKey = await askQuestion('\nAnthropic API key (optional, enables LLM enrichment — press Enter to skip): ');
+  if (anthropicApiKey) {
+    console.log('  API key will be stored in MCP config.');
+  } else {
+    console.log('  Skipped. You can add ANTHROPIC_API_KEY to MCP config later.');
+  }
+
+  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath, { anthropicApiKey });
   console.log('\nMCP config:');
   mcpFiles.forEach(f => console.log(`  ${f}`));
 

package/src/mcp-server.js

@@ -55,9 +55,11 @@ async function loadDescriptions() {
         logToFile('INFO', `Loaded ${Object.keys(descriptionMap).length} LLM descriptions via serve`);
         return;
       }
-    } catch {
-      // Fall through
+    } catch (err) {
+      logToFile('WARN', `Failed to load descriptions via serve: ${err.message}`);
     }
+  } else {
+    logToFile('INFO', 'Skipping description load (serve process not ready)');
   }
 
 }
@@ -82,13 +84,22 @@ function logToFile(level, message) {
 // Initialize log file on startup
 try { writeFileSync(LOG_PATH, `[${new Date().toISOString()}] [INFO] Magector MCP server starting\n`); } catch {}
 
+// Log resolved configuration so the log file is self-contained for debugging
+logToFile('INFO', `Config: MAGENTO_ROOT=${config.magentoRoot}`);
+logToFile('INFO', `Config: MAGECTOR_DB=${config.dbPath}`);
+logToFile('INFO', `Config: watchInterval=${config.watchInterval}s`);
+try { logToFile('INFO', `Config: rustBinary=${config.rustBinary}`); } catch (e) { logToFile('ERR', `Config: rustBinary resolution failed: ${e.message}`); }
+try { logToFile('INFO', `Config: modelCache=${config.modelCache}`); } catch (e) { logToFile('ERR', `Config: modelCache resolution failed: ${e.message}`); }
+logToFile('INFO', `Config: PID=${process.pid}`);
+
 // ─── Rust Core Integration ──────────────────────────────────────
 
-// Env vars to suppress ONNX Runtime native logs that would pollute stdout/JSON-RPC
+// Env vars for Rust subprocess logging — ORT_LOG_LEVEL suppresses ONNX native noise,
+// RUST_LOG=info surfaces watcher events, indexing progress, model loading, HNSW ops.
 const rustEnv = {
   ...process.env,
   ORT_LOG_LEVEL: 'error',
-  RUST_LOG: 'error',
+  RUST_LOG: 'info',
 };
 
 /**
@@ -120,6 +131,62 @@ function extractJson(stdout) {
   throw new SyntaxError('No valid JSON found in command output');
 }
 
+// ─── PID File & Orphan Cleanup ──────────────────────────────────
+// Track the serve process PID to clean up orphans on restart.
+
+const PID_PATH = path.join(config.magentoRoot, '.magector', 'serve.pid');
+
+/**
+ * Write the serve process PID to disk so future instances can clean up orphans.
+ */
+function writePidFile(pid) {
+  try { writeFileSync(PID_PATH, String(pid)); } catch {}
+}
+
+function removePidFile() {
+  try { if (existsSync(PID_PATH)) unlinkSync(PID_PATH); } catch {}
+}
+
+/**
+ * Kill any stale serve process from a previous MCP server instance.
+ * This handles the common case where the MCP server was killed without
+ * triggering its exit handler (SIGKILL, crash, IDE disconnect).
+ */
+function killStaleServeProcess() {
+  try {
+    if (!existsSync(PID_PATH)) return;
+    const stalePid = parseInt(readFileSync(PID_PATH, 'utf-8').trim(), 10);
+    if (!stalePid || isNaN(stalePid)) return;
+
+    // Check if the process is still alive
+    try {
+      process.kill(stalePid, 0); // signal 0 = existence check
+    } catch {
+      // Process doesn't exist, clean up stale PID file
+      removePidFile();
+      return;
+    }
+
+    logToFile('WARN', `Killing stale serve process (PID ${stalePid}) from previous session`);
+    console.error(`Killing stale serve process (PID ${stalePid})`);
+    try { process.kill(stalePid, 'SIGTERM'); } catch {}
+
+    // Give it a moment, then force kill if still alive
+    setTimeout(() => {
+      try {
+        process.kill(stalePid, 0);
+        process.kill(stalePid, 'SIGKILL');
+      } catch {
+        // Already dead, good
+      }
+    }, 2000);
+
+    removePidFile();
+  } catch {
+    // Non-fatal
+  }
+}
+
 // ─── Database Format Check & Background Re-index ────────────────
 
 let reindexInProgress = false;
@@ -180,6 +247,7 @@ function startBackgroundReindex() {
   if (existsSync(bgDescDbPath)) {
     reindexArgs.push('--descriptions-db', bgDescDbPath);
   }
+  logToFile('INFO', `Starting background reindex: ${config.rustBinary} ${reindexArgs.join(' ')}`);
   reindexProcess = spawn(config.rustBinary, reindexArgs, {
     stdio: ['pipe', 'pipe', 'pipe'],
     env: rustEnv,
@@ -326,11 +394,20 @@ function startServeProcess() {
     if (existsSync(descDbPath)) {
       args.push('--descriptions-db', descDbPath);
     }
+    logToFile('INFO', `Starting serve process: ${config.rustBinary} ${args.join(' ')}`);
     const proc = spawn(config.rustBinary, args,
       { stdio: ['pipe', 'pipe', 'pipe'], env: rustEnv });
 
-    proc.on('error', () => { serveProcess = null; serveReady = false; if (serveReadyResolve) { serveReadyResolve(false); serveReadyResolve = null; } });
-    proc.on('exit', () => { serveProcess = null; serveReady = false; if (serveReadyResolve) { serveReadyResolve(false); serveReadyResolve = null; } });
+    proc.on('error', (err) => {
+      logToFile('ERR', `Serve process error: ${err.message}`);
+      serveProcess = null; serveReady = false; removePidFile();
+      if (serveReadyResolve) { serveReadyResolve(false); serveReadyResolve = null; }
+    });
+    proc.on('exit', (code, signal) => {
+      logToFile('WARN', `Serve process exited (code=${code}, signal=${signal})`);
+      serveProcess = null; serveReady = false; removePidFile();
+      if (serveReadyResolve) { serveReadyResolve(false); serveReadyResolve = null; }
+    });
     proc.stderr.on('data', (d) => {
       // Log serve process stderr (watcher events, tracing, errors) to .magector/magector.log
       // Strip ANSI escape codes for clean log output
@@ -341,11 +418,15 @@ function startServeProcess() {
     serveReadline = createInterface({ input: proc.stdout });
     serveReadline.on('line', (line) => {
       let parsed;
-      try { parsed = JSON.parse(line); } catch { return; }
+      try { parsed = JSON.parse(line); } catch {
+        logToFile('WARN', `Unparseable serve stdout: ${line.slice(0, 200)}`);
+        return;
+      }
 
       // First line is ready signal
       if (parsed.ready) {
         serveReady = true;
+        logToFile('INFO', `Serve process ready (PID ${proc.pid})`);
         if (serveReadyResolve) { serveReadyResolve(true); serveReadyResolve = null; }
         return;
       }
@@ -359,7 +440,10 @@ function startServeProcess() {
     });
 
     serveProcess = proc;
-  } catch {
+    writePidFile(proc.pid);
+    logToFile('INFO', `Serve process spawned (PID ${proc.pid})`);
+  } catch (err) {
+    logToFile('ERR', `Failed to start serve process: ${err.message}`);
     serveProcess = null;
     serveReady = false;
     if (serveReadyResolve) { serveReadyResolve(false); serveReadyResolve = null; }
@@ -369,8 +453,10 @@ function startServeProcess() {
 function serveQuery(command, params = {}, timeoutMs = 30000) {
   return new Promise((resolve, reject) => {
     const id = serveNextId++;
+    logToFile('QUERY', `[${id}] → ${command}(${JSON.stringify(params).slice(0, 200)})`);
     const timer = setTimeout(() => {
       servePending.delete(id);
+      logToFile('ERR', `[${id}] ← ${command} TIMEOUT after ${timeoutMs}ms`);
       reject(new Error('Serve query timeout'));
     }, timeoutMs);
     servePending.set(id, {
@@ -384,11 +470,13 @@ function serveQuery(command, params = {}, timeoutMs = 30000) {
 async function rustSearchAsync(query, limit = 10) {
   const cacheKey = `${query}|${limit}`;
   if (searchCache.has(cacheKey)) {
+    logToFile('CACHE', `HIT: "${query}" (limit=${limit})`);
     return searchCache.get(cacheKey);
   }
 
   // Wait for serve process if it's starting up but not yet ready
   if (serveProcess && !serveReady && serveReadyPromise) {
+    logToFile('INFO', `Waiting for serve process to become ready...`);
     await Promise.race([serveReadyPromise, new Promise(r => setTimeout(() => r(false), 10000))]);
   }
 
@@ -400,12 +488,13 @@ async function rustSearchAsync(query, limit = 10) {
         cacheSet(cacheKey, resp.data);
         return resp.data;
       }
-    } catch {
-      // Fall through to execFileSync
+    } catch (err) {
+      logToFile('WARN', `Serve query failed, falling back to execFileSync: ${err.message}`);
     }
   }
 
   // Fallback: cold-start execFileSync
+  logToFile('INFO', `Using execFileSync fallback for search: "${query}"`);
   return rustSearchSync(query, limit);
 }
 
@@ -1837,7 +1926,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // SONA: flush accumulated feedback signals to Rust core
     const signals = sessionTracker.flush();
     if (signals.length > 0 && serveProcess && serveReady) {
-      serveQuery('feedback', { signals }).catch(() => {});
+      serveQuery('feedback', { signals }).catch((err) => logToFile('WARN', `Feedback signal send failed: ${err.message}`));
     }
   }
 });
@@ -1871,6 +1960,9 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 
 async function main() {
+  // Kill any orphaned serve process from a previous session
+  killStaleServeProcess();
+
   // Check database format compatibility before starting serve process
   if (existsSync(config.dbPath) && !checkDbFormat()) {
     startBackgroundReindex();
@@ -1908,11 +2000,28 @@ async function main() {
   console.error('Magector MCP server started (Rust core backend)');
 }
 
-// Cleanup on exit
-process.on('exit', () => {
+// Cleanup on exit — kill all child processes and remove PID file
+function cleanup(reason) {
+  logToFile('INFO', `Cleanup: ${reason || 'exit'}`);
   if (serveProcess) {
-    serveProcess.kill();
+    logToFile('INFO', `Cleanup: killing serve process (PID ${serveProcess.pid})`);
+    try { serveProcess.kill(); } catch {}
+    serveProcess = null;
   }
-});
+  if (reindexProcess) {
+    logToFile('INFO', `Cleanup: killing reindex process (PID ${reindexProcess.pid})`);
+    try { reindexProcess.kill(); } catch {}
+    reindexProcess = null;
+  }
+  removePidFile();
+}
 
-main().catch(console.error);
+process.on('exit', () => cleanup('process exit'));
+process.on('SIGTERM', () => { cleanup('SIGTERM'); process.exit(0); });
+process.on('SIGINT', () => { cleanup('SIGINT'); process.exit(0); });
+process.on('SIGHUP', () => { cleanup('SIGHUP'); process.exit(0); });
+
+main().catch((err) => {
+  logToFile('FATAL', `Startup failed: ${err.message}\n${err.stack}`);
+  console.error(err);
+});

package/src/update.js

@@ -0,0 +1,158 @@
+/**
+ * Auto-update check for Magector CLI.
+ *
+ * On each CLI run (except help/mcp), checks the npm registry for a newer version.
+ * If found, re-execs the current command via `npx magector@<latest>` so npx
+ * downloads the new version and runs it. Results are cached for 1 hour.
+ *
+ * Never blocks the CLI on failure — network errors are silently ignored.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CACHE_TTL = 3600000; // 1 hour
+const REGISTRY_TIMEOUT = 3000; // 3 seconds
+const SKIP_COMMANDS = new Set(['help', '--help', '-h', 'mcp', undefined]);
+
+/**
+ * Read current package version.
+ */
+function getCurrentVersion() {
+  const pkgPath = path.resolve(__dirname, '..', 'package.json');
+  if (!existsSync(pkgPath)) return null;
+  return JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
+}
+
+/**
+ * Resolve cache file path — prefer project .magector/ if it exists, else ~/.magector/
+ */
+function getCachePath() {
+  const projectDir = path.join(process.cwd(), '.magector');
+  if (existsSync(projectDir)) {
+    return path.join(projectDir, 'version-check.json');
+  }
+  const globalDir = path.join(homedir(), '.magector');
+  mkdirSync(globalDir, { recursive: true });
+  return path.join(globalDir, 'version-check.json');
+}
+
+/**
+ * Read cached version check result.
+ */
+function readCache(cachePath) {
+  try {
+    if (!existsSync(cachePath)) return null;
+    return JSON.parse(readFileSync(cachePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write cache.
+ */
+function writeCache(cachePath, latest) {
+  try {
+    writeFileSync(cachePath, JSON.stringify({ latest, checkedAt: Date.now() }));
+  } catch {
+    // Non-critical
+  }
+}
+
+/**
+ * Compare two semver strings. Returns true if a > b.
+ */
+function isNewer(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+/**
+ * Fetch latest version from npm registry using native fetch (Node 18+).
+ */
+async function fetchLatestVersion() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REGISTRY_TIMEOUT);
+  try {
+    const resp = await fetch('https://registry.npmjs.org/magector/latest', {
+      signal: controller.signal,
+      headers: { 'Accept': 'application/json' }
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    return data.version || null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Check for updates and self-update if a newer version is available.
+ *
+ * When a newer version is found, re-execs the CLI command via
+ * `npx -y magector@<latest> <original args>` so npx downloads
+ * the new version automatically. The current process exits after.
+ *
+ * @param {string} command - The CLI command being run
+ * @param {string[]} originalArgs - The original process.argv.slice(2)
+ */
+export async function checkForUpdate(command, originalArgs) {
+  // Skip for commands that don't need update checks
+  if (SKIP_COMMANDS.has(command)) return;
+
+  // Skip if MAGECTOR_NO_UPDATE is set (for CI, testing, or re-exec guard)
+  if (process.env.MAGECTOR_NO_UPDATE) return;
+
+  try {
+    const current = getCurrentVersion();
+    if (!current) return;
+
+    const cachePath = getCachePath();
+    const cached = readCache(cachePath);
+
+    // Cache hit — check if we already know about an update
+    if (cached && (Date.now() - cached.checkedAt) < CACHE_TTL) {
+      if (!isNewer(cached.latest, current)) return; // up to date
+      // Cached says there's an update — proceed to re-exec
+      return reExec(current, cached.latest, originalArgs);
+    }
+
+    // Fetch from registry
+    const latest = await fetchLatestVersion();
+    if (!latest) return;
+
+    writeCache(cachePath, latest);
+
+    if (!isNewer(latest, current)) return; // up to date
+
+    return reExec(current, latest, originalArgs);
+  } catch {
+    // Never block CLI on update check failure
+  }
+}
+
+/**
+ * Re-exec the current command with the latest version.
+ */
+function reExec(current, latest, originalArgs) {
+  console.log(`\n⬆  Updating magector: v${current} → v${latest}...\n`);
+  try {
+    const cmd = `npx -y magector@${latest} ${originalArgs.join(' ')}`;
+    execSync(cmd, {
+      stdio: 'inherit',
+      env: { ...process.env, MAGECTOR_NO_UPDATE: '1' }
+    });
+  } catch (err) {
+    process.exit(err.status || 1);
+  }
+  process.exit(0);
+}