@intellectronica/ruler 0.3.41 → 0.3.43

package/dist/mcp/propagateOpenHandsMcp.js

@@ -67,10 +67,14 @@ function extractApiKey(headers) {
     }
     return null;
 }
-function createRemoteServerEntry(url, headers) {
+function createRemoteServerEntry(name, url, headers) {
+    const hasHeaders = headers && Object.keys(headers).length > 0;
     const apiKey = extractApiKey(headers);
-    if (apiKey) {
-        return { url, api_key: apiKey };
+    if (hasHeaders) {
+        if (apiKey) {
+            return { url, api_key: apiKey };
+        }
+        throw new Error(`OpenHands MCP remote server "${name}" has unsupported headers. OpenHands config.toml can only represent a Bearer Authorization header as api_key.`);
     }
     return url;
 }
@@ -89,8 +93,11 @@ 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', containmentRoot) {
     const rulerMcp = rulerMcpData || {};
+    if (containmentRoot) {
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(openHandsConfigPath, containmentRoot, 'Refusing to write generated file outside project');
+    }
     // Always use the legacy Ruler MCP config format as input (top-level "mcpServers" key)
     const rulerServers = rulerMcp.mcpServers || {};
     // Return early if no servers to process
@@ -100,12 +107,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 (error) {
+        if (error.code !== 'ENOENT') {
+            throw new Error(`Could not read OpenHands config at ${openHandsConfigPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
-    catch {
-        // File doesn't exist, we'll create it.
+    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 +136,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) {
@@ -146,7 +169,7 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup
             else if (serverDef.url) {
                 // Remote server
                 const classification = classifyRemoteServer(serverDef.url);
-                const entry = createRemoteServerEntry(serverDef.url, serverDef.headers);
+                const entry = createRemoteServerEntry(name, serverDef.url, serverDef.headers);
                 if (classification === 'sse') {
                     existingSseServers.set(serverDef.url, entry);
                 }
@@ -160,10 +183,14 @@ async function propagateMcpToOpenHands(rulerMcpData, openHandsConfigPath, backup
     config.mcp.stdio_servers = Array.from(existingStdioServers.values());
     config.mcp.sse_servers = normalizeRemoteServerArray(Array.from(existingSseServers.values()));
     config.mcp.shttp_servers = normalizeRemoteServerArray(Array.from(existingShttpServers.values()));
+    const finalContent = (0, toml_1.stringify)(config);
+    if (tomlContent === finalContent) {
+        return;
+    }
     await (0, FileSystemUtils_1.ensureDirExists)(path.dirname(openHandsConfigPath));
     if (backup) {
         const { backupFile } = await Promise.resolve().then(() => __importStar(require('../core/FileSystemUtils')));
-        await backupFile(openHandsConfigPath);
+        await backupFile(openHandsConfigPath, containmentRoot);
     }
-    await fs.writeFile(openHandsConfigPath, (0, toml_1.stringify)(config));
+    await (0, FileSystemUtils_1.writeGeneratedFile)(openHandsConfigPath, finalContent, containmentRoot);
 }

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, containmentRoot?: string): Promise<void>;

package/dist/paths/mcp.js

@@ -35,9 +35,14 @@ 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");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /** Determine the native MCP config path for a given agent. */
 async function getNativeMcpPath(adapterName, projectRoot) {
     const candidates = [];
@@ -111,19 +116,50 @@ 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 parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            throw new Error('must be a JSON object');
+        }
+        return parsed;
+    }
+    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 {
-        const text = await fs_1.promises.readFile(filePath, 'utf8');
-        return JSON.parse(text);
+        return parseToml(text);
     }
-    catch {
-        return {};
+    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. */
-async function writeNativeMcp(filePath, data) {
-    await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+async function writeNativeMcp(filePath, data, containmentRoot) {
     const text = JSON.stringify(data, null, 2) + '\n';
-    await fs_1.promises.writeFile(filePath, text, 'utf8');
+    await (0, FileSystemUtils_1.writeGeneratedFile)(filePath, text, containmentRoot);
 }

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

package/dist/revert.js

@@ -35,7 +35,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.allAgents = void 0;
 exports.revertAllAgentConfigs = revertAllAgentConfigs;
-const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const FileSystemUtils = __importStar(require("./core/FileSystemUtils"));
 const ConfigLoader_1 = require("./core/ConfigLoader");
@@ -45,21 +44,25 @@ const constants_1 = require("./constants");
 const revert_engine_1 = require("./core/revert-engine");
 const agent_selection_1 = require("./core/agent-selection");
 const config_utils_1 = require("./core/config-utils");
+const GitignoreUtils_1 = require("./core/GitignoreUtils");
 const agents = agents_1.allAgents;
+const MANAGED_IGNORE_FILES = ['.gitignore', '.git/info/exclude'];
 /**
  * Reverts ruler configurations for selected AI agents.
  */
 async function revertAllAgentConfigs(projectRoot, includedAgents, configPath, keepBackups = false, verbose = false, dryRun = false, localOnly = false) {
-    (0, constants_1.logVerbose)(`Loading configuration for revert from project root: ${projectRoot}`, verbose);
-    const config = await (0, ConfigLoader_1.loadConfig)({
-        projectRoot,
-        cliAgents: includedAgents,
-        configPath,
-    });
     const rulerDir = await FileSystemUtils.findRulerDir(projectRoot, !localOnly);
     if (!rulerDir) {
         throw (0, constants_1.createRulerError)(`.ruler directory not found`, `Searched from: ${projectRoot}`);
     }
+    const effectiveProjectRoot = FileSystemUtils.resolveProjectRootForRulerDir(projectRoot, rulerDir);
+    (0, constants_1.logVerbose)(`Loading configuration for revert from project root: ${effectiveProjectRoot}`, verbose);
+    const config = await (0, ConfigLoader_1.loadConfig)({
+        projectRoot: effectiveProjectRoot,
+        cliAgents: includedAgents,
+        configPath,
+        checkGlobal: !localOnly,
+    });
     (0, constants_1.logVerbose)(`Found .ruler directory at: ${rulerDir}`, verbose);
     // Normalize per-agent config keys to agent identifiers
     config.agentConfigs = (0, config_utils_1.mapRawAgentConfigs)(config.agentConfigs, agents);
@@ -77,18 +80,19 @@ async function revertAllAgentConfigs(projectRoot, includedAgents, configPath, ke
             // Fall back to the old logic without validation
             if (config.cliAgents && config.cliAgents.length > 0) {
                 const filters = config.cliAgents.map((n) => n.toLowerCase());
-                selected = agents.filter((agent) => filters.some((f) => agent.getIdentifier() === f ||
-                    agent.getName().toLowerCase().includes(f)));
+                const validAgentIdentifiers = new Set(agents.map((agent) => agent.getIdentifier()));
+                selected = agents.filter((agent) => filters.some((f) => (0, agent_selection_1.agentMatchesFilter)(agent, f, validAgentIdentifiers)));
             }
             else if (config.defaultAgents && config.defaultAgents.length > 0) {
                 const defaults = config.defaultAgents.map((n) => n.toLowerCase());
+                const validAgentIdentifiers = new Set(agents.map((agent) => agent.getIdentifier()));
                 selected = agents.filter((agent) => {
                     const identifier = agent.getIdentifier();
                     const override = config.agentConfigs[identifier]?.enabled;
                     if (override !== undefined) {
                         return override;
                     }
-                    return defaults.some((d) => identifier === d || agent.getName().toLowerCase().includes(d));
+                    return defaults.some((d) => (0, agent_selection_1.agentMatchesFilter)(agent, d, validAgentIdentifiers));
                 });
             }
             else {
@@ -100,28 +104,36 @@ async function revertAllAgentConfigs(projectRoot, includedAgents, configPath, ke
         }
     }
     (0, constants_1.logVerbose)(`Selected agents: ${selected.map((a) => a.getName()).join(', ')}`, verbose);
+    const isFullRevert = !config.cliAgents || config.cliAgents.length === 0;
     // Revert configurations for each agent
     let totalFilesProcessed = 0;
     let totalFilesRestored = 0;
     let totalFilesRemoved = 0;
     let totalBackupsRemoved = 0;
+    let totalDirectoriesRemoved = 0;
     for (const agent of selected) {
         const prefix = (0, constants_1.actionPrefix)(dryRun);
         console.log(`${prefix} Reverting ${agent.getName()}...`);
         const agentConfig = config.agentConfigs[agent.getIdentifier()];
-        const result = await (0, revert_engine_1.revertAgentConfiguration)(agent, projectRoot, agentConfig, keepBackups, verbose, dryRun);
+        const result = await (0, revert_engine_1.revertAgentConfiguration)(agent, effectiveProjectRoot, agentConfig, keepBackups, verbose, dryRun);
         totalFilesProcessed += result.restored + result.removed;
         totalFilesRestored += result.restored;
         totalFilesRemoved += result.removed;
         totalBackupsRemoved += result.backupsRemoved;
+        if (!isFullRevert) {
+            totalDirectoriesRemoved += await (0, revert_engine_1.cleanUpAgentDirectories)(agent, effectiveProjectRoot, agentConfig, verbose, dryRun);
+        }
     }
-    // Clean up auxiliary files and directories
-    const cleanupResult = await (0, revert_engine_1.cleanUpAuxiliaryFiles)(projectRoot, verbose, dryRun);
+    // Clean up auxiliary files and directories only when reverting all agents.
+    const cleanupResult = isFullRevert
+        ? await (0, revert_engine_1.cleanUpAuxiliaryFiles)(effectiveProjectRoot, verbose, dryRun)
+        : { additionalFilesRemoved: 0, directoriesRemoved: 0 };
     totalFilesRemoved += cleanupResult.additionalFilesRemoved;
-    // Clean .gitignore if reverting all agents
-    const gitignoreCleaned = !config.cliAgents || config.cliAgents.length === 0
-        ? await cleanGitignore(projectRoot, verbose, dryRun)
-        : false;
+    totalDirectoriesRemoved += cleanupResult.directoriesRemoved;
+    // Clean managed ignore blocks if reverting all agents.
+    const cleanedIgnoreFiles = isFullRevert
+        ? await cleanManagedIgnoreFiles(effectiveProjectRoot, verbose, dryRun)
+        : [];
     // Display summary
     const prefix = (0, constants_1.actionPrefix)(dryRun);
     if (dryRun) {
@@ -133,53 +145,53 @@ async function revertAllAgentConfigs(projectRoot, includedAgents, configPath, ke
     console.log(`  Files processed: ${totalFilesProcessed}`);
     console.log(`  Files restored from backup: ${totalFilesRestored}`);
     console.log(`  Generated files removed: ${totalFilesRemoved}`);
-    if (!keepBackups) {
-        console.log(`  Backup files removed: ${totalBackupsRemoved}`);
-    }
-    if (cleanupResult.directoriesRemoved > 0) {
-        console.log(`  Empty directories removed: ${cleanupResult.directoriesRemoved}`);
+    console.log(`  Backup files removed: ${totalBackupsRemoved}`);
+    if (totalDirectoriesRemoved > 0) {
+        console.log(`  Empty directories removed: ${totalDirectoriesRemoved}`);
     }
-    if (gitignoreCleaned) {
-        console.log(`  .gitignore cleaned: yes`);
+    for (const ignoreFile of cleanedIgnoreFiles) {
+        console.log(`  ${ignoreFile} cleaned: yes`);
     }
 }
 /**
- * Removes the ruler-managed block from .gitignore file.
+ * Removes the ruler-managed block from ignore files Ruler can update.
  */
-async function cleanGitignore(projectRoot, verbose, dryRun) {
-    const gitignorePath = path.join(projectRoot, '.gitignore');
+async function cleanManagedIgnoreFiles(projectRoot, verbose, dryRun) {
+    const cleanedFiles = [];
+    for (const ignoreFile of MANAGED_IGNORE_FILES) {
+        if (await cleanIgnoreFile(projectRoot, ignoreFile, verbose, dryRun)) {
+            cleanedFiles.push(ignoreFile);
+        }
+    }
+    return cleanedFiles;
+}
+async function cleanIgnoreFile(projectRoot, ignoreFile, verbose, dryRun) {
+    const ignorePath = await (0, GitignoreUtils_1.resolveIgnoreFilePath)(projectRoot, ignoreFile);
     try {
-        await fs_1.promises.access(gitignorePath);
+        await fs_1.promises.access(ignorePath);
     }
     catch {
-        (0, constants_1.logVerbose)('No .gitignore file found', verbose);
+        (0, constants_1.logVerbose)(`No ${ignoreFile} file found`, verbose);
         return false;
     }
-    const content = await fs_1.promises.readFile(gitignorePath, 'utf8');
-    const startMarker = '# START Ruler Generated Files';
-    const endMarker = '# END Ruler Generated Files';
-    const startIndex = content.indexOf(startMarker);
-    const endIndex = content.indexOf(endMarker);
-    if (startIndex === -1 || endIndex === -1) {
-        (0, constants_1.logVerbose)('No ruler-managed block found in .gitignore', verbose);
+    const content = await fs_1.promises.readFile(ignorePath, 'utf8');
+    const cleaned = (0, GitignoreUtils_1.removeCompleteRulerBlocks)(content);
+    if (!cleaned.removed) {
+        (0, constants_1.logVerbose)(`No ruler-managed block found in ${ignoreFile}`, verbose);
         return false;
     }
     const prefix = (0, constants_1.actionPrefix)(dryRun);
     if (dryRun) {
-        (0, constants_1.logVerbose)(`${prefix} Would remove ruler block from .gitignore`, verbose);
+        (0, constants_1.logVerbose)(`${prefix} Would remove ruler block from ${ignoreFile}`, verbose);
     }
     else {
-        const beforeBlock = content.substring(0, startIndex);
-        const afterBlock = content.substring(endIndex + endMarker.length);
-        let newContent = beforeBlock + afterBlock;
-        newContent = newContent.replace(/\n{3,}/g, '\n\n'); // Replace 3+ newlines with 2
-        if (newContent.trim() === '') {
-            await fs_1.promises.unlink(gitignorePath);
-            (0, constants_1.logVerbose)(`${prefix} Removed empty .gitignore file`, verbose);
+        if (cleaned.content.trim() === '') {
+            await fs_1.promises.unlink(ignorePath);
+            (0, constants_1.logVerbose)(`${prefix} Removed empty ${ignoreFile} file`, verbose);
         }
         else {
-            await fs_1.promises.writeFile(gitignorePath, newContent);
-            (0, constants_1.logVerbose)(`${prefix} Removed ruler block from .gitignore`, verbose);
+            await fs_1.promises.writeFile(ignorePath, cleaned.content);
+            (0, constants_1.logVerbose)(`${prefix} Removed ruler block from ${ignoreFile}`, verbose);
         }
     }
     return true;

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Types for Model Context Protocol (MCP) server configuration.
+ */
+export type McpStrategy = 'merge' | 'overwrite';
+/** MCP configuration for an agent or global. */
+export interface McpConfig {
+    /** Enable or disable MCP propagation (merge or overwrite). */
+    enabled?: boolean;
+    /** Merge strategy: 'merge' to merge servers, 'overwrite' to replace config. */
+    strategy?: McpStrategy;
+}
+/** Global MCP configuration section (same as agent-specific config). */
+export type GlobalMcpConfig = McpConfig;
+/** Gitignore configuration for automatic .gitignore file updates. */
+export interface GitignoreConfig {
+    /** Enable or disable automatic .gitignore updates. */
+    enabled?: boolean;
+    /** Write managed ignore entries to .git/info/exclude instead of .gitignore. */
+    local?: boolean;
+}
+/** Backup configuration for .bak file generation. */
+export interface BackupConfig {
+    /** Enable or disable creation of .bak backup files. */
+    enabled?: boolean;
+}
+/** Skills configuration for automatic skills distribution. */
+export interface SkillsConfig {
+    /** Enable or disable skills support. */
+    enabled?: boolean;
+}
+/** Information about a discovered skill. */
+export interface SkillInfo {
+    /** Name of the skill (directory name). */
+    name: string;
+    /** Absolute path to the skill directory. */
+    path: string;
+    /** Whether the directory contains a SKILL.md file. */
+    hasSkillMd: boolean;
+    /** Whether this is a valid skill. */
+    valid: boolean;
+    /** Error message if invalid. */
+    error?: string;
+}
+/** Subagents configuration for automatic subagent distribution. */
+export interface SubagentsConfig {
+    /** Enable or disable subagents support. */
+    enabled?: boolean;
+    /**
+     * When true, Ruler may delete previously generated native subagent
+     * directories that are stale (disabled, no source definitions, or
+     * deselected targets). Defaults to false (non-destructive).
+     */
+    cleanup_orphaned?: boolean;
+    /**
+     * When true, `.ruler/agents/*.md` are also concatenated into the
+     * generated top-level rule files (CLAUDE.md, AGENTS.md, Copilot
+     * instructions, etc.). When false (default), `.ruler/agents/` is
+     * skipped during rule concatenation, mirroring `.ruler/skills/`.
+     */
+    include_in_rules?: boolean;
+}
+/** Frontmatter fields recognised on a source subagent definition. */
+export interface SubagentFrontmatter {
+    name: string;
+    description: string;
+    tools?: string[];
+    model?: string;
+    readonly?: boolean;
+    is_background?: boolean;
+}
+/** Information about a discovered subagent. */
+export interface SubagentInfo {
+    /** Name of the subagent (filename stem and frontmatter `name`). */
+    name: string;
+    /** Absolute path to the source `.md` file. */
+    path: string;
+    /** Relative `.md` path under `.ruler/agents/` (preserves nested layout). */
+    sourceRelativePath?: string;
+    /** Parsed frontmatter (only present when valid). */
+    frontmatter?: SubagentFrontmatter;
+    /** Body content after the frontmatter delimiter. */
+    body?: string;
+    /** Whether this subagent passed validation. */
+    valid: boolean;
+    /** Error message if invalid. */
+    error?: string;
+}

package/dist/vscode/settings.d.ts

@@ -0,0 +1,40 @@
+import { McpStrategy } from '../types';
+/**
+ * VSCode settings.json structure for Augment MCP configuration
+ */
+export interface VSCodeSettings {
+    'augment.advanced'?: {
+        mcpServers?: AugmentMcpServer[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Augment MCP server configuration format
+ */
+export interface AugmentMcpServer {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Read VSCode settings.json file
+ */
+export declare function readVSCodeSettings(settingsPath: string): Promise<VSCodeSettings>;
+/**
+ * Write VSCode settings.json file
+ */
+export declare function writeVSCodeSettings(settingsPath: string, settings: VSCodeSettings, containmentRoot?: string): Promise<void>;
+/**
+ * Transform ruler MCP config to Augment MCP server array format
+ */
+export declare function transformRulerToAugmentMcp(rulerMcpJson: Record<string, unknown>): AugmentMcpServer[];
+/**
+ * Merge MCP servers into VSCode settings using the specified strategy
+ */
+export declare function mergeAugmentMcpServers(existingSettings: VSCodeSettings, newServers: AugmentMcpServer[], strategy: McpStrategy): VSCodeSettings;
+/**
+ * Get the VSCode settings.json path for a project (local)
+ */
+export declare function getVSCodeSettingsPath(projectRoot: string): string;

package/dist/vscode/settings.js

@@ -40,6 +40,7 @@ exports.mergeAugmentMcpServers = mergeAugmentMcpServers;
 exports.getVSCodeSettingsPath = getVSCodeSettingsPath;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 /**
  * Read VSCode settings.json file
  */
@@ -58,9 +59,8 @@ async function readVSCodeSettings(settingsPath) {
 /**
  * Write VSCode settings.json file
  */
-async function writeVSCodeSettings(settingsPath, settings) {
-    await fs_1.promises.mkdir(path.dirname(settingsPath), { recursive: true });
-    await fs_1.promises.writeFile(settingsPath, JSON.stringify(settings, null, 4));
+async function writeVSCodeSettings(settingsPath, settings, containmentRoot) {
+    await (0, FileSystemUtils_1.writeGeneratedFile)(settingsPath, JSON.stringify(settings, null, 4), containmentRoot);
 }
 /**
  * Transform ruler MCP config to Augment MCP server array format

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@intellectronica/ruler",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "description": "Ruler — apply the same rules to all coding agents",
   "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
   "scripts": {
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
-    "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
-    "test": "jest",
+    "format": "prettier --write package.json package-lock.json tsconfig.json README.md \".github/**/*.yml\" \"src/**/*.{ts,tsx,json,md}\" \"tests/**/*.{ts,tsx,json,md}\"",
+    "format:check": "prettier --check package.json package-lock.json tsconfig.json README.md \".github/**/*.yml\" \"src/**/*.{ts,tsx,json,md}\" \"tests/**/*.{ts,tsx,json,md}\"",
+    "test": "jest --coverage",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:integration": "jest tests/e2e/ruler.integration.test.ts --verbose",
     "build": "tsc",
-    "prepare": "npm run build"
+    "check:package-lock": "node -e \"const pkg=require('./package.json'); const lock=require('./package-lock.json'); const root=lock.packages?.['']; if (lock.version !== pkg.version || root?.version !== pkg.version) { console.error('package-lock.json version metadata must match package.json version'); process.exit(1); }\"",
+    "prepublishOnly": "npm run build"
   },
   "repository": {
     "type": "git",
@@ -66,7 +69,7 @@
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.2.0",
     "yargs": "^18.0.0",
     "zod": "^4.1.12"
   }