skillrepo 4.0.0 → 4.2.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/removers/agent-hooks.mjs

@@ -0,0 +1,83 @@
+/**
+ * Cohort SessionStart-hook batch remover (#1240). Pairs with the two
+ * cohort installer mergers under `mergers/agent-hook-{claude,cursor}-shape.mjs`
+ * to satisfy the artifact-registry drift-protection test
+ * (`src/test/lib/artifact-registry.test.mjs`), which requires every
+ * descriptor to map to a remover.
+ *
+ * One file rather than per-vendor removers because:
+ *
+ *   1. The four cohort vendors share a single fingerprint
+ *      (`AGENT_HOOK_FINGERPRINT`), so all per-vendor removers would
+ *      delegate to identical logic.
+ *   2. The dispatch by `agentHook.shape` is already encoded in
+ *      `agent-hook-merge.mjs`; reusing it here keeps the two-shape
+ *      walk in exactly one place.
+ *   3. The uninstall command iterates the registry's
+ *      `kind: "agent-hook"` descriptors and calls this module once per
+ *      descriptor — the file count would otherwise grow with every
+ *      cohort vendor added.
+ *
+ * The artifact-registry CI test maps `removers/agent-hooks.mjs` to the
+ * four `agent-hook-<vendorKey>` descriptor ids via `REMOVER_EXPECTED`;
+ * any drift in that mapping fails CI before the user can run.
+ */
+
+import { uninstallAgentHookFor } from "../agent-hook-merge.mjs";
+import { ARTIFACT_REGISTRY } from "../artifact-registry.mjs";
+
+/**
+ * Remove the cohort hook for a single artifact descriptor. Used by
+ * `commands/uninstall.mjs`'s dispatch loop, which routes any
+ * `kind: "agent-hook"` descriptor here.
+ *
+ * @param {object} descriptor - One entry from `ARTIFACT_REGISTRY` with
+ *        `kind: "agent-hook"`. Must carry `vendorKey`.
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {{ path: string; action: "removed" | "would-remove" | "skipped" | "unchanged"; error?: string }}
+ */
+export function removeAgentHookArtifact(descriptor, { dryRun = false } = {}) {
+  if (!descriptor || descriptor.kind !== "agent-hook") {
+    throw new Error(
+      `removeAgentHookArtifact: expected kind="agent-hook", got "${descriptor?.kind}".`,
+    );
+  }
+  if (!descriptor.vendorKey) {
+    throw new Error(
+      `removeAgentHookArtifact: descriptor "${descriptor.id}" missing vendorKey.`,
+    );
+  }
+  return uninstallAgentHookFor(descriptor.vendorKey, { dryRun });
+}
+
+/**
+ * Remove every cohort hook in one call. Convenience wrapper for
+ * `skillrepo uninstall --global` and the standalone session-sync
+ * "disable all" workflow. Iterates all `kind: "agent-hook"` descriptors
+ * in the artifact registry — i.e. every cohort vendor that has an
+ * `agentHook` spec. Idempotent: vendors with no installed hook return
+ * `"skipped"` or `"unchanged"`, never failing.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {Array<{ id: string; path: string; action: string; error?: string }>}
+ */
+export function removeAllAgentHooks({ dryRun = false } = {}) {
+  const results = [];
+  for (const descriptor of ARTIFACT_REGISTRY) {
+    if (descriptor.kind !== "agent-hook") continue;
+    try {
+      const r = removeAgentHookArtifact(descriptor, { dryRun });
+      results.push({ id: descriptor.id, ...r });
+    } catch (err) {
+      results.push({
+        id: descriptor.id,
+        path: descriptor.displayPath,
+        action: "failed",
+        error: err?.message ?? String(err),
+      });
+    }
+  }
+  return results;
+}

package/src/lib/skill-walk.mjs

@@ -0,0 +1,97 @@
+/**
+ * Directory walker for `skillrepo push` (#1455).
+ *
+ * Walks a local skill directory and collects files for upload — the
+ * whole skill folder uniformly, including the root `SKILL.md`, per the
+ * agentskills.io specification (a skill is a directory containing
+ * `SKILL.md` at the root plus optional supporting files).
+ *
+ * Excludes:
+ *   - Any path component starting with `.` (e.g. `.git`, `.DS_Store`)
+ *     so `skillrepo push .` from a repo root doesn't accidentally
+ *     upload git internals.
+ *   - `node_modules` directories anywhere in the tree.
+ *
+ * Paths returned are relative to the skill directory and use forward
+ * slashes regardless of platform — that's what the server's
+ * `validateFilePath` expects, and what RFC 7578 `Content-Disposition:
+ * filename` carries on the wire.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const EXCLUDED_DIRS = new Set(["node_modules"]);
+
+/**
+ * @typedef {Object} WalkedFile
+ * @property {string} relativePath - POSIX-style path within the skill directory.
+ * @property {string} absolutePath - Absolute filesystem path on local disk.
+ * @property {number} size - File size in bytes (from stat).
+ */
+
+/**
+ * Walk a skill directory and yield every file that should be sent as
+ * a multipart `files` part.
+ *
+ * @param {string} skillDir - Absolute path to the skill directory.
+ * @returns {Promise<WalkedFile[]>}
+ */
+export async function walkSkillFiles(skillDir) {
+  const absRoot = path.resolve(skillDir);
+  const out = [];
+  await walkRecursive(absRoot, absRoot, out);
+  // Deterministic order so SHA fingerprints (and tests that assert on
+  // ordered output) are reproducible.
+  out.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return out;
+}
+
+/**
+ * @param {string} absRoot
+ * @param {string} currentDir
+ * @param {WalkedFile[]} out
+ */
+async function walkRecursive(absRoot, currentDir, out) {
+  let entries;
+  try {
+    entries = await fs.readdir(currentDir, { withFileTypes: true });
+  } catch (err) {
+    if (err && /** @type {NodeJS.ErrnoException} */ (err).code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
+
+  for (const entry of entries) {
+    const name = entry.name;
+
+    // Hidden files / directories (anything starting with `.`).
+    if (name.startsWith(".")) continue;
+
+    // Excluded directory names.
+    if (entry.isDirectory() && EXCLUDED_DIRS.has(name)) continue;
+
+    const absChild = path.join(currentDir, name);
+
+    if (entry.isDirectory()) {
+      await walkRecursive(absRoot, absChild, out);
+      continue;
+    }
+
+    if (!entry.isFile()) continue; // skip symlinks / sockets / etc.
+
+    // POSIX-style relative path from the skill root.
+    const relative = path
+      .relative(absRoot, absChild)
+      .split(path.sep)
+      .join("/");
+
+    const stat = await fs.stat(absChild);
+    out.push({
+      relativePath: relative,
+      absolutePath: absChild,
+      size: stat.size,
+    });
+  }
+}