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

Merged opened this

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

Merged

scout/forge:scout/13854-status-says-when-its-words-were-read-and → main 4 commits fork

  • Merged. scout/13854-status-says-when-its-words-were-read-and was merged into main as 7612a18.

Review

Sign in to review this change.
7 files changed +79 −17
docs/STATUS.md +1 −1
@@ -139,7 +139,7 @@ cannot confirm. A package registry is not shipped yet.
139139 working issues in the background with Claude Code and proposing through
140140 pulls a person merges.
141141 - **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.
143143
144144 Pages render without a line of JavaScript and are designed thumb-first. Six
145145 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).
485485
486486 Read with the guide page [When something is wrong](../guide-when-wrong.md).
487487
488 - [/status says when it was read, and since when a row is not ok](status-time.md)
488489 - [The machine's real size on /system and in health](system.md)
489490 - [A child forge the host stopped](child-stopped.md)
490491 - [A failed adapter pull speaks once in the writers' feed](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 {
3232 /** `All working.`, `Slowed: <cause>.`, `Down since <time>.` or `Down.` */
3333 readonly sentence: string;
3434 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 }[];
3642 }
3743
3844 /** What the forge was told, reduced to the plain facts: no sentence of its own survives. */
3945 export interface StatusInput {
46 /** When the facts were read (ISO). */
47 readonly asOf: string;
4048 readonly ok: boolean;
4149 readonly draining: boolean;
4250 /**
@@ -80,12 +88,14 @@ export function statusOf(input: StatusInput): StatusWords {
8088 const raise = (row: Row, s: RowState) => {
8189 if (state.get(row) === "ok" || s === "down") state.set(row, s);
8290 };
91 const since = new Map<Row, string>();
8392 const slow: string[] = [];
8493 const brokenSince: string[] = [];
8594 for (const c of input.causes) {
8695 if (!c.broken && WISHES(c.cause)) continue;
8796 const row: Row = BUILDING(c.cause) ? "building" : "pages and sign-in";
8897 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);
8999 if (c.broken) brokenSince.push(c.since);
90100 else slow.push(starts("queue", "stuck", "red", "shared", "memory", "memory-growth", "disk", "disk-floor", "errors", "internal", "crash-loop")(c.cause) ? PLAIN[row] : GENERIC);
91101 }
@@ -102,13 +112,26 @@ export function statusOf(input: StatusInput): StatusWords {
102112 raise("pages and sign-in", "down");
103113 const first = brokenSince.filter((s) => at(s) !== null).sort()[0];
104114 // 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) };
106116 }
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) };
109119 }
110120
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}`;
112135
113136 /** Each row's one word: `ok`, or why not. */
114137 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 {
126149 const health = forgeHealth();
127150 const v = forgeVitals(app);
128151 const words = statusOf({
152 asOf: new Date(now).toISOString(),
129153 ok: health.ok && v.ok,
130154 draining: health.draining,
131155 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 {
136160 }
137161
138162 /** 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 } {
140169 return {
141170 status: w.state,
142171 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 }])),
144174 };
145175 }
src/tui/screens/status.ts +2 −2
@@ -3,7 +3,7 @@
33 * shows, from the same `statusWords`. Anyone may open it; read-only.
44 */
55
6 import { statusWords, WORD } from "../../core/status_words.ts";
6 import { asOfWords, rowWords, statusWords } from "../../core/status_words.ts";
77 import type { Ctx, Screen } from "../app/app.ts";
88 import { binding } from "../app/keys.ts";
99 import type { Session } from "../session.ts";
@@ -13,7 +13,7 @@ import { pad } from "../term/width.ts";
1313 /** The screen's lines: the sentence, then each row's name and word. */
1414 export function statusLines(session: Session): string[] {
1515 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)}`)];
1717 }
1818
1919 export function statusScreen(session: Session, ctx: Ctx): Screen {
src/web/pages/status.ts +3 −3
@@ -9,7 +9,7 @@
99 * inside the window builds nothing.
1010 */
1111
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";
1313 import type { Ctx } from "../../http/context.ts";
1414 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
1515 import { stylesheetAsset } from "../asset.ts";
@@ -27,7 +27,7 @@ function markup(words: StatusWords): string {
2727 const kept = built.get(words);
2828 if (kept !== undefined) return kept;
2929 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] })));
3131 const text = html`<!doctype html>
3232 <html lang="en">
3333 <head>
@@ -39,7 +39,7 @@ function markup(words: StatusWords): string {
3939 </head>
4040 <body>
4141 <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>
4343 <dl class="status-rows">${rows}</dl>
4444 </main>
4545 <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";
44 import { join } from "node:path";
55 import { createApp, type App } from "../src/app.ts";
66 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";
88 import { statusBuilds } from "../src/web/pages/status.ts";
99 import { createForgeApp, forgeCommands, Session } from "../src/tui/forge.ts";
1010 import { statusLines } from "../src/tui/screens/status.ts";
@@ -28,7 +28,8 @@ afterAll(async () => {
2828 await rm(dir, { recursive: true, force: true });
2929 });
3030
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 };
3233 const cause = (c: string, broken: boolean, since = "2026-11-15T09:00:00Z") => ({ cause: c, broken, since });
3334
3435 describe("status words", () => {
@@ -52,6 +53,22 @@ describe("status words", () => {
5253 expect(statusOf({ ...healthy, causes: [cause("disk-full", true, "2026-11-15T08:30:00Z")] })).toEqual(b);
5354 });
5455
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
5572 test("not ok with no cause to name says Down. with no time", () => {
5673 expect(statusOf({ ...healthy, ok: false }).sentence).toBe("Down.");
5774 });
@@ -83,7 +100,8 @@ describe("statusWords", () => {
83100 const w = statusWords(failing);
84101 expect(w.state).toBe("down");
85102 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();
87105 expect(statusWords(app).state).toBe("working");
88106 const user = { sshUsername: "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user: undefined };
89107 expect(statusLines(new Session(failing, user))[0]).toBe(w.sentence);
@@ -110,6 +128,7 @@ describe("GET /status", () => {
110128 const text = await r.text();
111129 expect(r.status).toBe(200);
112130 expect(text).toContain("All working.");
131 expect(text).toMatch(/as of \d\d:\d\d UTC/);
113132 expect(text).toContain('<dl class="status-rows">');
114133 expect(text).not.toContain("<li>pages");
115134 expect(r.headers.get("content-security-policy")).toBeTruthy();
@@ -153,7 +172,8 @@ describe("GET /status", () => {
153172 expect(raw.length).toBeLessThan(512);
154173 const j = JSON.parse(raw) as ReturnType<typeof statusJson>;
155174 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}`));
157177 expect(Object.keys(j.rows)).toHaveLength(3);
158178 });
159179

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs