@intellectronica/ruler 0.3.5 → 0.3.7

package/README.md

@@ -57,18 +57,19 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | Agent            | Rules File(s)                                    | MCP Configuration / Notes                        |
 | ---------------- | ------------------------------------------------ | ------------------------------------------------ |
 | AGENTS.md        | `AGENTS.md`                                      | (pseudo-agent ensuring root `AGENTS.md` exists)  |
-| GitHub Copilot   | `.github/copilot-instructions.md`                | `.vscode/mcp.json`                               |
+| GitHub Copilot   | `AGENTS.md`, `.github/copilot-instructions.md`   | `.vscode/mcp.json`                               |
 | Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                      |
 | OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`                             |
 | Jules            | `AGENTS.md`                                      | -                                                |
 | Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`                               |
 | Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | -                                                |
 | Cline            | `.clinerules`                                    | -                                                |
+| Crush            | `CRUSH.md`                                       | `.crush.json`                                    |
 | Amp              | `AGENTS.md`                                      | -                                                |
 | Amazon Q CLI     | `.amazonq/rules/ruler_q_rules.md`                | `.amazonq/mcp.json`                              |
 | Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                      |
 | Firebase Studio  | `.idx/airules.md`                                | -                                                |
-| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`                         |
+| Open Hands       | `.openhands/microagents/repo.md`                 | `config.toml`                                    |
 | Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                          |
 | Junie            | `.junie/guidelines.md`                           | -                                                |
 | AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                          |
@@ -78,15 +79,12 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                            |
 | RooCode          | `AGENTS.md`                                      | `.roo/mcp.json`                                  |
 | Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME) |
+| Trae AI          | `.trae/rules/project_rules.md`                   | -                                                |
 | Warp             | `WARP.md`                                        | -                                                |
 | Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | -                                                |
 
 ## Getting Started
 
-### Prerequisites
-
-Node.js 18.x or higher is required.
-
 ### Installation
 
 **Global Installation (Recommended for CLI use):**
@@ -216,13 +214,16 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 | Option                         | Description                                                                                                                                                                     |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                        |
-| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, augmentcode, kilocode, warp, roo) |
+| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to target (agentsmd, amazonqcli, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, openhands, gemini-cli, jules, junie, augmentcode, kilocode, opencode, goose, crush, zed, qwen, kiro, warp, roo, trae) |
 | `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                                |
 | `--mcp` / `--with-mcp`         | Enable applying MCP server configurations (default: true)                                                                                                                       |
 | `--no-mcp`                     | Disable applying MCP server configurations                                                                                                                                      |
 | `--mcp-overwrite`              | Overwrite native MCP config entirely instead of merging                                                                                                                         |
 | `--gitignore`                  | Enable automatic .gitignore updates (default: true)                                                                                                                             |
 | `--no-gitignore`               | Disable automatic .gitignore updates                                                                                                                                            |
+| `--nested`                     | Enable nested rule loading from nested .ruler directories (default: disabled)                                                                                                  |
+| `--backup`                     | Enable/disable creation of .bak backup files (default: enabled)                                                                                                                |
+| `--dry-run`                    | Preview changes without writing files                                                                                                                                           |
 | `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                                             |
 | `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                        |
 
@@ -252,6 +253,12 @@ ruler apply --agents firebase
 ruler apply --agents warp
 ```
 
+**Apply rules only to Trae AI:**
+
+```bash
+ruler apply --agents trae
+```
+
 **Apply rules only to RooCode:**
 
 ```bash
@@ -300,7 +307,7 @@ ruler revert [options]
 | Option                         | Description                                                                                                                                                                  |
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--project-root <path>`        | Path to your project's root (default: current directory)                                                                                                                     |
-| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, warp) |
+| `--agents <agent1,agent2,...>` | Comma-separated list of agent names to revert (agentsmd, amazonqcli, amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, openhands, gemini-cli, jules, junie, augmentcode, kilocode, opencode, goose, crush, zed, qwen, kiro, warp, roo, trae) |
 | `--config <path>`              | Path to a custom `ruler.toml` configuration file                                                                                                                             |
 | `--keep-backups`               | Keep backup files (.bak) after restoration (default: false)                                                                                                                  |
 | `--dry-run`                    | Preview changes without actually reverting files                                                                                                                             |
@@ -616,7 +623,7 @@ This creates context-specific instructions for different parts of your project w
 2. Commit the `.ruler` directory to your repository
 3. Team members pull changes and run `ruler apply` to update their local AI agent configurations
 
-### Scenario 3: Project-Specific Context for AI
+### Scenario 4: Project-Specific Context for AI
 
 1. Detail your project's architecture in `.ruler/project_overview.md`
 2. Describe primary data structures in `.ruler/data_models.md`
@@ -792,43 +799,5 @@ MIT
 
 ---
 
-## Development and Testing
-
-### Running Tests
-
-The project includes comprehensive test coverage with unit, integration, and end-to-end tests:
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Run integration tests specifically
-npm run test:integration
-
-# Run tests in watch mode
-npm run test:watch
-```
-
-### Integration Testing
-
-The project includes comprehensive integration tests that validate the complete CLI workflow:
-
-- **`npm run test:integration`**: Runs a full end-to-end integration test that:
-  1. Creates a temporary test directory
-  2. Runs `ruler init` to set up the initial structure
-  3. Creates custom `ruler.toml` with MCP servers (both stdio and remote)
-  4. Creates sample `AGENTS.md` and additional markdown files for concatenation
-  5. Runs `ruler apply` to generate all agent configuration files
-  6. Inspects and validates all generated files contain expected content
-  7. Outputs the content of all generated files for manual verification
-  8. Validates MCP server configurations were properly applied
-
-This integration test ensures the entire CLI workflow functions correctly and can be used for manual testing or CI validation.
-
----
-
 © Eleanor Berger  
 [ai.intellectronica.net](https://ai.intellectronica.net/)

package/dist/agents/CodexCliAgent.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodexCliAgent = void 0;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
-const toml = __importStar(require("toml"));
 const toml_1 = require("@iarna/toml");
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
 const FileSystemUtils_1 = require("../core/FileSystemUtils");
@@ -85,7 +84,7 @@ class CodexCliAgent {
             let existingConfig = {};
             try {
                 const existingContent = await fs_1.promises.readFile(configPath, 'utf8');
-                existingConfig = toml.parse(existingContent);
+                existingConfig = (0, toml_1.parse)(existingContent);
             }
             catch {
                 // File doesn't exist or can't be parsed, use empty config
@@ -121,59 +120,10 @@ class CodexCliAgent {
                     updatedConfig.mcp_servers[serverName] = mcpServer;
                 }
             }
-            // Convert to TOML with special handling for env to ensure it's an inline table
-            let tomlContent = '';
-            // Handle non-mcp_servers sections first
-            const configWithoutMcpServers = { ...updatedConfig };
-            delete configWithoutMcpServers.mcp_servers;
-            if (Object.keys(configWithoutMcpServers).length > 0) {
-                tomlContent += (0, toml_1.stringify)(configWithoutMcpServers);
-            }
-            // Now handle mcp_servers with special formatting for env
-            if (updatedConfig.mcp_servers &&
-                Object.keys(updatedConfig.mcp_servers).length > 0) {
-                for (const [serverName, serverConfig] of Object.entries(updatedConfig.mcp_servers)) {
-                    tomlContent += `\n[mcp_servers.${serverName}]\n`;
-                    // Add command
-                    if (serverConfig.command) {
-                        tomlContent += `command = "${serverConfig.command}"\n`;
-                    }
-                    // Add args if present
-                    if (serverConfig.args && Array.isArray(serverConfig.args)) {
-                        const argsStr = JSON.stringify(serverConfig.args)
-                            .replace(/"/g, '"')
-                            .replace(/,/g, ', ');
-                        tomlContent += `args = ${argsStr}\n`;
-                    }
-                    // Add env as inline table if present
-                    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
-                        tomlContent += `env = { `;
-                        const entries = Object.entries(serverConfig.env);
-                        for (let i = 0; i < entries.length; i++) {
-                            const [key, value] = entries[i];
-                            tomlContent += `${key} = "${value}"`;
-                            if (i < entries.length - 1) {
-                                tomlContent += ', ';
-                            }
-                        }
-                        tomlContent += ` }\n`;
-                    }
-                    // Add headers as inline table if present (from transformed remote servers)
-                    if (serverConfig.headers &&
-                        Object.keys(serverConfig.headers).length > 0) {
-                        tomlContent += `headers = { `;
-                        const entries = Object.entries(serverConfig.headers);
-                        for (let i = 0; i < entries.length; i++) {
-                            const [key, value] = entries[i];
-                            tomlContent += `${JSON.stringify(key)} = "${value}"`;
-                            if (i < entries.length - 1) {
-                                tomlContent += ', ';
-                            }
-                        }
-                        tomlContent += ` }\n`;
-                    }
-                }
-            }
+            // Convert to TOML using structured objects
+            const finalConfig = { ...updatedConfig };
+            // @iarna/toml should handle the formatting properly
+            const tomlContent = (0, toml_1.stringify)(finalConfig);
             await (0, FileSystemUtils_1.writeGeneratedFile)(configPath, tomlContent);
         }
     }

package/dist/agents/CopilotAgent.js

@@ -1,17 +1,95 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CopilotAgent = void 0;
+const path = __importStar(require("path"));
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+const fs_1 = require("fs");
 /**
  * GitHub Copilot agent adapter.
+ * Writes to both AGENTS.md (for web-based GitHub Copilot) and
+ * .github/copilot-instructions.md (for VS Code extension compatibility).
  */
-class CopilotAgent extends AgentsMdAgent_1.AgentsMdAgent {
+class CopilotAgent {
+    constructor() {
+        this.agentsMdAgent = new AgentsMdAgent_1.AgentsMdAgent();
+    }
     getIdentifier() {
         return 'copilot';
     }
     getName() {
         return 'GitHub Copilot';
     }
+    /**
+     * Returns multiple output paths to ensure both files are added to .gitignore.
+     */
+    getDefaultOutputPath(projectRoot) {
+        return {
+            instructions: path.join(projectRoot, 'AGENTS.md'),
+            legacy: path.join(projectRoot, '.github', 'copilot-instructions.md'),
+        };
+    }
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
+        // First, write to AGENTS.md using the existing AgentsMdAgent infrastructure
+        await this.agentsMdAgent.applyRulerConfig(concatenatedRules, projectRoot, null, // No MCP config needed for the instructions file
+        {
+            // Preserve explicit outputPath precedence semantics if provided
+            outputPath: agentConfig?.outputPath || agentConfig?.outputPathInstructions,
+        }, backup);
+        // Additionally write to .github/copilot-instructions.md for VS Code extension compatibility
+        const outputPaths = this.getDefaultOutputPath(projectRoot);
+        const legacyPath = path.resolve(projectRoot, outputPaths.legacy);
+        // Add marker comment to the content to identify it as generated
+        const contentWithMarker = `<!-- Generated by Ruler -->\n${concatenatedRules}`;
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(legacyPath));
+        // Check if content has changed (idempotency)
+        let existingLegacy = null;
+        try {
+            existingLegacy = await fs_1.promises.readFile(legacyPath, 'utf8');
+        }
+        catch {
+            existingLegacy = null;
+        }
+        if (existingLegacy === null || existingLegacy !== contentWithMarker) {
+            if (backup) {
+                await (0, FileSystemUtils_1.backupFile)(legacyPath);
+            }
+            await (0, FileSystemUtils_1.writeGeneratedFile)(legacyPath, contentWithMarker);
+        }
+    }
     getMcpServerKey() {
         return 'servers';
     }

package/dist/agents/GeminiCliAgent.js

