skillrepo 4.1.0 → 4.3.0

package/src/lib/http.mjs

@@ -368,9 +368,9 @@ async function mapErrorResponse(res, url) {
     return networkError("Rate limit exceeded — server returned 429.", {
       hint:
         "Wait a minute and retry. Read-only commands (update, get, " +
-        "list, search) retry automatically; write commands (add, " +
-        "remove) are single-shot. Pass --verbose to see retry " +
-        "attempts when they happen.",
+        "list, search) and idempotent writes (push) retry " +
+        "automatically; non-idempotent writes (add, remove) are " +
+        "single-shot. Pass --verbose to see retry attempts.",
     });
   }
   if (res.status >= 500) {
@@ -621,7 +621,13 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
   return body.skill ?? null;
 }
 
-// ── /api/v1/library (POST — add to library) ────────────────────────────
+// ── /api/v1/library/refs (POST — add catalog skill to library) ─────────
+//
+// Previously POSTed to `/api/v1/library` directly. After epic #1444
+// Release 1 (#1452), `POST /api/v1/library` is the multipart file-push
+// endpoint and the JSON `{owner, name}` catalog-add operation lives at
+// `POST /api/v1/library/refs` (#1451). The handler logic and response
+// shape are unchanged — only the URL moved.
 
 /**
  * @typedef {Object} LibraryAddSuccess
@@ -650,19 +656,21 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
  */
 
 /**
- * POST /api/v1/library — add a skill to the authenticated account's
- * library.
+ * POST /api/v1/library/refs — add an existing catalog skill to the
+ * authenticated account's library by `{owner, name}` reference.
  *
- * The server's POST handler distinguishes several outcomes via both
- * HTTP status and a `code` field in the response body (see
- * src/app/api/v1/library/route.ts:190-237):
+ * Distinct from `pushSkill` above, which uploads a SKILL.md + files
+ * folder via multipart on `POST /api/v1/library`.
+ *
+ * The server distinguishes several outcomes via HTTP status + `code`
+ * field (see `src/app/api/v1/library/refs/route.ts`):
  *
  *   201 → { added: {...} }                         → "added"
  *   404 { code: "not_found" }                      → "not-found"
  *   409 { code: "already_in_library" }             → "already-in-library"
  *   409 { code: "self_ownership" }                 → "self-ownership"
  *   403 { code: "plan_limit" }                     → mapErrorResponse → validationError
- *   403 { code: "scope_required" } (or similar)    → mapErrorResponse → scopeError
+ *   403 { code: "insufficient_scope" }             → mapErrorResponse → scopeError
  *   401                                             → mapErrorResponse → authError
  *
  * The 404 / 409 cases are documented idempotent-friendly outcomes that
@@ -682,7 +690,7 @@ export async function getSkill(serverUrl, apiKey, owner, name) {
  * @returns {Promise<LibraryAddResult>}
  */
 export async function addSkillToLibrary(serverUrl, apiKey, owner, name) {
-  const url = `${normalizeUrl(serverUrl)}/api/v1/library`;
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/refs`;
   const res = await safeFetch(url, {
     method: "POST",
     headers: {
@@ -756,6 +764,156 @@ export async function addSkillToLibrary(serverUrl, apiKey, owner, name) {
   throw err;
 }
 
+// ── /api/v1/library (POST — multipart file-push, #1452) ─────────────────
+
+/**
+ * @typedef {Object} PushSkillFile
+ * @property {string} relativePath - POSIX-style skill-relative path (e.g. "references/intro.md").
+ * @property {Uint8Array | Buffer} content - Raw file bytes.
+ */
+
+/**
+ * @typedef {Object} PushSkillResultCreated
+ * @property {"created"} action
+ * @property {null} bump
+ * @property {any} skill
+ *
+ * @typedef {Object} PushSkillResultUpdated
+ * @property {"updated"} action
+ * @property {"major" | "minor"} bump
+ * @property {any} skill
+ *
+ * @typedef {Object} PushSkillResultUnchanged
+ * @property {"unchanged"} action
+ * @property {null} bump
+ * @property {any} skill
+ *
+ * @typedef {PushSkillResultCreated | PushSkillResultUpdated | PushSkillResultUnchanged} PushSkillResult
+ */
+
+/**
+ * POST /api/v1/library — multipart file-push / upsert (#1452).
+ *
+ * Uploads the whole skill folder per the agentskills.io spec. Every file
+ * (including the root `SKILL.md`) goes up as a `files[]` part with its
+ * in-skill relative path carried via the `Content-Disposition: filename`
+ * parameter (RFC 7578). The server identifies SKILL.md by exact-match
+ * `filename === "SKILL.md"` (case-sensitive, no path prefix).
+ *
+ * The `Idempotency-Key` header is set on every call (auto-generated if
+ * not supplied) so transient network failures can be retried safely. The
+ * server replays the cached response on a same-key + same-body retry
+ * within 24h.
+ *
+ * Server outcomes (see `src/app/api/v1/library/route.ts`):
+ *   201 { action: "created", bump: null, skill: SyncSkill }
+ *   200 { action: "updated", bump: "major"|"minor", skill: SyncSkill }
+ *   200 { action: "unchanged", bump: null, skill: SyncSkill }
+ *   400 { code: "missing_skill_md" | "invalid_skill_md" | "invalid_path" | "invalid_multipart" }
+ *   403 { code: "plan_limit" | "scope_required" }
+ *   409 { code: "source_conflict" | "idempotency_key_in_progress" }
+ *   413 { code: "payload_too_large" }
+ *   422 { code: "idempotency_key_reused" }
+ *   429 — rate-limited
+ *
+ * Documented 4xx/2xx outcomes return a discriminated union. Anything
+ * else is routed through mapErrorResponse for typed-error throwing.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {Object} input
+ * @param {PushSkillFile[]} input.files - The skill folder (SKILL.md plus supporting files).
+ * @param {string} [input.idempotencyKey] - Override the auto-generated key. Pass to retry idempotently.
+ * @returns {Promise<PushSkillResult>}
+ */
+export async function pushSkill(serverUrl, apiKey, input) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library`;
+  const idempotencyKey = input.idempotencyKey ?? generateIdempotencyKey();
+
+  const fd = new FormData();
+  for (const file of input.files) {
+    // Per RFC 7578 §4.2, `filename` carries the per-part relative path.
+    // The `File` constructor's second arg sets the `Content-Disposition:
+    // filename` parameter via undici's native FormData encoding. `File`
+    // accepts a `BlobPart[]` directly (Uint8Array / Buffer / Blob /
+    // string), so the previous `new Blob([content])` round-trip was
+    // unnecessary allocation.
+    fd.append("files", new File([file.content], file.relativePath));
+  }
+
+  // `retry: true` is safe here despite this being a write endpoint —
+  // every request carries an `Idempotency-Key` header (auto-generated
+  // above if not provided), and the server (#1465 middleware) replays
+  // the cached response on same-key + same-body retries within 24h.
+  // Without retry, a transient 503 from a cold-start Vercel function
+  // surfaces as an immediate `networkError` to the user even though
+  // the operation could safely re-attempt.
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: {
+      ...(await authHeaders(apiKey)),
+      "Idempotency-Key": idempotencyKey,
+      // Note: do NOT set Content-Type for FormData — undici will set
+      // `multipart/form-data; boundary=...` automatically. Setting it
+      // here would omit the boundary parameter and the server's parse
+      // would fail.
+    },
+    body: fd,
+    retry: true,
+  });
+
+  if (res.status === 200 || res.status === 201) {
+    const body = await parseJsonOrThrow(res, url);
+    if (
+      body?.action === "created" ||
+      body?.action === "updated" ||
+      body?.action === "unchanged"
+    ) {
+      return {
+        action: body.action,
+        bump: body.bump ?? null,
+        skill: body.skill,
+      };
+    }
+    throw networkError(
+      `Library push returned ${res.status} with unexpected action "${body?.action}" from ${url}`,
+    );
+  }
+
+  // Documented 4xx outcomes flow through mapErrorResponse so the CLI
+  // surfaces them with the same `code`-discriminated handling pattern
+  // used for catalog-add. The `*_too_large`, `*_in_progress`, and
+  // `*_reused` codes share a 4xx envelope; mapErrorResponse maps them
+  // to validationError/scopeError/authError consistently.
+  const err = await mapErrorResponse(res, url);
+  if (err === null) {
+    throw validationError(
+      `Library push returned ${res.status} with no documented meaning.`,
+    );
+  }
+  throw err;
+}
+
+/**
+ * Generate a random Idempotency-Key. UUID v4 if `crypto.randomUUID` is
+ * available; falls back to a hex random for older Node runtimes (Node
+ * 19+ ships randomUUID at the top level, so this is defensive).
+ */
+function generateIdempotencyKey() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
 // ── /api/v1/library/[owner]/[name] (DELETE — remove from library) ──────
 
 /**
@@ -897,3 +1055,192 @@ export async function searchSkills(serverUrl, apiKey, opts = {}) {
     pagination: body.pagination ?? { total: 0, limit: opts.limit ?? 20, offset: opts.offset ?? 0 },
   };
 }
+
+// ── /api/v1/library/[owner]/[name]/publish + /unpublish (#1444 R3 #1449) ──
+
+/**
+ * @typedef {Object} VisibilityResultPublished
+ * @property {"published"} action
+ * @property {any} skill
+ *
+ * @typedef {Object} VisibilityResultUnpublished
+ * @property {"unpublished"} action
+ * @property {number} notifiedSubscriberCount
+ * @property {any} skill
+ *
+ * @typedef {Object} VisibilityResultUnchanged
+ * @property {"unchanged"} action
+ * @property {any} skill
+ *
+ * @typedef {Object} VisibilityResultForbidden
+ * @property {"forbidden"} action
+ * @property {"publish_not_permitted" | "unpublish_not_permitted"} code
+ * @property {string} reason
+ *
+ * @typedef {Object} VisibilityResultBlocked
+ * @property {"publish-blocked"} action
+ * @property {"namespace_unset" | "analysis_pending" | "safety_grade_too_low"} code
+ * @property {string} reason
+ *
+ * @typedef {Object} VisibilityResultNotFound
+ * @property {"not-found"} action
+ * @property {string} owner
+ * @property {string} name
+ *
+ * @typedef {VisibilityResultPublished | VisibilityResultUnpublished | VisibilityResultUnchanged
+ *          | VisibilityResultForbidden | VisibilityResultBlocked | VisibilityResultNotFound} VisibilityResult
+ */
+
+/**
+ * Shared helper used by `publishLibrarySkill` and `unpublishLibrarySkill`.
+ * The two endpoints differ only in:
+ *   - URL suffix (/publish vs /unpublish)
+ *   - 200 `action` value (published vs unpublished)
+ *   - 200 response includes `notifiedSubscriberCount` only on unpublish
+ *   - 403 `code` (publish_not_permitted vs unpublish_not_permitted)
+ *   - 422 `code` set differs (publish has product-rule blocked codes;
+ *     unpublish has only `idempotency_key_reused` which routes
+ *     through `mapErrorResponse`)
+ *
+ * Both return a discriminated `VisibilityResult` so the command layer
+ * can map outcomes to user-facing exit codes without duplicating the
+ * status-code dispatch.
+ *
+ * Idempotency-Key: auto-generated unless supplied via `options.idempotencyKey`.
+ * `retry: true` is safe because the server caches responses for 24h
+ * keyed by `(accountId, key, route)`.
+ */
+async function setSkillVisibility(serverUrl, apiKey, owner, name, target, options = {}) {
+  const action = target === "global" ? "publish" : "unpublish";
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/${encodeURIComponent(
+    owner,
+  )}/${encodeURIComponent(name)}/${action}`;
+  const idempotencyKey = options.idempotencyKey ?? generateIdempotencyKey();
+
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: {
+      ...(await authHeaders(apiKey)),
+      "Idempotency-Key": idempotencyKey,
+    },
+    retry: true,
+  });
+
+  if (res.status === 200) {
+    const body = await parseJsonOrThrow(res, url);
+    if (body?.action === "published") {
+      return { action: "published", skill: body.skill };
+    }
+    if (body?.action === "unpublished") {
+      return {
+        action: "unpublished",
+        notifiedSubscriberCount: body.notifiedSubscriberCount ?? 0,
+        skill: body.skill,
+      };
+    }
+    if (body?.action === "unchanged") {
+      return { action: "unchanged", skill: body.skill };
+    }
+    throw networkError(
+      `Library ${action} returned 200 with unexpected action "${body?.action}" from ${url}`,
+    );
+  }
+
+  if (res.status === 404) {
+    await res.json().catch(() => undefined);
+    return { action: "not-found", owner, name };
+  }
+
+  // 403 / 422 require body inspection. Once we read the stream we
+  // CANNOT fall through to `mapErrorResponse` (which re-reads the
+  // body and would get an empty object — a `plan_limit` 403 would
+  // mis-classify as authError exit 2 instead of validationError
+  // exit 5 with billing hint). Pre-parse once, then dispatch every
+  // code path inline mirroring `mapErrorResponse`'s shape so the
+  // CliError types stay consistent across endpoints.
+  if (res.status === 403 || res.status === 422) {
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      // body stays null — fall through to the no-code branches below
+    }
+    const code = typeof body?.code === "string" ? body.code : null;
+    const message = body?.error || `${res.status} ${res.statusText}`;
+
+    if (res.status === 403) {
+      // Our endpoint-specific permission failure.
+      if (code === "publish_not_permitted" || code === "unpublish_not_permitted") {
+        return { action: "forbidden", code, reason: message };
+      }
+      // Mirror `mapErrorResponse`'s 403 taxonomy so a 403 here behaves
+      // identically to a 403 on any other endpoint:
+      //   - `plan_limit` → validationError (exit 5) with billing hint
+      //   - any `*scope*` code → scopeError (exit 4)
+      //   - everything else → authError (exit 2, "suspended" hint)
+      if (code === "plan_limit") {
+        throw validationError(message, {
+          hint: "Upgrade your plan at /app/settings/billing or remove an existing skill from your library.",
+        });
+      }
+      if (code && code.toLowerCase().includes("scope")) {
+        throw scopeError(message, {
+          hint: "Create a write-scoped key at /app/settings/access-keys.",
+        });
+      }
+      throw authError(message, {
+        hint: "If your account is suspended, contact support.",
+      });
+    }
+
+    // res.status === 422
+    if (target === "global") {
+      if (
+        code === "namespace_unset" ||
+        code === "analysis_pending" ||
+        code === "safety_grade_too_low"
+      ) {
+        return { action: "publish-blocked", code, reason: message };
+      }
+    }
+    // `idempotency_key_reused` and any other 422 code surface as
+    // validationError so the exit code matches the rest of v1.
+    throw validationError(message);
+  }
+
+  const err = await mapErrorResponse(res, url);
+  if (err === null) {
+    throw validationError(
+      `Library ${action} returned ${res.status} with no documented meaning.`,
+    );
+  }
+  throw err;
+}
+
+/**
+ * POST /api/v1/library/{owner}/{name}/publish (#1449).
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {string} owner
+ * @param {string} name
+ * @param {{ idempotencyKey?: string }} [options]
+ * @returns {Promise<VisibilityResult>}
+ */
+export async function publishLibrarySkill(serverUrl, apiKey, owner, name, options = {}) {
+  return setSkillVisibility(serverUrl, apiKey, owner, name, "global", options);
+}
+
+/**
+ * POST /api/v1/library/{owner}/{name}/unpublish (#1449).
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {string} owner
+ * @param {string} name
+ * @param {{ idempotencyKey?: string }} [options]
+ * @returns {Promise<VisibilityResult>}
+ */
+export async function unpublishLibrarySkill(serverUrl, apiKey, owner, name, options = {}) {
+  return setSkillVisibility(serverUrl, apiKey, owner, name, "private", options);
+}

package/src/lib/skill-walk.mjs

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