agents-md-gen 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,8 @@ on immediately.
 - **Go** — go.mod, golangci-lint
 - **Ruby** — Bundler, RSpec
 - **Java/Kotlin** — Maven, Gradle (with wrapper detection)
+- **Monorepos** — Turborepo, Nx, Lerna, npm/yarn/pnpm workspaces, listing
+  each detected sub-package
 - CI (GitHub Actions), license, and top-level project structure
 
 ## GitHub Action
@@ -47,12 +49,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.4.0",
   "description": "Generate a solid AGENTS.md / CLAUDE.md for any repo by detecting its stack, commands, and structure",
   "license": "MIT",
   "bin": {
@@ -29,6 +29,9 @@
     "java",
     "maven",
     "gradle",
+    "monorepo",
+    "turborepo",
+    "nx",
     "cli",
     "codegen",
     "developer-tools"

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();
 }
@@ -266,6 +272,50 @@ function detectLicense(root) {
   return null;
 }
 
+function detectMonorepo(root) {
+  const pkg = readJson(root, 'package.json');
+  const patterns = [];
+
+  if (pkg && Array.isArray(pkg.workspaces)) {
+    patterns.push(...pkg.workspaces);
+  } else if (pkg && pkg.workspaces && Array.isArray(pkg.workspaces.packages)) {
+    patterns.push(...pkg.workspaces.packages);
+  }
+
+  const pnpmWorkspace = readText(root, 'pnpm-workspace.yaml');
+  if (pnpmWorkspace) {
+    for (const m of pnpmWorkspace.matchAll(/^\s*-\s*['"]?([^'"\n]+)['"]?\s*$/gm)) {
+      patterns.push(m[1].trim());
+    }
+  }
+
+  const tool = exists(root, 'turbo.json') ? 'Turborepo'
+    : exists(root, 'nx.json') ? 'Nx'
+    : exists(root, 'lerna.json') ? 'Lerna'
+    : patterns.length ? 'workspaces'
+    : null;
+
+  if (!tool) return null;
+
+  const packages = new Set();
+  for (const pattern of patterns) {
+    const dirPath = path.join(root, pattern.replace(/\/\*+$/, ''));
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const subPkg = readJson(dirPath, e.name, 'package.json');
+      if (subPkg) packages.add(subPkg.name || e.name);
+    }
+  }
+
+  return { tool, packages: [...packages].sort() };
+}
+
 function detectProject(root) {
   const detectors = [detectNode, detectPython, detectRust, detectGo, detectRuby, detectJava];
   const stacks = detectors.map((fn) => fn(root)).filter(Boolean);
@@ -273,6 +323,7 @@ function detectProject(root) {
   return {
     root,
     stacks,
+    monorepo: detectMonorepo(root),
     structure: listStructure(root),
     ci: detectCI(root),
     license: detectLicense(root),

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');
 

package/src/render.js

@@ -51,6 +51,16 @@ function renderStack(stack) {
   return parts.join('\n');
 }
 
+function renderMonorepo(monorepo) {
+  if (!monorepo) return null;
+  const lines = [`This is a monorepo (${monorepo.tool}).`];
+  if (monorepo.packages.length) {
+    lines.push('', 'Packages:', '');
+    lines.push(...monorepo.packages.map((p) => `- \`${p}\``));
+  }
+  return ['## Monorepo', '', ...lines].join('\n');
+}
+
 function renderStructure(structure) {
   if (!structure.length) return null;
   const lines = structure.map((entry) => {
@@ -87,6 +97,9 @@ function renderAgentsMd(project) {
     }
   }
 
+  const monorepo = renderMonorepo(project.monorepo);
+  if (monorepo) sections.push('', monorepo);
+
   const structure = renderStructure(project.structure);
   if (structure) sections.push('', structure);