skillrepo 4.1.0 → 4.2.0

package/bin/skillrepo.mjs

@@ -25,6 +25,7 @@ import { runInit } from "../src/commands/init.mjs";
 import { runUpdate } from "../src/commands/update.mjs";
 import { runGet } from "../src/commands/get.mjs";
 import { runAdd } from "../src/commands/add.mjs";
+import { runPush } from "../src/commands/push.mjs";
 import { runRemove } from "../src/commands/remove.mjs";
 import { runList } from "../src/commands/list.mjs";
 import { runSearch } from "../src/commands/search.mjs";
@@ -62,6 +63,13 @@ const COMMANDS = {
     usage: "skillrepo add <@owner/name> [--global] [--agent <list>] [--json]",
     run: async (argv) => runAdd(argv),
   },
+  push: {
+    description: "Push a local skill directory to your library (create or release new version)",
+    usage:
+      "skillrepo push <path> [--version <label>] [--changelog <text>] " +
+      "[--idempotency-key <key>] [--json]",
+    run: async (argv) => runPush(argv),
+  },
   remove: {
     description: "Remove a skill from your library and delete it locally",
     usage: "skillrepo remove <@owner/name> [--global] [--agent <list>] [--json]",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
@@ -13,13 +13,19 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/atxpace/skill-repo.git",
+    "url": "https://github.com/skill-repo/skill-repo.git",
     "directory": "packages/cli"
   },
-  "keywords": ["skillrepo", "cli", "mcp", "ai-skills"],
+  "keywords": [
+    "skillrepo",
+    "cli",
+    "mcp",
+    "ai-skills"
+  ],
   "author": "SkillRepo LLC",
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
-    "cli-table3": "^0.6.5"
+    "cli-table3": "^0.6.5",
+    "gray-matter": "^4.0.3"
   }
 }

package/src/commands/push.mjs

@@ -0,0 +1,187 @@
+/**
+ * `skillrepo push <path>` (#1455).
+ *
+ * Smart upsert: walks a local skill directory and uploads it via
+ * `POST /api/v1/library` (#1452 multipart endpoint). The server detects
+ * existence by SKILL.md frontmatter name and either creates a new
+ * private skill (first push) or releases a new version (subsequent push
+ * with changed content). Identical content is a server-side no-op.
+ *
+ * **No write-back.** The files already live at `<path>` on the user's
+ * disk. The CLI uploads them and prints success — it does not write
+ * anything back. `skillrepo update` remains the canonical command for
+ * disk sync from server → local.
+ *
+ * Flags: --idempotency-key / --json / --key / --url
+ * Positional: <path>
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+
+import { pushSkill } from "../lib/http.mjs";
+import { walkSkillFiles } from "../lib/skill-walk.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `push`. Throws CliError on failure.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runPush(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let skillPath = null;
+
+  // `resolveFlags` only knows the shared flags (`--global`, `--agent`,
+  // `--json`, `--key`, `--url`, `--verbose`). The per-command value flag
+  // (`--idempotency-key <val>`) is consumed in `acceptPositional` by
+  // returning `2` to claim both the flag name and its value.
+  let idempotencyKey = null;
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg, i, allArgv) {
+      // Value flags: claim flag + value (2 args).
+      if (arg === "--idempotency-key") {
+        if (allArgv[i + 1] === undefined) {
+          throw validationError("Missing value for --idempotency-key.", {
+            hint: "Pass a key, e.g., --idempotency-key my-uuid-here.",
+          });
+        }
+        idempotencyKey = allArgv[i + 1];
+        return 2;
+      }
+      // Otherwise it must be the (sole) positional skill-path argument.
+      if (skillPath !== null) {
+        throw validationError(`Unexpected extra argument: ${arg}`, {
+          hint: "Pass exactly one local directory path.",
+        });
+      }
+      skillPath = arg;
+      return 1;
+    },
+  });
+
+  if (!skillPath) {
+    throw validationError("Missing skill directory path.", {
+      hint: "Usage: skillrepo push <path-to-skill>",
+    });
+  }
+
+  // ── Resolve the skill directory ────────────────────────────────────
+  const absDir = path.resolve(process.cwd(), skillPath);
+  let stat;
+  try {
+    stat = await fs.stat(absDir);
+  } catch (err) {
+    throw validationError(
+      `Path not found: ${skillPath}`,
+      { hint: `Resolved to ${absDir}. Pass a directory containing a SKILL.md.`, cause: err },
+    );
+  }
+  if (!stat.isDirectory()) {
+    throw validationError(`Not a directory: ${skillPath}`, {
+      hint: "Pass a directory containing a SKILL.md, not a single file.",
+    });
+  }
+
+  // ── Read + parse SKILL.md (local validation only) ──────────────────
+  // The walker below picks SKILL.md up as a regular file and sends it
+  // through the multipart `files[]` array. We still read it here for an
+  // early failure check: without this the user would upload every
+  // supporting file before the server's frontmatter-parser rejected the
+  // push.
+  const skillMdPath = path.join(absDir, "SKILL.md");
+  let skillMdLocal;
+  try {
+    skillMdLocal = await fs.readFile(skillMdPath, "utf-8");
+  } catch (err) {
+    throw validationError(`No SKILL.md at ${skillPath}/SKILL.md.`, {
+      hint:
+        "Every skill must have a SKILL.md at its root with YAML " +
+        "frontmatter including `name` and `description` fields.",
+      cause: err,
+    });
+  }
+
+  let frontmatter;
+  try {
+    const parsed = matter(skillMdLocal);
+    frontmatter = parsed.data;
+  } catch (err) {
+    throw validationError(
+      `SKILL.md frontmatter could not be parsed.`,
+      {
+        hint:
+          "Ensure the file starts with `---`, contains valid YAML, and " +
+          "ends the frontmatter block with `---` on its own line.",
+        cause: err,
+      },
+    );
+  }
+
+  if (!frontmatter?.name || typeof frontmatter.name !== "string") {
+    throw validationError("SKILL.md is missing the required `name` field.", {
+      hint: "Add `name: my-skill-name` to the YAML frontmatter.",
+    });
+  }
+
+  // ── Walk the skill folder ──────────────────────────────────────────
+  // The walker returns every file (including the root `SKILL.md`) per
+  // the agentskills.io spec. They all go up as `files[]` parts.
+  const walked = await walkSkillFiles(absDir);
+
+  const files = await Promise.all(
+    walked.map(async (f) => ({
+      relativePath: f.relativePath,
+      content: await fs.readFile(f.absolutePath),
+    })),
+  );
+
+  // ── POST to /api/v1/library ────────────────────────────────────────
+  const result = await pushSkill(flags.serverUrl, flags.apiKey, {
+    files,
+    idempotencyKey: idempotencyKey ?? undefined,
+  });
+
+  // ── Report ─────────────────────────────────────────────────────────
+  const totalUploaded = files.length;
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          bump: result.bump,
+          owner: result.skill?.owner ?? null,
+          name: result.skill?.name ?? frontmatter.name,
+          version: result.skill?.version ?? null,
+          filesUploaded: totalUploaded,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  const ident = `@${result.skill?.owner ?? "?"}/${result.skill?.name ?? frontmatter.name}`;
+  const fileCount = `${totalUploaded} file${totalUploaded === 1 ? "" : "s"}`;
+
+  if (result.action === "created") {
+    stdout.write(
+      `\n  ✓ Created ${ident} v${result.skill?.version ?? "1.0"} (${fileCount})\n\n`,
+    );
+  } else if (result.action === "updated") {
+    stdout.write(
+      `\n  ✓ Released ${ident} v${result.skill?.version} (${result.bump} bump, ${fileCount})\n\n`,
+    );
+  } else {
+    // unchanged
+    stdout.write(
+      `\n  ✓ No changes — ${ident} is already at v${result.skill?.version}\n\n`,
+    );
+  }
+}

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) ──────
 
 /**

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,
+    });
+  }
+}