Public: anyone can read this; the crew can change it.
/status says when its words were read, and since when a row that is not ok has been so #13858
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13854-status-says-when-its-words-were-read-and → main 4 commits fork
7 files
changed +79
−17
docs/STATUS.md +1 −1
| @@ -139,7 +139,7 @@ cannot confirm. A package registry is not shipped yet. | ||
| 139 | 139 | working issues in the background with Claude Code and proposing through |
| 140 | 140 | pulls a person merges. |
| 141 | 141 | - **The `flow` label**: ready issues labelled `flow` go first; no switch, no state. |
| 142 | - **`/status`**: one sentence, signed out, always 200: `All working.`, `Slowed: <cause>.` or `Down since <time>.`, over three rows (pages and sign-in, building, billing records), each `ok`, `slow` or `down` from a real signal. `Accept: application/json` gives the same words as data; the palette's *Status* shows them in the terminal. Words come from a fixed table (`src/core/status_words.ts`), never copied from errors. | |
| 142 | - **`/status`**: one sentence, signed out, always 200: `All working.`, `Slowed: <cause>.` or `Down since <time>.`, over three rows (pages and sign-in, building, billing records), each `ok`, `slow` or `down` from a real signal. `Accept: application/json` gives the same words as data; the palette's *Status* shows them in the terminal. Under the sentence the page says `as of HH:MM UTC`; a row that is slow or down says `since HH:MM UTC` (when its first cause was seen). The JSON carries `asOf` (ISO) and, per row, `{state, since?}`. Words come from a fixed table (`src/core/status_words.ts`), never copied from errors. | |
| 143 | 143 | |
| 144 | 144 | Pages render without a line of JavaScript and are designed thumb-first. Six |
| 145 | 145 | premade themes (from warm paper to polar night) switch instantly and persist in |
docs/features/README.md +1
| @@ -485,6 +485,7 @@ Read with the guide page [Every setting, by topic](../guide-settings.md). | ||
| 485 | 485 | |
| 486 | 486 | Read with the guide page [](../guide-when-wrong.md). |
| 487 | 487 | |
| 488 | - [](status-time.md) | |
| 488 | 489 | - [](system.md) |
| 489 | 490 | - [](child-stopped.md) |
| 490 | 491 | - [](sync-failed-feed.md) |
docs/features/status-time.md added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | # /status says when it was read, and since when | |
| 2 | ||
| 3 | Open `/status` (signed out) or choose **Status** in the terminal palette | |
| 4 | (`ssh` in, `ctrl+k`, Status). Under the sentence it says `as of 14:05 UTC`: when the | |
| 5 | words were read (held at most 10 s). A row that is slow or down says since when: | |
| 6 | `down since 14:02 UTC`, the time its first cause was seen. An ok row says only `ok`. | |
| 7 | ||
| 8 | `Accept: application/json` gives `asOf` (ISO) and, per row, `{ "state", "since" }`; | |
| 9 | `since` is absent on an ok row, and where no time is known (billing records, a restart). | |
| 10 | ||
| 11 | The page and the terminal read one function (`src/core/status_words.ts`). |
src/core/status_words.ts +37 −7
| @@ -32,11 +32,19 @@ export interface StatusWords { | ||
| 32 | 32 | /** `All working.`, `Slowed: <cause>.`, `Down since <time>.` or `Down.` */ |
| 33 | 33 | readonly sentence: string; |
| 34 | 34 | readonly state: "working" | "slowed" | "down"; |
| 35 | readonly rows: readonly { readonly name: Row; readonly state: RowState }[]; | |
| 35 | /** When these words were read (ISO). */ | |
| 36 | readonly asOf: string; | |
| 37 | /** | |
| 38 | * `since` is when the first cause on a row that is not ok was seen (ISO); absent when none is | |
| 39 | * known. | |
| 40 | */ | |
| 41 | readonly rows: readonly { readonly name: Row; readonly state: RowState; readonly since?: string }[]; | |
| 36 | 42 | } |
| 37 | 43 | |
| 38 | 44 | /** What the forge was told, reduced to the plain facts: no sentence of its own survives. */ |
| 39 | 45 | export interface StatusInput { |
| 46 | /** When the facts were read (ISO). */ | |
| 47 | readonly asOf: string; | |
| 40 | 48 | readonly ok: boolean; |
| 41 | 49 | readonly draining: boolean; |
| 42 | 50 | /** |
| @@ -80,12 +88,14 @@ export function statusOf(input: StatusInput): StatusWords { | ||
| 80 | 88 | const raise = (row: Row, s: RowState) => { |
| 81 | 89 | if (state.get(row) === "ok" || s === "down") state.set(row, s); |
| 82 | 90 | }; |
| 91 | const since = new Map<Row, string>(); | |
| 83 | 92 | const slow: string[] = []; |
| 84 | 93 | const brokenSince: string[] = []; |
| 85 | 94 | for (const c of input.causes) { |
| 86 | 95 | if (!c.broken && WISHES(c.cause)) continue; |
| 87 | 96 | const row: Row = BUILDING(c.cause) ? "building" : "pages and sign-in"; |
| 88 | 97 | raise(row, c.broken ? "down" : "slow"); |
| 98 | if (at(c.since) !== null && (since.get(row) === undefined || c.since < since.get(row)!)) since.set(row, c.since); | |
| 89 | 99 | if (c.broken) brokenSince.push(c.since); |
| 90 | 100 | else slow.push(starts("queue", "stuck", "red", "shared", "memory", "memory-growth", "disk", "disk-floor", "errors", "internal", "crash-loop")(c.cause) ? PLAIN[row] : GENERIC); |
| 91 | 101 | } |
| @@ -102,13 +112,26 @@ export function statusOf(input: StatusInput): StatusWords { | ||
| 102 | 112 | raise("pages and sign-in", "down"); |
| 103 | 113 | const first = brokenSince.filter((s) => at(s) !== null).sort()[0]; |
| 104 | 114 | // The time is when the forge first saw the cause; with none to name, no time is made up. |
| 105 | return { sentence: first === undefined ? "Down." : `Down since ${at(first)}.`, state: "down", rows: rowsOf(state) }; | |
| 115 | return { sentence: first === undefined ? "Down." : `Down since ${at(first)}.`, state: "down", asOf: input.asOf, rows: rowsOf(state, since) }; | |
| 106 | 116 | } |
| 107 | if (slow.length > 0) return { sentence: `Slowed: ${slow[0]}.`, state: "slowed", rows: rowsOf(state) }; | |
| 108 | return { sentence: "All working.", state: "working", rows: rowsOf(state) }; | |
| 117 | if (slow.length > 0) return { sentence: `Slowed: ${slow[0]}.`, state: "slowed", asOf: input.asOf, rows: rowsOf(state, since) }; | |
| 118 | return { sentence: "All working.", state: "working", asOf: input.asOf, rows: rowsOf(state, since) }; | |
| 109 | 119 | } |
| 110 | 120 | |
| 111 | const rowsOf = (m: Map<Row, RowState>) => ROWS.map((name) => ({ name, state: m.get(name)! })); | |
| 121 | const rowsOf = (m: Map<Row, RowState>, since: Map<Row, string>) => | |
| 122 | ROWS.map((name) => { | |
| 123 | const s = since.get(name); | |
| 124 | return m.get(name) !== "ok" && s !== undefined ? { name, state: m.get(name)!, since: s } : { name, state: m.get(name)! }; | |
| 125 | }); | |
| 126 | ||
| 127 | /** `down since 14:02 UTC`, or just the word when no time is known. */ | |
| 128 | export function rowWords(r: StatusWords["rows"][number]): string { | |
| 129 | const t = r.since === undefined ? null : at(r.since); | |
| 130 | return t === null || r.state === "ok" ? WORD[r.state] : `${WORD[r.state]} since ${t}`; | |
| 131 | } | |
| 132 | ||
| 133 | /** `as of 14:05 UTC`. */ | |
| 134 | export const asOfWords = (w: StatusWords): string => `as of ${at(w.asOf) ?? w.asOf}`; | |
| 112 | 135 | |
| 113 | 136 | /** Each row's one word: `ok`, or why not. */ |
| 114 | 137 | export const WORD: Readonly<Record<RowState, string>> = { ok: "ok", slow: "slow", down: "down" }; |
| @@ -126,6 +149,7 @@ export function statusWords(app: App, now: number = Date.now()): StatusWords { | ||
| 126 | 149 | const health = forgeHealth(); |
| 127 | 150 | const v = forgeVitals(app); |
| 128 | 151 | const words = statusOf({ |
| 152 | asOf: new Date(now).toISOString(), | |
| 129 | 153 | ok: health.ok && v.ok, |
| 130 | 154 | draining: health.draining, |
| 131 | 155 | causes: v.degraded.map((d) => ({ cause: d.cause, broken: d.broken, since: d.since })), |
| @@ -136,10 +160,16 @@ export function statusWords(app: App, now: number = Date.now()): StatusWords { | ||
| 136 | 160 | } |
| 137 | 161 | |
| 138 | 162 | /** The JSON answer: the same words, as data. */ |
| 139 | export function statusJson(w: StatusWords): { status: string; sentence: string; rows: Record<string, string> } { | |
| 163 | export function statusJson(w: StatusWords): { | |
| 164 | status: string; | |
| 165 | sentence: string; | |
| 166 | asOf: string; | |
| 167 | rows: Record<string, { state: string; since?: string }>; | |
| 168 | } { | |
| 140 | 169 | return { |
| 141 | 170 | status: w.state, |
| 142 | 171 | sentence: w.sentence, |
| 143 | rows: Object.fromEntries(w.rows.map((r) => [r.name, WORD[r.state]])), | |
| 172 | asOf: w.asOf, | |
| 173 | rows: Object.fromEntries(w.rows.map((r) => [r.name, r.since === undefined ? { state: WORD[r.state] } : { state: WORD[r.state], since: r.since }])), | |
| 144 | 174 | }; |
| 145 | 175 | } |
src/tui/screens/status.ts +2 −2
| @@ -3,7 +3,7 @@ | ||
| 3 | 3 | * shows, from the same `statusWords`. Anyone may open it; read-only. |
| 4 | 4 | */ |
| 5 | 5 | |
| 6 | import { statusWords, WORD } from "../../core/status_words.ts"; | |
| 6 | import { asOfWords, rowWords, statusWords } from "../../core/status_words.ts"; | |
| 7 | 7 | import type { Ctx, Screen } from "../app/app.ts"; |
| 8 | 8 | import { binding } from "../app/keys.ts"; |
| 9 | 9 | import type { Session } from "../session.ts"; |
| @@ -13,7 +13,7 @@ import { pad } from "../term/width.ts"; | ||
| 13 | 13 | /** The screen's lines: the sentence, then each row's name and word. */ |
| 14 | 14 | export function statusLines(session: Session): string[] { |
| 15 | 15 | const w = statusWords(session.app); |
| 16 | return [w.sentence, "", ...w.rows.map((r) => `${pad(r.name, 20)}${WORD[r.state]}`)]; | |
| 16 | return [w.sentence, asOfWords(w), "", ...w.rows.map((r) => `${pad(r.name, 20)}${rowWords(r)}`)]; | |
| 17 | 17 | } |
| 18 | 18 | |
| 19 | 19 | export function statusScreen(session: Session, ctx: Ctx): Screen { |
src/web/pages/status.ts +3 −3
| @@ -9,7 +9,7 @@ | ||
| 9 | 9 | * inside the window builds nothing. |
| 10 | 10 | */ |
| 11 | 11 | |
| 12 | import { statusJson, statusWords, WORD, type StatusWords } from "../../core/status_words.ts"; | |
| 12 | import { asOfWords, rowWords, statusJson, statusWords, type StatusWords } from "../../core/status_words.ts"; | |
| 13 | 13 | import type { Ctx } from "../../http/context.ts"; |
| 14 | 14 | import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts"; |
| 15 | 15 | import { stylesheetAsset } from "../asset.ts"; |
| @@ -27,7 +27,7 @@ function markup(words: StatusWords): string { | ||
| 27 | 27 | const kept = built.get(words); |
| 28 | 28 | if (kept !== undefined) return kept; |
| 29 | 29 | statusBuilds.count += 1; |
| 30 | const rows = words.rows.map((r) => statusRow(r.name, badge(WORD[r.state], { tone: tone[r.state] }))); | |
| 30 | const rows = words.rows.map((r) => statusRow(r.name, badge(rowWords(r), { tone: tone[r.state] }))); | |
| 31 | 31 | const text = html`<!doctype html> |
| 32 | 32 | <html lang="en"> |
| 33 | 33 | <head> |
| @@ -39,7 +39,7 @@ function markup(words: StatusWords): string { | ||
| 39 | 39 | </head> |
| 40 | 40 | <body> |
| 41 | 41 | <main class="shell" id="main"> |
| 42 | <div class="page-head"><h1>${words.sentence}</h1></div> | |
| 42 | <div class="page-head"><h1>${words.sentence}</h1><p class="hint">${asOfWords(words)}</p></div> | |
| 43 | 43 | <dl class="status-rows">${rows}</dl> |
| 44 | 44 | </main> |
| 45 | 45 | <footer class="foot"><a href="/">forge</a><span class="spacer"></span><a href="/status">Status</a><a href="/privacy">Privacy</a></footer> |
test/status-page.test.ts +24 −4
| @@ -4,7 +4,7 @@ import { tmpdir } from "node:os"; | ||
| 4 | 4 | import { join } from "node:path"; |
| 5 | 5 | import { createApp, type App } from "../src/app.ts"; |
| 6 | 6 | import { serve, type Servers } from "../src/http/server.ts"; |
| 7 | import { statusJson, statusOf, statusReuse, statusWords, type StatusInput } from "../src/core/status_words.ts"; | |
| 7 | import { asOfWords, rowWords, statusJson, statusOf, statusReuse, statusWords, type StatusInput } from "../src/core/status_words.ts"; | |
| 8 | 8 | import { statusBuilds } from "../src/web/pages/status.ts"; |
| 9 | 9 | import { createForgeApp, forgeCommands, Session } from "../src/tui/forge.ts"; |
| 10 | 10 | import { statusLines } from "../src/tui/screens/status.ts"; |
| @@ -28,7 +28,8 @@ afterAll(async () => { | ||
| 28 | 28 | await rm(dir, { recursive: true, force: true }); |
| 29 | 29 | }); |
| 30 | 30 | |
| 31 | const healthy: StatusInput = { ok: true, draining: false, causes: [], ledgerBroken: false }; | |
| 31 | const AS_OF = "2026-11-15T14:05:09.000Z"; | |
| 32 | const healthy: StatusInput = { asOf: AS_OF, ok: true, draining: false, causes: [], ledgerBroken: false }; | |
| 32 | 33 | const cause = (c: string, broken: boolean, since = "2026-11-15T09:00:00Z") => ({ cause: c, broken, since }); |
| 33 | 34 | |
| 34 | 35 | describe("status words", () => { |
| @@ -52,6 +53,22 @@ describe("status words", () => { | ||
| 52 | 53 | expect(statusOf({ ...healthy, causes: [cause("disk-full", true, "2026-11-15T08:30:00Z")] })).toEqual(b); |
| 53 | 54 | }); |
| 54 | 55 | |
| 56 | test("words carry when they were read; a down row says since when, an ok row says nothing", () => { | |
| 57 | const ok = statusOf(healthy); | |
| 58 | expect(ok.asOf).toBe(AS_OF); | |
| 59 | expect(asOfWords(ok)).toBe("as of 14:05 UTC"); | |
| 60 | expect(ok.rows.some((r) => r.since !== undefined)).toBe(false); | |
| 61 | const d = statusOf({ ...healthy, causes: [cause("disk-full", true, "2026-11-15T14:02:00Z"), cause("disk-full2", true, "2026-11-15T14:03:00Z")] }); | |
| 62 | const row = d.rows[0]!; | |
| 63 | expect(row.since).toBe("2026-11-15T14:02:00Z"); | |
| 64 | expect(rowWords(row)).toBe("down since 14:02 UTC"); | |
| 65 | expect(statusJson(d).rows["pages and sign-in"]).toEqual({ state: "down", since: "2026-11-15T14:02:00Z" }); | |
| 66 | expect(statusJson(d).rows["building"]).toEqual({ state: "ok" }); | |
| 67 | expect(statusJson(d).asOf).toBe(AS_OF); | |
| 68 | const s = statusOf({ ...healthy, causes: [cause("stuck:r", false, "2026-11-15T13:00:00Z")] }); | |
| 69 | expect(rowWords(s.rows[1]!)).toBe("slow since 13:00 UTC"); | |
| 70 | }); | |
| 71 | ||
| 55 | 72 | test("not ok with no cause to name says Down. with no time", () => { |
| 56 | 73 | expect(statusOf({ ...healthy, ok: false }).sentence).toBe("Down."); |
| 57 | 74 | }); |
| @@ -83,7 +100,8 @@ describe("statusWords", () => { | ||
| 83 | 100 | const w = statusWords(failing); |
| 84 | 101 | expect(w.state).toBe("down"); |
| 85 | 102 | expect(w.sentence).toMatch(/^Down since \d\d:\d\d UTC\.$/); |
| 86 | expect(w.rows[0]).toEqual({ name: "pages and sign-in", state: "down" }); | |
| 103 | expect(w.rows[0]).toMatchObject({ name: "pages and sign-in", state: "down" }); | |
| 104 | expect(w.rows[0]!.since).toBeString(); | |
| 87 | 105 | expect(statusWords(app).state).toBe("working"); |
| 88 | 106 | const user = { sshUsername: "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user: undefined }; |
| 89 | 107 | expect(statusLines(new Session(failing, user))[0]).toBe(w.sentence); |
| @@ -110,6 +128,7 @@ describe("GET /status", () => { | ||
| 110 | 128 | const text = await r.text(); |
| 111 | 129 | expect(r.status).toBe(200); |
| 112 | 130 | expect(text).toContain("All working."); |
| 131 | expect(text).toMatch(/as of \d\d:\d\d UTC/); | |
| 113 | 132 | expect(text).toContain('<dl class="status-rows">'); |
| 114 | 133 | expect(text).not.toContain("<li>pages"); |
| 115 | 134 | expect(r.headers.get("content-security-policy")).toBeTruthy(); |
| @@ -153,7 +172,8 @@ describe("GET /status", () => { | ||
| 153 | 172 | expect(raw.length).toBeLessThan(512); |
| 154 | 173 | const j = JSON.parse(raw) as ReturnType<typeof statusJson>; |
| 155 | 174 | expect(page).toContain(j.sentence); |
| 156 | for (const [name, word] of Object.entries(j.rows)) expect(page).toMatch(new RegExp(`<dt>${name}</dt>\\s*<dd>[^]*?${word}`)); | |
| 175 | expect(j.asOf).toMatch(/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/); | |
| 176 | for (const [name, row] of Object.entries(j.rows)) expect(page).toMatch(new RegExp(`<dt>${name}</dt>\\s*<dd>[^]*?${row.state}`)); | |
| 157 | 177 | expect(Object.keys(j.rows)).toHaveLength(3); |
| 158 | 178 | }); |
| 159 | 179 |
new above
offline