compose-agentsmd 3.2.3 → 3.2.5

package/README.md

@@ -134,4 +134,11 @@ npm install
 npm run lint
 npm run build
 npm test
-```
+```
+
+## Overview
+This repository contains the compose-agentsmd project.
+
+## Requirements and Configuration
+- No required environment variables are documented.
+

package/dist/compose-agents.js

@@ -16,6 +16,13 @@ const RULESET_SCHEMA_PATH = new URL("../agent-ruleset.schema.json", import.meta.
 const PACKAGE_JSON_PATH = new URL("../package.json", import.meta.url);
 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 readValueArg = (remaining, index, flag) => {
+    const value = remaining[index + 1];
+    if (!value) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+};
 const parseArgs = (argv) => {
     const args = {};
     const knownCommands = new Set(["edit-rules", "apply-rules", "init"]);
@@ -37,29 +44,28 @@ const parseArgs = (argv) => {
             args.verbose = true;
             continue;
         }
+        if (arg === "--quiet" || arg === "-q") {
+            args.quiet = true;
+            continue;
+        }
+        if (arg === "--json") {
+            args.json = true;
+            continue;
+        }
         if (arg === "--root") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --root");
-            }
+            const value = readValueArg(remaining, i, "--root");
             args.root = value;
             i += 1;
             continue;
         }
         if (arg === "--ruleset") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --ruleset");
-            }
+            const value = readValueArg(remaining, i, "--ruleset");
             args.ruleset = value;
             i += 1;
             continue;
         }
         if (arg === "--ruleset-name") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --ruleset-name");
-            }
+            const value = readValueArg(remaining, i, "--ruleset-name");
             args.rulesetName = value;
             i += 1;
             continue;
@@ -73,19 +79,13 @@ const parseArgs = (argv) => {
             continue;
         }
         if (arg === "--source") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --source");
-            }
+            const value = readValueArg(remaining, i, "--source");
             args.source = value;
             i += 1;
             continue;
         }
         if (arg === "--domains") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --domains");
-            }
+            const value = readValueArg(remaining, i, "--domains");
             args.domains = [...(args.domains ?? []), ...value.split(",").map((entry) => entry.trim())];
             i += 1;
             continue;
@@ -95,10 +95,7 @@ const parseArgs = (argv) => {
             continue;
         }
         if (arg === "--extra") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --extra");
-            }
+            const value = readValueArg(remaining, i, "--extra");
             args.extra = [...(args.extra ?? []), ...value.split(",").map((entry) => entry.trim())];
             i += 1;
             continue;
@@ -108,10 +105,7 @@ const parseArgs = (argv) => {
             continue;
         }
         if (arg === "--output") {
-            const value = remaining[i + 1];
-            if (!value) {
-                throw new Error("Missing value for --output");
-            }
+            const value = readValueArg(remaining, i, "--output");
             args.output = value;
             i += 1;
             continue;
@@ -550,8 +544,10 @@ 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`;
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-    fs.writeFileSync(outputPath, output, "utf8");
+    if (!options.dryRun) {
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        fs.writeFileSync(outputPath, output, "utf8");
+    }
     return normalizePath(path.relative(rootDir, outputPath));
 };
 const LOCAL_RULES_TEMPLATE = "# Local Rules\n\n- Add project-specific instructions here.\n";
@@ -655,9 +651,22 @@ const initProject = async (args, rootDir, rulesetName) => {
             plan.push({ action: "create", path: outputPath });
         }
     }
-    process.stdout.write(formatPlan(plan, rootDir));
+    if (!args.quiet && !args.json) {
+        process.stdout.write(formatPlan(plan, rootDir));
+    }
     if (args.dryRun) {
-        process.stdout.write("Dry run: no changes made.\n");
+        if (args.json) {
+            process.stdout.write(JSON.stringify({
+                dryRun: true,
+                plan: plan.map((item) => ({
+                    action: item.action,
+                    path: normalizePath(path.relative(rootDir, item.path))
+                }))
+            }, null, 2) + "\n");
+        }
+        else if (!args.quiet) {
+            process.stdout.write("Dry run: no changes made.\n");
+        }
         return;
     }
     await confirmInit(args);
@@ -667,15 +676,28 @@ const initProject = async (args, rootDir, rulesetName) => {
         fs.mkdirSync(path.dirname(extraPath), { recursive: true });
         fs.writeFileSync(extraPath, LOCAL_RULES_TEMPLATE, "utf8");
     }
-    process.stdout.write(`Initialized ruleset:\n- ${normalizePath(path.relative(rootDir, rulesetPath))}\n`);
-    if (extraToWrite.length > 0) {
-        process.stdout.write(`Initialized local rules:\n${extraToWrite
-            .map((filePath) => `- ${normalizePath(path.relative(rootDir, filePath))}`)
-            .join("\n")}\n`);
-    }
+    let composedOutput;
     if (args.compose) {
-        const output = composeRuleset(rulesetPath, rootDir, { refresh: args.refresh ?? false });
-        process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+        composedOutput = composeRuleset(rulesetPath, rootDir, { refresh: args.refresh ?? false });
+    }
+    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] : [],
+            dryRun: false
+        }, null, 2) + "\n");
+    }
+    else if (!args.quiet) {
+        process.stdout.write(`Initialized ruleset:\n- ${normalizePath(path.relative(rootDir, rulesetPath))}\n`);
+        if (extraToWrite.length > 0) {
+            process.stdout.write(`Initialized local rules:\n${extraToWrite
+                .map((filePath) => `- ${normalizePath(path.relative(rootDir, filePath))}`)
+                .join("\n")}\n`);
+        }
+        if (composedOutput) {
+            process.stdout.write(`Composed AGENTS.md:\n- ${composedOutput}\n`);
+        }
     }
 };
 const getRulesetFiles = (rootDir, specificRuleset, rulesetName) => {
@@ -745,8 +767,13 @@ const main = async () => {
         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`);
