skillrepo 4.1.0 → 4.3.0

package/src/test/commands/publish.test.mjs

@@ -0,0 +1,420 @@
+/**
+ * Unit / integration tests for `runPublish` and `runUnpublish` —
+ * Epic #1444 R3 #1456.
+ *
+ * Tests both verbs in one file because they share the
+ * `setSkillVisibility` HTTP helper and have symmetric outcome
+ * mappings (only the response shape and 403 code differ). Each
+ * test exercises a distinct outcome of the discriminated
+ * `VisibilityResult` union returned by the HTTP layer.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runPublish } from "../../commands/publish.mjs";
+import { runUnpublish } from "../../commands/unpublish.mjs";
+import {
+  CliError,
+  EXIT_VALIDATION,
+  EXIT_AUTH,
+  EXIT_SCOPE,
+} 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;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+let stdout;
+const VALID_KEY = "sk_live_test";
+
+async function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-cmd-pub-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  process.chdir(join(sandbox, "project"));
+  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;
+}
+
+// argv used by both verbs — identifier first, then auth + endpoint
+// flags. Caller can append extra flags (e.g. `--json`) at the end.
+const baseArgv = (...extra) => [
+  `@alice/my-skill`,
+  "--key",
+  VALID_KEY,
+  "--url",
+  serverUrl,
+  ...extra,
+];
+
+// ── runPublish ──────────────────────────────────────────────────────────
+
+describe("runPublish — happy path", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("200 published → exit 0, prints '✓ Published @owner/name'", async () => {
+    // Default mock-server response is 200 published with synthesised
+    // SyncSkill — no slot configuration needed.
+    await runPublish(baseArgv(), { stdout });
+    const out = stdout.text();
+    // Matches the established `✓ <verb>` shape used by add/remove/push.
+    assert.match(out, /✓ Published @alice\/my-skill/);
+    assert.match(out, /now in the public catalog/);
+  });
+
+  it("200 unchanged → exit 0, prints '✓ Already published'", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unchanged",
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runPublish(baseArgv(), { stdout });
+    assert.match(stdout.text(), /✓ Already published/);
+  });
+
+  it("--json emits a structured success payload (no `ok` field — matches add/remove/push convention)", async () => {
+    await runPublish(baseArgv("--json"), { stdout });
+    const parsed = JSON.parse(stdout.text());
+    // `action` is the success discriminator. NO `ok` field — the
+    // CLI exits non-zero on error, so the presence of stdout JSON
+    // already implies success. Matches add.mjs / remove.mjs /
+    // push.mjs shapes.
+    assert.equal(parsed.ok, undefined);
+    assert.equal(parsed.action, "published");
+    assert.equal(parsed.owner, "alice");
+    assert.equal(parsed.name, "my-skill");
+  });
+});
+
+describe("runPublish — error paths", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("missing identifier → CliError EXIT_VALIDATION", async () => {
+    await assert.rejects(
+      runPublish(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Missing skill identifier/.test(err.message),
+    );
+  });
+
+  it("404 not-found → CliError EXIT_VALIDATION with helpful hint", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 404,
+      body: { error: "Skill not found", code: "skill_not_found" },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /not found in your account/.test(err.message),
+    );
+  });
+
+  it("403 publish_not_permitted → CliError EXIT_SCOPE with canPublish hint", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 403,
+      body: {
+        error: "You do not have permission to publish this skill.",
+        code: "publish_not_permitted",
+      },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_SCOPE &&
+        /canPublish/.test(err.hint ?? ""),
+    );
+  });
+
+  it("403 hint does NOT duplicate the server's error reason text", async () => {
+    // Regression guard: pre-PR-F-review the CLI hint repeated the
+    // entitlement explanation that the server already includes in
+    // its `error` field. Result was the same sentence twice in
+    // terminal output. The hint must stay short and action-only.
+    server.setPublishResponse("alice", "my-skill", {
+      status: 403,
+      body: {
+        error:
+          "You do not have permission to publish this skill. Admins, or members with the `canPublish` entitlement, can publish.",
+        code: "publish_not_permitted",
+      },
+    });
+    await assert.rejects(runPublish(baseArgv(), { stdout }), (err) => {
+      assert.ok(err instanceof CliError);
+      // The server's reason text contains "Admins, or members with
+      // the `canPublish` entitlement, can publish." That sentence
+      // must NOT appear in the hint too.
+      assert.doesNotMatch(
+        err.hint ?? "",
+        /Admins, or members with the `canPublish` entitlement, can publish\./,
+      );
+      // But the hint should still be actionable.
+      assert.match(err.hint ?? "", /Ask an account admin/);
+      return true;
+    });
+  });
+
+  it("403 plan_limit → CliError EXIT_VALIDATION (NOT authError), billing hint surfaces", async () => {
+    // Real-world regression scenario: an account over its skill
+    // quota tries to publish. Server returns 403 with code
+    // `plan_limit`. The CLI MUST classify this as exit 5
+    // validation with the billing hint, NOT exit 2 authError
+    // ("contact support") — a pre-review version of the code
+    // consumed the 403 body and let mapErrorResponse re-parse, but
+    // the body was empty by then so plan_limit fell through to
+    // authError.
+    server.setPublishResponse("alice", "my-skill", {
+      status: 403,
+      body: {
+        error: "You are over your library skill quota.",
+        code: "plan_limit",
+      },
+    });
+    await assert.rejects(runPublish(baseArgv(), { stdout }), (err) => {
+      assert.ok(err instanceof CliError);
+      assert.equal(err.exitCode, EXIT_VALIDATION);
+      assert.match(err.hint ?? "", /Upgrade your plan|billing/);
+      return true;
+    });
+  });
+
+  it("422 namespace_unset → CliError EXIT_VALIDATION, reason text passes through", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 422,
+      body: {
+        error: "Set up your account namespace before publishing.",
+        code: "namespace_unset",
+      },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /account namespace/.test(err.message),
+    );
+  });
+
+  it("422 analysis_pending → CliError EXIT_VALIDATION, server reason wins", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 422,
+      body: {
+        error: "This skill must be analyzed before publishing.",
+        code: "analysis_pending",
+      },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /must be analyzed/.test(err.message),
+    );
+  });
+
+  it("422 safety_grade_too_low → CliError EXIT_VALIDATION, server reason wins", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 422,
+      body: {
+        error: "Skills with a safety grade of F cannot be published.",
+        code: "safety_grade_too_low",
+      },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /safety grade of F cannot be published/.test(err.message),
+    );
+  });
+
+  it("401 unauthorized → CliError EXIT_AUTH", async () => {
+    server.setPublishResponse("alice", "my-skill", {
+      status: 401,
+      body: { error: "Invalid access key" },
+    });
+    await assert.rejects(
+      runPublish(baseArgv(), { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+});
+
+// ── runUnpublish ────────────────────────────────────────────────────────
+
+describe("runUnpublish — happy path", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("200 unpublished with N=0 subscribers → exit 0, no-notifications message", async () => {
+    // Default mock-server response is 200 unpublished, count=0.
+    await runUnpublish(baseArgv(), { stdout });
+    assert.match(
+      stdout.text(),
+      /✓ Unpublished @alice\/my-skill — no other accounts had it in their library/,
+    );
+  });
+
+  it("200 unpublished with N=1 → singular 'notified 1 subscriber'", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unpublished",
+        notifiedSubscriberCount: 1,
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runUnpublish(baseArgv(), { stdout });
+    const out = stdout.text();
+    assert.match(out, /notified 1 subscriber\b/);
+    assert.doesNotMatch(out, /1 subscribers/);
+  });
+
+  it("200 unpublished with N=5 → plural 'notified 5 subscribers'", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unpublished",
+        notifiedSubscriberCount: 5,
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runUnpublish(baseArgv(), { stdout });
+    const out = stdout.text();
+    assert.match(out, /notified 5 subscribers/);
+    assert.match(out, /they keep their current copy/);
+  });
+
+  it("200 unchanged → exit 0, prints '✓ Already private'", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unchanged",
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runUnpublish(baseArgv(), { stdout });
+    assert.match(stdout.text(), /✓ Already private/);
+  });
+
+  it("--json emits a structured payload with notifiedSubscriberCount (no `ok` field)", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unpublished",
+        notifiedSubscriberCount: 3,
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runUnpublish(baseArgv("--json"), { stdout });
+    const parsed = JSON.parse(stdout.text());
+    assert.equal(parsed.ok, undefined);
+    assert.equal(parsed.action, "unpublished");
+    assert.equal(parsed.notifiedSubscriberCount, 3);
+  });
+
+  it("--json on unchanged emits notifiedSubscriberCount=0 (no `ok` field)", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 200,
+      body: {
+        action: "unchanged",
+        skill: { owner: "alice", name: "my-skill" },
+      },
+    });
+    await runUnpublish(baseArgv("--json"), { stdout });
+    const parsed = JSON.parse(stdout.text());
+    assert.equal(parsed.ok, undefined);
+    assert.equal(parsed.action, "unchanged");
+    assert.equal(parsed.notifiedSubscriberCount, 0);
+  });
+});
+
+describe("runUnpublish — error paths", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("404 not-found → CliError EXIT_VALIDATION", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 404,
+      body: { error: "Skill not found", code: "skill_not_found" },
+    });
+    await assert.rejects(
+      runUnpublish(baseArgv(), { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /not found in your account/.test(err.message),
+    );
+  });
+
+  it("403 unpublish_not_permitted → CliError EXIT_SCOPE with action-only hint", async () => {
+    server.setUnpublishResponse("alice", "my-skill", {
+      status: 403,
+      body: {
+        error:
+          "You do not have permission to unpublish this skill. Admins, or members with the `canPublish` entitlement, can unpublish.",
+        code: "unpublish_not_permitted",
+      },
+    });
+    await assert.rejects(runUnpublish(baseArgv(), { stdout }), (err) => {
+      assert.ok(err instanceof CliError);
+      assert.equal(err.exitCode, EXIT_SCOPE);
+      // Same regression guard as the publish path — hint must NOT
+      // duplicate the server's entitlement explanation.
+      assert.doesNotMatch(
+        err.hint ?? "",
+        /Admins, or members with the `canPublish` entitlement, can unpublish\./,
+      );
+      assert.match(err.hint ?? "", /Ask an account admin/);
+      return true;
+    });
+  });
+
+  it("missing identifier → CliError EXIT_VALIDATION", async () => {
+    await assert.rejects(
+      runUnpublish(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /Missing skill identifier/.test(err.message),
+    );
+  });
+});

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