@intellectronica/ruler 0.3.40 → 0.3.42

package/dist/core/apply-engine.js

@@ -52,6 +52,7 @@ const propagateOpenHandsMcp_1 = require("../mcp/propagateOpenHandsMcp");
 const propagateOpenCodeMcp_1 = require("../mcp/propagateOpenCodeMcp");
 const agent_utils_1 = require("../agents/agent-utils");
 const capabilities_1 = require("../mcp/capabilities");
+const path_utils_1 = require("./path-utils");
 const constants_1 = require("../constants");
 async function loadNestedConfigurations(projectRoot, configPath, localOnly, resolvedNested) {
     const { dirs: rulerDirs } = await findRulerDirectories(projectRoot, localOnly, true);
@@ -59,11 +60,11 @@ async function loadNestedConfigurations(projectRoot, configPath, localOnly, reso
     // Load config first so we know whether `.ruler/agents/` should be included
     // in the rule concatenation for each directory.
     for (const rulerDir of rulerDirs) {
-        const config = await loadConfigForRulerDir(rulerDir, configPath, resolvedNested);
+        const config = await loadConfigForRulerDir(rulerDir, configPath, resolvedNested, localOnly);
         const files = await FileSystemUtils.readMarkdownFiles(rulerDir, {
             includeAgents: shouldIncludeAgentsInRules(config),
         });
-        results.push(await createHierarchicalConfiguration(rulerDir, files, config, configPath));
+        results.push(await createHierarchicalConfiguration(rulerDir, files, config, configPath, localOnly));
     }
     return results;
 }
@@ -74,7 +75,7 @@ async function loadNestedConfigurations(projectRoot, configPath, localOnly, reso
 function shouldIncludeAgentsInRules(config) {
     return config.subagents?.include_in_rules === true;
 }
-async function createHierarchicalConfiguration(rulerDir, files, config, cliConfigPath) {
+async function createHierarchicalConfiguration(rulerDir, files, config, cliConfigPath, localOnly) {
     await warnAboutLegacyMcpJson(rulerDir);
     const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(rulerDir));
     const directoryRoot = path.dirname(rulerDir);
@@ -91,6 +92,7 @@ async function createHierarchicalConfiguration(rulerDir, files, config, cliConfi
     const unifiedConfig = await loadUnifiedConfig({
         projectRoot: directoryRoot,
         configPath: configPathToUse,
+        checkGlobal: !localOnly,
     });
     let rulerMcpJson = null;
     if (unifiedConfig.mcp && Object.keys(unifiedConfig.mcp.servers).length > 0) {
@@ -105,7 +107,7 @@ async function createHierarchicalConfiguration(rulerDir, files, config, cliConfi
         rulerMcpJson,
     };
 }
-async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested) {
+async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested, localOnly) {
     const directoryRoot = path.dirname(rulerDir);
     const localConfigPath = path.join(rulerDir, 'ruler.toml');
     let hasLocalConfig = false;
@@ -119,6 +121,7 @@ async function loadConfigForRulerDir(rulerDir, cliConfigPath, resolvedNested) {
     const loaded = await (0, ConfigLoader_1.loadConfig)({
         projectRoot: directoryRoot,
         configPath: hasLocalConfig ? localConfigPath : cliConfigPath,
+        checkGlobal: !localOnly,
     });
     const cloned = cloneLoadedConfig(loaded);
     if (resolvedNested) {
@@ -144,6 +147,7 @@ function cloneLoadedConfig(config) {
         cliAgents: config.cliAgents ? [...config.cliAgents] : undefined,
         mcp: config.mcp ? { ...config.mcp } : undefined,
         gitignore: config.gitignore ? { ...config.gitignore } : undefined,
+        backup: config.backup ? { ...config.backup } : undefined,
         skills: config.skills ? { ...config.skills } : undefined,
         subagents: config.subagents ? { ...config.subagents } : undefined,
         nested: config.nested,
@@ -156,18 +160,10 @@ function cloneLoadedConfig(config) {
 async function findRulerDirectories(projectRoot, localOnly, hierarchical) {
     if (hierarchical) {
         const dirs = await FileSystemUtils.findAllRulerDirs(projectRoot);
-        const allDirs = [...dirs];
-        // Add global config if not local-only
-        if (!localOnly) {
-            const globalDir = await FileSystemUtils.findGlobalRulerDir();
-            if (globalDir) {
-                allDirs.push(globalDir);
-            }
-        }
-        if (allDirs.length === 0) {
+        if (dirs.length === 0) {
             throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
         }
-        return { dirs: allDirs, primaryDir: allDirs[0] };
+        return { dirs, primaryDir: dirs[0] };
     }
     else {
         const dir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
@@ -202,6 +198,7 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
     const config = await (0, ConfigLoader_1.loadConfig)({
         projectRoot,
         configPath,
+        checkGlobal: !localOnly,
     });
     // Read rule files. `.ruler/agents/` is only included when
     // `[agents] include_in_rules = true`.
@@ -212,7 +209,11 @@ async function loadSingleConfiguration(projectRoot, configPath, localOnly) {
     const concatenatedRules = (0, RuleProcessor_1.concatenateRules)(files, path.dirname(primaryDir));
     // Load unified config to get merged MCP configuration
     const { loadUnifiedConfig } = await Promise.resolve().then(() => __importStar(require('./UnifiedConfigLoader')));
-    const unifiedConfig = await loadUnifiedConfig({ projectRoot, configPath });
+    const unifiedConfig = await loadUnifiedConfig({
+        projectRoot,
+        configPath,
+        checkGlobal: !localOnly,
+    });
     // Synthesize rulerMcpJson from unified MCP bundle for backward compatibility
     let rulerMcpJson = null;
     if (unifiedConfig.mcp && Object.keys(unifiedConfig.mcp.servers).length > 0) {
@@ -306,22 +307,27 @@ async function applyConfigurationsToAgents(agents, concatenatedRules, rulerMcpJs
                     agentsMdWritten = true;
                 }
             }
-            let finalAgentConfig = agentConfig;
-            if (agent.getIdentifier() === 'augmentcode' && agentRulerMcpJson) {
-                const resolvedStrategy = cliMcpStrategy ??
-                    agentConfig?.mcp?.strategy ??
-                    config.mcp?.strategy ??
-                    'merge';
-                finalAgentConfig = {
-                    ...agentConfig,
-                    mcp: {
-                        ...agentConfig?.mcp,
-                        strategy: resolvedStrategy,
-                    },
-                };
-            }
+            const effectiveMcpEnabled = cliMcpEnabled &&
+                (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
+            const effectiveMcpStrategy = cliMcpStrategy ??
+                agentConfig?.mcp?.strategy ??
+                config.mcp?.strategy ??
+                'merge';
+            const finalAgentConfig = {
+                ...agentConfig,
+                mcp: {
+                    ...agentConfig?.mcp,
+                    enabled: effectiveMcpEnabled,
+                    strategy: effectiveMcpStrategy,
+                },
+            };
+            const mcpForAgentApply = shouldUseEngineManagedMcp(agent)
+                ? null
+                : effectiveMcpEnabled
+                    ? agentRulerMcpJson
+                    : null;
             if (!skipApplyForThisAgent) {
-                await agent.applyRulerConfig(concatenatedRules, projectRoot, agentRulerMcpJson, finalAgentConfig, backup);
+                await agent.applyRulerConfig(concatenatedRules, projectRoot, mcpForAgentApply, finalAgentConfig, backup);
             }
         }
         // Handle MCP configuration
@@ -334,7 +340,7 @@ async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson,
         (0, constants_1.logVerbose)(`Agent ${agent.getName()} does not support MCP - skipping MCP configuration`, verbose);
         return;
     }
-    const dest = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+    const dest = await resolveMcpDestination(agent, agentConfig, projectRoot);
     const mcpEnabledForAgent = cliMcpEnabled && (agentConfig?.mcp?.enabled ?? config.mcp?.enabled ?? true);
     if (!dest || !mcpEnabledForAgent) {
         return;
@@ -349,8 +355,17 @@ async function handleMcpConfiguration(agent, agentConfig, config, rulerMcpJson,
     await updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup);
     await applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup);
 }
+function shouldUseEngineManagedMcp(agent) {
+    return (agent.getIdentifier() === 'codex' || agent.getIdentifier() === 'opencode');
+}
+async function resolveMcpDestination(agent, agentConfig, projectRoot) {
+    if (agentConfig?.outputPathConfig) {
+        return path.resolve(projectRoot, agentConfig.outputPathConfig);
+    }
+    return await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+}
 async function updateGitignoreForMcpFile(dest, projectRoot, generatedPaths, backup = true) {
-    if (dest.startsWith(projectRoot)) {
+    if ((0, path_utils_1.isPathInsideOrEqual)(projectRoot, dest)) {
         const relativeDest = path.relative(projectRoot, dest);
         generatedPaths.push(relativeDest);
         if (backup) {
@@ -391,16 +406,16 @@ function sanitizeMcpTimeoutsForAgent(agent, mcpJson, dryRun) {
 }
 async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig, config, projectRoot, cliMcpStrategy, dryRun, verbose, backup = true) {
     // Prevent writing MCP configs outside the project root (e.g., legacy home-directory targets)
-    if (!dest.startsWith(projectRoot)) {
+    if (!(0, path_utils_1.isPathInsideOrEqual)(projectRoot, dest)) {
         (0, constants_1.logVerbose)(`Skipping MCP config for ${agent.getName()} because target path is outside project: ${dest}`, verbose);
         return;
     }
     const agentMcpJson = sanitizeMcpTimeoutsForAgent(agent, filteredMcpJson, dryRun);
     if (agent.getIdentifier() === 'openhands') {
-        return await applyOpenHandsMcpConfiguration(agentMcpJson, dest, dryRun, verbose, backup);
+        return await applyOpenHandsMcpConfiguration(agentMcpJson, dest, cliMcpStrategy ?? agentConfig?.mcp?.strategy ?? config.mcp?.strategy, dryRun, verbose, backup);
     }
     if (agent.getIdentifier() === 'opencode') {
-        return await applyOpenCodeMcpConfiguration(agentMcpJson, dest, dryRun, verbose, backup);
+        return await applyOpenCodeMcpConfiguration(agentMcpJson, dest, cliMcpStrategy ?? agentConfig?.mcp?.strategy ?? config.mcp?.strategy, dryRun, verbose, backup);
     }
     // Agents that handle MCP configuration internally should not have external MCP handling
     if (agent.getIdentifier() === 'zed' ||
@@ -412,20 +427,20 @@ async function applyMcpConfiguration(agent, filteredMcpJson, dest, agentConfig,
     }
     return await applyStandardMcpConfiguration(agent, agentMcpJson, dest, agentConfig, config, cliMcpStrategy, dryRun, verbose, backup);
 }
-async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+async function applyOpenHandsMcpConfiguration(filteredMcpJson, dest, strategy, dryRun, verbose, backup = true) {
     if (dryRun) {
         (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating TOML file: ${dest}`, verbose);
     }
     else {
-        await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest, backup);
+        await (0, propagateOpenHandsMcp_1.propagateMcpToOpenHands)(filteredMcpJson, dest, backup, strategy);
     }
 }
-async function applyOpenCodeMcpConfiguration(filteredMcpJson, dest, dryRun, verbose, backup = true) {
+async function applyOpenCodeMcpConfiguration(filteredMcpJson, dest, strategy, dryRun, verbose, backup = true) {
     if (dryRun) {
         (0, constants_1.logVerbose)(`DRY RUN: Would apply MCP config by updating OpenCode config file: ${dest}`, verbose);
     }
     else {
-        await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest, backup);
+        await (0, propagateOpenCodeMcp_1.propagateMcpToOpenCode)(filteredMcpJson, dest, backup, strategy);
     }
 }
 /**
@@ -550,17 +565,9 @@ async function applyStandardMcpConfiguration(agent, filteredMcpJson, dest, agent
         }
         const CODEX_AGENT_ID = 'codex';
         const isCodexToml = agent.getIdentifier() === CODEX_AGENT_ID && dest.endsWith('.toml');
-        let existing = await (0, mcp_1.readNativeMcp)(dest);
-        if (isCodexToml) {
-            try {
-                const tomlContent = await fs_1.promises.readFile(dest, 'utf8');
-                existing = (0, toml_1.parse)(tomlContent);
-            }
-            catch (error) {
-                (0, constants_1.logVerbose)(`Failed to read Codex MCP TOML at ${dest}: ${error.message}`, verbose);
-                // ignore missing or invalid TOML, fall back to previously read value
-            }
-        }
+        const existing = isCodexToml
+            ? await (0, mcp_1.readNativeMcpToml)(dest, (text) => (0, toml_1.parse)(text))
+            : await (0, mcp_1.readNativeMcp)(dest);
         let merged = (0, merge_1.mergeMcp)(existing, mcpToMerge, strategy, serverKey);
         if (isCodexToml) {
             const { [serverKey]: servers, ...rest } = merged;

package/dist/core/config-utils.d.ts

@@ -0,0 +1,14 @@
+import { IAgent, IAgentConfig } from '../agents/IAgent';
+/**
+ * Maps raw agent configuration keys to their corresponding agent identifiers.
+ *
+ * This function normalizes configuration keys by matching them against agent identifiers
+ * and display names. It performs both exact matching (case-insensitive) with agent
+ * identifiers and substring matching (case-insensitive) with agent display names
+ * for backwards compatibility.
+ *
+ * @param raw Raw agent configurations with user-provided keys
+ * @param agents Array of all available agents
+ * @returns Record with agent identifiers as keys and their configurations as values
+ */
+export declare function mapRawAgentConfigs(raw: Record<string, IAgentConfig>, agents: IAgent[]): Record<string, IAgentConfig>;

package/dist/core/config-utils.js

@@ -17,11 +17,17 @@ function mapRawAgentConfigs(raw, agents) {
     const mappedConfigs = {};
     for (const [key, cfg] of Object.entries(raw)) {
         const lowerKey = key.toLowerCase();
+        const exactMatches = agents.filter((agent) => agent.getIdentifier().toLowerCase() === lowerKey);
+        // Exact identifier matches take precedence over fuzzy display-name matching.
+        if (exactMatches.length > 0) {
+            for (const agent of exactMatches) {
+                mappedConfigs[agent.getIdentifier()] = cfg;
+            }
+            continue;
+        }
         for (const agent of agents) {
             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)) {
+            if (agent.getName().toLowerCase().includes(lowerKey)) {
                 mappedConfigs[identifier] = cfg;
             }
         }

package/dist/core/hash.d.ts

@@ -0,0 +1,2 @@
+export declare function sha256(data: string): string;
+export declare function stableJson(value: unknown): string;

package/dist/core/path-utils.d.ts

@@ -0,0 +1 @@
+export declare function isPathInsideOrEqual(parentPath: string, targetPath: string): boolean;

package/dist/core/path-utils.js

@@ -0,0 +1,42 @@
+"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.isPathInsideOrEqual = isPathInsideOrEqual;
+const path = __importStar(require("path"));
+function isPathInsideOrEqual(parentPath, targetPath) {
+    const relative = path.relative(path.resolve(parentPath), path.resolve(targetPath));
+    return (relative === '' ||
+        (!relative.startsWith('..') && !path.isAbsolute(relative)));
+}

package/dist/core/revert-engine.d.ts

@@ -0,0 +1,36 @@
+import { IAgent } from '../agents/IAgent';
+import { IAgentConfig } from './ConfigLoader';
+/**
+ * Result of reverting an agent configuration
+ */
+export interface RevertAgentResult {
+    restored: number;
+    removed: number;
+    backupsRemoved: number;
+}
+/**
+ * Result of cleaning up auxiliary files
+ */
+export interface CleanUpResult {
+    additionalFilesRemoved: number;
+    directoriesRemoved: number;
+}
+/**
+ * Reverts configuration for a single agent.
+ * @param agent The agent to revert
+ * @param projectRoot Root directory of the project
+ * @param agentConfig Agent-specific configuration
+ * @param keepBackups Whether to keep backup files
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @returns Promise resolving to revert statistics
+ */
+export declare function revertAgentConfiguration(agent: IAgent, projectRoot: string, agentConfig: IAgentConfig | undefined, keepBackups: boolean, verbose: boolean, dryRun: boolean): Promise<RevertAgentResult>;
+/**
+ * Cleans up auxiliary files and directories.
+ * @param projectRoot Root directory of the project
+ * @param verbose Whether to enable verbose logging
+ * @param dryRun Whether to perform a dry run
+ * @returns Promise resolving to cleanup statistics
+ */
+export declare function cleanUpAuxiliaryFiles(projectRoot: string, verbose: boolean, dryRun: boolean): Promise<CleanUpResult>;

package/dist/core/revert-engine.js

@@ -40,7 +40,12 @@ const fs_1 = require("fs");
 const agent_utils_1 = require("../agents/agent-utils");
 const mcp_1 = require("../paths/mcp");
 const constants_1 = require("../constants");
+const GitignoreUtils_1 = require("./GitignoreUtils");
 const settings_1 = require("../vscode/settings");
+const path_utils_1 = require("./path-utils");
+const RULER_START_MARKER = '# START Ruler Generated Files';
+const RULER_END_MARKER = '# END Ruler Generated Files';
+const RULER_GENERATED_MARKER = '<!-- Generated by Ruler -->';
 /**
  * Checks if a file exists.
  */
@@ -53,6 +58,54 @@ async function fileExists(filePath) {
         return false;
     }
 }
+async function ignoreFileHasRulerGeneratedPath(ignoreFilePath, generatedPath) {
+    try {
+        const content = await fs_1.promises.readFile(ignoreFilePath, 'utf8');
+        const lines = content.split('\n');
+        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 === generatedPath || trimmed === generatedPath.slice(1))) {
+                return true;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+async function hasRulerGeneratedProvenance(filePath, projectRoot) {
+    try {
+        const content = await fs_1.promises.readFile(filePath, 'utf8');
+        if (content.startsWith(RULER_GENERATED_MARKER)) {
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    const relativePath = `/${path.relative(projectRoot, filePath).replace(/\\/g, '/')}`;
+    const ignoreFiles = [
+        await (0, GitignoreUtils_1.resolveIgnoreFilePath)(projectRoot, '.gitignore'),
+        await (0, GitignoreUtils_1.resolveIgnoreFilePath)(projectRoot, '.git/info/exclude'),
+    ];
+    for (const ignoreFile of ignoreFiles) {
+        if (await ignoreFileHasRulerGeneratedPath(ignoreFile, relativePath)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Restores a file from its backup if the backup exists.
  */
@@ -76,7 +129,7 @@ async function restoreFromBackup(filePath, verbose, dryRun) {
 /**
  * Removes a file if it exists and has no backup (meaning it was generated by ruler).
  */
-async function removeGeneratedFile(filePath, verbose, dryRun) {
+async function removeGeneratedFile(filePath, verbose, dryRun, projectRoot) {
     const fileExistsFlag = await fileExists(filePath);
     const backupExists = await fileExists(`${filePath}.bak`);
     if (!fileExistsFlag) {
@@ -87,6 +140,11 @@ async function removeGeneratedFile(filePath, verbose, dryRun) {
         (0, constants_1.logVerbose)(`File has backup, skipping removal: ${filePath}`, verbose);
         return false;
     }
+    if (projectRoot &&
+        !(await hasRulerGeneratedProvenance(filePath, projectRoot))) {
+        (0, constants_1.logVerbose)(`Preserving file without backup or Ruler provenance: ${filePath}`, verbose);
+        return false;
+    }
     const prefix = (0, constants_1.actionPrefix)(dryRun);
     if (dryRun) {
         (0, constants_1.logVerbose)(`${prefix} Would remove generated file: ${filePath}`, verbose);
@@ -267,6 +325,9 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
                     filesRemoved++;
                 }
             }
+            else if (!(await hasRulerGeneratedProvenance(fullPath, projectRoot))) {
+                (0, constants_1.logVerbose)(`Preserving additional file without backup or Ruler provenance: ${fullPath}`, verbose);
+            }
             else {
                 if (dryRun) {
                     (0, constants_1.logVerbose)(`${prefix} Would remove additional file: ${fullPath}`, verbose);
@@ -288,7 +349,7 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
         const restored = await restoreFromBackup(settingsPath, verbose, dryRun);
         if (restored) {
             filesRemoved++;
-            (0, constants_1.logVerbose)(`${constants_1.actionPrefix} Restored VSCode settings from backup`, verbose);
+            (0, constants_1.logVerbose)(`${prefix} Restored VSCode settings from backup`, verbose);
         }
     }
     else if (await fileExists(settingsPath)) {
@@ -299,10 +360,10 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
                     delete settings['augment.advanced'];
                     const remainingKeys = Object.keys(settings);
                     if (remainingKeys.length === 0) {
-                        (0, constants_1.logVerbose)(`${constants_1.actionPrefix} Would remove empty VSCode settings file`, verbose);
+                        (0, constants_1.logVerbose)(`${prefix} Would remove empty VSCode settings file`, verbose);
                     }
                     else {
-                        (0, constants_1.logVerbose)(`${constants_1.actionPrefix} Would remove augment.advanced section from ${settingsPath}`, verbose);
+                        (0, constants_1.logVerbose)(`${prefix} Would remove augment.advanced section from ${settingsPath}`, verbose);
                     }
                     filesRemoved++;
                 }
@@ -314,11 +375,11 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
                     const remainingKeys = Object.keys(settings);
                     if (remainingKeys.length === 0) {
                         await fs_1.promises.unlink(settingsPath);
-                        (0, constants_1.logVerbose)(`${constants_1.actionPrefix} Removed empty VSCode settings file`, verbose);
+                        (0, constants_1.logVerbose)(`${prefix} Removed empty VSCode settings file`, verbose);
                     }
                     else {
                         await (0, settings_1.writeVSCodeSettings)(settingsPath, settings);
-                        (0, constants_1.logVerbose)(`${constants_1.actionPrefix} Removed augment.advanced section from VSCode settings`, verbose);
+                        (0, constants_1.logVerbose)(`${prefix} Removed augment.advanced section from VSCode settings`, verbose);
                     }
                     filesRemoved++;
                 }
@@ -363,7 +424,7 @@ async function revertAgentConfiguration(agent, projectRoot, agentConfig, keepBac
             }
         }
         else {
-            const removed = await removeGeneratedFile(outputPath, verbose, dryRun);
+            const removed = await removeGeneratedFile(outputPath, verbose, dryRun, projectRoot);
             if (removed) {
                 result.removed++;
             }
@@ -371,7 +432,7 @@ async function revertAgentConfiguration(agent, projectRoot, agentConfig, keepBac
     }
     // Handle MCP files
     const mcpPath = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
-    if (mcpPath && mcpPath.startsWith(projectRoot)) {
+    if (mcpPath && (0, path_utils_1.isPathInsideOrEqual)(projectRoot, mcpPath)) {
         if (agent.getName() === 'AugmentCode' &&
             mcpPath.endsWith('.vscode/settings.json')) {
             (0, constants_1.logVerbose)(`Skipping MCP handling for AugmentCode settings.json - handled separately`, verbose);
@@ -388,7 +449,7 @@ async function revertAgentConfiguration(agent, projectRoot, agentConfig, keepBac
                 }
             }
             else {
-                const mcpRemoved = await removeGeneratedFile(mcpPath, verbose, dryRun);
+                const mcpRemoved = await removeGeneratedFile(mcpPath, verbose, dryRun, projectRoot);
                 if (mcpRemoved) {
                     result.removed++;
                 }

package/dist/lib.d.ts

@@ -0,0 +1,13 @@
+import { allAgents } from './agents';
+import { McpStrategy } from './types';
+export { allAgents };
+/**
+ * Applies ruler configurations for all supported AI agents.
+ * @param projectRoot Root directory of the project
+ */
+/**
+ * Applies ruler configurations for selected AI agents.
+ * @param projectRoot Root directory of the project
+ * @param includedAgents Optional list of agent name filters (case-insensitive substrings)
+ */
+export declare function applyAllAgentConfigs(projectRoot: string, includedAgents?: string[], configPath?: string, cliMcpEnabled?: boolean, cliMcpStrategy?: McpStrategy, cliGitignoreEnabled?: boolean, verbose?: boolean, dryRun?: boolean, localOnly?: boolean, nested?: boolean, backup?: boolean, skillsEnabled?: boolean, cliGitignoreLocal?: boolean, subagentsEnabled?: boolean): Promise<void>;

package/dist/lib.js

@@ -53,6 +53,17 @@ function resolveSkillsEnabled(cliFlag, configSetting) {
             ? configSetting
             : true; // default to enabled
 }
+/**
+ * Resolves backup enabled state based on precedence:
+ * CLI flag > ruler.toml > default (enabled).
+ */
+function resolveBackupEnabled(cliFlag, configSetting) {
+    return cliFlag !== undefined
+        ? cliFlag
+        : configSetting !== undefined
+            ? configSetting
+            : true; // default to enabled
+}
 /**
  * Resolves subagents enabled state based on precedence:
  * CLI flag > ruler.toml > default (disabled).
@@ -70,6 +81,9 @@ function resolveSubagentsEnabled(cliFlag, configSetting) {
             ? configSetting
             : false; // default to disabled — see spec: subagents must opt in
 }
+function resolveSubagentsCleanupOrphaned(configSetting) {
+    return configSetting === true;
+}
 /**
  * Applies ruler configurations for all supported AI agents.
  * @param projectRoot Root directory of the project
@@ -79,7 +93,7 @@ function resolveSubagentsEnabled(cliFlag, configSetting) {
  * @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, localOnly = false, nested = false, backup = true, skillsEnabled, cliGitignoreLocal, subagentsEnabled) {
+async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cliMcpEnabled = true, cliMcpStrategy, cliGitignoreEnabled, verbose = false, dryRun = false, localOnly = false, nested = false, backup, skillsEnabled, cliGitignoreLocal, subagentsEnabled) {
     // Load configuration and rules
     (0, constants_1.logVerbose)(`Loading configuration from project root: ${projectRoot}`, verbose);
     if (configPath) {
@@ -119,15 +133,17 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         }
         // Propagate subagents (mirrors skills handling for nested mode).
         const subagentsEnabledResolved = resolveSubagentsEnabled(subagentsEnabled, rootConfig.subagents?.enabled);
+        const subagentsCleanupOrphaned = resolveSubagentsCleanupOrphaned(rootConfig.subagents?.cleanup_orphaned);
+        const backupEnabledResolved = resolveBackupEnabled(backup, rootConfig.backup?.enabled);
         {
             const { propagateSubagents } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
             for (const configEntry of hierarchicalConfigs) {
                 const nestedRoot = path.dirname(configEntry.rulerDir);
                 (0, constants_1.logVerbose)(`Propagating subagents for nested directory: ${nestedRoot}`, verbose);
-                await propagateSubagents(nestedRoot, selectedAgents, subagentsEnabledResolved, verbose, dryRun);
+                await propagateSubagents(nestedRoot, selectedAgents, subagentsEnabledResolved, subagentsCleanupOrphaned, verbose, dryRun);
             }
         }
-        generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+        generatedPaths = await (0, apply_engine_1.processHierarchicalConfigurations)(selectedAgents, hierarchicalConfigs, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backupEnabledResolved);
     }
     else {
         const singleConfig = await (0, apply_engine_1.loadSingleConfiguration)(projectRoot, configPath, localOnly);
@@ -146,11 +162,13 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         }
         // Propagate subagents (mirrors skills handling).
         const subagentsEnabledResolvedSingle = resolveSubagentsEnabled(subagentsEnabled, singleConfig.config.subagents?.enabled);
+        const subagentsCleanupOrphanedSingle = resolveSubagentsCleanupOrphaned(singleConfig.config.subagents?.cleanup_orphaned);
+        const backupEnabledResolvedSingle = resolveBackupEnabled(backup, singleConfig.config.backup?.enabled);
         {
             const { propagateSubagents } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
-            await propagateSubagents(projectRoot, selectedAgents, subagentsEnabledResolvedSingle, verbose, dryRun);
+            await propagateSubagents(projectRoot, selectedAgents, subagentsEnabledResolvedSingle, subagentsCleanupOrphanedSingle, verbose, dryRun);
         }
-        generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backup);
+        generatedPaths = await (0, apply_engine_1.processSingleConfiguration)(selectedAgents, singleConfig, projectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backupEnabledResolvedSingle);
     }
     // Add skills-generated paths to gitignore if skills are enabled
     let allGeneratedPaths = generatedPaths;

package/dist/mcp/capabilities.d.ts

@@ -0,0 +1,20 @@
+import { IAgent } from '../agents/IAgent';
+/**
+ * MCP capability types for agents
+ */
+export interface McpCapabilities {
+    supportsStdio: boolean;
+    supportsRemote: boolean;
+}
+/**
+ * Derives MCP capabilities for an agent
+ */
+export declare function getAgentMcpCapabilities(agent: IAgent): McpCapabilities;
+/**
+ * Checks if an agent supports any MCP functionality
+ */
+export declare function agentSupportsMcp(agent: IAgent): boolean;
+/**
+ * Filters MCP configuration based on agent capabilities
+ */
+export declare function filterMcpConfigForAgent(mcpConfig: Record<string, unknown>, agent: IAgent): Record<string, unknown> | null;

package/dist/mcp/merge.d.ts

@@ -0,0 +1,10 @@
+import { McpStrategy } from '../types';
+/**
+ * Merge native and incoming MCP server configurations according to strategy.
+ * @param base Existing native MCP config object.
+ * @param incoming Ruler MCP config object.
+ * @param strategy Merge strategy: 'merge' to union servers, 'overwrite' to replace.
+ * @param serverKey The key to use for servers in the output (e.g., 'servers' for Copilot, 'mcpServers' for others).
+ * @returns Merged MCP config object.
+ */
+export declare function mergeMcp(base: Record<string, unknown>, incoming: Record<string, unknown>, strategy: McpStrategy, serverKey: string): Record<string, unknown>;