ai-lens 0.1.0

package/.commithash

@@ -0,0 +1 @@
+563282f

package/README.md

@@ -0,0 +1,221 @@
+# AI Lens
+
+Hook-based analytics for AI coding sessions. Captures events from Claude Code and Cursor, normalizes them to a unified format, queues locally, and ships to a centralized server with a web dashboard.
+
+```
+Hook fires → capture.js → normalize → queue.jsonl → sender.js → POST /api/events → server → dashboard
+```
+
+## Developer Setup (client)
+
+Run the init command on each developer machine:
+
+```bash
+npx ai-lens init
+```
+
+This will:
+1. Detect installed AI tools (Claude Code, Cursor)
+2. Copy client files to `~/.ai-lens/client/`
+3. Configure hooks in `~/.claude/settings.json` and/or `~/.cursor/hooks.json`
+
+Re-running is safe — it updates outdated hooks and skips current ones.
+
+Configure the server URL and optionally filter projects:
+
+```bash
+# In your shell profile (~/.zshrc, ~/.bashrc)
+export AI_LENS_SERVER_URL=http://your-server:13300
+export AI_LENS_PROJECTS="~/work/, ~/projects/"   # optional, default: all
+```
+
+<details>
+<summary>Manual hook setup</summary>
+
+**Claude Code** — `~/.claude/settings.json` (hooks section):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PreToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }],
+    "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "node ~/.ai-lens/client/capture.js" }] }]
+  }
+}
+```
+
+**Cursor** — `~/.cursor/hooks.json`:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "beforeSubmitPrompt": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "postToolUse": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "afterFileEdit": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "afterShellExecution": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "afterMCPExecution": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "stop": [{ "command": "node ~/.ai-lens/client/capture.js" }],
+    "sessionEnd": [{ "command": "node ~/.ai-lens/client/capture.js" }]
+  }
+}
+```
+
+</details>
+
+## Server Setup
+
+### Docker (production)
+
+```bash
+docker compose up -d
+```
+
+Starts three containers:
+- **nginx** — reverse proxy with basic auth, port `13300`
+- **app** — Node.js Express server with dashboard
+- **postgres** — PostgreSQL 16 database
+
+Dashboard: `http://your-server:13300`
+
+Default credentials:
+
+| User | Password | Purpose |
+|------|----------|---------|
+| `collector` | `secret-collector-token-2026-ai-lens` | Client sender (automatic via `AI_LENS_AUTH_TOKEN`) |
+| `meta` | `meta` | Browser / dashboard access |
+
+### Local development
+
+```bash
+npm install --prefix server   # Install server deps (auto-runs via prestart)
+npm start                     # Express on port 3000, SQLite at ~/.ai-lens-server/data.db
+```
+
+SQLite is used when `DATABASE_URL` is not set. PostgreSQL is used in Docker via `DATABASE_URL=postgresql://...`.
+
+## Dashboard
+
+React + TypeScript SPA with session timelines, tool breakdowns, adoption trends, and per-developer analytics.
+
+```bash
+cd dashboard
+npm install
+npm run dev          # Vite dev server with HMR (proxies API to localhost:3000)
+```
+
+Production build (served by Express as static files):
+
+```bash
+npm run build:dashboard
+```
+
+Tech: Vite, Tailwind CSS, Nivo charts, TanStack Query, react-router-dom.
+
+## API
+
+### `POST /api/events`
+
+Batch insert events. Deduplicates by `event_id` (ON CONFLICT DO NOTHING) — safe to re-send.
+
+```
+Headers: X-Developer-Git-Email, X-Developer-Name, Authorization: Basic <base64>
+Body: [{ source, session_id, type, project_path, timestamp, data, raw, event_id }]
+Response: { received, skipped, deduplicated }
+```
+
+### `GET /api/sessions`
+
+List sessions. Query params: `developer_id`, `source`, `days` (default 30).
+
+### `GET /api/sessions/:id`
+
+Session detail with all events, plan segments, and metadata.
+
+### `GET /api/developers`
+
+List all developers.
+
+### `GET /api/dashboard/*`
+
+Aggregate endpoints for dashboard charts (stats, trends, tool usage, etc.).
+
+## Event Types
+
+| Type | Source | Description |
+|------|--------|-------------|
+| `SessionStart` | Both | Session opened |
+| `SessionEnd` | Both | Session closed |
+| `UserPromptSubmit` | Both | User sent a prompt |
+| `PostToolUse` | Both | Tool execution completed |
+| `PostToolUseFailure` | Both | Tool execution failed |
+| `Stop` | Both | Agent stopped |
+| `PreCompact` | Both | Context compaction triggered |
+| `PlanModeStart` | Claude Code | Entered plan mode |
+| `PlanModeEnd` | Claude Code | Exited plan mode (plan content in raw payload) |
+| `SubagentStart` | Both | Subagent spawned |
+| `SubagentStop` | Both | Subagent finished |
+| `FileEdit` | Cursor | File edited |
+| `ShellExecution` | Cursor | Shell command executed |
+| `MCPExecution` | Cursor | MCP tool executed |
+| `AgentResponse` | Cursor | Agent response |
+| `AgentThought` | Cursor | Agent reasoning |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` (local), `13300` (Docker) | Server port |
+| `DATABASE_URL` | _(unset = SQLite)_ | PostgreSQL connection string |
+| `AI_LENS_SERVER_URL` | `http://localhost:3000` | Client → server endpoint |
+| `AI_LENS_AUTH_TOKEN` | `collector:secret-collector-token-2026-ai-lens` | Client auth (`user:password`) |
+| `AI_LENS_PROJECTS` | _(all)_ | Comma-separated project paths to monitor (`~` supported) |
+
+## Client Data
+
+Stored in `~/.ai-lens/`:
+
+| File | Purpose |
+|------|---------|
+| `client/` | Installed client files (capture.js, sender.js, config.js) |
+| `queue.jsonl` | Pending events |
+| `queue.sending.jsonl` | Events being sent (atomic rename as mutex) |
+| `sender.log` | Sender activity log |
+| `session-paths.json` | Session-to-project path cache |
+
+## Development
+
+```bash
+npm test               # Run all tests (vitest, 204 tests)
+npm run test:watch     # Watch mode
+npm run dev:dashboard  # Dashboard dev server
+```
+
+Tests use in-memory SQLite via `initTestDb()`.
+
+## Deployment
+
+GitLab CI (`.gitlab-ci.yml`) on push to `main`:
+
+1. `rsync` to deploy host
+2. `docker compose down && docker compose up -d --build`
+3. Health check
+
+## Data Migration
+
+Sync local SQLite data to a remote PostgreSQL server:
+
+```bash
+node scripts/sync-to-remote.js                       # Default remote
+node scripts/sync-to-remote.js http://custom:13300   # Custom URL
+```
+
+Safe to re-run — deduplicates by `event_id`.
+
+## Requirements
+
+- Node.js 20+
+- Docker + Docker Compose (for production deployment)

package/bin/ai-lens.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'init': {
+    const { default: init } = await import('../cli/init.js');
+    await init();
+    break;
+  }
+  case 'remove': {
+    const { default: remove } = await import('../cli/remove.js');
+    await remove();
+    break;
+  }
+  case 'mcp': {
+    await import('../mcp-server/index.js');
+    break;
+  }
+  default:
+    console.log('Usage: ai-lens <command>');
+    console.log('');
+    console.log('Commands:');
+    console.log('  init    Configure AI tool hooks for event capture');
+    console.log('  remove  Remove AI Lens hooks and client files');
+    console.log('  mcp     Start the MCP server (stdio transport)');
+    process.exit(command ? 1 : 0);
+}

package/cli/hooks.js

@@ -0,0 +1,365 @@
+import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Version info
+// ---------------------------------------------------------------------------
+
+export function getVersionInfo() {
+  let version = 'unknown';
+  let commit = 'unknown';
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8'));
+    version = pkg.version;
+  } catch { /* ignore */ }
+  try {
+    commit = readFileSync(join(PKG_ROOT, '.commithash'), 'utf-8').trim();
+  } catch { /* ignore */ }
+  return { version, commit };
+}
+
+// Stable install location for client files
+const CLIENT_INSTALL_DIR = join(homedir(), '.ai-lens', 'client');
+const CONFIG_PATH = join(homedir(), '.ai-lens', 'config.json');
+
+// Hooks always point to the installed copy at ~/.ai-lens/client/capture.js
+export const CAPTURE_PATH = join(CLIENT_INSTALL_DIR, 'capture.js');
+
+// ---------------------------------------------------------------------------
+// AI Lens config (~/.ai-lens/config.json)
+// ---------------------------------------------------------------------------
+
+export function readLensConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveLensConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+const DEFAULT_SERVER_URL = 'http://localhost:3000';
+
+/**
+ * Escape a string for safe embedding in a single-quoted shell context.
+ * Standard POSIX approach: replace each ' with '\'' (end quote, escaped quote, start quote).
+ */
+export function shellEscape(str) {
+  if (typeof str !== 'string') return "''";
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
+function captureCommand() {
+  const config = readLensConfig();
+  const envs = [];
+  if (config.serverUrl && config.serverUrl !== DEFAULT_SERVER_URL) {
+    envs.push(`AI_LENS_SERVER_URL=${shellEscape(config.serverUrl)}`);
+  }
+  if (config.projects) {
+    envs.push(`AI_LENS_PROJECTS=${shellEscape(config.projects)}`);
+  }
+  const base = `node ${CAPTURE_PATH}`;
+  return envs.length > 0 ? `${envs.join(' ')} ${base}` : base;
+}
+
+// ---------------------------------------------------------------------------
+// Client file installation
+// ---------------------------------------------------------------------------
+
+const CLIENT_FILES = ['capture.js', 'sender.js', 'config.js', 'redact.js'];
+
+/**
+ * Copy client/ files from the package source to ~/.ai-lens/client/.
+ * Works from npx cache, global install, and local dev.
+ */
+export function installClientFiles() {
+  const sourceDir = join(__dirname, '..', 'client');
+  mkdirSync(CLIENT_INSTALL_DIR, { recursive: true });
+
+  for (const file of CLIENT_FILES) {
+    copyFileSync(join(sourceDir, file), join(CLIENT_INSTALL_DIR, file));
+  }
+
+  // ESM needs package.json with "type": "module"
+  writeFileSync(
+    join(CLIENT_INSTALL_DIR, 'package.json'),
+    '{"type":"module"}\n',
+  );
+}
+
+/**
+ * Remove installed client files from ~/.ai-lens/client/.
+ */
+export function removeClientFiles() {
+  if (existsSync(CLIENT_INSTALL_DIR)) {
+    rmSync(CLIENT_INSTALL_DIR, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook definitions per tool
+// ---------------------------------------------------------------------------
+
+const CLAUDE_CODE_HOOKS = {
+  SessionStart: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  SessionEnd: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  UserPromptSubmit: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  PreToolUse: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  PostToolUse: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  PostToolUseFailure: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  Stop: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  PreCompact: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  SubagentStart: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+  SubagentStop: () => ({ matcher: '', hooks: [{ type: 'command', command: captureCommand() }] }),
+};
+
+const CURSOR_HOOKS = {
+  sessionStart: () => ({ command: captureCommand() }),
+  beforeSubmitPrompt: () => ({ command: captureCommand() }),
+  postToolUse: () => ({ command: captureCommand() }),
+  postToolUseFailure: () => ({ command: captureCommand() }),
+  afterFileEdit: () => ({ command: captureCommand() }),
+  afterShellExecution: () => ({ command: captureCommand() }),
+  afterMCPExecution: () => ({ command: captureCommand() }),
+  subagentStart: () => ({ command: captureCommand() }),
+  subagentStop: () => ({ command: captureCommand() }),
+  preCompact: () => ({ command: captureCommand() }),
+  afterAgentResponse: () => ({ command: captureCommand() }),
+  afterAgentThought: () => ({ command: captureCommand() }),
+  stop: () => ({ command: captureCommand() }),
+  sessionEnd: () => ({ command: captureCommand() }),
+};
+
+export const TOOL_CONFIGS = [
+  {
+    name: 'Claude Code',
+    dirPath: join(homedir(), '.claude'),
+    configPath: join(homedir(), '.claude', 'settings.json'),
+    hookDefs: CLAUDE_CODE_HOOKS,
+    topLevelFields: {},
+    sharedConfig: true,
+  },
+  {
+    name: 'Cursor',
+    dirPath: join(homedir(), '.cursor'),
+    configPath: join(homedir(), '.cursor', 'hooks.json'),
+    hookDefs: CURSOR_HOOKS,
+    topLevelFields: { version: 1 },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// AI Lens hook detection
+// ---------------------------------------------------------------------------
+
+export function isAiLensHook(entry) {
+  // Flat format (Cursor): { command: "..." }
+  const cmd = entry?.command || '';
+  if (cmd.includes('ai-lens') && cmd.includes('capture.js')) return true;
+  // Nested format (Claude Code): { matcher, hooks: [{ command: "..." }] }
+  if (Array.isArray(entry?.hooks)) {
+    return entry.hooks.some(h => {
+      const c = h?.command || '';
+      return c.includes('ai-lens') && c.includes('capture.js');
+    });
+  }
+  return false;
+}
+
+function isCurrentAiLensHook(entry) {
+  // Flat format (Cursor)
+  if (entry?.command === captureCommand()) return true;
+  // Nested format (Claude Code)
+  if (Array.isArray(entry?.hooks)) {
+    return entry.hooks.some(h => h?.command === captureCommand());
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Tool detection
+// ---------------------------------------------------------------------------
+
+export function detectInstalledTools() {
+  return TOOL_CONFIGS.filter(t => existsSync(t.dirPath));
+}
+
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze a tool's hooks.json and return status.
+ * Returns { status, config?, error? }
+ *   status: 'fresh' | 'current' | 'outdated' | 'absent' | 'malformed'
+ */
+export function analyzeToolHooks(tool) {
+  if (!existsSync(tool.configPath)) {
+    return { status: 'fresh' };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(tool.configPath, 'utf-8');
+  } catch (err) {
+    return { status: 'malformed', error: err.message };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    // For shared config files (settings.json), don't backup/rename — other tools depend on it
+    if (tool.sharedConfig) {
+      return { status: 'malformed', error: err.message };
+    }
+    const bakPath = tool.configPath + '.bak';
+    try { renameSync(tool.configPath, bakPath); } catch { /* ignore */ }
+    return { status: 'malformed', backupPath: bakPath, error: err.message };
+  }
+
+  const hooks = config.hooks;
+  if (!hooks || typeof hooks !== 'object') {
+    return { status: 'absent', config };
+  }
+
+  // Check if any AI Lens hooks exist
+  let hasAiLens = false;
+  let allCurrent = true;
+
+  for (const hookName of Object.keys(tool.hookDefs)) {
+    const entries = hooks[hookName];
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (isAiLensHook(entry)) {
+        hasAiLens = true;
+        if (!isCurrentAiLensHook(entry)) {
+          allCurrent = false;
+        }
+      }
+    }
+  }
+
+  if (!hasAiLens) {
+    return { status: 'absent', config };
+  }
+
+  // Check all expected hooks are present
+  for (const hookName of Object.keys(tool.hookDefs)) {
+    const entries = hooks[hookName];
+    if (!Array.isArray(entries) || !entries.some(e => isAiLensHook(e))) {
+      allCurrent = false;
+      break;
+    }
+  }
+
+  return { status: allCurrent ? 'current' : 'outdated', config };
+}
+
+// ---------------------------------------------------------------------------
+// Merge logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a merged config: strip old AI Lens entries, add new ones,
+ * preserve everything else.
+ */
+export function buildMergedConfig(tool, existingConfig) {
+  const base = existingConfig ? structuredClone(existingConfig) : {};
+
+  // Preserve top-level fields (e.g. Cursor's version: 1)
+  for (const [k, v] of Object.entries(tool.topLevelFields)) {
+    if (base[k] === undefined) {
+      base[k] = v;
+    }
+  }
+
+  if (!base.hooks || typeof base.hooks !== 'object') {
+    base.hooks = {};
+  }
+
+  for (const [hookName, entryFactory] of Object.entries(tool.hookDefs)) {
+    const existing = Array.isArray(base.hooks[hookName]) ? base.hooks[hookName] : [];
+    // Remove old AI Lens entries
+    const preserved = existing.filter(e => !isAiLensHook(e));
+    // Append new AI Lens entry
+    preserved.push(entryFactory());
+    base.hooks[hookName] = preserved;
+  }
+
+  return base;
+}
+
+/**
+ * Build a config with all AI Lens entries removed.
+ * Returns null if the resulting hooks object is empty (file can be deleted).
+ */
+export function buildStrippedConfig(tool, existingConfig) {
+  const base = structuredClone(existingConfig);
+
+  if (!base.hooks || typeof base.hooks !== 'object') {
+    return null;
+  }
+
+  for (const hookName of Object.keys(tool.hookDefs)) {
+    const entries = base.hooks[hookName];
+    if (!Array.isArray(entries)) continue;
+    const preserved = entries.filter(e => !isAiLensHook(e));
+    if (preserved.length > 0) {
+      base.hooks[hookName] = preserved;
+    } else {
+      delete base.hooks[hookName];
+    }
+  }
+
+  // If no hooks remain, clean up
+  if (Object.keys(base.hooks).length === 0) {
+    delete base.hooks;
+    // If other settings remain (shared config like settings.json), keep them
+    if (Object.keys(base).length > 0) {
+      return base;
+    }
+    return null;
+  }
+
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Write config
+// ---------------------------------------------------------------------------
+
+export function writeHooksConfig(tool, config) {
+  mkdirSync(dirname(tool.configPath), { recursive: true });
+  writeFileSync(tool.configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Describe what will happen (for plan display)
+// ---------------------------------------------------------------------------
+
+export function describePlan(tool, analysis) {
+  const hookNames = Object.keys(tool.hookDefs);
+
+  switch (analysis.status) {
+    case 'fresh':
+      return { action: 'create', description: `Create ${tool.configPath}`, hooks: hookNames };
+    case 'outdated':
+      return { action: 'update', description: `Update AI Lens hooks in ${tool.configPath}`, hooks: hookNames };
+    case 'absent':
+      return { action: 'add', description: `Add AI Lens hooks to ${tool.configPath}`, hooks: hookNames };
+    case 'malformed':
+      return { action: 'recreate', description: `Recreate ${tool.configPath} (backed up to .bak)`, hooks: hookNames };
+    default:
+      return null;
+  }
+}