#!/usr/bin/env node
// agents-md.mjs: the shape of a project's AGENTS.md, read from disk.
//
// Init and Init Update both start by establishing facts about AGENTS.md: does
// it exist, how long is it, which sections does it have, is it a single file
// or an index over .agents-docs/, which section files exist, which links are
// broken, which section files nothing links to. All of that is mechanical;
// what to write about it is not.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir } from "./common.mjs";
const USAGE = `
agents-md.mjs: inspect AGENTS.md and .agents-docs/. JSON on stdout.
node agents-md.mjs inspect [--root
]
exists, line count against the 500-line budget, structure
(progressive or single-file), every ## section with its line count and
its Details link, the always-inline sections, .agents-docs/ files with
their breadcrumb check, broken links, orphan section files (no link from
AGENTS.md).
node agents-md.mjs filename ""
The detail file for a section: AGENTS-.md, its link line
and its two header lines.
Exit: 0 ok (check "exists") · 2 bad arguments.
`;
const LIMIT = 500;
const ALWAYS_INLINE = ["Project Overview", "How to Use This File", "Keeping this file current", "Failure log"];
const BREADCRUMB = "> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.";
function kebab(name) {
return name
.normalize("NFKD")
.replace(/[̀-ͯ]/g, "")
.toLowerCase()
.replace(/&/g, " and ")
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "");
}
function lineCount(text) {
return text ? text.replace(/\r?\n$/, "").split(/\r?\n/).length : 0;
}
function sectionsOf(text) {
const lines = text.split(/\r?\n/);
const outList = [];
let inFence = false;
lines.forEach((l, i) => {
if (/^\s*(```|~~~)/.test(l)) inFence = !inFence;
if (inFence) return;
const m = l.match(/^## +(.+?)\s*$/);
if (m) outList.push({ name: m[1].trim(), line: i + 1 });
});
outList.forEach((s, i) => {
const end = i + 1 < outList.length ? outList[i + 1].line - 1 : lines.length;
const body = lines.slice(s.line, end).join("\n");
s.lines = end - s.line + 1;
const link = body.match(/\]\((\.\/)?\.agents-docs\/([^)\s#]+)/);
s.details = link ? `.agents-docs/${link[2]}` : null;
});
return outList;
}
function inspect(root) {
const file = path.join(root, "AGENTS.md");
const text = readText(file);
const docsDir = path.join(root, ".agents-docs");
const hasDocs = isDir(docsDir);
const docFiles = hasDocs
? fs.readdirSync(docsDir).filter((n) => n.toLowerCase().endsWith(".md")).sort().map((n) => {
const t = readText(path.join(docsDir, n)) || "";
const lines = t.split(/\r?\n/);
const h1 = lines.find((l) => /^# /.test(l));
return {
path: `.agents-docs/${n}`,
lines: lineCount(t),
title: h1 ? h1.replace(/^# +/, "").trim() : null,
breadcrumb: lines.slice(0, 6).some((l) => l.trim() === BREADCRUMB || /^> Part of \[AGENTS\.md\]\(\.\.\/AGENTS\.md\)/.test(l.trim())),
namedLikeConvention: /^AGENTS-[a-z0-9]+(-[a-z0-9]+)*\.md$/.test(n),
};
})
: [];
if (text === null) {
return { ok: true, root, exists: false, hasAgentsDocs: hasDocs, agentsDocs: docFiles, otherFiles: ["CLAUDE.md", "README.md", "PROJECT.md", "GEMINI.md", ".cursorrules", ".github/copilot-instructions.md"].filter((f) => fs.existsSync(path.join(root, f))) };
}
const sections = sectionsOf(text);
const linked = new Set();
for (const m of text.matchAll(/\]\((?:\.\/)?(\.agents-docs\/[^)\s#]+)/g)) linked.add(m[1]);
const broken = [...linked].filter((l) => !fs.existsSync(path.join(root, l)));
// A section file nothing in AGENTS.md links to is an orphan, unless another
// section file links to it: that one is reached indirectly, and deleting it
// would break a link, so it is reported apart and never offered for removal.
const fromDocs = new Set();
for (const d of docFiles) {
const t = readText(path.join(root, d.path)) || "";
for (const m of t.matchAll(/\]\((?:\.\/)?([^)\s#]+\.md)/g)) {
const target = path.posix.normalize(path.posix.join(".agents-docs", m[1]));
if (target !== d.path) fromDocs.add(target);
}
}
const unlinked = docFiles.map((d) => d.path).filter((p) => !linked.has(p));
const orphans = unlinked.filter((p) => !fromDocs.has(p));
const indirect = unlinked.filter((p) => fromDocs.has(p));
const inline = ALWAYS_INLINE.map((name) => {
const s = sections.find((x) => x.name.toLowerCase() === name.toLowerCase());
return { name, present: !!s, splitOut: !!(s && s.details) };
});
const count = lineCount(text);
return {
ok: true,
root,
exists: true,
lines: count,
budget: `${count}/${LIMIT}`,
nearLimit: count > LIMIT * 0.9,
overLimit: count > LIMIT,
structure: hasDocs ? "progressive" : "single-file",
sections,
alwaysInline: inline,
hasAgentsDocs: hasDocs,
agentsDocs: docFiles,
brokenLinks: broken,
orphans,
indirect,
problems: [
...broken.map((b) => `AGENTS.md links to ${b}, which does not exist`),
...orphans.map((o) => `${o} has no link from AGENTS.md (orphan: offer to remove it)`),
...inline.filter((s) => s.splitOut).map((s) => `${s.name} must stay inline in AGENTS.md but links out to a section file`),
...docFiles.filter((d) => !d.breadcrumb).map((d) => `${d.path} lacks the "> Part of [AGENTS.md](../AGENTS.md)" breadcrumb`),
...docFiles.filter((d) => !d.namedLikeConvention).map((d) => `${d.path} is not named AGENTS-.md`),
],
};
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { values: ["root"] });
const cmd = args._[0];
if (cmd === "inspect") {
out(inspect(path.resolve(args.root || ".")));
return;
}
if (cmd === "filename") {
const name = args._.slice(1).join(" ").trim();
if (!name) fail(EXIT.USAGE, "missing-name", "Give the section name.", 'Example: filename "Development Commands"');
const slug = kebab(name);
if (!slug) fail(EXIT.USAGE, "bad-name", `"${name}" has no letters or digits to name a file from.`, "Use the section's heading text.");
const file = `.agents-docs/AGENTS-${slug}.md`;
out({ ok: true, section: name, file, link: `Details: [${name}](./${file})`, header: [`# ${name}`, BREADCRUMB] });
return;
}
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: inspect, filename. Run with --help.");
});