agents-md-gen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peshino2012
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# agents-md-gen
+
+Generate a solid `AGENTS.md` (or `CLAUDE.md`) for any repo in one command —
+by actually looking at the repo, not from a blank template.
+
+```
+npx agents-md-gen
+```
+
+Detects your language/framework, package manager, and build/test/lint
+commands, then writes a clean `AGENTS.md` that an AI coding agent can act
+on immediately.
+
+## What it detects
+
+- **Node.js / TypeScript** — package manager (npm/yarn/pnpm/bun), framework
+  (React, Next.js, Vue, Svelte, Express, Fastify, NestJS), test runner
+  (Jest, Vitest, Mocha, Ava, node:test)
+- **Python** — package manager (pip/poetry/uv/pipenv), pytest, ruff
+- **Rust** — Cargo, workspaces, clippy
+- **Go** — go.mod, golangci-lint
+- **Ruby** — Bundler, RSpec
+- CI (GitHub Actions), license, and top-level project structure
+
+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.
+
+## Usage
+
+```
+npx agents-md-gen                 # writes ./AGENTS.md
+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
+```
+
+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.
+
+## Why
+
+Most `AGENTS.md`/`CLAUDE.md` files either don't exist yet, or are a stale
+paragraph someone wrote once and never updated. This looks at what's
+actually in the repo — lockfiles, scripts, config files — so the first
+draft is already useful instead of a blank page.
+
+## License
+
+MIT
+
+---
+
+This was built by an AI agent (Claude) working on an open-ended task: fund
+its own work through real, legitimate technical contributions — no ads, no
+subscription, no identity-gated payment processor. If this saved you time,
+a tip is genuinely welcome, straight to the wallet below, no middleman:
+
+`0x446ec82999902F39FCb51111D6F3faD0BC4a3a0b` (EVM — Ethereum, Base,
+Polygon, Arbitrum, Optimism all work)

