readfirst 0.8.0 → 0.9.0

package/README.md

@@ -15,11 +15,16 @@ No server, no account, no model calls. It reads your git checkout and `.readfirs
 Any language; needs Node 20+ for `npx`.
 
 ```sh
-npx readfirst init --agent   # first map from your folders, checks from your scripts, plus the line for CLAUDE.md / AGENTS.md
+npx readfirst init --agent --ci   # first map from your folders, checks from your scripts, the line for CLAUDE.md / AGENTS.md,
+                                  # and the GitHub Action that comments on PRs and keeps the map in step
 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
 ```
 
+In a monorepo, each workspace package with its own `package.json` becomes a group with its own checks
+(`pnpm --filter @acme/db test`, `yarn workspace …`, `npm test -w …`), so `verify` runs that package's tests, not the
+whole repository's, and its description becomes the group's title.
+
 Commit `.readfirst/map.json`. From then on:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readfirst",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "mcpName": "io.github.jeonghun917/readfirst",
   "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",

package/src/cli.mjs

@@ -1,5 +1,5 @@
 // readfirst: what to read and check before changing a file.
-//   readfirst init [--agent]       write a first .readfirst/map.json from the file tree (and the agent-notes line)
+//   readfirst init [--agent] [--ci] write a first .readfirst/map.json from the file tree (and the agent-notes line, the Action)
 //   readfirst prompt               the brief for a coding agent to fill in titles, checks, risks and rules
 //   readfirst prompt --labels <lang>  the brief for personal labels (a translation and plain notes) for the view
 //   readfirst check                the map covers every tracked file and is well formed
@@ -15,9 +15,9 @@
 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';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import { importEdges } from './imports.mjs';
-import { assertMap, draftMap, fixMap, MAP_PATH, mapProblems, settleMap } from './map.mjs';
+import { MAP_PATH, assertMap, draftChecks, draftMap, fixMap, mapProblems, settleMap } from './map.mjs';
 import { agentBrief } from './prompt.mjs';
 import { keepLocal, labelsBrief, LOCAL_DIR, readLabels } from './labels.mjs';
 import { viewData } from './view.mjs';
@@ -27,7 +27,7 @@ import { emptyList, readList, toMarkdown } from './readlist.mjs';
 
 const HELP = `readfirst — what to read and check before changing a file
 
-  readfirst init [--agent]       write a first ${MAP_PATH} from the file tree
+  readfirst init [--agent] [--ci] write a first ${MAP_PATH} from the file tree
   readfirst prompt               brief for your coding agent to fill in the map
   readfirst check [--strict]     check the map covers every tracked file (new files beside placed ones pass; --strict fails on them)
   readfirst fix                  place new files, drop patterns for deleted ones
@@ -41,7 +41,8 @@ const HELP = `readfirst — what to read and check before changing a file
   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>, --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)`;
