# 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:

```bash
uv sync
```

If it still fails, rebuild the environment once:

```bash
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

```bash
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 bump
`contrib/aur/PKGBUILD` (and its `.SRCINFO`) and the tap's formula by hand.