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

The home's milestone strip shows the open chapter's progress bar with a count and the next item #14112

Merged opened this

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

Merged

torque/forge:torque/14070-the-home-s-milestone-strip-shows-the-ope → main 7 commits fork 4 threads · 4 unresolved

  • Merged. torque/14070-the-home-s-milestone-strip-shows-the-ope was merged into main as b502512.

Review

Sign in to review this change.
9 files changed +240 −2
docs/design/areas/changelog.md +4
@@ -20,3 +20,7 @@ Each day is a `<section data-day>` with an `<h2>` (the day, the UTC mark when th
2020 ## Chapters on the changelog (#11868)
2121
2222 A closed chapter is one `row()` in a `list setting-list` (its name as the title, the closing note's first sentence in plain words as the meta, `Means` and `Pulls` as the row's `facts` dl, the close date as the trail), followed by the pulls under the same day headings as everywhere else. The closing note is never shown as raw markdown: `noteWords` drops the headings and marks and keeps one sentence. No new class; `test/changelog-chapters.test.ts` holds it.
23
24 ## The chapter bar on the home (#14070)
25
26 One `row()` in a `list setting-list` under the door's hero: "v2: 12 of 19" as the title, linking the open chapter, and the next unfinished item as the meta, in full so it wraps. Absent with no open chapter or an unreadable repository. No new class: the row already has the tap target and focus ring, and a hand-rolled line did not. `test/home-chapter-bar.test.ts` holds it.
docs/features/README.md +1
@@ -133,6 +133,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
133133 - [Bets](bets.md)
134134 - [Bugs on a clock](bugs.md)
135135 - [Chapters: a version with an end](chapters.md)
136 - [The open chapter's bar on the home](chapter-bar.md)
136137 - [Each app with its crew member](app-crew.md)
137138 - [The app's page: detail on demand](app-page-details.md)
138139 - [Estimates](estimates.md)
docs/features/chapter-bar.md added +12
@@ -0,0 +1,12 @@
1 # The chapter bar
2
3 The home shows one row under the hero for the open chapter: how far it is ("v2: 12 of 19") and the next unfinished
4 item ("next: #7 Title"). The row links the chapter's page. With no open chapter, or a repository the reader may not open,
5 there is no row.
6
7 Try it: open `/` while a chapter is open.
8
9 The terminal (both doors): the app's Chapters screen (palette: "<owner>/<app> — Chapters", `src/tui/screens/chapters.ts`)
10 starts with the same line, from the same `barCount`/`barNext` in `src/core/chapters.ts`.
11
12 Pinned by `test/home-chapter-bar.test.ts`; design note in `docs/design/areas/changelog.md`.
src/core/chapters.ts +27
@@ -484,3 +484,30 @@ export function chapterOfPulls(db: Database, repoId: string): Map<number, string
484484 }
485485 return out;
486486 }
487
488 /** The open chapter at a glance: its name, how far, and the first item not yet done. */
489 export interface Bar {
490 readonly chapter: Chapter;
491 readonly done: number;
492 readonly total: number;
493 readonly next: Item | null;
494 }
495
496 /** "v2: 12 of 19": how far the open chapter is, in the words the page and the terminal share. */
497 export const barCount = (bar: Bar): string => `${bar.chapter.name}: ${bar.done} of ${bar.total}`;
498
499 /** "next: #7 Title", or "" when every item is done. */
500 export const barNext = (bar: Bar): string => (bar.next === null ? "" : `next: #${bar.next.number} ${bar.next.title}`);
501
502 /**
503 * The bar for a repository; null when no chapter is open. The next item is the lowest-numbered
504 * one not done.
outdated

This long one-liner is hard to read; split it. Its branches (some done, all done, next null) are untested.

505 */
506 export function barOf(db: Database, repoId: string): Bar | null {
507 const chapter = openChapterOf(db, repoId);
508 if (chapter === undefined) return null;
509 const items = itemsOf(db, chapter);
510 const done = items.filter((i) => i.status === "done").length;
511 const next = items.find((i) => i.status !== "done") ?? null;
512 return { chapter, done, total: items.length, next };
513 }
src/tui/screens/chapters.ts +5 −2
@@ -10,7 +10,7 @@
1010 */
1111
1212 import { CHAPTER_WORDS, close, draft, fill, open, patch, reopen, refusalWords, undoableClose } from "../../actions/chapters.ts";
13 import { costSentence, getChapter, nextChapterOf, nextWords, itemsOf, listChapters, progressOf, progressSentence, type Chapter, type Item } from "../../core/chapters.ts";
13 import { barCount, barNext, barOf, costSentence, getChapter, nextChapterOf, nextWords, itemsOf, listChapters, progressOf, progressSentence, type Chapter, type Item } from "../../core/chapters.ts";
1414 import { canAdmin, type Repo } from "../../core/repos.ts";
1515 import type { Ctx, Screen } from "../app/app.ts";
1616 import type { Command } from "../app/palette.ts";
@@ -186,7 +186,10 @@ export function chaptersScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
186186 render(area, s) {
187187 const c = ctx.theme.c;
188188 const chapters = all();
189 const [head, list] = split(area, "v", [len(1), fillSpace(1)]);
189 const bar = barOf(f.app.db, repo.id);
190 const [barArea, head, list] = split(area, "v", [len(bar === null ? 0 : 1), len(1), fillSpace(1)]);
191 // The home's bar, the same words: the open chapter's count and its next item.
192 if (bar !== null) s.text(barArea!.x, barArea!.y, truncate(`${barCount(bar)} ${barNext(bar)}`.trim(), barArea!.w), style(c.fg, c.bg), barArea!.x + barArea!.w);
190193 s.text(
191194 head!.x,
192195 head!.y,
src/web/studio/chapter_bar.ts added +30
@@ -0,0 +1,30 @@
1 /**
2 * The home's chapter bar (#14070): one line, "v2: 12 of 19", with the next unfinished item's title.
3 * Read from `core/chapters.ts`, the same count the chapters page prints; absent with no open
4 * chapter or a repository the reader may not open. One `row()`: the count is the title and links
5 * the chapter, the next item is the meta, in full so it wraps rather than cuts.
6 */
7 import type { App } from "../../app.ts";
8 import { barCount, barNext, barOf } from "../../core/chapters.ts";
9 import { canRead, getRepo } from "../../core/repos.ts";
10 import type { User } from "../../core/users.ts";
11 import { repoBase } from "../chrome.ts";
12 import { html, type Html } from "../html.ts";
13 import { row } from "../ui.ts";
14 import { appReuse } from "./app_cache.ts";
15
16 export function chapterBar(app: App, user: User | undefined): Html | null {
17 const [owner = "", name = ""] = (app.config.forgeRepo ?? "").split("/");
18 if (owner === "" || name === "") return null;
19 const repo = getRepo(app.db, owner, name);
20 if (repo === undefined || !canRead(app.db, repo, user)) return null;
21 const bar = appReuse(app.db, `chapter-bar:${repo.id}`, () => barOf(app.db, repo.id));
22 if (bar === null) return null;
23 return html`<ul class="list setting-list door-section">${row({
outdated

Principle 7 and the design system: this is hand-rolled markup for a fact line. Use the named row/meta component. Also no terminal counterpart exists (both doors) and no docs/features/ how-to.

24 nav: true,
25 href: `${repoBase(repo)}/chapters/${encodeURIComponent(bar.chapter.name)}`,
26 title: barCount(bar),
27 ...(bar.next === null ? {} : { meta: html`${barNext(bar)}` }),
28 data: { "chapter-bar": "" },
29 })}</ul>`;
30 }
src/web/studio/home.ts +2
@@ -43,6 +43,7 @@ import { SITE_WHAT } from "../site_line.ts";
4343 import { siteStructuredData } from "../structured_data.ts";
4444 import { running } from "../../kernel/version.ts";
4545 import { biggestMilestones, homeMilestones } from "./milestone_lines.ts";
46 import { chapterBar } from "./chapter_bar.ts";
4647 import { isQuiet, quietLine } from "./home_empty.ts";
4748 import { liveClientJs } from "../live.ts";
4849 import {
@@ -826,6 +827,7 @@ export function studioDoor(ctx: Ctx): Response {
826827 </ul>
827828 </section>
828829
830 ${chapterBar(ctx.app, ctx.auth.user)}
829831 <div class="door-section">${homeMilestones(ctx, undefined, visitor)}</div>
830832
831833 <section class="door-section" id="yours">
test/home-chapter-bar.test.ts added +94
@@ -0,0 +1,94 @@
1 /**
2 * The home's chapter bar (#14070): "v2: 0 of 2" with the next item, and nothing with no open
3 * chapter.
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 { newApp } from "../src/actions/apps.ts";
10 import { openIssue } from "../src/actions/issues.ts";
11 import { createApp, type App } from "../src/app.ts";
12 import { draftChapter, putIssue, startChapter, getChapter } from "../src/core/chapters.ts";
13 import { getRepo } from "../src/core/repos.ts";
14 import { createUser } from "../src/core/users.ts";
15 import { serve, type Servers } from "../src/http/server.ts";
16 import { quietLogs } from "./helpers/globals.ts";
17
18 quietLogs();
19
20 let dir = "";
21 let app: App;
22 let servers: Servers;
23 const home = () => fetch(`${servers.url}/`).then((r) => r.text());
24
25 beforeAll(async () => {
26 dir = await mkdtemp(join(tmpdir(), "forge-chapter-bar-"));
27 app = createApp({ dataDir: dir, port: 0, host: "forge.test", forgeRepo: "alice/forge" });
28 servers = await serve(app);
29 }, 30_000);
30
31 afterAll(async () => {
32 servers.stop();
33 app.close();

Add cases: partial done count with the next item advancing, all done (no next span), and an unreadable repository (no bar).

34 await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
35 });
36
37 test("no open chapter: the home has no bar; an open one shows count and next item", async () => {
38 const made = await createUser(app.db, { username: "alice", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, adminIfFirst: true });
39 if (!made.ok) throw new Error(String(made.error));
40 const c = await newApp(app, made.value, { name: "forge", description: "Words", visibility: "public" });
41 if (!c.ok) throw new Error(String(c.error));
42 const repo = getRepo(app.db, "alice", "forge")!;
43 expect(await home()).not.toContain("data-chapter-bar");
44
45 const d = draftChapter(app.db, repo.id, { name: "v2", means: "Second" }, made.value.id);
46 if (!d.ok) throw new Error("draft");
47 expect(await home()).not.toContain("data-chapter-bar");
48
49 for (const title of ["First <thing>", "Second thing"]) {
50 const i = await openIssue(app, made.value, repo, { title, body: "x" });
51 if (!i.ok) throw new Error(String(i.error));
52 putIssue(app.db, d.value, i.value.id, made.value.id);
53 }
54 startChapter(app.db, getChapter(app.db, repo.id, "v2")!, new Date());
55 const page = await home();
56 expect(page).toContain("data-chapter-bar");
57 expect(page).toContain("v2: 0 of 2");
58 expect(page).toContain('href="/alice/forge/chapters/v2"');
59 expect(page).toContain("next: #");
60 expect(page).toContain("First &lt;thing&gt;");
61 expect(page).not.toContain("First <thing>");
62 });
63
64 /** Merge a pull that closes the issue and record production's proof, so the item reads done. */
65 let pullNo = 9000;
66 function land(repoId: string, issue: { id: string; number: number }, authorId: string): void {
67 app.db.query("UPDATE issue SET state = 'closed', closed_at = '2026-11-10T00:00:00.000Z' WHERE id = ?1").run(issue.id);
68 const n = ++pullNo;
69 app.db.query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state) VALUES (?1, ?2, ?3, 'pull', ?4, ?5, ?6, 'closed')`).run(`bar-pull${n}`, repoId, n, `Build #${issue.number}`, `Closes #${issue.number}`, authorId);
70 app.db.query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', ?2, 'a', 'b', '2026-11-10T00:00:00.000Z')`).run(`bar-pull${n}`, `b${n}`);
71 app.db.query(`INSERT INTO release (sha, repo_id, pull_number, ok, line, created_at) VALUES ('abc', ?1, ?2, 1, 'ok', '2026-11-11T08:00:00.000Z')`).run(repoId, n);
72 }
73
74 test("the count and the next item move as items are done; all done leaves no next line", async () => {
75 const repo = getRepo(app.db, "alice", "forge")!;
76 const items = app.db.query<{ id: string; number: number }, [string]>("SELECT i.id, i.number FROM chapter_item ci JOIN issue i ON i.id = ci.issue_id JOIN chapter c ON c.id = ci.chapter_id WHERE c.repo_id = ?1 ORDER BY i.number").all(repo.id);
77 expect(items.length).toBe(2);
78 land(repo.id, items[0]!, repo.ownerId);
79 const half = await home();
80 expect(half).toContain("v2: 1 of 2");
81 expect(half).toContain("next: #" + items[1]!.number + " Second thing");
82 expect(half).not.toContain("First &lt;thing&gt;");
83
84 land(repo.id, items[1]!, repo.ownerId);
85 const all = await home();
86 expect(all).toContain("v2: 2 of 2");
87 expect(all).not.toContain("next:");
88 });
89
90 test("a reader who cannot open the repository gets no bar", async () => {
91 const repo = getRepo(app.db, "alice", "forge")!;
92 app.db.query("UPDATE repo SET visibility = 'private' WHERE id = ?1").run(repo.id);
93 expect(await home()).not.toContain("data-chapter-bar");
94 });
test/tui-chapter-bar.test.ts added +65
@@ -0,0 +1,65 @@
1 /** The Chapters screen opens with the home's bar line, same words (#14070). */
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 { createRepo } from "../src/actions/repos.ts";
7 import { createApp, type App } from "../src/app.ts";
8 import { barCount, barNext, barOf, draftChapter, getChapter, startChapter } from "../src/core/chapters.ts";
9 import { createIssue } from "../src/core/issues.ts";
10 import { putIssue } from "../src/core/chapters.ts";
11 import type { Repo } from "../src/core/repos.ts";
12 import { createUser, type User } from "../src/core/users.ts";
13 import { createForgeApp } from "../src/tui/forge.ts";
14 import { chaptersScreen } from "../src/tui/screens/chapters.ts";
15 import { headlessTerminal } from "../src/tui/term/terminal.ts";
16 import { quietLogs } from "./helpers/globals.ts";
17 import { settleApp } from "./helpers/tui.ts";
18
19 quietLogs();
20
21 let dir: string;
22 let app: App;
23 let repo: Repo;
24 let owner: User;
25 const guest = { sshUsername: "git", remoteAddress: "127.0.0.1", fingerprint: "SHA256:test" };
26
27 beforeAll(async () => {
28 dir = await mkdtemp(join(tmpdir(), "forge-tui-chbar-"));
29 app = createApp({ dataDir: dir, port: 0, host: "forge.test" });
30 const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
31 if (!u.ok) throw new Error(u.error);
32 owner = u.value;
33 const made = await createRepo(app, owner, { name: "shop", visibility: "public" });
34 if (!made.ok) throw new Error(JSON.stringify(made.error));
35 repo = made.value;
36 }, 60_000);
37
38 afterAll(async () => {
39 app.close();
40 await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
41 });
42
43 async function screenText(): Promise<string> {
44 const { app: tui, session } = createForgeApp(app, guest, { terminal: headlessTerminal(100, 30), exitHooks: false });
45 tui.start();
46 tui.ctx.push(chaptersScreen(session, tui.ctx, repo));
47 await settleApp(tui);
48 const out = tui.screen.toText().replace(/\s+/g, " ");
49 tui.stop?.();
50 return out;
51 }
52
53 test("no open chapter: no bar line; an open one prints the count and the next item", async () => {
54 const d = draftChapter(app.db, repo.id, { name: "v2", means: "Second" }, owner.id);
55 if (!d.ok) throw new Error("draft");
56 expect(await screenText()).not.toContain("v2: 0 of 1");
57 const made = createIssue(app.db, { repoId: repo.id, authorId: owner.id, title: "First thing", body: "x" });
58 if (!made.ok) throw new Error("issue");
59 putIssue(app.db, d.value, made.value.id, owner.id);
60 startChapter(app.db, getChapter(app.db, repo.id, "v2")!, new Date());
61 const bar = barOf(app.db, repo.id)!;
62 expect(barCount(bar)).toBe("v2: 0 of 1");
63 expect(barNext(bar)).toBe(`next: #${made.value.number} First thing`);
64 expect(await screenText()).toContain(`v2: 0 of 1 next: #${made.value.number} First thing`);
65 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs