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

When a chapter closes, its page links the next draft chapter and /next names the chapter it ranks for #12712

Merged opened this

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

Merged

scout/forge:scout/12681-when-a-chapter-closes-its-page-links-the → main 6 commits fork 1 thread · 1 unresolved

  • Merged. scout/12681-when-a-chapter-closes-its-page-links-the was merged into main as f8d6405.

Review

Sign in to review this change.
6 files changed +101 −9
docs/features/chapters.md +2
@@ -19,6 +19,8 @@ A closed chapter's list is frozen, so `itemsOf` keeps it in process memory (at m
1919
2020 - **On /next (#12288).** `/:owner/:name/next` has a Chapters section: each chapter with issues closed against its list, and, for the repository's owner, **Close chapter** on the open one (`POST …/chapters/:chapter/close`, same-origin, nothing moves). A chapter with issues still open says which ones are in its way and refuses the close with the same sentence. A close shows its receipt (name, tag) and an **Undo** for 60 seconds (`…/undo`: the tag goes, the chapter is open again); a close that moved items to the next chapter (Ship it) has no undo. The terminal does the same on `src/tui/screens/chapters.ts` (`c`, `u`); its acts append the same events, so an open web page follows.
2121
22 - **Next line (#12681).** A closed chapter's page ends with `Next: <earliest draft>` (linked), or says no chapter is drafted. `/next` carries a header line: `Ranked for <open chapter>: <progress sentence>`, or, when chapters exist and none is open, "No chapter is open" with a link to draft one. A repository with no chapters shows neither. The terminal has no chapter screen line for these two facts yet.
23
2224 ## The first chapter: v1.0.0
2325
2426 Drafting a chapter named `v1.0.0` records the v1 list's issues in it (the issue of every probe in `scripts/v1-proven.ts`, those that exist in the repository). Closing it (Ship it or Close) runs those read-only probes against the forge's public origin and is refused, naming each probe that does not pass, until every one passes; `unproven` is not a pass. The close tags the default branch's tip and nothing more: a person cuts the release with `scripts/cut-release.ts`.
docs/features/next-up.md +2
@@ -15,6 +15,8 @@
1515
1616 **Filter (#11867):** a plain GET form above the list narrows `/next` to one pillar (`?pillar=P7` or `Later`, typed in a box) and/or a word (`?q=cache`, matched without regard to case, shown as typed, at most 80 characters). A filter only hides rows: each keeps its real place in the whole ranking, the cut line stays where the whole list puts it (drawn only between shown rows), and a move made under a filter moves in the whole order and returns to the same filter. A line says "N of M shown", and that the week's capacity bar is left out while filtered. An unknown or malformed pillar shows an empty list that says so. **Terminal:** `/` asks for a pillar and/or a word (`P7 cache`); an empty answer clears it; ranks, `t` `u` `d` `l` and the header count behave as on the page.
1717
18 **The chapter line (#12681):** under the title, once the repository has chapters, `Ranked for <open chapter>: <progress sentence>` (linked), or "No chapter is open" with a link to draft one; a repository that never drafted a chapter shows no line. The terminal's Next up screen does not show it yet.
19
1820 **The growth line (#12290):** under the title, two `dl` rows: *Week* (issues opened in the last seven days, who opened them, and how many closed: "2 issues opened (2 by owner), 0 closed.") and *Planner* (on, paused until a time in UTC, or paused until the owner switches it on). The owner (a person who administers the repository) also gets the switch in the Planner row: a button in a post form to the same `planner_switch` action as the queue page, sent back to `/next`, so the pause is one tap and the owner stays on the list. A reader sees both rows and no button. Both rows come from one read (`weekLine`), sealed issues left out for a viewer who may not see them. **Terminal:** Next up shows the same sentence (`growthWords`, `pauseSentence`) above the list, and the owner presses `p` to pause the planner until they switch it on, and `p` again to switch it on; for a reader and for an agent the key does nothing.
1921
2022 ## The week is the sprint (#8704)
src/web/pages/chapters.ts +7 −4
@@ -7,7 +7,7 @@
77 */
88
99 import { CHAPTER_WORDS, close, draft, fill, open, patch, reopen, refusalWords } from "../../actions/chapters.ts";
10 import { getChapter, itemsOf, listChapters, progressOf, progressSentence, type Chapter, type Item } from "../../core/chapters.ts";
10 import { getChapter, itemsOf, nextChapterOf, listChapters, progressOf, progressSentence, type Chapter, type Item } from "../../core/chapters.ts";
1111 import { canAdmin, type Repo } from "../../core/repos.ts";
1212 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
1313 import type { Ctx } from "../../http/context.ts";
@@ -77,7 +77,7 @@ export function chaptersPage(ctx: Ctx): Response {
7777
7878 const fact = (name: string, value: string): Html => html`<div class="status-row"><dt>${name}</dt><dd>${value}</dd></div>`;
7979
80 function finished(repo: Repo, c: Chapter, items: readonly Item[], may: boolean): Html {
80 function finished(repo: Repo, c: Chapter, items: readonly Item[], may: boolean, later: Chapter | undefined): Html {
8181 const done = items.filter((i) => i.status === "done");
8282 const days = c.openedAt === null || c.closedAt === null ? 0 : Math.max(1, Math.round((Date.parse(c.closedAt) - Date.parse(c.openedAt)) / 86_400_000));
8383 return html`<p data-finished><strong>${c.name} is finished.</strong> ${c.means}</p>
@@ -91,7 +91,10 @@ function finished(repo: Repo, c: Chapter, items: readonly Item[], may: boolean):
9191 <pre data-notes>${c.notes}</pre>
9292 ${may
9393 ? html`<form method="post" action="${hrefOf(repo, c)}/patch">${btn(`Open a patch chapter for ${c.name}`, { variant: "primary" })}</form>`
94 : null}`;
94 : null}
95 <p data-next-chapter>${later === undefined
96 ? "Next: no chapter is drafted."
97 : html`Next: <a href="${hrefOf(repo, later)}">${later.name}</a>`}</p>`;
9598 }
9699
97100 // GET /:owner/:name/chapters/:chapter
@@ -107,7 +110,7 @@ export function chapterPage(ctx: Ctx): Response {
107110 const rendering = performance.now();
108111 const here = hrefOf(repo, c);
109112 let main: Html;
110 if (c.state === "closed") main = finished(repo, c, items, may);
113 if (c.state === "closed") main = finished(repo, c, items, may, nextChapterOf(ctx.app.db, repo.id));
111114 else {
112115 const building = items.filter((i) => i.status === "building");
113116 const left = items.filter((i) => i.status === "left");
src/web/pages/next.ts +5 −2
@@ -27,7 +27,8 @@ import { html, raw, type Html } from "../html.ts";
2727 import { flashOrJson, page } from "../layout.ts";
2828 import { btn, kbd, row } from "../ui.ts";
2929 import { GROWTH_DAYS, growthLine } from "./next_growth.ts";
30 import { chaptersSection } from "./next_chapters.ts";
30 import { listChapters } from "../../core/chapters.ts";
31 import { chapterLine, chaptersSection } from "./next_chapters.ts";
3132 import { countWords, filterPath, markBefore, filtered, matches, readFilter } from "./next_filter.ts";
3233
3334 /**
@@ -257,16 +258,18 @@ export function nextPage(ctx: Ctx): Response {
257258 ${btn("Filter", { type: "submit", size: "sm" })}
258259 ${isFiltered ? html`<a href="${base}/next">Clear</a>` : null}
259260 </form>`;
261 const chapters = listChapters(ctx.app.db, repo.id);
260262 const body = html`${repoHeader(ctx, repo, "issues")}
261263 <div data-next>
262264 ${pageHead("Next up", { sub: "The crew builds strictly from the top." })}
265 ${chapterLine(ctx, repo, chapters)}
263266 ${growthLine(week7, pauseAt(week7, new Date()), writer && canAdmin(ctx.app.db, repo, ctx.auth.user!), base, back)}
264267 <p class="error" id="next-flash" role="alert" hidden></p>
265268 ${rows.length === 0
266269 ? html`<p class="muted">Nothing is ready: everything open waits for something. <a href="${base}/map">See the map</a>.</p>`
267270 : html`${bar}${isFiltered ? html`<p class="muted" id="next-count">${countWords(ats.length, rows.length)} shown${ats.length + parked.length === 0 ? html`. ${nothingWords}` : null}. Numbers and the cut line are the whole list's; the week's capacity bar is left out while filtered.</p>` : null}
268271 ${first.length > 0 ? section(isFiltered ? "Matching" : "Up next", first, true, "next-list") : null}${rest.length > 0 ? section("After", rest, false) : null}`}
269 ${chaptersSection(ctx, repo, back)}
272 ${chaptersSection(ctx, repo, back, chapters)}
270273 <p class="muted small mt" id="next-week">${sentence} <a href="${base}/week">The week</a>${writer
271274 ? " · Drag a row. Keys: t top · l Later · Shift+J/K or Alt+↓/↑ down/up · j/k choose a row."
272275 : null}</p>
src/web/pages/next_chapters.ts +15 −3
@@ -5,7 +5,7 @@
55 * `actions/chapters.ts`.
66 */
77 import { CLOSE_UNDO_MS, stopsClose, undoableClose } from "../../actions/chapters.ts";
8 import { itemsOf, listChapters, progressOf, progressSentence, type Chapter } from "../../core/chapters.ts";
8 import { itemsOf, progressOf, progressSentence, type Chapter } from "../../core/chapters.ts";
99 import { canAdmin, type Repo } from "../../core/repos.ts";
1010 import type { Ctx } from "../../http/context.ts";
1111 import { repoBase } from "../chrome.ts";
@@ -21,9 +21,8 @@ function act(base: string, c: Chapter, verb: "close" | "undo", back: string, lab
2121 </form>`;
2222 }
2323
24 export function chaptersSection(ctx: Ctx, repo: Repo, back: string): Html | null {
24 export function chaptersSection(ctx: Ctx, repo: Repo, back: string, all: readonly Chapter[]): Html | null {
2525 const app = ctx.app;
26 const all = listChapters(app.db, repo.id);
2726 if (all.length === 0) return null;
2827 const base = repoBase(repo);
2928 const may = ctx.auth.user !== undefined && ctx.auth.user.kind !== "agent" && canAdmin(app.db, repo, ctx.auth.user);
@@ -60,3 +59,16 @@ export function chaptersSection(ctx: Ctx, repo: Repo, back: string): Html | null
6059 <ul class="list setting-list">${rows}</ul>
6160 ${all.length > SHOWN ? html`<p class="muted small"><a href="${base}/chapters">All ${String(all.length)} chapters</a></p>` : null}</section>`;
6261 }
62
63 /**
64 * The line under the /next heading: the open chapter and where it stands, or that none is open
65 * once chapters exist.
66 */
outdated

Principle 1 / docs/features/chapters.md: return empty when all.length === 0 so a never-chaptered repo is unchanged; say 'No chapter is open' only when chapters exist and none is open. Make the return type Html | null.

67 export function chapterLine(ctx: Ctx, repo: Repo, all: readonly Chapter[]): Html | null {
68 if (all.length === 0) return null; // no chapter, no change: a repo that never drafted one flows on
69 const base = repoBase(repo);
70 const open = all.find((c) => c.state === "open");
71 if (open === undefined) return html`<p class="muted" data-chapter-line>No chapter is open. <a href="${base}/chapters">Draft one</a>.</p>`;
72 const p = progressOf(open, itemsOf(ctx.app.db, open), new Date());
73 return html`<p data-chapter-line>Ranked for <a href="${base}/chapters/${encodeURIComponent(open.name)}">${open.name}</a>: ${progressSentence(p)}</p>`;
74 }
test/chapter-next.test.ts added +70
@@ -0,0 +1,70 @@
1 /** A closed chapter links the next draft (#12681); /next names the open chapter or says none is. */
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 { newApp } from "../src/actions/apps.ts";
7 import { createApp, type App } from "../src/app.ts";
8 import { draftChapter, startChapter, getChapter } from "../src/core/chapters.ts";
9 import { getRepo, type Repo } from "../src/core/repos.ts";
10 import { createToken } from "../src/core/tokens.ts";
11 import { createUser, type User } from "../src/core/users.ts";
12 import { serve, type Servers } from "../src/http/server.ts";
13 import { quietLogs } from "./helpers/globals.ts";
14
15 quietLogs();
16
17 let dir = "";
18 let app: App;
19 let servers: Servers;
20 let owner: User;
21 let repo: Repo;
22 let token = "";
23 const get = (p: string) => fetch(`${servers.url}${p}`, { headers: { authorization: `Bearer ${token}` } }).then((r) => r.text());
24
25 beforeAll(async () => {
26 dir = await mkdtemp(join(tmpdir(), "forge-chapter-next-"));
27 app = createApp({ dataDir: dir, port: 0, host: "forge.test" });
28 servers = await serve(app);
29 const made = await createUser(app.db, { username: "alice", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, adminIfFirst: true });
30 if (!made.ok) throw new Error(String(made.error));
31 owner = made.value;
32 const c = await newApp(app, owner, { name: "shop", description: "Words", visibility: "public" });
33 if (!c.ok) throw new Error(String(c.error));
34 repo = getRepo(app.db, "alice", "shop")!;
35 token = createToken(app.db, owner.id, "t", "rw").token;
36 }, 30_000);
37
38 afterAll(async () => {
39 servers.stop();
40 app.close();
41 await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 });
42 });
43
44 test("a repo that never drafted a chapter: /next has no chapter line", async () => {
45 const page = await get("/alice/shop/next");
46 expect(page).not.toContain("data-chapter-line");
47 expect(page).not.toContain("No chapter is open.");
48 });
49
50 test("a closed chapter says none is drafted, then links the earliest draft", async () => {
51 const one = draftChapter(app.db, repo.id, { name: "v1.0.0", means: "First" }, owner.id);
52 if (!one.ok) throw new Error("draft");
53 app.db.query("UPDATE chapter SET state = 'closed', opened_at = ?2, closed_at = ?2, notes = 'n' WHERE id = ?1").run(one.value.id, "2026-11-01T00:00:00.000Z");
54 expect(await get("/alice/shop/chapters/v1.0.0")).toContain("Next: no chapter is drafted.");
55 draftChapter(app.db, repo.id, { name: "v1.1.0" }, owner.id);
56 draftChapter(app.db, repo.id, { name: "v1.2.0" }, owner.id);
57 const none = await get("/alice/shop/next");
58 expect(none).toContain("No chapter is open.");
59 expect(none).toContain('href="/alice/shop/chapters"');
60 const page = await get("/alice/shop/chapters/v1.0.0");
61 expect(page).toContain('Next: <a href="/alice/shop/chapters/v1.1.0">v1.1.0</a>');
62 expect(page).not.toContain("v1.2.0");
63 });
64
65 test("/next names the open chapter and its progress sentence", async () => {
66 startChapter(app.db, getChapter(app.db, repo.id, "v1.1.0")!, new Date());
67 const page = await get("/alice/shop/next");
68 expect(page).toContain('Ranked for <a href="/alice/shop/chapters/v1.1.0">v1.1.0</a>: 0 of 0 done.');
69 expect(page).not.toContain("No chapter is open.");
70 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs