skillrepo 4.2.0 → 4.3.0

package/bin/skillrepo.mjs

@@ -3,7 +3,8 @@
 /**
  * SkillRepo CLI — pull-based command dispatcher (#674, part of #646).
  *
- * Routes seven commands: init, update, get, add, remove, list, search.
+ * Routes the user-facing commands: init, update, get, add, push,
+ * publish, unpublish, remove, list, search, uninstall, session-sync.
  *
  * PR1 ships only the dispatcher; command modules other than init are
  * stubbed and exit with a "not yet implemented" message. The existing
@@ -26,6 +27,8 @@ 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 { runPublish } from "../src/commands/publish.mjs";
+import { runUnpublish } from "../src/commands/unpublish.mjs";
 import { runRemove } from "../src/commands/remove.mjs";
 import { runList } from "../src/commands/list.mjs";
 import { runSearch } from "../src/commands/search.mjs";
@@ -70,6 +73,16 @@ const COMMANDS = {
       "[--idempotency-key <key>] [--json]",
     run: async (argv) => runPush(argv),
   },
+  publish: {
+    description: "Make one of your skills visible in the public catalog",
+    usage: "skillrepo publish <@owner/name> [--json] [--key <key>] [--url <url>]",
+    run: async (argv) => runPublish(argv),
+  },
+  unpublish: {
+    description: "Remove one of your skills from the public catalog (subscribers keep their copy)",
+    usage: "skillrepo unpublish <@owner/name> [--json] [--key <key>] [--url <url>]",
+    run: async (argv) => runUnpublish(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.2.0",
+  "version": "4.3.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/publish.mjs

@@ -0,0 +1,125 @@
+/**
+ * `skillrepo publish <@owner/name>` — flip a skill's visibility from
+ * `private` to `global`, making it discoverable in the public catalog
+ * (Epic #1444 R3 #1456).
+ *
+ * Verb is RESERVED for visibility transitions. Releasing a new version
+ * happens via `skillrepo push <path>`. The `publish` and `unpublish`
+ * pair is symmetric — same auth, same access-key scope, same flag
+ * surface — and shares an `setSkillVisibility` HTTP helper under
+ * the hood.
+ *
+ * Outcomes (mirror the server's discriminated `LibraryVisibilityResult`):
+ *   - `published`        → 200 OK, "✓ Published @owner/name…"
+ *   - `unchanged`        → 200 OK, "✓ Already published…"
+ *   - `not-found`        → exit 5 (EXIT_VALIDATION) with skill-not-found message
+ *   - `forbidden`        → exit 4 (EXIT_SCOPE) with the permission hint
+ *   - `publish-blocked`  → exit 5 (EXIT_VALIDATION) with the precondition reason
+ *
+ * Other 4xx/5xx flow through `mapErrorResponse` in `http.mjs` and
+ * surface as `authError` / `scopeError` / `networkError`.
+ *
+ * Flags: `--json --key --url`. NO disk write. NO `--global` /
+ * `--agent` (visibility transitions touch only the registry; local
+ * skill files are unaffected).
+ */
+
+import { publishLibrarySkill } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError, scopeError } from "../lib/errors.mjs";
+
+/**
+ * Run `publish`. 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 runPublish(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let identifier = null;
+
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg) {
+      if (identifier !== null) {
+        throw validationError(`Unexpected extra argument: ${arg}`, {
+          hint: "Pass exactly one @owner/name.",
+        });
+      }
+      identifier = arg;
+      return 1;
+    },
+  });
+
+  if (!identifier) {
+    throw validationError("Missing skill identifier.", {
+      hint: "Usage: skillrepo publish <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const ref = formatIdentifier({ owner, name });
+
+  const result = await publishLibrarySkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (result.action === "not-found") {
+    throw validationError(`Skill ${ref} not found in your account.`, {
+      hint: "You can only publish skills that you own. Check `skillrepo list` for your skills.",
+    });
+  }
+
+  if (result.action === "forbidden") {
+    // exit 4 (EXIT_SCOPE) — same exit code as "missing API-key
+    // scope," semantically the closest match for "you're not
+    // permitted to do this." Scripts can distinguish via the `code`
+    // string in JSON output.
+    //
+    // Server `result.reason` already explains the entitlement model
+    // ("Admins, or members with the `canPublish` entitlement…").
+    // Hint must NOT repeat that text — just point at the next step
+    // the user takes, otherwise the terminal shows the same sentence
+    // twice (once as `error:`, once as `hint:`).
+    throw scopeError(result.reason, {
+      hint: "Ask an account admin to grant you the `canPublish` capability if you should have it.",
+    });
+  }
+
+  if (result.action === "publish-blocked") {
+    // 422 — product-rule precondition. The reason text from the server
+    // is already actionable (it tells the user what to do); pass it
+    // through verbatim. exit 5 (EXIT_VALIDATION) signals "the request
+    // was understood but cannot be processed in the current state."
+    throw validationError(result.reason);
+  }
+
+  if (flags.json) {
+    // Shape matches the rest of the CLI (`add`, `remove`, `push`):
+    // `action` is the success discriminator. No `ok: true` field —
+    // the CLI exits non-zero on error, so the presence of stdout
+    // JSON already implies success.
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          owner,
+          name,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  if (result.action === "unchanged") {
+    stdout.write(
+      `\n  ✓ Already published — ${ref} is already in the public catalog.\n\n`,
+    );
+    return;
+  }
+
+  // result.action === "published"
+  stdout.write(`\n  ✓ Published ${ref} — now in the public catalog.\n\n`);
+}

package/src/commands/unpublish.mjs

@@ -0,0 +1,129 @@
+/**
+ * `skillrepo unpublish <@owner/name>` — flip a skill's visibility from
+ * `global` to `private`, removing it from the public catalog
+ * (Epic #1444 R3 #1456).
+ *
+ * Pair to `publish.mjs`. Same auth, same scope, same flag surface.
+ *
+ * Side-effect note (per the locked decision in #1446 — surface to
+ * the user via the success-line copy):
+ *   - Subscribers KEEP their current copy of the skill on disk.
+ *   - Subscribers stop receiving future updates unless the publisher
+ *     re-publishes.
+ *   - Each affected subscriber account's owner-role member(s) get
+ *     an unpublish-notification email, debounced 24h per
+ *     (skill, subscriber-account) pair.
+ *
+ * The success line for an actual unpublish includes
+ * `notifiedSubscriberCount` so the publisher knows how many accounts
+ * the unpublish reached.
+ *
+ * Outcomes:
+ *   - `unpublished` → 200 OK, "✓ Unpublished @owner/name (notified N subscribers…)"
+ *   - `unchanged`   → 200 OK, "✓ Already private…"
+ *   - `not-found`   → exit 5 (EXIT_VALIDATION) with skill-not-found message
+ *   - `forbidden`   → exit 4 (EXIT_SCOPE) with the permission hint
+ *
+ * Unpublish has no product-rule preconditions of its own, so the
+ * `publish-blocked` outcome is never returned by the server here.
+ */
+
+import { unpublishLibrarySkill } from "../lib/http.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
+import { validationError, scopeError } from "../lib/errors.mjs";
+
+/**
+ * Run `unpublish`. 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 runUnpublish(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  let identifier = null;
+
+  const flags = resolveFlags(argv, {
+    acceptPositional(arg) {
+      if (identifier !== null) {
+        throw validationError(`Unexpected extra argument: ${arg}`, {
+          hint: "Pass exactly one @owner/name.",
+        });
+      }
+      identifier = arg;
+      return 1;
+    },
+  });
+
+  if (!identifier) {
+    throw validationError("Missing skill identifier.", {
+      hint: "Usage: skillrepo unpublish <@owner/name>",
+    });
+  }
+
+  const { owner, name } = parseIdentifier(identifier);
+  const ref = formatIdentifier({ owner, name });
+
+  const result = await unpublishLibrarySkill(flags.serverUrl, flags.apiKey, owner, name);
+
+  if (result.action === "not-found") {
+    throw validationError(`Skill ${ref} not found in your account.`, {
+      hint: "You can only unpublish skills that you own. Check `skillrepo list` for your skills.",
+    });
+  }
+
+  if (result.action === "forbidden") {
+    // exit 4 (EXIT_SCOPE) — same code as missing API-key scope.
+    // Server `result.reason` already names the entitlement. Hint
+    // stays short and action-only to avoid duplicating that text.
+    throw scopeError(result.reason, {
+      hint: "Ask an account admin to grant you the `canPublish` capability if you should have it.",
+    });
+  }
+
+  if (flags.json) {
+    // Shape matches the rest of the CLI: `action` is the success
+    // discriminator, no `ok` field. `notifiedSubscriberCount` is
+    // always present so scripts don't need conditional access.
+    stdout.write(
+      JSON.stringify(
+        {
+          action: result.action,
+          owner,
+          name,
+          notifiedSubscriberCount:
+            result.action === "unpublished" ? result.notifiedSubscriberCount : 0,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  if (result.action === "unchanged") {
+    stdout.write(
+      `\n  ✓ Already private — ${ref} is not in the public catalog.\n\n`,
+    );
+    return;
+  }
+
+  // result.action === "unpublished"
+  // Locked decision #1446: subscribers keep their copy; they stop
+  // getting updates. Surface that explicitly so the publisher knows
+  // the action was non-destructive for existing users.
+  const count = result.notifiedSubscriberCount;
+  if (count === 0) {
+    stdout.write(
+      `\n  ✓ Unpublished ${ref} — no other accounts had it in their library, no notifications sent.\n\n`,
+    );
+  } else {
+    const subscribers = count === 1 ? "subscriber" : "subscribers";
+    stdout.write(
+      `\n  ✓ Unpublished ${ref} — notified ${count} ${subscribers} ` +
+        `(they keep their current copy but won't receive future updates).\n\n`,
+    );
+  }
+}

package/src/lib/http.mjs

@@ -1055,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/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/e2e/mock-server.mjs

@@ -9,6 +9,8 @@
  *   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)
+ *   POST   /api/v1/library/[owner]/[name]/publish — make global (#1449)
+ *   POST   /api/v1/library/[owner]/[name]/unpublish — make private (#1449)
  *   GET    /api/v1/skills/[owner]/[name]          — single skill fetch (PR2)
  *   GET    /api/v1/skills/search                  — keyword search (PR2)
  *
@@ -30,6 +32,10 @@
  *   setPushResponse(resp)                — response for POST /library multipart push (#1452)
  *   getLastPostBody()                    — inspect the most recent POST body (JSON-parsed)
  *
+ *   (Epic #1444 R3 #1449 additions)
+ *   setPublishResponse(owner, name, resp)   — per-skill response for POST /library/<owner>/<name>/publish
+ *   setUnpublishResponse(owner, name, resp) — per-skill response for POST /library/<owner>/<name>/unpublish
+ *
  * 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.
@@ -86,6 +92,10 @@ export function createMockServer(initialPayload, options = {}) {
   // 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 }
+  // Epic #1444 R3 #1456 — POST /api/v1/library/[owner]/[name]/publish
+  // and POST /api/v1/library/[owner]/[name]/unpublish (#1449).
+  let publishResponses = new Map();   // key: "owner/name" or "*" → { status, body }
+  let unpublishResponses = 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,
@@ -307,6 +317,86 @@ export function createMockServer(initialPayload, options = {}) {
       return;
     }
 
+    // ── #1449: POST /api/v1/library/[owner]/[name]/publish ─────────
+    {
+      const m = url.pathname.match(
+        /^\/api\/v1\/library\/([^\/]+)\/([^\/]+)\/publish$/,
+      );
+      if (m && req.method === "POST") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const configured =
+          publishResponses.get(`${owner}/${name}`) ?? publishResponses.get("*");
+        if (configured) {
+          res.writeHead(configured.status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(configured.body));
+          return;
+        }
+        // Default: 200 published with synthesized SyncSkill.
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            action: "published",
+            skill: {
+              owner,
+              name,
+              version: "1.0.0",
+              description: "mock",
+              keywords: [],
+              updatedAt: new Date().toISOString(),
+              etag: `"${owner}/${name}@0"`,
+              contextSignals: null,
+              files: [],
+              filesIncomplete: false,
+            },
+          }),
+        );
+        return;
+      }
+    }
+
+    // ── #1449: POST /api/v1/library/[owner]/[name]/unpublish ───────
+    {
+      const m = url.pathname.match(
+        /^\/api\/v1\/library\/([^\/]+)\/([^\/]+)\/unpublish$/,
+      );
+      if (m && req.method === "POST") {
+        if (!checkAuth(req, res)) return;
+        const owner = decodeURIComponent(m[1]);
+        const name = decodeURIComponent(m[2]);
+        const configured =
+          unpublishResponses.get(`${owner}/${name}`) ??
+          unpublishResponses.get("*");
+        if (configured) {
+          res.writeHead(configured.status, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(configured.body));
+          return;
+        }
+        // Default: 200 unpublished, zero subscribers notified.
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(
+          JSON.stringify({
+            action: "unpublished",
+            notifiedSubscriberCount: 0,
+            skill: {
+              owner,
+              name,
+              version: "1.0.0",
+              description: "mock",
+              keywords: [],
+              updatedAt: new Date().toISOString(),
+              etag: `"${owner}/${name}@0"`,
+              contextSignals: null,
+              files: [],
+              filesIncomplete: false,
+            },
+          }),
+        );
+        return;
+      }
+    }
+
     // ── PR3a: DELETE /api/v1/library/[owner]/[name] (remove) ────────
     {
       const m = url.pathname.match(/^\/api\/v1\/library\/([^\/]+)\/([^\/]+)$/);
@@ -563,6 +653,26 @@ export function createMockServer(initialPayload, options = {}) {
       removeResponses = new Map();
     },
 
+    // Epic #1444 R3 #1456 — publish / unpublish slot setters.
+    setPublishResponse(owner, name, response) {
+      publishResponses.set(`${owner}/${name}`, response);
+    },
+    setPublishResponseForAny(response) {
+      publishResponses.set("*", response);
+    },
+    clearPublishResponses() {
+      publishResponses = new Map();
+    },
+    setUnpublishResponse(owner, name, response) {
+      unpublishResponses.set(`${owner}/${name}`, response);
+    },
+    setUnpublishResponseForAny(response) {
+      unpublishResponses.set("*", response);
+    },
+    clearUnpublishResponses() {
+      unpublishResponses = new Map();
+    },
+
     /**
      * #1452 — register the next POST /api/v1/library (multipart file-push)
      * response. Pass `null` to restore the default 201 LibraryPushResponse.