@emtai/xray-vision 1.0.0

package/bin/xray-vision.mjs

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+/**
+ * XRay-Vision CLI — One-time setup for Claude Code
+ *
+ * Usage:
+ *   npx @emtai/xray-vision init
+ *   npx @emtai/xray-vision init --no-instructions
+ *   npx @emtai/xray-vision init --no-browser
+ *   npx @emtai/xray-vision status
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MCP_SERVER_URL = 'https://mcp.emtailabs.com/mcp';
+const AUTH_URL = 'https://mcp.emtailabs.com/authorize';
+const DASHBOARD_URL = 'https://emtai-xray.emtailabs.com/dashboard';
+
+const MCP_CONFIG = {
+  'xray-vision': {
+    type: 'http',
+    url: MCP_SERVER_URL,
+  },
+};
+
+// ============================================================================
+// ANSI Colors (no dependencies)
+// ============================================================================
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+};
+
+const ok = (msg) => console.log(`${c.green}✓${c.reset} ${msg}`);
+const info = (msg) => console.log(`${c.blue}ℹ${c.reset} ${msg}`);
+const warn = (msg) => console.log(`${c.yellow}⚠${c.reset} ${msg}`);
+const err = (msg) => console.log(`${c.red}✗${c.reset} ${msg}`);
+const step = (n, msg) => console.log(`\n${c.cyan}[${n}]${c.reset} ${c.bold}${msg}${c.reset}`);
+
+// ============================================================================
+// Paths
+// ============================================================================
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, '.claude');
+const MCP_JSON_PATH = path.join(CLAUDE_DIR, 'mcp.json');
+const INSTRUCTIONS_PATH = path.join(CLAUDE_DIR, 'instructions.md');
+
+// ============================================================================
+// XRay Instructions (embedded — preloaded into Claude's context)
+// ============================================================================
+
+const XRAY_INSTRUCTIONS = `# XRay-Vision — AI Code Intelligence
+
+You have access to XRay-Vision MCP tools for deep code analysis. Use them for ALL code-related work.
+
+## Core Rules
+
+1. **XRay-first search** — Use \`fnid_lookup\`, \`graph_query\`, \`fnid_source\` instead of Grep/Glob/Read for code searches
+2. **Before code changes** — Run \`fnid_lookup\` to understand the function, \`graph_query\` to check callers and dependencies
+3. **After code changes** — Run \`indexer_changed\` to update the index, then \`xray_full\` to verify no regressions
+4. **Before commits** — Run \`xray_security\` to catch vulnerabilities
+
+## Quick Reference
+
+### Finding Code
+| Task | XRay Tool | NOT This |
+|------|-----------|----------|
+| Find a function | \`fnid_lookup name="foo"\` | Grep for "function foo" |
+| Read function source | \`fnid_source fnid="..."\` | Read entire file |
+| Find callers | \`graph_query "MATCH (c)-[:CALLS]->(f {name:'foo'}) RETURN c"\` | Grep for "foo(" |
+| Find dependencies | \`graph_query\` with CALLS/IMPORTS patterns | Manual file reading |
+
+### Repository Setup
+\`\`\`
+github_clone url="https://github.com/owner/repo"    # Clone
+indexer_full repo="<repoId>"                          # Full index (first time)
+indexer_changed repo="<repoId>"                       # Incremental (after changes)
+\`\`\`
+
+### Analysis Tools
+- \`xray_full\` — Comprehensive health check (run after every change)
+- \`xray_security\` — Security vulnerabilities (run before every commit)
+- \`xray_complexity\` — Cyclomatic/cognitive complexity hotspots
+- \`xray_architecture\` — Circular deps, layer violations, modularity
+- \`xray_debt\` — Technical debt estimation with quick wins
+- \`xray_smells\` — God objects, long methods, anti-patterns
+- \`xray_testing\` — Test coverage, fragile tests
+- \`xray_hotspots\` — High-churn + high-complexity files
+
+### Code Navigation
+- \`fnid_lookup\` — Find function by name/file
+- \`fnid_source\` — Get function source code
+- \`graph_query\` — Custom Cypher queries (no LIMIT clause!)
+- \`file_read_range\` — Read specific lines from a file
+
+### Remediation
+- \`remediate_dead_code\` — Remove dead code (creates backups)
+- \`remediate_duplicate\` — Merge duplicate functions
+- \`refactor_extract_function\` — Extract code to new function
+- \`refactor_rename\` — Rename across codebase
+
+### Memory
+- \`remember\` — Store findings, patterns, decisions
+- \`evoke\` — Search memories by query/category
+
+## Workflow: Feature Development
+1. \`fnid_lookup\` + \`graph_query\` → understand existing code
+2. \`xray_architecture\` → verify where new code fits
+3. Implement the feature
+4. \`indexer_changed\` → update index
+5. \`xray_full\` + \`xray_security\` → verify no regressions
+6. \`remember\` → record patterns/decisions
+
+## Graph Query Rules
+- **NEVER** add \`LIMIT\` to queries — you WILL miss critical data
+- Use \`WHERE\` to filter, \`ORDER BY\` to organize
+- Always include \`tenantId\` in queries for multi-tenant isolation
+`;
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function openBrowser(url) {
+  try {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+      execSync(`open "${url}"`, { stdio: 'ignore' });
+    } else if (platform === 'win32') {
+      execSync(`start "" "${url}"`, { stdio: 'ignore' });
+    } else {
+      execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(filePath, data) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+// ============================================================================
+// Commands
+// ============================================================================
+
+function cmdInit(flags) {
+  const skipInstructions = flags.includes('--no-instructions');
+  const skipBrowser = flags.includes('--no-browser');
+
+  console.log(`\n${c.bold}${c.magenta}  XRay-Vision${c.reset} ${c.dim}— One-time setup for Claude Code${c.reset}\n`);
+
+  // ── Step 1: Ensure ~/.claude/ exists ──
+  step(1, 'Checking Claude Code directory');
+
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    ok(`Created ${c.cyan}~/.claude/${c.reset}`);
+  } else {
+    ok(`Found ${c.cyan}~/.claude/${c.reset}`);
+  }
+
+  // ── Step 2: Add MCP config ──
+  step(2, 'Configuring MCP server');
+
+  let mcpJson = readJsonFile(MCP_JSON_PATH);
+  let configChanged = false;
+
+  if (!mcpJson) {
+    mcpJson = { mcpServers: {} };
+    configChanged = true;
+    info('Creating new mcp.json');
+  }
+
+  if (!mcpJson.mcpServers) {
+    mcpJson.mcpServers = {};
+    configChanged = true;
+  }
+
+  const existing = mcpJson.mcpServers['xray-vision'];
+  if (existing) {
+    // Check if it's the old npx/stdio config or has Bearer headers
+    const isOldConfig =
+      existing.command ||
+      existing.args ||
+      existing.headers?.Authorization?.includes('Bearer xray-') ||
+      existing.url !== MCP_SERVER_URL;
+
+    if (isOldConfig) {
+      mcpJson.mcpServers['xray-vision'] = { ...MCP_CONFIG['xray-vision'] };
+      configChanged = true;
+      ok(`Updated xray-vision config ${c.dim}(replaced old config)${c.reset}`);
+    } else {
+      ok(`xray-vision already configured ${c.dim}(up to date)${c.reset}`);
+    }
+  } else {
+    mcpJson.mcpServers['xray-vision'] = { ...MCP_CONFIG['xray-vision'] };
+    configChanged = true;
+    ok('Added xray-vision MCP server');
+  }
+
+  if (configChanged) {
+    writeJsonFile(MCP_JSON_PATH, mcpJson);
+    ok(`Saved ${c.cyan}~/.claude/mcp.json${c.reset}`);
+  }
+
+  console.log(`\n  ${c.dim}Config:${c.reset}`);
+  console.log(`  ${c.cyan}${JSON.stringify(MCP_CONFIG['xray-vision'], null, 2).split('\n').join('\n  ')}${c.reset}`);
+
+  // ── Step 3: Install instructions ──
+  if (!skipInstructions) {
+    step(3, 'Installing XRay instructions');
+
+    const existingInstructions = fs.existsSync(INSTRUCTIONS_PATH)
+      ? fs.readFileSync(INSTRUCTIONS_PATH, 'utf-8')
+      : '';
+
+    if (existingInstructions.includes('XRay-Vision')) {
+      ok(`Instructions already present ${c.dim}(~/.claude/instructions.md)${c.reset}`);
+    } else {
+      // Append to existing instructions or create new
+      const content = existingInstructions
+        ? existingInstructions.trimEnd() + '\n\n' + XRAY_INSTRUCTIONS
+        : XRAY_INSTRUCTIONS;
+
+      fs.writeFileSync(INSTRUCTIONS_PATH, content, 'utf-8');
+      ok(`Installed XRay instructions → ${c.cyan}~/.claude/instructions.md${c.reset}`);
+    }
+  }
+
+  // ── Step 4: Open browser for auth ──
+  const browserStep = skipInstructions ? 3 : 4;
+
+  if (!skipBrowser) {
+    step(browserStep, 'Opening browser for authentication');
+
+    info('Claude Code will authenticate via Cloudflare Access on first connect.');
+    info('Opening browser to verify your account is set up...\n');
+
+    const opened = openBrowser(DASHBOARD_URL);
+    if (opened) {
+      ok('Browser opened — sign in to verify your account');
+    } else {
+      warn(`Could not open browser. Visit manually:\n  ${c.cyan}${DASHBOARD_URL}${c.reset}`);
+    }
+  }
+
+  // ── Done ──
+  console.log(`\n${c.green}${c.bold}  Setup complete!${c.reset}\n`);
+  console.log(`  ${c.bold}Next steps:${c.reset}`);
+  console.log(`  ${c.cyan}1.${c.reset} Restart Claude Code ${c.dim}(required for MCP config to load)${c.reset}`);
+  console.log(`  ${c.cyan}2.${c.reset} Run ${c.cyan}/mcp${c.reset} to verify xray-vision is connected`);
+  console.log(`  ${c.cyan}3.${c.reset} A browser window will open for Cloudflare auth on first connect`);
+  console.log(`  ${c.cyan}4.${c.reset} Clone a repo: ${c.cyan}github_clone url="https://github.com/you/repo"${c.reset}`);
+  console.log(`  ${c.cyan}5.${c.reset} Run full analysis: ${c.cyan}indexer_full${c.reset} then ${c.cyan}xray_full${c.reset}\n`);
+}
+
+function cmdStatus() {
+  console.log(`\n${c.bold}${c.magenta}  XRay-Vision${c.reset} ${c.dim}— Status check${c.reset}\n`);
+
+  // Check mcp.json
+  const mcpJson = readJsonFile(MCP_JSON_PATH);
+  const xrayConfig = mcpJson?.mcpServers?.['xray-vision'];
+
+  if (xrayConfig) {
+    if (xrayConfig.url === MCP_SERVER_URL && xrayConfig.type === 'http' && !xrayConfig.headers) {
+      ok(`MCP config: ${c.green}OAuth (current)${c.reset}`);
+    } else if (xrayConfig.headers?.Authorization) {
+      warn(`MCP config: ${c.yellow}API key auth (outdated)${c.reset} — run ${c.cyan}npx @emtai/xray-vision init${c.reset} to upgrade`);
+    } else if (xrayConfig.command) {
+      warn(`MCP config: ${c.yellow}npx bridge (outdated)${c.reset} — run ${c.cyan}npx @emtai/xray-vision init${c.reset} to upgrade`);
+    } else {
+      info(`MCP config: ${c.blue}unknown format${c.reset}`);
+    }
+    console.log(`  ${c.dim}URL: ${xrayConfig.url || 'not set'}${c.reset}`);
+    console.log(`  ${c.dim}Type: ${xrayConfig.type || 'not set'}${c.reset}`);
+  } else {
+    err(`MCP config: ${c.red}not found${c.reset} — run ${c.cyan}npx @emtai/xray-vision init${c.reset}`);
+  }
+
+  // Check instructions
+  if (fs.existsSync(INSTRUCTIONS_PATH)) {
+    const content = fs.readFileSync(INSTRUCTIONS_PATH, 'utf-8');
+    if (content.includes('XRay-Vision')) {
+      ok(`Instructions: ${c.green}installed${c.reset} ${c.dim}(~/.claude/instructions.md)${c.reset}`);
+    } else {
+      warn(`Instructions: ${c.yellow}file exists but no XRay content${c.reset}`);
+    }
+  } else {
+    info(`Instructions: ${c.blue}not installed${c.reset} ${c.dim}(optional)${c.reset}`);
+  }
+
+  console.log('');
+}
+
+function cmdHelp() {
+  console.log(`
+${c.bold}${c.magenta}  XRay-Vision CLI${c.reset} — Setup tool for Claude Code
+
+${c.bold}  Usage:${c.reset}
+    npx @emtai/xray-vision ${c.cyan}init${c.reset}                Set up XRay-Vision in Claude Code
+    npx @emtai/xray-vision ${c.cyan}status${c.reset}              Check current configuration
+    npx @emtai/xray-vision ${c.cyan}help${c.reset}                Show this help
+
+${c.bold}  Init Flags:${c.reset}
+    ${c.dim}--no-instructions${c.reset}    Skip installing XRay instructions
+    ${c.dim}--no-browser${c.reset}         Skip opening browser for authentication
+
+${c.bold}  What init does:${c.reset}
+    1. Adds xray-vision to ${c.cyan}~/.claude/mcp.json${c.reset}
+    2. Installs XRay workflow instructions to ${c.cyan}~/.claude/instructions.md${c.reset}
+    3. Opens browser for Cloudflare authentication
+
+${c.bold}  Learn more:${c.reset}
+    Dashboard:  ${c.cyan}https://emtai-xray.emtailabs.com/dashboard${c.reset}
+    Pricing:    ${c.cyan}https://emtai-xray.emtailabs.com/pricing${c.reset}
+`);
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+const flags = args.slice(1);
+
+switch (command) {
+  case 'init':
+  case 'setup':
+  case 'install':
+    cmdInit(flags);
+    break;
+  case 'status':
+  case 'check':
+    cmdStatus();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    cmdHelp();
+    break;
+  default:
+    // If no recognized command, default to init (for `npx @emtai/xray-vision` with no args)
+    if (command.startsWith('-')) {
+      cmdInit([command, ...flags]);
+    } else {
+      err(`Unknown command: ${command}`);
+      cmdHelp();
+      process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@emtai/xray-vision",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "One-time setup for XRay-Vision MCP in Claude Code — adds config, instructions, and authenticates",
+  "bin": {
+    "xray-vision": "./bin/xray-vision.mjs"
+  },
+  "files": [
+    "bin/**/*"
+  ],
+  "keywords": [
+    "xray-vision",
+    "mcp",
+    "claude-code",
+    "code-analysis",
+    "model-context-protocol",
+    "setup"
+  ],
+  "author": "eMTAi Labs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}