skillrepo 4.3.0 → 4.5.0

package/README.md

@@ -179,14 +179,48 @@ One-shot fetch. Does NOT mutate your library or the server — just reads
 `GET /api/v1/skills/{owner}/{name}` and writes the skill to disk. Use
 this to preview or pin a specific skill without adding it to your library.
 
-### `list` — show what's in your library
+### `list` — show what's in your library and what needs syncing
 
 ```sh
 skillrepo list [--json]
 ```
 
-Renders your library as a table: owner, name, version, description. Uses
-the same cached ETag as `update`.
+Renders your library as a table with a per-row `Local` column showing
+on-disk drift state for each detected vendor:
+
+- `OK` — local copy matches the last sync.
+- `STALE` — library has a newer version than what's on disk.
+- `MISS` — library has the skill but no on-disk placement (or no sync
+  history yet — run `skillrepo update` to establish a baseline).
+- `EDIT` — local files have been modified since the last sync (different
+  SHA than what was persisted).
+
+When multiple vendors are detected, the column shows a worst-state-wins
+rollup (`missing > edited > stale > current`). The `--json` output
+includes a `placements[]` array per item with per-vendor states for
+scripts that want the full breakdown.
+
+A footer reports library-level sync state:
+
+- `library in sync — local skills up to date` — everything is current.
+- `library in sync — but N skills show local drift` — library hasn't
+  changed but some local placements need attention.
+- `library has changed since last sync` — registry has new content; run
+  `skillrepo update`.
+- `No sync history on this machine` — fresh install or
+  baseline-less state; run `skillrepo update`.
+
+Glyphs (`✓` / `⚠`) are used in TTY contexts; ASCII fallbacks (`OK` /
+`[!]` / `STALE` / `MISS` / `EDIT`) appear when stdout is not a TTY or
+`NO_COLOR` is set, so piped output stays clean.
+
+`--json` is a bare array of skill objects with the additional fields
+`state` (rollup) and `placements[]`. Existing scripts that consume
+the pre-#1555 `--json` shape keep working — the additions are purely
+per-item, no top-level wrapper.
+
+Uses the same cached ETag as `update` for the library-level footer
+state.
 
 ### `search` — explore the registry
 
@@ -219,6 +253,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
@@ -371,8 +508,28 @@ Two scenarios worth calling out:
 | `SKILLREPO_ACCESS_KEY` | Access key for any command. Takes precedence over the config file but not CLI flags. |
 | `SKILLREPO_URL` | Server URL. Same precedence as above. |
 | `SKILLREPO_TIMEOUT_MS` | Per-request fetch timeout in milliseconds (default 30000). Set to `0` to disable. |
+| `SKILLREPO_NO_UPDATE_CHECK` | Set to any non-empty truthy value (`1`, `yes`, `true`) to disable the post-command npm-registry self-staleness check. The check otherwise runs at most once per 24 hours, hits `registry.npmjs.org/skillrepo/latest`, and prints a one-line upgrade hint to stderr if a newer version is available. Auto-disabled when `CI=true`. |
 | `NO_COLOR` | Set any non-empty value to disable ANSI color in CLI output. |
 
+### Update nudge
+
+After every command that isn't `--json`, the CLI does a best-effort
+check against `https://registry.npmjs.org/skillrepo/latest` and prints
+a one-line hint on stderr when a newer version is available:
+
+```
+  A newer skillrepo is available: 4.3.0 → 4.5.0
+  Upgrade: npm install -g skillrepo@latest
+```
+
+The check is cached at `~/.claude/skillrepo/.npm-version-check` for
+24 hours on success and 1 hour on failure, has a 2-second fetch
+timeout, and is fire-and-forget — every failure mode (network error,
+non-2xx, parse failure, read-only FS) is swallowed silently. Set
+`SKILLREPO_NO_UPDATE_CHECK=1` to disable. `CI=true` auto-disables.
+Output is suppressed entirely when `--json` is on the parent command,
+so structured pipelines aren't disturbed.
+
 ### Skill placement
 
 Skills land at one of two project paths, depending on the agent:

package/bin/skillrepo.mjs

@@ -35,6 +35,8 @@ import { runSearch } from "../src/commands/search.mjs";
 import { runUninstall } from "../src/commands/uninstall.mjs";
 import { runSessionSync } from "../src/commands/session-sync.mjs";
 import { CliError, EXIT_OK, EXIT_VALIDATION } from "../src/lib/errors.mjs";
+import { checkForCliUpdate } from "../src/lib/npm-update-check.mjs";
+import { getCliVersion } from "../src/lib/cli-version.mjs";
 
 // ── Command registry ────────────────────────────────────────────────────
 
@@ -151,6 +153,49 @@ async function main(command, fullArgv) {
   }
 
   await COMMANDS[command].run(rest);
+
+  // After the primary command completes, do a best-effort npm-registry
+  // staleness check (#1554). Never blocks exit beyond a single tick:
+  // `Promise.race` against `setTimeout(0)` means if the fetch hasn't
+  // completed yet, we drop it and the user gets the nudge on the next
+  // invocation (when the cache file is more likely to be fresh).
+  //
+  // Suppressed entirely when the parent argv carries `--json` so we
+  // never inject text into a structured stream — not even on stderr,
+  // because some pipelines tee both streams.
+  if (!rest.includes("--json")) {
+    await runUpdateCheck();
+  }
+}
+
+/**
+ * Best-effort update check. On a CACHE HIT this resolves synchronously
+ * (within a microtask) and we emit the nudge before the 0ms timer
+ * fires — that's the steady-state behavior after the first invocation.
+ *
+ * On a cache miss we race against `setTimeout(0)` so the user's primary
+ * command exit isn't held up by the nudge logic when they don't have
+ * a cached answer yet. The in-flight fetch is INTENTIONALLY left
+ * running after the race resolves: it has its own 2s `AbortController`
+ * (inside `checkForCliUpdate`) and is silent on failure, so the worst
+ * case is the process appearing to take slightly longer on its very
+ * first invocation while the cache warms. Every subsequent invocation
+ * benefits from the 24h positive cache and exits immediately.
+ *
+ * Errors are swallowed at the source by `checkForCliUpdate` itself; the
+ * outer `.catch` is belt-and-braces for the rare case where loading
+ * the module synchronously throws.
+ */
+async function runUpdateCheck() {
+  let currentVersion;
+  try {
+    currentVersion = getCliVersion();
+  } catch {
+    return;
+  }
+  const checker = checkForCliUpdate({ currentVersion }).catch(() => {});
+  const yieldOnce = new Promise((resolve) => setTimeout(resolve, 0));
+  await Promise.race([checker, yieldOnce]);
 }
 
 // ── Help printing ───────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
@@ -26,6 +26,7 @@
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "cli-table3": "^0.6.5",
-    "gray-matter": "^4.0.3"
+    "gray-matter": "^4.0.3",
+    "semver": "^7.6.3"
   }
 }

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}`);