@intellectronica/ruler 0.3.41 → 0.3.43

package/dist/agents/WarpAgent.d.ts

@@ -0,0 +1,12 @@
+import { AbstractAgent } from './AbstractAgent';
+/**
+ * Warp Agent Mode adapter.
+ * Generates WARP.md configuration file in the project root.
+ */
+export declare class WarpAgent extends AbstractAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getDefaultOutputPath(projectRoot: string): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+}

package/dist/agents/WindsurfAgent.d.ts

@@ -0,0 +1,13 @@
+import { AgentsMdAgent } from './AgentsMdAgent';
+/**
+ * Windsurf agent adapter.
+ * Now uses AGENTS.md format like other agents.
+ */
+export declare class WindsurfAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): string;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+}

package/dist/agents/ZedAgent.d.ts

@@ -0,0 +1,21 @@
+import { AgentsMdAgent } from './AgentsMdAgent';
+import { IAgentConfig } from './IAgent';
+/**
+ * Zed editor agent adapter.
+ * Inherits from AgentsMdAgent to write instructions to AGENTS.md and handles
+ * MCP server configuration in .zed/settings.json at the project root.
+ */
+export declare class ZedAgent extends AgentsMdAgent {
+    getIdentifier(): string;
+    getName(): string;
+    applyRulerConfig(concatenatedRules: string, projectRoot: string, rulerMcpJson: Record<string, unknown> | null, agentConfig?: IAgentConfig, backup?: boolean): Promise<void>;
+    getMcpServerKey(): string;
+    supportsMcpStdio(): boolean;
+    supportsMcpRemote(): boolean;
+    supportsNativeSkills(): boolean;
+    /**
+     * Transform MCP server configuration from ruler format to Zed format.
+     * Converts "type": "stdio" to "source": "custom" and preserves other fields.
+     */
+    private transformMcpServerForZed;
+}

package/dist/agents/ZedAgent.js

@@ -37,6 +37,7 @@ exports.ZedAgent = void 0;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const AgentsMdAgent_1 = require("./AgentsMdAgent");
+const FileSystemUtils_1 = require("../core/FileSystemUtils");
 /**
  * Zed editor agent adapter.
  * Inherits from AgentsMdAgent to write instructions to AGENTS.md and handles
@@ -49,15 +50,15 @@ class ZedAgent extends AgentsMdAgent_1.AgentsMdAgent {
     getName() {
         return 'Zed';
     }
-    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig) {
+    async applyRulerConfig(concatenatedRules, projectRoot, rulerMcpJson, agentConfig, backup = true) {
         // First, perform idempotent AGENTS.md write via base class
         await super.applyRulerConfig(concatenatedRules, projectRoot, null, {
             outputPath: agentConfig?.outputPath,
-        });
+        }, backup);
         // Handle MCP server configuration if enabled and provided
         const mcpEnabled = agentConfig?.mcp?.enabled ?? true;
         if (mcpEnabled && rulerMcpJson) {
-            const zedSettingsPath = path.join(projectRoot, '.zed', 'settings.json');
+            const zedSettingsPath = path.resolve(projectRoot, agentConfig?.outputPathConfig ?? path.join('.zed', 'settings.json'));
             // Read existing settings
             let existingSettings = {};
             try {
@@ -103,8 +104,7 @@ class ZedAgent extends AgentsMdAgent_1.AgentsMdAgent {
                 };
             }
             // Write updated settings
-            await fs_1.promises.mkdir(path.dirname(zedSettingsPath), { recursive: true });
-            await fs_1.promises.writeFile(zedSettingsPath, JSON.stringify(mergedSettings, null, 2));
+            await (0, FileSystemUtils_1.writeGeneratedFile)(zedSettingsPath, JSON.stringify(mergedSettings, null, 2), projectRoot);
         }
     }
     getMcpServerKey() {
@@ -116,6 +116,9 @@ class ZedAgent extends AgentsMdAgent_1.AgentsMdAgent {
     supportsMcpRemote() {
         return true;
     }
+    supportsNativeSkills() {
+        return true;
+    }
     /**
      * Transform MCP server configuration from ruler format to Zed format.
      * Converts "type": "stdio" to "source": "custom" and preserves other fields.

package/dist/agents/agent-utils.d.ts

@@ -0,0 +1,5 @@
+import { IAgent, IAgentConfig } from './IAgent';
+/**
+ * Gets all output paths for an agent, taking into account any config overrides.
+ */
+export declare function getAgentOutputPaths(agent: IAgent, projectRoot: string, agentConfig?: IAgentConfig): string[];

package/dist/agents/agent-utils.js

@@ -17,17 +17,20 @@ function getAgentOutputPaths(agent, projectRoot, agentConfig) {
         const defaultPaths = defaults;
         // Handle instructions path
         if ('instructions' in defaultPaths) {
-            const instructionsPath = agentConfig?.outputPathInstructions ?? defaultPaths.instructions;
+            const instructionsPath = agentConfig?.outputPath ??
+                agentConfig?.outputPathInstructions ??
+                defaultPaths.instructions;
             paths.push(instructionsPath);
         }
-        // Handle config path
-        if ('config' in defaultPaths) {
-            const configPath = agentConfig?.outputPathConfig ?? defaultPaths.config;
+        // Handle config/MCP path
+        const configKey = 'config' in defaultPaths ? 'config' : 'mcp';
+        if (configKey in defaultPaths) {
+            const configPath = agentConfig?.outputPathConfig ?? defaultPaths[configKey];
             paths.push(configPath);
         }
         // Handle any other paths in the default paths record
         for (const [key, defaultPath] of Object.entries(defaultPaths)) {
-            if (key !== 'instructions' && key !== 'config') {
+            if (key !== 'instructions' && key !== configKey) {
                 // For unknown path types, use the default since we don't have specific config overrides
                 paths.push(defaultPath);
             }

package/dist/agents/index.d.ts

@@ -0,0 +1,9 @@
+import { IAgent } from './IAgent';
+import { AbstractAgent } from './AbstractAgent';
+export { AbstractAgent };
+export declare const allAgents: IAgent[];
+/**
+ * Generates a comma-separated list of agent identifiers for CLI help text.
+ * Returns identifiers in alphabetical order, with 'agentsmd' always first.
+ */
+export declare function getAgentIdentifiersForCliHelp(): string;

package/dist/cli/commands.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sets up and parses CLI commands.
+ */
+export declare function run(): void;

package/dist/cli/commands.js

@@ -71,8 +71,7 @@ function run() {
         })
             .option('backup', {
             type: 'boolean',
-            description: 'Enable/disable creation of .bak backup files (default: enabled)',
-            default: true,
+            description: 'Enable/disable creation of .bak backup files (default: from config or enabled)',
         })
             .option('skills', {
             type: 'boolean',

package/dist/cli/handlers.d.ts

@@ -0,0 +1,41 @@
+export interface ApplyArgs {
+    'project-root': string;
+    agents?: string;
+    config?: string;
+    mcp: boolean;
+    'mcp-overwrite': boolean;
+    gitignore?: boolean;
+    'gitignore-local'?: boolean;
+    verbose: boolean;
+    'dry-run': boolean;
+    'local-only': boolean;
+    nested?: boolean;
+    backup?: boolean;
+    skills?: boolean;
+    subagents?: boolean;
+}
+export interface InitArgs {
+    'project-root': string;
+    global: boolean;
+}
+export interface RevertArgs {
+    'project-root': string;
+    agents?: string;
+    config?: string;
+    'keep-backups': boolean;
+    verbose: boolean;
+    'dry-run': boolean;
+    'local-only': boolean;
+}
+/**
+ * Handler for the 'apply' command.
+ */
+export declare function applyHandler(argv: ApplyArgs): Promise<void>;
+/**
+ * Handler for the 'init' command.
+ */
+export declare function initHandler(argv: InitArgs): Promise<void>;
+/**
+ * Handler for the 'revert' command.
+ */
+export declare function revertHandler(argv: RevertArgs): Promise<void>;

package/dist/cli/handlers.js

@@ -51,15 +51,41 @@ function assertNotInsideRulerDir(projectRoot) {
         process.exit(1);
     }
 }
+function formatCliError(message) {
+    return message.startsWith(constants_1.ERROR_PREFIX)
+        ? message
+        : `${constants_1.ERROR_PREFIX} ${message}`;
+}
+function parseCliAgents(agents) {
+    if (agents === undefined) {
+        return undefined;
+    }
+    const parsedAgents = agents.split(',').map((agent) => agent.trim());
+    if (parsedAgents.some((agent) => agent.length === 0)) {
+        throw new Error('Empty agent token in --agents. Remove extra commas or provide an agent name.');
+    }
+    return parsedAgents;
+}
+async function resolveNestedPreference(argv, projectRoot, configPath, localOnly) {
+    if (argv.nested !== undefined) {
+        // CLI explicitly set nested (either --nested or --no-nested)
+        return argv.nested;
+    }
+    // CLI didn't set nested, check TOML configuration
+    const config = await (0, ConfigLoader_1.loadConfig)({
+        projectRoot,
+        configPath,
+        checkGlobal: !localOnly,
+    });
+    // Use TOML setting if available, otherwise default to false
+    return config.nested ?? false;
+}
 /**
  * Handler for the 'apply' command.
  */
 async function applyHandler(argv) {
     const projectRoot = argv['project-root'];
     assertNotInsideRulerDir(projectRoot);
-    const agents = argv.agents
-        ? argv.agents.split(',').map((a) => a.trim())
-        : undefined;
     const configPath = argv.config;
     const mcpEnabled = argv.mcp;
     const mcpStrategy = argv['mcp-overwrite']
@@ -85,27 +111,6 @@ async function applyHandler(argv) {
     else {
         gitignoreLocalPreference = undefined; // Let TOML/default decide
     }
-    // Determine nested preference: CLI > TOML > Default (false)
-    let nested;
-    if (argv.nested !== undefined) {
-        // CLI explicitly set nested (either --nested or --no-nested)
-        nested = argv.nested;
-    }
-    else {
-        // CLI didn't set nested, check TOML configuration
-        try {
-            const config = await (0, ConfigLoader_1.loadConfig)({
-                projectRoot,
-                configPath,
-            });
-            // Use TOML setting if available, otherwise default to false
-            nested = config.nested ?? false;
-        }
-        catch {
-            // If config loading fails, use default (false)
-            nested = false;
-        }
-    }
     // Determine skills preference: CLI > TOML > Default (enabled)
     let skillsEnabled;
     if (argv.skills !== undefined) {
@@ -123,12 +128,15 @@ async function applyHandler(argv) {
         subagentsEnabled = undefined; // Let config/default decide
     }
     try {
+        const agents = parseCliAgents(argv.agents);
+        // Determine nested preference: CLI > TOML > Default (false)
+        const nested = await resolveNestedPreference(argv, projectRoot, configPath, localOnly);
         await (0, lib_1.applyAllAgentConfigs)(projectRoot, agents, configPath, mcpEnabled, mcpStrategy, gitignorePreference, verbose, dryRun, localOnly, nested, backup, skillsEnabled, gitignoreLocalPreference, subagentsEnabled);
         console.log('Ruler apply completed successfully.');
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        console.error(formatCliError(message));
         process.exit(1);
     }
 }
@@ -138,23 +146,24 @@ async function applyHandler(argv) {
 async function initHandler(argv) {
     const projectRoot = argv['project-root'];
     const isGlobal = argv['global'];
-    const rulerDir = isGlobal
-        ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
-        : path.join(projectRoot, '.ruler');
-    await fs.mkdir(rulerDir, { recursive: true });
-    const instructionsPath = path.join(rulerDir, constants_1.DEFAULT_RULES_FILENAME); // .ruler/AGENTS.md
-    const tomlPath = path.join(rulerDir, 'ruler.toml');
-    const exists = async (p) => {
-        try {
-            await fs.access(p);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    };
-    const DEFAULT_INSTRUCTIONS = `# AGENTS.md\n\nCentralised AI agent instructions. Add coding guidelines, style guides, and project context here.\n\nRuler concatenates all .md files in this directory (and subdirectories), starting with AGENTS.md (if present), then remaining files in sorted order.\n`;
-    const DEFAULT_TOML = `# Ruler Configuration File
+    try {
+        const rulerDir = isGlobal
+            ? path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'ruler')
+            : path.join(projectRoot, '.ruler');
+        await fs.mkdir(rulerDir, { recursive: true });
+        const instructionsPath = path.join(rulerDir, constants_1.DEFAULT_RULES_FILENAME); // .ruler/AGENTS.md
+        const tomlPath = path.join(rulerDir, 'ruler.toml');
+        const exists = async (p) => {
+            try {
+                await fs.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        const DEFAULT_INSTRUCTIONS = `# AGENTS.md\n\nCentralised AI agent instructions. Add coding guidelines, style guides, and project context here.\n\nRuler concatenates all .md files in this directory (and subdirectories), starting with AGENTS.md (if present), then remaining files in sorted order.\n`;
+        const DEFAULT_TOML = `# Ruler Configuration File
 # See https://ai.intellectronica.net/ruler for documentation.
 
 # To specify which agents are active by default when --agents is not used,
@@ -169,6 +178,9 @@ async function initHandler(argv) {
 # enabled = true
 # local = false  # set true to write generated ignores to .git/info/exclude instead
 
+# [backup]
+# enabled = true  # set false to disable .bak backup files
+
 # --- Agent Specific Configurations ---
 # You can enable/disable agents and override their default output paths here.
 # Use lowercase agent identifiers: aider, amp, claude, cline, codex, copilot, cursor, jetbrains-ai, kilocode, pi, windsurf
@@ -199,20 +211,26 @@ async function initHandler(argv) {
 # url = "https://api.example.com/mcp"
 # headers = { Authorization = "Bearer REPLACE_ME" }
 `;
-    if (!(await exists(instructionsPath))) {
-        // Create new AGENTS.md regardless of legacy presence.
-        await fs.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
-        console.log(`[ruler] Created ${instructionsPath}`);
-    }
-    else {
-        console.log(`[ruler] ${constants_1.DEFAULT_RULES_FILENAME} already exists, skipping`);
-    }
-    if (!(await exists(tomlPath))) {
-        await fs.writeFile(tomlPath, DEFAULT_TOML);
-        console.log(`[ruler] Created ${tomlPath}`);
+        if (!(await exists(instructionsPath))) {
+            // Create new AGENTS.md regardless of legacy presence.
+            await fs.writeFile(instructionsPath, DEFAULT_INSTRUCTIONS);
+            console.log(`[ruler] Created ${instructionsPath}`);
+        }
+        else {
+            console.log(`[ruler] ${constants_1.DEFAULT_RULES_FILENAME} already exists, skipping`);
+        }
+        if (!(await exists(tomlPath))) {
+            await fs.writeFile(tomlPath, DEFAULT_TOML);
+            console.log(`[ruler] Created ${tomlPath}`);
+        }
+        else {
+            console.log(`[ruler] ruler.toml already exists, skipping`);
+        }
     }
-    else {
-        console.log(`[ruler] ruler.toml already exists, skipping`);
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(formatCliError(message));
+        process.exit(1);
     }
 }
 /**
@@ -221,20 +239,18 @@ async function initHandler(argv) {
 async function revertHandler(argv) {
     const projectRoot = argv['project-root'];
     assertNotInsideRulerDir(projectRoot);
-    const agents = argv.agents
-        ? argv.agents.split(',').map((a) => a.trim())
-        : undefined;
     const configPath = argv.config;
     const keepBackups = argv['keep-backups'];
     const verbose = argv.verbose;
     const dryRun = argv['dry-run'];
     const localOnly = argv['local-only'];
     try {
+        const agents = parseCliAgents(argv.agents);
         await (0, revert_1.revertAllAgentConfigs)(projectRoot, agents, configPath, keepBackups, verbose, dryRun, localOnly);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`${constants_1.ERROR_PREFIX} ${message}`);
+        console.error(formatCliError(message));
         process.exit(1);
     }
 }

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/constants.d.ts

@@ -0,0 +1,35 @@
+export declare const ERROR_PREFIX = "[ruler]";
+export declare const DEFAULT_RULES_FILENAME = "AGENTS.md";
+export declare function actionPrefix(dry: boolean): string;
+export declare function createRulerError(message: string, context?: string): Error;
+export declare function logVerbose(message: string, isVerbose: boolean): void;
+/**
+ * Centralized logging functions with consistent output streams and prefixing.
+ * - info/verbose go to stdout (user-visible progress)
+ * - warn/error go to stderr (problems)
+ */
+export declare function logInfo(message: string, dryRun?: boolean): void;
+export declare function logWarn(message: string, dryRun?: boolean): void;
+export declare function logError(message: string, dryRun?: boolean): void;
+export declare function logVerboseInfo(message: string, isVerbose: boolean, dryRun?: boolean): void;
+export declare const SKILLS_DIR = "skills";
+export declare const RULER_SKILLS_PATH = ".ruler/skills";
+export declare const CLAUDE_SKILLS_PATH = ".claude/skills";
+export declare const CODEX_SKILLS_PATH = ".agents/skills";
+export declare const OPENCODE_SKILLS_PATH = ".opencode/skills";
+export declare const PI_SKILLS_PATH = ".pi/skills";
+export declare const GOOSE_SKILLS_PATH = ".agents/skills";
+export declare const VIBE_SKILLS_PATH = ".vibe/skills";
+export declare const ROO_SKILLS_PATH = ".roo/skills";
+export declare const GEMINI_SKILLS_PATH = ".gemini/skills";
+export declare const JUNIE_SKILLS_PATH = ".junie/skills";
+export declare const CURSOR_SKILLS_PATH = ".cursor/skills";
+export declare const WINDSURF_SKILLS_PATH = ".windsurf/skills";
+export declare const FACTORY_SKILLS_PATH = ".factory/skills";
+export declare const ANTIGRAVITY_SKILLS_PATH = ".agent/skills";
+export declare const SKILL_MD_FILENAME = "SKILL.md";
+export declare const RULER_SUBAGENTS_PATH = ".ruler/agents";
+export declare const CLAUDE_SUBAGENTS_PATH = ".claude/agents";
+export declare const CURSOR_SUBAGENTS_PATH = ".cursor/agents";
+export declare const CODEX_SUBAGENTS_PATH = ".codex/agents";
+export declare const COPILOT_SUBAGENTS_PATH = ".github/agents";

package/dist/constants.js

@@ -53,7 +53,7 @@ function logVerboseInfo(message, isVerbose, dryRun = false) {
 exports.SKILLS_DIR = 'skills';
 exports.RULER_SKILLS_PATH = '.ruler/skills';
 exports.CLAUDE_SKILLS_PATH = '.claude/skills';
-exports.CODEX_SKILLS_PATH = '.codex/skills';
+exports.CODEX_SKILLS_PATH = '.agents/skills';
 exports.OPENCODE_SKILLS_PATH = '.opencode/skills';
 exports.PI_SKILLS_PATH = '.pi/skills';
 exports.GOOSE_SKILLS_PATH = '.agents/skills';

package/dist/core/ConfigLoader.d.ts

@@ -0,0 +1,59 @@
+import { McpConfig, GlobalMcpConfig, GitignoreConfig, BackupConfig, SkillsConfig, SubagentsConfig } from '../types';
+/** Test helper — re-arms the deprecation guard so suites can assert it fires. */
+export declare function _resetLegacySubagentsWarningForTests(): void;
+/**
+ * Configuration for a specific agent as defined in ruler.toml.
+ */
+export interface IAgentConfig {
+    enabled?: boolean;
+    outputPath?: string;
+    outputPathInstructions?: string;
+    outputPathConfig?: string;
+    /** MCP propagation config for this agent. */
+    mcp?: McpConfig;
+    /** Agent-scoped MCP server definitions. */
+    mcpServers?: Record<string, Record<string, unknown>>;
+}
+/**
+ * Parsed ruler configuration values.
+ */
+export interface LoadedConfig {
+    /** Agents to run by default, as specified by default_agents. */
+    defaultAgents?: string[];
+    /** Per-agent configuration overrides. */
+    agentConfigs: Record<string, IAgentConfig>;
+    /** Command-line agent filters (--agents), if provided. */
+    cliAgents?: string[];
+    /** Global MCP servers configuration section. */
+    mcp?: GlobalMcpConfig;
+    /** Gitignore configuration section. */
+    gitignore?: GitignoreConfig;
+    /** Backup configuration section. */
+    backup?: BackupConfig;
+    /** Skills configuration section. */
+    skills?: SkillsConfig;
+    /** Subagents configuration section. */
+    subagents?: SubagentsConfig;
+    /** Whether to enable nested rule loading from nested .ruler directories. */
+    nested?: boolean;
+    /** Whether the nested option was explicitly provided in the config. */
+    nestedDefined?: boolean;
+}
+/**
+ * Options for loading the ruler configuration.
+ */
+export interface ConfigOptions {
+    projectRoot: string;
+    /** Path to a custom TOML config file. */
+    configPath?: string;
+    /** CLI filters from --agents option. */
+    cliAgents?: string[];
+    /** Whether implicit config discovery may fall back to XDG_CONFIG_HOME/ruler. */
+    checkGlobal?: boolean;
+}
+/**
+ * Loads and parses the ruler TOML configuration file, applying defaults.
+ * Missing implicit configs return defaults. Explicit configs and existing
+ * implicit configs fail fast when missing, unreadable, or invalid.
+ */
+export declare function loadConfig(options: ConfigOptions): Promise<LoadedConfig>;