Files
sigcal/AGENTS.md
T
kawaiipunk f6d0db664e Document headless linking, dedicated identity and alpha status
- README: SSH-tunnel and QR-as-file linking for headless servers
- README: dedicated-number registration path for a separate bot identity
- README: alpha-quality notice, provenance caveat, non-affiliation
- add CHANGELOG.md (Keep a Changelog, everything under Unreleased)
- AGENTS.md: require Unreleased changelog entries
2026-11-18 17:06:18 +00:00

5.7 KiB
Raw Blame History

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

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.

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.