agents-md-gen 0.2.0 → 0.3.0

package/README.md

@@ -47,12 +47,18 @@ npx agents-md-gen ./some/repo     # target a different directory
 npx agents-md-gen --also-claude-md
 npx agents-md-gen --dry-run       # print instead of writing
 npx agents-md-gen --force         # overwrite an existing file
+npx agents-md-gen --check         # exit 1 if missing/stale, writes nothing (CI)
 ```
 
 It won't overwrite an existing `AGENTS.md`/`CLAUDE.md` unless you pass
 `--force` — this is meant to bootstrap a file you then edit by hand, not to
 clobber one you already wrote.
 
+`--check` is for CI: it fails the build if `AGENTS.md` doesn't exist or no
+longer matches what the repo would generate, so a stale file (say, a new
+test framework got added but nobody regenerated it) gets caught instead of
+silently rotting. Pair it with the GitHub Action below.
+
 ## Example
 
 Real output — this is what `npx agents-md-gen` produces when run against

package/bin/cli.js

@@ -11,6 +11,7 @@ function main() {
       'also-claude-md': { type: 'boolean', default: false },
       force: { type: 'boolean', short: 'f', default: false },
       'dry-run': { type: 'boolean', default: false },
+      check: { type: 'boolean', default: false },
       help: { type: 'boolean', short: 'h', default: false },
     },
     allowPositionals: true,
@@ -26,6 +27,7 @@ Options:
       --also-claude-md   Also write an identical CLAUDE.md
   -f, --force            Overwrite existing file(s)
       --dry-run          Print to stdout instead of writing
+      --check            Exit 1 if the file is missing or out of date (CI use, writes nothing)
   -h, --help             Show this help
 `);
     return;
@@ -33,6 +35,25 @@ Options:
 
   const cwd = positionals[0] ? path.resolve(positionals[0]) : process.cwd();
 
+  if (values.check) {
+    const { upToDate, existed, target } = run({
+      cwd,
+      output: values.output,
+      check: true,
+    });
+    if (upToDate) {
+      console.log(`${target} is up to date`);
+      return;
+    }
+    console.error(
+      existed
+        ? `${target} is out of date - run agents-md-gen --force to update it`
+        : `${target} does not exist - run agents-md-gen to create it`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   const { written, skipped } = run({
     cwd,
     output: values.output,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-md-gen",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Generate a solid AGENTS.md / CLAUDE.md for any repo by detecting its stack, commands, and structure",
   "license": "MIT",
   "bin": {

package/src/detect.js

@@ -229,6 +229,11 @@ function detectRuby(root) {
   };
 }
 
+// Excluded so re-running the generator doesn't see its own prior output as
+// part of the repo's structure - otherwise the file it just wrote would
+// never match a freshly rendered one, breaking `--check`.
+const OWN_OUTPUT_FILES = new Set(['AGENTS.md', 'CLAUDE.md']);
+
 function listStructure(root) {
   let entries;
   try {
@@ -239,6 +244,7 @@ function listStructure(root) {
   return entries
     .filter((e) => !e.name.startsWith('.') || e.name === '.github')
     .filter((e) => !IGNORE_DIRS.has(e.name))
+    .filter((e) => !OWN_OUTPUT_FILES.has(e.name))
     .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
     .sort();
 }

package/src/index.js

@@ -4,7 +4,7 @@ const path = require('path');
 const { detectProject } = require('./detect');
 const { renderAgentsMd } = require('./render');
 
-function run({ cwd, output, alsoClaudeMd, force, dryRun }) {
+function run({ cwd, output, alsoClaudeMd, force, dryRun, check }) {
   const project = detectProject(cwd);
   const content = renderAgentsMd(project);
 
@@ -13,6 +13,13 @@ function run({ cwd, output, alsoClaudeMd, force, dryRun }) {
     return { written: [], skipped: [] };
   }
 
+  if (check) {
+    const fullPath = path.join(cwd, output);
+    const existing = fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : null;
+    const upToDate = existing === content;
+    return { upToDate, existed: existing !== null, target: output };
+  }
+
   const targets = [output];
   if (alsoClaudeMd && !targets.includes('CLAUDE.md')) targets.push('CLAUDE.md');