Public: anyone can read this; the crew can change it.
The role-aware manifest names the open chapter and how many of its issues remain, in under 40 tokens #14061
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14050-the-role-aware-manifest-names-the-open-c → main 5 commits fork 2 threads · 2 unresolved
4 files
changed +181
−2
src/actions/here.ts +14 −2
| @@ -37,6 +37,7 @@ import type { User } from "../core/users.ts"; | ||
| 37 | 37 | import { mayDirectCrew } from "../crew/direct.ts"; |
| 38 | 38 | import { takesOffers } from "./offer.ts"; |
| 39 | 39 | import { originForRepo } from "../core/origins.ts"; |
| 40 | import { chapterManifestLine } from "../core/chapters.ts"; | |
| 40 | 41 | import { getPull } from "../core/pulls.ts"; |
| 41 | 42 | import { pullMayRun } from "../core/pull_trust.ts"; |
| 42 | 43 | import { emailVerified } from "../core/verify.ts"; |
| @@ -79,6 +80,11 @@ export interface Manifest { | ||
| 79 | 80 | /** On a pull's page: whether its code runs here (checks, preview) |
| 80 | 81 | * now, or waits for a writer's approval of its head. */ |
| 81 | 82 | readonly pull?: { readonly number: number; readonly runs: boolean }; |
| 83 | /** | |
| 84 | * The open chapter and how much of it is left, e.g. "chapter v2: 7 of 19 left"; absent with | |
| 85 | * none open. | |
| 86 | */ | |
| 87 | readonly chapter?: string; | |
| 82 | 88 | }; |
| 83 | 89 | readonly you: |
| 84 | 90 | | { readonly as: "anonymous" } |
| @@ -127,7 +133,7 @@ function keptPage( | ||
| 127 | 133 | // `tell` and `plan` file issues too, but as directing the crew, a different |
| 128 | 134 | // verb with a different check (`mayDirectCrew`). |
| 129 | 135 | const NO_ISSUE_TOOL = |
| 130 | "no MCP tool opens a plain issue; tell and plan file one as directing the crew"; | |
| 136 | "tell or plan files one"; | |
| 131 | 137 | |
| 132 | 138 | /** |
| 133 | 139 | * The manifest for a forge path, for `viewer` holding `scope`. `origin` is |
| @@ -269,6 +275,11 @@ function youFor( | ||
| 269 | 275 | }; |
| 270 | 276 | } |
| 271 | 277 | |
| 278 | function chapterField(app: App, repo: Repo): { chapter?: string } { | |
| 279 | const line = chapterManifestLine(app.db, repo.id); | |
| 280 | return line === null ? {} : { chapter: line }; | |
| 281 | } | |
| 282 | ||
| 272 | 283 | function repoHere( |
| 273 | 284 | app: App, |
| 274 | 285 | repo: Repo, |
| @@ -280,6 +291,7 @@ function repoHere( | ||
| 280 | 291 | name: `${repo.ownerName}/${repo.name}`, |
| 281 | 292 | visibility: repo.visibility, |
| 282 | 293 | audience: audienceFor(app.db, repo, viewer), |
| 294 | ...chapterField(app, repo), | |
| 283 | 295 | }; |
| 284 | 296 | // A private app the viewer may not enter is not there, to them. |
| 285 | 297 | if (record === undefined || !canEnterApp(app.db, repo, record, viewer)) |
| @@ -566,7 +578,7 @@ function repoActions( | ||
| 566 | 578 | out.push({ |
| 567 | 579 | do: "open the app", |
| 568 | 580 | http: `GET ${r}/app/production/open`, |
| 569 | noMcp: "a link to the running app; there is nothing to call", | |
| 581 | noMcp: "a link; nothing to call", | |
| 570 | 582 | }); |
| 571 | 583 | // The copy is for whoever cannot write the app (the web's button, `!canWrite`); |
| 572 | 584 | // its dry run is `ro`, so a read-only token sees it too. |
src/core/chapters.ts +39
| @@ -345,6 +345,45 @@ export function progressOf(chapter: Chapter, items: readonly Item[], now: Date): | ||
| 345 | 345 | return { done, total, finishesOn: new Date(now.getTime() + left * 86_400_000).toISOString().slice(0, 10) }; |
| 346 | 346 | } |
| 347 | 347 | |
| 348 | /** | |
| 349 | * The one short line a page's manifest carries ("chapter v2: 7 of 19 left"), or null with no | |
| 350 | * chapter open. Counts and the chapter's name only: no issue title, so it reads the same to | |
| 351 | * everyone. | |
| 352 | */ | |
| 353 | export function chapterManifestLine(db: Database, repoId: string): string | null { | |
| 354 | const open = openChapterOf(db, repoId); | |
| 355 | if (open === undefined) return null; | |
| 356 | const { left, total } = leftOf(db, open); | |
| 357 | return `chapter ${open.name}: ${left} of ${total} left`; | |
| 358 | } | |
| 359 | ||
| 360 | /** | |
| 361 | * How many of a chapter's items are not done, counted as `itemsOf` would but without its per-item | |
| 362 | * reads: every manifest asks, so it is one read of the list and, only when an item is closed, one | |
| 363 | * read of the repository's proven merged pulls. | |
| 364 | */ | |
| 365 | function leftOf(db: Database, chapter: Chapter): { left: number; total: number } { | |
| 366 | const rows = db | |
| 367 | .query<{ id: string; number: number; state: string }, [string]>( | |
| 368 | `SELECT i.id, i.number, i.state FROM chapter_item c JOIN issue i ON i.id = c.issue_id WHERE c.chapter_id = ?1`, | |
| 369 | ) | |
| 370 | .all(chapter.id); | |
| 371 | const closed = rows.filter((r) => r.state === "closed"); | |
| 372 | if (closed.length === 0) return { left: rows.length, total: rows.length }; | |
| 373 | // Done is closed and shipped by a merged pull production's release proof passed for. | |
| 374 | const proven = db | |
| 375 | .query<{ id: string; body: string }, [string]>( | |
| 376 | `SELECT i.id AS id, i.body AS body FROM release r | |
| 377 | JOIN issue i ON i.repo_id = r.repo_id AND i.number = r.pull_number | |
| 378 | JOIN pull p ON p.issue_id = i.id | |
| 379 | WHERE r.repo_id = ?1 AND r.ok = 1 AND p.merged_at IS NOT NULL AND i.body LIKE '%#%'`, | |
| 380 | ) | |
| 381 | .all(chapter.repoId) | |
| 382 | .map((p) => ({ id: p.id, closes: closesFromBody(p.body) })); | |
| 383 | const done = closed.filter((r) => proven.some((p) => p.id !== r.id && p.closes.includes(r.number))).length; | |
| 384 | return { left: rows.length - done, total: rows.length }; | |
| 385 | } | |
| 386 | ||
| 348 | 387 | /** The sentence the page, and the MCP, print under a chapter's name. */ |
| 349 | 388 | export const progressSentence = (p: Progress): string => |
| 350 | 389 | `${p.done} of ${p.total} done${p.finishesOn === null ? "" : `; at this pace it finishes ${p.finishesOn}`}.`; |
test/manifest-chapter.test.ts added +113
| @@ -0,0 +1,113 @@ | ||
| 1 | /** The manifest on a repository page names the open chapter and how much of it is left (#14050). */ | |
| 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 { manifestFor } from "../src/actions/here.ts"; | |
| 8 | import { createApp, type App } from "../src/app.ts"; | |
| 9 | import { chapterManifestLine, draftChapter, getChapter, itemsOf, NAME, putIssue, startChapter } from "../src/core/chapters.ts"; | |
| 10 | import { openIssue } from "../src/actions/issues.ts"; | |
| 11 | import { getRepo, type Repo } from "../src/core/repos.ts"; | |
| 12 | import { createUser, type User } from "../src/core/users.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | ||
| 15 | quietLogs(); | |
| 16 | ||
| 17 | let dir = ""; | |
| 18 | let app: App; | |
| 19 | let owner: User; | |
| 20 | let repo: Repo; | |
| 21 | ||
| 22 | const line = (viewer: User | undefined) => { | |
| 23 | const m = manifestFor(app, viewer, undefined, "https://forge.test", "/alice/shop"); | |
| 24 | if (!m.ok || m.value.here.kind !== "repository") throw new Error("no manifest"); | |
| 25 | return m.value.here.chapter; | |
| 26 | }; | |
| 27 | ||
| 28 | beforeAll(async () => { | |
| 29 | dir = await mkdtemp(join(tmpdir(), "forge-manifest-chapter-")); | |
| 30 | app = createApp({ dataDir: dir, port: 0, host: "forge.test" }); | |
| 31 | const made = await createUser(app.db, { username: "alice", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, adminIfFirst: true }); | |
| 32 | if (!made.ok) throw new Error(String(made.error)); | |
| 33 | owner = made.value; | |
| 34 | const c = await newApp(app, owner, { name: "shop", description: "Words", visibility: "public" }); | |
| 35 | if (!c.ok) throw new Error(String(c.error)); | |
| 36 | repo = getRepo(app.db, "alice", "shop")!; | |
| 37 | }, 30_000); | |
| 38 | ||
| 39 | afterAll(async () => { | |
| 40 | app.close(); | |
| 41 | await rm(dir, { recursive: true, force: true, maxRetries: 20, retryDelay: 100 }); | |
| 42 | }); | |
| 43 | ||
| 44 | test("no open chapter: the manifest has no chapter line", () => { | |
| 45 | expect(line(owner)).toBeUndefined(); | |
| 46 | draftChapter(app.db, repo.id, { name: "v2" }, owner.id); | |
| 47 | expect(line(owner)).toBeUndefined(); | |
| 48 | }); | |
| 49 | ||
| 50 | test("an open chapter reads 'chapter v2: N of M left', the same to an outsider, with no title", () => { | |
| 51 | const ch = draftChapter(app.db, repo.id, { name: "v3" }, owner.id); | |
| 52 | if (!ch.ok) throw new Error("draft"); | |
| 53 | for (const t of ["Secret plan alpha", "Secret plan beta"]) { | |
| 54 | const i = openIssue(app, owner, repo, { title: t }); | |
| 55 | if (!i.ok) throw new Error(String(i.error)); | |
| 56 | putIssue(app.db, ch.value, i.value.id, owner.id); | |
| 57 | } | |
| 58 | startChapter(app.db, ch.value, new Date()); | |
| 59 | expect(line(owner)).toBe("chapter v3: 2 of 2 left"); | |
| 60 | expect(line(undefined)).toBe("chapter v3: 2 of 2 left"); | |
| 61 | expect(JSON.stringify(line(undefined))).not.toContain("Secret"); | |
| 62 | }); | |
| 63 | ||
| 64 | /** | |
| 65 | * Merge a pull that closes `issue` and record production's passing proof for it: the item is done. | |
| 66 | */ | |
| 67 | let pullNo = 7000; | |
| 68 | const land = (issueId: string, number: number) => { | |
| 69 | app.db.query("UPDATE issue SET state = 'closed', closed_at = ?2 WHERE id = ?1").run(issueId, "2026-11-10T00:00:00.000Z"); | |
| 70 | const n = ++pullNo; | |
| 71 | app.db | |
| 72 | .query(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state) VALUES (?1, ?2, ?3, 'pull', 'Build', ?4, ?5, 'closed')`) | |
| 73 | .run(`pull${n}`, repo.id, n, `Closes #${number}`, owner.id); | |
| 74 | app.db | |
| 75 | .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')`) | |
| 76 | .run(`pull${n}`, `b${n}`); | |
| 77 | app.db | |
| 78 | .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')`) | |
| 79 | .run(repo.id, n); | |
| 80 | }; | |
| 81 | ||
| 82 | test("the count is items not yet done: a done item leaves it, a building one stays in it", () => { | |
| 83 | const ch = getChapter(app.db, repo.id, "v3")!; | |
| 84 | const made = [1, 2].map((k) => { | |
| 85 | const i = openIssue(app, owner, repo, { title: `Extra ${k}` }); | |
| 86 | if (!i.ok) throw new Error(String(i.error)); | |
| 87 | putIssue(app.db, ch, i.value.id, owner.id); | |
| 88 | return i.value; | |
| 89 | }); | |
| 90 | expect(line(owner)).toBe("chapter v3: 4 of 4 left"); | |
| 91 | const first = itemsOf(app.db, ch)[0]!; | |
| 92 | land(first.issueId, first.number); | |
| 93 | expect(line(owner)).toBe("chapter v3: 3 of 4 left"); | |
| 94 | // closed without a proven release: building, still counted as left | |
| 95 | app.db.query("UPDATE issue SET state = 'closed' WHERE id = ?1").run(made[0]!.id); | |
| 96 | expect(itemsOf(app.db, ch).find((i) => i.issueId === made[0]!.id)!.status).toBe("building"); | |
| 97 | expect(line(owner)).toBe("chapter v3: 3 of 4 left"); | |
| 98 | }); | |
| 99 | ||
| 100 | test("the line for the longest chapter name is at most 70 characters", async () => { | |
| 101 | const made = await newApp(app, owner, { name: "tall", description: "Words", visibility: "public" }); | |
| 102 | if (!made.ok) throw new Error(String(made.error)); | |
| 103 | const tall = getRepo(app.db, "alice", "tall")!; | |
| 104 | const longest = "v" + "9".repeat(39); | |
| 105 | expect(NAME.test(longest)).toBe(true); | |
| 106 | const ch = draftChapter(app.db, tall.id, { name: longest }, owner.id); | |
| 107 | if (!ch.ok) throw new Error("draft"); | |
| 108 | startChapter(app.db, ch.value, new Date()); | |
| 109 | const text = chapterManifestLine(app.db, tall.id)!; | |
| 110 | expect(text).toBe(`chapter ${longest}: 0 of 0 left`); | |
| 111 | // with three-digit counts, "999 of 999" in place of "0 of 0" | |
| 112 | expect(text.length + "999 of 999".length - "0 of 0".length).toBeLessThanOrEqual(70); | |
| 113 | }); |
test/manifest-roles.test.ts +15
| @@ -20,6 +20,7 @@ import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts"; | ||
| 20 | 20 | import { openIssue } from "../src/actions/issues.ts"; |
| 21 | 21 | import { openPull } from "../src/actions/pulls.ts"; |
| 22 | 22 | import { commitToBranch } from "../src/actions/repos.ts"; |
| 23 | import { draftChapter, startChapter } from "../src/core/chapters.ts"; | |
| 23 | 24 | import { getRepo } from "../src/core/repos.ts"; |
| 24 | 25 | import { createToken } from "../src/core/tokens.ts"; |
| 25 | 26 | import { serve, type Servers } from "../src/http/server.ts"; |
| @@ -157,6 +158,20 @@ test("the manifest stays under its ceiling for each role", () => { | ||
| 157 | 158 | ).toBeLessThanOrEqual(CEILINGS[role]); |
| 158 | 159 | }); |
| 159 | 160 | |
| 161 | test("the manifest stays under the same ceilings with a chapter open", () => { | |
| 162 | const repo = getRepo(app.db, "acme", "pub")!; | |
| 163 | const ch = draftChapter(app.db, repo.id, { name: "v" + "9".repeat(39) }, who["wren"]!.id); | |
| 164 | if (!ch.ok) throw new Error("draft"); | |
| 165 | startChapter(app.db, ch.value, new Date()); | |
| 166 | expect(manifest(undefined).here).toMatchObject({ chapter: `chapter ${ch.value.name}: 0 of 0 left` }); | |
| 167 | // counted with three-digit counts, the most a chapter holds in practice: "999 of 999" for "0 of | |
| 168 | // 0" | |
| 169 | const wide = (v: User | undefined) => size(v) + "999 of 999".length - "0 of 0".length; | |
| 170 | const sizes = { outsider: wide(undefined), writer: wide(who["wes"]), admin: wide(who["wren"]) }; | |
| 171 | for (const role of Object.keys(CEILINGS) as (keyof typeof CEILINGS)[]) | |
| 172 | expect(sizes[role], `the ${role} manifest is ${sizes[role]} characters with a chapter open`).toBeLessThanOrEqual(CEILINGS[role]); | |
| 173 | }); | |
| 174 | ||
| 160 | 175 | /** |
| 161 | 176 | * What following an action may answer: it ran, was queued, redirected, or the |
| 162 | 177 | * route took the caller and then refused the empty body or a state the fresh |
new above
offline
Non-blocking: this "closed and shipped by a merged pull with a passing release" rule is also written in
itemsOf. Share one predicate so the manifest count cannot drift from the chapter page.