Files
kawaiipunk add77f6cb8 Rename to sigcal-bot
- package src/sigcal_bot, distribution and CLI sigcal-bot
- environment variables SIGCAL_BOT_*
- database file, container names, user agents, logs and QR device name
- docs and changelog updated
2026-11-18 17:06:40 +00:00

121 lines
5.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/sigcal_bot/
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
sigcal-bot --config config.toml --dump # render the feed without sending
sigcal-bot --config config.toml --check # config + Signal account check
sigcal-bot --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/sigcal-bot.sqlite3` re-seeds silently.
## Changelog
`CHANGELOG.md` is Keep-a-Changelog format. For anything a user of the bot would
notice — behaviour, configuration, CLI, operational requirements — add a bullet
under `## [Unreleased]` in the right group (`Added`, `Changed`, `Fixed`,
`Removed`). Internal refactors and test-only changes do not need entries.
Never create version headings. No stable release exists yet; versions are cut
only when a release is actually deployed, by renaming Unreleased to
`## [x.y.z] - YYYY-MM-DD`.
## Before you finish
- `pytest` green, `python -m pyflakes src tests` clean.
- New behaviour covered by a test (especially failure paths).
- User-visible changes have a `CHANGELOG.md` entry under `## [Unreleased]`.
- `config.example.toml`, README and AGENTS.md still accurate.
- `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or
`signal-data/` files.