whygit 0.0.0-stage → 0.1.1

package/src/git.js

@@ -0,0 +1,311 @@
+/** Thin, fast wrappers around the git CLI. No shell, no dependencies. */
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+
+const MAX_BUFFER = 1024 * 1024 * 1024;
+
+export class GitError extends Error {
+  constructor(args, stderr, code) {
+    super('git ' + args.join(' ') + ' failed: ' + String(stderr || '').trim().slice(0, 500));
+    this.name = 'GitError';
+    this.code = code;
+    this.args = args;
+  }
+}
+
+/** Run git and return stdout as utf8. Throws GitError on failure. */
+export function git(args, opts) {
+  const o = opts || {};
+  try {
+    return execFileSync('git', args, {
+      cwd: o.cwd,
+      input: o.input,
+      encoding: 'utf8',
+      maxBuffer: o.maxBuffer || MAX_BUFFER,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: Object.assign({}, process.env, { GIT_PAGER: 'cat', GIT_OPTIONAL_LOCKS: '0' }),
+    });
+  } catch (err) {
+    throw new GitError(args, err.stderr || err.message, err.status);
+  }
+}
+
+/** Run git, returning null instead of throwing. */
+export function tryGit(args, opts) {
+  try {
+    return git(args, opts);
+  } catch {
+    return null;
+  }
+}
+
+export function isRepo(cwd) {
+  return tryGit(['rev-parse', '--is-inside-work-tree'], { cwd }) === 'true\n';
+}
+
+export function repoRoot(cwd) {
+  return git(['rev-parse', '--show-toplevel'], { cwd }).trim();
+}
+
+export function gitDir(cwd) {
+  return path.resolve(cwd, git(['rev-parse', '--git-dir'], { cwd }).trim());
+}
+
+export function headSha(cwd) {
+  return (tryGit(['rev-parse', 'HEAD'], { cwd }) || '').trim() || null;
+}
+
+export function isShallow(cwd) {
+  return String(tryGit(['rev-parse', '--is-shallow-repository'], { cwd }) || '').trim() === 'true';
+}
+
+export function branchName(cwd) {
+  const name = String(tryGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }) || '').trim();
+  return name && name !== 'HEAD' ? name : null;
+}
+
+/** Normalise the origin remote into a browsable https URL, or null. */
+export function remoteWebUrl(cwd) {
+  const raw = (tryGit(['config', '--get', 'remote.origin.url'], { cwd }) || '').trim().replace(/\.git$/, '');
+  if (!raw) return null;
+  if (/^https?:\/\//.test(raw)) return raw.replace(/\/$/, '');
+  if (/^git@[^:]+:/.test(raw)) {
+    const m = raw.match(/^git@([^:]+):(.+)$/);
+    return 'https://' + m[1] + '/' + m[2];
+  }
+  if (/^ssh:\/\//.test(raw)) {
+    const m = raw.match(/^ssh:\/\/(?:git@)?([^/]+)\/(.+)$/);
+    if (m) return 'https://' + m[1] + '/' + m[2];
+  }
+  return null;
+}
+
+export function commitUrl(webUrl, sha) {
+  return webUrl ? webUrl + '/commit/' + sha : null;
+}
+
+export function blameUrl(webUrl, branch, file, line) {
+  if (!webUrl || !branch) return null;
+  const enc = file.split('/').map(encodeURIComponent).join('/');
+  return webUrl + '/blame/' + encodeURIComponent(branch) + '/' + enc + '#L' + line;
+}
+
+/** All tracked files. */
+export function lsFiles(cwd) {
+  const out = tryGit(['ls-files', '-z'], { cwd });
+  if (!out) return [];
+  return out.split('\0').filter(Boolean);
+}
+
+export function revParse(cwd, rev) {
+  const out = tryGit(['rev-parse', '--verify', '--quiet', rev + '^{commit}'], { cwd });
+  return out ? out.trim() : null;
+}
+
+export function mergeBase(cwd, a, b) {
+  const out = tryGit(['merge-base', a, b], { cwd });
+  return out ? out.trim() : null;
+}
+
+export function currentUser(cwd) {
+  return {
+    name: (tryGit(['config', 'user.name'], { cwd }) || '').trim(),
+    email: (tryGit(['config', 'user.email'], { cwd }) || '').trim(),
+  };
+}
+
+export function shortSha(sha) {
+  return String(sha || '').slice(0, 8);
+}
+
+export function diffNameStatus(cwd, base, head) {
+  const out = tryGit(['diff', '--name-status', '-M', base, head], { cwd });
+  const rows = [];
+  for (const line of String(out || '').split('\n')) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    const status = parts[0][0];
+    if (status === 'R' || status === 'C') {
+      rows.push({ status: status, oldPath: parts[1], path: parts[2] });
+    } else {
+      rows.push({ status: status, oldPath: null, path: parts[1] });
+    }
+  }
+  return rows;
+}
+
+export function diffHunks(cwd, base, head) {
+  const out = tryGit(['diff', '--unified=0', '--no-color', '--no-ext-diff', '-M', base, head], { cwd });
+  return parseUnifiedDiff(String(out || ''));
+}
+
+/** Parse a unified diff (as produced by -U0) into files with hunk ranges. */
+export function parseUnifiedDiff(text) {
+  const files = [];
+  let cur = null;
+  let hunk = null;
+  for (const line of String(text).split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      cur = { path: null, oldPath: null, hunks: [], added: 0, removed: 0, isBinary: false, status: null };
+      files.push(cur);
+      hunk = null;
+      const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+      if (m) { cur.oldPath = m[1]; cur.path = m[2]; }
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith('new file mode')) { cur.status = 'A'; continue; }
+    if (line.startsWith('deleted file mode')) { cur.status = 'D'; continue; }
+    if (line.startsWith('rename from ')) { cur.oldPath = line.slice(11).trim(); continue; }
+    if (line.startsWith('rename to ')) { cur.path = line.slice(9).trim(); continue; }
+    if (line.startsWith('Binary files ')) { cur.isBinary = true; continue; }
+    if (line.startsWith('+++ ')) {
+      const p = line.slice(4).trim();
+      if (p !== '/dev/null') cur.path = p.replace(/^b\//, '');
+      continue;
+    }
+    if (line.startsWith('--- ')) {
+      const p = line.slice(4).trim();
+      if (p !== '/dev/null') cur.oldPath = p.replace(/^a\//, '');
+      continue;
+    }
+    if (line.startsWith('@@ ')) {
+      const m = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+      if (m) {
+        hunk = {
+          oldStart: Number(m[1]),
+          oldLines: m[2] === undefined ? 1 : Number(m[2]),
+          newStart: Number(m[3]),
+          newLines: m[4] === undefined ? 1 : Number(m[4]),
+          added: [],
+          removed: [],
+        };
+        cur.hunks.push(hunk);
+      }
+      continue;
+    }
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      if (hunk) hunk.added.push(line.slice(1));
+      cur.added += 1;
+      continue;
+    }
+    if (line.startsWith('-') && !line.startsWith('---')) {
+      if (hunk) hunk.removed.push(line.slice(1));
+      cur.removed += 1;
+      continue;
+    }
+  }
+  return files.filter(function (f) { return f.path; });
+}
+
+export function showCommit(cwd, sha, paths) {
+  const args = ['show', '--no-color', '--no-ext-diff', '--unified=2', '--format=%H%x1f%an%x1f%ae%x1f%at%x1f%s%x1f%b', sha];
+  if (paths && paths.length) args.push('--', ...paths);
+  const out = tryGit(args, { cwd });
+  if (!out) return null;
+  const sep = out.indexOf('\n');
+  const header = out.slice(0, sep < 0 ? out.length : sep);
+  const fields = header.split('\x1f');
+  const diffText = out.slice(sep + 1);
+  return {
+    sha: fields[0],
+    author: fields[1],
+    email: fields[2],
+    ts: Number(fields[3]),
+    subject: fields[4],
+    body: (fields[5] || '').trim(),
+    diff: parseUnifiedDiff(diffText),
+    raw: out,
+  };
+}
+
+/** Line-level blame for one file. Index 0 is line 1. */
+export function blamePorcelain(cwd, file, rev) {
+  const args = ['blame', '--porcelain'];
+  if (rev) args.push(rev);
+  args.push('--', file);
+  const out = tryGit(args, { cwd });
+  if (!out) return [];
+  const lines = [];
+  let cur = null;
+  for (const raw of out.split('\n')) {
+    if (!raw) continue;
+    const head = raw.match(/^([0-9a-f]{40}) (\d+) (\d+)(?: (\d+))?$/);
+    if (head) {
+      cur = { sha: head[1], line: Number(head[3]), author: '', ts: 0, text: '' };
+      lines[cur.line - 1] = cur;
+      continue;
+    }
+    if (!cur) continue;
+    if (raw.startsWith('author ')) cur.author = raw.slice(7);
+    else if (raw.startsWith('author-time ')) cur.ts = Number(raw.slice(12));
+    else if (raw.startsWith('\t')) cur.text = raw.slice(1);
+  }
+  return lines;
+}
+
+export function fileAt(cwd, rev, file) {
+  const out = tryGit(['show', rev + ':' + file], { cwd });
+  return out == null ? null : out;
+}
+
+export function lsTree(cwd, rev) {
+  const out = tryGit(['ls-tree', '-r', '--name-only', '-z', rev], { cwd });
+  return String(out || '').split('\0').filter(Boolean);
+}
+
+/** Full commit metadata (no merges) in one pass. */
+export function logMeta(cwd, opts) {
+  const o = opts || {};
+  const args = ['log', '--no-merges', '--format=%x1e%H%x1f%P%x1f%an%x1f%ae%x1f%at%x1f%cI%x1f%s%x1f%B'];
+  if (o.since) args.push(o.since + '..HEAD');
+  else if (o.rev) args.push(o.rev);
+  args.push('--');
+  const out = git(args, { cwd });
+  const rows = [];
+  for (const rec of out.split('\x1e')) {
+    if (!rec) continue;
+    const f = rec.split('\x1f');
+    if (f.length < 8) continue;
+    rows.push({
+      sha: f[0],
+      parents: f[1].trim() ? f[1].trim().split(' ') : [],
+      author: f[2],
+      email: f[3],
+      ts: Number(f[4]),
+      iso: f[5],
+      subject: f[6],
+      body: (f[7] || '').trim(),
+    });
+  }
+  return rows;
+}
+
+/** Per-commit file stats in one pass, keyed by sha. */
+export function logNumstat(cwd, opts) {
+  const o = opts || {};
+  const args = ['log', '--no-merges', '--format=%x1e%H', '--numstat', '-M'];
+  if (o.since) args.push(o.since + '..HEAD');
+  else if (o.rev) args.push(o.rev);
+  args.push('--');
+  const out = git(args, { cwd });
+  const map = new Map();
+  for (const rec of out.split('\x1e')) {
+    if (!rec) continue;
+    const lines = rec.split('\n').filter(function (l) { return l.trim().length > 0; });
+    if (!lines.length) continue;
+    const sha = lines[0].trim();
+    const files = [];
+    for (const line of lines.slice(1)) {
+      const parts = line.split('\t');
+      if (parts.length < 3) continue;
+      files.push({
+        added: parts[0] === '-' ? 0 : Number(parts[0]) || 0,
+        removed: parts[1] === '-' ? 0 : Number(parts[1]) || 0,
+        path: parts[2],
+      });
+    }
+    map.set(sha, files);
+  }
+  return map;
+}

package/src/indexer.js

@@ -0,0 +1,150 @@
+/** Full and incremental indexing of a repository's history. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, gitDir, headSha, logMeta, logNumstat, isShallow, lsFiles } from './git.js';
+import { openIndex, setMeta, getMeta, tx, dbStats } from './db.js';
+import { extractRationale, isBot, isTrivial, cleanSubject, hasFixWord } from './signals.js';
+
+export function indexPathFor(gitDirPath) {
+  return path.join(gitDirPath, 'whygit', 'index.db');
+}
+
+export function indexExists(gitDirPath) {
+  return fs.existsSync(indexPathFor(gitDirPath));
+}
+
+function chunk(arr, n) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n));
+  return out;
+}
+
+/**
+ * Build or refresh the index.
+ * opts: { cwd, full, quiet, onProgress(step, done, total) }
+ */
+export function buildIndex(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const t0 = Date.now();
+  const gd = gitDir(cwd);
+  const head = headSha(cwd);
+  if (!head) throw new Error('repository has no commits yet');
+  const dbc = openIndex(gd, { create: true });
+  const prevHead = getMeta(dbc, 'head');
+  let since = null;
+  if (!o.full && prevHead && prevHead !== head) {
+    const ok = git(['rev-parse', '--verify', '--quiet', prevHead + '^{commit}'], { cwd: cwd, maxBuffer: 1e7 });
+    if (ok) since = prevHead;
+  }
+
+  const metas = logMeta(cwd, { since: since });
+  const stats = logNumstat(cwd, { since: since });
+
+  const insertCommit = dbc.prepare(
+    'INSERT OR REPLACE INTO commits (sha, ts, iso, author, email, subject, body, parents, is_bot, files_changed, added, removed, paths) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)'
+  );
+  const insertFile = dbc.prepare('INSERT OR REPLACE INTO commit_files (sha, path, added, removed, status) VALUES (?,?,?,?,?)');
+  const insertDecision = dbc.prepare('INSERT OR REPLACE INTO decisions (sha, ts, title, rationale, paths, kind, confidence, evidence) VALUES (?,?,?,?,?,?,?,?)');
+  const deleteFts = dbc.prepare('DELETE FROM decisions_fts WHERE rowid = (SELECT rowid FROM decisions WHERE sha = ?)');
+  const insertFts = dbc.prepare('INSERT INTO decisions_fts (rowid, title, rationale, paths, subject) VALUES (?,?,?,?,?)');
+  const deleteTri = dbc.prepare('DELETE FROM decisions_tri WHERE rowid = (SELECT rowid FROM decisions WHERE sha = ?)');
+  const insertTri = dbc.prepare('INSERT INTO decisions_tri (rowid, title, rationale, paths) VALUES (?,?,?,?)');
+  const getRowid = dbc.prepare('SELECT rowid AS rid FROM decisions WHERE sha = ?');
+
+  let decisions = 0;
+  const batches = chunk(metas, 400);
+  for (let bi = 0; bi < batches.length; bi++) {
+    const batch = batches[bi];
+    tx(dbc, function () {
+      for (const com of batch) {
+        const files = stats.get(com.sha) || [];
+        const paths = files.map(function (f) { return f.path; });
+        const added = files.reduce(function (a, f) { return a + f.added; }, 0);
+        const removed = files.reduce(function (a, f) { return a + f.removed; }, 0);
+        const bot = isBot(com.author, com.email) ? 1 : 0;
+        insertCommit.run(com.sha, com.ts, com.iso, com.author, com.email, com.subject, com.body, com.parents.join(' '), bot, files.length, added, removed, paths.slice(0, 40).join(' '));
+        for (const f of files) {
+          const status = f.added > 0 && f.removed > 0 ? 'M' : f.added > 0 ? 'A' : 'D';
+          insertFile.run(com.sha, f.path, f.added, f.removed, status);
+        }
+        const rat = extractRationale(com.subject, com.body);
+        const title = cleanSubject(com.subject);
+        const kind = hasFixWord(title) || hasFixWord(com.body.slice(0, 400)) ? 'fix' : isTrivial(title) ? 'chore' : 'change';
+        let confidence = rat.confidence;
+        if (bot) confidence = Math.min(confidence, 0.2);
+        if (isTrivial(title)) confidence = Math.min(confidence, 0.25);
+        if (files.length > 60) confidence = Math.min(confidence, 0.5);
+        deleteFts.run(com.sha);
+        deleteTri.run(com.sha);
+        insertDecision.run(com.sha, com.ts, title, rat.rationale, paths.slice(0, 24).join(' '), kind, confidence, rat.source);
+        const rid = getRowid.get(com.sha);
+        if (rid) {
+          insertFts.run(rid.rid, title, rat.rationale, paths.slice(0, 24).join(' '), title);
+          insertTri.run(rid.rid, title, rat.rationale, paths.slice(0, 24).join(' '));
+        }
+        decisions += 1;
+      }
+    });
+    if (o.onProgress) o.onProgress('index', Math.min((bi + 1) * 400, metas.length), metas.length);
+  }
+
+  setMeta(dbc, 'head', head);
+  setMeta(dbc, 'indexed_at', String(Date.now()));
+  setMeta(dbc, 'commits_total', String(Number(getMeta(dbc, 'commits_total') || 0) + metas.length));
+  setMeta(dbc, 'shallow', isShallow(cwd) ? '1' : '0');
+  setMeta(dbc, 'root', String(cwd));
+  const elapsed = Date.now() - t0;
+  setMeta(dbc, 'last_seconds', String(elapsed));
+  const st = dbStats(dbc);
+  dbc.close();
+  return { commits: metas.length, decisions: decisions, elapsed: elapsed, since: since, files: st.files, total: st.commits };
+}
+
+/** Compute per-file risk metrics from commit_files. */
+export function computeRisk(dbc, opts) {
+  const o = opts || {};
+  const rows = dbc.prepare(
+    'SELECT cf.path AS path, COUNT(*) AS commits, COUNT(DISTINCT c.email) AS authors, SUM(cf.added) AS added, SUM(cf.removed) AS removed, MAX(c.ts) AS last_ts, SUM(CASE WHEN c.is_bot = 0 AND (LOWER(c.subject) LIKE \'%fix%\' OR LOWER(c.subject) LIKE \'%revert%\' OR LOWER(c.subject) LIKE \'%bug%\' OR LOWER(c.subject) LIKE \'%hotfix%\' OR LOWER(c.subject) LIKE \'%patch%\') THEN 1 ELSE 0 END) AS fixes FROM commit_files cf JOIN commits c ON c.sha = cf.sha GROUP BY cf.path'
+  ).all();
+  const del = dbc.prepare('DELETE FROM risk');
+  const ins = dbc.prepare('INSERT INTO risk (path, score, commits, authors, fixes, todos, last_ts, added, removed) VALUES (?,?,?,?,?,?,?,?,?)');
+  const now = Date.now() / 1000;
+  tx(dbc, function () {
+    del.run();
+    for (const r of rows) {
+      const churn = (r.added || 0) + (r.removed || 0);
+      const fixRatio = r.commits ? r.fixes / r.commits : 0;
+      const ageDays = Math.max(0, (now - (r.last_ts || now)) / 86400);
+      const freshness = 1 / (1 + ageDays / 180);
+      let score =
+        Math.log10(1 + churn) * (1 + fixRatio * 1.5) * (1 + Math.min(r.authors, 8) / 6) * (0.6 + 0.4 * freshness);
+      if (/(^|\/)(tests?|__tests__|specs?|fixtures?)\//.test(r.path)) score *= 0.55;
+      if (/\.(rst|md|mdx|txt)$/.test(r.path)) score *= 0.5;
+      if (/(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|poetry\.lock|go\.sum|Cargo\.lock)$/.test(r.path)) score *= 0.2;
+      ins.run(r.path, score, r.commits, r.authors, r.fixes, 0, r.last_ts, r.added, r.removed);
+    }
+  });
+  return rows.length;
+}
+
+/** Count TODO/FIXME-ish markers in the working tree, one pass, cheap. */
+export function scanMarkers(dbc, cwd) {
+  const files = lsFiles(cwd).filter(function (p) {
+    return /\.(js|jsx|mjs|cjs|ts|tsx|py|rb|go|rs|java|kt|c|h|cc|cpp|hpp|cs|php|swift|sh|ps1|lua|ex|exs|vue|svelte|sql|md|css|scss)$/i.test(p);
+  });
+  const upd = dbc.prepare('UPDATE risk SET todos = ? WHERE path = ?');
+  const RE = /\b(TODO|FIXME|HACK|XXX|BUG)\b/g;
+  let total = 0;
+  tx(dbc, function () {
+    for (const f of files) {
+      let text = '';
+      try { text = fs.readFileSync(path.join(cwd, f), 'utf8'); } catch { continue; }
+      if (text.length > 400000) continue;
+      const m = text.match(RE);
+      const n = m ? m.length : 0;
+      if (n) { upd.run(n, f); total += n; }
+    }
+  });
+  return { files: files.length, markers: total };
+}

package/src/install.js

@@ -0,0 +1,95 @@
+/** One-command wiring into agent tools. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { c } from './util.js';
+import { header, renderNote } from './ui.js';
+
+const START = '<!-- whygit:start -->';
+const END = '<!-- whygit:end -->';
+
+function agentsBlock() {
+  return [
+    START,
+    '## Why the code is the way it is',
+    '',
+    'This repository keeps a generated WHYLOG.md: every non-obvious decision, with the commit and date behind it.',
+    '',
+    'Before changing code whose intent is not obvious:',
+    '',
+    '1. Search WHYLOG.md for the file you are about to touch.',
+    '2. If a line there contradicts your plan, trust it until you can explain why it no longer applies.',
+    '3. When you make a non-obvious change, put a WHY: <reason> line in the commit body.',
+    '',
+    'Prefer the MCP tools when available: why_search, why_line, why_file, why_risk, whylog_read.',
+    END,
+  ].join('\n');
+}
+
+export function writeAgentsFile(cwd) {
+  const file = path.join(cwd, 'AGENTS.md');
+  let text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const block = agentsBlock();
+  const re = new RegExp(START + '[\\s\\S]*?' + END);
+  if (re.test(text)) text = text.replace(re, block);
+  else text = (text.trim() ? text.trim() + '\n\n' : '') + block + '\n';
+  fs.writeFileSync(file, text, 'utf8');
+  return file;
+}
+
+function serverEntry(command, args) {
+  return { command: command, args: args };
+}
+
+function mergeJson(file, key, entry) {
+  let cur = {};
+  if (fs.existsSync(file)) {
+    try { cur = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { cur = {}; }
+  }
+  cur[key] = Object.assign({}, cur[key], { whygit: entry });
+  fs.writeFileSync(file, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+  return file;
+}
+
+export function installFor(agent, cwd, opts) {
+  const o = opts || {};
+  const cmd = o.command || 'npx';
+  const args = o.command ? ['mcp'] : ['-y', 'whygit@latest', 'mcp'];
+  const done = [];
+  if (agent === 'claude' || agent === 'all') {
+    done.push(mergeJson(path.join(cwd, '.mcp.json'), 'mcpServers', serverEntry(cmd, args)));
+  }
+  if (agent === 'cursor' || agent === 'all') {
+    fs.mkdirSync(path.join(cwd, '.cursor'), { recursive: true });
+    done.push(mergeJson(path.join(cwd, '.cursor', 'mcp.json'), 'mcpServers', serverEntry(cmd, args)));
+  }
+  if (agent === 'vscode' || agent === 'all') {
+    fs.mkdirSync(path.join(cwd, '.vscode'), { recursive: true });
+    const f = path.join(cwd, '.vscode', 'mcp.json');
+    let cur = {};
+    if (fs.existsSync(f)) { try { cur = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { cur = {}; } }
+    cur.servers = Object.assign({}, cur.servers, { whygit: { type: 'stdio', command: cmd, args: args } });
+    fs.writeFileSync(f, JSON.stringify(cur, null, 2) + '\n', 'utf8');
+    done.push(f);
+  }
+  if (agent === 'agents' || agent === 'all') done.push(writeAgentsFile(cwd));
+  return done;
+}
+
+export function cmdInstall(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const agent = flags.agent || args[0] || 'all';
+  const known = ['claude', 'cursor', 'vscode', 'agents', 'all'];
+  if (!known.includes(agent)) {
+    console.log(renderNote('Unknown agent: ' + agent + '. Use one of ' + known.join(', '), 'warn'));
+    return 2;
+  }
+  const written = installFor(agent, cwd, { command: flags.local ? 'whygit' : null });
+  console.log(header('install', agent));
+  console.log('');
+  for (const f of written) console.log('  ' + c.green('\u2713') + ' ' + path.relative(cwd, f));
+  console.log('');
+  console.log(c.gray('  Restart your editor / agent session to pick up the MCP server.'));
+  if (!flags.local) console.log(c.gray('  Using npx whygit. Add --local to point at an installed binary instead.'));
+  console.log('');
+  return 0;
+}