crg-dev-kit 1.0.0 → 2.0.0

package/README.md

@@ -1,111 +1,72 @@
-# CRG Dev Kit
+# code-review-graph — Dev Kit
 
-One command to set up [code-review-graph](https://github.com/tirth8205/code-review-graph) across any project, any stack. Track token savings and prove ROI to your team.
+AI knowledge graph for your codebase. Gives your AI assistant (Claude Code, Cursor, etc.) structural understanding — callers, dependencies, test coverage, blast radius — without reading every file.
 
 ## Quick Start
 
-```bash
-# Open the dashboard
-npx crg-dev-kit
-
-# Copy setup scripts to your project
-npx crg-dev-kit install
-
-# Check installation status
-npx crg-dev-kit status
+### Windows (PowerShell)
+```powershell
+cd your-project
+.\setup-crg.ps1                          # basic install
+.\setup-crg.ps1 -WithCommunities         # + architecture view
+.\setup-crg.ps1 -WithAll                  # + semantic search (2GB download)
 ```
 
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `npx crg-dev-kit` | Opens the dashboard (default) |
-| `npx crg-dev-kit install` | Copies setup scripts to current directory |
-| `npx crg-dev-kit start --port 9000` | Dashboard on custom port |
-| `npx crg-dev-kit start --no-open` | Dashboard without auto-opening browser |
-| `npx crg-dev-kit status` | Check if CRG is installed in current project |
-| `npx crg-dev-kit uninstall` | Remove CRG files from current project |
-| `npx crg-dev-kit help` | Show all commands |
-
-## What You Get
-
-### Setup Scripts
-- **Linux/macOS/WSL**: `bash setup-crg.sh --with-communities`
-- **Windows**: `.\setup-crg.ps1 -WithCommunities`
-- **Health check**: `bash check-crg.sh`
-- **AI config**: `CLAUDE.md` (drop in project root)
-- **Reference**: `crg-cheatsheet.pdf`
-
-### Token Analytics Dashboard
-
-The dashboard at `http://localhost:8742` shows:
-- **Token savings %** — average reduction vs reading full source files
-- **Cost estimates** — approximate $ savings at current LLM pricing
-- **Per-project breakdown** — sessions, files reviewed, savings by project
-- **Tool usage** — which CRG tools your team uses most
-
-Data stored locally in `~/.crg-analytics/` — zero telemetry.
-
-### REST API
-
-The dashboard exposes endpoints for programmatic access:
+### Linux / macOS / WSL
+```bash
+cd your-project
+bash setup-crg.sh                         # basic install
+bash setup-crg.sh --with-communities      # + architecture view
+bash setup-crg.sh --with-all              # + semantic search (2GB download)
+```
 
+### Health Check
 ```bash
-# Get all analytics
-curl http://localhost:8742/api/analytics
-
-# Download analytics report (Markdown)
-curl http://localhost:8742/api/report
-
-# Start a new session
-curl -X POST http://localhost:8742/api/session \
-  -H 'Content-Type: application/json' \
-  -d '{"project": "/path/to/repo", "operation": "code_review"}'
-
-# Log tool usage
-curl -X POST http://localhost:8742/api/session/{sessionId} \
-  -H 'Content-Type: application/json' \
-  -d '{"tool": "detect_changes", "count": 1}'
-
-# End session
-curl -X POST http://localhost:8742/api/session/{sessionId} \
-  -H 'Content-Type: application/json' \
-  -d '{"filesReviewed": 12, "avgLinesPerFile": 150}'
+bash check-crg.sh                         # run anytime to verify
 ```
 
-## For Team Leads
+## What's in this kit
 
-Share this with your team:
+| File | Purpose |
+|------|---------|
+| `setup-crg.sh` | Setup script for Linux/macOS/WSL |
+| `setup-crg.ps1` | Setup script for Windows |
+| `check-crg.sh` | Health check (run anytime) |
+| `CLAUDE.md` | Drop into project root — tells AI which tools to use |
+| `crg-cheatsheet.pdf` | One-page visual reference |
+| `.github/workflows/test-crg.yml` | CI workflow to validate on Windows + Ubuntu |
 
-```bash
-# Everyone runs this in their project
-npx crg-dev-kit install
-bash setup-crg.sh --with-communities
-```
+## What the setup script does
 
-Then open the dashboard to see team-wide analytics:
-```bash
-npx crg-dev-kit
-```
+1. Detects OS and Python version
+2. Installs `code-review-graph` (pip on Windows, pipx on Linux)
+3. Configures MCP server for your AI tool
+4. Builds the knowledge graph
+5. Optionally installs extras (communities, embeddings)
+6. Runs community detection workaround (v2.1.0 bug)
+7. Adds `.code-review-graph/` to `.gitignore`
+8. Runs health check
 
-## Token Savings
+## What works after setup
 
-Based on benchmarks across 6 real repos, CRG tools reduce token usage by **8.2x on average**:
+**13 tools work immediately** — code review, search, impact analysis, refactoring.
 
-| Scenario | Without CRG | With CRG | Reduction |
-|----------|:---:|:---:|:---:|
-| 200-file project review | ~150k tokens | ~25k tokens | 6x |
-| Incremental review | ~150k tokens | ~8k tokens | 19x |
-| PR review | ~100k tokens | ~15k tokens | 6.7x |
+**5 tools need `--with-communities`** — architecture overview, module clusters.
 
-The dashboard tracks your actual savings in real time.
+**3 tools are broken in v2.1.0** — flow analysis (trace_flows TypeError). Skip these.
 
-## Requirements
+## Known Issues (v2.1.0)
 
-- Node.js >= 16
-- Python 3.10+ (for code-review-graph installation)
-- pipx (recommended) or pip
+| Issue | Impact | Workaround |
+|-------|--------|------------|
+| `architecture_overview` returns empty | Misleading — no error | Install communities extra |
+| `build` doesn't trigger Leiden | Communities stay 0 | Setup script handles this automatically |
+| `trace_flows` TypeError | Flows completely broken | No fix — wait for v2.2+ |
+| Over-clustering (400+ for 500 files) | Token overflow | Use `min_size=20` param |
+| `crg` is wrong package name | Installs different package | Always use `code-review-graph` |
+| PEP 668 on Linux | pip blocked | Setup script auto-detects, uses pipx |
+| MCP server caches old env | Extras don't activate | Restart AI tool after installing extras |
 
-## License
+## For CI
 
-MIT
+Copy `.github/workflows/test-crg.yml` into your repo. Tests install + build + communities on both Windows and Ubuntu. Trigger manually from Actions tab.

package/bin/cli.js

@@ -1,168 +1,35 @@
 #!/usr/bin/env node
-const { spawn, execFile } = require('child_process');
 const path = require('path');
-const fs = require('fs');
-const os = require('os');
-
 const pkg = require('../package.json');
-const ASSETS = path.join(__dirname, '..', 'assets');
+
 const args = process.argv.slice(2);
 const cmd = args[0];
-const roi = require('../lib/roi');
-
-const NO_ROI = args.includes('--no-roi');
 
 function printHelp() {
   console.log(`
-  \x1b[36mCRG Dev Kit\x1b[0m — One-click code-review-graph setup
+  \x1b[36mCRG Dev Kit\x1b[0m v${pkg.version} — AI-powered code review setup
 
   \x1b[1mUsage:\x1b[0m
-    npx crg-dev-kit [command] [options]
-
-  \x1b[1mCommands:\x1b[0m
-    install, setup    Copy setup scripts to current project
-    start, serve      Launch the dashboard (default)
-    uninstall         Remove CRG files from current project
-    status            Check if CRG is installed in current project
-    roi               Show ROI report (token savings)
-    tutorial          Launch interactive tutorial
-    help              Show this help message
-    version           Show version
+    npx crg-dev-kit [options]
 
   \x1b[1mOptions:\x1b[0m
     --port <number>   Dashboard port (default: 8742)
     --no-open         Don't auto-open browser
-    --communities     Include community detection flag
-    --no-roi          Skip ROI tracking (installs without analytics)
+    help              Show this help message
+    version           Show version
 
-  \x1b[1mExamples:\x1b[0m
-    npx crg-dev-kit                    # Open dashboard
-    npx crg-dev-kit install            # Copy scripts to project
-    npx crg-dev-kit start --port 9000  # Custom port
-    npx crg-dev-kit status             # Check installation
+  \x1b[1mHow it works:\x1b[0m
+    Run \x1b[36mnpx crg-dev-kit\x1b[0m to open the dashboard.
+    Everything happens in the browser — install, status,
+    analytics, downloads, and documentation.
 `);
 }
 
-function printVersion() {
+if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  printHelp();
+} else if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
   console.log(`crg-dev-kit v${pkg.version}`);
-}
-
-function copyFiles() {
-  const cwd = process.cwd();
-  const files = [
-    { name: 'setup-crg.sh', executable: true },
-    { name: 'setup-crg.ps1', executable: false },
-    { name: 'check-crg.sh', executable: true },
-    { name: 'CLAUDE.md', executable: false },
-    { name: 'crg-cheatsheet.pdf', executable: false },
-    { name: 'README.md', executable: false },
-  ];
-
-  let copied = 0;
-  files.forEach(f => {
-    const src = path.join(ASSETS, f.name);
-    const dst = path.join(cwd, f.name);
-    if (fs.existsSync(src)) {
-      if (fs.existsSync(dst)) {
-        console.log(`  \x1b[33m~\x1b[0m ${f.name} \x1b[2m(already exists, skipping)\x1b[0m`);
-        return;
-      }
-      fs.copyFileSync(src, dst);
-      if (f.executable) {
-        try { fs.chmodSync(dst, '755'); } catch {}
-      }
-      console.log(`  \x1b[32m✓\x1b[0m ${f.name}`);
-      copied++;
-    }
-  });
-
-  // Track install date (only if --no-roi not set)
-  if (!NO_ROI) {
-    roi.setInstallDate(cwd);
-    console.log('\n  \x1b[36m✓ Install date recorded for ROI tracking\x1b[0m');
-  }
-
-  if (copied === 0) {
-    console.log('\n  \x1b[33mFiles already exist, install date updated.\x1b[0m');
-    return;
-  }
-
-  const isWin = process.platform === 'win32';
-  console.log(`\n  \x1b[32m${copied} file(s) copied to ${cwd}\x1b[0m\n`);
-  console.log('  \x1b[1mNext steps:\x1b[0m');
-  if (isWin) {
-    console.log('    .\\setup-crg.ps1 -WithCommunities');
-    console.log('    code-review-graph status');
-  } else {
-    console.log('    bash setup-crg.sh --with-communities');
-    console.log('    bash check-crg.sh');
-  }
-  console.log('');
-}
-
-function checkStatus() {
-  const cwd = process.cwd();
-  const checks = [
-    { file: 'setup-crg.sh', label: 'Linux/macOS setup script' },
-    { file: 'setup-crg.ps1', label: 'Windows setup script' },
-    { file: 'check-crg.sh', label: 'Health check script' },
-    { file: 'CLAUDE.md', label: 'AI configuration' },
-  ];
-
-  console.log('\n  \x1b[36mCRG Installation Status\x1b[0m\n');
-  let found = 0;
-  checks.forEach(c => {
-    const exists = fs.existsSync(path.join(cwd, c.file));
-    if (exists) found++;
-    console.log(`  ${exists ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m'} ${c.label}`);
-  });
-
-  // Check if code-review-graph is installed
-  const checkCRG = () => {
-    return new Promise(resolve => {
-      execFile('code-review-graph', ['--version'], (err) => {
-        resolve(!err);
-      });
-    });
-  };
-
-  checkCRG().then(installed => {
-    console.log(`  ${installed ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m'} code-review-graph CLI`);
-    const total = checks.length + 1;
-    const score = found + (installed ? 1 : 0);
-    console.log(`\n  ${score}/${total} components present`);
-    if (score === total) {
-      console.log('  \x1b[32m✓ Fully set up!\x1b[0m\n');
-    } else if (score >= 3) {
-      console.log('  \x1b[33m~ Partially set up. Run install command.\x1b[0m\n');
-    } else {
-      console.log('  \x1b[31m✗ Not set up. Run: npx crg-dev-kit install\x1b[0m\n');
-    }
-  });
-}
-
-function uninstallFiles() {
-  const cwd = process.cwd();
-  const files = ['setup-crg.sh', 'setup-crg.ps1', 'check-crg.sh', 'CLAUDE.md', 'crg-cheatsheet.pdf', 'README.md'];
-  let removed = 0;
-
-  files.forEach(f => {
-    const dst = path.join(cwd, f);
-    if (fs.existsSync(dst)) {
-      fs.unlinkSync(dst);
-      console.log(`  \x1b[31m✗\x1b[0m ${f}`);
-      removed++;
-    }
-  });
-
-  if (removed === 0) {
-    console.log('\n  \x1b[33mNo CRG files found to remove.\x1b[0m\n');
-  } else {
-    console.log(`\n  \x1b[31m${removed} file(s) removed from ${cwd}\x1b[0m\n`);
-  }
-}
-
-function startServer() {
+} else {
   let port = 8742;
   let noOpen = false;
 
@@ -178,73 +45,6 @@ function startServer() {
     if (args[i] === '--no-open') noOpen = true;
   }
 
-  const serverPath = path.join(__dirname, '..', 'server.js');
-  const server = require(serverPath);
+  const server = require('../server');
   server.start(port, noOpen);
 }
-
-function showROI() {
-  const cwd = process.cwd();
-  const report = roi.generateROIReport(cwd);
-  console.log('\n' + report);
-}
-
-function runTutorial() {
-  const tutorialPath = path.join(__dirname, 'tutorial.js');
-  const tutorial = require(tutorialPath);
-}
-
-// Command routing
-switch (cmd) {
-  case 'install':
-  case 'setup':
-    copyFiles();
-    break;
-
-  case 'uninstall':
-  case 'remove':
-    uninstallFiles();
-    break;
-
-  case 'status':
-  case 'check':
-    checkStatus();
-    break;
-
-  case 'start':
-  case 'serve':
-  case 'dashboard':
-    startServer();
-    break;
-
-  case 'help':
-  case '--help':
-  case '-h':
-    printHelp();
-    break;
-
-  case 'version':
-  case '--version':
-  case '-v':
-    printVersion();
-    break;
-
-  case 'roi':
-    showROI();
-    break;
-
-  case 'tutorial':
-    runTutorial();
-    break;
-
-  default:
-    // No command or unknown command = start server
-    if (!cmd || cmd.startsWith('-')) {
-      startServer();
-    } else {
-      console.log(`\x1b[31mUnknown command: ${cmd}\x1b[0m`);
-      console.log('Run \x1b[1mnpx crg-dev-kit help\x1b[0m for usage.\n');
-      process.exit(1);
-    }
-    break;
-}

package/lib/actions.js

@@ -0,0 +1,127 @@
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+const { ANALYTICS_DIR } = require('./paths');
+const roi = require('./roi');
+
+const ASSETS = path.join(__dirname, '..', 'assets');
+
+const INSTALL_FILES = [
+  { name: 'setup-crg.sh', executable: true, label: 'Linux/macOS setup script' },
+  { name: 'setup-crg.ps1', executable: false, label: 'Windows setup script' },
+  { name: 'check-crg.sh', executable: true, label: 'Health check script' },
+  { name: 'CLAUDE.md', executable: false, label: 'AI configuration' },
+  { name: 'crg-cheatsheet.pdf', executable: false, label: 'Cheatsheet PDF' },
+  { name: 'README.md', executable: false, label: 'Documentation' },
+];
+
+function install(targetDir, trackROI = true) {
+  const results = [];
+  let copied = 0;
+
+  INSTALL_FILES.forEach(f => {
+    const src = path.join(ASSETS, f.name);
+    const dst = path.join(targetDir, f.name);
+    if (!fs.existsSync(src)) {
+      results.push({ file: f.name, status: 'missing_source' });
+      return;
+    }
+    if (fs.existsSync(dst)) {
+      results.push({ file: f.name, status: 'skipped', reason: 'already exists' });
+      return;
+    }
+    fs.copyFileSync(src, dst);
+    if (f.executable) {
+      try { fs.chmodSync(dst, '755'); } catch {}
+    }
+    results.push({ file: f.name, status: 'copied' });
+    copied++;
+  });
+
+  if (trackROI) {
+    roi.setInstallDate(targetDir);
+  }
+
+  return { copied, total: INSTALL_FILES.length, results, targetDir };
+}
+
+function status(targetDir) {
+  const checks = INSTALL_FILES.slice(0, 4).map(f => ({
+    file: f.name,
+    label: f.label,
+    exists: fs.existsSync(path.join(targetDir, f.name))
+  }));
+
+  return new Promise(resolve => {
+    execFile('code-review-graph', ['--version'], (err, stdout) => {
+      const crgInstalled = !err;
+      const crgVersion = crgInstalled ? (stdout || '').trim() : null;
+      const found = checks.filter(c => c.exists).length + (crgInstalled ? 1 : 0);
+      const total = checks.length + 1;
+
+      let verdict = 'not_setup';
+      if (found === total) verdict = 'ready';
+      else if (found >= 3) verdict = 'partial';
+
+      resolve({ checks, crgInstalled, crgVersion, found, total, verdict, targetDir });
+    });
+  });
+}
+
+function uninstall(targetDir) {
+  const files = INSTALL_FILES.map(f => f.name);
+  const existing = files.filter(f => fs.existsSync(path.join(targetDir, f)));
+  const removed = [];
+
+  existing.forEach(f => {
+    fs.unlinkSync(path.join(targetDir, f));
+    removed.push(f);
+  });
+
+  return { removed, targetDir };
+}
+
+function healthCheck(targetDir) {
+  const results = [];
+
+  // Check graph DB
+  const dbPath = path.join(targetDir, '.code-review-graph', 'graph.db');
+  results.push({ check: 'Graph DB exists', pass: fs.existsSync(dbPath) });
+
+  // Check setup files
+  results.push({ check: 'setup-crg.sh present', pass: fs.existsSync(path.join(targetDir, 'setup-crg.sh')) });
+  results.push({ check: 'CLAUDE.md present', pass: fs.existsSync(path.join(targetDir, 'CLAUDE.md')) });
+
+  return new Promise(resolve => {
+    execFile('code-review-graph', ['--version'], (err, stdout) => {
+      results.push({ check: 'code-review-graph CLI', pass: !err, version: err ? null : (stdout || '').trim() });
+
+      // Try getting graph stats
+      if (fs.existsSync(dbPath)) {
+        try {
+          const sqlite3 = require('child_process');
+          // Use python to read SQLite since we can't require sqlite3
+          const cmd = `python3 -c "import sqlite3,json;db=sqlite3.connect('${dbPath}');r=dict(nodes=db.execute('SELECT COUNT(*) FROM nodes').fetchone()[0],edges=db.execute('SELECT COUNT(*) FROM edges').fetchone()[0]);print(json.dumps(r))"`;
+          execFile('bash', ['-c', cmd], (err2, stdout2) => {
+            if (!err2 && stdout2) {
+              try {
+                const stats = JSON.parse(stdout2.trim());
+                results.push({ check: `Graph: ${stats.nodes} nodes, ${stats.edges} edges`, pass: stats.nodes > 0 });
+              } catch {}
+            }
+            const pass = results.filter(r => r.pass).length;
+            resolve({ results, pass, total: results.length, targetDir });
+          });
+        } catch {
+          const pass = results.filter(r => r.pass).length;
+          resolve({ results, pass, total: results.length, targetDir });
+        }
+      } else {
+        const pass = results.filter(r => r.pass).length;
+        resolve({ results, pass, total: results.length, targetDir });
+      }
+    });
+  });
+}
+
+module.exports = { install, status, uninstall, healthCheck, INSTALL_FILES, ASSETS };

package/lib/analytics.js

@@ -1,10 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-
-const ANALYTICS_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.crg-analytics');
-const SESSIONS_FILE = path.join(ANALYTICS_DIR, 'sessions.json');
-const TOKEN_BASELINES = path.join(ANALYTICS_DIR, 'baselines.json');
+const { ANALYTICS_DIR, SESSIONS_FILE, ensureDir } = require('./paths');
 
 const TOKEN_ESTIMATES = {
   read_file_per_100_lines: 75,
@@ -23,12 +20,6 @@ const TOKEN_ESTIMATES = {
   get_review_context_tool: 400,
 };
 
-function ensureDir() {
-  if (!fs.existsSync(ANALYTICS_DIR)) {
-    fs.mkdirSync(ANALYTICS_DIR, { recursive: true });
-  }
-}
-
 function readJSON(file, fallback) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -60,10 +51,14 @@ function estimateTokensWithCRG(toolsUsed) {
 }
 
 function createSession(projectPath, operation) {
+  if (typeof projectPath !== 'string' || projectPath.length === 0 || projectPath.length > 500) {
+    throw new Error('Invalid project path');
+  }
+  projectPath = path.resolve(projectPath);
   ensureDir();
   const sessions = readJSON(SESSIONS_FILE, []);
   const session = {
-    id: crypto.randomUUID(),
+    id: crypto.randomUUID ? crypto.randomUUID() : require('crypto').randomBytes(16).toString('hex'),
     project: projectPath,
     operation: operation || 'code_review',
     startTime: new Date().toISOString(),
@@ -174,6 +169,13 @@ function getAllStats() {
   const totalTokensWithCRG = projectStats.reduce((sum, p) => sum + p.totalTokensWithCRG, 0);
   const avgSavings = projectStats.reduce((sum, p) => sum + p.avgSavingsPercent, 0) / projectStats.length;
 
+  const toolUsage = {};
+  projectStats.forEach(p => {
+    Object.entries(p.toolUsage).forEach(([tool, count]) => {
+      toolUsage[tool] = (toolUsage[tool] || 0) + count;
+    });
+  });
+
   return {
     totalProjects: projectPaths.length,
     totalSessions: completedSessions.length,
@@ -182,6 +184,7 @@ function getAllStats() {
     totalTokensSaved: totalTokensWithoutCRG - totalTokensWithCRG,
     avgSavingsPercent: Math.round(avgSavings),
     estimatedCostSavings: Math.round((totalTokensWithoutCRG - totalTokensWithCRG) / 1000 * 0.01 * 100) / 100,
+    toolUsage,
     projects: projectStats
   };
 }

package/lib/paths.js

@@ -0,0 +1,13 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ANALYTICS_DIR = path.join(os.homedir(), '.crg-analytics');
+const SESSIONS_FILE = path.join(ANALYTICS_DIR, 'sessions.json');
+const HISTORY_FILE = path.join(os.homedir(), '.claude', 'history.jsonl');
+
+function ensureDir() {
+  fs.mkdirSync(ANALYTICS_DIR, { recursive: true });
+}
+
+module.exports = { ANALYTICS_DIR, SESSIONS_FILE, HISTORY_FILE, ensureDir };

package/lib/roi.js

@@ -1,14 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-
-const ANALYTICS_DIR = path.join(process.env.HOME || process.env.USERPROFILE, '.crg-analytics');
-const HISTORY_FILE = path.join(process.env.HOME || process.env.USERPROFILE, '.claude', 'history.jsonl');
-
-function ensureDir() {
-  if (!fs.existsSync(ANALYTICS_DIR)) {
-    fs.mkdirSync(ANALYTICS_DIR, { recursive: true });
-  }
-}
+const { ANALYTICS_DIR, HISTORY_FILE, ensureDir } = require('./paths');
 
 function getInstallDate(projectPath) {
   const installFile = path.join(ANALYTICS_DIR, 'install.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crg-dev-kit",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "One-click setup for code-review-graph — AI-powered codebase knowledge graph with token analytics",
   "main": "server.js",
   "bin": {