Add husky for branch protection rules, update GitHub Actions

Author: webstackdev

.github/pull_request_template.md

@@ -0,0 +1,60 @@
+## Description
+
+<!-- Provide a brief description of the changes in this PR -->
+
+## Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] 🐛 Bug fix (bugfix/*)
+- [ ] 🔥 Hot fix (hotfix/*)
+- [ ] ✨ New feature (feature/*)
+- [ ] 🏗️ Infrastructure (infrastructure/*)
+- [ ] 📝 Content update (content/*)
+- [ ] 📚 Documentation
+- [ ] 🎨 Style/UI change
+- [ ] ♻️ Code refactoring
+
+## Changes Made
+
+<!-- List the main changes in this PR -->
+
+-
+-
+-
+
+## Related Issues
+
+<!-- Link to related issues, e.g., Closes #123, Fixes #456 -->
+
+Closes #
+
+## Testing
+
+<!-- Describe the testing you've done -->
+
+- [ ] Unit tests pass locally (`npm run test:unit`)
+- [ ] E2E tests pass locally (`npm run test:e2e:ready`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] Manually tested in browser
+
+## Screenshots (if applicable)
+
+<!-- Add screenshots for UI changes -->
+
+## Checklist
+
+- [ ] My branch name follows the conventions (feature/*, bugfix/*, etc.)
+- [ ] My code follows the project's coding standards
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings or errors
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## Additional Notes
+
+<!-- Any additional information that reviewers should know -->

.github/workflows/branch-protection.yml

@@ -0,0 +1,46 @@
+name: Branch Protection
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  check-branch-name:
+    name: Validate Branch Name
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check branch naming convention
+        run: |
+          BRANCH_NAME="${{ github.head_ref }}"
+
+          # Valid patterns: bugfix/, hotfix/, feature/, infrastructure/, content/
+          if [[ ! $BRANCH_NAME =~ ^(bugfix|hotfix|feature|infrastructure|content)/[a-z0-9-]+$ ]]; then
+            echo "❌ Invalid branch name: $BRANCH_NAME"
+            echo ""
+            echo "Branch names must follow one of these patterns:"
+            echo "  - bugfix/<description>     (e.g., bugfix/fix-navigation-menu)"
+            echo "  - hotfix/<description>     (e.g., hotfix/critical-security-patch)"
+            echo "  - feature/<description>    (e.g., feature/add-contact-form)"
+            echo "  - infrastructure/<desc>    (e.g., infrastructure/setup-ci)"
+            echo "  - content/<description>    (e.g., content/update-about-page)"
+            echo ""
+            echo "Use lowercase letters, numbers, and hyphens only."
+            exit 1
+          fi
+
+          echo "✅ Branch name is valid: $BRANCH_NAME"
+
+  check-pr-target:
+    name: Verify PR Target
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ensure PR targets main
+        run: |
+          TARGET_BRANCH="${{ github.base_ref }}"
+
+          if [[ "$TARGET_BRANCH" != "main" ]]; then
+            echo "⚠️  Warning: PR is targeting '$TARGET_BRANCH' instead of 'main'"
+            echo "This is allowed, but make sure this is intentional."
+          else
+            echo "✅ PR correctly targets 'main' branch"
+          fi

.github/workflows/build-and-test.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20.x"
+          node-version: "22.x"
           cache: 'npm'
 
       - name: Install dependencies

.github/workflows/playwright.yml

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# Run unit tests (fast feedback)
+nvm use default && npm run test:unit
+
+# Verify branch naming convention
+.husky/scripts/check-branch-name.sh
+
+# Prevent commits directly to main
+.husky/scripts/prevent-main-commits.sh

.husky/pre-commit

@@ -0,0 +1,30 @@
+#!/bin/sh
+
+# Get current branch name
+branch=$(git symbolic-ref --short HEAD)
+
+# Define valid branch name patterns
+valid_patterns="^(bugfix|hotfix|feature|infrastructure|content)\/[a-z0-9-]+$"
+
+# Allow main and develop branches (for merges)
+if [ "$branch" = "main" ] || [ "$branch" = "develop" ]; then
+  exit 0
+fi
+
+# Check if branch name matches valid patterns
+if ! echo "$branch" | grep -Eq "$valid_patterns"; then
+  echo "❌ Invalid branch name: $branch"
+  echo ""
+  echo "Branch names must follow one of these patterns:"
+  echo "  - bugfix/<description>     (e.g., bugfix/fix-navigation-menu)"
+  echo "  - hotfix/<description>     (e.g., hotfix/critical-security-patch)"
+  echo "  - feature/<description>    (e.g., feature/add-contact-form)"
+  echo "  - infrastructure/<desc>    (e.g., infrastructure/setup-ci)"
+  echo "  - content/<description>    (e.g., content/update-about-page)"
+  echo ""
+  echo "Use lowercase letters, numbers, and hyphens only."
+  echo ""
+  exit 1
+fi
+
+exit 0

.husky/scripts/check-branch-name.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+
+# Get current branch name
+branch=$(git symbolic-ref --short HEAD)
+
+# Prevent direct commits to main
+if [ "$branch" = "main" ]; then
+  echo "❌ Direct commits to 'main' branch are not allowed!"
+  echo ""
+  echo "Please follow this workflow:"
+  echo "  1. Create a new branch:"
+  echo "     git checkout -b feature/your-feature-name"
+  echo ""
+  echo "  2. Make your changes and commit them"
+  echo ""
+  echo "  3. Push your branch and create a Pull Request:"
+  echo "     git push -u origin feature/your-feature-name"
+  echo ""
+  echo "Valid branch prefixes: bugfix/, hotfix/, feature/, infrastructure/, content/"
+  echo ""
+  exit 1
+fi
+
+exit 0

.husky/scripts/prevent-main-commits.sh

@@ -4,6 +4,37 @@
 
 @TODO: See here for utility components like shortcodes: <https://docs.astro.build/en/reference/api-reference/#astroslotsrender>
 
+## Contributing & Git Workflow
+
+This repository uses branch protection and automated quality checks. See [docs/GIT_WORKFLOW.md](./docs/GIT_WORKFLOW.md) for complete details.
+
+**Quick Start:**
+
+```bash
+# Create a feature branch (required - cannot commit to main)
+git checkout -b feature/your-feature-name
+
+# Make changes and commit (hooks will run automatically)
+git commit -m "Your message"
+
+# Push and create a Pull Request
+git push -u origin feature/your-feature-name
+```
+
+**Branch Naming:**
+
+- `feature/*` - New features
+- `bugfix/*` - Bug fixes
+- `hotfix/*` - Critical production fixes
+- `infrastructure/*` - DevOps/CI/CD changes
+- `content/*` - Content updates
+
+**Pre-commit Checks:**
+
+- Unit tests must pass
+- Branch name must follow conventions
+- Cannot commit directly to main
+
 ## Coding Standards
 
 ### Component Architecture

README.md

@@ -59,7 +59,8 @@
     "test:e2e:ui": "NODE_ENV=test npx playwright test --ui",
     "test:e2e:wip": "NODE_ENV=test npx playwright test --grep @wip",
     "test:unit": "NODE_ENV=test npx vitest run",
-    "upgrade": "npx @astrojs/upgrade"
+    "upgrade": "npx @astrojs/upgrade",
+    "prepare": "husky"
   },
   "dependencies": {
     "@astrojs/check": "0.9.4",
@@ -150,6 +151,7 @@
     "eslint-plugin-yml": "1.19.0",
     "happy-dom": "^20.0.2",
     "html-element-attributes": "^3.5.0",
+    "husky": "^9.1.7",
     "is-whitespace-character": "^2.0.1",
     "jsdom": "^27.0.0",
     "md-attr-parser": "^1.3.0",