skillrepo 4.5.1 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "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

@@ -196,11 +196,11 @@ export async function runAdd(argv, io = {}) {
     .join(", ")})`;
   if (wasNewlyAdded) {
     stdout.write(
-      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   } else {
     stdout.write(
-      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   }
 }

package/src/commands/get.mjs

@@ -143,6 +143,6 @@ export async function runGet(argv, io = {}) {
     .map(describePlacementTarget)
     .join(", ")})`;
   stdout.write(
-    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} files) → ${where}\n\n`,
+    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
   );
 }

package/src/commands/list.mjs

@@ -56,7 +56,14 @@ export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const flags = resolveFlags(argv);
 
-  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey);
+  // `list` is a read-only drift check — it must NEVER set sync state.
+  // Use the manifest read (#1832): metadata only, no file bodies, and the
+  // server records no delivery for it. Per-skill drift is computed from
+  // on-disk SHAs + `.last-sync` below, never from the response body, so
+  // the empty `files` array a manifest returns is irrelevant here.
+  const libraryResponse = await getLibrary(flags.serverUrl, flags.apiKey, {
+    manifest: true,
+  });
 
   // Defensive guard: `list` calls getLibrary without an If-None-Match
   // header so it can't legitimately receive a 304 today. But getLibrary's
@@ -243,9 +250,13 @@ function printTable(augmented, detected, out) {
       .join(", ");
     out.write(`\n  Detected: ${detectedLabel}\n`);
   } else {
-    out.write(
-      "\n  No agents detected in this project — drift cannot be reported.\n",
-    );
+    // Earlier copy said "drift cannot be reported" but the table
+    // below DOES report drift — every skill rolls up as MISSING
+    // because no placement exists to compare against. The simpler
+    // statement of fact is what users need; the footer ("No sync
+    // history…" / "library has changed…") tells them what to do
+    // next.
+    out.write("\n  No agents detected in this project.\n");
   }
 
   const sorted = augmented.slice().sort(sortByOwnerAndName);
@@ -337,12 +348,27 @@ function printFooter(augmented, libraryEtag, lastSync, out, useGlyphs) {
   }
 
   if (etagMatches && driftCount > 0) {
-    out.write(
-      `\n  ${warn} library in sync — but ${driftCount} skill${
-        driftCount === 1 ? "" : "s"
-      } show${driftCount === 1 ? "s" : ""} local drift.\n` +
-        "    Run `skillrepo update` to refresh.\n\n",
-    );
+    // Distinguish EDITED (running update loses user changes) from
+    // MISS/STALE (running update is non-destructive — fills gaps or
+    // pulls a newer version). The earlier copy said "Run `skillrepo
+    // update` to refresh" for every drift case, which silently
+    // destroyed user edits when EDITED rows were present. Now we
+    // warn explicitly when edits are at risk.
+    const editedCount = augmented.filter(
+      (s) => s.state === SKILL_STATE.EDITED,
+    ).length;
+    const driftPhrase = `${driftCount} skill${driftCount === 1 ? "" : "s"} show${driftCount === 1 ? "s" : ""}`;
+    if (editedCount > 0) {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift, including ${editedCount} with local edit${editedCount === 1 ? "" : "s"}.\n` +
+          "    Run `skillrepo update` to refresh — this will OVERWRITE local edits.\n\n",
+      );
+    } else {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift.\n` +
+          "    Run `skillrepo update` to refresh.\n\n",
+      );
+    }
     return;
   }
 

package/src/lib/http.mjs

@@ -305,10 +305,20 @@ async function mapErrorResponse(res, url) {
   if (res.status === 401) {
     // Derive the auth URL from the request URL's origin so users
     // running against staging see a staging hint, not a prod hint.
-    // `url` here is the full request URL (e.g.
-    // https://staging.skillrepo.dev/api/v1/library); `new URL(...).origin`
-    // gives us "https://staging.skillrepo.dev" which is what
-    // `cliAuthUrl` expects.
+    // `url` here is the full request URL — typically
+    // `https://staging.skillrepo.dev/api/v1/library` (canonical) or
+    // `https://api.staging.skillrepo.dev/v1/library` (subdomain alias
+    // per #1588). `new URL(...).origin` strips back to the host —
+    // `https://staging.skillrepo.dev` or `https://api.staging.skillrepo.dev`
+    // — and `cliAuthUrl` builds the `/cli/auth` URL from there.
+    //
+    // Known limitation: if the request URL uses the api.* / mcp.*
+    // subdomain, the resulting auth hint URL points at that subdomain
+    // (`https://api.staging.skillrepo.dev/cli/auth`), which 404s
+    // because /cli/auth only lives on the canonical host. Today the
+    // CLI defaults to the canonical URL so this is latent; surfaces
+    // only when a user passes `--url https://api.<env>.skillrepo.dev`
+    // explicitly. Tracked separately — not blocking this PR.
     let authUrl = DEFAULT_CLI_AUTH_URL;
     try {
       authUrl = cliAuthUrl(new URL(url).origin);
@@ -526,12 +536,20 @@ export async function validateAccessKey(serverUrl, apiKey, source = "validate")
  * @param {object} [opts]
  * @param {string} [opts.ifNoneMatch] - ETag to send as If-None-Match
  * @param {string} [opts.since]       - ISO timestamp for delta filter
+ * @param {boolean} [opts.manifest]   - Request a metadata-only manifest:
+ *   the server returns empty `files` for every skill and records NO
+ *   delivery. Used by `skillrepo list` for a read-only drift check that
+ *   must not set sync state (#1832).
  * @returns {Promise<LibrarySyncResult>}
  */
 export async function getLibrary(serverUrl, apiKey, opts = {}) {
   const base = normalizeUrl(serverUrl);
   const params = new URLSearchParams();
   if (opts.since) params.set("since", opts.since);
+  // Manifest mode (#1832): metadata-only, non-recording read used by
+  // `skillrepo list`. A peek must not set sync state, so the server
+  // returns empty `files` and records no delivery for this request.
+  if (opts.manifest) params.set("manifest", "1");
   const url = params.toString()
     ? `${base}/api/v1/library?${params.toString()}`
     : `${base}/api/v1/library`;
@@ -573,6 +591,56 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
   };
 }
 
+/**
+ * POST /api/v1/library/sync-receipts — report confirmed local writes (#1832).
+ *
+ * Called by `runSync` AFTER it successfully writes skill files to disk.
+ * Carries the (owner, name, version) pairs actually written so the server
+ * records sync state from a confirmed write, never from a fetch response.
+ *
+ * Best-effort + retryable: the receipt is telemetry and the files are
+ * already on disk by the time we call this, so callers treat a failure as
+ * a non-fatal warning. Transient 5xx / network failures retry — the server
+ * dedups by `(user, skill, version, UTC day)` and stamps idempotently, so
+ * a replay is safe. A non-2xx after retries throws a typed error.
+ *
+ * @param {string} serverUrl
+ * @param {string} apiKey
+ * @param {object} receipt
+ * @param {{owner: string, name: string, version: string}[]} receipt.skills
+ *   The skills written to disk this sync. Empty array is a valid no-op.
+ * @param {string} receipt.syncedAt - ISO timestamp of the sync.
+ * @returns {Promise<{recorded: number}>}
+ */
+export async function postSyncReceipt(serverUrl, apiKey, receipt) {
+  const url = `${normalizeUrl(serverUrl)}/api/v1/library/sync-receipts`;
+  const res = await safeFetch(url, {
+    method: "POST",
+    headers: {
+      ...(await authHeaders(apiKey)),
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      syncedAt: receipt.syncedAt,
+      skills: receipt.skills,
+    }),
+    // Idempotent server-side (dedup bucket + idempotent UPDATE), so a
+    // transient 5xx / network blip is safe to retry.
+    retry: true,
+  });
+  if (!res.ok) {
+    const err = await mapErrorResponse(res, url);
+    if (err === null) {
+      throw validationError(
+        `The server at ${normalizeUrl(serverUrl)} does not expose ` +
+          `/api/v1/library/sync-receipts. Is --url correct?`,
+      );
+    }
+    throw err;
+  }
+  return parseJsonOrThrow(res, url);
+}
+
 // ── /api/v1/skills/[owner]/[name] ───────────────────────────────────────
 
 /**

package/src/lib/sync.mjs

@@ -85,8 +85,9 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
-import { getLibrary } from "./http.mjs";
+import { getLibrary, postSyncReceipt } from "./http.mjs";
 import {
   writeSkillDir,
   removeSkillDir,
@@ -110,6 +111,103 @@ import { computeSkillShas } from "./crypto-shas.mjs";
  */
 export const LAST_SYNC_SCHEMA_VERSION = 2;
 
+/**
+ * Check whether every skill in the `.last-sync` baseline already exists
+ * under every placement target the current sync would write to. Returns
+ * true when the 304 short-circuit is safe (skipping writes won't leave
+ * any placement empty), false when at least one (skill, target) pair
+ * is missing on disk.
+ *
+ * This is the load-bearing guard for the ETag fast path. The contract:
+ * "library content unchanged AND every expected placement already has
+ * its content" — the second clause is what this function enforces.
+ *
+ * See the call site in runSync for the full motivation (upgrade-path,
+ * --global ↔ project swap, and cwd-switch scenarios all funnel through
+ * this gate).
+ *
+ * @param {Record<string, {skillMdSha256: string, filesSha256: string, version: string}> | null | undefined} skillsMap
+ *   The `.skills` map from `.last-sync` — keyed by `"<owner>/<name>"`.
+ * @param {string[] | undefined} vendors
+ *   The current sync's vendor list (output of `effectiveVendors`).
+ * @param {boolean | undefined} global
+ *   Whether the current sync is `--global` mode.
+ * @returns {boolean}
+ */
+export function placementsAreComplete(skillsMap, vendors, global) {
+  // Empty baseline: we cannot trust the ETag short-circuit. Two
+  // legitimate code paths land here:
+  //   1. Genuine fresh install — no `.last-sync` file at all; this
+  //      function isn't called because runSync's caller checks
+  //      `lastSync?.etag` before invoking. So we never see this
+  //      branch in the fresh-install case.
+  //   2. v1 → v2 migration — `readLastSync` synthesizes an empty
+  //      `skills` map for a v1 file (which had no per-skill SHA
+  //      cache). The etag IS present but the baseline is empty;
+  //      a 304 would tell us "library unchanged" but we'd still
+  //      have no per-skill cache, so `list` would render every
+  //      skill as MISS. Forcing a re-fetch here populates the
+  //      cache and surfaces the actual library state.
+  // The conservative direction is "force re-fetch" — wire cost
+  // happens once per upgrade, not every time.
+  if (
+    !skillsMap ||
+    typeof skillsMap !== "object" ||
+    Object.keys(skillsMap).length === 0
+  ) {
+    return false;
+  }
+
+  // No vendors: this is the `--agent none` case or a degenerate config.
+  // requireVendorTargets will catch this downstream; from here, treat
+  // as "no placements to verify" → trivially complete.
+  if (!Array.isArray(vendors) || vendors.length === 0) {
+    return true;
+  }
+
+  let targets;
+  try {
+    targets = placementTargetsFor({ vendors, global: global === true });
+  } catch {
+    // placementTargetsFor throws on an invalid vendor + scope combo
+    // (e.g., `--global` with a vendor that has no `globalTarget`).
+    // The downstream runSync write loop will surface the same error
+    // with the correct typed exception; conservatively treat as
+    // "placement incomplete" so we drop the ETag and force the
+    // full-fetch path (which is what we'd want under any error).
+    return false;
+  }
+
+  for (const key of Object.keys(skillsMap)) {
+    // Skill keys are `"<owner>/<name>"`. We only need the name half
+    // because placement directories are keyed by skill name alone.
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue; // malformed entry — skip rather than crash
+    const skillName = key.slice(slashAt + 1);
+    if (!skillName) continue;
+
+    for (const target of targets) {
+      const dir = resolvePlacementDir(target, skillName);
+      // Probe `SKILL.md` rather than the bare directory. An empty or
+      // partial directory left behind by a hostile filesystem
+      // condition (manual mkdir, third-party tool, interrupted write
+      // before the atomic rename — rare but possible) would otherwise
+      // satisfy `existsSync(dir)` and let the 304 fire, leaving the
+      // user with a placement that contains no usable skill content.
+      // SKILL.md is the spec-required entry point; its presence is
+      // the load-bearing invariant the placement-presence check is
+      // really asserting.
+      if (!existsSync(join(dir, "SKILL.md"))) {
+        // ONE missing placement is enough — full re-fetch will re-write
+        // EVERY skill to EVERY target, restoring the invariant in one
+        // round.
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
 /**
  * Read the persisted last-sync state from ~/.claude/skillrepo/.last-sync.
  * Returns null if the file doesn't exist, is malformed, or has a
@@ -370,8 +468,61 @@ export async function runSync(options) {
 
   // Step 3: fetch with conditional headers
   const opts = {};
-  if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
-  if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
+  // The ETag short-circuit is only safe when EVERY skill in
+  // `.last-sync`'s baseline is present in EVERY placement directory
+  // the current sync would write to. The 304 means "library content
+  // unchanged" — but the local placement set can change between
+  // syncs even when content does not:
+  //
+  //   - User upgrades from 4.5.0 (single-vendor default) to 4.5.1+
+  //     (all-detected default) — new vendors detected, their
+  //     placement dirs are empty.
+  //   - User runs `update --global` once, then `update` (no flag)
+  //     later — same vendor, but the resolved placement dir is
+  //     project-scoped now instead of global.
+  //   - User runs `update` in project A, then in project B — same
+  //     vendor and scope, but `<cwd>/.claude/skills/` resolves to a
+  //     different directory in B than in A.
+  //
+  // Without this check, any of those cases produces 304 → no writes
+  // → all-MISS output in `list`. The fix is a placement-presence
+  // check: for every (skill, target) pair the current sync would
+  // touch, the skill's directory MUST already exist under the
+  // target's root. If ANY is missing, drop `If-None-Match` so the
+  // server returns the full library and we populate the empty
+  // placement.
+  //
+  // Performance: N targets × M skills `existsSync` calls. For a 14-
+  // skill library with 2 targets, that's 28 stat calls — well under
+  // a millisecond. The conditional-fetch wire savings on a clean
+  // repeat sync still applies; this is the safety guard above it.
+  // BOTH the ETag short-circuit AND the `since` delta-query optimization
+  // depend on the same trust invariant: "the local placement set has
+  // every skill we expect." If a placement is missing, dropping ONLY
+  // `If-None-Match` is insufficient — the server filters `result.skills`
+  // by `updatedAt > since`, so a server response that we trigger by
+  // dropping the ETag will STILL omit any skill whose content hasn't
+  // changed on the server since the last sync. The missing placement
+  // would never be repopulated, producing a permanent ETag-miss loop
+  // that the user can only escape by `rm ~/.claude/skillrepo/.last-sync`.
+  //
+  // Verified against the production server at
+  // src/lib/queries/library.ts (`gt(skills.updatedAt, since)`): `since`
+  // alone is enough to filter unchanged skills out of the response.
+  //
+  // Fix: gate BOTH headers on the same `placementsAreComplete` check.
+  // When placements are incomplete, drop both — server returns the
+  // full library, runSync writes every skill to every detected
+  // vendor's placement, recovery is complete in one round.
+  const placementsComplete =
+    lastSync?.etag &&
+    placementsAreComplete(lastSync.skills, vendors, global);
+  if (placementsComplete) {
+    opts.ifNoneMatch = lastSync.etag;
+  }
+  if (lastSync?.syncedAt && placementsComplete) {
+    opts.since = lastSync.syncedAt;
+  }
 
   // Track whether this is a full or delta sync BEFORE the network
   // call, for the returned summary's `fullSync` field. A "full" sync
@@ -455,6 +606,11 @@ export async function runSync(options) {
   let anyIncomplete = false;
   /** @type {Record<string, SyncedSkillEntry>} */
   const skillsMap = {};
+  // Skills actually written to disk this sync, for the confirmed-write
+  // receipt (#1832). Only what we WRITE this round — carry-forward skills
+  // were reported on the sync that wrote them.
+  /** @type {{owner: string, name: string, version: string}[]} */
+  const writtenThisSync = [];
   // Carry forward entries from the previous sync for skills we did
   // NOT re-fetch this round. A delta sync that touched 2 of 50
   // skills must keep the other 48's metadata — otherwise the
@@ -518,9 +674,26 @@ export async function runSync(options) {
         syncedAt: result.syncedAt,
       };
     }
+
+    // Record this write for the sync receipt (#1832). Only entries with a
+    // real version label can resolve to a delivery server-side, so skip
+    // null/empty versions (a skill with no current published version).
+    if (typeof skill.version === "string" && skill.version !== "") {
+      writtenThisSync.push({
+        owner: skill.owner,
+        name: skill.name,
+        version: skill.version,
+      });
+    }
   }
 
-  // Step 7: persist new ETag + skills map (only if the response was complete)
+  // Step 7: persist new ETag + skills map (only if the response was
+  // complete). The placement-presence check in `placementsAreComplete`
+  // (called above before the conditional request) handles the safety
+  // gate for the ETag short-circuit — no need to persist a separate
+  // vendor-set field; the on-disk placements themselves are the
+  // source of truth for "did the local placement set change in a way
+  // that would invalidate 304?"
   if (!anyIncomplete && result.etag) {
     try {
       writeLastSync({
@@ -539,6 +712,28 @@ export async function runSync(options) {
     }
   }
 
+  // Post a sync receipt for the skills actually written this sync
+  // (#1832). This confirmed-write signal — not the fetch itself — is what
+  // sets team sync state. Independent of the ETag persist above: skills
+  // skipped for `filesIncomplete` are excluded from `writtenThisSync`, so
+  // a partial sync still reports exactly what landed on disk. Best-effort:
+  // the files are already written and the server dedups replays, so a
+  // failed receipt is a non-fatal warning, never a sync failure.
+  if (writtenThisSync.length > 0) {
+    try {
+      await postSyncReceipt(serverUrl, apiKey, {
+        skills: writtenThisSync,
+        syncedAt: result.syncedAt,
+      });
+    } catch (err) {
+      stderr.write(
+        `  warning: failed to report sync receipt (${err.message}). ` +
+          `Your skills are synced locally; team sync status may lag until ` +
+          `your next sync.\n`,
+      );
+    }
+  }
+
   return summary;
 }
 

package/src/test/commands/list.test.mjs

@@ -92,6 +92,20 @@ describe("runList — happy path", () => {
     assert.match(out, /2 skills in your library/);
   });
 
+  it("makes a non-recording manifest read (#1832)", async () => {
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    // `list` is a peek — it must hit the metadata-only manifest path so
+    // the server records no delivery for it...
+    assert.equal(server.getLastLibraryManifest(), "1");
+    // ...and it never posts a sync receipt (that's a write-confirm signal).
+    assert.equal(server.getReceiptRequestCount(), 0);
+  });
+
   it("sorts alphabetically by owner then name", async () => {
     server.setLibraryResponse({
       skills: [