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

Merged opened this

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

Merged

mason/forge:mason/14050-the-role-aware-manifest-names-the-open-c → main 5 commits fork 2 threads · 2 unresolved

  • Merged. mason/14050-the-role-aware-manifest-names-the-open-c was merged into main as 46c0345.

Review

Sign in to review this change.
4 files changed +181 −2
src/actions/here.ts +14 −2
@@ -37,6 +37,7 @@ import type { User } from "../core/users.ts";
3737 import { mayDirectCrew } from "../crew/direct.ts";
3838 import { takesOffers } from "./offer.ts";
3939 import { originForRepo } from "../core/origins.ts";
40 import { chapterManifestLine } from "../core/chapters.ts";
4041 import { getPull } from "../core/pulls.ts";
4142 import { pullMayRun } from "../core/pull_trust.ts";
4243 import { emailVerified } from "../core/verify.ts";
@@ -79,6 +80,11 @@ export interface Manifest {
7980 /** On a pull's page: whether its code runs here (checks, preview)
8081 * now, or waits for a writer's approval of its head. */
8182 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;
8288 };
8389 readonly you:
8490 | { readonly as: "anonymous" }
@@ -127,7 +133,7 @@ function keptPage(
127133 // `tell` and `plan` file issues too, but as directing the crew, a different
128134 // verb with a different check (`mayDirectCrew`).
129135 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";
131137
132138 /**
133139 * The manifest for a forge path, for `viewer` holding `scope`. `origin` is
@@ -269,6 +275,11 @@ function youFor(
269275 };
270276 }
271277
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
272283 function repoHere(
273284 app: App,
274285 repo: Repo,
@@ -280,6 +291,7 @@ function repoHere(
280291 name: `${repo.ownerName}/${repo.name}`,
281292 visibility: repo.visibility,
282293 audience: audienceFor(app.db, repo, viewer),
294 ...chapterField(app, repo),
283295 };
284296 // A private app the viewer may not enter is not there, to them.
285297 if (record === undefined || !canEnterApp(app.db, repo, record, viewer))
@@ -566,7 +578,7 @@ function repoActions(
566578 out.push({
567579 do: "open the app",
568580 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",
570582 });
571583 // The copy is for whoever cannot write the app (the web's button, `!canWrite`);
572584 // 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):
345345 return { done, total, finishesOn: new Date(now.getTime() + left * 86_400_000).toISOString().slice(0, 10) };
346346 }
347347
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 '%#%'`,

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.

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
348387 /** The sentence the page, and the MCP, print under a chapter's name. */
349388 export const progressSentence = (p: Progress): string =>
350389 `${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";
2020 import { openIssue } from "../src/actions/issues.ts";
2121 import { openPull } from "../src/actions/pulls.ts";
2222 import { commitToBranch } from "../src/actions/repos.ts";
23 import { draftChapter, startChapter } from "../src/core/chapters.ts";
2324 import { getRepo } from "../src/core/repos.ts";
2425 import { createToken } from "../src/core/tokens.ts";
2526 import { serve, type Servers } from "../src/http/server.ts";
@@ -157,6 +158,20 @@ test("the manifest stays under its ceiling for each role", () => {
157158 ).toBeLessThanOrEqual(CEILINGS[role]);
158159 });
159160
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
160175 /**
161176 * What following an action may answer: it ran, was queued, redirected, or the
162177 * route took the caller and then refused the empty body or a state the fresh

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs