@intellectronica/ruler 0.1.3 → 0.2.0

package/README.md

@@ -1,207 +1,396 @@
-> **Experimental Research Preview**
-> - Please test this version with caution in your own setup
-> - File issues at https://github.com/intellectronica/ruler/issues
+# Ruler: Centralise Your AI Coding Assistant Instructions
 
-# Ruler
+[![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)
 
-A CLI tool to manage custom rules and configs across different AI coding agents.
+- **GitHub**: [intellectronica/ruler](https://github.com/intellectronica/ruler)
+- **NPM**: [@intellectronica/ruler](https://www.npmjs.com/package/@intellectronica/ruler)
 
-## Features
+---
+
+> **Beta Research Preview**
+> - Please test this version carefully in your environment
+> - Report issues at https://github.com/intellectronica/ruler/issues
+
+## Why Ruler?
+
+Managing instructions across multiple AI coding tools becomes complex as your team grows. Different agents (GitHub Copilot, Claude, Cursor, Aider, etc.) require their own configuration files, leading to:
+
+- **Inconsistent guidance** across AI tools
+- **Duplicated effort** maintaining multiple config files  
+- **Context drift** as project requirements evolve
+- **Onboarding friction** for new AI tools
+
+Ruler solves this by providing a **single source of truth** for all your AI agent instructions, automatically distributing them to the right configuration files.
+
+## Core Features
+
+- **Centralised Rule Management**: Store all AI instructions in a dedicated `.ruler/` directory using Markdown files
+- **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
+- **`.gitignore` Automation**: Keeps generated agent config files out of version control automatically
+- **Simple CLI**: Easy-to-use commands for initialising and applying configurations
+
+## Supported AI Agents
+
+| Agent                  | File(s) Created/Updated                                    |
+| ---------------------- | ----------------------------------------------------------- |
+| GitHub Copilot         | `.github/copilot-instructions.md`                           |
+| Claude Code            | `CLAUDE.md`                                                 |
+| OpenAI Codex CLI       | `AGENTS.md`                                                 |
+| Cursor                 | `.cursor/rules/ruler_cursor_instructions.md`                |
+| Windsurf               | `.windsurf/rules/ruler_windsurf_instructions.md`            |
+| Cline                  | `.clinerules`                                               |
+| Aider                  | `ruler_aider_instructions.md` and `.aider.conf.yml`         |
 
-- Centralise AI agent instructions in a single `.ruler/` directory
-- Distribute rules to supported agents (GitHub Copilot, Claude Code, OpenAI Codex CLI, Cursor, Windsurf, Cline, Aider)
-- Extensible architecture: add new agent adapters easily
+## Getting Started
 
-## Installation
+### Prerequisites
 
-Install globally:
+Node.js 18.x or higher is required.
 
+### Installation
+
+**Global Installation (Recommended for CLI use):**
 ```bash
 npm install -g @intellectronica/ruler
 ```
 
-Or use npx:
-
+**Using `npx` (for one-off commands):**
 ```bash
 npx @intellectronica/ruler apply
 ```
 
-## Usage
+### Project Initialisation
 
-Create a `.ruler/` directory at your project root and add Markdown files defining your rules:
+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/
-├── coding_guidelines.md
-└── style_guide.md
+## Core Concepts
+
+### The `.ruler/` Directory
+
+This is your central hub for all AI agent instructions:
+
+- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` and alphabetically concatenated
+- **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
+
+### Best Practices for Rule Files
+
+**Granularity**: Break down complex instructions into focused `.md` files:
+- `coding_style.md`
+- `api_conventions.md`  
+- `project_architecture.md`
+- `security_guidelines.md`
+
+**Example rule file (`.ruler/python_guidelines.md`):**
+```markdown
+# Python Project Guidelines
+
+## General Style
+- Follow PEP 8 for all Python code
+- Use type hints for all function signatures and complex variables
+- Keep functions short and focused on a single task
+
+## Error Handling
+- Use specific exception types rather than generic `Exception`
+- Log errors effectively with context
+
+## Security
+- Always validate and sanitize user input
+- Be mindful of potential injection vulnerabilities
 ```
 
-Run the apply command:
+## Usage: The `apply` Command
 
+### Primary Command
 ```bash
-ruler apply [--project-root <path>] [--agents <agent1,agent2,...>] [--config <path>] [--gitignore] [--no-gitignore]
+ruler apply [options]
 ```
 
+### Options
 
-Run the init command to scaffold a basic `.ruler/` setup:
+| 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 |
+| `--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 |
+| `--verbose` / `-v` | Display detailed output during execution |
 
+### Common Examples
+
+**Apply rules to all configured agents:**
 ```bash
-ruler init [--project-root <path>]
+ruler apply
 ```
 
-Use `--agents` to specify a comma-separated list of agent names (case-insensitive substrings) to limit which agents the rules are applied to.
+**Apply rules only to GitHub Copilot and Claude:**
+```bash
+ruler apply --agents copilot,claude
+```
 
-The command will read all `.md` files under `.ruler/`, concatenate their contents, and generate/update configuration files for the following agents:
+**Use a specific configuration file:**
+```bash
+ruler apply --config ./team-configs/ruler.frontend.toml
+```
 
-| Agent                  | File(s) Created/Updated                                    |
-| ---------------------- | ----------------------------------------------------------- |
-| GitHub Copilot         | `.github/copilot-instructions.md`                           |
-| Claude Code            | `CLAUDE.md`                                                 |
-| OpenAI Codex CLI       | `AGENTS.md`                                                 |
-| Cursor                 | `.cursor/rules/ruler_cursor_instructions.md`                |
-| Windsurf               | `.windsurf/rules/ruler_windsurf_instructions.md`            |
-| Cline                  | `.clinerules`                                               |
-| Aider                  | `ruler_aider_instructions.md` <br>and updates `.aider.conf.yml` |
+**Apply rules with verbose output:**
+```bash
+ruler apply --verbose
+```
 
-## Configuration
+**Apply rules but skip MCP and .gitignore updates:**
+```bash
+ruler apply --no-mcp --no-gitignore
+```
 
-Ruler uses a TOML configuration file located at `.ruler/ruler.toml` by default. You can override its location with the `--config <path>` option in the `apply` command.
+## Configuration (`ruler.toml`) in Detail
 
-### Configuration structure
+### Location
+Defaults to `.ruler/ruler.toml` in the project root. Override with `--config` CLI option.
 
+### Complete Example
 ```toml
-# Run only these agents by default (omit to use all agents)
-# default_agents = ["GitHub Copilot", "Claude Code", "Aider"]
+# Default agents to run when --agents is not specified
+# Uses case-insensitive substring matching
+default_agents = ["copilot", "claude", "aider"]
 
-[agents.Copilot]
+# --- Global MCP Server Configuration ---
+[mcp]
+# Enable/disable MCP propagation globally (default: true)
+enabled = true
+# Global merge strategy: 'merge' or 'overwrite' (default: 'merge')
+merge_strategy = "merge"
+
+# --- Global .gitignore Configuration ---
+[gitignore]
+# Enable/disable automatic .gitignore updates (default: true)
+enabled = true
+
+# --- Agent-Specific Configurations ---
+[agents.copilot]
 enabled = true
 output_path = ".github/copilot-instructions.md"
 
-[agents.Claude]
+[agents.claude]
+enabled = true
+output_path = "CLAUDE.md"
+
+[agents.aider]
 enabled = true
-# output_path = "CLAUDE.md"
+output_path_instructions = "ruler_aider_instructions.md"
+output_path_config = ".aider.conf.yml"
 
-[agents.Aider]
+# Agent-specific MCP configuration
+[agents.cursor.mcp]
+enabled = true
+merge_strategy = "merge"
+
+# Disable specific agents
+[agents.windsurf]
 enabled = false
-# output_path_instructions = "ruler_aider_instructions.md"
-# output_path_config = ".aider.conf.yml"
 ```
 
-- `default_agents`: array of agent names (case-insensitive substrings) to run by default.
-- `[agents.<AgentName>]`: per-agent settings:
-  - `enabled` (boolean): enable or disable this agent.
-  - `output_path` (string): custom path for agents that produce a single file.
-  - `output_path_instructions`/`output_path_config`: custom paths for Aider's instruction and config files.
-
-### Precedence
+### Configuration Precedence
 
-1. CLI `--agents` option (substring filters)
-2. Config file `default_agents` and `[agents]` overrides
-3. Built-in defaults (all agents enabled, standard output paths)
+1. **CLI flags** (e.g., `--agents`, `--no-mcp`, `--mcp-overwrite`, `--no-gitignore`)
+2. **Settings in `ruler.toml`** (`default_agents`, specific agent settings, global sections)
+3. **Ruler's built-in defaults** (all agents enabled, standard output paths, MCP enabled with 'merge')
 
-## MCP servers
+## MCP (Model Context Protocol) Server Configuration
 
-Ruler can propagate a project-level `.ruler/mcp.json` file to native MCP configurations of supported agents, merging (or overwriting) each agent’s existing MCP server settings.
+MCP provides broader context to AI models through server configurations. Ruler can manage and distribute these settings across compatible agents.
 
 ### `.ruler/mcp.json`
-
-Place your MCP servers config in a file at `.ruler/mcp.json`:
-
+Define your project's MCP servers:
 ```json
 {
   "mcpServers": {
-    "example": {
-      "url": "https://mcp.example.com"
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    },
+    "git": {
+      "command": "npx", 
+      "args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
     }
   }
 }
 ```
 
-### CLI flags
+Ruler uses this file with the `merge` (default) or `overwrite` strategy, controlled by `ruler.toml` or CLI flags.
 
-| Flag              | Effect                                                       |
-|-------------------|--------------------------------------------------------------|
-| `--with-mcp`      | Enable writing MCP configs for all agents (default)          |
-| `--no-mcp`        | Disable writing MCP configs                                 |
-| `--mcp-overwrite` | Overwrite native MCP configs instead of merging              |
+## `.gitignore` Integration
 
-### Configuration (`ruler.toml`)
+Ruler automatically manages your `.gitignore` file to keep generated agent configuration files out of version control.
 
-Configure default behavior in your `ruler.toml`:
+### How it Works
+- Creates or updates `.gitignore` in your project root
+- Adds paths to a managed block marked with `# START Ruler Generated Files` and `# END Ruler Generated Files`
+- Preserves existing content outside this block
+- Sorts paths alphabetically and uses relative POSIX-style paths
 
-```toml
-[mcp]
-enabled = true
-merge_strategy = "merge"  # or "overwrite"
+### Example `.gitignore` Section
+```gitignore
+# Your existing rules
+node_modules/
+*.log
 
-[agents.Cursor.mcp]
-enabled = false
-merge_strategy = "overwrite"
+# START Ruler Generated Files
+.aider.conf.yml
+.clinerules
+.cursor/rules/ruler_cursor_instructions.md
+.github/copilot-instructions.md
+.windsurf/rules/ruler_windsurf_instructions.md
+AGENTS.md
+CLAUDE.md
+ruler_aider_instructions.md
+# END Ruler Generated Files
+
+dist/
 ```
 
-## .gitignore Integration
+### Control Options
+- **CLI flags**: `--gitignore` or `--no-gitignore`
+- **Configuration**: `[gitignore].enabled` in `ruler.toml`
+- **Default**: enabled
 
-Ruler automatically adds generated agent configuration files to your project's `.gitignore` file to prevent them from being committed to version control. This ensures that the AI agent configuration files remain local to each developer's environment.
+## Practical Usage Scenarios
 
-### Behavior
+### Scenario 1: Getting Started Quickly
+```bash
+# Initialize Ruler in your project
+cd your-project
+ruler init
 
-When `ruler apply` runs, it will:
-- Create or update a `.gitignore` file in your project root
-- Add all generated file paths to a managed block marked with `# START Ruler Generated Files` and `# END Ruler Generated Files`
-- Preserve any existing `.gitignore` content outside the managed block
-- Sort paths alphabetically within the Ruler block
-- Use relative POSIX-style paths (forward slashes)
+# Edit the generated files
+# - Add your coding guidelines to .ruler/instructions.md
+# - Customize .ruler/ruler.toml if needed
 
-### CLI flags
+# Apply rules to all AI agents
+ruler apply
+```
 
-| Flag              | Effect                                                       |
-|-------------------|--------------------------------------------------------------|
-| `--gitignore`     | Enable automatic .gitignore updates (default)               |
-| `--no-gitignore`  | Disable automatic .gitignore updates                        |
+### Scenario 2: Team Standardization
+1. Create `.ruler/coding_standards.md`, `.ruler/api_usage.md`
+2. Commit the `.ruler` directory to your repository
+3. Team members pull changes and run `ruler apply` to update their local AI agent configurations
 
-### Configuration (`ruler.toml`)
+### Scenario 3: 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`  
+3. Run `ruler apply` to help AI tools provide more relevant suggestions
 
-Configure the default behavior in your `ruler.toml`:
+### Integration with NPM Scripts
+```json
+{
+  "scripts": {
+    "ruler:apply": "ruler apply",
+    "dev": "npm run ruler:apply && your_dev_command",
+    "precommit": "npm run ruler:apply"
+  }
+}
+```
 
-```toml
-[gitignore]
-enabled = true  # or false to disable by default
+### Integration with GitHub Actions
+```yaml
+# .github/workflows/ruler-check.yml
+name: Check Ruler Configuration
+on:
+  pull_request:
+    paths: ['.ruler/**']
+
+jobs:
+  check-ruler:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+      
+      - name: Install Ruler
+        run: npm install -g @intellectronica/ruler
+      
+      - name: Apply Ruler configuration
+        run: ruler apply --no-gitignore
+      
+      - name: Check for uncommitted changes
+        run: |
+          if [[ -n $(git status --porcelain) ]]; then
+            echo "::error::Ruler configuration is out of sync!"
+            echo "Please run 'ruler apply' locally and commit the changes."
+            exit 1
+          fi
 ```
 
-### Precedence
+## Troubleshooting
 
-The configuration precedence for .gitignore updates is:
+### Common Issues
 
-1. CLI flags (`--gitignore` or `--no-gitignore`)
-2. Configuration file `[gitignore].enabled` setting
-3. Default behavior (enabled)
+**"Cannot find module" errors:**
+- Ensure Ruler is installed globally: `npm install -g @intellectronica/ruler`
+- Or use `npx @intellectronica/ruler`
 
-### Example
+**Permission denied errors:**
+- On Unix systems, you may need `sudo` for global installation
 
-After running `ruler apply`, your `.gitignore` might look like:
+**Agent files not updating:**
+- Check if the agent is enabled in `ruler.toml`
+- Verify agent isn't excluded by `--agents` flag
+- Use `--verbose` to see detailed execution logs
 
-```gitignore
-node_modules/
-*.log
+**Configuration validation errors:**
+- Ruler now validates `ruler.toml` format and will show specific error details
+- Check that all configuration values match the expected types and formats
 
-# START Ruler Generated Files
-.aider.conf.yml
-.clinerules
-.cursor/rules/ruler_cursor_instructions.md
-.github/copilot-instructions.md
-.windsurf/rules/ruler_windsurf_instructions.md
-AGENTS.md
-CLAUDE.md
-ruler_aider_instructions.md
-# END Ruler Generated Files
-
-dist/
+### Debug Mode
+Use `--verbose` flag to see detailed execution logs:
+```bash
+ruler apply --verbose
 ```
 
-## Development
+This shows:
+- Configuration loading details
+- Agent selection logic
+- File processing information
+- MCP configuration steps
+
+## FAQ
+
+**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".
 
-Clone the repository and install dependencies:
+**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.
 
+**Q: What happens to my existing agent configuration files?**
+A: Ruler creates backups with `.bak` extension before overwriting any existing files.
+
+**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.
+
+## Development
+
+### Setup
 ```bash
 git clone https://github.com/intellectronica/ruler.git
 cd ruler
@@ -209,28 +398,39 @@ npm install
 npm run build
 ```
 
-Run linting and formatting checks:
-
+### Testing
 ```bash
-npm run lint
-npm run format
-```
+# Run all tests
+npm test
 
-Run tests:
+# Run tests with coverage
+npm run test:coverage
 
-```bash
-npm test
+# Run tests in watch mode
+npm run test:watch
 ```
 
-End-to-end tests (run build before tests):
-
+### Code Quality
 ```bash
-npm run build && npm test
+# Run linting
+npm run lint
+
+# Run formatting
+npm run format
 ```
 
 ## Contributing
 
-Contributions are welcome! Please open issues or pull requests on GitHub.
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+For bugs and feature requests, please [open an issue](https://github.com/intellectronica/ruler/issues).
 
 ## License
 
@@ -238,6 +438,5 @@ MIT
 
 ---
 
-© Eleanor Berger
-
-[ai.intellectronica.net](https://ai.intellectronica.net/)
+© Eleanor Berger  
+[ai.intellectronica.net](https://ai.intellectronica.net/)

package/dist/agents/AiderAgent.js

@@ -42,6 +42,9 @@ const yaml = __importStar(require("js-yaml"));
  * Aider agent adapter (stub implementation).
  */
 class AiderAgent {
+    getIdentifier() {
+        return 'aider';
+    }
     getName() {
         return 'Aider';
     }

package/dist/agents/ClaudeAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * Claude Code agent adapter (stub implementation).
  */
 class ClaudeAgent {
+    getIdentifier() {
+        return 'claude';
+    }
     getName() {
         return 'Claude Code';
     }

package/dist/agents/ClineAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * Cline agent adapter (stub implementation).
  */
 class ClineAgent {
+    getIdentifier() {
+        return 'cline';
+    }
     getName() {
         return 'Cline';
     }

package/dist/agents/CodexCliAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * OpenAI Codex CLI agent adapter (stub implementation).
  */
 class CodexCliAgent {
+    getIdentifier() {
+        return 'codex';
+    }
     getName() {
         return 'OpenAI Codex CLI';
     }

package/dist/agents/CopilotAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * GitHub Copilot agent adapter (stub implementation).
  */
 class CopilotAgent {
+    getIdentifier() {
+        return 'copilot';
+    }
     getName() {
         return 'GitHub Copilot';
     }

package/dist/agents/CursorAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * Cursor agent adapter (stub implementation).
  */
 class CursorAgent {
+    getIdentifier() {
+        return 'cursor';
+    }
     getName() {
         return 'Cursor';
     }

package/dist/agents/WindsurfAgent.js

@@ -40,6 +40,9 @@ const FileSystemUtils_1 = require("../core/FileSystemUtils");
  * Windsurf agent adapter (stub implementation).
  */
 class WindsurfAgent {
+    getIdentifier() {
+        return 'windsurf';
+    }
     getName() {
         return 'Windsurf';
     }

package/dist/cli/commands.js

@@ -42,6 +42,7 @@ const helpers_1 = require("yargs/helpers");
 const lib_1 = require("../lib");
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
+const constants_1 = require("../constants");
 /**
  * Sets up and parses CLI commands.
  */
@@ -57,7 +58,7 @@ function run() {
         });
         y.option('agents', {
             type: 'string',
-            description: 'Comma-separated list of agent names to include (e.g. "copilot,claude")',
+            description: 'Comma-separated list of agent identifiers: copilot, claude, codex, cursor, windsurf, cline, aider',
         });
         y.option('config', {
             type: 'string',
@@ -78,6 +79,17 @@ function run() {
             type: 'boolean',
             description: 'Enable/disable automatic .gitignore updates (default: enabled)',
         });
+        y.option('verbose', {
+            type: 'boolean',
+            description: 'Enable verbose logging',
+            default: false,
+        });
+        y.alias('verbose', 'v');
+        y.option('dry-run', {
+            type: 'boolean',
+            description: 'Preview changes without writing files',
+            default: false,
+        });
     }, async (argv) => {
         const projectRoot = argv['project-root'];
         const agents = argv.agents
@@ -88,6 +100,8 @@ function run() {
         const mcpStrategy = argv['mcp-overwrite']
             ? 'overwrite'
             : undefined;
+        const verbose = argv.verbose;
+        const dryRun = argv['dry-run'];
         // Determine gitignore preference: CLI > TOML > Default (enabled)
         // yargs handles --no-gitignore by setting gitignore to false
         let gitignorePreference;
@@ -98,12 +112,12 @@ function run() {
             gitignorePreference = undefined; // Let TOML/default decide
         }
         try {
-            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference);
+            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun);
             console.log('Ruler apply completed successfully.');
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error('Error applying ruler configurations:', message);
+            console.error(`${constants_1.ERROR_PREFIX} ${message}`);
             process.exit(1);
         }
     })
@@ -141,36 +155,37 @@ and apply them to your configured AI coding agents.
 
 # To specify which agents are active by default when --agents is not used,
 # uncomment and populate the following line. If omitted, all agents are active.
-# default_agents = ["Copilot", "Claude"]
+# default_agents = ["copilot", "claude"]
 
 # --- Agent Specific Configurations ---
 # You can enable/disable agents and override their default output paths here.
+# Use lowercase agent identifiers: copilot, claude, codex, cursor, windsurf, cline, aider
 
-# [agents.GitHubCopilot]
+# [agents.copilot]
 # enabled = true
 # output_path = ".github/copilot-instructions.md"
 
-# [agents.ClaudeCode]
+# [agents.claude]
 # enabled = true
 # output_path = "CLAUDE.md"
 
-# [agents.OpenAICodexCLI]
+# [agents.codex]
 # enabled = true
 # output_path = "AGENTS.md"
 
-# [agents.Cursor]
+# [agents.cursor]
 # enabled = true
 # output_path = ".cursor/rules/ruler_cursor_instructions.md"
 
-# [agents.Windsurf]
+# [agents.windsurf]
 # enabled = true
 # output_path = ".windsurf/rules/ruler_windsurf_instructions.md"
 
-# [agents.Cline]
+# [agents.cline]
 # enabled = true
 # output_path = ".clinerules"
 
-# [agents.Aider]
+# [agents.aider]
 # enabled = true
 # output_path_instructions = "ruler_aider_instructions.md"
 # output_path_config = ".aider.conf.yml"

package/dist/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_PREFIX = void 0;
+exports.createRulerError = createRulerError;
+exports.logVerbose = logVerbose;
+exports.ERROR_PREFIX = '[RulerError]';
+function createRulerError(message, context) {
+    const fullMessage = context
+        ? `${exports.ERROR_PREFIX} ${message} (Context: ${context})`
+        : `${exports.ERROR_PREFIX} ${message}`;
+    return new Error(fullMessage);
+}
+function logVerbose(message, isVerbose) {
+    if (isVerbose) {
+        console.log(`[ruler:verbose] ${message}`);
+    }
+}

package/dist/core/ConfigLoader.js

@@ -40,6 +40,38 @@ exports.loadConfig = loadConfig;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const toml_1 = __importDefault(require("toml"));
+const zod_1 = require("zod");
+const constants_1 = require("../constants");
+const mcpConfigSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean().optional(),
+    merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
+})
+    .optional();
+const agentConfigSchema = zod_1.z
+    .object({
+    enabled: zod_1.z.boolean().optional(),
+    output_path: zod_1.z.string().optional(),
+    output_path_instructions: zod_1.z.string().optional(),
+    output_path_config: zod_1.z.string().optional(),
+    mcp: mcpConfigSchema,
+})
+    .optional();
+const rulerConfigSchema = zod_1.z.object({
+    default_agents: zod_1.z.array(zod_1.z.string()).optional(),
+    agents: zod_1.z.record(zod_1.z.string(), agentConfigSchema).optional(),
+    mcp: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+        merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
+    })
+        .optional(),
+    gitignore: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .optional(),
+});
 /**
  * Loads and parses the ruler TOML configuration file, applying defaults.
  * If the file is missing or invalid, returns empty/default config.
@@ -53,9 +85,17 @@ async function loadConfig(options) {
     try {
         const text = await fs_1.promises.readFile(configFile, 'utf8');
         raw = text.trim() ? toml_1.default.parse(text) : {};
+        // Validate the configuration with zod
+        const validationResult = rulerConfigSchema.safeParse(raw);
+        if (!validationResult.success) {
+            throw (0, constants_1.createRulerError)('Invalid configuration file format', `File: ${configFile}, Errors: ${validationResult.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`);
+        }
     }
     catch (err) {
         if (err instanceof Error && err.code !== 'ENOENT') {
+            if (err.message.includes('[RulerError]')) {
+                throw err; // Re-throw validation errors
+            }
             console.warn(`[ruler] Warning: could not read config file at ${configFile}: ${err.message}`);
         }
         raw = {};

package/dist/core/GitignoreUtils.js

@@ -59,7 +59,24 @@ async function updateGitignore(projectRoot, paths) {
     }
     // Convert paths to relative POSIX format
     const relativePaths = paths.map((p) => {
-        const relative = path.isAbsolute(p) ? path.relative(projectRoot, p) : p;
+        let relative;
+        if (path.isAbsolute(p)) {
+            relative = path.relative(projectRoot, p);
+        }
+        else {
+            // Handle relative paths that might include the project root prefix
+            const normalizedProjectRoot = path.normalize(projectRoot);
+            const normalizedPath = path.normalize(p);
+            // Get the basename of the project root to match against path prefixes
+            const projectBasename = path.basename(normalizedProjectRoot);
+            // If the path starts with the project basename, remove it
+            if (normalizedPath.startsWith(projectBasename + path.sep)) {
+                relative = normalizedPath.substring(projectBasename.length + 1);
+            }
+            else {
+                relative = normalizedPath;
+            }
+        }
         return relative.replace(/\\/g, '/'); // Convert to POSIX format
     });
     // Get all existing paths from .gitignore (excluding Ruler block)

package/dist/lib.js

@@ -50,6 +50,7 @@ const AiderAgent_1 = require("./agents/AiderAgent");
 const merge_1 = require("./mcp/merge");
 const validate_1 = require("./mcp/validate");
 const mcp_1 = require("./paths/mcp");
+const constants_1 = require("./constants");
 /**
  * Gets all output paths for an agent, taking into account any config overrides.
  */
@@ -102,74 +103,98 @@ const agents = [
  * @param projectRoot Root directory of the project
  * @param includedAgents Optional list of agent name filters (case-insensitive substrings)
  */
-async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false) {
     // Load configuration (default_agents, per-agent overrides, CLI filters)
+    (0, constants_1.logVerbose)(`Loading configuration from project root: ${projectRoot}`, verbose);
+    if (configPath) {
+        (0, constants_1.logVerbose)(`Using custom config path: ${configPath}`, verbose);
+    }
     const config = await (0, ConfigLoader_1.loadConfig)({
         projectRoot,
         cliAgents: includedAgents,
         configPath,
     });
-    // Normalize per-agent config keys to actual agent names (substring match)
+    (0, constants_1.logVerbose)(`Loaded configuration with ${Object.keys(config.agentConfigs).length} agent configs`, verbose);
+    // Normalize per-agent config keys to agent identifiers (exact match or substring match)
     const rawConfigs = config.agentConfigs;
     const mappedConfigs = {};
     for (const [key, cfg] of Object.entries(rawConfigs)) {
         const lowerKey = key.toLowerCase();
         for (const agent of agents) {
-            if (agent.getName().toLowerCase().includes(lowerKey)) {
-                mappedConfigs[agent.getName()] = cfg;
+            const identifier = agent.getIdentifier();
+            // Exact match with identifier or substring match with display name for backwards compatibility
+            if (identifier === lowerKey ||
+                agent.getName().toLowerCase().includes(lowerKey)) {
+                mappedConfigs[identifier] = cfg;
             }
         }
     }
     config.agentConfigs = mappedConfigs;
     const rulerDir = await FileSystemUtils.findRulerDir(projectRoot);
     if (!rulerDir) {
-        throw new Error(`.ruler directory not found from ${projectRoot}`);
+        throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
     }
-    await FileSystemUtils.ensureDirExists(path.join(rulerDir, 'generated'));
+    (0, constants_1.logVerbose)(`Found .ruler directory at: ${rulerDir}`, verbose);
     const files = await FileSystemUtils.readMarkdownFiles(rulerDir);
+    (0, constants_1.logVerbose)(`Found ${files.length} markdown files in .ruler directory`, verbose);
     const concatenated = (0, RuleProcessor_1.concatenateRules)(files);
+    (0, constants_1.logVerbose)(`Concatenated rules length: ${concatenated.length} characters`, verbose);
     const mcpFile = path.join(rulerDir, 'mcp.json');
     let rulerMcpJson = null;
     try {
         const raw = await fs_1.promises.readFile(mcpFile, 'utf8');
         rulerMcpJson = JSON.parse(raw);
         (0, validate_1.validateMcp)(rulerMcpJson);
+        (0, constants_1.logVerbose)(`Loaded MCP configuration from: ${mcpFile}`, verbose);
     }
     catch (err) {
         if (err.code !== 'ENOENT') {
-            throw err;
+            throw (0, constants_1.createRulerError)(`Failed to load MCP configuration`, `File: ${mcpFile}, Error: ${err.message}`);
         }
+        (0, constants_1.logVerbose)(`No MCP configuration found at: ${mcpFile}`, verbose);
     }
     // Determine which agents to run:
     // CLI --agents > config.default_agents > per-agent.enabled flags > default all
     let selected = agents;
     if (config.cliAgents && config.cliAgents.length > 0) {
         const filters = config.cliAgents.map((n) => n.toLowerCase());
-        selected = agents.filter((agent) => filters.some((f) => agent.getName().toLowerCase().includes(f)));
+        selected = agents.filter((agent) => filters.some((f) => agent.getIdentifier() === f ||
+            agent.getName().toLowerCase().includes(f)));
+        (0, constants_1.logVerbose)(`Selected agents via CLI filter: ${selected.map((a) => a.getName()).join(', ')}`, verbose);
     }
     else if (config.defaultAgents && config.defaultAgents.length > 0) {
         const defaults = config.defaultAgents.map((n) => n.toLowerCase());
         selected = agents.filter((agent) => {
-            const key = agent.getName();
-            const override = config.agentConfigs[key]?.enabled;
+            const identifier = agent.getIdentifier();
+            const override = config.agentConfigs[identifier]?.enabled;
             if (override !== undefined) {
                 return override;
             }
-            return defaults.includes(key.toLowerCase());
+            return defaults.some((d) => identifier === d || agent.getName().toLowerCase().includes(d));
         });
+        (0, constants_1.logVerbose)(`Selected agents via config default_agents: ${selected.map((a) => a.getName()).join(', ')}`, verbose);
     }
     else {
-        selected = agents.filter((agent) => config.agentConfigs[agent.getName()]?.enabled !== false);
+        selected = agents.filter((agent) => config.agentConfigs[agent.getIdentifier()]?.enabled !== false);
+        (0, constants_1.logVerbose)(`Selected all enabled agents: ${selected.map((a) => a.getName()).join(', ')}`, verbose);
     }
     // Collect all generated file paths for .gitignore
     const generatedPaths = [];
     for (const agent of selected) {
-        console.log(`[ruler] Applying rules for ${agent.getName()}...`);
-        const agentConfig = config.agentConfigs[agent.getName()];
-        await agent.applyRulerConfig(concatenated, projectRoot, agentConfig);
+        const actionPrefix = dryRun ? '[ruler:dry-run]' : '[ruler]';
+        console.log(`${actionPrefix} Applying rules for ${agent.getName()}...`);
+        (0, constants_1.logVerbose)(`Processing agent: ${agent.getName()}`, verbose);
+        const agentConfig = config.agentConfigs[agent.getIdentifier()];
         // Collect output paths for .gitignore
         const outputPaths = getAgentOutputPaths(agent, projectRoot, agentConfig);
+        (0, constants_1.logVerbose)(`Agent ${agent.getName()} output paths: ${outputPaths.join(', ')}`, verbose);
         generatedPaths.push(...outputPaths);
+        if (dryRun) {
+            (0, constants_1.logVerbose)(`DRY RUN: Would write rules to: ${outputPaths.join(', ')}`, true);
+        }
+        else {
+            await agent.applyRulerConfig(concatenated, projectRoot, agentConfig);
+        }
         const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
         const enabled = cliMcpEnabled &&
             (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
@@ -178,9 +203,15 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
                 agentConfig?.mcp?.strategy ??
                 config.mcp?.strategy ??
                 'merge';
-            const existing = await (0, mcp_1.readNativeMcp)(dest);
-            const merged = (0, merge_1.mergeMcp)(existing, rulerMcpJson, strategy);
-            await (0, mcp_1.writeNativeMcp)(dest, merged);
+            (0, constants_1.logVerbose)(`Applying MCP config for ${agent.getName()} with strategy: ${strategy}`, verbose);
+            if (dryRun) {
+                (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config to: ${dest}`, true);
+            }
+            else {
+                const existing = await (0, mcp_1.readNativeMcp)(dest);
+                const merged = (0, merge_1.mergeMcp)(existing, rulerMcpJson, strategy);
+                await (0, mcp_1.writeNativeMcp)(dest, merged);
+            }
         }
     }
     // Handle .gitignore updates
@@ -200,8 +231,14 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         const pathsToIgnore = generatedPaths.filter((p) => !p.endsWith('.bak'));
         const uniquePaths = [...new Set(pathsToIgnore)];
         if (uniquePaths.length > 0) {
-            await (0, GitignoreUtils_1.updateGitignore)(projectRoot, uniquePaths);
-            console.log(`[ruler] Updated .gitignore with ${uniquePaths.length} unique path(s) in the Ruler block.`);
+            const actionPrefix = dryRun ? '[ruler:dry-run]' : '[ruler]';
+            if (dryRun) {
+                console.log(`${actionPrefix} Would update .gitignore with ${uniquePaths.length} unique path(s): ${uniquePaths.join(', ')}`);
+            }
+            else {
+                await (0, GitignoreUtils_1.updateGitignore)(projectRoot, uniquePaths);
+                console.log(`${actionPrefix} Updated .gitignore with ${uniquePaths.length} unique path(s) in the Ruler block.`);
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
   "scripts": {
@@ -8,6 +8,7 @@
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
     "test": "jest",
     "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "build": "tsc",
     "prepare": "npm run build"
   },
@@ -58,6 +59,7 @@
   "dependencies": {
     "js-yaml": "^4.1.0",
     "toml": "^3.0.0",
-    "yargs": "^17.7.2"
+    "yargs": "^17.7.2",
+    "zod": "^3.25.28"
   }
 }