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)
git submodule update --init            # contrib/homebrew, the Homebrew tap
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

uvx ruff check . is the enforced lint and must pass. ruff format is not enforced: the tree is not format-clean (54 files would change), so never run a repo-wide reformat as a side effect of an unrelated change.

Packaging

contrib/ holds the two distribution channels, and they work differently:

• contrib/aur/ — plain tracked files (PKGBUILD, .SRCINFO), edited here. The package is not published in the AUR (sign-ups are closed), so makepkg -si from a checkout is the only route. _commit pins the archive the package builds from and must move with each release.
• contrib/homebrew/ — a git submodule of the tap at https://tildeforge.dev/beefcarver/homebrew, not a copy. Formula changes belong in the tap repository; commit them there and bump the gitlink here. Never add loose files under that path. The formula still carries a placeholder sha256, so it only installs with --HEAD.

Releases

.forgejo/workflows/release.yml fires on a v* tag: it asserts that the tag, the pyproject.toml version and beefy_player.__version__ all agree, then publishes release notes. It does not touch packaging, so run tools/bump_packaging.py <version> after publishing: it rewrites contrib/aur/PKGBUILD and regenerates its .SRCINFO from it, rewrites the tap formula in contrib/homebrew, and with --commit commits the tap first and then this repository. Both channels build the sdist attached to the release, so they hash the same asset.