skillrepo 4.8.0 → 4.8.2

package/bin/skillrepo.mjs

@@ -70,9 +70,12 @@ const COMMANDS = {
   },
   push: {
     description: "Push a local skill directory to your library (create or release new version)",
-    usage:
-      "skillrepo push <path> [--version <label>] [--changelog <text>] " +
-      "[--idempotency-key <key>] [--json]",
+    // Versioning is server-side (frontmatter-driven smart upsert), so the CLI
+    // does NOT accept --version/--changelog — they were removed in the #1455
+    // push rework. Do not re-add them here without wiring them into push.mjs:
+    // the advertised-surface contract test asserts every flag listed in this
+    // string is actually accepted by the command (#1923).
+    usage: "skillrepo push <path> [--idempotency-key <key>] [--json]",
     run: async (argv) => runPush(argv),
   },
   publish: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/add.mjs

@@ -27,7 +27,8 @@
  *   - 404 not-found → clean error, exit 5
  *   - 409 self-ownership → clean error, exit 5 ("you can't add your
  *     own skill to your own library")
- *   - 403 plan-limit → validationError (via http.mjs) with billing hint
+ *   - 403 plan-limit → validationError (via http.mjs); the server
+ *     message carries the per-cap remedy (no CLI-side hint, #2239)
  *   - 403 scope → scopeError (via http.mjs) with write-key hint
  *
  * Flags: --global / --agent / --json / --key / --url

package/src/commands/init.mjs

@@ -199,13 +199,23 @@ const BLACK_HOLE_STREAM = {
  * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
  * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
  * @param {object} [deps] - Test-only dependency injection. Production
- *        callers leave this empty. Forwarded to step 6
- *        (`installSessionSyncHook`); see `init-session-sync.mjs` for
- *        the supported keys (`spawn`, `getCliVersion`, `confirmFn`).
+ *        callers leave this empty. `promptFn` (below) is consumed locally;
+ *        the remaining keys are forwarded to step 6
+ *        (`installSessionSyncHook`) — see `init-session-sync.mjs` for
+ *        those (`spawn`, `getCliVersion`, `confirmFn`).
+ * @param {Function} [deps.promptFn] - Override for the interactive
+ *        access-key prompt (`promptWithBrowserOpen`). Lets tests drive
+ *        the step-1 prompt and the step-2 stale-key re-prompt recovery
+ *        without a real TTY/stdin. Default: the real
+ *        `promptWithBrowserOpen`. Same test-seam pattern as `confirmFn`.
  */
 export async function runInit(argv, io = {}, deps = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
+  // Test-seam for the interactive credential prompt. Production uses the
+  // real browser-assisted prompt; tests inject a stub to exercise the
+  // step-1 and stale-key re-prompt paths deterministically.
+  const promptForKey = deps.promptFn ?? promptWithBrowserOpen;
 
   const { flags, yes, force, noSessionSync } = parseInitFlags(argv);
 
@@ -270,7 +280,7 @@ export async function runInit(argv, io = {}, deps = {}) {
         hint: "Pass --key sk_live_... or set SKILLREPO_ACCESS_KEY.",
       });
     }
-    apiKey = await promptWithBrowserOpen(
+    apiKey = await promptForKey(
       cliAuthUrl(serverUrl),
       "Enter your access key (sk_live_...)",
     );
@@ -343,7 +353,7 @@ export async function runInit(argv, io = {}, deps = {}) {
     ) {
       p.warning("Existing config has an invalid key. Re-prompting for a new one.");
       apiKey = (
-        await promptWithBrowserOpen(
+        await promptForKey(
           cliAuthUrl(serverUrl),
           "Enter your access key (sk_live_...)",
         )

package/src/lib/http.mjs

@@ -339,7 +339,7 @@ async function mapErrorResponse(res, url) {
     //      `src/app/api/v1/library/route.ts:226-235`. The route comment
     //      EXPLICITLY documents that the CLI must distinguish this from
     //      scope errors. We map it to `validationError` (exit 5) with a
-    //      hint pointing at billing — it is not a key-permission issue
+    //      no CLI-side hint — it is not a key-permission issue
     //      so neither authError nor scopeError is the right fit, and
     //      adding a dedicated planLimitError to the exit code matrix is
     //      out of scope for v3.0.0.
@@ -350,9 +350,13 @@ async function mapErrorResponse(res, url) {
     //   3. Generic 403 — suspended account, blocked user, etc. Maps to
     //      authError with a "contact support" hint.
     if (typeof code === "string" && code === "plan_limit") {
-      return validationError(message, {
-        hint: "Upgrade your plan at /app/settings/billing or remove an existing skill from your library.",
-      });
+      // No CLI-side hint: the server's plan_limit message now states the
+      // limit AND the correct remedy for the specific cap that fired
+      // (skills "Delete one to add another.", library "Remove one to add
+      // another.", cap-0 "A personal library isn't included in your
+      // plan."). A generic hint here either duplicates it or — for the
+      // cap-0 tier — contradicts it (#2239 round-2 review).
+      return validationError(message);
     }
     if (typeof code === "string" && code.toLowerCase().includes("scope")) {
       return scopeError(message, {
@@ -1118,9 +1122,19 @@ export async function searchSkills(serverUrl, apiKey, opts = {}) {
   }
 
   const body = await parseJsonOrThrow(res, url);
+  const skills = body.skills ?? [];
   return {
-    skills: body.skills ?? [],
-    pagination: body.pagination ?? { total: 0, limit: opts.limit ?? 20, offset: opts.offset ?? 0 },
+    skills,
+    // When the server omits pagination, default `total` to the number of
+    // skills actually returned — never 0 — so the displayed count can't
+    // contradict the visible rows (a fabricated total:0 made `search`
+    // print "0 results" beneath a result, and `--json` emit a total of 0
+    // alongside a non-empty `results`). #1923.
+    pagination: body.pagination ?? {
+      total: skills.length,
+      limit: opts.limit ?? 20,
+      offset: opts.offset ?? 0,
+    },
   };
 }
 
@@ -1223,7 +1237,7 @@ async function setSkillVisibility(serverUrl, apiKey, owner, name, target, option
   // CANNOT fall through to `mapErrorResponse` (which re-reads the
   // body and would get an empty object — a `plan_limit` 403 would
   // mis-classify as authError exit 2 instead of validationError
-  // exit 5 with billing hint). Pre-parse once, then dispatch every
+  // exit 5, message self-contained). Pre-parse once, then dispatch every
   // code path inline mirroring `mapErrorResponse`'s shape so the
   // CliError types stay consistent across endpoints.
   if (res.status === 403 || res.status === 422) {
@@ -1243,13 +1257,13 @@ async function setSkillVisibility(serverUrl, apiKey, owner, name, target, option
       }
       // Mirror `mapErrorResponse`'s 403 taxonomy so a 403 here behaves
       // identically to a 403 on any other endpoint:
-      //   - `plan_limit` → validationError (exit 5) with billing hint
+      //   - `plan_limit` → validationError (exit 5), server message only
       //   - any `*scope*` code → scopeError (exit 4)
       //   - everything else → authError (exit 2, "suspended" hint)
       if (code === "plan_limit") {
-        throw validationError(message, {
-          hint: "Upgrade your plan at /app/settings/billing or remove an existing skill from your library.",
-        });
+        // Same as mapErrorResponse: the server message is the complete,
+        // cap-specific remedy — no CLI hint (#2239 round-2 review).
+        throw validationError(message);
       }
       if (code && code.toLowerCase().includes("scope")) {
         throw scopeError(message, {

package/src/test/commands/add.test.mjs

@@ -4,12 +4,13 @@
 
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { runAdd } from "../../commands/add.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
+import { writeLastSync } from "../../lib/sync.mjs";
 import { CliError, EXIT_VALIDATION, EXIT_AUTH, EXIT_SCOPE } from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
@@ -234,7 +235,7 @@ describe("runAdd — error paths", () => {
     );
   });
 
-  it("403 plan-limit maps to validationError with billing hint", async () => {
+  it("403 plan-limit maps to validationError (server message self-contained, no hint)", async () => {
     server.setAddResponse("alice", "limit-test", {
       status: 403,
       body: {
@@ -304,3 +305,79 @@ describe("runAdd — error paths", () => {
     );
   });
 });
+
+// ── #1911 bypass: add must NOT delta-filter ───────────────────────────
+//
+// add.mjs deliberately uses a single-skill GET (not runSync) precisely
+// so a skill whose content predates the user's last sync still lands —
+// the original #1911 trigger was an established user adding an OLDER
+// catalog skill and relying on delta sync, which silently dropped it.
+// add's whole protective property is "I never apply `since` filtering."
+// This was untested at the command layer; lock it.
+describe("runAdd — #1911 bypass: a skill older than last sync still lands", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("writes a skill whose updatedAt predates .last-sync.syncedAt, bypassing the delta endpoint", async () => {
+    // Seed a RECENT last sync — newer than the skill we're about to add.
+    // If `add` ever regressed to delta semantics, `updatedAt < since`
+    // would filter this skill out and it would never reach disk.
+    writeLastSync({
+      etag: '"lib-v9"',
+      syncedAt: "2099-01-01T00:00:00Z",
+      skills: {},
+    });
+    server.resetLibraryInspection();
+
+    // The catalog skill is OLD content (updatedAt years before `since`).
+    server.setSkillResponse("alice", "old-skill", {
+      ...makeSkill("alice", "old-skill"),
+      updatedAt: "2020-01-01T00:00:00Z",
+    });
+
+    await runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/old-skill"], { stdout });
+
+    assert.ok(
+      existsSync(join(resolvePlacementDir("claudeProject", "old-skill"), "SKILL.md")),
+      "an older-than-last-sync skill MUST land on disk via `add`",
+    );
+    // The protective invariant: add never touched the delta-filtered
+    // library endpoint, so `since` could not have dropped the skill.
+    assert.equal(
+      server.getLibraryRequestCount(),
+      0,
+      "add must bypass GET /library entirely (no `since` filter can apply)",
+    );
+    assert.match(stdout.text(), /Added @alice\/old-skill/);
+  });
+});
+
+// ── Best-effort .last-sync write (#1574 contract) ─────────────────────
+describe("runAdd — best-effort .last-sync write failure does not fail the command", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("adds the skill and exits cleanly even when the .last-sync state write throws", async () => {
+    // Same mechanism as get: occupy the global skillrepo state-dir path
+    // with a file so the upsertLastSyncEntry → writeLastSync write throws
+    // a diskError. add's whole job (POST + fetch + write the skill to the
+    // project placement) must still succeed; the state write is
+    // best-effort and the throw must be swallowed.
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    writeFileSync(join(process.env.HOME, ".claude", "skillrepo"), "not-a-dir");
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+
+    await assert.doesNotReject(
+      () =>
+        runAdd(
+          ["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper", "--agent", "claude"],
+          { stdout },
+        ),
+      "a .last-sync write failure must NOT fail `add` after the skill files landed",
+    );
+    assert.ok(
+      existsSync(join(resolvePlacementDir("claudeProject", "pdf-helper"), "SKILL.md")),
+      "the skill files must still be on disk despite the state-write failure",
+    );
+  });
+});

package/src/test/commands/get.test.mjs

@@ -4,13 +4,19 @@
 
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { runGet } from "../../commands/get.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
-import { CliError, EXIT_VALIDATION } from "../../lib/errors.mjs";
+import {
+  CliError,
+  EXIT_VALIDATION,
+  EXIT_AUTH,
+  EXIT_SCOPE,
+  EXIT_NETWORK,
+} from "../../lib/errors.mjs";
 import { createMockServer } from "../e2e/mock-server.mjs";
 import { createCaptureStream } from "../helpers/capture-stream.mjs";
 import {
@@ -180,3 +186,126 @@ describe("runGet — error paths", () => {
     );
   });
 });
+
+// ── Coverage gap closure: --agent vectors + transport errors ───────────
+//
+// These mirror the equivalent vectors already locked in add.test.mjs
+// (`--agent none` rejection, `--agent cursor` placement, 401/403/network
+// transport mapping). `get` and `add` share `requireVendorTargets` and
+// the `http.mjs` error mapping, so the assertions here assert the SAME
+// advertised contract: exit 5 for the no-op flag, exit 2/4 for auth/scope,
+// exit 1 for a network failure, and the cohort `.agents/skills/` placement
+// for `--agent cursor`.
+describe("runGet — --agent flag + transport error paths", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("rejects --agent none with a validation error (no targets to write)", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await assert.rejects(
+      () =>
+        runGet(
+          ["--key", VALID_KEY, "--url", serverUrl, "--agent", "none", "@alice/pdf-helper"],
+          { stdout },
+        ),
+      (err) =>
+        err instanceof CliError &&
+        err.exitCode === EXIT_VALIDATION &&
+        /--agent none has no effect on `skillrepo get`/.test(err.message),
+    );
+  });
+
+  it("--agent cursor writes to the cohort .agents/skills/ placement, NOT the claude placement", async () => {
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runGet(
+      ["--key", VALID_KEY, "--url", serverUrl, "--agent", "cursor", "@alice/pdf-helper"],
+      { stdout },
+    );
+
+    // Landed in cursor's project target (.agents/skills/).
+    const agentsDir = resolvePlacementDir("agentsProject", "pdf-helper");
+    assert.ok(
+      existsSync(join(agentsDir, "SKILL.md")),
+      "--agent cursor must write the skill into .agents/skills/",
+    );
+
+    // Did NOT also write the Claude Code placement — the flag is scoped.
+    // This couples the assertion to the placement behavior: a regression
+    // that ignored --agent and defaulted to claudeProject would fail here.
+    const claudeDir = resolvePlacementDir("claudeProject", "pdf-helper");
+    assert.ok(
+      !existsSync(claudeDir),
+      "--agent cursor must NOT write the claude placement",
+    );
+  });
+
+  it("401 auth error exits 2", async () => {
+    // The single-skill GET route has no per-skill error slot, so force
+    // the next request (getSkill) to return 401 — the same outcome
+    // add.test.mjs reaches via setAddResponse(status: 401).
+    server.setForcedStatus(401, { error: "Invalid access key" });
+    await assert.rejects(
+      () => runGet(["--key", VALID_KEY, "--url", serverUrl, "@alice/auth-test"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_AUTH,
+    );
+  });
+
+  it("403 scope-required maps to scopeError (exit 4)", async () => {
+    // Mirror add.test.mjs's 403-scope response shape (code: scope_required).
+    server.setForcedStatus(403, { error: "Insufficient scope", code: "scope_required" });
+    await assert.rejects(
+      () => runGet(["--key", VALID_KEY, "--url", serverUrl, "@alice/scope-test"], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_SCOPE,
+    );
+  });
+
+  it("network failure exits 1 (network)", async () => {
+    // Point at a port nothing is listening on — fetch rejects with a
+    // connection error that safeFetch wraps as networkError (exit 1).
+    await assert.rejects(
+      () =>
+        runGet(
+          ["--key", VALID_KEY, "--url", "http://127.0.0.1:1", "@alice/pdf-helper"],
+          { stdout },
+        ),
+      (err) => err instanceof CliError && err.exitCode === EXIT_NETWORK,
+    );
+  });
+});
+
+// ── Best-effort .last-sync write (#1574 contract) ─────────────────────
+//
+// get writes the skill bytes to disk, THEN records the skill in
+// .last-sync so `list` can see it. That second write is best-effort: if
+// it fails, the user already has the skill on disk, so the command must
+// NOT turn a successful fetch into a failure. get.mjs wraps it in a
+// try/catch; lock that the swallow actually happens.
+describe("runGet — best-effort .last-sync write failure does not fail the command", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("writes the skill and exits cleanly even when the .last-sync state write throws", async () => {
+    // Occupy the global skillrepo state-dir PATH with a regular file, so
+    // writeLastSync (via upsertLastSyncEntry) can't create the directory
+    // and throws a diskError. Cross-platform: a file where a directory is
+    // expected fails identically on POSIX and Windows (no chmod needed).
+    // The skill itself lands in the PROJECT placement (a different path),
+    // so the command's real work succeeds.
+    mkdirSync(join(process.env.HOME, ".claude"), { recursive: true });
+    writeFileSync(join(process.env.HOME, ".claude", "skillrepo"), "not-a-dir");
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+
+    await assert.doesNotReject(
+      () =>
+        runGet(
+          ["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper", "--agent", "claude"],
+          { stdout },
+        ),
+      "a .last-sync write failure must NOT fail `get` after the skill files landed",
+    );
+    assert.ok(
+      existsSync(join(resolvePlacementDir("claudeProject", "pdf-helper"), "SKILL.md")),
+      "the skill files must still be on disk despite the state-write failure",
+    );
+  });
+});