# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

SmileyFace is a Python CLI tool for automating Unreal Tournament 4 (UT4) server administration. It handles building local server instances from custom maps/mutators/configs, deploying them to remote game and redirect servers via rsync/SSH, and managing server lifecycle (start/stop/restart).

## Commands

```bash
# Install dependencies
poetry install

# Run the tool
python smileyface.py --help

# Format code
black smileyface/
isort --profile black --filter-files smileyface/

# Lint
flake8 smileyface/

# Run pre-commit hooks manually
pre-commit run --all-files
```

There is no test suite.

## Code Style

- **Black** formatter: 120 char line length, target Python 3.13
- **isort**: profile black, multi_line_output=3, trailing commas, force_grid_wrap=3
- **flake8**: 120 char max, ignores E121/E123/E126/E226/E24/E704/W605

## Architecture

The app uses **Click** for CLI dispatch, **pydantic-settings** for configuration, and stdlib `logging` for log management.

**Entry point**: `smileyface.py` (project root) imports `smileyface.start_app()` which invokes the Click CLI.

**Configuration**: `AppSettings` (`settings.py`) is a pydantic `BaseSettings` model. Config is loaded from environment variables (prefix `SMILEYFACE_`) or a `.env` file. See `.env.example` for all available settings.

**Context**: `AppContext` (`context.py`) holds the `settings` instance and a dict-like `log` accessor. Passed to all command classes as `ctx`.

**CLI**: `cli.py` defines Click commands that instantiate the context and delegate to class methods.

**Key classes**:
- `UT4ServerMachine` (`hub_machine.py`) - Core logic. Each CLI subcommand (generate_instance, upload_server, upload_redirects, etc.) is a method here. This is the largest and most important file.
- `DataLayer` (`datalayer/datalayer.py`) - Lazy SQLite3 connection wrapper.
- `DbFuncs` (`datalayer/db_ops.py`) - Database operations for tracking pak file state (MD5 sums, validation).
- `GameIniSpecial` (`gameconfig_edit.py`) - Generates redirect references in Game.ini for custom pak files.

**Deployment flow**: `oneclickdeploy` chains `generate_instance` -> `upload_redirects` -> `upload_server`. The generate step builds a local instance directory with the server binary, configs, maps, and mutators. Upload steps rsync to remote hosts.

**Scraping module** (`scrape_latest/`) uses Selenium to scrape pak file listings from ut4pugs.us and utcc.unrealpugs.com for MD5 validation against local files.