skillrepo 3.2.0 → 4.1.0

package/src/lib/mergers/agent-hook-cursor-shape.mjs

@@ -0,0 +1,318 @@
+/**
+ * SessionStart-hook installer/uninstaller for cursor-shape vendors
+ * (#1240). Currently only Cursor itself, but the shape is documented
+ * separately so a future vendor that ships the same flat-array
+ * sessionStart schema slots in without code changes.
+ *
+ * Cursor docs 2026-05 specify the file shape:
+ *
+ *   {
+ *     "version": 1,
+ *     "hooks": {
+ *       "sessionStart": [
+ *         { "command": "..." }
+ *       ]
+ *     }
+ *   }
+ *
+ * Differences from the claude-shape merger:
+ *
+ *   - `version: 1` at the top level. The merger preserves it on
+ *     re-write and creates it for fresh files. A future Cursor
+ *     `version: 2` is a real possibility — when that lands, the
+ *     migration is a separate PR that bumps the writer here AND
+ *     adds an upgrade-path test that proves both shapes round-trip
+ *     through the remover.
+ *   - Single-level `hooks.<event>` array (no nested `{ hooks: [...] }`
+ *     groups). Walks are correspondingly shallower.
+ *   - Event-name casing differs: lowercase `sessionStart` per Cursor
+ *     docs. Comes from the agent registry's `agentHook.eventName`.
+ *   - Multi-tool merge surface: 1Password, Snyk, and Apiiro all
+ *     extend `~/.cursor/hooks.json`. The walk MUST preserve unknown
+ *     entries — round-trip preservation is the load-bearing
+ *     idempotency test.
+ *
+ * The shared concerns (atomic writes, fingerprint matching, idempotent
+ * actions, dispatcher integration) are intentionally implemented
+ * twice — once here, once in `agent-hook-claude-shape.mjs` — rather
+ * than abstracted. The architect review on #1240 specifically called
+ * out that a single-function `variant` switch becomes load-bearing
+ * config that no type system enforces; per-shape modules are the
+ * idiom that scales as new variants land.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "../fs-utils.mjs";
+import {
+  AGENT_HOOK_COMMAND,
+  AGENT_HOOK_FINGERPRINT,
+} from "../artifact-registry.mjs";
+import { getAgentByKey } from "../agent-registry.mjs";
+import { diskError, validationError } from "../errors.mjs";
+
+/**
+ * Build the per-hook entry the cursor-shape merger writes. The
+ * `entryFields` from the agent registry's `agentHook.entryFields` are
+ * spread BEFORE `command` so the registry can NEVER override the
+ * canonical command via a typo. Cursor itself has no extra entry
+ * fields today, but the spread is symmetrical with the claude-shape
+ * merger to keep both code paths consistent.
+ *
+ * @param {object} entryFields
+ * @returns {Record<string, unknown>}
+ */
+export function buildCursorShapeEntry(entryFields = {}) {
+  return {
+    ...entryFields,
+    command: AGENT_HOOK_COMMAND,
+  };
+}
+
+/**
+ * Install (or refresh) the cohort SessionStart hook in a cursor-shape
+ * vendor's hook config file. Creates the file with `version: 1` at
+ * the top level if it doesn't exist.
+ *
+ * @param {object} options
+ * @param {string} options.vendorKey
+ * @returns {{
+ *   path: string;
+ *   action: "installed" | "updated" | "unchanged";
+ *   command: string;
+ * }}
+ */
+export function mergeCursorShapeAgentHook({ vendorKey }) {
+  const { hookSpec } = resolveAgent(vendorKey);
+  const filePath = hookSpec.pathFn();
+  const eventName = hookSpec.eventName;
+  const desiredEntry = buildCursorShapeEntry(hookSpec.entryFields);
+
+  const config = readConfigOrEmpty(filePath, hookSpec.displayPath);
+
+  // Preserve any existing `version` value if the file already had one;
+  // otherwise default to 1 per Cursor's documented shape. A future
+  // user manually setting `version: 2` does NOT get silently demoted
+  // — we only set the default on a brand-new file.
+  if (config.version === undefined) {
+    config.version = 1;
+  }
+  if (!config.hooks || typeof config.hooks !== "object") {
+    config.hooks = {};
+  }
+  if (!Array.isArray(config.hooks[eventName])) {
+    config.hooks[eventName] = [];
+  }
+
+  // Exhaustive walk: drop any prior SkillRepo entries beyond the
+  // first match. The remover strips ALL fingerprint-matching entries,
+  // so the installer also has to handle ALL of them — otherwise a
+  // prior buggy run that left two ghosts would leave one behind on
+  // re-install. Cheap defense; aligns the installer-remover
+  // invariant ("exactly one SkillRepo entry per cohort hook config").
+  let primaryHandled = false;
+  let foundChanged = false;
+  let foundUnchangedExact = false;
+
+  const survivors = [];
+  let arrayMutated = false;
+  for (const inner of config.hooks[eventName]) {
+    if (
+      inner &&
+      typeof inner === "object" &&
+      typeof inner.command === "string" &&
+      inner.command.includes(AGENT_HOOK_FINGERPRINT)
+    ) {
+      if (!primaryHandled) {
+        primaryHandled = true;
+        if (entriesEqual(inner, desiredEntry)) {
+          foundUnchangedExact = true;
+          survivors.push(inner);
+        } else {
+          foundChanged = true;
+          arrayMutated = true; // in-place replacement at same index
+          survivors.push(desiredEntry);
+        }
+      } else {
+        // Duplicate from a prior buggy run — drop it.
+        foundChanged = true;
+        arrayMutated = true; // length-changing drop
+      }
+      continue;
+    }
+    survivors.push(inner);
+  }
+  // Write back when we mutated the array — either by replacing the
+  // primary entry in place (same length) or by dropping duplicates
+  // (smaller length). A length-only check would miss the
+  // replacement case.
+  if (arrayMutated) {
+    config.hooks[eventName] = survivors;
+  }
+
+  let matchedAction;
+  if (!primaryHandled) {
+    config.hooks[eventName].push(desiredEntry);
+    matchedAction = "installed";
+  } else if (foundChanged) {
+    matchedAction = "updated";
+  } else if (foundUnchangedExact) {
+    matchedAction = "unchanged";
+  } else {
+    matchedAction = "updated";
+  }
+
+  if (matchedAction === "unchanged") {
+    return {
+      path: hookSpec.displayPath,
+      action: "unchanged",
+      command: AGENT_HOOK_COMMAND,
+    };
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+
+  return {
+    path: hookSpec.displayPath,
+    action: matchedAction,
+    command: AGENT_HOOK_COMMAND,
+  };
+}
+
+/**
+ * Strip the SkillRepo cohort hook from a cursor-shape vendor's hook
+ * config. Idempotent — non-SkillRepo entries and unknown event arrays
+ * are never touched.
+ *
+ * @param {object} options
+ * @param {string} options.vendorKey
+ * @param {boolean} [options.dryRun=false]
+ * @returns {{
+ *   path: string;
+ *   action: "removed" | "would-remove" | "skipped" | "unchanged";
+ *   error?: string;
+ * }}
+ */
+export function unmergeCursorShapeAgentHook({ vendorKey, dryRun = false }) {
+  const { hookSpec } = resolveAgent(vendorKey);
+  const filePath = hookSpec.pathFn();
+  const eventName = hookSpec.eventName;
+
+  if (!existsSync(filePath)) {
+    return { path: hookSpec.displayPath, action: "skipped" };
+  }
+
+  const raw = readFileSync(filePath, "utf-8");
+  if (raw.trim().length === 0) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch (err) {
+    return {
+      path: hookSpec.displayPath,
+      action: "skipped",
+      error: `Cannot parse ${hookSpec.displayPath}: ${err.message}. Fix or delete the file and re-run.`,
+    };
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    !config.hooks ||
+    typeof config.hooks !== "object" ||
+    !Array.isArray(config.hooks[eventName])
+  ) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  const beforeCount = config.hooks[eventName].length;
+  const survivors = config.hooks[eventName].filter((h) => {
+    if (!h || typeof h !== "object" || typeof h.command !== "string") {
+      return true;
+    }
+    return !h.command.includes(AGENT_HOOK_FINGERPRINT);
+  });
+
+  if (survivors.length === beforeCount) {
+    return { path: hookSpec.displayPath, action: "unchanged" };
+  }
+
+  if (dryRun) {
+    return { path: hookSpec.displayPath, action: "would-remove" };
+  }
+
+  if (survivors.length === 0) {
+    delete config.hooks[eventName];
+  } else {
+    config.hooks[eventName] = survivors;
+  }
+  if (Object.keys(config.hooks).length === 0) {
+    delete config.hooks;
+  }
+
+  writeFileAtomic(filePath, JSON.stringify(config, null, 2) + "\n");
+  return { path: hookSpec.displayPath, action: "removed" };
+}
+
+// ── Internal helpers ───────────────────────────────────────────────
+
+function resolveAgent(vendorKey) {
+  const entry = getAgentByKey(vendorKey);
+  if (!entry) {
+    throw validationError(
+      `Unknown agent key: ${vendorKey}. Add it to AGENT_REGISTRY.`,
+    );
+  }
+  if (!entry.agentHook) {
+    throw validationError(
+      `Agent "${vendorKey}" has no agentHook spec — cannot install a SessionStart hook.`,
+    );
+  }
+  if (entry.agentHook.shape !== "cursor-shape") {
+    throw validationError(
+      `Agent "${vendorKey}" has shape "${entry.agentHook.shape}", expected "cursor-shape".`,
+      {
+        hint: "Use the matching shape merger (e.g. mergeClaudeShapeAgentHook).",
+      },
+    );
+  }
+  return { entry, hookSpec: entry.agentHook };
+}
+
+function readConfigOrEmpty(filePath, displayPath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, "utf-8");
+  if (raw.trim().length === 0) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw diskError(
+      `Cannot parse ${displayPath}: ${err.message}. Fix or delete the file, then re-run.`,
+      { cause: err },
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw diskError(
+      `${displayPath} must be a JSON object at the top level.`,
+    );
+  }
+  return parsed;
+}
+
+function entriesEqual(a, b) {
+  return stableJson(a) === stableJson(b);
+}
+
+function stableJson(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  const sortedKeys = Object.keys(value).sort();
+  const parts = sortedKeys.map(
+    (k) => `${JSON.stringify(k)}:${stableJson(value[k])}`,
+  );
+  return `{${parts.join(",")}}`;
+}

