skillrepo 4.6.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/lib/sync.mjs

@@ -69,7 +69,14 @@
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
  * @property {string} [syncedAt]
- * @property {string} syncedAt    - ISO timestamp from the server response
+ * @property {string} syncedAt    - ISO timestamp of the sync: the server
+ *                                   response `syncedAt` on a 200, or the
+ *                                   previously-cached sync timestamp on a
+ *                                   304 (the server sends no body). NOTE:
+ *                                   this is distinct from the re-assertion
+ *                                   receipt's own timestamp on a 304, which
+ *                                   is the CLI's "now" (a liveness signal),
+ *                                   not this cached value.
  *
  * @typedef {Object} SyncedSkillEntry
  * @property {string} version       - Version of the skill as synced (e.g. "1.4.0").
@@ -417,7 +424,8 @@ export function deleteLastSyncEntry(owner, name) {
  *   2. Read the last-sync state file
  *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
  *      cached ETag) AND `since` (always, for delta semantics)
- *   4. Short-circuit on 304 — return `notModified: true`
+ *   4. On 304 — re-assert the on-disk state via a receipt (liveness +
+ *      heal) and short-circuit with `notModified: true`
  *   5. For each skill in the response:
  *      a. Write it via `writeSkillDir` — overwrites if changed
  *      b. Skip writing skills with `filesIncomplete: true` (see comment)
@@ -425,7 +433,9 @@ export function deleteLastSyncEntry(owner, name) {
  *      a. Call `removeSkillDir` — deletes from all configured targets
  *   7. Persist the new ETag (if the response was complete) for the
  *      next sync
- *   8. Return the summary
+ *   8. Re-assert the full on-disk state via a sync receipt (#1832) —
+ *      the confirmed-write signal that sets team sync state
+ *   9. Return the summary
  *
  * Error handling: any thrown error from the network or filesystem
  * layer propagates unchanged. The caller (a command) decides how to
@@ -536,6 +546,23 @@ export async function runSync(options) {
 
   // Step 4: 304 short-circuit
   if (result.notModified) {
+    // Re-assert the on-disk state even though nothing changed (#1832).
+    // The library is unchanged, so what's on disk is exactly the prior
+    // `.last-sync` skills map. This receipt:
+    //   • is the liveness signal that REPLACES the GET-side 304 heartbeat
+    //     for receipt-era servers (>= 4.7.0 CLIs no longer trigger it), so
+    //     a deliberately-stable library doesn't drift to "stale"; and
+    //   • heals any delivery the server missed (a receipt POST that failed
+    //     on a prior sync), correcting drift in the safe direction.
+    // Timestamp is the CLI's "now" so freshness advances; the server's
+    // 5-minute future tolerance absorbs ordinary clock skew. Best-effort.
+    await reportReceipt(
+      serverUrl,
+      apiKey,
+      receiptEntriesFromSkillsMap(lastSync?.skills),
+      new Date().toISOString(),
+      stderr,
+    );
     return {
       added: 0,
       updated: 0,
@@ -606,11 +633,6 @@ export async function runSync(options) {
   let anyIncomplete = false;
   /** @type {Record<string, SyncedSkillEntry>} */
   const skillsMap = {};
-  // Skills actually written to disk this sync, for the confirmed-write
-  // receipt (#1832). Only what we WRITE this round — carry-forward skills
-  // were reported on the sync that wrote them.
-  /** @type {{owner: string, name: string, version: string}[]} */
-  const writtenThisSync = [];
   // Carry forward entries from the previous sync for skills we did
   // NOT re-fetch this round. A delta sync that touched 2 of 50
   // skills must keep the other 48's metadata — otherwise the
@@ -674,17 +696,6 @@ export async function runSync(options) {
         syncedAt: result.syncedAt,
       };
     }
-
-    // Record this write for the sync receipt (#1832). Only entries with a
-    // real version label can resolve to a delivery server-side, so skip
-    // null/empty versions (a skill with no current published version).
-    if (typeof skill.version === "string" && skill.version !== "") {
-      writtenThisSync.push({
-        owner: skill.owner,
-        name: skill.name,
-        version: skill.version,
-      });
-    }
   }
 
   // Step 7: persist new ETag + skills map (only if the response was
@@ -712,33 +723,92 @@ export async function runSync(options) {
     }
   }
 
-  // Post a sync receipt for the skills actually written this sync
-  // (#1832). This confirmed-write signal — not the fetch itself — is what
-  // sets team sync state. Independent of the ETag persist above: skills
-  // skipped for `filesIncomplete` are excluded from `writtenThisSync`, so
-  // a partial sync still reports exactly what landed on disk. Best-effort:
-  // the files are already written and the server dedups replays, so a
-  // failed receipt is a non-fatal warning, never a sync failure.
-  if (writtenThisSync.length > 0) {
-    try {
-      await postSyncReceipt(serverUrl, apiKey, {
-        skills: writtenThisSync,
-        syncedAt: result.syncedAt,
-      });
-    } catch (err) {
-      stderr.write(
-        `  warning: failed to report sync receipt (${err.message}). ` +
-          `Your skills are synced locally; team sync status may lag until ` +
-          `your next sync.\n`,
-      );
-    }
-  }
+  // Re-assert the full on-disk state via a sync receipt (#1832). This
+  // confirmed-write signal — not the fetch itself — is what sets team
+  // sync state. We post the COMPLETE post-sync on-disk set (`skillsMap`:
+  // carry-forward skills + the skills written this round), not just what
+  // changed, so the receipt heals any delivery the server missed (a prior
+  // receipt POST that failed) and re-stamps freshness, replacing the
+  // GET-side heartbeat. `skillsMap` already reflects exactly what is on
+  // disk: skills skipped for `filesIncomplete` keep their prior carry-
+  // forward version (still on disk) and tombstoned skills were deleted
+  // from the map, so a partial or delta sync still re-asserts precisely
+  // what landed on disk. The server dedups (user, skill, version, UTC
+  // day), so re-asserting unchanged versions doesn't bloat the event log.
+  // Best-effort: files are already written, so a failed receipt is a
+  // non-fatal warning, never a sync failure.
+  await reportReceipt(
+    serverUrl,
+    apiKey,
+    receiptEntriesFromSkillsMap(skillsMap),
+    result.syncedAt,
+    stderr,
+  );
 
   return summary;
 }
 
 // ── Internals ──────────────────────────────────────────────────────────
 
+/**
+ * Build sync-receipt entries from a `.last-sync` skills map (#1832).
+ *
+ * Each key is `"<owner>/<name>"`; the value carries the version label of
+ * the skill as written to disk. The returned `[{ owner, name, version }]`
+ * array is the CLI's assertion of what it actually has on disk — the
+ * evidence the server treats as the single source of truth for sync
+ * state. Entries with no version label are skipped: a skill with no
+ * published version can't resolve to a delivery server-side. Malformed
+ * keys (no `/`, empty owner/name) are skipped defensively rather than
+ * producing a bogus receipt entry.
+ *
+ * @param {Record<string, {version?: string}> | null | undefined} skillsMap
+ * @returns {{owner: string, name: string, version: string}[]}
+ */
+function receiptEntriesFromSkillsMap(skillsMap) {
+  /** @type {{owner: string, name: string, version: string}[]} */
+  const entries = [];
+  if (!skillsMap || typeof skillsMap !== "object") return entries;
+  for (const [key, entry] of Object.entries(skillsMap)) {
+    if (!entry || typeof entry !== "object") continue;
+    const version = typeof entry.version === "string" ? entry.version : "";
+    if (version === "") continue;
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue;
+    const owner = key.slice(0, slashAt);
+    const name = key.slice(slashAt + 1);
+    if (!owner || !name) continue;
+    entries.push({ owner, name, version });
+  }
+  return entries;
+}
+
+/**
+ * Post a sync receipt, best-effort (#1832). A no-op when `skills` is
+ * empty (nothing on disk to assert — e.g. an empty library). The skill
+ * files are already on disk and the server dedups replays, so a failed
+ * receipt is a non-fatal warning surfaced via the injected stderr
+ * stream — never a sync failure.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {{owner: string, name: string, version: string}[]} skills
+ * @param {string} syncedAt - ISO timestamp for the delivery + dedup key.
+ * @param {NodeJS.WritableStream} stderr
+ */
+async function reportReceipt(serverUrl, apiKey, skills, syncedAt, stderr) {
+  if (skills.length === 0) return;
+  try {
+    await postSyncReceipt(serverUrl, apiKey, { skills, syncedAt });
+  } catch (err) {
+    stderr.write(
+      `  warning: failed to report sync receipt (${err.message}). ` +
+        `Your skills are synced locally; team sync status may lag until ` +
+        `your next sync.\n`,
+    );
+  }
+}
+
 /**
  * Check whether ANY of the configured placement targets already
  * contains a directory for the given skill name. Used to distinguish

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

@@ -415,7 +415,7 @@ describe("runSync — sync receipts (#1832)", () => {
     }
   });
 
-  it("does NOT post a receipt on a 304 (nothing written)", async () => {
+  it("re-asserts the on-disk state on a 304 (liveness + heal), not nothing", async () => {
     server.setEtag('"v1"');
     server.setLibraryResponse({
       skills: [makeSkill("pdf-helper")],
@@ -427,14 +427,120 @@ describe("runSync — sync receipts (#1832)", () => {
     assert.equal(server.getReceiptRequestCount(), 1);
     server.resetReceipts();
 
-    // Second sync 304-short-circuits (etag matches, placement present).
+    // Second sync 304-short-circuits (etag matches, placement present) but
+    // STILL posts a receipt re-asserting the on-disk set. This is the
+    // liveness signal that replaces the GET-side 304 heartbeat for
+    // receipt-era servers, and it heals any delivery a prior failed
+    // receipt POST lost (#1832 PR B).
     const result = await runSync({
       serverUrl,
       apiKey: VALID_KEY,
       vendors: ["claudeCode"],
     });
     assert.equal(result.notModified, true);
-    assert.equal(server.getReceiptRequestCount(), 0);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["pdf-helper"],
+    );
+    assert.equal(receipt.skills[0].version, "1.0.0");
+    // syncedAt on a 304 is the CLI's "now" (the server sends no body),
+    // so freshness advances — not the stale first-sync timestamp.
+    assert.ok(
+      Number.isFinite(new Date(receipt.syncedAt).getTime()),
+      "304 receipt carries a valid ISO syncedAt",
+    );
+    assert.notEqual(
+      receipt.syncedAt,
+      "2025-06-01T00:00:00Z",
+      "304 receipt uses the CLI's now, not the prior sync timestamp",
+    );
+    // Stronger than "not the fixture": prove the timestamp is wall-clock
+    // FRESH. A regression that stamped the receipt with any stale cached
+    // value (e.g. lastSync.syncedAt) could differ from the fixture and
+    // still pass the notEqual above — but it would fail this. The liveness
+    // signal that replaces the 304 heartbeat must advance every sync.
+    assert.ok(
+      Date.now() - new Date(receipt.syncedAt).getTime() < 60_000,
+      "304 receipt syncedAt must be wall-clock fresh (within the last minute)",
+    );
+  });
+
+  it("re-asserts the full on-disk set (carry-forward + newly written) on a delta sync", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // Library changes: only `gamma` is new this round; alpha+beta are
+    // unchanged and arrive only via the carry-forward `.last-sync` map.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("gamma")],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    // The receipt re-asserts EVERYTHING on disk, not just the changed
+    // skill — that is what heals server drift and keeps freshness honest.
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta", "gamma"],
+    );
+    // A 200 uses the server's response syncedAt for the delivery time.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("re-asserts carry-forward on a 200 delta that writes nothing new", async () => {
+    // Distinct from the 304 short-circuit: here the ETag changes (a real
+    // 200) but the response carries no skills to write, so nothing new
+    // lands on disk. The receipt must still re-assert the full carry-
+    // forward set — the 200 path's re-assertion is driven by the on-disk
+    // `.last-sync` map, not by what was written this round.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alpha"), makeSkill("beta")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    assert.equal(result.notModified, false);
+    assert.equal(result.added, 0);
+    assert.equal(result.updated, 0);
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name).sort(),
+      ["alpha", "beta"],
+    );
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
   });
 
   it("excludes a filesIncomplete skill from the receipt", async () => {
@@ -454,9 +560,48 @@ describe("runSync — sync receipts (#1832)", () => {
     );
   });
 
-  it("does NOT post a receipt when ALL skills are filesIncomplete", async () => {
-    // Distinct branch from the mixed case above: `writtenThisSync` stays
-    // empty, so the `writtenThisSync.length > 0` guard skips the POST.
+  it("re-asserts the OLD on-disk version when a newer version fails to inline (filesIncomplete carry-forward)", async () => {
+    // First sync writes pdf-helper@1.0.0.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // The server tries to deliver pdf-helper@1.1.0 but its files fail to
+    // inline. The CLI skips the write (1.0.0 stays on disk) and must
+    // re-assert the OLD version it still has — not the version it failed
+    // to write, and not nothing.
+    const newer = makeSkill("pdf-helper");
+    newer.version = "1.1.0";
+    newer.filesIncomplete = true;
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [newer],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(receipt.skills, [
+      { owner: "alice", name: "pdf-helper", version: "1.0.0" },
+    ]);
+    // Freshness still advances on a partial sync: the receipt carries the
+    // SERVER's 200 response syncedAt (the fresh sync time), not the stale
+    // carry-forward entry's own recorded syncedAt.
+    assert.equal(receipt.syncedAt, "2025-01-02T00:00:00Z");
+  });
+
+  it("does NOT post a receipt when ALL skills are filesIncomplete (nothing on disk to assert)", async () => {
+    // A first sync where every skill is filesIncomplete writes nothing
+    // and has no carry-forward `.last-sync` baseline, so the post-sync
+    // on-disk set is empty and `reportReceipt`'s empty-skills guard skips
+    // the POST.
     const a = makeSkill("inc-a");
     a.filesIncomplete = true;
     const b = makeSkill("inc-b");
@@ -821,10 +966,41 @@ describe("runSync — tombstones", () => {
     });
     assert.equal(result.removed, 1);
     assert.ok(!existsSync(resolvePlacementDir("claudeProject", "doomed")));
-    // A tombstone-only sync writes nothing → posts no receipt (#1832).
+    // The `.last-sync` baseline was reset (rm above) and the only skill
+    // was tombstoned, so the post-sync on-disk set is empty → the
+    // re-assertion receipt has nothing to send and is skipped (#1832).
     assert.equal(server.getReceiptRequestCount(), 0);
   });
 
+  it("re-asserts surviving skills but excludes a tombstoned one", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("keep"), makeSkill("drop")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    server.resetReceipts();
+
+    // `drop` is tombstoned; `keep` stays on disk and must be re-asserted.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [
+        { owner: "alice", name: "drop", removedAt: "2025-01-02T00:00:00Z" },
+      ],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    assert.equal(server.getReceiptRequestCount(), 1);
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(
+      receipt.skills.map((s) => s.name),
+      ["keep"],
+    );
+  });
+
   it("applies removals BEFORE writes (re-add scenario)", async () => {
     // The server returns a tombstone AND a skill with the same name
     // (the user removed and re-added in the same window). The CLI