Skip to content
Shell

feat(hooks): add GitHub Workflow Guardian hook

eddiebe1474a7b35aeb826
diff --git a/hooks/github-workflow-guardian.sh b/hooks/github-workflow-guardian.sh
new file mode 100755
index 0000000..e1f0f65
--- /dev/null
+++ b/hooks/github-workflow-guardian.sh
@@ -0,0 +1,240 @@
+#!/bin/bash
+# ============================================================================
+# GITHUB WORKFLOW GUARDIAN - "The Guardian"
+# ============================================================================
+# A blocking hook that enforces GitHub workflow best practices before
+# allowing code changes. Prevents common build failures like:
+# - Missing module imports
+# - Components with non-existent dependencies
+# - Direct pushes to protected branches
+# - Commits with missing/failing builds
+#
+# Part of: ID8Pipeline Quality Enforcement System
+# Author: ID8Labs
+# Version: 1.0.0
+#
+# BLOCKING ISSUES (exit 2):
+# - CRITICAL: Missing imports/modules that would break build
+# - ERROR: Working on protected branch
+# - WARNING: TypeScript errors in modified files
+#
+# NON-BLOCKING (exit 0 with warning):
+# - INFO: Uncommitted changes, suggested improvements
+#
+# Usage: Triggered automatically via PostToolUse hook on Edit|Write
+# ============================================================================
+
+set -uo pipefail
+
+# Read input from stdin (Claude Code hook format)
+INPUT=$(cat)
+
+# Extract file path from tool input
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+# If no file path, try to get from positional arg
+if [[ -z "$FILE_PATH" ]]; then
+ FILE_PATH="${1:-}"
+fi
+
+# Exit if no file path or not a code file
+if [[ -z "$FILE_PATH" || ! -f "$FILE_PATH" ]]; then
+ exit 0
+fi
+
+# Get file extension
+FILE_EXT="${FILE_PATH##*.}"
+
+# Only check TypeScript/JavaScript files
+case "$FILE_EXT" in
+ ts|tsx|js|jsx)
+ ;;
+ *)
+ exit 0
+ ;;
+esac
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+log() { echo -e "${CYAN}[GUARDIAN]${NC} $1"; }
+warn() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
+error() { echo -e "${RED}[ERROR]${NC} $1"; }
+pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+block() { echo -e "${RED}[BLOCKED]${NC} $1"; }
+
+BLOCKING_ISSUES=0
+WARNINGS=0
+REVIEW_REPORT=""
+
+add_issue() {
+ local severity="$1"
+ local message="$2"
+ REVIEW_REPORT="${REVIEW_REPORT}\n - [$severity] $message"
+
+ if [[ "$severity" == "CRITICAL" || "$severity" == "ERROR" ]]; then
+ BLOCKING_ISSUES=$((BLOCKING_ISSUES + 1))
+ else
+ WARNINGS=$((WARNINGS + 1))
+ fi
+}
+
+# Get working directory from file path
+WORK_DIR=$(dirname "$FILE_PATH")
+while [[ ! -f "$WORK_DIR/package.json" && "$WORK_DIR" != "/" ]]; do
+ WORK_DIR=$(dirname "$WORK_DIR")
+done
+
+if [[ ! -f "$WORK_DIR/package.json" ]]; then
+ # Not in a Node.js project
+ exit 0
+fi
+
+cd "$WORK_DIR" || exit 0
+
+log "Checking: $FILE_PATH"
+
+# ==========================================
+# 1. IMPORT RESOLUTION CHECK
+# ==========================================
+# This is the key check that would have caught NorthStarConsole
+
+log "Validating imports..."
+
+# Extract imports from the file
+IMPORTS=$(grep -E "^import .* from ['\"](@/|\.\.?/)" "$FILE_PATH" 2>/dev/null || true)
+
+if [[ -n "$IMPORTS" ]]; then
+ while IFS= read -r import_line; do
+ # Extract the path from the import
+ IMPORT_PATH=$(echo "$import_line" | sed -n "s/.*from ['\"]\\([^'\"]*\\)['\"].*/\\1/p")
+
+ if [[ -z "$IMPORT_PATH" ]]; then
+ continue
+ fi
+
+ # Resolve @/ paths to src/
+ if [[ "$IMPORT_PATH" == @/* ]]; then
+ RESOLVED_PATH="src/${IMPORT_PATH#@/}"
+ else
+ # Relative path
+ FILE_DIR=$(dirname "$FILE_PATH")
+ RESOLVED_PATH="$FILE_DIR/$IMPORT_PATH"
+ fi
+
+ # Check if import exists
+ FOUND=false
+ for ext in "" ".ts" ".tsx" ".js" ".jsx" "/index.ts" "/index.tsx" "/index.js"; do
+ CHECK_PATH="${RESOLVED_PATH}${ext}"
+ if [[ -f "$CHECK_PATH" ]]; then
+ FOUND=true
+ break
+ fi
+ done
+
+ if [[ "$FOUND" == false ]]; then
+ # This is critical - would break the build
+ add_issue "CRITICAL" "Missing module: $IMPORT_PATH"
+
+ # Special message for stores
+ if [[ "$IMPORT_PATH" == *"stores/"* ]]; then
+ STORE_NAME=$(basename "$IMPORT_PATH")
+ REVIEW_REPORT="${REVIEW_REPORT}\n πŸ’‘ Store '$STORE_NAME' does not exist. Create it first!"
+ fi
+ fi
+ done <<< "$IMPORTS"
+fi
+
+# ==========================================
+# 2. TYPESCRIPT QUICK CHECK
+# ==========================================
+
+if [[ -f "tsconfig.json" ]]; then
+ log "Running TypeScript check..."
+
+ # Quick type check on the specific file's related modules
+ TSC_OUTPUT=$(npx tsc --noEmit --skipLibCheck 2>&1 | grep -E "error TS" | head -5 || true)
+
+ if [[ -n "$TSC_OUTPUT" ]]; then
+ # Check if errors are in the modified file
+ if echo "$TSC_OUTPUT" | grep -q "$(basename "$FILE_PATH")"; then
+ add_issue "ERROR" "TypeScript errors in modified file"
+ REVIEW_REPORT="${REVIEW_REPORT}\n $(echo "$TSC_OUTPUT" | head -3)"
+ fi
+ else
+ pass "TypeScript: Clean"
+ fi
+fi
+
+# ==========================================
+# 3. BRANCH PROTECTION CHECK
+# ==========================================
+
+if git rev-parse --git-dir > /dev/null 2>&1; then
+ CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+ if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" || "$CURRENT_BRANCH" == "develop" ]]; then
+ add_issue "ERROR" "Modifying code on protected branch '$CURRENT_BRANCH'"
+ REVIEW_REPORT="${REVIEW_REPORT}\n πŸ’‘ Create a feature branch: git checkout -b feature/<name>"
+ fi
+fi
+
+# ==========================================
+# 4. LAYOUT/CRITICAL COMPONENT WARNING
+# ==========================================
+
+if [[ "$FILE_PATH" == *"components/layout/"* || "$FILE_PATH" == *"/app/"* ]]; then
+ warn "Modifying critical component - build verification recommended"
+ add_issue "INFO" "Critical path modification: run 'npm run build' before commit"
+fi
+
+# ==========================================
+# 5. OUTPUT REVIEW
+# ==========================================
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "GITHUB WORKFLOW GUARDIAN"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [[ $BLOCKING_ISSUES -eq 0 && $WARNINGS -eq 0 ]]; then
+ pass "All workflow checks passed!"
+ echo ""
+ exit 0
+elif [[ $BLOCKING_ISSUES -eq 0 ]]; then
+ warn "Found $WARNINGS warning(s):"
+ echo -e "$REVIEW_REPORT"
+ echo ""
+ echo "ℹ️ Non-blocking - proceeding with caution"
+ echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+ exit 0
+else
+ error "Found $BLOCKING_ISSUES blocking issue(s):"
+ echo -e "$REVIEW_REPORT"
+ echo ""
+ echo "πŸ›‘ ═══════════════════════════════════════════════════════"
+ echo " BLOCKED: Fix these issues before proceeding"
+ echo ""
+ echo " This prevents build failures in CI/CD pipeline."
+ echo ""
+ if echo "$REVIEW_REPORT" | grep -q "Missing module"; then
+ echo " To fix missing imports:"
+ echo " 1. Create the missing module/store, OR"
+ echo " 2. Remove the import from this file"
+ fi
+ if echo "$REVIEW_REPORT" | grep -q "protected branch"; then
+ echo " To fix branch issue:"
+ echo " 1. Stash changes: git stash"
+ echo " 2. Create branch: git checkout -b feature/<name>"
+ echo " 3. Pop changes: git stash pop"
+ fi
+ echo "═══════════════════════════════════════════════════════════"
+
+ # Exit code 2 = blocking error
+ exit 2
+fi
diff --git a/settings.json b/settings.json
index 2e31d33..cbed16b 100644
--- a/settings.json
+++ b/settings.json
@@ -8,6 +8,21 @@
"type": "command",
"command": "~/.claude/hooks/code-review-gate.sh",
"timeout": 30000
+ },
+ {
+ "type": "command",
+ "command": "~/.claude/hooks/github-workflow-guardian.sh",
+ "timeout": 60000
+ }
+ ]
+ },
+ {
+ "matcher": "Bash",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "echo \"$TOOL_INPUT\" > /tmp/claude_last_command",
+ "timeout": 5000
}
]
}
@@ -17,8 +32,9 @@
"matcher": "",
"hooks": [
{
- "type": "prompt",
- "prompt": "Before proceeding to the next task, verify: (1) Did the code-review-gate report any issues? If so, fix them first. (2) For pipeline stages, ensure current stage checkpoint is cleared before advancing."
+ "type": "command",
+ "command": "~/.claude/hooks/verify-deployment.sh",
+ "timeout": 60000
}
]
}