skillrepo 2.0.0 → 3.1.0

package/src/test/e2e/mock-server.mjs

@@ -1,16 +1,36 @@
 /**
- * Minimal mock HTTP server for CLI E2E tests.
+ * Mock HTTP server for CLI E2E + integration tests.
  *
  * Serves:
- *   GET /api/v1/setup          — configurable SetupPayload
- *   GET /api/v1/skill-content  — mock skill content by owner/name
+ *   GET    /api/v1/setup                          — legacy setup payload (init flow)
+ *   GET    /api/v1/skill-content                  — legacy skill content
+ *   POST   /api/v1/auth/validate                  — credential check (PR2)
+ *   GET    /api/v1/library                        — library sync with ETag + since (PR2)
+ *   POST   /api/v1/library                        — add to library (PR3a)
+ *   DELETE /api/v1/library/[owner]/[name]         — remove from library (PR3a)
+ *   GET    /api/v1/skills/[owner]/[name]          — single skill fetch (PR2)
+ *   GET    /api/v1/skills/search                  — keyword search (PR2)
  *
- * Validates Authorization: Bearer sk_live_* header.
+ * Validates Authorization: Bearer sk_live_* header on every endpoint.
  * Listens on port 0 (OS-assigned) for parallel-safe tests.
  *
- * The payload is stored in a mutable variable so callers can call
- * setPayload() after start() to inject the real baseUrl once the
- * OS-assigned port is known.
+ * Mutable slots:
+ *   setPayload(payload)                  — legacy setup payload
+ *   setLibraryResponse(response)         — what GET /api/v1/library returns
+ *   setSkillResponse(owner, name, s)     — per-skill payload for getSkill
+ *   setSearchResponse(response)          — what GET /api/v1/skills/search returns
+ *   setValidateResponse(response)        — what POST /auth/validate returns
+ *   setForcedStatus(status, body)        — force the next request to error
+ *   setEtag(etag)                        — what library responses include
+ *
+ *   (PR3a additions)
+ *   setAddResponse(owner, name, resp)    — per-skill response for POST /library
+ *   setRemoveResponse(owner, name, resp) — per-skill response for DELETE /library/<owner>/<name>
+ *   getLastPostBody()                    — inspect the most recent POST body (JSON-parsed)
+ *
+ * The slot APIs let unit/integration tests configure each scenario
+ * without spinning up multiple servers per test. Default behavior
+ * for an unconfigured slot is a sensible empty payload.
  */
 
 import { createServer } from "node:http";
@@ -20,13 +40,67 @@ import { createServer } from "node:http";
  * @param {object} initialPayload - The SetupPayload to return from /api/v1/setup
  * @param {object} [options]
  * @param {string} [options.validKey] - Exact key to accept (default: any sk_live_* key)
- * @returns {{ start: () => Promise<number>, stop: () => Promise<void>, port: number, setPayload: (p: object) => void }}
+ * @returns {object} server controls — see top-of-file slot list
  */
 export function createMockServer(initialPayload, options = {}) {
   const { validKey } = options;
   let port = 0;
   let payload = initialPayload;
 
+  // PR2 mutable slots
+  let libraryResponse = { skills: [], removals: [], syncedAt: new Date().toISOString() };
+  let libraryEtag = null;
+  // PR3b round-2 slot: persistent override for the library endpoint.
+  // Tests set this to simulate a repeatable failure (e.g. 500) on
+  // just the /api/v1/library route WITHOUT tripping forced-status on
+  // the validate call that runs first. Unlike setForcedStatus() —
+  // which fires once and applies to ANY path — this slot only
+  // affects GET /api/v1/library and stays set until explicitly
+  // cleared. null means "use the normal handler".
+  let libraryStatusOverride = null;
+  let skillResponses = new Map(); // key: "owner/name" → SyncSkill
+  let searchResponse = { skills: [], pagination: { total: 0, limit: 20, offset: 0 } };
+  let validateResponse = {
+    userId: "user-mock",
+    accountId: "acc-mock",
+    accountSlug: "mock",
+    accountName: "Mock Account",
+    scopes: ["registry:read", "registry:write"],
+    keyId: "key-mock",
+    tier: "free",
+  };
+  /** @type {{ status: number, body: any } | null} */
+  let forcedError = null;
+
+  // PR3a mutable slots for POST/DELETE library routes
+  //
+  // Each entry is `{ status: number, body: any }` describing the
+  // per-request response. Defaults:
+  //   POST /api/v1/library   → 201 { added: {...} } (successful add)
+  //   DELETE /api/v1/library/x/y → 200 { removed: {...} } (successful remove)
+  //
+  // Tests call setAddResponse / setRemoveResponse to inject specific
+  // outcomes (404, 409, 403, etc.) by owner/name. A `*` wildcard
+  // matches any owner/name when no exact match is registered.
+  let addResponses = new Map();    // key: "owner/name" or "*" → { status, body }
+  let removeResponses = new Map(); // key: "owner/name" or "*" → { status, body }
+
+  // Most recent POST body (JSON-parsed) for test inspection.
+  //
+  // IMPORTANT:
+  //   - POST ONLY. DELETE/PUT/PATCH bodies are buffered (for streaming
+  //     correctness) but NOT captured here. `getLastPostBody()` always
+  //     returns the most recent POST, or null if no POST has happened.
+  //     Tests that need to inspect a DELETE body should add a dedicated
+  //     `lastDeleteBody` slot.
+  //   - Not concurrent-safe. Multiple parallel POSTs to the same
+  //     server would overwrite each other. The entire test suite is
+  //     sequential (node:test runs describe blocks in order and each
+  //     `it` awaits the full `runCli` / `runCommand` call), so in
+  //     practice this is fine — but a future parallel test runner
+  //     would need per-request capture.
+  let lastPostBody = null;
+
   /**
    * Validate the Authorization header.
    * Returns true if valid, false otherwise (and sends a 401 response).
@@ -50,15 +124,168 @@ export function createMockServer(initialPayload, options = {}) {
   }
 
   const server = createServer((req, res) => {
-    if (req.method !== "GET") {
-      res.writeHead(404, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "Not found" }));
+    // Buffer the request body for POST/DELETE before dispatching.
+    // The old PR2 handler ignored request bodies entirely because no
+    // endpoint actually consumed one (the POST /auth/validate
+    // endpoint takes a bearer header and no body). PR3a's add
+    // command sends a JSON body to POST /api/v1/library, so we
+    // now collect chunks and re-dispatch once the stream ends.
+    if (req.method === "POST" || req.method === "DELETE" || req.method === "PUT" || req.method === "PATCH") {
+      let bodyChunks = "";
+      req.on("data", (chunk) => {
+        bodyChunks += chunk.toString("utf-8");
+      });
+      req.on("end", () => {
+        if (req.method === "POST" && bodyChunks.length > 0) {
+          try {
+            lastPostBody = JSON.parse(bodyChunks);
+          } catch {
+            lastPostBody = bodyChunks; // preserve as string for tests
+          }
+        }
+        handleRequest(req, res, bodyChunks);
+      });
+      req.on("error", () => {
+        // Connection dropped — nothing to do, client is gone
+      });
       return;
     }
+    handleRequest(req, res, "");
+  });
 
+  function handleRequest(req, res, rawBody) {
     const url = new URL(req.url, `http://${req.headers.host}`);
 
-    // GET /api/v1/setup
+    // ── Forced-error short-circuit (PR2 test slot) ──────────────────
+    // Set via setForcedStatus(); fires once and clears itself so the
+    // next request behaves normally. Bypasses auth so tests can
+    // simulate 5xx without setting up a valid key.
+    if (forcedError !== null) {
+      const { status, body } = forcedError;
+      forcedError = null;
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(typeof body === "string" ? body : JSON.stringify(body));
+      return;
+    }
+
+    // ── PR2: POST /api/v1/auth/validate ─────────────────────────────
+    if (url.pathname === "/api/v1/auth/validate" && req.method === "POST") {
+      if (!checkAuth(req, res)) return;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(validateResponse));
+      return;
+    }
+
+    // ── PR3a: POST /api/v1/library (add to library) ─────────────────
+    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+      if (!checkAuth(req, res)) return;
+      let body;
+      try {
+        body = rawBody.length > 0 ? JSON.parse(rawBody) : {};
+      } catch {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON", code: "invalid_json" }));
+        return;
+      }
+      const { owner, name } = body ?? {};
+      if (!owner || !name) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error: "Missing owner or name",
+            code: "validation_error",
+          }),
+        );
+        return;
+      }
+      const configured =
+        addResponses.get(`${owner}/${name}`) ?? addResponses.get("*");
+      if (configured) {
+        res.writeHead(configured.status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(configured.body));
+        return;
+      }
+      // Default: 201 added
+      res.writeHead(201, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          added: {
+            owner,
+            name,
+            version: "1.0.0",
+            addedAt: new Date().toISOString(),
+          },
+        }),
+      );
+      return;
+    }
+
+    // ── PR3a: DELETE /api/v1/library/[owner]/[name] (remove) ────────
+    {
+      const m = url.pathname.match(/^\/api\/v1\/library\/([^\/]+)\/([^\/]+)$/);
+      if (m && req.method === "DELETE") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const configured =
+          removeResponses.get(`${owner}/${name}`) ?? removeResponses.get("*");
+        if (configured) {
+          res.writeHead(configured.status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(configured.body));
+          return;
+        }
+        // Default: 200 removed
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            removed: {
+              owner,
+              name,
+              removedAt: new Date().toISOString(),
+            },
+          }),
+        );
+        return;
+      }
+    }
+
+    // ── PR2: GET /api/v1/skills/[owner]/[name] ──────────────────────
+    // Match before the legacy /skill-content path. Uses the canonical
+    // route shape — encoded path params decoded via URL.
+    {
+      const m = url.pathname.match(/^\/api\/v1\/skills\/([^\/]+)\/([^\/]+)$/);
+      if (m && req.method === "GET") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const skill = skillResponses.get(`${owner}/${name}`);
+        if (!skill) {
+          res.writeHead(404, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Skill not found" }));
+          return;
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ skill }));
+        return;
+      }
+    }
+
+    // ── PR2: GET /api/v1/skills/search ──────────────────────────────
+    if (url.pathname === "/api/v1/skills/search" && req.method === "GET") {
+      if (!checkAuth(req, res)) return;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(searchResponse));
+      return;
+    }
+
+    // Reject unsupported methods on unknown paths
+    if (req.method !== "GET" && req.method !== "POST" && req.method !== "DELETE") {
+      res.writeHead(405, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Method not allowed" }));
+      return;
+    }
+
+    // GET /api/v1/setup (legacy)
     if (url.pathname === "/api/v1/setup") {
       if (!checkAuth(req, res)) return;
 
@@ -67,20 +294,37 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
-    // GET /api/v1/sync/library — used by the first sync during init
-    if (url.pathname === "/api/v1/sync/library") {
+    // GET /api/v1/library — canonical library sync endpoint
+    if (url.pathname === "/api/v1/library" && req.method === "GET") {
       if (!checkAuth(req, res)) return;
 
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({
-        skills: [],
-        removals: [],
-        syncedAt: new Date().toISOString(),
-      }));
+      // Persistent status override (PR3b round-2 slot). When set,
+      // every library request returns the configured status +
+      // body until the test clears it. Used to simulate a broken
+      // sync without tripping the one-shot forced-status slot on
+      // the validate call that runs earlier in init's flow.
+      if (libraryStatusOverride) {
+        res.writeHead(libraryStatusOverride.status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(libraryStatusOverride.body ?? { error: "Library override" }));
+        return;
+      }
+
+      // ETag short-circuit
+      const ifNoneMatch = req.headers["if-none-match"];
+      if (libraryEtag && ifNoneMatch === libraryEtag) {
+        res.writeHead(304, { ETag: libraryEtag });
+        res.end();
+        return;
+      }
+
+      const headers = { "Content-Type": "application/json" };
+      if (libraryEtag) headers.ETag = libraryEtag;
+      res.writeHead(200, headers);
+      res.end(JSON.stringify(libraryResponse));
       return;
     }
 
-    // GET /api/v1/skill-content?owner=X&name=Y
+    // GET /api/v1/skill-content?owner=X&name=Y (legacy)
     if (url.pathname === "/api/v1/skill-content") {
       if (!checkAuth(req, res)) return;
 
@@ -107,7 +351,7 @@ export function createMockServer(initialPayload, options = {}) {
     // Fallback 404
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Not found" }));
-  });
+  }
 
   return {
     /** Start the server and return the assigned port. */
@@ -142,5 +386,103 @@ export function createMockServer(initialPayload, options = {}) {
     setPayload(newPayload) {
       payload = newPayload;
     },
+
+    // ── PR2 mutable slots ─────────────────────────────────────────
+
+    /** Replace the GET /api/v1/library response. */
+    setLibraryResponse(response) {
+      libraryResponse = response;
+    },
+
+    /**
+     * Persistently override the HTTP status/body returned by
+     * GET /api/v1/library. Pass null to clear. Unlike setForcedStatus
+     * which is one-shot and global, this stays in effect and only
+     * affects the library endpoint.
+     */
+    setLibraryStatus(override) {
+      libraryStatusOverride = override;
+    },
+
+    /** Set the ETag served by /api/v1/library and used for 304 short-circuit. */
+    setEtag(etag) {
+      libraryEtag = etag;
+    },
+
+    /** Register a single-skill response keyed by `owner/name`. */
+    setSkillResponse(owner, name, skill) {
+      skillResponses.set(`${owner}/${name}`, skill);
+    },
+
+    /** Clear all registered single-skill responses. */
+    clearSkillResponses() {
+      skillResponses = new Map();
+    },
+
+    /** Replace the GET /api/v1/skills/search response. */
+    setSearchResponse(response) {
+      searchResponse = response;
+    },
+
+    /** Replace the POST /api/v1/auth/validate response. */
+    setValidateResponse(response) {
+      validateResponse = response;
+    },
+
+    /**
+     * Force the next request (any path, any method) to return a
+     * specific status + body. Fires once and clears itself, so a
+     * test can simulate a single 5xx without affecting subsequent
+     * requests. Bypasses auth so callers can simulate unauth errors.
+     */
+    setForcedStatus(status, body) {
+      forcedError = { status, body };
+    },
+
+    // ── PR3a slots ────────────────────────────────────────────────
+
+    /**
+     * Register a per-skill POST /api/v1/library response. Key by
+     * `owner/name` or use `"*"` as a wildcard for any skill.
+     * Example: setAddResponse("alice", "pdf", { status: 404, body: { error: "Skill not found", code: "not_found" } })
+     */
+    setAddResponse(owner, name, response) {
+      addResponses.set(`${owner}/${name}`, response);
+    },
+
+    /** Shortcut for a wildcard add response (applies to any owner/name). */
+    setAddResponseForAny(response) {
+      addResponses.set("*", response);
+    },
+
+    clearAddResponses() {
+      addResponses = new Map();
+    },
+
+    /**
+     * Register a per-skill DELETE /api/v1/library/<owner>/<name>
+     * response. Key by `owner/name` or `"*"` for a wildcard.
+     */
+    setRemoveResponse(owner, name, response) {
+      removeResponses.set(`${owner}/${name}`, response);
+    },
+
+    /** Shortcut for a wildcard remove response. */
+    setRemoveResponseForAny(response) {
+      removeResponses.set("*", response);
+    },
+
+    clearRemoveResponses() {
+      removeResponses = new Map();
+    },
+
+    /**
+     * Return the most recent POST body the server received, or null
+     * if no POST has been made yet. Body is JSON-parsed when
+     * possible, otherwise returned as a string.
+     */
+    getLastPostBody() {
+      return lastPostBody;
+    },
   };
 }

package/src/test/helpers/capture-stream.mjs

@@ -0,0 +1,48 @@
+/**
+ * Small Writable-stream helper for capturing command output in unit
+ * tests. Replaces the previous `process.stdout.write` monkey-patch
+ * pattern, which collided with node:test's TAP IPC protocol when
+ * running with subtests (see commit history for the ugly debug
+ * session that uncovered this).
+ *
+ * Usage:
+ *
+ *   import { createCaptureStream } from "../helpers/capture-stream.mjs";
+ *
+ *   const out = createCaptureStream();
+ *   await runCommand(argv, { stdout: out });
+ *   assert.match(out.text(), /expected text/);
+ */
+
+import { Writable } from "node:stream";
+
+/**
+ * Create a Writable stream that buffers everything written to it
+ * into an in-memory string. Returns the stream itself with two
+ * extra helpers attached: `text()` returns the captured content,
+ * and `clear()` resets the buffer.
+ *
+ * The stream accepts both string and Buffer chunks. Strings are
+ * appended directly; Buffers are decoded as UTF-8.
+ */
+export function createCaptureStream() {
+  const chunks = [];
+  const stream = new Writable({
+    write(chunk, encoding, callback) {
+      if (typeof chunk === "string") {
+        chunks.push(chunk);
+      } else if (Buffer.isBuffer(chunk)) {
+        chunks.push(chunk.toString("utf-8"));
+      } else {
+        // Unknown type — fall back to String() so we never lose data
+        chunks.push(String(chunk));
+      }
+      callback();
+    },
+  });
+  stream.text = () => chunks.join("");
+  stream.clear = () => {
+    chunks.length = 0;
+  };
+  return stream;
+}