skillrepo 2.0.0 → 3.0.0

package/src/test/lib/http.test.mjs

@@ -0,0 +1,1198 @@
+/**
+ * Unit tests for src/lib/http.mjs (PR2 of #646).
+ *
+ * Strategy: spin up a minimal in-process HTTP server per test (or per
+ * suite when shape is identical) and point the http.mjs functions at
+ * it. This is the same pattern as the existing E2E mock-server, scoped
+ * down to the unit-test layer so we exercise every status-code branch
+ * and every error contract without spawning a subprocess.
+ *
+ * Coverage targets:
+ *   • validateAccessKey: 200 happy, 401, 403 (suspended), 403 (scope),
+ *     403 (plan_limit), 404 (route missing), 429, 500, network failure
+ *   • getLibrary: 200 fresh, 304 short-circuit, since param, ETag echo,
+ *     400 invalid since, 401, 5xx, missing fields tolerance
+ *   • getSkill: 200 happy, 200 with `skill: null`, 404 (returns null),
+ *     401, 403 (scope), encodeURIComponent applied
+ *   • searchSkills: 200 happy with results, 200 empty, query
+ *     encoding, limit/offset/sort, 401
+ *   • mapErrorResponse: 401 → authError, 403 plan_limit → validationError,
+ *     403 scope → scopeError, 403 generic → authError, 404 → null,
+ *     429 → networkError, 5xx → networkError, generic 4xx → validationError
+ *   • Edge cases: empty apiKey rejected upfront, empty serverUrl
+ *     rejected, non-JSON success body wrapped as networkError, AbortError
+ *     wrapped as networkError, SKILLREPO_TIMEOUT_MS environment handling
+ *
+ * `parseJsonOrThrow` and `mapErrorResponse` are not exported; we
+ * exercise them indirectly via the public functions.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { once } from "node:events";
+
+import {
+  validateAccessKey,
+  getLibrary,
+  getSkill,
+  searchSkills,
+  addSkillToLibrary,
+  removeSkillFromLibrary,
+} from "../../lib/http.mjs";
+import {
+  CliError,
+  EXIT_AUTH,
+  EXIT_NETWORK,
+  EXIT_SCOPE,
+  EXIT_VALIDATION,
+} from "../../lib/errors.mjs";
+
+// ── Tiny test HTTP server ──────────────────────────────────────────────
+
+/**
+ * Spin up an HTTP server with a per-test handler. Returns
+ * { url, close, lastRequest }. The handler signature mirrors node:http.
+ */
+async function startServer(handler) {
+  let lastRequest = null;
+  const server = createServer((req, res) => {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => {
+      lastRequest = {
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        body,
+      };
+      handler(req, res, body);
+    });
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const { port } = server.address();
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+    get lastRequest() { return lastRequest; },
+  };
+}
+
+/** Send a JSON response. */
+function jsonRes(res, status, body, extraHeaders = {}) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  for (const [k, v] of Object.entries(extraHeaders)) res.setHeader(k, v);
+  res.end(JSON.stringify(body));
+}
+
+const VALID_KEY = "sk_live_test_abc123";
+
+// ── validateAccessKey ──────────────────────────────────────────────────
+
+describe("validateAccessKey", () => {
+  it("returns the account context on 200", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 200, {
+        userId: "user-1",
+        accountId: "acc-1",
+        accountSlug: "alice",
+        accountName: "Alice's Org",
+        scopes: ["registry:read", "registry:write"],
+        keyId: "key-1",
+        tier: "free",
+      });
+    });
+    try {
+      const result = await validateAccessKey(srv.url, VALID_KEY);
+      assert.equal(result.userId, "user-1");
+      assert.equal(result.accountSlug, "alice");
+      assert.deepEqual(result.scopes, ["registry:read", "registry:write"]);
+      // Verify the request was actually a POST with the bearer header
+      assert.equal(srv.lastRequest.method, "POST");
+      assert.equal(srv.lastRequest.headers.authorization, `Bearer ${VALID_KEY}`);
+      assert.match(srv.lastRequest.headers["user-agent"], /^skillrepo-cli\//);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 401, { error: "Invalid access key" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 403 generic (suspended account)", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 403, { error: "Account suspended", code: "suspended" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH && /suspended/i.test(err.message),
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws scopeError on 403 with scope code", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 403, { error: "Insufficient scope", code: "scope_required" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws validationError on 403 plan_limit (NOT authError)", async () => {
+    // This is the central proof of the round-3 review fix: plan_limit
+    // must not be misrouted to authError ("contact support").
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 403, {
+        error: "Your free plan allows up to 5 library skills.",
+        code: "plan_limit",
+      });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) =>
+          err instanceof CliError &&
+          err.exitCode === EXIT_VALIDATION &&
+          /plan/i.test(err.message),
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws validationError on 404 (route missing)", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 404, { error: "Not found" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("exhausts retries on persistent 429 and surfaces networkError", async () => {
+    // PR4 added `retry: true` to validateAccessKey, so a persistent
+    // 429 should trigger the full 3-attempt retry loop before the
+    // terminal networkError surfaces. Before PR4, this test was a
+    // single-shot "429 → networkError" check; after the retry
+    // wiring it needs an explicit hit count or it silently stops
+    // verifying what it claims to test.
+    let hits = 0;
+    const srv = await startServer((req, res) => {
+      hits++;
+      jsonRes(res, 429, { error: "Rate limit exceeded" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+      assert.equal(hits, 3, "expected 3 attempts (initial + 2 retries) before giving up");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on 500", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 500, { error: "Internal Server Error" });
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError when the server is unreachable", async () => {
+    // Port 1 is reserved and refuses connections on most systems.
+    await assert.rejects(
+      () => validateAccessKey("http://127.0.0.1:1", VALID_KEY),
+      (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+    );
+  });
+
+  it("throws networkError on a non-JSON 200 response", async () => {
+    const srv = await startServer((req, res) => {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html");
+      res.end("<html>upstream broken</html>");
+    });
+    try {
+      await assert.rejects(
+        () => validateAccessKey(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("rejects empty apiKey upfront with authError (no network round-trip)", async () => {
+    // No server needed — the upfront guard fires before any fetch.
+    await assert.rejects(
+      () => validateAccessKey("http://127.0.0.1:1", ""),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH && /No access key/.test(err.message),
+    );
+  });
+
+  it("rejects null apiKey upfront with authError", async () => {
+    await assert.rejects(
+      () => validateAccessKey("http://127.0.0.1:1", null),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("rejects empty serverUrl with validationError", async () => {
+    await assert.rejects(
+      () => validateAccessKey("", VALID_KEY),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /Invalid server URL/.test(err.message),
+    );
+  });
+
+  it("accepts undefined serverUrl (does NOT throw validationError upfront)", async () => {
+    // `undefined` is the documented "use the default URL" sentinel.
+    // It must NOT trip the empty-string guard. The downstream fetch
+    // will hit the real default URL and either fail (no network /
+    // sandbox) or get 401 from the real server (test key is bogus).
+    // Both outcomes are acceptable — the test only locks in that
+    // the upfront validationError DOESN'T fire for undefined.
+    await assert.rejects(
+      () => validateAccessKey(undefined, VALID_KEY),
+      (err) => err instanceof CliError && err.exitCode !== EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── getLibrary ──────────────────────────────────────────────────────────
+
+describe("getLibrary", () => {
+  it("returns skills + removals + etag on 200", async () => {
+    const srv = await startServer((req, res) => {
+      assert.equal(req.method, "GET");
+      assert.match(req.url, /^\/api\/v1\/library/);
+      jsonRes(res, 200, {
+        skills: [{ owner: "alice", name: "pdf", version: "1.0.0", files: [] }],
+        removals: [],
+        syncedAt: "2025-01-01T00:00:00Z",
+      }, { ETag: '"abc123"' });
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY);
+      assert.equal(result.skills.length, 1);
+      assert.equal(result.skills[0].owner, "alice");
+      assert.equal(result.etag, '"abc123"');
+      assert.equal(result.notModified, false);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("sends If-None-Match when ifNoneMatch is provided", async () => {
+    const srv = await startServer((req, res) => {
+      // Echo the conditional check
+      if (req.headers["if-none-match"] === '"abc123"') {
+        res.statusCode = 304;
+        res.end();
+        return;
+      }
+      jsonRes(res, 200, { skills: [], removals: [], syncedAt: "x" });
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY, { ifNoneMatch: '"abc123"' });
+      assert.equal(result.notModified, true);
+      assert.equal(result.etag, '"abc123"');
+      assert.deepEqual(result.skills, []);
+      assert.deepEqual(result.removals, []);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("sends since query param when provided", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { skills: [], removals: [{ owner: "a", name: "b", removedAt: "x" }], syncedAt: "x" });
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY, { since: "2025-01-01T00:00:00Z" });
+      assert.match(capturedUrl, /\?since=/);
+      assert.equal(result.removals.length, 1);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("tolerates missing fields in the response (defaults applied)", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 200, {});
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY);
+      assert.deepEqual(result.skills, []);
+      assert.deepEqual(result.removals, []);
+      assert.ok(result.syncedAt); // defaults to new Date().toISOString()
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 401, { error: "nope" }));
+    try {
+      await assert.rejects(
+        () => getLibrary(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on non-JSON 200 body", async () => {
+    const srv = await startServer((req, res) => {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html");
+      res.end("<!doctype html><body>broken</body>");
+    });
+    try {
+      await assert.rejects(
+        () => getLibrary(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+});
+
+// ── getSkill ────────────────────────────────────────────────────────────
+
+describe("getSkill", () => {
+  it("returns the skill on 200", async () => {
+    const srv = await startServer((req, res) => {
+      assert.equal(req.method, "GET");
+      jsonRes(res, 200, {
+        skill: {
+          owner: "alice",
+          name: "pdf",
+          version: "1.0.0",
+          files: [{ path: "SKILL.md", content: "x", sha256: "x", size: 1, contentType: "text/markdown" }],
+        },
+      });
+    });
+    try {
+      const result = await getSkill(srv.url, VALID_KEY, "alice", "pdf");
+      assert.ok(result);
+      assert.equal(result.owner, "alice");
+      assert.equal(result.files.length, 1);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns null on 404", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 404, { error: "not found" }));
+    try {
+      const result = await getSkill(srv.url, VALID_KEY, "alice", "missing");
+      assert.equal(result, null);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns null when body has skill: null on 200 (defensive)", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 200, { skill: null }));
+    try {
+      const result = await getSkill(srv.url, VALID_KEY, "alice", "x");
+      assert.equal(result, null);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("encodes owner and name in the URL path", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { skill: null });
+    });
+    try {
+      await getSkill(srv.url, VALID_KEY, "name with spaces", "name/with/slashes");
+      // Verify encoding: spaces become %20, slashes become %2F
+      assert.match(capturedUrl, /%20/);
+      assert.match(capturedUrl, /%2F/);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 401, { error: "x" }));
+    try {
+      await assert.rejects(
+        () => getSkill(srv.url, VALID_KEY, "a", "b"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws scopeError on 403 with scope code", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 403, { error: "scope required", code: "scope_required" }),
+    );
+    try {
+      await assert.rejects(
+        () => getSkill(srv.url, VALID_KEY, "a", "b"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on non-JSON 200 body", async () => {
+    const srv = await startServer((req, res) => {
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/plain");
+      res.end("not json");
+    });
+    try {
+      await assert.rejects(
+        () => getSkill(srv.url, VALID_KEY, "a", "b"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+});
+
+// ── searchSkills ────────────────────────────────────────────────────────
+
+describe("searchSkills", () => {
+  it("returns skills + pagination on 200", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 200, {
+        skills: [
+          { owner: "a", name: "x", version: "1.0", description: "d", license: null, compatibility: null, installs: 1, avgRating: null, safetyGrade: null, publishedAt: null },
+        ],
+        pagination: { total: 1, limit: 20, offset: 0 },
+      });
+    });
+    try {
+      const result = await searchSkills(srv.url, VALID_KEY, { q: "test" });
+      assert.equal(result.skills.length, 1);
+      assert.equal(result.pagination.total, 1);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("encodes query parameters with special characters", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { skills: [], pagination: { total: 0, limit: 20, offset: 0 } });
+    });
+    try {
+      await searchSkills(srv.url, VALID_KEY, { q: "foo & bar?baz=qux+more" });
+      // URLSearchParams correctly percent-encodes these
+      assert.match(capturedUrl, /q=foo\+%26\+bar%3Fbaz%3Dqux%2Bmore|q=foo%20%26%20bar%3Fbaz%3Dqux%2Bmore/);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("passes limit, offset, sort to the URL", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { skills: [], pagination: { total: 0, limit: 50, offset: 100 } });
+    });
+    try {
+      await searchSkills(srv.url, VALID_KEY, { q: "x", limit: 50, offset: 100, sort: "recent" });
+      assert.match(capturedUrl, /limit=50/);
+      assert.match(capturedUrl, /offset=100/);
+      assert.match(capturedUrl, /sort=recent/);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("tolerates missing pagination in response (provides default)", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 200, { skills: [] }));
+    try {
+      const result = await searchSkills(srv.url, VALID_KEY, { limit: 10, offset: 5 });
+      assert.equal(result.pagination.limit, 10);
+      assert.equal(result.pagination.offset, 5);
+      assert.equal(result.pagination.total, 0);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) => jsonRes(res, 401, { error: "x" }));
+    try {
+      await assert.rejects(
+        () => searchSkills(srv.url, VALID_KEY, { q: "test" }),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+});
+
+// ── Cross-cutting: every endpoint guards empty apiKey and serverUrl ────
+
+describe("http.mjs — credential and URL guards", () => {
+  it("getLibrary rejects empty apiKey", async () => {
+    await assert.rejects(
+      () => getLibrary("http://127.0.0.1:1", ""),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("getSkill rejects empty apiKey", async () => {
+    await assert.rejects(
+      () => getSkill("http://127.0.0.1:1", "", "a", "b"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("searchSkills rejects empty apiKey", async () => {
+    await assert.rejects(
+      () => searchSkills("http://127.0.0.1:1", "", { q: "x" }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("getLibrary rejects empty serverUrl", async () => {
+    await assert.rejects(
+      () => getLibrary("", VALID_KEY),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("getSkill rejects whitespace-only serverUrl", async () => {
+    await assert.rejects(
+      () => getSkill("   ", VALID_KEY, "a", "b"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("getLibrary rejects non-string serverUrl (number)", async () => {
+    await assert.rejects(
+      () => getLibrary(42, VALID_KEY),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── addSkillToLibrary (PR3a) ───────────────────────────────────────────
+
+describe("addSkillToLibrary", () => {
+  it("returns { status: 'added' } on 201", async () => {
+    const srv = await startServer((req, res) => {
+      assert.equal(req.method, "POST");
+      assert.match(req.url, /^\/api\/v1\/library$/);
+      assert.equal(req.headers["content-type"], "application/json");
+      jsonRes(res, 201, {
+        added: {
+          owner: "alice",
+          name: "pdf",
+          version: "1.0.0",
+          addedAt: "2025-01-01T00:00:00Z",
+        },
+      });
+    });
+    try {
+      const result = await addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf");
+      assert.equal(result.status, "added");
+      assert.equal(result.owner, "alice");
+      assert.equal(result.name, "pdf");
+      assert.equal(result.version, "1.0.0");
+      assert.equal(result.addedAt, "2025-01-01T00:00:00Z");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("sends the owner/name JSON body", async () => {
+    const srv = await startServer((req, res) => {
+      jsonRes(res, 201, {
+        added: { owner: "alice", name: "pdf", version: "1", addedAt: "x" },
+      });
+    });
+    try {
+      await addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf");
+      assert.equal(srv.lastRequest.body, JSON.stringify({ owner: "alice", name: "pdf" }));
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { status: 'not-found' } on 404", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 404, { error: "Skill not found", code: "not_found" }),
+    );
+    try {
+      const result = await addSkillToLibrary(srv.url, VALID_KEY, "alice", "ghost");
+      assert.equal(result.status, "not-found");
+      assert.equal(result.owner, "alice");
+      assert.equal(result.name, "ghost");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { status: 'already-in-library' } on 409 default", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 409, {
+        error: "Skill is already in your library",
+        code: "already_in_library",
+      }),
+    );
+    try {
+      const result = await addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf");
+      assert.equal(result.status, "already-in-library");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { status: 'self-ownership' } on 409 with self_ownership code", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 409, {
+        error: "Cannot add your own skill to your library",
+        code: "self_ownership",
+      }),
+    );
+    try {
+      const result = await addSkillToLibrary(srv.url, VALID_KEY, "alice", "my-skill");
+      assert.equal(result.status, "self-ownership");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on 409 with unparseable body (round-1 review fix)", async () => {
+    // Regression for the round-1 finding both reviewers caught:
+    // the previous handler used `.catch(() => ({}))` which silently
+    // mapped a malformed 409 body to `already-in-library`. Now a
+    // malformed body surfaces as a networkError so a self_ownership
+    // outcome can't be silently dropped.
+    const srv = await startServer((req, res) => {
+      res.statusCode = 409;
+      res.setHeader("Content-Type", "text/html");
+      res.end("<html>upstream broken</html>");
+    });
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws validationError on 409 with unknown code (round-1 review fix)", async () => {
+    // A 409 with a code we don't recognize (e.g., a future server
+    // contract change) surfaces as a validationError rather than
+    // silently assuming already-in-library.
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 409, { error: "Weird edge case", code: "brand_new_conflict" }),
+    );
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION && /brand_new_conflict/.test(err.message),
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws validationError on 403 plan_limit (mapErrorResponse path)", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 403, {
+        error: "Your free plan allows up to 5 library skills.",
+        code: "plan_limit",
+      }),
+    );
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws scopeError on 403 scope_required", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 403, { error: "Scope required", code: "scope_required" }),
+    );
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 401, { error: "Invalid access key" }),
+    );
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on 500", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 500, { error: "Internal Server Error" }),
+    );
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("rejects empty apiKey upfront", async () => {
+    await assert.rejects(
+      () => addSkillToLibrary("http://127.0.0.1:1", "", "alice", "pdf"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("rejects empty serverUrl", async () => {
+    await assert.rejects(
+      () => addSkillToLibrary("", VALID_KEY, "alice", "pdf"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── removeSkillFromLibrary (PR3a) ──────────────────────────────────────
+
+describe("removeSkillFromLibrary", () => {
+  it("returns { status: 'removed' } on 200", async () => {
+    const srv = await startServer((req, res) => {
+      assert.equal(req.method, "DELETE");
+      assert.match(req.url, /^\/api\/v1\/library\/alice\/pdf$/);
+      jsonRes(res, 200, {
+        removed: {
+          owner: "alice",
+          name: "pdf",
+          removedAt: "2025-01-01T00:00:00Z",
+        },
+      });
+    });
+    try {
+      const result = await removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "pdf");
+      assert.equal(result.status, "removed");
+      assert.equal(result.owner, "alice");
+      assert.equal(result.name, "pdf");
+      assert.equal(result.removedAt, "2025-01-01T00:00:00Z");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("encodes owner and name in the URL path", async () => {
+    let capturedUrl;
+    const srv = await startServer((req, res) => {
+      capturedUrl = req.url;
+      jsonRes(res, 200, { removed: { owner: "x", name: "y", removedAt: "z" } });
+    });
+    try {
+      await removeSkillFromLibrary(srv.url, VALID_KEY, "owner with space", "name/slash");
+      assert.match(capturedUrl, /%20/);
+      assert.match(capturedUrl, /%2F/);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("returns { status: 'not-in-library' } on 404", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 404, {
+        error: "Skill is not in your library",
+        code: "not_in_library",
+      }),
+    );
+    try {
+      const result = await removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "ghost");
+      assert.equal(result.status, "not-in-library");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws scopeError on 403 scope_required", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 403, { error: "Scope required", code: "scope_required" }),
+    );
+    try {
+      await assert.rejects(
+        () => removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws authError on 401", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 401, { error: "Invalid access key" }),
+    );
+    try {
+      await assert.rejects(
+        () => removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("throws networkError on 500", async () => {
+    const srv = await startServer((req, res) =>
+      jsonRes(res, 500, { error: "boom" }),
+    );
+    try {
+      await assert.rejects(
+        () => removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("rejects empty apiKey upfront", async () => {
+    await assert.rejects(
+      () => removeSkillFromLibrary("http://127.0.0.1:1", "", "alice", "pdf"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("rejects empty serverUrl", async () => {
+    await assert.rejects(
+      () => removeSkillFromLibrary("", VALID_KEY, "alice", "pdf"),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+// ── Retry behavior (PR4, #683) ─────────────────────────────────────────
+
+/**
+ * Start a flaky HTTP server that returns `failuresBeforeSuccess`
+ * transient errors before returning a final successful response.
+ * Used to prove withRetry wires through to the read endpoints.
+ */
+async function startFlakyServer({ failuresBeforeSuccess, transientStatus, successBody }) {
+  let hits = 0;
+  const server = createServer((req, res) => {
+    // Drain the request body even though we don't read it — without
+    // this the client can hang waiting for the server to ack the
+    // POST body on validateAccessKey retries.
+    req.on("data", () => {});
+    req.on("end", () => {
+      hits++;
+      if (hits <= failuresBeforeSuccess) {
+        jsonRes(res, transientStatus, { error: `flaky-${hits}` });
+      } else {
+        jsonRes(res, 200, successBody);
+      }
+    });
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const { port } = server.address();
+  return {
+    url: `http://127.0.0.1:${port}`,
+    get hits() { return hits; },
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}
+
+describe("http.mjs — retry wiring", () => {
+  // Note: we can't directly override baseMs/capMs here because the
+  // commands pass `retry: true` with no options, so safeFetch uses
+  // the errors.mjs defaults. The default base is 500ms, so each
+  // retry sleeps up to ~500ms on attempt 2 and ~1000ms on attempt 3.
+  // The total wall-time for a 2-failure test is < 2s, which is
+  // within the node:test default timeout.
+
+  it("getLibrary retries through 503 and eventually succeeds", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 2,
+      transientStatus: 503,
+      successBody: { skills: [], removals: [], syncedAt: "2026-04-15T00:00:00Z" },
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY);
+      assert.deepEqual(result.skills, []);
+      assert.equal(srv.hits, 3, "expected 2 failures + 1 success = 3 total attempts");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("getLibrary retries through 429 rate-limit and eventually succeeds", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 1,
+      transientStatus: 429,
+      successBody: { skills: [], removals: [], syncedAt: "2026-04-15T00:00:00Z" },
+    });
+    try {
+      const result = await getLibrary(srv.url, VALID_KEY);
+      assert.deepEqual(result.skills, []);
+      assert.equal(srv.hits, 2);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("getLibrary does NOT retry a 401 auth error", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 2,
+      transientStatus: 401, // NOT transient — should not retry
+      successBody: { skills: [] },
+    });
+    try {
+      await assert.rejects(
+        () => getLibrary(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+      );
+      assert.equal(srv.hits, 1, "401 must not trigger a retry");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("getLibrary exhausts retries and surfaces the terminal error", async () => {
+    // 5 failures + default 3 attempts = never succeeds. The terminal
+    // response is mapped via mapErrorResponse which returns a
+    // networkError (exit 1) for transient codes.
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 5,
+      transientStatus: 503,
+      successBody: { skills: [] },
+    });
+    try {
+      await assert.rejects(
+        () => getLibrary(srv.url, VALID_KEY),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+      // Attempt count equals DEFAULT_RETRY_ATTEMPTS
+      assert.equal(srv.hits, 3, "expected exactly 3 attempts before giving up");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("searchSkills retries through transient failures", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 1,
+      transientStatus: 502,
+      successBody: { skills: [], pagination: { total: 0, limit: 20, offset: 0 } },
+    });
+    try {
+      const result = await searchSkills(srv.url, VALID_KEY, { q: "test" });
+      assert.deepEqual(result.skills, []);
+      assert.equal(srv.hits, 2);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("getSkill retries and returns null on terminal 404 (not retried)", async () => {
+    // 404 is NOT transient. getSkill should return null without retrying.
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 5,
+      transientStatus: 404,
+      successBody: { skill: null },
+    });
+    try {
+      const result = await getSkill(srv.url, VALID_KEY, "alice", "pdf");
+      assert.equal(result, null);
+      assert.equal(srv.hits, 1, "404 must not trigger retry");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("validateAccessKey retries through transient 504", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 2,
+      transientStatus: 504,
+      successBody: {
+        userId: "u", accountId: "a", accountSlug: "alice",
+        accountName: "Alice", scopes: ["registry:read"],
+        keyId: "k", tier: "free",
+      },
+    });
+    try {
+      const result = await validateAccessKey(srv.url, VALID_KEY);
+      assert.equal(result.accountSlug, "alice");
+      assert.equal(srv.hits, 3);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("addSkillToLibrary does NOT retry (write-path stays single-shot)", async () => {
+    // Write endpoints are deliberately NOT retried in PR4 scope to
+    // minimize behavioral risk around PR3a's idempotent add flow.
+    // This test locks the decision so a future drive-by edit can't
+    // enable retry on writes without updating the comment + tests.
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 5,
+      transientStatus: 503,
+      successBody: { skill: { owner: "alice", name: "pdf" } },
+    });
+    try {
+      await assert.rejects(
+        () => addSkillToLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+      assert.equal(srv.hits, 1, "add must not retry");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("removeSkillFromLibrary does NOT retry (parallel lock to addSkillToLibrary)", async () => {
+    // The round-1 architect review flagged that only addSkillToLibrary
+    // had a single-shot lock test. removeSkillFromLibrary is also a
+    // write endpoint that the PR4 comment rationale covers, but
+    // without a parallel test a drive-by edit adding `retry: true`
+    // to the DELETE call would go undetected. This test is the
+    // second half of the belt-and-suspenders.
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 5,
+      transientStatus: 503,
+      successBody: { ok: true },
+    });
+    try {
+      await assert.rejects(
+        () => removeSkillFromLibrary(srv.url, VALID_KEY, "alice", "pdf"),
+        (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+      );
+      assert.equal(srv.hits, 1, "remove must not retry");
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("SKILLREPO_VERBOSE emits [retry] lines to stderr during retry", async () => {
+    // Cross-review gap: the retry helper has unit tests for the
+    // onRetry callback but nothing verified the end-to-end wiring
+    // from SKILLREPO_VERBOSE env var → safeFetch → withRetry →
+    // process.stderr. This test locks the full path so a regression
+    // in bin/skillrepo.mjs's --verbose → env var handoff or in
+    // http.mjs's resolveRetryOptions default-onRetry installer
+    // fails loudly.
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 2,
+      transientStatus: 503,
+      successBody: { skills: [], removals: [], syncedAt: "2026-04-15T00:00:00Z" },
+    });
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    const captured = [];
+    process.stderr.write = (chunk, ...rest) => {
+      captured.push(String(chunk));
+      return originalWrite(chunk, ...rest);
+    };
+    process.env.SKILLREPO_VERBOSE = "1";
+    try {
+      await getLibrary(srv.url, VALID_KEY);
+      const retryLines = captured.filter((c) => c.includes("[retry]"));
+      // 2 failures + 1 success = 2 retry messages before the successful attempt
+      assert.equal(retryLines.length, 2, "expected 2 [retry] stderr lines");
+      assert.match(retryLines[0], /attempt 1 failed \(HTTP 503\)/);
+      assert.match(retryLines[1], /attempt 2 failed \(HTTP 503\)/);
+    } finally {
+      process.stderr.write = originalWrite;
+      delete process.env.SKILLREPO_VERBOSE;
+      await srv.close();
+    }
+  });
+
+  it("without SKILLREPO_VERBOSE, retries are silent", async () => {
+    const srv = await startFlakyServer({
+      failuresBeforeSuccess: 1,
+      transientStatus: 503,
+      successBody: { skills: [], removals: [], syncedAt: "2026-04-15T00:00:00Z" },
+    });
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    const captured = [];
+    process.stderr.write = (chunk, ...rest) => {
+      captured.push(String(chunk));
+      return originalWrite(chunk, ...rest);
+    };
+    // Ensure SKILLREPO_VERBOSE is NOT set
+    delete process.env.SKILLREPO_VERBOSE;
+    try {
+      await getLibrary(srv.url, VALID_KEY);
+      const retryLines = captured.filter((c) => c.includes("[retry]"));
+      assert.equal(retryLines.length, 0, "retries must be silent without SKILLREPO_VERBOSE");
+    } finally {
+      process.stderr.write = originalWrite;
+      await srv.close();
+    }
+  });
+});