readfirst 0.4.0 → 0.6.0

package/README.md

@@ -24,6 +24,7 @@ Commit `.readfirst/map.json`. From then on:
 npx readfirst read <file>...     # before changing files
 npx readfirst diff               # everything your branch changed since main
 npx readfirst diff --json        # the same, for tools and agents
+npx readfirst verify             # run the checks the map lists for everything your branch changed (exit 1 if one fails)
 npx readfirst fix                # after moving code: place new files, drop patterns for deleted ones
 ```
 
@@ -33,7 +34,8 @@ npx readfirst fix                # after moving code: place new files, drop patt
 
 ```md
 Before changing a file, run `npx readfirst read <file>` and follow what it says: keep the rules, read the risks, run the
-checks it lists. Before you finish, run `npx readfirst diff` and run every check it lists.
+checks it lists. Before you finish, run `npx readfirst verify`: it runs the checks the map lists for everything you
+changed; fix what fails.
 When you learn something a newcomer would get wrong, add it as a risk in .readfirst/map.json.
 ```
 
@@ -61,6 +63,31 @@ Labels for yourself: `npx readfirst prompt --labels ko` (or `en`, ...) gives you
 to the code. The view then has a switch between the two. `.readfirst/local/` is added to `.git/info/exclude`, so labels
 stay on your machine and never reach the team's map.
 
+### Any agent, through MCP
+
+`npx readfirst mcp` is an MCP server on stdio with three tools: `read_list` (files → what to read and check before
+changing them), `changed_read_list` (the same for everything changed on the branch) and `check_map`. It answers from the
+checkout as it is and writes nothing.
+
+```sh
+claude mcp add readfirst -- npx --yes readfirst mcp          # Claude Code
+```
+
+```json
+// Cursor: .cursor/mcp.json · Windsurf: ~/.codeium/windsurf/mcp_config.json
+{ "mcpServers": { "readfirst": { "command": "npx", "args": ["--yes", "readfirst", "mcp"] } } }
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.readfirst]
+command = "npx"
+args = ["--yes", "readfirst", "mcp"]
+```
+
+The server reads the git repository it is started in. If your agent starts it elsewhere, add `"--root", "/path/to/repo"`
+to the arguments.
+
 ## On every pull request (GitHub Action)
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "What to read and check before you (or your AI agent) change a file: project rules, risks and tests tied to code.",
   "type": "module",
   "license": "MIT",

package/src/cli.mjs

@@ -6,10 +6,12 @@
 //   readfirst fix                  place new files and drop patterns for deleted ones, then check
 //   readfirst read <file>...       the read list for files you are about to change
 //   readfirst diff [--base <ref>]  the read list for the files changed since <ref> (default: origin/main, else main)
+//   readfirst verify [--base <ref>] run the checks the read list names for the changed files; exit 1 if one fails
 //   readfirst hook [--install]     a Claude Code PreToolUse hook: the read list for the file an Edit or Write is about to change
+//   readfirst mcp                  an MCP server on stdio: read_list, changed_read_list and check_map as tools for any agent
 //   readfirst view [--out <file>]  the map as a city in one HTML page (default .readfirst/local/view.html)
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, relative } from 'node:path';
@@ -18,6 +20,7 @@ import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
+import { mcpHandler, serveMcp } from './mcp.mjs';
 import { cityData, viewHtmlCity } from './view-city.mjs';
 import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
@@ -29,11 +32,13 @@ const HELP = `readfirst — what to read and check before changing a file
   readfirst fix                  place new files, drop patterns for deleted ones
   readfirst read <file>...       read list for files you are about to change
   readfirst diff [--base <ref>]  read list for files changed since <ref>
+  readfirst verify [--base <ref>]  run the checks for the files changed since <ref> (--dry-run lists them)
   readfirst hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json)
   readfirst view [--out <file>]  the map as a city in one HTML page
+  readfirst mcp                  MCP server on stdio for Cursor, Codex, Windsurf and other agents
   readfirst prompt --labels <lang>  brief for your agent to write personal labels for the view (e.g. ko, en)
 
-Options: --root <dir>, --json, --limit <n>, --force (init: replace the map),
+Options: --root <dir>, --json, --limit <n>, --timeout <s> (verify, per check; default 900), --force (init: replace the map),
          --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules)`;
 
 function parse(argv) {
@@ -44,6 +49,7 @@ function parse(argv) {
     else if (a === '--force') args.force = true;
     else if (a === '--agent') args.agent = true;
     else if (a === '--install') args.install = true;
+    else if (a === '--dry-run') args.dryRun = true;
     else if (a === '-h' || a === '--help') args.help = true;
     else if (a.startsWith('--')) { const v = argv[++i]; if (v === undefined) throw new Error(`${a} needs a value`); args[a.slice(2)] = v; }
     else args._.push(a);
@@ -87,7 +93,7 @@ function loadMapLenient(root, files, io) {
 
 // The one line that makes a coding agent use readfirst, added to the agent notes the project already has (CLAUDE.md,
 // AGENTS.md, .cursorrules), or to a new AGENTS.md when it has none. A file that already mentions readfirst is left alone.
-export const AGENT_LINE = 'Before changing a file, run `npx readfirst read <file>` and follow what it says: keep the rules, read the risks, run the checks it lists. Before you finish, run `npx readfirst diff` and run every check it lists. When you learn something a newcomer would get wrong, add it as a risk in .readfirst/map.json.';
+export const AGENT_LINE = 'Before changing a file, run `npx readfirst read <file>` and follow what it says: keep the rules, read the risks, run the checks it lists. Before you finish, run `npx readfirst verify`: it runs the checks the map lists for everything you changed; fix what fails. When you learn something a newcomer would get wrong, add it as a risk in .readfirst/map.json.';
 function addAgentLine(root) {
   const notes = ['CLAUDE.md', 'AGENTS.md', '.cursorrules'].filter((f) => existsSync(join(root, f)));
   const wrote = [];
@@ -104,7 +110,10 @@ function addAgentLine(root) {
 function changedFiles(root, base) {
   const ref = base ?? ['origin/main', 'main', 'origin/master', 'master'].find((r) => { try { git(root, 'rev-parse', '--verify', '--quiet', r); return true; } catch { return false; } });
   if (!ref) throw new Error('no base branch found: pass --base <ref>');
-  const since = git(root, 'merge-base', ref, 'HEAD').trim();
+  let since;
+  try { since = git(root, 'merge-base', ref, 'HEAD').trim(); } catch {
+    throw new Error(`cannot find where this branch left ${ref}, often because the clone is shallow: fetch more history (git fetch --deepen=100, or fetch-depth: 0 in actions/checkout) or pass --base <ref>`);
+  }
   const names = new Set([
     ...git(root, 'diff', '--name-only', since).split('\n'),
     ...git(root, 'ls-files', '--others', '--exclude-standard').split('\n'),
@@ -112,6 +121,37 @@ function changedFiles(root, base) {
   return { ref, files: [...names].sort() };
 }
 
+// Runs each check with the shell in the repository root, one after another, and keeps the end of the output of the ones
+// that fail. readfirst writes nothing itself; the commands are the map's own and may write, as they would by hand.
+export function verifyChecks(root, checks, { dryRun = false, timeout = 900, progress = () => {} } = {}) {
+  const out = [];
+  for (const c of checks) {
+    const row = { run: c.run, why: c.why, for: c.for ?? [] };
+    if (dryRun) { out.push({ ...row, status: 'listed' }); continue; }
+    progress(`running ${c.run}\n`);
+    const started = Date.now();
+    const r = spawnSync(c.run, { cwd: root, shell: true, encoding: 'utf8', timeout: timeout * 1000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, CI: process.env.CI ?? '1' } });
+    const seconds = Math.round((Date.now() - started) / 100) / 10;
+    const timedOut = r.error?.code === 'ETIMEDOUT';
+    const status = timedOut ? 'timeout' : r.status === 0 ? 'pass' : 'fail';
+    const tail = status === 'pass' ? undefined : `${r.stdout ?? ''}${r.stderr ?? ''}${r.error && !timedOut ? r.error.message : ''}`.trimEnd().split('\n').slice(-30).join('\n');
+    out.push({ ...row, status, code: r.status, seconds, ...(tail !== undefined ? { output: tail } : {}) });
+  }
+  return out;
+}
+
+function verifyText(report, dryRun) {
+  if (!report.files.length) return `no files changed since ${report.base}: nothing to verify.\n`;
+  if (!report.checks.length) return `${report.files.length} changed file(s) since ${report.base}; the map lists no checks for them.\n`;
+  if (dryRun) return `checks for ${report.files.length} changed file(s) since ${report.base}:\n${report.checks.map((c) => `- ${c.run}${c.why ? ` — ${c.why}` : ''}`).join('\n')}\n`;
+  const mark = { pass: 'pass', fail: 'FAIL', timeout: 'TIMEOUT' };
+  let s = `\nverify: ${report.checks.length} check(s) for ${report.files.length} changed file(s) since ${report.base}\n`;
+  for (const c of report.checks) s += `${mark[c.status]}  ${c.run}  (${c.seconds}s)\n`;
+  for (const c of report.checks.filter((x) => x.status !== 'pass')) s += `\n--- ${c.run} (${c.status}${c.code != null ? `, exit ${c.code}` : ''}); last lines:\n${c.output}\n`;
+  s += report.ok ? '\nall checks passed.\n' : `\n${report.checks.filter((c) => c.status !== 'pass').length} check(s) failed.\n`;
+  return s;
+}
+
 // The read list as a few factual lines for an agent's context: rules, risks and checks, nothing else.
 export function brief(list) {
   const lines = [];
@@ -258,5 +298,29 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     io.out(args.json ? `${JSON.stringify(list, null, 2)}\n` : `${toMarkdown(list)}\n`);
     return 0;
   }
+  if (cmd === 'mcp') {
+    const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const run = (argv) => {
+      let out = ''; let err = ''; let code;
+      try { code = main(['--root', root, ...argv], { out: (s) => { out += s; }, err: (s) => { err += s; } }); } catch (e) { code = 2; err += e.message; }
+      return { code, out, err };
+    };
+    serveMcp({ handle: mcpHandler({ run, version }), input: process.stdin, output: process.stdout });
+    return 0;
+  }
+  if (cmd === 'verify') {
+    const map = loadMapLenient(root, files, io);
+    const changed = changedFiles(root, args.base);
+    const list = changed.files.length
+      ? readList({ map, files, imports: importEdges(files, readText(root)), targets: changed.files, commit, limit: 1 })
+      : emptyList(commit);
+    const timeout = Number(args.timeout ?? 900);
+    if (!(timeout > 0)) throw new Error('--timeout needs a number of seconds above 0');
+    const result = verifyChecks(root, list.checks, { dryRun: args.dryRun, timeout, progress: args.json ? () => {} : io.out });
+    const report = { format: 'readfirst/verify@1', commit, base: changed.ref, files: changed.files, ok: result.every((c) => c.status === 'pass' || c.status === 'listed'), checks: result };
+    if (args.json) io.out(`${JSON.stringify(report, null, 2)}\n`);
+    else io.out(verifyText(report, args.dryRun));
+    return report.ok ? 0 : 1;
+  }
   throw new Error(`unknown command ${cmd}\n\n${HELP}`);
 }

package/src/mcp.mjs

@@ -0,0 +1,77 @@
+// readfirst as an MCP server over stdio, so any agent that speaks MCP (Cursor, Codex, Windsurf, Claude Code...) can ask
+// what to read before it changes a file. JSON-RPC 2.0, one message per line, written by hand: no dependencies.
+// Every tool call runs the same code as the command line, on the checkout as it is at that moment, and writes nothing.
+const VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const TOOLS = [
+  {
+    name: 'read_list',
+    description: 'What to read and check before changing these files: the project rules and risks that apply, the checks to run, the tests that reach the code and the files that use it. Call it before editing.',
+    inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'paths relative to the repository root' } }, required: ['files'] },
+    args: (a) => {
+      if (!Array.isArray(a.files) || !a.files.length || a.files.some((f) => typeof f !== 'string' || !f)) throw new Error('files must be a non-empty list of paths');
+      return ['read', ...a.files];
+    },
+  },
+  {
+    name: 'changed_read_list',
+    description: 'The same read list for every file changed on this branch since the base (default origin/main, else main). Call it before finishing, then run the checks it lists.',
+    inputSchema: { type: 'object', properties: { base: { type: 'string', description: 'git ref to compare against' } } },
+    args: (a) => ['diff', ...(typeof a.base === 'string' && a.base ? ['--base', a.base] : [])],
+  },
+  {
+    name: 'check_map',
+    description: 'Whether .readfirst/map.json still covers the code: files in no group, patterns that match nothing, broken rules.',
+    inputSchema: { type: 'object', properties: {} },
+    args: () => ['check'],
+  },
+];
+
+// One request in, one response out (null for notifications). run(argv) runs the CLI and returns { code, out, err }.
+export function mcpHandler({ run, version }) {
+  return (msg) => {
+    const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code, message } });
+    if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return fail(-32600, 'invalid request');
+    if (msg.id === undefined) return null; // notifications (initialized, cancelled) need no answer
+    if (msg.method === 'initialize') {
+      const asked = msg.params?.protocolVersion;
+      return reply({
+        protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+        capabilities: { tools: {} },
+        serverInfo: { name: 'readfirst', version },
+        instructions: 'Before changing a file, call read_list with it and follow what it says. Before you finish, call changed_read_list and run the checks it lists (or run `npx readfirst verify`).',
+      });
+    }
+    if (msg.method === 'ping') return reply({});
+    if (msg.method === 'tools/list') return reply({ tools: TOOLS.map(({ args, ...t }) => t) });
+    if (msg.method === 'tools/call') {
+      const tool = TOOLS.find((t) => t.name === msg.params?.name);
+      if (!tool) return fail(-32602, `unknown tool ${msg.params?.name}`);
+      let r;
+      try { r = run(tool.args(msg.params?.arguments ?? {})); } catch (e) { r = { code: 2, out: '', err: e.message }; }
+      const text = [r.out.trimEnd(), r.err.trimEnd()].filter(Boolean).join('\n\n') || '(nothing)';
+      return reply({ content: [{ type: 'text', text }], isError: r.code === 2 });
+    }
+    return fail(-32601, `unknown method ${msg.method}`);
+  };
+}
+
+// Reads newline-delimited JSON-RPC from input and writes answers to output until input ends.
+export function serveMcp({ handle, input, output }) {
+  let buf = '';
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buf += chunk;
+    let nl;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } })}\n`); continue; }
+      const res = handle(msg);
+      if (res) output.write(`${JSON.stringify(res)}\n`);
+    }
+  });
+}