compose-agentsmd 1.1.2 → 2.0.1

package/README.md

@@ -6,10 +6,7 @@ This repository contains CLI tooling for composing per-project `AGENTS.md` files
 
 See `CHANGELOG.md` for release notes.
 
-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)
+It is intended to be used together with shared rule modules such as the public `agent-rules` repository.
 
 ## Install (global CLI)
 
@@ -23,17 +20,7 @@ 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`.
+The default ruleset for this repository is `agent-ruleset.json` and currently composes the `node` domain into `AGENTS.md` from the shared GitHub source.
 
 ## Compose
 
@@ -47,59 +34,40 @@ The tool searches for `agent-ruleset.json` under the given root directory (defau
 
 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:
-
-```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",
+  "source": "github:org/agent-rules@latest",
   "domains": ["node", "unreal"],
-  "rules": ["agent-rules-local/custom.md"]
+  "extra": ["agent-rules-local/custom.md"],
+  "output": "AGENTS.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.
+Ruleset keys:
+
+- `source` (required): rules source. Use `github:owner/repo@ref` or a local path.
+- `global` (optional): include `rules/global` (defaults to true). Omit this unless you want to disable globals.
+- `domains` (optional): domain folders under `rules/domains/<domain>`.
+- `extra` (optional): additional local rule files to append.
+- `output` (optional): output file name (defaults to `AGENTS.md`).
 
 ### 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:
+### Cache
 
-- `rulesRoot`: override `agent-rules/rules`.
-- `globalDir`: override `global` (relative to `rulesRoot`).
-- `domainsDir`: override `domains` (relative to `rulesRoot`).
+Remote sources are cached under `~/.agentsmd/<owner>/<repo>/<ref>/`. Use `--refresh` to re-fetch or `--clear-cache` to remove cached rules.
 
 ### 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`)
+- `--refresh`: refresh cached remote rules
+- `--clear-cache`: remove cached remote rules and exit
 
 ## Development
 

package/agent-ruleset.schema.json

@@ -3,7 +3,15 @@
   "title": "Compose AGENTS.md ruleset",
   "type": "object",
   "additionalProperties": false,
+  "required": ["source"],
   "properties": {
+    "source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "global": {
+      "type": "boolean"
+    },
     "output": {
       "type": "string",
       "minLength": 1
@@ -15,24 +23,12 @@
         "minLength": 1
       }
     },
-    "rules": {
+    "extra": {
       "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,13 +1,12 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
 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 DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd");
 const RULESET_SCHEMA_PATH = new URL("../agent-ruleset.schema.json", import.meta.url);
 const TOOL_RULES = [
     "# Tool Rules (compose-agentsmd)",
@@ -30,13 +29,14 @@ const DEFAULT_IGNORE_DIRS = new Set([
     ".turbo",
     "coverage"
 ]);
-const usage = `Usage: compose-agentsmd [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--rules-root <path>]
+const usage = `Usage: compose-agentsmd [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--refresh] [--clear-cache]
 
 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})
+  --refresh             Refresh cached remote rules
+  --clear-cache         Remove cached remote rules and exit
 `;
 const parseArgs = (argv) => {
     const args = {};
@@ -73,13 +73,12 @@ const parseArgs = (argv) => {
             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;
+        if (arg === "--refresh") {
+            args.refresh = true;
+            continue;
+        }
+        if (arg === "--clear-cache") {
+            args.clearCache = true;
             continue;
         }
         throw new Error(`Unknown argument: ${arg}`);
@@ -109,6 +108,11 @@ const resolveFrom = (baseDir, targetPath) => {
     }
     return path.resolve(baseDir, targetPath);
 };
+const clearCache = () => {
+    if (fs.existsSync(DEFAULT_CACHE_ROOT)) {
+        fs.rmSync(DEFAULT_CACHE_ROOT, { recursive: true, force: true });
+    }
+};
 const ensureFileExists = (filePath) => {
     if (!fs.existsSync(filePath)) {
         throw new Error(`Missing file: ${filePath}`);
@@ -138,32 +142,10 @@ const readProjectRuleset = (rulesetPath) => {
     if (ruleset.output === undefined) {
         ruleset.output = DEFAULT_OUTPUT;
     }
-    return ruleset;
-};
-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 (ruleset.global === undefined) {
+        ruleset.global = true;
     }
-    if (isNonEmptyString(projectRuleset.rulesRoot)) {
-        return resolveFrom(rulesetDir, projectRuleset.rulesRoot);
-    }
-    return path.resolve(rulesetDir, DEFAULT_RULES_ROOT);
-};
-const resolveGlobalRoot = (rulesRoot, projectRuleset) => {
-    const globalDirName = isNonEmptyString(projectRuleset.globalDir)
-        ? projectRuleset.globalDir
-        : DEFAULT_GLOBAL_DIR;
-    return path.resolve(rulesRoot, globalDirName);
-};
-const resolveDomainsRoot = (rulesRoot, projectRuleset) => {
-    const domainsDirName = isNonEmptyString(projectRuleset.domainsDir)
-        ? projectRuleset.domainsDir
-        : DEFAULT_DOMAINS_DIR;
-    return path.resolve(rulesRoot, domainsDirName);
+    return ruleset;
 };
 const collectMarkdownFiles = (rootDir) => {
     ensureDirectoryExists(rootDir);
@@ -203,27 +185,176 @@ const addRulePaths = (rulePaths, resolvedRules, seenRules) => {
         seenRules.add(resolvedRulePath);
     }
 };
+const sanitizeCacheSegment = (value) => value.replace(/[\\/]/gu, "__");
+const looksLikeCommitHash = (value) => /^[a-f0-9]{7,40}$/iu.test(value);
+const execGit = (args, cwd) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+const parseGithubSource = (source) => {
+    const trimmed = source.trim();
+    if (!trimmed.startsWith("github:")) {
+        throw new Error(`Unsupported source: ${source}`);
+    }
+    const withoutPrefix = trimmed.slice("github:".length);
+    const [repoPart, refPart] = withoutPrefix.split("@");
+    const [owner, repo] = repoPart.split("/");
+    if (!isNonEmptyString(owner) || !isNonEmptyString(repo)) {
+        throw new Error(`Invalid GitHub source (expected github:owner/repo@ref): ${source}`);
+    }
+    const ref = isNonEmptyString(refPart) ? refPart : "latest";
+    return { owner, repo, ref, url: `https://github.com/${owner}/${repo}.git` };
+};
+const parseSemver = (tag) => {
+    const cleaned = tag.startsWith("v") ? tag.slice(1) : tag;
+    const parts = cleaned.split(".");
+    if (parts.length < 2 || parts.length > 3) {
+        return null;
+    }
+    const numbers = parts.map((part) => Number(part));
+    if (numbers.some((value) => Number.isNaN(value))) {
+        return null;
+    }
+    return numbers;
+};
+const compareSemver = (a, b) => {
+    const maxLength = Math.max(a.length, b.length);
+    for (let i = 0; i < maxLength; i += 1) {
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left !== right) {
+            return left - right;
+        }
+    }
+    return 0;
+};
+const resolveLatestTag = (repoUrl) => {
+    const raw = execGit(["ls-remote", "--tags", "--refs", repoUrl]);
+    if (!raw) {
+        return {};
+    }
+    const candidates = raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [hash, ref] = line.split(/\s+/u);
+        const tag = ref?.replace("refs/tags/", "");
+        if (!hash || !tag) {
+            return null;
+        }
+        const semver = parseSemver(tag);
+        if (!semver) {
+            return null;
+        }
+        return { hash, tag, semver };
+    })
+        .filter((item) => Boolean(item));
+    if (candidates.length === 0) {
+        return {};
+    }
+    candidates.sort((a, b) => compareSemver(a.semver, b.semver));
+    const latest = candidates[candidates.length - 1];
+    return { tag: latest.tag, hash: latest.hash };
+};
+const resolveHeadHash = (repoUrl) => {
+    const raw = execGit(["ls-remote", repoUrl, "HEAD"]);
+    const [hash] = raw.split(/\s+/u);
+    if (!hash) {
+        throw new Error(`Unable to resolve HEAD for ${repoUrl}`);
+    }
+    return hash;
+};
+const resolveRefHash = (repoUrl, ref) => {
+    const raw = execGit(["ls-remote", repoUrl, ref, `refs/tags/${ref}`, `refs/heads/${ref}`]);
+    if (!raw) {
+        return null;
+    }
+    const [hash] = raw.split(/\s+/u);
+    return hash ?? null;
+};
+const ensureDir = (dirPath) => {
+    fs.mkdirSync(dirPath, { recursive: true });
+};
+const cloneAtRef = (repoUrl, ref, destination) => {
+    execGit(["clone", "--depth", "1", "--branch", ref, repoUrl, destination]);
+};
+const fetchCommit = (repoUrl, commitHash, destination) => {
+    ensureDir(destination);
+    execGit(["init"], destination);
+    execGit(["remote", "add", "origin", repoUrl], destination);
+    execGit(["fetch", "--depth", "1", "origin", commitHash], destination);
+    execGit(["checkout", "FETCH_HEAD"], destination);
+};
+const resolveGithubRulesRoot = (source, refresh) => {
+    const parsed = parseGithubSource(source);
+    const resolved = parsed.ref === "latest" ? resolveLatestTag(parsed.url) : null;
+    const resolvedRef = resolved?.tag ?? (parsed.ref === "latest" ? "HEAD" : parsed.ref);
+    const resolvedHash = resolved?.hash ??
+        (resolvedRef === "HEAD"
+            ? resolveHeadHash(parsed.url)
+            : resolveRefHash(parsed.url, resolvedRef));
+    if (!resolvedHash && !looksLikeCommitHash(resolvedRef)) {
+        throw new Error(`Unable to resolve ref ${resolvedRef} for ${parsed.url}`);
+    }
+    const cacheSegment = resolvedRef === "HEAD" ? sanitizeCacheSegment(resolvedHash ?? resolvedRef) : sanitizeCacheSegment(resolvedRef);
+    const cacheDir = path.join(DEFAULT_CACHE_ROOT, parsed.owner, parsed.repo, cacheSegment);
+    if (refresh && fs.existsSync(cacheDir)) {
+        fs.rmSync(cacheDir, { recursive: true, force: true });
+    }
+    if (!fs.existsSync(cacheDir)) {
+        ensureDir(path.dirname(cacheDir));
+        try {
+            cloneAtRef(parsed.url, resolvedRef, cacheDir);
+        }
+        catch (error) {
+            if (resolvedHash && looksLikeCommitHash(resolvedHash)) {
+                fetchCommit(parsed.url, resolvedHash, cacheDir);
+            }
+            else if (looksLikeCommitHash(resolvedRef)) {
+                fetchCommit(parsed.url, resolvedRef, cacheDir);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const rulesRoot = path.join(cacheDir, "rules");
+    ensureDirectoryExists(rulesRoot);
+    return { rulesRoot, resolvedRef };
+};
+const resolveLocalRulesRoot = (rulesetDir, source) => {
+    const resolvedSource = resolveFrom(rulesetDir, source);
+    if (!fs.existsSync(resolvedSource)) {
+        throw new Error(`Missing source path: ${resolvedSource}`);
+    }
+    const candidate = path.basename(resolvedSource) === "rules" ? resolvedSource : path.join(resolvedSource, "rules");
+    ensureDirectoryExists(candidate);
+    return candidate;
+};
+const resolveRulesRoot = (rulesetDir, source, refresh) => {
+    if (source.startsWith("github:")) {
+        return resolveGithubRulesRoot(source, refresh);
+    }
+    return { rulesRoot: resolveLocalRulesRoot(rulesetDir, source) };
+};
 const composeRuleset = (rulesetPath, rootDir, options) => {
     const rulesetDir = path.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 { rulesRoot } = resolveRulesRoot(rulesetDir, projectRuleset.source, options.refresh ?? false);
+    const globalRoot = path.join(rulesRoot, "global");
+    const domainsRoot = path.join(rulesRoot, "domains");
     const resolvedRules = [];
     const seenRules = new Set();
-    // Global rules always apply.
-    addRulePaths(collectMarkdownFiles(globalRoot), resolvedRules, seenRules);
+    if (projectRuleset.global !== false) {
+        addRulePaths(collectMarkdownFiles(globalRoot), resolvedRules, seenRules);
+    }
     const domains = Array.isArray(projectRuleset.domains) ? projectRuleset.domains : [];
     for (const domain of domains) {
         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));
+    const extraRules = Array.isArray(projectRuleset.extra) ? projectRuleset.extra : [];
+    const directRulePaths = extraRules.map((rulePath) => resolveFrom(rulesetDir, rulePath));
     addRulePaths(directRulePaths, resolvedRules, seenRules);
     const parts = resolvedRules.map((rulePath) => normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8")));
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
@@ -272,6 +403,11 @@ const main = () => {
         process.stdout.write(`${usage}\n`);
         return;
     }
+    if (args.clearCache) {
+        clearCache();
+        process.stdout.write("Cache cleared.\n");
+        return;
+    }
     const rootDir = args.root ? path.resolve(args.root) : process.cwd();
     const rulesetName = args.rulesetName || DEFAULT_RULESET_NAME;
     const rulesetFiles = getRulesetFiles(rootDir, args.ruleset, rulesetName);
@@ -280,7 +416,7 @@ const main = () => {
     }
     const outputs = rulesetFiles
         .sort()
-        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { cliRulesRoot: args.rulesRoot }));
+        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh }));
     process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
 };
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "1.1.2",
+  "version": "2.0.1",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {