@intellectronica/ruler 0.3.41 → 0.3.43

package/dist/core/revert-engine.js

@@ -35,12 +35,29 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.revertAgentConfiguration = revertAgentConfiguration;
 exports.cleanUpAuxiliaryFiles = cleanUpAuxiliaryFiles;
+exports.cleanUpAgentDirectories = cleanUpAgentDirectories;
 const path = __importStar(require("path"));
 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 FileSystemUtils_1 = require("./FileSystemUtils");
+const RULER_START_MARKER = '# START Ruler Generated Files';
+const RULER_END_MARKER = '# END Ruler Generated Files';
+const RULER_GENERATED_MARKER = '<!-- Generated by Ruler -->';
+const RULER_SOURCE_MARKER_PREFIXES = [
+    '<!-- Source: .ruler/',
+    '<!-- Source: ruler/',
+];
+async function resolveMcpPathForRevert(agent, projectRoot, agentConfig) {
+    if (agentConfig?.outputPathConfig) {
+        return path.resolve(projectRoot, agentConfig.outputPathConfig);
+    }
+    return await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+}
 /**
  * Checks if a file exists.
  */
@@ -53,10 +70,62 @@ 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;
+        }
+        const trimmedContent = content.trimStart();
+        if (RULER_SOURCE_MARKER_PREFIXES.some((prefix) => trimmedContent.startsWith(prefix))) {
+            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.
  */
-async function restoreFromBackup(filePath, verbose, dryRun) {
+async function restoreFromBackup(filePath, verbose, dryRun, projectRoot) {
     const backupPath = `${filePath}.bak`;
     const backupExists = await fileExists(backupPath);
     if (!backupExists) {
@@ -68,6 +137,10 @@ async function restoreFromBackup(filePath, verbose, dryRun) {
         (0, constants_1.logVerbose)(`${prefix} Would restore: ${filePath} from backup`, verbose);
     }
     else {
+        if (projectRoot) {
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(filePath, projectRoot, 'Refusing to restore backup through symlinked output path');
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(backupPath, projectRoot, 'Refusing to restore from backup through symlinked backup path');
+        }
         await fs_1.promises.copyFile(backupPath, filePath);
         (0, constants_1.logVerbose)(`${prefix} Restored: ${filePath} from backup`, verbose);
     }
@@ -76,7 +149,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,11 +160,19 @@ 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);
     }
     else {
+        if (projectRoot) {
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(filePath, projectRoot, 'Refusing to remove generated file through symlinked path');
+        }
         await fs_1.promises.unlink(filePath);
         (0, constants_1.logVerbose)(`${prefix} Removed generated file: ${filePath}`, verbose);
     }
@@ -100,7 +181,7 @@ async function removeGeneratedFile(filePath, verbose, dryRun) {
 /**
  * Removes backup files.
  */
-async function removeBackupFile(filePath, verbose, dryRun) {
+async function removeBackupFile(filePath, verbose, dryRun, projectRoot) {
     const backupPath = `${filePath}.bak`;
     const backupExists = await fileExists(backupPath);
     if (!backupExists) {
@@ -111,6 +192,9 @@ async function removeBackupFile(filePath, verbose, dryRun) {
         (0, constants_1.logVerbose)(`${prefix} Would remove backup file: ${backupPath}`, verbose);
     }
     else {
+        if (projectRoot) {
+            await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(backupPath, projectRoot, 'Refusing to remove backup file through symlinked path');
+        }
         await fs_1.promises.unlink(backupPath);
         (0, constants_1.logVerbose)(`${prefix} Removed backup file: ${backupPath}`, verbose);
     }
@@ -262,11 +346,14 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
             }
             const backupExists = await fileExists(`${fullPath}.bak`);
             if (backupExists) {
-                const restored = await restoreFromBackup(fullPath, verbose, dryRun);
+                const restored = await restoreFromBackup(fullPath, verbose, dryRun, projectRoot);
                 if (restored) {
                     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);
@@ -285,10 +372,10 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
     const settingsPath = (0, settings_1.getVSCodeSettingsPath)(projectRoot);
     const backupPath = `${settingsPath}.bak`;
     if (await fileExists(backupPath)) {
-        const restored = await restoreFromBackup(settingsPath, verbose, dryRun);
+        const restored = await restoreFromBackup(settingsPath, verbose, dryRun, projectRoot);
         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 +386,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++;
                 }
@@ -313,12 +400,13 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
                     delete settings['augment.advanced'];
                     const remainingKeys = Object.keys(settings);
                     if (remainingKeys.length === 0) {
+                        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(settingsPath, projectRoot, 'Refusing to remove VSCode settings through symlinked path');
                         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);
+                        await (0, settings_1.writeVSCodeSettings)(settingsPath, settings, projectRoot);
+                        (0, constants_1.logVerbose)(`${prefix} Removed augment.advanced section from VSCode settings`, verbose);
                     }
                     filesRemoved++;
                 }
@@ -338,7 +426,7 @@ async function removeAdditionalAgentFiles(projectRoot, verbose, dryRun) {
  * @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 keepBackups Whether restored backup files should be preserved
  * @param verbose Whether to enable verbose logging
  * @param dryRun Whether to perform a dry run
  * @returns Promise resolving to revert statistics
@@ -350,49 +438,44 @@ async function revertAgentConfiguration(agent, projectRoot, agentConfig, keepBac
         backupsRemoved: 0,
     };
     const outputPaths = (0, agent_utils_1.getAgentOutputPaths)(agent, projectRoot, agentConfig);
+    const processedPaths = new Set();
     (0, constants_1.logVerbose)(`Agent ${agent.getName()} output paths: ${outputPaths.join(', ')}`, verbose);
-    for (const outputPath of outputPaths) {
-        const restored = await restoreFromBackup(outputPath, verbose, dryRun);
+    const processPath = async (outputPath) => {
+        const resolvedPath = path.resolve(projectRoot, outputPath);
+        if (processedPaths.has(resolvedPath)) {
+            (0, constants_1.logVerbose)(`Skipping already processed path: ${outputPath}`, verbose);
+            return;
+        }
+        processedPaths.add(resolvedPath);
+        const restored = await restoreFromBackup(outputPath, verbose, dryRun, projectRoot);
         if (restored) {
             result.restored++;
             if (!keepBackups) {
-                const backupRemoved = await removeBackupFile(outputPath, verbose, dryRun);
+                const backupRemoved = await removeBackupFile(outputPath, verbose, dryRun, projectRoot);
                 if (backupRemoved) {
                     result.backupsRemoved++;
                 }
             }
         }
         else {
-            const removed = await removeGeneratedFile(outputPath, verbose, dryRun);
+            const removed = await removeGeneratedFile(outputPath, verbose, dryRun, projectRoot);
             if (removed) {
                 result.removed++;
             }
         }
+    };
+    for (const outputPath of outputPaths) {
+        await processPath(outputPath);
     }
     // Handle MCP files
-    const mcpPath = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
-    if (mcpPath && mcpPath.startsWith(projectRoot)) {
+    const mcpPath = await resolveMcpPathForRevert(agent, projectRoot, agentConfig);
+    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);
         }
         else {
-            const mcpRestored = await restoreFromBackup(mcpPath, verbose, dryRun);
-            if (mcpRestored) {
-                result.restored++;
-                if (!keepBackups) {
-                    const mcpBackupRemoved = await removeBackupFile(mcpPath, verbose, dryRun);
-                    if (mcpBackupRemoved) {
-                        result.backupsRemoved++;
-                    }
-                }
-            }
-            else {
-                const mcpRemoved = await removeGeneratedFile(mcpPath, verbose, dryRun);
-                if (mcpRemoved) {
-                    result.removed++;
-                }
-            }
+            await processPath(mcpPath);
         }
     }
     return result;
@@ -412,3 +495,28 @@ async function cleanUpAuxiliaryFiles(projectRoot, verbose, dryRun) {
         directoriesRemoved,
     };
 }
+async function cleanUpAgentDirectories(agent, projectRoot, agentConfig, verbose, dryRun) {
+    const candidateFiles = (0, agent_utils_1.getAgentOutputPaths)(agent, projectRoot, agentConfig);
+    const mcpPath = await (0, mcp_1.getNativeMcpPath)(agent.getName(), projectRoot);
+    if (mcpPath && (0, path_utils_1.isPathInsideOrEqual)(projectRoot, mcpPath)) {
+        candidateFiles.push(mcpPath);
+    }
+    const candidateDirs = [
+        ...new Set(candidateFiles.map((filePath) => path.dirname(filePath))),
+    ];
+    let directoriesRemoved = 0;
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    for (const candidateDir of candidateDirs) {
+        let currentDir = path.resolve(candidateDir);
+        while (currentDir !== resolvedProjectRoot &&
+            (0, path_utils_1.isPathInsideOrEqual)(resolvedProjectRoot, currentDir)) {
+            const removed = await removeEmptyDirectory(currentDir, verbose, dryRun);
+            if (!removed) {
+                break;
+            }
+            directoriesRemoved++;
+            currentDir = path.dirname(currentDir);
+        }
+    }
+    return directoriesRemoved;
+}

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).
@@ -82,7 +93,7 @@ function resolveSubagentsCleanupOrphaned(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) {
@@ -91,6 +102,7 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
     let selectedAgents;
     let generatedPaths;
     let loadedConfig;
+    let outputProjectRoot = projectRoot;
     if (nested) {
         const hierarchicalConfigs = await (0, apply_engine_1.loadNestedConfigurations)(projectRoot, configPath, localOnly, nested);
         if (hierarchicalConfigs.length === 0) {
@@ -123,6 +135,7 @@ 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) {
@@ -131,10 +144,12 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
                 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);
+        const singleProjectRoot = singleConfig.projectRoot;
+        outputProjectRoot = singleProjectRoot;
         loadedConfig = singleConfig.config;
         singleConfig.config.cliAgents = includedAgents;
         (0, constants_1.logVerbose)(`Loaded configuration with ${Object.keys(singleConfig.config.agentConfigs).length} agent configs`, verbose);
@@ -146,16 +161,17 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
         const skillsEnabledResolved = resolveSkillsEnabled(skillsEnabled, singleConfig.config.skills?.enabled);
         if (skillsEnabledResolved) {
             const { propagateSkills } = await Promise.resolve().then(() => __importStar(require('./core/SkillsProcessor')));
-            await propagateSkills(projectRoot, selectedAgents, skillsEnabledResolved, verbose, dryRun);
+            await propagateSkills(singleProjectRoot, selectedAgents, skillsEnabledResolved, verbose, dryRun);
         }
         // 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, subagentsCleanupOrphanedSingle, verbose, dryRun);
+            await propagateSubagents(singleProjectRoot, 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, singleProjectRoot, verbose, dryRun, cliMcpEnabled, cliMcpStrategy, backupEnabledResolvedSingle);
     }
     // Add skills-generated paths to gitignore if skills are enabled
     let allGeneratedPaths = generatedPaths;
@@ -163,17 +179,17 @@ async function applyAllAgentConfigs(projectRoot, includedAgents, configPath, cli
     if (skillsEnabledForGitignore) {
         // Skills enabled by default or explicitly
         const { getSkillsGitignorePaths } = await Promise.resolve().then(() => __importStar(require('./core/SkillsProcessor')));
-        const skillsPaths = await getSkillsGitignorePaths(projectRoot, selectedAgents);
+        const skillsPaths = await getSkillsGitignorePaths(outputProjectRoot, selectedAgents);
         allGeneratedPaths = [...allGeneratedPaths, ...skillsPaths];
     }
     // Add subagents-generated paths to gitignore if subagents are enabled.
     const subagentsEnabledForGitignore = resolveSubagentsEnabled(subagentsEnabled, loadedConfig.subagents?.enabled);
     if (subagentsEnabledForGitignore) {
         const { getSubagentsGitignorePaths } = await Promise.resolve().then(() => __importStar(require('./core/SubagentsProcessor')));
-        const subagentPaths = await getSubagentsGitignorePaths(projectRoot, selectedAgents);
+        const subagentPaths = await getSubagentsGitignorePaths(outputProjectRoot, selectedAgents);
         allGeneratedPaths = [...allGeneratedPaths, ...subagentPaths];
     }
-    await (0, apply_engine_1.updateGitignore)(projectRoot, allGeneratedPaths, loadedConfig, cliGitignoreEnabled, dryRun, cliGitignoreLocal);
+    await (0, apply_engine_1.updateGitignore)(outputProjectRoot, allGeneratedPaths, loadedConfig, cliGitignoreEnabled, dryRun, cliGitignoreLocal);
 }
 /**
  * Normalizes per-agent config keys to agent identifiers for consistent lookup.

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>;

package/dist/mcp/merge.js

@@ -1,6 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mergeMcp = mergeMcp;
+const MCP_SERVER_KEYS = [
+    'mcp',
+    'mcpServers',
+    'servers',
+    'mcp_servers',
+    'context_servers',
+];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function collectMcpServers(config, serverKey) {
+    const servers = {};
+    const aliases = MCP_SERVER_KEYS.filter((key) => key !== serverKey);
+    for (const key of [...aliases, serverKey]) {
+        const value = config[key];
+        if (isRecord(value)) {
+            Object.assign(servers, value);
+        }
+    }
+    return servers;
+}
+function removeServerAliases(config, serverKey) {
+    const result = { ...config };
+    for (const key of MCP_SERVER_KEYS) {
+        if (key !== serverKey) {
+            delete result[key];
+        }
+    }
+    return result;
+}
 /**
  * Merge native and incoming MCP server configurations according to strategy.
  * @param base Existing native MCP config object.
@@ -11,27 +41,17 @@ exports.mergeMcp = mergeMcp;
  */
 function mergeMcp(base, incoming, strategy, serverKey) {
     if (strategy === 'overwrite') {
-        // Ensure the incoming object uses the correct server key.
-        // Transform from the standard (Crush) MCP config format
-        const incomingServers = incoming[serverKey] ||
-            incoming.mcpServers ||
-            incoming.mcp ||
-            {};
+        const incomingServers = collectMcpServers(incoming, serverKey);
+        const preservedBase = removeServerAliases(base, serverKey);
         return {
+            ...preservedBase,
             [serverKey]: incomingServers,
         };
     }
-    const baseServers = base[serverKey] ||
-        base.mcpServers ||
-        base.mcp ||
-        {};
-    const incomingServers = incoming[serverKey] ||
-        incoming.mcpServers ||
-        incoming.mcp ||
-        {};
+    const baseServers = collectMcpServers(base, serverKey);
+    const incomingServers = collectMcpServers(incoming, serverKey);
     const mergedServers = { ...baseServers, ...incomingServers };
-    const newBase = { ...base };
-    delete newBase.mcpServers; // Remove old key if present
+    const newBase = removeServerAliases(base, serverKey);
     return {
         ...newBase,
         [serverKey]: mergedServers,

package/dist/mcp/propagateOpenCodeMcp.d.ts

@@ -0,0 +1,2 @@
+import { McpStrategy } from '../types';
+export declare function propagateMcpToOpenCode(rulerMcpData: Record<string, unknown> | null, openCodeConfigPath: string, backup?: boolean, strategy?: McpStrategy, containmentRoot?: string): Promise<void>;

package/dist/mcp/propagateOpenCodeMcp.js

@@ -91,16 +91,29 @@ function transformToOpenCodeFormat(rulerMcp) {
         mcp: openCodeServers,
     };
 }
-async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup = true) {
+async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup = true, strategy = 'merge', containmentRoot) {
     const rulerMcp = rulerMcpData || {};
+    if (containmentRoot) {
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(openCodeConfigPath, containmentRoot, 'Refusing to write generated file outside project');
+    }
     // Read existing OpenCode config if it exists
     let existingConfig = {};
+    let existingContent;
     try {
-        const existingContent = await fs.readFile(openCodeConfigPath, 'utf8');
-        existingConfig = JSON.parse(existingContent);
+        existingContent = await fs.readFile(openCodeConfigPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Could not read OpenCode config at ${openCodeConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    catch {
-        // File doesn't exist, we'll create it
+    if (existingContent !== undefined) {
+        try {
+            existingConfig = JSON.parse(existingContent);
+        }
+        catch (error) {
+            throw new Error(`Invalid OpenCode config at ${openCodeConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     // Transform ruler MCP to OpenCode format
     const transformedConfig = transformToOpenCodeFormat(rulerMcp);
@@ -108,15 +121,21 @@ async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup =
     const finalConfig = {
         ...existingConfig,
         $schema: transformedConfig.$schema,
-        mcp: {
-            ...existingConfig.mcp,
-            ...transformedConfig.mcp,
-        },
+        mcp: strategy === 'overwrite'
+            ? transformedConfig.mcp
+            : {
+                ...existingConfig.mcp,
+                ...transformedConfig.mcp,
+            },
     };
+    const finalContent = JSON.stringify(finalConfig, null, 2) + '\n';
+    if (existingContent === finalContent) {
+        return;
+    }
     await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(openCodeConfigPath));
     if (backup) {
         const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
-        await backupFile(openCodeConfigPath);
+        await backupFile(openCodeConfigPath, containmentRoot);
     }
-    await fs.writeFile(openCodeConfigPath, JSON.stringify(finalConfig, null, 2) + '\n');
+    await (0, FileSystemUtils_1.writeGeneratedFile)(openCodeConfigPath, finalContent, containmentRoot);
 }

package/dist/mcp/propagateOpenHandsMcp.d.ts

@@ -0,0 +1,2 @@
+import { McpStrategy } from '../types';
+export declare function propagateMcpToOpenHands(rulerMcpData: Record<string, unknown> | null, openHandsConfigPath: string, backup?: boolean, strategy?: McpStrategy, containmentRoot?: string): Promise<void>;