magector 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "magector",
+  "version": "1.0.0",
+  "description": "Semantic code search for Magento 2 — index, search, MCP server",
+  "type": "module",
+  "main": "src/mcp-server.js",
+  "bin": {
+    "magector": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "config/"
+  ],
+  "scripts": {
+    "index": "node src/cli.js index",
+    "search": "node src/cli.js search",
+    "mcp": "node src/mcp-server.js",
+    "start": "node src/mcp-server.js",
+    "validate": "node src/cli.js validate",
+    "validate:verbose": "node src/cli.js validate --verbose",
+    "validate:keep": "node src/cli.js validate --verbose --keep",
+    "benchmark": "node src/cli.js benchmark",
+    "test": "node tests/mcp-server.test.js",
+    "test:no-index": "node tests/mcp-server.test.js --no-index"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "chalk": "^5.3.0",
+    "glob": "^10.3.10",
+    "ora": "^8.0.1",
+    "ruvector": "^0.1.96"
+  },
+  "optionalDependencies": {
+    "@magector/cli-darwin-arm64": "1.0.0",
+    "@magector/cli-linux-x64": "1.0.0",
+    "@magector/cli-linux-arm64": "1.0.0",
+    "@magector/cli-win32-x64": "1.0.0"
+  },
+  "keywords": [
+    "magento",
+    "indexer",
+    "vector-search",
+    "mcp",
+    "claude-code",
+    "semantic-search",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/krejcif/magector.git"
+  },
+  "license": "MIT"
+}

package/src/binary.js

@@ -0,0 +1,66 @@
+/**
+ * Resolve the platform-specific Rust binary (magector-core).
+ *
+ * Resolution order:
+ * 1. MAGECTOR_BIN env var
+ * 2. @magector/cli-{os}-{arch} optionalDependency
+ * 3. rust-core/target/release/magector-core (dev fallback)
+ * 4. magector-core in PATH
+ */
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const BINARY_NAME = process.platform === 'win32' ? 'magector-core.exe' : 'magector-core';
+
+export function resolveBinary() {
+  // 1. Explicit env var
+  if (process.env.MAGECTOR_BIN) {
+    if (existsSync(process.env.MAGECTOR_BIN)) {
+      return process.env.MAGECTOR_BIN;
+    }
+    throw new Error(`MAGECTOR_BIN set to ${process.env.MAGECTOR_BIN} but file not found`);
+  }
+
+  // 2. Platform-specific npm package
+  const platformPkg = `@magector/cli-${process.platform}-${process.arch}`;
+  try {
+    const pkgDir = path.dirname(require.resolve(`${platformPkg}/package.json`));
+    const binPath = path.join(pkgDir, 'bin', BINARY_NAME);
+    if (existsSync(binPath)) {
+      return binPath;
+    }
+  } catch {
+    // Package not installed — continue
+  }
+
+  // 3. Dev fallback: local Rust build
+  const devPath = path.join(__dirname, '..', 'rust-core', 'target', 'release', BINARY_NAME);
+  if (existsSync(devPath)) {
+    return devPath;
+  }
+
+  // 4. Global PATH
+  try {
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    const result = execFileSync(which, ['magector-core'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    if (result) return result.split('\n')[0];
+  } catch {
+    // Not in PATH
+  }
+
+  throw new Error(
+    `Could not find magector-core binary.\n` +
+    `Install the platform package: npm install ${platformPkg}\n` +
+    `Or build from source: cd rust-core && cargo build --release\n` +
+    `Or set MAGECTOR_BIN environment variable.`
+  );
+}

package/src/cli.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Magector CLI — npx magector <command>
+ *
+ * All search/index/stats commands delegate to the Rust binary (magector-core).
+ * The CLI resolves the binary and model paths, then shells out.
+ */
+import { execFileSync, spawn } from 'child_process';
+import path from 'path';
+import { resolveBinary } from './binary.js';
+import { ensureModels, resolveModels } from './model.js';
+import { init, setup } from './init.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function showHelp() {
+  console.log(`
+Magector — Semantic code search for Magento 2
+
+Usage:
+  npx magector init [path]       Full setup: index + IDE config
+  npx magector index [path]      Index (or re-index) Magento codebase
+  npx magector search <query>    Search indexed code
+  npx magector mcp               Start MCP server (for Claude Code / Cursor)
+  npx magector stats             Show index statistics
+  npx magector setup [path]      IDE setup only (no indexing)
+  npx magector help              Show this help
+
+Options:
+  -l, --limit <n>    Number of search results (default: 10)
+  -f, --format <fmt> Output format: text, json (default: text)
+
+Environment Variables:
+  MAGENTO_ROOT     Path to Magento installation (default: cwd)
+  MAGECTOR_DB      Path to index database (default: ./magector.db)
+  MAGECTOR_BIN     Path to magector-core binary
+  MAGECTOR_MODELS  Path to ONNX model directory
+
+Examples:
+  npx magector init /var/www/magento
+  npx magector search "product price calculation"
+  npx magector search "checkout controller" -l 20
+  npx magector index
+  npx magector mcp
+`);
+}
+
+function getConfig() {
+  return {
+    dbPath: process.env.MAGECTOR_DB || './magector.db',
+    magentoRoot: process.env.MAGENTO_ROOT || process.cwd()
+  };
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '-l' || argv[i] === '--limit') {
+      opts.limit = argv[++i];
+    } else if (argv[i] === '-f' || argv[i] === '--format') {
+      opts.format = argv[++i];
+    } else if (argv[i] === '-v' || argv[i] === '--verbose') {
+      opts.verbose = true;
+    }
+  }
+  return opts;
+}
+
+async function runIndex(targetPath) {
+  const config = getConfig();
+  const root = targetPath || config.magentoRoot;
+  const binary = resolveBinary();
+  const modelPath = await ensureModels();
+
+  console.log(`\nIndexing: ${path.resolve(root)}`);
+  console.log(`Database: ${path.resolve(config.dbPath)}\n`);
+
+  try {
+    const output = execFileSync(binary, [
+      'index',
+      '-m', path.resolve(root),
+      '-d', path.resolve(config.dbPath),
+      '-c', modelPath
+    ], { encoding: 'utf-8', timeout: 600000, stdio: ['pipe', 'pipe', 'pipe'] });
+    if (output.trim()) console.log(output.trim());
+    console.log('\nIndexing complete.');
+  } catch (err) {
+    const output = err.stderr || err.stdout || err.message;
+    console.error(`Indexing error: ${output}`);
+    process.exit(1);
+  }
+}
+
+function runSearch(query, opts = {}) {
+  const config = getConfig();
+  const binary = resolveBinary();
+  const modelPath = resolveModels();
+
+  if (!modelPath) {
+    console.error('ONNX model not found. Run `npx magector init` or `npx magector index` first.');
+    process.exit(1);
+  }
+
+  const searchArgs = [
+    'search', query,
+    '-d', path.resolve(config.dbPath),
+    '-c', modelPath,
+    '-l', String(opts.limit || 10),
+    '-f', opts.format || 'text'
+  ];
+
+  try {
+    const output = execFileSync(binary, searchArgs, {
+      encoding: 'utf-8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe']
+    });
+    console.log(output);
+  } catch (err) {
+    const output = err.stderr || err.stdout || err.message;
+    console.error(`Search error: ${output}`);
+    process.exit(1);
+  }
+}
+
+function runStats() {
+  const config = getConfig();
+  const binary = resolveBinary();
+
+  try {
+    const output = execFileSync(binary, [
+      'stats', '-d', path.resolve(config.dbPath)
+    ], { encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] });
+    console.log(output);
+  } catch (err) {
+    const output = err.stderr || err.stdout || err.message;
+    console.error(`Stats error: ${output}`);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  switch (command) {
+    case 'init':
+      await init(args[1]);
+      break;
+
+    case 'index':
+      await runIndex(args[1]);
+      break;
+
+    case 'search': {
+      const query = args.slice(1).filter(a => !a.startsWith('-')).join(' ');
+      if (!query) {
+        console.error('Usage: npx magector search <query>');
+        process.exit(1);
+      }
+      const opts = parseArgs(args.slice(1));
+      runSearch(query, opts);
+      break;
+    }
+
+    case 'mcp':
+      await import('./mcp-server.js');
+      break;
+
+    case 'stats':
+      runStats();
+      break;
+
+    case 'setup':
+      await setup(args[1]);
+      break;
+
+    case 'validate': {
+      const { runFullValidation } = await import('./validation/validator.js');
+      const verbose = args.includes('--verbose') || args.includes('-v');
+      const keepData = args.includes('--keep');
+      await runFullValidation({ verbose, keepTestData: keepData });
+      break;
+    }
+
+    case 'benchmark':
+      await import('./validation/benchmark.js');
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      showHelp();
+      break;
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/src/init.js

@@ -0,0 +1,293 @@
+/**
+ * Full init command: verify Magento project, index, detect IDE, write configs.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import path from 'path';
+import { resolveBinary } from './binary.js';
+import { ensureModels } from './model.js';
+import { CURSORRULES } from './templates/cursorrules.js';
+import { CLAUDE_MD } from './templates/claude-md.js';
+
+/**
+ * Detect if the given path is a Magento 2 project root.
+ */
+function isMagentoProject(projectPath) {
+  // Check app/etc/env.php
+  if (existsSync(path.join(projectPath, 'app', 'etc', 'env.php'))) {
+    return true;
+  }
+  // Check composer.json for magento packages
+  const composerPath = path.join(projectPath, 'composer.json');
+  if (existsSync(composerPath)) {
+    try {
+      const content = readFileSync(composerPath, 'utf-8');
+      if (content.includes('magento/') || content.includes('"magento-')) {
+        return true;
+      }
+    } catch {
+      // ignore read errors
+    }
+  }
+  return false;
+}
+
+/**
+ * Detect which IDEs are present.
+ * Returns { cursor: boolean, claude: boolean }
+ */
+function detectIDEs(projectPath) {
+  const cursor =
+    existsSync(path.join(projectPath, '.cursor')) ||
+    existsSync(path.join(projectPath, '.cursorrules'));
+  const claude =
+    existsSync(path.join(projectPath, '.claude')) ||
+    existsSync(path.join(projectPath, 'CLAUDE.md')) ||
+    existsSync(path.join(projectPath, '.mcp.json'));
+  return { cursor, claude };
+}
+
+/**
+ * Write MCP server configuration for the given IDE(s).
+ */
+function writeMcpConfig(projectPath, ides, dbPath) {
+  const mcpConfig = {
+    mcpServers: {
+      magector: {
+        command: 'npx',
+        args: ['-y', 'magector', 'mcp'],
+        env: {
+          MAGENTO_ROOT: projectPath,
+          MAGECTOR_DB: dbPath
+        }
+      }
+    }
+  };
+
+  const configJson = JSON.stringify(mcpConfig, null, 2);
+  const written = [];
+
+  if (ides.cursor) {
+    const cursorDir = path.join(projectPath, '.cursor');
+    mkdirSync(cursorDir, { recursive: true });
+    writeFileSync(path.join(cursorDir, 'mcp.json'), configJson);
+    written.push('.cursor/mcp.json');
+  }
+
+  if (ides.claude) {
+    writeFileSync(path.join(projectPath, '.mcp.json'), configJson);
+    written.push('.mcp.json');
+  }
+
+  // If neither detected, set up both
+  if (!ides.cursor && !ides.claude) {
+    writeFileSync(path.join(projectPath, '.mcp.json'), configJson);
+    written.push('.mcp.json');
+    const cursorDir = path.join(projectPath, '.cursor');
+    mkdirSync(cursorDir, { recursive: true });
+    writeFileSync(path.join(cursorDir, 'mcp.json'), configJson);
+    written.push('.cursor/mcp.json');
+  }
+
+  return written;
+}
+
+/**
+ * Write IDE rules files.
+ */
+function writeRules(projectPath, ides) {
+  const written = [];
+
+  const writeCursor = ides.cursor || (!ides.cursor && !ides.claude);
+  const writeClaude = ides.claude || (!ides.cursor && !ides.claude);
+
+  if (writeCursor) {
+    const rulesPath = path.join(projectPath, '.cursorrules');
+    if (!existsSync(rulesPath)) {
+      writeFileSync(rulesPath, CURSORRULES);
+      written.push('.cursorrules (created)');
+    } else {
+      const existing = readFileSync(rulesPath, 'utf-8');
+      if (!existing.includes('Magector')) {
+        appendFileSync(rulesPath, '\n\n' + CURSORRULES);
+        written.push('.cursorrules (appended)');
+      } else {
+        written.push('.cursorrules (already configured)');
+      }
+    }
+  }
+
+  if (writeClaude) {
+    const claudePath = path.join(projectPath, 'CLAUDE.md');
+    if (!existsSync(claudePath)) {
+      writeFileSync(claudePath, CLAUDE_MD);
+      written.push('CLAUDE.md (created)');
+    } else {
+      const existing = readFileSync(claudePath, 'utf-8');
+      if (!existing.includes('Magector')) {
+        appendFileSync(claudePath, '\n\n' + CLAUDE_MD);
+        written.push('CLAUDE.md (appended)');
+      } else {
+        written.push('CLAUDE.md (already configured)');
+      }
+    }
+  }
+
+  return written;
+}
+
+/**
+ * Add magector.db to .gitignore if not already present.
+ */
+function updateGitignore(projectPath) {
+  const giPath = path.join(projectPath, '.gitignore');
+  if (existsSync(giPath)) {
+    const content = readFileSync(giPath, 'utf-8');
+    if (!content.includes('magector.db')) {
+      appendFileSync(giPath, '\n# Magector index\nmagector.db\n');
+      return true;
+    }
+    return false;
+  }
+  writeFileSync(giPath, '# Magector index\nmagector.db\n');
+  return true;
+}
+
+/**
+ * Main init function.
+ */
+export async function init(projectPath) {
+  projectPath = path.resolve(projectPath || process.cwd());
+  const dbPath = path.join(projectPath, 'magector.db');
+
+  console.log('\nMagector Init\n');
+
+  // 1. Verify Magento project
+  console.log('Checking Magento project...');
+  if (!isMagentoProject(projectPath)) {
+    console.error(
+      `Error: ${projectPath} does not appear to be a Magento 2 project.\n` +
+      `Expected app/etc/env.php or composer.json with "magento/" dependencies.`
+    );
+    process.exit(1);
+  }
+  console.log(`  Magento project: ${projectPath}`);
+
+  // 2. Resolve binary
+  console.log('\nResolving binary...');
+  let binary;
+  try {
+    binary = resolveBinary();
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  console.log(`  Binary: ${binary}`);
+
+  // 3. Ensure ONNX model
+  console.log('\nChecking ONNX model...');
+  let modelPath;
+  try {
+    modelPath = await ensureModels();
+  } catch (err) {
+    console.error(`Error downloading model: ${err.message}`);
+    process.exit(1);
+  }
+  console.log(`  Models: ${modelPath}`);
+
+  // 4. Run indexing
+  console.log('\nIndexing codebase...');
+  const startTime = Date.now();
+  try {
+    const output = execFileSync(binary, [
+      'index',
+      '-m', projectPath,
+      '-d', dbPath,
+      '-c', modelPath
+    ], { encoding: 'utf-8', timeout: 600000, stdio: ['pipe', 'pipe', 'pipe'] });
+    if (output.trim()) {
+      console.log(output.trim().split('\n').map(l => `  ${l}`).join('\n'));
+    }
+  } catch (err) {
+    const output = err.stderr || err.stdout || err.message;
+    console.error(`Indexing error: ${output}`);
+    process.exit(1);
+  }
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  // 5. Detect IDE
+  console.log('\nDetecting IDE...');
+  const ides = detectIDEs(projectPath);
+  const ideNames = [];
+  if (ides.cursor) ideNames.push('Cursor');
+  if (ides.claude) ideNames.push('Claude Code');
+  if (ideNames.length === 0) ideNames.push('Cursor', 'Claude Code');
+  console.log(`  Detected: ${ideNames.join(' + ') || 'none (configuring both)'}`);
+
+  // 6. Write MCP config
+  console.log('\nWriting MCP config...');
+  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath);
+  mcpFiles.forEach(f => console.log(`  ${f}`));
+
+  // 7. Write rules
+  console.log('\nWriting IDE rules...');
+  const rulesFiles = writeRules(projectPath, ides);
+  rulesFiles.forEach(f => console.log(`  ${f}`));
+
+  // 8. Update .gitignore
+  const giUpdated = updateGitignore(projectPath);
+  if (giUpdated) {
+    console.log('\nUpdated .gitignore with magector.db');
+  }
+
+  // 9. Get stats and print summary
+  let vectorCount = '?';
+  try {
+    const statsOutput = execFileSync(binary, ['stats', '-d', dbPath], {
+      encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe']
+    });
+    const match = statsOutput.match(/Total vectors:\s*(\d+)/);
+    if (match) vectorCount = match[1];
+  } catch {
+    // ignore
+  }
+
+  console.log(`\n${'='.repeat(50)}`);
+  console.log(`Setup complete!`);
+  console.log(`  Indexed ${vectorCount} vectors in ${elapsed}s`);
+  console.log(`  Configured for: ${ideNames.join(' + ')}`);
+  console.log(`  Database: ${dbPath}`);
+  console.log(`\nTest it:`);
+  console.log(`  npx magector search "product price calculation"`);
+  console.log(`${'='.repeat(50)}\n`);
+}
+
+/**
+ * IDE setup only (no indexing). For projects already indexed.
+ */
+export async function setup(projectPath) {
+  projectPath = path.resolve(projectPath || process.cwd());
+  const dbPath = path.join(projectPath, 'magector.db');
+
+  console.log('\nMagector IDE Setup\n');
+
+  const ides = detectIDEs(projectPath);
+  const ideNames = [];
+  if (ides.cursor) ideNames.push('Cursor');
+  if (ides.claude) ideNames.push('Claude Code');
+  if (ideNames.length === 0) ideNames.push('Cursor', 'Claude Code');
+
+  console.log(`Detected: ${ideNames.join(' + ')}`);
+
+  const mcpFiles = writeMcpConfig(projectPath, ides, dbPath);
+  console.log('\nMCP config:');
+  mcpFiles.forEach(f => console.log(`  ${f}`));
+
+  const rulesFiles = writeRules(projectPath, ides);
+  console.log('\nIDE rules:');
+  rulesFiles.forEach(f => console.log(`  ${f}`));
+
+  updateGitignore(projectPath);
+
+  console.log(`\nDone. Configured for: ${ideNames.join(' + ')}\n`);
+}