compose-agentsmd 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,10 @@
 
 This repository contains CLI tooling for composing per-project `AGENTS.md` files from modular rule sets.
 
+## Release notes
+
+See `CHANGELOG.md` for release notes.
+
 It is intended to be used together with shared rule modules such as:
 
 - `agent-rules/` (public rule modules)
@@ -41,6 +45,8 @@ compose-agentsmd
 
 The tool searches for `agent-ruleset.json` under the given root directory (default: current working directory), and writes output files as specified by each ruleset. If `output` is omitted, it defaults to `AGENTS.md`.
 
+The tool prepends a small "Tool Rules" block to every generated `AGENTS.md` so agents know how to regenerate or update rules.
+
 ### Rules root resolution (important for global installs)
 
 When installed globally, the rules directory is usually outside the project. You can point to it in either of the following ways:
@@ -78,6 +84,10 @@ Rules root resolution precedence is:
 - `domains` selects domain folders under `agent-rules/rules/domains`.
 - `rules` is optional and appends additional rule files.
 
+### Ruleset schema validation
+
+`compose-agentsmd` validates rulesets against `agent-ruleset.schema.json` on every run. If the ruleset does not conform to the schema, the tool exits with a schema error.
+
 Optional path overrides:
 
 - `rulesRoot`: override `agent-rules/rules`.

package/agent-ruleset.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Compose AGENTS.md ruleset",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "output": {
+      "type": "string",
+      "minLength": 1
+    },
+    "domains": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "rulesRoot": {
+      "type": "string",
+      "minLength": 1
+    },
+    "globalDir": {
+      "type": "string",
+      "minLength": 1
+    },
+    "domainsDir": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

package/dist/compose-agents.js

@@ -1,17 +1,20 @@
 #!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
+import fs from "node:fs";
+import path from "node:path";
+import { Ajv } from "ajv";
 const DEFAULT_RULESET_NAME = "agent-ruleset.json";
 const DEFAULT_RULES_ROOT = "agent-rules/rules";
 const DEFAULT_GLOBAL_DIR = "global";
 const DEFAULT_DOMAINS_DIR = "domains";
 const RULES_ROOT_ENV_VAR = "AGENT_RULES_ROOT";
 const DEFAULT_OUTPUT = "AGENTS.md";
