# AGENTS.md

Guidelines for AI agents working on this codebase.

## Project Overview

This is a Python CLI tool for Debian package maintainers. It tracks packages with new upstream versions by querying the Debian UDD database.

## Architecture

- `debian_todo/` - Python package with core logic
- `todo` - CLI entry point script
- `tests/` - pytest test suite
- Rich library for terminal output (tables and formatting)
- python-debian library for parsing APT Sources files
- JSON-based caching for performance

## Key Components

### Data Flow
1. `fetch_todo_list()` - Downloads JSON from UDD
2. `filter_todo_list()` - Removes non-upstream items and pre-releases
3. `load_source_info_map()` - Parses APT Sources for Vcs-Git and uploaders
4. `list_todos()` - Renders output table

### Important Patterns
- Version normalization strips epoch and Debian revision
- Pre-release detection via regex (`alpha`, `beta`, `rc`, `a`, `b`)
- Team extraction from Vcs-Git URLs on salsa.debian.org
- Cache invalidation based on Sources file mtimes

## Code Style

- Type hints throughout (Python 3.10+ syntax)
- No external config files; constants at module top
- Functions are pure where possible
- Error handling is minimal; tool is for personal use

## Testing

Run tests with pytest:
```bash
PYTHONPATH=. pytest tests/ -v
```

Manual testing:
```bash
./todo list
./todo list --show-prerelease
./todo update
```

## Common Tasks

### Adding a new filter
Modify `filter_todo_list()` to add conditions.

### Changing output columns
Edit `list_todos()` - both table and narrow-mode branches.

### Updating cache format
Increment `CACHE_VERSION` to invalidate old caches.

## Dependencies

System packages (Debian):
- python3-click
- python3-debian
- python3-rich
- python3-pytest (for testing)

No pip/venv setup; uses system Python.