@@ -44,13 +44,12 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getName() {
         return 'Gemini CLI';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
-    agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
         // First, perform idempotent write of AGENTS.md via base class
         await super.applyRulerConfig(concatenatedRules, projectRoot, null, {
             outputPath: agentConfig?.outputPath,
         });
-        // Ensure .gemini/settings.json has contextFileName set to AGENTS.md
+        // Prepare .gemini/settings.json with contextFileName and MCP configuration
         const settingsPath = path.join(projectRoot, '.gemini', 'settings.json');
         let existingSettings = {};
         try {
@@ -66,6 +65,23 @@ class GeminiCliAgent extends AgentsMdAgent_1.AgentsMdAgent {
             ...existingSettings,
             contextFileName: 'AGENTS.md',
         };
+        // Handle MCP server configuration if provided
+        const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
+        if (mcpEnabled && rulerMcpJson) {
+            const strategy = agentConfig?.mcp?.strategy ?? 'merge';
+            if (strategy === 'overwrite') {
+                // For overwrite, preserve existing settings except MCP servers
+                const incomingServers = rulerMcpJson.mcpServers || {};
+                updated[this.getMcpServerKey()] = incomingServers;
+            }
+            else {
+                // For merge strategy, merge with existing MCP servers
+                const baseServers = existingSettings[this.getMcpServerKey()] || {};
+                const incomingServers = rulerMcpJson.mcpServers || {};
+                const mergedServers = { ...baseServers, ...incomingServers };
+                updated[this.getMcpServerKey()] = mergedServers;
+            }
+        }
         await fs_1.promises.mkdir(path.dirname(settingsPath), { recursive: true });
         await fs_1.promises.writeFile(settingsPath, JSON.stringify(updated, null, 2));
     }

package/dist/agents/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allAgents = exports.AbstractAgent = void 0;
+exports.getAgentIdentifiersForCliHelp = getAgentIdentifiersForCliHelp;
 const AbstractAgent_1 = require("./AbstractAgent");
 Object.defineProperty(exports, "AbstractAgent", { enumerable: true, get: function () { return AbstractAgent_1.AbstractAgent; } });
 const CopilotAgent_1 = require("./CopilotAgent");
@@ -57,3 +58,18 @@ exports.allAgents = [
     new TraeAgent_1.TraeAgent(),
     new AmazonQCliAgent_1.AmazonQCliAgent(),
 ];
+/**
+ * Generates a comma-separated list of agent identifiers for CLI help text.
+ * Returns identifiers in alphabetical order, with 'agentsmd' always first.
+ */
+function getAgentIdentifiersForCliHelp() {
+    const identifiers = exports.allAgents.map((agent) => agent.getIdentifier());
+    const sorted = identifiers.sort();
+    // Ensure agentsmd is first (it should already be first alphabetically, but let's be explicit)
+    const agentsMdIndex = sorted.indexOf('agentsmd');
+    if (agentsMdIndex > 0) {
+        const agentsmd = sorted.splice(agentsMdIndex, 1)[0];
+        sorted.unshift(agentsmd);
+    }
+    return sorted.join(', ');
+}

package/dist/cli/commands.js

@@ -7,6 +7,7 @@ exports.run = run;
 const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
 const handlers_1 = require("./handlers");
+const index_1 = require("../agents/index");
 /**
  * Sets up and parses CLI commands.
  */
@@ -23,7 +24,7 @@ function run() {
         })
             .option('agents', {
             type: 'string',
-            description: 'Comma-separated list of agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush, zed, qwen',
+            description: `Comma-separated list of agent identifiers: ${(0, index_1.getAgentIdentifiersForCliHelp)()}`,
         })
             .option('config', {
             type: 'string',
@@ -93,7 +94,7 @@ function run() {
         })
             .option('agents', {
             type: 'string',
-            description: 'Comma-separated list of agent identifiers: amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode, crush, zed, qwen',
+            description: `Comma-separated list of agent identifiers: ${(0, index_1.getAgentIdentifiersForCliHelp)()}`,
         })
             .option('config', {
             type: 'string',

package/dist/constants.js

@@ -4,6 +4,10 @@ exports.DEFAULT_RULES_FILENAME = exports.ERROR_PREFIX = void 0;
 exports.actionPrefix = actionPrefix;
 exports.createRulerError = createRulerError;
 exports.logVerbose = logVerbose;
+exports.logInfo = logInfo;
+exports.logWarn = logWarn;
+exports.logError = logError;
+exports.logVerboseInfo = logVerboseInfo;
 exports.ERROR_PREFIX = '[ruler]';
 // Centralized default rules filename. Now points to 'AGENTS.md'.
 // Legacy '.ruler/instructions.md' is still supported as a fallback with a warning.
@@ -22,3 +26,26 @@ function logVerbose(message, isVerbose) {
         console.error(`[ruler:verbose] ${message}`);
     }
 }
+/**
+ * Centralized logging functions with consistent output streams and prefixing.
+ * - info/verbose go to stdout (user-visible progress)
+ * - warn/error go to stderr (problems)
+ */
+function logInfo(message, dryRun = false) {
+    const prefix = actionPrefix(dryRun);
+    console.log(`${prefix} ${message}`);
+}
+function logWarn(message, dryRun = false) {
+    const prefix = actionPrefix(dryRun);
+    console.warn(`${prefix} ${message}`);
+}
+function logError(message, dryRun = false) {
+    const prefix = actionPrefix(dryRun);
+    console.error(`${prefix} ${message}`);
+}
+function logVerboseInfo(message, isVerbose, dryRun = false) {
+    if (isVerbose) {
+        const prefix = actionPrefix(dryRun);
+        console.log(`${prefix} ${message}`);
+    }
+}

package/dist/core/ConfigLoader.js

@@ -37,7 +37,7 @@ exports.loadConfig = loadConfig;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
-const TOML = __importStar(require("toml"));
+const toml_1 = require("@iarna/toml");
 const zod_1 = require("zod");
 const constants_1 = require("../constants");
 const mcpConfigSchema = zod_1.z
@@ -97,7 +97,7 @@ async function loadConfig(options) {
     let raw = {};
     try {
         const text = await fs_1.promises.readFile(configFile, 'utf8');
-        raw = text.trim() ? TOML.parse(text) : {};
+        raw = text.trim() ? (0, toml_1.parse)(text) : {};
         // Validate the configuration with zod
         const validationResult = rulerConfigSchema.safeParse(raw);
         if (!validationResult.success) {

package/dist/core/UnifiedConfigLoader.js

@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadUnifiedConfig = loadUnifiedConfig;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
-const TOML = __importStar(require("toml"));
+const toml_1 = require("@iarna/toml");
 const hash_1 = require("./hash");
 const RuleProcessor_1 = require("./RuleProcessor");
 const FileSystemUtils = __importStar(require("./FileSystemUtils"));
@@ -58,7 +58,7 @@ async function loadUnifiedConfig(options) {
         : path.join(meta.rulerDir, 'ruler.toml');
     try {
         const text = await fs_1.promises.readFile(tomlFile, 'utf8');
-        tomlRaw = text.trim() ? TOML.parse(text) : {};
+        tomlRaw = text.trim() ? (0, toml_1.parse)(text) : {};
         meta.configFile = tomlFile;
     }
     catch (err) {
@@ -228,11 +228,21 @@ async function loadUnifiedConfig(options) {
     try {
         await fs_1.promises.access(mcpFile);
         mcpJsonExists = true;
-        console.warn('[ruler] Warning: Using legacy .ruler/mcp.json. Please migrate to ruler.toml. This fallback will be removed in a future release.');
+        // Warning is handled by apply-engine to avoid duplication
     }
     catch {
         // file not present
     }
+    // Add deprecation warning if mcp.json exists (regardless of validity)
+    if (mcpJsonExists) {
+        meta.mcpFile = mcpFile;
+        diagnostics.push({
+            severity: 'warning',
+            code: 'MCP_JSON_DEPRECATED',
+            message: 'mcp.json detected: please migrate MCP servers to ruler.toml [mcp_servers.*] sections',
+            file: mcpFile,
+        });
+    }
     try {
         if (mcpJsonExists) {
             const raw = await fs_1.promises.readFile(mcpFile, 'utf8');
@@ -256,14 +266,6 @@ async function loadUnifiedConfig(options) {
                     throw e; // rethrow original error for diagnostics
                 }
             }
-            meta.mcpFile = mcpFile;
-            // Add deprecation warning if mcp.json exists (structured diagnostic)
-            diagnostics.push({
-                severity: 'warning',
-                code: 'MCP_JSON_DEPRECATED',
-                message: 'mcp.json detected: please migrate MCP servers to ruler.toml [mcp_servers.*] sections',
-                file: mcpFile,
-            });
             const parsedObj = parsed;
             const serversRaw = parsedObj.mcpServers ||
                 parsedObj.servers ||

package/dist/core/apply-engine.js

@@ -35,7 +35,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadNestedConfigurations = loadNestedConfigurations;
 exports.loadSingleConfiguration = loadSingleConfiguration;
-exports.selectAgentsToRun = selectAgentsToRun;
 exports.processHierarchicalConfigurations = processHierarchicalConfigurations;
 exports.processSingleConfiguration = processSingleConfiguration;
 exports.applyConfigurationsToAgents = applyConfigurationsToAgents;
@@ -122,7 +121,7 @@ async function warnAboutLegacyMcpJson(rulerDir) {
     try {
         const legacyMcpPath = path.join(rulerDir, 'mcp.json');
         await (await Promise.resolve().then(() => __importStar(require('fs/promises')))).access(legacyMcpPath);
-        console.warn('[ruler] Warning: Using legacy .ruler/mcp.json. Please migrate to ruler.toml. This fallback will be removed in a future release.');
+        (0, constants_1.logWarn)('Warning: Using legacy .ruler/mcp.json. Please migrate to ruler.toml. This fallback will be removed in a future release.');
     }
     catch {
         // ignore
@@ -161,52 +160,6 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
         rulerMcpJson,
     };
 }
-/**
- * Selects the agents to process based on configuration.
- * @param allAgents Array of all available agents
- * @param config Loaded configuration
- * @returns Array of agents to be processed
- */
-function selectAgentsToRun(allAgents, config) {
-    // CLI --agents > config.default_agents > per-agent.enabled flags > default all
-    let selected = allAgents;
-    if (config.cliAgents && config.cliAgents.length > 0) {
-        const filters = config.cliAgents.map((n) => n.toLowerCase());
-        // Check if any of the specified agents don't exist
-        const validAgentIdentifiers = new Set(allAgents.map((agent) => agent.getIdentifier()));
-        const validAgentNames = new Set(allAgents.map((agent) => agent.getName().toLowerCase()));
-        const invalidAgents = filters.filter((filter) => !validAgentIdentifiers.has(filter) &&
-            ![...validAgentNames].some((name) => name.includes(filter)));
-        if (invalidAgents.length > 0) {
-            throw (0, constants_1.createRulerError)(`Invalid agent specified: ${invalidAgents.join(', ')}`, `Valid agents are: ${[...validAgentIdentifiers].join(', ')}`);
-        }
-        selected = allAgents.filter((agent) => filters.some((f) => agent.getIdentifier() === f ||
-            agent.getName().toLowerCase().includes(f)));
-    }
-    else if (config.defaultAgents && config.defaultAgents.length > 0) {
-        const defaults = config.defaultAgents.map((n) => n.toLowerCase());
-        // Check if any of the default agents don't exist
-        const validAgentIdentifiers = new Set(allAgents.map((agent) => agent.getIdentifier()));
-        const validAgentNames = new Set(allAgents.map((agent) => agent.getName().toLowerCase()));
-        const invalidAgents = defaults.filter((filter) => !validAgentIdentifiers.has(filter) &&
-            ![...validAgentNames].some((name) => name.includes(filter)));
-        if (invalidAgents.length > 0) {
-            throw (0, constants_1.createRulerError)(`Invalid agent specified in default_agents: ${invalidAgents.join(', ')}`, `Valid agents are: ${[...validAgentIdentifiers].join(', ')}`);
-        }
-        selected = allAgents.filter((agent) => {
-            const identifier = agent.getIdentifier();
-            const override = config.agentConfigs[identifier]?.enabled;
-            if (override !== undefined) {
-                return override;
-            }
-            return defaults.some((d) => identifier === d || agent.getName().toLowerCase().includes(d));
-        });
-    }
-    else {
-        selected = allAgents.filter((agent) => config.agentConfigs[agent.getIdentifier()]?.enabled !== false);
-    }
-    return selected;
-}
 /**
  * Processes hierarchical configurations by applying rules to each .ruler directory independently.
  * Each directory gets its own set of rules and generates its own agent files.
@@ -221,7 +174,7 @@ function selectAgentsToRun(allAgents, config) {
 async function processHierarchicalConfigurations(agents, configurations, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup = true) {
     const allGeneratedPaths = [];
     for (const config of configurations) {
-        console.log(`[ruler] Processing .ruler directory: ${config.rulerDir}`);
+        (0, constants_1.logVerboseInfo)(`Processing .ruler directory: ${config.rulerDir}`, verbose, dryRun);
         const rulerRoot = path.dirname(config.rulerDir);
         const paths = await applyConfigurationsToAgents(agents, config.concatenatedRules, config.rulerMcpJson, config.config, rulerRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
         allGeneratedPaths.push(...paths);
@@ -258,8 +211,7 @@ async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJs
     const generatedPaths = [];
     let agentsMdWritten = false;
     for (const agent of agents) {
-        const prefix = (0, constants_1.actionPrefix)(dryRun);
-        console.log(`${prefix} Applying rules for ${agent.getName()}...`);
+        (0, constants_1.logInfo)(`Applying rules for ${agent.getName()}...`, dryRun);
         (0, constants_1.logVerbose)(`Processing agent: ${agent.getName()}`, verbose);
         const agentConfig = config.agentConfigs[agent.getIdentifier()];
         // Collect output paths for .gitignore
@@ -356,6 +308,13 @@ async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig,
     if (agent.getIdentifier() === 'opencode') {
         return await applyOpenCodeMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup);
     }
+    // Agents that handle MCP configuration internally should not have external MCP handling
+    if (agent.getIdentifier() === 'zed' ||
+        agent.getIdentifier() === 'gemini-cli' ||
+        agent.getIdentifier() === 'amazon-q-cli') {
+        (0, constants_1.logVerbose)(`Skipping external MCP config for ${agent.getName()} - handled internally by agent`, verbose);
+        return;
+    }
     return await applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, cliMcpStrategy, dryRun, verbose, backup);
 }
 async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
@@ -385,13 +344,21 @@ async function applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agent
         (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config to: ${dest}`, verbose);
     }
     else {
-        if (backup) {
-            const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
-            await backupFile(dest);
-        }
         const existing = await (0, mcp_1.readNativeMcp)(dest);
         const merged = (0, merge_1.mergeMcp)(existing, filteredMcpJson, strategy, serverKey);
-        await (0, mcp_1.writeNativeMcp)(dest, merged);
+        // Only backup and write if content would actually change (idempotent)
+        const currentContent = JSON.stringify(existing, null, 2);
+        const newContent = JSON.stringify(merged, null, 2);
+        if (currentContent !== newContent) {
+            if (backup) {
+                const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
+                await backupFile(dest);
+            }
+            await (0, mcp_1.writeNativeMcp)(dest, merged);
+        }
+        else {
+            (0, constants_1.logVerbose)(`MCP config for ${agent.getName()} is already up to date - skipping backup and write`, verbose);
+        }
     }
 }
 /**
@@ -419,13 +386,12 @@ async function updateGitignore(projectRoot, generatedPaths, config, cliGitignore
         // Note: Individual backup patterns are added per-file in the collection phase
         // No need to add a broad *.bak pattern here
         if (uniquePaths.length > 0) {
-            const prefix = (0, constants_1.actionPrefix)(dryRun);
             if (dryRun) {
-                console.log(`${prefix} Would update .gitignore with ${uniquePaths.length} unique path(s): ${uniquePaths.join(', ')}`);
+                (0, constants_1.logInfo)(`Would update .gitignore with ${uniquePaths.length} unique path(s): ${uniquePaths.join(', ')}`, dryRun);
             }
             else {
                 await (0, GitignoreUtils_1.updateGitignore)(projectRoot, uniquePaths);
-                console.log(`${prefix} Updated .gitignore with ${uniquePaths.length} unique path(s) in the Ruler block.`);
+                (0, constants_1.logInfo)(`Updated .gitignore with ${uniquePaths.length} unique path(s) in the Ruler block.`, dryRun);
             }
         }
     }

package/dist/lib.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "allAgents", { enumerable: true, get: function ()
 const constants_1 = require("./constants");
 const apply_engine_1 = require("./core/apply-engine");
 const config_utils_1 = require("./core/config-utils");
+const agent_selection_1 = require("./core/agent-selection");
 const agents = agents_1.allAgents;
 /**
  * Applies ruler configurations for all supported AI agents.
@@ -38,7 +39,7 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         (0, constants_1.logVerbose)(`Loaded ${hierarchicalConfigs.length} .ruler directory configurations`, verbose);
         (0, constants_1.logVerbose)(`Root configuration has ${Object.keys(rootConfig.agentConfigs).length} agent configs`, verbose);
         normalizeAgentConfigs(rootConfig, agents);
-        selectedAgents = (0, apply_engine_1.selectAgentsToRun)(agents, rootConfig);
+        selectedAgents = (0, agent_selection_1.resolveSelectedAgents)(rootConfig, agents);
         (0, constants_1.logVerbose)(`Selected ${selectedAgents.length} agents: ${selectedAgents.map((a) => a.getName()).join(', ')}`, verbose);
         generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }
@@ -49,7 +50,7 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         (0, constants_1.logVerbose)(`Loaded configuration with ${Object.keys(singleConfig.config.agentConfigs).length} agent configs`, verbose);
         (0, constants_1.logVerbose)(`Found .ruler directory with ${singleConfig.concatenatedRules.length} characters of rules`, verbose);
         normalizeAgentConfigs(singleConfig.config, agents);
-        selectedAgents = (0, apply_engine_1.selectAgentsToRun)(agents, singleConfig.config);
+        selectedAgents = (0, agent_selection_1.resolveSelectedAgents)(singleConfig.config, agents);
         (0, constants_1.logVerbose)(`Selected ${selectedAgents.length} agents: ${selectedAgents.map((a) => a.getName()).join(', ')}`, verbose);
         generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
     }

package/dist/mcp/propagateOpenHandsMcp.js

@@ -35,7 +35,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.propagateMcpToOpenHands = propagateMcpToOpenHands;
 const fs = __importStar(require("fs/promises"));
-const TOML = __importStar(require("toml"));
 const toml_1 = require("@iarna/toml");
 const FileSystemUtils_1 = require("../core/FileSystemUtils");
 const path = __importStar(require("path"));
@@ -103,7 +102,7 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup
     let config = {};
     try {
         const tomlContent = await fs.readFile(openHandsConfigPath, 'utf8');
-        config = TOML.parse(tomlContent);
+        config = (0, toml_1.parse)(tomlContent);
     }
     catch {
         // File doesn't exist, we'll create it.

package/dist/paths/mcp.js

@@ -36,12 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNativeMcpPath = getNativeMcpPath;
 exports.readNativeMcp = readNativeMcp;
 exports.writeNativeMcp = writeNativeMcp;
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 /** Determine the native MCP config path for a given agent. */
 async function getNativeMcpPath(adapterName, projectRoot) {
-    const home = os.homedir();
     const candidates = [];
     switch (adapterName) {
         case 'GitHub Copilot':
@@ -53,16 +51,15 @@ async function getNativeMcpPath(adapterName, projectRoot) {
             break;
         case 'Cursor':
             candidates.push(path.join(projectRoot, '.cursor', 'mcp.json'));
-            candidates.push(path.join(home, '.cursor', 'mcp.json'));
             break;
         case 'Windsurf':
-            candidates.push(path.join(home, '.codeium', 'windsurf', 'mcp_config.json'));
+            candidates.push(path.join(projectRoot, '.windsurf', 'mcp_config.json'));
             break;
         case 'Claude Code':
             candidates.push(path.join(projectRoot, '.mcp.json'));
             break;
         case 'OpenAI Codex CLI':
-            candidates.push(path.join(home, '.codex', 'config.json'));
+            candidates.push(path.join(projectRoot, '.codex', 'config.json'));
             break;
         case 'Aider':
             candidates.push(path.join(projectRoot, '.mcp.json'));
@@ -82,7 +79,6 @@ async function getNativeMcpPath(adapterName, projectRoot) {
             break;
         case 'OpenCode':
             candidates.push(path.join(projectRoot, 'opencode.json'));
-            candidates.push(path.join(home, '.config', 'opencode', 'opencode.json'));
             break;
         case 'Zed':
             // Only consider project-local Zed settings (avoid writing to user home directory)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {
@@ -62,7 +62,6 @@
   "dependencies": {
     "@iarna/toml": "^2.2.5",
     "js-yaml": "^4.1.0",
-    "toml": "^3.0.0",
     "yargs": "^17.7.2",
     "zod": "^3.25.28"
   }