+const RULESET_SCHEMA_PATH = new URL("../agent-ruleset.schema.json", import.meta.url);
+const TOOL_RULES = [
+    "# Tool Rules (compose-agentsmd)",
+    "- Before starting any work, run `compose-agentsmd` from the project root.",
+    "- To update rules, update the source rule modules or ruleset, then rerun `compose-agentsmd`.",
+    "- Do not edit `AGENTS.md` directly; update the source rules and regenerate."
+].join("\n");
 const DEFAULT_IGNORE_DIRS = new Set([
     ".git",
     "agent-rules",
@@ -86,59 +89,56 @@ const parseArgs = (argv) => {
 const normalizeTrailingWhitespace = (content) => content.replace(/\s+$/u, "");
 const normalizePath = (filePath) => filePath.replace(/\\/g, "/");
 const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+const rulesetSchema = JSON.parse(fs.readFileSync(RULESET_SCHEMA_PATH, "utf8"));
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validateRulesetSchema = ajv.compile(rulesetSchema);
+const formatSchemaErrors = (errors) => {
+    if (!errors || errors.length === 0) {
+        return "Unknown schema validation error";
+    }
+    return errors
+        .map((error) => {
+        const pathLabel = error.instancePath ? error.instancePath : "(root)";
+        return `${pathLabel} ${error.message ?? "is invalid"}`;
+    })
+        .join("; ");
+};
 const resolveFrom = (baseDir, targetPath) => {
-    if (node_path_1.default.isAbsolute(targetPath)) {
+    if (path.isAbsolute(targetPath)) {
         return targetPath;
     }
-    return node_path_1.default.resolve(baseDir, targetPath);
+    return path.resolve(baseDir, targetPath);
 };
 const ensureFileExists = (filePath) => {
-    if (!node_fs_1.default.existsSync(filePath)) {
+    if (!fs.existsSync(filePath)) {
         throw new Error(`Missing file: ${filePath}`);
     }
 };
 const ensureDirectoryExists = (dirPath) => {
-    if (!node_fs_1.default.existsSync(dirPath)) {
+    if (!fs.existsSync(dirPath)) {
         throw new Error(`Missing directory: ${dirPath}`);
     }
-    const stat = node_fs_1.default.statSync(dirPath);
+    const stat = fs.statSync(dirPath);
     if (!stat.isDirectory()) {
         throw new Error(`Not a directory: ${dirPath}`);
     }
 };
 const readJsonFile = (filePath) => {
-    const raw = node_fs_1.default.readFileSync(filePath, "utf8");
+    const raw = fs.readFileSync(filePath, "utf8");
     return JSON.parse(raw);
 };
 const readProjectRuleset = (rulesetPath) => {
     const parsed = readJsonFile(rulesetPath);
-    if (parsed.output === undefined) {
-        parsed.output = DEFAULT_OUTPUT;
+    const isValid = validateRulesetSchema(parsed);
+    if (!isValid) {
+        const message = formatSchemaErrors(validateRulesetSchema.errors);
+        throw new Error(`Invalid ruleset schema in ${rulesetPath}: ${message}`);
     }
-    else if (!isNonEmptyString(parsed.output)) {
-        throw new Error(`Invalid ruleset output in ${rulesetPath}`);
-    }
-    if (parsed.domains !== undefined) {
-        if (!Array.isArray(parsed.domains)) {
-            throw new Error(`"domains" must be an array in ${rulesetPath}`);
-        }
-        for (const domain of parsed.domains) {
-            if (!isNonEmptyString(domain)) {
-                throw new Error(`"domains" entries must be non-empty strings in ${rulesetPath}`);
-            }
-        }
-    }
-    if (parsed.rules !== undefined) {
-        if (!Array.isArray(parsed.rules)) {
-            throw new Error(`"rules" must be an array in ${rulesetPath}`);
-        }
-        for (const rule of parsed.rules) {
-            if (!isNonEmptyString(rule)) {
-                throw new Error(`"rules" entries must be non-empty strings in ${rulesetPath}`);
-            }
-        }
+    const ruleset = parsed;
+    if (ruleset.output === undefined) {
+        ruleset.output = DEFAULT_OUTPUT;
     }
-    return parsed;
+    return ruleset;
 };
 const resolveRulesRoot = (rulesetDir, projectRuleset, options) => {
     if (isNonEmptyString(options.cliRulesRoot)) {
@@ -151,19 +151,19 @@ const resolveRulesRoot = (rulesetDir, projectRuleset, options) => {
     if (isNonEmptyString(projectRuleset.rulesRoot)) {
         return resolveFrom(rulesetDir, projectRuleset.rulesRoot);
     }
-    return node_path_1.default.resolve(rulesetDir, DEFAULT_RULES_ROOT);
+    return path.resolve(rulesetDir, DEFAULT_RULES_ROOT);
 };
 const resolveGlobalRoot = (rulesRoot, projectRuleset) => {
     const globalDirName = isNonEmptyString(projectRuleset.globalDir)
         ? projectRuleset.globalDir
         : DEFAULT_GLOBAL_DIR;
-    return node_path_1.default.resolve(rulesRoot, globalDirName);
+    return path.resolve(rulesRoot, globalDirName);
 };
 const resolveDomainsRoot = (rulesRoot, projectRuleset) => {
     const domainsDirName = isNonEmptyString(projectRuleset.domainsDir)
         ? projectRuleset.domainsDir
         : DEFAULT_DOMAINS_DIR;
-    return node_path_1.default.resolve(rulesRoot, domainsDirName);
+    return path.resolve(rulesRoot, domainsDirName);
 };
 const collectMarkdownFiles = (rootDir) => {
     ensureDirectoryExists(rootDir);
@@ -174,27 +174,27 @@ const collectMarkdownFiles = (rootDir) => {
         if (!currentDir) {
             continue;
         }
-        const entries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
         for (const entry of entries) {
-            const entryPath = node_path_1.default.join(currentDir, entry.name);
+            const entryPath = path.join(currentDir, entry.name);
             if (entry.isDirectory()) {
                 pending.push(entryPath);
                 continue;
             }
-            if (entry.isFile() && node_path_1.default.extname(entry.name).toLowerCase() === ".md") {
+            if (entry.isFile() && path.extname(entry.name).toLowerCase() === ".md") {
                 results.push(entryPath);
             }
         }
     }
     return results.sort((a, b) => {
-        const relA = normalizePath(node_path_1.default.relative(rootDir, a));
-        const relB = normalizePath(node_path_1.default.relative(rootDir, b));
+        const relA = normalizePath(path.relative(rootDir, a));
+        const relB = normalizePath(path.relative(rootDir, b));
         return relA.localeCompare(relB);
     });
 };
 const addRulePaths = (rulePaths, resolvedRules, seenRules) => {
     for (const rulePath of rulePaths) {
-        const resolvedRulePath = node_path_1.default.resolve(rulePath);
+        const resolvedRulePath = path.resolve(rulePath);
         if (seenRules.has(resolvedRulePath)) {
             continue;
         }
@@ -204,7 +204,7 @@ const addRulePaths = (rulePaths, resolvedRules, seenRules) => {
     }
 };
 const composeRuleset = (rulesetPath, rootDir, options) => {
-    const rulesetDir = node_path_1.default.dirname(rulesetPath);
+    const rulesetDir = path.dirname(rulesetPath);
     const projectRuleset = readProjectRuleset(rulesetPath);
     const outputFileName = projectRuleset.output ?? DEFAULT_OUTPUT;
     const outputPath = resolveFrom(rulesetDir, outputFileName);
@@ -219,18 +219,19 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     addRulePaths(collectMarkdownFiles(globalRoot), resolvedRules, seenRules);
     const domains = Array.isArray(projectRuleset.domains) ? projectRuleset.domains : [];
     for (const domain of domains) {
-        const domainRoot = node_path_1.default.resolve(domainsRoot, domain);
+        const domainRoot = path.resolve(domainsRoot, domain);
         addRulePaths(collectMarkdownFiles(domainRoot), resolvedRules, seenRules);
     }
     const directRules = Array.isArray(projectRuleset.rules) ? projectRuleset.rules : [];
     const directRulePaths = directRules.map((rulePath) => resolveFrom(rulesetDir, rulePath));
     addRulePaths(directRulePaths, resolvedRules, seenRules);
-    const parts = resolvedRules.map((rulePath) => normalizeTrailingWhitespace(node_fs_1.default.readFileSync(rulePath, "utf8")));
+    const parts = resolvedRules.map((rulePath) => normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8")));
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
-    const output = `${lintHeader}\n${parts.join("\n\n")}\n`;
-    node_fs_1.default.mkdirSync(node_path_1.default.dirname(outputPath), { recursive: true });
-    node_fs_1.default.writeFileSync(outputPath, output, "utf8");
-    return normalizePath(node_path_1.default.relative(rootDir, outputPath));
+    const toolRules = normalizeTrailingWhitespace(TOOL_RULES);
+    const output = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, output, "utf8");
+    return normalizePath(path.relative(rootDir, outputPath));
 };
 const findRulesetFiles = (rootDir, rulesetName) => {
     const results = [];
@@ -240,9 +241,9 @@ const findRulesetFiles = (rootDir, rulesetName) => {
         if (!currentDir) {
             continue;
         }
-        const entries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
         for (const entry of entries) {
-            const entryPath = node_path_1.default.join(currentDir, entry.name);
+            const entryPath = path.join(currentDir, entry.name);
             if (entry.isDirectory()) {
                 if (DEFAULT_IGNORE_DIRS.has(entry.name)) {
                     continue;
@@ -271,7 +272,7 @@ const main = () => {
         process.stdout.write(`${usage}\n`);
         return;
     }
-    const rootDir = args.root ? node_path_1.default.resolve(args.root) : process.cwd();
+    const rootDir = args.root ? path.resolve(args.root) : process.cwd();
     const rulesetName = args.rulesetName || DEFAULT_RULESET_NAME;
     const rulesetFiles = getRulesetFiles(rootDir, args.ruleset, rulesetName);
     if (rulesetFiles.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {
@@ -18,17 +18,24 @@
     "cli",
     "markdown"
   ],
-  "type": "commonjs",
+  "type": "module",
   "bin": {
     "compose-agentsmd": "dist/compose-agents.js"
   },
   "files": [
     "dist",
-    "tools"
+    "agent-ruleset.schema.json",
+    "tools",
+    "README.md",
+    "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
+    "prepare": "npm run build",
     "prepack": "npm run build",
     "test": "npm run build && node --test",
     "compose": "npm run build && node dist/compose-agents.js"
@@ -39,5 +46,8 @@
   "devDependencies": {
     "@types/node": "^25.0.10",
     "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
   }
 }

package/tools/compose-agents.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/compose-agents.js";

package/tools/compose-agents.cjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-require("../dist/compose-agents.js");