+        const output = composeRuleset(rulesetPath, rootDir, { refresh: true, dryRun: args.dryRun });
+        if (args.json) {
+            process.stdout.write(JSON.stringify({ composed: [output], dryRun: !!args.dryRun }, null, 2) + "\n");
+        }
+        else if (!args.quiet) {
+            process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+        }
         return;
     }
     if (rulesetFiles.length === 0) {
@@ -755,8 +782,13 @@ const main = async () => {
     }
     const outputs = rulesetFiles
         .sort()
-        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh }));
-    process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
+        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh, dryRun: args.dryRun }));
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ composed: outputs, dryRun: !!args.dryRun }, null, 2) + "\n");
+    }
+    else if (!args.quiet) {
+        process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
+    }
 };
 const run = async () => {
     try {

package/package.json

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

package/tools/tool-rules.md

@@ -1,7 +1,11 @@
 # Tool Rules (compose-agentsmd)
 - Before starting any work, run `compose-agentsmd` from the project root.
+- `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`.
 - 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.
 - These tool rules live in tools/tool-rules.md in the compose-agentsmd repository; do not duplicate them in global rule modules.
 - When updating rules, include a colorized diff-style summary in the final response. Use `git diff --stat` first, then include the raw ANSI-colored output of `git diff --color=always` (no sanitizing or reformatting), and limit the output to the rule files that changed.
 - Also provide a short, copy-pasteable command the user can run to view the diff in the same format. Use absolute paths so it works regardless of the current working directory, and scope it to the changed rule files.

package/tools/usage.txt

@@ -1,9 +1,11 @@
-Usage: compose-agentsmd [edit-rules|apply-rules|init] [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--source <source>] [--domains <list>] [--extra <list>] [--output <file>] [--no-domains] [--no-extra] [--no-global] [--compose] [--dry-run] [--yes] [--force] [--refresh] [--clear-cache] [--version|-V] [--verbose|-v] [--help|-h]
+Usage: compose-agentsmd [edit-rules|apply-rules|init] [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--source <source>] [--domains <list>] [--extra <list>] [--output <file>] [--no-domains] [--no-extra] [--no-global] [--compose] [--dry-run] [--yes] [--force] [--refresh] [--clear-cache] [--version|-V] [--verbose|-v] [--quiet|-q] [--json] [--help|-h]
 
 Options:
   --help, -h           Show help and exit
   --version, -V        Show version and exit
   --verbose, -v        Show verbose diagnostics
+  --quiet, -q          Suppress non-error human-readable output (JSON output is not suppressed)
+  --json               Output machine-readable JSON (takes precedence over --quiet)
   --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)