skillrepo 4.17.1 → 4.18.0

package/README.md

@@ -166,11 +166,18 @@ skillrepo update [--global] [--agent <list>] [--json] [--silent]
 ```
 
 Pulls the latest state of your library from the server using a delta
-sync. Writes new and updated skills, removes skills that were removed
-from the library, and skips skills that are unchanged. In a repo that
-declares a skillset, `update` instead reconciles that declared set (a
-full-set resolve, not a delta). Uses ETag caching so repeat runs return
-`304 Not Modified` when nothing has changed.
+sync. Writes new and updated skills, removes skills that left your
+library, and skips skills that are unchanged. Removals apply on both the
+delta sync and the periodic full re-sync (the one that runs on a first
+sync, after a CLI upgrade, or when a new editor is detected), so a skill
+your team recalled or deleted stops loading everywhere rather than
+lingering on disk. If you had edited a removed skill locally, its folder
+isn't discarded — it is moved to a quarantine area
+(`~/.claude/skillrepo/quarantine/`) with a warning, so it leaves the
+folders your agents load while your changes are preserved. In a repo
+that declares a skillset, `update` instead reconciles that declared set
+(a full-set resolve, not a delta). Uses ETag caching so repeat runs
+return `304 Not Modified` when nothing has changed.
 
 `--silent` suppresses normal output and writes a single `{}` line to
 stdout on success. Designed for SessionStart hooks that pipe stdout
@@ -221,9 +228,12 @@ receives its declared skillset. Skillset-scoped sync resolves the
 complete set on every pass: skills added to the skillset appear,
 skills removed from it are deleted from the repo's skill folders, and
 everything lands at the repository root no matter which subdirectory
-you run from. Deletes are guarded — a directory the CLI did not write,
-or one you modified locally, is never removed or overwritten; it stays
-put with a warning and shows up in your team's sync reporting instead.
+you run from. Deletes are guarded — a directory the CLI did not write is
+never removed or overwritten; it stays put with a warning and shows up
+in your team's sync reporting instead. A skill the CLI wrote that you
+then edited is moved to the quarantine area
+(`~/.claude/skillrepo/quarantine/`) rather than deleted when it leaves
+the set, so it stops loading while your edits are preserved.
 Declared entries in `extra` that cannot be honored (for example when
 extras are not enabled for your organization) are skipped loudly with
 the reason, never silently. If the registry is unreachable, the repo
@@ -322,6 +332,15 @@ is not a TTY or `NO_COLOR` is set, so piped output stays clean.
 (worst-wins drift rollup) field is kept for backward compatibility, so
 existing scripts keep working.
 
+Each row's `version` is the **installed** (on-disk) version — what your
+last sync wrote — while `servedVersion` is the version the server
+currently serves. They differ whenever you hold a version the server has
+moved off (a recall fallback reads `SERVING`, a stale copy reads
+`BEHIND`), and the reason line for those rows names the served version.
+Before 4.17.1 the top-level `version` reported the *served* version and
+there was no installed-version field, so a script that read `version` as
+"what the server serves" should read `servedVersion` instead.
+
 ### `search` — explore the registry
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.17.1",
+  "version": "4.18.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library, synced across your dev environment",
   "type": "module",
   "bin": {

package/src/commands/update.mjs

@@ -172,6 +172,11 @@ export async function runUpdate(argv, io = {}) {
       // gates output ignores skips, a quarantined skill produces no output
       // anywhere and exits 0 (#2413 adversarial review).
       const skipped = summary.skipped ?? 0;
+      // Quarantines (#2804) are a subset of `removed`, so they're already in
+      // `total`; surfaced separately below so this black-holed hook vector —
+      // where the per-skill quarantine warning is lost — still tells the
+      // user a removed skill they'd EDITED was moved (not deleted) and where.
+      const quarantined = summary.quarantined ?? 0;
       const total =
         summary.added + summary.updated + summary.removed + skipped;
       const subject = syncSubject(summary);
@@ -236,6 +241,9 @@ export async function runUpdate(argv, io = {}) {
       }
       stdout.write(
         `[SkillRepo] ${subject} synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+          (quarantined > 0
+            ? ` (${quarantined} edited, moved to ~/.claude/skillrepo/quarantine/)`
+            : "") +
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
@@ -366,6 +374,11 @@ function printSummary(s, out) {
   if (s.added > 0)   out.write(`    + ${s.added} added\n`);
   if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
   if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);
+  const quarantined = s.quarantined ?? 0;
+  if (quarantined > 0)
+    out.write(
+      `      (${quarantined} of those were edited — moved to ~/.claude/skillrepo/quarantine/, your changes preserved)\n`,
+    );
   if (skipped > 0)   out.write(`    ! ${skipped} skipped (see warnings above)\n`);
   out.write("\n");
 }

package/src/lib/file-write.mjs

@@ -51,9 +51,11 @@ import {
   writeFileSync,
   renameSync,
   rmSync,
+  cpSync,
   readdirSync,
   statSync,
 } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname, join, isAbsolute, relative } from "node:path";
 
 import {
@@ -68,6 +70,7 @@ import {
   windsurfSkillsGlobal,
   windsurfSkillsGlobalRoot,
   gitignorePath,
+  globalQuarantineDir,
 } from "./paths.mjs";
 import { AGENT_REGISTRY, getAgentByKey } from "./agent-registry.mjs";
 import { ensureManagedRootIgnores } from "./gitignore-section.mjs";
@@ -372,6 +375,34 @@ export function placementTargetsFor({ vendors, global = false }) {
   return targets;
 }
 
+/**
+ * Placement targets for `vendors` in the given scope, SKIPPING any vendor
+ * that doesn't support it — unlike `placementTargetsFor`, which throws.
+ * For READ-ONLY probing where a partial answer is correct and an
+ * unsupported vendor should contribute nothing rather than fail the whole
+ * resolve: the full-sync reconcile (#2804) uses it to check whether a
+ * recalled skill still lives in the OTHER scope (`.last-sync` is
+ * machine-global and scope-agnostic) before dropping its state key, and a
+ * vendor with no global scope (e.g. VS Code + Copilot) simply has no
+ * global dir to probe. Never use this to decide WRITES/DELETES — those
+ * must use the strict `placementTargetsFor` so a misconfigured scope fails
+ * loudly.
+ *
+ * @param {string[]} vendors
+ * @param {boolean} global
+ * @returns {PlacementTarget[]}
+ */
+export function placementTargetsForScopeLenient(vendors, global) {
+  const targets = [];
+  for (const vendor of Array.isArray(vendors) ? vendors : []) {
+    const entry = getAgentByKey(vendor);
+    if (!entry) continue;
+    const target = global ? entry.globalTarget : entry.projectTarget;
+    if (target && !targets.includes(target)) targets.push(target);
+  }
+  return targets;
+}
+
 /**
  * Find the SKILL.md file inside a skill's files array and return its
  * frontmatter `name` value, or null if none could be parsed.
@@ -463,6 +494,68 @@ export function writeSkillDir(skill, options = {}) {
   return { written };
 }
 
+/**
+ * Run a filesystem mutation, retrying briefly on the transient lock
+ * errors Windows raises (EBUSY / EPERM / ENOTEMPTY) when another process
+ * — antivirus, an editor, a vendor agent mid-scan — holds a handle on a
+ * file inside the target dir. The op typically succeeds a few ms later
+ * once the handle is released; POSIX effectively never hits this. After
+ * the last delay the ORIGINAL error is rethrown, so a genuine permission
+ * failure still surfaces. `removeSkillDir` / `removeManagedDir` /
+ * `quarantineSkillDir` route their rm/rename/copy through here — a
+ * compliance delete (#2804) must not silently fail on a momentary lock.
+ * Delays are injectable so unit tests exercise the retry loop without
+ * real sleeps.
+ *
+ * @template T
+ * @param {() => T} op
+ * @param {number[]} [delaysMs]
+ * @returns {T}
+ */
+export function withFsRetry(op, delaysMs = [20, 50, 100, 200]) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return op();
+    } catch (err) {
+      const transient =
+        !!err &&
+        (err.code === "EBUSY" ||
+          err.code === "EPERM" ||
+          err.code === "ENOTEMPTY");
+      if (!transient || attempt >= delaysMs.length) throw err;
+      const ms = delaysMs[attempt];
+      // Synchronous sleep: this whole pipeline is sync (rmSync/renameSync),
+      // so there is no event loop to yield to. Atomics.wait on a throwaway
+      // SharedArrayBuffer blocks the thread for `ms` without a busy spin.
+      if (ms > 0) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+      }
+    }
+  }
+}
+
+/**
+ * Recursively remove a single resolved placement directory, with the
+ * Windows-lock retry above. Returns true if the dir existed and was
+ * removed, false if it was already absent. Throws a typed disk error on
+ * a genuine failure. The per-directory primitive shared by
+ * `removeSkillDir` (all targets of a name) and the full-sync reconcile
+ * (#2804, one target at a time, alongside quarantine).
+ *
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function removeManagedDir(dir) {
+  if (!existsSync(dir)) return false;
+  try {
+    withFsRetry(() => rmSync(dir, { recursive: true, force: true }));
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw diskError(`Failed to remove ${dir}: ${err.message}`, { cause: err });
+  }
+  return true;
+}
+
 /**
  * Remove a skill directory from all configured placement targets.
  *
@@ -487,21 +580,71 @@ export function removeSkillDir(skillName, options = {}) {
 
   for (const target of targets) {
     const targetDir = resolvePlacementDir(target, skillName, options.baseDir);
-    if (!existsSync(targetDir)) {
-      notFound.push(targetDir);
-      continue;
-    }
-    try {
-      rmSync(targetDir, { recursive: true, force: true });
+    if (removeManagedDir(targetDir)) {
       removed.push(targetDir);
-    } catch (err) {
-      throw diskError(`Failed to remove ${targetDir}: ${err.message}`, { cause: err });
+    } else {
+      notFound.push(targetDir);
     }
   }
 
   return { removed, notFound };
 }
 
+/**
+ * Move a skill's loadable placement directory into the non-loaded
+ * quarantine area (`~/.claude/skillrepo/quarantine/`), preserving its
+ * contents, and return the destination path.
+ *
+ * The full-sync reconcile (#2804) calls this for a recalled / removed
+ * skill whose on-disk dir the CLI provably wrote (it is in the recorded
+ * write baseline) but which has since been locally EDITED. Deleting it
+ * would lose the user's edits; leaving it in place would keep the
+ * recalled skill loadable by agents — the exact compliance hole recall
+ * exists to close. Quarantine resolves both: the loadable copy goes away,
+ * the edited content survives outside every vendor's scan path. Unmodified
+ * recalled skills are deleted outright (`removeManagedDir`); a dir the CLI
+ * never wrote is never quarantined (the reconcile guards on the baseline).
+ *
+ * Destination names are uniquely stamped so quarantining the same skill
+ * from several placement targets in one sync never collides.
+ *
+ * @param {string} sourceDir  Absolute path of the loadable dir to move.
+ * @param {object} opts
+ * @param {string} opts.skillName  Spec-valid skill name (caller-validated).
+ * @returns {string} The quarantine destination path.
+ */
+export function quarantineSkillDir(sourceDir, { skillName } = {}) {
+  // Local state / server payloads are untrusted: never build a path from
+  // an invalid name (a traversal shape must never reach `join`).
+  if (!isValidSkillName(skillName)) {
+    throw validationError(`Invalid skill name: "${skillName}"`);
+  }
+
+  const root = globalQuarantineDir();
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dest = join(root, `${skillName}-${stamp}-${randomBytes(4).toString("hex")}`);
+
+  try {
+    withFsRetry(() => mkdirSync(root, { recursive: true }));
+    // Copy-then-remove rather than rename. The quarantine root lives under
+    // HOME while the placement dir lives under the repo, which can be a
+    // different filesystem (a mounted volume) — renameSync can't cross
+    // devices (EXDEV). Copying first and removing the loadable copy second
+    // is also the fail-safe order: if the remove fails, the edits are
+    // already preserved in quarantine (worst case the loadable dir lingers
+    // and is re-quarantined next sync), never lost.
+    withFsRetry(() => cpSync(sourceDir, dest, { recursive: true }));
+    withFsRetry(() => rmSync(sourceDir, { recursive: true, force: true }));
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw diskError(`Failed to quarantine ${sourceDir}: ${err.message}`, {
+      cause: err,
+    });
+  }
+
+  return dest;
+}
+
 /**
  * Scan all configured placement roots and remove orphan .tmp/ and .old/
  * directories left over from a crashed write. Called at the start of

package/src/lib/http.mjs

@@ -662,8 +662,30 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
   }
 
   const body = await parseJsonOrThrow(res, url);
+  // #2804 / #2879 data-safety: a 200 whose JSON lacks a top-level `skills`
+  // ARRAY is a malformed library response (an upstream proxy/CDN body, an
+  // API-gateway health envelope, or a changed server contract). Before #2804
+  // the `?? []` collapse was a harmless no-op; now a FULL-sync reconcile
+  // treats an empty served set as AUTHORITATIVE and removes every local skill
+  // absent from it. Refuse to read a missing/non-array `skills` as "empty
+  // library" — fail loud instead of silently reconciling the user's whole
+  // library off disk. A genuine empty library sends `skills: []` (a real
+  // array), so this never fires on the legitimate empty-library reconcile.
+  // `--session-hook` callers catch this and exit 0 WITHOUT reconciling
+  // (getLibrary throws before the reconcile is reached); `list` degrades to
+  // its EXIT_NETWORK disk fallback. The transient legit-empty `skills: []`
+  // case (replica lag / transient empty accessible set) is NOT this guard's
+  // job — it needs a server-side guarantee, tracked in #2880.
+  if (!Array.isArray(body.skills)) {
+    throw networkError(
+      `Server returned a ${res.status} library response with no skills[] array from ${url}`,
+      {
+        hint: "An upstream proxy or CDN may have replaced the response body, or the server contract changed. The CLI refuses to treat a malformed library response as an authoritative empty library. Check the URL or retry.",
+      },
+    );
+  }
   return {
-    skills: body.skills ?? [],
+    skills: body.skills,
     removals: body.removals ?? [],
     syncedAt: body.syncedAt ?? new Date().toISOString(),
     // Verbatim as received (#2365 ETag rule): Vercel serves strong

package/src/lib/paths.mjs

@@ -81,6 +81,18 @@ export const globalGovernanceSeenPath = () =>
 export const globalRepoStateDir = () =>
   join(homedir(), ".claude", "skillrepo", "repos");
 
+/**
+ * Quarantine area for the full-sync reconcile (#2804). When a recalled /
+ * removed skill's on-disk dir was written by the CLI but has since been
+ * locally EDITED, compliance requires it leave the loadable placement
+ * dirs, but the user's edits must not be destroyed — so the dir is moved
+ * here instead of deleted. NO vendor scans `~/.claude/skillrepo/`, so a
+ * quarantined skill is never loaded by an agent. Same parent dir as
+ * `.last-sync`, so `rm -rf ~/.claude/skillrepo/` still removes it.
+ */
+export const globalQuarantineDir = () =>
+  join(homedir(), ".claude", "skillrepo", "quarantine");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This