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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13391-the-terminal-s-changelog-opens-a-wave-to → main 5 commits fork 2 threads · 2 unresolved
4 files
changed +118
−6
docs/features/changelog.md +3 −3
| @@ -2,7 +2,7 @@ | ||
| 2 | 2 | |
| 3 | 3 | `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. |
| 4 | 4 | |
| 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`. | |
| 6 | 6 | |
| 7 | 7 | One bounded `git log` read, cached per head oid; Server-Timing names `releases` and `render`. |
| 8 | 8 | |
| @@ -26,13 +26,13 @@ A squash keeps the people behind its commits: the landed message carries every d | ||
| 26 | 26 | |
| 27 | 27 | ## For agents |
| 28 | 28 | |
| 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`. | |
| 30 | 30 | |
| 31 | 31 | ## As a feed (#8213) |
| 32 | 32 | |
| 33 | 33 | `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"`. |
| 34 | 34 | |
| 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. | |
| 36 | 36 | |
| 37 | 37 | ## Chapters (#12695) |
| 38 | 38 |
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 | ||
| 25 | 25 | |
| 26 | 26 | ## What a wave changed, in one sentence |
| 27 | 27 | |
| 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`. | |
| 29 | 29 | |
| 30 | 30 | ## A wave's size |
| 31 | 31 |
src/tui/screens/changelog.ts +11 −2
| @@ -2,7 +2,9 @@ | ||
| 2 | 2 | * The changelog, the terminal's /changelog: the same `forgeChangelog` read the |
| 3 | 3 | * page makes, for anyone, a guest included. Each release is a row: version, |
| 4 | 4 | * 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 | |
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. | |
| 6 | 8 | */ |
| 7 | 9 | |
| 8 | 10 | import { chapterOfPulls, listChapters } from "../../core/chapters.ts"; |
| @@ -20,6 +22,7 @@ import { style } from "../term/style.ts"; | ||
| 20 | 22 | import { truncate } from "../term/width.ts"; |
| 21 | 23 | import { emptyState } from "../ui/widgets.ts"; |
| 22 | 24 | import { pullScreen } from "./pull.ts"; |
| 25 | import { wavesScreen } from "./waves.ts"; | |
| 23 | 26 | import { Filter, ListState, ago, drawList, metaOf, type ListRow } from "./common.ts"; |
| 24 | 27 | |
| 25 | 28 | /** 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 { | ||
| 139 | 142 | binding(["j", "k"], "move"), |
| 140 | 143 | binding(["/"], "find"), |
| 141 | 144 | binding(["enter"], "open"), |
| 145 | binding(["w"], "by wave"), | |
| 142 | 146 | binding(["esc", "q"], "close"), |
| 143 | 147 | ], |
| 144 | 148 | async load() { |
| @@ -207,7 +211,12 @@ export function changelogScreen(f: Session, ctx: Ctx): Screen { | ||
| 207 | 211 | filter.query = ""; |
| 208 | 212 | state.clamp(lines().length); |
| 209 | 213 | } 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 |
||
| 219 | } else if (e.key === "enter") { | |
| 211 | 220 | const line = lines()[state.index]; |
| 212 | 221 | const opened = repoRef === undefined ? undefined : sourceFor(f.app, f.user, repoRef); |
| 213 | 222 | 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 | }); |
new above
offline
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.