@spardutti/claude-skills 2.17.0 → 2.19.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>
 
@@ -295,8 +299,17 @@ GAUNTLET_REQUIRE_TESTS=1             # block when the runner matched 0 test file
 GAUNTLET_MAX_LINES=200               # per-file limit; 0 turns the check off
 GAUNTLET_SOURCE_EXT='ts|tsx|py'      # what counts as SOURCE — not the same question
 GAUNTLET_MUTATE='bash mutate.sh'     # replace per-project mutation detection
+GAUNTLET_IGNORE_FILES='*.gen.ts'     # globs that are never gated — see below
 ```
 
+`GAUNTLET_IGNORE_FILES` holds files nobody wrote, so the line limit and mutation both
+skip them. It defaults to `*.gen.ts *.gen.tsx *.generated.* */migrations/*.py
+*/alembic/versions/*.py */components/ui/*.tsx` — a TanStack `routeTree.gen.ts`, a Django
+or Alembic migration, and a vendored shadcn component are all over 200 lines, none of
+them can be split, and gating them only teaches `--force`. Every skipped file is named in
+the output. Patterns match against `/<path>`, so `*/components/ui/*.tsx` covers the repo
+root and `apps/web/src` alike. Set it to `""` to gate everything.
+
 `GAUNTLET_SOURCE_EXT` is separate from `GAUNTLET_CODE_EXT` on purpose. The Stop hook asks
 "did anything worth checking change", so a docs repo sets `CODE_EXT` to include `.md`. The
 line limit and mutation ask about source code, where that answer is wrong.
@@ -345,7 +358,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,12 @@ 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_IGNORE_FILES=.. space-separated globs, matched against /<path>, for
+#                            files nobody wrote: generated code and vendored
+#                            components. They are named in the output, never
+#                            dropped silently. Set it to "" to gate everything
 #   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 +612,24 @@ 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"
+GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx"
 [ -n "\${HOME:-}" ] && [ -f "$HOME/.claude/gauntlet.conf" ] && . "$HOME/.claude/gauntlet.conf"
 [ -f ".claude/gauntlet.conf" ] && . ".claude/gauntlet.conf"
 
@@ -645,12 +666,58 @@ if [ "$MODE" = force ]; then
   echo "ship-gate: FORCED — receipt written without running any check."
   exit 0
 fi
-FILES=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_SOURCE_EXT)$" \\
+SOURCED=$(printf '%s\\n' "$CHANGED" | grep -E "\\.($GAUNTLET_SOURCE_EXT)$" \\
         | grep -vE '(\\.|_)(test|spec)\\.[^.]+$|(^|/)tests?/|(^|/)\\.stryker-tmp/' | while read -r f; do
           [ -f "$f" ] && printf '%s\\n' "$f"
         done)
 
+# A generated file cannot be split and a vendored one is not ours to split, so
+# the length check fires on every route regeneration and teaches people to
+# --force. A gate that is always forced is not a gate. These are held out of
+# both checks — and printed, because a silent skip is the same lie as a fake
+# PASS. The leading / is what lets one pattern match components/ui at the repo
+# root and apps/web/src/components/ui alike.
+# set -f matters: an unquoted list is glob-expanded before it is split, so
+# */components/ui/*.tsx turned itself into the very path it was meant to match
+# and then matched nothing.
+is_ignored() {
+  set -f
+  for pat in $GAUNTLET_IGNORE_FILES; do
+    case "/$1" in $pat) set +f; return 0 ;; esac
+  done
+  set +f
+  return 1
+}
+FILES=$(printf '%s\\n' "$SOURCED" | while IFS= read -r f; do
+          [ -n "$f" ] && ! is_ignored "$f" && printf '%s\\n' "$f"
+        done)
+IGNORED=$(printf '%s\\n' "$SOURCED" | while IFS= read -r f; do
+            [ -n "$f" ] && is_ignored "$f" && printf '%s\\n' "$f"
+          done)
+if [ -n "$IGNORED" ]; then
+  echo "ship-gate: not gated, matched GAUNTLET_IGNORE_FILES:"
+  printf '%s\\n' "$IGNORED" | sed 's/^/  /'
+fi
+
 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 +1021,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 +1184,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 +1200,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 +1277,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,8 +1,12 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "CLI to install Claude Code skills from the claude-skills collection",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Spardutti/claude-skills.git"
+  },
   "bin": {
     "claude-skills": "bin/cli.mjs"
   },