From c3b0057b4438ed3080b80fe0c8611683138c1bd5 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 19 Apr 2026 07:54:47 -0500
Subject: chore(hooks): add tracked pre-commit hook via githooks/

Portable setup: pre-commit lives in githooks/ (tracked), activated
by `make install-hooks` which sets core.hooksPath. Survives fresh
clones.

The hook does two things on staged changes:
- Scans added lines for common credential patterns (AWS keys, sk-*
  tokens, BEGIN PRIVATE KEY blocks, api_key/password literals)
- Runs check-parens on staged .el files

Bypass with `git commit --no-verify` for confirmed false positives.
---
 Makefile            | 11 ++++++++++-
 githooks/pre-commit | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100755 githooks/pre-commit

diff --git a/Makefile b/Makefile
index d85a290b..a517c094 100644
--- a/Makefile
+++ b/Makefile
@@ -40,7 +40,7 @@ EMACS_TEST = $(EMACS_BATCH) -L $(TEST_DIR) -L $(MODULE_DIR)
 
 .PHONY: help targets test test-all test-unit test-integration test-file test-name \
         validate-parens validate-modules compile lint profile \
-        clean clean-compiled clean-tests reset
+        clean clean-compiled clean-tests reset install-hooks
 
 # Alias for help
 targets: help
@@ -70,6 +70,7 @@ help:
 	@echo "    make clean-compiled    - Remove .elc/.eln files only"
 	@echo "    make clean-tests       - Remove test artifacts only"
 	@echo "    make reset             - Reset to first launch (DESTRUCTIVE!)"
+	@echo "    make install-hooks     - Activate tracked git hooks (githooks/)"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make test-file FILE=test-custom-buffer-file-copy-whole-buffer.el"
@@ -365,3 +366,11 @@ reset:
 	@find $(EMACS_HOME) -name "*.eln" -type f -delete
 	@find $(EMACS_HOME) -name "*.elc" -type f -delete
 	@echo "✓ Reset complete"
+
+install-hooks:
+	@echo "Activating tracked git hooks from githooks/..."
+	@git config core.hooksPath githooks
+	@chmod +x githooks/* 2>/dev/null || true
+	@echo "✓ core.hooksPath set to githooks/"
+	@echo "  Active hooks:"
+	@ls -1 githooks/ 2>/dev/null | grep -v '\.md$$' | sed 's/^/    /'
diff --git a/githooks/pre-commit b/githooks/pre-commit
new file mode 100755
index 00000000..909cde22
--- /dev/null
+++ b/githooks/pre-commit
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Pre-commit hook: secret scan + paren validation on staged .el files.
+# Use `git commit --no-verify` to bypass for confirmed false positives.
+
+set -u
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# --- 1. Secret scan ---
+# Patterns for common credentials. Scans only added lines in the staged diff.
+SECRET_PATTERNS='(AKIA[0-9A-Z]{16}|sk-[a-zA-Z0-9_-]{20,}|-----BEGIN (RSA|DSA|EC|OPENSSH|PGP)( PRIVATE)?( KEY| KEY BLOCK)?-----|(api[_-]?key|api[_-]?secret|auth[_-]?token|secret[_-]?key|bearer[_-]?token|access[_-]?token|password)[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']{16,}["'"'"'])'
+
+secret_hits="$(git diff --cached -U0 --diff-filter=AM \
+  | grep '^+' | grep -v '^+++' \
+  | grep -iEn "$SECRET_PATTERNS" || true)"
+
+if [ -n "$secret_hits" ]; then
+  echo "pre-commit: potential secret in staged changes:" >&2
+  echo "$secret_hits" >&2
+  echo "" >&2
+  echo "Review the lines above. If this is a false positive (test fixture, documentation)," >&2
+  echo "bypass with: git commit --no-verify" >&2
+  exit 1
+fi
+
+# --- 2. Paren check on staged .el files ---
+staged_el="$(git diff --cached --name-only --diff-filter=AM | grep '\.el$' || true)"
+
+if [ -n "$staged_el" ]; then
+  paren_fail=""
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    [ -f "$f" ] || continue
+    if ! out="$(emacs --batch --no-site-file --no-site-lisp "$f" \
+                  --eval '(check-parens)' 2>&1)"; then
+      paren_fail="${paren_fail}${f}:
+${out}
+
+"
+    fi
+  done <<< "$staged_el"
+
+  if [ -n "$paren_fail" ]; then
+    printf 'pre-commit: paren check failed:\n\n%s' "$paren_fail" >&2
+    exit 1
+  fi
+fi
+
+exit 0
-- 
cgit v1.2.3