compose-agentsmd 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 metyatech
+
+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,101 @@
+# Compose AGENTS.md
+
+This repository contains CLI tooling for composing per-project `AGENTS.md` files from modular rule sets.
+
+It is intended to be used together with shared rule modules such as:
+
+- `agent-rules/` (public rule modules)
+- `agent-rules-private/` (optional, private-only rule modules)
+
+## Install (global CLI)
+
+After publishing to npm, install globally:
+
+```sh
+npm install -g compose-agentsmd
+```
+
+This provides the `compose-agentsmd` command.
+
+## Rules setup (this repository)
+
+This repository expects the public rules to be available at `agent-rules/rules` via the `agent-rules/` submodule.
+
+Initialize submodules and compose the rules:
+
+```sh
+git submodule update --init --recursive
+npm install
+npm run compose
+```
+
+The default ruleset for this repository is `agent-ruleset.json` and currently composes the `node` domain into `AGENTS.md`.
+
+## Compose
+
+From each project root, run:
+
+```sh
+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`.
+
+### 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:
+
+```sh
+compose-agentsmd --rules-root "C:/path/to/agent-rules/rules"
+```
+
+Or via environment variable:
+
+```sh
+set AGENT_RULES_ROOT=C:/path/to/agent-rules/rules
+compose-agentsmd
+```
+
+Rules root resolution precedence is:
+
+- `--rules-root` CLI option
+- `AGENT_RULES_ROOT` environment variable
+- `rulesRoot` in the ruleset file
+- Default: `agent-rules/rules` relative to the ruleset file
+
+## Project ruleset format
+
+```json
+{
+  "output": "AGENTS.md",
+  "domains": ["node", "unreal"],
+  "rules": ["agent-rules-local/custom.md"]
+}
+```
+
+- Global rules are always included from `agent-rules/rules/global`.
+- `output` is optional; when omitted, `AGENTS.md` is used.
+- `domains` selects domain folders under `agent-rules/rules/domains`.
+- `rules` is optional and appends additional rule files.
+
+Optional path overrides:
+
+- `rulesRoot`: override `agent-rules/rules`.
+- `globalDir`: override `global` (relative to `rulesRoot`).
+- `domainsDir`: override `domains` (relative to `rulesRoot`).
+
+### Optional arguments
+
+- `--root <path>`: project root (defaults to current working directory)
+- `--ruleset <path>`: only compose a single ruleset file
+- `--ruleset-name <name>`: override the ruleset filename (default: `agent-ruleset.json`)
+- `--rules-root <path>`: override the rules root for all rulesets (or set `AGENT_RULES_ROOT`)
+
+## Development
+
+```sh
+npm install
+npm run lint
+npm run build
+npm test
+```

package/dist/compose-agents.js

@@ -0,0 +1,293 @@
+#!/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"));
+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 DEFAULT_IGNORE_DIRS = new Set([
+    ".git",
+    "agent-rules",
+    "agent-rules-private",
+    "agent-rules-local",
+    "agent-rules-tools",
+    "compose-agentsmd",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".turbo",
+    "coverage"
+]);
+const usage = `Usage: compose-agentsmd [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--rules-root <path>]
+
+Options:
+  --root <path>         Project root directory (default: current working directory)
+  --ruleset <path>      Only compose a single ruleset file
+  --ruleset-name <name> Ruleset filename to search for (default: agent-ruleset.json)
+  --rules-root <path>   Override rules root directory for all rulesets (or set ${RULES_ROOT_ENV_VAR})
+`;
+const parseArgs = (argv) => {
+    const args = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            args.help = true;
+            continue;
+        }
+        if (arg === "--root") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --root");
+            }
+            args.root = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--ruleset") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --ruleset");
+            }
+            args.ruleset = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--ruleset-name") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --ruleset-name");
+            }
+            args.rulesetName = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--rules-root") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --rules-root");
+            }
+            args.rulesRoot = value;
+            i += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return args;
+};
+const normalizeTrailingWhitespace = (content) => content.replace(/\s+$/u, "");
+const normalizePath = (filePath) => filePath.replace(/\\/g, "/");
+const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+const resolveFrom = (baseDir, targetPath) => {
+    if (node_path_1.default.isAbsolute(targetPath)) {
+        return targetPath;
+    }
+    return node_path_1.default.resolve(baseDir, targetPath);
+};
+const ensureFileExists = (filePath) => {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        throw new Error(`Missing file: ${filePath}`);
+    }
+};
+const ensureDirectoryExists = (dirPath) => {
+    if (!node_fs_1.default.existsSync(dirPath)) {
+        throw new Error(`Missing directory: ${dirPath}`);
+    }
+    const stat = node_fs_1.default.statSync(dirPath);
+    if (!stat.isDirectory()) {
+        throw new Error(`Not a directory: ${dirPath}`);
+    }
+};
+const readJsonFile = (filePath) => {
+    const raw = node_fs_1.default.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+};
+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}`);
+            }
+        }
+    }
+    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}`);
+            }
+        }
+    }
+    return parsed;
+};
+const resolveRulesRoot = (rulesetDir, projectRuleset, options) => {
+    if (isNonEmptyString(options.cliRulesRoot)) {
+        return resolveFrom(rulesetDir, options.cliRulesRoot);
+    }
+    const envRulesRoot = process.env[RULES_ROOT_ENV_VAR];
+    if (isNonEmptyString(envRulesRoot)) {
+        return resolveFrom(rulesetDir, envRulesRoot);
+    }
+    if (isNonEmptyString(projectRuleset.rulesRoot)) {
+        return resolveFrom(rulesetDir, projectRuleset.rulesRoot);
+    }
+    return node_path_1.default.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);
+};
+const resolveDomainsRoot = (rulesRoot, projectRuleset) => {
+    const domainsDirName = isNonEmptyString(projectRuleset.domainsDir)
+        ? projectRuleset.domainsDir
+        : DEFAULT_DOMAINS_DIR;
+    return node_path_1.default.resolve(rulesRoot, domainsDirName);
+};
+const collectMarkdownFiles = (rootDir) => {
+    ensureDirectoryExists(rootDir);
+    const results = [];
+    const pending = [rootDir];
+    while (pending.length > 0) {
+        const currentDir = pending.pop();
+        if (!currentDir) {
+            continue;
+        }
+        const entries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = node_path_1.default.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                pending.push(entryPath);
+                continue;
+            }
+            if (entry.isFile() && node_path_1.default.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));
+        return relA.localeCompare(relB);
+    });
+};
+const addRulePaths = (rulePaths, resolvedRules, seenRules) => {
+    for (const rulePath of rulePaths) {
+        const resolvedRulePath = node_path_1.default.resolve(rulePath);
+        if (seenRules.has(resolvedRulePath)) {
+            continue;
+        }
+        ensureFileExists(resolvedRulePath);
+        resolvedRules.push(resolvedRulePath);
+        seenRules.add(resolvedRulePath);
+    }
+};
+const composeRuleset = (rulesetPath, rootDir, options) => {
+    const rulesetDir = node_path_1.default.dirname(rulesetPath);
+    const projectRuleset = readProjectRuleset(rulesetPath);
+    const outputFileName = projectRuleset.output ?? DEFAULT_OUTPUT;
+    const outputPath = resolveFrom(rulesetDir, outputFileName);
+    const rulesRoot = resolveRulesRoot(rulesetDir, projectRuleset, {
+        cliRulesRoot: options.cliRulesRoot
+    });
+    const globalRoot = resolveGlobalRoot(rulesRoot, projectRuleset);
+    const domainsRoot = resolveDomainsRoot(rulesRoot, projectRuleset);
+    const resolvedRules = [];
+    const seenRules = new Set();
+    // Global rules always apply.
+    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);
+        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 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 findRulesetFiles = (rootDir, rulesetName) => {
+    const results = [];
+    const pending = [rootDir];
+    while (pending.length > 0) {
+        const currentDir = pending.pop();
+        if (!currentDir) {
+            continue;
+        }
+        const entries = node_fs_1.default.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = node_path_1.default.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (DEFAULT_IGNORE_DIRS.has(entry.name)) {
+                    continue;
+                }
+                pending.push(entryPath);
+                continue;
+            }
+            if (entry.isFile() && entry.name === rulesetName) {
+                results.push(entryPath);
+            }
+        }
+    }
+    return results;
+};
+const getRulesetFiles = (rootDir, specificRuleset, rulesetName) => {
+    if (specificRuleset) {
+        const resolved = resolveFrom(rootDir, specificRuleset);
+        ensureFileExists(resolved);
+        return [resolved];
+    }
+    return findRulesetFiles(rootDir, rulesetName);
+};
+const main = () => {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(`${usage}\n`);
+        return;
+    }
+    const rootDir = args.root ? node_path_1.default.resolve(args.root) : process.cwd();
+    const rulesetName = args.rulesetName || DEFAULT_RULESET_NAME;
+    const rulesetFiles = getRulesetFiles(rootDir, args.ruleset, rulesetName);
+    if (rulesetFiles.length === 0) {
+        throw new Error(`No ruleset files named ${rulesetName} found under ${rootDir}`);
+    }
+    const outputs = rulesetFiles
+        .sort()
+        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { cliRulesRoot: args.rulesRoot }));
+    process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
+};
+try {
+    main();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.stderr.write(`${usage}\n`);
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "compose-agentsmd",
+  "version": "1.0.0",
+  "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/metyatech/compose-agentsmd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/metyatech/compose-agentsmd/issues"
+  },
+  "homepage": "https://github.com/metyatech/compose-agentsmd#readme",
+  "keywords": [
+    "agents",
+    "agentsmd",
+    "rules",
+    "cli",
+    "markdown"
+  ],
+  "type": "commonjs",
+  "bin": {
+    "compose-agentsmd": "dist/compose-agents.js"
+  },
+  "files": [
+    "dist",
+    "tools"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test",
+    "compose": "npm run build && node dist/compose-agents.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "typescript": "^5.7.3"
+  }
+}

package/tools/compose-agents.cjs

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