skillrepo 4.8.4 → 4.9.1

package/README.md

@@ -370,7 +370,7 @@ By default `skillrepo init` prompts you to install this hook. If you said no (or
 
 #### Auto-refresh hooks for other agents
 
-For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library refreshes on every session start without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
+For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library stays current across your sessions without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
 
 | Agent | Hook config path | Notes |
 |-------|------------------|-------|
@@ -393,6 +393,8 @@ Auto-refresh hooks for Windsurf and Cline are not yet supported — those agents
 
 **On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
 
+**Throttled to skip redundant syncs (v4.9.0+).** Because the hook fires on *every* editor session, the hook-triggered `update` (`--session-hook` / `--silent`) syncs at most once per ~15 minutes: within that window it exits immediately with **no network call**. This bounds redundant per-session load. The tradeoff is that a brand-new session started shortly after a recent sync may be up to ~15 minutes behind a just-published change — and the same bound applies to local repair: if you delete or corrupt a synced skill's folder on disk, the hook restores it on its next non-throttled run, up to ~15 minutes later. A bare `skillrepo update` **you** run yourself is never throttled — it always syncs immediately (repairing any local damage) and resets the window. `skillrepo list` is likewise never throttled (it always queries the server live), though it doesn't reset the window.
+
 Flags:
 
 - `--global` — operates on `~/.claude/settings.local.json` so the hook fires in every Claude Code session across all projects on your machine.

package/package.json

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

package/src/commands/init.mjs

@@ -605,8 +605,17 @@ export async function runInit(argv, io = {}, deps = {}) {
   // placementTargetsFor (no vendors specified), and even if it
   // didn't, fetching skill files we have nowhere to write is
   // pure waste.
-  const skipFirstSync =
-    Array.isArray(vendors) && vendors.length === 0 && !flags.global;
+  //
+  // `--global` does NOT change that. `effectiveVendors` returns the
+  // `--agent none` sentinel verbatim under --global precisely because
+  // "--global --agent none" still means "no placement writes" (see its
+  // test in cli-config.test.mjs), and this guard has to honour the same
+  // contract. It previously carried `&& !flags.global`, which defeated
+  // the skip for exactly the combination the comment above says would
+  // throw: every skill in the library was quarantined one-by-one with a
+  // misleading "will be retried next session" warning, and init then
+  // printed "No skills in library yet" and "SkillRepo is ready" (#2433).
+  const skipFirstSync = Array.isArray(vendors) && vendors.length === 0;
   if (skipFirstSync) {
     p.success("Skipped first sync (--agent none).");
     syncSummary = {
@@ -681,13 +690,29 @@ export async function runInit(argv, io = {}, deps = {}) {
     }
   }
 
+  // `skipped` counts here: a run that dropped a skill is NOT a
+  // zero-delta run, and reporting "No skills in library yet" or
+  // "up to date" for it is a false statement to the user. Same defect
+  // class as the printSummary/hook fix in update.mjs (#2433).
   const zeroDeltas =
-    syncSummary.added + syncSummary.updated + syncSummary.removed === 0;
+    syncSummary.added +
+      syncSummary.updated +
+      syncSummary.removed +
+      (syncSummary.skipped ?? 0) ===
+    0;
 
-  if (syncFailedReason) {
-    // The warning already printed; the step-summary success line
-    // would be misleading, so we skip it. Any helpful "next steps"
-    // is in the final `SkillRepo is ready` block.
+  if (syncFailedReason || skipFirstSync) {
+    // The warning (or the "Skipped first sync" line) already printed;
+    // the step-summary success line would be misleading, so we skip
+    // it. Any helpful "next steps" is in the final `SkillRepo is
+    // ready` block.
+    //
+    // `skipFirstSync` belongs here for the same reason the synthesized
+    // summary above uses `fullSync: null`: the network call never ran,
+    // so we do not know the library's state. Falling through printed
+    // "Library is up to date (no changes since last sync)" — a
+    // confident claim about a server we never contacted, on the same
+    // screen as "Skipped first sync" (#2433).
   } else if (syncSummary.notModified) {
     // 304 Not Modified — the client had the current ETag already.
     // Definitively "up to date" regardless of whether the library

package/src/commands/update.mjs

@@ -20,6 +20,10 @@
  *                    full contract. When this flag is absent, the
  *                    command behaves as before (exit non-zero on
  *                    network / auth / disk failures).
+ *                    Throttled (#2174): within MIN_SYNC_INTERVAL_MS of the
+ *                    last sync attempt this makes ZERO network calls (the
+ *                    hook fires every session; a bare `update` is never
+ *                    throttled).
  *
  * v4.1.0 silent mode (#1240):
  *   --silent         Suppress stdout: write `{}` on success, propagate
@@ -144,9 +148,20 @@ export async function runUpdate(argv, io = {}) {
         apiKey: flags.apiKey,
         vendors,
         global: flags.global,
+        // Throttle SessionStart syncs (#2174): this hook fires on every
+        // Claude Code session, so within MIN_SYNC_INTERVAL_MS of the last
+        // attempt runSync short-circuits with zero network calls. ONLY hook
+        // invocations pass this — a bare `skillrepo update` always syncs.
+        throttle: true,
         io: { stdout: BLACK_HOLE_STREAM, stderr: BLACK_HOLE_STREAM },
       });
-      const total = summary.added + summary.updated + summary.removed;
+      // `skipped` is included so the hook cannot go silent on a dropped
+      // skill: this path black-holes BOTH streams, so if the count that
+      // gates output ignores skips, a quarantined skill produces no output
+      // anywhere and exits 0 (#2413 adversarial review).
+      const skipped = summary.skipped ?? 0;
+      const total =
+        summary.added + summary.updated + summary.removed + skipped;
       if (summary.notModified || total === 0) {
         // 304 Not Modified OR 200 with zero deltas — silent by
         // contract. Users should not see "Syncing..." on every
@@ -154,7 +169,9 @@ export async function runUpdate(argv, io = {}) {
         return;
       }
       stdout.write(
-        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed.\n`,
+        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+          (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
+          `.\n`,
       );
     } catch (err) {
       // The one-line failure message is the user's primary signal
@@ -218,6 +235,10 @@ export async function runUpdate(argv, io = {}) {
       apiKey: flags.apiKey,
       vendors,
       global: flags.global,
+      // Throttle the cohort SessionStart hook too (#2174) — same reasoning
+      // as --session-hook: it fires every session, so skip the network
+      // within MIN_SYNC_INTERVAL_MS of the last attempt.
+      throttle: true,
       // sync.mjs surfaces non-fatal warnings (e.g. failed to persist
       // last-sync state) via stderr; preserve that channel so a real
       // operator running `update --silent` from a terminal can still
@@ -253,7 +274,11 @@ export async function runUpdate(argv, io = {}) {
 }
 
 function printSummary(s, out) {
-  const total = s.added + s.updated + s.removed;
+  // `skipped` counts here: a run that dropped a skill is NOT "up to date",
+  // and saying so was a false statement to the user (#2413 adversarial
+  // review — the counter was incremented and never read).
+  const skipped = s.skipped ?? 0;
+  const total = s.added + s.updated + s.removed + skipped;
   if (s.notModified || total === 0) {
     out.write("  ✓ Library is up to date.\n");
     return;
@@ -262,6 +287,7 @@ 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`);
+  if (skipped > 0)   out.write(`    ! ${skipped} skipped (see warnings above)\n`);
   out.write("\n");
 }
 

package/src/lib/file-write.mjs

@@ -27,6 +27,8 @@
  *     next `update` run fully overwrites it.
  *
  *   • Safety checks (NOT layout enforcement):
+ *       - Control characters (C0/DEL/C1, raw or URL-encoded) — rejected
+ *         (matches server CONTROL_CHARS, #2402)
  *       - Path traversal (..) — rejected
  *       - Absolute paths — rejected
  *       - Depth > 5 — rejected (matches server MAX_PATH_DEPTH)
@@ -131,6 +133,31 @@ const GLOBAL_TARGETS = Object.freeze([
 
 // ── Public API ──────────────────────────────────────────────────────────
 
+// Unicode Cc: C0 controls, DEL, and C1 controls. Same rule as the
+// server-side validator (#2402): a control character in a path can inject
+// line breaks or terminal escapes into prompts, logs, and rendered file
+// trees — and the CLI writes these paths to the user's disk on sync.
+// Mirrors CONTROL_CHAR_CLASS in src/lib/skills/file-validation.ts (the
+// CLI cannot import server TS). Always extend via \uXXXX escapes — NEVER
+// paste a raw control byte; a raw byte silently corrupts the class.
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+const CONTROL_CHARS_GLOBAL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/**
+ * Render a path for an error message with control characters
+ * \uXXXX-escaped, so the error string can never re-inject the characters
+ * it rejects into terminal output or sync logs.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeControlChars(value) {
+  return value.replace(
+    CONTROL_CHARS_GLOBAL,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
 /**
  * Validate a single file path inside a skill directory.
  *
@@ -142,6 +169,12 @@ const GLOBAL_TARGETS = Object.freeze([
  * @returns {string | null}
  */
 export function validateFilePath(rawPath) {
+  // Checked before decoding so no error message below (they interpolate
+  // the raw path verbatim) can ever echo a raw control character.
+  if (CONTROL_CHARS.test(rawPath)) {
+    return `Blocked control character in path "${escapeControlChars(rawPath)}".`;
+  }
+
   // Decode URL-encoded characters before validation
   let path;
   try {
@@ -150,6 +183,12 @@ export function validateFilePath(rawPath) {
     return `Invalid URL encoding in path "${rawPath}".`;
   }
 
+  // Re-check after the single decode: %0A-style encodings become real
+  // control characters here.
+  if (CONTROL_CHARS.test(path)) {
+    return `Blocked control character in path "${escapeControlChars(path)}".`;
+  }
+
   // Path traversal
   if (path.includes("..")) {
     return `Blocked path traversal in "${rawPath}".`;