dev-diagnosis-cli 0.1.8 → 0.2.0

package/lib/checks.mjs

@@ -0,0 +1,280 @@
+/**
+ * The four checks, as functions both the CLI and the MCP server call.
+ *
+ * This is the one place the check logic lives: bin/dev-diagnosis.js
+ * renders it for humans, lib/mcp.mjs serves it to agents, and neither
+ * re-implements a verdict. Each runner returns the same shape —
+ * `{ result, passed, verdict }` — and a check that could not run
+ * returns `{ result: null, passed: false, verdict, error }` instead of
+ * throwing, so the `all` report can say why it failed.
+ */
+import { scanDirectory, applyAiignore, formatBytes } from './context.mjs';
+import {
+  buildContexts, findCommandCopies, fixForDirectory, lookupCommand,
+  searchToolchainBins,
+} from './pathcheck.mjs';
+import { runCacheCheck as runCacheCheckImpl } from './cache.mjs';
+import { scanRuns } from './flakes.mjs';
+import { formatMs } from './report.mjs';
+
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+// "login", "login and daemon-like", "login, non-login and daemon-like".
+function joinNames(names) {
+  if (names.length <= 1) return names.join('');
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+export function runContextCheck(target) {
+  const result = scanDirectory(target || process.cwd());
+  const passed = result.score >= 85;
+  return { result, passed, verdict: passed ? 'context is clean' : `${result.status.toLowerCase()} (score ${result.score}/100)` };
+}
+
+/**
+ * Apply the context check's .aiignore suggestions and record the
+ * outcome on the check result, so --json output carries it too.
+ */
+export function applyContextFix(check) {
+  const fix = applyAiignore(check.result.root, check.result.suggestions);
+  check.result.fix = fix;
+  return fix;
+}
+
+/**
+ * Apply a context check's .aiignore fix, then re-scan so the returned
+ * check describes the repo as it stands after the fix. The fix outcome
+ * is carried onto the re-scanned result, so --json and MCP output still
+ * say what was written. Without the re-scan, `context --fix` on a noisy
+ * repo would report the pre-fix verdict — exit 1 and FAIL — even though
+ * the fix landed and a re-run scores clean. The exit code of a fix
+ * command should say whether the repo is fixed now, the way
+ * eslint --fix does: it exits 0 when everything it could fix is fixed.
+ */
+export function applyContextFixAndRescan(check) {
+  const fix = applyContextFix(check);
+  const fixed = runContextCheck(check.result.root);
+  fixed.result.fix = fix;
+  return fixed;
+}
+
+/**
+ * Re-scan the context check of an `all` run after --fix, and refresh
+ * the run's overall verdict and summary to match. The pre-fix report
+ * stays printed above; what changes is the verdict the run reports.
+ * The fix outcome recorded by applyContextFix is carried over, so the
+ * post-fix result still says what was written.
+ */
+export function rescanContext(run) {
+  const before = run.checks.context;
+  const fixed = runContextCheck(run.root);
+  if (before?.result?.fix) fixed.result.fix = before.result.fix;
+  run.checks.context = fixed;
+  run.overall = Object.values(run.checks).every((check) => check.passed);
+  run.summary = buildSummary(run.checks, run.skipped);
+  return fixed;
+}
+
+export function runPathCheck(commandName) {
+  if (!commandName) throw new UsageError('path needs a command, for example: dev-diagnosis path node');
+  const contexts = buildContexts();
+  const rows = contexts.map((ctx) => {
+    const found = lookupCommand(commandName, ctx.pathValue);
+    return { ...ctx, resolved: found.resolved, path: found.path, reason: found.reason || null };
+  });
+  const copies = findCommandCopies(commandName, process.env.PATH || '');
+  const toolchainHits = rows[0].resolved ? [] : searchToolchainBins(commandName);
+  let fix = null;
+  if (!rows[0].resolved && toolchainHits.length > 0) fix = fixForDirectory(toolchainHits[0].directory);
+  else if (!rows[0].resolved && rows.some((row) => row.resolved)) {
+    fix = 'it resolves in another shell context — check which startup file sets your PATH';
+  }
+  const passed = rows[0].resolved;
+  // The verdict must agree with the four-context table above it: "missing
+  // in the current shell" was wrong on both sides — when the command
+  // missed everywhere it sounded like it might exist elsewhere, and when
+  // it resolved in another context it never said where. Name the contexts
+  // it resolves in, or say plainly that no context has it.
+  const foundIn = rows.filter((row) => row.resolved).map((row) => row.name);
+  let verdict;
+  if (passed) verdict = `${commandName} resolves to ${rows[0].path}`;
+  else if (foundIn.length > 0) verdict = `${commandName} is missing in the current shell, but resolves in ${joinNames(foundIn)}`;
+  else verdict = `${commandName} is not found in any shell context`;
+  return {
+    result: { command: commandName, contexts: rows, copies, toolchainHits, fix },
+    passed,
+    verdict,
+  };
+}
+
+export function runFlakesCheck(dir) {
+  if (!dir) throw new UsageError('flakes needs a runs directory, for example: dev-diagnosis flakes examples/runs');
+  const result = scanRuns(dir);
+  const unparsable = result.warnings.length;
+  const skippedRuns = result.skippedRuns ? result.skippedRuns.length : 0;
+  // A file that could not be parsed, or a run directory that produced no
+  // reports, means the verdict is based on incomplete data: "no flaky
+  // tests" on a half-read run set is not a pass, so the check fails and
+  // the verdict says what was unreadable. The warnings themselves are
+  // printed with the table.
+  const passed = result.totals.flaky === 0 && result.totals.alwaysFailing === 0 && unparsable === 0 && skippedRuns === 0;
+  const base = result.totals.flaky === 0 && result.totals.alwaysFailing === 0
+    ? `no flaky tests across ${result.totals.runs} runs`
+    : `${result.totals.flaky} flaky, ${result.totals.alwaysFailing} always-failing across ${result.totals.runs} runs`;
+  const problems = [];
+  if (unparsable > 0) problems.push(`${unparsable} file${unparsable === 1 ? '' : 's'} could not be parsed`);
+  if (skippedRuns > 0) problems.push(`${skippedRuns} run director${skippedRuns === 1 ? 'y' : 'ies'} had no JUnit XML files`);
+  return {
+    result,
+    passed,
+    verdict: problems.length > 0 ? `${base}; ${problems.join('; ')}` : base,
+  };
+}
+
+export function runCacheCheck(options) {
+  if (!options.buildCommand || options.buildCommand.length === 0) {
+    throw new UsageError('cache needs a build command after --, for example: dev-diagnosis cache -- node build.mjs');
+  }
+  const result = runCacheCheckImpl({
+    root: options.cwd || process.cwd(),
+    cacheDir: options.cacheDir,
+    command: options.buildCommand,
+  });
+  const passed = result.verdict !== 'cache costs';
+  return {
+    result,
+    passed,
+    verdict: `${result.verdict}: cold ${formatMs(result.coldMs)}, warm ${formatMs(result.warmMs)} (${result.verdictDetail})`,
+  };
+}
+
+// The raw cache result carries the build's full stdout from both runs;
+// JSON output drops it, so a chatty build does not bloat the machine-
+// readable output. Used by the standalone cache output and by the
+// `all --json` builder below, so both shapes stay identical.
+export function stripCacheStdout(result) {
+  const { coldStdout, warmStdout, ...rest } = result;
+  return rest;
+}
+
+/**
+ * One-line summary of an `all` run: how many checks passed, failed or
+ * were skipped, how much context noise was found, and what the cache
+ * saved when it ran. `contextNoiseBytes` is the listed noise — the
+ * same bytes the token estimate is based on.
+ */
+export function buildSummary(checks, skipped) {
+  const ran = Object.values(checks);
+  const passed = ran.filter((check) => check.passed).length;
+  const noiseBytes = checks.context && checks.context.result
+    ? checks.context.result.noise.reduce((sum, item) => sum + item.bytes, 0)
+    : 0;
+  const cacheResult = checks.cache && checks.cache.result ? checks.cache.result : null;
+  return {
+    checks: { total: ran.length + skipped.length, passed, failed: ran.length - passed, skipped: skipped.length },
+    contextNoiseBytes: noiseBytes,
+    cacheSavedPct: cacheResult ? cacheResult.savedPct : null,
+  };
+}
+
+export function formatSummary(summary) {
+  const parts = [
+    `${summary.checks.total} checks — ${summary.checks.passed} passed, ${summary.checks.failed} failed, ${summary.checks.skipped} skipped`,
+  ];
+  if (summary.contextNoiseBytes > 0) parts.push(`context noise ${formatBytes(summary.contextNoiseBytes)}`);
+  if (summary.cacheSavedPct != null) parts.push(`cache saved ${summary.cacheSavedPct}%`);
+  return `Summary: ${parts.join('; ')}`;
+}
+
+/**
+ * Run every check that has what it needs, the way `all` does. The
+ * context fix is not applied here: the caller decides when, so the
+ * human report can print the diagnosis before writing .aiignore, and
+ * the JSON report can include the fix outcome. Call the returned
+ * `applyContextFix()` (memoized) when the fix should happen.
+ */
+export function runAll(options = {}) {
+  const root = options.root;
+  const checks = {};
+  const skipped = [];
+
+  const contextCheck = runContextCheck(root);
+  checks.context = contextCheck;
+  let contextFix = null;
+  const applyFix = () => {
+    if (!contextFix) contextFix = applyContextFix(contextCheck);
+    return contextFix;
+  };
+
+  if (options.commandName) checks.path = runPathCheck(options.commandName);
+  else skipped.push('path — pass --command <name>, for example: dev-diagnosis all --command node');
+
+  if (options.flakesDir) {
+    try {
+      checks.flakes = runFlakesCheck(options.flakesDir);
+    } catch (error) {
+      checks.flakes = { result: null, passed: false, verdict: `could not run: ${error.message}`, error: error.message };
+    }
+  } else {
+    skipped.push('flakes — pass --flakes <runs-dir>, for example: dev-diagnosis all --flakes examples/runs');
+  }
+
+  if (options.buildCommand && options.buildCommand.length > 0) {
+    try {
+      checks.cache = runCacheCheck({ buildCommand: options.buildCommand, cacheDir: options.cacheDir, cwd: root });
+    } catch (error) {
+      if (String(error.message).includes('no cache directory found')) {
+        // Nothing to measure is not a failure: report it as skipped so
+        // `all` on a repo without a build cache does not end in FAIL.
+        skipped.push('cache — no cache directory found in this project; pass --cache-dir <dir> to measure one');
+      } else {
+        checks.cache = { result: null, passed: false, verdict: `could not run: ${error.message}`, error: error.message };
+      }
+    }
+  } else {
+    skipped.push('cache — add -- <build-command>, for example: dev-diagnosis all -- node build.mjs');
+  }
+
+  const overall = Object.values(checks).every((check) => check.passed);
+  return {
+    root, checks, skipped, overall,
+    summary: buildSummary(checks, skipped),
+    applyContextFix: applyFix,
+  };
+}
+
+/**
+ * The `all --json` shape: each check's result (flakes limited by
+ * --top, cache without the build stdout), failed checks carrying their
+ * reason instead of null, plus the summary.
+ */
+export function allJson(run, top = null) {
+  return {
+    command: 'all',
+    root: run.root,
+    checks: Object.fromEntries(Object.entries(run.checks).map(([key, check]) => {
+      let result = check.result;
+      // Same --top split as the standalone flakes output: the embedded
+      // tests array is limited, totals stay whole-scan.
+      if (key === 'flakes' && result && top != null) {
+        result = { ...result, tests: result.tests.slice(0, top) };
+      }
+      // Same stdout strip as standalone `cache --json`: the raw result
+      // carries the build's full stdout from both runs.
+      if (key === 'cache' && result) result = stripCacheStdout(result);
+      // A check that could not run has no result: keep its reason in
+      // the JSON instead of emitting null, or a script consumer sees
+      // overall FAIL with no way to tell why.
+      if (result == null) result = { error: check.error || check.verdict };
+      return [key, result];
+    })),
+    skipped: run.skipped,
+    overall: run.overall ? 'PASS' : 'FAIL',
+    summary: run.summary,
+  };
+}

package/lib/context.mjs

@@ -56,6 +56,17 @@ export function formatBytes(bytes) {
   return `${value.toFixed(value >= 10 ? 1 : 2)} ${unit}`;
 }
 
+/**
+ * Rough token cost of the listed noise: about 4 bytes per token, the
+ * rule of thumb most tokenizers land near. It is an estimate, not a
+ * count — the label in the output says so. Returns null when there is
+ * no listed noise, so a clean repo does not claim a saving of zero.
+ */
+export function estimateTokens(bytes) {
+  if (!bytes || bytes <= 0) return null;
+  return Math.round(bytes / 4);
+}
+
 function noiseCategory(reason) {
   if (reason === 'lockfile') return 'lockfile';
   if (reason === 'local log file') return 'log';
@@ -398,36 +409,60 @@ export function scanDirectory(root, options = {}) {
   const files = [];
   walk(absolute, absolute, files, state);
 
-  const noise = [];
+  const allNoise = [];
   // One row per build-output directory, not one row per file inside it:
   // a dist/ with hundreds of files would otherwise flood the noise list
   // (and the score uses the summed bytes either way).
   const dirNoise = new Map();
   const review = [];
-  const suggestions = new Set();
+  const reviewSuggestions = new Set();
   for (const file of files) {
     const result = classifyPath(file.relativePath, file.size);
     if (result.noise) {
-      const item = { ...result.noise, bytes: file.size, path: file.relativePath.split(path.sep).join('/') };
+      const item = {
+        ...result.noise,
+        bytes: file.size,
+        path: file.relativePath.split(path.sep).join('/'),
+        suggestion: result.suggestion || null,
+      };
       if (item.label.endsWith('/')) {
         const existing = dirNoise.get(item.label);
         if (existing) existing.bytes += file.size;
         else {
-          const aggregated = { label: item.label, reason: item.reason, bytes: file.size, path: item.label };
+          const aggregated = { label: item.label, reason: item.reason, bytes: file.size, path: item.label, suggestion: result.suggestion || null };
           dirNoise.set(item.label, aggregated);
-          noise.push(aggregated);
+          allNoise.push(aggregated);
         }
       } else {
-        noise.push(item);
+        allNoise.push(item);
       }
-      if (result.suggestion) suggestions.add(result.suggestion);
     } else if (result.review) {
       review.push({ ...result.review, bytes: file.size, path: file.relativePath.split(path.sep).join('/') });
-      if (result.suggestion) suggestions.add(result.suggestion);
+      if (result.suggestion) reviewSuggestions.add(result.suggestion);
     }
   }
 
-  const scored = scoreNoise(noise, state.bytes);
+  const scored = scoreNoise(allNoise, state.bytes);
+  // Only noise in a category that actually lost points is reported. A
+  // 95 B lockfile in a 1.7 MB repo loses 0 points, so listing it as
+  // "noise to keep away" — with a fix suggestion — would contradict the
+  // PASS verdict on a 100/100 scan. The score itself still uses every
+  // noise byte; the filter only decides what is worth fixing.
+  const costly = new Set(scored.breakdown.filter((item) => item.lost > 0).map((item) => item.id));
+  const noise = allNoise
+    .filter((item) => costly.has(noiseCategory(item.reason)))
+    .map(({ suggestion, ...item }) => item);
+  const suggestions = new Set();
+  for (const item of allNoise) {
+    if (item.suggestion && costly.has(noiseCategory(item.reason))) suggestions.add(item.suggestion);
+  }
+  // Review suggestions are advisory only and are never part of
+  // `suggestions`, so --fix never writes them: a review item costs no
+  // score points, so writing its entry would fix nothing — and a
+  // basename pattern like `secret.js` would hide every same-named file
+  // in the repo, including harmless test fixtures. They are reported
+  // separately so the user can add them to .aiignore by hand.
+  const noiseBytes = noise.reduce((sum, item) => sum + item.bytes, 0);
   return {
     root: absolute,
     files: state.files,
@@ -436,10 +471,15 @@ export function scanDirectory(root, options = {}) {
     noise,
     review,
     suggestions: [...suggestions].sort(),
+    // Advisory only: --fix never writes these (see above).
+    reviewSuggestions: [...reviewSuggestions].sort(),
     score: scored.score,
     lost: scored.lost,
     breakdown: scored.breakdown,
     status: statusFor(scored.score),
+    // What the listed noise costs in tokens, at ~4 bytes per token
+    // (estimate, not a count); null when there is no listed noise.
+    estimatedTokens: estimateTokens(noiseBytes),
   };
 }
 

package/lib/mcp.mjs

@@ -0,0 +1,271 @@
+/**
+ * MCP server mode: `dev-diagnosis --mcp`.
+ *
+ * A stdio MCP server in the standard library only — the same code the
+ * CLI runs, served over JSON-RPC 2.0, one message per line. Agents
+ * connect with the usual config:
+ *
+ *   { "mcpServers": { "dev-diagnosis": { "command": "dev-diagnosis", "args": ["--mcp"] } } }
+ *
+ * Protocol: `initialize` (2024-11-05), `notifications/initialized`,
+ * `tools/list`, `tools/call`, `ping`. Each tool returns the same JSON
+ * the CLI's --json output produces, so an agent that already knows the
+ * CLI output knows the tool output too.
+ *
+ * Sandbox: `--sandbox <dir>` (alias `--root`) restricts every path the
+ * tools touch to that directory. A path outside it is rejected with a
+ * plain error before anything runs. The `path` tool takes only a
+ * command name, so it has nothing to sandbox and is always allowed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  UsageError, allJson, applyContextFixAndRescan, rescanContext, runAll,
+  runCacheCheck, runContextCheck, runFlakesCheck, runPathCheck,
+  stripCacheStdout,
+} from './checks.mjs';
+
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+const TOOLS = [
+  {
+    name: 'diagnose_context',
+    description: 'Find the files an AI coding agent should not read in a repo: build output, lockfiles, logs and oversized files. Returns a 0-100 score, the noise found, the token estimate, and the .aiignore suggestions that would fix it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Repo to scan (default: the sandbox root, or the current directory without one).' },
+        fix: { type: 'boolean', description: 'Write the .aiignore suggestions into <path>/.aiignore.' },
+      },
+    },
+  },
+  {
+    name: 'diagnose_path',
+    description: 'Diagnose why a CLI command is missing: one row per shell context (current, login, non-login, daemon-like), shadowed copies, toolchain installs, and a copy-paste fix.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'Command to look up, for example "node".' },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'diagnose_cache',
+    description: 'Time one build command cold (cache moved aside) and warm (cache present) and say whether the cache pays. The cache directory is restored afterwards.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project directory to run the build in (default: the sandbox root, or the current directory without one).' },
+        command: { type: 'array', items: { type: 'string' }, description: 'Build command as an argv array, for example ["node", "build.mjs"].' },
+        cacheDir: { type: 'string', description: 'Cache directory to measure (default: auto-detected under the project).' },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'diagnose_flakes',
+    description: 'Rank flaky tests from JUnit XML across CI runs, including passed-on-retry. Each subdirectory of the runs directory is one run; each *.xml file directly under it is a run of its own.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Runs directory to scan.' },
+        top: { type: 'integer', description: 'Show only the N highest-ranked flaky tests.' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'diagnose_all',
+    description: 'Run every check that has what it needs and print one unified report: context always runs, path runs with a command name, flakes with a runs directory, cache with a build command. Checks without their input are listed as skipped.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Repo to diagnose (default: the sandbox root, or the current directory without one).' },
+        command: { type: 'string', description: 'Command name for the path check, for example "node".' },
+        flakesDir: { type: 'string', description: 'JUnit runs directory for the flakes check.' },
+        buildCommand: { type: 'array', items: { type: 'string' }, description: 'Build command as an argv array for the cache check.' },
+        cacheDir: { type: 'string', description: 'Cache directory to measure (default: auto-detected).' },
+        fix: { type: 'boolean', description: 'Write the context check .aiignore suggestions.' },
+        top: { type: 'integer', description: 'Show only the N highest-ranked flaky tests.' },
+      },
+    },
+  },
+];
+
+/** Resolve a tool argument to an absolute path inside the sandbox, or throw. */
+export function resolveInSandbox(sandbox, value, label) {
+  if (value == null || value === '') return sandbox || process.cwd();
+  const resolved = path.resolve(sandbox || process.cwd(), value);
+  if (!sandbox) return resolved;
+  const root = path.resolve(sandbox);
+  if (resolved === root) return resolved;
+  const rel = path.relative(root, resolved);
+  if (rel.startsWith(`..${path.sep}`) || rel === '..' || path.isAbsolute(rel)) {
+    throw new Error(`${label} is outside the sandbox (${sandbox}): ${value}`);
+  }
+  return resolved;
+}
+
+function textResult(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: false };
+}
+
+function errorResult(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+function callTool(name, args, sandbox) {
+  const input = args && typeof args === 'object' ? args : {};
+  switch (name) {
+    case 'diagnose_context': {
+      const target = resolveInSandbox(sandbox, input.path, 'path');
+      const check = runContextCheck(target);
+      // With fix, the tool answers with the post-fix scan — an agent
+      // reading the result needs to know whether the repo is fixed
+      // now, not what it scored before the fix.
+      if (input.fix) return textResult(applyContextFixAndRescan(check).result);
+      return textResult(check.result);
+    }
+    case 'diagnose_path': {
+      if (!input.command) throw new UsageError('diagnose_path needs a command');
+      return textResult(runPathCheck(input.command).result);
+    }
+    case 'diagnose_cache': {
+      if (!Array.isArray(input.command) || input.command.length === 0) {
+        throw new UsageError('diagnose_cache needs a build command array');
+      }
+      const root = resolveInSandbox(sandbox, input.path, 'path');
+      const cacheDir = input.cacheDir
+        ? resolveInSandbox(sandbox, path.resolve(root, input.cacheDir), 'cacheDir')
+        : undefined;
+      const check = runCacheCheck({ buildCommand: input.command, cacheDir, cwd: root });
+      return textResult(stripCacheStdout(check.result));
+    }
+    case 'diagnose_flakes': {
+      if (!input.path) throw new UsageError('diagnose_flakes needs a runs directory');
+      const dir = resolveInSandbox(sandbox, input.path, 'path');
+      const check = runFlakesCheck(dir);
+      const out = input.top != null ? { ...check.result, tests: check.result.tests.slice(0, input.top) } : check.result;
+      return textResult(out);
+    }
+    case 'diagnose_all': {
+      const root = resolveInSandbox(sandbox, input.path, 'path');
+      // flakesDir is relative to the sandbox (or cwd), like the CLI's
+      // --flakes is relative to the process cwd — not to the repo root.
+      const flakesDir = input.flakesDir
+        ? resolveInSandbox(sandbox, input.flakesDir, 'flakesDir')
+        : null;
+      // cacheDir is relative to the repo root, like the CLI's
+      // --cache-dir.
+      const cacheDir = input.cacheDir
+        ? resolveInSandbox(sandbox, path.resolve(root, input.cacheDir), 'cacheDir')
+        : null;
+      const run = runAll({
+        root,
+        commandName: input.command || null,
+        flakesDir,
+        buildCommand: Array.isArray(input.buildCommand) && input.buildCommand.length > 0 ? input.buildCommand : null,
+        cacheDir,
+      });
+      if (input.fix) {
+        run.applyContextFix();
+        rescanContext(run);
+      }
+      return textResult(allJson(run, input.top != null ? input.top : null));
+    }
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+function handleMessage(message, sandbox, version) {
+  if (message == null || typeof message !== 'object' || Array.isArray(message)) {
+    return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid Request' } };
+  }
+  const { method, id, params } = message;
+  // A notification (no id) never gets a response.
+  const isNotification = id === undefined;
+  if (typeof method !== 'string') {
+    return isNotification ? null : { jsonrpc: '2.0', id: id ?? null, error: { code: -32600, message: 'Invalid Request' } };
+  }
+  if (method.startsWith('notifications/')) return null;
+  if (isNotification) return null;
+
+  const respond = (result) => ({ jsonrpc: '2.0', id, result });
+  const fail = (code, text) => ({ jsonrpc: '2.0', id, error: { code, message: text } });
+
+  try {
+    switch (method) {
+      case 'initialize':
+        return respond({
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'dev-diagnosis', version },
+        });
+      case 'ping':
+        return respond({});
+      case 'tools/list':
+        return respond({ tools: TOOLS });
+      case 'tools/call': {
+        if (!params || typeof params.name !== 'string') return fail(-32602, 'tools/call needs a tool name');
+        try {
+          return respond(callTool(params.name, params.arguments, sandbox));
+        } catch (error) {
+          // A tool failure is a tool result with isError, not a
+          // JSON-RPC error: the call itself worked, the check did not.
+          return respond(errorResult(error.message));
+        }
+      }
+      default:
+        return fail(-32601, `Method not found: ${method}`);
+    }
+  } catch (error) {
+    return fail(-32603, error.message);
+  }
+}
+
+/**
+ * Serve MCP over stdio until stdin closes. One JSON message per line;
+ * a malformed line gets a -32700 parse error and the server keeps going.
+ * Resolves when stdin ends; never throws for a bad message.
+ */
+export function runMcpServer(options = {}) {
+  const sandbox = options.sandbox ? path.resolve(options.sandbox) : null;
+  const version = options.version || '0.2.0';
+  if (sandbox) {
+    let stat;
+    try { stat = fs.statSync(sandbox); } catch { stat = null; }
+    if (!stat || !stat.isDirectory()) throw new Error(`sandbox is not a directory: ${sandbox}`);
+  }
+  let buffer = '';
+  const write = (payload) => process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).replace(/\r$/, '');
+      buffer = buffer.slice(newline + 1);
+      if (line.trim() === '') {
+        newline = buffer.indexOf('\n');
+        continue;
+      }
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        newline = buffer.indexOf('\n');
+        continue;
+      }
+      const response = handleMessage(message, sandbox, version);
+      if (response) write(response);
+      newline = buffer.indexOf('\n');
+    }
+  });
+  return new Promise((resolve) => {
+    process.stdin.on('end', resolve);
+    process.stdin.resume();
+  });
+}

package/lib/report.mjs

@@ -16,3 +16,15 @@ export function formatMs(ms) {
   if (ms < 1000) return `${Math.round(ms)} ms`;
   return `${(ms / 1000).toFixed(2)} s`;
 }
+
+/** Short form for a token estimate: 420, 4.2k, 1.2M. */
+export function formatTokens(tokens) {
+  if (tokens == null) return '—';
+  if (tokens < 1000) return String(tokens);
+  if (tokens < 1000000) {
+    const value = tokens / 1000;
+    return `${value >= 100 ? Math.round(value) : value.toFixed(1).replace(/\.0$/, '')}k`;
+  }
+  const value = tokens / 1000000;
+  return `${value >= 100 ? Math.round(value) : value.toFixed(1).replace(/\.0$/, '')}M`;
+}