@intellectronica/ruler 0.3.41 → 0.3.42

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).
@@ -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) {
@@ -123,6 +134,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,7 +143,7 @@ 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);
@@ -151,11 +163,12 @@ 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, 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>;

package/dist/mcp/merge.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mergeMcp = mergeMcp;
+const MCP_SERVER_KEYS = [
+    'mcp',
+    'mcpServers',
+    'servers',
+    'mcp_servers',
+    'context_servers',
+];
 /**
  * Merge native and incoming MCP server configurations according to strategy.
  * @param base Existing native MCP config object.
@@ -17,7 +24,14 @@ function mergeMcp(base, incoming, strategy, serverKey) {
             incoming.mcpServers ||
             incoming.mcp ||
             {};
+        const preservedBase = { ...base };
+        for (const key of MCP_SERVER_KEYS) {
+            if (key !== serverKey) {
+                delete preservedBase[key];
+            }
+        }
         return {
+            ...preservedBase,
             [serverKey]: incomingServers,
         };
     }
@@ -31,7 +45,11 @@ function mergeMcp(base, incoming, strategy, serverKey) {
         {};
     const mergedServers = { ...baseServers, ...incomingServers };
     const newBase = { ...base };
-    delete newBase.mcpServers; // Remove old key if present
+    for (const key of MCP_SERVER_KEYS) {
+        if (key !== serverKey) {
+            delete newBase[key];
+        }
+    }
     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): Promise<void>;

package/dist/mcp/propagateOpenCodeMcp.js

@@ -91,16 +91,26 @@ function transformToOpenCodeFormat(rulerMcp) {
         mcp: openCodeServers,
     };
 }
-async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup = true) {
+async function propagateMcpToOpenCode(rulerMcpData, openCodeConfigPath, backup = true, strategy = 'merge') {
     const rulerMcp = rulerMcpData || {};
     // 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 {
-        // File doesn't exist, we'll create it
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Could not read OpenCode config at ${openCodeConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    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,10 +118,12 @@ 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,
+            },
     };
     await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(openCodeConfigPath));
     if (backup) {

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): Promise<void>;

package/dist/mcp/propagateOpenHandsMcp.js

@@ -89,7 +89,7 @@ function normalizeRemoteServerArray(entries) {
     // All entries are strings, keep as is
     return entries;
 }
-async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup = true) {
+async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup = true, strategy = 'merge') {
     const rulerMcp = rulerMcpData || {};
     // Always use the legacy Ruler MCP config format as input (top-level "mcpServers" key)
     const rulerServers = rulerMcp.mcpServers || {};
@@ -100,12 +100,22 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup
         return;
     }
     let config = {};
+    let tomlContent;
     try {
-        const tomlContent = await fs.readFile(openHandsConfigPath, 'utf8');
-        config = (0, toml_1.parse)(tomlContent);
+        tomlContent = await fs.readFile(openHandsConfigPath, 'utf8');
     }
-    catch {
-        // File doesn't exist, we'll create it.
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Could not read OpenHands config at ${openHandsConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (tomlContent !== undefined) {
+        try {
+            config = (0, toml_1.parse)(tomlContent);
+        }
+        catch (error) {
+            throw new Error(`Invalid OpenHands config at ${openHandsConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     if (!config.mcp) {
         config.mcp = {};
@@ -119,18 +129,24 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup
     if (!config.mcp.shttp_servers) {
         config.mcp.shttp_servers = [];
     }
-    // Build maps for merging existing servers
-    const existingStdioServers = new Map(config.mcp.stdio_servers.map((s) => [s.name, s]));
+    // Build maps for merging existing servers, or start fresh when overwriting.
+    const existingStdioServers = new Map(strategy === 'overwrite'
+        ? []
+        : config.mcp.stdio_servers.map((s) => [s.name, s]));
     const existingSseServers = new Map();
-    config.mcp.sse_servers.forEach((entry) => {
-        const url = typeof entry === 'string' ? entry : entry.url;
-        existingSseServers.set(url, entry);
-    });
+    if (strategy !== 'overwrite') {
+        config.mcp.sse_servers.forEach((entry) => {
+            const url = typeof entry === 'string' ? entry : entry.url;
+            existingSseServers.set(url, entry);
+        });
+    }
     const existingShttpServers = new Map();
-    config.mcp.shttp_servers.forEach((entry) => {
-        const url = typeof entry === 'string' ? entry : entry.url;
-        existingShttpServers.set(url, entry);
-    });
+    if (strategy !== 'overwrite') {
+        config.mcp.shttp_servers.forEach((entry) => {
+            const url = typeof entry === 'string' ? entry : entry.url;
+            existingShttpServers.set(url, entry);
+        });
+    }
     for (const [name, serverDef] of Object.entries(rulerServers)) {
         if (isRulerMcpServer(serverDef)) {
             if (serverDef.command) {

package/dist/mcp/validate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate the structure of the Ruler MCP JSON config.
+ * Minimal validation: ensure 'mcpServers' property exists and is an object.
+ * @param data Parsed JSON object from .ruler/mcp.json.
+ * @throws Error if validation fails.
+ */
+export declare function validateMcp(data: unknown): void;

package/dist/mcp/validate.js

@@ -8,10 +8,15 @@ exports.validateMcp = validateMcp;
  * @throws Error if validation fails.
  */
 function validateMcp(data) {
+    const mcpServers = data && typeof data === 'object'
+        ? data.mcpServers
+        : undefined;
     if (!data ||
         typeof data !== 'object' ||
         !('mcpServers' in data) ||
-        typeof data.mcpServers !== 'object') {
+        !mcpServers ||
+        typeof mcpServers !== 'object' ||
+        Array.isArray(mcpServers)) {
         throw new Error('[ruler] Invalid MCP config: must contain an object property "mcpServers" (Ruler style)');
     }
 }

package/dist/paths/mcp.d.ts

@@ -0,0 +1,8 @@
+/** Determine the native MCP config path for a given agent. */
+export declare function getNativeMcpPath(adapterName: string, projectRoot: string): Promise<string | null>;
+/** Read native MCP config from disk, or return empty object if missing. */
+export declare function readNativeMcp(filePath: string): Promise<Record<string, unknown>>;
+/** Read native Codex TOML MCP config from disk, or return empty object if missing. */
+export declare function readNativeMcpToml(filePath: string, parseToml: (text: string) => Record<string, unknown>): Promise<Record<string, unknown>>;
+/** Write native MCP config to disk, creating parent directories as needed. */
+export declare function writeNativeMcp(filePath: string, data: unknown): Promise<void>;

package/dist/paths/mcp.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNativeMcpPath = getNativeMcpPath;
 exports.readNativeMcp = readNativeMcp;
+exports.readNativeMcpToml = readNativeMcpToml;
 exports.writeNativeMcp = writeNativeMcp;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
@@ -111,14 +112,42 @@ async function getNativeMcpPath(adapterName, projectRoot) {
     // default to first candidate if none exist
     return candidates.length > 0 ? candidates[0] : null;
 }
-/** Read native MCP config from disk, or return empty object if missing/invalid. */
+/** Read native MCP config from disk, or return empty object if missing. */
 async function readNativeMcp(filePath) {
+    let text;
+    try {
+        text = await fs_1.promises.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        throw new Error(`Could not read MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
     try {
-        const text = await fs_1.promises.readFile(filePath, 'utf8');
         return JSON.parse(text);
     }
-    catch {
-        return {};
+    catch (error) {
+        throw new Error(`Invalid MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Read native Codex TOML MCP config from disk, or return empty object if missing. */
+async function readNativeMcpToml(filePath, parseToml) {
+    let text;
+    try {
+        text = await fs_1.promises.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        throw new Error(`Could not read MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return parseToml(text);
+    }
+    catch (error) {
+        throw new Error(`Invalid MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 /** Write native MCP config to disk, creating parent directories as needed. */

package/dist/revert.d.ts

@@ -0,0 +1,6 @@
+import { allAgents } from './agents';
+export { allAgents };
+/**
+ * Reverts ruler configurations for selected AI agents.
+ */
+export declare function revertAllAgentConfigs(projectRoot: string, includedAgents?: string[], configPath?: string, keepBackups?: boolean, verbose?: boolean, dryRun?: boolean, localOnly?: boolean): Promise<void>;