compose-agentsmd 3.1.0 → 3.2.1

package/README.md

@@ -33,6 +33,25 @@ compose-agentsmd
 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.
+Each composed rule section is also prefixed with the source file path that produced it.
+
+## Setup (init)
+
+For a project that does not have a ruleset yet, bootstrap one with `init`:
+
+```sh
+compose-agentsmd init --root path/to/project --yes
+```
+
+Defaults:
+
+- `source`: `github:owner/repo@latest`
+- `domains`: empty
+- `extra`: empty
+- `global`: omitted (defaults to `true`)
+- `output`: `AGENTS.md`
+
+Use `--dry-run` to preview actions, `--force` to overwrite existing files, and `--compose` to generate `AGENTS.md` immediately.
 
 ## Updating shared rules
 
@@ -53,11 +72,17 @@ compose-agentsmd apply-rules
 
 ## Project ruleset format
 
-```json
+Ruleset files accept JSON with `//` or `/* */` comments.
+
+```jsonc
 {
-  "source": "github:org/agent-rules@latest",
+  // Rules source. Use github:owner/repo@ref or a local path.
+  "source": "github:owner/repo@latest",
+  // Domain folders under rules/domains.
   "domains": ["node", "unreal"],
+  // Additional local rule files to append.
   "extra": ["agent-rules-local/custom.md"],
+  // Output file name.
   "output": "AGENTS.md"
 }
 ```
@@ -87,8 +112,20 @@ Remote sources are cached under `~/.agentsmd/cache/<owner>/<repo>/<ref>/`. Use `
 - `--clear-cache`: remove cached remote rules and exit
 - `--version` / `-V`: show version and exit
 - `--verbose` / `-v`: show verbose diagnostics
+- `--source <source>`: rules source for `init`
+- `--domains <list>`: comma-separated domains for `init`
+- `--extra <list>`: comma-separated extra rules for `init`
+- `--output <file>`: output filename for `init`
+- `--no-domains`: initialize with no domains
+- `--no-extra`: initialize without extra rule files
+- `--no-global`: initialize without global rules
+- `--compose`: compose `AGENTS.md` after `init`
+- `--dry-run`: show init plan without writing files
+- `--yes`: skip init confirmation prompt
+- `--force`: overwrite existing files during init
 - `edit-rules`: prepare or locate a writable rules workspace
 - `apply-rules`: push workspace changes (if GitHub source) and regenerate rules with refresh
+- `init`: generate a new ruleset and optional local rules file
 
 ## Development
 

package/dist/compose-agents.js

@@ -3,18 +3,22 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { execFileSync } from "node:child_process";
+import readline from "node:readline";
 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", "cache");
 const DEFAULT_WORKSPACE_ROOT = path.join(os.homedir(), ".agentsmd", "workspace");
+const DEFAULT_INIT_SOURCE = "github:owner/repo@latest";
+const DEFAULT_INIT_DOMAINS = [];
+const DEFAULT_INIT_EXTRA = [];
 const RULESET_SCHEMA_PATH = new URL("../agent-ruleset.schema.json", import.meta.url);
 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 parseArgs = (argv) => {
     const args = {};
-    const knownCommands = new Set(["edit-rules", "apply-rules"]);
+    const knownCommands = new Set(["edit-rules", "apply-rules", "init"]);
     const remaining = [...argv];
     if (remaining.length > 0 && knownCommands.has(remaining[0])) {
         args.command = remaining.shift();
@@ -68,6 +72,70 @@ const parseArgs = (argv) => {
             args.clearCache = true;
             continue;
         }
+        if (arg === "--source") {
+            const value = remaining[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --source");
+            }
+            args.source = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--domains") {
+            const value = remaining[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --domains");
+            }
+            args.domains = [...(args.domains ?? []), ...value.split(",").map((entry) => entry.trim())];
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-domains") {
+            args.domains = [];
+            continue;
+        }
+        if (arg === "--extra") {
+            const value = remaining[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --extra");
+            }
+            args.extra = [...(args.extra ?? []), ...value.split(",").map((entry) => entry.trim())];
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-extra") {
+            args.extra = [];
+            continue;
+        }
+        if (arg === "--output") {
+            const value = remaining[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --output");
+            }
+            args.output = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--no-global") {
+            args.global = false;
+            continue;
+        }
+        if (arg === "--compose") {
+            args.compose = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            args.dryRun = true;
+            continue;
+        }
+        if (arg === "--yes") {
+            args.yes = true;
+            continue;
+        }
+        if (arg === "--force") {
+            args.force = true;
+            continue;
+        }
         throw new Error(`Unknown argument: ${arg}`);
     }
     return args;
@@ -75,6 +143,23 @@ 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 normalizeListOption = (values, label) => {
+    if (!values) {
+        return undefined;
+    }
+    const trimmed = values.map((value) => value.trim());
+    if (trimmed.some((value) => value.length === 0)) {
+        throw new Error(`Invalid value for ${label}`);
+    }
+    return [...new Set(trimmed)];
+};
+const askQuestion = (prompt) => new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+        rl.close();
+        resolve(answer);
+    });
+});
 const usage = normalizeTrailingWhitespace(fs.readFileSync(USAGE_PATH, "utf8"));
 const packageJson = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));
 const getVersion = () => packageJson.version ?? "unknown";
@@ -121,9 +206,69 @@ const ensureDirectoryExists = (dirPath) => {
         throw new Error(`Not a directory: ${dirPath}`);
     }
 };
+const stripJsonComments = (input) => {
+    let output = "";
+    let inString = false;
+    let stringChar = "";
+    let escaping = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < input.length; i += 1) {
+        const char = input[i];
+        const next = input[i + 1];
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+                output += char;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (char === "*" && next === "/") {
+                inBlockComment = false;
+                i += 1;
+            }
+            continue;
+        }
+        if (inString) {
+            output += char;
+            if (escaping) {
+                escaping = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaping = true;
+                continue;
+            }
+            if (char === stringChar) {
+                inString = false;
+                stringChar = "";
+            }
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            inLineComment = true;
+            i += 1;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            inBlockComment = true;
+            i += 1;
+            continue;
+        }
+        if (char === "\"" || char === "'") {
+            inString = true;
+            stringChar = char;
+            output += char;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+};
 const readJsonFile = (filePath) => {
     const raw = fs.readFileSync(filePath, "utf8");
-    return JSON.parse(raw);
+    return JSON.parse(stripJsonComments(raw));
 };
 const readProjectRuleset = (rulesetPath) => {
     const parsed = readJsonFile(rulesetPath);
@@ -382,7 +527,10 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     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 parts = resolvedRules.map((rulePath) => {
+        const body = normalizeTrailingWhitespace(fs.readFileSync(rulePath, "utf8"));
+        return `Source: ${normalizePath(rulePath)}\n\n${body}`;
+    });
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
     const toolRules = normalizeTrailingWhitespace(TOOL_RULES);
     const output = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
@@ -390,6 +538,130 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     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";
+const buildInitRuleset = (args) => {
+    const domains = normalizeListOption(args.domains, "--domains");
+    const extra = normalizeListOption(args.extra, "--extra");
+    const ruleset = {
+        source: args.source ?? DEFAULT_INIT_SOURCE,
+        output: args.output ?? DEFAULT_OUTPUT
+    };
+    if (args.global === false) {
+        ruleset.global = false;
+    }
+    const resolvedDomains = domains ?? DEFAULT_INIT_DOMAINS;
+    if (resolvedDomains.length > 0) {
+        ruleset.domains = resolvedDomains;
+    }
+    const resolvedExtra = extra ?? DEFAULT_INIT_EXTRA;
+    if (resolvedExtra.length > 0) {
+        ruleset.extra = resolvedExtra;
+    }
+    return ruleset;
+};
+const formatInitRuleset = (ruleset) => {
+    const domainsValue = JSON.stringify(ruleset.domains ?? []);
+    const extraValue = JSON.stringify(ruleset.extra ?? []);
+    const lines = [
+        "{",
+        '  // Rules source. Use github:owner/repo@ref or a local path.',
+        `  "source": "${ruleset.source}",`,
+        '  // Domain folders under rules/domains.',
+        `  "domains": ${domainsValue},`,
+        '  // Additional local rule files to append.',
+        `  "extra": ${extraValue},`
+    ];
+    if (ruleset.global === false) {
+        lines.push('  // Include rules/global from the source.');
+        lines.push('  "global": false,');
+    }
+    lines.push('  // Output file name.');
+    lines.push(`  "output": "${ruleset.output ?? DEFAULT_OUTPUT}"`);
+    lines.push("}");
+    return `${lines.join("\n")}\n`;
+};
+const formatPlan = (items, rootDir) => {
+    const lines = items.map((item) => {
+        const verb = item.action === "overwrite" ? "Overwrite" : "Create";
+        const relative = normalizePath(path.relative(rootDir, item.path));
+        return `- ${verb}: ${relative}`;
+    });
+    return `Init plan:\n${lines.join("\n")}\n`;
+};
+const confirmInit = async (args) => {
+    if (args.dryRun || args.yes) {
+        return;
+    }
+    if (!process.stdin.isTTY) {
+        throw new Error("Confirmation required. Re-run with --yes to continue.");
+    }
+    const answer = await askQuestion("Proceed with init? [y/N] ");
+    if (!/^y(es)?$/iu.test(answer.trim())) {
+        throw new Error("Init aborted.");
+    }
+};
+const initProject = async (args, rootDir, rulesetName) => {
+    const rulesetPath = args.ruleset ? resolveFrom(rootDir, args.ruleset) : path.join(rootDir, rulesetName);
+    const rulesetDir = path.dirname(rulesetPath);
+    const ruleset = buildInitRuleset(args);
+    const outputPath = resolveFrom(rulesetDir, ruleset.output ?? DEFAULT_OUTPUT);
+    const plan = [];
+    if (fs.existsSync(rulesetPath)) {
+        if (!args.force) {
+            throw new Error(`Ruleset already exists: ${normalizePath(rulesetPath)}`);
+        }
+        plan.push({ action: "overwrite", path: rulesetPath });
+    }
+    else {
+        plan.push({ action: "create", path: rulesetPath });
+    }
+    const extraFiles = (ruleset.extra ?? []).map((rulePath) => resolveFrom(rulesetDir, rulePath));
+    const extraToWrite = [];
+    for (const extraPath of extraFiles) {
+        if (fs.existsSync(extraPath)) {
+            if (args.force) {
+                plan.push({ action: "overwrite", path: extraPath });
+                extraToWrite.push(extraPath);
+            }
+            continue;
+        }
+        plan.push({ action: "create", path: extraPath });
+        extraToWrite.push(extraPath);
+    }
+    if (args.compose) {
+        if (fs.existsSync(outputPath)) {
+            if (!args.force) {
+                throw new Error(`Output already exists: ${normalizePath(outputPath)} (use --force to overwrite)`);
+            }
+            plan.push({ action: "overwrite", path: outputPath });
+        }
+        else {
+            plan.push({ action: "create", path: outputPath });
+        }
+    }
+    process.stdout.write(formatPlan(plan, rootDir));
+    if (args.dryRun) {
+        process.stdout.write("Dry run: no changes made.\n");
+        return;
+    }
+    await confirmInit(args);
+    fs.mkdirSync(path.dirname(rulesetPath), { recursive: true });
+    fs.writeFileSync(`${rulesetPath}`, formatInitRuleset(ruleset), "utf8");
+    for (const extraPath of extraToWrite) {
+        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`);
+    }
+    if (args.compose) {
+        const output = composeRuleset(rulesetPath, rootDir, { refresh: args.refresh ?? false });
+        process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+    }
+};
 const getRulesetFiles = (rootDir, specificRuleset, rulesetName) => {
     if (specificRuleset) {
         const resolved = resolveFrom(rootDir, specificRuleset);
@@ -409,7 +681,7 @@ const ensureSingleRuleset = (rulesetFiles, rootDir, rulesetName) => {
     }
     return rulesetFiles[0];
 };
-const main = () => {
+const main = async () => {
     const args = parseArgs(process.argv.slice(2));
     if (args.version) {
         process.stdout.write(`${getVersion()}\n`);
@@ -448,6 +720,10 @@ const main = () => {
         process.stdout.write(`Rules workspace: ${workspaceRoot}\n`);
         return;
     }
+    if (command === "init") {
+        await initProject(args, rootDir, rulesetName);
+        return;
+    }
     if (command === "apply-rules") {
         const rulesetPath = ensureSingleRuleset(rulesetFiles, rootDir, rulesetName);
         const rulesetDir = path.dirname(rulesetPath);
@@ -466,12 +742,15 @@ const main = () => {
         .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh }));
     process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
 };
-try {
-    main();
-}
-catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`${message}\n`);
-    process.stderr.write(`${usage}\n`);
-    process.exit(1);
-}
+const run = async () => {
+    try {
+        await main();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.stderr.write(`${usage}\n`);
+        process.exit(1);
+    }
+};
+void run();

package/package.json

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

package/tools/tool-rules.md

@@ -2,4 +2,6 @@
 - 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.
-- When updating rules, include a detailed summary of what changed (added/removed/modified items) in the final response.
+- 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.
+- If a diff is provided, a separate detailed summary is not required. If a diff is not possible, include a detailed summary of what changed (added/removed/modified items).

package/tools/usage.txt

@@ -1,11 +1,22 @@
-Usage: compose-agentsmd [edit-rules|apply-rules] [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--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] [--help|-h]
 
 Options:
   --help, -h           Show help and exit
   --version, -V        Show version and exit
   --verbose, -v        Show verbose diagnostics
-  --root <path>         Project root directory (default: current working directory)
-  --ruleset <path>      Only compose a single ruleset file
+  --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
+  --source <source>    Rules source for init (default: github:owner/repo@latest)
+  --domains <list>     Comma-separated domains for init (default: none)
+  --extra <list>       Comma-separated extra rules for init
+  --output <file>      Output filename for init (default: AGENTS.md)
+  --no-domains         Initialize with no domains
+  --no-extra           Initialize without extra rule files
+  --no-global          Initialize without global rules
+  --compose            Compose AGENTS.md after init
+  --dry-run            Show init plan without writing files
+  --yes                Skip init confirmation prompt
+  --force              Overwrite existing files during init
+  --refresh            Refresh cached remote rules
+  --clear-cache        Remove cached remote rules and exit