@sdsrs/code-graph 0.4.0 → 0.4.3

package/README.md

@@ -4,14 +4,16 @@ A high-performance code knowledge graph server implementing the [Model Context P
 
 ## Features
 
-- **Multi-language parsing** — Tree-sitter based AST extraction for TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS
+- **Multi-language parsing** — Tree-sitter AST extraction for TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS
 - **Semantic code search** — Hybrid BM25 full-text + vector semantic search with Reciprocal Rank Fusion (RRF), powered by sqlite-vec
 - **Call graph traversal** — Recursive CTE queries to trace callers/callees with cycle detection
 - **HTTP route tracing** — Map route paths to backend handler functions (Express, Flask/FastAPI, Go)
+- **Impact analysis** — Determine the blast radius of code changes by tracing all dependents
 - **Incremental indexing** — Merkle tree change detection with file system watcher for real-time updates
-- **Context compression** — Token-aware snippet extraction for LLM context windows
+- **Context compression** — Token-aware snippet extraction for LLM context windows (L0→full code, L1→summaries, L2→file groups, L3→directory overview)
 - **Embedding model** — Optional local embedding via Candle (feature-gated `embed-model`)
-- **MCP protocol** — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, and other MCP clients
+- **MCP protocol** — JSON-RPC 2.0 over stdio, plug-and-play with Claude Code, Cursor, Windsurf, and other MCP clients
+- **Claude Code Plugin** — First-class plugin with slash commands (`/understand`, `/trace`, `/impact`), agents, skills, auto-indexing hooks, StatusLine integration, and self-updating
 
 ## Why code-graph-mcp?
 
@@ -23,7 +25,7 @@ BLAKE3 Merkle tree tracks every file's content hash. On re-index, only changed f
 
 ### Hybrid Search, Not Just Grep
 
-Combines BM25 full-text ranking (FTS5) with vector semantic similarity (sqlite-vec) via **Reciprocal Rank Fusion (RRF)** — so searching "handle user login" finds the right function even if it's named `authenticate_session`. Results are auto-compressed to fit LLM context windows (L0→full code, L1→summaries, L2→file groups, L3→directory overview).
+Combines BM25 full-text ranking (FTS5) with vector semantic similarity (sqlite-vec) via **Reciprocal Rank Fusion (RRF)** — so searching "handle user login" finds the right function even if it's named `authenticate_session`. Results are auto-compressed to fit LLM context windows.
 
 ### Scope-Aware Relation Extraction
 
@@ -58,15 +60,35 @@ src/
 
 ## Installation
 
-### Option 1: Claude Code (Recommended)
+### Option 1: Claude Code Plugin (Recommended)
 
-One-command setup — registers as an MCP server directly in Claude Code:
+Install as a Claude Code plugin for the best experience — includes slash commands, agents, skills, auto-indexing hooks, StatusLine health display, and automatic updates:
+
+```bash
+# Step 1: Add the marketplace
+/plugin marketplace add sdsrss/code-graph-mcp
+
+# Step 2: Install the plugin
+/plugin install code-graph@sdsrss-code-graph
+```
+
+What you get:
+- **MCP Server** — All code-graph tools available to Claude
+- **Slash Commands** — `/understand <module>`, `/trace <route>`, `/impact <symbol>`
+- **Code Explorer Agent** — Deep code understanding expert via `code-explorer`
+- **Auto-indexing Hook** — Incremental index on every file edit (PostToolUse)
+- **StatusLine** — Real-time health display (nodes, files, watch status) — compatible with other plugins' StatusLine via composite multiplexer
+- **Auto-update** — Checks for new versions every 24h, updates silently
+
+### Option 2: Claude Code MCP Server Only
+
+Register as an MCP server without the plugin features:
 
 ```bash
 claude mcp add code-graph-mcp -- npx -y @sdsrs/code-graph
 ```
 
-### Option 2: Cursor / Windsurf / Other MCP Clients
+### Option 3: Cursor / Windsurf / Other MCP Clients
 
 Add to your MCP settings file (e.g. `~/.cursor/mcp.json`):
 
@@ -81,7 +103,7 @@ Add to your MCP settings file (e.g. `~/.cursor/mcp.json`):
 }
 ```
 
-### Option 3: npx (No Install)
+### Option 4: npx (No Install)
 
 Run directly without installing:
 
@@ -89,7 +111,7 @@ Run directly without installing:
 npx -y @sdsrs/code-graph
 ```
 
-### Option 4: npm (Global Install)
+### Option 5: npm (Global Install)
 
 Install globally, then run anywhere:
 
@@ -100,7 +122,20 @@ code-graph-mcp
 
 ## Uninstallation
 
-### Claude Code
+### Claude Code Plugin
+
+```bash
+# Uninstall the plugin
+/plugin uninstall code-graph@sdsrss-code-graph
+
+# (Optional) Remove the marketplace
+/plugin marketplace remove sdsrss-code-graph
+
+# (Optional) Clean up all config and cache data
+node ~/.claude/plugins/cache/sdsrss/code-graph/*/scripts/lifecycle.js uninstall
+```
+
+### Claude Code MCP Server
 
 ```bash
 claude mcp remove code-graph-mcp
@@ -116,6 +151,47 @@ Remove the `code-graph` entry from your MCP settings file (e.g. `~/.cursor/mcp.j
 npm uninstall -g @sdsrs/code-graph
 ```
 
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `semantic_code_search` | Hybrid BM25 + vector + graph search for AST nodes |
+| `get_call_graph` | Trace upstream/downstream call chains for a function |
+| `find_http_route` | Map route path to backend handler function |
+| `trace_http_chain` | Full request flow: route → handler → downstream call chain |
+| `impact_analysis` | Analyze the blast radius of changing a symbol |
+| `module_overview` | High-level overview of a module's structure and exports |
+| `dependency_graph` | Visualize dependency relationships between modules |
+| `find_similar_code` | Find code snippets similar to a given pattern |
+| `get_ast_node` | Extract a specific code symbol from a file |
+| `read_snippet` | Read original code snippet by node ID with context |
+| `start_watch` / `stop_watch` | Start/stop file system watcher for incremental indexing |
+| `get_index_status` | Query index status and health |
+| `rebuild_index` | Force full index rebuild |
+
+## Plugin Slash Commands
+
+Available when installed as a Claude Code plugin:
+
+| Command | Description |
+|---------|-------------|
+| `/understand <module>` | Deep dive into a module or file's architecture and relationships |
+| `/trace <route>` | Trace a full HTTP request flow from route to data layer |
+| `/impact <symbol>` | Analyze the impact scope of changing a symbol before modifying it |
+
+## Supported Languages
+
+TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS
+
+## Storage
+
+Uses SQLite with:
+- FTS5 for full-text search
+- sqlite-vec extension for vector similarity search
+- Merkle tree hashes for incremental change detection
+
+Data is stored in `.code-graph/index.db` under the project root (auto-created, gitignored).
+
 ## Build from Source
 
 ### Prerequisites
@@ -147,33 +223,6 @@ Add the compiled binary to your MCP settings:
 }
 ```
 
-## MCP Tools
-
-| Tool | Description |
-|------|-------------|
-| `semantic_code_search` | Hybrid BM25 + vector + graph search for AST nodes |
-| `get_call_graph` | Trace upstream/downstream call chains for a function |
-| `find_http_route` | Map route path to backend handler function |
-| `trace_http_chain` | Full request flow: route → handler → downstream call chain |
-| `get_ast_node` | Extract a specific code symbol from a file |
-| `read_snippet` | Read original code snippet by node ID with context |
-| `start_watch` / `stop_watch` | Start/stop file system watcher for incremental indexing |
-| `get_index_status` | Query index status and health |
-| `rebuild_index` | Force full index rebuild |
-
-## Supported Languages
-
-TypeScript, JavaScript, Go, Python, Rust, Java, C, C++, HTML, CSS
-
-## Storage
-
-Uses SQLite with:
-- FTS5 for full-text search
-- sqlite-vec extension for vector similarity search
-- Merkle tree hashes for incremental change detection
-
-Data is stored in `.code-graph/index.db` under the project root (auto-created, gitignored).
-
 ## Development
 
 ```bash

package/claude-plugin/.claude-plugin/plugin.json

@@ -4,6 +4,6 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.3.0",
+  "version": "0.4.3",
   "keywords": ["code-graph", "ast", "navigation", "mcp", "knowledge-graph"]
 }

package/claude-plugin/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "code-graph-mcp incremental-index --quiet",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/incremental-index.js\"",
             "timeout": 10
           }
         ],
@@ -15,14 +15,15 @@
     ],
     "SessionStart": [
       {
+        "matcher": "startup",
         "hooks": [
           {
             "type": "command",
-            "command": "code-graph-mcp health-check --format oneline",
-            "timeout": 5
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-init.js\"",
+            "timeout": 8
           }
         ],
-        "description": "Verify code graph index freshness at session start"
+        "description": "Health check, StatusLine registration, and update check at session start"
       }
     ]
   }

package/claude-plugin/scripts/auto-update.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+'use strict';
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { CACHE_DIR, PLUGIN_ID, readManifest, readJson, writeJsonAtomic } = require('./lifecycle');
+
+// ── Configuration ──────────────────────────────────────────
+const GITHUB_REPO = 'sdsrss/code-graph-mcp';
+const NPM_PACKAGE = '@sdsrs/code-graph';
+const STATE_FILE = path.join(CACHE_DIR, 'update-state.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;       // 24h
+const RATE_LIMIT_INTERVAL_MS = 6 * 60 * 60 * 1000;   // 6h if rate-limited
+const FETCH_TIMEOUT_MS = 3000;
+
+// ── State Persistence ──────────────────────────────────────
+
+function readState() {
+  return readJson(STATE_FILE) || {};
+}
+
+function saveState(state) {
+  try {
+    writeJsonAtomic(STATE_FILE, state);
+  } catch { /* ok */ }
+}
+
+// ── Dev Mode Detection ─────────────────────────────────────
+
+function isDevMode() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+  // Dev mode: running from source repo (has Cargo.toml nearby)
+  if (fs.existsSync(path.join(pluginRoot, '..', 'Cargo.toml'))) return true;
+  // Dev mode: plugin root is a symlink
+  try { if (fs.lstatSync(pluginRoot).isSymbolicLink()) return true; } catch { /* ok */ }
+  return false;
+}
+
+// ── Throttle ───────────────────────────────────────────────
+
+function shouldCheck(state) {
+  if (!state.lastCheck) return true;
+  const elapsed = Date.now() - new Date(state.lastCheck).getTime();
+  const interval = state.rateLimited ? RATE_LIMIT_INTERVAL_MS : CHECK_INTERVAL_MS;
+  return elapsed >= interval;
+}
+
+// ── Version Comparison (semver) ────────────────────────────
+
+function compareVersions(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 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+// ── GitHub API ─────────────────────────────────────────────
+
+async function fetchLatestRelease() {
+  const url = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+  try {
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: {
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'code-graph-auto-update/1.0',
+      },
+    });
+
+    if (res.status === 403) {
+      // Rate limited
+      const state = readState();
+      saveState({ ...state, rateLimited: true });
+      return null;
+    }
+    if (!res.ok) return null;
+
+    const data = await res.json();
+    return {
+      version: data.tag_name.replace(/^v/, ''),
+      tarballUrl: data.tarball_url,
+    };
+  } catch { return null; }
+}
+
+// ── Download & Install ─────────────────────────────────────
+
+async function downloadAndInstall(latest) {
+  const tmpDir = path.join(os.tmpdir(), `code-graph-update-${Date.now()}`);
+  try {
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    // 1. Download and extract tarball (plugin files)
+    execSync(
+      `curl -sL -H "Accept: application/vnd.github+json" "${latest.tarballUrl}" | tar xz -C "${tmpDir}" --strip-components=1`,
+      { timeout: 30000, stdio: 'pipe' }
+    );
+
+    // 2. Copy plugin files to cache
+    const pluginSrc = path.join(tmpDir, 'claude-plugin');
+    const pluginDst = path.join(
+      os.homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'code-graph', latest.version
+    );
+
+    if (fs.existsSync(pluginSrc)) {
+      fs.mkdirSync(pluginDst, { recursive: true });
+      // Copy recursively
+      execSync(`cp -r "${pluginSrc}/." "${pluginDst}/"`, { stdio: 'pipe' });
+    }
+
+    // 3. Update installed_plugins.json to point to new version
+    const installedPath = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+    try {
+      const installed = readJson(installedPath);
+      if (installed && installed.plugins && installed.plugins[PLUGIN_ID]) {
+        installed.plugins[PLUGIN_ID][0].installPath = pluginDst;
+        installed.plugins[PLUGIN_ID][0].version = latest.version;
+        installed.plugins[PLUGIN_ID][0].lastUpdated = new Date().toISOString();
+        writeJsonAtomic(installedPath, installed);
+      }
+    } catch { /* installed_plugins update failed — not fatal */ }
+
+    // 4. Update install manifest with tag version
+    try {
+      const manifest = readManifest();
+      manifest.version = latest.version;
+      manifest.updatedAt = new Date().toISOString();
+      writeJsonAtomic(path.join(CACHE_DIR, 'install-manifest.json'), manifest);
+    } catch { /* manifest update failed — not fatal */ }
+
+    // 5. Update npm binary (non-blocking, best-effort)
+    try {
+      execSync(`npm install -g ${NPM_PACKAGE}@${latest.version}`, {
+        timeout: 60000,
+        stdio: 'pipe',
+      });
+    } catch {
+      // npm install failed — plugin files still updated
+      // User can manually update binary later
+    }
+
+    return true;
+  } catch { return false; }
+  finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ok */ }
+  }
+}
+
+// ── Main Entry ─────────────────────────────────────────────
+
+async function checkForUpdate() {
+  try {
+    // Skip in dev mode
+    if (isDevMode()) return null;
+
+    const state = readState();
+
+    // Time-based throttle
+    if (!shouldCheck(state)) {
+      // Report pending update from previous check
+      if (state.updateAvailable && state.latestVersion) {
+        return { updateAvailable: true, from: state.installedVersion, to: state.latestVersion };
+      }
+      return null;
+    }
+
+    // Check GitHub for latest release
+    const latest = await fetchLatestRelease();
+    if (!latest) {
+      saveState({ ...state, lastCheck: new Date().toISOString() });
+      return null;
+    }
+
+    // Compare versions
+    const manifest = readManifest();
+    const currentVersion = manifest.version || '0.0.0';
+    const hasUpdate = compareVersions(latest.version, currentVersion) > 0;
+
+    if (hasUpdate) {
+      // Auto-update
+      const success = await downloadAndInstall(latest);
+      const newState = {
+        lastCheck: new Date().toISOString(),
+        installedVersion: success ? latest.version : currentVersion,
+        latestVersion: latest.version,
+        updateAvailable: !success,
+        lastUpdate: success ? new Date().toISOString() : state.lastUpdate,
+        rateLimited: false,
+      };
+      saveState(newState);
+
+      return {
+        updateAvailable: !success,
+        updated: success,
+        from: currentVersion,
+        to: latest.version,
+      };
+    }
+
+    // No update needed
+    saveState({
+      ...state,
+      lastCheck: new Date().toISOString(),
+      latestVersion: latest.version,
+      updateAvailable: false,
+      rateLimited: false,
+    });
+    return null;
+  } catch {
+    // Silent failure — never block session
+    return null;
+  }
+}
+
+module.exports = { checkForUpdate, isDevMode, readState };
+
+// CLI: node auto-update.js [check|status]
+if (require.main === module) {
+  (async () => {
+    const cmd = process.argv[2] || 'check';
+    if (cmd === 'status') {
+      const state = readState();
+      console.log(JSON.stringify(state, null, 2));
+    } else {
+      console.log('Checking for updates...');
+      const result = await checkForUpdate();
+      if (result && result.updated) {
+        console.log(`Updated: v${result.from} → v${result.to}`);
+      } else if (result && result.updateAvailable) {
+        console.log(`Update available: v${result.to} (auto-install failed)`);
+      } else if (isDevMode()) {
+        console.log('Dev mode — auto-update skipped');
+      } else {
+        const manifest = readManifest();
+        console.log(`Up to date (v${manifest.version || 'unknown'})`);
+      }
+    }
+  })();
+}

package/claude-plugin/scripts/find-binary.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const PLATFORM = os.platform();
+const CACHE_FILE = path.join(os.homedir(), '.cache', 'code-graph', 'binary-path');
+
+/**
+ * Locate the code-graph-mcp binary using multiple strategies.
+ * Results are cached to disk so repeated calls (e.g. per-hook) are fast.
+ * Priority: cache > PATH > local dev build > cargo install > npm platform pkg > npx cache
+ * Returns the absolute path or null if not found.
+ */
+function findBinary() {
+  // Try disk cache first (avoids spawning `which` on hot paths)
+  try {
+    const cached = fs.readFileSync(CACHE_FILE, 'utf8').trim();
+    if (cached && fs.existsSync(cached)) return cached;
+  } catch { /* no cache or stale */ }
+
+  const result = findBinaryUncached();
+
+  // Write cache for subsequent calls
+  if (result) {
+    try {
+      fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+      fs.writeFileSync(CACHE_FILE, result);
+    } catch { /* ok */ }
+  }
+
+  return result;
+}
+
+function findBinaryUncached() {
+  const name = PLATFORM === 'win32' ? 'code-graph-mcp.exe' : 'code-graph-mcp';
+
+  // 1. PATH lookup (user has intentionally installed it)
+  try {
+    const which = PLATFORM === 'win32' ? 'where' : 'which';
+    const found = execFileSync(which, [name], { stdio: ['pipe', 'pipe', 'pipe'] })
+      .toString().trim().split('\n')[0];
+    if (found && fs.existsSync(found)) return found;
+  } catch { /* not in PATH */ }
+
+  // 2. Local dev build (target/release in project directory)
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const devBin = path.join(projectRoot, 'target', 'release', name);
+  if (fs.existsSync(devBin)) return devBin;
+
+  // 3. Cargo install (~/.cargo/bin)
+  const cargoBin = path.join(os.homedir(), '.cargo', 'bin', name);
+  if (fs.existsSync(cargoBin)) return cargoBin;
+
+  // 4. npm platform package (installed via @sdsrs/code-graph)
+  const platformPkg = `@sdsrs/code-graph-${PLATFORM}-${os.arch()}`;
+  try {
+    const pkgPath = require.resolve(`${platformPkg}/package.json`);
+    const bin = path.join(path.dirname(pkgPath), name);
+    if (fs.existsSync(bin)) return bin;
+  } catch { /* not installed via npm */ }
+
+  // 5. npx cache (last resort — may be outdated)
+  const npxDir = path.join(os.homedir(), '.npm', '_npx');
+  try {
+    for (const entry of fs.readdirSync(npxDir)) {
+      const pkgJsonPath = path.join(npxDir, entry, 'node_modules', '@sdsrs', 'code-graph', 'package.json');
+      if (!fs.existsSync(pkgJsonPath)) continue;
+      const platDir = path.join(npxDir, entry, 'node_modules', '@sdsrs', `code-graph-${PLATFORM}-${os.arch()}`);
+      const platBin = path.join(platDir, name);
+      if (fs.existsSync(platBin)) return platBin;
+    }
+  } catch { /* no npx cache */ }
+
+  return null;
+}
+
+module.exports = { findBinary };
+
+// Allow direct invocation for testing
+if (require.main === module) {
+  const bin = findBinary();
+  if (bin) {
+    process.stdout.write(bin);
+  } else {
+    process.stderr.write('code-graph-mcp binary not found\n');
+    process.exit(1);
+  }
+}

package/claude-plugin/scripts/incremental-index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync } = require('child_process');
+const { findBinary } = require('./find-binary');
+
+const bin = findBinary();
+if (!bin) process.exit(0); // silent — binary not installed yet
+
+try {
+  execFileSync(bin, ['incremental-index', '--quiet'], {
+    timeout: 8000,
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+} catch { /* timeout or error — silent for hook */ }

package/claude-plugin/scripts/lifecycle.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PLUGIN_ID = 'code-graph@sdsrss';
+const CACHE_DIR = path.join(os.homedir(), '.cache', 'code-graph');
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+const MANIFEST_FILE = path.join(CACHE_DIR, 'install-manifest.json');
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const INSTALLED_PLUGINS_PATH = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+const REGISTRY_FILE = path.join(CACHE_DIR, 'statusline-registry.json');
+
+// --- Helpers ---
+
+function readJson(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = filePath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  fs.renameSync(tmp, filePath);
+}
+
+function readManifest() {
+  return readJson(MANIFEST_FILE) || { version: null, config: {} };
+}
+
+function writeManifest(manifest) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  writeJsonAtomic(MANIFEST_FILE, manifest);
+}
+
+function getPluginVersion() {
+  const pj = readJson(path.join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json'));
+  return pj ? pj.version : '0.0.0';
+}
+
+function compositeCommand() {
+  return `node ${JSON.stringify(path.join(PLUGIN_ROOT, 'scripts', 'statusline-composite.js'))}`;
+}
+
+function codeGraphStatuslineCommand() {
+  return `node ${JSON.stringify(path.join(PLUGIN_ROOT, 'scripts', 'statusline.js'))}`;
+}
+
+function isOurComposite(settings) {
+  return settings.statusLine &&
+    settings.statusLine.command &&
+    settings.statusLine.command.includes('statusline-composite');
+}
+
+// --- StatusLine Registry ---
+// Multiple providers can register. The composite script runs them all.
+
+function readRegistry() {
+  return readJson(REGISTRY_FILE) || [];
+}
+
+function writeRegistry(registry) {
+  writeJsonAtomic(REGISTRY_FILE, registry);
+}
+
+function registerStatuslineProvider(id, command, needsStdin) {
+  const registry = readRegistry();
+  const idx = registry.findIndex(p => p.id === id);
+  const entry = { id, command, needsStdin: !!needsStdin };
+  if (idx >= 0) {
+    // Update existing entry only if command changed
+    if (registry[idx].command === command) return false;
+    registry[idx] = entry;
+  } else {
+    registry.push(entry);
+  }
+  writeRegistry(registry);
+  return true;
+}
+
+function unregisterStatuslineProvider(id) {
+  const registry = readRegistry();
+  const filtered = registry.filter(p => p.id !== id);
+  if (filtered.length === registry.length) return false;
+  writeRegistry(filtered);
+  return true;
+}
+
+// --- Install (idempotent) ---
+
+function install() {
+  const version = getPluginVersion();
+  const manifest = readManifest();
+  const settings = readJson(SETTINGS_PATH) || {};
+  let settingsChanged = false;
+
+  // 1. StatusLine — composite approach
+  //    a. Capture existing statusline as a provider (if not already composite)
+  //    b. Register code-graph as a provider
+  //    c. Set statusLine to composite script
+  if (!isOurComposite(settings)) {
+    // Preserve existing statusline as first provider
+    if (settings.statusLine && settings.statusLine.command) {
+      registerStatuslineProvider('_previous', settings.statusLine.command, true);
+    }
+    // Set composite as the statusLine
+    settings.statusLine = { type: 'command', command: compositeCommand() };
+    settingsChanged = true;
+    manifest.config.statusLine = true;
+  }
+
+  // Register code-graph provider
+  registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
+
+  // 2. enabledPlugins — add if missing
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  if (!(PLUGIN_ID in settings.enabledPlugins)) {
+    settings.enabledPlugins[PLUGIN_ID] = true;
+    settingsChanged = true;
+    manifest.config.enabledPlugins = true;
+  }
+
+  // 3. Write settings atomically if changed
+  if (settingsChanged) {
+    writeJsonAtomic(SETTINGS_PATH, settings);
+  }
+
+  // 4. Write manifest with version
+  manifest.version = version;
+  manifest.installedAt = manifest.installedAt || new Date().toISOString();
+  manifest.updatedAt = new Date().toISOString();
+  writeManifest(manifest);
+
+  return { version, settingsChanged, statusLineClaimed: manifest.config.statusLine };
+}
+
+// --- Uninstall (clean all config) ---
+
+function uninstall() {
+  const settings = readJson(SETTINGS_PATH);
+  let settingsChanged = false;
+
+  if (settings) {
+    // 1. StatusLine: remove code-graph from registry
+    unregisterStatuslineProvider('code-graph');
+    const remaining = readRegistry();
+
+    if (isOurComposite(settings)) {
+      if (remaining.length === 1 && remaining[0].id === '_previous') {
+        // Only the previous provider remains — restore it directly
+        settings.statusLine = { type: 'command', command: remaining[0].command };
+        unregisterStatuslineProvider('_previous');
+        settingsChanged = true;
+      } else if (remaining.length === 0) {
+        // No providers left — remove statusLine entirely
+        delete settings.statusLine;
+        settingsChanged = true;
+      }
+      // else: other providers still using composite — leave it
+    }
+
+    // 2. Remove from enabledPlugins
+    if (settings.enabledPlugins && PLUGIN_ID in settings.enabledPlugins) {
+      delete settings.enabledPlugins[PLUGIN_ID];
+      settingsChanged = true;
+    }
+
+    // 3. Write settings if changed
+    if (settingsChanged) {
+      writeJsonAtomic(SETTINGS_PATH, settings);
+    }
+  }
+
+  // 4. Remove from installed_plugins.json
+  const installedPlugins = readJson(INSTALLED_PLUGINS_PATH);
+  if (installedPlugins && installedPlugins.plugins && PLUGIN_ID in installedPlugins.plugins) {
+    delete installedPlugins.plugins[PLUGIN_ID];
+    writeJsonAtomic(INSTALLED_PLUGINS_PATH, installedPlugins);
+  }
+
+  // 5. Remove cache directory
+  try { fs.rmSync(CACHE_DIR, { recursive: true, force: true }); } catch { /* ok */ }
+
+  // 6. Remove plugin files from cache
+  const pluginCacheDir = path.join(os.homedir(), '.claude', 'plugins', 'cache', 'sdsrss', 'code-graph');
+  try { fs.rmSync(pluginCacheDir, { recursive: true, force: true }); } catch { /* ok */ }
+
+  return { settingsChanged };
+}
+
+// --- Update (refresh config points) ---
+
+function update() {
+  const version = getPluginVersion();
+  const manifest = readManifest();
+  const oldVersion = manifest.version;
+  const settings = readJson(SETTINGS_PATH) || {};
+  let settingsChanged = false;
+
+  // 1. Update composite command path if version changed
+  if (isOurComposite(settings)) {
+    const cmd = compositeCommand();
+    if (settings.statusLine.command !== cmd) {
+      settings.statusLine.command = cmd;
+      settingsChanged = true;
+    }
+  }
+
+  // 2. Update code-graph provider in registry
+  registerStatuslineProvider('code-graph', codeGraphStatuslineCommand(), false);
+
+  // 3. Ensure enabledPlugins entry exists
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  if (!(PLUGIN_ID in settings.enabledPlugins)) {
+    settings.enabledPlugins[PLUGIN_ID] = true;
+    settingsChanged = true;
+  }
+
+  // 4. Write settings if changed
+  if (settingsChanged) {
+    writeJsonAtomic(SETTINGS_PATH, settings);
+  }
+
+  // 5. Clear update-check cache (force re-check after update)
+  const updateCache = path.join(CACHE_DIR, 'update-check');
+  try { fs.unlinkSync(updateCache); } catch { /* ok */ }
+
+  // 6. Update manifest
+  manifest.version = version;
+  manifest.updatedAt = new Date().toISOString();
+  writeManifest(manifest);
+
+  return { oldVersion, version, settingsChanged };
+}
+
+module.exports = {
+  install, uninstall, update,
+  readManifest, readJson, writeJsonAtomic,
+  readRegistry, writeRegistry,
+  getPluginVersion,
+  PLUGIN_ID, CACHE_DIR, REGISTRY_FILE,
+};
+
+// CLI: node lifecycle.js <install|uninstall|update>
+if (require.main === module) {
+  const cmd = process.argv[2];
+  if (cmd === 'install') {
+    const r = install();
+    console.log(`Installed v${r.version} | settings=${r.settingsChanged} | statusLine=${r.statusLineClaimed}`);
+  } else if (cmd === 'uninstall') {
+    const r = uninstall();
+    console.log(`Uninstalled | settings cleaned=${r.settingsChanged}`);
+  } else if (cmd === 'update') {
+    const r = update();
+    console.log(`Updated ${r.oldVersion} → ${r.version} | settings=${r.settingsChanged}`);
+  } else {
+    console.error('Usage: lifecycle.js <install|uninstall|update>');
+    process.exit(1);
+  }
+}

package/claude-plugin/scripts/session-init.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+'use strict';
+const { execFileSync } = require('child_process');
+const { findBinary } = require('./find-binary');
+const { install, update, readManifest, getPluginVersion } = require('./lifecycle');
+const { checkForUpdate } = require('./auto-update');
+
+const BIN = findBinary();
+
+// --- 1. Health check (always runs) ---
+if (BIN) {
+  try {
+    const out = execFileSync(BIN, ['health-check', '--format', 'oneline'], {
+      timeout: 2000,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).toString().trim();
+    if (out) process.stdout.write(out);
+  } catch { /* timeout — silent */ }
+}
+
+// --- 2. Lifecycle: install or update config (idempotent) ---
+const manifest = readManifest();
+const currentVersion = getPluginVersion();
+
+if (!manifest.version) {
+  install();
+} else if (manifest.version !== currentVersion) {
+  update();
+}
+
+// --- 3. Auto-update (throttled, non-blocking) ---
+(async () => {
+  const result = await checkForUpdate();
+  if (result && result.updated) {
+    process.stderr.write(`[code-graph] Updated: v${result.from} \u2192 v${result.to}\n`);
+  } else if (result && result.updateAvailable) {
+    process.stderr.write(
+      `[code-graph] Update available: v${result.from} \u2192 v${result.to}. ` +
+      `Run: npx @sdsrs/code-graph@latest\n`
+    );
+  }
+})();

package/claude-plugin/scripts/statusline-composite.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Composite StatusLine — combines multiple statusline providers.
+ * Reads stdin (JSON context from Claude Code), pipes to the primary
+ * statusline (GSD), then appends code-graph status.
+ */
+const { execFileSync } = require('child_process');
+const path = require('path');
+const { readRegistry } = require('./lifecycle');
+
+const SEPARATOR = ' \x1b[2m|\x1b[0m ';
+
+// Collect stdin (Claude Code pipes JSON context)
+let stdinData = '';
+let ran = false;
+const stdinTimeout = setTimeout(() => { if (!ran) { ran = true; run(''); } }, 2000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { stdinData += chunk; });
+process.stdin.on('end', () => { clearTimeout(stdinTimeout); if (!ran) { ran = true; run(stdinData); } });
+
+function run(stdin) {
+  const registry = readRegistry();
+  if (registry.length === 0) {
+    // Fallback: no registry, run code-graph only
+    const cg = runProvider(codeGraphCommand(), false, stdin);
+    if (cg) process.stdout.write(cg);
+    return;
+  }
+
+  const outputs = [];
+  for (const provider of registry) {
+    const out = runProvider(provider.command, provider.needsStdin, stdin);
+    if (out) outputs.push(out);
+  }
+  if (outputs.length > 0) {
+    process.stdout.write(outputs.join(SEPARATOR));
+  }
+}
+
+function runProvider(command, needsStdin, stdin) {
+  if (!command) return null;
+  try {
+    // Parse command into executable + args
+    const parts = parseCommand(command);
+    if (!parts) return null;
+
+    const out = execFileSync(parts[0], parts.slice(1), {
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      input: needsStdin ? stdin : '',
+    }).toString().trim();
+
+    return out || null;
+  } catch { return null; }
+}
+
+function parseCommand(cmd) {
+  // Handle: node "/path/to/script.js"
+  const match = cmd.match(/^(\S+)\s+"([^"]+)"(.*)$/);
+  if (match) {
+    const args = [match[2]];
+    if (match[3].trim()) args.push(...match[3].trim().split(/\s+/));
+    return [match[1], ...args];
+  }
+  // Handle: node /path/to/script.js
+  const parts = cmd.split(/\s+/);
+  return parts.length > 0 ? parts : null;
+}
+
+function codeGraphCommand() {
+  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || path.resolve(__dirname, '..');
+  return `node "${path.join(pluginRoot, 'scripts', 'statusline.js')}"`;
+}
+
+module.exports = { run };

package/claude-plugin/scripts/statusline.js

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
-const { execSync } = require('child_process');
+'use strict';
+const { execFileSync } = require('child_process');
+const { findBinary } = require('./find-binary');
+
+const bin = findBinary();
+if (!bin) {
+  process.stdout.write('code-graph: offline');
+  process.exit(0);
+}
+
 try {
-  const out = execSync('code-graph-mcp health-check --format json', {
+  const out = execFileSync(bin, ['health-check', '--format', 'json'], {
     timeout: 3000,
     stdio: ['pipe', 'pipe', 'pipe']
   }).toString().trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/code-graph",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "MCP server that indexes codebases into an AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing",
   "license": "MIT",
   "repository": {
@@ -33,10 +33,10 @@
     "node": ">=16"
   },
   "optionalDependencies": {
-    "@sdsrs/code-graph-linux-x64": "0.4.0",
-    "@sdsrs/code-graph-linux-arm64": "0.4.0",
-    "@sdsrs/code-graph-darwin-x64": "0.4.0",
-    "@sdsrs/code-graph-darwin-arm64": "0.4.0",
-    "@sdsrs/code-graph-win32-x64": "0.4.0"
+    "@sdsrs/code-graph-linux-x64": "0.4.3",
+    "@sdsrs/code-graph-linux-arm64": "0.4.3",
+    "@sdsrs/code-graph-darwin-x64": "0.4.3",
+    "@sdsrs/code-graph-darwin-arm64": "0.4.3",
+    "@sdsrs/code-graph-win32-x64": "0.4.3"
   }
 }