package/src/lib/mergers/gitignore.mjs

@@ -1,22 +1,14 @@
 /**
- * Merger for .gitignore — adds the three paths `skillrepo init` writes
- * that must not be committed.
- *
- * This module is v3.0.0-rewritten. The v2.0.0 version added a single
- * `.claude/rules/skillrepo-*.md` pattern for the now-deleted rules
- * delivery flow. The hooks were removed in #835 and the rules-delivery
- * model was replaced with direct skill syncing to `.claude/skills/`.
- * The three paths this merger adds are:
+ * Merger for .gitignore — adds the paths `skillrepo init` writes that
+ * must not be committed.
  *
+ * Always added:
  *   - `.env.local` — contains SKILLREPO_ACCESS_KEY, a live credential
- *   - `.claude/skills/` — per-developer synced library content
  *   - `.claude/settings.local.json` — Claude Code per-user settings
  *
- * The `.env.local` entry is the security-critical one: without it, a
- * developer running `skillrepo init` in a fresh project could commit
- * their access key on the next `git add .`. PR4 round-3 review caught
- * that the docs promised this behavior but the CLI never actually
- * wrote the entries — this merger closes the gap.
+ * Conditionally added based on the `vendors` option:
+ *   - `.claude/skills/` — when any vendor maps to `claudeProject`
+ *   - `.agents/skills/` — when any vendor maps to `agentsProject`
  *
  * Idempotent: entries already present are skipped. A single call
  * either adds all missing entries in one grouped section or exits
@@ -24,35 +16,70 @@
  */
 
 import { readFileSafe, writeFileSafe } from "../fs-utils.mjs";
-import { join } from "node:path";
+import { gitignorePath } from "../paths.mjs";
+import { placementTargetsFor } from "../file-write.mjs";
 
 const SECTION_HEADER = "# SkillRepo CLI (added by `skillrepo init`)";
-const REQUIRED_ENTRIES = [
+const ALWAYS_ENTRIES = Object.freeze([
   ".env.local",
-  ".claude/skills/",
   ".claude/settings.local.json",
-];
+]);
+
+/**
+ * Compute the gitignore entries to ensure based on the placement
+ * targets the caller will write to. When no vendors are passed, fall
+ * back to the historical default of `.claude/skills/` so existing
+ * call sites that haven't been threaded through `vendors` keep
+ * working.
+ *
+ * @param {{ vendors?: string[], global?: boolean }} options
+ * @returns {string[]}
+ */
+function entriesFor(options) {
+  const entries = [...ALWAYS_ENTRIES];
+  if (!Array.isArray(options.vendors) || options.vendors.length === 0) {
+    entries.push(".claude/skills/");
+    return entries;
+  }
+  let targets;
+  try {
+    targets = placementTargetsFor({
+      vendors: options.vendors,
+      global: !!options.global,
+    });
+  } catch {
+    // Caller passed an unknown vendor; fall back to the always-set
+    // entries plus `.claude/skills/` so we never under-protect.
+    entries.push(".claude/skills/");
+    return entries;
+  }
+  if (targets.includes("claudeProject")) entries.push(".claude/skills/");
+  if (targets.includes("agentsProject")) entries.push(".agents/skills/");
+  return entries;
+}
 
 /**
- * Ensure the three init-required paths are in .gitignore. Creates the
- * file if it doesn't exist. Idempotent — returns `"skipped"` if every
+ * Ensure the init-required paths are in .gitignore. Creates the file
+ * if it doesn't exist. Idempotent — returns `"skipped"` if every
  * required entry is already present, `"created"` if the file didn't
  * exist, `"updated"` if it did and at least one entry was missing.
  *
+ * @param {{ vendors?: string[], global?: boolean }} [options]
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
-export function mergeGitignore() {
-  const gitignorePath = join(process.cwd(), ".gitignore");
-  const existing = readFileSafe(gitignorePath);
+export function mergeGitignore(options = {}) {
+  const requiredEntries = entriesFor(options);
+  const filePath = gitignorePath();
+  const existing = readFileSafe(filePath);
 
   if (existing === null) {
     // Fresh .gitignore — write all required entries as one section.
-    const content = renderSection(REQUIRED_ENTRIES);
-    writeFileSafe(gitignorePath, content);
+    const content = renderSection(requiredEntries);
+    writeFileSafe(filePath, content);
     return {
       path: ".gitignore",
       action: "created",
-      added: [...REQUIRED_ENTRIES],
+      added: [...requiredEntries],
     };
   }
 
@@ -60,7 +87,7 @@ export function mergeGitignore() {
   // `.env.local.backup` or a comment `# .env.local` — split on
   // newlines and trim so we match the entry literally.
   const lines = existing.split(/\r?\n/).map((l) => l.trim());
-  const missing = REQUIRED_ENTRIES.filter((entry) => !lines.includes(entry));
+  const missing = requiredEntries.filter((entry) => !lines.includes(entry));
 
   if (missing.length === 0) {
     return {
@@ -75,7 +102,7 @@ export function mergeGitignore() {
   const lineEnding = existing.includes("\r\n") ? "\r\n" : "\n";
   const separator = existing.endsWith("\n") ? "" : lineEnding;
   const block = renderSection(missing, lineEnding);
-  writeFileSafe(gitignorePath, existing + separator + lineEnding + block);
+  writeFileSafe(filePath, existing + separator + lineEnding + block);
 
   return {
     path: ".gitignore",

package/src/lib/paths.mjs

@@ -28,25 +28,13 @@ export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
 
-// ── Skill placement targets (added in #646 / PR1) ─────────────────────
+// ── Skill placement targets ────────────────────────────────────────────
 //
-// Claude Code documents two skill discovery locations at
-// https://code.claude.com/docs/en/skills:
-//
-//   Personal: ~/.claude/skills/<name>/SKILL.md
-//   Project:  <cwd>/.claude/skills/<name>/SKILL.md
-//
-// The `name` segment must match the `name` field in the SKILL.md
-// frontmatter per the agentskills.io spec — the file-write pipeline
-// enforces this at write time.
-//
-// Other detected vendors (Cursor, Windsurf, VS Code Copilot) do not
-// currently document an on-disk skill discovery convention. For those
-// vendors, the file-write pipeline writes to a project-level fallback
-// at `<cwd>/skills/<name>/`, with an entry added to .gitignore on
-// first write so the user-specific skill set never leaks into the repo
-// history. See follow-up issue #876 for tracking when those IDEs
-// publish their own conventions.
+// Per-vendor placement decisions live in `agent-registry.mjs`. This
+// module exposes the path resolvers each placement target maps to;
+// `file-write.mjs` switches on the registry's PlacementTarget union to
+// pick the right resolver. See `packages/cli/docs/vendor-paths.md` for
+// the verified vendor-by-vendor reference and primary-source citations.
 
 /** Claude Code project-local skill directory for a specific skill name. */
 export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", name);
@@ -54,25 +42,39 @@ export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", na
 /** Claude Code personal/global skill directory for a specific skill name. */
 export const claudeSkillsGlobal = (name) => join(homedir(), ".claude", "skills", name);
 
-/** Project-local fallback skills root (used when --ide includes a vendor without a documented convention). */
-export const projectSkillsFallbackRoot = () => join(cwd(), "skills");
-
-/** Project-local fallback for a specific skill name. */
-export const projectSkillsFallback = (name) => join(cwd(), "skills", name);
-
 /** Parent directory of the project-local Claude Code skills (used by orphan cleanup). */
 export const claudeSkillsProjectRoot = () => join(cwd(), ".claude", "skills");
 
 /** Parent directory of the personal/global Claude Code skills (used by orphan cleanup). */
 export const claudeSkillsGlobalRoot = () => join(homedir(), ".claude", "skills");
 
+/** Cross-vendor `.agents/skills/<name>/` project-local placement (cursor, windsurf, gemini, codex, cline, copilot). */
+export const agentsSkillsProject = (name) => join(cwd(), ".agents", "skills", name);
+
+/** Parent of the project-local `.agents/skills/` cohort root (used by orphan cleanup). */
+export const agentsSkillsProjectRoot = () => join(cwd(), ".agents", "skills");
+
+/** Cross-vendor personal `.agents/skills/<name>/` placement (cursor, gemini, codex, cline). */
+export const agentsSkillsGlobal = (name) => join(homedir(), ".agents", "skills", name);
+
+/** Parent of the personal `.agents/skills/` cohort root (used by orphan cleanup). */
+export const agentsSkillsGlobalRoot = () => join(homedir(), ".agents", "skills");
+
+/** Windsurf's vendor-specific personal placement under `~/.codeium/windsurf/skills/<name>/`. */
+export const windsurfSkillsGlobal = (name) =>
+  join(homedir(), ".codeium", "windsurf", "skills", name);
+
+/** Parent of the Windsurf personal skills root (used by orphan cleanup). */
+export const windsurfSkillsGlobalRoot = () =>
+  join(homedir(), ".codeium", "windsurf", "skills");
+
 // ── Shared ────────────────────────────────────────────────────────────
 
 export const envLocal = () => join(cwd(), ".env.local");
 
 /**
  * Project .gitignore — used by the file-write pipeline to ensure the
- * project /skills/ fallback directory is gitignored on first write.
+ * `.agents/skills/` cohort directory is gitignored on first write.
  */
 export const gitignorePath = () => join(cwd(), ".gitignore");