readfirst 0.2.0 → 0.3.0

package/README.md

@@ -13,9 +13,9 @@ No server, no account, no model calls. It reads your git checkout and `.readfirs
 ## Start
 
 ```sh
-npx readfirst init      # first map from your folders: one group per folder, media folders ignored
-npx readfirst prompt    # a brief for your coding agent to fill in titles, checks, risks and rules
-npx readfirst check     # every tracked file is in exactly one group (or ignored); rules point at real files
+npx readfirst init --agent   # first map from your folders, checks from your scripts, plus the line for CLAUDE.md / AGENTS.md
+npx readfirst prompt         # a brief for your coding agent to fill in titles, checks, risks and rules
+npx readfirst check          # every tracked file is in exactly one group (or ignored); rules point at real files
 ```
 
 Commit `.readfirst/map.json`. From then on:
@@ -29,7 +29,7 @@ npx readfirst fix                # after moving code: place new files, drop patt
 
 ### Tell your agent to use it
 
-Add this to `CLAUDE.md`, `AGENTS.md` or `.cursorrules`:
+`init --agent` adds this to your `CLAUDE.md`, `AGENTS.md` or `.cursorrules` (or a new `AGENTS.md`); or add it yourself:
 
 ```md
 Before changing a file, run `npx readfirst read <file>` and follow what it says: keep the rules, read the risks, run the
@@ -37,6 +37,15 @@ checks it lists. Before you finish, run `npx readfirst diff` and run every check
 When you learn something a newcomer would get wrong, add it as a risk in .readfirst/map.json.
 ```
 
+### Or let Claude Code pick it up by itself
+
+```sh
+npx readfirst hook --install
+```
+
+adds a hook to `.claude/settings.json`. Before each Edit or Write, Claude Code gets the rules, risks and checks for that
+file as context, once per file per session. Nothing to remember, and the edit is never blocked.
+
 ## On every pull request (GitHub Action)
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.2.0",
+  "version": "0.3.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

@@ -1,14 +1,16 @@
 // readfirst: what to read and check before changing a file.
-//   readfirst init                 write a first .readfirst/map.json from the file tree
+//   readfirst init [--agent]       write a first .readfirst/map.json from the file tree (and the agent-notes line)
 //   readfirst prompt               the brief for a coding agent to fill in titles, checks, risks and rules
 //   readfirst check                the map covers every tracked file and is well formed
 //   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 hook [--install]     a Claude Code PreToolUse hook: the read list for the file an Edit or Write is about to change
 // Options: --root <dir> (default: the current git repository), --json, --limit <n>.
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative } from 'node:path';
 import { importEdges } from './imports.mjs';
 import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
@@ -16,14 +18,16 @@ import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
 const HELP = `readfirst — what to read and check before changing a file
 
-  readfirst init                 write a first ${MAP_PATH} from the file tree
+  readfirst init [--agent]       write a first ${MAP_PATH} from the file tree
   readfirst prompt               brief for your coding agent to fill in the map
   readfirst check                check the map covers every tracked 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 hook [--install]     Claude Code hook: the read list before each edit (--install adds it to .claude/settings.json)
 
