skillrepo 4.2.0 → 4.4.0

package/README.md

@@ -219,6 +219,109 @@ DELETEs from `/api/v1/library` and deletes the local directory. Requires
 a write-scoped access key. The local delete is immediate and does not
 wait for a follow-up sync.
 
+### `push` — upload a local skill directory to your account
+
+```sh
+skillrepo push <path> [--idempotency-key <key>] [--key <key>] [--url <url>] [--json]
+```
+
+Multipart `POST` to `/api/v1/library`. Walks `<path>`, packages
+`SKILL.md` plus every supporting file under `scripts/`, `references/`,
+and `assets/`, and uploads them as a single request. The server picks
+the outcome by SKILL.md frontmatter `name`:
+
+- **First push** of this name → creates a private skill and returns
+  `action: "created"`.
+- **Subsequent push with changed content** → releases a new version.
+  The server classifies the bump as major (if `description`,
+  `allowed-tools`, or `compatibility` changed) or minor otherwise, and
+  returns `action: "updated"` with the bump kind.
+- **Identical content** → no-op (SHA-matched). Returns
+  `action: "unchanged"`.
+
+`push` is the only CLI command that uploads local content; it does not
+write anything back to disk. Use `update` to pull canonical skills
+from the server to your local library.
+
+Limits: total multipart body ≤ 4.5 MB, per-file path depth ≤ 5
+segments, executable/archive extensions blocked (full list in
+`src/lib/skills/constants.ts`). Anti-abuse rate limit: 5/min and
+30/hr on Publisher; 30/min and 500/hr on Team.
+
+Flags:
+
+- `--idempotency-key <key>` — explicit key for safe retries. By default
+  the CLI generates a fresh UUID per invocation and uses it for the
+  in-process retry loop (transient 5xx/429 get up to 3 attempts with
+  exponential backoff and jitter). Pass an explicit key to share it
+  across separate shell invocations (CI step retries, manual reruns)
+  and replay the cached response. Cached responses live for 24 hours.
+- `--json` — emit a structured object (`action`, `bump`, `owner`,
+  `name`, `version`, `filesUploaded`).
+- `--key`, `--url` — standard auth / endpoint flags.
+
+Exit codes: `5` (validation — bad SKILL.md, blocked path, payload too
+large, `plan_limit`), `4` (scope — read-only key), `2` (auth), `1`
+(network/5xx after retries).
+
+### `publish` — make one of your skills visible in the public catalog
+
+```sh
+skillrepo publish <@owner/name> [--key <key>] [--url <url>] [--json]
+```
+
+`POST`s to `/api/v1/library/{owner}/{name}/publish` to flip the
+skill's visibility from `private` to `global`. Idempotent: calling
+`publish` on an already-global skill returns `200` with
+`action: "unchanged"` (the CLI prints "Already published").
+Requires a write-scoped access key.
+
+Permission model: admin+ members can always publish. Non-admin members
+can publish if their account-membership has `canPublish: true` (or the
+account-wide `memberCanPublish` default is enabled). Without either,
+the CLI exits `4 / scope` with `code: publish_not_permitted`. The same
+`canPublish` capability gates `unpublish` and `delete` symmetrically.
+
+Publish-only preconditions that surface as exit `5 / validation`:
+
+- `namespace_unset` — the account's name still equals its
+  auto-generated slug; customize the namespace first.
+- `analysis_pending` — safety analysis hasn't completed (only fires
+  where analysis is enabled).
+- `safety_grade_too_low` — the skill's safety grade is `F`.
+
+Flags:
+
+- `--json` — emit `{ action, owner, name }`. The CLI exits non-zero on error, so the presence of stdout JSON already implies success — there is no `ok` field.
+- `--key`, `--url` — standard auth / endpoint flags.
+
+### `unpublish` — remove one of your skills from the public catalog
+
+```sh
+skillrepo unpublish <@owner/name> [--key <key>] [--url <url>] [--json]
+```
+
+`POST`s to `/api/v1/library/{owner}/{name}/unpublish` to flip the
+skill's visibility from `global` to `private`. Pair to `publish`:
+same auth, same scope, same flag surface.
+
+**Subscribers keep their copy.** Accounts that already had your skill
+in their library retain the version they pulled — they just stop
+receiving future updates unless you republish. The CLI surfaces a
+one-line summary (e.g. "Notified 12 subscribers") so you know how
+many accounts the unpublish reached.
+
+Each affected subscriber account's owner-role member(s) receive a
+one-time notification email, debounced 24h per `(skill, account)`
+pair so a fast unpublish/republish/unpublish cycle doesn't spam the
+same recipient. The publisher's own account is excluded.
+Already-private skills (`action: "unchanged"`) trigger no emails.
+
+Flags:
+
+- `--json` — emit `{ action, owner, name, notifiedSubscriberCount }`. `notifiedSubscriberCount` is `0` when `action === "unchanged"`. No `ok` field — exit code carries success/failure.
+- `--key`, `--url` — standard auth / endpoint flags.
+
 ### `session-sync` — auto-sync on Claude Code session start
 
 ```sh

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.4.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -87,7 +87,7 @@ import {
   claudeSkillsProjectRoot,
   agentsSkillsProjectRoot,
 } from "../lib/paths.mjs";
-import { promptWithBrowserOpen } from "../lib/prompt.mjs";
+import { promptWithBrowserOpen, confirm } from "../lib/prompt.mjs";
 import { promptMultiSelect } from "../lib/prompt-multiselect.mjs";
 import {
   CliError,
@@ -96,6 +96,10 @@ import {
   EXIT_AUTH,
 } from "../lib/errors.mjs";
 import { cliAuthUrl } from "../lib/constants.mjs";
+import {
+  reportInitFailure,
+  telemetryDisabledByEnv,
+} from "../lib/telemetry.mjs";
 
 /**
  * Format the user-visible "configured X, Y" line for the init step-4
@@ -288,6 +292,38 @@ export async function runInit(argv, io = {}, deps = {}) {
 
   p.blank();
 
+  // Determine the telemetry preference for THIS init run (#1539).
+  // Priority: SKILLREPO_NO_TELEMETRY env var (always wins) → existing
+  // config flag (if set explicitly) → opt-out default of `true`
+  // (enabled). The env-var check is the only opt-out path that fires
+  // BEFORE the very first user interaction; everything else assumes
+  // the user is willing to receive the prompt below.
+  let telemetryEnabledForRun;
+  if (telemetryDisabledByEnv()) {
+    telemetryEnabledForRun = false;
+  } else if (
+    existingConfig &&
+    typeof existingConfig.telemetry === "boolean"
+  ) {
+    telemetryEnabledForRun = existingConfig.telemetry;
+  } else if (yes || !process.stdin.isTTY) {
+    // Non-interactive: take the opt-out-friendly default. Users in
+    // CI / scripts can pin `SKILLREPO_NO_TELEMETRY=1` to override.
+    // The `!isTTY` check protects existing CI patterns like
+    // `init --key sk_live_...` (no --yes) that worked before this
+    // prompt was added — they would hang on `readline.question()`
+    // waiting for stdin that never arrives.
+    telemetryEnabledForRun = true;
+  } else {
+    // First-init prompt — only fires when no preference is recorded,
+    // the env var didn't already opt out, AND stdin is a TTY. Y/n
+    // with Y default, so a bare Enter keeps telemetry enabled.
+    telemetryEnabledForRun = await confirm(
+      "Send anonymous error reports to help improve setup?",
+      true,
+    );
+  }
+
   // ── Step 2: Validate against the server ──────────────────────
   p.step(2, 7, "Validating key");
   let accountCtx;
@@ -315,8 +351,27 @@ export async function runInit(argv, io = {}, deps = {}) {
       if (!apiKey || !apiKey.startsWith("sk_live_")) {
         throw validationError("Invalid access key format.");
       }
-      accountCtx = await validateAccessKey(serverUrl, apiKey, "init");
+      try {
+        accountCtx = await validateAccessKey(serverUrl, apiKey, "init");
+      } catch (retryErr) {
+        // The user re-pasted and validate still failed. This is the
+        // failure mode the diagnostic exercise surfaced — exactly the
+        // case telemetry exists for. Fire-and-forget; never throws.
+        void reportInitFailure({
+          serverUrl,
+          config: telemetryEnabledForRun ? { telemetry: true } : { telemetry: false },
+          stage: "post_paste_validate",
+          errorCode: retryErr instanceof CliError ? retryErr.exitCode : EXIT_AUTH,
+        });
+        throw retryErr;
+      }
     } else {
+      void reportInitFailure({
+        serverUrl,
+        config: telemetryEnabledForRun ? { telemetry: true } : { telemetry: false },
+        stage: "post_paste_validate",
+        errorCode: err instanceof CliError ? err.exitCode : EXIT_AUTH,
+      });
       throw err;
     }
   }
@@ -325,12 +380,15 @@ export async function runInit(argv, io = {}, deps = {}) {
 
   // ── Step 3: Write global config ──────────────────────────────
   p.step(3, 7, "Writing config");
+  // Persist the telemetry preference alongside the credentials so
+  // subsequent inits skip the prompt and honor the same choice (#1539).
   const configAction = writeConfig({
     apiKey,
     serverUrl,
     accountSlug: accountCtx.accountSlug,
     accountId: accountCtx.accountId,
     userId: accountCtx.userId,
+    telemetry: telemetryEnabledForRun,
   });
   p.success(`~/.claude/skillrepo/config.json ${configAction}`);
 

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/config.mjs

@@ -174,6 +174,12 @@ export function writeConfig(config) {
   for (const key of ["accountSlug", "accountId", "userId"]) {
     if (config[key] !== undefined) merged[key] = config[key];
   }
+  // Telemetry opt-in/out flag (#1539). Persisted only when the caller
+  // explicitly sets it — omitting means "no preference recorded,"
+  // which the telemetry module treats as "enabled" (opt-out default).
+  if (typeof config.telemetry === "boolean") {
+    merged.telemetry = config.telemetry;
+  }
 
   // Atomic write via temp-file + rename. Matches the file-write.mjs
   // pattern: the config file is never in a half-written state, so