Public: anyone can read this; the crew can change it.
/maintenance shows each duty's last run and next due in plain words #14694
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14674-maintenance-shows-each-duty-s-last-run-a → main 21 commits fork 8 threads · 8 unresolved
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 | ||
| 8 | 8 | |
| 9 | 9 | All doors are for a forge admin and call one function, `switchDuty` in `src/maintain/pause.ts`, so they say the same words. |
| 10 | 10 | |
| 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. | |
| 13 | 13 | - **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. |
| 14 | 14 | - **In the MCP.** The `maintenance` tool: `pause-duty` and `resume-duty` with `duty`. |
| 15 | 15 |
src/maintain/runs.ts +6
| @@ -45,6 +45,12 @@ export function lastStarted(db: Database, duty: string): number | undefined { | ||
| 45 | 45 | return row ? Date.parse(row.started) : undefined; |
| 46 | 46 | } |
| 47 | 47 | |
| 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 | ||
| 48 | 54 | export const LIST_MAX = 100; |
| 49 | 55 | |
| 50 | 56 | 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"; | |
| 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"; | ||
| 4 | 4 | // own state and runs, so the count moves with the number of duties and background ticks; an N+1 |
| 5 | 5 | // over the duties would still show. One query reads every dismissal (#13967), one every quieted |
| 6 | 6 | // 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 @@ | ||
| 8 | 8 | |
| 9 | 9 | import { dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts"; |
| 10 | 10 | import { dutyStates, switchDuty } from "../../maintain/pause.ts"; |
| 11 | import { dutySchedules, scheduleWords } from "../../maintain/schedule.ts"; | |
| 11 | 12 | import type { Ctx, Screen } from "../app/app.ts"; |
| 12 | 13 | import { binding } from "../app/keys.ts"; |
| 13 | 14 | import type { Session } from "../session.ts"; |
| @@ -21,9 +22,12 @@ const mayAct = (session: { readonly user: { readonly isAdmin: boolean; readonly | ||
| 21 | 22 | export function dutyLines(session: Session, chosen: number): string[] { |
| 22 | 23 | if (!mayAct(session)) return []; |
| 23 | 24 | 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) => { | |
| 25 | 28 | 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" : ""})`}`; | |
| 27 | 31 | }); |
| 28 | 32 | } |
| 29 | 33 |
src/web/pages/maintenance.ts +4 −1
| @@ -25,6 +25,7 @@ import { badge, btn, disclosure, field, seg } from "../ui.ts"; | ||
| 25 | 25 | import { STALE_DAYS, STALE_WORDS, closeStale, nudge, stalePulls } from "../../maintain/stale_pulls.ts"; |
| 26 | 26 | import { PREVIEW_DAYS, PREVIEW_WORDS, previewDirs, previewLine, removePreviewDirs, sizeWords, totalWords, type PreviewDir } from "../../maintain/previews.ts"; |
| 27 | 27 | import { MERGED_DAYS, MERGED_WORDS, deleteMerged, lineOf, mergedBranches, type MergedBranch } from "../../maintain/duties/merged_branches.ts"; |
| 28 | import { dutySchedules, scheduleWords } from "../../maintain/schedule.ts"; | |
| 28 | 29 | import { isKind, quiet, quieted, quietKeys, unquiet, when, type QuietKind, type Quieted } from "../../maintenance/quiet.ts"; |
| 29 | 30 | import { liveLabel } from "../../maintenance/quiet_live.ts"; |
| 30 | 31 | import { writePauseFold } from "./maintenance_pause.ts"; |
| @@ -118,6 +119,7 @@ async function maintenanceAnswer(ctx: Ctx): Promise<Response> { | ||
| 118 | 119 | const { quiet, loud } = splitDuties(ran); |
| 119 | 120 | const dismissed = dismissals(ctx.app.db); |
| 120 | 121 | const states = dutyStates(ctx.app.db); |
| 122 | const schedules = dutySchedules(ctx.app.db, states, Date.now()); | |
| 121 | 123 | const hidden = quieted(ctx.app.db); |
| 122 | 124 | const mergedPending = (await mergedBranches(ctx.app, new Date())).filter((b) => !quietKeys(hidden, "merged-branches").has(lineOf(b))); |
| 123 | 125 | 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> { | ||
| 141 | 143 | ${states.map((d) => { |
| 142 | 144 | const dm = dismissed.get(d.name); |
| 143 | 145 | 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} | |
| 145 | 148 | <form method="post" action="/maintenance/duties/${d.name}" class="inline"> |
| 146 | 149 | <input type="hidden" name="paused" value="${d.paused ? "no" : "yes"}">${btn(d.paused ? "Resume" : "Pause", { variant: "outline" })} |
| 147 | 150 | </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 }> = { | ||
| 59 | 59 | "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277) |
| 60 | 60 | "/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 |
| 61 | 61 | "/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 | |
| 63 | 63 | "/api/v1/maintenance/duties": { statements: 69 }, // the same duties as JSON; slow-tests (#13966), stale-branches (#14141) and edge-kept (#14682) each add 3 |
| 64 | 64 | }; |
| 65 | 65 |
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/.