skillrepo 4.8.3 → 4.9.0

package/src/test/lib/sync.test.mjs

@@ -44,6 +44,7 @@ import {
   cliVersionBelowFloor,
   FULL_RESYNC_FLOOR,
   LAST_SYNC_SCHEMA_VERSION,
+  MIN_SYNC_INTERVAL_MS,
 } from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
@@ -124,11 +125,11 @@ describe("readLastSync / writeLastSync", () => {
     assert.equal(result.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
   });
 
-  it("writes v2 schema (LAST_SYNC_SCHEMA_VERSION === 2)", () => {
-    // Locks the constant so a future bump back to 1, or accidental
-    // change, fails loudly. The whole epic depends on v2 being the
-    // current schema and v1 files producing null (full-sync trigger).
-    assert.equal(LAST_SYNC_SCHEMA_VERSION, 2);
+  it("writes v3 schema (LAST_SYNC_SCHEMA_VERSION === 3)", () => {
+    // Locks the constant so an accidental change fails loudly. #2174
+    // bumped it 2 → 3 (adds `lastAttemptAt`). v1 files migrate in-memory,
+    // v2 files are accepted in place, unknown future versions read null.
+    assert.equal(LAST_SYNC_SCHEMA_VERSION, 3);
   });
 
   it("persists an empty skills map by default", () => {
@@ -164,7 +165,7 @@ describe("readLastSync / writeLastSync", () => {
     assert.deepEqual(result.skills, skills);
   });
 
-  it("an old v1 file migrates in-memory to a v2 shape with empty skills", () => {
+  it("an old v1 file migrates in-memory to the current-schema shape with empty skills", () => {
     // Backward compat: a user upgrading from a v1-era CLI to v2 still
     // has a v1 `.last-sync` on disk. Returning null would force a
     // full sync on every command (the etag is lost), which is
@@ -235,9 +236,9 @@ describe("readLastSync / writeLastSync", () => {
   });
 
   it("a file with an unknown schemaVersion still reads as null", () => {
-    // Forward compat: a v3 or v999 file (from a newer CLI we don't
-    // understand) reads as null, triggering a full sync. We only
-    // migrate KNOWN older shapes, not arbitrary unknown ones.
+    // Forward compat: a v4 or v999 file (from a newer CLI we don't
+    // understand) reads as null, triggering a full sync. We only accept
+    // KNOWN shapes (v1 migrate, v2/v3 in place), not arbitrary unknown ones.
     mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
     writeFileSync(
       globalLastSyncPath(),
@@ -2046,3 +2047,490 @@ describe("placementsAreComplete — direct unit coverage", () => {
     assert.equal(placementsAreComplete(skills, ["claudeCode"], false), true);
   });
 });
+
+// ── .last-sync — lastAttemptAt (v3, #2174) ─────────────────────────────
+
+describe("readLastSync / writeLastSync — lastAttemptAt (v3, #2174)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("round-trips a lastAttemptAt ISO string", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      lastAttemptAt: "2025-01-01T00:00:00.000Z",
+    });
+    assert.equal(readLastSync().lastAttemptAt, "2025-01-01T00:00:00.000Z");
+  });
+
+  it("persists lastAttemptAt: null when omitted, and reads it back as ABSENT", () => {
+    // Omitting the field writes explicit null on disk; readLastSync
+    // normalizes a non-string to absent so the throttle sees "never
+    // attempted" rather than a bogus clock value.
+    writeLastSync({ etag: '"e"', syncedAt: "s" });
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.equal(onDisk.lastAttemptAt, null);
+    assert.equal("lastAttemptAt" in readLastSync(), false);
+  });
+
+  it("coerces a non-string lastAttemptAt to absent (bogus clock ignored)", () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({
+        schemaVersion: 3,
+        etag: "x",
+        syncedAt: "x",
+        skills: {},
+        lastAttemptAt: 12345,
+      }),
+    );
+    assert.equal("lastAttemptAt" in readLastSync(), false);
+  });
+
+  it("accepts a v2 file in place (no lastAttemptAt) — etag + skills preserved", () => {
+    // A v2 file written by a pre-#2174 CLI must be read in place: etag and
+    // skills preserved (so the first post-upgrade sync stays a cheap 304),
+    // lastAttemptAt absent (the throttle treats it as "never attempted").
+    // This is the additive-forward-compat contract, distinct from the
+    // v1→v2 migration which forces a re-fetch via an empty skills map.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    const v2 = {
+      schemaVersion: 2,
+      etag: '"v2etag"',
+      syncedAt: "2025-01-01T00:00:00Z",
+      cliVersion: "4.8.1",
+      skills: {
+        "alice/x": {
+          version: "1.0.0",
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+          syncedAt: "2025-01-01T00:00:00Z",
+        },
+      },
+    };
+    writeFileSync(globalLastSyncPath(), JSON.stringify(v2));
+    const read = readLastSync();
+    assert.ok(read, "a v2 file must be accepted, not null");
+    assert.equal(read.etag, '"v2etag"');
+    assert.deepEqual(Object.keys(read.skills), ["alice/x"]);
+    assert.equal(
+      "lastAttemptAt" in read,
+      false,
+      "v2 has no lastAttemptAt → the throttle treats it as never attempted",
+    );
+  });
+
+  it("upsertLastSyncEntry preserves the prior lastAttemptAt (single-skill add is not a full sync)", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      skills: {},
+      lastAttemptAt: "2025-02-02T00:00:00.000Z",
+    });
+    upsertLastSyncEntry({
+      owner: "alice",
+      name: "added",
+      version: "1.0.0",
+      files: [
+        {
+          path: "SKILL.md",
+          content: "---\nname: added\ndescription: d\n---\nbody\n",
+        },
+      ],
+    });
+    assert.equal(
+      readLastSync().lastAttemptAt,
+      "2025-02-02T00:00:00.000Z",
+      "a single-skill add must NOT advance the throttle clock",
+    );
+  });
+
+  it("deleteLastSyncEntry preserves the prior lastAttemptAt", () => {
+    writeLastSync({
+      etag: '"e"',
+      syncedAt: "s",
+      skills: {
+        "alice/gone": {
+          version: "1.0.0",
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+          syncedAt: "s",
+        },
+      },
+      lastAttemptAt: "2025-03-03T00:00:00.000Z",
+    });
+    deleteLastSyncEntry("alice", "gone");
+    assert.equal(readLastSync().lastAttemptAt, "2025-03-03T00:00:00.000Z");
+  });
+});
+
+// ── runSync — SessionStart staleness throttle (#2174) ──────────────────
+//
+// A hook-triggered sync (`throttle: true`, passed ONLY by update.mjs's
+// --session-hook / --silent branches) skips ALL network work — no library
+// GET, no receipt POST — when the last ATTEMPT was within the window. A
+// bare interactive sync (no `throttle`) always runs. `lastAttemptAt` is
+// stamped on the 304 path and every successful write, NOT on a throttled
+// skip, so the window is measured from the last REAL sync — a run of quick
+// restarts can't push the clock forward and starve the sync.
+
+describe("runSync — SessionStart throttle (#2174)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("locks the default window at 15 minutes (a change must be deliberate)", () => {
+    assert.equal(MIN_SYNC_INTERVAL_MS, 15 * 60 * 1000);
+  });
+
+  it("ACCEPTANCE: two throttled syncs within the window → the 2nd makes ZERO HTTP calls", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // Run 1 (hook-triggered): a real sync — no prior attempt, so it is NOT
+    // throttled. It stamps lastAttemptAt = now.
+    const first = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(first.throttled ?? false, false, "first run is a real sync");
+    assert.ok(server.getLibraryRequestCount() >= 1, "first run hit the library GET");
+
+    // Reset the request-count spies, then run again immediately. Within the
+    // 15-min window the throttle MUST skip both the library GET and the
+    // receipt POST — zero HTTP, the acceptance criterion.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    const second = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+
+    assert.equal(second.throttled, true, "second run within the window is throttled");
+    assert.equal(server.getLibraryRequestCount(), 0, "throttled run makes NO library GET");
+    assert.equal(server.getReceiptRequestCount(), 0, "throttled run makes NO receipt POST");
+    assert.equal(
+      second.notModified,
+      false,
+      "throttled is distinct from a 304 — we never contacted the server",
+    );
+  });
+
+  it("a bare interactive sync (no throttle) ALWAYS syncs, even within the window", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Arm the clock with a hook sync.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    // Interactive: `throttle` omitted → must hit the network despite a
+    // fresh lastAttemptAt.
+    const res = await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "an explicit interactive sync always contacts the server",
+    );
+  });
+
+  it("does NOT throttle a fresh install (no lastAttemptAt yet)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // No prior .last-sync → lastAttemptAt absent → never attempted → the
+    // very first hook sync proceeds.
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("throttle expires: an attempt older than the window syncs again", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // Backdate lastAttemptAt to just past the window.
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - MIN_SYNC_INTERVAL_MS - 1000).toISOString(),
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "past the window → not throttled");
+    assert.ok(server.getLibraryRequestCount() >= 1, "expired window re-contacts the server");
+  });
+
+  it("minSyncIntervalMs override pins the boundary (0 disables the throttle)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+    // interval 0 → `now - last < 0` is never true → always syncs.
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 0,
+    });
+    assert.equal(res.throttled ?? false, false);
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("brackets the window: a 1h-old attempt throttles under a 2h interval, syncs under a 30-min one", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+    });
+
+    // Inside a 2h window → throttled (zero HTTP). A throttled skip does
+    // not re-stamp, so the same 1h-old attempt then drives the second leg.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    const inside = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 2 * 60 * 60 * 1000,
+    });
+    assert.equal(inside.throttled, true, "1h elapsed < 2h window → throttled");
+    assert.equal(server.getLibraryRequestCount(), 0);
+
+    // Outside a 30-min window → syncs.
+    const outside = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+      minSyncIntervalMs: 30 * 60 * 1000,
+    });
+    assert.equal(outside.throttled ?? false, false, "1h elapsed >= 30-min window → syncs");
+    assert.ok(server.getLibraryRequestCount() >= 1);
+  });
+
+  it("a FUTURE lastAttemptAt (backward clock jump) syncs and self-heals instead of throttling until the clock catches up", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // A backward clock jump (NTP correction, VM snapshot restore) leaves a
+    // stamp that is now in the FUTURE. `now - lastAttemptMs` goes negative —
+    // an unguarded `< intervalMs` would throttle every hook sync until the
+    // wall clock catches up, silently (hook modes are contract-silent).
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "a future stamp must NOT throttle");
+    assert.ok(server.getLibraryRequestCount() >= 1, "the hook sync proceeded");
+    // The sync (304 path here) re-stamps a sane "now" — the bogus future
+    // value is gone after ONE pass; the next window measures from reality.
+    const healed = readLastSync().lastAttemptAt;
+    assert.ok(
+      new Date(healed).getTime() <= Date.now(),
+      "the sync self-healed the stamp back to a non-future time",
+    );
+  });
+
+  it("a malformed lastAttemptAt string ('not-a-date') is not trusted — the hook sync proceeds", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+
+    // readLastSync only normalizes NON-string values to absent; a string
+    // that fails Date.parse reaches runSync's Number.isFinite guard. This
+    // pins that guard: bogus clock → sync (safe direction), never throttle.
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: "not-a-date",
+    });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+
+    const res = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      throttle: true,
+    });
+    assert.equal(res.throttled ?? false, false, "unparseable stamp must NOT throttle");
+    assert.ok(server.getLibraryRequestCount() >= 1, "the hook sync proceeded");
+    const healed = readLastSync().lastAttemptAt;
+    assert.ok(
+      typeof healed === "string" && Number.isFinite(Date.parse(healed)),
+      "the sync replaced the malformed stamp with a valid timestamp",
+    );
+  });
+
+  it("304 path stamps lastAttemptAt — LOAD-BEARING so the throttle re-arms every steady-state session", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // First (interactive) sync stamps lastAttemptAt and the etag.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(
+      typeof readLastSync().lastAttemptAt,
+      "string",
+      "first sync stamped lastAttemptAt",
+    );
+
+    // Backdate so the next sync is NOT throttled but WILL 304 (etag matches,
+    // placement present).
+    const s = readLastSync();
+    writeLastSync({
+      etag: s.etag,
+      syncedAt: s.syncedAt,
+      skills: s.skills,
+      cliVersion: s.cliVersion,
+      lastAttemptAt: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+    });
+
+    // Snapshot the full pre-304 state — the re-stamp must move ONLY the
+    // attempt clock. etag/skills/cliVersion wiped here (e.g. a future
+    // edit letting `skills` default to {}) would silently destroy every
+    // user's per-skill SHA cache on their next up-to-date sync.
+    const before = readLastSync();
+
+    const res = await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(res.notModified, true, "etag match → 304");
+    const after = readLastSync();
+    assert.equal(typeof after.lastAttemptAt, "string");
+    assert.ok(
+      Date.now() - new Date(after.lastAttemptAt).getTime() < 60_000,
+      "the 304 path re-stamped lastAttemptAt to a fresh time (throttle re-arms)",
+    );
+    assert.equal(after.etag, before.etag, "304 re-stamp preserves the etag verbatim");
+    assert.deepEqual(
+      after.skills,
+      before.skills,
+      "304 re-stamp preserves the per-skill SHA map verbatim",
+    );
+    assert.equal(
+      after.cliVersion,
+      before.cliVersion,
+      "304 re-stamp preserves cliVersion (a 304 is not a membership heal)",
+    );
+    assert.equal(after.syncedAt, before.syncedAt, "304 re-stamp preserves syncedAt");
+  });
+
+  it("does NOT stamp lastAttemptAt on a filesIncomplete sync (a broken sync is retried, not throttled)", async () => {
+    const inc = makeSkill("inc");
+    inc.filesIncomplete = true;
+    server.setEtag('"v1"');
+    server.setLibraryResponse({ skills: [inc], removals: [], syncedAt: "x" });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    // filesIncomplete → the whole state-file write is skipped → no
+    // lastAttemptAt persisted → the next hook sync is NOT throttled.
+    assert.equal(readLastSync(), null, "no state persisted on filesIncomplete");
+  });
+
+  it("emits a SKILLREPO_VERBOSE stderr line when it throttles", async () => {
+    const { createCaptureStream } = await import("../helpers/capture-stream.mjs");
+    const stderr = createCaptureStream();
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("x")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"], throttle: true });
+    server.resetLibraryInspection();
+
+    const prevVerbose = process.env.SKILLREPO_VERBOSE;
+    process.env.SKILLREPO_VERBOSE = "1";
+    try {
+      const res = await runSync({
+        serverUrl,
+        apiKey: VALID_KEY,
+        vendors: ["claudeCode"],
+        throttle: true,
+        io: { stderr },
+      });
+      assert.equal(res.throttled, true);
+    } finally {
+      if (prevVerbose === undefined) delete process.env.SKILLREPO_VERBOSE;
+      else process.env.SKILLREPO_VERBOSE = prevVerbose;
+    }
+    assert.match(stderr.text(), /throttled/);
+    assert.equal(server.getLibraryRequestCount(), 0, "verbose throttle still makes no GET");
+  });
+});