@intellectronica/ruler 0.3.41 → 0.3.43

package/dist/core/SkillsProcessor.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.discoverSkills = discoverSkills;
 exports.getSkillsGitignorePaths = getSkillsGitignorePaths;
+exports.replaceSkillsDirectory = replaceSkillsDirectory;
 exports.propagateSkills = propagateSkills;
 exports.propagateSkillsForClaude = propagateSkillsForClaude;
 exports.propagateSkillsForCodex = propagateSkillsForCodex;
@@ -53,6 +54,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs/promises"));
 const constants_1 = require("../constants");
 const SkillsUtils_1 = require("./SkillsUtils");
+const FileSystemUtils_1 = require("./FileSystemUtils");
 /**
  * Discovers skills in the project's .ruler/skills directory.
  * Returns discovered skills and any validation warnings.
@@ -101,7 +103,8 @@ async function getSkillsGitignorePaths(projectRoot, agents) {
         factory: FACTORY_SKILLS_PATH,
         antigravity: ANTIGRAVITY_SKILLS_PATH,
     };
-    return Array.from(selectedTargets).map((target) => path.join(projectRoot, targetPaths[target]));
+    const pathSet = new Set(Array.from(selectedTargets).map((target) => path.join(projectRoot, targetPaths[target])));
+    return Array.from(pathSet);
 }
 /**
  * Module-level state to track if experimental warning has been shown.
@@ -126,7 +129,7 @@ const SKILL_TARGET_TO_IDENTIFIERS = new Map([
     ['codex', ['codex']],
     ['opencode', ['opencode']],
     ['pi', ['pi']],
-    ['goose', ['goose', 'amp']],
+    ['goose', ['goose', 'amp', 'zed']],
     ['vibe', ['mistral']],
     ['roo', ['roo']],
     ['gemini', ['gemini-cli']],
@@ -136,6 +139,21 @@ const SKILL_TARGET_TO_IDENTIFIERS = new Map([
     ['factory', ['factory']],
     ['antigravity', ['antigravity']],
 ]);
+const SKILL_TARGET_PATHS = Array.from(new Set([
+    constants_1.CLAUDE_SKILLS_PATH,
+    constants_1.CODEX_SKILLS_PATH,
+    constants_1.OPENCODE_SKILLS_PATH,
+    constants_1.PI_SKILLS_PATH,
+    constants_1.GOOSE_SKILLS_PATH,
+    constants_1.VIBE_SKILLS_PATH,
+    constants_1.ROO_SKILLS_PATH,
+    constants_1.GEMINI_SKILLS_PATH,
+    constants_1.JUNIE_SKILLS_PATH,
+    constants_1.CURSOR_SKILLS_PATH,
+    constants_1.WINDSURF_SKILLS_PATH,
+    constants_1.FACTORY_SKILLS_PATH,
+    constants_1.ANTIGRAVITY_SKILLS_PATH,
+]));
 function getSelectedSkillTargets(agents) {
     const selectedIdentifiers = new Set(agents
         .filter((agent) => agent.supportsNativeSkills?.())
@@ -148,205 +166,82 @@ function getSelectedSkillTargets(agents) {
     }
     return targets;
 }
-/**
- * Cleans up skills directories 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 codexSkillsPath = path.join(projectRoot, constants_1.CODEX_SKILLS_PATH);
-    const opencodeSkillsPath = path.join(projectRoot, constants_1.OPENCODE_SKILLS_PATH);
-    const piSkillsPath = path.join(projectRoot, constants_1.PI_SKILLS_PATH);
-    const gooseSkillsPath = path.join(projectRoot, constants_1.GOOSE_SKILLS_PATH);
-    const vibeSkillsPath = path.join(projectRoot, constants_1.VIBE_SKILLS_PATH);
-    const rooSkillsPath = path.join(projectRoot, constants_1.ROO_SKILLS_PATH);
-    const geminiSkillsPath = path.join(projectRoot, constants_1.GEMINI_SKILLS_PATH);
-    const junieSkillsPath = path.join(projectRoot, constants_1.JUNIE_SKILLS_PATH);
-    const cursorSkillsPath = path.join(projectRoot, constants_1.CURSOR_SKILLS_PATH);
-    const windsurfSkillsPath = path.join(projectRoot, constants_1.WINDSURF_SKILLS_PATH);
-    const factorySkillsPath = path.join(projectRoot, constants_1.FACTORY_SKILLS_PATH);
-    const antigravitySkillsPath = path.join(projectRoot, constants_1.ANTIGRAVITY_SKILLS_PATH);
-    // 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 .codex/skills
-    try {
-        await fs.access(codexSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.CODEX_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(codexSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.CODEX_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .opencode/skills
-    try {
-        await fs.access(opencodeSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.OPENCODE_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(opencodeSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.OPENCODE_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .pi/skills
-    try {
-        await fs.access(piSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.PI_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(piSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.PI_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .agents/skills
-    try {
-        await fs.access(gooseSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.GOOSE_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(gooseSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.GOOSE_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .vibe/skills
-    try {
-        await fs.access(vibeSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.VIBE_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(vibeSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.VIBE_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .roo/skills
-    try {
-        await fs.access(rooSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.ROO_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(rooSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.ROO_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .gemini/skills
-    try {
-        await fs.access(geminiSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.GEMINI_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(geminiSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.GEMINI_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .junie/skills
+function isMissingPathError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+async function cleanupSkillsDirectory(projectRoot, relativePath, dryRun, verbose) {
+    const targetPath = path.join(projectRoot, relativePath);
     try {
-        await fs.access(junieSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.JUNIE_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(junieSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.JUNIE_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
-    }
-    catch {
-        // Directory doesn't exist, nothing to clean
+        await fs.access(targetPath);
     }
-    // Clean up .cursor/skills
-    try {
-        await fs.access(cursorSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.CURSOR_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(cursorSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.CURSOR_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return;
         }
+        throw error;
     }
-    catch {
-        // Directory doesn't exist, nothing to clean
+    if (dryRun) {
+        (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${relativePath}`, verbose, dryRun);
+        return;
     }
-    // Clean up .windsurf/skills
-    try {
-        await fs.access(windsurfSkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.WINDSURF_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(windsurfSkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.WINDSURF_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
+    await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(targetPath, projectRoot, 'Refusing to remove skills directory through symlinked path');
+    await fs.rm(targetPath, { recursive: true, force: true });
+    (0, constants_1.logVerboseInfo)(`Removed ${relativePath} (skills disabled)`, verbose, dryRun);
+}
+async function createTempSkillsDir(parentDir, containmentRoot) {
+    if (containmentRoot) {
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(parentDir, containmentRoot, 'Refusing to create temporary skills directory through symlinked path');
     }
-    catch {
-        // Directory doesn't exist, nothing to clean
+    return fs.mkdtemp(path.join(parentDir, 'skills.tmp-'));
+}
+const TRANSIENT_RENAME_ERROR_CODES = new Set(['EPERM', 'EBUSY', 'ENOTEMPTY']);
+const RENAME_RETRY_ATTEMPTS = 5;
+const RENAME_RETRY_DELAY_MS = 50;
+function isTransientRenameError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        TRANSIENT_RENAME_ERROR_CODES.has(error.code));
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function replaceSkillsDirectory(tempDir, targetDir, fsOps = fs, containmentRoot) {
+    if (containmentRoot) {
+        await (0, FileSystemUtils_1.assertManagedPathInsideRoot)(targetDir, containmentRoot, 'Refusing to replace skills directory through symlinked path');
     }
-    // Clean up .factory/skills
-    try {
-        await fs.access(factorySkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.FACTORY_SKILLS_PATH}`, verbose, dryRun);
+    let lastError;
+    for (let attempt = 1; attempt <= RENAME_RETRY_ATTEMPTS; attempt += 1) {
+        try {
+            await fsOps.rename(tempDir, targetDir);
+            return;
         }
-        else {
-            await fs.rm(factorySkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.FACTORY_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
+        catch (error) {
+            lastError = error;
+            if (!isTransientRenameError(error) || attempt === RENAME_RETRY_ATTEMPTS) {
+                break;
+            }
+            await wait(RENAME_RETRY_DELAY_MS * attempt);
         }
     }
-    catch {
-        // Directory doesn't exist, nothing to clean
-    }
-    // Clean up .agent/skills
-    try {
-        await fs.access(antigravitySkillsPath);
-        if (dryRun) {
-            (0, constants_1.logVerboseInfo)(`DRY RUN: Would remove ${constants_1.ANTIGRAVITY_SKILLS_PATH}`, verbose, dryRun);
-        }
-        else {
-            await fs.rm(antigravitySkillsPath, { recursive: true, force: true });
-            (0, constants_1.logVerboseInfo)(`Removed ${constants_1.ANTIGRAVITY_SKILLS_PATH} (skills disabled)`, verbose, dryRun);
-        }
+    if (isTransientRenameError(lastError)) {
+        await fsOps.cp(tempDir, targetDir, { recursive: true, force: true });
+        await fsOps.rm(tempDir, { recursive: true, force: true });
+        return;
     }
-    catch {
-        // Directory doesn't exist, nothing to clean
+    throw lastError;
+}
+/**
+ * Cleans up skills directories 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) {
+    for (const skillPath of SKILL_TARGET_PATHS) {
+        await cleanupSkillsDirectory(projectRoot, skillPath, dryRun, verbose);
     }
 }
 /**
@@ -416,7 +311,7 @@ async function propagateSkills(projectRoot, agents, skillsEnabled, verbose, dryR
         await propagateSkillsForPi(projectRoot, { dryRun });
     }
     if (selectedTargets.has('goose')) {
-        (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.GOOSE_SKILLS_PATH} for Goose and Amp`, verbose, dryRun);
+        (0, constants_1.logVerboseInfo)(`Copying skills to ${constants_1.GOOSE_SKILLS_PATH} for Goose, Amp and Zed`, verbose, dryRun);
         await propagateSkillsForGoose(projectRoot, { dryRun });
     }
     if (selectedTargets.has('vibe')) {
@@ -476,7 +371,7 @@ async function propagateSkillsForClaude(projectRoot, options) {
     // 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()}`);
+    const tempDir = await createTempSkillsDir(claudeDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -489,7 +384,7 @@ async function propagateSkillsForClaude(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, claudeSkillsPath);
+        await replaceSkillsDirectory(tempDir, claudeSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -504,14 +399,14 @@ async function propagateSkillsForClaude(projectRoot, options) {
     return [];
 }
 /**
- * Propagates skills for OpenAI Codex CLI by copying .ruler/skills to .codex/skills.
+ * Propagates skills for OpenAI Codex CLI by copying .ruler/skills to .agents/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 propagateSkillsForCodex(projectRoot, options) {
     const skillsDir = path.join(projectRoot, constants_1.RULER_SKILLS_PATH);
-    const codexSkillsPath = path.join(projectRoot, constants_1.CODEX_SKILLS_PATH);
-    const codexDir = path.dirname(codexSkillsPath);
+    const agentsSkillsPath = path.join(projectRoot, constants_1.CODEX_SKILLS_PATH);
+    const agentsDir = path.dirname(agentsSkillsPath);
     // Check if source skills directory exists
     try {
         await fs.access(skillsDir);
@@ -523,23 +418,23 @@ async function propagateSkillsForCodex(projectRoot, options) {
     if (options.dryRun) {
         return [`Copy skills from ${constants_1.RULER_SKILLS_PATH} to ${constants_1.CODEX_SKILLS_PATH}`];
     }
-    // Ensure .codex directory exists
-    await fs.mkdir(codexDir, { recursive: true });
+    // Ensure .agents directory exists
+    await fs.mkdir(agentsDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(codexDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(agentsDir, projectRoot);
     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(codexSkillsPath, { recursive: true, force: true });
+            await fs.rm(agentsSkillsPath, { recursive: true, force: true });
         }
         catch {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, codexSkillsPath);
+        await replaceSkillsDirectory(tempDir, agentsSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -576,7 +471,7 @@ async function propagateSkillsForOpenCode(projectRoot, options) {
     // Ensure .opencode directory exists
     await fs.mkdir(opencodeDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(opencodeDir, `skill.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(opencodeDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -589,7 +484,7 @@ async function propagateSkillsForOpenCode(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, opencodeSkillsPath);
+        await replaceSkillsDirectory(tempDir, opencodeSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -626,7 +521,7 @@ async function propagateSkillsForPi(projectRoot, options) {
     // Ensure .pi directory exists
     await fs.mkdir(piDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(piDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(piDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -639,7 +534,7 @@ async function propagateSkillsForPi(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, piSkillsPath);
+        await replaceSkillsDirectory(tempDir, piSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -676,7 +571,7 @@ async function propagateSkillsForGoose(projectRoot, options) {
     // Ensure .agents directory exists
     await fs.mkdir(gooseDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(gooseDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(gooseDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -689,7 +584,7 @@ async function propagateSkillsForGoose(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, gooseSkillsPath);
+        await replaceSkillsDirectory(tempDir, gooseSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -726,7 +621,7 @@ async function propagateSkillsForVibe(projectRoot, options) {
     // Ensure .vibe directory exists
     await fs.mkdir(vibeDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(vibeDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(vibeDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -739,7 +634,7 @@ async function propagateSkillsForVibe(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, vibeSkillsPath);
+        await replaceSkillsDirectory(tempDir, vibeSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -776,7 +671,7 @@ async function propagateSkillsForRoo(projectRoot, options) {
     // Ensure .roo directory exists
     await fs.mkdir(rooDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(rooDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(rooDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -789,7 +684,7 @@ async function propagateSkillsForRoo(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, rooSkillsPath);
+        await replaceSkillsDirectory(tempDir, rooSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -826,7 +721,7 @@ async function propagateSkillsForGemini(projectRoot, options) {
     // Ensure .gemini directory exists
     await fs.mkdir(geminiDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(geminiDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(geminiDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -839,7 +734,7 @@ async function propagateSkillsForGemini(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, geminiSkillsPath);
+        await replaceSkillsDirectory(tempDir, geminiSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -872,7 +767,7 @@ async function propagateSkillsForJunie(projectRoot, options) {
         return [`Copy skills from ${constants_1.RULER_SKILLS_PATH} to ${constants_1.JUNIE_SKILLS_PATH}`];
     }
     await fs.mkdir(junieDir, { recursive: true });
-    const tempDir = path.join(junieDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(junieDir, projectRoot);
     try {
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
         try {
@@ -881,7 +776,7 @@ async function propagateSkillsForJunie(projectRoot, options) {
         catch {
             // Target didn't exist, that's fine
         }
-        await fs.rename(tempDir, junieSkillsPath);
+        await replaceSkillsDirectory(tempDir, junieSkillsPath, fs, projectRoot);
     }
     catch (error) {
         try {
@@ -917,7 +812,7 @@ async function propagateSkillsForCursor(projectRoot, options) {
     // Ensure .cursor directory exists
     await fs.mkdir(cursorDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(cursorDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(cursorDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -930,7 +825,7 @@ async function propagateSkillsForCursor(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, cursorSkillsPath);
+        await replaceSkillsDirectory(tempDir, cursorSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -967,7 +862,7 @@ async function propagateSkillsForWindsurf(projectRoot, options) {
     // Ensure .windsurf directory exists
     await fs.mkdir(windsurfDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(windsurfDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(windsurfDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -980,7 +875,7 @@ async function propagateSkillsForWindsurf(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, windsurfSkillsPath);
+        await replaceSkillsDirectory(tempDir, windsurfSkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -1017,7 +912,7 @@ async function propagateSkillsForFactory(projectRoot, options) {
     // Ensure .factory directory exists
     await fs.mkdir(factoryDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(factoryDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(factoryDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -1030,7 +925,7 @@ async function propagateSkillsForFactory(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, factorySkillsPath);
+        await replaceSkillsDirectory(tempDir, factorySkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error
@@ -1069,7 +964,7 @@ async function propagateSkillsForAntigravity(projectRoot, options) {
     // Ensure .agent directory exists
     await fs.mkdir(antigravityDir, { recursive: true });
     // Use atomic replace: copy to temp, then rename
-    const tempDir = path.join(antigravityDir, `skills.tmp-${Date.now()}`);
+    const tempDir = await createTempSkillsDir(antigravityDir, projectRoot);
     try {
         // Copy to temp directory
         await (0, SkillsUtils_1.copySkillsDirectory)(skillsDir, tempDir);
@@ -1082,7 +977,7 @@ async function propagateSkillsForAntigravity(projectRoot, options) {
             // Target didn't exist, that's fine
         }
         // Rename temp to target
-        await fs.rename(tempDir, antigravitySkillsPath);
+        await replaceSkillsDirectory(tempDir, antigravitySkillsPath, fs, projectRoot);
     }
     catch (error) {
         // Clean up temp directory on error

package/dist/core/SkillsUtils.d.ts

@@ -0,0 +1,26 @@
+import { SkillInfo } from '../types';
+/**
+ * Checks if a directory contains a SKILL.md file.
+ */
+export declare function hasSkillMd(dirPath: string): Promise<boolean>;
+/**
+ * Checks if a directory is a grouping directory (contains subdirectories with SKILL.md).
+ */
+export declare function isGroupingDir(dirPath: string): Promise<boolean>;
+/**
+ * Walks the skills tree and discovers all skills.
+ * Returns skills and any validation warnings.
+ */
+export declare function walkSkillsTree(root: string): Promise<{
+    skills: SkillInfo[];
+    warnings: string[];
+}>;
+/**
+ * Formats validation warnings for display.
+ */
+export declare function formatValidationWarnings(warnings: string[]): string;
+/**
+ * Copies the skills directory to the destination, preserving structure.
+ * Creates the destination directory if it doesn't exist.
+ */
+export declare function copySkillsDirectory(srcDir: string, destDir: string): Promise<void>;

package/dist/core/SubagentsProcessor.d.ts

@@ -0,0 +1,38 @@
+import type { SubagentInfo } from '../types';
+import type { IAgent } from '../agents/IAgent';
+/**
+ * Discovers subagent definitions in `.ruler/agents/`.
+ * Each `.md` file is parsed for YAML frontmatter (name, description, …).
+ * Files that fail validation are dropped from the returned list and
+ * reported via warnings.
+ */
+export declare function discoverSubagents(projectRoot: string): Promise<{
+    subagents: SubagentInfo[];
+    warnings: string[];
+}>;
+type SubagentTarget = 'claude' | 'cursor' | 'codex' | 'copilot';
+/**
+ * Returns which native subagent targets are reachable through the supplied
+ * agent list. An agent only contributes to a target when it implements
+ * `supportsNativeSubagents()` returning true.
+ */
+export declare function getSelectedSubagentTargets(agents: IAgent[]): Set<SubagentTarget>;
+/**
+ * Returns absolute paths that subagent propagation may generate, for the
+ * supplied agents, used for `.gitignore` integration.
+ */
+export declare function getSubagentsGitignorePaths(projectRoot: string, agents: IAgent[]): Promise<string[]>;
+/**
+ * Test-only hook to reset the once-per-process experimental warning state.
+ */
+export declare function _resetExperimentalWarningForTests(): void;
+interface PropagateOptions {
+    dryRun: boolean;
+    verbose?: boolean;
+}
+export declare function propagateSubagentsForClaude(projectRoot: string, subagents: SubagentInfo[], options: PropagateOptions): Promise<string[]>;
+export declare function propagateSubagentsForCursor(projectRoot: string, subagents: SubagentInfo[], options: PropagateOptions): Promise<string[]>;
+export declare function propagateSubagentsForCodex(projectRoot: string, subagents: SubagentInfo[], options: PropagateOptions): Promise<string[]>;
+export declare function propagateSubagentsForCopilot(projectRoot: string, subagents: SubagentInfo[], options: PropagateOptions): Promise<string[]>;
+export declare function propagateSubagents(projectRoot: string, agents: IAgent[], subagentsEnabled: boolean, cleanupOrphaned: boolean, verbose: boolean, dryRun: boolean): Promise<void>;
+export {};