@spardutti/claude-skills 2.56.3 → 2.57.0

package/README.md

@@ -36,7 +36,7 @@ npx @spardutti/claude-skills
 ```
 
 ```text
-  Claude Skills Installer v2.56.3
+  Claude Skills Installer v2.57.0
 
   ── Frontend ──────────────────────────────
   ◉ react              ◯ tanstack-query

package/hooks/gate-config.sh

@@ -18,6 +18,25 @@ load_gauntlet_conf() {  # load_gauntlet_conf <project conf> <fallback conf>
   if [ -f "$conf" ]; then . "$conf"; fi
 }
 
+skill_field() {  # skill_field <SKILL.md> <key pattern> — its first value, quotes stripped
+  sed -n "s/^$2:[[:space:]]*//p" "$1" | head -1 | sed "s/^[\"']//; s/[\"']\$//"
+}
+
+# Claude Code writes gate-paths gitignore-style. A case glob has no **, but * already crosses /
+# here, so dropping the **/ prefix is equivalent. set -f keeps the globs from matching real files.
+skill_hits() {  # skill_hits <gate-paths> <files...> — the files those globs match
+  local g t globs
+  set -f
+  globs=$(printf '%s' "$1" | tr ',' ' ' | sed 's!\*\*/!!g')
+  for t in "${@:2}"; do
+    for g in $globs; do
+      case "$g" in \**|/*) ;; *) g="*$g" ;; esac
+      case "$t" in $g) printf '%s\n' "$t"; break ;; esac
+    done
+  done
+  set +f
+}
+
 json_field() {  # json_field <json> <key> — a flat string value; \" is unescaped, \n is kept as two characters
   printf '%s' "$1" | grep -oE "\"$2\"[[:space:]]*:[[:space:]]*\"([^\"\\\\]|\\\\.)*\"" | head -1 \
     | sed -E 's/^[^:]*:[[:space:]]*"//; s/"$//; s/\\"/"/g'

package/hooks/ship-gate-projects.sh

@@ -89,6 +89,25 @@ changed_files() {
     git ls-files --others --exclude-standard 2>/dev/null; } | sort -u | grep -vE '(^|/)\.claude/'
 }
 
+file_hunks() {  # file_hunks <base> <file> — its new-side line ranges, one "start-end" a line
+  local h
+  h=$(git diff -U0 "$1" -- "$2" 2>/dev/null | grep -oE '^@@ -[0-9,]+ \+[0-9]+(,[0-9]+)?' | sed 's/.*+//' \
+      | while IFS=, read -r s l; do l=${l:-1}; [ "$l" -gt 0 ] && echo "$s-$((s+l-1))"; done)
+  if [ -n "$h" ]; then printf '%s\n' "$h"; else echo "1-$(wc -l < "$2" | tr -d ' ')"; fi
+}
+
+# The audit's scope: every changed text file, minus generated, vendored and lock files. Tab-separated: paths may hold spaces.
+scope_report() {
+  local f r new
+  echo "base $BASE"
+  printf '%s\n' "$CHANGED" | grep -vE '(^|/)(package-lock\.json|pnpm-lock\.yaml|[^/]*\.lock)$' | while IFS= read -r f; do
+    [ -f "$f" ] && ! is_ignored "$f" && grep -qI . "$f" || continue
+    r=$(file_hunks "$BASE" "$f" | sed -E 's/^([0-9]+)-\1$/\1/' | paste -sd, -)
+    new=""; git cat-file -e "$BASE:$f" 2>/dev/null || new=" (new)"
+    printf '%s\t%s%s\n' "$f" "$r" "$new"
+  done
+}
+
 # Ignored extensions are left out; see the comment where ship-gate.sh first calls this.
 receipt_key() {
   { printf '%s\n' "$PROJECT_DIR"

package/hooks/ship-gate.sh

@@ -52,6 +52,7 @@ HERE=$(cd "$(dirname "$0")" && pwd)
 MODE=""
 case "${1:-}" in
   --key)      MODE=key; shift ;;
+  --scope)    MODE=scope; shift ;;
   --force)    MODE=force; shift ;;
   --baseline) MODE=baseline; shift ;;
 esac
@@ -81,6 +82,7 @@ for B in ${GAUNTLET_BASE:-} develop dev main; do [ -n "$BASE" ] || BASE=$(git me
 [ -n "$BASE" ] || BASE=$(git rev-list --max-parents=0 HEAD | head -1)
 
 CHANGED=$(changed_files)
+[ "$MODE" = scope ] && { scope_report; exit 0; }
 
 # Only the files this gate can actually read go into the key. It used to be every
 # changed file, so a version bump in package.json or a line in a changelog threw
@@ -205,10 +207,7 @@ for owner in $OWNERS; do
   FLAGS=""
   GLOBBED=","
   while IFS= read -r f; do
-    hunks=$(git diff -U0 "$BASE" -- "$f" 2>/dev/null \
-            | grep -oE '^@@ -[0-9,]+ \+[0-9]+(,[0-9]+)?' | sed 's/.*+//' \
-            | while IFS=, read -r s l; do l=${l:-1}; [ "$l" -gt 0 ] && echo "$s-$((s+l-1))"; done)
-    [ -z "$hunks" ] && hunks="1-$(wc -l < "$f")"
+    hunks=$(file_hunks "$BASE" "$f")
     rel=${f#$owner/}
     # A Next.js route folder — [id], [[...slug]] — is a glob expression to
     # Stryker, which refuses "Cannot combine a glob expression with a mutation

package/hooks/ship-log.mjs

@@ -145,8 +145,8 @@ function run(mode, args) {
     if (todo.length) console.log(todo.map((t) => `  - ${t}`).join("\n"));
     return todo.length ? 1 : 0;
   }
-  // A gate run by hand or on a release is not a ship; only /ship's start opens one.
-  if (mode === "gate" && !existsSync(path)) return 0;
+  // A gate run or a review outside /ship is not a ship; only /ship's start opens one.
+  if ((mode === "gate" || mode === "step") && !existsSync(path)) return 0;
   if (mode === "gate") addGateRun(record, args);
   else if (mode === "finding") addFinding(record, args[0]);
   else if (mode === "step") addStep(record, args);

package/hooks/ship-prep.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+HERE=$(cd "$(dirname "$0")" && pwd)
+. "$HERE/gate-config.sh" || { echo "ship-prep: cannot read $HERE/gate-config.sh"; exit 1; }
+cd "${CLAUDE_PROJECT_DIR:-$PWD}" 2>/dev/null || { echo "ship-prep: cannot read ${CLAUDE_PROJECT_DIR:-$PWD}"; exit 1; }
+
+stop() { echo "ship-prep: STOP — $1"; exit 1; }
+
+first_remote() {  # first_remote <branch...> — the first one origin has
+  local b
+  for b in "$@"; do git rev-parse -q --verify "origin/$b" >/dev/null && { echo "$b"; return; }; done
+}
+
+base_branch() { local dev; dev=$(first_remote develop development dev); echo "${dev:-$(first_remote main master)}"; }
+
+start() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || stop "not a git repo."
+  local branch base dirty behind ahead
+  branch=$(git branch --show-current)
+  [ -n "$branch" ] || stop "Detached HEAD — check out a branch first."
+  if git remote | grep -qx origin; then git fetch -q origin 2>/dev/null; else echo "remote none: pr, merge and release cannot run"; fi
+  base=$(base_branch)
+  echo "branch $branch"
+  echo "base ${base:-none} (main $(first_remote main master))"
+  if ! git rev-parse -q --verify HEAD >/dev/null; then echo "commits none"
+  elif [ -n "$base" ]; then
+    read -r behind ahead < <(git rev-list --left-right --count "origin/$base...HEAD")
+    echo "ahead $ahead, behind $behind of origin/$base"
+  fi
+  dirty=$(git status --porcelain)
+  echo "uncommitted $(printf '%s' "$dirty" | grep -c .)"
+  [ -n "$dirty" ] && printf '%s\n' "$dirty" | sed 's/^/  /'
+  if gh auth status >/dev/null 2>&1; then
+    echo "gh logged in"
+    echo "pr $(gh pr view --json state,number,url -q '.state+" #"+(.number|tostring)+" "+.url' 2>/dev/null || echo none)"
+  else
+    echo "gh NOT logged in: pr, merge and release cannot run"
+  fi
+  bash "$HERE/ship-mark.sh" begin || stop "ship-mark.sh begin failed."
+}
+
+skills_report() {  # skills_report <files...>
+  local f name paths hits
+  for f in "$(diary_dir "$HERE")"/skills/*/SKILL.md; do
+    [ -f "$f" ] || continue
+    name=$(skill_field "$f" name); paths=$(skill_field "$f" '[[:space:]]*gate-paths')
+    if [ -z "$paths" ]; then echo "skill $name: decide from its description"; continue; fi
+    hits=$(skill_hits "$paths" "$@" | paste -sd' ' -)
+    if [ -n "$hits" ]; then echo "skill $name: audit $hits"; else echo "skill $name: skip, no changed file matches $paths"; fi
+  done
+}
+
+scope() {
+  local branch scope base files=() diff f
+  cd "$(git rev-parse --show-toplevel)" || stop "cannot find the repo root."
+  branch=$(git branch --show-current)
+  scope=$(bash "$HERE/ship-gate.sh" --scope) || stop "ship-gate.sh --scope failed: $scope"
+  printf '%s\n' "$scope"
+  base=$(printf '%s\n' "$scope" | sed -n '1s/^base //p')
+  while IFS=$'\t' read -r f _; do [ -n "$f" ] && files+=("$f"); done < <(printf '%s\n' "$scope" | sed '1d')
+  skills_report "${files[@]}"
+  diff="/tmp/claude-ship-$(printf '%s %s' "$PWD" "$branch" | cksum | cut -d' ' -f1).diff"
+  : > "$diff"
+  if [ ${#files[@]} -gt 0 ]; then
+    git diff "$base" -- "${files[@]}" >> "$diff"
+    for f in "${files[@]}"; do
+      git ls-files --error-unmatch "$f" >/dev/null 2>&1 || git diff --no-index /dev/null "$f" >> "$diff"
+    done
+  fi
+  echo "diff $diff"
+  echo "review /code-review medium origin/$(base_branch)...$branch"
+  node "$HERE/ship-log.mjs" step audit start >/dev/null 2>&1
+  node "$HERE/ship-log.mjs" step review start >/dev/null 2>&1
+  return 0
+}
+
+secrets() {
+  local branch names hits
+  branch=$(git branch --show-current)
+  case "$branch" in main|master|develop|development|dev) stop "on protected branch $branch — commit on a feature or hotfix/<desc> branch." ;; esac
+  git status --short
+  names=$({ git diff HEAD --name-only --diff-filter=d; git ls-files --others --exclude-standard; } 2>/dev/null \
+    | grep -iE '(^|/)(\.env(\..*)?|[^/]*\.pem|[^/]*credentials[^/]*|[^/]*\.key)$' | grep -viE '\.(example|sample|template)$')
+  hits=$({ git diff HEAD; git ls-files --others --exclude-standard -z | xargs -0 -r -I{} git diff --no-index /dev/null {}; } 2>/dev/null \
+    | grep -E '^\+' | grep -E 'AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|xox[abprs]-[A-Za-z0-9-]{10,}|[Bb]earer [A-Za-z0-9._~+/-]{20,}' | cut -c1-120)
+  [ -z "$names$hits" ] && { echo "secrets none"; return 0; }
+  echo "secrets FOUND — STOP and tell the user; suggest gitleaks or git-secrets as a pre-commit guard:"
+  [ -n "$names" ] && printf '%s\n' "$names" | sed 's/^/  file /'
+  [ -n "$hits" ] && printf '%s\n' "$hits" | sed 's/^/  line /'
+  return 1
+}
+
+CHECKS_FAILED='[.statusCheckRollup[]? | select(((.conclusion // .state) // "") | test("FAILURE|ERROR|CANCELLED|TIMED_OUT|ACTION_REQUIRED")) | (.name // .context)] | join(",")'
+CHECKS_RUNNING='[.statusCheckRollup[]? | select((.status // .state // "") | test("IN_PROGRESS|QUEUED|PENDING|WAITING")) | (.name // .context)] | join(",")'
+PR_JQ="[.number, .isDraft, .mergeable, (.reviewDecision // \"\"), ($CHECKS_FAILED), ($CHECKS_RUNNING), .baseRefName, .headRefName] | map(tostring) | join(\"|\")"
+
+merge_check() {  # merge_check [pr]; sets PR_BASE and PR_HEAD
+  local line n draft mergeable review failing pending why=""
+  line=$(gh pr view ${1:+"$1"} --json number,isDraft,mergeable,reviewDecision,statusCheckRollup,baseRefName,headRefName -q "$PR_JQ") || stop "no open PR found."
+  IFS='|' read -r n draft mergeable review failing pending PR_BASE PR_HEAD <<< "$line"
+  [ "$draft" = true ] && why="$why draft;"
+  [ "$mergeable" = CONFLICTING ] && why="$why conflicts with the base;"
+  [ -n "$failing" ] && why="$why CI failing: $failing;"
+  case "$review" in REVIEW_REQUIRED|CHANGES_REQUESTED) why="$why review: $review;" ;; esac
+  [ -n "$pending" ] && why="$why CI still running: $pending;"
+  [ -z "$why" ] && { echo "merge ok #$n"; return 0; }
+  echo "merge STOP #$n:$why"; return 1
+}
+
+land() {  # land <pr> [squash|merge]
+  local worktree=""
+  [ -n "${1:-}" ] || stop "usage: ship-prep.sh land <pr> [squash|merge]"
+  merge_check "$1" >/dev/null || { merge_check "$1"; exit 1; }
+  [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && worktree=1
+  if [ "${2:-squash}" = merge ]; then gh pr merge "$1" --merge || stop "gh pr merge failed."
+  elif [ -n "$worktree" ]; then
+    # gh --delete-branch switches the local checkout, which a worktree cannot; delete the branch on origin instead.
+    gh pr merge "$1" --squash || stop "gh pr merge failed."
+    git push -q origin --delete "$PR_HEAD" 2>/dev/null
+  else gh pr merge "$1" --squash --delete-branch || stop "gh pr merge failed."; fi
+  if [ -n "$worktree" ]; then
+    git fetch -q origin 2>/dev/null
+    echo "landed #$1; this is a worktree, so it stays on its branch — close the session to remove it"
+  else
+    git checkout -q "$PR_BASE" && git pull -q --ff-only origin "$PR_BASE" 2>/dev/null
+    echo "landed #$1; now on $(git branch --show-current) at $(git rev-parse --short HEAD)"
+  fi
+}
+
+release() {
+  local tag v major minor patch commits breaking feat next
+  git fetch -q --tags origin 2>/dev/null
+  tag=$(git tag --sort=-v:refname | head -1)
+  [ -n "$tag" ] || { echo "tag none; suggest v0.1.0 (confirm with the user)"; return 0; }
+  commits=$(git log "$tag"..HEAD --format='%s')
+  [ -n "$commits" ] || stop "no commits since $tag — nothing to release."
+  v=${tag##*[!0-9.]}; IFS=. read -r major minor patch <<< "$v"
+  breaking=$(( $(printf '%s\n' "$commits" | grep -cE '^[a-z]+(\([^)]*\))?!:') + $(git log "$tag"..HEAD --format=%B | grep -c 'BREAKING CHANGE') ))
+  feat=$(printf '%s\n' "$commits" | grep -cE '^feat(\([^)]*\))?!?:')
+  if [ "$major" -ge 1 ]; then
+    if [ "$breaking" -gt 0 ]; then next="$((major+1)).0.0"; elif [ "$feat" -gt 0 ]; then next="$major.$((minor+1)).0"; else next="$major.$minor.$((patch+1))"; fi
+  elif [ "$breaking" -gt 0 ]; then next="0.$((minor+1)).0"
+  else next="0.$minor.$((patch+1))"; fi
+  echo "tag $tag"
+  echo "suggest ${tag%"$v"}$next (confirm with the user)"
+  printf '%s\n' "$commits" | sed 's/^/  /'
+}
+
+case "${1:-}" in
+  start) start ;;
+  scope) scope ;;
+  secrets) secrets ;;
+  merge) merge_check "${2:-}" ;;
+  land) land "${2:-}" "${3:-}" ;;
+  release) release ;;
+  *) echo "usage: ship-prep.sh start | scope | secrets | merge [pr] | land <pr> [squash|merge] | release" >&2; exit 2 ;;
+esac

package/hooks/skill-flags-record.sh

@@ -26,4 +26,7 @@ BRANCH=$(git -C "${CWD:-$PROJECT_DIR}" branch --show-current 2>/dev/null | json_
 printf '{"ts":"%s","branch":"%s","model":"%s","reply":"%s"}\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$BRANCH" "$MODEL" "$REPLY" \
   >> "$(diary_dir "$SCRIPT_DIR")/$LOG"
 
+case "$LOG" in skill-flags.jsonl) STEP=audit ;; *) STEP=review ;; esac
+SHIP_LOG_ROOT="${CWD:-$PROJECT_DIR}" node "$SCRIPT_DIR/ship-log.mjs" step "$STEP" end >/dev/null 2>&1
+
 exit 0

package/hooks/skill-gate.sh

@@ -4,6 +4,7 @@
 INPUT=$(cat)
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+. "$SCRIPT_DIR/gate-config.sh"
 PROJECT_DIR="$(dirname "$(dirname "$SCRIPT_DIR")")"
 
 if ! find "$PROJECT_DIR" -path '*/.claude/skills/*/SKILL.md' 2>/dev/null | grep -q .; then
@@ -130,25 +131,14 @@ if [ -n "$TARGETS" ]; then
     #
     # The value must be quoted in YAML either way: a scalar opening with * is
     # an alias indicator.
-    UNQUOTE='s/^["'"'"']//; s/["'"'"']$//'
-    SPATHS=$(sed -n 's/^[[:space:]]*gate-paths:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
-    STRACKS=$(sed -n 's/^tracks:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
-    SNAME=$(sed -n 's/^name:[[:space:]]*//p' "$SKILL_FILE" | head -1 | sed "$UNQUOTE")
+    SPATHS=$(skill_field "$SKILL_FILE" '[[:space:]]*gate-paths')
+    STRACKS=$(skill_field "$SKILL_FILE" tracks)
+    SNAME=$(skill_field "$SKILL_FILE" name)
     [ -z "$SPATHS" ] && continue
     [ -z "$SNAME" ] && continue
     case "$INSTALLED" in *"\"$SNAME\""*) ;; *) continue ;; esac  # automark marks only installed and custom skills
-
-    HIT=""
-    for G in $(printf '%s' "$SPATHS" | tr ',' ' '); do
-      # Claude Code writes these gitignore-style. A case glob has no **, but *
-      # already crosses / here, so dropping the **/ prefix is equivalent.
-      G=$(printf '%s' "$G" | sed 's!\*\*/!!g')
-      case "$G" in \**|/*) ;; *) G="*$G" ;; esac
-      for T in $TARGETS; do
-        case "$T" in $G) HIT=1 ;; esac
-      done
-    done
-    [ -z "$HIT" ] && continue
+    # shellcheck disable=SC2086
+    [ -n "$(skill_hits "$SPATHS" $TARGETS)" ] || continue
 
     # A .tsx file is not proof of React — it could be Astro, Solid or Preact.
     # The packages the skill tracks are the proof, so the manifests decide.

package/lib/setup-hook.mjs

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 //   ship-gate-projects.sh     sourced by ship-gate.sh — project detection, reuse
 //   ship-gate-hook.sh         PreToolUse on Bash — no commit without a receipt
 //   ship-mark.sh              written by /ship — no PR on a branch /ship never ran on
+//   ship-prep.sh              run by /ship — prechecks, scope and skills in one call
 //   version-check.sh          SessionStart — a line when a newer catalog exists
 //   skill-flags-record.sh     SubagentStop — logs each skills-audit verdict
 //   skill-report.mjs          read by /skill-report — tallies that log
@@ -55,6 +56,7 @@ const SHIP_LOG_FILENAME = "ship-log.mjs";
 const SHIP_LOG_PARSE_FILENAME = "ship-log-parse.mjs";
 const SHIP_LOG_REPORT_FILENAME = "ship-log-report.mjs";
 const SHIP_MARK_FILENAME = "ship-mark.sh";
+const SHIP_PREP_FILENAME = "ship-prep.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
 const LEGACY_AUDIT_RUNNER_FILENAME = "skill-audit-runner.sh";
 
@@ -163,6 +165,7 @@ export async function setupHook(targetDir = process.cwd()) {
     SHIP_LOG_PARSE_FILENAME,
     SHIP_LOG_REPORT_FILENAME,
     SHIP_MARK_FILENAME,
+    SHIP_PREP_FILENAME,
   ]) {
     const dest = join(hooksDir, name);
     await writeFile(dest, await readHookSource(name), { mode: 0o755 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.56.3",
+  "version": "2.57.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/gate-config.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 ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs ../scripts/diary-check.mjs ../scripts/diary-lib.mjs ../scripts/ship-log.mjs ../scripts/ship-log-parse.mjs ../scripts/ship-log-report.mjs ../scripts/ship-mark.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/gate-config.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 ../scripts/skill-flags-record.sh ../scripts/skill-report.mjs ../scripts/edit-check.sh ../scripts/line-limit.sh ../scripts/lint-ratchet.mjs ../scripts/text-rules.mjs ../scripts/ratchet-baseline.mjs ../scripts/diary-check.mjs ../scripts/diary-lib.mjs ../scripts/ship-log.mjs ../scripts/ship-log-parse.mjs ../scripts/ship-log-report.mjs ../scripts/ship-mark.sh ../scripts/ship-prep.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {