composto-ai 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,4 +1,73 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/memory/git.ts
+var git_exports = {};
+__export(git_exports, {
+  countCommits: () => countCommits,
+  isAncestor: () => isAncestor,
+  isShallowRepo: () => isShallowRepo,
+  logRange: () => logRange,
+  resolveSinceBoundary: () => resolveSinceBoundary,
+  revListCount: () => revListCount,
+  revParseHead: () => revParseHead
+});
+import { execSync as execSync2 } from "child_process";
+function run(cwd, cmd, timeoutMs = 1e4) {
+  return execSync2(cmd, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+}
+function revParseHead(cwd) {
+  return run(cwd, "git rev-parse HEAD");
+}
+function isShallowRepo(cwd) {
+  return run(cwd, "git rev-parse --is-shallow-repository") === "true";
+}
+function revListCount(cwd, from, to) {
+  if (from === to) return 0;
+  const out = run(cwd, `git rev-list --count ${from}..${to}`);
+  return parseInt(out, 10);
+}
+function isAncestor(cwd, ancestor, descendant) {
+  try {
+    execSync2(`git merge-base --is-ancestor ${ancestor} ${descendant}`, {
+      cwd,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function countCommits(cwd) {
+  const out = run(cwd, "git rev-list --count HEAD");
+  return parseInt(out, 10);
+}
+function resolveSinceBoundary(cwd, since) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(since)) {
+    throw new Error(`--since must be YYYY-MM-DD (got "${since}")`);
+  }
+  const out = run(cwd, `git rev-list -n 1 --before='${since}T23:59:59' HEAD`);
+  return out || null;
+}
+function logRange(cwd, from, to, timeoutMs = 6e4) {
+  const range = from ? `${from}..${to}` : to;
+  const fmt = "--format=%x1e%H%x00%P%x00%an%x00%at%x00%s%x00%b%x1f";
+  const cmd = `git log ${fmt} --numstat --no-renames ${range}`;
+  return execSync2(cmd, { cwd, encoding: "utf-8", timeout: timeoutMs, maxBuffer: 256 * 1024 * 1024 });
+}
+var init_git = __esm({
+  "src/memory/git.ts"() {
+    "use strict";
+  }
+});
 
 // src/cli/commands.ts
 import { readFileSync as readFileSync4 } from "fs";
@@ -1717,7 +1786,25 @@ function openDatabase(path) {
 }
 
 // src/memory/schema.ts
-var CURRENT_VERSION = 1;
+var CURRENT_VERSION = 3;
+var V2_SQL = `
+CREATE INDEX IF NOT EXISTS idx_ft_file_commit ON file_touches(file_path, commit_sha);
+`;
+var V3_SQL = `
+CREATE TABLE IF NOT EXISTS hook_invocations (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp       INTEGER NOT NULL,
+  platform        TEXT NOT NULL,
+  event           TEXT NOT NULL,
+  file_path       TEXT,
+  verdict         TEXT,
+  score           REAL,
+  confidence      REAL,
+  latency_ms      INTEGER NOT NULL,
+  cache_hit       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_hi_timestamp ON hook_invocations(timestamp);
+`;
 var V1_SQL = `
 CREATE TABLE IF NOT EXISTS index_state (
   key   TEXT PRIMARY KEY,
@@ -1805,7 +1892,9 @@ function runMigrations(db) {
   if (current >= CURRENT_VERSION) return;
   db.exec("BEGIN");
   try {
-    db.exec(V1_SQL);
+    if (current < 1) db.exec(V1_SQL);
+    if (current < 2) db.exec(V2_SQL);
+    if (current < 3) db.exec(V3_SQL);
     db.pragma(`user_version = ${CURRENT_VERSION}`);
     db.exec("COMMIT");
   } catch (err) {
@@ -1814,39 +1903,8 @@ function runMigrations(db) {
   }
 }
 
-// src/memory/git.ts
-import { execSync as execSync2 } from "child_process";
-function run(cwd, cmd, timeoutMs = 1e4) {
-  return execSync2(cmd, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
-}
-function revParseHead(cwd) {
-  return run(cwd, "git rev-parse HEAD");
-}
-function isShallowRepo(cwd) {
-  return run(cwd, "git rev-parse --is-shallow-repository") === "true";
-}
-function revListCount(cwd, from, to) {
-  if (from === to) return 0;
-  const out = run(cwd, `git rev-list --count ${from}..${to}`);
-  return parseInt(out, 10);
-}
-function isAncestor(cwd, ancestor, descendant) {
-  try {
-    execSync2(`git merge-base --is-ancestor ${ancestor} ${descendant}`, {
-      cwd,
-      stdio: "ignore"
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-function countCommits(cwd) {
-  const out = run(cwd, "git rev-list --count HEAD");
-  return parseInt(out, 10);
-}
-
 // src/memory/freshness.ts
+init_git();
 function ensureFresh(db, repoPath) {
   const head = revParseHead(repoPath);
   const row = db.prepare("SELECT value FROM index_state WHERE key = 'last_indexed_sha'").get();
@@ -1947,13 +2005,19 @@ function computeRevertMatch(db, filePath) {
   };
 }
 
+// src/memory/signals/db-clock.ts
+function getDbMaxTimestamp(db) {
+  const row = db.prepare("SELECT MAX(timestamp) AS ts FROM commits").get();
+  return row?.ts ?? null;
+}
+
 // src/memory/signals/hotspot.ts
 var WINDOW_SECONDS = 90 * 86400;
 var SATURATION_TOUCHES = 30;
 var FALLBACK_PRECISION2 = 0.3;
 function computeHotspot(db, filePath) {
-  const now = Math.floor(Date.now() / 1e3);
-  const lowerBound = now - WINDOW_SECONDS;
+  const anchor = getDbMaxTimestamp(db) ?? Math.floor(Date.now() / 1e3);
+  const lowerBound = anchor - WINDOW_SECONDS;
   const row = db.prepare(`
       SELECT COUNT(*) AS n
       FROM file_touches ft
@@ -2011,38 +2075,12 @@ function computeFixRatio(db, filePath) {
   };
 }
 
-// src/memory/signals/coverage-decline.ts
-var FALLBACK_PRECISION4 = 0.3;
-function computeCoverageDecline(db, repoPath, filePath) {
-  const cal = getCalibration(db, "coverage_decline", FALLBACK_PRECISION4);
-  let strength = 0;
-  try {
-    const entries = getGitLog(repoPath, 200);
-    const trends = {
-      hotspots: detectHotspots(entries, { threshold: 10, fixRatioThreshold: 0.5 }),
-      decaySignals: detectDecay(entries),
-      inconsistencies: detectInconsistencies(entries)
-    };
-    const health = computeHealthFromTrends(filePath, trends);
-    if (health.coverageTrend === "down") strength = 1;
-  } catch {
-    strength = 0;
-  }
-  return {
-    type: "coverage_decline",
-    strength,
-    precision: cal.precision,
-    sample_size: cal.sampleSize,
-    evidence: []
-  };
-}
-
 // src/memory/signals/author-churn.ts
 var WINDOW_SECONDS2 = 90 * 86400;
 var INACTIVE_THRESHOLD = 5;
-var FALLBACK_PRECISION5 = 0.3;
+var FALLBACK_PRECISION4 = 0.3;
 function computeAuthorChurn(db, filePath) {
-  const cal = getCalibration(db, "author_churn", FALLBACK_PRECISION5);
+  const cal = getCalibration(db, "author_churn", FALLBACK_PRECISION4);
   const base = {
     type: "author_churn",
     precision: cal.precision,
@@ -2058,8 +2096,8 @@ function computeAuthorChurn(db, filePath) {
       LIMIT 1
     `).get(filePath);
   if (!lastTouch) return { ...base, strength: 0 };
-  const now = Math.floor(Date.now() / 1e3);
-  const lowerBound = now - WINDOW_SECONDS2;
+  const anchor = getDbMaxTimestamp(db) ?? Math.floor(Date.now() / 1e3);
+  const lowerBound = anchor - WINDOW_SECONDS2;
   const activity = db.prepare(`SELECT COUNT(*) AS n FROM commits WHERE author = ? AND timestamp >= ?`).get(lastTouch.author, lowerBound);
   let strength = 0;
   if (activity.n === 0) strength = 1;
@@ -2068,12 +2106,11 @@ function computeAuthorChurn(db, filePath) {
 }
 
 // src/memory/signals/index.ts
-function collectSignals(db, repoPath, filePath) {
+function collectSignals(db, _repoPath, filePath) {
   return [
     computeRevertMatch(db, filePath),
     computeHotspot(db, filePath),
     computeFixRatio(db, filePath),
-    computeCoverageDecline(db, repoPath, filePath),
     computeAuthorChurn(db, filePath)
   ];
 }
@@ -2236,6 +2273,9 @@ var WorkerPool = class {
   }
 };
 
+// src/memory/api.ts
+init_git();
+
 // src/memory/detectors.ts
 function detectSquashed(db) {
   const row = db.prepare(`
@@ -2404,6 +2444,24 @@ var MemoryAPI = class {
     });
     return this.bootstrapPromise;
   }
+  // bootstrapFromBoundary indexes only commits between fromSha and HEAD.
+  // Used by `composto index --since=YYYY-MM-DD` to bound work on huge repos.
+  // Pass fromSha=null to index the full history (same as bootstrapIfNeeded).
+  async bootstrapFromBoundary(fromSha) {
+    if (this.bootstrapPromise) return this.bootstrapPromise;
+    const head = revParseHead(this.repoPath);
+    const range = { from: fromSha, to: head };
+    this.bootstrapPromise = this.pool.runIngest({ dbPath: this.dbPath, repoPath: this.repoPath, range }).then(() => {
+      this.log.info("bootstrap_done", { through: range.to, from: range.from });
+    }).catch((err) => {
+      this.log.error("bootstrap_failed", { message: err.message });
+      this.failures.recordFailure("ingest_failure");
+      throw err;
+    }).finally(() => {
+      this.bootstrapPromise = null;
+    });
+    return this.bootstrapPromise;
+  }
   async blastradius(input) {
     const start = Date.now();
     if (this.failures.isDisabled()) {
@@ -2567,7 +2625,7 @@ function statFileSize(path) {
 function runScan(projectPath) {
   const adapter = new CLIAdapter();
   const config = loadConfig(projectPath);
-  console.log("composto v0.4.0 \u2014 scanning...\n");
+  console.log("composto v0.4.2 \u2014 scanning...\n");
   const files = collectFiles(projectPath, [".ts", ".tsx", ".js", ".jsx"]);
   console.log(`  Found ${files.length} files
 `);
@@ -2594,7 +2652,7 @@ function runScan(projectPath) {
 function runTrends(projectPath) {
   const adapter = new CLIAdapter();
   const config = loadConfig(projectPath);
-  console.log("composto v0.4.0 \u2014 trend analysis...\n");
+  console.log("composto v0.4.2 \u2014 trend analysis...\n");
   const entries = getGitLog(projectPath, 100);
   if (entries.length === 0) {
     console.log("  No git history found.\n");
@@ -2636,7 +2694,7 @@ async function runIR(projectPath, filePath, layer) {
 }
 var ALL_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".py", ".go", ".rs"];
 async function runBenchmark(projectPath) {
-  console.log("composto v0.4.0 \u2014 benchmark\n");
+  console.log("composto v0.4.2 \u2014 benchmark\n");
   const files = collectFiles(projectPath, ALL_EXTENSIONS);
   console.log(`  ${files.length} files
 `);
@@ -2683,7 +2741,7 @@ async function runBenchmarkQuality(projectPath, filePath) {
   }
   const code = readFileSync4(filePath, "utf-8");
   const relPath = relative2(projectPath, filePath);
-  console.log("composto v0.4.0 \u2014 quality benchmark\n");
+  console.log("composto v0.4.2 \u2014 quality benchmark\n");
   console.log(`  File: ${relPath}
 `);
   console.log("  Sending to Claude Haiku...\n");
@@ -2713,8 +2771,8 @@ ${result.ir.response}
   }
 }
 async function runContext(projectPath, budget, target) {
-  const header = target ? `composto v0.4.0 \u2014 context (target: ${target}, budget: ${budget} tokens)
-` : `composto v0.4.0 \u2014 context (budget: ${budget} tokens)
+  const header = target ? `composto v0.4.2 \u2014 context (target: ${target}, budget: ${budget} tokens)
+` : `composto v0.4.2 \u2014 context (budget: ${budget} tokens)
 `;
   console.log(header);
   const files = collectFiles(projectPath, ALL_EXTENSIONS);
@@ -2812,18 +2870,60 @@ async function runImpact(projectPath, file, opts = {}) {
     await api.close();
   }
 }
-async function runIndex(projectPath) {
+async function runIndex(projectPath, options = {}) {
+  const { resolveSinceBoundary: resolveSinceBoundary2 } = await Promise.resolve().then(() => (init_git(), git_exports));
   const dbPath = join6(projectPath, ".composto", "memory.db");
   const api = new MemoryAPI({ dbPath, repoPath: projectPath });
+  const Database2 = (await import("better-sqlite3")).default;
+  const probeDb = new Database2(dbPath, { readonly: true, fileMustExist: false });
+  const start = Date.now();
+  let stopProgress = () => {
+  };
   try {
-    console.log("composto: bootstrapping memory index...");
-    const start = Date.now();
-    await api.bootstrapIfNeeded();
-    console.log(`composto: index ready (${Date.now() - start} ms)`);
+    if (options.since) {
+      const fromSha = resolveSinceBoundary2(projectPath, options.since);
+      console.log(`composto: indexing commits since ${options.since}${fromSha ? ` (boundary ${fromSha.slice(0, 8)})` : " (whole history \u2014 date predates first commit)"}...`);
+      stopProgress = startProgressPoller(probeDb, start);
+      await api.bootstrapFromBoundary(fromSha);
+    } else {
+      console.log("composto: bootstrapping memory index...");
+      stopProgress = startProgressPoller(probeDb, start);
+      await api.bootstrapIfNeeded();
+    }
+    stopProgress();
+    const total = readIndexedTotal(probeDb);
+    const elapsed = Date.now() - start;
+    const rate = total > 0 && elapsed > 0 ? Math.round(total * 1e3 / elapsed) : 0;
+    console.log(`composto: index ready \u2014 ${total.toLocaleString()} commits in ${(elapsed / 1e3).toFixed(1)}s (${rate.toLocaleString()} commits/sec)`);
   } finally {
+    stopProgress();
+    probeDb.close();
     await api.close();
   }
 }
+function readIndexedTotal(db) {
+  try {
+    const row = db.prepare("SELECT value FROM index_state WHERE key = 'indexed_commits_total'").get();
+    return row ? parseInt(row.value, 10) : 0;
+  } catch {
+    return 0;
+  }
+}
+function startProgressPoller(db, start) {
+  let last = -1;
+  const interval = setInterval(() => {
+    const total = readIndexedTotal(db);
+    if (total === last) return;
+    last = total;
+    const elapsed = Date.now() - start;
+    const rate = total > 0 && elapsed > 0 ? Math.round(total * 1e3 / elapsed) : 0;
+    process.stdout.write(`  indexed ${total.toLocaleString()} commits (${rate.toLocaleString()}/sec) [${(elapsed / 1e3).toFixed(1)}s]\r`);
+  }, 1500);
+  return () => {
+    clearInterval(interval);
+    process.stdout.write("\n");
+  };
+}
 async function runIndexStatus(projectPath) {
   const dbPath = join6(projectPath, ".composto", "memory.db");
   const s = collectStatus(dbPath);
@@ -2852,8 +2952,633 @@ async function runIndexStatus(projectPath) {
   console.log(`  Integrity check:          ${s.integrityOk ? "OK" : "FAIL"}`);
 }
 
+// src/cli/init.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname5, join as join7 } from "path";
+var CURSOR_RULES_MDC = `---
+description: Composto MCP usage \u2014 tells the agent when to prefer composto_blastradius / composto_context / composto_ir / composto_scan over built-in file tools.
+alwaysApply: true
+---
+
+# Composto MCP \u2014 when to use
+
+This project has the \`composto\` MCP server registered. Prefer Composto tools over Cursor's built-in tools in the situations below.
+
+## Before editing any existing file under \`src/\`, \`lib/\`, or \`app/\`
+
+Call \`composto_blastradius\` with the target file path **first**, before proposing any edit.
+
+- If \`verdict\` is \`high\`: surface the risk to the user before changing the file. Mention the strongest signal (e.g. "this file was reverted the last time it was touched", "high fix-ratio in recent history").
+- If \`verdict\` is \`medium\`: note it briefly and proceed.
+- If \`verdict\` is \`low\` or \`unknown\`: proceed without comment.
+
+Skip this on test files, generated code, lockfiles, and anything in \`node_modules/\` or \`dist/\`.
+
+## When the user says "fix this bug in X", "why does X return wrong value", or "trace X"
+
+Call \`composto_context\` with \`target: "<symbol-or-file>"\` and \`budget: 4000\` instead of opening 5 files individually. The target file comes back as raw code; surrounding files come back as compressed IR. One round-trip, full picture.
+
+## When you only need to know what a file does (not its exact code)
+
+Call \`composto_ir\` with \`layer: "L1"\` instead of \`read_file\`. ~89% fewer tokens, same understanding. Use \`read_file\` only when you need exact strings, regexes, or formatting.
+
+## Before staging commits / when reviewing diffs
+
+Call \`composto_scan\` on the changed paths to catch hardcoded secrets, debug artifacts, and stray \`console.log\` calls before the user commits.
+
+## Don't
+
+- Don't call \`composto_benchmark\` unless the user explicitly asks about token savings.
+- Don't run \`composto_blastradius\` on every read \u2014 only before edits.
+- Don't compress a file the user explicitly asked to see in full.
+`;
+function ensureDir(filePath) {
+  mkdirSync4(dirname5(filePath), { recursive: true });
+}
+function writeJsonMerged(filePath, patch, result, relPath) {
+  ensureDir(filePath);
+  if (existsSync4(filePath)) {
+    const existing = JSON.parse(readFileSync5(filePath, "utf-8"));
+    const mergedServers = {
+      ...existing.mcpServers ?? {},
+      ...patch.mcpServers ?? {}
+    };
+    const merged = { ...existing, ...patch, mcpServers: mergedServers };
+    writeFileSync2(filePath, JSON.stringify(merged, null, 2) + "\n");
+    result.merged.push(relPath);
+  } else {
+    writeFileSync2(filePath, JSON.stringify(patch, null, 2) + "\n");
+    result.written.push(relPath);
+  }
+}
+function writeFileSkipIfExists(filePath, content, result, relPath) {
+  ensureDir(filePath);
+  if (existsSync4(filePath)) {
+    result.skipped.push(relPath);
+    return;
+  }
+  writeFileSync2(filePath, content);
+  result.written.push(relPath);
+}
+function mergeHookArray(existingHooks, newEntry, dedupKey) {
+  const arr = Array.isArray(existingHooks) ? [...existingHooks] : [];
+  const key = dedupKey(newEntry);
+  if (arr.some((e) => dedupKey(e) === key)) return arr;
+  arr.push(newEntry);
+  return arr;
+}
+function readJsonIfExists(filePath) {
+  if (!existsSync4(filePath)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync5(filePath, "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function writeCursorHooks(projectPath, result) {
+  const hooksPath = join7(projectPath, ".cursor", "hooks.json");
+  const relPath = ".cursor/hooks.json";
+  const existed = existsSync4(hooksPath);
+  const existing = readJsonIfExists(hooksPath);
+  const existingHooks = existing.hooks ?? {};
+  const compostoEntry = {
+    matcher: "Edit|Write",
+    command: "composto hook cursor pretooluse"
+  };
+  const preToolUse = mergeHookArray(
+    existingHooks.preToolUse,
+    compostoEntry,
+    (e) => e?.command ?? ""
+  );
+  const merged = {
+    ...existing,
+    version: existing.version ?? 1,
+    hooks: { ...existingHooks, preToolUse }
+  };
+  ensureDir(hooksPath);
+  writeFileSync2(hooksPath, JSON.stringify(merged, null, 2) + "\n");
+  if (existed) result.merged.push(relPath);
+  else result.written.push(relPath);
+}
+function initCursor(projectPath, result) {
+  writeJsonMerged(
+    join7(projectPath, ".cursor", "mcp.json"),
+    { mcpServers: { composto: { command: "composto-mcp" } } },
+    result,
+    ".cursor/mcp.json"
+  );
+  writeFileSkipIfExists(
+    join7(projectPath, ".cursor", "rules", "composto.mdc"),
+    CURSOR_RULES_MDC,
+    result,
+    ".cursor/rules/composto.mdc"
+  );
+  writeCursorHooks(projectPath, result);
+}
+function initClaudeCode(projectPath, result) {
+  const settingsPath = join7(projectPath, ".claude", "settings.json");
+  const relPath = ".claude/settings.json";
+  const existed = existsSync4(settingsPath);
+  const existing = readJsonIfExists(settingsPath);
+  const mcpServers = {
+    ...existing.mcpServers ?? {},
+    composto: { command: "composto-mcp" }
+  };
+  const compostoHookEntry = {
+    matcher: "Edit|Write|MultiEdit",
+    hooks: [
+      { type: "command", command: "composto hook claude-code pretooluse" }
+    ]
+  };
+  const existingHooks = existing.hooks ?? {};
+  const preToolUse = mergeHookArray(
+    existingHooks.PreToolUse,
+    compostoHookEntry,
+    (e) => e?.hooks?.[0]?.command ?? ""
+  );
+  const merged = {
+    ...existing,
+    mcpServers,
+    hooks: { ...existingHooks, PreToolUse: preToolUse }
+  };
+  ensureDir(settingsPath);
+  writeFileSync2(settingsPath, JSON.stringify(merged, null, 2) + "\n");
+  if (existed) result.merged.push(relPath);
+  else result.written.push(relPath);
+}
+function initGeminiCli(_projectPath, result, options) {
+  const settingsPath = options.geminiSettingsPath ?? join7(homedir(), ".gemini", "settings.json");
+  const relPath = settingsPath;
+  try {
+    const existed = existsSync4(settingsPath);
+    const existing = readJsonIfExists(settingsPath);
+    const mcpServers = {
+      ...existing.mcpServers ?? {},
+      composto: { command: "composto-mcp" }
+    };
+    const compostoHookEntry = {
+      matcher: "edit_file|write_file|replace",
+      hooks: [
+        { type: "command", command: "composto hook gemini-cli beforetool" }
+      ]
+    };
+    const existingHooks = existing.hooks ?? {};
+    const beforeTool = mergeHookArray(
+      existingHooks.BeforeTool,
+      compostoHookEntry,
+      (e) => e?.hooks?.[0]?.command ?? ""
+    );
+    const merged = {
+      ...existing,
+      mcpServers,
+      hooks: { ...existingHooks, BeforeTool: beforeTool }
+    };
+    ensureDir(settingsPath);
+    writeFileSync2(settingsPath, JSON.stringify(merged, null, 2) + "\n");
+    if (existed) result.merged.push(relPath);
+    else result.written.push(relPath);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    result.skipped.push(`${settingsPath} (write failed: ${reason})`);
+  }
+}
+function runInit(projectPath, options) {
+  const client = options.client ?? "cursor";
+  const result = { client, written: [], skipped: [], merged: [] };
+  if (client === "claude-code") initClaudeCode(projectPath, result);
+  else if (client === "gemini-cli") initGeminiCli(projectPath, result, options);
+  else initCursor(projectPath, result);
+  return result;
+}
+
+// src/cli/hook/api-deps.ts
+var defaultDeps = {
+  makeApi(opts) {
+    return new MemoryAPI(opts);
+  }
+};
+
+// src/cli/hook/extract.ts
+var FILE_TOOLS = {
+  Edit: ["file_path"],
+  Write: ["file_path"],
+  MultiEdit: ["file_path"],
+  edit_file: ["path", "file_path"],
+  write_file: ["path", "file_path"],
+  replace: ["path", "file_path"]
+};
+function extractFilePath(inv) {
+  const name = inv.tool_name;
+  if (typeof name !== "string") return null;
+  const candidates = FILE_TOOLS[name];
+  if (!candidates) return null;
+  const input = inv.tool_input;
+  if (!input || typeof input !== "object") return null;
+  for (const field of candidates) {
+    const v = input[field];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return null;
+}
+
+// src/cli/hook/format.ts
+function formatBlastRadiusContext(filePath, res, opts = {}) {
+  const firing = res.signals.filter((s) => s.strength > 0).map((s) => `${s.type}=${s.strength.toFixed(2)}`).join(", ");
+  const hint = opts.hint ?? "this file's bug history may be relevant to your edit. See composto_blastradius for detail.";
+  return [
+    `<composto_blastradius>`,
+    `  file: ${filePath}`,
+    `  verdict: ${res.verdict}`,
+    `  score: ${res.score.toFixed(2)} confidence: ${res.confidence.toFixed(2)}`,
+    firing ? `  firing_signals: ${firing}` : `  firing_signals: (none)`,
+    `  hint: ${hint}`,
+    `</composto_blastradius>`
+  ].join("\n");
+}
+
+// src/cli/hook/adapters/claude-code.ts
+import { join as join8 } from "path";
+var EMPTY_META = {
+  filePath: null,
+  verdict: null,
+  score: null,
+  confidence: null
+};
+function passthrough(filePath = null) {
+  return {
+    envelope: { hookSpecificOutput: {} },
+    metadata: { ...EMPTY_META, filePath }
+  };
+}
+async function runClaudeCodeHook(opts, deps = defaultDeps) {
+  let payload;
+  try {
+    payload = JSON.parse(opts.stdin);
+  } catch {
+    return passthrough();
+  }
+  if (typeof payload !== "object" || payload === null) return passthrough();
+  const filePath = extractFilePath(payload);
+  if (!filePath) return passthrough();
+  try {
+    const dbPath = join8(opts.cwd, ".composto", "memory.db");
+    const api = deps.makeApi({ dbPath, repoPath: opts.cwd });
+    try {
+      const res = await api.blastradius({ file: filePath });
+      if (!res || res.verdict === "low") {
+        return {
+          envelope: { hookSpecificOutput: {} },
+          metadata: {
+            filePath,
+            verdict: res ? res.verdict : null,
+            score: res ? res.score : null,
+            confidence: res ? res.confidence : null
+          }
+        };
+      }
+      const body = formatBlastRadiusContext(filePath, res);
+      return {
+        envelope: {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: body
+          }
+        },
+        metadata: {
+          filePath,
+          verdict: res.verdict,
+          score: res.score,
+          confidence: res.confidence
+        }
+      };
+    } finally {
+      await api.close();
+    }
+  } catch {
+    return passthrough(filePath);
+  }
+}
+
+// src/cli/hook/adapters/cursor.ts
+import { join as join9 } from "path";
+var CURSOR_HINT = "this file's bug history suggests high risk \u2014 ask the user to confirm before editing.";
+var EMPTY_META2 = {
+  filePath: null,
+  verdict: null,
+  score: null,
+  confidence: null
+};
+function passthrough2(filePath = null) {
+  return { envelope: {}, metadata: { ...EMPTY_META2, filePath } };
+}
+async function runCursorHook(opts, deps = defaultDeps) {
+  let payload;
+  try {
+    payload = JSON.parse(opts.stdin);
+  } catch {
+    return passthrough2();
+  }
+  if (typeof payload !== "object" || payload === null) return passthrough2();
+  const filePath = extractFilePath(payload);
+  if (!filePath) return passthrough2();
+  try {
+    const dbPath = join9(opts.cwd, ".composto", "memory.db");
+    const api = deps.makeApi({ dbPath, repoPath: opts.cwd });
+    try {
+      const res = await api.blastradius({ file: filePath });
+      if (!res || res.verdict !== "high") {
+        return {
+          envelope: {},
+          metadata: {
+            filePath,
+            verdict: res ? res.verdict : null,
+            score: res ? res.score : null,
+            confidence: res ? res.confidence : null
+          }
+        };
+      }
+      return {
+        envelope: {
+          permissionDecision: "deny",
+          permissionDecisionReason: formatBlastRadiusContext(filePath, res, { hint: CURSOR_HINT })
+        },
+        metadata: {
+          filePath,
+          verdict: res.verdict,
+          score: res.score,
+          confidence: res.confidence
+        }
+      };
+    } finally {
+      await api.close();
+    }
+  } catch {
+    return passthrough2(filePath);
+  }
+}
+
+// src/cli/hook/adapters/gemini-cli.ts
+import { join as join10 } from "path";
+var EMPTY_META3 = {
+  filePath: null,
+  verdict: null,
+  score: null,
+  confidence: null
+};
+function passthrough3(filePath = null) {
+  return {
+    envelope: { hookSpecificOutput: {} },
+    metadata: { ...EMPTY_META3, filePath }
+  };
+}
+async function runGeminiCliHook(opts, deps = defaultDeps) {
+  let payload;
+  try {
+    payload = JSON.parse(opts.stdin);
+  } catch {
+    return passthrough3();
+  }
+  if (typeof payload !== "object" || payload === null) return passthrough3();
+  const filePath = extractFilePath(payload);
+  if (!filePath) return passthrough3();
+  try {
+    const dbPath = join10(opts.cwd, ".composto", "memory.db");
+    const api = deps.makeApi({ dbPath, repoPath: opts.cwd });
+    try {
+      const res = await api.blastradius({ file: filePath });
+      if (!res || res.verdict === "low") {
+        return {
+          envelope: { hookSpecificOutput: {} },
+          metadata: {
+            filePath,
+            verdict: res ? res.verdict : null,
+            score: res ? res.score : null,
+            confidence: res ? res.confidence : null
+          }
+        };
+      }
+      const body = formatBlastRadiusContext(filePath, res);
+      return {
+        envelope: {
+          hookSpecificOutput: {
+            hookEventName: "BeforeTool",
+            additionalContext: body
+          }
+        },
+        metadata: {
+          filePath,
+          verdict: res.verdict,
+          score: res.score,
+          confidence: res.confidence
+        }
+      };
+    } finally {
+      await api.close();
+    }
+  } catch {
+    return passthrough3(filePath);
+  }
+}
+
+// src/cli/hook/dispatcher.ts
+async function runHookDispatch(opts, deps = defaultDeps) {
+  const p = opts.platform;
+  const e = opts.event;
+  const hookOpts = { stdin: opts.stdin, cwd: opts.cwd };
+  switch (p) {
+    case "claude-code":
+      if (e === "pretooluse") return runClaudeCodeHook(hookOpts, deps);
+      throw new Error(`unknown event for claude-code: ${e}`);
+    case "cursor":
+      if (e === "pretooluse") return runCursorHook(hookOpts, deps);
+      throw new Error(`unknown event for cursor: ${e}`);
+    case "gemini-cli":
+      if (e === "beforetool") return runGeminiCliHook(hookOpts, deps);
+      throw new Error(`unknown event for gemini-cli: ${e}`);
+    default: {
+      const _exhaustive = p;
+      throw new Error(`unknown platform: ${_exhaustive}`);
+    }
+  }
+}
+
+// src/cli/stats.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
+import { join as join12 } from "path";
+
+// src/memory/telemetry/hook-invocations.ts
+import { existsSync as existsSync5 } from "fs";
+import { dirname as dirname6, join as join11 } from "path";
+var SEVEN_DAYS_SEC = 7 * 24 * 60 * 60;
+var DISABLE_MARKER_NAME = "telemetry-disabled";
+function dbDirectory(db) {
+  const name = db.name;
+  if (typeof name !== "string" || name.length === 0 || name === ":memory:") {
+    return null;
+  }
+  return dirname6(name);
+}
+function isTelemetryDisabled(db) {
+  const dir = dbDirectory(db);
+  if (!dir) return false;
+  try {
+    return existsSync5(join11(dir, DISABLE_MARKER_NAME));
+  } catch {
+    return false;
+  }
+}
+function recordInvocation(db, record) {
+  try {
+    if (isTelemetryDisabled(db)) return;
+    const stmt = db.prepare(
+      `INSERT INTO hook_invocations
+         (timestamp, platform, event, file_path, verdict, score, confidence, latency_ms, cache_hit)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    );
+    stmt.run(
+      record.timestamp,
+      record.platform,
+      record.event,
+      record.filePath,
+      record.verdict,
+      record.score,
+      record.confidence,
+      record.latencyMs,
+      record.cacheHit ? 1 : 0
+    );
+  } catch {
+  }
+}
+function percentile(sortedAsc, p) {
+  if (sortedAsc.length === 0) return 0;
+  if (sortedAsc.length === 1) return sortedAsc[0];
+  const rank = Math.min(
+    sortedAsc.length - 1,
+    Math.max(0, Math.ceil(p / 100 * sortedAsc.length) - 1)
+  );
+  return sortedAsc[rank];
+}
+function recentSummary(db, opts = {}) {
+  const now = opts.now ?? Math.floor(Date.now() / 1e3);
+  const since = opts.since ?? now - SEVEN_DAYS_SEC;
+  const empty = {
+    windowStart: since,
+    windowEnd: now,
+    total: 0,
+    byVerdict: {},
+    byPlatform: {},
+    latencyP50: 0,
+    latencyP95: 0,
+    cacheHitRate: 0
+  };
+  let rows;
+  try {
+    rows = db.prepare(
+      `SELECT platform, verdict, latency_ms, cache_hit
+         FROM hook_invocations
+         WHERE timestamp >= ? AND timestamp <= ?`
+    ).all(since, now);
+  } catch {
+    return empty;
+  }
+  if (rows.length === 0) return empty;
+  const byVerdict = {};
+  const byPlatform = {};
+  const latencies = [];
+  let cacheHits = 0;
+  for (const r of rows) {
+    const v = r.verdict == null || r.verdict === "" ? "passthrough" : r.verdict;
+    byVerdict[v] = (byVerdict[v] ?? 0) + 1;
+    byPlatform[r.platform] = (byPlatform[r.platform] ?? 0) + 1;
+    latencies.push(r.latency_ms);
+    if (r.cache_hit === 1) cacheHits++;
+  }
+  latencies.sort((a, b) => a - b);
+  return {
+    windowStart: since,
+    windowEnd: now,
+    total: rows.length,
+    byVerdict,
+    byPlatform,
+    latencyP50: percentile(latencies, 50),
+    latencyP95: percentile(latencies, 95),
+    cacheHitRate: rows.length > 0 ? cacheHits / rows.length : 0
+  };
+}
+
+// src/cli/stats.ts
+var DISABLE_NOTICE = "Composto telemetry disabled. Delete .composto/telemetry-disabled to re-enable.";
+function runStats(opts) {
+  const composstoDir = join12(opts.cwd, ".composto");
+  if (opts.disable) {
+    mkdirSync5(composstoDir, { recursive: true });
+    writeFileSync3(join12(composstoDir, "telemetry-disabled"), "");
+    return { action: "disabled", output: DISABLE_NOTICE };
+  }
+  const dbPath = join12(composstoDir, "memory.db");
+  if (!existsSync6(dbPath)) {
+    const msg = "No .composto/memory.db yet \u2014 run `composto index` or trigger a hook first.";
+    if (opts.json) {
+      return {
+        action: "printed",
+        output: JSON.stringify({ total: 0, note: msg }, null, 2)
+      };
+    }
+    return { action: "printed", output: msg };
+  }
+  const db = openDatabase(dbPath);
+  try {
+    runMigrations(db);
+    const summary = recentSummary(db);
+    return {
+      action: "printed",
+      output: opts.json ? JSON.stringify(summary, null, 2) : renderSummary(summary)
+    };
+  } finally {
+    db.close();
+  }
+}
+function pct(n, total) {
+  if (total === 0) return "0%";
+  return `${Math.round(n / total * 100)}%`;
+}
+function renderSummary(s) {
+  const lines = [];
+  lines.push(`hook invocations (last 7d):  ${s.total}`);
+  if (s.total === 0) {
+    lines.push("  no hook firings recorded yet.");
+    return lines.join("\n");
+  }
+  const verdictOrder = ["low", "medium", "high", "unknown", "passthrough"];
+  const verdictKeys = [
+    ...verdictOrder.filter((k) => k in s.byVerdict),
+    ...Object.keys(s.byVerdict).filter((k) => !verdictOrder.includes(k))
+  ];
+  const verdictParts = verdictKeys.map(
+    (k) => `${k} ${pct(s.byVerdict[k], s.total)}`
+  );
+  lines.push(`  by verdict:  ${verdictParts.join(" / ")}`);
+  const platformParts = Object.entries(s.byPlatform).map(([k, v]) => `${k} ${v}`);
+  lines.push(`  by platform: ${platformParts.join(", ")}`);
+  lines.push(`  latency:     p50 ${s.latencyP50}ms, p95 ${s.latencyP95}ms`);
+  lines.push(
+    `  cache:       hit rate ${Math.round(s.cacheHitRate * 100)}% (cache feature deferred \u2014 see Phase 1 plan)`
+  );
+  return lines.join("\n");
+}
+
 // src/index.ts
-import { resolve as resolve2 } from "path";
+import { join as join13, resolve as resolve2 } from "path";
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
 var args = process.argv.slice(2);
 var command = args[0];
 switch (command) {
@@ -2925,15 +3650,85 @@ switch (command) {
     if (args.includes("--status")) {
       await runIndexStatus(resolve2("."));
     } else {
-      await runIndex(resolve2("."));
+      const sinceArg = args.find((a) => a.startsWith("--since="))?.slice("--since=".length);
+      await runIndex(resolve2("."), { since: sinceArg });
     }
     break;
   }
+  case "init": {
+    const valid = ["cursor", "claude-code", "gemini-cli"];
+    const clientArg = args.find((a) => a.startsWith("--client="))?.slice("--client=".length);
+    if (clientArg && !valid.includes(clientArg)) {
+      console.error(`Unknown --client=${clientArg}. Valid: ${valid.join(", ")}`);
+      process.exit(1);
+    }
+    const result = runInit(resolve2("."), { client: clientArg });
+    console.log(`composto init \u2014 configured for ${result.client}
+`);
+    for (const f of result.written) console.log(`  wrote   ${f}`);
+    for (const f of result.merged) console.log(`  merged  ${f}`);
+    for (const f of result.skipped) console.log(`  skipped ${f} (already exists)`);
+    console.log("\nRestart your AI client and check that 'composto' MCP is green.");
+    console.log(
+      "Composto collects local-only hook telemetry to help you monitor agent behavior. Disable with `composto stats --disable` at any time."
+    );
+    break;
+  }
+  case "hook": {
+    const hookStart = Date.now();
+    try {
+      const platform = args[1];
+      const event = args[2];
+      if (!platform || !event) {
+        console.log('{"hookSpecificOutput":{}}');
+        break;
+      }
+      const stdin = await readStdin();
+      const result = await runHookDispatch({
+        platform,
+        event,
+        stdin,
+        cwd: process.cwd()
+      });
+      console.log(JSON.stringify(result.envelope));
+      try {
+        const dbPath = join13(process.cwd(), ".composto", "memory.db");
+        const db = openDatabase(dbPath);
+        try {
+          runMigrations(db);
+          recordInvocation(db, {
+            timestamp: Math.floor(Date.now() / 1e3),
+            platform,
+            event,
+            filePath: result.metadata.filePath,
+            verdict: result.metadata.verdict,
+            score: result.metadata.score,
+            confidence: result.metadata.confidence,
+            latencyMs: Date.now() - hookStart,
+            cacheHit: false
+          });
+        } finally {
+          db.close();
+        }
+      } catch {
+      }
+    } catch {
+      console.log('{"hookSpecificOutput":{}}');
+    }
+    break;
+  }
+  case "stats": {
+    const json = args.includes("--json");
+    const disable = args.includes("--disable");
+    const res = runStats({ cwd: resolve2("."), json, disable });
+    console.log(res.output);
+    break;
+  }
   case "version":
-    console.log("composto v0.4.0");
+    console.log("composto v0.4.2");
     break;
   default:
-    console.log("composto v0.4.0 \u2014 less tokens, more insight\n");
+    console.log("composto v0.4.2 \u2014 less tokens, more insight\n");
     console.log("Commands:");
     console.log("  scan [path]                           Scan codebase for issues");
     console.log("  trends [path]                         Analyze codebase health trends");
@@ -2943,8 +3738,12 @@ switch (command) {
     console.log("  context [path] --budget N             Smart context within token budget");
     console.log("  context [path] --target <symbol>      Target file as raw, surrounding as IR");
     console.log("  impact <file>                         Show historical blast radius for a file");
-    console.log("  index                                 Build or refresh the memory index");
+    console.log("  index [--since=YYYY-MM-DD]            Build or refresh the memory index (--since bounds work for huge repos)");
     console.log("  index --status                        Show memory index diagnostics");
+    console.log("  init [--client=<name>]                Configure Composto MCP + hooks for an AI client");
+    console.log("                                          (clients: cursor, claude-code, gemini-cli)");
+    console.log("  hook <platform> <event>               Run BlastRadius hook (reads tool JSON from stdin)");
+    console.log("  stats [--json] [--disable]            Show hook telemetry (last 7d); --disable opts out");
     console.log("  version                               Show version");
     break;
 }