skillrepo 4.3.0 → 4.5.0

package/src/lib/drift.mjs

@@ -0,0 +1,175 @@
+/**
+ * Per-skill drift classification (#1555 — `list` local-awareness).
+ *
+ * Pure functions for deciding "is this skill current, stale, missing,
+ * or edited?" given the three input axes:
+ *
+ *   1. **Library state** — version from `GET /api/v1/library`.
+ *   2. **Last-sync baseline** — version + content SHAs persisted by
+ *      `runSync` to `~/.claude/skillrepo/.last-sync` (v2 schema).
+ *   3. **On-disk presence** — { present, skillMdSha256, filesSha256 }
+ *      from walking the vendor's placement directory.
+ *
+ * No I/O, no clock, no env reads. Same input → same output. This is
+ * the layer that gets exhaustive unit tests; the file-system walker
+ * and the `list` renderer compose this with their own concerns.
+ */
+
+import semver from "semver";
+
+/**
+ * Per-vendor placement state. The four values cover the
+ * "where is this skill, and is it the right version" question. A
+ * fifth state, `extra` (on disk but not in the library), lives in
+ * the renderer because it depends on the library shape, not just
+ * the per-skill comparison here.
+ */
+export const SKILL_STATE = Object.freeze({
+  CURRENT: "current",
+  STALE: "stale",
+  MISSING: "missing",
+  EDITED: "edited",
+});
+
+/**
+ * Compute the placement-level state for a single (skill, vendor) pair.
+ *
+ * Decision order — first match wins:
+ *
+ *   1. **No on-disk presence** → `missing`. The vendor's placement
+ *      directory does not contain this skill.
+ *   2. **No last-sync baseline** → `missing`. We can't verify
+ *      anything without the SHA from the prior sync. Even if the
+ *      directory exists, treating it as `current` would lie about
+ *      drift we cannot detect. The user's resolution is the same as
+ *      true `missing`: run `skillrepo update` to establish a
+ *      baseline. This matches the spec's "fresh install → missing
+ *      everywhere" behavior.
+ *   3. **Library version newer than synced version** → `stale`. The
+ *      registry has moved on; the user is behind.
+ *   4. **Either SHA differs from baseline** → `edited`. Same
+ *      version, content drifted. The user (or an agent) touched the
+ *      files on disk after the last sync.
+ *   5. **Otherwise** → `current`.
+ *
+ * Semver comparison falls back to strict string equality when either
+ * value is not a valid semver. The fallback's effect: any non-semver
+ * mismatch is treated as `stale` (the user is "behind" some
+ * unparseable label). Pre-existing test fixtures (`"1.0.0"`,
+ * `"2.0.1"`) all parse; this branch exists for forward-compat with
+ * versioning schemes the registry may adopt later.
+ *
+ * @param {Object} input
+ * @param {string | null} input.libraryVersion
+ *   The current version per the library response, or null if the
+ *   library entry has no version yet (shouldn't happen in production
+ *   but the type allows it).
+ * @param {{ version: string, skillMdSha256: string, filesSha256: string } | null} input.lastSyncEntry
+ *   Persisted state from the last successful sync, or null if no
+ *   baseline exists for this skill.
+ * @param {{ present: boolean, skillMdSha256: string | null, filesSha256: string | null } | null} input.localPlacement
+ *   Disk presence at one vendor's placement target. `present: false`
+ *   means the directory is absent; non-null SHAs imply `present:
+ *   true`.
+ * @returns {"current" | "stale" | "missing" | "edited"}
+ */
+export function computeSkillState({ libraryVersion, lastSyncEntry, localPlacement }) {
+  if (!localPlacement || !localPlacement.present) {
+    return SKILL_STATE.MISSING;
+  }
+  if (!lastSyncEntry) {
+    // On-disk but no baseline → cannot verify. Spec choice: report
+    // missing rather than fabricating a "current" verdict. See the
+    // docstring's decision-order comment.
+    return SKILL_STATE.MISSING;
+  }
+
+  if (libraryVersionIsNewer(libraryVersion, lastSyncEntry.version)) {
+    return SKILL_STATE.STALE;
+  }
+
+  const skillMdMatches =
+    localPlacement.skillMdSha256 !== null &&
+    localPlacement.skillMdSha256 === lastSyncEntry.skillMdSha256;
+  const filesMatch =
+    localPlacement.filesSha256 !== null &&
+    localPlacement.filesSha256 === lastSyncEntry.filesSha256;
+
+  if (skillMdMatches && filesMatch) return SKILL_STATE.CURRENT;
+  return SKILL_STATE.EDITED;
+}
+
+/**
+ * Reduce per-vendor states for a single skill to a single
+ * worst-state-wins value for the `Local` column in `list`'s table
+ * and the top-level `state` in `--json`.
+ *
+ * Precedence (high → low severity):
+ *   missing > edited > stale > current
+ *
+ * Reasoning: the user's action depends on the worst state.
+ *   - `missing` requires `skillrepo update` to populate the placement.
+ *   - `edited` requires user judgement (keep edits? overwrite?).
+ *   - `stale` requires `skillrepo update` to fetch the new version.
+ *   - `current` requires nothing.
+ *
+ * Edited ranks above stale because the user is more likely to lose
+ * work on `edited` (overwrite by sync). Missing ranks above edited
+ * because the missing placement is the most immediately broken.
+ *
+ * An empty input array returns `missing` — there are no detected
+ * vendors to check against, so we can't claim anything is current.
+ * Callers that have a true "no vendors detected" case usually
+ * short-circuit before getting here, but the safe fallback is the
+ * conservative one.
+ *
+ * @param {ReadonlyArray<"current" | "stale" | "missing" | "edited">} perVendorStates
+ * @returns {"current" | "stale" | "missing" | "edited"}
+ */
+export function rollupState(perVendorStates) {
+  if (!Array.isArray(perVendorStates) || perVendorStates.length === 0) {
+    return SKILL_STATE.MISSING;
+  }
+  const order = [
+    SKILL_STATE.MISSING,
+    SKILL_STATE.EDITED,
+    SKILL_STATE.STALE,
+    SKILL_STATE.CURRENT,
+  ];
+  for (const s of order) {
+    if (perVendorStates.includes(s)) return s;
+  }
+  // Defensive fallback for an array containing an unknown enum value.
+  // Treating it as the worst case (missing) is the conservative
+  // choice — it tells the user "something's off, run update" rather
+  // than silently rendering as current.
+  return SKILL_STATE.MISSING;
+}
+
+/**
+ * Strict semver `>` with a string-fallback escape hatch.
+ *
+ * `semver.gt` throws on invalid versions; we wrap with `semver.valid`
+ * to avoid the throw. When EITHER side is not valid semver, fall
+ * back to a plain string inequality — any difference is treated as
+ * the library being "ahead," which classifies the skill as `stale`.
+ * This is the right safety direction: false-stale tells the user to
+ * run `update`, which is harmless; false-current would mask drift.
+ *
+ * @param {string | null} libraryVersion
+ * @param {string | null} syncedVersion
+ * @returns {boolean}
+ */
+function libraryVersionIsNewer(libraryVersion, syncedVersion) {
+  if (typeof libraryVersion !== "string" || libraryVersion === "") return false;
+  if (typeof syncedVersion !== "string" || syncedVersion === "") {
+    // No baseline version → we can't decide ordering. Caller treats
+    // this as "version comparison inconclusive" and continues to
+    // the SHA check.
+    return false;
+  }
+  if (semver.valid(libraryVersion) && semver.valid(syncedVersion)) {
+    return semver.gt(libraryVersion, syncedVersion);
+  }
+  return libraryVersion !== syncedVersion;
+}

package/src/lib/file-write.mjs

@@ -227,10 +227,25 @@ export function describePlacementTarget(target) {
   }
 }
 
+/**
+ * Resolve the parent directory for a `PlacementTarget` — the dir
+ * that contains all skill subdirectories for this target. Exposed so
+ * read-side consumers (`placement-walk.mjs` for `list`'s drift
+ * detection in #1555) can enumerate skill placements without
+ * duplicating the target→root mapping that already lives here.
+ *
+ * @param {PlacementTarget} target
+ * @returns {string}
+ */
+export function resolvePlacementRoot(target) {
+  return placementRootFn(target)();
+}
+
 /**
  * Map a `PlacementTarget` to its parent root resolver. Used by
  * `cleanupOrphans` to know which directories to scan for `.tmp`/`.old`
- * siblings.
+ * siblings, and by `resolvePlacementRoot` above for read-side
+ * consumers.
  *
  * @param {PlacementTarget} target
  * @returns {() => string}

package/src/lib/npm-update-check.mjs

@@ -0,0 +1,366 @@
+/**
+ * npm-registry self-staleness checker (#1554, part of epic #1552).
+ *
+ * The CLI ships with no self-staleness detection today. This module adds
+ * a daily-cached check against `https://registry.npmjs.org/skillrepo/latest`
+ * so a stale `npx skillrepo`/global install gets nudged toward an upgrade
+ * after the primary command completes. The nudge is a HINT, not a feature:
+ * every failure mode (network error, non-2xx, parse failure, timeout,
+ * read-only FS) returns null and never throws.
+ *
+ * Design contract
+ * ---------------
+ *
+ * 1. **Fire-and-forget at the call site.** `bin/skillrepo.mjs` invokes
+ *    this module after `await COMMANDS[command].run(rest)` returns and
+ *    races the promise with `setTimeout(0)`. On a cache HIT the checker
+ *    resolves before the timer fires and the nudge is emitted before
+ *    the binary exits. On a cache MISS the timer wins and the in-flight
+ *    fetch is left running in the background — it has its own 2s
+ *    timeout, writes the cache on completion, and lets the NEXT
+ *    invocation use it. The user's command output appears before the
+ *    process exits; the residual fetch happens in parallel.
+ *
+ * 2. **Silent failure mode.** No "couldn't reach npm." Users opening a
+ *    Network tab to debug a CLI command don't want a second unrelated
+ *    request explained. If the check can't complete, the user sees no
+ *    artifact at all.
+ *
+ * 3. **24h positive cache, 1h negative cache.** A successful read pins
+ *    the answer for 24 hours — npm publishes are rare enough that more
+ *    frequent polling is just rude. A failed read pins for 1 hour so a
+ *    transient outage doesn't blind the CLI for a full day; AND
+ *    `checkedAt` still updates on failure so we don't hammer a broken
+ *    endpoint every command in the meantime.
+ *
+ * 4. **Kill switches.** `SKILLREPO_NO_UPDATE_CHECK=1` is the explicit
+ *    opt-out. `process.env.CI === "true"` auto-disables (GitHub Actions,
+ *    GitLab CI, CircleCI, and most other vendors set this). Both are
+ *    checked before any network or cache I/O.
+ *
+ * 5. **JSON suppression at the binary level.** The checker itself does
+ *    NOT inspect `argv` for `--json`; that's the dispatcher's job.
+ *    When a parent command was invoked with `--json`, the dispatcher
+ *    skips calling `checkForCliUpdate` entirely so we never inject text
+ *    into a structured stream — not even on stderr, because some tools
+ *    (notably ts-node + Vitest hooks) read both streams.
+ *
+ * 6. **Live version comparison on the read path.** The cache records
+ *    `currentCliVersion` so a stale cache from a previous binary
+ *    doesn't keep nudging the user after they upgrade. The render-time
+ *    comparison is `latestPublishedVersion` vs. the LIVE version
+ *    (`io.currentVersion`), not the cached one — the cached value is
+ *    only used to validate freshness.
+ *
+ * 7. **Windows compat.** All paths use `path.join`; never separator
+ *    concatenation. The cache directory is created with
+ *    `mkdir { recursive: true }` so Windows drive-letter roots work
+ *    identically to POSIX `~/.claude/...`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import semver from "semver";
+
+import { globalNpmVersionCheckPath } from "./paths.mjs";
+
+/** Endpoint that resolves npm's `dist-tags.latest` for `skillrepo`. */
+export const NPM_LATEST_URL = "https://registry.npmjs.org/skillrepo/latest";
+
+/** Hard cap on the fetch. Network calls slower than this are treated as a no-result. */
+export const FETCH_TIMEOUT_MS = 2000;
+
+/** Cache TTL on a successful fetch (24 hours). */
+export const POSITIVE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Cache TTL on a failed fetch (1 hour) — fast retry without hammering. */
+export const NEGATIVE_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Cache file location — delegated to `paths.mjs` so every CLI-written
+ * path lives in a single registry. Tests inject via `sandbox-home.mjs`
+ * (which sets both HOME and USERPROFILE so `homedir()` reads sandbox
+ * locations on POSIX AND Windows), not by mocking this function.
+ *
+ * Kept as a re-export rather than a direct import in callers so the
+ * test boundary stays consistent with the module's other public API.
+ */
+export function cachePath() {
+  return globalNpmVersionCheckPath();
+}
+
+/** Current cache schema. Bump only when fields change incompatibly. */
+export const CACHE_SCHEMA_VERSION = 1;
+
+/**
+ * Try to read and parse the cache file. Returns null on any failure
+ * (missing file, malformed JSON, wrong schemaVersion, missing required
+ * field). The caller treats null as "cache miss" and proceeds to fetch.
+ *
+ * This intentionally does NOT differentiate between "no cache yet" and
+ * "cache exists but is unusable" — both lead to the same recovery path.
+ */
+function readCache() {
+  let raw;
+  try {
+    raw = readFileSync(cachePath(), "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+  if (parsed.schemaVersion !== CACHE_SCHEMA_VERSION) return null;
+  if (typeof parsed.checkedAt !== "string") return null;
+  if (typeof parsed.currentCliVersion !== "string") return null;
+  if (typeof parsed.fetchOk !== "boolean") return null;
+  // latestPublishedVersion may be null when fetchOk: false; both shapes
+  // are valid cache entries.
+  if (
+    parsed.latestPublishedVersion !== null &&
+    typeof parsed.latestPublishedVersion !== "string"
+  ) {
+    return null;
+  }
+
+  return parsed;
+}
+
+/**
+ * Persist the cache. Best-effort: read-only filesystems (Docker layers,
+ * some CI snapshots) cause writeFileSync to throw EROFS/EACCES, which
+ * we swallow. The user still sees the nudge on this run (if applicable);
+ * they just won't get a cached answer next time.
+ */
+function writeCache(entry, io) {
+  const target = cachePath();
+  const dir = dirname(target);
+  const writeFn = io.writeFile;
+  const mkdirFn = io.mkdir;
+  const existsFn = io.exists;
+
+  try {
+    if (!existsFn(dir)) {
+      mkdirFn(dir, { recursive: true });
+    }
+    writeFn(target, JSON.stringify(entry, null, 2) + "\n", "utf-8");
+  } catch {
+    // Read-only FS or permission denied — silently give up. The user's
+    // primary command output already showed; we will not interrupt it
+    // with a cache-write warning. Next invocation will re-fetch.
+  }
+}
+
+/**
+ * Decide whether a cache entry is still fresh given the CURRENT live
+ * version. Two gates must pass:
+ *
+ *   1. The cache must have been written by the same CLI version that's
+ *      running now. If the user upgraded between calls, the cached
+ *      `latestPublishedVersion` may now be the version they're running
+ *      — discarding the entry forces a re-check so we don't nudge the
+ *      user to upgrade to the same version they just installed.
+ *   2. `checkedAt` must be within the appropriate TTL — positive for
+ *      successful fetches, negative for failed ones.
+ *
+ * Returns true when the cache is reusable; false means re-fetch.
+ */
+function isCacheFresh(entry, currentVersion, now) {
+  if (entry.currentCliVersion !== currentVersion) return false;
+  const checkedAtMs = Date.parse(entry.checkedAt);
+  if (!Number.isFinite(checkedAtMs)) return false;
+  const ageMs = now - checkedAtMs;
+  const ttl = entry.fetchOk ? POSITIVE_TTL_MS : NEGATIVE_TTL_MS;
+  return ageMs < ttl && ageMs >= 0;
+}
+
+/**
+ * Fetch `/skillrepo/latest` from the npm registry with a 2-second hard
+ * timeout. Returns the parsed `version` string on success, null on any
+ * failure (network, non-2xx, parse, abort).
+ *
+ * The `/latest` shortcut returns the version manifest for `dist-tags.latest`
+ * — about 1.5 KB on the wire. The User-Agent identifies the CLI so npm's
+ * abuse tooling can rate-limit us specifically if we ever misbehave.
+ *
+ * Accept header note: the issue spec called for
+ * `application/vnd.npm.install-v1+json`, but the npm registry returns
+ * HTTP 406 for that media type on the `/latest` endpoint — the install
+ * manifest type is only valid against the FULL packument
+ * (`/skillrepo`), which is ~10x larger. `application/json` is the
+ * documented accept for the `/latest` shortcut and is what `npm view`
+ * itself uses under the hood. Verified via curl on 2026-05-19. The
+ * issue body should be updated to reflect this; tracked in the PR.
+ */
+async function fetchLatestVersion(currentVersion, fetchImpl) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(NPM_LATEST_URL, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": `skillrepo-cli/${currentVersion} (+https://skillrepo.dev)`,
+      },
+      signal: controller.signal,
+    });
+    if (!res || !res.ok) return null;
+    let body;
+    try {
+      body = await res.json();
+    } catch {
+      return null;
+    }
+    if (!body || typeof body !== "object") return null;
+    if (typeof body.version !== "string" || body.version.length === 0) {
+      return null;
+    }
+    // Validate semver shape upfront — a malformed version from a
+    // compromised mirror should not surface to the user as a nudge.
+    if (!semver.valid(body.version)) return null;
+    return body.version;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Style helpers — duplicated from bin/skillrepo.mjs to keep this module
+ * standalone (a CLI nudge module that pulls in the dispatcher's helpers
+ * would create a cycle). `bold`/`dim` mirror the existing http.mjs:248
+ * pattern.
+ */
+function dim(s) {
+  return process.stderr.isTTY && !process.env.NO_COLOR ? `\x1b[2m${s}\x1b[0m` : s;
+}
+function bold(s) {
+  return process.stderr.isTTY && !process.env.NO_COLOR ? `\x1b[1m${s}\x1b[0m` : s;
+}
+
+/**
+ * Render the nudge to stderr. Two lines, indented to match the
+ * dispatcher's error/help shape. Never throws — if stderr is closed
+ * (e.g. parent pipe shut down) the write call's exception is swallowed
+ * at the call site so a failing nudge can't break the user's flow.
+ */
+function emitNudge(currentVersion, latestVersion, stderrWrite) {
+  const line1 = dim(
+    `  A newer ${bold("skillrepo")} is available: ${currentVersion} → ${latestVersion}`,
+  );
+  const line2 = dim(`  Upgrade: ${bold("npm install -g skillrepo@latest")}`);
+  try {
+    stderrWrite(`\n${line1}\n${line2}\n`);
+  } catch {
+    // Closed stream. Nothing to do.
+  }
+}
+
+/**
+ * Are the kill switches set? Centralized so the bin layer and any
+ * test fixtures share the same view of "should we even bother."
+ */
+export function updateCheckDisabledByEnv() {
+  const explicit = process.env.SKILLREPO_NO_UPDATE_CHECK;
+  if (explicit && explicit !== "0" && explicit.toLowerCase() !== "false") {
+    return true;
+  }
+  if (process.env.CI === "true") return true;
+  return false;
+}
+
+/**
+ * Main entry point.
+ *
+ * @param {object} params
+ * @param {string} params.currentVersion - The CLI's own version
+ *   (`getCliVersion()` from the dispatcher).
+ * @param {object} [params.io] - I/O dependency injection. Production
+ *   callers pass nothing and get Node built-ins; tests inject mocks.
+ *   Shape:
+ *   - `fetch`: fetch impl (default `globalThis.fetch`)
+ *   - `now`: () => number, ms since epoch (default `Date.now`)
+ *   - `writeFile`/`mkdir`/`exists`: fs primitives for the cache write
+ *     path. Reads use real `fs` directly (no injection seam) — tests
+ *     redirect the read path via `sandbox-home.mjs` instead.
+ *     (defaults from `node:fs`)
+ *   - `stderrWrite`: (s) => void (default `process.stderr.write`)
+ *
+ * @returns {Promise<{ nudged: boolean, reason?: string }>} Resolves
+ *   with a tiny status object — tests assert on it directly. Production
+ *   callers ignore the return value.
+ */
+export async function checkForCliUpdate({ currentVersion, io = {} } = {}) {
+  if (updateCheckDisabledByEnv()) {
+    return { nudged: false, reason: "disabled" };
+  }
+  if (typeof currentVersion !== "string" || !semver.valid(currentVersion)) {
+    // Defensive: a malformed live version is a programming error
+    // upstream. Don't try to compare against random strings.
+    return { nudged: false, reason: "invalid-current-version" };
+  }
+
+  const resolvedIo = {
+    fetch: io.fetch ?? globalThis.fetch,
+    now: io.now ?? Date.now,
+    writeFile: io.writeFile ?? writeFileSync,
+    mkdir: io.mkdir ?? mkdirSync,
+    exists: io.exists ?? existsSync,
+    stderrWrite: io.stderrWrite ?? ((s) => process.stderr.write(s)),
+  };
+
+  if (typeof resolvedIo.fetch !== "function") {
+    // Node < 18 has no global fetch. The CLI's minimum is 18 (README),
+    // so this should never fire — but a missing fetch isn't a user-
+    // visible failure either.
+    return { nudged: false, reason: "no-fetch" };
+  }
+
+  const now = resolvedIo.now();
+  const cache = readCache();
+  let latestVersion = null;
+
+  if (cache && isCacheFresh(cache, currentVersion, now)) {
+    // Fresh cache. Reuse its latestPublishedVersion (which may be null
+    // for a negative cache hit — in which case we don't nudge).
+    latestVersion = cache.latestPublishedVersion;
+  } else {
+    // Cache miss / stale / version mismatch. Try the network. The
+    // fetch has its own 2-second AbortController; the dispatcher's
+    // `Promise.race` with `setTimeout(0)` means we return synchronously
+    // either way — but the fetch keeps running in the background so
+    // the cache lands and the NEXT invocation can use it.
+    latestVersion = await fetchLatestVersion(currentVersion, resolvedIo.fetch);
+    const entry = {
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now).toISOString(),
+      currentCliVersion: currentVersion,
+      latestPublishedVersion: latestVersion,
+      fetchOk: latestVersion !== null,
+    };
+    writeCache(entry, resolvedIo);
+  }
+
+  if (!latestVersion) {
+    return { nudged: false, reason: "no-result" };
+  }
+
+  // Compare against the LIVE current version, not the cached
+  // currentCliVersion. The cached value was only used to gate freshness;
+  // the user is running THIS binary now, and that's what they need a
+  // nudge relative to.
+  if (!semver.gt(latestVersion, currentVersion)) {
+    return { nudged: false, reason: "up-to-date" };
+  }
+
+  emitNudge(currentVersion, latestVersion, resolvedIo.stderrWrite);
+  return { nudged: true };
+}

package/src/lib/paths.mjs

@@ -28,6 +28,16 @@ export const vscodeMcpJson = () => join(cwd(), ".vscode", "mcp.json");
 export const globalConfigPath = () => join(homedir(), ".claude", "skillrepo", "config.json");
 export const globalLastSyncPath = () => join(homedir(), ".claude", "skillrepo", ".last-sync");
 
+/**
+ * npm-registry self-staleness check cache (#1554). Separate file from
+ * `.last-sync` — different concern (CLI's own version vs. library
+ * content state) and a schema bump in one must not gate the other.
+ * Lives under the same `~/.claude/skillrepo/` directory so cleanup
+ * stays simple (rm -rf the parent removes both).
+ */
+export const globalNpmVersionCheckPath = () =>
+  join(homedir(), ".claude", "skillrepo", ".npm-version-check");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This