compose-agentsmd 2.0.1 → 3.0.0

package/README.md

@@ -30,10 +30,27 @@ From each project root, run:
 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 reads `agent-ruleset.json` from the given root directory (default: current working directory), and writes the output file specified by the 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.
 
+## Updating shared rules
+
+For GitHub sources, the tool keeps two locations:
+
+- Cache: `~/.agentsmd/cache/<owner>/<repo>/<ref>/` (read-only, used for compose)
+- Workspace: `~/.agentsmd/workspace/<owner>/<repo>/` (editable)
+
+Update flow:
+
+```sh
+compose-agentsmd edit-rules
+# edit files under rules/ in the workspace
+compose-agentsmd apply-rules
+```
+
+`edit-rules` clones the GitHub source into the workspace (or reuses it). `apply-rules` pushes the workspace (if clean) and regenerates `AGENTS.md` by refreshing the cache. If your `source` is a local path, `edit-rules` will just print that path and `apply-rules` will skip the push.
+
 ## Project ruleset format
 
 ```json
@@ -59,7 +76,7 @@ Ruleset keys:
 
 ### Cache
 
-Remote sources are cached under `~/.agentsmd/<owner>/<repo>/<ref>/`. Use `--refresh` to re-fetch or `--clear-cache` to remove cached rules.
+Remote sources are cached under `~/.agentsmd/cache/<owner>/<repo>/<ref>/`. Use `--refresh` to re-fetch or `--clear-cache` to remove cached rules.
 
 ### Optional arguments
 
@@ -68,6 +85,8 @@ Remote sources are cached under `~/.agentsmd/<owner>/<repo>/<ref>/`. Use `--refr
 - `--ruleset-name <name>`: override the ruleset filename (default: `agent-ruleset.json`)
 - `--refresh`: refresh cached remote rules
 - `--clear-cache`: remove cached remote rules and exit
+- `edit-rules`: prepare or locate a writable rules workspace
+- `apply-rules`: push workspace changes (if GitHub source) and regenerate rules with refresh
 
 ## Development
 

package/dist/compose-agents.js

@@ -6,48 +6,26 @@ import { execFileSync } from "node:child_process";
 import { Ajv } from "ajv";
 const DEFAULT_RULESET_NAME = "agent-ruleset.json";
 const DEFAULT_OUTPUT = "AGENTS.md";
-const DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd");
+const DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd", "cache");
+const DEFAULT_WORKSPACE_ROOT = path.join(os.homedir(), ".agentsmd", "workspace");
 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",
-    "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>] [--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)
-  --refresh             Refresh cached remote rules
-  --clear-cache         Remove cached remote rules and exit
-`;
+const TOOL_RULES_PATH = new URL("../tools/tool-rules.md", import.meta.url);
+const USAGE_PATH = new URL("../tools/usage.txt", import.meta.url);
 const parseArgs = (argv) => {
     const args = {};
-    for (let i = 0; i < argv.length; i += 1) {
-        const arg = argv[i];
+    const knownCommands = new Set(["edit-rules", "apply-rules"]);
+    const remaining = [...argv];
+    if (remaining.length > 0 && knownCommands.has(remaining[0])) {
+        args.command = remaining.shift();
+    }
+    for (let i = 0; i < remaining.length; i += 1) {
+        const arg = remaining[i];
         if (arg === "--help" || arg === "-h") {
             args.help = true;
             continue;
         }
         if (arg === "--root") {
-            const value = argv[i + 1];
+            const value = remaining[i + 1];
             if (!value) {
                 throw new Error("Missing value for --root");
             }
@@ -56,7 +34,7 @@ const parseArgs = (argv) => {
             continue;
         }
         if (arg === "--ruleset") {
-            const value = argv[i + 1];
+            const value = remaining[i + 1];
             if (!value) {
                 throw new Error("Missing value for --ruleset");
             }
@@ -65,7 +43,7 @@ const parseArgs = (argv) => {
             continue;
         }
         if (arg === "--ruleset-name") {
-            const value = argv[i + 1];
+            const value = remaining[i + 1];
             if (!value) {
                 throw new Error("Missing value for --ruleset-name");
             }
@@ -88,7 +66,9 @@ 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 usage = normalizeTrailingWhitespace(fs.readFileSync(USAGE_PATH, "utf8"));
 const rulesetSchema = JSON.parse(fs.readFileSync(RULESET_SCHEMA_PATH, "utf8"));
+const TOOL_RULES = normalizeTrailingWhitespace(fs.readFileSync(TOOL_RULES_PATH, "utf8"));
 const ajv = new Ajv({ allErrors: true, strict: false });
 const validateRulesetSchema = ajv.compile(rulesetSchema);
 const formatSchemaErrors = (errors) => {
@@ -108,6 +88,9 @@ const resolveFrom = (baseDir, targetPath) => {
     }
     return path.resolve(baseDir, targetPath);
 };
+const ensureDir = (dirPath) => {
+    fs.mkdirSync(dirPath, { recursive: true });
+};
 const clearCache = () => {
     if (fs.existsSync(DEFAULT_CACHE_ROOT)) {
         fs.rmSync(DEFAULT_CACHE_ROOT, { recursive: true, force: true });
@@ -270,9 +253,6 @@ const resolveRefHash = (repoUrl, ref) => {
     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]);
 };
@@ -329,6 +309,41 @@ const resolveLocalRulesRoot = (rulesetDir, source) => {
     ensureDirectoryExists(candidate);
     return candidate;
 };
+const resolveWorkspaceRoot = (rulesetDir, source) => {
+    if (source.startsWith("github:")) {
+        const parsed = parseGithubSource(source);
+        return path.join(DEFAULT_WORKSPACE_ROOT, parsed.owner, parsed.repo);
+    }
+    return resolveFrom(rulesetDir, source);
+};
+const ensureWorkspaceForGithubSource = (source) => {
+    const parsed = parseGithubSource(source);
+    const workspaceRoot = path.join(DEFAULT_WORKSPACE_ROOT, parsed.owner, parsed.repo);
+    if (!fs.existsSync(workspaceRoot)) {
+        ensureDir(path.dirname(workspaceRoot));
+        execGit(["clone", parsed.url, workspaceRoot]);
+    }
+    if (parsed.ref !== "latest") {
+        execGit(["fetch", "--all"], workspaceRoot);
+        execGit(["checkout", parsed.ref], workspaceRoot);
+    }
+    return workspaceRoot;
+};
+const applyRulesFromWorkspace = (rulesetDir, source) => {
+    if (!source.startsWith("github:")) {
+        return;
+    }
+    const workspaceRoot = ensureWorkspaceForGithubSource(source);
+    const status = execGit(["status", "--porcelain"], workspaceRoot);
+    if (status) {
+        throw new Error(`Workspace has uncommitted changes: ${workspaceRoot}`);
+    }
+    const branch = execGit(["rev-parse", "--abbrev-ref", "HEAD"], workspaceRoot);
+    if (branch === "HEAD") {
+        throw new Error(`Workspace is in detached HEAD state: ${workspaceRoot}`);
+    }
+    execGit(["push"], workspaceRoot);
+};
 const resolveRulesRoot = (rulesetDir, source, refresh) => {
     if (source.startsWith("github:")) {
         return resolveGithubRulesRoot(source, refresh);
@@ -364,38 +379,24 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     fs.writeFileSync(outputPath, output, "utf8");
     return normalizePath(path.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 = fs.readdirSync(currentDir, { withFileTypes: true });
-        for (const entry of entries) {
-            const entryPath = path.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 defaultRuleset = path.join(rootDir, rulesetName);
+    if (!fs.existsSync(defaultRuleset)) {
+        return [];
+    }
+    return [defaultRuleset];
+};
+const ensureSingleRuleset = (rulesetFiles, rootDir, rulesetName) => {
+    if (rulesetFiles.length === 0) {
+        const expectedPath = normalizePath(path.join(rootDir, rulesetName));
+        throw new Error(`Missing ruleset file: ${expectedPath}`);
+    }
+    return rulesetFiles[0];
 };
 const main = () => {
     const args = parseArgs(process.argv.slice(2));
@@ -411,8 +412,30 @@ const main = () => {
     const rootDir = args.root ? path.resolve(args.root) : process.cwd();
     const rulesetName = args.rulesetName || DEFAULT_RULESET_NAME;
     const rulesetFiles = getRulesetFiles(rootDir, args.ruleset, rulesetName);
+    const command = args.command ?? "compose";
+    if (command === "edit-rules") {
+        const rulesetPath = ensureSingleRuleset(rulesetFiles, rootDir, rulesetName);
+        const rulesetDir = path.dirname(rulesetPath);
+        const ruleset = readProjectRuleset(rulesetPath);
+        let workspaceRoot = resolveWorkspaceRoot(rulesetDir, ruleset.source);
+        if (ruleset.source.startsWith("github:")) {
+            workspaceRoot = ensureWorkspaceForGithubSource(ruleset.source);
+        }
+        process.stdout.write(`Rules workspace: ${workspaceRoot}\n`);
+        return;
+    }
+    if (command === "apply-rules") {
+        const rulesetPath = ensureSingleRuleset(rulesetFiles, rootDir, rulesetName);
+        const rulesetDir = path.dirname(rulesetPath);
+        const ruleset = readProjectRuleset(rulesetPath);
+        applyRulesFromWorkspace(rulesetDir, ruleset.source);
+        const output = composeRuleset(rulesetPath, rootDir, { refresh: true });
+        process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+        return;
+    }
     if (rulesetFiles.length === 0) {
-        throw new Error(`No ruleset files named ${rulesetName} found under ${rootDir}`);
+        const expectedPath = normalizePath(path.join(rootDir, rulesetName));
+        throw new Error(`Missing ruleset file: ${expectedPath}`);
     }
     const outputs = rulesetFiles
         .sort()

package/package.json

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

package/tools/tool-rules.md

@@ -0,0 +1,4 @@
+# Tool Rules (compose-agentsmd)
+- Before starting any work, run `compose-agentsmd` from the project root.
+- To update shared rules, run `compose-agentsmd edit-rules`, edit the workspace rules, then run `compose-agentsmd apply-rules`.
+- Do not edit `AGENTS.md` directly; update the source rules and regenerate.

package/tools/usage.txt

@@ -0,0 +1,8 @@
+Usage: compose-agentsmd [edit-rules|apply-rules] [--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 in the project root (default: agent-ruleset.json)
+  --refresh             Refresh cached remote rules
+  --clear-cache         Remove cached remote rules and exit