skillrepo 3.2.0 → 4.1.0

package/src/lib/file-write.mjs

@@ -33,11 +33,14 @@
  *       - Blocked extensions — rejected (matches server BLOCKED_EXTENSIONS)
  *       - Skill name vs frontmatter `name` — must match
  *
- *   • Vendor placement: Claude Code uses .claude/skills/<name>/ (project)
- *     or ~/.claude/skills/<name>/ (--global) per Anthropic's documented
- *     convention. Other detected vendors without their own convention
- *     fall back to <cwd>/skills/<name>/, with /skills/ added to .gitignore
- *     on first creation. See follow-up #876.
+ *   • Vendor placement: per-vendor decisions live in `agent-registry.mjs`.
+ *     Claude Code writes to .claude/skills/<name>/ (Anthropic's documented
+ *     convention); the cohort of cursor / windsurf / gemini / codex / cline
+ *     / copilot shares .agents/skills/<name>/ for project scope (with
+ *     `.agents/skills/` added to .gitignore on first cohort write). Personal
+ *     scope honors per-vendor conventions where they exist (Windsurf has its
+ *     own personal path under ~/.codeium/windsurf/skills/). See
+ *     `packages/cli/docs/vendor-paths.md` for the full citation list.
  */
 
 import {
@@ -55,12 +58,17 @@ import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
   claudeSkillsProject,
   claudeSkillsGlobal,
-  projectSkillsFallback,
-  projectSkillsFallbackRoot,
   claudeSkillsProjectRoot,
   claudeSkillsGlobalRoot,
+  agentsSkillsProject,
+  agentsSkillsProjectRoot,
+  agentsSkillsGlobal,
+  agentsSkillsGlobalRoot,
+  windsurfSkillsGlobal,
+  windsurfSkillsGlobalRoot,
   gitignorePath,
 } from "./paths.mjs";
+import { AGENT_REGISTRY, getAgentByKey } from "./agent-registry.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
 import { platformConventions } from "./platform.mjs";
 
@@ -83,7 +91,7 @@ export const BLOCKED_EXTENSIONS = new Set([
   ".wasm",
 ]);
 
-const GITIGNORE_SKILLS_LINE = "/skills/";
+const GITIGNORE_AGENTS_SKILLS_LINE = ".agents/skills/";
 const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
 
 // ── Types (JSDoc only — this is plain JS) ───────────────────────────────
@@ -102,9 +110,25 @@ const GITIGNORE_SKILLS_HEADER = "# SkillRepo (CLI-managed library skills)";
  */
 
 /**
- * @typedef {"claudeProject" | "claudeGlobal" | "projectFallback"} PlacementTarget
+ * @typedef {"claudeProject" | "claudeGlobal" | "agentsProject" | "agentsGlobal" | "windsurfGlobal"} PlacementTarget
  */
 
+/** @type {readonly PlacementTarget[]} */
+const ALL_TARGETS = Object.freeze([
+  "claudeProject",
+  "claudeGlobal",
+  "agentsProject",
+  "agentsGlobal",
+  "windsurfGlobal",
+]);
+
+/** @type {readonly PlacementTarget[]} */
+const GLOBAL_TARGETS = Object.freeze([
+  "claudeGlobal",
+  "agentsGlobal",
+  "windsurfGlobal",
+]);
+
 // ── Public API ──────────────────────────────────────────────────────────
 
 /**
@@ -165,8 +189,64 @@ export function resolvePlacementDir(target, skillName) {
       return claudeSkillsProject(skillName);
     case "claudeGlobal":
       return claudeSkillsGlobal(skillName);
-    case "projectFallback":
-      return projectSkillsFallback(skillName);
+    case "agentsProject":
+      return agentsSkillsProject(skillName);
+    case "agentsGlobal":
+      return agentsSkillsGlobal(skillName);
+    case "windsurfGlobal":
+      return windsurfSkillsGlobal(skillName);
+    default: {
+      throw validationError(`Unknown placement target: ${target}`);
+    }
+  }
+}
+
+/**
+ * Human-readable path label for a placement target. Used in success
+ * messages so the user sees where files actually landed (`.agents/skills/`
+ * for cohort vendors, not the misleading `.claude/skills/` previously
+ * hardcoded in add/get).
+ *
+ * @param {PlacementTarget} target
+ * @returns {string}
+ */
+export function describePlacementTarget(target) {
+  switch (target) {
+    case "claudeProject":
+      return ".claude/skills/";
+    case "claudeGlobal":
+      return "~/.claude/skills/";
+    case "agentsProject":
+      return ".agents/skills/";
+    case "agentsGlobal":
+      return "~/.agents/skills/";
+    case "windsurfGlobal":
+      return "~/.codeium/windsurf/skills/";
+    default:
+      return target;
+  }
+}
+
+/**
+ * Map a `PlacementTarget` to its parent root resolver. Used by
+ * `cleanupOrphans` to know which directories to scan for `.tmp`/`.old`
+ * siblings.
+ *
+ * @param {PlacementTarget} target
+ * @returns {() => string}
+ */
+function placementRootFn(target) {
+  switch (target) {
+    case "claudeProject":
+      return claudeSkillsProjectRoot;
+    case "claudeGlobal":
+      return claudeSkillsGlobalRoot;
+    case "agentsProject":
+      return agentsSkillsProjectRoot;
+    case "agentsGlobal":
+      return agentsSkillsGlobalRoot;
+    case "windsurfGlobal":
+      return windsurfSkillsGlobalRoot;
     default: {
       throw validationError(`Unknown placement target: ${target}`);
     }
@@ -174,46 +254,52 @@ export function resolvePlacementDir(target, skillName) {
 }
 
 /**
- * Compute the placement targets for a write based on detected/requested
- * vendors and the --global flag.
+ * Compute the placement targets for a write based on requested vendors
+ * and the --global flag.
  *
- * Rules:
- *   - --global → only ["claudeGlobal"] (other vendors don't have a
- *     documented global convention; we don't synthesize one)
- *   - claudeCode in vendors → "claudeProject"
- *   - any non-claudeCode vendor in vendors (cursor, windsurf, vscode)
- *     → "projectFallback" (single fallback, deduped — multiple
- *     non-claude vendors share the same fallback)
+ * Each vendor's `projectTarget` and `globalTarget` come from
+ * `agent-registry.mjs`. Multiple vendors mapping to the same target
+ * (e.g. cursor + windsurf both at `agentsProject`) collapse into one
+ * write. A vendor with `globalTarget === null` is rejected under
+ * `--global` because the vendor has no documented personal scope.
  *
  * @param {object} options
- * @param {string[]} options.vendors - List of vendor keys (claudeCode, cursor, windsurf, vscode).
- * @param {boolean} [options.global] - If true, write to personal/global Claude Code dir only.
+ * @param {string[]} options.vendors - List of canonical vendor keys.
+ * @param {boolean} [options.global] - If true, use each vendor's globalTarget.
  * @returns {PlacementTarget[]}
  */
 export function placementTargetsFor({ vendors, global = false }) {
-  if (global) {
-    return ["claudeGlobal"];
-  }
-
   if (!Array.isArray(vendors) || vendors.length === 0) {
     throw validationError(
-      "No vendors specified. Pass --ide claude (or another vendor) explicitly.",
+      "No vendors specified. Pass --agent claude (or another target) explicitly.",
     );
   }
 
   const targets = [];
-  let needsFallback = false;
   for (const vendor of vendors) {
-    if (vendor === "claudeCode") {
-      targets.push("claudeProject");
-    } else if (vendor === "cursor" || vendor === "windsurf" || vendor === "vscode") {
-      needsFallback = true;
-    } else {
-      throw validationError(`Unknown vendor: ${vendor}`);
+    const entry = getAgentByKey(vendor);
+    if (!entry) {
+      throw validationError(`Unknown vendor: ${vendor}`, {
+        hint: `Valid keys: ${AGENT_REGISTRY.map((e) => e.key).join(", ")}.`,
+      });
+    }
+    const target = global ? entry.globalTarget : entry.projectTarget;
+    if (target === null) {
+      const supported = AGENT_REGISTRY
+        .filter((e) => e.globalTarget !== null)
+        .map((e) => e.key)
+        .join(", ");
+      throw validationError(
+        `${vendor} has no documented personal scope, so --global is not supported.`,
+        {
+          hint:
+            `Drop --global, or use --agent with a vendor that supports it (${supported}).`,
+        },
+      );
+    }
+    if (!targets.includes(target)) {
+      targets.push(target);
     }
-  }
-  if (needsFallback) {
-    targets.push("projectFallback");
   }
   return targets;
 }
@@ -264,7 +350,7 @@ export function readFrontmatterName(files) {
  * skip-if-unchanged enhancement at this layer would duplicate that work
  * and require re-reading every file from disk.
  *
- * Pre-flight: `.gitignore` setup for the projectFallback target runs
+ * Pre-flight: `.gitignore` setup for the agentsProject target runs
  * BEFORE any per-target write. This is intentional — running it inline
  * inside the loop would let a read-only `.gitignore` failure abort the
  * loop AFTER an earlier vendor (e.g., claudeCode) had already
@@ -277,14 +363,15 @@ export function writeSkillDir(skill, options = {}) {
 
   const targets = placementTargetsFor(options);
 
-  // Pre-flight: if any target requires the project /skills/ fallback,
-  // ensure .gitignore is set up before starting any writes. A failure
-  // here is recoverable (user fixes their .gitignore and re-runs)
-  // because nothing has hit disk yet. A failure here AFTER a successful
-  // claudeProject write would leave the user with a half-applied state
-  // and an error message that doesn't reflect what's actually on disk.
-  if (targets.includes("projectFallback")) {
-    ensureFallbackGitignore();
+  // Pre-flight: if any target writes to .agents/skills/, ensure
+  // .gitignore is set up before starting any writes. A failure here
+  // is recoverable (user fixes their .gitignore and re-runs) because
+  // nothing has hit disk yet. A failure here AFTER a successful
+  // claudeProject write would leave the user with a half-applied
+  // state and an error message that doesn't reflect what's actually
+  // on disk.
+  if (targets.includes("agentsProject")) {
+    ensureAgentsGitignore();
   }
 
   const written = [];
@@ -377,26 +464,26 @@ export function removeSkillDir(skillName, options = {}) {
  * @returns {{ cleaned: string[] }}
  */
 export function cleanupOrphans(options = {}) {
-  const roots = [];
-  if (options.global) {
-    roots.push(claudeSkillsGlobalRoot());
+  const roots = new Set();
+  if (Array.isArray(options.vendors) && options.vendors.length > 0) {
+    const targets = placementTargetsFor({
+      vendors: options.vendors,
+      global: !!options.global,
+    });
+    for (const target of targets) {
+      roots.add(placementRootFn(target)());
+    }
+  } else if (options.global) {
+    // No vendors under --global — sweep every known global root so a
+    // stale orphan from any prior --global write is cleaned.
+    for (const target of GLOBAL_TARGETS) {
+      roots.add(placementRootFn(target)());
+    }
   } else {
-    if (Array.isArray(options.vendors) && options.vendors.length > 0) {
-      if (options.vendors.includes("claudeCode")) {
-        roots.push(claudeSkillsProjectRoot());
-      }
-      if (
-        options.vendors.includes("cursor") ||
-        options.vendors.includes("windsurf") ||
-        options.vendors.includes("vscode")
-      ) {
-        roots.push(projectSkillsFallbackRoot());
-      }
-    } else {
-      // No vendors specified — clean everything we know about.
-      roots.push(claudeSkillsProjectRoot());
-      roots.push(projectSkillsFallbackRoot());
-      roots.push(claudeSkillsGlobalRoot());
+    // No vendors and no --global — sweep every root we know about so
+    // any orphan from any prior run is cleaned.
+    for (const target of ALL_TARGETS) {
+      roots.add(placementRootFn(target)());
     }
   }
 
@@ -666,17 +753,14 @@ function writeSkillToDir(skill, targetDir) {
 }
 
 /**
- * Ensure the project /skills/ directory is gitignored. Idempotent —
- * skips if the entry is already present. Creates .gitignore if missing.
+ * Ensure `.agents/skills/` is gitignored. Idempotent — skips if the
+ * entry is already present. Creates .gitignore if missing.
  *
  * Throws diskError on any write failure so a read-only or symlinked
  * .gitignore surfaces as a user-visible error instead of silent data
- * loss. This is the explicit fix for the architect's PR1 review item:
- * `writeFileSafe` was previously called without a try/catch and a
- * failing write would leave the user with skills on disk but no
- * .gitignore protection — the next `git add` would commit them.
+ * loss.
  */
-function ensureFallbackGitignore() {
+function ensureAgentsGitignore() {
   const filePath = gitignorePath();
   let existing = null;
   try {
@@ -684,18 +768,19 @@ function ensureFallbackGitignore() {
   } catch (err) {
     throw diskError(`Cannot read ${filePath}: ${err.message}`, {
       cause: err,
-      hint: "Update your .gitignore manually to add /skills/ before re-running.",
+      hint:
+        `Update your .gitignore manually to add ${GITIGNORE_AGENTS_SKILLS_LINE} before re-running.`,
     });
   }
 
-  if (existing !== null && existing.includes(GITIGNORE_SKILLS_LINE)) {
+  if (existing !== null && existing.includes(GITIGNORE_AGENTS_SKILLS_LINE)) {
     return; // Already present — no-op
   }
 
   const newContent =
     existing === null
-      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`
-      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_SKILLS_LINE}\n`;
+      ? `${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`
+      : `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${GITIGNORE_SKILLS_HEADER}\n${GITIGNORE_AGENTS_SKILLS_LINE}\n`;
 
   try {
     writeFileSafe(filePath, newContent);
@@ -703,7 +788,7 @@ function ensureFallbackGitignore() {
     throw diskError(`Cannot update ${filePath}: ${err.message}`, {
       cause: err,
       hint:
-        "The CLI needs to add /skills/ to .gitignore so library skills don't get committed. " +
+        `The CLI needs to add ${GITIGNORE_AGENTS_SKILLS_LINE} to .gitignore so library skills don't get committed. ` +
         "Update .gitignore manually and re-run, or remove the read-only/symlinked constraint.",
     });
   }

package/src/lib/fs-utils.mjs

@@ -87,7 +87,22 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
     throw new Error(`${filePath} is a directory, expected a file`);
   }
 
-  const tmpPath = `${filePath}.tmp`;
+  // Per-process unique temp suffix prevents two concurrent writers
+  // (e.g. a SessionStart hook firing `skillrepo update --silent` while
+  // the user runs `skillrepo uninstall --global`) from writing to the
+  // same `.tmp` path and producing non-deterministic final content.
+  // The cohort SessionStart hooks (#1240) made this race observable
+  // in production: hook configs at user-scope can be touched by both
+  // the hook runner and the uninstaller simultaneously.
+  //
+  // `process.pid` plus a `Math.random()` token gives uniqueness across
+  // processes AND across rapid same-process re-entrant writes. The
+  // token is base-36 chars from a 64-bit float — collision probability
+  // between siblings within the rename window is astronomically low.
+  // No cryptographic strength required: this is a temp-file suffix,
+  // not a security boundary.
+  const uniqueSuffix = `${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
+  const tmpPath = `${filePath}.${uniqueSuffix}.tmp`;
   try {
     writeFileSync(tmpPath, content, "utf-8");
   } catch (err) {

package/src/lib/mcp-merge.mjs

@@ -46,6 +46,7 @@ import { mergeWindsurfMcpConfig } from "./mergers/windsurf-mcp.mjs";
 import { mergeVscodeMcpConfig } from "./mergers/vscode-mcp.mjs";
 import { confirm as realConfirm } from "./prompt.mjs";
 import { validationError } from "./errors.mjs";
+import { getAgentByKey } from "./agent-registry.mjs";
 
 /**
  * @typedef {Object} McpMergeResult
@@ -69,7 +70,7 @@ import { validationError } from "./errors.mjs";
  * user for each one unless `yes` is true.
  *
  * @param {object} options
- * @param {string[]} options.vendors - Vendor keys: claudeCode | cursor | windsurf | vscode
+ * @param {string[]} options.vendors - Canonical vendor keys (see agent-registry.mjs).
  * @param {string} options.mcpUrl - The SkillRepo MCP endpoint URL
  * @param {boolean} [options.yes] - Skip prompts (auto-accept everything)
  * @param {object} [options.io] - Injected streams for testability
@@ -111,18 +112,26 @@ export async function mergeMcpForVendors(options) {
   }
 
   // Deduplicate vendors so a caller passing `["claudeCode",
-  // "claudeCode"]` doesn't run the merger twice. The round-1 review
-  // flagged this as a latent caller trap — `cli-config.mjs`'s
-  // parseVendorList doesn't dedupe either, so `--ide claude,claude`
-  // would reach this loop twice for the same vendor. Idempotent on
-  // a single vendor key (Set preserves first-seen insertion order).
+  // "claudeCode"]` doesn't run the merger twice. Defense-in-depth —
+  // `cli-config.mjs`'s `parseAgentList` already dedupes, but a future
+  // caller building the vendor list manually could reintroduce the
+  // duplicate. Idempotent on a single vendor key (Set preserves
+  // first-seen insertion order).
   const uniqueVendors = Array.from(new Set(vendors));
 
   const results = [];
   for (const vendor of uniqueVendors) {
+    const entry = getAgentByKey(vendor);
+    // Vendors with `hasMcp: false` are file-only (no documented MCP
+    // config the CLI knows how to merge). Skipping silently is correct
+    // — they're a deliberate registry classification, not user error.
+    // A truly unknown vendor (no registry entry at all) is a caller
+    // bug; surface that as a "failed" result so it can't hide.
+    if (entry && entry.hasMcp === false) {
+      continue;
+    }
     const vendorInfo = VENDOR_INFO[vendor];
     if (!vendorInfo) {
-      // Unknown vendor — skip with a recorded failure
       results.push({
         vendor,
         path: "(unknown)",
@@ -183,34 +192,6 @@ export async function mergeMcpForVendors(options) {
   return results;
 }
 
-/**
- * Print MCP config JSON for undetected IDEs so the user can paste
- * it into their own IDE's MCP settings manually. Called by init
- * when no IDEs were detected or when the user wants to see the
- * raw config shape.
- *
- * @param {string} mcpUrl
- * @param {object} [io]
- * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
- */
-export function printManualMcpInstructions(mcpUrl, io = {}) {
-  const stdout = io.stdout ?? process.stdout;
-  const config = {
-    mcpServers: {
-      skillrepo: {
-        type: "http",
-        url: mcpUrl,
-        headers: {
-          Authorization: "Bearer ${SKILLREPO_ACCESS_KEY}",
-        },
-      },
-    },
-  };
-  stdout.write("\n  To configure MCP manually, add this to your IDE's MCP settings:\n\n");
-  stdout.write(JSON.stringify(config, null, 2).replace(/^/gm, "    ") + "\n\n");
-  stdout.write("  The SKILLREPO_ACCESS_KEY env var is set in .env.local.\n\n");
-}
-
 // ── Internals ──────────────────────────────────────────────────────────
 
 /**
@@ -233,7 +214,7 @@ const VENDOR_INFO = {
     pathFn: windsurfMcpJson,
     displayPath: "~/.codeium/windsurf/mcp_config.json",
   },
-  vscode: {
+  copilot: {
     merger: mergeVscodeMcpConfig,
     pathFn: vscodeMcpJson,
     displayPath: ".vscode/mcp.json",