@intellectronica/ruler 0.2.19 → 0.3.1

package/README.md

@@ -1,11 +1,27 @@
 # Ruler: Centralise Your AI Coding Assistant Instructions
 
-[![CI](https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg)](https://github.com/intellectronica/ruler/actions/workflows/ci.yml)
-[![npm version](https://badge.fury.io/js/%40intellectronica%2Fruler.svg)](https://badge.fury.io/js/%40intellectronica%2Fruler)
-![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-
-- **GitHub**: [intellectronica/ruler](https://github.com/intellectronica/ruler)
-- **NPM**: [@intellectronica/ruler](https://www.npmjs.com/package/@intellectronica/ruler)
+<table style="width:100%">
+  <tr>
+    <td style="vertical-align: top;">
+      <p>
+        <a href="https://github.com/intellectronica/ruler/actions/workflows/ci.yml"><img src="https://github.com/intellectronica/ruler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+        <a href="https://www.npmjs.com/package/@intellectronica/ruler"><img src="https://badge.fury.io/js/%40intellectronica%2Fruler.svg" alt="npm version"></a>
+        <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+      </p>
+      <ul>
+        <li><strong>GitHub</strong>: <a href="https://github.com/intellectronica/ruler">intellectronica/ruler</a></li>
+        <li><strong>NPM</strong>: <a href="https://www.npmjs.com/package/@intellectronica/ruler">@intellectronica/ruler</a></li>
+      </ul>
+      <hr />
+      <p>
+        <em>Animation by <a href="https://isaacflath.com/">Isaac Flath</a> of <strong><a href="https://elite-ai-assisted-coding.dev/">Elite AI-Assisted Coding</a></strong></em> ➡︎
+      </p>
+    </td>
+    <td style="vertical-align: top; width:33%;">
+      <img src="img/ruler-short.gif" alt="Ruler demo" style="width:300px; height:auto; display:block;" />
+    </td>
+  </tr>
+</table>
 
 ---
 
@@ -22,12 +38,14 @@ Managing instructions across multiple AI coding tools becomes complex as your te
 - **Duplicated effort** maintaining multiple config files
 - **Context drift** as project requirements evolve
 - **Onboarding friction** for new AI tools
+- **Complex project structures** requiring context-specific instructions for different components
 
-Ruler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files.
+Ruler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files. With support for **nested rule loading**, Ruler can handle complex project structures with context-specific instructions for different components.
 
 ## Core Features
 
 - **Centralised Rule Management**: Store all AI instructions in a dedicated `.ruler/` directory using Markdown files
+- **Nested Rule Loading**: Support complex project structures with multiple `.ruler/` directories for context-specific instructions
 - **Automatic Distribution**: Ruler applies these rules to configuration files of supported AI agents
 - **Targeted Agent Configuration**: Fine-tune which agents are affected and their specific output paths via `ruler.toml`
 - **MCP Server Propagation**: Manage and distribute Model Context Protocol (MCP) server settings
@@ -36,25 +54,30 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 
 ## Supported AI Agents
 
-| Agent            | Rules File(s)                                    | MCP Configuration                                   |
-| ---------------- | ------------------------------------------------ | --------------------------------------------------- |
-| GitHub Copilot   | `.github/copilot-instructions.md`                | `.vscode/mcp.json`                                  |
-| Claude Code      | `CLAUDE.md`                                      | `.mcp.json`                                         |
-| OpenAI Codex CLI | `AGENTS.md`                                      | `.codex/config.toml`, `~/.codex/config.json`        |
-| Jules            | `AGENTS.md`                                      | -                                                   |
-| Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`    | `.cursor/mcp.json`, `~/.cursor/mcp.json`            |
-| Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md` | `~/.codeium/windsurf/mcp_config.json`               |
-| Cline            | `.clinerules`                                    | -                                                   |
-| Amp              | `AGENT.md`                                       | -                                                   |
-| Aider            | `ruler_aider_instructions.md`, `.aider.conf.yml` | `.mcp.json`                                         |
-| Firebase Studio  | `.idx/airules.md`                                | -                                                   |
-| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`                            |
-| Gemini CLI       | `GEMINI.md`                                      | `.gemini/settings.json`                             |
-| Junie            | `.junie/guidelines.md`                           | -                                                   |
-| AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                             |
-| Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                                |
-| OpenCode         | `AGENTS.md`                                      | `opencode.json`, `~/.config/opencode/opencode.json` |
-| Goose            | `.goosehints`                                    | -                                                   |
+| 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`                               |
+| 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`                                    | -                                                |
+| Amp              | `AGENTS.md`                                      | -                                                |
+| Aider            | `AGENTS.md`, `.aider.conf.yml`                   | `.mcp.json`                                      |
+| Firebase Studio  | `.idx/airules.md`                                | -                                                |
+| Open Hands       | `.openhands/microagents/repo.md`                 | `.openhands/config.toml`                         |
+| Gemini CLI       | `AGENTS.md`                                      | `.gemini/settings.json`                          |
+| Junie            | `.junie/guidelines.md`                           | -                                                |
+| AugmentCode      | `.augment/rules/ruler_augment_instructions.md`   | `.vscode/settings.json`                          |
+| Kilo Code        | `.kilocode/rules/ruler_kilocode_instructions.md` | `.kilocode/mcp.json`                             |
+| opencode         | `AGENTS.md`                                      | `opencode.json`                                  |
+| Goose            | `.goosehints`                                    | -                                                |
+| Qwen Code        | `AGENTS.md`                                      | `.qwen/settings.json`                            |
+| Zed              | `AGENTS.md`                                      | `.zed/settings.json` (project root, never $HOME) |
+| Warp             | `WARP.md`                                        | -                                                |
+| Kiro             | `.kiro/steering/ruler_kiro_instructions.md`      | -                                                |
 
 ## Getting Started
 
@@ -81,10 +104,10 @@ npx @intellectronica/ruler apply
 1. Navigate to your project's root directory
 2. Run `ruler init`
 3. This creates:
-   - `.ruler/` directory
-   - `.ruler/instructions.md`: A starter Markdown file for your rules
-   - `.ruler/ruler.toml`: The main configuration file for Ruler
-   - `.ruler/mcp.json`: An example MCP server configuration
+  - `.ruler/` directory
+  - `.ruler/AGENTS.md`: The primary starter Markdown file for your rules
+  - `.ruler/ruler.toml`: The main configuration file for Ruler (now contains sample MCP server sections; legacy `.ruler/mcp.json` no longer scaffolded)
+  - (Optional legacy fallback) If you previously used `.ruler/instructions.md`, it is still respected when `AGENTS.md` is absent. (The prior runtime warning was removed.)
 
 Additionally, you can create a global configuration to use when no local `.ruler/` directory is found:
 
@@ -100,11 +123,51 @@ The global configuration will be created to `$XDG_CONFIG_HOME/ruler` (default: `
 
 This is your central hub for all AI agent instructions:
 
-- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/ruler` and alphabetically concatenated
+- **Primary File Order & Precedence**:
+  1. A repository root `AGENTS.md` (outside `.ruler/`) if present (highest precedence, prepended)
+  2. `.ruler/AGENTS.md` (new default starter file)
+  3. Legacy `.ruler/instructions.md` (only if `.ruler/AGENTS.md` absent; no longer emits a deprecation warning)
+  4. Remaining discovered `.md` files under `.ruler/` (and subdirectories) in sorted order
+- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/ruler` and concatenated in the order above
 - **Concatenation Marker**: Each file's content is prepended with `--- Source: <relative_path_to_md_file> ---` for traceability
 - **`ruler.toml`**: Master configuration for Ruler's behavior, agent selection, and output paths
 - **`mcp.json`**: Shared MCP server settings
 
+This ordering lets you keep a short, high-impact root `AGENTS.md` (e.g. executive project summary) while housing detailed guidance inside `.ruler/`.
+
+### Nested Rule Loading
+
+Ruler now supports **nested rule loading** with the `--nested` flag, enabling context-specific instructions for different parts of your project:
+
+```
+project/
+├── .ruler/           # Global project rules
+│   ├── AGENTS.md
+│   └── coding_style.md
+├── src/
+│   └── .ruler/       # Component-specific rules
+│       └── api_guidelines.md
+├── tests/
+│   └── .ruler/       # Test-specific rules
+│       └── testing_conventions.md
+└── docs/
+    └── .ruler/       # Documentation rules
+        └── writing_style.md
+```
+
+**How it works:**
+
+- Discover all `.ruler/` directories in the project hierarchy
+- Load and concatenate rules from each directory in order
+- Enable with: `ruler apply --nested`
+
+**Perfect for:**
+
+- Monorepos with multiple services
+- Projects with distinct components (frontend/backend)
+- Teams needing different instructions for different areas
+- Complex codebases with varying standards
+
 ### Best Practices for Rule Files
 
 **Granularity**: Break down complex instructions into focused `.md` files:
@@ -148,18 +211,18 @@ The `apply` command looks for `.ruler/` in the current directory tree, reading t
 
 ### 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 target (amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, augmentcode, kilocode) |
-| `--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                                                                                                                       |
-| `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                        |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                   |
+| 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) |
+| `--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                                                                                                                                            |
+| `--local-only`                 | Do not look for configuration in `$XDG_CONFIG_HOME`                                                                                                                             |
+| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                        |
 
 ### Common Examples
 
@@ -181,6 +244,12 @@ ruler apply --agents copilot,claude
 ruler apply --agents firebase
 ```
 
+**Apply rules only to Warp:**
+
+```bash
+ruler apply --agents warp
+```
+
 **Use a specific configuration file:**
 
 ```bash
@@ -220,15 +289,15 @@ ruler revert [options]
 
 ### 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 (amp, copilot, claude, codex, cursor, windsurf, cline, aider, firebase, gemini-cli, junie, kilocode, opencode) |
-| `--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                                                                                                        |
-| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                |
-| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                          |
+| 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) |
+| `--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                                                                                                                             |
+| `--verbose` / `-v`             | Display detailed output during execution                                                                                                                                     |
+| `--local-only`                 | Only search for local .ruler directories, ignore global config                                                                                                               |
 
 ### Common Examples
 
@@ -282,6 +351,21 @@ enabled = true
 # Global merge strategy: 'merge' or 'overwrite' (default: 'merge')
 merge_strategy = "merge"
 
+# --- MCP Server Definitions ---
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+
+[mcp_servers.git]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
+
+[mcp_servers.remote_api]
+url = "https://api.example.com"
+
+[mcp_servers.remote_api.headers]
+Authorization = "Bearer your-token"
+
 # --- Global .gitignore Configuration ---
 [gitignore]
 # Enable/disable automatic .gitignore updates (default: true)
@@ -298,7 +382,7 @@ output_path = "CLAUDE.md"
 
 [agents.aider]
 enabled = true
-output_path_instructions = "ruler_aider_instructions.md"
+output_path_instructions = "AGENTS.md"
 output_path_config = ".aider.conf.yml"
 
 # OpenAI Codex CLI agent and MCP config
@@ -338,6 +422,10 @@ enabled = false
 [agents.kilocode]
 enabled = true
 output_path = ".kilocode/rules/ruler_kilocode_instructions.md"
+
+[agents.warp]
+enabled = true
+output_path = "WARP.md"
 ```
 
 ### Configuration Precedence
@@ -350,9 +438,36 @@ output_path = ".kilocode/rules/ruler_kilocode_instructions.md"
 
 MCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.
 
-### `.ruler/mcp.json`
+### TOML Configuration (Recommended)
 
-Define your project's MCP servers:
+You can now define MCP servers directly in `ruler.toml` using the `[mcp_servers.<name>]` syntax:
+
+```toml
+# Global MCP behavior
+[mcp]
+enabled = true
+merge_strategy = "merge"  # or "overwrite"
+
+# Local (stdio) server
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+
+[mcp_servers.filesystem.env]
+API_KEY = "your-api-key"
+
+# Remote server
+[mcp_servers.search]
+url = "https://mcp.example.com"
+
+[mcp_servers.search.headers]
+Authorization = "Bearer your-token"
+"X-API-Version" = "v1"
+```
+
+### Legacy `.ruler/mcp.json` (Deprecated)
+
+For backward compatibility, you can still use the JSON format; a warning is issued encouraging migration to TOML. The file is no longer created during `ruler init`.
 
 ```json
 {
@@ -373,10 +488,42 @@ Define your project's MCP servers:
 }
 ```
 
+### Configuration Precedence
+
+When both TOML and JSON configurations are present:
+
+1. **TOML servers take precedence** over JSON servers with the same name
+2. **Servers are merged** from both sources (unless using overwrite strategy)
+3. **Deprecation warning** is shown encouraging migration to TOML (warning shown once per run)
+
+### Server Types
 
-Ruler uses this file with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.
+**Local/stdio servers** require a `command` field:
+
+```toml
+[mcp_servers.local_server]
+command = "node"
+args = ["server.js"]
+
+[mcp_servers.local_server.env]
+DEBUG = "1"
+```
+
+**Remote servers** require a `url` field (headers optional; bearer Authorization token auto-extracted for OpenHands when possible):
+```toml
+[mcp_servers.remote_server]
+url = "https://api.example.com"
+
+[mcp_servers.remote_server.headers]
+Authorization = "Bearer token"
+```
+
+Ruler uses this configuration with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.
+
+**Home Directory Safety:** Ruler never writes MCP configuration files outside your project root. Any historical references to user home directories (e.g. `~/.codeium/windsurf/mcp_config.json` or `~/.zed/settings.json`) have been removed; only project-local paths are targeted.
 
 **Note for OpenAI Codex CLI:** To apply the local Codex CLI MCP configuration, set the `CODEX_HOME` environment variable to your project’s `.codex` directory:
+
 ```bash
 export CODEX_HOME="$(pwd)/.codex"
 ```
@@ -392,7 +539,7 @@ Ruler automatically manages your `.gitignore` file to keep generated agent confi
 - Preserves existing content outside this block
 - Sorts paths alphabetically and uses relative POSIX-style paths
 
-### Example `.gitignore` Section
+### Example `.gitignore` Section (sample - actual list depends on enabled agents)
 
 ```gitignore
 # Your existing rules
@@ -407,7 +554,7 @@ node_modules/
 .windsurf/rules/ruler_windsurf_instructions.md
 AGENTS.md
 CLAUDE.md
-ruler_aider_instructions.md
+AGENTS.md
 # END Ruler Generated Files
 
 dist/
@@ -429,14 +576,33 @@ cd your-project
 ruler init
 
 # Edit the generated files
-# - Add your coding guidelines to .ruler/instructions.md
+# - Add your coding guidelines to .ruler/AGENTS.md (or keep adding additional .md files)
 # - Customize .ruler/ruler.toml if needed
 
 # Apply rules to all AI agents
 ruler apply
 ```
 
-### Scenario 2: Team Standardization
+### Scenario 2: Complex Projects with Nested Rules
+
+For large projects with multiple components or services, use nested rule loading:
+
+```bash
+# Set up nested .ruler directories
+mkdir -p src/.ruler tests/.ruler docs/.ruler
+
+# Add component-specific instructions
+echo "# API Design Guidelines" > src/.ruler/api_rules.md
+echo "# Testing Best Practices" > tests/.ruler/test_rules.md
+echo "# Documentation Standards" > docs/.ruler/docs_rules.md
+
+# Apply with nested loading
+ruler apply --nested --verbose
+```
+
+This creates context-specific instructions for different parts of your project while maintaining global rules in the root `.ruler/` directory.
+
+### Scenario 3: Team Standardization
 
 1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`
 2. Commit the `.ruler` directory to your repository
@@ -538,6 +704,9 @@ This shows:
 **Q: Can I use different rules for different agents?**
 A: Currently, all agents receive the same concatenated rules. For agent-specific instructions, include sections in your rule files like "## GitHub Copilot Specific" or "## Aider Configuration".
 
+**Q: How do I set up different instructions for different parts of my project?**
+A: Use the `--nested` flag with `ruler apply --nested`. This enables Ruler to discover and load rules from multiple `.ruler/` directories throughout your project hierarchy. Place component-specific instructions in `src/.ruler/`, test-specific rules in `tests/.ruler/`, etc., while keeping global rules in the root `.ruler/` directory.
+
 **Q: How do I temporarily disable Ruler for an agent?**
 A: Set `enabled = false` in `ruler.toml` under `[agents.agentname]`, or use `--agents` flag to specify only the agents you want.
 
@@ -547,8 +716,20 @@ A: Ruler creates backups with `.bak` extension before overwriting any existing f
 **Q: Can I run Ruler in CI/CD pipelines?**
 A: Yes! Use `ruler apply --no-gitignore` in CI to avoid modifying `.gitignore`. See the GitHub Actions example above.
 
-**Q: How do I migrate from version 0.1.x to 0.2.0?**
-A: Version 0.2.0 is backward compatible. Your existing `.ruler/` directory and `ruler.toml` will continue to work. New features like verbose logging and improved error messages are opt-in.
+**Q: How do I migrate from older versions using `instructions.md`?**
+A: Simply rename `.ruler/instructions.md` to `.ruler/AGENTS.md` (recommended). If you keep the legacy file and omit `AGENTS.md`, Ruler will still use it (without emitting the old deprecation warning). Having both causes `AGENTS.md` to take precedence; the legacy file is still concatenated afterward.
+
+**Q: How does OpenHands MCP propagation classify servers?**
+A: Local stdio servers become `stdio_servers`. Remote URLs containing `/sse` are classified as `sse_servers`; others become `shttp_servers`. Bearer tokens in an `Authorization` header are extracted into `api_key` where possible.
+
+**Q: Where is Zed configuration written now?**
+A: Ruler writes a `settings.json` in the project root (not the user home dir) and transforms MCP server definitions to Zed's `context_servers` format including `source: "custom"`.
+
+**Q: What changed about MCP initialization?**
+A: `ruler init` now only adds example MCP server sections to `ruler.toml` instead of creating `.ruler/mcp.json`. The JSON file is still consumed if present, but TOML servers win on name conflicts.
+
+**Q: Is Kiro supported?**
+A: Yes. Kiro receives concatenated rules at `.kiro/steering/ruler_kiro_instructions.md`.
 
 ## Development
 
@@ -603,5 +784,43 @@ 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/AbstractAgent.js

@@ -0,0 +1,82 @@
+"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.AbstractAgent = void 0;
+const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+/**
+ * Abstract base class for agents that write to a single configuration file.
+ * Implements common logic for applying ruler configuration.
+ */
+class AbstractAgent {
+    /**
+     * Applies the concatenated ruler rules to the agent's configuration.
+     * This implementation handles the common pattern of:
+     * 1. Determining the output path
+     * 2. Ensuring the parent directory exists
+     * 3. Backing up the existing file
+     * 4. Writing the new content
+     */
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, // eslint-disable-line @typescript-eslint/no-unused-vars
+    agentConfig) {
+        const output = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, output);
+        await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(absolutePath));
+        await (0, FileSystemUtils_1.backupFile)(absolutePath);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+    }
+    /**
+     * Returns the specific key to be used for the server object in MCP JSON.
+     * Defaults to 'mcpServers' if not overridden.
+     */
+    getMcpServerKey() {
+        return 'mcpServers';
+    }
+    /**
+     * Returns whether this agent supports MCP STDIO servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpStdio() {
+        return false;
+    }
+    /**
+     * Returns whether this agent supports MCP remote servers.
+     * Defaults to false if not overridden.
+     */
+    supportsMcpRemote() {
+        return false;
+    }
+}
+exports.AbstractAgent = AbstractAgent;