compose-agentsmd 3.0.0 → 3.2.0

package/README.md

@@ -34,6 +34,24 @@ 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.
 
+## 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
 
 For GitHub sources, the tool keeps two locations:
@@ -53,11 +71,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"
 }
 ```
@@ -85,8 +109,22 @@ Remote sources are cached under `~/.agentsmd/cache/<owner>/<repo>/<ref>/`. Use `
 - `--ruleset-name <name>`: override the ruleset filename (default: `agent-ruleset.json`)
 - `--refresh`: refresh cached remote rules
 - `--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,17 +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();
@@ -24,6 +29,14 @@ const parseArgs = (argv) => {
             args.help = true;
             continue;
         }
+        if (arg === "--version" || arg === "-V") {
+            args.version = true;
+            continue;
+        }
+        if (arg === "--verbose" || arg === "-v") {
+            args.verbose = true;
+            continue;
+        }
         if (arg === "--root") {
             const value = remaining[i + 1];
             if (!value) {
@@ -59,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;
@@ -66,7 +143,26 @@ 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";
 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 });
@@ -110,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);
@@ -379,6 +535,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);
@@ -398,8 +678,12 @@ 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`);
+        return;
+    }
     if (args.help) {
         process.stdout.write(`${usage}\n`);
         return;
@@ -413,6 +697,15 @@ const main = () => {
     const rulesetName = args.rulesetName || DEFAULT_RULESET_NAME;
     const rulesetFiles = getRulesetFiles(rootDir, args.ruleset, rulesetName);
     const command = args.command ?? "compose";
+    const logVerbose = (message) => {
+        if (args.verbose) {
+            process.stdout.write(`${message}\n`);
+        }
+    };
+    logVerbose("Verbose:");
+    logVerbose(`- Root: ${rootDir}`);
+    logVerbose(`- Ruleset name: ${rulesetName}`);
+    logVerbose(`- Ruleset files:\n${rulesetFiles.map((file) => `  - ${normalizePath(path.relative(rootDir, file))}`).join("\n")}`);
     if (command === "edit-rules") {
         const rulesetPath = ensureSingleRuleset(rulesetFiles, rootDir, rulesetName);
         const rulesetDir = path.dirname(rulesetPath);
@@ -424,6 +717,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);
@@ -442,12 +739,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.0.0",
+  "version": "3.2.0",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {

package/tools/tool-rules.md

@@ -1,4 +1,5 @@
 # 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.
+- 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.

package/tools/usage.txt

@@ -1,8 +1,22 @@
-Usage: compose-agentsmd [edit-rules|apply-rules] [--root <path>] [--ruleset <path>] [--ruleset-name <name>] [--refresh] [--clear-cache]
+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:
-  --root <path>         Project root directory (default: current working directory)
-  --ruleset <path>      Only compose a single ruleset file
+  --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
   --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