Public: anyone can read this; the crew can change it.

/maintenance shows each duty's last run and next due in plain words #14694

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/14674-maintenance-shows-each-duty-s-last-run-a → main 21 commits fork 8 threads · 8 unresolved

  • Merged. mason/14674-maintenance-shows-each-duty-s-last-run-a was merged into main as a4b5145.

Review

Sign in to review this change.
8 files changed +190 −9
docs/features/maintenance-duties.md +2 −2
@@ -8,8 +8,8 @@ Each duty the forge's maintenance runner runs (`src/maintain/registry.ts`) has a
88
99 All doors are for a forge admin and call one function, `switchDuty` in `src/maintain/pause.ts`, so they say the same words.
1010
11 - **On the web.** `/maintenance` lists each duty once; the ones the runner runs carry their state ("on", or "paused since … ; why") and one **Pause** / **Resume** button (`POST /maintenance/duties/:name`, same-origin only, form body bounded, `paused` is `yes` or `no`).
12 - **In the terminal.** Ctrl-K, **Pause, resume or dismiss a maintenance duty** (an admin who is a person): `j`/`k` choose, Enter or Space flips, `d` dismisses its finding for seven days (see duty-dismiss.md), Esc closes. It writes the same row, so a web viewer sees it on its next load.
11 - **On the web.** `/maintenance` lists each duty once; the ones the runner runs carry their state ("on", or "paused since … ; why") then when it last ran and is next due ("on; ran 2h ago; next in 4h", "due now"; a paused duty says only when it ran, since its state already says paused; a **late** badge once the due time was missed by twice the interval; #14674, `src/maintain/schedule.ts`, `dutySchedules`), and one **Pause** / **Resume** button (`POST /maintenance/duties/:name`, same-origin only, form body bounded, `paused` is `yes` or `no`).
12 - **In the terminal.** Ctrl-K, **Pause, resume or dismiss a maintenance duty** (an admin who is a person): `j`/`k` choose, Enter or Space flips, `d` dismisses its finding for seven days (see duty-dismiss.md), Esc closes. Each line ends with the same schedule in brackets, "(ran 2h ago; next in 4h)", "; late" when late, "(ran 4d ago)" when paused. It writes the same row, so a web viewer sees it on its next load.
1313 - **Over the API.** `GET /api/v1/maintenance/duties` lists the states; `POST /api/v1/maintenance/duties/:name` with `{"paused": true|false}` needs an `admin`-scope token.
1414 - **In the MCP.** The `maintenance` tool: `pause-duty` and `resume-duty` with `duty`.
1515
src/maintain/runs.ts +6
@@ -45,6 +45,12 @@ export function lastStarted(db: Database, duty: string): number | undefined {
4545 return row ? Date.parse(row.started) : undefined;
4646 }
4747
48 /** Every duty's last real start in one query: duty name to time. */
49 export function lastStartedAll(db: Database): Map<string, number> {
50 const rows = db.query("SELECT duty, MAX(started) AS started FROM maintenance_run WHERE outcome NOT LIKE 'budget:%' GROUP BY duty").all() as { duty: string; started: string }[];
51 return new Map(rows.map((r) => [r.duty, Date.parse(r.started)]));
52 }
53
4854 export const LIST_MAX = 100;
4955
5056 export function latest(db: Database, limit: number): RunRow[] {
src/maintain/schedule.ts added +51
@@ -0,0 +1,51 @@
1 /**
2 * When a maintenance duty last ran and when it is next due, in plain words (#14674): "ran 2h ago",
3 * "next in 4h", "paused", and "late" once the due time was missed by twice the interval. Plain data
4 * in (a clock is an argument), plain data out.
5 */
6
7 import type { Database } from "bun:sqlite";
outdated

Both doors: nothing in src/tui/ or docs/features/ uses this module. The terminal should show the same words, and the how-to belongs in docs/features/.

8 import { duties as registered } from "./registry.ts";
9 import { lastStartedAll } from "./runs.ts";
10
11 export interface Schedule {
12 /** "ran 2h ago", or "not run yet". */
13 readonly ran: string;
14 /** "next in 4h", "due now", or "paused". */
15 readonly next: string;
16 /** The due time was missed by twice the interval; never for a paused or never-run duty. */
17 readonly late: boolean;
18 }
19
20 /** A span as one short unit: "5m", "2h", "3d"; under a minute is "1m". */
21 export function span(ms: number): string {
22 const minutes = Math.max(1, Math.floor(ms / 60_000));
23 if (minutes < 60) return `${String(minutes)}m`;
24 if (minutes < 48 * 60) return `${String(Math.floor(minutes / 60))}h`;
25 return `${String(Math.floor(minutes / 1440))}d`;
26 }
27
28 export function scheduleOf(o: { lastStarted: number | undefined; intervalMs: number; paused: boolean; now: number }): Schedule {
29 const { lastStarted: last, intervalMs, paused, now } = o;
30 const ran = last === undefined ? "not run yet" : `ran ${span(now - last)} ago`;
31 if (paused) return { ran, next: "paused", late: false };
32 if (last === undefined) return { ran, next: "due now", late: false };
33 const due = last + intervalMs;
34 return { ran, next: now >= due ? "due now" : `next in ${span(due - now)}`, late: now > due + 2 * intervalMs };
35 }
36
37 /**
38 * The schedule of every registered duty by name, from one registry pass and one query of last runs.
39 */
40 export function dutySchedules(db: Database, states: readonly { name: string; paused: boolean }[], now: number): Map<string, Schedule> {
41 const starts = lastStartedAll(db);
42 const paused = new Map(states.map((d) => [d.name, d.paused]));
43 return new Map(registered.map((d) => [d.name, scheduleOf({ lastStarted: starts.get(d.name), intervalMs: d.intervalMs, paused: paused.get(d.name) === true, now })]));
44 }
45
46 /**
47 * The schedule as words after a duty's state: "ran 2h ago; next in 4h". A paused duty's state
48 * already says "paused since …", so its schedule is only when it ran. Late is not in the words: the
49 * page shows it as a badge and the terminal adds "; late" itself.
50 */
51 export const scheduleWords = (s: Schedule): string => (s.next === "paused" ? s.ran : `${s.ran}; ${s.next}`);
src/perf/page_budgets/maintenance.ts +3 −3
@@ -4,6 +4,6 @@ import type { PageBudget } from "../page_budget.ts";
44 // own state and runs, so the count moves with the number of duties and background ticks; an N+1
55 // over the duties would still show. One query reads every dismissal (#13967), one every quieted
66 // finding (#14557); one grouped read of the degraded findings (#14577); +3: the edge-kept duty
7 // (#14682). 86 is the steady count measured warm on every run (83 before another duty joined the
8 // board), not a load-sensitive figure.
9 export const budget: PageBudget = { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 86 };
7 // (#14682); one grouped read of every duty's last run (#14674). 87 is the steady count measured
8 // warm on every run, not a load-sensitive figure.
9 export const budget: PageBudget = { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 87 };
src/tui/screens/dutyswitch.ts +6 −2
@@ -8,6 +8,7 @@
88
99 import { dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts";
1010 import { dutyStates, switchDuty } from "../../maintain/pause.ts";
11 import { dutySchedules, scheduleWords } from "../../maintain/schedule.ts";
1112 import type { Ctx, Screen } from "../app/app.ts";
1213 import { binding } from "../app/keys.ts";
1314 import type { Session } from "../session.ts";
@@ -21,9 +22,12 @@ const mayAct = (session: { readonly user: { readonly isAdmin: boolean; readonly
2122 export function dutyLines(session: Session, chosen: number): string[] {
2223 if (!mayAct(session)) return [];
2324 const kept = dismissals(session.db);
24 return dutyStates(session.db).map((d, i) => {
25 const states = dutyStates(session.db);
26 const schedules = dutySchedules(session.db, states, Date.now());
27 return states.map((d, i) => {
2528 const dm = kept.get(d.name);
26 return `${i === chosen ? ">" : " "} ${d.says}${dm === undefined ? "" : `; ${dismissalWords(dm)}`}`;
29 const sched = schedules.get(d.name);
30 return `${i === chosen ? ">" : " "} ${d.says}${dm === undefined ? "" : `; ${dismissalWords(dm)}`}${sched === undefined ? "" : ` (${scheduleWords(sched)}${sched.late ? "; late" : ""})`}`;
2731 });
2832 }
2933
src/web/pages/maintenance.ts +4 −1
@@ -25,6 +25,7 @@ import { badge, btn, disclosure, field, seg } from "../ui.ts";
2525 import { STALE_DAYS, STALE_WORDS, closeStale, nudge, stalePulls } from "../../maintain/stale_pulls.ts";
2626 import { PREVIEW_DAYS, PREVIEW_WORDS, previewDirs, previewLine, removePreviewDirs, sizeWords, totalWords, type PreviewDir } from "../../maintain/previews.ts";
2727 import { MERGED_DAYS, MERGED_WORDS, deleteMerged, lineOf, mergedBranches, type MergedBranch } from "../../maintain/duties/merged_branches.ts";
28 import { dutySchedules, scheduleWords } from "../../maintain/schedule.ts";
2829 import { isKind, quiet, quieted, quietKeys, unquiet, when, type QuietKind, type Quieted } from "../../maintenance/quiet.ts";
2930 import { liveLabel } from "../../maintenance/quiet_live.ts";
3031 import { writePauseFold } from "./maintenance_pause.ts";
@@ -118,6 +119,7 @@ async function maintenanceAnswer(ctx: Ctx): Promise<Response> {
118119 const { quiet, loud } = splitDuties(ran);
119120 const dismissed = dismissals(ctx.app.db);
120121 const states = dutyStates(ctx.app.db);
122 const schedules = dutySchedules(ctx.app.db, states, Date.now());
121123 const hidden = quieted(ctx.app.db);
122124 const mergedPending = (await mergedBranches(ctx.app, new Date())).filter((b) => !quietKeys(hidden, "merged-branches").has(lineOf(b)));
123125 const previewPending = previewDirs(ctx.app, new Date()).filter((p) => !quietKeys(hidden, "preview-dirs").has(previewLine(p)));
@@ -141,7 +143,8 @@ async function maintenanceAnswer(ctx: Ctx): Promise<Response> {
141143 ${states.map((d) => {
142144 const dm = dismissed.get(d.name);
143145 const detail = dm === undefined ? d.detail : dm.active && !d.paused ? `on; ${dismissalWords(dm)}` : `${d.detail}; ${dismissalWords(dm)}`;
144 return fact(d.name, html`${detail}
146 const sched = schedules.get(d.name);
outdated

Non-null assertion on a lookup across two separate lists; handle undefined as the terminal does. Also hand-rolled status-row markup instead of the row helper (principle 7); 'paused' is said twice with the detail (principle 1).

147 return fact(d.name, html`${detail}${sched === undefined ? null : html`; ${scheduleWords(sched)}`}${sched?.late === true ? html` ${badge("late", { tone: "attn" })}` : null}
145148 <form method="post" action="/maintenance/duties/${d.name}" class="inline">
146149 <input type="hidden" name="paused" value="${d.paused ? "no" : "yes"}">${btn(d.paused ? "Resume" : "Pause", { variant: "outline" })}
147150 </form>`);
test/maintenance-last-run.test.ts added +117
@@ -0,0 +1,117 @@
1 /** Each duty's row on /maintenance says when it ran and when it is next due (#14674). */
2 import { afterAll, afterEach, beforeAll, expect, setSystemTime, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { createUser } from "../src/core/users.ts";
8 import { serve, type Servers } from "../src/http/server.ts";
9 import { dutyStates, setPaused } from "../src/maintain/pause.ts";
10 import { duties } from "../src/maintain/registry.ts";
11 import { dutySchedules, scheduleOf, scheduleWords, span } from "../src/maintain/schedule.ts";
12 import { Session } from "../src/tui/session.ts";
13 import { getUserById } from "../src/core/users.ts";
14 import { dutyLines } from "../src/tui/screens/dutyswitch.ts";
15 import { quietLogs } from "./helpers/globals.ts";
16
17 quietLogs();
18 const H = 3_600_000;
19 const NOW = Date.parse("2026-11-20T12:00:00Z");
20
21 test("on time: ran 2h ago, next in 4h", () => {
22 expect(scheduleOf({ lastStarted: NOW - 2 * H, intervalMs: 6 * H, paused: false, now: NOW })).toEqual({ ran: "ran 2h ago", next: "next in 4h", late: false });
23 });
24
25 test("due but not yet late: due now", () => {
26 const s = scheduleOf({ lastStarted: NOW - 8 * H, intervalMs: 6 * H, paused: false, now: NOW });
27 expect(s).toEqual({ ran: "ran 8h ago", next: "due now", late: false });
28 });
29
30 test("late only past the due time by twice the interval", () => {
31 const at = (ago: number) => scheduleOf({ lastStarted: NOW - ago, intervalMs: 6 * H, paused: false, now: NOW }).late;
32 expect(at(18 * H)).toBe(false);
33 expect(at(18 * H + 60_000)).toBe(true);
34 });
35
36 test("paused says paused and is never late; never-run says so", () => {
37 expect(scheduleOf({ lastStarted: NOW - 100 * H, intervalMs: H, paused: true, now: NOW })).toEqual({ ran: "ran 4d ago", next: "paused", late: false });
38 expect(scheduleOf({ lastStarted: undefined, intervalMs: H, paused: false, now: NOW })).toEqual({ ran: "not run yet", next: "due now", late: false });
39 expect(span(1000)).toBe("1m");
40 });
41
42 let adminId = "", dir = "", app: App, servers: Servers, cookie = "";
43 beforeAll(async () => {
44 dir = await mkdtemp(join(tmpdir(), "forge-last-run-"));
45 app = createApp({ dataDir: dir, port: 0 });
46 servers = await serve(app);
47 const made = await createUser(app.db, { username: "boss", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, isAdmin: true });
48 if (!made.ok) throw new Error("user");
49 adminId = made.value.id;
50 const res = await fetch(`${servers.url}/signin`, {
51 method: "POST", redirect: "manual",
52 headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url },
53 body: new URLSearchParams({ username: "boss", password: "a-good-passphrase" }),
54 });
55 cookie = (res.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
56 });
57 afterAll(async () => {
outdated

The page test depends on real time and a regex over markup; fragile. Add a terminal test too once the screen exists.

58 servers.stop();
59 app.db.close();
60 await rm(dir, { recursive: true, force: true });
61 });
62
63 /**
64 * Each test below starts from no runs and nothing paused, on the fixed clock: a ran half its
65 * interval ago, b is far past due, c is paused. Seeding here, not in an earlier test, keeps each
66 * one standing alone.
67 */
68 function seed(): { a: string; b: string; c: string; ran: string } {
69 const [a, b, c] = duties;
70 setSystemTime(new Date(NOW));
71 app.db.run("DELETE FROM maintenance_run");
72 for (const d of duties) setPaused(app.db, d.name, false, "boss");
73 const ins = app.db.query("INSERT INTO maintenance_run (duty, started, finished, outcome) VALUES (?1, ?2, ?2, 'ok')");
74 ins.run(a!.name, new Date(NOW - a!.intervalMs / 2).toISOString());
75 ins.run(b!.name, new Date(NOW - 4 * b!.intervalMs).toISOString());
76 setPaused(app.db, c!.name, true, "boss");
77 return { a: a!.name, b: b!.name, c: c!.name, ran: `ran ${span(a!.intervalMs / 2)} ago; next in` };
78 }
79 afterEach(() => { setSystemTime(); });
80
81 test("the page shows ran/next, late in the attn tone, and says paused once", async () => {
82 const { a, b, c, ran } = seed();
83 const html = await (await fetch(`${servers.url}/maintenance`, { headers: { cookie } })).text();
84 const row = (n: string): string => {
85 const at = html.indexOf(`<dt>${n}</dt>`);
86 expect(at).toBeGreaterThan(-1);
87 return html.slice(at, html.indexOf("</dd>", at));
88 };
89 expect(row(a)).toContain(ran);
90 expect(row(a)).not.toContain("late");
91 expect(row(b)).toContain('data-variant="attn"');
92 expect(row(b)).toContain(">late<");
93 expect(row(c)).toContain("paused since");
94 expect(row(c)).toMatch(/; not run yet\s*</);
outdated

This test passes only because the earlier page test inserted the run rows; seed its own so it stands alone.

95 expect(row(c)).not.toContain("late");
96 });
97
98 test("every registered duty has a schedule; a paused one's words are only when it ran", () => {
99 seed();
100 const all = dutySchedules(app.db, dutyStates(app.db), Date.now());
101 expect([...all.keys()]).toEqual(duties.map((d) => d.name));
102 expect(scheduleWords({ ran: "ran 2h ago", next: "next in 4h", late: true })).toBe("ran 2h ago; next in 4h");
103 expect(scheduleWords({ ran: "ran 4d ago", next: "paused", late: false })).toBe("ran 4d ago");
104 });
105
106 test("the terminal's duty list says the same words", () => {
107 const { a, b, c, ran } = seed();
108 const user = getUserById(app.db, adminId);
109 if (user === undefined) throw new Error("user");
110 const session = new Session(app, { sshUsername: "boss", remoteAddress: "127.0.0.1", user });
111 const lines = dutyLines(session, 0);
112 const line = (n: string): string => lines.find((l) => l.includes(`${n}:`)) ?? "";
113 expect(line(a)).toContain(`(${ran}`);
114 expect(line(b)).toContain("; late)");
115 expect(line(c)).toContain("paused since");
116 expect(line(c)).toMatch(/\(not run yet\)$/);
117 });
test/pages-budget.test.ts +1 −1
@@ -59,7 +59,7 @@ const HEAVIER: Record<string, { statements?: number; git?: number }> = {
5959 "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277)
6060 "/board": { statements: 72 }, // +1: the forge-copy read for the tell box (#12037); +1: the vitals read the database's growth (#12025); +6: the money line (#510) — one settings read, then the month's and the 30 days' meter, storage and ledger reads; constant in the number of apps
6161 "/settings/capacity": { statements: 70 },
62 "/maintenance": { statements: 86 }, // +3: edge-kept (#14682), one more duty reading its own state; +1: quieted findings (#14557); +1: the findings fold (#14577); +5: slow-tests (#13966); +3: untested-sources (#14125) and the dismissal query (#13967); +4: flaky-tests (#13937), red apps (#13938), chapter stall (#14057), dead-doc-paths (#13977); +3: stale-branches (#14141) — each reads its own state and runs
62 "/maintenance": { statements: 87 }, // +3: edge-kept (#14682), one more duty reading its own state; +1: every duty's last run in one query (#14674); +1: quieted findings (#14557); +1: the findings fold (#14577); +5: slow-tests (#13966); +3: untested-sources (#14125) and the dismissal query (#13967); +4: flaky-tests (#13937), red apps (#13938), chapter stall (#14057), dead-doc-paths (#13977); +3: stale-branches (#14141) — each reads its own state and runs
6363 "/api/v1/maintenance/duties": { statements: 69 }, // the same duties as JSON; slow-tests (#13966), stale-branches (#14141) and edge-kept (#14682) each add 3
6464 };
6565

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs