37 lines
2.6 KiB
Markdown
37 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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`.
|