@luanpdd/kit-mcp 1.27.0 → 1.29.0

package/src/cli/index.js

@@ -27,6 +27,7 @@ import { collectFailures, summarizeByAgent, writeLearnings } from '../core/failu
 import { reflect } from '../core/reflect.js';
 import { listReplays, loadReplay } from '../core/replays.js';
 import { installMcp, listInstallTargets } from '../mcp-server/install.js';
+import { listLogs, tailLogs, logDir, currentLogPath } from '../core/logger.js';
 import * as render from './render.js';
 import { c, icons, spinner, progress, select, confirm } from '../core/ui.js';
 import { readLock, lockPathFor } from '../ui/lockfile.js';
@@ -217,14 +218,28 @@ sync.command('install [target]')
   .option('--project-root <path>')
   .option('--mode <mode>', 'reference | copy', 'reference')
   .option('--dry-run')
+  .option('--quiet', 'Suppress per-file progress; keep final summary')
   .action(async (target, opts) => {
     if (!target) target = await pickTarget(listTargets(), 'Which IDE do you want to sync the kit into?');
-    const result = await withProgress(
-      `Syncing kit → ${target}`,
-      300,
-      (onProgress) => syncTo(target, { projectRoot: opts.projectRoot, mode: opts.mode, dryRun: opts.dryRun, onProgress }),
-      { tool: 'sync.install', projectRoot: opts.projectRoot },
-    );
+    // Phase 160 (v1.28): count written vs skipped so the post-sync summary
+    // can render "X new/updated, Y unchanged".
+    const tally = { written: 0, skipped: 0 };
+    const wrapOnProgress = (orig) => (ev) => {
+      if (ev?.skipped) tally.skipped += 1;
+      else tally.written += 1;
+      if (orig) orig(ev);
+    };
+    const runSync = (onProgress) => syncTo(target, {
+      projectRoot: opts.projectRoot,
+      mode: opts.mode,
+      dryRun: opts.dryRun,
+      onProgress: wrapOnProgress(opts.quiet ? null : onProgress),
+    });
+    const result = opts.quiet
+      ? await runSync()
+      : await withProgress(`Syncing kit → ${target}`, 300, runSync,
+          { tool: 'sync.install', projectRoot: opts.projectRoot });
+    result._tally = tally; // surfaced by renderSyncInstall (v1.28)
     out(result, render.renderSyncInstall);
   });
 sync.command('remove <target>')
@@ -669,6 +684,63 @@ async function runDoctorChecks(projectRoot) {
     }
   } catch { /* tmpdir scan is best-effort */ }
 
+  // 8. (v1.28) log dir writable — required for kit logs
+  try {
+    const dir = logDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const probe = path.join(dir, `.doctor-probe-${process.pid}`);
+    fs.writeFileSync(probe, '', 'utf8');
+    fs.unlinkSync(probe);
+    const files = listLogs();
+    checks.push({ label: 'log dir', status: 'pass',
+      detail: `${dir} writable (${files.length} log file${files.length === 1 ? '' : 's'})` });
+  } catch (err) {
+    checks.push({ label: 'log dir', status: 'fail',
+      detail: `${logDir()} not writable: ${err.message}`,
+      fix: 'check permissions or set KIT_MCP_LOG_DIR to a writable path' });
+  }
+
+  // 9. (v1.28) sidecar auto-spawn config — informational
+  const noUi = process.env.KIT_MCP_NO_UI === '1' || process.env.KIT_MCP_NO_UI === 'true';
+  checks.push({ label: 'sidecar auto-spawn', status: noUi ? 'warn' : 'pass',
+    detail: noUi
+      ? 'KIT_MCP_NO_UI=1 — sidecar will NOT auto-start on MCP boot'
+      : 'enabled (default) — sidecar starts when MCP server boots',
+    fix: noUi ? 'unset KIT_MCP_NO_UI if you want live tool-call visibility' : undefined });
+
+  // 10. (v1.29) auto-install drift check — is .claude/.kit-mcp-version aligned
+  // with the running kit-mcp package version?
+  try {
+    const versionMarker = path.join(projectRoot, '.claude', '.kit-mcp-version');
+    const restartMarker = path.join(projectRoot, '.claude', '.kit-mcp-restart-required');
+    let installedVersion = null;
+    try { installedVersion = fs.readFileSync(versionMarker, 'utf8').trim(); } catch { /* not installed */ }
+    const currentVersion = readPkgVersion();
+
+    if (!installedVersion) {
+      checks.push({ label: 'auto-install', status: 'warn',
+        detail: '.claude/.kit-mcp-version not found — kit not auto-installed in this project',
+        fix: 'call kit:auto-install MCP tool, or run: kit init' });
+    } else if (installedVersion !== currentVersion) {
+      checks.push({ label: 'auto-install', status: 'warn',
+        detail: `kit installed v${installedVersion}, MCP server is v${currentVersion}`,
+        fix: 'call kit:auto-install (idempotent) or rerun: kit sync claude-code' });
+    } else {
+      checks.push({ label: 'auto-install', status: 'pass',
+        detail: `v${installedVersion} (in sync)` });
+    }
+
+    if (fs.existsSync(restartMarker)) {
+      let payload = {};
+      try { payload = JSON.parse(fs.readFileSync(restartMarker, 'utf8')); } catch { /* malformed */ }
+      checks.push({ label: 'restart pending', status: 'warn',
+        detail: payload.reason
+          ? `${payload.reason} (written ${payload.writtenAt || 'unknown'})`
+          : 'restart marker present — IDE not yet reloaded since last auto-install',
+        fix: 'restart your IDE session, then call kit:ack-restart MCP tool (or just close/reopen)' });
+    }
+  } catch { /* .claude/ check is best-effort */ }
+
   return checks;
 }
 
@@ -739,4 +811,304 @@ function renderUiStatusFallback(v) {
   ].join('\n');
 }
 
+// --- status (Phase 162, v1.28: live metrics snapshot + log file path) ---
+program.command('status')
+  .description('Show MCP server metrics (p50/p95/p99/error rate) + log file path.')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (opts) => {
+    const { snapshot, loadSnapshots } = await import('../core/metrics.js');
+    const projectRoot = opts.projectRoot || process.cwd();
+    const live = snapshot(); // current-process metrics (only useful when called from inside the MCP process)
+    const persisted = await loadSnapshots(projectRoot, 60 * 60 * 1000).catch(() => []); // last hour
+
+    if (program.opts().json) {
+      out({ live, persistedCount: persisted.length, latest: persisted[persisted.length - 1] || null, logPath: currentLogPath() }, () => '');
+      return;
+    }
+
+    process.stdout.write(`\n${c.bold('kit-mcp status')}\n\n`);
+
+    // Sidecar
+    const lock = readLock(projectRoot);
+    process.stdout.write(`${c.bold('sidecar:')}  ${lock ? c.green(`running on port ${lock.port}`) : c.dim('not running')}\n`);
+
+    // Log file
+    const files = listLogs();
+    process.stdout.write(`${c.bold('log:')}      ${currentLogPath()}\n`);
+    process.stdout.write(`           ${c.dim(`${files.length} file(s) in ${logDir()}`)}\n`);
+
+    // Latency from latest persisted snapshot (last hour window)
+    const latest = persisted[persisted.length - 1];
+    const lat = latest?.latency || live.latency || {};
+    const tools = Object.keys(lat);
+    process.stdout.write(`\n${c.bold('latency (last hour, or current process):')}\n`);
+    if (tools.length === 0) {
+      process.stdout.write(`  ${c.dim('no samples yet')}\n`);
+    } else {
+      const w = Math.max(...tools.map((t) => t.length));
+      for (const t of tools) {
+        const s = lat[t];
+        process.stdout.write(`  ${t.padEnd(w)}  p50 ${c.cyan(s.p50 + 'ms').padEnd(20)} p95 ${c.cyan(s.p95 + 'ms').padEnd(20)} p99 ${c.cyan(s.p99 + 'ms').padEnd(20)} n=${s.count}\n`);
+      }
+    }
+
+    // Error rate from counters
+    const counters = latest?.counters || live.counters || {};
+    let okTotal = 0, errTotal = 0;
+    for (const [k, v] of Object.entries(counters)) {
+      if (k.endsWith(':ok')) okTotal += v;
+      if (k.endsWith(':error')) errTotal += v;
+    }
+    const total = okTotal + errTotal;
+    const rate = total === 0 ? 0 : (errTotal / total) * 100;
+    process.stdout.write(`\n${c.bold('errors:')}   ${errTotal}/${total} (${rate.toFixed(2)}%)\n\n`);
+  });
+
+// --- init (Phase 161, v1.28: guided onboarding — install + sync + doctor) ---
+program.command('init')
+  .description('Onboard: register kit-mcp into an IDE, sync the kit, run doctor.')
+  .option('--ide <id>', 'Skip the IDE picker (e.g. claude-code, cursor, codex)')
+  .option('--project-root <path>', 'Default: cwd')
+  .option('--non-interactive', 'Fail fast if --ide is missing instead of prompting')
+  .option('--mode <mode>', 'sync mode: reference | copy', 'reference')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const targets = listInstallTargets();
+    const targetIds = targets.map(t => t.id);
+
+    let ide = opts.ide;
+    if (!ide) {
+      if (opts.nonInteractive) {
+        process.stderr.write(`${c.red(icons.cross)} --non-interactive requires --ide=<${targetIds.join('|')}>\n`);
+        process.exit(2);
+      }
+      ide = await pickTarget(targets, 'Which IDE should kit-mcp register with?');
+    }
+    if (!targetIds.includes(ide)) {
+      process.stderr.write(`${c.red(icons.cross)} unknown IDE "${ide}" — valid: ${targetIds.join(', ')}\n`);
+      process.exit(2);
+    }
+
+    process.stdout.write(`\n${c.bold('kit init')} → ${ide}\n\n`);
+
+    // 1. Register MCP server in IDE config
+    process.stdout.write(`${c.cyan('1/3')} registering MCP server...\n`);
+    try {
+      const r = await installMcp(ide, { projectRoot });
+      process.stdout.write(`     ${c.green(icons.check)} ${r.path || 'config updated'}\n`);
+    } catch (e) {
+      process.stdout.write(`     ${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+
+    // 2. Sync kit content
+    process.stdout.write(`\n${c.cyan('2/3')} syncing kit content...\n`);
+    const tally = { written: 0, skipped: 0 };
+    try {
+      const r = await syncTo(ide, {
+        projectRoot,
+        mode: opts.mode,
+        onProgress: (ev) => { if (ev?.skipped) tally.skipped += 1; else tally.written += 1; },
+      });
+      const total = (r.written || []).length;
+      process.stdout.write(`     ${c.green(icons.check)} ${total} files (${tally.written} new/updated, ${tally.skipped} unchanged)\n`);
+    } catch (e) {
+      process.stdout.write(`     ${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+
+    // 3. Doctor
+    process.stdout.write(`\n${c.cyan('3/3')} running diagnostic...\n`);
+    const checks = await runDoctorChecks(projectRoot);
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+    const passed = checks.length - failed - warned;
+    process.stdout.write(`     ${failed === 0 ? c.green(icons.check) : c.red(icons.cross)} `
+      + `${passed} pass · ${warned} warn · ${failed} fail\n`);
+
+    // 4. Final confirmation
+    try {
+      const kit = await listKit();
+      process.stdout.write(`\n${c.green(icons.check)} ${c.bold(ide)} now sees `
+        + `${c.cyan(kit.skills.length)} skills, `
+        + `${c.cyan(kit.agents.length)} agents, `
+        + `${c.cyan(kit.commands.length)} commands\n\n`);
+    } catch { /* non-fatal */ }
+
+    if (failed > 0) {
+      process.stdout.write(`${c.yellow(icons.warn)} doctor reported failures — run ${c.cyan('kit doctor')} for details\n`);
+      process.exit(1);
+    }
+  });
+
+// --- replay (Phase 165, v1.28: inspect recorded agent Task() payloads) ---
+const replay = program.command('replay').description('List or inspect recorded agent replays.');
+
+replay.command('list')
+  .description('List replays in <project-root>/.planning/replays/')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    const items = await listReplays({ projectRoot });
+    if (program.opts().json) {
+      out(items, () => '');
+      return;
+    }
+    if (items.length === 0) {
+      process.stderr.write(`${c.yellow(icons.warn)} no replays at ${path.join(projectRoot, '.planning', 'replays')}\n`);
+      return;
+    }
+    process.stdout.write(`\n${c.bold(items.length + ' replay(s)')}\n\n`);
+    for (const r of items) {
+      process.stdout.write(`  ${c.cyan(r.id)}\n`);
+      process.stdout.write(`    agent: ${c.bold(r.agent || '?')}  phase: ${r.phase || '?'}  plan: ${r.plan || '?'}\n`);
+      process.stdout.write(`    ${c.dim(r.recorded_at || '?')}\n\n`);
+    }
+  });
+
+replay.command('show <id>')
+  .description('Show the full recorded payload for a replay id.')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (id, opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    try {
+      const r = await loadReplay(id, { projectRoot });
+      if (program.opts().json) {
+        out(r, () => '');
+        return;
+      }
+      process.stdout.write(`\n${c.bold(r.id)}\n`);
+      process.stdout.write(`${c.dim('recorded:')} ${r.recorded_at}\n`);
+      process.stdout.write(`${c.dim('agent:')}    ${c.bold(r.agent || '?')}\n`);
+      process.stdout.write(`${c.dim('phase:')}    ${r.phase || '?'}\n`);
+      process.stdout.write(`${c.dim('plan:')}     ${r.plan || '?'}\n`);
+      if (r.outcome) {
+        process.stdout.write(`${c.dim('outcome:')}  ${JSON.stringify(r.outcome)}\n`);
+      }
+      process.stdout.write(`\n${c.bold('payload:')}\n`);
+      const { id: _id, recorded_at: _rec, agent: _a, phase: _p, plan: _pl, outcome: _o, ...rest } = r;
+      process.stdout.write(JSON.stringify(rest, null, 2) + '\n');
+    } catch (e) {
+      process.stderr.write(`${c.red(icons.cross)} replay "${id}" not found: ${e.message}\n`);
+      process.exit(1);
+    }
+  });
+
+replay.command('diff <id>')
+  .description('Compare a replay payload against its most recent re-record (if any).')
+  .option('--project-root <path>', 'Default: cwd')
+  .action(async (id, opts) => {
+    const projectRoot = opts.projectRoot || process.cwd();
+    try {
+      const target = await loadReplay(id, { projectRoot });
+      const all = await listReplays({ projectRoot });
+      // Find newest replay with same agent that isn't the target itself.
+      const candidate = all.find((r) => r.id !== id && r.agent === target.agent);
+      if (!candidate) {
+        process.stdout.write(`${c.yellow(icons.warn)} no peer replay for agent "${target.agent}" — nothing to diff\n`);
+        return;
+      }
+      const newer = await loadReplay(candidate.id, { projectRoot });
+      const a = JSON.stringify(target, null, 2).split('\n');
+      const b = JSON.stringify(newer, null, 2).split('\n');
+      process.stdout.write(`\n${c.bold(`diff ${id}  ↔  ${candidate.id}`)}\n\n`);
+      const max = Math.max(a.length, b.length);
+      for (let i = 0; i < max; i++) {
+        if (a[i] !== b[i]) {
+          if (a[i] !== undefined) process.stdout.write(c.red('-') + ' ' + a[i] + '\n');
+          if (b[i] !== undefined) process.stdout.write(c.green('+') + ' ' + b[i] + '\n');
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`${c.red(icons.cross)} ${e.message}\n`);
+      process.exit(1);
+    }
+  });
+
+// --- inspect (Phase 163, v1.28: live TUI mirror of MCP request/response) ---
+program.command('inspect')
+  .description('Live request/response mirror — pretty-print MCP tool calls as they happen.')
+  .option('--tail <n>', 'show last N events (default 20)', '20')
+  .action(async (opts) => {
+    const lines = parseInt(opts.tail, 10) || 20;
+    if (process.env.KIT_MCP_INSPECT !== '1' && process.env.KIT_MCP_INSPECT !== 'true') {
+      process.stderr.write(`${c.yellow(icons.warn)} verbose payload capture is OFF\n`);
+      process.stderr.write(`${c.dim('set KIT_MCP_INSPECT=1 in the env where kit-mcp runs to capture args/result')}\n`);
+      process.stderr.write(`${c.dim('(events are still tailed; just without payloads)')}\n\n`);
+    }
+
+    const render = (raw) => {
+      try {
+        const ev = JSON.parse(raw);
+        const t = ev.ts ? ev.ts.replace('T', ' ').replace('Z', '') : '?';
+        const status = ev.status === 'ok' ? c.green('●') : c.red('●');
+        const tool = c.bold(ev.tool || '?');
+        const action = ev.action ? c.cyan(ev.action) : '';
+        const dur = ev.duration_ms !== undefined ? c.dim(`(${ev.duration_ms}ms)`) : '';
+        process.stdout.write(`\n${status} ${c.dim(t)}  ${tool} ${action} ${dur}\n`);
+        if (ev.args !== undefined) {
+          process.stdout.write(`  ${c.dim('req:')}  ${JSON.stringify(ev.args)}\n`);
+        }
+        if (ev.result !== undefined && ev.result !== null) {
+          const pretty = JSON.stringify(ev.result);
+          process.stdout.write(`  ${c.dim('res:')}  ${pretty.length > 200 ? pretty.slice(0, 200) + '…' : pretty}\n`);
+        }
+        if (ev.error_type) {
+          process.stdout.write(`  ${c.red('err:')}  ${ev.error_type}\n`);
+        }
+      } catch {
+        process.stdout.write(raw + '\n');
+      }
+    };
+
+    const t = tailLogs({ lines, follow: true, onLine: render });
+    process.stdout.write(`${c.dim(`-- inspecting ${currentLogPath()} (Ctrl-C to stop) --`)}\n`);
+    process.on('SIGINT', () => { t.stop(); process.exit(0); });
+    await new Promise(() => {});
+  });
+
+// --- logs (Phase 158, v1.28: tail kit-mcp tool-call log) ---
+program.command('logs')
+  .description('Tail JSONL logs of MCP tool invocations (~/.kit-mcp/logs/).')
+  .option('--tail <n>', 'show last N lines (default 50)', '50')
+  .option('--follow', 'keep streaming new events as they arrive')
+  .option('--path', 'print the current log file path and exit')
+  .action(async (opts) => {
+    if (opts.path) {
+      process.stdout.write(`${currentLogPath()}\n`);
+      return;
+    }
+    const lines = parseInt(opts.tail, 10) || 50;
+    const files = listLogs();
+    if (files.length === 0) {
+      process.stderr.write(`${c.yellow(icons.warn)} no logs yet at ${logDir()}\n`);
+      process.stderr.write(`${c.dim('logs are appended when the MCP server handles a tool call')}\n`);
+      process.exit(0);
+    }
+    const isJson = program.opts().json;
+    const render = (raw) => {
+      if (isJson) { process.stdout.write(raw + '\n'); return; }
+      try {
+        const ev = JSON.parse(raw);
+        const t = ev.ts ? ev.ts.replace('T', ' ').replace('Z', '') : '?';
+        const status = ev.status === 'ok' ? c.green(icons.check) : c.red(icons.cross);
+        const tool = c.bold(ev.tool || '?');
+        const action = ev.action ? c.dim(`[${ev.action}]`) : '';
+        const dur = ev.duration_ms !== undefined ? c.cyan(`${ev.duration_ms}ms`) : '';
+        const err = ev.error_type ? c.red(` (${ev.error_type})`) : '';
+        process.stdout.write(`${c.dim(t)}  ${status} ${tool} ${action} ${dur}${err}\n`);
+      } catch {
+        process.stdout.write(raw + '\n');
+      }
+    };
+
+    const t = tailLogs({ lines, follow: !!opts.follow, onLine: render });
+    if (opts.follow) {
+      process.stdout.write(`${c.dim(`-- following ${currentLogPath()} (Ctrl-C to stop) --`)}\n`);
+      process.on('SIGINT', () => { t.stop(); process.exit(0); });
+      // keep process alive
+      await new Promise(() => {});
+    }
+  });
+
 program.parseAsync(process.argv);

package/src/cli/render.js

@@ -85,6 +85,13 @@ export function renderSyncInstall(result) {
     if (counts[cap] !== undefined) rows.push([cap, counts[cap]]);
   }
   const visibleTotal = Object.values(counts).reduce((a, b) => a + b, 0);
+  // Phase 160 (v1.28): append diff tally row if cli attached one.
+  if (result._tally) {
+    const w = result._tally.written;
+    const s = result._tally.skipped;
+    rows.push(['new / updated', w]);
+    rows.push(['unchanged', s]);
+  }
   return summary({
     title: `Synced kit → ${result.target}${result.dryRun ? ' (dry-run)' : ''}`,
     rows,