Document behaviour, invariants and architecture

- expand README: post cadence, architecture, config reference, ops,
  troubleshooting, limitations
- add AGENTS.md with hard rules and domain gotchas
- comment the non-obvious parts: window clamping, reminder fallback,
  series vs occurrence, outbox lifecycle, image failure handling
This commit is contained in:
2026-11-18 16:45:00 +00:00
parent bdd41929d4
commit 751fa518e6
10 changed files with 413 additions and 83 deletions
+108
View File
@@ -0,0 +1,108 @@
# AGENTS.md
Guidance for AI agents (and humans) changing this repository.
## What this is
A single-purpose service: it polls an iCalendar feed (The Events Calendar /
MCR Commons) and posts events, with poster images, to one Signal group. Signal
has no bot API, so sending goes through `signal-cli-rest-api` in Docker.
Read `README.md` for the user-facing behaviour and setup.
## Layout
```
src/calbot/
config.py TOML loading, defaults, duration/time parsers
feed.py conditional GET; validators committed only after parse
expand.py iCalendar -> Event; series-ID heuristics; recurrence expansion
format.py the group's post template (title/hashtags/time/venue/link)
images.py page scraping (venue, og:image) + poster download/resize/cache
store.py SQLite schema and all persistence
scheduler.py windows, reminder planning, dispatch/batching, Bot.tick
signal_client.py /v2/send HTTP client
watchdog.py throttled operator alerts
__main__.py CLI: run loop, --dump, --check, --once
tests/ pytest; fixtures are *.ics.txt (never *.ics)
```
## Commands
```bash
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest # must pass, no network
calbot --config config.toml --dump # render the feed without sending
calbot --config config.toml --check # config + Signal account check
calbot --config config.toml --once # one tick
```
`--dump` uses a throwaway database and never sends; keep it that way.
## Hard rules
1. **Never commit calendar data.** `*.ics` is gitignored; test fixtures must be
named `*.ics.txt`. `config.toml`, `signal-data/`, `data/`, `cache/` are
local-only.
2. **UTC inside, local only at the edges.** Store and compare UTC. Convert to
`[calendar].timezone` only for window maths and rendering. Never use naive
`datetime.now()` in code that persists a timestamp.
3. **`tick()` must never raise.** Feed, scrape, image, and send problems are
logged and reported to the watchdog; the loop has to survive all of them.
The one catch-all in `__main__` is a backstop, not a design.
4. **Images are optional; text is not.** Any image or scraping failure must
degrade to a text-only post. Never let enrichment raise through `_compose`.
5. **Plan once, persist it.** Reminder times and outbox rows are written when
an event is first seen. Do not recompute schedules on every tick; that
reorders posts when the feed changes or the process restarts.
6. **Delivery is at-least-once.** Write `deliveries` and delete the outbox row
only after a successful send. A crash may duplicate one post; that is
accepted. Do not add silent "mark sent before send" shortcuts.
7. **No network in tests.** Inject `now`, and use the fake sender/scraper/image
service patterns in `tests/test_scheduler.py` (`httpx.MockTransport` for the
feed).
## Domain gotchas
- **Series vs occurrence.** TEC's UID is
`{postID}-{startUnix}-{endUnix}@{host}`, and the feed pre-expands
recurrences. Announcements are deduped per `series_id`; reminders per
`Event.key`. Changing this will spam the group with one post per occurrence.
- **Feed is capped** (30 events by default) and contains no past events. Use
the coverage horizon (`max(start)` of the snapshot) before marking events
`gone`; otherwise a busy week "cancels" next month's events.
- **No `LOCATION` on many events.** Venue/postcode come from the event page's
JSON-LD (`Event.location.name` / `address.postalCode`), then the description.
This is cached per URL in `pages`.
- **Poster URLs are full-size originals**, sometimes WebP or a 20 MB phone
photo. Always cap the download, downscale, flatten transparency onto white,
and re-encode as JPEG.
- **Posting windows** (`08:00–10:00`, `18:00–21:00`) are a preference, not a
rule: `clamp_send_at` breaks them when the next window would miss the event
minus `urgent_guard_minutes`.
- **Reminder fallback.** If `start − lead` has already passed when the event is
discovered, the reminder moves to the morning of the event (or earlier, if
the event starts before that morning time).
- **Batching.** All outbox rows due in a tick become one message (text blocks
joined by blank lines, at most `max_images_per_post` attachments).
## Changing behaviour
- **New post kind** (e.g. digest): add a `kind` to `outbox`, plan rows in
`_sync`/a new planner, make `_dispatch` treat it like the others, add a
template in `format.py`, and test planning + dispatch with a fake clock.
- **New config option**: add a dataclass field in `config.py` with a sensible
default, parse it in `load_config`, document it in `config.example.toml` and
the README table.
- **Schema change**: append to `SCHEMA` in `store.py`. There is no migration
framework; deleting `data/calbot.sqlite3` re-seeds silently.
## Before you finish
- `pytest` green, `python -m pyflakes src tests` clean.
- New behaviour covered by a test (especially failure paths).
- `config.example.toml`, README and AGENTS.md still accurate.
- `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or
`signal-data/` files.