feat: enhance shell-check workflow for PR pre-merge validation

- Add pull_request_target trigger to check PRs from forks
- Add explicit failure message with instructions
- Create BRANCH_PROTECTION.md with setup guide
- Ensure workflow runs on all PRs targeting main/master

Co-authored-by: kuhyx <147418882+kuhyx@users.noreply.github.com>

.github/BRANCH_PROTECTION.md

@@ -0,0 +1,72 @@
+# Branch Protection and Pre-Merge Checks
+
+This repository uses GitHub Actions to ensure code quality before merging to `main` or `master` branches.
+
+## Required Checks
+
+### Shell Script Linting
+
+The `Shell Script Linting` workflow automatically runs on:
+- Pull requests targeting `main` or `master` branches
+- Direct pushes to `main` or `master` branches
+- Pull requests from forks (via `pull_request_target`)
+
+This workflow checks:
+- Shell script syntax with `shellcheck`
+- Code formatting with `shfmt` (2-space indentation, no tabs)
+- Optional checks: `checkbashisms`, syntax validation
+
+## Enabling Branch Protection
+
+To make the shell linting check **required** before merging PRs, follow these steps:
+
+1. Go to repository **Settings** → **Branches**
+2. Click **Add rule** or edit existing rule for `main`/`master`
+3. Configure the following settings:
+   - ✅ **Require a pull request before merging**
+   - ✅ **Require status checks to pass before merging**
+     - Search for and select: `Lint Shell Scripts`
+   - ✅ **Require branches to be up to date before merging** (recommended)
+   - ✅ **Do not allow bypassing the above settings** (recommended)
+4. Click **Create** or **Save changes**
+
+## Running Checks Locally
+
+Before pushing changes, run the linting script locally to catch issues early:
+
+```bash
+bash scripts/meta/shell_check.sh
+```
+
+This will:
+- Install required linters on Arch Linux (if needed)
+- Check all shell scripts in the repository
+- Report any formatting or syntax issues
+
+To auto-fix formatting issues:
+
+```bash
+# Install shfmt if not already installed
+# On Arch: sudo pacman -S shfmt
+# Or download from: https://github.com/mvdan/sh/releases
+
+# Fix formatting in-place
+find . -name "*.sh" -type f | xargs shfmt -w -i 2 -ci -sr -s
+```
+
+## What Gets Checked
+
+The workflow validates shell scripts with these extensions or shebangs:
+- `*.sh`, `*.bash`, `*.zsh` files
+- Executable files with shell shebangs (`#!/bin/bash`, `#!/bin/sh`, etc.)
+
+## Troubleshooting
+
+If the check fails on your PR:
+
+1. Review the workflow logs to see which files failed
+2. Run `bash scripts/meta/shell_check.sh` locally to reproduce
+3. Fix the issues (usually formatting with `shfmt -w -i 2 -ci -sr -s`)
+4. Commit and push the fixes
+
+The workflow will automatically re-run on new commits to the PR.

.github/workflows/shell-check.yml

@@ -17,6 +17,15 @@ on:
       - '**.zsh'
       - '.github/workflows/shell-check.yml'
       - 'scripts/meta/shell_check.sh'
+  # Also run on pull_request_target for forks to ensure all PRs are checked
+  pull_request_target:
+    branches: [ main, master ]
+    paths:
+      - '**.sh'
+      - '**.bash'
+      - '**.zsh'
+      - '.github/workflows/shell-check.yml'
+      - 'scripts/meta/shell_check.sh'
 
 jobs:
   shellcheck:
@@ -26,6 +35,9 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          # For pull_request_target, checkout the PR head
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
       
       - name: Install shellcheck
         run: |
@@ -48,3 +60,11 @@ jobs:
       - name: Report status
         if: success()
         run: echo "✅ All shell scripts passed linting checks!"
+      
+      - name: Fail on linting errors
+        if: failure()
+        run: |
+          echo "❌ Shell script linting failed!"
+          echo "This check is required to merge PRs into main/master."
+          echo "Please run 'bash scripts/meta/shell_check.sh' locally and fix any issues."
+          exit 1