# AGENTS.md - Development Guide for not-my-ex

This document provides essential information for AI agents working on the `not-my-ex` codebase.

## Project Overview

`not-my-ex` is a Python CLI application that posts simultaneously to Mastodon and Bluesky. It supports posting text, images with alt text, and language detection.

## Essential Commands

### Development Setup
- **Install dependencies**: `uv sync` (uses uv package manager)
- **Run tests**: `uv run pytest` (includes Ruff linting and Mypy type checking)
- **Test with specific Python versions**: `uv run tox` (tests Python 3.10-3.14)

### Testing & Quality
- **Run all tests**: `uv run pytest`
- **Linting**: Ruff is automatically run with pytest via `--ruff` flag
- **Type checking**: Mypy is automatically run with pytest via `--mypy` flag
- **Test matrix**: Tests run on Python 3.10, 3.11, 3.12, 3.13, 3.14 (see `.woodpecker/test.yaml`)

### Building & Distribution
- **Build package**: Uses Hatchling build system (configured in `pyproject.toml`)
- **Install CLI**: `pip install not-my-ex` (installs as `not-my-ex` command)

## Code Organization

### Main Package Structure
- `not_my_ex/` - Main package
  - `__main__.py` - CLI entry point using Typer
  - `auth.py` - Authentication management (environment variables + encrypted cache)
  - `bluesky.py` - Bluesky API client
  - `mastodon.py` - Mastodon API client
  - `post.py` - Post data model and validation
  - `media.py` - Media handling (images, alt text)
  - `language.py` - Language detection and selection
  - `cli/` - CLI subcommands
    - `config.py` - Configuration management
    - `post.py` - Post command implementation

### Test Structure
- `tests/` - Comprehensive test suite
  - `conftest.py` - Test configuration and fixtures
  - `test_*.py` - Tests for each module
  - Test images: `image.jpeg`, `image.png`

## Key Patterns & Conventions

### Authentication System
- Two authentication methods: `EnvAuth` (environment variables) and `EncryptedAuth` (encrypted cache)
- Environment variables prefixed with `NOT_MY_EX_`
- Credentials stored in user cache directory: `~/.cache/not-my-ex/auth`

### API Clients
- Both Bluesky and Mastodon clients inherit from base `Client` class
- Async HTTP client using `httpx`
- Error handling through `ClientError` exceptions
- Automatic language detection using `eld` library

### Data Models
- `Post` class: text content, media, language, character limit validation
- `Media` class: image handling with alt text support
- Character limits: 300 for Bluesky, 1024 for Mastodon
- Image size limit: 1MB for Bluesky

### CLI Structure
- Built with Typer framework
- Main commands: `post`, `config`, `clean`
- Supports posting with images: `--images` and `--alt-texts`
- Can post images without text

## Testing Approach

### Test Patterns
- Uses `pytest` with `pytest-asyncio` for async tests
- Mock-based testing for API clients
- Test fixtures provide authentication data
- Tests include linting and type checking

### Test Environment
- Test credentials configured in `tests/conftest.py`
- Environment variables set automatically for tests
- Test images provided for media testing

## Important Gotchas

### Character Limits
- Bluesky: 300 characters
- Mastodon: 1024 characters
- When both clients are configured, uses the stricter limit (300)

### Image Handling
- Bluesky has 1MB image size limit
- Images are automatically resized if needed
- Alt text support for accessibility

### Language Detection
- Automatic detection using `eld` library
- Can be overridden with `--lang` flag or environment variable
- Uses ISO 639-1 language codes

### Authentication
- Environment variables take precedence over encrypted cache
- Missing credentials disable the respective client
- At least one client must be configured

## Development Workflow

1. **Make changes** to source code
2. **Run tests**: `uv run pytest` (validates code, types, and linting)
3. **Test multiple Python versions**: `uv run tox` (if needed)
4. **Commit changes** following existing patterns

## Environment Variables

See `README.md` for complete list, but key ones:
- `NOT_MY_EX_BSKY_EMAIL`, `NOT_MY_EX_BSKY_PASSWORD` - Bluesky credentials
- `NOT_MY_EX_MASTODON_TOKEN` - Mastodon access token
- `NOT_MY_EX_DEFAULT_LANG` - Default language code

## Dependencies

- **HTTP**: `httpx` for async requests
- **CLI**: `typer` for command-line interface
- **Language**: `eld` for language detection
- **Media**: `aiofiles` for async file operations
- **Security**: `cryptography` for encrypted storage
- **Testing**: `pytest`, `pytest-asyncio`, `pytest-mypy`, `pytest-ruff`

This project follows Python best practices with comprehensive testing, type hints, and modern async patterns.