beefy-player/AGENTS.md

AGENTS.md

Notes for coding agents working in this repository.

Re-sync the uv environment before doing anything

The checked-out .venv is not portable. It is built by uv sync, and its python symlink points at a uv-managed interpreter path belonging to whichever machine created it (for example /home/node/.local/share/uv/python/...). When the repository is re-synced from the host, that interpreter is gone, the symlink dangles, and every .venv/bin/* command fails with:

.venv/bin/python: No such file or directory

So always re-sync first — before tests, lint, the app, or any tooling:

uv sync

If it still fails, rebuild the environment once:

rm -rf .venv && uv sync

There is no project Python on PATH; use uv run <command> or the freshly synced .venv/bin/python explicitly.

Commands

uv sync                                # resync the environment (do this first)
uv run pytest                          # full test suite
uvx ruff check .                       # lint (ruff is not a project dependency)
uv run beefy-player --list             # station ids for the current catalogue
uv run python tools/ansi_art.py ...    # regenerate a provider's header art