Public: anyone can read this; the crew can change it.
A paused duty says who paused it and when, on /maintenance #14876
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14864-a-paused-duty-says-who-paused-it-and-whe → main 8 commits fork 3 threads · 3 unresolved
8 files
changed +153
−8
docs/features/duty-paused-by.md added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | --- | |
| 2 | topic: Your apps | |
| 3 | row: A paused duty says who paused it and when | |
| 4 | --- | |
| 5 | # A paused duty says who paused it and when (#14864) | |
| 6 | ||
| 7 | A paused maintenance duty's row reads "paused by <handle> 3 h ago" (`just now`, `N min ago`, `N h ago`, `N d ago`; a runner auto-pause names `the runner`). Resuming clears the line; a duty never paused has none. `dutyState` in `src/maintain/pause.ts` words it once (replacing the old "paused since <UTC>"), so the page, terminal, API and MCP say the same thing; a runner pause adds its reason after it. | |
| 8 | ||
| 9 | - **On the web.** `/maintenance`, Duties: the duty's detail carries it, no separate line. The page is admin-only, so the handle is shown to the same audience as the Pause button. | |
| 10 | - **In the terminal.** Ctrl-K **maintenance** screen: the paused duty's line says the same words. | |
| 11 | ||
| 12 | Tests: `test/maintenance-pause-who.test.ts`, `test/tui-maintenance-pause-who.test.ts`. |
docs/features/maintenance-duties.md +1 −1
| @@ -8,7 +8,7 @@ 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") 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`). | |
| 11 | - **On the web.** `/maintenance` lists each duty once; the ones the runner runs carry their state ("on", or "paused by … 3 h ago; 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 | 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`. |
src/maintain/pause.ts +13 −2
| @@ -4,6 +4,7 @@ | ||
| 4 | 4 | */ |
| 5 | 5 | |
| 6 | 6 | import type { Database } from "bun:sqlite"; |
| 7 | import { ageWords } from "../snapshot/bucket.ts"; | |
| 7 | 8 | import { clip } from "./duty.ts"; |
| 8 | 9 | import { duties as registered } from "./registry.ts"; |
| 9 | 10 | |
| @@ -70,13 +71,23 @@ export function failing(db: Database, name: string, fromRun?: number): { since: | ||
| 70 | 71 | return { since: `${rows[n - 1]!.started.slice(0, 16).replace("T", " ")} UTC`, line }; |
| 71 | 72 | } |
| 72 | 73 | |
| 73 | export function dutyState(db: Database, name: string): DutyState { | |
| 74 | /** "paused by alice 3 h ago"; the age is dropped when the stored time is unreadable. */ | |
| 75 | function pausedWords(by: string, since: string, now: number): string { | |
| 76 | const t = Date.parse(since); | |
| 77 | if (Number.isNaN(t)) return `paused by ${by}`; | |
| 78 | const age = ageWords(now - t); | |
| 79 | return age === "just now" ? `paused by ${by} just now` : `paused by ${by} ${age} ago`; | |
| 80 | } | |
| 81 | ||
| 82 | export function dutyState(db: Database, name: string, now = Date.now()): DutyState { | |
| 74 | 83 | const s = stateRow(db, name); |
| 75 | 84 | if (s?.paused === 1) { |
| 76 | 85 | const f = failing(db, name, s.from_run); |
| 77 | 86 | // The runner's own pause reason already carries the last error: add only the time. |
| 78 | 87 | const more = f === undefined ? "" : s.by === "the runner" ? `; failing since ${f.since}` : `; failing since ${f.since}: ${f.line}`; |
| 79 | const detail = `paused since ${s.since.slice(0, 16).replace("T", " ")} UTC; ${s.reason}${more}`; | |
| 88 | // A person's reason is only "paused by <handle>", which the opening words already say. | |
| 89 | const why = s.by === "the runner" ? `; ${s.reason}` : ""; | |
| 90 | const detail = `${pausedWords(s.by, s.since, now)}${why}${more}`; | |
| 80 | 91 | return { name, paused: true, says: `${name}: ${detail}.`, detail }; |
| 81 | 92 | } |
| 82 | 93 | const last = db.query("SELECT outcome FROM maintenance_run WHERE duty = ?1 ORDER BY id DESC LIMIT 1").get(name) as { outcome: string } | null; |
src/maintain/schedule.ts +1 −1
| @@ -45,7 +45,7 @@ export function dutySchedules(db: Database, states: readonly { name: string; pau | ||
| 45 | 45 | |
| 46 | 46 | /** |
| 47 | 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 | |
| 48 | * already says "paused by … ", so its schedule is only when it ran. Late is not in the words: the | |
| 49 | 49 | * page shows it as a badge and the terminal adds "; late" itself. |
| 50 | 50 | */ |
| 51 | 51 | export const scheduleWords = (s: Schedule): string => (s.next === "paused" ? s.ran : `${s.ran}; ${s.next}`); |
test/maintenance-last-run.test.ts +2 −2
| @@ -90,7 +90,7 @@ test("the page shows ran/next, late in the attn tone, and says paused once", asy | ||
| 90 | 90 | expect(row(a)).not.toContain("late"); |
| 91 | 91 | expect(row(b)).toContain('data-variant="attn"'); |
| 92 | 92 | expect(row(b)).toContain(">late<"); |
| 93 | expect(row(c)).toContain("paused since"); | |
| 93 | expect(row(c)).toContain("paused by"); | |
| 94 | 94 | expect(row(c)).toMatch(/; not run yet\s*</); |
| 95 | 95 | expect(row(c)).not.toContain("late"); |
| 96 | 96 | }); |
| @@ -112,6 +112,6 @@ test("the terminal's duty list says the same words", () => { | ||
| 112 | 112 | const line = (n: string): string => lines.find((l) => l.includes(`${n}:`)) ?? ""; |
| 113 | 113 | expect(line(a)).toContain(`(${ran}`); |
| 114 | 114 | expect(line(b)).toContain("; late)"); |
| 115 | expect(line(c)).toContain("paused since"); | |
| 115 | expect(line(c)).toContain("paused by"); | |
| 116 | 116 | expect(line(c)).toMatch(/\(not run yet\)$/); |
| 117 | 117 | }); |
test/maintenance-level.test.ts +2 −2
| @@ -140,9 +140,9 @@ test("the terminal puts an overdue duty and a paused duty under needs-you, not f | ||
| 140 | 140 | const needs = maintenanceLines(f, undefined, "needs-you").join("\n"); |
| 141 | 141 | const fyi = maintenanceLines(f, undefined, "fyi").join("\n"); |
| 142 | 142 | expect(needs).toContain("overdue"); |
| 143 | expect(needs).toContain(`${stopped}: paused since`); | |
| 143 | expect(needs).toContain(`${stopped}: paused by`); | |
| 144 | 144 | expect(fyi).not.toContain("overdue"); |
| 145 | expect(fyi).not.toContain(`${stopped}: paused since`); | |
| 145 | expect(fyi).not.toContain(`${stopped}: paused by`); | |
| 146 | 146 | // The page agrees: both put Duties under Needs you. |
| 147 | 147 | expect(await get("?level=needs-you")).toContain('id="maintenance-duties-fold"'); |
| 148 | 148 | expect(await get("?level=fyi")).not.toContain('id="maintenance-duties-fold"'); |
test/maintenance-pause-who.test.ts added +72
| @@ -0,0 +1,72 @@ | ||
| 1 | /** | |
| 2 | * A paused duty's row on /maintenance says who paused it and when; a resume clears the line | |
| 3 | * (#14864). | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { createToken } from "../src/core/tokens.ts"; | |
| 11 | import { createUser } from "../src/core/users.ts"; | |
| 12 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 13 | import { duties } from "../src/maintain/registry.ts"; | |
| 14 | import { dutyState, pauseOnErrors, setPaused } from "../src/maintain/pause.ts"; | |
| 15 | import { quietLogs } from "./helpers/globals.ts"; | |
| 16 | ||
| 17 | quietLogs(); | |
| 18 | let root = ""; | |
| 19 | let app: App; | |
| 20 | let servers: Servers; | |
| 21 | let admin = ""; | |
| 22 | const name = duties[0]!.name; | |
| 23 | const page = async (): Promise<string> => (await fetch(`${servers.url}/maintenance`, { headers: { authorization: `Bearer ${admin}` } })).text(); | |
| 24 | ||
| 25 | beforeAll(async () => { | |
| 26 | root = mkdtempSync(join(tmpdir(), "forge-pause-who-")); | |
| 27 | app = createApp({ dataDir: root, port: 0 }); | |
| 28 | servers = await serve(app); | |
| 29 | const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 30 | if (!a.ok) throw new Error("user"); | |
| 31 | admin = createToken(app.db, a.value.id, "a", "admin").token; | |
| 32 | }); | |
| 33 | afterAll(() => { | |
| 34 | servers.stop?.(); | |
| 35 | rmSync(root, { recursive: true, force: true }); | |
| 36 | }); | |
| 37 | ||
| 38 | test("never paused: no line", async () => { | |
| 39 | app.db.exec("DELETE FROM maintenance_duty_state"); | |
| 40 | expect(dutyState(app.db, name).detail).not.toContain("paused"); | |
| 41 | expect(await page()).not.toContain("paused by"); | |
| 42 | }); | |
| 43 | ||
| 44 | test("paused: one wording says by whom and how long ago, once; resumed: it is gone", async () => { | |
| 45 | app.db.exec("DELETE FROM maintenance_duty_state"); | |
| 46 | setPaused(app.db, name, true, "alice", new Date(Date.now() - 3 * 3_600_000 - 1000)); | |
| 47 | expect(dutyState(app.db, name).detail).toBe("paused by alice 3 h ago"); | |
| 48 | const html = await page(); | |
| 49 | expect(html).toContain("paused by alice 3 h ago"); | |
| 50 | expect(html.split("paused by alice").length - 1).toBe(1); | |
| 51 | expect(html).not.toContain("paused since"); | |
| 52 | setPaused(app.db, name, false, "alice"); | |
| 53 | expect(dutyState(app.db, name).detail).not.toContain("paused"); | |
| 54 | expect(await page()).not.toContain("paused by alice"); | |
| 55 | }); | |
| 56 | ||
| 57 | test("a runner auto-pause says 'paused by the runner N h ago' with its reason", () => { | |
| 58 | app.db.exec("DELETE FROM maintenance_duty_state; DELETE FROM maintenance_run"); | |
| 59 | for (let i = 0; i < 3; i++) app.db.query("INSERT INTO maintenance_run (duty, started, finished, outcome) VALUES (?1, ?2, ?2, 'failed: boom')").run(name, new Date().toISOString()); | |
| 60 | const at = new Date(Date.now() - 2 * 3_600_000 - 1000); | |
| 61 | expect(pauseOnErrors(app.db, name, at)).toBe(true); | |
| 62 | const d = dutyState(app.db, name).detail; | |
| 63 | expect(d.startsWith("paused by the runner 2 h ago; paused after 3 errors in a row; last error: failed: boom")).toBe(true); | |
| 64 | expect(d.split("paused by").length - 1).toBe(1); | |
| 65 | }); | |
| 66 | ||
| 67 | test("the handle is for admins: a visitor without a session is refused the page", async () => { | |
| 68 | setPaused(app.db, name, true, "alice"); | |
| 69 | const r = await fetch(`${servers.url}/maintenance`, { redirect: "manual" }); | |
| 70 | expect(r.status).not.toBe(200); | |
| 71 | expect(await r.text()).not.toContain("paused by alice"); | |
| 72 | }); |
test/tui-maintenance-pause-who.test.ts added +50
| @@ -0,0 +1,50 @@ | ||
| 1 | /** The terminal's /maintenance says who paused a duty and when, as the page does (#14864). */ | |
| 2 | import { afterAll, beforeAll, expect, 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, type User } from "../src/core/users.ts"; | |
| 8 | import { setPaused } from "../src/maintain/pause.ts"; | |
| 9 | import { duties } from "../src/maintain/registry.ts"; | |
| 10 | import { createForgeApp } from "../src/tui/forge.ts"; | |
| 11 | import { entry, maintenanceScreen } from "../src/tui/screens/maintenance.ts"; | |
| 12 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | import { settleUntil } from "./helpers/tui.ts"; | |
| 15 | ||
| 16 | quietLogs(); | |
| 17 | let dir = "", app: App, admin: User; | |
| 18 | ||
| 19 | beforeAll(async () => { | |
| 20 | dir = await mkdtemp(join(tmpdir(), "forge-tui-pause-who-")); | |
| 21 | app = createApp({ dataDir: dir, port: 0 }); | |
| 22 | const r = await createUser(app.db, { username: "boss", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, isAdmin: true }); | |
| 23 | if (!r.ok) throw new Error("user"); | |
| 24 | admin = r.value; | |
| 25 | }); | |
| 26 | afterAll(async () => { | |
| 27 | app.close(); | |
| 28 | await rm(dir, { recursive: true, force: true }); | |
| 29 | }); | |
| 30 | ||
| 31 | test("a paused duty reads 'paused by <handle> 3 h ago' in the terminal", async () => { | |
| 32 | setPaused(app.db, duties[0]!.name, true, "boss", new Date(Date.now() - 3 * 3_600_000 - 1000)); | |
| 33 | const terminal = headlessTerminal(160, 40); | |
| 34 | const { app: tui, session } = createForgeApp(app, { sshUsername: "boss", remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user: admin }, { terminal, exitHooks: false }); | |
| 35 | tui.start(); | |
| 36 | tui.ctx.push(maintenanceScreen(session, tui.ctx)); | |
| 37 | await settleUntil(tui, "paused by boss 3 h ago"); | |
| 38 | expect(tui.screen.toText().split("paused by boss").length - 1).toBe(1); | |
| 39 | tui.stop?.(); | |
| 40 | }); | |
| 41 | ||
| 42 | test("a non-admin and an agent are not offered the screen, as the page refuses them", () => { | |
| 43 | const mk = (u: User) => createForgeApp(app, { sshUsername: u.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user: u }, { terminal: headlessTerminal(80, 24), exitHooks: false }); | |
| 44 | const person = { ...admin, isAdmin: false } as User; | |
| 45 | for (const u of [person, { ...admin, kind: "agent" } as User]) { | |
| 46 | const { app: tui, session } = mk(u); | |
| 47 | expect(entry.offered?.(session)).toBe(false); | |
| 48 | tui.stop?.(); | |
| 49 | } | |
| 50 | }); |
new above
offline