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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12681-when-a-chapter-closes-its-page-links-the → main 6 commits fork 1 thread · 1 unresolved
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 | ||
| 19 | 19 | |
| 20 | 20 | - **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. |
| 21 | 21 | |
| 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 | ||
| 22 | 24 | ## The first chapter: v1.0.0 |
| 23 | 25 | |
| 24 | 26 | 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 @@ | ||
| 15 | 15 | |
| 16 | 16 | **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. |
| 17 | 17 | |
| 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 | ||
| 18 | 20 | **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. |
| 19 | 21 | |
| 20 | 22 | ## The week is the sprint (#8704) |
src/web/pages/chapters.ts +7 −4
| @@ -7,7 +7,7 @@ | ||
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | 9 | 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"; | |
| 11 | 11 | import { canAdmin, type Repo } from "../../core/repos.ts"; |
| 12 | 12 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; |
| 13 | 13 | import type { Ctx } from "../../http/context.ts"; |
| @@ -77,7 +77,7 @@ export function chaptersPage(ctx: Ctx): Response { | ||
| 77 | 77 | |
| 78 | 78 | const fact = (name: string, value: string): Html => html`<div class="status-row"><dt>${name}</dt><dd>${value}</dd></div>`; |
| 79 | 79 | |
| 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 { | |
| 81 | 81 | const done = items.filter((i) => i.status === "done"); |
| 82 | 82 | 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)); |
| 83 | 83 | 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): | ||
| 91 | 91 | <pre data-notes>${c.notes}</pre> |
| 92 | 92 | ${may |
| 93 | 93 | ? 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>`; | |
| 95 | 98 | } |
| 96 | 99 | |
| 97 | 100 | // GET /:owner/:name/chapters/:chapter |
| @@ -107,7 +110,7 @@ export function chapterPage(ctx: Ctx): Response { | ||
| 107 | 110 | const rendering = performance.now(); |
| 108 | 111 | const here = hrefOf(repo, c); |
| 109 | 112 | 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)); | |
| 111 | 114 | else { |
| 112 | 115 | const building = items.filter((i) => i.status === "building"); |
| 113 | 116 | 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"; | ||
| 27 | 27 | import { flashOrJson, page } from "../layout.ts"; |
| 28 | 28 | import { btn, kbd, row } from "../ui.ts"; |
| 29 | 29 | 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"; | |
| 31 | 32 | import { countWords, filterPath, markBefore, filtered, matches, readFilter } from "./next_filter.ts"; |
| 32 | 33 | |
| 33 | 34 | /** |
| @@ -257,16 +258,18 @@ export function nextPage(ctx: Ctx): Response { | ||
| 257 | 258 | ${btn("Filter", { type: "submit", size: "sm" })} |
| 258 | 259 | ${isFiltered ? html`<a href="${base}/next">Clear</a>` : null} |
| 259 | 260 | </form>`; |
| 261 | const chapters = listChapters(ctx.app.db, repo.id); | |
| 260 | 262 | const body = html`${repoHeader(ctx, repo, "issues")} |
| 261 | 263 | <div data-next> |
| 262 | 264 | ${pageHead("Next up", { sub: "The crew builds strictly from the top." })} |
| 265 | ${chapterLine(ctx, repo, chapters)} | |
| 263 | 266 | ${growthLine(week7, pauseAt(week7, new Date()), writer && canAdmin(ctx.app.db, repo, ctx.auth.user!), base, back)} |
| 264 | 267 | <p class="error" id="next-flash" role="alert" hidden></p> |
| 265 | 268 | ${rows.length === 0 |
| 266 | 269 | ? html`<p class="muted">Nothing is ready: everything open waits for something. <a href="${base}/map">See the map</a>.</p>` |
| 267 | 270 | : 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} |
| 268 | 271 | ${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)} | |
| 270 | 273 | <p class="muted small mt" id="next-week">${sentence} <a href="${base}/week">The week</a>${writer |
| 271 | 274 | ? " · Drag a row. Keys: t top · l Later · Shift+J/K or Alt+↓/↑ down/up · j/k choose a row." |
| 272 | 275 | : null}</p> |
src/web/pages/next_chapters.ts +15 −3
| @@ -5,7 +5,7 @@ | ||
| 5 | 5 | * `actions/chapters.ts`. |
| 6 | 6 | */ |
| 7 | 7 | 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"; | |
| 9 | 9 | import { canAdmin, type Repo } from "../../core/repos.ts"; |
| 10 | 10 | import type { Ctx } from "../../http/context.ts"; |
| 11 | 11 | import { repoBase } from "../chrome.ts"; |
| @@ -21,9 +21,8 @@ function act(base: string, c: Chapter, verb: "close" | "undo", back: string, lab | ||
| 21 | 21 | </form>`; |
| 22 | 22 | } |
| 23 | 23 | |
| 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 { | |
| 25 | 25 | const app = ctx.app; |
| 26 | const all = listChapters(app.db, repo.id); | |
| 27 | 26 | if (all.length === 0) return null; |
| 28 | 27 | const base = repoBase(repo); |
| 29 | 28 | 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 | ||
| 60 | 59 | <ul class="list setting-list">${rows}</ul> |
| 61 | 60 | ${all.length > SHOWN ? html`<p class="muted small"><a href="${base}/chapters">All ${String(all.length)} chapters</a></p>` : null}</section>`; |
| 62 | 61 | } |
| 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 | */ | |
| 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 | }); |
new above
offline
Principle 1 / docs/features/chapters.md: return empty when
all.length === 0so 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.