-Options: --root <dir>, --json, --limit <n>, --force (init: replace the map)`;
+Options: --root <dir>, --json, --limit <n>, --force (init: replace the map),
+         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules)`;
 
 function parse(argv) {
   const args = { _: [], json: false };
@@ -31,6 +35,8 @@ function parse(argv) {
     const a = argv[i];
     if (a === '--json') args.json = true;
     else if (a === '--force') args.force = true;
+    else if (a === '--agent') args.agent = true;
+    else if (a === '--install') args.install = 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);
@@ -60,6 +66,33 @@ function loadMap(root, files) {
   return assertMap(readMapFile(root), files);
 }
 
+// read and diff keep working while the map is only behind the code (new files in no group, patterns for deleted files):
+// they warn and point at `readfirst fix`. A map that is broken in itself still stops them.
+function loadMapLenient(root, files, io) {
+  const map = readMapFile(root);
+  const broken = mapProblems(map, files, { placement: false });
+  if (broken.length) throw new Error(`${MAP_PATH} has problems:\n- ${broken.join('\n- ')}`);
+  const behind = mapProblems(map, files);
+  if (behind.length) io.err(`note: ${MAP_PATH} is behind the code (${behind.length} problem${behind.length > 1 ? 's' : ''}); \`readfirst fix\` repairs most of it.\n`);
+  return map;
+}
+
+// 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.';
+function addAgentLine(root) {
+  const notes = ['CLAUDE.md', 'AGENTS.md', '.cursorrules'].filter((f) => existsSync(join(root, f)));
+  const wrote = [];
+  for (const f of notes.length ? notes : ['AGENTS.md']) {
+    const at = join(root, f);
+    const now = existsSync(at) ? readFileSync(at, 'utf8') : '';
+    if (/readfirst/u.test(now)) continue;
+    writeFileSync(at, `${now}${now && !now.endsWith('\n') ? '\n' : ''}${now ? '\n' : ''}${AGENT_LINE}\n`);
+    wrote.push(f);
+  }
+  return wrote;
+}
+
 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>');
@@ -71,10 +104,72 @@ function changedFiles(root, base) {
   return { ref, files: [...names].sort() };
 }
 
-export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(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 = [];
+  for (const r of list.rules) lines.push(`Rule ${r.id}: ${r.rule}${r.why ? ` (why: ${r.why})` : ''}`);
+  for (const r of list.risks) lines.push(`Risk: ${r.text}`);
+  for (const c of list.checks) lines.push(`Check to run after the change: ${c.run}${c.why ? ` (${c.why})` : ''}`);
+  if (list.tests.length) lines.push(`Tests that reach this file: ${list.tests.slice(0, 5).map((t) => t.path).join(', ')}`);
+  return lines;
+}
+
+// Claude Code PreToolUse hook. Reads the hook's JSON on stdin; for an Edit, Write or MultiEdit of a file the map covers,
+// prints the read list as additionalContext, once per file per session. Never blocks the edit: any problem means no output.
+export function runHook(input, { now = Date.now(), stateDir = tmpdir() } = {}) {
+  try {
+    const event = JSON.parse(input);
+    const file = event.tool_input?.file_path;
+    if (!file || !/^(?:Edit|Write|MultiEdit)$/u.test(event.tool_name ?? '')) return null;
+    const cwd = event.cwd ?? process.cwd();
+    const root = git(cwd, 'rev-parse', '--show-toplevel').trim();
+    const path = (isAbsolute(file) ? relative(root, file) : file).replace(/\\/gu, '/');
+    if (path.startsWith('..') || path === MAP_PATH || !existsSync(join(root, MAP_PATH))) return null;
+    const seenAt = join(stateDir, `readfirst-hook-${String(event.session_id ?? 'none').replace(/[^\w-]/gu, '')}.json`);
+    let seen = {};
+    try { seen = JSON.parse(readFileSync(seenAt, 'utf8')); } catch { seen = {}; }
+    if (seen[path] && now - seen[path] < 6 * 3600_000) return null;
+    const files = repoFiles(root);
+    const map = readMapFile(root);
+    if (mapProblems(map, files, { placement: false }).length) return null;
+    const list = readList({ map, files: files.includes(path) ? files : [...files, path].sort(), imports: importEdges(files, readText(root)), targets: [path], limit: 10 });
+    const lines = brief(list);
+    seen[path] = now;
+    try { writeFileSync(seenAt, JSON.stringify(seen)); } catch { /* best effort */ }
+    if (!lines.length) return null;
+    const shown = lines.slice(0, 12);
+    if (lines.length > shown.length) shown.push(`${lines.length - shown.length} more in \`npx readfirst read ${path}\``);
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: `readfirst notes for ${path} (from ${MAP_PATH}):\n- ${shown.join('\n- ')}` } });
+  } catch {
+    return null;
+  }
+}
+
+export const HOOK_COMMAND = 'npx --yes readfirst hook';
+// Adds the hook to the project's .claude/settings.json, keeping everything already there.
+export function installHook(root) {
+  const at = join(root, '.claude', 'settings.json');
+  let settings = {};
+  if (existsSync(at)) {
+    try { settings = JSON.parse(readFileSync(at, 'utf8')); } catch { throw new Error('.claude/settings.json is not valid JSON; fix it first'); }
+  }
+  const pre = ((settings.hooks ??= {}).PreToolUse ??= []);
+  if (pre.some((m) => (m.hooks ?? []).some((h) => /readfirst hook/u.test(h.command ?? '')))) return false;
+  pre.push({ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 15 }] });
+  mkdirSync(join(root, '.claude'), { recursive: true });
+  writeFileSync(at, `${JSON.stringify(settings, null, 2)}\n`);
+  return true;
+}
+
+export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s) => process.stderr.write(s) }, stdin = () => readFileSync(0, 'utf8')) {
   const args = parse(argv);
   const [cmd, ...rest] = args._;
   if (args.help || !cmd) { io.out(`${HELP}\n`); return cmd || args.help ? 0 : 2; }
+  if (cmd === 'hook' && !args.install) {
+    const out = runHook(stdin());
+    if (out) io.out(`${out}\n`);
+    return 0;
+  }
   const root = args.root ?? git(process.cwd(), 'rev-parse', '--show-toplevel').trim();
   const files = repoFiles(root);
   const commit = (() => { try { return git(root, 'rev-parse', 'HEAD').trim(); } catch { return null; } })();
@@ -82,10 +177,17 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
   if (cmd === 'init') {
     const at = join(root, MAP_PATH);
     if (existsSync(at) && args.force !== true) throw new Error(`${MAP_PATH} already exists (pass --force to replace it)`);
-    const map = draftMap(files);
+    const map = draftMap(files, readText(root));
     mkdirSync(join(root, '.readfirst'), { recursive: true });
     writeFileSync(at, `${JSON.stringify(map, null, 2)}\n`);
-    io.out(`wrote ${MAP_PATH}: ${map.groups.length} groups, ${map.ignore.length} ignored folders.\nNext: run \`readfirst prompt\` and give the brief to your coding agent, or fill in titles, checks, risks and rules by hand.\n`);
+    const checks = map.groups.find((g) => g.checks.length)?.checks ?? [];
+    io.out(`wrote ${MAP_PATH}: ${map.groups.length} groups${checks.length ? `, checks found: ${checks.map((c) => c.run).join(', ')}` : ''}.\n`);
+    if (args.agent) {
+      const wrote = addAgentLine(root);
+      io.out(wrote.length ? `added the read-first line to ${wrote.join(', ')}.\n` : 'your agent notes already mention readfirst.\n');
+      io.out('Using Claude Code? `readfirst hook --install` hands it the read list automatically before each edit.\n');
+    }
+    io.out(`Next: run \`readfirst prompt\` and give the brief to your coding agent, or fill in titles, checks, risks and rules by hand.${args.agent ? '' : '\nTip: `readfirst init --agent` also adds the one line your coding agent needs to CLAUDE.md or AGENTS.md.'}\n`);
     return 0;
   }
   if (cmd === 'prompt') {
@@ -98,6 +200,10 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     else io.out(problems.length ? `${MAP_PATH} has ${problems.length} problem(s):\n- ${problems.join('\n- ')}\n` : `${MAP_PATH} is good: ${files.length} files.\n`);
     return problems.length ? 1 : 0;
   }
+  if (cmd === 'hook') {
+    io.out(installHook(root) ? 'added the readfirst hook to .claude/settings.json: Claude Code now sees the read list before each edit.\n' : '.claude/settings.json already has the readfirst hook.\n');
+    return 0;
+  }
   if (cmd === 'fix') {
     const { map, changes, problems } = fixMap(readMapFile(root), files);
     if (changes.length) writeFileSync(join(root, MAP_PATH), `${JSON.stringify(map, null, 2)}\n`);
@@ -109,7 +215,7 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     return problems.length ? 1 : 0;
   }
   if (cmd === 'read' || cmd === 'diff') {
-    const map = loadMap(root, files);
+    const map = loadMapLenient(root, files, io);
     let targets = rest;
     if (cmd === 'diff') {
       const changed = changedFiles(root, args.base);

package/src/map.mjs

@@ -43,7 +43,7 @@ const checkList = (v, where, p) => {
 };
 
 // Problems with the map against the list of tracked files. An empty list means the map is good.
-export function mapProblems(map, files) {
+export function mapProblems(map, files, { placement = true } = {}) {
   const p = [];
   if (!isRecord(map)) return ['map: a JSON object'];
   only(map, ['format', 'groups', 'rules', 'ignore'], 'map', p);
@@ -90,7 +90,7 @@ export function mapProblems(map, files) {
     }
   }
   if (map.ignore !== undefined) strings(map.ignore, 'ignore', p);
-  if (p.length) return p;
+  if (p.length || !placement) return p;
 
   // Placement: each tracked file in exactly one group or ignored; each group pattern matches something.
   const ignored = matcher(map.ignore ?? []);
@@ -121,7 +121,7 @@ export const groupOf = (map, path) => map.groups.find((g) => matcher(g.files)(pa
 // that code belong there; "ignore" is left for a person to fill with what nothing depends on. Titles and risks are left
 // for a person or an agent to write.
 const MEDIA = /\.(?:png|jpe?g|gif|webp|svg|ico|mp3|wav|ogg|m4a|flac|mp4|webm|mov|woff2?|ttf|otf|eot|glb|gltf|fbx|blend|zip|pdf)$/iu;
-export function draftMap(files) {
+export function draftMap(files, read = () => null) {
   const nested = new Set(['src', 'lib', 'app', 'packages', 'apps']);
   const keyOf = (path) => {
     const parts = path.split('/');
@@ -133,6 +133,7 @@ export function draftMap(files) {
   const groups = new Map();
   const ignore = new Set();
   const byFolder = new Map();
+  const projectChecks = draftChecks(files, read);
   for (const f of files) {
     if (f === MAP_PATH) continue;
     const { key, pattern } = keyOf(f);
@@ -148,7 +149,7 @@ export function draftMap(files) {
     const title = media
       ? `TODO: what loads the media files in ${slot.pattern} (binary, not read)`
       : `TODO: what ${slot.pattern ?? 'the top-level files'} ${slot.pattern ? 'is' : 'are'} for`;
-    groups.set(id, { id, title, files: prev ? [...prev.files, ...patterns] : patterns, checks: [], risks: [] });
+    groups.set(id, { id, title, files: prev ? [...prev.files, ...patterns] : patterns, checks: media ? [] : projectChecks, risks: [] });
   }
   // A nested pattern ("src/a/**") and the parent's loose files ("src/x.js") must not overlap; loose files under a nested root
   // become their own group.
@@ -217,3 +218,27 @@ export function fixMap(map, files) {
   }
   return { map: out, changes, problems: mapProblems(out, files) };
 }
+
+// The project's own check commands, found in its build files, so a first map already says what to run. Repository-wide
+// on purpose: narrowing a check to the group it covers is left to a person or an agent.
+export function draftChecks(files, read = () => null) {
+  const has = new Set(files);
+  const out = [];
+  const add = (run, why) => { if (!out.some((c) => c.run === run)) out.push({ run, why }); };
+  if (has.has('package.json')) {
+    let scripts = {};
+    try { scripts = JSON.parse(read('package.json') ?? '{}').scripts ?? {}; } catch { scripts = {}; }
+    const pm = has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm';
+    const run = (name) => (pm === 'npm' ? (name === 'test' ? 'npm test' : `npm run ${name}`) : `${pm} ${name === 'test' && pm !== 'bun' ? 'test' : `run ${name}`}`);
+    const placeholder = /no test specified/u;
+    if (typeof scripts.test === 'string' && !placeholder.test(scripts.test)) add(run('test'), 'the test suite');
+    for (const name of ['typecheck', 'type-check', 'check-types', 'lint']) if (typeof scripts[name] === 'string') add(run(name), name === 'lint' ? 'lint rules' : 'types');
+  }
+  const makefile = has.has('Makefile') ? read('Makefile') ?? '' : '';
+  if (/^test:/mu.test(makefile)) add('make test', 'the test suite (Makefile)');
+  if (has.has('go.mod')) add('go test ./...', 'the Go tests');
+  if (has.has('Cargo.toml')) add('cargo test', 'the Rust tests');
+  const py = has.has('pyproject.toml') || has.has('setup.py') || has.has('pytest.ini');
+  if (py && files.some((f) => /(?:^|\/)(?:test_[^/]*|[^/]*_test)\.py$/u.test(f))) add('pytest', 'the Python tests');
+  return out;
+}

package/src/prompt.mjs

@@ -19,7 +19,8 @@ Do this:
 3. Add "rules": promises the code must keep, each {"id": "kebab-id", "rule": "...", "why": "...", "files": [...],
    "checks": [{"run": "..."}]}. Take them from comments, docs, tests and commit messages. Only write rules you can point to
    in the code or docs. Ask the user for the ones only they know.
-4. Run \`npx readfirst check\` until it says the map is good, then show the user the diff of ${MAP_PATH}.
+4. Run \`npx readfirst check\` until it says the map is good (\`npx readfirst fix\` places new files and drops dead
+   patterns for you), then show the user the diff of ${MAP_PATH}.
 
 Current groups: ${map.groups.map((g) => `${g.id} (${g.files.join(', ')})`).join('; ')}.
 `;

package/src/readlist.mjs

@@ -1,6 +1,6 @@
 // The read list for files someone is about to change: the rules that cover them, the risks written for their group,
 // the checks to run (the group's commands, the rules' commands, and the tests that import them), and who uses them.
-import { groupOf, matcher, MAP_PATH } from './map.mjs';
+import { fixMap, groupOf, matcher, MAP_PATH } from './map.mjs';
 
 export const READ_LIST_FORMAT = 'readfirst/read-list@1';
 const TEST = /(^|\/)(?:tests?|__tests__|spec|e2e)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(^|\/)test[-_][^/]*\.(?:[cm]?[jt]sx?|py)$|_test\.(?:py|go)$/u;
@@ -26,6 +26,12 @@ export function readList({ map, files, imports, targets, commit = null, limit =
     out[kind].push(row);
   };
   const indirect = new Set();
+  // Where `readfirst fix` would put files that are in no group; worked out only when such a file is asked about.
+  let fixes = null;
+  const suggestFor = (target) => {
+    fixes ??= (() => { try { return fixMap(map, files).changes.map((c) => c.match(/^groups\.([^:]+): added (.+)$/u)).filter(Boolean).map((m) => ({ group: m[1], target: m[2] })); } catch { return []; } })();
+    return fixes.find((c) => target === c.target || (c.target.endsWith('/**') && target.startsWith(c.target.slice(0, -2))));
+  };
 
   for (const raw of targets) {
     const target = raw.replace(/^\.\//u, '').replace(/\\/gu, '/');
@@ -38,7 +44,8 @@ export function readList({ map, files, imports, targets, commit = null, limit =
     const group = groupOf(map, target);
     out.targets.push({ path: target, group: group?.id ?? null, status: group ? 'IN_MAP' : ignored(target) ? 'IGNORED' : 'NO_GROUP' });
     if (!group) {
-      out.notCovered.push({ path: target, why: ignored(target) ? 'ignored by the map' : 'in no group: run `readfirst check`' });
+      const suggest = ignored(target) ? null : suggestFor(target);
+      out.notCovered.push({ path: target, why: ignored(target) ? 'ignored by the map' : suggest ? `in no group: \`readfirst fix\` would add it to group ${suggest.group}` : 'in no group: run `readfirst check`' });
     } else {
       for (const r of group.risks ?? []) if (!r.files || matcher(r.files)(target)) note('risks', `${group.id}\0${r.text}`, { group: group.id, text: r.text }, target);
       for (const c of group.checks ?? []) note('checks', c.run, { run: c.run, why: c.why ?? `checks for ${group.title}`, from: `group ${group.id}` }, target);