# gmfind

A Python CLI tool for finding and purchasing Steam games. Check deals, view compatibility ratings, and manage your library from the terminal.

## Features

- **Game Discovery**: Find discounted games filtered by price, Metacritic score, ProtonDB rating, and Steam Deck compatibility.
- **Compatibility Checks**: Get ProtonDB and Steam Deck verification status for any game.
- **Smart Filtering**: Exclude games you already own, match blocklist patterns, and enforce preference criteria.
- **Headless Purchasing**: Buy games using your Steam Wallet with Playwright browser automation.
- **Private Profile Support**: Export your game library even with a private Steam profile.

## Requirements

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
- Steam account with Steam Wallet funds (for purchases)

## Installation

```bash
# Clone and install
git clone https://github.com/your-username/steam-bot.git
cd steam-bot
uv pip install -e .

# Initialize (installs Playwright browsers and creates config templates)
gmfind init
```

## Configuration

Set your Steam credentials as environment variables:

```bash
export STEAM_USERNAME="your_username"
export STEAM_PASSWORD="your_password"
export STEAM_ID="76561198xxxxxxxxx"
```

Or create a `.env` file in your working directory (for development).

### Config Files

Config files are stored in platform-specific locations:
- **Linux**: `~/.config/gmfind/`
- **macOS**: `~/Library/Application Support/gmfind/`
- **Windows**: `%APPDATA%\gmfind\`

Files:
- `config.yaml` - Preferences (max price, min ratings, etc.)
- `block_list.yaml` - Game title patterns to exclude

## Usage

### Check Game Details
Get comprehensive info including price, ProtonDB rating, Steam Deck status, and reviews:
```bash
gmfind check 1145350
```

### Find Deals
Find discounted games matching your preferences:
```bash
gmfind deals           # Find 10 deals
gmfind deals 5         # Find 5 deals
gmfind deals --output ./deals.md   # Save to file
```

### Purchase a Game
Buy a game by App ID (validates against your config first):
```bash
gmfind buy 1145350            # Buy specific game
gmfind buy 1145350 --force    # Skip validation checks
gmfind buy 1145350 --headful  # Show browser window
gmfind buy --auto             # Autonomous: balance -> recommend -> buy
```

### Check Wallet Balance
```bash
gmfind balance
```

### Export Game Library
```bash
gmfind inventory --private    # Browser-based (works with private profiles)
gmfind inventory --public     # API-based (requires public profile)
```

### Check Blocklist
```bash
gmfind blocklist "FIFA 24"
```

### Global Options
```bash
gmfind --version     # Show version
gmfind --verbose     # Enable debug logging
gmfind <cmd> --help  # Command-specific help
```

### Per-Command Options
Most commands accept config overrides:
```bash
gmfind deals 5 --config ./config.yaml --block-list ./blocklist.yaml
gmfind check 1145350 --inventory ./my_games.csv
```

## Project Structure

```
steam-bot/
├── pyproject.toml              # Package configuration
├── src/gmfind/                 # Package source
│   ├── cli.py                  # CLI entry point (subcommands)
│   ├── config.py               # Configuration loading (Pydantic)
│   ├── paths.py                # XDG-compliant path handling
│   ├── steam_auth.py           # Headless authentication
│   ├── buy_game.py             # Purchase flow
│   ├── check_balance.py        # Wallet balance
│   ├── game_check.py           # Game details aggregator
│   ├── find_deals.py           # Deal discovery
│   ├── report_generator.py     # Markdown report output
│   ├── blocklist_checker.py    # Title filtering
│   ├── inventory.py            # API-based library export
│   ├── inventory_private.py    # Browser-based library export
│   └── recommendations/        # Rating clients
│       ├── protondb.py
│       ├── steam_deck.py
│       └── metacritic.py
```

## Development

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run checks
uv run ruff check .         # Lint
uv run ruff format .        # Format
uv run mypy src/gmfind      # Type check
```

## Security

- Credentials are read from environment variables, never stored in config files.
- Session data is stored locally in XDG data directory.
- Browser automation uses real Chromium with human-like behavior.

## License

MIT License - see [LICENSE](LICENSE) for details.
