diff --git a/agents.md b/agents.md index 6ef12c6..7ff9e61 100644 --- a/agents.md +++ b/agents.md @@ -199,3 +199,51 @@ This file is the single source of truth for codebase obstacles, oddities, and th **Obstacle:** Calculating the next page from the requested limit stops pagination early when Forgejo's configured page-size cap is lower. **Solution/Workaround:** Preserve the `next` relation from Forgejo's `Link` header as `RepoPage.has_next_page` and use it directly on the dashboard. **Preference:** Use upstream pagination links rather than assuming the requested page size was honored. + +### Picker listing endpoints omit pagination metadata +**Area:** web/app/routers/repositories.py, web/app/templates/snapshot_picker.html +**Obstacle:** Branch and commit client helpers return plain lists; a short page cannot prove there are no further results because Forgejo may cap page sizes. +**Solution/Workaround:** The picker-specific HTML route follows repository pagination metadata and walks branch pages until empty. Commit requests stop at an empty page or 30 recent commits. JSON listing responses are unchanged. +**Preference:** Paginate automatically without guessing from page length or changing existing API consumers. + +### Branch refs need URL query encoding +**Area:** web/app/clients/forgejo.py +**Obstacle:** Interpolating a branch ref into the Forgejo commits query can corrupt names containing characters such as `&` or `#`. +**Solution/Workaround:** Build query strings with `httpx.QueryParams` and quote owner and repository path components. +**Preference:** Encode URL components at the HTTP client boundary. + +### Duplicate element IDs silently broke the snapshot picker +**Area:** web/app/templates/dashboard.html, web/app/static/js/snapshot-picker.js +**Obstacle:** The selected-snapshot summary cells reused `snapshot-branch` and `snapshot-commit`, colliding with the picker's `` wrapper auto-selects its first option before HTMX moves it into the live select, overriding the user's choice. +**Solution/Workaround:** The old paginated UI appended through an inert `