skillrepo 2.0.0 → 3.0.0

package/src/lib/http.mjs

@@ -1,66 +1,846 @@
 /**
- * HTTP client for the SkillRepo API.
- * Uses Node 18+ built-in fetch. Zero dependencies.
+ * HTTP client for the SkillRepo v1 API (#646 PR2).
+ *
+ * Replaces the v2.0.0 setup-payload client with one function per
+ * documented v1 endpoint. Every endpoint is implemented as a thin
+ * fetch + status-code dispatcher that returns a structured result
+ * (success or typed CliError) so commands can map outcomes to
+ * exit codes without duplicating HTTP bookkeeping.
+ *
+ * Design rules:
+ *   • Zero non-Node dependencies — use built-in `fetch`
+ *   • Every function takes `(serverUrl, apiKey, ...args)` so callers
+ *     stay explicit about credentials and target
+ *   • 401 → authError (exit 2)
+ *   • 403 with `code: scope_required` (or any 403 on a scoped route) → scopeError (exit 4)
+ *   • 403 generic → authError (suspended account)
+ *   • 404 → null result (let caller decide if that's an error)
+ *   • 429/5xx → networkError with the response body as hint
+ *   • Network failures (fetch throws) → networkError
+ *
+ * The `User-Agent` header threads through every request so server-side
+ * telemetry can attribute traffic by CLI version.
  */
 
-const VERSION = "1.9.0";
+import {
+  authError,
+  networkError,
+  scopeError,
+  validationError,
+  withRetry,
+} from "./errors.mjs";
+
 const DEFAULT_URL = "https://skillrepo.dev";
 
 /**
- * Fetch the setup payload from the SkillRepo API.
- * @param {string} apiKey - Access key (sk_live_...)
- * @param {string} [baseUrl] - SkillRepo base URL (defaults to https://skillrepo.dev)
- * @returns {Promise<object>} The setup payload
+ * Default per-request timeout in milliseconds. The CLI must NOT hang
+ * indefinitely on a slow or unreachable server — every fetch wraps
+ * itself in an AbortController that fires this timeout. PR4's retry
+ * logic layers on top by wrapping individual calls.
+ *
+ * 30 seconds is generous for the slowest expected operation
+ * (the bulk library sync with 100+ inlined skill files), and short
+ * enough that a hung connection surfaces as a clean error within
+ * the user's patience window. Override via SKILLREPO_TIMEOUT_MS for
+ * smoke tests against a known-slow staging environment.
+ *
+ * Special values:
+ *   • SKILLREPO_TIMEOUT_MS=0 → disable the timeout entirely (Infinity).
+ *     Use only when you know the server can hang forever (debugging).
+ *   • SKILLREPO_TIMEOUT_MS=<positive> → use that value
+ *   • SKILLREPO_TIMEOUT_MS=<negative or non-numeric> → fall back to 30s
+ */
+const DEFAULT_TIMEOUT_MS = (() => {
+  const raw = process.env.SKILLREPO_TIMEOUT_MS;
+  if (raw === "0") return Infinity;
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return 30_000;
+})();
+
+// PR3b deleted the legacy AuthError/SuspendedError/NetworkError
+// classes and `fetchSetupPayload` function — the v2.0.0 init flow
+// was rewritten to use `validateAccessKey` via the new
+// /api/v1/auth/validate route, and nothing else in the codebase
+// imported those names. The /api/v1/setup route deletion is
+// tracked as a follow-up PR (scheduled after the v3.0.0 npm publish).
+
+/**
+ * Read the package version once at import time. Separate from the
+ * dispatcher so commands that import http.mjs without going through
+ * the binary still get a meaningful UA string.
+ */
+let _cachedVersion = null;
+async function userAgent() {
+  if (_cachedVersion) return `skillrepo-cli/${_cachedVersion}`;
+  try {
+    const pkg = await import("../../package.json", { with: { type: "json" } });
+    _cachedVersion = pkg.default.version;
+  } catch {
+    _cachedVersion = "unknown";
+  }
+  return `skillrepo-cli/${_cachedVersion}`;
+}
+
+/**
+ * Build the canonical headers for every authenticated request.
+ */
+async function authHeaders(apiKey) {
+  // Upfront guard so a misconfigured caller fails with a clear,
+  // typed error instead of sending `Bearer undefined` over the wire.
+  // Without this, the round-trip succeeds (server returns 401), the
+  // user sees an opaque auth error, and server logs get a spammed
+  // literal "undefined" Bearer token. The PR3 commands all flow
+  // through here, so a single guard catches the whole class.
+  //
+  // Round-1 review (PR4) caught that init.mjs trims the key before
+  // persisting, but `--key` flags and env-var fallbacks do NOT —
+  // so a pasted key with a trailing newline could reach this
+  // helper with whitespace and get sent verbatim as
+  // `Bearer sk_live_xyz\n`. We trim unconditionally here so every
+  // path through authHeaders produces a clean Bearer header.
+  if (typeof apiKey !== "string") {
+    throw authError("No access key configured.", {
+      hint: "Run `skillrepo init` or pass --key <sk_live_...>.",
+    });
+  }
+  const trimmed = apiKey.trim();
+  if (trimmed === "") {
+    throw authError("No access key configured.", {
+      hint: "Run `skillrepo init` or pass --key <sk_live_...>.",
+    });
+  }
+  return {
+    Authorization: `Bearer ${trimmed}`,
+    Accept: "application/json",
+    "User-Agent": await userAgent(),
+  };
+}
+
+/**
+ * Normalize a server URL for use in API requests.
+ *
+ * Treats `null` and `undefined` as "use the default" but rejects an
+ * explicit empty string so a misconfigured `--url ""` flag fails
+ * loudly instead of silently targeting production. This matters for
+ * write commands (PR3a's add/remove) where a user thinking they're
+ * hitting staging would mutate production data.
+ */
+function normalizeUrl(serverUrl) {
+  if (serverUrl === null || serverUrl === undefined) {
+    return DEFAULT_URL;
+  }
+  if (typeof serverUrl !== "string" || serverUrl.trim() === "") {
+    throw validationError(
+      `Invalid server URL: ${JSON.stringify(serverUrl)}`,
+      { hint: "Pass --url <url> with a valid URL, or omit it to use the default." },
+    );
+  }
+  return serverUrl.replace(/\/+$/, "");
+}
+
+/**
+ * Wrap a fetch invocation with a timeout and a typed error.
+ *
+ * The AbortController fires `DEFAULT_TIMEOUT_MS` after the request
+ * starts. A timeout produces a `networkError` with a hint pointing the
+ * user at `SKILLREPO_TIMEOUT_MS` for the slow-server case. Any other
+ * fetch failure (DNS, refused, TLS, etc.) is also wrapped as
+ * `networkError` so callers can catch by exit code without checking
+ * the underlying cause.
+ *
+ * Signal composition: the init may include its own `signal`, but this
+ * function intentionally OVERWRITES it with the timeout signal — see
+ * the inline comment at the spread. When retry is enabled, each
+ * attempt creates its own `AbortController` inside the nested
+ * `attempt()` closure so aborting attempt 1 does NOT cascade into
+ * attempt 2 — this is the per-attempt timeout pattern. No caller
+ * passes its own signal today, so first-caller-wins on the spread
+ * is still acceptable for the single-attempt path.
+ *
+ * If `DEFAULT_TIMEOUT_MS` is `Infinity` (set via `SKILLREPO_TIMEOUT_MS=0`),
+ * we skip the `setTimeout` entirely so we don't leak a never-firing
+ * timer into the event loop.
+ */
+async function safeFetch(url, init = {}) {
+  // `retry` and `retryOptions` are consumed here and NOT forwarded
+  // to fetch — pull them out before building the fetch init.
+  const { retry, retryOptions, ...fetchInit } = init;
+
+  const attempt = async () => {
+    const controller = new AbortController();
+    const timeoutId = Number.isFinite(DEFAULT_TIMEOUT_MS)
+      ? setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS)
+      : null;
+    try {
+      // Intentional: our timeout signal wins over any caller-provided
+      // signal. The retry loop creates a fresh controller per attempt
+      // so aborting attempt 1 doesn't cascade into attempt 2.
+      return await fetch(url, { ...fetchInit, signal: controller.signal });
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw networkError(
+          `Request to ${url} timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+          {
+            cause: err,
+            hint: "Set SKILLREPO_TIMEOUT_MS (milliseconds) to override, or 0 to disable the timeout.",
+          },
+        );
+      }
+      throw networkError(`Cannot reach ${url}: ${err.message}`, { cause: err });
+    } finally {
+      if (timeoutId !== null) clearTimeout(timeoutId);
+    }
+  };
+
+  if (!retry) {
+    return attempt();
+  }
+
+  // Retry path: wrap attempt() in withRetry so both a thrown
+  // networkError AND a Response with a transient status get retried.
+  // The retried attempt() returns a Response — withRetry checks
+  // `isRetryable(result)` which handles the Response case via the
+  // TRANSIENT_STATUS_CODES set. After retries are exhausted (either
+  // from success on a later attempt or from running out), we return
+  // whatever attempt() returned so mapErrorResponse handles the
+  // final status normally.
+  //
+  // --verbose wiring: the dispatcher sets SKILLREPO_VERBOSE=1 when
+  // the user passes --verbose, and this layer installs a default
+  // onRetry handler that writes to stderr. Callers can still pass
+  // their own retryOptions.onRetry to override (it wins). Without
+  // --verbose, there's no onRetry handler and retries fire silently
+  // — that's the pre-existing behavior.
+  const mergedOptions = resolveRetryOptions(url, retryOptions);
+  return withRetry(attempt, mergedOptions);
+}
+
+/**
+ * Merge caller-supplied retry options with the verbose default.
+ * When SKILLREPO_VERBOSE is truthy and the caller did not supply
+ * its own onRetry, install a default handler that reports each
+ * retry attempt to stderr. The handler honors NO_COLOR and is
+ * silenced when the caller supplies its own onRetry (explicit
+ * test injections still win).
+ */
+function resolveRetryOptions(url, callerOptions) {
+  if (!process.env.SKILLREPO_VERBOSE) return callerOptions;
+  if (callerOptions?.onRetry) return callerOptions;
+
+  const dim = (s) =>
+    process.env.NO_COLOR || !process.stderr.isTTY ? s : `\x1b[2m${s}\x1b[0m`;
+  const onRetry = ({ attempt, delayMs, cause }) => {
+    const causeSummary =
+      cause instanceof Error
+        ? cause.message
+        : cause && typeof cause === "object" && typeof cause.status === "number"
+        ? `HTTP ${cause.status}`
+        : String(cause);
+    process.stderr.write(
+      dim(
+        `  [retry] ${url}: attempt ${attempt} failed (${causeSummary}), ` +
+          `sleeping ${delayMs}ms before retry\n`,
+      ),
+    );
+  };
+  return { ...(callerOptions ?? {}), onRetry };
+}
+
+/**
+ * Parse a JSON body in the success path, wrapping any parse failure
+ * as a typed `networkError`. The error path uses its own `try/catch`
+ * around `res.json()` because it tolerates a body-less or non-JSON
+ * response (the status code is the signal). The success path cannot
+ * tolerate a malformed body — if a proxy or CDN returned 200 with an
+ * HTML error page, the consumer would otherwise get an untyped
+ * `SyntaxError` with no exit code.
+ */
+async function parseJsonOrThrow(res, url) {
+  try {
+    return await res.json();
+  } catch (err) {
+    throw networkError(
+      `Server returned a non-JSON ${res.status} response from ${url}`,
+      {
+        cause: err,
+        hint: "An upstream proxy or CDN may have replaced the response body. Check the URL or retry.",
+      },
+    );
+  }
+}
+
+/**
+ * Map an error response body to a CliError of the right exit code.
+ * Pulled out as a shared helper so every endpoint applies the same
+ * 401/403 semantics.
+ */
+async function mapErrorResponse(res, url) {
+  let body = {};
+  try {
+    body = await res.json();
+  } catch {
+    /* not JSON — body stays {} */
+  }
+  const message = body.error || `${res.status} ${res.statusText}`;
+  const code = body.code;
+
+  if (res.status === 401) {
+    return authError(message, {
+      hint: "Run `skillrepo init` to refresh your access key.",
+    });
+  }
+  if (res.status === 403) {
+    // 403 has THREE distinct meanings on the CLI surface, distinguished
+    // by the `code` field in the response body:
+    //
+    //   1. `plan_limit` — the user is over their library quota. POST
+    //      /api/v1/library returns this with code `plan_limit` per
+    //      `src/app/api/v1/library/route.ts:226-235`. The route comment
+    //      EXPLICITLY documents that the CLI must distinguish this from
+    //      scope errors. We map it to `validationError` (exit 5) with a
+    //      hint pointing at billing — it is not a key-permission issue
+    //      so neither authError nor scopeError is the right fit, and
+    //      adding a dedicated planLimitError to the exit code matrix is
+    //      out of scope for v3.0.0.
+    //
+    //   2. Scope-related 403s carry a `code` containing "scope" (the
+    //      exact name is documented in #875). These map to scopeError.
+    //
+    //   3. Generic 403 — suspended account, blocked user, etc. Maps to
+    //      authError with a "contact support" hint.
+    if (typeof code === "string" && code === "plan_limit") {
+      return validationError(message, {
+        hint: "Upgrade your plan at /app/settings/billing or remove an existing skill from your library.",
+      });
+    }
+    if (typeof code === "string" && code.toLowerCase().includes("scope")) {
+      return scopeError(message, {
+        hint: "Create a write-scoped key at /app/settings/access-keys.",
+      });
+    }
+    return authError(message, {
+      hint: "If your account is suspended, contact support.",
+    });
+  }
+  if (res.status === 404) {
+    return null; // Caller decides
+  }
+  if (res.status === 429) {
+    // 429 hits mapErrorResponse in two cases: (1) a read-only
+    // endpoint's retry budget was exhausted (safeFetch with
+    // retry:true), or (2) a write endpoint that doesn't retry
+    // (add/remove) just saw its single shot return 429. The old
+    // hint claimed "retried automatically" which is only true for
+    // case 1 — case 2 users saw a false claim. The generic hint
+    // below is accurate for both without needing to thread the
+    // retry flag all the way through.
+    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.",
+    });
+  }
+  if (res.status >= 500) {
+    return networkError(`Server error ${res.status} from ${url}: ${message}`);
+  }
+  // Generic 4xx (validation etc.)
+  return validationError(message);
+}
+
+// ── /api/v1/auth/validate ──────────────────────────────────────────────
+
+/**
+ * @typedef {Object} AuthValidateResult
+ * @property {string} userId
+ * @property {string} accountId
+ * @property {string} accountSlug
+ * @property {string} accountName
+ * @property {string[]} scopes
+ * @property {string} keyId
+ * @property {string} tier
+ */
+
+/**
+ * POST /api/v1/auth/validate — verify an access key and fetch the
+ * authenticated account context. Replaces the deprecated
+ * `/api/v1/setup` endpoint for credential validation.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @returns {Promise<AuthValidateResult>}
+ */
+export async function validateAccessKey(serverUrl, apiKey) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/auth/validate`;
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: await authHeaders(apiKey),
+    // POST /auth/validate is side-effect-free on the server (it
+    // only reads the key and returns account context), so retrying
+    // a transient 5xx is safe. 4xx auth errors are NOT retried
+    // because isRetryable() only matches networkError + TRANSIENT_STATUS_CODES.
+    retry: true,
+  });
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) {
+      // 404 on validate means the route doesn't exist on the server —
+      // surface that as a validation error so the user knows the URL
+      // is wrong, not the key.
+      throw validationError(`The server at ${normalizeUrl(serverUrl)} does not expose /api/v1/auth/validate. Is --url correct?`);
+    }
+    throw err;
+  }
+  return parseJsonOrThrow(res, url);
+}
+
+// ── /api/v1/library ─────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} SyncFile
+ * @property {string} path
+ * @property {string} content
+ * @property {string} sha256
+ * @property {number} size
+ * @property {string} contentType
+ * @property {string} [encoding] - Optional encoding hint. The server
+ *   sends `"utf-8"` on the SKILL.md entry; supporting files generally
+ *   omit it. PR2 commands should pass through verbatim — they don't
+ *   need to interpret it.
+ */
+
+/**
+ * @typedef {Object} SyncSkill
+ * @property {string} owner
+ * @property {string} name
+ * @property {string} version
+ * @property {string} description
+ * @property {string|null} [license]
+ * @property {string[]} [keywords] - Trigger keywords extracted from the
+ *   skill's frontmatter `triggers` field. Used by `list` and `search`
+ *   for display, not by `update`/`get` for anything functional.
+ * @property {string} etag - Per-skill version-pinned ETag computed by
+ *   the server as `"<owner>/<name>@<updatedAtMs>"`. Stable across
+ *   reads of the same version. PR4's retry logic may use this for
+ *   single-skill cache invalidation.
+ * @property {object} [contextSignals] - Server-computed activation
+ *   signals (file globs, prompt patterns, etc.). Forward-compatible
+ *   payload — PR2 commands ignore it.
+ * @property {SyncFile[]} files
+ * @property {boolean} [filesIncomplete] - True when one or more files
+ *   failed to inline from blob storage. CLI must NOT cache the
+ *   skill's ETag in that case (the server already stripped its own
+ *   ETag header for incomplete responses).
+ * @property {string} updatedAt
+ */
+
+/**
+ * @typedef {Object} Removal
+ * @property {string} owner
+ * @property {string} name
+ * @property {string} removedAt
  */
-export async function fetchSetupPayload(apiKey, baseUrl) {
-  const url = `${(baseUrl || DEFAULT_URL).replace(/\/+$/, "")}/api/v1/setup`;
 
-  const res = await fetch(url, {
+/**
+ * @typedef {Object} LibrarySyncResult
+ * @property {SyncSkill[]} skills
+ * @property {Removal[]} removals
+ * @property {string} syncedAt
+ * @property {string|null} etag
+ * @property {boolean} notModified  - True if the server returned 304
+ */
+
+/**
+ * GET /api/v1/library — bulk library sync with ETag + delta support.
+ *
+ * Returns either a fresh payload OR a `notModified: true` sentinel.
+ *
+ * Contract for the 304 path: `notModified: true` is reachable ONLY
+ * when `opts.ifNoneMatch` was provided, because the server only
+ * returns 304 in response to an `If-None-Match` header. In that case
+ * the returned `etag` is whatever the caller sent (the same value is
+ * still authoritative — the server confirms it's current). If a
+ * misconfigured server returns 304 without an `If-None-Match` (rare;
+ * misbehaving CDN/proxy), `etag` falls back to null and the caller's
+ * next sync will be unconditional. That fallback is a safety net, not
+ * a contract — callers should treat `etag === null && notModified`
+ * as "something is wrong, refetch fresh".
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {object} [opts]
+ * @param {string} [opts.ifNoneMatch] - ETag to send as If-None-Match
+ * @param {string} [opts.since]       - ISO timestamp for delta filter
+ * @returns {Promise<LibrarySyncResult>}
+ */
+export async function getLibrary(serverUrl, apiKey, opts = {}) {
+  const base = normalizeUrl(serverUrl);
+  const params = new URLSearchParams();
+  if (opts.since) params.set("since", opts.since);
+  const url = params.toString()
+    ? `${base}/api/v1/library?${params.toString()}`
+    : `${base}/api/v1/library`;
+
+  const headers = await authHeaders(apiKey);
+  if (opts.ifNoneMatch) {
+    headers["If-None-Match"] = opts.ifNoneMatch;
+  }
+
+  // GET /library is read-only and idempotent — safe to retry on
+  // transient 5xx / network errors / 429.
+  const res = await safeFetch(url, { method: "GET", headers, retry: true });
+
+  if (res.status === 304) {
+    return {
+      skills: [],
+      removals: [],
+      syncedAt: new Date().toISOString(),
+      etag: opts.ifNoneMatch || null,
+      notModified: true,
+    };
+  }
+
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) {
+      throw validationError(`Library endpoint returned 404 — server URL probably wrong.`);
+    }
+    throw err;
+  }
+
+  const body = await parseJsonOrThrow(res, url);
+  return {
+    skills: body.skills ?? [],
+    removals: body.removals ?? [],
+    syncedAt: body.syncedAt ?? new Date().toISOString(),
+    etag: res.headers.get("etag"),
+    notModified: false,
+  };
+}
+
+// ── /api/v1/skills/[owner]/[name] ───────────────────────────────────────
+
+/**
+ * GET /api/v1/skills/{owner}/{name} — fetch a single skill with inlined
+ * file content.
+ *
+ * Returns `null` on 404. This is intentionally asymmetric with
+ * `validateAccessKey` and `getLibrary`, which throw a `validationError`
+ * when `mapErrorResponse` returns null. The reason: 404 on a single
+ * skill means "this owner/name doesn't exist OR isn't accessible to
+ * you", which is a normal user-facing outcome that the `get` command
+ * surfaces as a clean error message ("skill not found"). 404 on the
+ * library or auth/validate endpoint means the route isn't on the
+ * server at all, which is a configuration mistake the CLI should
+ * loudly flag.
+ *
+ * The double-handling (`if (res.status === 404)` AND
+ * `if (err === null)`) exists for defense-in-depth: the first branch
+ * catches the documented 404 contract, the second catches any future
+ * status code that might be added to `mapErrorResponse`'s null-return
+ * path.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {string} owner
+ * @param {string} name
+ * @returns {Promise<SyncSkill|null>}
+ */
+export async function getSkill(serverUrl, apiKey, owner, name) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/skills/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
+  const res = await safeFetch(url, {
     method: "GET",
+    headers: await authHeaders(apiKey),
+    // Read-only and idempotent.
+    retry: true,
+  });
+
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) return null;
+    throw err;
+  }
+
+  const body = await parseJsonOrThrow(res, url);
+  return body.skill ?? null;
+}
+
+// ── /api/v1/library (POST — add to library) ────────────────────────────
+
+/**
+ * @typedef {Object} LibraryAddSuccess
+ * @property {"added"} status - Server confirmed the row was inserted
+ * @property {string} owner
+ * @property {string} name
+ * @property {string|null} version
+ * @property {string} addedAt - ISO timestamp
+ *
+ * @typedef {Object} LibraryAddAlreadyInLibrary
+ * @property {"already-in-library"} status
+ * @property {string} owner
+ * @property {string} name
+ *
+ * @typedef {Object} LibraryAddNotFound
+ * @property {"not-found"} status
+ * @property {string} owner
+ * @property {string} name
+ *
+ * @typedef {Object} LibraryAddSelfOwnership
+ * @property {"self-ownership"} status
+ * @property {string} owner
+ * @property {string} name
+ *
+ * @typedef {LibraryAddSuccess | LibraryAddAlreadyInLibrary | LibraryAddNotFound | LibraryAddSelfOwnership} LibraryAddResult
+ */
+
+/**
+ * POST /api/v1/library — add a skill to the authenticated account's
+ * library.
+ *
+ * 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):
+ *
+ *   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
+ *   401                                             → mapErrorResponse → authError
+ *
+ * The 404 / 409 cases are documented idempotent-friendly outcomes that
+ * the CLI's `add` command intentionally routes through its own
+ * dispatcher (not mapErrorResponse) so it can react differently to
+ * each. Everything else flows through mapErrorResponse.
+ *
+ * Returns a discriminated union instead of throwing for the four
+ * "documented outcome" cases. That lets the command handle them
+ * without needing to catch CliError subclasses. Undocumented error
+ * responses are still thrown.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {string} owner
+ * @param {string} name
+ * @returns {Promise<LibraryAddResult>}
+ */
+export async function addSkillToLibrary(serverUrl, apiKey, owner, name) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library`;
+  const res = await safeFetch(url, {
+    method: "POST",
     headers: {
-      Authorization: `Bearer ${apiKey}`,
-      Accept: "application/json",
-      "User-Agent": `skillrepo-cli/${VERSION}`,
+      ...(await authHeaders(apiKey)),
+      "Content-Type": "application/json",
     },
+    body: JSON.stringify({ owner, name }),
   });
 
-  if (res.status === 401) {
-    const body = await res.json().catch(() => ({}));
-    throw new AuthError(body.error || "Invalid access key");
+  if (res.status === 201) {
+    const body = await parseJsonOrThrow(res, url);
+    const added = body?.added ?? {};
+    return {
+      status: "added",
+      owner: added.owner ?? owner,
+      name: added.name ?? name,
+      version: added.version ?? null,
+      addedAt: added.addedAt ?? new Date().toISOString(),
+    };
   }
 
-  if (res.status === 403) {
-    const body = await res.json().catch(() => ({}));
-    throw new SuspendedError(body.error || "Account suspended", body.reason);
+  // 404 — skill doesn't exist or isn't accessible
+  if (res.status === 404) {
+    // Drain the body so the response isn't left open
+    await res.json().catch(() => undefined);
+    return { status: "not-found", owner, name };
   }
 
-  if (!res.ok) {
-    throw new NetworkError(`Server returned ${res.status}: ${res.statusText}`);
+  // 409 — two distinct outcomes, disambiguated by `code`:
+  //   code: "self_ownership"    → "self-ownership" (validationError)
+  //   code: "already_in_library" → "already-in-library" (idempotent)
+  //   anything else             → throw networkError, don't guess
+  //
+  // Previously the 409 handler used `res.json().catch(() => ({}))`
+  // which silently mapped a malformed body to `"already-in-library"`.
+  // The round-1 review caught that — a 409 with a corrupt body that
+  // semantically means self_ownership would have silently fallen
+  // through to the refresh-and-write path. Now we require a
+  // parseable body with one of the two documented codes; any other
+  // shape is a server contract violation and surfaces as a typed
+  // network error.
+  if (res.status === 409) {
+    let body;
+    try {
+      body = await res.json();
+    } catch (err) {
+      throw networkError(
+        `Server returned 409 with unparseable body from ${url}`,
+        { cause: err },
+      );
+    }
+    if (body?.code === "self_ownership") {
+      return { status: "self-ownership", owner, name };
+    }
+    if (body?.code === "already_in_library") {
+      return { status: "already-in-library", owner, name };
+    }
+    // Unknown 409 code — don't guess which outcome was meant
+    throw validationError(
+      `Server returned 409 with unexpected code "${body?.code}" from ${url}`,
+    );
   }
 
-  return res.json();
+  // Everything else → typed error via mapErrorResponse
+  const err = await mapErrorResponse(res, url);
+  if (err === null) {
+    throw validationError(
+      `Library POST returned ${res.status} with no documented meaning.`,
+    );
+  }
+  throw err;
 }
 
-// ── Error types ─────────────────────────────────────────────────────────
+// ── /api/v1/library/[owner]/[name] (DELETE — remove from library) ──────
 
-export class AuthError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AuthError";
+/**
+ * @typedef {Object} LibraryRemoveSuccess
+ * @property {"removed"} status
+ * @property {string} owner
+ * @property {string} name
+ * @property {string} removedAt
+ *
+ * @typedef {Object} LibraryRemoveNotInLibrary
+ * @property {"not-in-library"} status
+ * @property {string} owner
+ * @property {string} name
+ *
+ * @typedef {LibraryRemoveSuccess | LibraryRemoveNotInLibrary} LibraryRemoveResult
+ */
+
+/**
+ * DELETE /api/v1/library/{owner}/{name} — remove a skill from the
+ * authenticated account's library.
+ *
+ * The server writes a `libraryRemovals` tombstone so other machines
+ * syncing this account see the removal on their next sync (pending
+ * the ETag fix in #875). The CLI's `remove` command does NOT depend
+ * on the tombstone for local cleanup — it deletes the local files
+ * directly after a successful DELETE (see the plan's #875 workaround).
+ *
+ * Documented outcomes:
+ *   200 → { removed: {...} }        → "removed"
+ *   404 { code: "not_in_library" }  → "not-in-library" (idempotent)
+ *   403 { code: "scope_required" }  → mapErrorResponse → scopeError
+ *   401                              → mapErrorResponse → authError
+ *
+ * Like `addSkillToLibrary`, this returns a discriminated union for the
+ * two documented outcomes so the command's idempotency logic stays
+ * out of mapErrorResponse.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {string} owner
+ * @param {string} name
+ * @returns {Promise<LibraryRemoveResult>}
+ */
+export async function removeSkillFromLibrary(serverUrl, apiKey, owner, name) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
+  const res = await safeFetch(url, {
+    method: "DELETE",
+    headers: await authHeaders(apiKey),
+  });
+
+  if (res.status === 200) {
+    const body = await parseJsonOrThrow(res, url);
+    const removed = body?.removed ?? {};
+    return {
+      status: "removed",
+      owner: removed.owner ?? owner,
+      name: removed.name ?? name,
+      removedAt: removed.removedAt ?? new Date().toISOString(),
+    };
   }
-}
 
-export class SuspendedError extends Error {
-  constructor(message, reason) {
-    super(message);
-    this.name = "SuspendedError";
-    this.reason = reason;
+  if (res.status === 404) {
+    await res.json().catch(() => undefined);
+    return { status: "not-in-library", owner, name };
   }
+
+  const err = await mapErrorResponse(res, url);
+  if (err === null) {
+    throw validationError(
+      `Library DELETE returned ${res.status} with no documented meaning.`,
+    );
+  }
+  throw err;
 }
 
-export class NetworkError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NetworkError";
+// ── /api/v1/skills/search ───────────────────────────────────────────────
+
+/**
+ * @typedef {Object} SearchResult
+ * @property {string} owner
+ * @property {string} name
+ * @property {string} description
+ * @property {string} version
+ * @property {string|null} license
+ * @property {string|null} compatibility
+ * @property {number} installs
+ * @property {number|null} avgRating
+ * @property {string|null} safetyGrade
+ * @property {string|null} publishedAt
+ */
+
+/**
+ * @typedef {Object} SearchResponse
+ * @property {SearchResult[]} skills
+ * @property {{ total: number, limit: number, offset: number }} pagination
+ */
+
+/**
+ * GET /api/v1/skills/search — public skill search via account key.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {object} opts
+ * @param {string} [opts.q]
+ * @param {number} [opts.limit]
+ * @param {number} [opts.offset]
+ * @param {string} [opts.sort]
+ * @returns {Promise<SearchResponse>}
+ */
+export async function searchSkills(serverUrl, apiKey, opts = {}) {
+  const base = normalizeUrl(serverUrl);
+  const params = new URLSearchParams();
+  if (opts.q) params.set("q", opts.q);
+  if (opts.limit != null) params.set("limit", String(opts.limit));
+  if (opts.offset != null) params.set("offset", String(opts.offset));
+  if (opts.sort) params.set("sort", opts.sort);
+  const url = params.toString()
+    ? `${base}/api/v1/skills/search?${params.toString()}`
+    : `${base}/api/v1/skills/search`;
+
+  const res = await safeFetch(url, {
+    method: "GET",
+    headers: await authHeaders(apiKey),
+    // Read-only and idempotent.
+    retry: true,
+  });
+
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) {
+      throw validationError(`Search endpoint returned 404 — server URL probably wrong.`);
+    }
+    throw err;
   }
+
+  const body = await parseJsonOrThrow(res, url);
+  return {
+    skills: body.skills ?? [],
+    pagination: body.pagination ?? { total: 0, limit: opts.limit ?? 20, offset: opts.offset ?? 0 },
+  };
 }