Owlbot/AGENTS.md

# Master Repository Guidelines

## Project Overview
Owlbot is a modular, event-driven chat bot for Owncast.
- Python `3.12+`
- Fully async stack (`aiohttp`, `aiosqlite`)
- Built-in features include custom commands, quote management, and recurring timers

## Project Structure & Module Organization
- Core package code lives in `owlbot/`.
- Public interfaces and extension hooks are under `owlbot/api/`.
- Built-in modules are in `owlbot/builtin_modules/` (for example `custom_commands/`, `quotes/`, `timers/`).
- Registry and loader infrastructure is in `owlbot/registries/` and `owlbot/module_loader.py`.
- Tests live in `tests/` and cover key runtime behavior.
- User-facing docs are in `docs/`, which is a **git submodule**. You need to pull it before you can read any documentation files (e.g. `git submodule update --init`). Start with `docs/Home.md`, then `docs/Modules.md` for extension work.
- Default runtime config template is `config.example.yaml`.

## Architecture
- Entry point: `owlbot/__main__.py` parses CLI/config, creates `Owlbot` (`bot.py`), then starts HTTP server (`http_server.py`) and `ModuleLoader` (`module_loader.py`).
- Dispatchers:
  - `EventDispatcher` (`registries/events.py`) routes by event type with priority ordering.
  - `CommandDispatcher` (`registries/commands.py`) parses chat commands and checks permissions.
  - `RouteDispatcher` (`registries/routes.py`) handles HTTP endpoints at `/owlbot/<module>` and `/owlbot/<module>/*`.
- Module loading:
  - `ModuleLoader` discovers built-in modules and user modules (`modules/`).
  - Two-phase process: import and collect decorated handlers, then run `@on_setup` hooks.
- Dependency container:
  - `ModuleContext` (`api/context.py`) provides `config`, `storage`, `owncast_client`, `commands`, `events`, `routes`, `http`, optional `admin_client`, and `logger`.
- Handler registration:
  - Use decorators: `@on_command`, `@on_event`, `@on_route`, `@on_setup`, `@on_teardown`.
  - Dynamic runtime registration is also supported via context registries.
- Storage:
  - `api/storage.py` wraps `aiosqlite` with per-module DB files, connection pooling, and auto-commit semantics.

## Build, Test, and Development Commands
- `uv sync`: install runtime and dev dependencies from `uv.lock`.
- `uv run owlbot`: run the bot.
- `uv run owlbot init`: scaffold `config.yaml` in the current directory.
- `uv run owlbot -c config.yaml`: run the bot with explicit config.
- `uv run pytest -v --cov --cov-report=`: run tests with coverage collection.
- `uv run pytest tests/test_storage.py`: run a single test file.
- `uv run pytest -k "test_name"`: run tests matching a name.
- `uv run coverage report`: print coverage summary.
- `uv run ruff format .`: apply formatting.
- `uv run ruff format --check --diff .`: check formatting without changing files.
- `uv run ruff check .`: run lint checks.
- `uv run mypy .`: run strict type checking.
- `uv run pip-audit --skip-editable`: audit dependencies for known vulnerabilities.
- `uv run codespell`: check spelling across the project.

## Creating Modules
- Read `docs/Modules.md` first, then focused references:
  - `docs/Modules-Events.md`
  - `docs/Modules-Commands.md`
  - `docs/Modules-Routes.md`
  - `docs/Modules-Config.md`

## Pre-Commit Checklist
Before committing any changes, always run the following checks and make sure they all pass:
1. `uv run ruff format --check --diff .` -- verify formatting is correct. If it fails, run `uv run ruff format .` to fix it automatically.
2. `uv run ruff check .` -- catch lint violations. Fix any issues before proceeding.
3. `uv run mypy .` -- confirm type safety. The project uses strict mode, so all type errors must be resolved.
4. `uv run pytest -v --cov --cov-report=` -- run the full test suite and confirm nothing is broken.
5. `uv run codespell` -- catch spelling mistakes in code, comments, and documentation.

Do not commit if any of these fail.

## Keeping Documentation in Sync
Whenever you make a change to the codebase, check the files in `docs/` to see if any documentation needs to be updated to reflect your changes. This includes things like new or modified commands, events, config options, module behavior, API surfaces, or adding entirely new modules.

Since `docs/` is a git submodule, doc updates require normal submodule workflow:
1. Commit doc changes in the docs repository.
2. Update this repository's `docs` submodule pointer to that commit.
3. Include the pointer update in the same PR as the code change.

## Coding Style & Quality
- Use 4-space indentation and full type hints.
- Keep compatibility with `pyproject.toml` settings.
- mypy runs in strict mode.
- Ruff controls formatting, linting, and import ordering.
- Naming: `snake_case` for functions/modules, `PascalCase` for classes.
- `owlbot/_version.py` is auto-generated by hatch-vcs and excluded from linting/coverage.
- Never commit real credentials (Owncast tokens, admin passwords, webhook secrets). Keep values in tracked files sanitized.

## Testing Guidelines
- Framework: `pytest` with `pytest-asyncio` (`asyncio_mode = auto`).
- Prefer real implementations over mocks where practical (especially storage behavior).
- Use parametrization for repetitive matrices, with clear IDs.
- Keep assertions explicit and specific.
- Add tests in `tests/` near related runtime behavior.
- When changing dispatchers, module loading, or HTTP routing behavior, add or update regression tests that exercise the changed flow.
- Run `uv run pytest -v --cov --cov-report=` before opening a PR.

## CI Parity
The pre-commit checklist mirrors `.gitea/workflows/ci.yml`. Keep local checks and CI checks aligned when adding or changing quality gates.
A separate `.gitea/workflows/audit.yml` runs `pip-audit` when dependencies change. Run `uv run pip-audit --skip-editable` locally when updating dependencies.