skillrepo 4.1.0 → 4.2.0

package/src/test/commands/push.test.mjs

@@ -0,0 +1,289 @@
+/**
+ * Unit / integration tests for `src/commands/push.mjs` (#1455).
+ *
+ * Runs against the mock server which exposes `POST /api/v1/library`
+ * (multipart upsert). The mock doesn't actually parse multipart — it
+ * just checks the Content-Type and serves either a configured response
+ * (via `setPushResponse`) or a default 201 LibraryPushResponse.
+ *
+ * Coverage: happy paths (created / updated / unchanged), JSON output,
+ * missing-path / missing-SKILL.md errors, invalid frontmatter,
+ * idempotency-key flag.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runPush } from "../../commands/push.mjs";
+import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import { createMockServer } from "../e2e/mock-server.mjs";
+import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let server;
+let serverUrl;
+let originalCwd;
+let originalHomeEnv;
+let stdout;
+const VALID_KEY = "sk_live_test";
+
+const VALID_SKILL_MD = `---
+name: my-skill
+description: A skill exercising the push command
+---
+
+# my-skill
+
+body
+`;
+
+function file(rel, content = "x") {
+  const abs = join(sandbox, "skill", rel);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+async function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-cmd-push-"));
+  mkdirSync(join(sandbox, "skill"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  process.chdir(sandbox);
+  setSandboxHome(join(sandbox, "home"));
+  delete process.env.SKILLREPO_ACCESS_KEY;
+
+  server = createMockServer({});
+  const port = await server.start();
+  serverUrl = `http://127.0.0.1:${port}`;
+
+  stdout = createCaptureStream();
+}
+
+async function teardown() {
+  if (server) await server.stop();
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  server = null;
+}
+
+describe("runPush — happy paths", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("pushes a fresh skill (default response: 201 created)", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    file("references/intro.md", "intro");
+
+    await runPush(
+      ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+      { stdout },
+    );
+
+    assert.match(stdout.text(), /Created @mock\/test-skill/);
+  });
+
+  it("--json prints action / bump / owner / name / version / filesUploaded", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    file("references/intro.md", "intro");
+
+    await runPush(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json", "skill"],
+      { stdout },
+    );
+
+    const json = JSON.parse(stdout.text());
+    assert.equal(json.action, "created");
+    assert.equal(json.owner, "mock");
+    assert.equal(json.name, "test-skill");
+    assert.equal(json.version, "1.0");
+    // SKILL.md + 1 supporting file = 2 (the walker includes SKILL.md as
+    // a regular file per the agentskills.io spec).
+    assert.equal(json.filesUploaded, 2);
+    assert.equal(json.bump, null);
+  });
+
+  it("reports 'updated' with bump when server returns action=updated", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    server.setPushResponse({
+      status: 200,
+      body: {
+        action: "updated",
+        bump: "minor",
+        skill: {
+          owner: "alice",
+          name: "my-skill",
+          version: "1.1",
+          description: "A skill exercising the push command",
+          keywords: [],
+          updatedAt: new Date().toISOString(),
+          etag: '"alice/my-skill@0"',
+          contextSignals: null,
+          files: [],
+          filesIncomplete: false,
+        },
+      },
+    });
+
+    await runPush(
+      ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+      { stdout },
+    );
+
+    assert.match(stdout.text(), /Released @alice\/my-skill v1\.1.*minor bump/);
+  });
+
+  it("reports 'no changes' when server returns action=unchanged", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    server.setPushResponse({
+      status: 200,
+      body: {
+        action: "unchanged",
+        bump: null,
+        skill: {
+          owner: "alice",
+          name: "my-skill",
+          version: "1.0",
+          description: "A skill exercising the push command",
+          keywords: [],
+          updatedAt: new Date().toISOString(),
+          etag: '"alice/my-skill@0"',
+          contextSignals: null,
+          files: [],
+          filesIncomplete: false,
+        },
+      },
+    });
+
+    await runPush(
+      ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+      { stdout },
+    );
+
+    assert.match(stdout.text(), /No changes — @alice\/my-skill is already at v1\.0/);
+  });
+});
+
+describe("runPush — input validation", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("errors when no path is provided", async () => {
+    await assert.rejects(
+      runPush(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Missing skill directory path/.test(err.message),
+    );
+  });
+
+  it("errors when the path doesn't exist", async () => {
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "./does-not-exist"],
+        { stdout },
+      ),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Path not found/.test(err.message),
+    );
+  });
+
+  it("errors when the path is a file, not a directory", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "skill/SKILL.md"],
+        { stdout },
+      ),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Not a directory/.test(err.message),
+    );
+  });
+
+  it("errors when SKILL.md is missing", async () => {
+    // Empty `skill/` directory — no SKILL.md.
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+        { stdout },
+      ),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /No SKILL\.md at skill\/SKILL\.md/.test(err.message),
+    );
+  });
+
+  it("errors when SKILL.md frontmatter is missing the `name` field", async () => {
+    file("SKILL.md", "---\ndescription: only description\n---\n\nbody\n");
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+        { stdout },
+      ),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /SKILL\.md is missing the required `name` field/.test(err.message),
+    );
+  });
+
+  it("errors when SKILL.md frontmatter is malformed YAML", async () => {
+    file("SKILL.md", "---\nname: [unclosed\n---\n");
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "skill"],
+        { stdout },
+      ),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+});
+
+describe("runPush — flags", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("--idempotency-key requires a value", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    await assert.rejects(
+      runPush(
+        ["--key", VALID_KEY, "--url", serverUrl, "--idempotency-key"],
+        { stdout },
+      ),
+      (err) => /Missing value for --idempotency-key/.test(err.message),
+    );
+  });
+
+  it("accepts --idempotency-key + path together", async () => {
+    file("SKILL.md", VALID_SKILL_MD);
+    await runPush(
+      [
+        "--key",
+        VALID_KEY,
+        "--url",
+        serverUrl,
+        "--idempotency-key",
+        "test-key-123",
+        "skill",
+      ],
+      { stdout },
+    );
+    // Default server response is 201 created.
+    assert.match(stdout.text(), /Created @mock\/test-skill/);
+  });
+});

package/src/test/dispatcher.test.mjs

@@ -71,7 +71,7 @@ describe("dispatcher — top-level help", () => {
     assert.equal(r.status, 0);
     assert.match(r.stdout, /SkillRepo CLI/);
     // All 7 commands listed
-    for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+    for (const cmd of ["init", "update", "get", "add", "push", "remove", "list", "search"]) {
       assert.match(r.stdout, new RegExp(`\\b${cmd}\\b`), `expected to see "${cmd}" in help`);
     }
   });
@@ -123,7 +123,7 @@ describe("dispatcher — unknown command", () => {
 describe("dispatcher — per-command help", () => {
   // PR1 only ships init for real; the other 6 are stubs but still
   // route --help correctly.
-  for (const cmd of ["init", "update", "get", "add", "remove", "list", "search"]) {
+  for (const cmd of ["init", "update", "get", "add", "push", "remove", "list", "search"]) {
     it(`\`skillrepo ${cmd} --help\` prints command-specific help`, async () => {
       const r = await runCli([cmd, "--help"]);
       assert.equal(r.status, 0);
@@ -194,6 +194,14 @@ describe("dispatcher — implemented commands route to their modules", () => {
     assert.ok([1, 2, 5].includes(r.status));
   });
 
+  it("`skillrepo push` is wired to the real module (not a stub)", async () => {
+    // Missing path exits validation (5); missing credentials would
+    // exit auth (2). Either proves the stub is gone.
+    const r = await runCli(["push"], { env: { HOME: "/tmp/no-skillrepo-config" } });
+    assert.doesNotMatch(r.stderr, /Not yet implemented/);
+    assert.ok([2, 5].includes(r.status));
+  });
+
   it("`skillrepo remove` is wired to the real module (not a stub)", async () => {
     const r = await runCli(["remove", "@alice/pdf-helper"], { env: { HOME: "/tmp/no-skillrepo-config" } });
     assert.doesNotMatch(r.stderr, /Not yet implemented/);

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

@@ -6,7 +6,8 @@
  *   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)
+ *   POST   /api/v1/library                        — multipart file-push (#1452)
+ *   POST   /api/v1/library/refs                   — add catalog skill to library (#1451)
  *   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)
@@ -24,8 +25,9 @@
  *   setEtag(etag)                        — what library responses include
  *
  *   (PR3a additions)
- *   setAddResponse(owner, name, resp)    — per-skill response for POST /library
+ *   setAddResponse(owner, name, resp)    — per-skill response for POST /library/refs (#1451)
  *   setRemoveResponse(owner, name, resp) — per-skill response for DELETE /library/<owner>/<name>
+ *   setPushResponse(resp)                — response for POST /library multipart push (#1452)
  *   getLastPostBody()                    — inspect the most recent POST body (JSON-parsed)
  *
  * The slot APIs let unit/integration tests configure each scenario
@@ -85,6 +87,14 @@ export function createMockServer(initialPayload, options = {}) {
   let addResponses = new Map();    // key: "owner/name" or "*" → { status, body }
   let removeResponses = new Map(); // key: "owner/name" or "*" → { status, body }
 
+  // #1452 — POST /api/v1/library (multipart file-push) response slot.
+  // Tests set this with `setPushResponse({ status, body })`; when null,
+  // a default 201 LibraryPushResponse is served. The test server does
+  // not parse multipart bodies — verifying the wire format is the
+  // client's responsibility.
+  /** @type {{ status: number, body: any } | null} */
+  let pushResponse = null;
+
   // Most recent POST body (JSON-parsed) for test inspection.
   //
   // IMPORTANT:
@@ -138,19 +148,25 @@ export function createMockServer(initialPayload, options = {}) {
     // 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 = "";
+      // Buffer as Buffer chunks, not string concatenation. JSON routes
+      // re-interpret as UTF-8; binary multipart bodies (#1452 push) keep
+      // their bytes intact. Concatenating `chunk.toString("utf-8")`
+      // would silently corrupt non-UTF-8 file content.
+      const chunks = [];
       req.on("data", (chunk) => {
-        bodyChunks += chunk.toString("utf-8");
+        chunks.push(chunk);
       });
       req.on("end", () => {
-        if (req.method === "POST" && bodyChunks.length > 0) {
+        const rawBody = Buffer.concat(chunks);
+        const rawBodyText = rawBody.toString("utf-8");
+        if (req.method === "POST" && rawBodyText.length > 0) {
           try {
-            lastPostBody = JSON.parse(bodyChunks);
+            lastPostBody = JSON.parse(rawBodyText);
           } catch {
-            lastPostBody = bodyChunks; // preserve as string for tests
+            lastPostBody = rawBodyText; // preserve as string for tests
           }
         }
-        handleRequest(req, res, bodyChunks);
+        handleRequest(req, res, rawBodyText);
       });
       req.on("error", () => {
         // Connection dropped — nothing to do, client is gone
@@ -189,8 +205,11 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
-    // ── PR3a: POST /api/v1/library (add to library) ─────────────────
-    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+    // ── #1451: POST /api/v1/library/refs (add catalog skill) ───────
+    //
+    // Was at /api/v1/library until #1452 rebound that URL to multipart
+    // file-push. Same handler logic; only the URL moved.
+    if (url.pathname === "/api/v1/library/refs" && req.method === "POST") {
       if (!checkAuth(req, res)) return;
       let body;
       try {
@@ -233,6 +252,61 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
+    // ── #1452: POST /api/v1/library (multipart file-push) ──────────
+    //
+    // Accepts multipart/form-data and returns a synthesized
+    // `LibraryPushResponse` shape. The handler does not actually
+    // parse the multipart body — it just inspects the Content-Type
+    // header to confirm the client sent multipart, and serves either
+    // a `pushResponse` slot value (set via `setPushResponse`) or a
+    // default 201 with `action: "created"` shape.
+    if (url.pathname === "/api/v1/library" && req.method === "POST") {
+      if (!checkAuth(req, res)) return;
+      const contentType = req.headers["content-type"] ?? "";
+      if (!contentType.includes("multipart/form-data")) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            error:
+              "Invalid multipart body. Set Content-Type: multipart/form-data.",
+            code: "invalid_multipart",
+          }),
+        );
+        return;
+      }
+      if (pushResponse) {
+        res.writeHead(pushResponse.status, {
+          "Content-Type": "application/json",
+        });
+        res.end(JSON.stringify(pushResponse.body));
+        return;
+      }
+      // Default: 201 with a synthesized SyncSkill response.
+      res.writeHead(201, {
+        "Content-Type": "application/json",
+        Location: "/api/v1/library/mock/test-skill",
+      });
+      res.end(
+        JSON.stringify({
+          action: "created",
+          bump: null,
+          skill: {
+            owner: "mock",
+            name: "test-skill",
+            version: "1.0",
+            description: "mock",
+            keywords: [],
+            updatedAt: new Date().toISOString(),
+            etag: '"mock/test-skill@0"',
+            contextSignals: null,
+            files: [],
+            filesIncomplete: false,
+          },
+        }),
+      );
+      return;
+    }
+
     // ── PR3a: DELETE /api/v1/library/[owner]/[name] (remove) ────────
     {
       const m = url.pathname.match(/^\/api\/v1\/library\/([^\/]+)\/([^\/]+)$/);
@@ -489,6 +563,14 @@ export function createMockServer(initialPayload, options = {}) {
       removeResponses = new Map();
     },
 
+    /**
+     * #1452 — register the next POST /api/v1/library (multipart file-push)
+     * response. Pass `null` to restore the default 201 LibraryPushResponse.
+     */
+    setPushResponse(response) {
+      pushResponse = response;
+    },
+
     /**
      * Return the most recent POST body the server received, or null
      * if no POST has been made yet. Body is JSON-parsed when