@intellectronica/ruler 0.1.2 → 0.1.4

package/README.md

@@ -1,3 +1,7 @@
+> **Experimental Research Preview**
+> - Please test this version with caution in your own setup
+> - File issues at https://github.com/intellectronica/ruler/issues
+
 # Ruler
 
 A CLI tool to manage custom rules and configs across different AI coding agents.
@@ -35,7 +39,7 @@ Create a `.ruler/` directory at your project root and add Markdown files definin
 Run the apply command:
 
 ```bash
-ruler apply [--project-root <path>] [--agents <agent1,agent2,...>] [--config <path>]
+ruler apply [--project-root <path>] [--agents <agent1,agent2,...>] [--config <path>] [--gitignore] [--no-gitignore]
 ```
 
 
@@ -135,6 +139,65 @@ enabled = false
 merge_strategy = "overwrite"
 ```
 
+## .gitignore Integration
+
+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.
+
+### Behavior
+
+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)
+
+### CLI flags
+
+| Flag              | Effect                                                       |
+|-------------------|--------------------------------------------------------------|
+| `--gitignore`     | Enable automatic .gitignore updates (default)               |
+| `--no-gitignore`  | Disable automatic .gitignore updates                        |
+
+### Configuration (`ruler.toml`)
+
+Configure the default behavior in your `ruler.toml`:
+
+```toml
+[gitignore]
+enabled = true  # or false to disable by default
+```
+
+### Precedence
+
+The configuration precedence for .gitignore updates is:
+
+1. CLI flags (`--gitignore` or `--no-gitignore`)
+2. Configuration file `[gitignore].enabled` setting
+3. Default behavior (enabled)
+
+### Example
+
+After running `ruler apply`, your `.gitignore` might look like:
+
+```gitignore
+node_modules/
+*.log
+
+# 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/
+```
+
 ## Development
 
 Clone the repository and install dependencies:
@@ -165,13 +228,6 @@ End-to-end tests (run build before tests):
 npm run build && npm test
 ```
 
-### Roadmap
-- [ ] Support for MCP servers config
-- [ ] Support for transforming and rewriting the rules using AI
-- [ ] Support "harmonisation" (reading existing rules of specific agents and combining them with the master config)
-- [ ] Support for additional agents
-- [ ] Support for agent-specific features (for example: apply rules in copilot)
-
 ## Contributing
 
 Contributions are welcome! Please open issues or pull requests on GitHub.

package/dist/cli/commands.js

@@ -74,6 +74,10 @@ function run() {
             description: 'Replace (not merge) the native MCP config(s)',
             default: false,
         });
+        y.option('gitignore', {
+            type: 'boolean',
+            description: 'Enable/disable automatic .gitignore updates (default: enabled)',
+        });
     }, async (argv) => {
         const projectRoot = argv['project-root'];
         const agents = argv.agents
@@ -84,8 +88,17 @@ function run() {
         const mcpStrategy = argv['mcp-overwrite']
             ? 'overwrite'
             : undefined;
+        // Determine gitignore preference: CLI > TOML > Default (enabled)
+        // yargs handles --no-gitignore by setting gitignore to false
+        let gitignorePreference;
+        if (argv.gitignore !== undefined) {
+            gitignorePreference = argv.gitignore;
+        }
+        else {
+            gitignorePreference = undefined; // Let TOML/default decide
+        }
         try {
-            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy);
+            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference);
             console.log('Ruler apply completed successfully.');
         }
         catch (err) {

package/dist/core/ConfigLoader.js

@@ -113,5 +113,20 @@ async function loadConfig(options) {
             globalMcpConfig.strategy = strat;
         }
     }
-    return { defaultAgents, agentConfigs, cliAgents, mcp: globalMcpConfig };
+    const rawGitignoreSection = raw.gitignore &&
+        typeof raw.gitignore === 'object' &&
+        !Array.isArray(raw.gitignore)
+        ? raw.gitignore
+        : {};
+    const gitignoreConfig = {};
+    if (typeof rawGitignoreSection.enabled === 'boolean') {
+        gitignoreConfig.enabled = rawGitignoreSection.enabled;
+    }
+    return {
+        defaultAgents,
+        agentConfigs,
+        cliAgents,
+        mcp: globalMcpConfig,
+        gitignore: gitignoreConfig,
+    };
 }

package/dist/core/GitignoreUtils.js

@@ -0,0 +1,162 @@
+"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.updateGitignore = updateGitignore;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const RULER_START_MARKER = '# START Ruler Generated Files';
+const RULER_END_MARKER = '# END Ruler Generated Files';
+/**
+ * Updates the .gitignore file in the project root with paths in a managed Ruler block.
+ * Creates the file if it doesn't exist, and creates or updates the Ruler-managed block.
+ *
+ * @param projectRoot The project root directory (where .gitignore should be located)
+ * @param paths Array of file paths to add to .gitignore (can be absolute or relative)
+ */
+async function updateGitignore(projectRoot, paths) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    // Read existing .gitignore or start with empty content
+    let existingContent = '';
+    try {
+        existingContent = await fs_1.promises.readFile(gitignorePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    // Convert paths to relative POSIX format
+    const relativePaths = paths.map((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)
+    const existingPaths = getExistingPathsExcludingRulerBlock(existingContent);
+    // Filter out paths that already exist outside the Ruler block
+    const newPaths = relativePaths.filter((p) => !existingPaths.includes(p));
+    // The Ruler block should contain only the new paths (replacement behavior)
+    const allRulerPaths = [...new Set(newPaths)].sort();
+    // Create new content
+    const newContent = updateGitignoreContent(existingContent, allRulerPaths);
+    // Write the updated content
+    await fs_1.promises.writeFile(gitignorePath, newContent);
+}
+/**
+ * Gets all paths from .gitignore content excluding those in the Ruler block.
+ */
+function getExistingPathsExcludingRulerBlock(content) {
+    const lines = content.split('\n');
+    const paths = [];
+    let inRulerBlock = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === RULER_START_MARKER) {
+            inRulerBlock = true;
+            continue;
+        }
+        if (trimmed === RULER_END_MARKER) {
+            inRulerBlock = false;
+            continue;
+        }
+        if (!inRulerBlock && trimmed && !trimmed.startsWith('#')) {
+            paths.push(trimmed);
+        }
+    }
+    return paths;
+}
+/**
+ * Updates the .gitignore content by replacing or adding the Ruler block.
+ */
+function updateGitignoreContent(existingContent, rulerPaths) {
+    const lines = existingContent.split('\n');
+    const newLines = [];
+    let inFirstRulerBlock = false;
+    let hasRulerBlock = false;
+    let processedFirstBlock = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === RULER_START_MARKER && !processedFirstBlock) {
+            inFirstRulerBlock = true;
+            hasRulerBlock = true;
+            newLines.push(line);
+            // Add the new Ruler paths
+            rulerPaths.forEach((p) => newLines.push(p));
+            continue;
+        }
+        if (trimmed === RULER_END_MARKER && inFirstRulerBlock) {
+            inFirstRulerBlock = false;
+            processedFirstBlock = true;
+            newLines.push(line);
+            continue;
+        }
+        if (!inFirstRulerBlock) {
+            newLines.push(line);
+        }
+        // Skip lines that are in the first Ruler block (they get replaced)
+    }
+    // If no Ruler block exists, add one at the end
+    if (!hasRulerBlock) {
+        // Add blank line if content exists and doesn't end with blank line
+        if (existingContent.trim() && !existingContent.endsWith('\n\n')) {
+            newLines.push('');
+        }
+        newLines.push(RULER_START_MARKER);
+        rulerPaths.forEach((p) => newLines.push(p));
+        newLines.push(RULER_END_MARKER);
+    }
+    // Ensure file ends with a newline
+    let result = newLines.join('\n');
+    if (!result.endsWith('\n')) {
+        result += '\n';
+    }
+    return result;
+}

package/dist/lib.js

@@ -39,6 +39,7 @@ const fs_1 = require("fs");
 const FileSystemUtils = __importStar(require("./core/FileSystemUtils"));
 const RuleProcessor_1 = require("./core/RuleProcessor");
 const ConfigLoader_1 = require("./core/ConfigLoader");
+const GitignoreUtils_1 = require("./core/GitignoreUtils");
 const CopilotAgent_1 = require("./agents/CopilotAgent");
 const ClaudeAgent_1 = require("./agents/ClaudeAgent");
 const CodexCliAgent_1 = require("./agents/CodexCliAgent");
@@ -49,6 +50,40 @@ const AiderAgent_1 = require("./agents/AiderAgent");
 const merge_1 = require("./mcp/merge");
 const validate_1 = require("./mcp/validate");
 const mcp_1 = require("./paths/mcp");
+/**
+ * Gets all output paths for an agent, taking into account any config overrides.
+ */
+function getAgentOutputPaths(agent, projectRoot, agentConfig) {
+    const paths = [];
+    const defaults = agent.getDefaultOutputPath(projectRoot);
+    if (typeof defaults === 'string') {
+        // Single output path (most agents)
+        const actualPath = agentConfig?.outputPath ?? defaults;
+        paths.push(actualPath);
+    }
+    else {
+        // Multiple output paths (e.g., AiderAgent)
+        const defaultPaths = defaults;
+        // Handle instructions path
+        if ('instructions' in defaultPaths) {
+            const instructionsPath = agentConfig?.outputPathInstructions ?? defaultPaths.instructions;
+            paths.push(instructionsPath);
+        }
+        // Handle config path
+        if ('config' in defaultPaths) {
+            const configPath = agentConfig?.outputPathConfig ?? defaultPaths.config;
+            paths.push(configPath);
+        }
+        // Handle any other paths in the default paths record
+        for (const [key, defaultPath] of Object.entries(defaultPaths)) {
+            if (key !== 'instructions' && key !== 'config') {
+                // For unknown path types, use the default since we don't have specific config overrides
+                paths.push(defaultPath);
+            }
+        }
+    }
+    return paths;
+}
 const agents = [
     new CopilotAgent_1.CopilotAgent(),
     new ClaudeAgent_1.ClaudeAgent(),
@@ -67,7 +102,7 @@ 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) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled) {
     // Load configuration (default_agents, per-agent overrides, CLI filters)
     const config = await (0, ConfigLoader_1.loadConfig)({
         projectRoot,
@@ -126,10 +161,15 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
     else {
         selected = agents.filter((agent) => config.agentConfigs[agent.getName()]?.enabled !== false);
     }
+    // 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);
+        // Collect output paths for .gitignore
+        const outputPaths = getAgentOutputPaths(agent, projectRoot, agentConfig);
+        generatedPaths.push(...outputPaths);
         const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
         const enabled = cliMcpEnabled &&
             (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
@@ -143,4 +183,25 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
             await (0, mcp_1.writeNativeMcp)(dest, merged);
         }
     }
+    // Handle .gitignore updates
+    // Configuration precedence: CLI > TOML > Default (enabled)
+    let gitignoreEnabled;
+    if (cliGitignoreEnabled !== undefined) {
+        gitignoreEnabled = cliGitignoreEnabled;
+    }
+    else if (config.gitignore?.enabled !== undefined) {
+        gitignoreEnabled = config.gitignore.enabled;
+    }
+    else {
+        gitignoreEnabled = true; // Default enabled
+    }
+    if (gitignoreEnabled && generatedPaths.length > 0) {
+        // Filter out .bak files as specified in requirements
+        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.`);
+        }
+    }
 }

package/package.json

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