@spardutti/claude-skills 2.16.1 → 2.18.0

package/README.md

@@ -164,6 +164,10 @@ The last two guard the **back** — nothing finishes or ships until the code pas
 - `gauntlet.sh` — a `Stop` hook running the fast gates on your changed files (see [Automatic Verification](#automatic-verification-gauntlet))
 - `ship-gate-hook.sh` — a `PreToolUse` gate on `Bash` that refuses `git commit` and `git push` without a receipt from `ship-gate.sh`
 
+One more hook stays out of the way entirely:
+
+- `version-check.sh` — a `SessionStart` hook that mentions a newer catalog at most once a day. It never touches the network in the foreground: it reads a cache the previous session refreshed in the background, so it costs a file read. Silent when there is no cache, no network, or nothing new. `CLAUDE_SKILLS_NO_VERSION_CHECK=1` turns it off.
+
 <details>
 <summary>How the gate works</summary>
 
@@ -345,7 +349,8 @@ scripts/       validate-skills.mjs — checks skill length caps and reference in
                gauntlet.sh — the Stop-hook verification gates, embedded by the CLI
                ship-gate.sh — /ship's file-length and mutation checks, behind an exit code
                ship-gate-hook.sh — refuses git commit/push without a ship-gate receipt
-               gauntlet-selftest.sh — 15 behavioural tests for the hook (runs on pre-push)
+               version-check.sh — SessionStart nudge when a newer catalog is published
+               gauntlet-selftest.sh — behavioural tests for the hooks (runs on pre-push)
                gauntlet-survey.sh — what the hook would do in every repo under a directory
                preflight.sh — everything that must pass before a release
                check-freshness.mjs — compares each skill's `tracks:` versions to the registries

package/lib/setup-hook.mjs

@@ -565,6 +565,8 @@ const SHIP_GATE_SCRIPT = `#!/usr/bin/env bash
 #   bash .claude/hooks/ship-gate.sh [base-ref]
 #   bash .claude/hooks/ship-gate.sh --key      print the receipt key and stop
 #   bash .claude/hooks/ship-gate.sh --force    write a FORCED receipt, run nothing
+#   bash .claude/hooks/ship-gate.sh --baseline record today's mutmut survivors as
+#                                              accepted debt, write no receipt
 #
 # On completion it writes a RECEIPT at /tmp/claude-shipgate-<key>, and the
 # PreToolUse hook refuses \`git commit\` / \`git push\` without a matching one. The
@@ -587,6 +589,8 @@ const SHIP_GATE_SCRIPT = `#!/usr/bin/env bash
 #   GAUNTLET_SOURCE_EXT=...  which extensions count as source. Deliberately NOT
 #                            GAUNTLET_CODE_EXT: the Stop hook's key answers a
 #                            different question, and a docs repo sets it to .md
+#   GAUNTLET_IGNORE_EXT=...  extensions that need no gate at all. An extension in
+#                            neither list is reported UNPROVEN rather than passed
 #   GAUNTLET_MUTATE="cmd"    one explicit mutation command for the whole repo,
 #                            replacing per-project detection. $MUTATE_FLAGS holds
 #                            the --mutate flags, $FILES the changed files.
@@ -594,15 +598,33 @@ const SHIP_GATE_SCRIPT = `#!/usr/bin/env bash
 set -uo pipefail
 
 MODE=""
-case "\${1:-}" in --key) MODE=key; shift ;; --force) MODE=force; shift ;; esac
+case "\${1:-}" in
+  --key)      MODE=key; shift ;;
+  --force)    MODE=force; shift ;;
+  --baseline) MODE=baseline; shift ;;
+esac
 
 PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-$PWD}"
 cd "$PROJECT_DIR" 2>/dev/null || { echo "ship-gate: cannot read $PROJECT_DIR"; exit 1; }
 git rev-parse --git-dir >/dev/null 2>&1 || { echo "ship-gate: not a git repo"; exit 1; }
 
+# \`git diff --name-only\` prints paths from the repo ROOT, but CLAUDE_PROJECT_DIR
+# can point at a subdirectory of it. Testing those paths from the subdirectory
+# found no files at all, so the gate said "nothing to check" and wrote a PASS
+# receipt over a diff it never looked at. Work from the root and the paths git
+# prints are the paths this script tests. The receipt key moves with it, and the
+# PreToolUse hook asks this script for the key rather than computing its own, so
+# the two cannot disagree.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -n "$ROOT" ]; then
+  cd "$ROOT" || { echo "ship-gate: cannot read $ROOT"; exit 1; }
+  PROJECT_DIR="$ROOT"
+fi
+
 GAUNTLET_MAX_LINES=200
 GAUNTLET_MUTATE=""
-GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift"
+GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
+GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|json|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
 [ -n "\${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
 [ -f ".claude/gauntlet.conf" ] && . ".claude/gauntlet.conf"
 
@@ -645,6 +667,24 @@ FILES=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_SOURCE_EXT)$" \\
         done)
 
 if [ -z "$FILES" ]; then
+  # "I recognised nothing" is not "there is nothing", and the gate used to report
+  # both as a PASS. A Godot repo changed only .gd files, which no extension in
+  # the list named, so zero source files were found and a PASS receipt was
+  # written over work nothing had checked. An extension this gate cannot place is
+  # UNPROVEN: it does not block, but it never claims a pass either.
+  UNKNOWN=$(printf '%s\\n' "$CHANGED" | grep -E '\\.[A-Za-z0-9]+$' \\
+            | grep -viE "\\.($GAUNTLET_SOURCE_EXT)$" \\
+            | grep -viE "\\.($GAUNTLET_IGNORE_EXT)$" \\
+            | sed 's/.*\\.//' | sort -u | tr '\\n' ' ')
+  if [ -n "$UNKNOWN" ]; then
+    echo "ship-gate: UNPROVEN — nothing here was checked. These changed files are"
+    echo "  in a language this gate does not know: $UNKNOWN"
+    echo "  If they are source, add the extension in .claude/gauntlet.conf:"
+    echo "    GAUNTLET_SOURCE_EXT=\\"\\$GAUNTLET_SOURCE_EXT|\${UNKNOWN%% *}\\""
+    echo "  If they are not, add it to GAUNTLET_IGNORE_EXT the same way."
+    printf 'UNPROVEN %s unknown-extensions\\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
+    exit 2
+  fi
   echo "ship-gate: no changed code files — nothing to check"
   printf 'PASS %s no-code-changes\\n' "$(date -u +%FT%TZ)" > "$RECEIPT"
   exit 0
@@ -788,16 +828,59 @@ for owner in $OWNERS; do
   esac
   SURVIVED=$(printf '%s\\n' "$OUT" | grep -E "$PATTERN" \\
              | grep -vE '^[[:space:]]*[#│|+-]|# *surviv' | head -20)
+  FIXED=0
+  NOTE=""
+
+  # Stryker takes --mutate per changed hunk, so it already answers "did YOUR
+  # change get tested". mutmut cannot be asked that — 3.x dropped 1.x's
+  # --use-patch-file and never replaced it — so it mutates all of source_paths
+  # and reports the repo's entire backlog. Held to the same bar, the Python half
+  # answers "is this repo perfect" instead, which it never is, so it could never
+  # go green. The baseline supplies the missing half: survivors recorded once
+  # are accepted debt, and only a name that is not in it fails the gate.
+  #
+  # A mutant name carries an index within its own function, not a line number,
+  # so editing elsewhere in the file does not rename it — and editing the
+  # function itself DOES, which correctly re-charges its survivors to that edit.
+  if [ "$TOOL" = mutmut ]; then
+    BL="$base.mutmut-baseline"
+    NOWF=$(mktemp)
+    printf '%s\\n' "$OUT" \\
+      | sed -n 's/^[[:space:]]*\\([^[:space:]]*\\): survived$/\\1/p' | sort -u > "$NOWF"
+    if [ "$MODE" = baseline ]; then
+      cp "$NOWF" "$BL"
+      NOTE="  $label mutmut — baseline set: $(wc -l < "$BL") survivor(s) accepted. Commit $BL."
+      SURVIVED=""
+    elif [ -f "$BL" ]; then
+      # -Fxv against an empty baseline reports every survivor, which is right:
+      # an empty baseline means nothing has been accepted.
+      SURVIVED=$(grep -Fxv -f "$BL" "$NOWF" | head -20)
+      FIXED=$(grep -Fxvc -f "$NOWF" "$BL")
+    else
+      cp "$NOWF" "$BL"
+      NOTE="  $label mutmut — no baseline, so nothing could be compared. Recorded
+      $(wc -l < "$BL") existing survivor(s) in $BL — commit it, then run the
+      gate again. From here only NEW survivors fail; --baseline accepts more."
+      SURVIVED=""
+      [ "$STATUS" = 0 ] && STATUS=2
+    fi
+    rm -f "$NOWF"
+  fi
+
   if [ -n "$SURVIVED" ]; then
     echo "  $label $TOOL — surviving mutants; these lines can break and no test notices:"
     printf '%s\\n' "$SURVIVED" | sed 's/^/      /'
+    [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
     STATUS=1
   elif [ $RC -ne 0 ]; then
     echo "  $label $TOOL — the run failed:"
     printf '%s\\n' "$OUT" | tail -12 | sed 's/^/      /'
     [ "$STATUS" = 0 ] && STATUS=2
+  elif [ -n "$NOTE" ]; then
+    printf '%s\\n' "$NOTE"
   else
     echo "  $label $TOOL — ok, no surviving mutants in the changed lines"
+    [ "$FIXED" -gt 0 ] && echo "      ($FIXED baselined survivor(s) now killed — --baseline banks them)"
   fi
 done
 
@@ -808,6 +891,12 @@ if [ -n "$MISSING" ]; then
   [ "$STATUS" = 0 ] && STATUS=2
 fi
 
+if [ "$MODE" = baseline ]; then
+  echo
+  echo "ship-gate: baselines updated. No receipt written — run the gate for real."
+  exit 0
+fi
+
 # The receipt is written by this script and nothing else. A hand-rolled check
 # produces no receipt, which is the whole point: substituting a weaker check is
 # a choice that can be argued for, but it cannot be passed off as this one.
@@ -899,12 +988,105 @@ printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision"
 exit 0
 `;
 
+// SessionStart: a once-a-day line when a newer catalog has been published.
+// Canonical source: scripts/version-check.sh.
+const VERSION_CHECK_SCRIPT = `#!/usr/bin/env bash
+# version-check.sh — SessionStart. Says once a day when a newer catalog exists.
+#
+# SessionStart stdout is added to the model's context, so this does not draw a
+# banner: it tells the assistant, and the assistant mentions it. That is the
+# whole reach of this hook — it never installs anything and never asks a
+# question the user has to answer before working.
+#
+# The rule that keeps it invisible: NEVER touch the network in the foreground.
+# A session start that waits on npm is a session start that hangs on a bad
+# connection, and a version nudge is not worth one second of that. So it reads
+# a cache written by the PREVIOUS session's background refresh, and kicks off
+# the next refresh detached. The first session after an install therefore says
+# nothing, and after that the answer is at worst a day old — which is the right
+# resolution for "there is a new version" anyway.
+#
+# Silent when: no manifest, no cache yet, offline, already current, or the user
+# has already been told today.
+#
+#   CLAUDE_SKILLS_NO_VERSION_CHECK=1   turns it off entirely
+
+set -uo pipefail
+
+[ -n "\${CLAUDE_SKILLS_NO_VERSION_CHECK:-}" ] && exit 0
+
+PKG="@spardutti/claude-skills"
+PROJECT_DIR="\${CLAUDE_PROJECT_DIR:-$PWD}"
+MANIFEST="$PROJECT_DIR/.claude/.claude-skills.json"
+
+# No manifest means the CLI never installed here, so there is nothing to update.
+[ -f "$MANIFEST" ] || exit 0
+
+INSTALLED=$(sed -n 's/.*"catalogVersion"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' "$MANIFEST" | head -1)
+[ -n "$INSTALLED" ] || exit 0
+
+# One cache for the whole machine, not one per project: the answer is the same
+# everywhere, and a developer with ten repos should still cost one request.
+CACHE_DIR="\${HOME:-/tmp}/.claude"
+CACHE="$CACHE_DIR/.claude-skills-version"
+STAMP="$CACHE_DIR/.claude-skills-version-told"
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+NOW=$(date +%s 2>/dev/null || echo 0)
+DAY=86400
+
+# Refresh in the background, fully detached. Nothing downstream waits on it: all
+# three streams are closed, or the session start blocks until curl gives up.
+refresh() {
+  AGE=$DAY
+  if [ -f "$CACHE" ]; then
+    MTIME=$(date -r "$CACHE" +%s 2>/dev/null || echo 0)
+    AGE=$((NOW - MTIME))
+  fi
+  [ "$AGE" -lt "$DAY" ] && return
+  command -v curl >/dev/null 2>&1 || return
+  ( curl -fsS --max-time 5 "https://registry.npmjs.org/$PKG/latest" \\
+      | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p' \\
+      | head -1 > "$CACHE.tmp" 2>/dev/null
+    # Only replace the cache with something that parsed. A truncated reply that
+    # overwrote it would nudge toward a version that does not exist.
+    if [ -s "$CACHE.tmp" ]; then mv "$CACHE.tmp" "$CACHE"; else rm -f "$CACHE.tmp"; fi
+  ) </dev/null >/dev/null 2>&1 &
+}
+refresh
+
+[ -f "$CACHE" ] || exit 0
+LATEST=$(head -1 "$CACHE" | tr -d '[:space:]')
+[ -n "$LATEST" ] || exit 0
+[ "$LATEST" = "$INSTALLED" ] && exit 0
+
+# sort -V puts the newer one last. Equal versions were already handled, so the
+# only case left to reject is a cache that is BEHIND the install — which happens
+# normally right after publishing from the machine that publishes.
+NEWER=$(printf '%s\\n%s\\n' "$INSTALLED" "$LATEST" | sort -V | tail -1)
+[ "$NEWER" = "$LATEST" ] || exit 0
+
+# Once a day, however many sessions that day holds.
+if [ -f "$STAMP" ]; then
+  TOLD=$(date -r "$STAMP" +%s 2>/dev/null || echo 0)
+  [ $((NOW - TOLD)) -lt "$DAY" ] && exit 0
+fi
+: > "$STAMP"
+
+echo "A newer version of the $PKG catalog is available: $INSTALLED installed, $LATEST published."
+echo "Mention this to the user ONCE, in a single line, and only when the current task is done."
+echo "Do not interrupt what they are doing, and do not run the installer unless they ask."
+echo "To update, they run: npx $PKG"
+exit 0
+`;
+
 const GATE_FILENAME = "skill-gate.sh";
 const AUTO_MARK_FILENAME = "skill-gate-automark.sh";
 const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
 const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
+const VERSION_CHECK_FILENAME = "version-check.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -969,6 +1151,7 @@ export async function setupHook(targetDir = process.cwd()) {
   const gauntletPath = join(hooksDir, GAUNTLET_FILENAME);
   const shipGatePath = join(hooksDir, SHIP_GATE_FILENAME);
   const shipGateHookPath = join(hooksDir, SHIP_GATE_HOOK_FILENAME);
+  const versionCheckPath = join(hooksDir, VERSION_CHECK_FILENAME);
   const settingsPath = join(resolved, ".claude", "settings.json");
 
   await mkdir(hooksDir, { recursive: true });
@@ -984,6 +1167,8 @@ export async function setupHook(targetDir = process.cwd()) {
   await chmod(shipGatePath, 0o755);
   await writeFile(shipGateHookPath, SHIP_GATE_HOOK_SCRIPT, { mode: 0o755 });
   await chmod(shipGateHookPath, 0o755);
+  await writeFile(versionCheckPath, VERSION_CHECK_SCRIPT, { mode: 0o755 });
+  await chmod(versionCheckPath, 0o755);
 
   // Remove the legacy audit-runner hook file from prior installs (2.3.x).
   try {
@@ -1059,6 +1244,17 @@ export async function setupHook(targetDir = process.cwd()) {
     settings.hooks.PostToolUse = [autoMarkEntry];
   }
 
+  // Register SessionStart version check. No matcher: startup and resume both
+  // want it, and the script's own daily stamp keeps a burst of resumes quiet.
+  const versionCheckCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${VERSION_CHECK_FILENAME}`;
+  const versionCheckEntry = { hooks: [{ type: "command", command: versionCheckCommand }] };
+
+  if (Array.isArray(settings.hooks.SessionStart)) {
+    upsert(settings.hooks.SessionStart, VERSION_CHECK_FILENAME, versionCheckEntry);
+  } else {
+    settings.hooks.SessionStart = [versionCheckEntry];
+  }
+
   // Register Stop gauntlet hook.
   const gauntletCommand = `$CLAUDE_PROJECT_DIR/.claude/hooks/${GAUNTLET_FILENAME}`;
   const gauntletEntry = { hooks: [{ type: "command", command: gauntletCommand }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.16.1",
+  "version": "2.18.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {