skillrepo 4.4.0 → 4.5.0

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

@@ -34,10 +34,17 @@ import {
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { runSync, readLastSync, writeLastSync, LAST_SYNC_SCHEMA_VERSION } from "../../lib/sync.mjs";
+import {
+  runSync,
+  readLastSync,
+  writeLastSync,
+  LAST_SYNC_SCHEMA_VERSION,
+} from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
 import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import { computeSkillShas } from "../../lib/crypto-shas.mjs";
+import { walkDetectedPlacements } from "../../lib/placement-walk.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import {
   captureHome,
@@ -112,6 +119,128 @@ 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("persists an empty skills map by default", () => {
+    // Callers that omit `skills` (e.g. the round-1 304 short-circuit
+    // before any rewrite) get an empty map, not undefined. This keeps
+    // the on-disk shape stable.
+    writeLastSync({ etag: '"x"', syncedAt: "x" });
+    const result = readLastSync();
+    assert.deepEqual(result.skills, {});
+  });
+
+  it("round-trips a populated skills map", () => {
+    const skills = {
+      "alice/pdf-helper": {
+        version: "1.4.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "2025-01-01T00:00:00Z",
+      },
+      "bob/code-review": {
+        version: "2.0.1",
+        skillMdSha256: "c".repeat(64),
+        filesSha256: "d".repeat(64),
+        syncedAt: "2025-01-01T00:00:00Z",
+      },
+    };
+    writeLastSync({
+      etag: '"abc"',
+      syncedAt: "2025-01-01T00:00:00Z",
+      skills,
+    });
+    const result = readLastSync();
+    assert.deepEqual(result.skills, skills);
+  });
+
+  it("an old v1 file migrates in-memory to a v2 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
+    // wasteful AND breaks `init`'s "Library is up to date" branch
+    // for users on a fresh upgrade.
+    //
+    // The migration is in-memory only: the on-disk file stays v1
+    // until the next successful runSync writes a fresh v2. The
+    // skills map starts empty — we don't fabricate per-skill state
+    // from a sync that didn't track it.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    const v1 = {
+      schemaVersion: 1,
+      etag: '"old"',
+      syncedAt: "2024-12-01T00:00:00Z",
+    };
+    writeFileSync(globalLastSyncPath(), JSON.stringify(v1));
+    const migrated = readLastSync();
+    assert.ok(migrated, "v1 file must migrate, not return null");
+    assert.equal(migrated.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
+    assert.equal(migrated.etag, '"old"');
+    assert.equal(migrated.syncedAt, "2024-12-01T00:00:00Z");
+    assert.deepEqual(migrated.skills, {});
+
+    // The on-disk file is NOT modified by the read.
+    const onDisk = JSON.parse(readFileSync(globalLastSyncPath(), "utf-8"));
+    assert.equal(onDisk.schemaVersion, 1, "on-disk file must stay v1 until next write");
+  });
+
+  it("coerces a malformed `skills` field (array) to {} in v2", () => {
+    // A truncated write or a hand-edit could produce a v2 file with
+    // `skills: []`. typeof [] === "object" so a naive guard at the
+    // caller would pass; direct dictionary access then returns
+    // undefined for every key and the user sees every skill as
+    // missing. readLastSync normalizes this to {} so callers can
+    // trust the contract.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({ schemaVersion: 2, etag: "x", syncedAt: "x", skills: [] }),
+    );
+    const result = readLastSync();
+    assert.ok(result, "v2 file with malformed skills should still parse");
+    assert.equal(typeof result.skills, "object");
+    assert.equal(Array.isArray(result.skills), false);
+    assert.deepEqual(result.skills, {});
+  });
+
+  it("coerces a null `skills` field to {} in v2", () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({ schemaVersion: 2, etag: "x", syncedAt: "x", skills: null }),
+    );
+    const result = readLastSync();
+    assert.deepEqual(result.skills, {});
+  });
+
+  it("coerces a missing `skills` field to {} in v2", () => {
+    // A v2 file from an older writer that forgot to emit `skills`.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({ schemaVersion: 2, etag: "x", syncedAt: "x" }),
+    );
+    const result = readLastSync();
+    assert.deepEqual(result.skills, {});
+  });
+
+  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.
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalLastSyncPath(),
+      JSON.stringify({ schemaVersion: 999, etag: "x", syncedAt: "x", skills: {} }),
+    );
+    assert.equal(readLastSync(), null);
+  });
+
   it("returns null on corrupt JSON", () => {
     const path = globalLastSyncPath();
     mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
@@ -260,6 +389,285 @@ describe("runSync — write skills", () => {
   });
 });
 
+// ── runSync — skills map population (v2) ───────────────────────────────
+//
+// #1553 — every successful sync populates `.last-sync.skills` with the
+// per-skill version + content SHAs. This is what unblocks per-skill
+// drift detection in #1555.
+
+describe("runSync — skills map population (v2)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("populates skills map for every written skill", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("first"), makeSkill("second")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    const state = readLastSync();
+    assert.ok(state, "state file must exist after a successful sync");
+    assert.deepEqual(
+      Object.keys(state.skills).sort(),
+      ["alice/first", "alice/second"],
+    );
+    for (const entry of Object.values(state.skills)) {
+      assert.equal(entry.version, "1.0.0");
+      assert.equal(typeof entry.skillMdSha256, "string");
+      assert.equal(entry.skillMdSha256.length, 64);
+      assert.equal(typeof entry.filesSha256, "string");
+      assert.equal(entry.filesSha256.length, 64);
+      assert.equal(entry.syncedAt, "2025-01-01T00:00:00Z");
+    }
+  });
+
+  it("persisted SHA matches the locally-computed SHA of the same content", async () => {
+    // The whole point of #1555's `edited` detection: a SHA persisted
+    // at sync time must equal the SHA of the same content recomputed
+    // later (e.g. from disk). This test pins that invariant by
+    // recomputing on the in-memory `skill.files` payload and asserting
+    // equality with the persisted entry.
+    const skill = makeSkill("integrity-check");
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [skill],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    const state = readLastSync();
+    const entry = state.skills["alice/integrity-check"];
+    const expected = computeSkillShas(skill.files);
+    assert.equal(entry.skillMdSha256, expected.skillMdSha256);
+    assert.equal(entry.filesSha256, expected.filesSha256);
+  });
+
+  it("omits filesIncomplete skills from the skills map", async () => {
+    const incomplete = makeSkill("incomplete");
+    incomplete.filesIncomplete = true;
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [incomplete, makeSkill("complete")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    // The state file is NOT persisted at all when any skill is
+    // filesIncomplete (existing behavior), so the map is implicitly
+    // empty for this sync. The next sync will be a full fetch.
+    assert.equal(readLastSync(), null);
+  });
+
+  it("carries forward prior entries on a delta sync that didn't touch a skill", async () => {
+    // First sync writes two skills, persists them in the map.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("untouched"), makeSkill("about-to-change", "v1")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    const firstState = readLastSync();
+    const untouchedShaBefore = firstState.skills["alice/untouched"].skillMdSha256;
+
+    // Second sync (different ETag → not 304) returns ONLY the changed
+    // skill, simulating a delta sync. The untouched skill must remain
+    // in the persisted map — otherwise the local cache would shrink
+    // on every delta sync and drift detection would lose entries.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("about-to-change", "v2-content")],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    const secondState = readLastSync();
+    // The untouched skill survives unchanged.
+    assert.ok(
+      secondState.skills["alice/untouched"],
+      "untouched skill must be carried forward",
+    );
+    assert.equal(
+      secondState.skills["alice/untouched"].skillMdSha256,
+      untouchedShaBefore,
+      "carried-forward SHA must equal the prior SHA, unchanged",
+    );
+    // The changed skill has fresh SHAs from the new content.
+    assert.notEqual(
+      secondState.skills["alice/about-to-change"].skillMdSha256,
+      firstState.skills["alice/about-to-change"].skillMdSha256,
+      "changed skill must have a different SHA",
+    );
+    assert.equal(
+      secondState.skills["alice/about-to-change"].syncedAt,
+      "2025-01-02T00:00:00Z",
+    );
+  });
+
+  it("removes tombstoned entries from the skills map", async () => {
+    // Seed: two skills on disk + in the map.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("survivor"), makeSkill("doomed")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    const before = readLastSync();
+    assert.ok(before.skills["alice/doomed"]);
+
+    // Second sync delivers a tombstone for `doomed`. The map entry
+    // must be purged — leaving a stale entry would let `list` think
+    // the skill is still tracked when in fact the library no longer
+    // references it.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [{ owner: "alice", name: "doomed", removedAt: "2025-01-02T00:00:00Z" }],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+
+    const after = readLastSync();
+    assert.equal(after.skills["alice/doomed"], undefined, "tombstoned entry must be deleted");
+    assert.ok(after.skills["alice/survivor"], "untouched entry must remain");
+  });
+
+  it("the skills map is empty after 304 short-circuit IF prior state was empty", async () => {
+    // 304 short-circuit means runSync returns the existing `lastSync`
+    // unchanged. If there was no `.last-sync` file at all, a 304
+    // can't happen (no ETag to send) — so this test only validates
+    // the path where a prior empty-skills state exists.
+    writeLastSync({ etag: '"v1"', syncedAt: "x", skills: {} });
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "ignored",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    const state = readLastSync();
+    assert.deepEqual(state.skills, {});
+  });
+});
+
+// ── SHA round-trip — runSync writes, placement-walk reads back ─────────
+//
+// THE load-bearing invariant of the staleness epic: the SHAs runSync
+// persists to .last-sync must equal the SHAs placement-walk computes
+// from the files on disk. If they don't match, `list`'s `edited`
+// detection breaks for every skill on every invocation.
+//
+// Individual halves are tested in isolation (sync.test asserts SHAs
+// against in-memory skill.files; placement-walk.test asserts disk
+// reads round-trip with computeSkillShas). This block composes them.
+
+describe("runSync + walkDetectedPlacements round-trip", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("disk SHAs after runSync match the persisted .last-sync SHAs", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("single-file"),
+        // Multi-file skill to exercise the `filesSha256` path
+        // (sorted path|sha projection across several files).
+        {
+          ...makeSkill("multi-file"),
+          files: [
+            {
+              path: "SKILL.md",
+              content: "---\nname: multi-file\ndescription: x\n---\n# body\n",
+              sha256: "x",
+              size: 0,
+              contentType: "text/markdown",
+            },
+            {
+              path: "references/notes.md",
+              content: "# notes\n",
+              sha256: "x",
+              size: 8,
+              contentType: "text/markdown",
+            },
+            {
+              path: "scripts/run.sh",
+              content: "#!/bin/sh\necho hi\n",
+              sha256: "x",
+              size: 18,
+              contentType: "text/x-shellscript",
+            },
+          ],
+        },
+      ],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // runSync writes the files to .claude/skills/ AND persists SHAs.
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // Walk the disk independently.
+    const placements = walkDetectedPlacements(["claudeCode"]);
+
+    // Read the persisted SHAs out of .last-sync.
+    const state = readLastSync();
+    assert.ok(state, "post-sync state must exist");
+
+    // For each skill: the SHAs on disk must equal the SHAs persisted.
+    // If this fails, EVERY user would see EVERY skill as `edited` on
+    // their first `list` after syncing — the epic's failure mode.
+    for (const skillName of ["single-file", "multi-file"]) {
+      const onDisk = placements.get(`claudeCode::project::${skillName}`);
+      const persisted = state.skills[`alice/${skillName}`];
+      assert.ok(onDisk, `disk placement for ${skillName} must exist`);
+      assert.ok(persisted, `persisted entry for ${skillName} must exist`);
+      assert.equal(
+        onDisk.skillMdSha256,
+        persisted.skillMdSha256,
+        `${skillName}: SKILL.md SHA must round-trip`,
+      );
+      assert.equal(
+        onDisk.filesSha256,
+        persisted.filesSha256,
+        `${skillName}: files SHA must round-trip`,
+      );
+    }
+  });
+});
+
 // ── runSync — tombstones ───────────────────────────────────────────────
 
 describe("runSync — tombstones", () => {