+         --agent (init: add the read-first line to CLAUDE.md / AGENTS.md / .cursorrules),
+         --ci (init: add .github/workflows/readfirst.yml, the Action with auto-fix)`;
 
 function parse(argv) {
   const args = { _: [], json: false };
@@ -54,6 +55,7 @@ function parse(argv) {
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--strict') args.strict = true;
     else if (a === '--verify') args.verify = true;
+    else if (a === '--ci') args.ci = true;
     else if (a === '--stop') args.stop = 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; }
@@ -255,6 +257,34 @@ export function runStopHook(input, { stateDir = tmpdir(), timeout = 600 } = {})
   }
 }
 
+export const WORKFLOW_PATH = '.github/workflows/readfirst.yml';
+// The Action as `init --ci` writes it: on each PR, the read-list comment, and new files placed in the map on the PR's
+// branch (auto-fix). Never over a workflow that is already there.
+export function writeWorkflow(root) {
+  const at = join(root, WORKFLOW_PATH);
+  if (existsSync(at)) return false;
+  mkdirSync(dirname(at), { recursive: true });
+  writeFileSync(at, [
+    '# readfirst: one comment per PR with the rules, risks and checks for the files it changes,',
+    '# and new files placed in .readfirst/map.json on the PR branch (auto-fix). https://github.com/jeonghun917/readfirst',
+    'name: readfirst',
+    'on: pull_request',
+    'permissions:',
+    '  contents: write       # auto-fix commits the map update to the PR branch',
+    '  pull-requests: write  # the comment',
+    'jobs:',
+    '  readfirst:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0',
+    '      - uses: jeonghun917/readfirst@v0',
+    '        with:',
+    '          auto-fix: true',
+    '',
+  ].join('\n'));
+  return true;
+}
+
 export const HOOK_COMMAND = 'npx --yes readfirst hook';
 export const STOP_HOOK_COMMAND = 'npx --yes readfirst hook --stop';
 // Adds the hook to the project's .claude/settings.json, keeping everything already there. With verify, also the Stop
@@ -315,14 +345,21 @@ export function main(argv, io = { out: (s) => process.stdout.write(s), err: (s)
     const map = draftMap(files, readText(root));
     mkdirSync(join(root, '.readfirst'), { recursive: true });
     writeFileSync(at, `${JSON.stringify(map, null, 2)}\n`);
-    const checks = map.groups.find((g) => g.checks.length)?.checks ?? [];
-    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? "" : "s"}${checks.length ? `, checks found: ${checks.map((c) => c.run).join(', ')}` : ''}.\n`);
+    const repoChecks = draftChecks(files, readText(root)).map((c) => c.run);
+    const scoped = map.groups.filter((g) => g.checks.length && g.checks.some((c) => !repoChecks.includes(c.run))).length;
+    io.out(`wrote ${MAP_PATH}: ${map.groups.length} group${map.groups.length === 1 ? '' : 's'}${repoChecks.length ? `, checks found: ${repoChecks.join(', ')}` : ''}${scoped ? `; ${scoped} workspace package${scoped === 1 ? '' : 's'} got ${scoped === 1 ? 'its' : 'their'} own checks` : ''}.\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`);
+    if (args.ci) io.out(writeWorkflow(root) ? `wrote ${WORKFLOW_PATH}: a PR comment with the read list, and new files placed in the map on the PR branch.\n` : `${WORKFLOW_PATH} already exists; left as it is.\n`);
+    const next = [
+      'run `readfirst prompt` and give the brief to your coding agent (or fill in titles, risks and rules by hand)',
+      ...(args.agent ? [] : ['`readfirst init --agent` would add the one line your agent needs to CLAUDE.md or AGENTS.md']),
+      'Claude Code: `readfirst hook --install` gives it the read list before each edit (`--verify` also runs the checks before it finishes)',
+      ...(args.ci ? [] : ['`readfirst init --ci` would add the GitHub Action that comments on PRs and keeps the map in step']),
+    ];
+    io.out(`Next:\n${next.map((n) => `- ${n}`).join('\n')}\n`);
     return 0;
   }
   if (cmd === 'prompt') {

package/src/map.mjs

@@ -160,9 +160,44 @@ export function draftMap(files, read = () => null) {
     const hasNested = [...byFolder.values()].some((slot) => slot.pattern?.startsWith(`${root}/`) && slot.pattern !== `${root}/**`);
     if (covered && hasNested) covered.files = covered.files.filter((p) => p !== `${root}/**`).concat(loose);
   }
+  // A folder that is a workspace package of its own (packages/db/package.json) gets that package's checks, run through the
+  // package manager's workspace filter, so verify runs the package's tests instead of the whole repository's. Its title
+  // comes from the package's description when it has one.
+  for (const g of groups.values()) {
+    const dir = g.files.length === 1 && /^(.+)\/\*\*$/u.exec(g.files[0])?.[1];
+    if (!dir || !files.includes(`${dir}/package.json`)) continue;
+    let pkg;
+    try { pkg = JSON.parse(read(`${dir}/package.json`) ?? ''); } catch { continue; }
+    const checks = workspaceChecks(files, dir, pkg);
+    if (checks.length) g.checks = checks;
+    const about = typeof pkg?.description === 'string' ? pkg.description.trim().replace(/\s+/gu, ' ') : '';
+    if (about && g.title.startsWith('TODO:')) g.title = `${typeof pkg.name === 'string' ? `${pkg.name}: ` : ''}${about}`.slice(0, 200);
+  }
   return { format: MAP_FORMAT, groups: [...groups.values()].sort((a, b) => a.id.localeCompare(b.id)), rules: [], ignore: [...ignore].sort() };
 }
 
+const packageManager = (has) => (has.has('pnpm-lock.yaml') ? 'pnpm' : has.has('yarn.lock') ? 'yarn' : has.has('bun.lockb') || has.has('bun.lock') ? 'bun' : 'npm');
+const PLACEHOLDER = /no test specified/u;
+// The scripts worth running as checks, in order, with what each covers.
+const scriptChecks = (scripts, run) => [
+  ...(typeof scripts.test === 'string' && !PLACEHOLDER.test(scripts.test) ? [{ run: run('test'), why: 'the test suite' }] : []),
+  ...['typecheck', 'type-check', 'check-types', 'lint'].filter((n) => typeof scripts[n] === 'string').map((n) => ({ run: run(n), why: n === 'lint' ? 'lint rules' : 'types' })),
+];
+
+// One workspace package's own scripts, scoped to it: pnpm --filter, yarn workspace, bun --filter or npm -w.
+export function workspaceChecks(files, dir, pkg) {
+  const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const name = typeof pkg?.name === 'string' && pkg.name ? pkg.name : null;
+  const pm = packageManager(new Set(files));
+  const run = (script) => {
+    if (pm === 'pnpm') return `pnpm --filter ${name ?? `./${dir}`} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'yarn' && name) return `yarn workspace ${name} ${script === 'test' ? 'test' : `run ${script}`}`;
+    if (pm === 'bun' && name) return `bun --filter ${name} run ${script}`;
+    return script === 'test' ? `npm test -w ${dir}` : `npm run ${script} -w ${dir}`;
+  };
+  return scriptChecks(scripts, run).map((c) => ({ ...c, why: `${c.why} of ${name ?? dir}` }));
+}
+
 // Repairs the two ways a good map goes stale as code moves, without guessing at meaning:
 // - a tracked file in no group joins the group of its nearest neighbour (same folder, else the closest parent folder);
 //   a new folder whose files are all unplaced joins as "<folder>/**", a lone new file by its path;
@@ -244,11 +279,9 @@ export function draftChecks(files, read = () => null) {
   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 pm = packageManager(has);
     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');
+    for (const c of scriptChecks(scripts, run)) add(c.run, c.why);
   }
   const makefile = has.has('Makefile') ? read('Makefile') ?? '' : '';
   if (/^test:/mu.test(makefile)) add('make test', 'the test suite (Makefile)');