compose-agentsmd 1.0.1 → 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,12 +1,20 @@
 #!/usr/bin/env node
 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",
@@ -81,6 +89,20 @@ 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 (path.isAbsolute(targetPath)) {
         return targetPath;
@@ -107,33 +129,16 @@ const readJsonFile = (filePath) => {
 };
 const readProjectRuleset = (rulesetPath) => {
     const parsed = readJsonFile(rulesetPath);
-    if (parsed.output === undefined) {
-        parsed.output = DEFAULT_OUTPUT;
-    }
-    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}`);
-            }
-        }
+    const isValid = validateRulesetSchema(parsed);
+    if (!isValid) {
+        const message = formatSchemaErrors(validateRulesetSchema.errors);
+        throw new Error(`Invalid ruleset schema in ${rulesetPath}: ${message}`);
     }
-    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)) {
@@ -222,7 +227,8 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     addRulePaths(directRulePaths, resolvedRules, seenRules);
     const parts = resolvedRules.map((rulePath) => normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8")));
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
-    const output = `${lintHeader}\n${parts.join("\n\n")}\n`;
+    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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "agent-ruleset.schema.json",
     "tools",
     "README.md",
     "LICENSE"
@@ -45,5 +46,8 @@
   "devDependencies": {
     "@types/node": "^25.0.10",
     "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
   }
 }