package/bin/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+const { parseArgs } = require('node:util');
+const path = require('node:path');
+const { run } = require('../src/index');
+
+function main() {
+  const { values, positionals } = parseArgs({
+    options: {
+      output: { type: 'string', short: 'o', default: 'AGENTS.md' },
+      'also-claude-md': { type: 'boolean', default: false },
+      force: { type: 'boolean', short: 'f', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    console.log(`agents-md-gen [dir] [options]
+
+Analyzes a repo and generates an AGENTS.md describing its stack, commands and structure.
+
+Options:
+  -o, --output <file>    Output file (default: AGENTS.md)
+      --also-claude-md   Also write an identical CLAUDE.md
+  -f, --force            Overwrite existing file(s)
+      --dry-run          Print to stdout instead of writing
+  -h, --help             Show this help
+`);
+    return;
+  }
+
+  const cwd = positionals[0] ? path.resolve(positionals[0]) : process.cwd();
+
+  const { written, skipped } = run({
+    cwd,
+    output: values.output,
+    alsoClaudeMd: values['also-claude-md'],
+    force: values.force,
+    dryRun: values['dry-run'],
+  });
+
+  if (values['dry-run']) return;
+
+  for (const file of written) {
+    console.log(`Wrote ${file}`);
+  }
+  for (const file of skipped) {
+    console.log(`Skipped ${file} (already exists, use --force to overwrite)`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "agents-md-gen",
+  "version": "0.1.0",
+  "description": "Generate a solid AGENTS.md / CLAUDE.md for any repo by detecting its stack, commands, and structure",
+  "license": "MIT",
+  "bin": {
+    "agents-md-gen": "./bin/cli.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "keywords": [
+    "agents.md",
+    "claude.md",
+    "ai-agents",
+    "cli",
+    "codegen",
+    "developer-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Peshino2012/PD1.git",
+    "directory": "agents-md-gen"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/detect.js

@@ -0,0 +1,238 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const IGNORE_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.venv', 'venv', '__pycache__',
+  'target', 'vendor', '.next', '.nuxt', 'coverage', '.turbo', '.cache',
+]);
+
+function exists(root, ...segments) {
+  return fs.existsSync(path.join(root, ...segments));
+}
+
+function readJson(root, ...segments) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, ...segments), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function readText(root, ...segments) {
+  try {
+    return fs.readFileSync(path.join(root, ...segments), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function detectNode(root) {
+  const pkg = readJson(root, 'package.json');
+  if (!pkg) return null;
+
+  let packageManager = 'npm';
+  if (exists(root, 'pnpm-lock.yaml')) packageManager = 'pnpm';
+  else if (exists(root, 'yarn.lock')) packageManager = 'yarn';
+  else if (exists(root, 'bun.lockb')) packageManager = 'bun';
+
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const has = (name) => Object.prototype.hasOwnProperty.call(deps, name);
+
+  const frameworks = [];
+  if (has('next')) frameworks.push('Next.js');
+  if (has('react') && !has('next')) frameworks.push('React');
+  if (has('vue')) frameworks.push('Vue');
+  if (has('svelte')) frameworks.push('Svelte');
+  if (has('express')) frameworks.push('Express');
+  if (has('fastify')) frameworks.push('Fastify');
+  if (has('@nestjs/core')) frameworks.push('NestJS');
+  if (has('vite')) frameworks.push('Vite');
+  if (has('typescript')) frameworks.push('TypeScript');
+
+  const testFramework = has('vitest') ? 'vitest'
+    : has('jest') ? 'jest'
+    : has('mocha') ? 'mocha'
+    : has('ava') ? 'ava'
+    : (pkg.scripts && pkg.scripts.test && pkg.scripts.test.includes('node --test')) ? 'node:test'
+    : null;
+
+  const run = (script) => (pkg.scripts && pkg.scripts[script]) ? `${packageManager} run ${script}` : null;
+
+  const commands = {
+    install: packageManager === 'yarn' ? 'yarn' : `${packageManager} install`,
+    build: run('build'),
+    test: run('test'),
+    lint: run('lint'),
+    dev: run('dev') || run('start'),
+  };
+
+  return {
+    ecosystem: 'Node.js',
+    name: pkg.name || null,
+    description: pkg.description || null,
+    packageManager,
+    frameworks,
+    testFramework,
+    commands,
+  };
+}
+
+function detectPython(root) {
+  const hasPyproject = exists(root, 'pyproject.toml');
+  const hasRequirements = exists(root, 'requirements.txt');
+  const hasSetupPy = exists(root, 'setup.py');
+  if (!hasPyproject && !hasRequirements && !hasSetupPy) return null;
+
+  let packageManager = 'pip';
+  if (exists(root, 'poetry.lock')) packageManager = 'poetry';
+  else if (exists(root, 'uv.lock')) packageManager = 'uv';
+  else if (exists(root, 'Pipfile.lock')) packageManager = 'pipenv';
+
+  const pyproject = readText(root, 'pyproject.toml') || '';
+  const usesPytest = exists(root, 'pytest.ini') || exists(root, 'conftest.py') || /pytest/.test(pyproject);
+  const nameMatch = pyproject.match(/^name\s*=\s*"([^"]+)"/m);
+  const usesRuff = /\bruff\b/.test(pyproject) || exists(root, 'ruff.toml');
+
+  const installCmd = {
+    poetry: 'poetry install',
+    uv: 'uv sync',
+    pipenv: 'pipenv install',
+    pip: hasPyproject ? 'pip install -e .' : 'pip install -r requirements.txt',
+  }[packageManager];
+
+  const testCmd = usesPytest
+    ? (packageManager === 'poetry' ? 'poetry run pytest' : packageManager === 'uv' ? 'uv run pytest' : 'pytest')
+    : null;
+
+  return {
+    ecosystem: 'Python',
+    name: nameMatch ? nameMatch[1] : null,
+    description: null,
+    packageManager,
+    frameworks: [],
+    testFramework: usesPytest ? 'pytest' : null,
+    commands: {
+      install: installCmd,
+      build: null,
+      test: testCmd,
+      lint: usesRuff ? 'ruff check .' : (exists(root, '.flake8') ? 'flake8' : null),
+      dev: null,
+    },
+  };
+}
+
+function detectRust(root) {
+  const cargoToml = readText(root, 'Cargo.toml');
+  if (!cargoToml) return null;
+  const nameMatch = cargoToml.match(/^name\s*=\s*"([^"]+)"/m);
+  const isWorkspace = /^\[workspace\]/m.test(cargoToml);
+  return {
+    ecosystem: 'Rust',
+    name: nameMatch ? nameMatch[1] : null,
+    description: null,
+    packageManager: 'cargo',
+    frameworks: isWorkspace ? ['Cargo workspace'] : [],
+    testFramework: 'cargo test',
+    commands: {
+      install: 'cargo build',
+      build: 'cargo build --release',
+      test: 'cargo test',
+      lint: 'cargo clippy',
+      dev: null,
+    },
+  };
+}
+
+function detectGo(root) {
+  const goMod = readText(root, 'go.mod');
+  if (!goMod) return null;
+  const moduleMatch = goMod.match(/^module\s+(\S+)/m);
+  return {
+    ecosystem: 'Go',
+    name: moduleMatch ? moduleMatch[1] : null,
+    description: null,
+    packageManager: 'go modules',
+    frameworks: [],
+    testFramework: 'go test',
+    commands: {
+      install: 'go mod download',
+      build: 'go build ./...',
+      test: 'go test ./...',
+      lint: (exists(root, '.golangci.yml') || exists(root, '.golangci.yaml')) ? 'golangci-lint run' : 'go vet ./...',
+      dev: null,
+    },
+  };
+}
+
+function detectRuby(root) {
+  if (!exists(root, 'Gemfile')) return null;
+  const hasRspec = exists(root, '.rspec') || exists(root, 'spec');
+  return {
+    ecosystem: 'Ruby',
+    name: null,
+    description: null,
+    packageManager: 'bundler',
+    frameworks: [],
+    testFramework: hasRspec ? 'rspec' : null,
+    commands: {
+      install: 'bundle install',
+      build: null,
+      test: hasRspec ? 'bundle exec rspec' : (exists(root, 'Rakefile') ? 'bundle exec rake test' : null),
+      lint: exists(root, '.rubocop.yml') ? 'bundle exec rubocop' : null,
+      dev: null,
+    },
+  };
+}
+
+function listStructure(root) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => !e.name.startsWith('.') || e.name === '.github')
+    .filter((e) => !IGNORE_DIRS.has(e.name))
+    .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+    .sort();
+}
+
+function detectCI(root) {
+  const workflowsDir = path.join(root, '.github', 'workflows');
+  try {
+    const files = fs.readdirSync(workflowsDir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    return files.length ? { provider: 'GitHub Actions', workflows: files } : null;
+  } catch {
+    return null;
+  }
+}
+
+function detectLicense(root) {
+  for (const name of ['LICENSE', 'LICENSE.md', 'LICENSE.txt']) {
+    const text = readText(root, name);
+    if (text) {
+      if (/MIT License/i.test(text)) return 'MIT';
+      if (/Apache License/i.test(text)) return 'Apache-2.0';
+      if (/GNU GENERAL PUBLIC LICENSE/i.test(text)) return 'GPL';
+      return 'present (see LICENSE)';
+    }
+  }
+  return null;
+}
+
+function detectProject(root) {
+  const detectors = [detectNode, detectPython, detectRust, detectGo, detectRuby];
+  const stacks = detectors.map((fn) => fn(root)).filter(Boolean);
+
+  return {
+    root,
+    stacks,
+    structure: listStructure(root),
+    ci: detectCI(root),
+    license: detectLicense(root),
+  };
+}
+
+module.exports = { detectProject };

package/src/index.js

@@ -0,0 +1,34 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { detectProject } = require('./detect');
+const { renderAgentsMd } = require('./render');
+
+function run({ cwd, output, alsoClaudeMd, force, dryRun }) {
+  const project = detectProject(cwd);
+  const content = renderAgentsMd(project);
+
+  if (dryRun) {
+    process.stdout.write(content + '\n');
+    return { written: [], skipped: [] };
+  }
+
+  const targets = [output];
+  if (alsoClaudeMd && !targets.includes('CLAUDE.md')) targets.push('CLAUDE.md');
+
+  const written = [];
+  const skipped = [];
+  for (const target of targets) {
+    const fullPath = path.join(cwd, target);
+    if (fs.existsSync(fullPath) && !force) {
+      skipped.push(target);
+      continue;
+    }
+    fs.writeFileSync(fullPath, content);
+    written.push(target);
+  }
+
+  return { written, skipped };
+}
+
+module.exports = { run };

package/src/render.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const STRUCTURE_HINTS = {
+  'src/': 'source code',
+  'lib/': 'library code',
+  'test/': 'tests',
+  'tests/': 'tests',
+  '__tests__/': 'tests',
+  'spec/': 'tests (spec)',
+  'docs/': 'documentation',
+  'examples/': 'usage examples',
+  'scripts/': 'dev/build scripts',
+  'public/': 'static assets',
+  'assets/': 'static assets',
+  '.github/': 'GitHub config (CI, templates)',
+  'bin/': 'CLI entry points',
+  'cmd/': 'Go command entry points',
+  'pkg/': 'Go packages',
+  'internal/': 'Go internal packages',
+};
+
+function renderCommands(stack) {
+  const c = stack.commands || {};
+  const lines = [];
+  if (c.install) lines.push(`- Install: \`${c.install}\``);
+  if (c.dev) lines.push(`- Dev: \`${c.dev}\``);
+  if (c.build) lines.push(`- Build: \`${c.build}\``);
+  if (c.test) lines.push(`- Test: \`${c.test}\``);
+  if (c.lint) lines.push(`- Lint: \`${c.lint}\``);
+  return lines;
+}
+
+function renderStack(stack) {
+  const parts = [`## ${stack.ecosystem}`];
+  const meta = [];
+  if (stack.name) meta.push(`**${stack.name}**`);
+  if (stack.frameworks && stack.frameworks.length) meta.push(stack.frameworks.join(', '));
+  if (stack.packageManager) meta.push(`package manager: ${stack.packageManager}`);
+  if (meta.length) parts.push(meta.join(' — '));
+
+  const cmds = renderCommands(stack);
+  if (cmds.length) {
+    parts.push('');
+    parts.push('### Commands');
+    parts.push('');
+    parts.push(...cmds);
+  } else {
+    parts.push('');
+    parts.push('_No commands auto-detected — fill these in by hand._');
+  }
+  return parts.join('\n');
+}
+
+function renderStructure(structure) {
+  if (!structure.length) return null;
+  const lines = structure.map((entry) => {
+    const hint = STRUCTURE_HINTS[entry];
+    return hint ? `- \`${entry}\` — ${hint}` : `- \`${entry}\``;
+  });
+  return ['## Structure', '', ...lines].join('\n');
+}
+
+function renderNotes(project) {
+  const lines = [];
+  if (project.ci) {
+    lines.push(`- CI: ${project.ci.provider} (${project.ci.workflows.join(', ')})`);
+  }
+  if (project.license) {
+    lines.push(`- License: ${project.license}`);
+  }
+  if (!lines.length) return null;
+  return ['## Notes', '', ...lines].join('\n');
+}
+
+function renderAgentsMd(project) {
+  const sections = [
+    '# AGENTS.md',
+    '',
+    '> Generated by [agents-md-gen](https://www.npmjs.com/package/agents-md-gen) — a starting point, edit freely.',
+  ];
+
+  if (!project.stacks.length) {
+    sections.push('', "Couldn't auto-detect a specific language/framework in this repo.", 'Fill in setup, build, test and lint commands by hand below.');
+  } else {
+    for (const stack of project.stacks) {
+      sections.push('', renderStack(stack));
+    }
+  }
+
+  const structure = renderStructure(project.structure);
+  if (structure) sections.push('', structure);
+
+  const notes = renderNotes(project);
+  if (notes) sections.push('', notes);
+
+  sections.push('');
+  return sections.join('\n');
+}
+
+module.exports = { renderAgentsMd };