skiller 0.4.3

package/dist/core/SkillsProcessor.js

@@ -0,0 +1,528 @@
+"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.generateSkillsFromRules = generateSkillsFromRules;
+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");
+const FrontmatterParser_1 = require("./FrontmatterParser");
+/**
+ * Discovers skills in the project's skills directory (.ruler/skills or .claude/skills).
+ * Returns discovered skills and any validation warnings.
+ */
+async function discoverSkills(projectRoot, rulerDir) {
+    // Determine skills directory based on rulerDir
+    let skillsPath;
+    if (rulerDir && path.basename(rulerDir) === '.claude') {
+        // Use .claude/skills
+        skillsPath = path.join(rulerDir, 'skills');
+    }
+    else {
+        // Use .ruler/skills (default)
+        skillsPath = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    }
+    // Check if skills directory exists
+    try {
+        await fs.access(skillsPath);
+    }
+    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)(skillsPath);
+}
+/**
+ * Gets the paths that skills will generate, for gitignore purposes.
+ * Returns empty array if skills directory doesn't exist.
+ */
+async function getSkillsGitignorePaths(projectRoot) {
+    const rulerSkillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
+    const claudeSkillsDir = path.join(projectRoot, '.claude', 'skills');
+    // Check if skills directory exists in either location
+    let isClaudeMode = false;
+    let skillsExist = false;
+    try {
+        await fs.access(rulerSkillsDir);
+        skillsExist = true;
+        isClaudeMode = false;
+    }
+    catch {
+        // Try .claude/skills
+        try {
+            await fs.access(claudeSkillsDir);
+            skillsExist = true;
+            isClaudeMode = true;
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!skillsExist) {
+        return [];
+    }
+    // Import here to avoid circular dependency
+    const { CLAUDE_SKILLS_PATH, SKILLZ_DIR } = await Promise.resolve().then(() => __importStar(require('../constants')));
+    const paths = [];
+    // When using .claude/skills, check if it's generated from .claude/rules
+    if (isClaudeMode) {
+        // If .claude/rules exists, then .claude/skills is generated and should be gitignored
+        const claudeRulesDir = path.join(projectRoot, '.claude', 'rules');
+        try {
+            await fs.access(claudeRulesDir);
+            // .claude/rules exists, so .claude/skills is generated
+            paths.push(path.join(projectRoot, CLAUDE_SKILLS_PATH));
+        }
+        catch {
+            // .claude/rules doesn't exist, so .claude/skills is versioned (don't gitignore)
+        }
+    }
+    else {
+        // Using .ruler/skills - gitignore .claude/skills (generated copy)
+        paths.push(path.join(projectRoot, CLAUDE_SKILLS_PATH));
+    }
+    // Always gitignore .skillz (for MCP agents)
+    paths.push(path.join(projectRoot, SKILLZ_DIR));
+    return paths;
+}
+/**
+ * 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.
+ */
+// Currently unused but kept for potential future use
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+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);
+}
+/**
+ * Recursively finds all .mdc files in a directory.
+ */
+async function findMdcFiles(dir) {
+    const mdcFiles = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // Skip skills directory to avoid processing generated files
+                if (entry.name !== 'skills') {
+                    const subFiles = await findMdcFiles(fullPath);
+                    mdcFiles.push(...subFiles);
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith('.mdc')) {
+                mdcFiles.push(fullPath);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read, return empty
+    }
+    return mdcFiles;
+}
+/**
+ * Generates skills from .mdc rule files with frontmatter.
+ * Creates skill files in the skills directory with @filename references to the original .mdc files.
+ */
+async function generateSkillsFromRules(projectRoot, rulerDir, verbose, dryRun) {
+    // Determine skills directory based on rulerDir
+    const skillsDir = path.join(rulerDir, 'skills');
+    // Find all .mdc files in the ruler directory
+    const mdcFiles = await findMdcFiles(rulerDir);
+    if (mdcFiles.length === 0) {
+        (0, constants_1.logVerboseInfo)('No .mdc files found for skill generation', verbose, dryRun);
+        return;
+    }
+    let generatedCount = 0;
+    const skillsToRemove = [];
+    for (const mdcFile of mdcFiles) {
+        // Read file content
+        const content = await fs.readFile(mdcFile, 'utf8');
+        // Parse frontmatter
+        const { frontmatter } = (0, FrontmatterParser_1.parseFrontmatter)(content);
+        // Skip files without frontmatter
+        if (!frontmatter || Object.keys(frontmatter).length === 0) {
+            continue;
+        }
+        // Derive skill name from filename (without extension)
+        const fileName = path.basename(mdcFile, '.mdc');
+        // If alwaysApply: true, mark any existing skill for removal
+        if (frontmatter.alwaysApply === true) {
+            skillsToRemove.push(fileName);
+            continue;
+        }
+        // Build description with globs sentence
+        let description = frontmatter.description || `Generated from ${fileName}.mdc`;
+        if (frontmatter.globs && frontmatter.globs.length > 0) {
+            const globsText = frontmatter.globs.join(', ');
+            description += ` Applies to files matching: ${globsText}.`;
+        }
+        // Create skill directory
+        const skillDir = path.join(skillsDir, fileName);
+        const skillFile = path.join(skillDir, 'SKILL.md');
+        // Generate @filename reference to the original .mdc file (relative to projectRoot)
+        const relativeToProject = path
+            .relative(projectRoot, mdcFile)
+            .replace(/\\/g, '/');
+        const fileReference = `@${relativeToProject}`;
+        // Generate skill content with frontmatter
+        const skillContent = `---
+name: ${fileName}
+description: ${description}
+---
+
+${fileReference}
+`;
+        if (dryRun) {
+            (0, constants_1.logVerboseInfo)(`DRY RUN: Would generate skill ${fileName} from ${path.relative(projectRoot, mdcFile)}`, verbose, dryRun);
+        }
+        else {
+            // Create skill directory and write file
+            await fs.mkdir(skillDir, { recursive: true });
+            await fs.writeFile(skillFile, skillContent, 'utf8');
+            (0, constants_1.logVerboseInfo)(`Generated skill ${fileName} from ${path.relative(projectRoot, mdcFile)}`, verbose, dryRun);
+            // Check if .mdc file is in a folder with the same name
+            // e.g., rules/docx/docx.mdc -> copy all files from rules/docx/ to skills/docx/
+            const mdcDir = path.dirname(mdcFile);
+            const mdcDirName = path.basename(mdcDir);
+            if (mdcDirName === fileName) {
+                // Parent folder matches the file name, copy additional files
+                try {
+                    const entries = await fs.readdir(mdcDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        // Skip the .mdc file itself
+                        if (entry.name === `${fileName}.mdc`) {
+                            continue;
+                        }
+                        const sourcePath = path.join(mdcDir, entry.name);
+                        const targetPath = path.join(skillDir, entry.name);
+                        if (entry.isDirectory()) {
+                            // Recursively copy subdirectories
+                            const { copySkillsDirectory } = await Promise.resolve().then(() => __importStar(require('./SkillsUtils')));
+                            await copySkillsDirectory(sourcePath, targetPath);
+                            (0, constants_1.logVerboseInfo)(`Copied directory ${entry.name} to skill ${fileName}`, verbose, dryRun);
+                        }
+                        else {
+                            // Copy file
+                            await fs.copyFile(sourcePath, targetPath);
+                            (0, constants_1.logVerboseInfo)(`Copied file ${entry.name} to skill ${fileName}`, verbose, dryRun);
+                        }
+                    }
+                }
+                catch (error) {
+                    // If we can't read the directory, just skip copying additional files
+                    (0, constants_1.logVerboseInfo)(`Could not copy additional files for skill ${fileName}: ${error}`, verbose, dryRun);
+                }
+            }
+        }
+        generatedCount++;
+    }
+    if (generatedCount > 0) {
+        (0, constants_1.logVerboseInfo)(`Generated ${generatedCount} skill(s) from .mdc files`, verbose, dryRun);
+    }
+    // Remove skills for .mdc files that now have alwaysApply: true
+    if (skillsToRemove.length > 0) {
+        for (const skillName of skillsToRemove) {
+            const skillPath = path.join(skillsDir, skillName);
+            try {
+                const exists = await fs
+                    .access(skillPath)
+                    .then(() => true)
+                    .catch(() => false);
+                if (exists) {
+                    if (dryRun) {
+                        (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove skill ${skillName} (alwaysApply changed to true)`, verbose, dryRun);
+                    }
+                    else {
+                        await fs.rm(skillPath, { recursive: true, force: true });
+                        (0, constants_1.logVerboseInfo)(`Removed skill ${skillName} (alwaysApply changed to true)`, verbose, dryRun);
+                    }
+                }
+            }
+            catch {
+                // Ignore errors - skill might not exist
+            }
+        }
+    }
+}
+/**
+ * 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, rulerDir) {
+    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;
+    }
+    // Determine skills directory based on rulerDir
+    let skillsDir;
+    if (rulerDir && path.basename(rulerDir) === '.claude') {
+        skillsDir = path.join(rulerDir, 'skills');
+    }
+    else {
+        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
+        const dirName = rulerDir && path.basename(rulerDir) === '.claude'
+            ? '.claude/skills'
+            : '.ruler/skills';
+        (0, constants_1.logVerboseInfo)(`No ${dirName} directory found, skipping skills propagation`, verbose, dryRun);
+        return;
+    }
+    // Discover skills
+    const { skills, warnings } = await discoverSkills(projectRoot, rulerDir);
+    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?.());
+    // Only add skillz for agents that support MCP stdio but not native skills
+    // Claude Code and Cursor are excluded because they have native skills support
+    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) {
+        const isClaudeRoot = rulerDir && path.basename(rulerDir) === '.claude';
+        if (!isClaudeRoot) {
+            (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.CLAUDE_SKILLS_PATH} for Claude Code`, verbose, dryRun);
+        }
+        await propagateSkillsForClaude(projectRoot, { dryRun, rulerDir });
+    }
+    // Copy to .skillz directory if needed
+    if (hasMcpAgent) {
+        (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.SKILLZ_DIR} for MCP agents without native skills support`, verbose, dryRun);
+        await propagateSkillsForSkillz(projectRoot, { dryRun, rulerDir });
+    }
+}
+/**
+ * Propagates skills for Claude Code by copying .ruler/skills to .claude/skills.
+ * If rulerDir is .claude, skills are already in the right place, so no copy is needed.
+ * 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) {
+    // If using .claude as the root folder, skills are already in .claude/skills
+    const isClaudeRoot = options.rulerDir && path.basename(options.rulerDir) === '.claude';
+    if (isClaudeRoot) {
+        // No need to copy, skills are already in .claude/skills
+        return [];
+    }
+    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 skills to .skillz.
+ * Supports both .ruler/skills and .claude/skills as source.
+ * 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) {
+    // Determine source skills directory based on rulerDir
+    const isClaudeRoot = options.rulerDir && path.basename(options.rulerDir) === '.claude';
+    const skillsDir = isClaudeRoot
+        ? path.join(projectRoot, '.claude', 'skills')
+        : 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) {
+        const relativeSkillsPath = path.relative(projectRoot, skillsDir);
+        return [
+            `Copy skills from ${relativeSkillsPath} 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 and transform to temp directory
+        // Transform @filename references to actual content for MCP agents
+        const { copySkillsDirectoryWithTransform } = await Promise.resolve().then(() => __importStar(require('./SkillsUtils')));
+        await copySkillsDirectoryWithTransform(skillsDir, tempDir, projectRoot);
+        // 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],
+        },
+    };
+}