@spardutti/claude-skills 2.44.4 → 2.46.0

package/README.md

@@ -162,6 +162,7 @@ Every install writes a manifest at `.claude/.claude-skills.json` recording what
 - **Pre-check what you already have** in the picker — re-running doubles as an update screen; toggle to add or remove.
 - **Detect stale items** — skills/commands renamed or removed from the catalog upstream are flagged, and the CLI offers to delete them.
 - **Never touch what it didn't install** — the manifest is the CLI's own record; hand-written skills are invisible to it and always safe.
+- **Gate your own skills** — list a hand-written skill under `"custom"` (`"custom": ["brand"]`) and the skill gate enforces its `gate-paths` like an installed one. The CLI keeps `"custom"` as written and never deletes those skills. Never add your own skill to `"skills"`: a sync deletes anything there that is not in the catalog.
 
 ```bash
 npx @spardutti/claude-skills --sync

package/hooks/ship-gate-files.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Sourced by ship-gate.sh: which changed files a Stryker run can skip, and what its output says.
+
+TEST_RE='(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/'
+
+stryker_owner() {  # stryker_owner <owner> <owned files>
+  b=""; [ "$1" != "." ] && b="$1/"
+  [ -z "$GAUNTLET_MUTATE" ] && ! grep -q '\.py$' <<< "$2" \
+    && grep -qs '@stryker-mutator/core' "${b}package.json"
+}
+
+changed_tests() {  # changed_tests <family>
+  printf '%s\n' "$CHANGED" | grep -E "$TEST_RE" | while IFS= read -r t; do
+    [ -n "$t" ] && [ "$(family_of "$t")" = "$1" ] && printf '%s\n' "$t"
+  done
+}
+
+# Everything a file's verdict rests on besides the file itself and the tests.
+# Tests are left out: adding to them can only kill more, so only a lost line counts.
+files_context() {  # files_context <owner> <owned files>
+  fam=$(family_of "$1/.")
+  { printf '%s\n' "$PROJECT_DIR" "$1" "$(git rev-parse "$BASE" 2>/dev/null)"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
+    printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | grep -vE "$TEST_RE" \
+      | grep -vxF -f <(printf '%s\n' "$2") | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac
+    done; } | git hash-object --stdin
+}
+
+file_receipt() {  # file_receipt <context> <file>
+  printf '/tmp/claude-shipgate-file-%s\n' "$({ printf '%s\n' "$1" "$2"; cat "$2"; } | git hash-object --stdin)"
+}
+
+test_then() {  # test_then <snapshot> <test>: its content when the snapshot was taken
+  if grep -qxF "$2" "$1/manifest"; then cat "$1/files/$2" 2>/dev/null
+  else git show "$BASE:$2" 2>/dev/null; fi
+}
+
+# Never `| grep -q` under pipefail: diff exits 1 on any difference, and an early
+# grep exit fails the writer, so a match reads as none.
+tests_lost_lines() {  # tests_lost_lines <snapshot> <family>
+  [ -f "$1/manifest" ] || return 0
+  while IFS= read -r t; do
+    [ -n "$t" ] || continue
+    case "$(diff <(test_then "$1" "$t") <(cat "$t" 2>/dev/null))" in *$'\n<'*) return 0 ;; esac
+  done <<< "$({ cat "$1/manifest"; changed_tests "$2"; } | sort -u)"
+  return 1
+}
+
+# Sets OWNED to the files that still need mutating.
+files_split() {  # files_split <context> <owner> <label>
+  fam=$(family_of "$2/."); kept=""; rest=""
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    r=$(file_receipt "$1" "$f")
+    if [ -f "$r" ] && ! tests_lost_lines "$(cat "$r")" "$fam"; then kept="$kept ${f#"$2"/}"
+    else rest="$rest$f"$'\n'; fi
+  done <<< "$OWNED"
+  OWNED=${rest%$'\n'}
+  [ -n "$kept" ] || return 0
+  echo "  $3 stryker — ok, not re-run: passed and unchanged since:$kept"
+  echo "      A change in a file they call is not re-checked."
+  b=""; [ "$2" != "." ] && b="$2/"
+  [ -z "$OWNED" ] && stryker_page_tests "$b" "$3"
+  return 0
+}
+
+# A finding with no location cannot be pinned on one file, so it keeps none.
+files_record() {  # files_record <context> <owner> <findings>
+  [ -n "$(printf '%s\n' "$3" | grep . | grep -vE ':[0-9]+:[0-9]+$')" ] && return 0
+  fam=$(family_of "$2/.")
+  snap="/tmp/claude-shipgate-tests-$({ printf '%s\n' "$1"; changed_tests "$fam" \
+    | while IFS= read -r t; do printf '%s\n' "$t"; cat "$t" 2>/dev/null; done; } | git hash-object --stdin)"
+  mkdir -p "$snap/files"; changed_tests "$fam" > "$snap/manifest"
+  while IFS= read -r t; do
+    [ -f "$t" ] && mkdir -p "$snap/files/$(dirname "$t")" && cp "$t" "$snap/files/$t"
+  done < "$snap/manifest"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -qF "  ${f#"$2"/}:" <<< "$3" && continue
+    printf '%s\n' "$snap" > "$(file_receipt "$1" "$f")"
+  done <<< "$OWNED"
+}
+
+# Match a finding, never a summary row. Stryker prints a `# survived` COLUMN
+# HEADER every run and repeats the word in its table, so a bare grep reports
+# survivors on a clean run — worse than not running at all. Stryker marks each
+# real finding `[Survived]`; table and border lines are excluded outright.
+# NoCoverage is printed exactly like Survived and means something worse: not
+# "a test missed this mutation" but "no test executes this line at all". The
+# gate matched only [Survived], so a diff whose files have no tests came back
+# PASS — 306 uncovered mutants reported as proven on one commit. It is judged
+# only for files that went in WITH a range: a glob-shaped path is mutated
+# whole, so its untouched lines would report uncovered forever, and a finding
+# nobody can close is what teaches people to --force.
+#
+# The status line carries no file name; the line under it does, as
+# file:line:column. They are paired here rather than grepped separately.
+stryker_findings() {  # stryker_findings <output> <globbed paths, comma-wrapped>
+  printf '%s\n' "$1" | awk -v globbed="$2" '
+    /^\[Survived\]/   { pend = $0; kind = "s"; next }
+    /^\[NoCoverage\]/ { pend = $0; kind = "n"; next }
+    pend != "" {
+      file = $0; sub(/:[0-9]+:[0-9]+$/, "", file)
+      if (kind == "s" || index(globbed, "," file ",") == 0) print pend "  " $0
+      pend = ""
+    }
+    # A survivor with no location under it is still a survivor, never dropped.
+    END { if (pend != "" && kind == "s") print pend }
+  '
+}

package/hooks/ship-gate-projects.sh

@@ -25,6 +25,18 @@ py_mutmut() {
   command -v mutmut >/dev/null 2>&1 && printf 'mutmut\n'
 }
 
+# Node that lives only in Docker leaves no Stryker on the host. An executable
+# .stryker-run runs it there instead, taking the arguments stryker would.
+stryker_bin() { if [ -x "$1.stryker-run" ]; then echo ./.stryker-run; else echo npx --no-install stryker; fi; }
+stryker_elsewhere() {  # stryker_elsewhere <tool> <base>: after a failed run, say where Stryker could run
+  [ "$1" = stryker ] && [ ! -x "$2.stryker-run" ] || return 0
+  d=$(cd "${2:-.}" && pwd)
+  while [ "$d" != / ]; do [ -d "$d/node_modules/@stryker-mutator/core" ] && return 0; d=$(dirname "$d"); done
+  echo "      Stryker is not installed on this machine. If Node runs only in Docker, add an"
+  echo "      executable $2.stryker-run that runs it there and passes on its arguments:"
+  echo "        docker compose run --rm -T <service> nice -n 19 npx stryker \"\$@\""
+}
+
 owner_of() {
   d=$(dirname "$1")
   while :; do
@@ -127,7 +139,7 @@ project_key() {  # project_key <owner> <tool>
   fam=$(family_of "$1/.")
   { printf '%s\n' "$PROJECT_DIR" "$1" "$2" "$(git rev-parse "$BASE" 2>/dev/null)" \
       "$GAUNTLET_NO_MUTATE" "$GAUNTLET_IGNORE_FILES"
-    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh"
+    cat "$HERE/ship-gate.sh" "$HERE/ship-gate-projects.sh" "$HERE/ship-gate-files.sh"
     printf '%s\n' "$CHANGED" | grep -vE '\.(md|mdx|txt|rst|adoc)$' | while IFS= read -r f; do
       [ -n "$f" ] || continue
       case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac

package/hooks/ship-gate.sh

@@ -46,7 +46,7 @@
 set -uo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
-. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
+. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" && . "$HERE/ship-gate-files.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
 
 MODE=""
 case "${1:-}" in
@@ -122,7 +122,7 @@ if [ "$MODE" = force ]; then
 fi
 gate_report "$RECEIPT_KEY"
 SOURCED=$(printf '%s\n' "$CHANGED" | grep -E "\.($GAUNTLET_SOURCE_EXT)$" \
-        | grep -vE '(\.|_)(test|spec)\.[^.]+$|(^|/)tests?/|(^|/)\.stryker-tmp/' | while read -r f; do
+        | grep -vE "$TEST_RE|(^|/)\.stryker-tmp/" | while read -r f; do
           [ -f "$f" ] && printf '%s\n' "$f"
         done)
 
@@ -223,6 +223,7 @@ for owner in $OWNERS; do
   OWNED=$(while IFS= read -r f; do
             [ "$(owner_of "$f")" = "$owner" ] && printf '%s\n' "$f"
           done <<< "$FILES" | grep -vE "$GAUNTLET_NO_MUTATE" || true)
+  FCTX=""; if stryker_owner "$owner" "$OWNED"; then FCTX=$(files_context "$owner" "$OWNED"); files_split "$FCTX" "$owner" "$label"; fi
   [ -z "$OWNED" ] && continue
 
   # ONE comma-joined --mutate value, never a flag per range. Stryker's CLI
@@ -271,7 +272,7 @@ for owner in $OWNERS; do
     # 8 of them on one commit, all long since killed. --mutate already scopes
     # the run to the changed hunks, so incremental buys nothing here and costs
     # a cache that goes stale exactly the way mutmut's did.
-    CMD="${RUN}npx --no-install stryker run --concurrency $(gate_workers) --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
+    CMD="${RUN}$(stryker_bin "$base") run --concurrency $(gate_workers) --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
   elif [ -z "$PY" ] && [ -f "$base"package.json ]; then
     MISSING="$MISSING  $label needs Stryker:
       npm --prefix ${owner} i -D @stryker-mutator/core @stryker-mutator/vitest-runner
@@ -324,32 +325,9 @@ for owner in $OWNERS; do
   T0=$SECONDS; OUT=$(export FILES="$(printf '%s' "$OWNED" | tr '\n' ' ')" MUTATE_FLAGS="--mutate ${FLAGS#,}"; eval "$CMD" 2>&1); RC=$?; T=$((SECONDS - T0))
   [ "$TOOL" = mutmut ] && [ $RC -eq 0 ] && { printf '%s\n' "$OUT" > "$PKEY.out"; cp "$MLOG" "$PKEY.log" 2>/dev/null; }
   [ -n "$SCOPE_RE" ] && [ $RC -eq 0 ] && OUT=$(printf '%s\n' "$OUT" | grep -E "^[[:space:]]*($SCOPE_RE)\.x")
-  # Match a finding, never a summary row. Stryker prints a `# survived` COLUMN
-  # HEADER every run and repeats the word in its table, so a bare grep reports
-  # survivors on a clean run — worse than not running at all. Stryker marks each
-  # real finding `[Survived]`; table and border lines are excluded outright.
-  # NoCoverage is printed exactly like Survived and means something worse: not
-  # "a test missed this mutation" but "no test executes this line at all". The
-  # gate matched only [Survived], so a diff whose files have no tests came back
-  # PASS — 306 uncovered mutants reported as proven on one commit. It is judged
-  # only for files that went in WITH a range: a glob-shaped path is mutated
-  # whole, so its untouched lines would report uncovered forever, and a finding
-  # nobody can close is what teaches people to --force.
-  #
-  # The status line carries no file name; the line under it does, as
-  # file:line:column. They are paired here rather than grepped separately.
   if [ "$TOOL" = stryker ]; then
-    ALL=$(printf '%s\n' "$OUT" | awk -v globbed="$GLOBBED" '
-      /^\[Survived\]/   { pend = $0; kind = "s"; next }
-      /^\[NoCoverage\]/ { pend = $0; kind = "n"; next }
-      pend != "" {
-        file = $0; sub(/:[0-9]+:[0-9]+$/, "", file)
-        if (kind == "s" || index(globbed, "," file ",") == 0) print pend "  " $0
-        pend = ""
-      }
-      # A survivor with no location under it is still a survivor, never dropped.
-      END { if (pend != "" && kind == "s") print pend }
-    ')
+    ALL=$(stryker_findings "$OUT" "$GLOBBED")
+    [ -n "$FCTX" ] && [ $RC -eq 0 ] && files_record "$FCTX" "$owner" "$ALL"
   else
     ALL=$(printf '%s\n' "$OUT" | grep -E '[Ss]urvived' \
           | grep -vE '^[[:space:]]*[#│|+-]|# *surviv')
@@ -433,7 +411,7 @@ for owner in $OWNERS; do
     STATUS=1
   elif [ $RC -ne 0 ]; then
     echo "  $label $TOOL (${T}s) — the run failed:"
-    printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'
+    printf '%s\n' "$OUT" | tail -12 | sed 's/^/      /'; stryker_elsewhere "$TOOL" "$base"
     [ "$STATUS" = 0 ] && STATUS=2
   elif [ -n "$NOTE" ]; then
     printf '%s\n' "$NOTE"

package/hooks/skill-gate-automark.sh

@@ -24,9 +24,9 @@ SKILL_NAME=$(printf '%s' "$INPUT" | grep -o '"skill":"[^"]*"' | head -1 | sed 's
 if [ -n "$SKILL_NAME" ]; then
   # Sanitize: only allow [A-Za-z0-9_-] in the marker filename.
   SAFE_NAME=$(printf '%s' "$SKILL_NAME" | tr -cd 'A-Za-z0-9_-')
-  # Only skills the CLI installed get acked; built-ins and hand-made skills have no rules for us.
+  # Only skills the CLI installed, or the user listed under "custom", get acked.
   MANIFEST="$(dirname "$(cd "$(dirname "$0")" && pwd)")/.claude-skills.json"
-  if [ -n "$SAFE_NAME" ] && tr -d ' \n' 2>/dev/null < "$MANIFEST" | grep -o '"skills":\[[^]]*\]' | grep -q "\"$SAFE_NAME\""; then
+  if [ -n "$SAFE_NAME" ] && tr -d ' \n' 2>/dev/null < "$MANIFEST" | grep -oE '"(skills|custom)":\[[^]]*\]' | grep -q "\"$SAFE_NAME\""; then
     touch "/tmp/claude-skill-loaded-$KEY-$SAFE_NAME"
     # The ack path holds a key the model cannot know, so without this line its
     # first write is always denied just to learn it.

package/hooks/skill-gate.sh

@@ -116,7 +116,7 @@ MISSING=""
 ACKS=""
 MANIFESTS=""
 if [ -n "$TARGETS" ]; then
-  INSTALLED=$(tr -d ' \n' 2>/dev/null < "$PROJECT_DIR/.claude/.claude-skills.json" | grep -o '"skills":\[[^]]*\]')
+  INSTALLED=$(tr -d ' \n' 2>/dev/null < "$PROJECT_DIR/.claude/.claude-skills.json" | grep -oE '"(skills|custom)":\[[^]]*\]')
   MANIFESTS=$(find "$PROJECT_DIR" -maxdepth 4 \( -name node_modules -o -name .git -o -name .venv -o -name dist \) -prune -o \( -name package.json -o -name pyproject.toml -o -name requirements.txt \) -print 2>/dev/null)
 fi
 if [ -n "$TARGETS" ]; then
@@ -136,7 +136,7 @@ if [ -n "$TARGETS" ]; then
     SNAME=$(sed -n 's/^name:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
     [ -z "$SPATHS" ] && continue
     [ -z "$SNAME" ] && continue
-    case "$INSTALLED" in *"\"$SNAME\""*) ;; *) continue ;; esac  # automark never marks a hand-made skill
+    case "$INSTALLED" in *"\"$SNAME\""*) ;; *) continue ;; esac  # automark marks only installed and custom skills
 
     HIT=""
     for G in $(printf '%s' "$SPATHS" | tr ',' ' '); do

package/lib/manifest.mjs

@@ -16,6 +16,7 @@ export async function readManifest(targetDir = process.cwd()) {
       skills: data.skills ?? [],
       commands: data.commands ?? [],
       agents: data.agents ?? [],
+      custom: data.custom ?? [],
     };
   } catch {
     return null; // no manifest — a pre-manifest project or a fresh install
@@ -23,15 +24,17 @@ export async function readManifest(targetDir = process.cwd()) {
 }
 
 // Record exactly what the CLI has installed. This is the CLI's source of truth —
-// it never deletes anything not listed here.
+// it never deletes anything not listed here. `custom` is the user's own gated skills, carried over untouched.
 export async function writeManifest(targetDir, { catalogVersion, skills, commands, agents }) {
   await mkdir(join(targetDir, ".claude"), { recursive: true });
+  const custom = (await readManifest(targetDir))?.custom ?? [];
   const data = {
     catalogVersion,
     installedAt: new Date().toISOString(),
     skills: [...new Set(skills)].sort(),
     commands: [...new Set(commands)].sort(),
     agents: [...new Set(agents)].sort(),
+    custom,
   };
   await writeFile(manifestPath(targetDir), JSON.stringify(data, null, 2) + "\n");
 }

package/lib/setup-hook.mjs

@@ -28,6 +28,7 @@ const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_PROJECTS_FILENAME = "ship-gate-projects.sh";
 const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
+const SHIP_GATE_FILES_FILENAME = "ship-gate-files.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";
@@ -108,6 +109,7 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_GATE_FILENAME,
     SHIP_GATE_PROJECTS_FILENAME,
     SHIP_GATE_STRUCTURE_FILENAME,
+    SHIP_GATE_FILES_FILENAME,
     SHIP_GATE_HOOK_FILENAME,
     VERSION_CHECK_FILENAME,
   ]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.44.4",
+  "version": "2.46.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-files.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {