@intellectronica/ruler 0.2.5 → 0.2.7

package/README.md

@@ -40,6 +40,7 @@ Ruler solves this by providing a **single source of truth** for all your AI agen
 | GitHub Copilot   | `.github/copilot-instructions.md`                             |
 | Claude Code      | `CLAUDE.md`                                                   |
 | OpenAI Codex CLI | `AGENTS.md`                                                   |
+| Jules            | `AGENTS.md`                                                   |
 | Cursor           | `.cursor/rules/ruler_cursor_instructions.mdc`                 |
 | Windsurf         | `.windsurf/rules/ruler_windsurf_instructions.md`              |
 | Cline            | `.clinerules`                                                 |
@@ -78,13 +79,20 @@ npx @intellectronica/ruler apply
    - `.ruler/ruler.toml`: The main configuration file for Ruler
    - `.ruler/mcp.json`: An example MCP server configuration
 
+Additionally, you can create a global configuration to use when no local `.ruler/` directory is found:
+```bash
+ruler init --global
+```
+
+The global configuration will be created to `$XDG_CONFIG_HOME/ruler` (default: `~/.config/ruler`).
+
 ## 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
+- **Rule Files (`*.md`)**: Discovered recursively from `.ruler/` or `$XDG_CONFIG_HOME/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
@@ -128,6 +136,8 @@ This is your central hub for all AI agent instructions:
 ruler apply [options]
 ```
 
+The `apply` command looks for `.ruler/` in the current directory tree, reading the first match. If no such directory is found, it will look for a global configuration in `$XDG_CONFIG_HOME/ruler`.
+
 ### Options
 
 | Option                         | Description                                               |
@@ -140,6 +150,7 @@ ruler apply [options]
 | `--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
@@ -226,6 +237,9 @@ output_path = ".idx/airules.md"
 [agents.gemini-cli]
 enabled = true
 
+[agents.jules]
+enabled = true
+
 # Agent-specific MCP configuration
 [agents.cursor.mcp]
 enabled = true

package/dist/agents/JulesAgent.js

@@ -0,0 +1,55 @@
+"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.JulesAgent = void 0;
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+const path = __importStar(require("path"));
+class JulesAgent {
+    getIdentifier() {
+        return 'jules';
+    }
+    getName() {
+        return 'Jules';
+    }
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+        const outputPath = agentConfig?.outputPath ?? this.getDefaultOutputPath(projectRoot);
+        const absolutePath = path.resolve(projectRoot, outputPath);
+        await (0, FileSystemUtils_1.writeGeneratedFile)(absolutePath, concatenatedRules);
+    }
+    getDefaultOutputPath(projectRoot) {
+        return path.join(projectRoot, 'AGENTS.md');
+    }
+}
+exports.JulesAgent = JulesAgent;

package/dist/cli/commands.js

@@ -41,6 +41,7 @@ const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
 const lib_1 = require("../lib");
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const fs_1 = require("fs");
 const constants_1 = require("../constants");
 /**
@@ -90,6 +91,11 @@ function run() {
             description: 'Preview changes without writing files',
             default: false,
         });
+        y.option('local-only', {
+            type: 'boolean',
+            description: 'Only search for local .ruler directories, ignore global config',
+            default: false,
+        });
     }, async (argv) => {
         const projectRoot = argv['project-root'];
         const agents = argv.agents
@@ -102,6 +108,7 @@ function run() {
             : undefined;
         const verbose = argv.verbose;
         const dryRun = argv['dry-run'];
+        const localOnly = argv['local-only'];
         // Determine gitignore preference: CLI > TOML > Default (enabled)
         // yargs handles --no-gitignore by setting gitignore to false
         let gitignorePreference;
@@ -112,7 +119,7 @@ function run() {
             gitignorePreference = undefined; // Let TOML/default decide
         }
         try {
-            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun);
+            await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly);
             console.log('Ruler apply completed successfully.');
         }
         catch (err) {
@@ -126,10 +133,17 @@ function run() {
             type: 'string',
             description: 'Project root directory',
             default: process.cwd(),
+        }).option('global', {
+            type: 'boolean',
+            description: 'Initialize in global config directory (XDG_CONFIG_HOME/ruler)',
+            default: false,
         });
     }, async (argv) => {
         const projectRoot = argv['project-root'];
-        const rulerDir = path.join(projectRoot, '.ruler');
+        const isGlobal = argv['global'];
+        const rulerDir = isGlobal
+            ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
+            : path.join(projectRoot, '.ruler');
         await fs_1.promises.mkdir(rulerDir, { recursive: true });
         const instructionsPath = path.join(rulerDir, 'instructions.md');
         const tomlPath = path.join(rulerDir, 'ruler.toml');

package/dist/core/ConfigLoader.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
 const toml_1 = __importDefault(require("@iarna/toml"));
 const zod_1 = require("zod");
 const constants_1 = require("../constants");
@@ -78,9 +79,23 @@ const rulerConfigSchema = zod_1.z.object({
  */
 async function loadConfig(options) {
     const { projectRoot, configPath, cliAgents } = options;
-    const configFile = configPath
-        ? path.resolve(configPath)
-        : path.join(projectRoot, '.ruler', 'ruler.toml');
+    let configFile;
+    if (configPath) {
+        configFile = path.resolve(configPath);
+    }
+    else {
+        // Try local .ruler/ruler.toml first
+        const localConfigFile = path.join(projectRoot, '.ruler', 'ruler.toml');
+        try {
+            await fs_1.promises.access(localConfigFile);
+            configFile = localConfigFile;
+        }
+        catch {
+            // If local config doesn't exist, try global config
+            const xdgConfigDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+            configFile = path.join(xdgConfigDir, 'ruler', 'ruler.toml');
+        }
+    }
     let raw = {};
     try {
         const text = await fs_1.promises.readFile(configFile, 'utf8');

package/dist/core/FileSystemUtils.js

@@ -40,11 +40,20 @@ exports.backupFile = backupFile;
 exports.ensureDirExists = ensureDirExists;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+/**
+ * Gets the XDG config directory path, falling back to ~/.config if XDG_CONFIG_HOME is not set.
+ */
+function getXdgConfigDir() {
+    return process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+}
 /**
  * Searches upwards from startPath to find a directory named .ruler.
+ * If not found locally and checkGlobal is true, checks for global config at XDG_CONFIG_HOME/ruler.
  * Returns the path to the .ruler directory, or null if not found.
  */
-async function findRulerDir(startPath) {
+async function findRulerDir(startPath, checkGlobal = true) {
+    // First, search upwards from startPath for local .ruler directory
     let current = startPath;
     while (current) {
         const candidate = path.join(current, '.ruler');
@@ -63,6 +72,19 @@ async function findRulerDir(startPath) {
         }
         current = parent;
     }
+    // If no local .ruler found and checkGlobal is true, check global config directory
+    if (checkGlobal) {
+        const globalConfigDir = path.join(getXdgConfigDir(), 'ruler');
+        try {
+            const stat = await fs_1.promises.stat(globalConfigDir);
+            if (stat.isDirectory()) {
+                return globalConfigDir;
+            }
+        }
+        catch (err) {
+            console.error(`[ruler] Error checking global config directory ${globalConfigDir}:`, err);
+        }
+    }
     return null;
 }
 /**

package/dist/lib.js

@@ -50,6 +50,7 @@ const AiderAgent_1 = require("./agents/AiderAgent");
 const FirebaseAgent_1 = require("./agents/FirebaseAgent");
 const OpenHandsAgent_1 = require("./agents/OpenHandsAgent");
 const GeminiCliAgent_1 = require("./agents/GeminiCliAgent");
+const JulesAgent_1 = require("./agents/JulesAgent");
 const merge_1 = require("./mcp/merge");
 const validate_1 = require("./mcp/validate");
 const mcp_1 = require("./paths/mcp");
@@ -100,6 +101,7 @@ const agents = [
     new FirebaseAgent_1.FirebaseAgent(),
     new OpenHandsAgent_1.OpenHandsAgent(),
     new GeminiCliAgent_1.GeminiCliAgent(),
+    new JulesAgent_1.JulesAgent(),
 ];
 /**
  * Applies ruler configurations for all supported AI agents.
@@ -110,7 +112,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, cliGitignoreEnabled, verbose = false, dryRun = false) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false) {
     // Load configuration (default_agents, per-agent overrides, CLI filters)
     (0, constants_1.logVerbose)(`Loading configuration from project root: ${projectRoot}`, verbose);
     if (configPath) {
@@ -137,13 +139,13 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         }
     }
     config.agentConfigs = mappedConfigs;
-    const rulerDir = await FileSystemUtils.findRulerDir(projectRoot);
+    const rulerDir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
     if (!rulerDir) {
         throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
     }
     (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);
+    (0, constants_1.logVerbose)(`Found ${files.length} markdown files in ruler configuration 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');
@@ -187,6 +189,7 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
     }
     // Collect all generated file paths for .gitignore
     const generatedPaths = [];
+    let agentsMdWritten = false;
     for (const agent of selected) {
         const actionPrefix = dryRun ? '[ruler:dry-run]' : '[ruler]';
         console.log(`${actionPrefix} Applying rules for ${agent.getName()}...`);
@@ -196,10 +199,20 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         const outputPaths = getAgentOutputPaths(agent, projectRoot, agentConfig);
         (0, constants_1.logVerbose)(`Agent ${agent.getName()} output paths: ${outputPaths.join(', ')}`, verbose);
         generatedPaths.push(...outputPaths);
+        // Also add the backup file paths to the gitignore list
+        const backupPaths = outputPaths.map((p) => `${p}.bak`);
+        generatedPaths.push(...backupPaths);
         if (dryRun) {
             (0, constants_1.logVerbose)(`DRY RUN: Would write rules to: ${outputPaths.join(', ')}`, verbose);
         }
         else {
+            if (agent.getIdentifier() === 'jules' ||
+                agent.getIdentifier() === 'codex') {
+                if (agentsMdWritten) {
+                    continue;
+                }
+                agentsMdWritten = true;
+            }
             await agent.applyRulerConfig(concatenated, projectRoot, rulerMcpJson, agentConfig);
         }
         const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
@@ -207,6 +220,13 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
             (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
         const rulerMcpFile = path.join(rulerDir, 'mcp.json');
         if (dest && mcpEnabledForAgent) {
+            // Include MCP config file in .gitignore only if it's within the project directory
+            if (dest.startsWith(projectRoot)) {
+                const relativeDest = path.relative(projectRoot, dest);
+                generatedPaths.push(relativeDest);
+                // Also add the backup for the MCP file
+                generatedPaths.push(`${relativeDest}.bak`);
+            }
             if (agent.getIdentifier() === 'openhands') {
                 // *** Special handling for Open Hands ***
                 if (dryRun) {
@@ -215,8 +235,7 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
                 else {
                     await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(rulerMcpFile, dest);
                 }
-                // Include Open Hands config file in .gitignore
-                generatedPaths.push(dest);
+                // Open Hands config file is already included above
             }
             else {
                 if (rulerMcpJson) {
@@ -252,9 +271,9 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         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)];
+        const uniquePaths = [...new Set(generatedPaths)];
+        // Add wildcard pattern for backup files
+        uniquePaths.push('*.bak');
         if (uniquePaths.length > 0) {
             const actionPrefix = dryRun ? '[ruler:dry-run]' : '[ruler]';
             if (dryRun) {

package/dist/paths/mcp.js

@@ -71,6 +71,9 @@ async function getNativeMcpPath(adapterName, projectRoot) {
             // For Open Hands, we target the main config file, not a separate mcp.json
             candidates.push(path.join(projectRoot, '.openhands', 'config.toml'));
             break;
+        case 'Gemini CLI':
+            candidates.push(path.join(projectRoot, '.gemini', 'settings.json'));
+            break;
         default:
             return null;
     }

package/package.json

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