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

A settings line that is changed shows who changed it and when, in one muted phrase #13096

Merged opened this

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

Merged

torque/forge:torque/13050-a-settings-line-that-is-changed-shows-wh → main 4 commits fork 3 threads · 3 unresolved

  • Merged. torque/13050-a-settings-line-that-is-changed-shows-wh was merged into main as 4cdb9ee.

Review

Sign in to review this change.
10 files changed +282 −10
docs/design/areas/settings.md +2
@@ -27,6 +27,8 @@ its name, its control (the checkbox, select or number is the value) and a mark t
2727 `settingLine()` and `toggleLine()` in `src/web/setting_line.ts`; styled in `src/web/style/components.ts`.
2828
2929 - `.setting-line` — the `.field` row: a wrapping flex line of label, control and mark, at desktop and 390 px alike.
30 - `.setting-changed` — the muted "changed by <name>, <time>" phrase at the end of a `.setting-line`; present only once the
31 setting has changed (read from `repo.settings_updated`), so an untouched row is unchanged. Under 600 px it takes its own full line, so a long label never squeezes it.
3032 - `.why` — the `<details>` holding a setting's reason. Its summary is the help mark drawn as a small bordered round
3133 button (28px, 44px on touch), named "Why" for a screen reader and a tooltip; open, the reason takes the full width
3234 under the row.
docs/features/README.md +1
@@ -35,6 +35,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
3535 - [Plans on the home](home-plans.md)
3636 - [Returning visitors](returning-visitors.md)
3737 - [Template mark](repo-template.md)
38 - [Who changed a setting, and when](setting-history.md)
3839 - [A new forge can start from a template repository](new-forge-template.md)
3940 - [The explorer's sorts](explore.md)
4041 - [The feed pages by cursor](feed-cursor.md)
docs/features/setting-history.md added +12
@@ -0,0 +1,12 @@
1 # Who changed a setting, and when
2
3 A setting that has changed says so on its row of the repository's settings page, in one muted phrase:
4 `changed by olive, 2 hours ago`. A setting that never changed shows nothing.
5
6 - **Where it comes from.** The `repo.settings_updated` events that saving the page already writes
7 (`src/settings/last_change.ts`, `lastChanges`). No new table. It looks through the newest 200 such events, so a
8 setting last changed before that shows nothing.
9 - **Which rows.** Default branch, protect, review, deploy check, how a pull lands, outsiders and polish share.
10 - **On the web.** Open `/<owner>/<repo>/settings`. Under 600 px the phrase takes its own line under the row.
11 - **In the terminal.** Open the palette and choose "Setting history" while the repository is open (admins of it): one
12 line per changed setting, `Landing: changed by olive, 2 hours ago`. It redraws when a change is saved.
src/settings/last_change.ts added +51
@@ -0,0 +1,51 @@
1 /**

Both doors: a person can read who changed a setting on the page but not in the terminal. Add the per-row phrase to the settings screen in src/tui/ (entry where AGENTS.md says), reading lastChanges, and add docs/features/setting-history.md as the how-to. A "No door:" line in a commit message does not satisfy this.

2 * Who last changed each of a repository's settings, and when (#13050), read
3 * from the record `updateRepoSettings` already keeps: `repo.settings_updated`
4 * events, each carrying `changed: { setting: { from, to } }`. No new table.
5 * A setting that never changed has no entry.
6 */
7 import type { Database } from "bun:sqlite";
8 import { listEvents } from "../core/events.ts";
9 import { getUsersByIds } from "../core/users.ts";
10 import { eventActor } from "../design/activity.ts";
11
12 export interface LastChange {
13 /** Who, as the activity feed names them. */
14 readonly by: string;
15 /** ISO-8601 instant of the change. */
16 readonly at: string;
17 }
18
19 /** The page's row names, in the order the page draws them, with the label each carries. */
20 export const SETTING_ROWS: ReadonlyArray<readonly [row: string, label: string]> = [
21 ["defaultBranch", "Default branch"],
22 ["protect", "Protect the default branch"],
23 ["requireReview", "Require an approving review"],
24 ["requireChecks", "Require a passing deploy"],
25 ["landing", "How a pull lands"],
26 ["crewOutsiders", "Outsiders may trigger the crew"],
27 ["polishShare", "Polish share"],
28 ];
29
30 /** How many of the newest settings events one read looks through. */
31 const WINDOW = 200;
32
33 /** The page's row name for a setting, where it differs from the audited key. */
34 const ROW_OF: Record<string, string> = { protectDefault: "protect" };
35
36 /** Row name → its most recent change, for every setting changed within the window. */
37 export function lastChanges(db: Database, repoId: string): Map<string, LastChange> {
38 const events = listEvents(db, { repoId, kind: "repo.settings_updated", limit: WINDOW });
39 const users = getUsersByIds(db, events.flatMap((e) => (e.actorId === null ? [] : [e.actorId])));
40 const out = new Map<string, LastChange>();
41 for (const event of events) {
42 const changed = event.payload["changed"];
43 if (changed === null || typeof changed !== "object" || Array.isArray(changed)) continue;
44 const by = eventActor(event, event.actorId === null ? undefined : users.get(event.actorId)?.username);
45 for (const key of Object.keys(changed)) {
46 const row = ROW_OF[key] ?? key;
47 if (!out.has(row)) out.set(row, { by, at: event.createdAt });
48 }
49 }
50 return out;
51 }
src/tui/screens/settinghistory.ts added +59
@@ -0,0 +1,59 @@
1 /**
2 * Who last changed each setting, in the terminal (#13050): the settings page's
3 * muted "changed by olive, 2 hours ago" phrase, one line per changed setting,
4 * read by the same `lastChanges` from the `repo.settings_updated` record. Read
5 * only; for a repository's admins, who see the settings page. It follows a
6 * write made on the page or here, since both are events on the bus.
7 */
8
9 import { canAdmin, getRepoById, type Repo } from "../../core/repos.ts";
10 import { agoWords } from "../../kernel/ago.ts";
11 import { lastChanges, SETTING_ROWS } from "../../settings/last_change.ts";
12 import type { Ctx, Screen } from "../app/app.ts";
13 import type { Command } from "../app/palette.ts";
14 import type { Session } from "../session.ts";
15 import { style } from "../term/style.ts";
16 import { truncate } from "../term/width.ts";
17 import { live } from "./common.ts";
18
19 /** The lines: "Landing changed by olive, 2 hours ago", or one sentence when nothing changed. */
20 export function historyLines(f: Session, repo: Repo, now: number = Date.now()): string[] {
21 const last = lastChanges(f.db, repo.id);
22 const lines = SETTING_ROWS.flatMap(([row, label]) => {
23 const c = last.get(row);
24 return c === undefined ? [] : [`${label}: changed by ${c.by}, ${agoWords(c.at, now)}`];
25 });
26 return lines.length > 0 ? lines : ["No setting has been changed yet."];
27 }
28
29 export const maySeeHistory = (f: Session, repo: Repo): boolean => f.user !== undefined && canAdmin(f.db, repo, f.user);
30
31 export function settingHistoryScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
32 return {
33 title: `${repo.ownerName}/${repo.name} — Setting history`,
34 keys: [],
35 async load(signal) {
36 live(f, signal, { repoId: repo.id, kinds: ["repo.settings_updated"] }, () => ctx.invalidate());
37 },
38 render(area, s) {
39 const c = ctx.theme.c;
40 const current = getRepoById(f.db, repo.id) ?? repo;
41 const lines = maySeeHistory(f, current) ? historyLines(f, current) : ["An admin of this repository reads who changed its settings."];
42 lines.slice(0, area.h).forEach((line, i) => s.text(area.x, area.y + i, truncate(line, area.w), style(c.mutedFg, c.bg), area.x + area.w));
43 },
44 key: () => false,
45 };
46 }
47
48 /** The palette's command while a repository the viewer administers is open. */
49 export function settingHistoryCommands(f: Session, ctx: Ctx, repo: Repo | undefined): Command[] {
50 if (repo === undefined || !maySeeHistory(f, repo)) return [];
51 return [
52 {
53 id: "setting-history",
54 title: `${repo.ownerName}/${repo.name} — Setting history`,
55 hint: "who changed each setting, and when",
56 run: () => ctx.push(settingHistoryScreen(f, ctx, repo)),
57 },
58 ];
59 }
src/tui/screens/workspace.ts +2
@@ -181,6 +181,7 @@ import { autonomyCommands } from "./autonomy.ts";
181181 import { trafficCommands } from "./trafficview.ts";
182182 import { chaptersCommands } from "./chapters.ts";
183183 import { outsideAgentsCommands } from "./outsideagents.ts";
184 import { settingHistoryCommands } from "./settinghistory.ts";
184185 import { templateCommands } from "./template.ts";
185186 import { buildCacheCommands } from "./buildcache.ts";
186187 import { schedulesCommands } from "./schedules.ts";
@@ -2083,6 +2084,7 @@ export function workspaceScreen(
20832084 ...deskCommands(f, ctx, repo),
20842085 ...outsideAgentsCommands(f, ctx, repo),
20852086 ...templateCommands(f, ctx, repo),
2087 ...settingHistoryCommands(f, ctx, repo),
20862088 ...buildCacheCommands(f, ctx, repo),
20872089 ...landCommands(f, ctx, repo),
20882090 ...shiftCommands(f, ctx, repo, () => screen),
src/web/pages/settings.ts +14 −7
@@ -101,6 +101,7 @@ import type { NeedRow } from "../../core/app_secrets.ts";
101101 import { field } from "../form.ts";
102102 import { html, raw, when, type Html } from "../html.ts";
103103 import { settingLine, toggleLine } from "../setting_line.ts";
104 import { lastChanges } from "../../settings/last_change.ts";
104105 import { NOT_CHANGED } from "../edit_words.ts";
105106 import { STOP_APP } from "../danger_words.ts";
106107 import { icon } from "../icons.ts";
@@ -268,35 +269,41 @@ export async function settingsPage(
268269 if (!branches.includes(repo.defaultBranch))
269270 branches.unshift(repo.defaultBranch);
270271
272 // Each row says who last changed it and when, from the settings record.
273 const last = lastChanges(ctx.app.db, repo.id);
274 const lineOf = (name: string, body: Html, reason: string | Html): Html => settingLine(name, body, reason, last.get(name));
275 const toggleOf = (name: string, label: string, on: boolean, reason: string | Html, shown?: string): Html =>
276 toggleLine(name, label, on, reason, shown, last.get(name));
277
271278 // The lead's About card owns the description and visibility; this form
272279 // sends them back unchanged, as that one does the gates below.
273280 const body = html`<section class="settings-block">
274281 <h2>Branch and gates</h2>
275282 <form method="post" action="${base}/settings">
276283 <input type="hidden" name="card" value="gates" />
277 ${settingLine("defaultBranch", html`<label for="f-defaultBranch">Default branch</label>
284 ${lineOf("defaultBranch", html`<label for="f-defaultBranch">Default branch</label>
278285 <select class="input" id="f-defaultBranch" name="defaultBranch" aria-describedby="why-defaultBranch">
279286 ${branches.map(
280287 (b) =>
281288 html`<option value="${b}" ${b === repo.defaultBranch ? raw("selected") : null}>${b}</option>`,
282289 )}
283290 </select>`, "Where the repository opens, and what a bare clone checks out.")}
284 ${toggleLine("protect", "Protect the default branch", repo.protectDefault,
291 ${toggleOf("protect", "Protect the default branch", repo.protectDefault,
285292 "No force-push, no deletion, and only its admins push it; everyone else lands through a pull. Enforced by the pre-receive hook, so it holds for every client.")}
286 ${toggleLine("requireReview", "Require an approving review", repo.requireReview,
293 ${toggleOf("requireReview", "Require an approving review", repo.requireReview,
287294 html`Of the commit that is head <em>now</em>, so a push after an approval dismisses it. Refused in the merge itself, not just hidden on the button.`)}
288 ${toggleLine("requireChecks", "Require a passing deploy", repo.requireChecks,
295 ${toggleOf("requireChecks", "Require a passing deploy", repo.requireChecks,
289296 html`The check is the pull request's preview coming up at the commit that is head <em>now</em>. Read live inside the merge, like the review.`)}
290 ${settingLine("landing", html`<input type="hidden" name="landingShown" value="1" />
297 ${lineOf("landing", html`<input type="hidden" name="landingShown" value="1" />
291298 <label for="f-landing">How a pull lands</label>
292299 <select class="input" id="f-landing" name="landing" aria-describedby="why-landing">
293300 <option value="merge" ${repo.landing === "merge" ? raw("selected") : null}>A merge commit</option>
294301 <option value="linear" ${repo.landing === "linear" ? raw("selected") : null}>One commit, in a line</option>
295302 </select>`, "For a pull from a fork.")}
296 ${toggleLine("crewOutsiders", "Outsiders may trigger the crew", repo.crewOutsiders,
303 ${toggleOf("crewOutsiders", "Outsiders may trigger the crew", repo.crewOutsiders,
297304 "Anyone signed in who can read this repository starts and steers runs by commenting, on your budget. Off, only people who can write here direct the crew; anyone else's words stay on the thread. Turning it on or off is recorded in the activity.",
298305 "crewOutsidersShown")}
299 ${settingLine("polishShare", html`<input type="hidden" name="polishShareShown" value="1" />
306 ${lineOf("polishShare", html`<input type="hidden" name="polishShareShown" value="1" />
300307 <label for="polish-share">Polish share, percent (0 to ${String(POLISH_SHARE_MAX)})</label>
301308 <input
302309 class="input input-num mono"
src/web/setting_line.ts +20 −3
@@ -7,6 +7,22 @@
77 */
88 import { html, raw, type Html } from "./html.ts";
99 import { icon } from "./icons.ts";
10 import { agoWords } from "../kernel/ago.ts";
11
12 /** Who changed a setting and when (ISO-8601): the plain shape the page is handed. */
13 export interface ChangedBy {
14 readonly by: string;
15 readonly at: string;
16 }
17
18 /**
outdated

Principle 8 and the design rules: the phrase is fine and muted, but the note is inside a flex row with margin-left:auto, so at 360-390 px with the open Why it wraps to its own line only when the row has history. Show it at 390 px in the before/after pictures to prove it stays one line and shifts nothing. Also this web module now imports from src/settings/, which pulls data-layer types into a view helper; pass a plain {by, at} shape instead.

19 * The muted phrase after a changed setting: "changed by olive, 2 hours ago".
20 * Nothing for one never changed.
21 */
22 export function changedNote(last: ChangedBy | undefined, now: number = Date.now()): Html | null {
23 if (last === undefined) return null;
24 return html`<span class="muted small setting-changed" data-changed>changed by ${last.by}, <time datetime="${last.at}">${agoWords(last.at, now)}</time></span>`;
25 }
1026
1127 /** The reason behind a setting, behind its mark. `id` ties it to the control via aria-describedby. */
1228 export function why(id: string, reason: string | Html): Html {
@@ -14,15 +30,16 @@ export function why(id: string, reason: string | Html): Html {
1430 }
1531
1632 /** A setting line around any control: the caller passes the label and control markup. */
17 export function settingLine(name: string, body: Html, reason: string | Html): Html {
18 return html`<div class="field setting-line" data-setting="${name}">${body}${why(name, reason)}</div>`;
33 export function settingLine(name: string, body: Html, reason: string | Html, last?: ChangedBy): Html {
34 return html`<div class="field setting-line" data-setting="${name}">${body}${why(name, reason)}${changedNote(last)}</div>`;
1935 }
2036
2137 /** A yes/no setting: the checkbox is its value. `shown` names the hidden field saying the box was on the form. */
22 export function toggleLine(name: string, label: string, on: boolean, reason: string | Html, shown?: string): Html {
38 export function toggleLine(name: string, label: string, on: boolean, reason: string | Html, shown?: string, last?: ChangedBy): Html {
2339 return settingLine(
2440 name,
2541 html`${shown ? html`<input type="hidden" name="${shown}" value="1" />` : null}<label class="check"><input type="checkbox" name="${name}" aria-describedby="why-${name}" ${on ? raw("checked") : null} /><span>${label}</span></label>`,
2642 reason,
43 last,
2744 );
2845 }
src/web/style/components.ts +2
@@ -140,6 +140,8 @@ select.input {
140140 .setting-line > .check { flex: 0 1 auto; }
141141 .setting-line > details.why { margin: 0; }
142142 .setting-line > details.why[open] { flex-basis: 100%; }
143 .setting-line > .setting-changed { margin-left: auto; }
144 @media (max-width: 600px) { .setting-line > .setting-changed { flex-basis: 100%; margin-left: 0; } }
143145 .why > summary {
144146 list-style: none; cursor: pointer; display: inline-grid; place-items: center;
145147 width: 28px; height: 28px; border: 1px solid var(--border); border-radius: 999px;
test/settings-last-change.test.ts added +119
@@ -0,0 +1,119 @@
1 /** #13050: a changed setting's row says who changed it and when; an untouched one says nothing. */

Tests: add (a) a changed protect setting shows the phrase on the protect row (covers ROW_OF), and (b) a setting changed only before the 200-event window shows nothing. Also this file is where the terminal screen test should go once the TUI door exists.

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 { serve, type Servers } from "../src/http/server.ts";
8 import { agoWords } from "../src/kernel/ago.ts";
9 import { getUserByName } from "../src/core/users.ts";
10 import { getRepo } from "../src/core/repos.ts";
11 import { lastChanges } from "../src/settings/last_change.ts";
12 import { historyLines, settingHistoryCommands, settingHistoryScreen } from "../src/tui/screens/settinghistory.ts";
13 import { createForgeApp } from "../src/tui/forge.ts";
14 import { headlessTerminal } from "../src/tui/term/terminal.ts";
15 import { settleApp } from "./helpers/tui.ts";
16 import { changedNote } from "../src/web/setting_line.ts";
17 import { adminCookie } from "./helpers/admin.ts";
18
19 let dir = "";
20 let app: App;
21 let servers: Servers;
22 let cookie = "";
23
24 beforeAll(async () => {
25 dir = await mkdtemp(join(tmpdir(), "forge-lastchange-"));
26 app = createApp({ dataDir: dir, port: 0 });
27 servers = await serve(app);
28 cookie = await adminCookie(app, { username: "olive", email: "[email protected]", password: "settings-password" });
29 await fetch(`${servers.url}/new`, {
30 method: "POST",
31 headers: { cookie },
32 body: new URLSearchParams({ name: "proj", visibility: "private", description: "x" }),
33 redirect: "manual",
34 });
35 });
36
37 afterAll(async () => {
38 servers.stop();
39 app.close();
40 await rm(dir, { recursive: true, force: true });
41 });
42
43 const row = (html: string, key: string): string =>
44 html.match(new RegExp(`<div class="field setting-line" data-setting="${key}">([\\s\\S]*?)</div>`))?.[1] ?? "";
45 const get = async (): Promise<string> =>
46 (await fetch(`${servers.url}/olive/proj/settings`, { headers: { cookie, accept: "text/html" } })).text();
47
48 test("a changed setting shows who and when; an untouched one shows nothing", async () => {
49 const before = await get();
50 expect(before).not.toContain("data-changed");
51 const form = new URLSearchParams({ card: "gates", landing: "linear", landingShown: "1" });
52 const res = await fetch(`${servers.url}/olive/proj/settings`, {
53 method: "POST",
54 headers: { cookie, origin: servers.url },
55 body: form,
56 redirect: "manual",
57 });
58 expect(res.status).toBeLessThan(400);
59 const after = await get();
60 expect(row(after, "landing")).toMatch(/changed by olive, <time datetime="[^"]+">just now<\/time>/);
61 expect(row(after, "polishShare")).not.toContain("data-changed");
62 expect(row(after, "requireReview")).not.toContain("data-changed");
63 });
64
65 test("the phrase reads from the instant, and is empty without a change", () => {
66 const now = Date.parse("2026-01-01T12:00:00Z");
67 const out = String(changedNote({ by: "ana", at: "2026-01-01T10:00:00Z" }, now));
68 expect(out).toContain("changed by ana, ");
69 expect(out).toContain(agoWords("2026-01-01T10:00:00Z", now));
70 expect(out).toContain("2 hours ago");
71 expect(changedNote(undefined)).toBeNull();
72 });
73
74 const repoId = (): string => getRepo(app.db, "olive", "proj")!.id;
75
76 test("a changed protect setting shows the phrase on the protect row, not another", async () => {
77 const res = await fetch(`${servers.url}/olive/proj/settings`, {
78 method: "POST",
79 headers: { cookie, origin: servers.url },
80 body: new URLSearchParams({ card: "gates", protect: "on" }),
81 redirect: "manual",
82 });
83 expect(res.status).toBeLessThan(400);
84 const page = await get();
85 expect(row(page, "protect")).toContain("data-changed");
86 expect(row(page, "requireChecks")).not.toContain("data-changed");
87 expect(lastChanges(app.db, repoId()).has("protectDefault")).toBe(false);
88 });
89
90 test("the terminal door reads the same record, for an admin only", async () => {
91 const owner = getUserByName(app.db, "olive")!;
92 const repo = getRepo(app.db, "olive", "proj")!;
93 const terminal = headlessTerminal(120, 30);
94 const { app: tui, session } = createForgeApp(
95 app,
96 { sshUsername: "olive", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user: owner },
97 { terminal, exitHooks: false },
98 );
99 tui.start();
100 tui.ctx.push(settingHistoryScreen(session, tui.ctx, repo));
101 await settleApp(tui);
102 const text = tui.screen.toText();
103 expect(text).toContain("Protect the default branch: changed by olive");
104 expect(text).toContain("How a pull lands: changed by olive");
105 expect(historyLines(session, repo).some((l) => l.startsWith("Default branch"))).toBe(false);
106 expect(settingHistoryCommands(session, tui.ctx, repo).length).toBe(1);
107 expect(settingHistoryCommands({ ...session, user: undefined } as typeof session, tui.ctx, repo)).toEqual([]);
108 tui.stop?.();
109 });
110
111 test("a setting changed only before the newest 200 settings events shows nothing", () => {
112 const id = repoId();
113 app.bus.append({ kind: "repo.settings_updated", repoId: id, actorId: undefined, payload: { changed: { requireChecks: { from: false, to: true } } } });
114 expect(lastChanges(app.db, id).has("requireChecks")).toBe(true);
115 for (let i = 0; i < 200; i++)
116 app.bus.append({ kind: "repo.settings_updated", repoId: id, actorId: undefined, payload: { changed: { polishShare: { from: i, to: i + 1 } } } });
117 expect(lastChanges(app.db, id).has("requireChecks")).toBe(false);
118 expect(lastChanges(app.db, id).has("polishShare")).toBe(true);
119 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs