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

A repository with no waves shows one sentence and a way to ask the crew to write the first #13434

Merged opened this

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

Merged

mason/forge:mason/13408-a-repository-with-no-waves-shows-one-sen → main 6 commits fork 2 threads · 2 unresolved

  • Merged. mason/13408-a-repository-with-no-waves-shows-one-sen was merged into main as f1f64de.

Review

Sign in to review this change.
8 files changed +157 −30
docs/features/README.md +1
@@ -156,6 +156,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
156156 - [Walking a wave](wave-walk.md)
157157 - [The wave-standing line](wave-standing.md)
158158 - [How many of a wave's changes are live and waiting to ship](wave-landing.md)
159 - [What a repository with no waves says and offers](wave-empty.md)
159160 - [What became of the first ask](ask-status.md)
160161 - [When a setting or a permission stands in the way](blocked-by.md)
161162 - [The map's growth line](map-growth.md)
docs/features/wave-empty.md added +15
@@ -0,0 +1,15 @@
1 # Waves: a repository with no waves
2
3 A repository with no waves says one sentence and offers one tell, "write the first wave", instead of an empty list.
4
5 - The web page `/<owner>/<name>/waves` shows the sentence and a Tell the crew button that opens the tell with that text.

The web page no longer offers 'Cut a wave' on an empty repository. Say here where an admin cuts the first wave on the web (Settings) and in the terminal (c).

6 - The terminal's waves screen shows the same sentence and the same tell.
7
8 Both doors take the words from `src/story/words.ts`, so they say the same thing.
9
10 The empty page does not offer "Cut a wave". Where a person cuts the first wave:
11
12 - On the web, an admin uses the form on the repository's Settings page.
13 - In the terminal, `c` on the waves screen.
14
15 The tell is shown only to someone who may direct the crew here; a reader sees the sentence alone, on both doors, and `t` in the terminal does nothing for them.
src/story/words.ts +6 −2
@@ -7,8 +7,12 @@
77
88 import type { DeciderPile } from "../core/decisions.ts";
99
10 /** A repository's waves, empty because there is no `waves/` to read. */
11 export const NO_WAVES = "This repository has no waves/ directory.";
10 /** A repository with no waves: one sentence, said the same on the page and in the terminal. */
11 export const NO_WAVES = "Nothing has been written up yet. Ask the crew to write the first wave.";
12
13 /** What the one button tells the crew, and what it is called. */
14 export const FIRST_WAVE_TELL = "write the first wave";
15 export const FIRST_WAVE_BUTTON = "Tell the crew";
1216
1317 /**
1418 * "The decider closed 4, deferred 2, asked you about 1." as its parts, each
src/tui/screens/waves.ts +24 −7
@@ -7,6 +7,7 @@
77
88 import { cutWaveFor, planCutFor } from "../../actions/cut_wave.ts";
99 import { canRead, getRepo } from "../../core/repos.ts";
10 import { mayDirectCrew } from "../../crew/direct.ts";
1011 import { nearMilestones, standingLine } from "../../web/pages/milestones_near.ts";
1112 import { VERSION } from "../../story/wave.ts";
1213 import { movedWithPulls, shippedOf, shippedWords, waveProgress, type MovedMilestone } from "../../story/wave_moved.ts";
@@ -15,7 +16,7 @@ import { repoBase } from "../../web/chrome.ts";
1516 import { waitingKeys } from "../../release/landings.ts";
1617 import { carriedPulls, pullPath, type CarriedPull } from "../../story/wave_pulls.ts";
1718 import { pullRefs, readWave, readWaves, sizeWords, waveLine, waveSize, type WaveEntry } from "../../story/waves.ts";
18 import { NO_WAVES, waveSentence } from "../../story/words.ts";
19 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts";
1920 import type { RepoSource } from "../../view/source.ts";
2021 import type { Ctx, Screen } from "../app/app.ts";
2122 import { binding } from "../app/keys.ts";
@@ -26,6 +27,7 @@ import { emptyState } from "../ui/widgets.ts";
2627 import type { Session } from "../session.ts";
2728 import { ListState, Scroll, confirmScreen, drawList, drawLines, hitList, plural, runAsync, yesNo } from "./common.ts";
2829 import { pullScreen } from "./pull.ts";
outdated

Move these two imports into the existing order. Then add a terminal test for the viewer who may not direct the crew: no action shown, and t creates no issue.

30 import { tellHereNow } from "./tell_here.ts";
2931 import { local, localRepo, sourceName, whereRows, whereStrip } from "./where.ts";
3032
3133 /**
@@ -275,14 +277,24 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
275277 });
276278 };
277279
280 /**
281 * Whether the empty screen offers the one tell: loaded, nothing to read, and this viewer directs
282 * the crew here.
283 */
284 const askable = (): boolean =>
285 loaded && entries.length === 0 && repo !== undefined && f.user !== undefined && canRead(f.db, repo, f.user) && mayDirectCrew(f.db, repo, f.user);
286
278287 const self: Screen = {
279288 title: "Waves",
280 keys: [
281 binding(["j", "k"], "move"),
282 binding(["enter"], "open"),
283 binding(["c"], "cut a wave"),
284 binding(["r"], "refresh"),
285 ],
289 get keys() {
290 return [
291 binding(["j", "k"], "move"),
292 binding(["enter"], "open"),
293 binding(["c"], "cut a wave"),
294 ...(askable() ? [binding(["t"], "tell the crew to write the first wave")] : []),
295 binding(["r"], "refresh"),
296 ];
297 },
286298 load: reload,
287299 render(area, s) {
288300 const c = ctx.theme.c;
@@ -310,6 +322,7 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
310322 : repo === undefined
311323 ? "Waves are only read on this forge."
312324 : NO_WAVES,
325 ...(askable() ? { action: `${FIRST_WAVE_BUTTON} (t)` } : {}),
313326 });
314327 return;
315328 }
@@ -327,6 +340,10 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
327340 runAsync(ctx, reload);
328341 return true;
329342 }
343 if (e.key === "t" && askable()) {
344 runAsync(ctx, () => tellHereNow(f, ctx, { repo: repo! }, FIRST_WAVE_TELL));
345 return true;
346 }
330347 if (e.key === "c") {
331348 cut();
332349 return true;
src/web/pages/waves.ts +9 −9
@@ -6,7 +6,8 @@
66 * it does for any other page of a private repository.
77 */
88
9 import { canAdmin, canRead, getRepo } from "../../core/repos.ts";
9 import { canRead, getRepo } from "../../core/repos.ts";
10 import { mayDirectCrew } from "../../crew/direct.ts";
1011 import { notFound } from "../../http/respond.ts";
1112 import { waitingKeys } from "../../release/landings.ts";
1213 import { holds, stamp, xml } from "../feeds.ts";
@@ -18,7 +19,7 @@ import { VERSION, type Wave } from "../../story/wave.ts";
1819 import { movedWithPulls, shippedOf, shippedWords, waveProgress } from "../../story/wave_moved.ts";
1920 import { carriedPulls, pullPath } from "../../story/wave_pulls.ts";
2021 import { fromWave, pullRefs, readWave, readWaves, sizeWords, waveSize } from "../../story/waves.ts";
21 import { NO_WAVES, waveSentence } from "../../story/words.ts";
22 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts";
2223 import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts";
2324 import { escapeHtml, html } from "../html.ts";
2425 import { page } from "../layout.ts";
@@ -36,9 +37,6 @@ export const WAVES_CSS = `[data-waves] { overflow-wrap: anywhere; }
3637 [data-waves] .row-title, [data-waves] .row-meta { white-space: normal; overflow: visible; text-overflow: clip; }
3738 [data-waves] .row { align-items: flex-start; }`;
3839
39 const WHAT_A_WAVE =
40 "A wave is a release note in waves/<version>.md that names its highlights and the pulls merged since the last one.";
41
4240 /**
4341 * One wave on the list: its headline, the first highlight's why as the one sentence under it, and
4442 * version, date and pull count as a muted trail.
@@ -90,11 +88,13 @@ export async function wavesPage(ctx: Ctx): Promise<Response> {
9088 ${entries.length === 0
9189 ? empty({
9290 title: "No waves yet",
93 note: `${WHAT_A_WAVE} ${NO_WAVES}`,
94 ...(canAdmin(ctx.app.db, repo, ctx.auth.user)
91 note: NO_WAVES,
92 ...(mayDirectCrew(ctx.app.db, repo, ctx.auth.user)
9593 ? {
96 action: html`<form method="post" action="${repoBase(repo)}/settings/wave">
97 ${btn("Cut a wave", { variant: "primary" })}
94 action: html`<form method="post" action="${repoBase(repo)}/tell">
95 <input type="hidden" name="text" value="${FIRST_WAVE_TELL}" />
96 <input type="hidden" name="from" value="${repoBase(repo)}/waves" />
97 ${btn(FIRST_WAVE_BUTTON, { variant: "primary" })}
9898 </form>`,
9999 }
100100 : {}),
test/story-words.test.ts +1 −1
@@ -19,7 +19,7 @@ const SAYERS = [
1919 ];
2020
2121 test("the sentences read as they always have", () => {
22 expect(NO_WAVES).toBe("This repository has no waves/ directory.");
22 expect(NO_WAVES).toBe("Nothing has been written up yet. Ask the crew to write the first wave.");
2323 const n = { closed: 4, deferred: 2, asked: 1 };
2424 expect(deciderSentence((p) => n[p]).join("")).toBe(
2525 "The decider closed 4, deferred 2, asked you about 1.",
test/wave-empty.test.ts added +101
@@ -0,0 +1,101 @@
1 /**
2 * A repository with no waves invites: one sentence and one tell, 'write the first wave', on both
3 * doors.
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 type { Repo } from "../src/core/repos.ts";
12 import { createSession } from "../src/core/sessions.ts";
13 import { createUser, type User } from "../src/core/users.ts";
14 import { serve, type Servers } from "../src/http/server.ts";
15 import { FIRST_WAVE_TELL, NO_WAVES } from "../src/story/words.ts";
16 import { createForgeApp } from "../src/tui/forge.ts";
17 import { wavesScreen } from "../src/tui/screens/waves.ts";
18 import { local } from "../src/tui/screens/where.ts";
19 import { headlessTerminal } from "../src/tui/term/terminal.ts";
20 import { quietLogs } from "./helpers/globals.ts";
21 import { settleApp } from "./helpers/tui.ts";
22
23 quietLogs();
24
25 let dir = "";
26 let app: App;
27 let servers: Servers;
28 let alice: User;
29 let bare: Repo;
30 let cookie = "";
31
32 const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
33 if (!r.ok) throw new Error(JSON.stringify(r.error));
34 return r.value;
35 };
36
37 beforeAll(async () => {
38 dir = await mkdtemp(join(tmpdir(), "forge-wave-empty-"));
39 app = createApp({ dataDir: dir, port: 0 });
40 servers = await serve(app);
41 alice = ok(await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }));
42 cookie = `forge_session=${createSession(app.db, alice.id).token}`;
43 bare = ok(await createRepo(app, alice, { name: "bare", visibility: "public" }));
44 ok(await commitToBranch(app, alice, bare, { message: "init", files: [{ path: "README.md", content: "hi\n" }] }));
45 });
46 afterAll(async () => {
47 app.close();
48 await rm(dir, { recursive: true, force: true });
49 });
50
51 test("web: no waves says one sentence and one tell prefilled 'write the first wave'", async () => {
52 const body = await (await fetch(`${servers.url}/alice/bare/waves`, { headers: { cookie } })).text();
53 expect(body).toContain(NO_WAVES);
54 expect(body).toContain('action="/alice/bare/tell"');
55 expect(body).toContain(`name="text" value="${FIRST_WAVE_TELL}"`);
56 expect(body.match(/action="\/alice\/bare\/tell"/g)?.length).toBe(1);
57 });
58
59 test("web: a reader who cannot direct the crew sees the sentence and no button", async () => {
60 const body = await (await fetch(`${servers.url}/alice/bare/waves`)).text();
61 expect(body).toContain(NO_WAVES);
62 expect(body).not.toContain('action="/alice/bare/tell"');
63 });
64
65 test("terminal: the same sentence, and t sends the same tell through the tell action", async () => {
66 const terminal = headlessTerminal(120, 40);
67 const { app: tui, session } = createForgeApp(app, { sshUsername: "alice", remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user: alice }, { terminal, exitHooks: false });
68 tui.start();
69 await settleApp(tui);
70 tui.push(wavesScreen(session, tui.ctx, local(session, bare)));
71 await settleApp(tui);
72 const text = tui.screen.toText();
73 expect(text).toContain("No waves yet");
74 expect(text).toContain("Nothing has been written up yet.");
75 expect(text).toContain("Tell the crew");
76 const before = app.db.query<{ n: number }, []>("SELECT count(*) AS n FROM issue").get()!.n;
77 terminal.feed("t");
78 await settleApp(tui);
79 const row = app.db.query<{ n: number; title: string }, []>("SELECT count(*) AS n, max(title) AS title FROM issue").get()!;
80 expect(row.n).toBe(before + 1);
81 expect(row.title).toContain(FIRST_WAVE_TELL);
82 tui.stop();
83 });
84
85 test("terminal: a read-only user sees the sentence, no Tell the crew action, and t creates no issue", async () => {
86 const bob = ok(await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" }));
87 const terminal = headlessTerminal(120, 40);
88 const { app: tui, session } = createForgeApp(app, { sshUsername: "bob", remoteAddress: "127.0.0.1", fingerprint: "SHA256:b", user: bob }, { terminal, exitHooks: false });
89 tui.start();
90 await settleApp(tui);
91 tui.push(wavesScreen(session, tui.ctx, local(session, bare)));
92 await settleApp(tui);
93 const text = tui.screen.toText();
94 expect(text).toContain("Nothing has been written up yet.");
95 expect(text).not.toContain("Tell the crew");
96 const before = app.db.query<{ n: number }, []>("SELECT count(*) AS n FROM issue").get()!.n;
97 terminal.feed("t");
98 await settleApp(tui);
99 expect(app.db.query<{ n: number }, []>("SELECT count(*) AS n FROM issue").get()!.n).toBe(before);
100 tui.stop();
101 });
test/waves-page.test.ts −11
@@ -152,17 +152,6 @@ describe("waves page", () => {
152152 expect(await res.text()).toContain("No waves yet");
153153 });
154154
155 test("the empty state says what a wave is; an admin gets Cut a wave, a reader does not", async () => {
156 const admin = await (await get("/alice/bare/waves")).text();
157 expect(admin).toContain("A wave is a release note");
158 expect(admin).toContain('action="/alice/bare/settings/wave"');
159 expect(admin).toContain("Cut a wave");
160 const reader = await (await get("/alice/bare/waves", false)).text();
161 expect(reader).toContain("A wave is a release note");
162 expect(reader).not.toContain("Cut a wave");
163 expect(reader).not.toContain("/settings/wave");
164 });
165
166155 test("the waves pages mark no tab as current", async () => {
167156 for (const path of ["/alice/pub/waves", "/alice/bare/waves", "/alice/pub/waves/0.10.0"]) {
168157 const body = await (await get(path)).text();

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs