README Refresh Validator - Claude Code Hook

#!/usr/bin/env bash
set -u

# Claude Code PostToolUse hook. When a README or package.json is edited, it
# checks the README for the standard-readme core sections (Install, Usage) and
# verifies that every CLI command exposed via package.json "bin" is mentioned.
# Advisory only - it always exits 0, never edits files - and fails open when jq
# is unavailable.

command -v jq >/dev/null 2>&1 || exit 0

sanitize_output() {
  # Strip ASCII control characters before printing untrusted package or path
  # names to the terminal.
  LC_ALL=C tr -d '\000-\037\177'
}

safe() {
  printf '%s' "$1" | sanitize_output
}

INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""')

readme=""
pkg=""
case "$FILE" in
  *README.md|*README.markdown|*Readme.md|*readme.md) readme="$FILE" ;;
  */package.json|package.json) pkg="$FILE" ;;
  *) exit 0 ;;
esac

dir=$(dirname -- "$FILE")
if [ -z "$readme" ]; then
  for c in "$dir/README.md" "README.md" "$dir/readme.md"; do
    [ -f "$c" ] && { readme="$c"; break; }
  done
fi
if [ -z "$pkg" ]; then
  for c in "$dir/package.json" "package.json"; do
    [ -f "$c" ] && { pkg="$c"; break; }
  done
fi

if [ -z "$readme" ] || [ ! -f "$readme" ]; then
  [ -n "$pkg" ] && echo "README refresh: no README found near $(safe "$FILE") - add one with Install and Usage sections (see standard-readme)." >&2
  exit 0
fi

low=$(tr '[:upper:]' '[:lower:]' < "$readme")

for sec in install usage; do
  if ! printf '%s' "$low" | grep -qE "^#{1,3}[[:space:]].*${sec}"; then
    echo "README refresh: missing a '${sec}' section (standard-readme expects Install and Usage)." >&2
  fi
done

if [ -n "$pkg" ] && [ -f "$pkg" ]; then
  bins=$(jq -r '
    if (.bin | type) == "object" then (.bin | keys[])
    elif (.bin | type) == "string" then (.name // empty)
    else empty end' -- "$pkg" 2>/dev/null)
  printf '%s\n' "$bins" | while IFS= read -r b; do
    [ -z "$b" ] && continue
    if ! printf '%s' "$b" | LC_ALL=C grep -qE '^[[:alnum:]_.@/:+-]+$'; then
      echo "README refresh: skipping package.json bin with unsupported characters: '$(safe "$b")'." >&2
      continue
    fi
    if ! grep -qiF -- "$b" "$readme"; then
      echo "README refresh: CLI command '$(safe "$b")' (from package.json bin) is not mentioned in $(safe "$readme")." >&2
    fi
  done
fi

exit 0