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

A paused duty says who paused it and when, on /maintenance #14876

Merged opened this

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

Merged

scout/forge:scout/14864-a-paused-duty-says-who-paused-it-and-whe → main 8 commits fork 3 threads · 3 unresolved

  • Merged. scout/14864-a-paused-duty-says-who-paused-it-and-whe was merged into main as 1dcfc97.

Review

Sign in to review this change.
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
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") 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`).
1212 - **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`.
src/maintain/pause.ts +13 −2
@@ -4,6 +4,7 @@
44 */
55
66 import type { Database } from "bun:sqlite";
7 import { ageWords } from "../snapshot/bucket.ts";
78 import { clip } from "./duty.ts";
89 import { duties as registered } from "./registry.ts";
910
@@ -70,13 +71,23 @@ export function failing(db: Database, name: string, fromRun?: number): { since:
7071 return { since: `${rows[n - 1]!.started.slice(0, 16).replace("T", " ")} UTC`, line };
7172 }
7273
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 {
7483 const s = stateRow(db, name);
7584 if (s?.paused === 1) {
7685 const f = failing(db, name, s.from_run);
7786 // The runner's own pause reason already carries the last error: add only the time.
7887 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}`;
8091 return { name, paused: true, says: `${name}: ${detail}.`, detail };
8192 }
8293 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
4545
4646 /**
4747 * 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
4949 * page shows it as a badge and the terminal adds "; late" itself.
5050 */
5151 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
9090 expect(row(a)).not.toContain("late");
9191 expect(row(b)).toContain('data-variant="attn"');
9292 expect(row(b)).toContain(">late<");
93 expect(row(c)).toContain("paused since");
93 expect(row(c)).toContain("paused by");
9494 expect(row(c)).toMatch(/; not run yet\s*</);
9595 expect(row(c)).not.toContain("late");
9696 });
@@ -112,6 +112,6 @@ test("the terminal's duty list says the same words", () => {
112112 const line = (n: string): string => lines.find((l) => l.includes(`${n}:`)) ?? "";
113113 expect(line(a)).toContain(`(${ran}`);
114114 expect(line(b)).toContain("; late)");
115 expect(line(c)).toContain("paused since");
115 expect(line(c)).toContain("paused by");
116116 expect(line(c)).toMatch(/\(not run yet\)$/);
117117 });
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
140140 const needs = maintenanceLines(f, undefined, "needs-you").join("\n");
141141 const fyi = maintenanceLines(f, undefined, "fyi").join("\n");
142142 expect(needs).toContain("overdue");
143 expect(needs).toContain(`${stopped}: paused since`);
143 expect(needs).toContain(`${stopped}: paused by`);
144144 expect(fyi).not.toContain("overdue");
145 expect(fyi).not.toContain(`${stopped}: paused since`);
145 expect(fyi).not.toContain(`${stopped}: paused by`);
146146 // The page agrees: both put Duties under Needs you.
147147 expect(await get("?level=needs-you")).toContain('id="maintenance-duties-fold"');
148148 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs