compose-agentsmd 3.2.5 → 3.2.7

package/README.md

@@ -35,6 +35,8 @@ The tool reads `agent-ruleset.json` from the given root directory (default: curr
 The tool prepends a small "Tool Rules" block to every generated `AGENTS.md` so agents know how to regenerate or update rules.
 Each composed rule section is also prefixed with the source file path that produced it.
 
+When the output file is `AGENTS.md`, the CLI also prints a unified diff for `AGENTS.md` when it changes (and prints `AGENTS.md unchanged.` when it does not). This works even when the project is not under git. `--quiet` and `--json` suppress this output.
+
 ## Setup (init)
 
 For a project that does not have a ruleset yet, bootstrap one with `init`:
@@ -68,7 +70,7 @@ compose-agentsmd edit-rules
 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.
+`edit-rules` clones the GitHub source into the workspace (or reuses it), then prints the workspace path, rules directory, and next steps. `apply-rules` pushes the workspace (if clean) and regenerates `AGENTS.md` by refreshing the cache. If your `source` is a local path, `edit-rules` points to the local workspace and `apply-rules` skips the push.
 
 ## Project ruleset format
 

package/dist/compose-agents.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import { execFileSync } from "node:child_process";
 import readline from "node:readline";
 import { Ajv } from "ajv";
+import { createTwoFilesPatch } from "diff";
 const DEFAULT_RULESET_NAME = "agent-ruleset.json";
 const DEFAULT_OUTPUT = "AGENTS.md";
 const DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd", "cache");
@@ -520,6 +521,7 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     const projectRuleset = readProjectRuleset(rulesetPath);
     const outputFileName = projectRuleset.output ?? DEFAULT_OUTPUT;
     const outputPath = resolveFrom(rulesetDir, outputFileName);
+    const composedOutputPath = normalizePath(path.relative(rootDir, outputPath));
     const { rulesRoot, resolvedRef } = resolveRulesRoot(rulesetDir, projectRuleset.source, options.refresh ?? false);
     const globalRoot = path.join(rulesRoot, "global");
     const domainsRoot = path.join(rulesRoot, "domains");
@@ -544,11 +546,42 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
     const toolRules = normalizeTrailingWhitespace(TOOL_RULES);
     const output = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
+    let agentsMdDiff;
+    if (options.emitAgentsMdDiff && path.basename(outputPath) === DEFAULT_OUTPUT) {
+        const before = fs.existsSync(outputPath) ? fs.readFileSync(outputPath, "utf8") : "";
+        if (before === output) {
+            agentsMdDiff = { status: "unchanged" };
+        }
+        else {
+            agentsMdDiff = {
+                status: "updated",
+                patch: createTwoFilesPatch(`a/${composedOutputPath}`, `b/${composedOutputPath}`, before, output, "", "", { context: 3 })
+            };
+        }
+    }
     if (!options.dryRun) {
         fs.mkdirSync(path.dirname(outputPath), { recursive: true });
         fs.writeFileSync(outputPath, output, "utf8");
     }
-    return normalizePath(path.relative(rootDir, outputPath));
+    return { output: composedOutputPath, agentsMdDiff };
+};
+const printAgentsMdDiffIfPresent = (result) => {
+    if (!result.agentsMdDiff) {
+        return;
+    }
+    if (result.agentsMdDiff.status === "unchanged") {
+        process.stdout.write("AGENTS.md unchanged.\n");
+        return;
+    }
+    process.stdout.write("AGENTS.md updated. ACTION (agent): refresh rule recognition from the diff below.\n");
+    process.stdout.write("--- BEGIN DIFF ---\n");
+    if (result.agentsMdDiff.patch) {
+        process.stdout.write(result.agentsMdDiff.patch);
+        if (!result.agentsMdDiff.patch.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+    }
+    process.stdout.write("--- END DIFF ---\n");
 };
 const LOCAL_RULES_TEMPLATE = "# Local Rules\n\n- Add project-specific instructions here.\n";
 const buildInitRuleset = (args) => {
@@ -678,13 +711,16 @@ const initProject = async (args, rootDir, rulesetName) => {
     }
     let composedOutput;
     if (args.compose) {
-        composedOutput = composeRuleset(rulesetPath, rootDir, { refresh: args.refresh ?? false });
+        composedOutput = composeRuleset(rulesetPath, rootDir, {
+            refresh: args.refresh ?? false,
+            emitAgentsMdDiff: !args.quiet && !args.json
+        });
     }
     if (args.json) {
         process.stdout.write(JSON.stringify({
             initialized: [normalizePath(path.relative(rootDir, rulesetPath))],
             localRules: extraToWrite.map((filePath) => normalizePath(path.relative(rootDir, filePath))),
-            composed: composedOutput ? [composedOutput] : [],
+            composed: composedOutput ? [composedOutput.output] : [],
             dryRun: false
         }, null, 2) + "\n");
     }
@@ -696,7 +732,8 @@ const initProject = async (args, rootDir, rulesetName) => {
                 .join("\n")}\n`);
         }
         if (composedOutput) {
-            process.stdout.write(`Composed AGENTS.md:\n- ${composedOutput}\n`);
+            process.stdout.write(`Composed AGENTS.md:\n- ${composedOutput.output}\n`);
+            printAgentsMdDiffIfPresent(composedOutput);
         }
     }
 };
@@ -755,7 +792,17 @@ const main = async () => {
         if (ruleset.source.startsWith("github:")) {
             workspaceRoot = ensureWorkspaceForGithubSource(ruleset.source);
         }
-        process.stdout.write(`Rules workspace: ${workspaceRoot}\n`);
+        const rulesDirectory = ruleset.source.startsWith("github:")
+            ? path.join(workspaceRoot, "rules")
+            : resolveLocalRulesRoot(rulesetDir, ruleset.source);
+        process.stdout.write([
+            `Rules workspace: ${workspaceRoot}`,
+            `Rules directory: ${rulesDirectory}`,
+            "Next steps:",
+            `- Edit rule files under: ${rulesDirectory}`,
+            "- If this source is GitHub, commit and push the workspace changes before apply-rules.",
+            "- Run compose-agentsmd apply-rules from your project root to apply updates and regenerate AGENTS.md."
+        ].join("\n") + "\n");
         return;
     }
     if (command === "init") {
@@ -767,12 +814,17 @@ const main = async () => {
         const rulesetDir = path.dirname(rulesetPath);
         const ruleset = readProjectRuleset(rulesetPath);
         applyRulesFromWorkspace(rulesetDir, ruleset.source);
-        const output = composeRuleset(rulesetPath, rootDir, { refresh: true, dryRun: args.dryRun });
+        const output = composeRuleset(rulesetPath, rootDir, {
+            refresh: true,
+            dryRun: args.dryRun,
+            emitAgentsMdDiff: !args.quiet && !args.json
+        });
         if (args.json) {
-            process.stdout.write(JSON.stringify({ composed: [output], dryRun: !!args.dryRun }, null, 2) + "\n");
+            process.stdout.write(JSON.stringify({ composed: [output.output], dryRun: !!args.dryRun }, null, 2) + "\n");
         }
         else if (!args.quiet) {
-            process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+            process.stdout.write(`Composed AGENTS.md:\n- ${output.output}\n`);
+            printAgentsMdDiffIfPresent(output);
         }
         return;
     }
@@ -782,12 +834,19 @@ const main = async () => {
     }
     const outputs = rulesetFiles
         .sort()
-        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh, dryRun: args.dryRun }));
+        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, {
+        refresh: args.refresh,
+        dryRun: args.dryRun,
+        emitAgentsMdDiff: !args.quiet && !args.json
+    }));
     if (args.json) {
-        process.stdout.write(JSON.stringify({ composed: outputs, dryRun: !!args.dryRun }, null, 2) + "\n");
+        process.stdout.write(JSON.stringify({ composed: outputs.map((result) => result.output), dryRun: !!args.dryRun }, null, 2) + "\n");
     }
     else if (!args.quiet) {
-        process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
+        process.stdout.write(`Composed AGENTS.md:\n${outputs.map((result) => `- ${result.output}`).join("\n")}\n`);
+        for (const result of outputs) {
+            printAgentsMdDiffIfPresent(result);
+        }
     }
 };
 const run = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "diff": "^8.0.3"
   }
 }

package/tools/tool-rules.md

@@ -3,6 +3,7 @@
 - `compose-agentsmd` intentionally regenerates `AGENTS.md`; any resulting `AGENTS.md` diff is expected and must not be treated as an unexpected external change.
 - If `compose-agentsmd` is not available, install it via npm: `npm install -g compose-agentsmd`.
 - To update shared rules, run `compose-agentsmd edit-rules`, edit the workspace rules, then run `compose-agentsmd apply-rules`.
+- `compose-agentsmd apply-rules` pushes the rules workspace when `source` is GitHub (if the workspace is clean), then regenerates `AGENTS.md` with refreshed rules.
 - Do not edit `AGENTS.md` directly; update the source rules and regenerate.
 - `tools/tool-rules.md` is the shared rule source for all repositories that use compose-agentsmd.
 - Before applying any rule updates, present the planned changes first (prefer a colorized diff-style preview), ask for explicit approval, then make the edits.