src/digest.ts

Functions

Imports

It imports src/auto-merge-tick.ts, src/env.ts, src/log.ts, src/ops-types/views.ts, src/overnight-plan.ts, src/portal-host.ts, src/time.ts, src/watcher-digest.ts. Imported by src/push.ts, src/tick.ts.

Source

1import type { Env } from "./env";
2import { AWAITING_SEAT_KEY, type AwaitingSeat } from "./auto-merge-tick";
3import { readOvernightDigest } from "./overnight-plan";
4import { PORTAL_HOST } from "./portal-host";
5import type { DigestState } from "./ops-types/views";
6import { logEvent } from "./log";
7import { weeklyDigestLines } from "./watcher-digest";
8import { DAY_MS } from "./time";
9
10// THE DAILY EMAIL DIGEST (docs/design/design-merge-pipeline.md section 5; Dustin's DECIDE
11// 5 of 2026-10-09: Web Push for the four urgent things, and everything else in a daily
12// email). Once a UTC day, after DIGEST_HOUR_UTC, the tick mails one plain-text message to
13// ALERT_EMAIL: what waits on Dustin now (pull requests by class, questions, blocked jobs),
14// rollbacks, and what finished, blocked and became ready since the last digest. It is
15// read from what the queue, the auto-merge tick and the watcher already keep, through the
16// same reader as capsid_work_jobs action list view digest, so the mail and the Portal
17// cannot disagree. It writes nothing but its own state in KV.
18//
19// It does nothing until Email Routing is on. Cloudflare's send_email binding can only send
20// to a destination address verified in Email Routing, and only from the zone that has
21// Email Routing turned on, which is an account setting only Dustin can change. So the
22// digest needs all four of: the EMAIL binding, ALERT_EMAIL, ALERT_FROM, and the var
23// EMAIL_ROUTING set to "on", which the seat sets after Dustin's steps (docs/portal.md,
24// "Daily digest"). Until then each tick returns at once, and the Portal's Settings says
25// which is missing (digestState below).
26
27export const DIGEST_LAST_KEY = "digest:last";
28// 12:00 UTC is 07:00 in Chicago in summer and 06:00 in winter: before the day starts.
29const DIGEST_HOUR_UTC = 12;
30const LIST_MAX = 15;
31const PORTAL_URL = `https://${PORTAL_HOST}/`;
32
33interface LastDigest {
34  at: string;
35  outcome: "sent" | "failed";
36  note: string;
37}
38
39/** Why the digest cannot send, or null when everything it needs is configured. */
40export function digestProblem(env: Env): string | null {
41  const missing: string[] = [];
42  if (!env.EMAIL) missing.push("the send_email binding EMAIL");
43  if (!env.ALERT_EMAIL) missing.push("ALERT_EMAIL");
44  if (!env.ALERT_FROM) missing.push("ALERT_FROM");
45  if (env.EMAIL_ROUTING !== "on") {
46    return `Email Routing is not on: EMAIL_ROUTING is ${env.EMAIL_ROUTING ? `"${env.EMAIL_ROUTING}"` : "unset"}, not "on". Dustin turns Email Routing on for the domain and verifies the address, then the seat sets EMAIL_ROUTING to "on"${missing.length ? ` and sets ${missing.join(", ")}` : ""} (docs/portal.md, "Daily digest").`;
47  }
48  if (missing.length) return `Email Routing is on, but ${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} not set, so there is nowhere to send from or to.`;
49  return null;
50}
51
52async function readLast(env: Env): Promise<LastDigest | null> {
53  const raw = await env.APP_KV.get(DIGEST_LAST_KEY).catch(() => null);
54  if (!raw) return null;
55  try {
56    return JSON.parse(raw) as LastDigest;
57  } catch {
58    return null;
59  }
60}
61
62/** What the Portal shows: on or off and why, and the last send. */
63export async function digestState(env: Env): Promise<DigestState> {
64  const problem = digestProblem(env);
65  return { on: problem === null, problem, to: problem === null ? (env.ALERT_EMAIL ?? null) : null, hour_utc: DIGEST_HOUR_UTC, last: await readLast(env) };
66}
67
68const list = <T>(items: T[], line: (t: T) => string): string[] => [
69  ...items.slice(0, LIST_MAX).map((t) => `- ${line(t)}`),
70  ...(items.length > LIST_MAX ? [`- and ${items.length - LIST_MAX} more in the Portal`] : []),
71];
72
73/** The mail, from the state now. Reads only. */
74// The reader behind capsid_work_jobs action list view digest, or a test's stand-in.
75type DigestReader = typeof readOvernightDigest;
76
77async function composeDigest(env: Env, now: Date, since: string, read: DigestReader = readOvernightDigest): Promise<{ subject: string; text: string; waiting: number }> {
78  const raw = await env.APP_KV.get(AWAITING_SEAT_KEY).catch(() => null);
79  const parsed: unknown = raw ? JSON.parse(raw) : [];
80  const awaiting = (Array.isArray(parsed) ? (parsed as AwaitingSeat[]) : []).filter((a) => a.class !== "auto" && a.class !== "wait");
81  const digest = await read(env, { since }, now);
82  const questions = digest.blocked.filter((b) => b.summary.startsWith("QUESTION:"));
83  const blocked = digest.blocked.filter((b) => !b.summary.startsWith("QUESTION:"));
84  const rolled = await env.DB.prepare(
85    `SELECT repo, head_sha, outcome FROM deploy_outcomes WHERE outcome IN ('rolled_back', 'rollback_failed') AND recorded_at >= ?1 ORDER BY recorded_at LIMIT 20`
86  )
87    .bind(since.replace("T", " ").slice(0, 19))
88    .all<{ repo: string; head_sha: string; outcome: string }>();
89  const rollbacks = rolled.results ?? [];
90
91  const waiting = awaiting.length + questions.length + blocked.length;
92  const day = now.toISOString().slice(0, 10);
93  const text: string[] = [`Capsid, ${day}. Since ${since.replace("T", " ").slice(0, 16)} UTC.`, ""];
94  const section = (title: string, lines: string[]) => {
95    if (lines.length) text.push(title, ...lines, "");
96  };
97  section(
98    `Pull requests waiting on you (${awaiting.length})`,
99    list(awaiting, (a) => `${a.repo}#${a.number}, class ${a.class ?? "unclassed"}${a.class === "typed" ? " (money: approve by typing its number)" : ""}${a.visual ? ` (visual: look${a.visual.preview ? ` at ${a.visual.preview}` : ""} and approve in the Portal)` : ""}: https://github.com/${a.repo}/pull/${a.number}`)
100  );
101  section(`Questions (${questions.length})`, list(questions, (q) => `${q.namespace} ${q.id}: ${q.title}`));
102  section(`Blocked (${blocked.length})`, list(blocked, (b) => `${b.namespace} ${b.id}: ${b.title}`));
103  section(`Rollbacks (${rollbacks.length})`, list(rollbacks, (r) => `${r.repo} at ${r.head_sha.slice(0, 7)}: ${r.outcome === "rollback_failed" ? "the rollback failed" : "rolled back"}`));
104  section(`Pull requests ready (${digest.pull_requests_ready.length})`, list(digest.pull_requests_ready, (p) => `${p.namespace} ${p.job_id}: ${p.url}`));
105  section(`Finished (${digest.finished.length}), ${digest.pull_requests_merged} pull request(s) merged`, list(digest.finished, (j) => `${j.namespace} ${j.id}: ${j.title} (${j.result_kind ?? j.status})`));
106  // Mondays UTC only: the watcher's hygiene findings, per site (src/watcher-digest.ts).
107  // A failed read is a note here, never a failed mail.
108  let weekly: string[] = [];
109  if (now.getUTCDay() === 1) {
110    try {
111      weekly = await weeklyDigestLines(env.DB, now);
112    } catch (err) {
113      logEvent("error", "DIGEST_WEEKLY_UNREAD", { message: `DIGEST_WEEKLY_UNREAD: ${err instanceof Error ? err.message : String(err)}` });
114      weekly = ["Weekly digest could not be read."];
115    }
116  }
117  if (weekly.length) text.push(...weekly, "");
118  if (waiting === 0 && rollbacks.length === 0 && digest.finished.length === 0 && digest.pull_requests_ready.length === 0) text.push("Nothing waits on you and nothing happened.", "");
119  if (digest.truncated.length) text.push(`Some lists were cut: ${digest.truncated.join("; ")}.`, "");
120  text.push(`Open the Portal: ${PORTAL_URL}`);
121  return { subject: `Capsid digest ${day}: ${waiting === 0 ? "nothing waits on you" : `${waiting} waiting on you`}`, text: text.join("\n"), waiting };
122}
123
124export interface DigestReport {
125  ran: boolean;
126  note: string;
127  sent: boolean;
128}
129
130/** Once a UTC day after DIGEST_HOUR_UTC, when Email Routing is on: compose and send. */
131export async function digestTick(env: Env, now: Date, read: DigestReader = readOvernightDigest): Promise<DigestReport> {
132  const problem = digestProblem(env);
133  if (problem) return { ran: false, note: problem, sent: false };
134  if (now.getUTCHours() < DIGEST_HOUR_UTC) return { ran: false, note: `before ${DIGEST_HOUR_UTC}:00 UTC`, sent: false };
135  const last = await readLast(env);
136  const today = now.toISOString().slice(0, 10);
137  if (last && last.at.slice(0, 10) === today) return { ran: false, note: `already ${last.outcome} ${last.at}`, sent: false };
138  // Since the last digest that went out, so a failed day's news is in the next one; a
139  // first digest, or one after a long gap, covers the last day only.
140  const lastAt = last?.outcome === "sent" ? Date.parse(last.at) : NaN;
141  const since = new Date(Number.isFinite(lastAt) && now.getTime() - lastAt < 7 * DAY_MS ? lastAt : now.getTime() - DAY_MS).toISOString();
142  const mail = await composeDigest(env, now, since, read);
143  let record: LastDigest;
144  try {
145    await env.EMAIL!.send({ from: env.ALERT_FROM!, to: env.ALERT_EMAIL!, subject: mail.subject, text: mail.text });
146    record = { at: now.toISOString(), outcome: "sent", note: mail.subject };
147  } catch (err) {
148    // Recorded for the day, so a refusal is not retried every five minutes; the Portal
149    // shows it, and tomorrow's digest covers today too.
150    record = { at: now.toISOString(), outcome: "failed", note: `Cloudflare refused the mail: ${(err instanceof Error ? err.message : String(err)).slice(0, 300)}` };
151  }
152  await env.APP_KV.put(DIGEST_LAST_KEY, JSON.stringify(record));
153  return { ran: true, note: record.note, sent: record.outcome === "sent" };
154}