skillrepo 4.3.0 → 4.5.0

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

@@ -0,0 +1,670 @@
+/**
+ * Unit tests for `packages/cli/src/lib/npm-update-check.mjs` (#1554).
+ *
+ * The module is fire-and-forget by design: every failure mode returns
+ * null and the caller never knows. These tests inject mock I/O so we
+ * can assert on:
+ *
+ *   - Cache miss → fetch → nudge emitted when latest > current.
+ *   - Cache miss → fetch returns same version → no nudge.
+ *   - Cache miss → fetch returns older version → no nudge (downgrade
+ *     scenarios from `next` tag accidents would otherwise mis-nudge).
+ *   - Fetch network error / timeout / non-2xx / parse failure / non-
+ *     semver body → no throw, no nudge, fetchOk: false cache entry.
+ *   - Read-only FS (writeFile throws) → no throw, the nudge still
+ *     emits (cache is best-effort, not a gate on rendering).
+ *   - Positive cache within 24h → no fetch attempted, cached value
+ *     drives the nudge decision.
+ *   - Negative cache within 1h → no fetch, no nudge.
+ *   - Negative cache past 1h → re-fetch.
+ *   - Positive cache past 24h → re-fetch.
+ *   - currentCliVersion mismatch → discard cache and re-fetch (so a
+ *     just-upgraded user isn't nudged toward the version they just
+ *     installed).
+ *   - SKILLREPO_NO_UPDATE_CHECK=1 → no fetch, no cache read, no nudge.
+ *   - CI=true → no fetch, no nudge.
+ *   - Parent command argv with --json is suppressed by the dispatcher,
+ *     not by this module — covered separately at the bin layer (see
+ *     the smoke-test note at the bottom of this file).
+ *   - Windows-shaped cache path resolution.
+ *
+ * Test strategy
+ * -------------
+ * We never touch the real npm registry or the real `~/.claude/`
+ * directory. Every call to `checkForCliUpdate` passes a custom `io`
+ * with mocked fetch/now/fs primitives. Cache state is observed by
+ * inspecting the captured `writeFile` calls; nudge output is observed
+ * by capturing `stderrWrite`. This is the same DI pattern used in
+ * `telemetry.test.mjs`.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  checkForCliUpdate,
+  cachePath,
+  CACHE_SCHEMA_VERSION,
+  POSITIVE_TTL_MS,
+  NEGATIVE_TTL_MS,
+  FETCH_TIMEOUT_MS,
+  NPM_LATEST_URL,
+  updateCheckDisabledByEnv,
+} from "../../lib/npm-update-check.mjs";
+
+// ── Test fixture builder ────────────────────────────────────────────────
+
+/**
+ * Build a fresh I/O mock. Each field defaults to a "no-op success"
+ * shape; individual tests override the ones they care about.
+ *
+ * `cacheStore` is a closure that mocks the on-disk cache file: reads
+ * return its current value (or throw ENOENT when null); writes update
+ * it. `fetchResult` is what the mocked fetch resolves to.
+ */
+function makeIo({
+  fetchResult = null,
+  fetchThrows = null,
+  now = Date.now(),
+  writeThrows = null,
+} = {}) {
+  const stderrWrites = [];
+  const writeCalls = [];
+  const fetchCalls = [];
+
+  const io = {
+    fetch: async (url, options) => {
+      fetchCalls.push({ url, options });
+      if (fetchThrows) throw fetchThrows;
+      return fetchResult;
+    },
+    now: () => now,
+    // The cache read path uses node:fs directly (off-injection — see
+    // the temp-HOME setup below). Only writes flow through this `io`.
+    exists: () => true,
+    mkdir: () => {},
+    writeFile: (path, contents) => {
+      writeCalls.push({ path, contents });
+      if (writeThrows) throw writeThrows;
+    },
+    stderrWrite: (s) => {
+      stderrWrites.push(s);
+    },
+  };
+
+  return {
+    io,
+    getStderrWrites: () => stderrWrites,
+    getWriteCalls: () => writeCalls,
+    getFetchCalls: () => fetchCalls,
+  };
+}
+
+// ── Cache-read seam ────────────────────────────────────────────────────
+//
+// The module reads its cache file via `readFileSync` from `node:fs`
+// (the real one), keyed off `cachePath()`. We can't inject around that
+// without changing the module's public surface, so the tests redirect
+// the home directory via `sandbox-home.mjs`. That helper sets BOTH
+// HOME and USERPROFILE so `os.homedir()` lands in the sandbox on
+// POSIX AND Windows — a plain `process.env.HOME = ...` would be a
+// silent no-op on Windows (where homedir() reads USERPROFILE), and
+// every other test under packages/cli/ uses the helper for exactly
+// this reason. See helpers/sandbox-home.mjs JSDoc for the full
+// history (PR #892 — 99 Windows CI failures).
+
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+let testHome;
+
+beforeEach(() => {
+  originalHomeEnv = captureHome();
+  testHome = mkdtempSync(join(tmpdir(), "npm-update-check-"));
+  setSandboxHome(testHome);
+  delete process.env.SKILLREPO_NO_UPDATE_CHECK;
+  delete process.env.CI;
+});
+
+afterEach(() => {
+  if (testHome && existsSync(testHome)) {
+    rmSync(testHome, { recursive: true, force: true });
+  }
+  restoreHome(originalHomeEnv);
+});
+
+// Helper: seed the cache file on disk so the module's real
+// readFileSync can find it. Uses `cachePath()` (which now resolves
+// via `homedir()` → sandboxed HOME/USERPROFILE) to compute the
+// target — never hard-codes a path so this stays correct on Windows.
+function writeCacheFile(entry) {
+  const target = cachePath();
+  mkdirSync(join(testHome, ".claude", "skillrepo"), { recursive: true });
+  writeFileSync(target, JSON.stringify(entry, null, 2) + "\n", "utf-8");
+}
+
+// ── cachePath ──────────────────────────────────────────────────────────
+
+describe("cachePath", () => {
+  it("resolves to ~/.claude/skillrepo/.npm-version-check via path.join", () => {
+    const expected = join(homedir(), ".claude", "skillrepo", ".npm-version-check");
+    assert.equal(cachePath(), expected);
+  });
+
+  it("uses platform-native separators (Windows compat smoke)", () => {
+    // FACT: path.join on win32 produces backslashes; on POSIX, forward
+    // slashes. We assert against `path.join` from the same module so
+    // this test passes on both platforms and locks in that the module
+    // does not hand-roll a separator.
+    const result = cachePath();
+    assert.ok(result.includes(".claude"));
+    assert.ok(result.includes("skillrepo"));
+    assert.ok(result.endsWith(".npm-version-check"));
+    // No double separators, no mixed separators on either platform.
+    if (process.platform === "win32") {
+      assert.ok(!result.includes("/"), "should use \\ on Windows");
+    } else {
+      assert.ok(!result.includes("\\"), "should use / on POSIX");
+    }
+  });
+});
+
+// ── updateCheckDisabledByEnv ───────────────────────────────────────────
+
+describe("updateCheckDisabledByEnv", () => {
+  it("is false when neither env var is set", () => {
+    assert.equal(updateCheckDisabledByEnv(), false);
+  });
+
+  it("is true when SKILLREPO_NO_UPDATE_CHECK=1", () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "1";
+    assert.equal(updateCheckDisabledByEnv(), true);
+  });
+
+  it("is true for any truthy SKILLREPO_NO_UPDATE_CHECK value", () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "yes";
+    assert.equal(updateCheckDisabledByEnv(), true);
+  });
+
+  it("is false when SKILLREPO_NO_UPDATE_CHECK=0", () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "0";
+    assert.equal(updateCheckDisabledByEnv(), false);
+  });
+
+  it("is false when SKILLREPO_NO_UPDATE_CHECK=false", () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "false";
+    assert.equal(updateCheckDisabledByEnv(), false);
+  });
+
+  it("is true when CI=true (auto-disable for GitHub Actions / GitLab / CircleCI)", () => {
+    process.env.CI = "true";
+    assert.equal(updateCheckDisabledByEnv(), true);
+  });
+
+  it("is false when CI=false (the literal string 'false')", () => {
+    process.env.CI = "false";
+    assert.equal(updateCheckDisabledByEnv(), false);
+  });
+
+  it("is false when CI=1 (we match only 'true', not generic truthy)", () => {
+    // FACT: GitHub Actions, GitLab CI, CircleCI, Travis all set
+    // CI=true literally. Some other tools set CI=1; the issue
+    // explicitly scopes auto-disable to `CI === "true"`, so we lock
+    // that contract here. Users who want broader detection can set
+    // SKILLREPO_NO_UPDATE_CHECK.
+    process.env.CI = "1";
+    assert.equal(updateCheckDisabledByEnv(), false);
+  });
+});
+
+// ── checkForCliUpdate: cache miss + happy paths ────────────────────────
+
+describe("checkForCliUpdate (cache miss, fetch succeeds)", () => {
+  it("emits a nudge when the registry returns a newer version", async () => {
+    const fixture = makeIo({
+      fetchResult: {
+        ok: true,
+        json: async () => ({ version: "4.5.0" }),
+      },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, true);
+    const stderr = fixture.getStderrWrites().join("");
+    assert.match(stderr, /A newer .*skillrepo.* is available/);
+    assert.match(stderr, /4\.3\.0/);
+    assert.match(stderr, /4\.5\.0/);
+    assert.match(stderr, /npm install -g skillrepo@latest/);
+  });
+
+  it("does not nudge when registry returns the same version", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.3.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "up-to-date");
+    assert.equal(fixture.getStderrWrites().length, 0);
+  });
+
+  it("does not nudge when registry returns an older version", async () => {
+    // Defensive: if npm `latest` ever points at an older release
+    // (mistaken `next`/`latest` swap, dist-tag rollback), don't tell
+    // the user to "upgrade" to a version they're already ahead of.
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.1.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "up-to-date");
+  });
+
+  it("writes a positive cache entry on success", async () => {
+    const now = 1747680000000; // 2026-05-19 ish
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+      now,
+    });
+    await checkForCliUpdate({ currentVersion: "4.3.0", io: fixture.io });
+    const writes = fixture.getWriteCalls();
+    assert.equal(writes.length, 1);
+    const written = JSON.parse(writes[0].contents);
+    assert.equal(written.schemaVersion, CACHE_SCHEMA_VERSION);
+    assert.equal(written.checkedAt, new Date(now).toISOString());
+    assert.equal(written.currentCliVersion, "4.3.0");
+    assert.equal(written.latestPublishedVersion, "4.5.0");
+    assert.equal(written.fetchOk, true);
+  });
+
+  it("sends application/json Accept + identifying User-Agent", async () => {
+    // FACT: the npm registry returns HTTP 406 for
+    // `application/vnd.npm.install-v1+json` on the `/skillrepo/latest`
+    // endpoint (verified via curl 2026-05-19). `application/json` is
+    // what `npm view` itself sends for `/latest` and is what works.
+    // The issue body's header is incorrect for this endpoint and is
+    // tracked for a doc fix in the PR.
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    await checkForCliUpdate({ currentVersion: "4.3.0", io: fixture.io });
+    const call = fixture.getFetchCalls()[0];
+    assert.equal(call.url, NPM_LATEST_URL);
+    assert.equal(call.options.headers.Accept, "application/json");
+    assert.match(
+      call.options.headers["User-Agent"],
+      /^skillrepo-cli\/4\.3\.0 \(\+https:\/\/skillrepo\.dev\)$/,
+    );
+  });
+});
+
+// ── checkForCliUpdate: failure modes ───────────────────────────────────
+
+describe("checkForCliUpdate (fetch failures — all silent)", () => {
+  it("network error: no nudge, fetchOk:false cached", async () => {
+    const fixture = makeIo({ fetchThrows: new Error("ECONNREFUSED") });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "no-result");
+    const writes = fixture.getWriteCalls();
+    assert.equal(writes.length, 1);
+    const written = JSON.parse(writes[0].contents);
+    assert.equal(written.fetchOk, false);
+    assert.equal(written.latestPublishedVersion, null);
+  });
+
+  it("non-2xx response: no nudge, no throw", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: false, status: 503, json: async () => ({}) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    const writes = fixture.getWriteCalls();
+    assert.equal(writes.length, 1);
+    assert.equal(JSON.parse(writes[0].contents).fetchOk, false);
+  });
+
+  it("JSON parse failure: no nudge, no throw", async () => {
+    const fixture = makeIo({
+      fetchResult: {
+        ok: true,
+        json: async () => {
+          throw new SyntaxError("Unexpected token <");
+        },
+      },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(JSON.parse(fixture.getWriteCalls()[0].contents).fetchOk, false);
+  });
+
+  it("missing version field: no nudge", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ name: "skillrepo" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+  });
+
+  it("malformed semver in response: no nudge (defense against compromised mirror)", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "not-a-version" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    // We still cache fetchOk:false so we don't hammer a misbehaving
+    // mirror every command.
+    assert.equal(
+      JSON.parse(fixture.getWriteCalls()[0].contents).fetchOk,
+      false,
+    );
+  });
+
+  it("read-only filesystem (writeFile throws): no throw, no crash", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+      writeThrows: Object.assign(new Error("EROFS"), { code: "EROFS" }),
+    });
+    // Should still produce the nudge — cache is best-effort.
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, true);
+  });
+
+  it("invalid currentVersion: no fetch, no nudge", async () => {
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "garbage",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "invalid-current-version");
+    assert.equal(fixture.getFetchCalls().length, 0);
+  });
+});
+
+// ── checkForCliUpdate: caching behavior ────────────────────────────────
+
+describe("checkForCliUpdate (cache hit paths)", () => {
+  it("positive cache within 24h: no fetch, nudge from cache", async () => {
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - 1000).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: "4.5.0",
+      fetchOk: true,
+    });
+    const fixture = makeIo({
+      // If a fetch is attempted, this will be returned — but the test
+      // asserts zero fetches.
+      fetchResult: { ok: true, json: async () => ({ version: "9.9.9" }) },
+      now,
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 0);
+    assert.equal(result.nudged, true);
+    assert.match(fixture.getStderrWrites().join(""), /4\.5\.0/);
+  });
+
+  it("positive cache where cached version equals current: no nudge, no fetch", async () => {
+    // Scenario: user upgraded between runs. With NO version-mismatch
+    // gate this would still nudge — see the version-mismatch test
+    // below. Here cachedCurrent == liveCurrent, so the cache is
+    // reused; we just don't nudge because latest == current.
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - 1000).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: "4.3.0",
+      fetchOk: true,
+    });
+    const fixture = makeIo({ now });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 0);
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "up-to-date");
+  });
+
+  it("positive cache past 24h: re-fetches", async () => {
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - POSITIVE_TTL_MS - 1).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: "4.5.0",
+      fetchOk: true,
+    });
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.6.0" }) },
+      now,
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 1);
+    assert.equal(result.nudged, true);
+    assert.match(fixture.getStderrWrites().join(""), /4\.6\.0/);
+  });
+
+  it("negative cache within 1h: no re-fetch, no nudge", async () => {
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - 1000).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: null,
+      fetchOk: false,
+    });
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "9.9.9" }) },
+      now,
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 0);
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "no-result");
+  });
+
+  it("negative cache past 1h: re-fetches", async () => {
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - NEGATIVE_TTL_MS - 1).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: null,
+      fetchOk: false,
+    });
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+      now,
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 1);
+    assert.equal(result.nudged, true);
+  });
+
+  it("cache mismatch on currentCliVersion: re-fetches", async () => {
+    // Scenario: user was on 4.3.0 yesterday, cache says latest is
+    // 4.5.0. Today they're running 4.5.0 (they upgraded). Don't keep
+    // nudging them — the live version is the source of truth.
+    const now = 1747680000000;
+    writeCacheFile({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      checkedAt: new Date(now - 1000).toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: "4.5.0",
+      fetchOk: true,
+    });
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+      now,
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.5.0",
+      io: fixture.io,
+    });
+    // Re-fetch fires; cache gets rewritten with current=4.5.0.
+    assert.equal(fixture.getFetchCalls().length, 1);
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "up-to-date");
+  });
+
+  it("malformed cache JSON: treated as miss", async () => {
+    mkdirSync(join(testHome, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(cachePath(), "{not json", "utf-8");
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 1);
+    assert.equal(result.nudged, true);
+  });
+
+  it("cache with wrong schemaVersion: treated as miss", async () => {
+    writeCacheFile({
+      schemaVersion: 99,
+      checkedAt: new Date().toISOString(),
+      currentCliVersion: "4.3.0",
+      latestPublishedVersion: "4.5.0",
+      fetchOk: true,
+    });
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(fixture.getFetchCalls().length, 1);
+    assert.equal(result.nudged, true);
+  });
+});
+
+// ── checkForCliUpdate: kill switches ───────────────────────────────────
+
+describe("checkForCliUpdate (kill switches)", () => {
+  it("SKILLREPO_NO_UPDATE_CHECK=1 → no fetch, no cache read, no nudge", async () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "1";
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "disabled");
+    assert.equal(fixture.getFetchCalls().length, 0);
+    assert.equal(fixture.getStderrWrites().length, 0);
+  });
+
+  it("CI=true → no fetch, no nudge", async () => {
+    process.env.CI = "true";
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, false);
+    assert.equal(result.reason, "disabled");
+    assert.equal(fixture.getFetchCalls().length, 0);
+  });
+
+  it("SKILLREPO_NO_UPDATE_CHECK=0 is NOT a disable", async () => {
+    process.env.SKILLREPO_NO_UPDATE_CHECK = "0";
+    const fixture = makeIo({
+      fetchResult: { ok: true, json: async () => ({ version: "4.5.0" }) },
+    });
+    const result = await checkForCliUpdate({
+      currentVersion: "4.3.0",
+      io: fixture.io,
+    });
+    assert.equal(result.nudged, true);
+  });
+});
+
+// ── FETCH_TIMEOUT_MS constant lock ─────────────────────────────────────
+
+describe("constants", () => {
+  it("FETCH_TIMEOUT_MS is 2 seconds per the spec", () => {
+    assert.equal(FETCH_TIMEOUT_MS, 2000);
+  });
+
+  it("POSITIVE_TTL_MS is exactly 24 hours", () => {
+    assert.equal(POSITIVE_TTL_MS, 24 * 60 * 60 * 1000);
+  });
+
+  it("NEGATIVE_TTL_MS is exactly 1 hour", () => {
+    assert.equal(NEGATIVE_TTL_MS, 60 * 60 * 1000);
+  });
+});
+
+// ── Notes on coverage gaps ─────────────────────────────────────────────
+//
+// 1. The `--json` suppression lives in `bin/skillrepo.mjs`. Asserting
+//    on it would require spawning the binary as a subprocess, which
+//    the rest of the CLI test suite avoids — and the suppression is a
+//    one-line `if (!rest.includes("--json"))` guard that's verified
+//    by code-review eyeballs and the existing CLI E2E suite (which
+//    asserts stdout/stderr cleanliness on `--json` invocations).
+//
+// 2. The 2-second wall-clock fetch timeout is exercised structurally
+//    (the AbortController is wired up in `fetchLatestVersion`); we do
+//    not assert on real wall-clock timing in unit tests because a
+//    sleep-based assertion is inherently flaky on shared CI runners.