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

A wave's page says how close it is to done: closed of total changes in one sentence and one bar, server-rendered #13450

Merged opened this

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

Merged

scout/forge:scout/13425-a-wave-s-page-says-how-close-it-is-to-do → main 7 commits fork 3 threads · 3 unresolved

  • Merged. scout/13425-a-wave-s-page-says-how-close-it-is-to-do was merged into main as 96a8a99.

Review

Sign in to review this change.
7 files changed +139 −4
docs/features/README.md +1
@@ -161,6 +161,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
161161 - [Walking a wave](wave-walk.md)
162162 - [The wave-standing line](wave-standing.md)
163163 - [How many of a wave's changes are live and waiting to ship](wave-landing.md)
164 - [How close a wave is to done](wave-landed.md)
164165 - [What a repository with no waves says and offers](wave-empty.md)
165166 - [What became of the first ask](ask-status.md)
166167 - [When a setting or a permission stands in the way](blocked-by.md)
docs/features/wave-landed.md added +11
@@ -0,0 +1,11 @@
1 # How close a wave is to done
2
3 A wave's page, the MCP wave tool and the terminal's wave screen say how many of the wave's changes landed, in one sentence: `2 of 5 changes landed.` The sentence sits on the version line; the page adds one bar under that line.
4
5 - **Landed** counts the wave's pulls that merged; the total is every pull of the wave the reader may see. A pull the reader cannot read is in neither number.
6 - A wave with no visible change says `This wave has no changes yet.` and draws no bar.
7 - One change reads `1 of 1 change landed.`
8
9 Try it: open `/trevato/forge/waves/<version>`, or the waves screen in the terminal, and read the sentence on the version line under the headline.
10
11 All doors build the sentence with `landedSentence` in `src/story/words.ts`, so they say the same words.
src/http/mcp/tools/waves.ts +3
@@ -2,6 +2,8 @@ import { pullRefs, readWave, readWaves } from "../../../story/waves.ts";
22 import { VERSION as WAVE_VERSION } from "../../../story/wave.ts";
33 import { repoDir } from "../../../git/repos.ts";
44 import { movedForViewer, waveProgress } from "../../../story/wave_moved.ts";
5 import { carriedPulls } from "../../../story/wave_pulls.ts";
6 import { landedSentence } from "../../../story/words.ts";
57 import { planNow } from "../../../story/wave_plan.ts";
68 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
79
@@ -47,6 +49,7 @@ export const tool: Tool = {
4749 version: w.version,
4850 date: w.date,
4951 headline: w.headline,
52 landed: landedSentence(carriedPulls(ctx.app.db, pullRefs(w), user)),
5053 ...(progress === "" ? {} : { progress }),
5154 highlights: w.highlights,
5255 pulls: w.pulls.flatMap((p) => {
src/story/words.ts +16
@@ -60,3 +60,19 @@ export function waveSentence(titles: readonly string[], cap = WAVE_SENTENCE_CAP)
6060 const room = cap - lead.length - 1;
6161 return `${lead}${text.length > room ? `${text.slice(0, room - 1).trimEnd()}…` : text}.`;
6262 }
63
64 /** Said when a wave carries no change the viewer can see. */
65 export const WAVE_NO_CHANGES = "This wave has no changes yet.";
66
67 /**
68 * How close a wave is to done, in one sentence: "2 of 5 changes landed." Every door says it alike.
69 */
70 export function waveLanded(landed: number, total: number): string {
71 if (total <= 0) return WAVE_NO_CHANGES;
72 return `${landed} of ${total} ${total === 1 ? "change" : "changes"} landed.`;
73 }
74
75 /** How close a wave is to done, said from the pulls the viewer may see: merged ones landed. */
76 export function landedSentence(pulls: readonly { mergedAt: string | null }[]): string {
77 return waveLanded(pulls.filter((p) => p.mergedAt !== null).length, pulls.length);
78 }
src/tui/screens/waves.ts +2 −2
@@ -16,7 +16,7 @@ import { repoBase } from "../../web/chrome.ts";
1616 import { waitingKeys } from "../../release/landings.ts";
1717 import { carriedPulls, pullPath, type CarriedPull } from "../../story/wave_pulls.ts";
1818 import { pullRefs, readWave, readWaves, sizeWords, waveLine, waveSize, type WaveEntry } from "../../story/waves.ts";
19 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts";
19 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts";
2020 import type { RepoSource } from "../../view/source.ts";
2121 import type { Ctx, Screen } from "../app/app.ts";
2222 import { binding } from "../app/keys.ts";
@@ -73,7 +73,7 @@ export function waveLines(
7373 plain(w.headline),
7474 plain(waveSentence(pulls.filter((p) => p.mergedAt !== null).map((p) => p.title))),
7575 // Sized over `pulls`, the ones this viewer may see, as the page's header is.
outdated

Hard-to-read IIFE; add a helper in words.ts taking the pulls. Also box 3 names the changelog, not this screen.

76 `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))}${standing === "" ? "" : ` ${plain(standing)}`}`,
76 `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))} ${landedSentence(pulls)}${standing === "" ? "" : ` ${plain(standing)}`}`,
7777 ...(moved.length === 0 ? [] : [plain(waveProgress(moved))]),
7878 "",
7979 "Highlights",
src/web/pages/waves.ts +7 −2
@@ -19,7 +19,7 @@ import { VERSION, type Wave } from "../../story/wave.ts";
1919 import { movedWithPulls, type MovedMilestone, shippedOf, shippedWords, waveProgress, widestMoved } from "../../story/wave_moved.ts";
2020 import { carriedPulls, pullPath } from "../../story/wave_pulls.ts";
2121 import { fromWave, pullRefs, readWave, readWaves, sizeWords, waveSize } from "../../story/waves.ts";
22 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts";
22 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts";
2323 import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts";
2424 import { escapeHtml, html, type Html } from "../html.ts";
2525 import { page } from "../layout.ts";
@@ -237,10 +237,15 @@ export async function wavePage(ctx: Ctx): Promise<Response> {
237237 )
238238 : "";
239239
240 /**
241 * The bar under the version line, named differently from the sentence beside it; none when empty.
242 */
243 const landed = carried.length === 0 ? "" : progress(carried.filter((p) => p.mergedAt !== null).length, carried.length, "Share landed");
240244 const content = entry.ok
241245 ? html`<h1>${entry.wave.headline}</h1>
242246 <p data-wave-sentence>${waveSentence(carried.filter((p) => p.mergedAt !== null).map((p) => p.title))}</p>
243 <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span> · <span data-wave-standing>${standing}</span></p>
247 <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span> · <span data-wave-landed>${landedSentence(carried)}</span> · <span data-wave-standing>${standing}</span></p>
248 ${landed}
244249 ${waveProgressRow(moved)}
outdated

Principle 1: the sentence and the bar's label are the same words, so the page says it twice. Also three sentence lines now stack above the version line. Keep one.

245250 <h2>Highlights</h2>
246251 <ul>
test/wave-landed.test.ts added +99
@@ -0,0 +1,99 @@
1 /**
2 * A wave says how close it is to done: one sentence on the line under the headline, one bar
3 * (#13425).
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 { commitToBranch, createRepo } from "../src/actions/repos.ts";
10 import { createApp, type App } from "../src/app.ts";
11 import { createSession } from "../src/core/sessions.ts";
12 import { createToken } from "../src/core/tokens.ts";
13 import { createUser } from "../src/core/users.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { landedSentence, WAVE_NO_CHANGES } from "../src/story/words.ts";
16 import type { CarriedPull } from "../src/story/wave_pulls.ts";
17 import type { WaveEntry } from "../src/story/waves.ts";
18 import { waveLines } from "../src/tui/screens/waves.ts";
19 import { quietLogs } from "./helpers/globals.ts";
20 import { mergedPull, waveNaming } from "./helpers/wave-pulls.ts";
21
22 quietLogs();
outdated

No test for the web page (sentence, bar value/max, no bar when empty) or the MCP landed field. Both are behaviour this change adds.

23
24 const pull = (n: number, mergedAt: string | null): CarriedPull => ({ owner: "o", name: "r", number: n, title: `P${n}`, mergedAt, state: mergedAt ? "closed" : "open" });
25
26 test("the sentence for 0, partial and complete waves", () => {
27 expect(landedSentence([])).toBe(WAVE_NO_CHANGES);
28 expect(landedSentence([pull(1, "2026-01-01"), pull(2, null), pull(3, null)])).toBe("1 of 3 changes landed.");
29 expect(landedSentence([pull(1, "2026-01-01")])).toBe("1 of 1 change landed.");
30 expect(landedSentence([pull(1, "x"), pull(2, "y")])).toBe("2 of 2 changes landed.");
31 });
32
33 test("the terminal wave screen carries the same sentence, on the version line", () => {
34 const entry: WaveEntry = { ok: true, file: "1.0.0.md", wave: { version: "1.0.0", date: "2026-01-01", headline: "H", highlights: [], pulls: [] } };
35 expect(waveLines(entry, [pull(1, "x"), pull(2, null)])[2]).toContain("1 of 2 changes landed.");
36 expect(waveLines(entry, [])[2]).toContain(WAVE_NO_CHANGES);
37 });
38
39 let dataDir = "";
40 let app: App;
41 let servers: Servers;
42 let cookie = "";
43 let token = "";
44
45 beforeAll(async () => {
46 dataDir = await mkdtemp(join(tmpdir(), "forge-wave-landed-"));
47 app = createApp({ dataDir, port: 0 });
48 servers = await serve(app);
49 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
50 if (!u.ok) throw new Error(String(u.error));
51 cookie = `forge_session=${createSession(app.db, u.value.id).token}; forge_mode=dev`;
52 token = createToken(app.db, u.value.id, "ro", "ro").token;
53 const made = await createRepo(app, u.value, { name: "plan", visibility: "public" });
54 if (!made.ok) throw new Error(String(made.error));
55 const repo = made.value;
56 const init = await commitToBranch(app, u.value, repo, { message: "init", files: [{ path: "README.md", content: "hi\n" }] });
57 if (!init.ok) throw new Error(JSON.stringify(init.error));
58 const one = await mergedPull(app, u.value, repo, "Done work");
59 const two = await mergedPull(app, u.value, repo, "More work");
60 app.db.query("UPDATE pull SET merged_at = NULL WHERE issue_id = (SELECT id FROM issue WHERE repo_id = ? AND number = ?)").run(repo.id, two);
61 const ref = (number: number) => ({ owner: "alice", name: "plan", number });
62 const c = await commitToBranch(app, u.value, repo, {
63 message: "waves",
64 files: [
65 { path: "waves/0.1.0.md", content: waveNaming("0.1.0", [ref(one), ref(two)]) },
66 { path: "waves/0.2.0.md", content: waveNaming("0.2.0", []) },
67 ],
68 });
69 if (!c.ok) throw new Error(JSON.stringify(c.error));
70 }, 60_000);
71
72 afterAll(async () => {
73 servers?.stop();
74 app?.close();
75 await rm(dataDir, { recursive: true, force: true });
76 });
77
78 test("the wave page says N of M once and draws one bar with that value and max", async () => {
79 const text = await (await fetch(`${servers.url}/alice/plan/waves/0.1.0`, { headers: { cookie } })).text();
80 expect(text).toContain("<span data-wave-landed>1 of 2 changes landed.</span>");
81 expect(text.split("1 of 2 changes landed.").length).toBe(2);
82 expect(text).toMatch(/<progress\s+max="2"\s+value="1"/);
83 });
84
85 test("a wave with no changes says so and draws no bar", async () => {
86 const text = await (await fetch(`${servers.url}/alice/plan/waves/0.2.0`, { headers: { cookie } })).text();
87 expect(text).toContain(`<span data-wave-landed>${WAVE_NO_CHANGES}</span>`);
88 expect(text).not.toContain("<progress");
89 });
90
91 test("the MCP wave answer carries landed", async () => {
92 const res = await fetch(`${servers.url}/mcp`, {
93 method: "POST",
94 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
95 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "waves", arguments: { repo: "alice/plan", version: "0.1.0" } } }),
96 });
97 const body = (await res.json()) as any;
98 expect(JSON.parse(body.result.content[0].text).wave.landed).toBe("1 of 2 changes landed.");
99 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs