@intellectronica/ruler 0.3.40 → 0.3.42

package/dist/cli/handlers.js

@@ -51,15 +51,41 @@ function assertNotInsideRulerDir(projectRoot) {
         process.exit(1);
     }
 }
+function formatCliError(message) {
+    return message.startsWith(constants_1.ERROR_PREFIX)
+        ? message
+        : `${constants_1.ERROR_PREFIX} ${message}`;
+}
+function parseCliAgents(agents) {
+    if (agents === undefined) {
+        return undefined;
+    }
+    const parsedAgents = agents.split(',').map((agent) => agent.trim());
+    if (parsedAgents.some((agent) => agent.length === 0)) {
+        throw new Error('Empty agent token in --agents. Remove extra commas or provide an agent name.');
+    }
+    return parsedAgents;
+}
+async function resolveNestedPreference(argv, projectRoot, configPath, localOnly) {
+    if (argv.nested !== undefined) {
+        // CLI explicitly set nested (either --nested or --no-nested)
+        return argv.nested;
+    }
+    // CLI didn't set nested, check TOML configuration
+    const config = await (0, ConfigLoader_1.loadConfig)({
+        projectRoot,
+        configPath,
+        checkGlobal: !localOnly,
+    });
+    // Use TOML setting if available, otherwise default to false
+    return config.nested ?? false;
+}
 /**
  * Handler for the 'apply' command.
  */
 async function applyHandler(argv) {
     const projectRoot = argv['project-root'];
     assertNotInsideRulerDir(projectRoot);
-    const agents = argv.agents
-        ? argv.agents.split(',').map((a) => a.trim())
-        : undefined;
     const configPath = argv.config;
     const mcpEnabled = argv.mcp;
     const mcpStrategy = argv['mcp-overwrite']
@@ -85,27 +111,6 @@ async function applyHandler(argv) {
     else {
         gitignoreLocalPreference = undefined; // Let TOML/default decide
     }
-    // Determine nested preference: CLI > TOML > Default (false)
-    let nested;
-    if (argv.nested !== undefined) {
-        // CLI explicitly set nested (either --nested or --no-nested)
-        nested = argv.nested;
-    }
-    else {
-        // CLI didn't set nested, check TOML configuration
-        try {
-            const config = await (0, ConfigLoader_1.loadConfig)({
-                projectRoot,
-                configPath,
-            });
-            // Use TOML setting if available, otherwise default to false
-            nested = config.nested ?? false;
-        }
-        catch {
-            // If config loading fails, use default (false)
-            nested = false;
-        }
-    }
     // Determine skills preference: CLI > TOML > Default (enabled)
     let skillsEnabled;
     if (argv.skills !== undefined) {
@@ -114,7 +119,7 @@ async function applyHandler(argv) {
     else {
         skillsEnabled = undefined; // Let config/default decide
     }
-    // Determine subagents preference: CLI > TOML > Default (enabled)
+    // Determine subagents preference: CLI > TOML > Default (disabled)
     let subagentsEnabled;
     if (argv.subagents !== undefined) {
         subagentsEnabled = argv.subagents;
@@ -123,12 +128,15 @@ async function applyHandler(argv) {
         subagentsEnabled = undefined; // Let config/default decide
     }
     try {
+        const agents = parseCliAgents(argv.agents);
+        // Determine nested preference: CLI > TOML > Default (false)
+        const nested = await resolveNestedPreference(argv, projectRoot, configPath, localOnly);
         await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup, skillsEnabled, gitignoreLocalPreference, subagentsEnabled);
         console.log('Ruler apply completed successfully.');
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        console.error(formatCliError(message));
         process.exit(1);
     }
 }
@@ -138,23 +146,24 @@ async function applyHandler(argv) {
 async function initHandler(argv) {
     const projectRoot = argv['project-root'];
     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.mkdir(rulerDir, { recursive: true });
-    const instructionsPath = path.join(rulerDir, constants_1.DEFAULT_RULES_FILENAME); // .ruler/AGENTS.md
-    const tomlPath = path.join(rulerDir, 'ruler.toml');
-    const exists = async (p) => {
-        try {
-            await fs.access(p);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
-    const DEFAULT_INSTRUCTIONS = `# AGENTS.md\n\nCentralised AI agent instructions. Add coding guidelines, style guides, and project context here.\n\nRuler concatenates all .md files in this directory (and subdirectories), starting with AGENTS.md (if present), then remaining files in sorted order.\n`;
-    const DEFAULT_TOML = `# Ruler Configuration File
+    try {
+        const rulerDir = isGlobal
+            ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
+            : path.join(projectRoot, '.ruler');
+        await fs.mkdir(rulerDir, { recursive: true });
+        const instructionsPath = path.join(rulerDir, constants_1.DEFAULT_RULES_FILENAME); // .ruler/AGENTS.md
+        const tomlPath = path.join(rulerDir, 'ruler.toml');
+        const exists = async (p) => {
+            try {
+                await fs.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const DEFAULT_INSTRUCTIONS = `# AGENTS.md\n\nCentralised AI agent instructions. Add coding guidelines, style guides, and project context here.\n\nRuler concatenates all .md files in this directory (and subdirectories), starting with AGENTS.md (if present), then remaining files in sorted order.\n`;
+        const DEFAULT_TOML = `# Ruler Configuration File
 # See https://ai.intellectronica.net/ruler for documentation.
 
 # To specify which agents are active by default when --agents is not used,
@@ -169,6 +178,9 @@ async function initHandler(argv) {
 # enabled = true
 # local = false  # set true to write generated ignores to .git/info/exclude instead
 
+# [backup]
+# enabled = true  # set false to disable .bak backup files
+
 # --- Agent Specific Configurations ---
 # You can enable/disable agents and override their default output paths here.
 # Use lowercase agent identifiers: aider, amp, claude, cline, codex, copilot, cursor, jetbrains-ai, kilocode, pi, windsurf
@@ -199,20 +211,26 @@ async function initHandler(argv) {
 # url = "https://api.example.com/mcp"
 # headers = { Authorization = "Bearer REPLACE_ME" }
 `;
-    if (!(await exists(instructionsPath))) {
-        // Create new AGENTS.md regardless of legacy presence.
-        await fs.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
-        console.log(`[ruler] Created ${instructionsPath}`);
-    }
-    else {
-        console.log(`[ruler] ${constants_1.DEFAULT_RULES_FILENAME} already exists, skipping`);
-    }
-    if (!(await exists(tomlPath))) {
-        await fs.writeFile(tomlPath, DEFAULT_TOML);
-        console.log(`[ruler] Created ${tomlPath}`);
+        if (!(await exists(instructionsPath))) {
+            // Create new AGENTS.md regardless of legacy presence.
+            await fs.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
+            console.log(`[ruler] Created ${instructionsPath}`);
+        }
+        else {
+            console.log(`[ruler] ${constants_1.DEFAULT_RULES_FILENAME} already exists, skipping`);
+        }
+        if (!(await exists(tomlPath))) {
+            await fs.writeFile(tomlPath, DEFAULT_TOML);
+            console.log(`[ruler] Created ${tomlPath}`);
+        }
+        else {
+            console.log(`[ruler] ruler.toml already exists, skipping`);
+        }
     }
-    else {
-        console.log(`[ruler] ruler.toml already exists, skipping`);
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(formatCliError(message));
+        process.exit(1);
     }
 }
 /**
@@ -221,20 +239,18 @@ async function initHandler(argv) {
 async function revertHandler(argv) {
     const projectRoot = argv['project-root'];
     assertNotInsideRulerDir(projectRoot);
-    const agents = argv.agents
-        ? argv.agents.split(',').map((a) => a.trim())
-        : undefined;
     const configPath = argv.config;
     const keepBackups = argv['keep-backups'];
     const verbose = argv.verbose;
     const dryRun = argv['dry-run'];
     const localOnly = argv['local-only'];
     try {
+        const agents = parseCliAgents(argv.agents);
         await (0, revert_1.revertAllAgentConfigs)(projectRoot, agents, configPath, keepBackups, verbose, dryRun, localOnly);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        console.error(formatCliError(message));
         process.exit(1);
     }
 }

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/constants.d.ts

@@ -0,0 +1,35 @@
+export declare const ERROR_PREFIX = "[ruler]";
+export declare const DEFAULT_RULES_FILENAME = "AGENTS.md";
+export declare function actionPrefix(dry: boolean): string;
+export declare function createRulerError(message: string, context?: string): Error;
+export declare function logVerbose(message: string, isVerbose: boolean): void;
+/**
+ * Centralized logging functions with consistent output streams and prefixing.
+ * - info/verbose go to stdout (user-visible progress)
+ * - warn/error go to stderr (problems)
+ */
+export declare function logInfo(message: string, dryRun?: boolean): void;
+export declare function logWarn(message: string, dryRun?: boolean): void;
+export declare function logError(message: string, dryRun?: boolean): void;
+export declare function logVerboseInfo(message: string, isVerbose: boolean, dryRun?: boolean): void;
+export declare const SKILLS_DIR = "skills";
+export declare const RULER_SKILLS_PATH = ".ruler/skills";
+export declare const CLAUDE_SKILLS_PATH = ".claude/skills";
+export declare const CODEX_SKILLS_PATH = ".codex/skills";
+export declare const OPENCODE_SKILLS_PATH = ".opencode/skills";
+export declare const PI_SKILLS_PATH = ".pi/skills";
+export declare const GOOSE_SKILLS_PATH = ".agents/skills";
+export declare const VIBE_SKILLS_PATH = ".vibe/skills";
+export declare const ROO_SKILLS_PATH = ".roo/skills";
+export declare const GEMINI_SKILLS_PATH = ".gemini/skills";
+export declare const JUNIE_SKILLS_PATH = ".junie/skills";
+export declare const CURSOR_SKILLS_PATH = ".cursor/skills";
+export declare const WINDSURF_SKILLS_PATH = ".windsurf/skills";
+export declare const FACTORY_SKILLS_PATH = ".factory/skills";
+export declare const ANTIGRAVITY_SKILLS_PATH = ".agent/skills";
+export declare const SKILL_MD_FILENAME = "SKILL.md";
+export declare const RULER_SUBAGENTS_PATH = ".ruler/agents";
+export declare const CLAUDE_SUBAGENTS_PATH = ".claude/agents";
+export declare const CURSOR_SUBAGENTS_PATH = ".cursor/agents";
+export declare const CODEX_SUBAGENTS_PATH = ".codex/agents";
+export declare const COPILOT_SUBAGENTS_PATH = ".github/agents";

package/dist/core/ConfigLoader.d.ts

@@ -0,0 +1,57 @@
+import { McpConfig, GlobalMcpConfig, GitignoreConfig, BackupConfig, SkillsConfig, SubagentsConfig } from '../types';
+/** Test helper — re-arms the deprecation guard so suites can assert it fires. */
+export declare function _resetLegacySubagentsWarningForTests(): void;
+/**
+ * Configuration for a specific agent as defined in ruler.toml.
+ */
+export interface IAgentConfig {
+    enabled?: boolean;
+    outputPath?: string;
+    outputPathInstructions?: string;
+    outputPathConfig?: string;
+    /** MCP propagation config for this agent. */
+    mcp?: McpConfig;
+}
+/**
+ * Parsed ruler configuration values.
+ */
+export interface LoadedConfig {
+    /** Agents to run by default, as specified by default_agents. */
+    defaultAgents?: string[];
+    /** Per-agent configuration overrides. */
+    agentConfigs: Record<string, IAgentConfig>;
+    /** Command-line agent filters (--agents), if provided. */
+    cliAgents?: string[];
+    /** Global MCP servers configuration section. */
+    mcp?: GlobalMcpConfig;
+    /** Gitignore configuration section. */
+    gitignore?: GitignoreConfig;
+    /** Backup configuration section. */
+    backup?: BackupConfig;
+    /** Skills configuration section. */
+    skills?: SkillsConfig;
+    /** Subagents configuration section. */
+    subagents?: SubagentsConfig;
+    /** Whether to enable nested rule loading from nested .ruler directories. */
+    nested?: boolean;
+    /** Whether the nested option was explicitly provided in the config. */
+    nestedDefined?: boolean;
+}
+/**
+ * Options for loading the ruler configuration.
+ */
+export interface ConfigOptions {
+    projectRoot: string;
+    /** Path to a custom TOML config file. */
+    configPath?: string;
+    /** CLI filters from --agents option. */
+    cliAgents?: string[];
+    /** Whether implicit config discovery may fall back to XDG_CONFIG_HOME/ruler. */
+    checkGlobal?: boolean;
+}
+/**
+ * Loads and parses the ruler TOML configuration file, applying defaults.
+ * Missing implicit configs return defaults. Explicit configs and existing
+ * implicit configs fail fast when missing, unreadable, or invalid.
+ */
+export declare function loadConfig(options: ConfigOptions): Promise<LoadedConfig>;

package/dist/core/ConfigLoader.js

@@ -76,13 +76,18 @@ const agentConfigSchema = zod_1.z
 //   - one nested table per coding-agent integration (`[agents.claude]`, etc.)
 // Reserved keys are validated by the object shape; everything else falls
 // through `catchall` and is treated as a per-agent config record.
-const SUBAGENT_RESERVED_KEYS = new Set(['enabled', 'include_in_rules']);
+const SUBAGENT_RESERVED_KEYS = new Set([
+    'enabled',
+    'include_in_rules',
+    'cleanup_orphaned',
+]);
 const rulerConfigSchema = zod_1.z.object({
     default_agents: zod_1.z.array(zod_1.z.string()).optional(),
     agents: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
         include_in_rules: zod_1.z.boolean().optional(),
+        cleanup_orphaned: zod_1.z.boolean().optional(),
     })
         .catchall(agentConfigSchema)
         .optional(),
@@ -98,6 +103,11 @@ const rulerConfigSchema = zod_1.z.object({
         local: zod_1.z.boolean().optional(),
     })
         .optional(),
+    backup: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .optional(),
     skills: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
@@ -111,6 +121,7 @@ const rulerConfigSchema = zod_1.z.object({
         .object({
         enabled: zod_1.z.boolean().optional(),
         include_in_rules: zod_1.z.boolean().optional(),
+        cleanup_orphaned: zod_1.z.boolean().optional(),
     })
         .optional(),
     nested: zod_1.z.boolean().optional(),
@@ -138,48 +149,16 @@ function stripSymbols(obj) {
 }
 /**
  * Loads and parses the ruler TOML configuration file, applying defaults.
- * If the file is missing or invalid, returns empty/default config.
+ * Missing implicit configs return defaults. Explicit configs and existing
+ * implicit configs fail fast when missing, unreadable, or invalid.
  */
 async function loadConfig(options) {
     const { projectRoot, configPath, cliAgents } = options;
-    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');
-        const parsed = text.trim() ? (0, toml_1.parse)(text) : {};
-        // Strip Symbol properties added by @iarna/toml (required for Zod v4+)
-        raw = stripSymbols(parsed);
-        // 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('[ruler]')) {
-                throw err; // Re-throw validation errors
-            }
-            console.warn(`[ruler] Warning: could not read config file at ${configFile}: ${err.message}`);
-        }
-        raw = {};
-    }
+    const checkGlobal = options.checkGlobal ?? true;
+    const configFile = configPath
+        ? path.resolve(configPath)
+        : await resolveImplicitConfigFile(projectRoot, checkGlobal);
+    const raw = configFile ? await readConfigFile(configFile) : {};
     const defaultAgents = Array.isArray(raw.default_agents)
         ? raw.default_agents.map((a) => String(a))
         : undefined;
@@ -250,6 +229,13 @@ async function loadConfig(options) {
     if (typeof rawGitignoreSection.local === 'boolean') {
         gitignoreConfig.local = rawGitignoreSection.local;
     }
+    const rawBackupSection = raw.backup && typeof raw.backup === 'object' && !Array.isArray(raw.backup)
+        ? raw.backup
+        : {};
+    const backupConfig = {};
+    if (typeof rawBackupSection.enabled === 'boolean') {
+        backupConfig.enabled = rawBackupSection.enabled;
+    }
     const rawSkillsSection = raw.skills && typeof raw.skills === 'object' && !Array.isArray(raw.skills)
         ? raw.skills
         : {};
@@ -272,7 +258,8 @@ async function loadConfig(options) {
         ? raw.subagents
         : {};
     const legacyHasContent = typeof rawLegacySubagentsSection.enabled === 'boolean' ||
-        typeof rawLegacySubagentsSection.include_in_rules === 'boolean';
+        typeof rawLegacySubagentsSection.include_in_rules === 'boolean' ||
+        typeof rawLegacySubagentsSection.cleanup_orphaned === 'boolean';
     if (legacyHasContent) {
         warnLegacySubagentsSection();
     }
@@ -291,6 +278,14 @@ async function loadConfig(options) {
         subagentsConfig.include_in_rules =
             rawLegacySubagentsSection.include_in_rules;
     }
+    if (typeof agentsSection.cleanup_orphaned === 'boolean') {
+        subagentsConfig.cleanup_orphaned =
+            agentsSection.cleanup_orphaned;
+    }
+    else if (typeof rawLegacySubagentsSection.cleanup_orphaned === 'boolean') {
+        subagentsConfig.cleanup_orphaned =
+            rawLegacySubagentsSection.cleanup_orphaned;
+    }
     const nestedDefined = typeof raw.nested === 'boolean';
     const nested = nestedDefined ? raw.nested : false;
     return {
@@ -299,9 +294,96 @@ async function loadConfig(options) {
         cliAgents,
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
+        backup: backupConfig,
         skills: skillsConfig,
         subagents: subagentsConfig,
         nested,
         nestedDefined,
     };
 }
+async function resolveImplicitConfigFile(projectRoot, checkGlobal) {
+    const localRulerDir = await findNearestLocalRulerDir(projectRoot);
+    const localConfigFile = localRulerDir
+        ? path.join(localRulerDir, 'ruler.toml')
+        : path.join(projectRoot, '.ruler', 'ruler.toml');
+    if (await configFileExists(localConfigFile)) {
+        return localConfigFile;
+    }
+    if (!checkGlobal) {
+        return undefined;
+    }
+    const xdgConfigDir = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    const globalConfigFile = path.join(xdgConfigDir, 'ruler', 'ruler.toml');
+    if (await configFileExists(globalConfigFile)) {
+        return globalConfigFile;
+    }
+    return undefined;
+}
+async function findNearestLocalRulerDir(startPath) {
+    let current = path.resolve(startPath);
+    while (current) {
+        const candidate = path.join(current, '.ruler');
+        try {
+            const stat = await fs_1.promises.stat(candidate);
+            if (stat.isDirectory()) {
+                return candidate;
+            }
+        }
+        catch {
+            // Keep walking; missing or inaccessible candidates simply do not match.
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+    return undefined;
+}
+async function configFileExists(configFile) {
+    try {
+        await fs_1.promises.access(configFile);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return false;
+        }
+        throw (0, constants_1.createRulerError)('Could not access configuration file', `File: ${configFile}, Error: ${errorMessage(err)}`);
+    }
+}
+async function readConfigFile(configFile) {
+    const text = await readConfigText(configFile);
+    const parsed = parseConfigText(text, configFile);
+    const raw = stripSymbols(parsed);
+    validateConfig(raw, configFile);
+    return raw;
+}
+async function readConfigText(configFile) {
+    try {
+        return await fs_1.promises.readFile(configFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw (0, constants_1.createRulerError)('Configuration file not found', `File: ${configFile}`);
+        }
+        throw (0, constants_1.createRulerError)('Could not read configuration file', `File: ${configFile}, Error: ${errorMessage(err)}`);
+    }
+}
+function parseConfigText(text, configFile) {
+    try {
+        return text.trim() ? (0, toml_1.parse)(text) : {};
+    }
+    catch (err) {
+        throw (0, constants_1.createRulerError)('Invalid configuration file', `File: ${configFile}, Error: ${errorMessage(err)}`);
+    }
+}
+function validateConfig(raw, configFile) {
+    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(', ')}`);
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/core/FileSystemUtils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+export declare function findRulerDir(startPath: string, checkGlobal?: boolean): Promise<string | null>;
+/**
+ * Options for {@link readMarkdownFiles}.
+ */
+export interface ReadMarkdownFilesOptions {
+    /**
+     * When true, include `.ruler/agents/*.md` in the returned set so they are
+     * concatenated into the top-level generated rule files. When false or
+     * omitted, `.ruler/agents/` is skipped, mirroring `.ruler/skills/`.
+     */
+    includeAgents?: boolean;
+}
+/**
+ * Recursively reads all Markdown (.md) files in rulerDir, returning their paths and contents.
+ * Files are sorted alphabetically by path.
+ *
+ * `.ruler/skills/` is always skipped (skills are propagated separately).
+ * `.ruler/agents/` is skipped unless `options.includeAgents` is `true`.
+ */
+export declare function readMarkdownFiles(rulerDir: string, options?: ReadMarkdownFilesOptions): Promise<{
+    path: string;
+    content: string;
+}[]>;
+/**
+ * Writes content to filePath, creating parent directories if necessary.
+ */
+export declare function writeGeneratedFile(filePath: string, content: string): Promise<void>;
+/**
+ * Creates a backup of the given filePath by copying it to filePath.bak if it exists.
+ * Keeps an existing backup intact so repeated applies preserve the original file.
+ */
+export declare function backupFile(filePath: string): Promise<void>;
+/**
+ * Ensures that the given directory exists by creating it recursively.
+ */
+export declare function ensureDirExists(dirPath: string): Promise<void>;
+/**
+ * Finds the global ruler configuration directory at XDG_CONFIG_HOME/ruler.
+ * Returns the path if it exists, null otherwise.
+ */
+export declare function findGlobalRulerDir(): Promise<string | null>;
+/**
+ * Searches the entire directory tree from startPath to find all .ruler directories.
+ * Returns an array of .ruler directory paths from most specific to least specific.
+ */
+export declare function findAllRulerDirs(startPath: string): Promise<string[]>;

package/dist/core/FileSystemUtils.js

@@ -45,12 +45,27 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const constants_1 = require("../constants");
 const SUBAGENTS_DIR_NAME = path.basename(constants_1.RULER_SUBAGENTS_PATH);
+const DEFAULT_NESTED_DISCOVERY_IGNORES = new Set([
+    '__fixtures__',
+    '__generated__',
+    'build',
+    'coverage',
+    'dist',
+    'fixtures',
+    'generated',
+    'node_modules',
+    'temp',
+    'tmp',
+]);
 /**
  * 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');
 }
+function shouldSkipNestedDiscoveryDir(dirName) {
+    return (dirName.startsWith('.') || DEFAULT_NESTED_DISCOVERY_IGNORES.has(dirName));
+}
 /**
  * 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.
@@ -222,11 +237,19 @@ async function writeGeneratedFile(filePath, content) {
 }
 /**
  * Creates a backup of the given filePath by copying it to filePath.bak if it exists.
+ * Keeps an existing backup intact so repeated applies preserve the original file.
  */
 async function backupFile(filePath) {
+    const backupPath = `${filePath}.bak`;
     try {
-        await fs_1.promises.access(filePath);
-        await fs_1.promises.copyFile(filePath, `${filePath}.bak`);
+        await fs_1.promises.access(backupPath);
+        return;
+    }
+    catch {
+        // continue if no backup exists yet
+    }
+    try {
+        await fs_1.promises.copyFile(filePath, backupPath);
     }
     catch {
         // ignore if file does not exist
@@ -272,23 +295,20 @@ async function findAllRulerDirs(startPath) {
                     if (entry.name === '.ruler') {
                         rulerDirs.push(fullPath);
                     }
-                    else {
-                        // Recursively search subdirectories (but skip hidden directories like .git)
-                        if (!entry.name.startsWith('.')) {
-                            // Do not cross git repository boundaries (except the starting root)
-                            const gitDir = path.join(fullPath, '.git');
-                            try {
-                                const gitStat = await fs_1.promises.stat(gitDir);
-                                if (gitStat.isDirectory() &&
-                                    path.resolve(fullPath) !== rootPath) {
-                                    continue;
-                                }
-                            }
-                            catch {
-                                // no .git boundary, continue traversal
+                    else if (!shouldSkipNestedDiscoveryDir(entry.name)) {
+                        // Do not cross git repository boundaries (except the starting root)
+                        const gitDir = path.join(fullPath, '.git');
+                        try {
+                            const gitStat = await fs_1.promises.stat(gitDir);
+                            if (gitStat.isDirectory() &&
+                                path.resolve(fullPath) !== rootPath) {
+                                continue;
                             }
-                            await findRulerDirs(fullPath);
                         }
+                        catch {
+                            // no .git boundary, continue traversal
+                        }
+                        await findRulerDirs(fullPath);
                     }
                 }
             }