skillrepo 4.4.0 → 4.5.0

package/src/lib/sync.mjs

@@ -22,6 +22,32 @@
  * can evolve it without breaking older CLIs catastrophically. Future
  * versions should bump the schema when fields are added/removed.
  *
+ * Schema history
+ * --------------
+ *   v1 — `{ schemaVersion, etag, syncedAt }`. Library-level state only;
+ *        no per-skill information persisted. Sufficient for ETag-based
+ *        short-circuit, insufficient for per-skill drift detection.
+ *   v2 — Adds a `skills` map keyed by `"<owner>/<name>"` carrying the
+ *        version + content SHAs of every skill written in the last
+ *        successful sync. Unblocks per-skill drift detection in `list`
+ *        (#1555) and any future `status`-style command.
+ *
+ * Forward/backward compatibility
+ * ------------------------------
+ *   • Old CLI reading a v2 file → unknown schemaVersion → null → full
+ *     sync → writes v1 file. User loses per-skill metadata until they
+ *     upgrade again.
+ *   • New CLI reading a v1 file → in-memory migration to a v2 shape
+ *     with the existing `etag` + `syncedAt` preserved and an EMPTY
+ *     `skills` map. The next successful sync writes a v2 file on
+ *     disk. This is safe because an empty map means "we don't know
+ *     per-skill state from this sync" — callers must treat absent
+ *     entries as unknown, not as "missing from library." Preserving
+ *     the etag also keeps the 304 short-circuit working, so an
+ *     upgrade-then-no-changes path stays cheap.
+ *   • Future unknown schemaVersion → null → full sync. Forward-compat
+ *     without crashing.
+ *
  * @typedef {Object} SyncSummary
  * @property {number} added       - Skills newly written that were not on disk
  * @property {number} updated     - Skills overwritten on disk
@@ -45,14 +71,20 @@
  * @property {string} [syncedAt]
  * @property {string} syncedAt    - ISO timestamp from the server response
  *
+ * @typedef {Object} SyncedSkillEntry
+ * @property {string} version       - Version of the skill as synced (e.g. "1.4.0").
+ * @property {string} skillMdSha256 - Hex SHA-256 of SKILL.md content as written.
+ * @property {string} filesSha256   - Hex SHA-256 of the full file projection.
+ * @property {string} syncedAt      - ISO timestamp when this skill was synced.
+ *
  * @typedef {Object} SyncStateFile
  * @property {number} schemaVersion
  * @property {string|null} etag
  * @property {string} syncedAt
+ * @property {Record<string, SyncedSkillEntry>} skills - v2+. Keyed by `"<owner>/<name>"`.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 
 import { getLibrary } from "./http.mjs";
 import {
@@ -62,16 +94,21 @@ import {
   placementTargetsFor,
   resolvePlacementDir,
 } from "./file-write.mjs";
+import { writeFileAtomic } from "./fs-utils.mjs";
 import { globalLastSyncPath } from "./paths.mjs";
 import { diskError, validationError } from "./errors.mjs";
+import { computeSkillShas } from "./crypto-shas.mjs";
 
 /**
  * Current schema version of the .last-sync file. Bump on any
  * structural change. The reader treats unknown future versions as
  * "ignore the cache and do a full sync" — forward-compat without
  * crashing.
+ *
+ * v2 (#1553): adds `skills` map keyed by `"<owner>/<name>"` →
+ * `{ version, skillMdSha256, filesSha256, syncedAt }`.
  */
-export const LAST_SYNC_SCHEMA_VERSION = 1;
+export const LAST_SYNC_SCHEMA_VERSION = 2;
 
 /**
  * Read the persisted last-sync state from ~/.claude/skillrepo/.last-sync.
@@ -99,12 +136,42 @@ export function readLastSync() {
     return null;
   }
 
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+
+  // v1 → v2 in-memory migration. Preserve the etag and syncedAt so
+  // delta sync still benefits from the prior state; start with an
+  // empty `skills` map. The next successful runSync writes v2 to
+  // disk. We do NOT write here — readers should be pure with
+  // respect to the filesystem.
+  if (parsed.schemaVersion === 1) {
+    return {
+      schemaVersion: LAST_SYNC_SCHEMA_VERSION,
+      etag: typeof parsed.etag === "string" ? parsed.etag : null,
+      syncedAt: typeof parsed.syncedAt === "string" ? parsed.syncedAt : null,
+      skills: {},
+    };
+  }
+
+  if (parsed.schemaVersion !== LAST_SYNC_SCHEMA_VERSION) {
+    return null;
+  }
+
+  // Defense: coerce a malformed `skills` field to {}. Both an array
+  // (`typeof === "object"` but not a real map) and a missing/null
+  // field can otherwise sneak past callers that only check
+  // `typeof === "object"`. Specifically: `list.mjs` does direct
+  // dictionary access on `lastSync.skills`, and `lastSync.skills[key]`
+  // on an array returns `undefined`, which would render every skill
+  // as `missing` — wrong, not safe-fail. Normalizing here means every
+  // caller sees a real Record<string, ...>.
   if (
-    !parsed ||
-    typeof parsed !== "object" ||
-    parsed.schemaVersion !== LAST_SYNC_SCHEMA_VERSION
+    !parsed.skills ||
+    typeof parsed.skills !== "object" ||
+    Array.isArray(parsed.skills)
   ) {
-    return null;
+    parsed.skills = {};
   }
 
   return parsed;
@@ -116,22 +183,36 @@ export function readLastSync() {
  * error. Most callers should treat a state-file write failure as
  * non-fatal because the actual skill files were already written
  * successfully.
+ *
+ * v2 (#1553): `skills` is the per-skill version+SHA map. Omitting it
+ * persists an empty `{}` — the schema bump is structural even when
+ * the caller has no skills to record (e.g. a 304 short-circuit before
+ * runSync ran any writes). An empty map means "we know the library
+ * was up-to-date at syncedAt but have no per-skill details from this
+ * sync"; consumers should treat absent entries as "unknown" rather
+ * than as "missing from library."
+ *
+ * @param {object} state
+ * @param {string | null} [state.etag]
+ * @param {string} [state.syncedAt]
+ * @param {Record<string, SyncedSkillEntry>} [state.skills]
  */
-export function writeLastSync({ etag, syncedAt }) {
+export function writeLastSync({ etag, syncedAt, skills } = {}) {
   const path = globalLastSyncPath();
-  const dir = dirname(path);
-  try {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  } catch (err) {
-    throw diskError(`Cannot create ${dir}: ${err.message}`, { cause: err });
-  }
   const body = {
     schemaVersion: LAST_SYNC_SCHEMA_VERSION,
     etag: etag ?? null,
     syncedAt: syncedAt ?? new Date().toISOString(),
+    skills: skills && typeof skills === "object" && !Array.isArray(skills) ? skills : {},
   };
   try {
-    writeFileSync(path, JSON.stringify(body, null, 2) + "\n", "utf-8");
+    // writeFileAtomic handles parent-dir creation and uses a
+    // per-process unique temp suffix so two concurrent writers
+    // (e.g., a SessionStart hook running `skillrepo update` while
+    // the user runs another command) can't collide on the same
+    // .tmp path and produce a torn final file. The cohort hooks
+    // (#1240) made this race observable in production.
+    writeFileAtomic(path, JSON.stringify(body, null, 2) + "\n");
   } catch (err) {
     throw diskError(`Cannot write ${path}: ${err.message}`, { cause: err });
   }
@@ -270,7 +351,50 @@ export async function runSync(options) {
   // a partial skill would leave the user with broken resource
   // references (the SKILL.md body would point to files that don't
   // exist on disk).
+  //
+  // v2 of `.last-sync` carries a per-skill version + SHA map. We
+  // compute SHAs from the in-memory `skill.files` array — same bytes
+  // we're about to write to disk via writeSkillDir — so the persisted
+  // SHA exactly matches what landed on the user's filesystem. SHAs are
+  // recorded ONLY for skills we actually wrote (skipped on
+  // filesIncomplete, never persisted on a write failure since the
+  // throw propagates and the whole state file write is bypassed).
   let anyIncomplete = false;
+  /** @type {Record<string, SyncedSkillEntry>} */
+  const skillsMap = {};
+  // 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
+  // persisted map shrinks every delta sync until only the most
+  // recently-touched skills remain, defeating `list`'s drift
+  // detection. The previous ETag is only persisted again when no
+  // filesIncomplete fired, so this carry-forward is safe even on
+  // partial syncs.
+  //
+  // We reuse `lastSync` (captured before the network call) rather
+  // than re-reading from disk. No write happens between line ~330
+  // and here, so the values are identical — but re-reading would
+  // be a footgun if a future change ever persisted partial state
+  // between those points (the carry-forward would silently pick up
+  // the freshly-written data instead of the truly-prior state).
+  if (lastSync && lastSync.skills && typeof lastSync.skills === "object") {
+    for (const [key, entry] of Object.entries(lastSync.skills)) {
+      if (entry && typeof entry === "object") {
+        skillsMap[key] = entry;
+      }
+    }
+  }
+  // Tombstones invalidate any prior map entry: a skill that was
+  // removed from the library should not linger in our local
+  // version/SHA cache. Apply this BEFORE re-adding entries from the
+  // current response so a re-add in the same sync window (handled
+  // earlier under "removals applied first") still ends up in the
+  // map with fresh data.
+  for (const tombstone of result.removals) {
+    const key = `${tombstone.owner}/${tombstone.name}`;
+    delete skillsMap[key];
+  }
+
   for (const skill of result.skills) {
     if (skill.filesIncomplete) {
       anyIncomplete = true;
@@ -283,12 +407,34 @@ export async function runSync(options) {
     } else {
       summary.added++;
     }
+
+    // Compute SHAs from the same content writeSkillDir just persisted
+    // to disk. If the skill has no SKILL.md (malformed payload that
+    // somehow passed validateSkill), `skillMdSha256` is null and we
+    // skip the map entry — recording a partial entry would poison
+    // future drift detection. validateSkill in file-write.mjs already
+    // rejects skills without SKILL.md, so this branch is defense in
+    // depth; if it ever fires, our cache is correct (no entry > bad
+    // entry).
+    const shas = computeSkillShas(skill.files);
+    if (shas.skillMdSha256 !== null) {
+      skillsMap[`${skill.owner}/${skill.name}`] = {
+        version: typeof skill.version === "string" ? skill.version : "",
+        skillMdSha256: shas.skillMdSha256,
+        filesSha256: shas.filesSha256,
+        syncedAt: result.syncedAt,
+      };
+    }
   }
 
-  // Step 7: persist new ETag (only if the response was complete)
+  // Step 7: persist new ETag + skills map (only if the response was complete)
   if (!anyIncomplete && result.etag) {
     try {
-      writeLastSync({ etag: result.etag, syncedAt: result.syncedAt });
+      writeLastSync({
+        etag: result.etag,
+        syncedAt: result.syncedAt,
+        skills: skillsMap,
+      });
     } catch (err) {
       // Non-fatal — the skills are on disk, we just won't get the
       // 304 short-circuit on the next run. Surface a warning via