@intellectronica/ruler 0.3.41 → 0.3.43

package/dist/core/ConfigLoader.js

@@ -40,6 +40,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const toml_1 = require("@iarna/toml");
 const zod_1 = require("zod");
+const path_utils_1 = require("./path-utils");
 const constants_1 = require("../constants");
 // One-shot guard so the deprecation message fires once per process even when
 // `loadConfig` is called multiple times (e.g. nested mode walks every
@@ -61,6 +62,7 @@ const mcpConfigSchema = zod_1.z
     enabled: zod_1.z.boolean().optional(),
     merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
 })
+    .strict()
     .optional();
 const agentConfigSchema = zod_1.z
     .object({
@@ -69,7 +71,11 @@ const agentConfigSchema = zod_1.z
     output_path_instructions: zod_1.z.string().optional(),
     output_path_config: zod_1.z.string().optional(),
     mcp: mcpConfigSchema,
+    mcp_servers: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
+        .optional(),
 })
+    .strict()
     .optional();
 // `[agents]` is a heterogeneous table that holds two unrelated kinds of keys:
 //   - reserved subagent-control booleans (`enabled`, `include_in_rules`)
@@ -81,7 +87,8 @@ const SUBAGENT_RESERVED_KEYS = new Set([
     'include_in_rules',
     'cleanup_orphaned',
 ]);
-const rulerConfigSchema = zod_1.z.object({
+const rulerConfigSchema = zod_1.z
+    .object({
     default_agents: zod_1.z.array(zod_1.z.string()).optional(),
     agents: zod_1.z
         .object({
@@ -96,17 +103,29 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
         merge_strategy: zod_1.z.enum(['merge', 'overwrite']).optional(),
     })
+        .strict()
+        .optional(),
+    mcp_servers: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
         .optional(),
     gitignore: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
         local: zod_1.z.boolean().optional(),
     })
+        .strict()
+        .optional(),
+    backup: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .strict()
         .optional(),
     skills: zod_1.z
         .object({
         enabled: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     // Deprecated: kept in the schema only so that legacy `[subagents]` blocks
     // are preserved through validation. The parser reads from here as a
@@ -118,9 +137,11 @@ const rulerConfigSchema = zod_1.z.object({
         include_in_rules: zod_1.z.boolean().optional(),
         cleanup_orphaned: zod_1.z.boolean().optional(),
     })
+        .strict()
         .optional(),
     nested: zod_1.z.boolean().optional(),
-});
+})
+    .strict();
 /**
  * Recursively creates a new object with only enumerable string keys,
  * effectively excluding Symbol properties.
@@ -142,50 +163,44 @@ function stripSymbols(obj) {
     }
     return result;
 }
+function parseAgentMcpServers(sectionObj) {
+    if (!sectionObj.mcp_servers ||
+        typeof sectionObj.mcp_servers !== 'object' ||
+        Array.isArray(sectionObj.mcp_servers)) {
+        return undefined;
+    }
+    const servers = {};
+    for (const [name, def] of Object.entries(sectionObj.mcp_servers)) {
+        if (def && typeof def === 'object' && !Array.isArray(def)) {
+            servers[name] = normalizeAgentMcpServer(def);
+        }
+    }
+    return Object.keys(servers).length > 0 ? servers : undefined;
+}
+function normalizeAgentMcpServer(def) {
+    const server = { ...def };
+    const hasCommand = typeof server.command === 'string';
+    const hasUrl = typeof server.url === 'string';
+    if (hasCommand && hasUrl) {
+        delete server.command;
+        delete server.args;
+        delete server.env;
+        server.type = 'remote';
+    }
+    return server;
+}
 /**
  * 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;
@@ -206,13 +221,13 @@ async function loadConfig(options) {
                 cfg.enabled = sectionObj.enabled;
             }
             if (typeof sectionObj.output_path === 'string') {
-                cfg.outputPath = path.resolve(projectRoot, sectionObj.output_path);
+                cfg.outputPath = resolveProjectOutputPath(projectRoot, sectionObj.output_path, configFile, `[agents.${name}].output_path`);
             }
             if (typeof sectionObj.output_path_instructions === 'string') {
-                cfg.outputPathInstructions = path.resolve(projectRoot, sectionObj.output_path_instructions);
+                cfg.outputPathInstructions = resolveProjectOutputPath(projectRoot, sectionObj.output_path_instructions, configFile, `[agents.${name}].output_path_instructions`);
             }
             if (typeof sectionObj.output_path_config === 'string') {
-                cfg.outputPathConfig = path.resolve(projectRoot, sectionObj.output_path_config);
+                cfg.outputPathConfig = resolveProjectOutputPath(projectRoot, sectionObj.output_path_config, configFile, `[agents.${name}].output_path_config`);
             }
             if (sectionObj.mcp && typeof sectionObj.mcp === 'object') {
                 const m = sectionObj.mcp;
@@ -228,6 +243,7 @@ async function loadConfig(options) {
                 }
                 cfg.mcp = mcpCfg;
             }
+            cfg.mcpServers = parseAgentMcpServers(sectionObj);
             agentConfigs[name] = cfg;
         }
     }
@@ -256,6 +272,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
         : {};
@@ -314,9 +337,120 @@ async function loadConfig(options) {
         cliAgents,
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
+        backup: backupConfig,
         skills: skillsConfig,
         subagents: subagentsConfig,
         nested,
         nestedDefined,
     };
 }
+function resolveProjectOutputPath(projectRoot, configuredPath, configFile, fieldName) {
+    const resolvedPath = path.resolve(projectRoot, configuredPath);
+    if (!(0, path_utils_1.isPathInsideOrEqual)(projectRoot, resolvedPath)) {
+        throw (0, constants_1.createRulerError)('Configured output path is outside the project root', [
+            configFile ? `File: ${configFile}` : undefined,
+            `Field: ${fieldName}`,
+            `Path: ${configuredPath}`,
+            `Project root: ${projectRoot}`,
+        ]
+            .filter(Boolean)
+            .join(', '));
+    }
+    return resolvedPath;
+}
+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(formatZodIssue).join(', ')}`);
+    }
+}
+function formatZodIssue(issue) {
+    const basePath = issue.path.join('.');
+    if (issue.code === 'unrecognized_keys') {
+        const keys = issue.keys;
+        return keys
+            .map((key) => (basePath ? `${basePath}.${key}` : key))
+            .join(', ');
+    }
+    return `${basePath}: ${issue.message}`;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/core/FileSystemUtils.d.ts

@@ -0,0 +1,53 @@
+export declare function assertManagedPathInsideRoot(managedPath: string, rootPath: string, action: string): Promise<void>;
+/**
+ * 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>;
+export declare function resolveProjectRootForRulerDir(requestedProjectRoot: string, rulerDir: string): string;
+/**
+ * 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, containmentRoot?: 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, containmentRoot?: 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

@@ -33,7 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertManagedPathInsideRoot = assertManagedPathInsideRoot;
 exports.findRulerDir = findRulerDir;
+exports.resolveProjectRootForRulerDir = resolveProjectRootForRulerDir;
 exports.readMarkdownFiles = readMarkdownFiles;
 exports.writeGeneratedFile = writeGeneratedFile;
 exports.backupFile = backupFile;
@@ -44,13 +46,90 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const constants_1 = require("../constants");
+const path_utils_1 = require("./path-utils");
 const SUBAGENTS_DIR_NAME = path.basename(constants_1.RULER_SUBAGENTS_PATH);
+const RULER_GENERATED_MARKER = '<!-- Generated by Ruler -->';
+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));
+}
+async function isSymbolicLink(filePath) {
+    try {
+        return (await fs_1.promises.lstat(filePath)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function assertNotSymbolicLink(filePath, action) {
+    if (await isSymbolicLink(filePath)) {
+        throw new Error(`${action}: ${filePath}`);
+    }
+}
+async function assertContainingDirectoryInsideRoot(filePath, rootPath, action) {
+    const realRoot = await fs_1.promises.realpath(rootPath);
+    let current = path.dirname(path.resolve(filePath));
+    while (true) {
+        try {
+            const realCurrent = await fs_1.promises.realpath(current);
+            if (!(0, path_utils_1.isPathInsideOrEqual)(realRoot, realCurrent)) {
+                throw new Error(`${action}: ${filePath}`);
+            }
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+async function assertManagedPathInsideRoot(managedPath, rootPath, action) {
+    const realRoot = await fs_1.promises.realpath(rootPath);
+    await assertContainingDirectoryInsideRoot(managedPath, rootPath, action);
+    try {
+        const realManagedPath = await fs_1.promises.realpath(managedPath);
+        if (!(0, path_utils_1.isPathInsideOrEqual)(realRoot, realManagedPath)) {
+            throw new Error(`${action}: ${managedPath}`);
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+async function isRulerGeneratedFile(filePath) {
+    try {
+        const content = await fs_1.promises.readFile(filePath, 'utf8');
+        return content.startsWith(RULER_GENERATED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 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.
@@ -86,11 +165,19 @@ async function findRulerDir(startPath, checkGlobal = true) {
             }
         }
         catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
             console.error(`[ruler] Error checking global config directory ${globalConfigDir}:`, err);
         }
     }
     return null;
 }
+function resolveProjectRootForRulerDir(requestedProjectRoot, rulerDir) {
+    return path.basename(rulerDir) === '.ruler'
+        ? path.dirname(rulerDir)
+        : requestedProjectRoot;
+}
 /**
  * Recursively reads all Markdown (.md) files in rulerDir, returning their paths and contents.
  * Files are sorted alphabetically by path.
@@ -101,6 +188,8 @@ async function findRulerDir(startPath, checkGlobal = true) {
 async function readMarkdownFiles(rulerDir, options = {}) {
     const mdFiles = [];
     const includeAgents = options.includeAgents === true;
+    const realRulerDir = await fs_1.promises.realpath(rulerDir);
+    const visitedDirectories = new Set();
     // Tracks whether we skipped a `.ruler/agents` subtree so the root-AGENTS.md
     // fallback below still recognises ruler content as present and does not
     // resurrect a previously generated root AGENTS.md (which may itself contain
@@ -108,6 +197,17 @@ async function readMarkdownFiles(rulerDir, options = {}) {
     let sawExcludedAgents = false;
     // Gather all markdown files (recursive) first
     async function walk(dir) {
+        let realDir;
+        try {
+            realDir = await fs_1.promises.realpath(dir);
+        }
+        catch {
+            return;
+        }
+        if (visitedDirectories.has(realDir)) {
+            return;
+        }
+        visitedDirectories.add(realDir);
         const entries = await fs_1.promises.readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
@@ -116,6 +216,10 @@ async function readMarkdownFiles(rulerDir, options = {}) {
             let isFile = entry.isFile();
             if (entry.isSymbolicLink()) {
                 try {
+                    const realTarget = await fs_1.promises.realpath(fullPath);
+                    if (!(0, path_utils_1.isPathInsideOrEqual)(realRulerDir, realTarget)) {
+                        continue;
+                    }
                     const stat = await fs_1.promises.stat(fullPath);
                     isDir = stat.isDirectory();
                     isFile = stat.isFile();
@@ -186,7 +290,19 @@ async function readMarkdownFiles(rulerDir, options = {}) {
         const repoRoot = path.dirname(rulerDir); // .ruler parent
         const rootAgentsPath = path.join(repoRoot, 'AGENTS.md');
         if (path.resolve(rootAgentsPath) !== path.resolve(topLevelAgents)) {
-            const stat = await fs_1.promises.stat(rootAgentsPath);
+            const rootAgentsStat = await fs_1.promises.lstat(rootAgentsPath);
+            if (rootAgentsStat.isSymbolicLink()) {
+                const [realRepoRoot, realRootAgentsPath] = await Promise.all([
+                    fs_1.promises.realpath(repoRoot),
+                    fs_1.promises.realpath(rootAgentsPath),
+                ]);
+                if (!(0, path_utils_1.isPathInsideOrEqual)(realRepoRoot, realRootAgentsPath)) {
+                    return ordered;
+                }
+            }
+            const stat = rootAgentsStat.isSymbolicLink()
+                ? await fs_1.promises.stat(rootAgentsPath)
+                : rootAgentsStat;
             if (stat.isFile()) {
                 const content = await fs_1.promises.readFile(rootAgentsPath, 'utf8');
                 // Check if this is a generated file and we have other .ruler files.
@@ -216,17 +332,41 @@ async function readMarkdownFiles(rulerDir, options = {}) {
 /**
  * Writes content to filePath, creating parent directories if necessary.
  */
-async function writeGeneratedFile(filePath, content) {
+async function writeGeneratedFile(filePath, content, containmentRoot) {
+    if (containmentRoot) {
+        await assertContainingDirectoryInsideRoot(filePath, containmentRoot, 'Refusing to write generated file through symlinked directory');
+    }
     await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    await assertNotSymbolicLink(filePath, 'Refusing to write generated file through symlink');
+    if (containmentRoot) {
+        await assertContainingDirectoryInsideRoot(filePath, containmentRoot, 'Refusing to write generated file through symlinked directory');
+    }
     await fs_1.promises.writeFile(filePath, content, 'utf8');
 }
 /**
  * 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) {
+async function backupFile(filePath, containmentRoot) {
+    const backupPath = `${filePath}.bak`;
+    if (containmentRoot) {
+        await assertManagedPathInsideRoot(filePath, containmentRoot, 'Refusing to back up generated file through symlinked directory');
+        await assertManagedPathInsideRoot(backupPath, containmentRoot, 'Refusing to create backup file through symlinked directory');
+    }
+    await assertNotSymbolicLink(filePath, 'Refusing to back up symlinked file');
+    await assertNotSymbolicLink(backupPath, 'Refusing to use symlinked backup file');
+    try {
+        await fs_1.promises.access(backupPath);
+        return;
+    }
+    catch {
+        // continue if no backup exists yet
+    }
+    if (await isRulerGeneratedFile(filePath)) {
+        return;
+    }
     try {
-        await fs_1.promises.access(filePath);
-        await fs_1.promises.copyFile(filePath, `${filePath}.bak`);
+        await fs_1.promises.copyFile(filePath, backupPath);
     }
     catch {
         // ignore if file does not exist
@@ -272,23 +412,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);
                     }
                 }
             }

package/dist/core/GitignoreUtils.d.ts

@@ -0,0 +1,25 @@
+export interface RulerBlockRange {
+    start: number;
+    end: number;
+}
+export interface RemoveRulerBlocksResult {
+    content: string;
+    removed: boolean;
+}
+/**
+ * Updates an ignore 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
+ * @param paths Array of file paths to add to the ignore file (can be absolute or relative)
+ * @param ignoreFile Relative path to the ignore file from project root (defaults to .gitignore)
+ */
+export declare function updateGitignore(projectRoot: string, paths: string[], ignoreFile?: string): Promise<void>;
+/**
+ * Resolves ignore files Ruler manages. Linked worktrees store `.git` as a
+ * file containing a `gitdir:` pointer, so `.git/info/exclude` must be resolved
+ * through that pointer.
+ */
+export declare function resolveIgnoreFilePath(projectRoot: string, ignoreFile: string): Promise<string>;
+export declare function findCompleteRulerBlocks(lines: string[]): RulerBlockRange[];
+export declare function removeCompleteRulerBlocks(content: string): RemoveRulerBlocksResult;