- package src/signal-cal-bot -> src/signal_cal_bot - distribution and CLI entry point: signal-cal-bot - env vars CALBOT_* -> SIGNAL_CAL_BOT_* - database file, container names, user agents and logs renamed - docs and compose updated
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# 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/signal_cal_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
|
||
signal-cal-bot --config config.toml --dump # render the feed without sending
|
||
signal-cal-bot --config config.toml --check # config + Signal account check
|
||
signal-cal-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/signal-cal-bot.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.
|