@intellectronica/ruler 0.3.6 → 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/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/apply-engine.js

@@ -121,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
@@ -174,7 +174,7 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
 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);
@@ -211,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
@@ -309,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) {
@@ -380,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {