skillrepo 2.0.0 → 3.1.0

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

@@ -0,0 +1,514 @@
+/**
+ * Unit tests for src/lib/sync.mjs (PR2 of #646).
+ *
+ * Strategy: spin up an in-process HTTP mock server with mutable
+ * library response, point sync.runSync at it, assert on the resulting
+ * filesystem state and the returned summary.
+ *
+ * Coverage:
+ *   • Empty library → no writes, summary all zeros
+ *   • Single skill → writeSkillDir called, added++
+ *   • Existing skill → writeSkillDir overwrites, updated++
+ *   • Tombstone → removeSkillDir called, removed++
+ *   • Both writes and tombstones in one sync
+ *   • ETag round-trip → second call short-circuits 304
+ *   • Last-sync state file persisted with correct schema
+ *   • Last-sync state file read on second call
+ *   • Corrupt last-sync state file is tolerated
+ *   • filesIncomplete skill is skipped AND ETag is NOT persisted
+ *   • Removals applied BEFORE writes (ordering matters for re-add)
+ *   • runSync rejects missing serverUrl/apiKey
+ *   • cleanupOrphans runs as part of sync (orphans gone after)
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+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 { createMockServer } from "../e2e/mock-server.mjs";
+
+let sandbox;
+let originalCwd;
+let originalHome;
+let server;
+let serverUrl;
+const VALID_KEY = "sk_live_test123";
+
+function makeSkill(name, content = `# ${name}\n`) {
+  return {
+    owner: "alice",
+    name,
+    version: "1.0.0",
+    description: `${name} skill`,
+    files: [
+      {
+        path: "SKILL.md",
+        content: `---\nname: ${name}\ndescription: Test skill ${name}\n---\n\n${content}`,
+        sha256: "x",
+        size: content.length,
+        contentType: "text/markdown",
+      },
+    ],
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+async function setupServer() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-sync-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHome = process.env.HOME;
+  process.chdir(join(sandbox, "project"));
+  process.env.HOME = join(sandbox, "home");
+
+  server = createMockServer({});
+  const port = await server.start();
+  serverUrl = `http://127.0.0.1:${port}`;
+}
+
+async function teardownServer() {
+  if (server) await server.stop();
+  process.chdir(originalCwd);
+  process.env.HOME = originalHome;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  server = null;
+}
+
+// ── Last-sync state file ───────────────────────────────────────────────
+
+describe("readLastSync / writeLastSync", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("returns null when state file does not exist", () => {
+    assert.equal(readLastSync(), null);
+  });
+
+  it("round-trips a valid state file", () => {
+    writeLastSync({ etag: '"abc123"', syncedAt: "2025-01-01T00:00:00Z" });
+    const result = readLastSync();
+    assert.equal(result.etag, '"abc123"');
+    assert.equal(result.syncedAt, "2025-01-01T00:00:00Z");
+    assert.equal(result.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
+  });
+
+  it("returns null on corrupt JSON", () => {
+    const path = globalLastSyncPath();
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(path, "not json {{{");
+    assert.equal(readLastSync(), null);
+  });
+
+  it("returns null on unknown schema version", () => {
+    writeLastSync({ etag: "x", syncedAt: "x" });
+    const path = globalLastSyncPath();
+    const obj = JSON.parse(readFileSync(path, "utf-8"));
+    obj.schemaVersion = 999;
+    writeFileSync(path, JSON.stringify(obj));
+    assert.equal(readLastSync(), null);
+  });
+
+  it("creates the parent directory if missing", () => {
+    rmSync(join(process.env.HOME, ".claude"), { recursive: true, force: true });
+    writeLastSync({ etag: "x", syncedAt: "x" });
+    assert.ok(existsSync(globalLastSyncPath()));
+  });
+});
+
+// ── runSync — empty library ────────────────────────────────────────────
+
+describe("runSync — empty library", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("returns all-zero summary for empty server response", async () => {
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(result.added, 0);
+    assert.equal(result.updated, 0);
+    assert.equal(result.removed, 0);
+    assert.equal(result.notModified, false);
+  });
+});
+
+// ── runSync — write skills ─────────────────────────────────────────────
+
+describe("runSync — write skills", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("writes a new skill and increments added", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(result.added, 1);
+    assert.equal(result.updated, 0);
+
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+  });
+
+  it("overwrites an existing skill and increments updated", async () => {
+    // First sync writes the skill
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper", "version 1")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // Clear state so the second sync doesn't 304-short-circuit
+    rmSync(globalLastSyncPath(), { force: true });
+
+    // Second sync overwrites with new content
+    server.setLibraryResponse({
+      skills: [makeSkill("pdf-helper", "version 2")],
+      removals: [],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.equal(result.added, 0);
+    assert.equal(result.updated, 1);
+
+    const dir = resolvePlacementDir("claudeProject", "pdf-helper");
+    const skillMd = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    assert.match(skillMd, /version 2/);
+  });
+
+  it("writes multiple skills in one sync", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("first"), makeSkill("second"), makeSkill("third")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(result.added, 3);
+  });
+
+  it("skips a filesIncomplete skill", async () => {
+    const incomplete = makeSkill("incomplete");
+    incomplete.filesIncomplete = true;
+    server.setLibraryResponse({
+      skills: [incomplete, makeSkill("complete")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    // Only `complete` was written
+    assert.equal(result.added, 1);
+    const incompleteDir = resolvePlacementDir("claudeProject", "incomplete");
+    assert.ok(!existsSync(incompleteDir));
+    const completeDir = resolvePlacementDir("claudeProject", "complete");
+    assert.ok(existsSync(completeDir));
+  });
+
+  it("does NOT persist ETag when any skill is filesIncomplete", async () => {
+    const incomplete = makeSkill("incomplete");
+    incomplete.filesIncomplete = true;
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [incomplete],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    // The next sync would re-fetch instead of short-circuiting
+    assert.equal(readLastSync(), null);
+  });
+});
+
+// ── runSync — tombstones ───────────────────────────────────────────────
+
+describe("runSync — tombstones", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("applies a tombstone and increments removed", async () => {
+    // Pre-write a skill
+    server.setLibraryResponse({
+      skills: [makeSkill("doomed")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "doomed")));
+
+    // Now the server says it's removed (the response has the tombstone
+    // AND the skill is no longer in skills[])
+    rmSync(globalLastSyncPath(), { force: true });
+    server.setLibraryResponse({
+      skills: [],
+      removals: [{ owner: "alice", name: "doomed", removedAt: "2025-01-02T00:00:00Z" }],
+      syncedAt: "2025-01-02T00:00:00Z",
+    });
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(result.removed, 1);
+    assert.ok(!existsSync(resolvePlacementDir("claudeProject", "doomed")));
+  });
+
+  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
+    // must apply the tombstone first so the new skill survives.
+    server.setLibraryResponse({
+      skills: [makeSkill("phoenix", "freshly re-added")],
+      removals: [{ owner: "alice", name: "phoenix", removedAt: "x" }],
+      syncedAt: "x",
+    });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    // The phoenix skill should EXIST because the write came after
+    // the removal, not the other way around.
+    const dir = resolvePlacementDir("claudeProject", "phoenix");
+    assert.ok(existsSync(join(dir, "SKILL.md")));
+    const skillMd = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    assert.match(skillMd, /freshly re-added/);
+  });
+});
+
+// ── runSync — ETag short-circuit ───────────────────────────────────────
+
+describe("runSync — ETag round-trip", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("first sync persists ETag, second sync 304s", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("first")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    const first = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(first.added, 1);
+    assert.equal(first.notModified, false);
+
+    // Second sync with same ETag → 304
+    const second = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    assert.equal(second.notModified, true);
+    assert.equal(second.added, 0);
+    assert.equal(second.updated, 0);
+    assert.equal(second.removed, 0);
+  });
+
+  it("304 short-circuit does not delete or modify on-disk skills", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("staying")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    const dir = resolvePlacementDir("claudeProject", "staying");
+    const before = readFileSync(join(dir, "SKILL.md"), "utf-8");
+
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    const after = readFileSync(join(dir, "SKILL.md"), "utf-8");
+    assert.equal(before, after);
+  });
+});
+
+// ── runSync — argument validation ──────────────────────────────────────
+
+describe("runSync — input validation", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("throws validationError when serverUrl is missing", async () => {
+    await assert.rejects(
+      () => runSync({ serverUrl: "", apiKey: VALID_KEY, vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("throws validationError when apiKey is missing", async () => {
+    await assert.rejects(
+      () => runSync({ serverUrl, apiKey: "", vendors: ["claudeCode"] }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_VALIDATION,
+    );
+  });
+
+  it("accepts io: null without crashing (round-2 review fix)", async () => {
+    // Regression for the round-2 finding both reviewers caught: the
+    // destructure default `io = {}` only handles `undefined`, so an
+    // explicit `io: null` would crash on the .stderr access. The
+    // sync.mjs fix coalesces null → {} via `io ?? {}`. This test
+    // confirms it.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      io: null,
+    });
+    // No throw → pass
+  });
+
+  it("accepts io: undefined as if io was omitted", async () => {
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+      io: undefined,
+    });
+  });
+});
+
+describe("runSync — io.stderr injection (round-3 coverage fix)", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("forwards the writeLastSync failure warning to io.stderr (not process.stderr)", { skip: process.platform === "win32" || process.getuid?.() === 0 }, async () => {
+    // Round-3 review found that the previous io: null test didn't
+    // actually exercise the writeLastSync failure path because the
+    // fixture had no ETag, so the `stderr.write(...)` branch was
+    // never reached. This test arranges for ALL of:
+    //   1. Server response has an ETag (so the persist branch runs)
+    //   2. writeLastSync is forced to fail (state dir is read-only)
+    //   3. io.stderr is an injected capture stream
+    // and asserts the warning lands on the injection target, NOT
+    // on process.stderr.
+
+    const { chmodSync } = await import("node:fs");
+    const { createCaptureStream } = await import("../helpers/capture-stream.mjs");
+    const { globalLastSyncPath } = await import("../../lib/paths.mjs");
+    const { dirname } = await import("node:path");
+
+    // Pre-create the state dir, then make it read-only so writeLastSync
+    // fails on the writeFileSync call.
+    const stateDir = dirname(globalLastSyncPath());
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(stateDir, { recursive: true });
+    chmodSync(stateDir, 0o555);
+
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("with-etag")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    const stderr = createCaptureStream();
+    try {
+      await runSync({
+        serverUrl,
+        apiKey: VALID_KEY,
+        vendors: ["claudeCode"],
+        io: { stderr },
+      });
+    } finally {
+      // Restore writable permissions so afterEach can clean up
+      chmodSync(stateDir, 0o755);
+    }
+
+    // The warning must have landed on the injected stream
+    assert.match(stderr.text(), /failed to persist last-sync state/);
+    assert.match(stderr.text(), /Next sync will be a full fetch/);
+  });
+
+  it("falls back to process.stderr when io.stderr is not provided", async () => {
+    // The flip side: when no io is passed, the warning still goes
+    // somewhere (process.stderr) rather than crashing. We don't
+    // assert on process.stderr's contents (that would require
+    // monkey-patching, which conflicts with node:test's IPC), but
+    // we do assert that runSync completes successfully.
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    // No throw → pass; the happy-path uses no warning so this is
+    // also covered by all the other tests, but explicit is good.
+  });
+});
+
+// ── runSync — orphan cleanup ───────────────────────────────────────────
+
+describe("runSync — orphan cleanup", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  it("cleans orphan .tmp/ with a live sibling before writing", async () => {
+    // Pre-write a skill so a stale .tmp/ has a live sibling
+    server.setLibraryResponse({
+      skills: [makeSkill("clean-me")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // Inject a stale .tmp/ from a "previous crash"
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(root, "clean-me.tmp"));
+    writeFileSync(join(root, "clean-me.tmp", "garbage.txt"), "x");
+
+    // Run sync again — the orphan cleanup should fire first
+    rmSync(globalLastSyncPath(), { force: true });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.ok(!existsSync(join(root, "clean-me.tmp")));
+  });
+
+  it("preserves orphan .tmp/ with NO live sibling (Windows recovery)", async () => {
+    // No live sibling — this .tmp/ is the user's only copy of a
+    // crashed-mid-rename skill. cleanupOrphans must preserve it.
+    const root = join(process.cwd(), ".claude", "skills");
+    mkdirSync(join(root, "recoverable.tmp"), { recursive: true });
+    writeFileSync(join(root, "recoverable.tmp", "SKILL.md"), "x");
+
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+    assert.ok(existsSync(join(root, "recoverable.tmp", "SKILL.md")));
+  });
+});