skillrepo 4.0.0 → 4.2.0

package/src/lib/artifact-registry.mjs

@@ -42,6 +42,13 @@ import {
 } from "./paths.mjs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+// Cohort agent-hook descriptors derive from the agent registry so the
+// catalog never drifts from the registry's `agentHook` data. Pure data
+// composition: no fs, no dynamic behavior beyond reading frozen
+// constants. The DATA-ONLY rule for this module forbids fs access and
+// runtime mutation; reading another data-only module's exports is in
+// scope.
+import { AGENT_REGISTRY } from "./agent-registry.mjs";
 
 // ── Fingerprint constants exported for cross-module consumption ───────
 
@@ -139,13 +146,84 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
  */
 export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
 
+/**
+ * The canonical SessionStart-hook command the CLI installs into every
+ * cohort agent's hook config (#1240). Cohort agents = Cursor, Gemini
+ * CLI, Codex CLI, VS Code + Copilot — every cohort vendor whose
+ * placement target is `agentsProject` AND whose vendor docs publish a
+ * SessionStart-equivalent hook surface.
+ *
+ * The command is intentionally short and shell-portable:
+ *
+ *   - `npx --yes` works on Windows (cmd.exe + PowerShell) and POSIX
+ *     shells with no shell-builtin dependency. The session-hook
+ *     installer's `<absolute-path>` + `|| true` design is
+ *     Claude-Code-specific (Claude doesn't load PATH); the cohort
+ *     vendors all spawn hooks through the user's normal shell where
+ *     `npx` resolves naturally.
+ *   - `--yes` suppresses npx's interactive "Need to install …" prompt
+ *     so the hook never blocks waiting for stdin.
+ *   - `--silent` (#1240) suppresses stdout to a single `{}` line on
+ *     success. Gemini CLI specifically requires hook stdout to be
+ *     valid JSON; the empty object is the minimal valid value that
+ *     injects no model context. Other vendors tolerate it.
+ *
+ * Distinct from `--session-hook` (Claude-Code-specific, exit-0 on
+ * every error). See `commands/update.mjs`'s docstring for the
+ * cross-flag contract table.
+ */
+export const AGENT_HOOK_COMMAND = "npx --yes skillrepo update --silent";
+
+/**
+ * Substring that identifies a cohort SessionStart-hook entry as
+ * SkillRepo-owned (#1240). The cohort installers write a `command`
+ * field equal to `AGENT_HOOK_COMMAND`; the remover walks each cohort
+ * agent's hook config and filters out any entry whose command
+ * contains this substring.
+ *
+ * Same word-boundary rationale as `SESSION_HOOK_FINGERPRINT`: the
+ * leading space requires `skillrepo` to be preceded by whitespace
+ * (i.e., its own argv token), so a hypothetical command like
+ * `myapp-skillrepo update --silent` cannot false-match.
+ *
+ * Both ends of the fingerprint are deliberately permissive — the
+ * fingerprint is shorter than the full command at BOTH the prefix
+ * and suffix:
+ *   - PREFIX tolerance: a future change to the wrapper invocation
+ *     (e.g., switching from `npx --yes` to `bunx`) preserves this
+ *     substring and stays round-trip compatible with installed
+ *     hook entries.
+ *   - SUFFIX tolerance: a future suffix addition (e.g., piping to
+ *     a logger, or adding a `--quiet`-style alias flag) ALSO
+ *     preserves the substring. This is intentional: the remover
+ *     must match every legitimate evolution of the SkillRepo hook
+ *     command without forcing a fingerprint bump.
+ *
+ * The trade-off is that an unrelated tool's hook command containing
+ * the literal sequence ` skillrepo update --silent` somewhere in its
+ * argv would false-match. The two-token combination
+ * `skillrepo update --silent` is specific enough that no real-world
+ * non-SkillRepo command realistically produces it; the fingerprint
+ * test in `agent-hook-{claude,cursor}-shape.test.mjs` covers the
+ * round-trip but does not enumerate every possible false-positive.
+ * If a real-world collision ever surfaces, the right fix is to bump
+ * the fingerprint to a more specific marker (e.g., a version-pinned
+ * sentinel) and gate the change with a backward-compat test that
+ * proves both old and new shapes are matched.
+ *
+ * Any change to the substring itself MUST be coordinated with the
+ * installer mergers (agent-hook-{claude,cursor}-shape.mjs) and the
+ * remover (removers/agent-hooks.mjs).
+ */
+export const AGENT_HOOK_FINGERPRINT = " skillrepo update --silent";
+
 // ── Artifact descriptors ────────────────────────────────────────────
 
 /**
  * @typedef {Object} ArtifactDescriptor
  * @property {string} id - Stable identifier. Shows up in --json output.
  * @property {"project" | "global"} scope - Which teardown pass owns this.
- * @property {"json-key" | "json-input" | "line" | "section" | "directory"} kind
+ * @property {"json-key" | "json-input" | "line" | "section" | "directory" | "agent-hook"} kind
  *          How the remover deletes this artifact.
  * @property {() => string} pathFn - Resolves the on-disk path (absolute).
  * @property {string} displayPath - Human-readable path for output (e.g.
@@ -158,7 +236,13 @@ export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
  * @property {string} [sectionHeader] - For section: the header line;
  *          every line under it up to a blank-line sentinel is owned.
  * @property {string} [commandFingerprint] - For the SessionStart hook
- *          entry: `command` field contains this substring.
+ *          entry (kind="json-key" or "agent-hook"): `command` field
+ *          contains this substring.
+ * @property {string} [vendorKey] - For kind="agent-hook" (#1240):
+ *          AGENT_REGISTRY key whose `agentHook` spec drives the walk.
+ *          The remover dispatches to the per-shape merger via this key
+ *          rather than inlining the shape data here, so the registry
+ *          stays static even as the per-shape merger logic evolves.
  */
 
 /**
@@ -284,6 +368,31 @@ export const ARTIFACT_REGISTRY = Object.freeze([
     displayPath: "~/.claude/settings.local.json",
     commandFingerprint: SESSION_HOOK_FINGERPRINT,
   }),
+
+  // ── Cohort agent-hook artifacts (#1240) ────────────────────────────
+  //
+  // One descriptor per cohort vendor whose `agentHook` spec is non-null
+  // in the agent registry. Each descriptor's `kind: "agent-hook"`
+  // routes the uninstaller to `removers/agent-hooks.mjs`, which uses
+  // the `vendorKey` to look up the per-shape walk in the agent
+  // registry. The cohort hooks live under `~/.<vendor>/...` (user
+  // scope), so all four are scope: "global".
+  //
+  // These descriptors are derived (filter+map) rather than hand-typed
+  // so the catalog cannot drift from `agent-registry.mjs`'s `agentHook`
+  // data. The agent registry is the single source of truth for
+  // per-vendor hook configuration; this is just its uninstall index.
+  ...AGENT_REGISTRY.filter((entry) => entry.agentHook !== null).map((entry) =>
+    Object.freeze({
+      id: `agent-hook-${entry.key}`,
+      scope: "global",
+      kind: "agent-hook",
+      pathFn: entry.agentHook.pathFn,
+      displayPath: entry.agentHook.displayPath,
+      commandFingerprint: AGENT_HOOK_FINGERPRINT,
+      vendorKey: entry.key,
+    }),
+  ),
 ]);
 
 /**

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/http.mjs

@@ -368,9 +368,9 @@ async function mapErrorResponse(res, url) {
     return networkError("Rate limit exceeded — server returned 429.", {
       hint:
         "Wait a minute and retry. Read-only commands (update, get, " +
-        "list, search) retry automatically; write commands (add, " +
-        "remove) are single-shot. Pass --verbose to see retry " +
-        "attempts when they happen.",
+        "list, search) and idempotent writes (push) retry " +
+        "automatically; non-idempotent writes (add, remove) are " +
+        "single-shot. Pass --verbose to see retry attempts.",
     });
   }
   if (res.status >= 500) {
@@ -621,7 +621,13 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
   return body.skill ?? null;
 }
 
-// ── /api/v1/library (POST — add to library) ────────────────────────────
+// ── /api/v1/library/refs (POST — add catalog skill to library) ─────────
+//
+// Previously POSTed to `/api/v1/library` directly. After epic #1444
+// Release 1 (#1452), `POST /api/v1/library` is the multipart file-push
+// endpoint and the JSON `{owner, name}` catalog-add operation lives at
+// `POST /api/v1/library/refs` (#1451). The handler logic and response
+// shape are unchanged — only the URL moved.
 
 /**
  * @typedef {Object} LibraryAddSuccess
@@ -650,19 +656,21 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
  */
 
 /**
- * POST /api/v1/library — add a skill to the authenticated account's
- * library.
+ * POST /api/v1/library/refs — add an existing catalog skill to the
+ * authenticated account's library by `{owner, name}` reference.
  *
- * The server's POST handler distinguishes several outcomes via both
- * HTTP status and a `code` field in the response body (see
- * src/app/api/v1/library/route.ts:190-237):
+ * Distinct from `pushSkill` above, which uploads a SKILL.md + files
+ * folder via multipart on `POST /api/v1/library`.
+ *
+ * The server distinguishes several outcomes via HTTP status + `code`
+ * field (see `src/app/api/v1/library/refs/route.ts`):
  *
  *   201 → { added: {...} }                         → "added"
  *   404 { code: "not_found" }                      → "not-found"
  *   409 { code: "already_in_library" }             → "already-in-library"
  *   409 { code: "self_ownership" }                 → "self-ownership"
  *   403 { code: "plan_limit" }                     → mapErrorResponse → validationError
- *   403 { code: "scope_required" } (or similar)    → mapErrorResponse → scopeError
+ *   403 { code: "insufficient_scope" }             → mapErrorResponse → scopeError
  *   401                                             → mapErrorResponse → authError
  *
  * The 404 / 409 cases are documented idempotent-friendly outcomes that
@@ -682,7 +690,7 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
  * @returns {Promise<LibraryAddResult>}
  */
 export async function addSkillToLibrary(serverUrl, apiKey, owner, name) {
-  const url = `${normalizeUrl(serverUrl)}/api/v1/library`;
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/refs`;
   const res = await safeFetch(url, {
     method: "POST",
     headers: {
@@ -756,6 +764,156 @@ export async function addSkillToLibrary(serverUrl, apiKey, owner, name) {
   throw err;
 }
 
+// ── /api/v1/library (POST — multipart file-push, #1452) ─────────────────
+
+/**
+ * @typedef {Object} PushSkillFile
+ * @property {string} relativePath - POSIX-style skill-relative path (e.g. "references/intro.md").
+ * @property {Uint8Array | Buffer} content - Raw file bytes.
+ */
+
+/**
+ * @typedef {Object} PushSkillResultCreated
+ * @property {"created"} action
+ * @property {null} bump
+ * @property {any} skill
+ *
+ * @typedef {Object} PushSkillResultUpdated
+ * @property {"updated"} action
+ * @property {"major" | "minor"} bump
+ * @property {any} skill
+ *
+ * @typedef {Object} PushSkillResultUnchanged
+ * @property {"unchanged"} action
+ * @property {null} bump
+ * @property {any} skill
+ *
+ * @typedef {PushSkillResultCreated | PushSkillResultUpdated | PushSkillResultUnchanged} PushSkillResult
+ */
+
+/**
+ * POST /api/v1/library — multipart file-push / upsert (#1452).
+ *
+ * Uploads the whole skill folder per the agentskills.io spec. Every file
+ * (including the root `SKILL.md`) goes up as a `files[]` part with its
+ * in-skill relative path carried via the `Content-Disposition: filename`
+ * parameter (RFC 7578). The server identifies SKILL.md by exact-match
+ * `filename === "SKILL.md"` (case-sensitive, no path prefix).
+ *
+ * The `Idempotency-Key` header is set on every call (auto-generated if
+ * not supplied) so transient network failures can be retried safely. The
+ * server replays the cached response on a same-key + same-body retry
+ * within 24h.
+ *
+ * Server outcomes (see `src/app/api/v1/library/route.ts`):
+ *   201 { action: "created", bump: null, skill: SyncSkill }
+ *   200 { action: "updated", bump: "major"|"minor", skill: SyncSkill }
+ *   200 { action: "unchanged", bump: null, skill: SyncSkill }
+ *   400 { code: "missing_skill_md" | "invalid_skill_md" | "invalid_path" | "invalid_multipart" }
+ *   403 { code: "plan_limit" | "scope_required" }
+ *   409 { code: "source_conflict" | "idempotency_key_in_progress" }
+ *   413 { code: "payload_too_large" }
+ *   422 { code: "idempotency_key_reused" }
+ *   429 — rate-limited
+ *
+ * Documented 4xx/2xx outcomes return a discriminated union. Anything
+ * else is routed through mapErrorResponse for typed-error throwing.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {Object} input
+ * @param {PushSkillFile[]} input.files - The skill folder (SKILL.md plus supporting files).
+ * @param {string} [input.idempotencyKey] - Override the auto-generated key. Pass to retry idempotently.
+ * @returns {Promise<PushSkillResult>}
+ */
+export async function pushSkill(serverUrl, apiKey, input) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library`;
+  const idempotencyKey = input.idempotencyKey ?? generateIdempotencyKey();
+
+  const fd = new FormData();
+  for (const file of input.files) {
+    // Per RFC 7578 §4.2, `filename` carries the per-part relative path.
+    // The `File` constructor's second arg sets the `Content-Disposition:
+    // filename` parameter via undici's native FormData encoding. `File`
+    // accepts a `BlobPart[]` directly (Uint8Array / Buffer / Blob /
+    // string), so the previous `new Blob([content])` round-trip was
+    // unnecessary allocation.
+    fd.append("files", new File([file.content], file.relativePath));
+  }
+
+  // `retry: true` is safe here despite this being a write endpoint —
+  // every request carries an `Idempotency-Key` header (auto-generated
+  // above if not provided), and the server (#1465 middleware) replays
+  // the cached response on same-key + same-body retries within 24h.
+  // Without retry, a transient 503 from a cold-start Vercel function
+  // surfaces as an immediate `networkError` to the user even though
+  // the operation could safely re-attempt.
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: {
+      ...(await authHeaders(apiKey)),
+      "Idempotency-Key": idempotencyKey,
+      // Note: do NOT set Content-Type for FormData — undici will set
+      // `multipart/form-data; boundary=...` automatically. Setting it
+      // here would omit the boundary parameter and the server's parse
+      // would fail.
+    },
+    body: fd,
+    retry: true,
+  });
+
+  if (res.status === 200 || res.status === 201) {
+    const body = await parseJsonOrThrow(res, url);
+    if (
+      body?.action === "created" ||
+      body?.action === "updated" ||
+      body?.action === "unchanged"
+    ) {
+      return {
+        action: body.action,
+        bump: body.bump ?? null,
+        skill: body.skill,
+      };
+    }
+    throw networkError(
+      `Library push returned ${res.status} with unexpected action "${body?.action}" from ${url}`,
+    );
+  }
+
+  // Documented 4xx outcomes flow through mapErrorResponse so the CLI
+  // surfaces them with the same `code`-discriminated handling pattern
+  // used for catalog-add. The `*_too_large`, `*_in_progress`, and
+  // `*_reused` codes share a 4xx envelope; mapErrorResponse maps them
+  // to validationError/scopeError/authError consistently.
+  const err = await mapErrorResponse(res, url);
+  if (err === null) {
+    throw validationError(
+      `Library push returned ${res.status} with no documented meaning.`,
+    );
+  }
+  throw err;
+}
+
+/**
+ * Generate a random Idempotency-Key. UUID v4 if `crypto.randomUUID` is
+ * available; falls back to a hex random for older Node runtimes (Node
+ * 19+ ships randomUUID at the top level, so this is defensive).
+ */
+function generateIdempotencyKey() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 // ── /api/v1/library/[owner]/[name] (DELETE — remove from library) ──────
 
 /**