compose-agentsmd 2.0.0 → 2.0.2

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,6 +34,23 @@ 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.
 
+## 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
@@ -72,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
 
@@ -81,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,14 +6,9 @@ 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",
@@ -29,25 +24,23 @@ const DEFAULT_IGNORE_DIRS = new Set([
     ".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 +49,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 +58,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 +81,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 +103,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 +268,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 +324,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);
@@ -397,6 +427,16 @@ const getRulesetFiles = (rootDir, specificRuleset, rulesetName) => {
     }
     return findRulesetFiles(rootDir, rulesetName);
 };
+const ensureSingleRuleset = (rulesetFiles, rootDir, rulesetName) => {
+    if (rulesetFiles.length === 0) {
+        throw new Error(`No ruleset files named ${rulesetName} found under ${rootDir}`);
+    }
+    if (rulesetFiles.length > 1) {
+        const list = rulesetFiles.map((file) => `- ${normalizePath(path.relative(rootDir, file))}`).join("\n");
+        throw new Error(`Multiple ruleset files found. Specify one with --ruleset:\n${list}`);
+    }
+    return rulesetFiles[0];
+};
 const main = () => {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
@@ -411,6 +451,27 @@ 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}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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 to search for (default: agent-ruleset.json)
+  --refresh             Refresh cached remote rules
+  --clear-cache         Remove cached remote rules and exit