@spardutti/claude-skills 2.17.0 → 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

@@ -589,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.
@@ -606,9 +608,23 @@ 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"
 
@@ -651,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
@@ -954,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";
 
@@ -1024,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 });
@@ -1039,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 {
@@ -1114,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.17.0",
+  "version": "2.18.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
   "bin": {