skillrepo 4.4.0 → 4.5.1

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
 
@@ -474,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.4.0",
+  "version": "4.5.1",
   "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/add.mjs

@@ -46,6 +46,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { upsertLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -158,6 +159,20 @@ export async function runAdd(argv, io = {}) {
 
   writeSkillDir(skill, { vendors, global: flags.global });
 
+  // Update `.last-sync` so `list` immediately recognizes this skill
+  // as `current`. Without this the user adds a skill, then runs
+  // `list`, and sees their freshly-added skill marked MISS — the
+  // exact same class of contract gap that PR #1574 fixed for the
+  // multi-vendor case in `update`/`list`. See `upsertLastSyncEntry`
+  // docstring for the etag-preservation rationale.
+  try {
+    upsertLastSyncEntry(skill);
+  } catch {
+    // Non-fatal: skill is on disk, the state file write failure
+    // does not change that. Same semantics as runSync's warn-and-
+    // proceed for last-sync persistence failures.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify(

package/src/commands/get.mjs

@@ -36,6 +36,7 @@ import {
   effectiveVendors,
   requireVendorTargets,
 } from "../lib/cli-config.mjs";
+import { upsertLastSyncEntry } from "../lib/sync.mjs";
 import { parseIdentifier, formatIdentifier } from "../lib/identifier.mjs";
 import { validationError } from "../lib/errors.mjs";
 
@@ -109,6 +110,21 @@ export async function runGet(argv, io = {}) {
 
   writeSkillDir(skill, { vendors, global: flags.global });
 
+  // Update `.last-sync` so `list` recognizes this skill as `current`
+  // afterward instead of reporting a stale `MISSING`. Best-effort:
+  // a state-file write failure is non-fatal (the files are already
+  // on disk), but writeLastSync throws diskError if it cannot
+  // persist — we catch and continue. Pre-PR #1574 `get` skipped
+  // this entirely, which surfaced every freshly-fetched skill as
+  // MISS in the very next `list` invocation.
+  try {
+    upsertLastSyncEntry(skill);
+  } catch {
+    // Same failure semantics as runSync's "couldn't persist last
+    // sync state" path: warn and proceed, the user's intent (files
+    // on disk) was honored.
+  }
+
   if (flags.json) {
     stdout.write(
       JSON.stringify({