skillrepo 4.3.0 → 4.5.0

package/src/test/lib/crypto-shas.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * Unit tests for `computeSkillShas` in `src/lib/crypto-shas.mjs`.
+ *
+ * The helper is pure (no I/O), so these are direct input → output
+ * assertions. The properties we lock in:
+ *
+ *   1. Determinism: same input → same output, every time.
+ *   2. SKILL.md identification: case-sensitive, root-only.
+ *   3. Sort order: byte-order, not locale-aware.
+ *   4. Empty array → well-defined empty-string SHA.
+ *   5. Missing SKILL.md → `skillMdSha256: null` (callers MUST handle).
+ *   6. Type discipline: rejects non-array / non-string inputs.
+ *
+ * Why explicit SHA constants
+ * --------------------------
+ * The whole point of #1553 is that a v2 `.last-sync` written by one
+ * CLI version must be readable by another. The SHAs MUST be stable
+ * across Node versions, locales, and platforms. Pinning expected hex
+ * digests in the test catches the regression where someone "helpfully"
+ * swaps in `Buffer.from(content).toString("hex")` or normalizes line
+ * endings — both of which produce different bytes for the same
+ * apparent string and break drift detection silently.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+
+import { computeSkillShas } from "../../lib/crypto-shas.mjs";
+
+/** Test helper — computes the same SHA we expect the implementation to. */
+function sha256Utf8(s) {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+
+describe("computeSkillShas", () => {
+  it("hashes SKILL.md content as UTF-8 bytes", () => {
+    const content = "# pdf-helper\n\nReads PDFs.\n";
+    const result = computeSkillShas([
+      { path: "SKILL.md", content },
+    ]);
+    assert.equal(result.skillMdSha256, sha256Utf8(content));
+  });
+
+  it("is deterministic across calls", () => {
+    const files = [
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/x.md", content: "x\n" },
+      { path: "scripts/run.sh", content: "#!/bin/sh\necho hi\n" },
+    ];
+    const a = computeSkillShas(files);
+    const b = computeSkillShas(files);
+    assert.equal(a.skillMdSha256, b.skillMdSha256);
+    assert.equal(a.filesSha256, b.filesSha256);
+  });
+
+  it("filesSha256 is order-independent on input", () => {
+    // The same files in two different orders MUST produce the same
+    // filesSha256 — the helper sorts internally. If a caller passed
+    // server-sorted vs locally-sorted arrays, drift detection would
+    // false-positive on every sync.
+    const reordered = [
+      { path: "scripts/run.sh", content: "#!/bin/sh\n" },
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/x.md", content: "x\n" },
+    ];
+    const original = [
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/x.md", content: "x\n" },
+      { path: "scripts/run.sh", content: "#!/bin/sh\n" },
+    ];
+    const a = computeSkillShas(original);
+    const b = computeSkillShas(reordered);
+    assert.equal(a.filesSha256, b.filesSha256);
+  });
+
+  it("filesSha256 changes when any file's content changes", () => {
+    const before = computeSkillShas([
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/x.md", content: "x\n" },
+    ]);
+    const after = computeSkillShas([
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/x.md", content: "y\n" }, // changed content
+    ]);
+    assert.notEqual(before.filesSha256, after.filesSha256);
+  });
+
+  it("filesSha256 changes when a file is added", () => {
+    const before = computeSkillShas([
+      { path: "SKILL.md", content: "# a\n" },
+    ]);
+    const after = computeSkillShas([
+      { path: "SKILL.md", content: "# a\n" },
+      { path: "references/new.md", content: "new\n" },
+    ]);
+    assert.notEqual(before.filesSha256, after.filesSha256);
+    // SKILL.md itself didn't change → its sha is stable.
+    assert.equal(before.skillMdSha256, after.skillMdSha256);
+  });
+
+  it("skillMdSha256 is null when no SKILL.md is present (root, case-sensitive)", () => {
+    // Lowercase skill.md is NOT the canonical SKILL.md per the spec.
+    const result = computeSkillShas([
+      { path: "skill.md", content: "# a\n" },
+      { path: "references/x.md", content: "x\n" },
+    ]);
+    assert.equal(result.skillMdSha256, null);
+    // filesSha256 is still well-defined.
+    assert.equal(typeof result.filesSha256, "string");
+    assert.equal(result.filesSha256.length, 64);
+  });
+
+  it("skillMdSha256 is null when SKILL.md is nested (not at root)", () => {
+    const result = computeSkillShas([
+      { path: "docs/SKILL.md", content: "# a\n" },
+    ]);
+    assert.equal(result.skillMdSha256, null);
+  });
+
+  it("empty files array yields the SHA of the empty string", () => {
+    const result = computeSkillShas([]);
+    assert.equal(result.skillMdSha256, null);
+    assert.equal(result.filesSha256, sha256Utf8(""));
+  });
+
+  it("hashes UTF-8 content with non-ASCII characters consistently", () => {
+    // Regression guard: any future "fix" that encodes via a different
+    // charset (e.g. latin1) would silently produce different bytes for
+    // the same string input. The hex below is the SHA-256 of the
+    // UTF-8 bytes of the content string.
+    const content = "# café\n— résumé\n";
+    const result = computeSkillShas([
+      { path: "SKILL.md", content },
+    ]);
+    assert.equal(result.skillMdSha256, sha256Utf8(content));
+  });
+
+  it("uses byte-order sort, NOT locale-aware sort", () => {
+    // Byte-order: 'Z' (0x5A) < 'a' (0x61). Locale-aware sort
+    // typically puts 'a' before 'Z'. Both orderings yield the SAME
+    // input set, but DIFFERENT projection strings, so they hash to
+    // DIFFERENT filesSha256 values. We assert the byte-order
+    // projection wins.
+    const files = [
+      { path: "SKILL.md", content: "x\n" },
+      { path: "Z.md", content: "z\n" },
+      { path: "a.md", content: "a\n" },
+    ];
+    const result = computeSkillShas(files);
+    // Construct the expected projection in byte-order: SKILL.md, Z.md, a.md.
+    const shaSkill = sha256Utf8("x\n");
+    const shaZ = sha256Utf8("z\n");
+    const shaA = sha256Utf8("a\n");
+    const expectedProjection = `SKILL.md|${shaSkill}\nZ.md|${shaZ}\na.md|${shaA}`;
+    assert.equal(result.filesSha256, sha256Utf8(expectedProjection));
+  });
+
+  it("throws TypeError on non-array input", () => {
+    assert.throws(() => computeSkillShas(null), TypeError);
+    assert.throws(() => computeSkillShas(undefined), TypeError);
+    assert.throws(() => computeSkillShas({}), TypeError);
+    assert.throws(() => computeSkillShas("SKILL.md"), TypeError);
+  });
+
+  it("throws TypeError when a file is missing path/content as strings", () => {
+    assert.throws(() => computeSkillShas([{ path: 123, content: "x" }]), TypeError);
+    assert.throws(() => computeSkillShas([{ path: "SKILL.md", content: null }]), TypeError);
+    assert.throws(() => computeSkillShas([{ path: "SKILL.md" }]), TypeError);
+    assert.throws(() => computeSkillShas([null]), TypeError);
+  });
+});

package/src/test/lib/drift.test.mjs

@@ -0,0 +1,289 @@
+/**
+ * Unit tests for `src/lib/drift.mjs` (#1555).
+ *
+ * The module is pure — every test is a direct input → output
+ * assertion. The properties locked in here are load-bearing for
+ * `skillrepo list`'s drift column and `--json` shape:
+ *
+ *   - Every state in `SKILL_STATE` reachable from `computeSkillState`.
+ *   - Rollup precedence (missing > edited > stale > current).
+ *   - Semver fallback to string comparison for non-semver versions.
+ *   - "On-disk but no baseline" treated as `missing` (not `current`).
+ *   - Both SHA fields contribute to `edited` detection.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { computeSkillState, rollupState, SKILL_STATE } from "../../lib/drift.mjs";
+
+// Test fixtures — keep them readable. SHAs use distinct repeated
+// characters so an assertion comparing the wrong field is obvious.
+const SHA_A = "a".repeat(64);
+const SHA_B = "b".repeat(64);
+const SHA_C = "c".repeat(64);
+const SHA_D = "d".repeat(64);
+
+const BASELINE = Object.freeze({
+  version: "1.0.0",
+  skillMdSha256: SHA_A,
+  filesSha256: SHA_B,
+});
+
+function localPresence(skillMdSha = SHA_A, filesSha = SHA_B) {
+  return { present: true, skillMdSha256: skillMdSha, filesSha256: filesSha };
+}
+
+// ── computeSkillState ──────────────────────────────────────────────────
+
+describe("computeSkillState", () => {
+  it("returns CURRENT when version matches and both SHAs match", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.CURRENT);
+  });
+
+  it("returns MISSING when localPlacement is null", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: null,
+    });
+    assert.equal(result, SKILL_STATE.MISSING);
+  });
+
+  it("returns MISSING when localPlacement.present is false", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: { present: false, skillMdSha256: null, filesSha256: null },
+    });
+    assert.equal(result, SKILL_STATE.MISSING);
+  });
+
+  it("returns MISSING when lastSyncEntry is null (no baseline)", () => {
+    // The on-disk file exists but we have no SHA to compare against.
+    // We MUST NOT report this as `current` — that would mask drift
+    // we cannot detect. Reporting `missing` tells the user to run
+    // `skillrepo update` to establish a baseline, which is the
+    // correct resolution.
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: null,
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.MISSING);
+  });
+
+  it("returns STALE when library version is newer than synced version", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.1.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.STALE);
+  });
+
+  it("returns STALE for major version bump even with matching SHAs", () => {
+    // Edge case: if the user reverted their local file to match the
+    // OLD baseline SHAs but a major bump shipped, they're still stale.
+    // Stale takes precedence over SHA-match because the registry has
+    // strictly moved on.
+    const result = computeSkillState({
+      libraryVersion: "2.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.STALE);
+  });
+
+  it("returns EDITED when SKILL.md SHA differs but version matches", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(SHA_C, SHA_B), // SKILL.md changed
+    });
+    assert.equal(result, SKILL_STATE.EDITED);
+  });
+
+  it("returns EDITED when files SHA differs but SKILL.md SHA matches", () => {
+    // Support files (references/, scripts/, assets/) changed but
+    // SKILL.md didn't. Still `edited` — the user modified the skill.
+    // This is why crypto-shas exposes BOTH digests rather than just
+    // SKILL.md's: a support-file edit would otherwise read as `current`.
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(SHA_A, SHA_D), // files changed
+    });
+    assert.equal(result, SKILL_STATE.EDITED);
+  });
+
+  it("returns EDITED when both SHAs differ but version matches", () => {
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(SHA_C, SHA_D),
+    });
+    assert.equal(result, SKILL_STATE.EDITED);
+  });
+
+  it("STALE wins over EDITED when both apply", () => {
+    // Library bumped AND local edited. The user's action is `update`
+    // (which will overwrite their edits — they should commit first).
+    // Stale gives the more actionable signal: "you're behind."
+    const result = computeSkillState({
+      libraryVersion: "1.1.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(SHA_C, SHA_D),
+    });
+    assert.equal(result, SKILL_STATE.STALE);
+  });
+
+  it("returns CURRENT when library version is older than synced (defensive)", () => {
+    // This shouldn't happen in normal flow (the library is authoritative)
+    // but defending against the case: if the library's version is
+    // somehow LOWER than what we synced, don't flag stale. The SHAs
+    // are the source of truth for "is the on-disk content right."
+    const result = computeSkillState({
+      libraryVersion: "0.9.0",
+      lastSyncEntry: BASELINE, // version: "1.0.0"
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.CURRENT);
+  });
+
+  it("treats non-semver versions as different → STALE when they differ", () => {
+    // Future-proof: registry could adopt date-stamped or git-sha
+    // versioning. Any non-semver mismatch is treated as `stale`,
+    // which is the safe direction (user runs `update`, no drift
+    // gets masked).
+    const result = computeSkillState({
+      libraryVersion: "2026-05-19",
+      lastSyncEntry: { ...BASELINE, version: "2026-05-18" },
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.STALE);
+  });
+
+  it("treats non-semver versions as same → CURRENT when they match", () => {
+    const result = computeSkillState({
+      libraryVersion: "git-abc123",
+      lastSyncEntry: { ...BASELINE, version: "git-abc123" },
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.CURRENT);
+  });
+
+  it("handles null library version (no comparison, falls through to SHA check)", () => {
+    // libraryVersion null → can't decide stale → falls through to
+    // SHA comparison. With matching SHAs, we're current.
+    const result = computeSkillState({
+      libraryVersion: null,
+      lastSyncEntry: BASELINE,
+      localPlacement: localPresence(),
+    });
+    assert.equal(result, SKILL_STATE.CURRENT);
+  });
+
+  it("treats null SHA on disk as EDITED when baseline is present", () => {
+    // If the walker couldn't compute a SHA for some reason (e.g.,
+    // permission error, malformed file) we should NOT claim current.
+    // Edited is the safe verdict.
+    const result = computeSkillState({
+      libraryVersion: "1.0.0",
+      lastSyncEntry: BASELINE,
+      localPlacement: { present: true, skillMdSha256: null, filesSha256: SHA_B },
+    });
+    assert.equal(result, SKILL_STATE.EDITED);
+  });
+});
+
+// ── rollupState ────────────────────────────────────────────────────────
+
+describe("rollupState", () => {
+  it("returns CURRENT when every vendor is current", () => {
+    assert.equal(
+      rollupState([SKILL_STATE.CURRENT, SKILL_STATE.CURRENT]),
+      SKILL_STATE.CURRENT,
+    );
+  });
+
+  it("returns STALE when one vendor is stale and rest are current", () => {
+    assert.equal(
+      rollupState([SKILL_STATE.CURRENT, SKILL_STATE.STALE]),
+      SKILL_STATE.STALE,
+    );
+  });
+
+  it("returns EDITED when one vendor is edited and rest are stale/current", () => {
+    assert.equal(
+      rollupState([SKILL_STATE.CURRENT, SKILL_STATE.STALE, SKILL_STATE.EDITED]),
+      SKILL_STATE.EDITED,
+    );
+  });
+
+  it("returns MISSING when any vendor is missing", () => {
+    // Worst-case wins. A skill that's current in Claude Code but
+    // missing from Cursor renders as `missing` so the user knows
+    // a vendor placement needs attention.
+    assert.equal(
+      rollupState([SKILL_STATE.CURRENT, SKILL_STATE.MISSING]),
+      SKILL_STATE.MISSING,
+    );
+  });
+
+  it("returns MISSING over EDITED, STALE, CURRENT (full precedence)", () => {
+    assert.equal(
+      rollupState([
+        SKILL_STATE.MISSING,
+        SKILL_STATE.EDITED,
+        SKILL_STATE.STALE,
+        SKILL_STATE.CURRENT,
+      ]),
+      SKILL_STATE.MISSING,
+    );
+  });
+
+  it("returns EDITED over STALE", () => {
+    assert.equal(
+      rollupState([SKILL_STATE.EDITED, SKILL_STATE.STALE]),
+      SKILL_STATE.EDITED,
+    );
+  });
+
+  it("returns STALE over CURRENT", () => {
+    assert.equal(
+      rollupState([SKILL_STATE.STALE, SKILL_STATE.CURRENT]),
+      SKILL_STATE.STALE,
+    );
+  });
+
+  it("returns MISSING on an empty array", () => {
+    assert.equal(rollupState([]), SKILL_STATE.MISSING);
+  });
+
+  it("returns MISSING when input is not an array", () => {
+    assert.equal(rollupState(null), SKILL_STATE.MISSING);
+    assert.equal(rollupState(undefined), SKILL_STATE.MISSING);
+  });
+
+  it("returns MISSING when input contains only unknown enum values", () => {
+    // Defensive fallback: a future state value or a typo shouldn't
+    // silently render as `current`. Bias toward the conservative
+    // verdict.
+    assert.equal(rollupState(["unknown-state", "weird"]), SKILL_STATE.MISSING);
+  });
+
+  it("ignores unknown values and reports the worst known state", () => {
+    // If the array mixes valid + unknown values, the worst valid
+    // state still wins.
+    assert.equal(
+      rollupState(["unknown", SKILL_STATE.STALE, "weird", SKILL_STATE.CURRENT]),
+      SKILL_STATE.STALE,
+    );
+  });
+});