FairBuddy

In order install necessary dependencies, run:

./boot.sh

Note: This bootstrap script is designed for Unix-like environments (Linux/macOS) and relies on common tools such as bash and standard CLI utilities. Supporting native Windows (e.g., PowerShell) would introduce additional maintenance overhead and platform-specific complexity. Since this bootstrap is intended for developer use only and not part of the end-user product, Linux/macOS are the primary supported environments. Windows users are encouraged to use WSL2 as a compatible execution environment.

Run FairBuddy

Use ./buddy.sh in CLI to gain access to all features. With ./buddy.sh --help you will get the complete usage overview (auto-generated).

E.g. run:

./buddy.sh test unit

for a unit test execution.

Pre-commit Hooks

This project uses prek to enforce code quality before each commit.

Setup

The hooks are installed automatically by boot.sh. To install them manually:

uv run prek install
uv run prek install --hook-type commit-msg

They can always be run by:

uv run prek run --all-files

or

./buddy test precommit

The same check is done remotely during PullRequest action runs.

What Gets Checked

On every commit the following hooks run automatically:

• Standard Hygiene Tasks - line endings, whitespaces, ...
• Ruff lint - checks Python code and auto-fixes issues
• Ruff format - formats Python code
• Commitizen - validates commit messages follow Conventional Commits
• PyProject validation - by validating the toml file
• MD Format - formats markdown files
• MD Linting - opinionated markdown formatting
• typos - detecting typos in code and fixing them
• shellcheck - checking shell scripts
• zizmor - linting GitHub actions
• ty- Python type checker
• complexipy - Python checker for cognitive complexity
• opengrep - Search security relevant patterns

Commit Message Format

Commit messages must follow Conventional Commits:

feat: add delete_item service
fix: correct DynamoDB table name
docs: update README with setup instructions
chore: bump ruff to 0.15.1

Docker Desktop Installation (for macOS)

This is required to run GitHub Actions locally with act.

You can install Docker Desktop using their own installer from https://www.docker.com/products/docker-desktop/ or using HomeBrew.

• Install Docker Desktop via Homebrew Cask:

  brew install --cask docker

• Open Docker Desktop from /Applications.

  Wait until the whale icon says “Docker is running”.

• Verify installation:

  docker info
  docker run hello-world

Running GitHub Actions Locally (act)

Once Docker Desktop is running:

• Install act:

  uv sync

• Create a .secrets file if your workflow uses secrets:

  AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
  AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
  AWS_DEFAULT_REGION=your_default_region_here
  PULUMI_CONFIG_PASSPHRASE=your_pulumi_passphrase_here
  

• Run the Pull Request workflow:

  act pull_request --secret-file .secrets

  or

  ./buddy.sh test action

Choose medium-Image if asked.