@intellectronica/ruler 0.3.10 → 0.3.12

package/dist/core/ConfigLoader.js

@@ -69,8 +69,34 @@ const rulerConfigSchema = zod_1.z.object({
         enabled: zod_1.z.boolean().optional(),
     })
         .optional(),
+    skills: zod_1.z
+        .object({
+        enabled: zod_1.z.boolean().optional(),
+    })
+        .optional(),
     nested: zod_1.z.boolean().optional(),
 });
+/**
+ * Recursively creates a new object with only enumerable string keys,
+ * effectively excluding Symbol properties.
+ * The @iarna/toml parser adds Symbol properties (Symbol(type), Symbol(declared))
+ * for metadata, which Zod v4+ validates and rejects as invalid record keys.
+ * By rebuilding the object structure using Object.keys(), we create clean objects
+ * that only contain the actual data without Symbol metadata.
+ */
+function stripSymbols(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(stripSymbols);
+    }
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        result[key] = stripSymbols(obj[key]);
+    }
+    return result;
+}
 /**
  * Loads and parses the ruler TOML configuration file, applying defaults.
  * If the file is missing or invalid, returns empty/default config.
@@ -97,7 +123,9 @@ async function loadConfig(options) {
     let raw = {};
     try {
         const text = await fs_1.promises.readFile(configFile, 'utf8');
-        raw = text.trim() ? (0, toml_1.parse)(text) : {};
+        const parsed = text.trim() ? (0, toml_1.parse)(text) : {};
+        // Strip Symbol properties added by @iarna/toml (required for Zod v4+)
+        raw = stripSymbols(parsed);
         // Validate the configuration with zod
         const validationResult = rulerConfigSchema.safeParse(raw);
         if (!validationResult.success) {
@@ -175,13 +203,23 @@ async function loadConfig(options) {
     if (typeof rawGitignoreSection.enabled === 'boolean') {
         gitignoreConfig.enabled = rawGitignoreSection.enabled;
     }
-    const nested = typeof raw.nested === 'boolean' ? raw.nested : false;
+    const rawSkillsSection = raw.skills && typeof raw.skills === 'object' && !Array.isArray(raw.skills)
+        ? raw.skills
+        : {};
+    const skillsConfig = {};
+    if (typeof rawSkillsSection.enabled === 'boolean') {
+        skillsConfig.enabled = rawSkillsSection.enabled;
+    }
+    const nestedDefined = typeof raw.nested === 'boolean';
+    const nested = nestedDefined ? raw.nested : false;
     return {
         defaultAgents,
         agentConfigs,
         cliAgents,
         mcp: globalMcpConfig,
         gitignore: gitignoreConfig,
+        skills: skillsConfig,
         nested,
+        nestedDefined,
     };
 }

package/dist/core/SkillsProcessor.js

@@ -0,0 +1,301 @@
+"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.discoverSkills = discoverSkills;
+exports.getSkillsGitignorePaths = getSkillsGitignorePaths;
+exports.propagateSkills = propagateSkills;
+exports.propagateSkillsForClaude = propagateSkillsForClaude;
+exports.propagateSkillsForSkillz = propagateSkillsForSkillz;
+exports.buildSkillzMcpConfig = buildSkillzMcpConfig;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const constants_1 = require("../constants");
+const SkillsUtils_1 = require("./SkillsUtils");
+/**
+ * Discovers skills in the project's .ruler/skills directory.
+ * Returns discovered skills and any validation warnings.
+ */
+async function discoverSkills(projectRoot) {
+    const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    // Check if skills directory exists
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        // Skills directory doesn't exist - this is fine, just return empty
+        return { skills: [], warnings: [] };
+    }
+    // Walk the skills tree
+    return await (0, SkillsUtils_1.walkSkillsTree)(skillsDir);
+}
+/**
+ * Gets the paths that skills will generate, for gitignore purposes.
+ * Returns empty array if skills directory doesn't exist.
+ */
+async function getSkillsGitignorePaths(projectRoot) {
+    const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    // Check if skills directory exists
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    // Import here to avoid circular dependency
+    const { CLAUDE_SKILLS_PATH, SKILLZ_DIR } = await Promise.resolve().then(() => __importStar(require('../constants')));
+    return [
+        path.join(projectRoot, CLAUDE_SKILLS_PATH),
+        path.join(projectRoot, SKILLZ_DIR),
+    ];
+}
+/**
+ * Module-level state to track if experimental warning has been shown.
+ * This ensures the warning appears once per process (CLI invocation), not once per apply call.
+ * This is intentional: warnings about experimental features should not spam the user
+ * if they run multiple applies in the same process or test suite.
+ */
+let hasWarnedExperimental = false;
+/**
+ * Warns once per process about experimental skills features and uv requirement.
+ * Uses module-level state to prevent duplicate warnings within the same process.
+ */
+function warnOnceExperimentalAndUv(verbose, dryRun) {
+    if (hasWarnedExperimental) {
+        return;
+    }
+    hasWarnedExperimental = true;
+    (0, constants_1.logWarn)('Skills support is experimental and behavior may change in future releases.', dryRun);
+    (0, constants_1.logWarn)('Skills MCP server (Skillz) requires uv. Install: https://github.com/astral-sh/uv', dryRun);
+}
+/**
+ * Cleans up skills directories (.claude/skills and .skillz) when skills are disabled.
+ * This ensures that stale skills from previous runs don't persist when skills are turned off.
+ */
+async function cleanupSkillsDirectories(projectRoot, dryRun, verbose) {
+    const claudeSkillsPath = path.join(projectRoot, constants_1.CLAUDE_SKILLS_PATH);
+    const skillzPath = path.join(projectRoot, constants_1.SKILLZ_DIR);
+    // Clean up .claude/skills
+    try {
+        await fs.access(claudeSkillsPath);
+        if (dryRun) {
+            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.CLAUDE_SKILLS_PATH}`, verbose, dryRun);
+        }
+        else {
+            await fs.rm(claudeSkillsPath, { recursive: true, force: true });
+            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.CLAUDE_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
+        }
+    }
+    catch {
+        // Directory doesn't exist, nothing to clean
+    }
+    // Clean up .skillz
+    try {
+        await fs.access(skillzPath);
+        if (dryRun) {
+            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.SKILLZ_DIR}`, verbose, dryRun);
+        }
+        else {
+            await fs.rm(skillzPath, { recursive: true, force: true });
+            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.SKILLZ_DIR} (skills disabled)`, verbose, dryRun);
+        }
+    }
+    catch {
+        // Directory doesn't exist, nothing to clean
+    }
+}
+/**
+ * Propagates skills for agents that need them.
+ */
+async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryRun) {
+    if (!skillsEnabled) {
+        (0, constants_1.logVerboseInfo)('Skills support disabled, cleaning up skills directories', verbose, dryRun);
+        // Clean up skills directories when skills are disabled
+        await cleanupSkillsDirectories(projectRoot, dryRun, verbose);
+        return;
+    }
+    const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    // Check if skills directory exists
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        // No skills directory - this is fine
+        (0, constants_1.logVerboseInfo)('No .ruler/skills directory found, skipping skills propagation', verbose, dryRun);
+        return;
+    }
+    // Discover skills
+    const { skills, warnings } = await discoverSkills(projectRoot);
+    if (warnings.length > 0) {
+        warnings.forEach((warning) => (0, constants_1.logWarn)(warning, dryRun));
+    }
+    if (skills.length === 0) {
+        (0, constants_1.logVerboseInfo)('No valid skills found in .ruler/skills', verbose, dryRun);
+        return;
+    }
+    (0, constants_1.logVerboseInfo)(`Discovered ${skills.length} skill(s)`, verbose, dryRun);
+    // Check if any agents need skills
+    const hasNativeSkillsAgent = agents.some((a) => a.supportsNativeSkills?.());
+    const hasMcpAgent = agents.some((a) => a.supportsMcpStdio?.() && !a.supportsNativeSkills?.());
+    if (!hasNativeSkillsAgent && !hasMcpAgent) {
+        (0, constants_1.logVerboseInfo)('No agents require skills support', verbose, dryRun);
+        return;
+    }
+    // Warn about experimental features
+    if (hasMcpAgent) {
+        warnOnceExperimentalAndUv(verbose, dryRun);
+    }
+    // Copy to Claude skills directory if needed
+    if (hasNativeSkillsAgent) {
+        (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.CLAUDE_SKILLS_PATH} for Claude Code`, verbose, dryRun);
+        await propagateSkillsForClaude(projectRoot, { dryRun });
+    }
+    // Copy to .skillz directory if needed
+    if (hasMcpAgent) {
+        (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.SKILLZ_DIR} for MCP agents`, verbose, dryRun);
+        await propagateSkillsForSkillz(projectRoot, { dryRun });
+    }
+}
+/**
+ * Propagates skills for Claude Code by copying .ruler/skills to .claude/skills.
+ * Uses atomic replace to ensure safe overwriting of existing skills.
+ * Returns dry-run steps if dryRun is true, otherwise returns empty array.
+ */
+async function propagateSkillsForClaude(projectRoot, options) {
+    const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    const claudeSkillsPath = path.join(projectRoot, constants_1.CLAUDE_SKILLS_PATH);
+    const claudeDir = path.dirname(claudeSkillsPath);
+    // Check if source skills directory exists
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        // No skills directory - return empty
+        return [];
+    }
+    if (options.dryRun) {
+        return [`Copy skills from ${constants_1.RULER_SKILLS_PATH} to ${constants_1.CLAUDE_SKILLS_PATH}`];
+    }
+    // Ensure .claude directory exists
+    await fs.mkdir(claudeDir, { recursive: true });
+    // Use atomic replace: copy to temp, then rename
+    const tempDir = path.join(claudeDir, `skills.tmp-${Date.now()}`);
+    try {
+        // Copy to temp directory
+        await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
+        // Atomically replace the target
+        // First, remove existing target if it exists
+        try {
+            await fs.rm(claudeSkillsPath, { recursive: true, force: true });
+        }
+        catch {
+            // Target didn't exist, that's fine
+        }
+        // Rename temp to target
+        await fs.rename(tempDir, claudeSkillsPath);
+    }
+    catch (error) {
+        // Clean up temp directory on error
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+    return [];
+}
+/**
+ * Propagates skills for MCP agents by copying .ruler/skills to .skillz.
+ * Uses atomic replace to ensure safe overwriting of existing skills.
+ * Returns dry-run steps if dryRun is true, otherwise returns empty array.
+ */
+async function propagateSkillsForSkillz(projectRoot, options) {
+    const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    const skillzPath = path.join(projectRoot, constants_1.SKILLZ_DIR);
+    // Check if source skills directory exists
+    try {
+        await fs.access(skillsDir);
+    }
+    catch {
+        // No skills directory - return empty
+        return [];
+    }
+    if (options.dryRun) {
+        return [
+            `Copy skills from ${constants_1.RULER_SKILLS_PATH} to ${constants_1.SKILLZ_DIR}`,
+            `Configure Skillz MCP server with absolute path to ${constants_1.SKILLZ_DIR}`,
+        ];
+    }
+    // Use atomic replace: copy to temp, then rename
+    const tempDir = path.join(projectRoot, `${constants_1.SKILLZ_DIR}.tmp-${Date.now()}`);
+    try {
+        // Copy to temp directory
+        await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
+        // Atomically replace the target
+        // First, remove existing target if it exists
+        try {
+            await fs.rm(skillzPath, { recursive: true, force: true });
+        }
+        catch {
+            // Target didn't exist, that's fine
+        }
+        // Rename temp to target
+        await fs.rename(tempDir, skillzPath);
+    }
+    catch (error) {
+        // Clean up temp directory on error
+        try {
+            await fs.rm(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+    return [];
+}
+/**
+ * Builds MCP config for Skillz server.
+ */
+function buildSkillzMcpConfig(projectRoot) {
+    const skillzAbsPath = path.resolve(projectRoot, constants_1.SKILLZ_DIR);
+    return {
+        [constants_1.SKILLZ_MCP_SERVER_NAME]: {
+            command: 'uvx',
+            args: ['skillz@latest', skillzAbsPath],
+        },
+    };
+}

package/dist/core/SkillsUtils.js

@@ -0,0 +1,161 @@
+"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.hasSkillMd = hasSkillMd;
+exports.isGroupingDir = isGroupingDir;
+exports.walkSkillsTree = walkSkillsTree;
+exports.formatValidationWarnings = formatValidationWarnings;
+exports.copySkillsDirectory = copySkillsDirectory;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const constants_1 = require("../constants");
+/**
+ * Checks if a directory contains a SKILL.md file.
+ */
+async function hasSkillMd(dirPath) {
+    try {
+        const skillMdPath = path.join(dirPath, constants_1.SKILL_MD_FILENAME);
+        await fs.access(skillMdPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if a directory is a grouping directory (contains subdirectories with SKILL.md).
+ */
+async function isGroupingDir(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        const subdirs = entries.filter((e) => e.isDirectory());
+        for (const subdir of subdirs) {
+            const subdirPath = path.join(dirPath, subdir.name);
+            if (await hasSkillMd(subdirPath)) {
+                return true;
+            }
+            // Check recursively for nested grouping
+            if (await isGroupingDir(subdirPath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walks the skills tree and discovers all skills.
+ * Returns skills and any validation warnings.
+ */
+async function walkSkillsTree(root) {
+    const skills = [];
+    const warnings = [];
+    async function walk(currentPath, relativePath) {
+        try {
+            const entries = await fs.readdir(currentPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const entryPath = path.join(currentPath, entry.name);
+                const entryRelativePath = relativePath
+                    ? path.join(relativePath, entry.name)
+                    : entry.name;
+                const hasSkill = await hasSkillMd(entryPath);
+                const isGrouping = !hasSkill && (await isGroupingDir(entryPath));
+                if (hasSkill) {
+                    // This is a valid skill directory
+                    skills.push({
+                        name: entry.name,
+                        path: entryPath,
+                        hasSkillMd: true,
+                        valid: true,
+                    });
+                }
+                else if (isGrouping) {
+                    // This is a grouping directory, recurse into it
+                    await walk(entryPath, entryRelativePath);
+                }
+                else {
+                    // This is neither a skill nor a grouping directory - warn about it
+                    warnings.push(`Directory '${entryRelativePath}' in .ruler/skills has no SKILL.md and contains no sub-skills. It may be malformed or stray.`);
+                }
+            }
+        }
+        catch (err) {
+            // If we can't read the directory, just return what we have
+            warnings.push(`Failed to read directory ${relativePath || 'root'}: ${err.message}`);
+        }
+    }
+    await walk(root, '');
+    return { skills, warnings };
+}
+/**
+ * Formats validation warnings for display.
+ */
+function formatValidationWarnings(warnings) {
+    if (warnings.length === 0) {
+        return '';
+    }
+    return warnings.map((w) => `  - ${w}`).join('\n');
+}
+/**
+ * Recursively copies a directory and all its contents.
+ */
+async function copyRecursive(src, dest) {
+    const stat = await fs.stat(src);
+    if (stat.isDirectory()) {
+        await fs.mkdir(dest, { recursive: true });
+        const entries = await fs.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            await copyRecursive(srcPath, destPath);
+        }
+    }
+    else {
+        await fs.copyFile(src, dest);
+    }
+}
+/**
+ * Copies the skills directory to the destination, preserving structure.
+ * Creates the destination directory if it doesn't exist.
+ */
+async function copySkillsDirectory(srcDir, destDir) {
+    await fs.mkdir(destDir, { recursive: true });
+    await copyRecursive(srcDir, destDir);
+}

package/dist/core/UnifiedConfigLoader.js

@@ -85,12 +85,24 @@ async function loadUnifiedConfig(options) {
         typeof tomlRaw.nested === 'boolean') {
         nested = tomlRaw.nested;
     }
+    // Parse skills configuration
+    let skillsConfig;
+    if (tomlRaw && typeof tomlRaw === 'object') {
+        const skillsSection = tomlRaw.skills;
+        if (skillsSection && typeof skillsSection === 'object') {
+            const skillsObj = skillsSection;
+            if (typeof skillsObj.enabled === 'boolean') {
+                skillsConfig = { enabled: skillsObj.enabled };
+            }
+        }
+    }
     const toml = {
         raw: tomlRaw,
         schemaVersion: 1,
         agents: {},
         defaultAgents,
         nested,
+        skills: skillsConfig,
     };
     // Collect rule markdown files
     let ruleFiles = [];