skillrepo 4.5.0 → 4.5.1

package/src/test/integration/update-list-contract.integration.test.mjs

@@ -0,0 +1,1018 @@
+/**
+ * Cross-command integration: `update` → `list` contract.
+ *
+ * Why this file exists
+ * --------------------
+ * This is the test layer the v4.5.0 production-readiness review missed.
+ *
+ * The 4.5.0 staleness epic shipped two commands that share a contract:
+ *
+ *   `update` WRITES skills to disk under every vendor it targets.
+ *   `list`   READS those placements to compute per-skill drift state.
+ *
+ * The shared contract is the set of "detected vendors." If `update`
+ * writes to a smaller set than `list` walks, the list rolls up as
+ * MISSING for every multi-vendor user — exactly the production bug
+ * that triggered the 4.5.1 hotfix.
+ *
+ * Per-command unit tests (update.test.mjs + list.test.mjs) cannot
+ * surface this. They each fix one half of the contract and mock the
+ * other. Only an end-to-end test that runs `update` THEN reads the
+ * resulting `list` output catches a contract divergence. That's what
+ * this file is — the test that would have caught 4.5.1 pre-shipping.
+ *
+ * Test isolation
+ * --------------
+ * Every test runs inside a sandbox HOME so detection env vars are
+ * controlled, on-disk placements live in temp dirs, and the
+ * `.last-sync` state file is sandbox-local. The mock server stands in
+ * for the real registry. Detection signals are toggled via env vars
+ * documented in `agent-registry.mjs`:
+ *
+ *   - claudeCode: CLAUDECODE=1
+ *   - cursor:     CURSOR_AGENT=1
+ *
+ * Detection via `home`/`project` filesystem signals is also exercised
+ * implicitly when a test seeds `.claude/` or `.agents/` directories
+ * before invoking `update`.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runUpdate } from "../../commands/update.mjs";
+import { runList } from "../../commands/list.mjs";
+import { runGet } from "../../commands/get.mjs";
+import { runAdd } from "../../commands/add.mjs";
+import { runRemove } from "../../commands/remove.mjs";
+import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import { globalLastSyncPath } from "../../lib/paths.mjs";
+import { readLastSync } from "../../lib/sync.mjs";
+import { createMockServer } from "../e2e/mock-server.mjs";
+import { createCaptureStream } from "../helpers/capture-stream.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+} from "../helpers/sandbox-home.mjs";
+
+let sandbox;
+let server;
+let serverUrl;
+let originalCwd;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
+let stdout;
+const VALID_KEY = "sk_live_test";
+
+/**
+ * Build a registry skill payload with a single SKILL.md file. Same
+ * helper the unit tests use; replicated here so changes in either
+ * place don't silently break the other.
+ */
+function makeSkill(owner, name, version = "1.0.0") {
+  const content = `---\nname: ${name}\ndescription: ${name} description\n---\n\nbody\n`;
+  return {
+    owner,
+    name,
+    version,
+    description: `${name} description`,
+    files: [
+      {
+        path: "SKILL.md",
+        content,
+        // Server-side SHAs are not used by the CLI for drift detection —
+        // the CLI re-computes from content on disk. Any non-empty
+        // placeholder works.
+        sha256: "x",
+        size: content.length,
+        contentType: "text/markdown",
+      },
+    ],
+    updatedAt: "2025-01-01T12:00:00Z",
+  };
+}
+
+async function setup() {
+  sandbox = mkdtempSync(join(tmpdir(), "cli-int-update-list-"));
+  mkdirSync(join(sandbox, "project"), { recursive: true });
+  mkdirSync(join(sandbox, "home"), { recursive: true });
+  originalCwd = process.cwd();
+  originalHomeEnv = captureHome();
+  process.chdir(join(sandbox, "project"));
+  setSandboxHome(join(sandbox, "home"));
+
+  // Strip any inherited credentials/detection that would otherwise
+  // pollute the test's controlled environment.
+  delete process.env.SKILLREPO_ACCESS_KEY;
+  delete process.env.SKILLREPO_URL;
+  delete process.env.CLAUDECODE;
+  delete process.env.CURSOR_AGENT;
+  delete process.env.CURSOR_CLI;
+
+  server = createMockServer({});
+  const port = await server.start();
+  serverUrl = `http://127.0.0.1:${port}`;
+
+  stdout = createCaptureStream();
+}
+
+async function teardown() {
+  if (server) await server.stop();
+  process.chdir(originalCwd);
+  restoreHome(originalHomeEnv);
+  delete process.env.CLAUDECODE;
+  delete process.env.CURSOR_AGENT;
+  delete process.env.CURSOR_CLI;
+  if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  server = null;
+}
+
+// ───────────────────────────────────────────────────────────────────────
+// The 4.5.1 regression suite
+// ───────────────────────────────────────────────────────────────────────
+//
+// The bug: `effectiveVendors` defaulted to `["claudeCode"]` when no
+// `--agent` was passed, so `skillrepo update` (with no flags) wrote
+// ONLY to claudeCode's placement. Meanwhile, `skillrepo list` walked
+// EVERY detected vendor's placement. Result for multi-agent users:
+// every skill rolled up as MISSING for every vendor that wasn't
+// Claude Code.
+//
+// The fix: `effectiveVendors` now defaults to every detected vendor
+// (DI-injectable for testability). These tests prove the new contract
+// end-to-end.
+
+describe("update → list cross-command contract (#1574)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("multi-vendor: update with no --agent writes to every detected vendor (no MISS in list)", async () => {
+    // ── Forcing detection of TWO vendors ─────────────────────────────
+    // This is the exact production scenario behind 4.5.1: a user with
+    // both Claude Code AND Cursor installed runs `skillrepo update`
+    // with no `--agent`. Pre-fix, only claudeCode got the files. We
+    // assert both placements receive the skill AND that `list` agrees.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "shared-skill", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    // ── Step 1: update with no --agent ───────────────────────────────
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Both placements must exist on disk — the contract claim.
+    const claudeDir = resolvePlacementDir("claudeProject", "shared-skill");
+    const agentsDir = resolvePlacementDir("agentsProject", "shared-skill");
+    assert.ok(existsSync(claudeDir), "claudeProject placement must be written");
+    assert.ok(existsSync(agentsDir), "agentsProject (cursor) placement must be written");
+
+    // Same bytes in both placements — sync writes identical content,
+    // not a stub. A future regression that wrote to multiple targets
+    // but produced divergent content would break list's drift check
+    // and surface here.
+    const claudeBody = readFileSync(join(claudeDir, "SKILL.md"), "utf-8");
+    const agentsBody = readFileSync(join(agentsDir, "SKILL.md"), "utf-8");
+    assert.equal(claudeBody, agentsBody, "writes to multiple targets must produce identical content");
+
+    // ── Step 2: list reads the same placements ───────────────────────
+    // Use --json so we can assert the per-placement state directly.
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.name, "shared-skill");
+    // The rollup: both placements are current → rollup is current.
+    // Pre-fix this was "missing" because cursor's placement was empty.
+    assert.equal(item.state, "current", "rollup must be `current` when every detected vendor has the skill");
+    // Lock in the EXACT vendor count. Without this assertion a
+    // regression that over-detects (e.g., a future change that
+    // defaults to ALL seven registry entries instead of detected-only)
+    // would still pass the per-vendor `state === "current"` checks
+    // below because both claudeCode and cursor would land in the
+    // list. The `.length === 2` check catches the over-detection
+    // direction; the test above already catches under-detection.
+    assert.equal(
+      item.placements.length,
+      2,
+      "list must walk exactly the two detected vendors, not every registered one",
+    );
+    // Each vendor's placement entry reports current independently.
+    const byVendor = Object.fromEntries(item.placements.map((p) => [p.vendor, p]));
+    assert.ok(byVendor.claudeCode, "claudeCode placement must appear");
+    assert.ok(byVendor.cursor, "cursor placement must appear");
+    assert.equal(byVendor.claudeCode.state, "current");
+    assert.equal(byVendor.cursor.state, "current");
+  });
+
+  it("single-vendor: update with only cursor detected → list shows current for cursor only", async () => {
+    // The narrow contract: only the one detected vendor gets the
+    // placement, AND `list` afterwards reports `current` for that
+    // vendor — no phantom MISS for claudeCode.
+    //
+    // This test used to opt out of the `list` assertion because of a
+    // companion bug: writing `~/.claude/skillrepo/.last-sync`
+    // created `~/.claude/`, which then matched claudeCode's home
+    // detection signal. PR #1574's production-readiness audit
+    // narrowed that signal to `~/.claude/settings.json` (a file
+    // Claude Code itself creates, that SkillRepo never writes) so
+    // the false positive no longer fires. This test is now the
+    // regression guard: a Cursor-only user must see `list` reporting
+    // their skills as `current`, NOT all-MISS for a vendor they
+    // don't use.
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "cursor-only", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Only cursor's placement exists.
+    assert.ok(
+      existsSync(resolvePlacementDir("agentsProject", "cursor-only")),
+      "agentsProject placement should exist for cursor",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("claudeProject", "cursor-only")),
+      false,
+      "claudeProject placement should NOT exist when claudeCode is not detected at update-time",
+    );
+
+    // `list` now correctly sees ONE detected vendor and reports
+    // `current`. The false-positive claudeCode detection that
+    // shipped in 4.5.0/4.5.1 produced all-MISS output here.
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+    assert.equal(
+      item.placements.length,
+      1,
+      "Cursor-only user must not see a phantom claudeCode placement entry",
+    );
+    assert.equal(item.placements[0].vendor, "cursor");
+    assert.equal(item.placements[0].state, "current");
+  });
+
+  it("no-detection fallback: update with no --agent uses the historical claudeCode default", async () => {
+    // The other edge of the fix: if NOTHING is detected (no env vars,
+    // no `.claude/` or `.agents/` dirs anywhere), the CLI falls back
+    // to writing claudeCode-only — preserving the pre-4.5.1 behavior
+    // for first-run users. Without this fallback, a brand-new
+    // checkout in a clean shell would silently no-op `update` because
+    // detection returned an empty list.
+    //
+    // We don't set ANY env vars. The sandbox HOME is brand-new
+    // (no .claude / no .cursor / no .agents).
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "fallback", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // claudeProject is the documented fallback target.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "fallback")),
+      "fallback to claudeProject must hold when nothing is detected",
+    );
+  });
+
+  it("explicit --agent narrows the write set even when more vendors are detected", async () => {
+    // The explicit-flag escape hatch: even if both vendors are
+    // detected, `--agent claude` (or `--agent cursor`) writes only
+    // to the named vendor. `effectiveVendors` returns the explicit
+    // list verbatim — detection is ONLY consulted when no --agent
+    // is passed.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "narrowed", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"],
+      { stdout },
+    );
+
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "narrowed")));
+    // cursor's placement must NOT be written, even though cursor
+    // is detected. Explicit > implicit.
+    assert.equal(
+      existsSync(resolvePlacementDir("agentsProject", "narrowed")),
+      false,
+      "--agent claude must NOT incidentally write to cursor's placement",
+    );
+  });
+
+  it("explicit --agent ALSO has the listed vendor appear in list when detected", async () => {
+    // Defense-in-depth check: a user can run `update --agent claude`
+    // on a multi-vendor machine and `list` will still walk EVERY
+    // detected vendor (including cursor) and surface cursor's
+    // placement as MISS — that's the correct user-visible signal that
+    // their explicit-narrow update left a vendor un-updated.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "explicit", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    server.setEtag('"v1"');
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--agent", "claude"],
+      { stdout },
+    );
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    // Cursor's placement is empty → its per-vendor state is missing
+    // → rollup is missing (worst state wins). User sees a clear
+    // signal that one of their vendors didn't get the update.
+    assert.equal(item.state, "missing");
+    const cursor = item.placements.find((p) => p.vendor === "cursor");
+    assert.ok(cursor, "list must still include cursor's placement entry");
+    assert.equal(cursor.state, "missing");
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// .last-sync v1 → v2 migration round-trip
+// ───────────────────────────────────────────────────────────────────────
+//
+// A user upgrading from 4.4.x to 4.5.x has a v1 `.last-sync` on disk.
+// The new CLI must:
+//   1. Read it without crashing.
+//   2. Preserve the etag + syncedAt so the next sync still benefits
+//      from a 304 short-circuit.
+//   3. After the next successful sync, write a v2 file with the
+//      per-skill SHA map populated.
+//
+// Sync.test.mjs has unit-level coverage. This integration test
+// exercises the path through runSync against the mock server, which
+// is the only way to verify the v2 file that lands on disk has the
+// expected shape AND the ETag carry-forward took effect.
+
+describe("v1 → v2 .last-sync migration round-trip", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("reads v1 .last-sync, performs sync, writes v2 with SHA map populated", async () => {
+    // Seed a v1 state file at the documented path. Both fields are
+    // strings — that's the v1 shape `readLastSync` migrates from.
+    const v1Path = globalLastSyncPath();
+    mkdirSync(join(v1Path, ".."), { recursive: true });
+    writeFileSync(
+      v1Path,
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"v1-etag"',
+        syncedAt: "2025-12-01T00:00:00Z",
+      }),
+    );
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v2-etag"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "migrated", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    // ── Run update — this triggers the v1→v2 in-memory migration
+    //    in readLastSync and the v2 write at the end of runSync ──
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // The on-disk file must now be v2 and carry the per-skill SHA
+    // map. The pre-existing v1 etag/syncedAt are NOT preserved
+    // because the sync actually completed and got a fresh ETag from
+    // the server. Carry-forward applies to the per-skill SHA map
+    // (which was empty in v1), not to the library ETag itself.
+    const afterRaw = readFileSync(v1Path, "utf-8");
+    const after = JSON.parse(afterRaw);
+    assert.equal(after.schemaVersion, 2, "must persist as v2");
+    assert.equal(after.etag, '"v2-etag"', "etag must reflect server's response");
+    assert.ok(
+      after.skills && typeof after.skills === "object",
+      "skills map must be populated",
+    );
+    assert.ok(after.skills["alice/migrated"], "synced skill must appear in the SHA map");
+    const entry = after.skills["alice/migrated"];
+    assert.equal(entry.version, "1.0.0");
+    assert.match(entry.skillMdSha256, /^[a-f0-9]{64}$/, "skillMdSha256 must be a hex SHA-256");
+    assert.match(entry.filesSha256, /^[a-f0-9]{64}$/, "filesSha256 must be a hex SHA-256");
+  });
+
+  it("v1 state with NO content changes (304) preserves the etag and lets list see the upgrade transparently", async () => {
+    // Edge case: user upgrades, runs update, server returns 304 (no
+    // changes). The v1 etag was carried into the in-memory v2 shape
+    // so the 304 fires. No writeLastSync happens on 304 — so the
+    // on-disk file STAYS v1 until something actually changes. This
+    // is the documented behavior; the test makes it explicit so a
+    // future "always rewrite on 304" change would surface here.
+    const v1Path = globalLastSyncPath();
+    mkdirSync(join(v1Path, ".."), { recursive: true });
+    writeFileSync(
+      v1Path,
+      JSON.stringify({
+        schemaVersion: 1,
+        etag: '"unchanged"',
+        syncedAt: "2025-12-01T00:00:00Z",
+      }),
+    );
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"unchanged"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "unmigrated", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    // Force a 304 — the mock server's `setEtag('"unchanged"')`
+    // combined with the v1 etag triggers the conditional short-circuit.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(stdout.text(), /up to date/, "304 should produce the up-to-date message");
+
+    // The on-disk file stayed v1 because runSync's 304 branch
+    // doesn't write. readLastSync's in-memory migration is what kept
+    // the conditional request behaving correctly.
+    const afterRaw = readFileSync(v1Path, "utf-8");
+    const after = JSON.parse(afterRaw);
+    assert.equal(after.schemaVersion, 1, "304 should leave the v1 file untouched on disk");
+
+    // But — the migrated in-memory shape is what `list` consumes.
+    // Calling readLastSync directly should return the v2 shape
+    // (synthesized from v1 + empty skills map). The integration
+    // contract is: any reader on the new CLI sees a v2 shape, even
+    // if the file on disk is still v1.
+    const migrated = readLastSync();
+    assert.equal(migrated.schemaVersion, 2);
+    assert.equal(migrated.etag, '"unchanged"');
+    assert.deepEqual(migrated.skills, {});
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// End-to-end drift state through the real update path
+// ───────────────────────────────────────────────────────────────────────
+//
+// list.test.mjs synthesizes `.last-sync` and disk state by hand to
+// exercise each drift state. Those tests prove computeSkillState is
+// correct given a state. They do NOT prove that the state runSync
+// actually persists, when fed back into list, yields the expected
+// classification.
+//
+// These tests run a real update first, then mutate something, then
+// run list. They lock in the round-trip from update → on-disk state
+// → list → drift verdict — which is the only layer where a mismatch
+// between sync's persisted shape and list's expected shape would
+// surface as a user-visible bug.
+
+describe("update → mutate → list: drift verdicts on real persisted state", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("OK after update: a freshly synced skill is `current` in list with no mutation", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "fresh", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+  });
+
+  it("EDIT after update: hand-edit a SKILL.md and list shows `edited`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "tampered", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Append a line to SKILL.md — the persisted SHA in .last-sync
+    // no longer matches the on-disk SHA. drift.mjs's contract is
+    // "version match + SHA mismatch → edited."
+    const skillPath = join(
+      resolvePlacementDir("claudeProject", "tampered"),
+      "SKILL.md",
+    );
+    const original = readFileSync(skillPath, "utf-8");
+    writeFileSync(skillPath, original + "\n<!-- user edit -->\n");
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "edited", "post-update hand-edit must surface as `edited`");
+  });
+
+  it("STALE after update: server bumps version and list shows `stale`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "aging", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Server's library moves forward: same skill, new version. No
+    // second `update` happens — `.last-sync` still shows 1.0.0 as
+    // synced.
+    server.setEtag('"v2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "aging", "1.1.0")],
+      removals: [],
+      syncedAt: "2026-05-19T01:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "stale", "library moved ahead → `stale`");
+  });
+
+  it("MISSING after update + manual delete: removing a placement makes list show `missing`", async () => {
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "deletable", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Delete the placement directory the user just synced. .last-sync
+    // still records this skill as present (the SHA map remembers it)
+    // but the disk no longer has it — drift.mjs's contract is
+    // "baseline exists + on-disk gone → missing."
+    rmSync(resolvePlacementDir("claudeProject", "deletable"), {
+      recursive: true,
+      force: true,
+    });
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "missing");
+  });
+
+  it("multi-vendor mixed drift: claudeCode edited + cursor current rolls up to `edited` (worst-state-wins)", async () => {
+    // The rollup contract is "worst state wins" — defined in
+    // drift.mjs's `rollupState`. End-to-end coverage proves the
+    // contract holds when both placements go through the real
+    // update + list path, not just the synthesized state path.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "split-drift", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Edit ONLY the claudeCode placement.
+    const claudeFile = join(
+      resolvePlacementDir("claudeProject", "split-drift"),
+      "SKILL.md",
+    );
+    writeFileSync(claudeFile, readFileSync(claudeFile, "utf-8") + "// drift\n");
+
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+
+    // Rollup: edited vs current → edited (worst wins). The user-
+    // visible signal is "something needs attention" even though one
+    // vendor is fine.
+    assert.equal(item.state, "edited");
+    const byVendor = Object.fromEntries(item.placements.map((p) => [p.vendor, p]));
+    assert.equal(byVendor.claudeCode.state, "edited");
+    assert.equal(byVendor.cursor.state, "current");
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// `get` / `add` / `remove` write-back to `.last-sync`
+// ───────────────────────────────────────────────────────────────────────
+//
+// The 4.5.1 effective-vendors fix was a write-side contract gap. PR
+// #1574's production-readiness audit surfaced THREE more of the same
+// shape: `get`, `add`, and `remove` write to disk via `writeSkillDir`
+// (or `removeSkillDir`) but never updated `.last-sync` — so the very
+// next `list` reported every freshly-fetched / freshly-added skill as
+// `MISSING` even though it was sitting right there on disk. These
+// tests lock in the closed contract.
+
+describe("get → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `get`, list reports the skill as current (not MISSING)", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // Prime `.last-sync` with one prior-synced skill so we can also
+    // verify that `get` doesn't clobber existing entries.
+    server.setEtag('"baseline"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "prior-sync", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Now `get` a different skill that's NOT in the library
+    // response yet. The mock server serves it from setSkillResponse.
+    server.setSkillResponse(
+      "bob",
+      "fetched",
+      makeSkill("bob", "fetched", "1.0.0"),
+    );
+    stdout = createCaptureStream();
+    await runGet(
+      ["@bob/fetched", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Server's library now reports both skills (the maintainer
+    // published `bob/fetched` to the catalog). list must see both
+    // as `current` — the freshly-fetched one IS on disk and IS in
+    // the baseline.
+    server.setEtag('"baseline+1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "prior-sync", "1.0.0"),
+        makeSkill("bob", "fetched", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-02T00:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const parsed = JSON.parse(stdout.text());
+    const prior = parsed.find((s) => s.name === "prior-sync");
+    const fetched = parsed.find((s) => s.name === "fetched");
+    assert.equal(prior.state, "current", "prior-synced skill must stay current");
+    assert.equal(
+      fetched.state,
+      "current",
+      "skill fetched via `get` must show as current — get must update .last-sync",
+    );
+  });
+
+  it("get preserves the library-level etag (next update can still 304)", async () => {
+    // Critical invariant: `get` updates the per-skill SHA entry but
+    // leaves the library-level `etag` and `syncedAt` alone. If `get`
+    // clobbered the etag, the next `update` would do a wasted full
+    // sync. This test guards that behavior.
+    process.env.CLAUDECODE = "1";
+
+    server.setEtag('"original-etag"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "prior", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    server.setSkillResponse("bob", "extra", makeSkill("bob", "extra", "1.0.0"));
+    await runGet(
+      ["@bob/extra", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Read the persisted state directly — the etag/syncedAt must
+    // match what the prior update wrote, not what `get` happened to
+    // synthesize.
+    const after = readLastSync();
+    assert.equal(after.etag, '"original-etag"', "get must not clobber the library etag");
+    assert.equal(
+      after.syncedAt,
+      "2026-01-01T00:00:00Z",
+      "get must not clobber the library syncedAt",
+    );
+    // The new skill entry IS in the map alongside the prior entry.
+    assert.ok(after.skills["alice/prior"], "prior entry preserved");
+    assert.ok(after.skills["bob/extra"], "newly-fetched entry recorded");
+  });
+});
+
+describe("add → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `add`, list reports the skill as current (not MISSING)", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // `add` does POST /library/refs THEN GET /skills/<owner>/<name>.
+    // Both need responses on the mock server.
+    server.setAddResponseForAny({
+      status: 201,
+      body: {
+        added: {
+          owner: "carol",
+          name: "added-skill",
+          version: "2.0.0",
+          addedAt: "2026-01-01T00:00:00Z",
+        },
+      },
+    });
+    server.setSkillResponse(
+      "carol",
+      "added-skill",
+      makeSkill("carol", "added-skill", "2.0.0"),
+    );
+
+    await runAdd(
+      ["@carol/added-skill", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // Subsequent list with the catalog now showing the same skill —
+    // it should report as `current`.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("carol", "added-skill", "2.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.name, "added-skill");
+    assert.equal(
+      item.state,
+      "current",
+      "skill added via `add` must show as current — add must update .last-sync",
+    );
+  });
+});
+
+describe("remove → list cross-command contract", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("after `remove`, the skill's entry is purged from .last-sync", async () => {
+    process.env.CLAUDECODE = "1";
+
+    // Sync two skills, then remove one.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "keep", "1.0.0"),
+        makeSkill("alice", "drop", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Confirm both entries are present in .last-sync.
+    let state = readLastSync();
+    assert.ok(state.skills["alice/keep"]);
+    assert.ok(state.skills["alice/drop"]);
+
+    server.setRemoveResponseForAny({
+      status: 200,
+      body: { removed: { owner: "alice", name: "drop" } },
+    });
+    await runRemove(
+      ["@alice/drop", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+
+    // `alice/drop` is now absent from .last-sync; the kept skill is
+    // unaffected; the library-level etag is preserved (remove does
+    // NOT touch it).
+    state = readLastSync();
+    assert.ok(state.skills["alice/keep"], "kept skill's entry remains");
+    assert.equal(
+      state.skills["alice/drop"],
+      undefined,
+      "removed skill's entry must be purged",
+    );
+    assert.equal(state.etag, '"v1"', "remove must not clobber the library etag");
+  });
+
+  it("removing a skill that was never in .last-sync is idempotent (no throw, no spurious write)", async () => {
+    // Edge case: user runs `skillrepo remove @alice/never-synced`
+    // for a skill that was never on disk and was never tracked. The
+    // server returns 404 (not-in-library) but `remove` still tries
+    // to clean local files (which don't exist) and update
+    // `.last-sync` (which has no entry to remove). This must not
+    // throw and must not change the etag/syncedAt.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"unchanged"');
+    server.setLibraryResponse({
+      skills: [],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    server.setRemoveResponseForAny({
+      status: 404,
+      body: { error: "Skill not found", code: "not_found" },
+    });
+    await assert.doesNotReject(() =>
+      runRemove(
+        ["@alice/never-synced", "--key", VALID_KEY, "--url", serverUrl],
+        { stdout },
+      ),
+    );
+
+    const state = readLastSync();
+    assert.equal(state.etag, '"unchanged"');
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────
+// QA-flagged coverage gaps (from PR #1574 production-readiness audit)
+// ───────────────────────────────────────────────────────────────────────
+
+describe("additional coverage from production-readiness audit", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("corrupt .last-sync survives — runUpdate writes a fresh v2 file and list works", async () => {
+    // Real-world failure mode: a power loss mid-write leaves a
+    // partially-written `.last-sync` that won't parse as JSON.
+    // `readLastSync` returns null on parse failure (documented
+    // forward-compat behavior) and runSync performs a full re-sync.
+    // This test holds that contract — a future refactor that removes
+    // the try/catch and throws on parse error would break every user
+    // with a corrupt cache.
+    const path = globalLastSyncPath();
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, "CORRUPTED-NOT-JSON{{{", "utf-8");
+
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"fresh"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "recovered", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-19T00:00:00Z",
+    });
+
+    await assert.doesNotReject(
+      () => runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      "runUpdate must survive a corrupt .last-sync and complete the sync",
+    );
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.etag, '"fresh"');
+    assert.ok(after.skills["alice/recovered"]);
+  });
+
+  it("delta sync preserves entries the server didn't return in this round", async () => {
+    // The carry-forward contract. Server returns skill A on sync 1,
+    // then returns only skill B on sync 2 (delta — A didn't change).
+    // After sync 2, `.last-sync` must STILL contain A's SHA entry.
+    // Without this carry-forward, every delta sync shrinks the map
+    // until only the most-recently-touched skills remain — defeating
+    // list's drift detection for stable skills.
+    process.env.CLAUDECODE = "1";
+
+    // Sync 1: both A and B in the library.
+    server.setEtag('"sync1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "stable", "1.0.0"),
+        makeSkill("alice", "churning", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    let state = readLastSync();
+    assert.ok(state.skills["alice/stable"]);
+    assert.ok(state.skills["alice/churning"]);
+
+    // Sync 2: server returns ONLY the changed skill (delta). The
+    // stable skill is untouched. Note: production runSync sends
+    // `since` based on the persisted syncedAt; the mock server
+    // doesn't filter by `since`, so the test mimics the delta-only
+    // server response shape directly.
+    server.setEtag('"sync2"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "churning", "1.1.0")],
+      removals: [],
+      syncedAt: "2026-01-02T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    state = readLastSync();
+    assert.ok(
+      state.skills["alice/stable"],
+      "stable skill's entry must survive a delta sync that didn't return it",
+    );
+    assert.equal(state.skills["alice/churning"].version, "1.1.0");
+  });
+
+  it("three detected vendors all receive the skill (proves verbatim passthrough)", async () => {
+    // Earlier integration tests only cover two vendors. A hardcoded
+    // `["claudeCode", "cursor"]` impl would pass those — it would
+    // even produce both placements. This test forces three vendors
+    // (claudeCode + cursor + windsurf via CURSOR_AGENT + CLAUDECODE
+    // + the windsurf home signal). Detection returns three entries
+    // and `update` must write to all three.
+    process.env.CLAUDECODE = "1";
+    // Cursor needs its env signal AND its settings.json equivalent
+    // (cursor's home signal is `.cursor` which is a dir — cursor
+    // doesn't have the same `.claude` poisoning issue because we
+    // never write into `~/.cursor`).
+    process.env.CURSOR_AGENT = "1";
+    // Trigger windsurf detection via its home signal
+    // (`~/.codeium/windsurf/`). The dir-existing signal is the
+    // documented detection mechanism per the registry.
+    mkdirSync(join(process.env.HOME, ".codeium", "windsurf"), {
+      recursive: true,
+    });
+
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "everywhere", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-01-01T00:00:00Z",
+    });
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // All three vendors' placements must exist on disk. claudeCode
+    // writes to `.claude/skills/`. cursor + windsurf both share the
+    // `.agents/skills/` cohort placement target — one physical
+    // write satisfies both (placementTargetsFor dedupes by target).
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "everywhere")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "everywhere")));
+
+    // List walks every detected vendor independently. claudeCode,
+    // cursor, AND windsurf all have project targets (windsurf's
+    // project target is `agentsProject` per the registry — windsurf
+    // joins the cohort for project-scope skills, even though its
+    // personal-scope placement is at `~/.codeium/windsurf/skills/`).
+    // All three must appear in the JSON output, all `current`.
+    stdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(item.state, "current");
+    const vendors = item.placements.map((p) => p.vendor).sort();
+    assert.deepEqual(
+      vendors,
+      ["claudeCode", "cursor", "windsurf"],
+      "list must walk every detected vendor (3 in this case — proves no hardcoded pair)",
+    );
+    for (const p of item.placements) {
+      assert.equal(p.state, "current");
+    }
+  });
+});