src/inbox.ts

Functions

Imports

It imports src/auto-merge-tick.ts, src/check-words.ts, src/env.ts, src/inbox-report.ts, src/manual-steps.ts, src/merge-class.ts, src/merge-units.ts, src/ops-sites.ts, src/ops-snapshot.ts, src/ops-types/feed.ts, src/outcome-prs.ts, src/stale-jobs.ts. Imported by src/inbox-report.ts, src/ops-feed.ts, src/routes.ts, src/status.ts, src/whats-next.ts.

Source

1import type { Env } from "./env";
2import { AWAITING_SEAT_KEY, type AwaitingSeat } from "./auto-merge-tick";
3import { readSiteConfig } from "./ops-sites";
4import { readSnapshot } from "./ops-snapshot";
5import { prUrlsFromJob } from "./outcome-prs";
6import { readReports } from "./inbox-report";
7import { unitInboxItems } from "./merge-units";
8import type { MergeClass } from "./merge-class";
9import { checkWords } from "./check-words";
10import { prsSettled, readStaleCache, type StalePrCache } from "./stale-jobs";
11import { readStepCache, stepsSeen, type StaleStepCache } from "./manual-steps";
12
13// "WHAT NEEDS DUSTIN, PER APP" (job_84e901d8eb71, Dustin 2026-10-06). The shared admin
14// shell shows a badge per app and a combined inbox count; Capsid answers it once, so no
15// app queries another. Everything here is read from what the queue, auto-merge and the
16// watcher already keep; this module only gathers and counts. It writes nothing.
17//
18// The app list is configuration (the ops_sites rows the Portal edits), never a list in
19// code. A namespace that has something waiting but no site row (Carrel, Capsomer) still
20// appears, under its namespace name, because a job waiting on Dustin there is just as
21// real.
22//
23// Severity, per app: needs-you when anything is waiting on a person (a job blocked for
24// the seat, a question, a pull request auto-merge declined), failing when only a machine
25// fault is open (the latest CI run on the repo failed, the site's health probe is down),
26// none otherwise. "Needs you" wins, because it is the thing only Dustin can clear.
27//
28// What an app reports about itself (Carrel's drafts waiting) arrives through
29// POST /ops/inbox/report (src/inbox-report.ts) and is read here as kind "report". A
30// reported item is always needs-you: an app may say a person must act, never that its
31// badge should be quieter.
32
33// The shapes are in the feed contract (src/ops-types/), which the Portal also reads.
34export type { Inbox, InboxApp, InboxItem, InboxSeverity } from "./ops-types/feed";
35import type { Inbox, InboxApp, InboxItem, InboxKind, InboxSeverity } from "./ops-types/feed";
36
37const MAX_BLOCKED = 200;
38const MAX_ITEMS_PER_APP = 50;
39const WAITING_ON_PERSON: ReadonlySet<InboxKind> = new Set(["blocked-job", "question", "pr", "report", "proposal"]);
40
41/** The worst severity of a set of items. */
42export function severityOf(items: readonly Pick<InboxItem, "kind">[]): InboxSeverity {
43  if (items.some((i) => WAITING_ON_PERSON.has(i.kind))) return "needs-you";
44  return items.length > 0 ? "failing" : "none";
45}
46
47
48// What answering it takes, by the class the tick gave it (src/merge-class.ts).
49const CLASS_WORDS: Record<MergeClass, string> = {
50  auto: "merges on its own",
51  approve: "one tap to approve",
52  typed: "a typed confirmation",
53  seat: "a step outside a merge",
54  wait: "nothing yet, CI is running",
55};
56
57/** An auto-merge hold as an inbox title, in plain words: what held it, then what it takes.
58 *  A visual pull request one tap would merge says it waits for his look, whichever check
59 *  stopped it first: a session's visual PR usually names no job, and "names no job" hid
60 *  that there was something to look at (job_0368576da167). */
61export function prHoldTitle(a: Pick<AwaitingSeat, "number" | "failed" | "class" | "visual">): string {
62  const why = checkWords(a.visual && a.class === "approve" ? "visual_awaits_look" : a.failed);
63  return `PR #${a.number} waits for you: ${why}${a.class ? ` (${CLASS_WORDS[a.class]})` : ""}`;
64}
65
66// A blocked job whose block is already answered is not waiting on anyone (Dustin's review of
67// 2026-10-11: the inbox kept a migration the seat had applied, and a job whose pull requests
68// had merged). Two facts the Worker already holds settle it: every pull request it names is
69// merged or closed, as the merge-resume step last read them after the job last changed
70// (src/stale-jobs.ts, the same test as the stale view's prs-settled), or every migration
71// file its block names (the command is in its summary, src/jobs-holder.ts) is in d1_migrations,
72// or every manual step its "check:" lines name was seen by the watcher's last pass after the
73// job last changed (src/manual-steps.ts, the stale view's steps-seen). Such a job stays
74// blocked and shows in the stale view, where it is closed; the inbox leaves it out.
75const MIGRATION_FILE = /\b(\d{4}_[a-z0-9_]+)(?:\.sql)?\b/gi;
76
77/** The migration files a blocked job's summary names, without ".sql". */
78export function migrationsNamed(text: string): string[] {
79  return [...new Set([...text.matchAll(MIGRATION_FILE)].map((m) => m[1]!.toLowerCase()))];
80}
81
82export function blockSettled(
83  job: { id: string; result_summary: string | null; updated_at: string },
84  stale: StalePrCache,
85  applied: ReadonlySet<string> | null,
86  steps: StaleStepCache = {}
87): boolean {
88  const entry = stale[job.id];
89  if (entry && entry.at >= job.updated_at && prsSettled(entry)) return true;
90  const step = steps[job.id];
91  if (step && step.at >= job.updated_at && stepsSeen(step)) return true;
92  if (!applied) return false;
93  const named = migrationsNamed(job.result_summary ?? "");
94  return named.length > 0 && named.every((n) => applied.has(n));
95}
96
97/** The applied migrations by file name without ".sql", or null when the table cannot be read. */
98export async function appliedMigrations(db: D1Database): Promise<Set<string> | null> {
99  try {
100    const rows = await db.prepare("SELECT name FROM d1_migrations").all<{ name: string }>();
101    return new Set((rows.results ?? []).map((r) => r.name.toLowerCase().replace(/\.sql$/, "")));
102  } catch {
103    return null;
104  }
105}
106
107/** A blocked job as an inbox item. A block that asks a question is marked in its summary
108 *  (src/jobs-holder.ts), and it is the kind that most needs a person's words. */
109export function blockedJobItem(job: { id: string; title: string; result_ref: string | null; result_summary: string | null; updated_at: string }): InboxItem {
110  const question = (job.result_summary ?? "").startsWith("QUESTION:");
111  const [pr] = prUrlsFromJob({ result_ref: job.result_ref, result_summary: job.result_summary });
112  return { title: job.title, kind: question ? "question" : "blocked-job", link: pr ?? null, since: job.updated_at, job: job.id };
113}
114
115/**
116 * Gather the inbox for `namespaces` (the ones the caller may read; null means all).
117 * `now` stamps the answer.
118 */
119export async function gatherInbox(env: Env, now: Date, namespaces: readonly string[] | null): Promise<Inbox> {
120  const allowed = namespaces === null ? null : new Set(namespaces);
121  const keep = (namespace: string) => allowed === null || allowed.has(namespace);
122  const byNamespace = new Map<string, InboxItem[]>();
123  const add = (namespace: string, item: InboxItem) => {
124    if (!keep(namespace)) return;
125    const list = byNamespace.get(namespace) ?? [];
126    if (list.length < MAX_ITEMS_PER_APP) list.push(item);
127    byNamespace.set(namespace, list);
128  };
129
130  const blocked = await env.DB.prepare(
131    "SELECT id, namespace, title, result_ref, result_summary, updated_at FROM jobs WHERE status = 'blocked' ORDER BY updated_at LIMIT ?1"
132  )
133    .bind(MAX_BLOCKED)
134    .all<{ id: string; namespace: string; title: string; result_ref: string | null; result_summary: string | null; updated_at: string }>();
135  // An unreadable cache or migrations table settles nothing: the job shows, as before.
136  // All three are read whether or not a job is blocked, so the feed's stated read count
137  // (src/ops-feed.ts, OPS_FEED_READS) does not move with the data.
138  const stale = (await readStaleCache(env.APP_KV).catch(() => ({ cache: {} }))).cache;
139  const steps = (await readStepCache(env.APP_KV).catch(() => ({ cache: {} }))).cache;
140  const applied = await appliedMigrations(env.DB);
141  for (const job of blocked.results ?? []) {
142    if (!blockSettled(job, stale, applied, steps)) add(job.namespace, blockedJobItem(job));
143  }
144
145  // The pull requests auto-merge declined, rewritten whole by its tick. An unreadable
146  // list reads as none, not as a failure of the inbox.
147  try {
148    const raw = await env.APP_KV.get(AWAITING_SEAT_KEY);
149    const parsed: unknown = raw ? JSON.parse(raw) : [];
150    if (Array.isArray(parsed)) {
151      for (const a of parsed as AwaitingSeat[]) {
152        add(a.namespace, { title: prHoldTitle(a), kind: "pr", link: `https://github.com/${a.repo}/pull/${a.number}`, since: a.at });
153      }
154    }
155  } catch {
156    // none
157  }
158
159  // The watcher's last pass: the newest CI run on each repo and each site's probe.
160  const snapshot = await readSnapshot(env).catch(() => null);
161  for (const ci of snapshot?.ci ?? []) {
162    if (ci.latest?.conclusion === "failure") {
163      add(ci.namespace, { title: `CI is failing on ${ci.latest.head_sha.slice(0, 7)}`, kind: "ci", link: ci.latest.url, since: ci.latest.created_at });
164    }
165  }
166  for (const site of snapshot?.sites ?? []) {
167    if (site.state === "down") {
168      add(site.namespace, { title: `${site.name} is down${site.error ? ` (${site.error})` : ""}`, kind: "site-down", link: site.origin, since: site.checked_at });
169    }
170  }
171
172  // The merge units' proposals and suspensions (src/merge-units.ts): a widening or a
173  // narrowing only Dustin signs.
174  for (const { namespace, item } of await unitInboxItems(env.APP_KV)) add(namespace, item);
175
176  // What each app last reported about itself, while it is under 6 hours old.
177  for (const [namespace, items] of await readReports(env.APP_KV, now)) {
178    for (const item of items) add(namespace, item);
179  }
180
181  // Every configured app appears, with a count of zero when nothing waits, so the shell
182  // can draw a quiet badge; a namespace with items but no site row is added after.
183  const config = await readSiteConfig(env.DB).catch(() => []);
184  const names = new Map<string, string>(config.map((c) => [c.namespace, c.name]));
185  const apps: InboxApp[] = [];
186  const seen = new Set<string>();
187  for (const [namespace, name] of names) {
188    if (!keep(namespace)) continue;
189    seen.add(namespace);
190    const items = byNamespace.get(namespace) ?? [];
191    apps.push({ namespace, name, count: items.length, severity: severityOf(items), items });
192  }
193  for (const [namespace, items] of byNamespace) {
194    if (seen.has(namespace)) continue;
195    apps.push({ namespace, name: namespace, count: items.length, severity: severityOf(items), items });
196  }
197
198  const all = apps.flatMap((a) => a.items);
199  return { generated: now.toISOString(), count: all.length, severity: severityOf(all), apps };
200}
201
202/** The inbox limited to the apps `readable` admits, with the totals recomputed, so a
203 *  scoped caller sees its own apps and a count that matches them. */
204export function restrictInbox(inbox: Inbox, readable: (namespace: string) => boolean): Inbox {
205  const apps = inbox.apps.filter((a) => readable(a.namespace));
206  const all = apps.flatMap((a) => a.items);
207  return { generated: inbox.generated, count: all.length, severity: severityOf(all), apps };
208}