skillrepo 4.8.3 → 4.9.0

package/src/test/commands/update.test.mjs

@@ -18,7 +18,9 @@ import {
   writeLastSync,
   FULL_RESYNC_FLOOR,
   cliVersionBelowFloor,
+  LAST_SYNC_SCHEMA_VERSION,
 } from "../../lib/sync.mjs";
+import { globalLastSyncPath } from "../../lib/paths.mjs";
 import { CliError, EXIT_AUTH, EXIT_VALIDATION } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
@@ -689,3 +691,167 @@ describe("runUpdate — #1911 membership heal lands the skill on disk", () => {
     );
   });
 });
+
+// ── SessionStart throttle through the `update` command (#2174) ─────────
+//
+// The throttle lives in runSync, but what matters at the product boundary
+// is that `skillrepo update --session-hook` (Claude Code) and the
+// `--silent` cohort hook make ZERO HTTP calls when re-run within the
+// window, while a bare interactive `skillrepo update` always syncs. These
+// drive the real command entry point against the mock server's request
+// spies — the acceptance criterion, end to end.
+
+describe("runUpdate — SessionStart throttle (#2174)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("ACCEPTANCE: two `update --session-hook` runs within the window → the 2nd makes zero HTTP calls", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("throttle-me")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+
+    // Session 1: the hook runs a real sync (no prior attempt).
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.ok(server.getLibraryRequestCount() >= 1, "session 1 hit the library GET");
+    assert.match(stdout.text(), /Library synced/, "session 1 reports the sync");
+
+    // Session 2 (same 15-min window): the hook must make NO HTTP calls.
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+
+    assert.equal(
+      server.getLibraryRequestCount(),
+      0,
+      "throttled session makes NO library GET",
+    );
+    assert.equal(
+      server.getReceiptRequestCount(),
+      0,
+      "throttled session makes NO receipt POST",
+    );
+    assert.equal(
+      stdout.text(),
+      "",
+      "throttled session-hook stays silent (nothing changed to report)",
+    );
+  });
+
+  it("a bare interactive `skillrepo update` always syncs, even seconds after a hook sync", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("fresh")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Hook sync arms the throttle clock.
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    // Interactive `update` (no hook flag) must contact the server despite
+    // the fresh clock — explicit intent always syncs.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "interactive update is never throttled",
+    );
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "interactive 304 prints the up-to-date line",
+    );
+  });
+
+  it("the --silent cohort hook throttles too (2nd run: zero HTTP, still emits `{}`)", async () => {
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("cohort")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--silent"], { stdout });
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl, "--silent"], { stdout });
+    assert.equal(
+      server.getLibraryRequestCount(),
+      0,
+      "throttled --silent makes NO library GET",
+    );
+    assert.equal(
+      server.getReceiptRequestCount(),
+      0,
+      "throttled --silent makes NO receipt POST",
+    );
+    // The JSON hook contract still holds: stdout is exactly `{}` even when
+    // the sync was throttled away.
+    assert.equal(stdout.text(), "{}\n");
+  });
+
+  it("upgrade path: a real v2 .last-sync (etag + skills, no lastAttemptAt) → first hook sync proceeds and upgrades to v3", async () => {
+    // Every existing install upgrading to 4.9.0 hits exactly this state:
+    // a v2 file with a genuine etag/skills baseline written by the old
+    // CLI. The first --session-hook run after upgrade must NOT throttle
+    // (no lastAttemptAt = never attempted), must keep the cheap 304 (etag
+    // preserved in place), and must leave a v3 file with the stamp.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("veteran")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    // Arm a fully-populated state via a real sync, then rewrite it as the
+    // v2 shape a pre-#2174 CLI would have left behind.
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    const prior = readLastSync();
+    const v2File = {
+      schemaVersion: 2,
+      etag: prior.etag,
+      syncedAt: prior.syncedAt,
+      cliVersion: prior.cliVersion,
+      skills: prior.skills,
+    };
+    writeFileSync(globalLastSyncPath(), JSON.stringify(v2File, null, 2) + "\n");
+    server.resetLibraryInspection();
+    server.resetReceipts();
+    stdout.clear();
+
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.ok(
+      server.getLibraryRequestCount() >= 1,
+      "first post-upgrade hook sync is NOT throttled (v2 = never attempted)",
+    );
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      prior.etag,
+      "the v2 etag was accepted in place — the post-upgrade sync stays a cheap 304",
+    );
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION, "file upgraded to v3");
+    assert.equal(typeof after.lastAttemptAt, "string", "throttle clock stamped");
+    assert.deepEqual(after.skills, prior.skills, "per-skill SHA baseline preserved");
+  });
+});

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

@@ -57,7 +57,7 @@ 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 { readLastSync, LAST_SYNC_SCHEMA_VERSION } from "../../lib/sync.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
 import {
@@ -391,11 +391,11 @@ describe("update → list cross-command contract (#1574)", () => {
 // 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", () => {
+describe("v1 → current-schema .last-sync migration round-trip", () => {
   beforeEach(setup);
   afterEach(teardown);
 
-  it("reads v1 .last-sync, performs sync, writes v2 with SHA map populated", async () => {
+  it("reads v1 .last-sync, performs sync, writes the current schema 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();
@@ -421,14 +421,18 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
     //    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
+    // The on-disk file must now carry the CURRENT schema and 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.schemaVersion,
+      LAST_SYNC_SCHEMA_VERSION,
+      "must persist as the current schema (v1 migrates forward on write)",
+    );
     assert.equal(after.etag, '"v2-etag"', "etag must reflect server's response");
     assert.ok(
       after.skills && typeof after.skills === "object",
@@ -502,11 +506,11 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
       "v1 migration must drop If-None-Match (placementsAreComplete returns false for empty map)",
     );
 
-    // After the recovery sync, the on-disk file is v2 with the
-    // skills map populated. The skill is on disk in the claudeProject
-    // placement — the user-visible recovery.
+    // After the recovery sync, the on-disk file carries the current
+    // schema with the skills map populated. The skill is on disk in the
+    // claudeProject placement — the user-visible recovery.
     const after = readLastSync();
-    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
     assert.ok(after.skills["alice/unmigrated"]);
     assert.ok(existsSync(resolvePlacementDir("claudeProject", "unmigrated")));
 
@@ -1014,7 +1018,7 @@ describe("additional coverage from production-readiness audit", () => {
       "runUpdate must survive a corrupt .last-sync and complete the sync",
     );
     const after = readLastSync();
-    assert.equal(after.schemaVersion, 2);
+    assert.equal(after.schemaVersion, LAST_SYNC_SCHEMA_VERSION);
     assert.equal(after.etag, '"fresh"');
     assert.ok(after.skills["alice/recovered"]);
   });

package/src/test/lib/http.test.mjs

@@ -1296,6 +1296,93 @@ describe("pushSkill", () => {
     }
   });
 
+  it("maps 422 handle_required to validationError with a Settings hint on the server's own host (#2310)", async () => {
+    const SERVER_MESSAGE = "Set your Author ID before adding skills.";
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 422, {
+        error: SERVER_MESSAGE,
+        code: "handle_required",
+      });
+    });
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill(srv.url, VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) =>
+          err instanceof CliError &&
+          err.exitCode === EXIT_VALIDATION &&
+          // Line 1: the server's message verbatim; line 2 (hint): the
+          // Settings path on the REQUEST host (staging users get a
+          // staging link), not hardcoded prod.
+          err.message === SERVER_MESSAGE &&
+          err.hint === `Set it in Settings → Account Profile: ${srv.url}/app/settings`,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("handle_required hint falls back to the prod host when the request URL is unparseable (#2310)", async () => {
+    // The `new URL(url)` origin-derivation inside the handle_required
+    // mapping can only throw if the URL that reached fetch was itself
+    // unparseable — impossible over a real socket (undici validates the
+    // URL before connecting), so stub fetch to hand back the 422
+    // directly. `normalizeUrl` passes any non-empty string through, so
+    // the raw serverUrl below reaches mapErrorResponse verbatim.
+    const SERVER_MESSAGE = "Set your Author ID before adding skills.";
+    const realFetch = globalThis.fetch;
+    globalThis.fetch = async () =>
+      new Response(
+        JSON.stringify({ error: SERVER_MESSAGE, code: "handle_required" }),
+        { status: 422, headers: { "Content-Type": "application/json" } },
+      );
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill("not a url", VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) =>
+          err instanceof CliError &&
+          err.exitCode === EXIT_VALIDATION &&
+          err.message === SERVER_MESSAGE &&
+          // Parse-failure fallback: the hint pins the prod host instead
+          // of the (unusable) request origin.
+          err.hint ===
+            "Set it in Settings → Account Profile: https://skillrepo.dev/app/settings",
+      );
+    } finally {
+      globalThis.fetch = realFetch;
+    }
+  });
+
+  it("does NOT special-case a 422 without the handle_required code (generic validation)", async () => {
+    // A 422 carrying a different code (e.g. idempotency_key_reused) must
+    // keep the pre-#2310 generic mapping: validationError, no Settings hint.
+    const srv = await makePushServer((req, res) => {
+      jsonRes(res, 422, {
+        error: "Idempotency-Key was reused with a different request body.",
+        code: "idempotency_key_reused",
+      });
+    });
+    try {
+      await assert.rejects(
+        () =>
+          pushSkill(srv.url, VALID_KEY, {
+            files: [{ relativePath: "SKILL.md", content: SKILL_MD }],
+          }),
+        (err) =>
+          err instanceof CliError &&
+          err.exitCode === EXIT_VALIDATION &&
+          err.hint === undefined,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
   it("maps 413 payload_too_large through mapErrorResponse", async () => {
     const srv = await makePushServer((req, res) => {
       jsonRes(res, 413, {