2.6 KiB
Repository Guidelines
Project Structure & Module Organization
This repository is a small, script-first Python project. bot.py is the long-running Twitch IRC bot that controls MPD. _twitch.py holds shared Helix auth and token-refresh helpers for the CLI tools. search-game.py resolves free-form game queries to Twitch category IDs, and set-channel.py updates the channel title and game. examples/stream.sh is the interactive pre-stream wrapper that writes examples/stream.json. Keep secret-bearing runtime files in .env or .env.broadcaster; only the *.example templates are tracked.
Build, Test, and Development Commands
There is no package build step. Use direct script execution:
pip install python-mpd2
python3 bot.py
TWITCH_BOT_DEBUG=1 python3 bot.py
./search-game.py "DOOM"
./set-channel.py --dry-run --game-id 517520 "Stream title"
./examples/stream.sh
python3 bot.py runs the chat bot. TWITCH_BOT_DEBUG=1 dumps raw IRC lines for troubleshooting. The two CLI helpers are intended to be run directly, and stream.sh composes them into a guided flow.
Coding Style & Naming Conventions
Match the existing style: Python 3.10+, standard library first, minimal dependencies, and small top-level scripts instead of packages. Use 4-space indentation in Python and keep helpers simple and explicit. Follow the current naming pattern: snake_case for functions and variables, short module names for single-purpose scripts, and uppercase constants such as SKIP_COOLDOWN. Shell scripts should keep set -euo pipefail.
Testing Guidelines
There is no automated test suite yet. Before opening a PR, do targeted smoke tests for the code path you changed. Examples: run python3 bot.py against a local MPD instance, run ./search-game.py "Heroes", or use ./set-channel.py --dry-run ... to validate argument handling without issuing a PATCH. If you add tests later, place them under a new tests/ directory and use test_*.py.
Commit & Pull Request Guidelines
Git history is minimal; the current commit style is short and imperative (Initial version). Keep commits concise, scoped, and written in the imperative mood. PRs should explain the user-visible behavior change, note any .env or token-scope impact, and include terminal output or screenshots when changing interactive flows such as examples/stream.sh.
Security & Configuration Tips
Do not merge .env and .env.broadcaster. The bot account and broadcaster account require different scopes and are intentionally separated. Never commit live tokens or generated examples/stream.json.