potiuk opened a new pull request, #277: URL: https://github.com/apache/airflow-steward/pull/277
## Summary Refactors the mail-source surface that `security-issue-import` and `security-issue-sync` use so Gmail, Ponymail, IMAP, mbox, and any future backend are treated **uniformly**. Adopters declare their backends in `<project-config>/project.md` with per-backend roles (`primary` / `preferred for <op>` / `fallback` / `optional`) and a `mandatory` flag; the skills apply a documented resolution rule per operation at run time. ### The contract New **`tools/mail-source/contract.md`** is the single source of truth. Defines six abstract operations a backend may implement: | Operation | Purpose | |---|---| | `list_recent_threads` | Find candidate reports in a time window | | `read_thread` | Fetch full message history | | `list_drafts` | Detect pending drafts (idempotency) | | `list_sent_since` | *\"Have we already replied?\"* | | `create_draft` | Compose an un-sent reply (draft-only per framework rule) | | `thread_url` | Render a clickable URL for the tracker body | Plus the capability matrix, role values, mandatory flag semantics, and a resolution rule (`preferred for <op>` > `primary` > `fallback` in declared order). ### Adapter docs | Backend | Status | Capabilities | |---|---|---| | **`gmail`** (existing, `tools/gmail/`) | reframed | All 6 ops — full read+write | | **`ponymail`** (existing, `tools/ponymail/`) | reframed | Read-only: `list_recent_threads`, `read_thread`, `thread_url` | | **`imap`** (new, `tools/mail-source/imap/`) | stub | All 6 ops, drafts gated on `Drafts` mailbox write rights | | **`mbox`** (new, `tools/mail-source/mbox/`) | stub | Read-only offline archive — forensics / late triage | ### Adopter config `projects/_template/project.md` gains a new **Mail sources** section: a `Backend | Role | Mandatory | Notes` declaration table plus per-backend config keys covering Gmail, Ponymail, IMAP, and mbox. The old *Gmail and PonyMail* section is replaced; the *Tools enabled* row for inbound email now points at the contract. ### Skill updates `security-issue-import` and `security-issue-sync` Prerequisites + Step 0 are rewritten in terms of the abstract operations and the contract's resolution rule. Mandatory-backend failure is an explicit hard stop; non-mandatory backends degrade quietly per the contract. Legacy Gmail-centric step-by-step detail is retained as the *reference-adopter* description so the existing operational guidance still applies for `airflow-s` and any project with the same `Mail sources` table. ## Test plan - [x] `prek run` on all touched files — all hooks pass. - [ ] No behaviour change for the reference adopter (Gmail primary + Ponymail fallback) — manual confirmation on the next real `security-issue-import` invocation. - [ ] An adopter with a different `Mail sources` table (e.g. corporate IMAP primary) follows the same skill flow with the new resolution rule picking IMAP for reads and Gmail for drafts — to be exercised when the first such adopter wires it in. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
