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

The terminal's changelog opens a wave to its changes and then a change to its pull #13420

Merged opened this

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

Merged

scout/forge:scout/13391-the-terminal-s-changelog-opens-a-wave-to → main 5 commits fork 2 threads · 2 unresolved

  • Merged. scout/13391-the-terminal-s-changelog-opens-a-wave-to was merged into main as 42b3e7a.

Review

Sign in to review this change.
4 files changed +118 −6
docs/features/changelog.md +3 −3
@@ -2,7 +2,7 @@
22
33 `GET /changelog` is public. It lists the last 30 `Release <version>: …` commits on the default branch of the forge's own repository (`FORGE_REPO`), newest first. Each has a heading anchored `#<version>`, its date, and one link per pull named in the subject (`title (#N);title (#N)`). When `FORGE_REPO` is unset or its repository is private, the page answers 200 with "No releases yet". The footer links to it.
44
5 The terminal's palette has `Changelog`, the same read for anyone, a guest included. `/` takes a word and keeps only releases whose version or carried pull titles contain it, ignoring case; the header says how many match, and `esc` clears it. Enter on a release lists its pulls (`#N title`); a release whose subject names none shows "No pulls". Enter on a pull opens it, as Enter does on any pull.
5 The terminal's palette has `Changelog`, the same read for anyone, a guest included. `/` takes a word and keeps only releases whose version or carried pull titles contain it, ignoring case; the header says how many match, and `esc` clears it. Enter on a release lists its pulls (`#N title`); a release whose subject names none shows "No pulls". Enter on a pull opens it, as Enter does on any pull. `w` reads the changelog by wave, as the page's "Read it by wave" link does: Enter on a wave opens its changes, Enter on a change opens its pull, and `esc` goes back to the row you left. It goes through `sourceFor`, so a repository the reader may not open stays closed. Tested in `test/tui-changelog-waves.test.ts`.
66
77 One bounded `git log` read, cached per head oid; Server-Timing names `releases` and `render`.
88
@@ -26,13 +26,13 @@ A squash keeps the people behind its commits: the landed message carries every d
2626
2727 ## For agents
2828
29 `GET /api/v1/changelog` is the page's list as JSON, public, cached five seconds: `{version, commit, live, onItsWay}`, each landing `{repo, number, title, at, live[, with]}`. `?repo=all` or `?repo=owner/name` filters; the default is the forge's own repository, as on the page. MCP `releases` with `{shipped: true, repo?}` and `GET /api/v1/releases?shipped=true[&repo=]` answer the same rows with the same default. Only public repositories are read; concurrent requests share one read of git and the merged rows, so an anonymous caller costs no more than a page view. The page links the JSON with `rel="alternate"`. The terminal's Changelog screen is the release-commit view (`release/changelog.ts`), told in chapters when there are any (see Chapters).
29 `GET /api/v1/changelog` is the page's list as JSON, public, cached five seconds: `{version, commit, live, onItsWay}`, each landing `{repo, number, title, at, live[, with]}`. `?repo=all` or `?repo=owner/name` filters; the default is the forge's own repository, as on the page. MCP `releases` with `{shipped: true, repo?}` and `GET /api/v1/releases?shipped=true[&repo=]` answer the same rows with the same default. Only public repositories are read; concurrent requests share one read of git and the merged rows, so an anonymous caller costs no more than a page view. The page links the JSON with `rel="alternate"`. The terminal's Changelog screen is the release-commit view (`release/changelog.ts`), told in chapters when there are any (see Chapters), and it reads by wave on `w`.
3030
3131 ## As a feed (#8213)
3232
3333 `GET /changelog.atom` is the same list as an Atom feed, public, for a feed reader. It holds the newest 20 live landings of the forge's own repository (`FORGE_REPO`, public only), newest first, one entry each titled `Went live: <title>` with a one-sentence summary (`Landed in <repo> as pull #<n> on <date> and is live.`) and linked to that release's row on the page, `/changelog?release=release-<owner>-<name>-<n>#release-<owner>-<name>-<n>` (the row's `id`, from `release/anchor.ts`). The `release=` part opens a gathered line that holds the row, so the link lands on a row you can see without any script. what has landed but is not yet live is left out. A landing a wave covers collapses into one entry per wave (not per release or per landing): the wave's headline is the title, its highlights the summary, the link goes to the wave's page, and the entry is dated at the wave's newest landing. Waves are read from the forge repository's default branch, so the `ETag` moves with that branch's tip as well as with the list. The tip is read on every request, the 304 path included; the five-minute cache is what keeps git off the hot path. The 20 is the feed's own cap (`CHANGELOG_ENTRIES` in `web/feeds.ts`); the page and `/api/v1/changelog` are not capped. It is cached for five minutes (`cache-control: public, max-age=300`) and carries a weak `ETag`, so a reader that sends `If-None-Match` gets a 304. The page links it with `rel="alternate"`.
3434
35 An agent reads the same data as JSON, not Atom: MCP `releases` with `{shipped: true}` or `GET /api/v1/changelog` (see above). The terminal has no screen for the feed, since a feed is for a reader program; its Changelog screen is the release-commit view.
35 An agent reads the same data as JSON, not Atom: MCP `releases` with `{shipped: true}` or `GET /api/v1/changelog` (see above). The terminal has no screen for the feed, since a feed is for a reader program; its Changelog screen is the release-commit view, with `w` for the waves.
3636
3737 ## Chapters (#12695)
3838
docs/features/wave-walk.md +1 −1
@@ -25,7 +25,7 @@ Only pulls the viewer may read are listed, and Enter re-checks that before openi
2525
2626 ## What a wave changed, in one sentence
2727
28 Under the headline a wave says in one plain sentence what landed, from the titles of its merged pulls the viewer may read: `This wave landed Add search, Fix the nav and 3 more.`, or `No pull in this wave has landed yet.` It is built from titles alone (no model), capped at 160 characters, escaped on the page and stripped of control characters in the terminal. The changelog links on to the forge's waves ("Read it by wave"). Tested in `test/wave-sentence.test.ts`, `test/wave-pulls.test.ts`, `test/tui-waves.test.ts` and `test/changelog.test.ts`.
28 Under the headline a wave says in one plain sentence what landed, from the titles of its merged pulls the viewer may read: `This wave landed Add search, Fix the nav and 3 more.`, or `No pull in this wave has landed yet.` It is built from titles alone (no model), capped at 160 characters, escaped on the page and stripped of control characters in the terminal. The changelog links on to the forge's waves ("Read it by wave"); in the terminal, `w` on the Changelog screen opens the same waves, then a wave's changes, then a change's pull, and `esc` returns to the changelog row. Tested in `test/wave-sentence.test.ts`, `test/wave-pulls.test.ts`, `test/tui-waves.test.ts` and `test/changelog.test.ts`.
2929
3030 ## A wave's size
3131
src/tui/screens/changelog.ts +11 −2
@@ -2,7 +2,9 @@
22 * The changelog, the terminal's /changelog: the same `forgeChangelog` read the
33 * page makes, for anyone, a guest included. Each release is a row: version,
44 * date and the pulls it carried. `/` narrows them by a word of the version or a
5 * pull title; Enter lists a release's pulls, and Enter on a pull opens it.
5 * pull title; Enter lists a release's pulls, and Enter on a pull opens it. `w` reads it by wave, as

The header paragraph now breaks mid-sentence; reflow it as one paragraph. The other comment rewraps in this file are unrelated to the issue; revert them.

Header comment wraps at about 100 columns while its neighbours wrap near 80; reflow it to match.

6 * the page's link does: Enter on a wave opens its changes, Enter on a change opens its pull, and
7 * Esc returns to the same row.
68 */
79
810 import { chapterOfPulls, listChapters } from "../../core/chapters.ts";
@@ -20,6 +22,7 @@ import { style } from "../term/style.ts";
2022 import { truncate } from "../term/width.ts";
2123 import { emptyState } from "../ui/widgets.ts";
2224 import { pullScreen } from "./pull.ts";
25 import { wavesScreen } from "./waves.ts";
2326 import { Filter, ListState, ago, drawList, metaOf, type ListRow } from "./common.ts";
2427
2528 /** Whether a release's version or any pull it carried names the word. */
@@ -139,6 +142,7 @@ export function changelogScreen(f: Session, ctx: Ctx): Screen {
139142 binding(["j", "k"], "move"),
140143 binding(["/"], "find"),
141144 binding(["enter"], "open"),
145 binding(["w"], "by wave"),
142146 binding(["esc", "q"], "close"),
143147 ],
144148 async load() {
@@ -207,7 +211,12 @@ export function changelogScreen(f: Session, ctx: Ctx): Screen {
207211 filter.query = "";
208212 state.clamp(lines().length);
209213 } else if (e.key === "esc" || e.key === "q") ctx.pop();
210 else if (e.key === "enter") {
214 else if (e.key === "w") {
215 // The page's "Read it by wave": waves → a wave's changes → a change's pull, the same gate
216 // as a pull.
217 const opened = repoRef === undefined ? undefined : sourceFor(f.app, f.user, repoRef);
218 if (opened?.ok) ctx.push(wavesScreen(f, ctx, opened.value));

When opened is not ok, w does nothing and gives no word why. A one-line notice such as "No waves to read here" would help a keyboard user who thinks the key is broken.

219 } else if (e.key === "enter") {
211220 const line = lines()[state.index];
212221 const opened = repoRef === undefined ? undefined : sourceFor(f.app, f.user, repoRef);
213222 if (line?.entry !== undefined && repoRef !== undefined) ctx.push(releasePulls(f, ctx, repoRef, line.entry, credits));
test/tui-changelog-waves.test.ts added +103
@@ -0,0 +1,103 @@
1 /**
2 * The changelog's `w` reads by wave: wave → its changes → a change's pull, and Esc returns to the
3 * same row.
4 */
5 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { openPull } from "../src/actions/pulls.ts";
10 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
11 import { createApp, type App } from "../src/app.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { createForgeApp } from "../src/tui/forge.ts";
14 import { changelogScreen } from "../src/tui/screens/changelog.ts";
15 import { writeWave, type Wave } from "../src/story/wave.ts";
16 import { headlessTerminal } from "../src/tui/term/terminal.ts";
17 import { quietLogs } from "./helpers/globals.ts";
18 import { settleApp, settleUntil } from "./helpers/tui.ts";
19
20 quietLogs();
21
22 let dir: string;
23 let app: App;
24 const guest = { sshUsername: "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test" };
25
26 beforeAll(async () => {
27 dir = await mkdtemp(join(tmpdir(), "forge-tui-changelog-waves-"));
28 app = createApp({ dataDir: dir, port: 0 });
29 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
30 if (!made.ok) throw new Error(made.error);
31 const repo = await createRepo(app, made.value, { name: "forge", visibility: "public" });
32 if (!repo.ok) throw new Error(JSON.stringify(repo.error));
33 app.config.forgeRepo = "alice/forge";
34 const wave: Wave = {
35 version: "0.2.0",
36 date: "2026-10-01",
37 headline: "Waves in the terminal",
38 highlights: [1, 2, 3].map((n) => ({ title: `Thing ${n}`, why: "because" })),
39 pulls: [{ title: "#1 Newer thing", url: "https://forge.example/alice/forge/pulls/1" }],
40 };
41 const text = writeWave(wave);
42 if (!text.ok) throw text.error;
43 const done = await commitToBranch(app, made.value, repo.value, { message: "Release 0.2.0: Waves (#1)", files: [{ path: "waves/0.2.0.md", content: text.value }] });
44 if (!done.ok) throw new Error(JSON.stringify(done.error));
45 const b = await commitToBranch(app, made.value, repo.value, { message: "Newer thing", branch: "p1", files: [{ path: "p.txt", content: "1\n" }] });
46 if (!b.ok) throw new Error(JSON.stringify(b.error));
47 const pull = await openPull(app, made.value, repo.value, { title: "Newer thing", baseBranch: repo.value.defaultBranch, headBranch: "p1" });
48 if (!pull.ok) throw new Error(JSON.stringify(pull.error));
49 }, 60_000);
50
51 afterAll(async () => {
52 app.close();
53 await rm(dir, { recursive: true, force: true });
54 });
55
56 test("w opens the waves, Enter a wave's changes, Enter a change's pull; Esc walks back", async () => {
57 const terminal = headlessTerminal(120, 30);
58 const { app: tui, session } = createForgeApp(app, guest, { terminal, exitHooks: false });
59 tui.start();
60 tui.ctx.push(changelogScreen(session, tui.ctx));
61 await settleApp(tui);
62 const list = tui.screen.toText();
63 const step = async (k: string): Promise<string> => {
64 terminal.feed(k);
65 if (k === "\x1b") await new Promise((r) => setTimeout(r, 60)); // real-timer: the terminal holds a lone Esc 25 ms (ESC_MS) to tell it from Alt; only the clock releases it
66 await settleApp(tui);
67 return tui.screen.toText();
68 };
69 const waves = await step("w");
70 expect(waves).toContain("Waves in the terminal");
71 expect(waves).toContain("1 change in 1 app");
72 const wave = await step("\r");
73 expect(wave).toContain("Pulls");
74 expect(wave).toContain("#1 Newer thing");
75 const pull = await step("\r");
76 expect(pull).toContain("Changelog › Waves › 0.2.0 › #1");
77 await settleUntil(tui, "Newer thing");
78 const head = (t: string): string => t.split("\n")[1] ?? "";
79 expect(head(await step("\x1b"))).toBe("Guest › Changelog › Waves › 0.2.0");
80 expect(head(await step("\x1b"))).toBe("Guest › Changelog › Waves");
81 const back = await step("\x1b");
82 tui.stop?.();
83 expect(back).toBe(list);
84 });
85
86 test("a private forge repository gives the terminal no waves", async () => {
87 app.db.run("UPDATE repo SET visibility = 'private' WHERE name = 'forge'");
88 try {
89 const terminal = headlessTerminal(120, 30);
90 const { app: tui, session } = createForgeApp(app, guest, { terminal, exitHooks: false });
91 tui.start();
92 tui.ctx.push(changelogScreen(session, tui.ctx));
93 await settleApp(tui);
94 terminal.feed("w");
95 await settleApp(tui);
96 const text = tui.screen.toText();
97 tui.stop?.();
98 expect(text).not.toContain("Waves in the terminal");
99 expect(text).toContain("No releases yet");
100 } finally {
101 app.db.run("UPDATE repo SET visibility = 'public' WHERE name = 'forge'");
102 }
103 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs