agents-md-gen 0.1.1 → 0.3.0

package/README.md

@@ -20,8 +20,22 @@ on immediately.
 - **Rust** — Cargo, workspaces, clippy
 - **Go** — go.mod, golangci-lint
 - **Ruby** — Bundler, RSpec
+- **Java/Kotlin** — Maven, Gradle (with wrapper detection)
 - CI (GitHub Actions), license, and top-level project structure
 
+## GitHub Action
+
+Use it directly in CI without installing anything:
+
+```yaml
+- uses: Peshino2012/PD1@claude/busy-newton-5h97oh
+  with:
+    directory: .
+    also-claude-md: 'true'
+```
+
+(pin to a tagged release instead of a branch once one exists)
+
 A repo can match more than one of these (e.g. a Python backend next to a
 Node frontend) — each detected stack gets its own section.
 
@@ -33,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.1.1",
+  "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": {
@@ -26,6 +26,9 @@
     "github-copilot",
     "openai-codex",
     "readme-generator",
+    "java",
+    "maven",
+    "gradle",
     "cli",
     "codegen",
     "developer-tools"

package/src/detect.js

@@ -165,6 +165,50 @@ function detectGo(root) {
   };
 }
 
+function detectJava(root) {
+  const hasGradle = exists(root, 'build.gradle') || exists(root, 'build.gradle.kts');
+  const hasMaven = exists(root, 'pom.xml');
+  if (!hasGradle && !hasMaven) return null;
+
+  if (hasGradle) {
+    const gradleCmd = exists(root, 'gradlew') ? './gradlew' : 'gradle';
+    return {
+      ecosystem: 'Java/Kotlin (Gradle)',
+      name: null,
+      description: null,
+      packageManager: 'gradle',
+      frameworks: [],
+      testFramework: null,
+      commands: {
+        install: `${gradleCmd} build`,
+        build: `${gradleCmd} build`,
+        test: `${gradleCmd} test`,
+        lint: null,
+        dev: null,
+      },
+    };
+  }
+
+  const pom = readText(root, 'pom.xml') || '';
+  const nameMatch = pom.match(/<artifactId>([^<]+)<\/artifactId>/);
+  const mvnCmd = exists(root, 'mvnw') ? './mvnw' : 'mvn';
+  return {
+    ecosystem: 'Java (Maven)',
+    name: nameMatch ? nameMatch[1] : null,
+    description: null,
+    packageManager: 'maven',
+    frameworks: [],
+    testFramework: null,
+    commands: {
+      install: `${mvnCmd} install`,
+      build: `${mvnCmd} package`,
+      test: `${mvnCmd} test`,
+      lint: null,
+      dev: null,
+    },
+  };
+}
+
 function detectRuby(root) {
   if (!exists(root, 'Gemfile')) return null;
   const hasRspec = exists(root, '.rspec') || exists(root, 'spec');
@@ -185,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 {
@@ -195,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();
 }
@@ -223,7 +273,7 @@ function detectLicense(root) {
 }
 
 function detectProject(root) {
-  const detectors = [detectNode, detectPython, detectRust, detectGo, detectRuby];
+  const detectors = [detectNode, detectPython, detectRust, detectGo, detectRuby, detectJava];
   const stacks = detectors.map((fn) => fn(root)).filter(Boolean);
 
   return {

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