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

The forge toolbar in a preview names its pull and the check's state in plain words #14060

Merged opened this

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

Merged

scout/forge:scout/14051-the-forge-toolbar-in-a-preview-names-its → main 2 commits fork 3 threads · 3 unresolved

  • Merged. scout/14051-the-forge-toolbar-in-a-preview-names-its was merged into main as 964e01c.

Review

Sign in to review this change.
11 files changed +95 −27
docs/features/forge-toolbar.md +2 −2
@@ -8,8 +8,8 @@ preview), so you always know where you are and can get back to the forge.
88 images, scripts, styles, attachments, ranges and `HEAD` pass through byte for
99 byte. A page that already carries the tag is not given a second.
1010 - **What it says:** the app, the environment and, on a preview, a link
11 "Preview of pull #N" to the pull's page on the forge; Home goes to the forge.
12 - **The preview line:** on a preview the pill's panel says "Preview of pull #N: <title>", the title as the forge holds it, set as text, linked to the pull. Production has no such line.
11 "Pull #N: <state>" to the pull's page on the forge; Home goes to the forge.
12 - **The preview line:** on a preview the pill's panel has one link to the pull, "Pull #N: checking", "Pull #N: green" or "Pull #N: red" (running or queued reads checking; also "cancelled" and "no check yet"), with the title as its tooltip, set as text. The state is the newest check of the pull's head, read when the page loads: it updates on reload only, never polled. Production has no such line.
1313 - **Comment on the pull:** a preview's panel also has a comment box, built by a small script of its own (`src/apps/toolbar_comment.ts`, under 4 KB) that the pill fetches from the app's host the first time a preview's panel opens; production pages and a closed pill never load it, and the pill keeps its 24 KB budget. A viewer the tag names as signed out (`data-in` absent) sees "Sign in to comment on this pull", which goes through `/__forge/signin` and back to the page, instead of a box. The box posts `POST /__forge/comment` with `{ text }`, same-origin and with the page's proof, and the comment lands on the pull the environment's name gives (`pull-N`; never a number from the body), as the person the app's grant names. Words: signed out is `401` ("Sign in to the forge to comment on this pull."); production, an unknown number or a non-pull is `404`; empty text is `400`, and so is text over 4000 characters (`COMMENT_MAX`, the box's `maxLength` too) with `body_too_long`; too many is `429` with `Retry-After` (6 a minute for a person, 20 for a socket address, so a script holding one proof cannot flood the pull's author). A refused comment keeps what was typed and says why under the box; only a posted one clears it, and its "Commented on pull #N." links to the address the door answered with (only when that is on the forge's origin). The terminal already comments on a pull (`src/tui/screens/pull.ts`), so this is a page-only surface. See `src/apps/pull_comment.ts`.
1414 - **Which commit:** one more line, `Serving a1b2c3d, live 4 min ago`, the short
1515 id linked to the commit on the forge. The id and the instant come from the
src/apps/pill_check.ts +7 −7
@@ -1,5 +1,5 @@
11 /**
2 * The check state the forge pill names for a preview's pull, in plain words:
2 * The check state the forge pill names for a preview's pull, in plain words (checking, green, red):
33 * the newest check run of the pull's head. One word set, so the panel and the
44 * tests read the same table.
55 */
@@ -7,12 +7,12 @@
77 import type { Database } from "bun:sqlite";
88
99 export const CHECK_WORDS = {
10 passed: "Checks passed",
11 failed: "Checks failed",
12 running: "Checks running",
13 waiting: "Checks waiting",
14 cancelled: "Checks cancelled",
15 none: "No checks yet",
10 passed: "green",
11 failed: "red",
12 running: "checking",
13 waiting: "checking",
14 cancelled: "cancelled",
15 none: "no check yet",
1616 } as const;
1717
1818 export type PillCheck = keyof typeof CHECK_WORDS;
src/apps/toolbar.ts +3 −3
@@ -108,10 +108,12 @@ const toolbarSource = `(function () {
108108 if (pv && /^\\d{1,9}$/.test(d.pull) && /^[\\w.-]+\\/[\\w.-]+$/.test(d.repo || "")) {
109109 try { pullHref = new URL("/" + d.repo + "/pulls/" + d.pull, fo).href; } catch (e) {}
110110 }
111 var pt = "Preview of pull #" + d.pull + (d.title ? ": " + d.title : "");
111 var cw = ${JSON.stringify(CHECK_WORDS)};
112 var pt = "Pull #" + d.pull + (d.check && Object.prototype.hasOwnProperty.call(cw, d.check) ? ": " + cw[d.check] : "");
outdated

This adds a second link to the same pull right above 'Preview of pull #N' (a duplicate 44px tap target on a scrolling panel), and the check state is also said by the CW line below. Fold the words into the existing link and remove the CW line for previews.

112113 if (pullHref) {
113114 var pl = document.createElement("a");
114115 pl.textContent = pt;
116 if (d.title) pl.title = d.title;
115117 pl.href = pullHref;
116118 pl.rel = "noopener";
117119 pl.style.cssText = LS + ";overflow-wrap:anywhere";
@@ -130,8 +132,6 @@ const toolbarSource = `(function () {
130132 }
131133 if (pv) line("Environment: preview");
132134 if (pv && d.branch) line("Branch: " + d.branch);
133 var CW = ${JSON.stringify(CHECK_WORDS)};
134 if (d.env !== "production" && d.check && Object.prototype.hasOwnProperty.call(CW, d.check)) line(CW[d.check]);
135135 // Whether this is the pull as it stands now; an open, current preview says nothing.
136136 var W = ${JSON.stringify(FRESHNESS_WORDS)};
137137 var freshness = d.state === "merged" ? W.merged
test/apps-pill-check.test.ts +4 −4
@@ -84,10 +84,10 @@ describe("the pill's check line", () => {
8484
8585 test("the panel script draws the line for a pull, never for production or an unknown key", () => {
8686 const pull = { app: "notes", env: "pull-3", pull: "3" };
87 expect(drawn({ ...pull, check: "failed" })).toContain(CHECK_WORDS.failed);
88 expect(drawn({ ...pull, check: "cancelled" })).toContain("Checks cancelled");
89 expect(drawn({ ...pull, check: "bogus" }).filter((t) => t.startsWith("Checks"))).toEqual([]);
90 expect(drawn({ ...pull, check: "constructor" }).filter((t) => t.startsWith("Checks"))).toEqual([]);
87 expect(drawn({ ...pull, check: "failed" })).toContain(`Pull #3: ${CHECK_WORDS.failed}`);
88 expect(drawn({ ...pull, check: "cancelled" })).toContain("Pull #3: cancelled");
89 expect(drawn({ ...pull, check: "bogus" }).filter((t) => t.startsWith("Pull"))).toEqual(["Pull #3"]);
90 expect(drawn({ ...pull, check: "constructor" }).filter((t) => t.startsWith("Pull"))).toEqual(["Pull #3"]);
9191 expect(drawn(pull).some((t) => /^(Checks|No checks)/.test(t))).toBe(false);
9292 // Production, even handed a check, names the app and says no check.
9393 const prod = drawn({ app: "notes", env: "production", check: "passed" });
test/apps-pill-freshness.test.ts +2 −2
@@ -269,14 +269,14 @@ describe("the pill's script draws the freshness line", () => {
269269 ];
270270 for (const [extra, said] of cases) {
271271 const lines = panelLines({ ...base, ...extra });
272 expect(lines.slice(0, 4)).toEqual(["site", "Preview of pull #7: Add a thing", "Environment: preview", said]);
272 expect(lines.slice(0, 4)).toEqual(["site", "Pull #7", "Environment: preview", said]);
273273 expect(lines.filter((l) => words.includes(l as never))).toEqual([said]);
274274 }
275275 });
276276
277277 test("the line follows the pull when there is no title", () => {
278278 const lines = panelLines({ ...base, title: "", state: "merged" });
279 expect(lines.slice(0, 4)).toEqual(["site", "Preview of pull #7", "Environment: preview", FRESHNESS_WORDS.merged]);
279 expect(lines.slice(0, 4)).toEqual(["site", "Pull #7", "Environment: preview", FRESHNESS_WORDS.merged]);
280280 });
281281
282282 test("merged and closed win over deploying and behind; deploying wins over behind", () => {
test/apps-toolbar.test.ts +3 −3
@@ -476,19 +476,19 @@ describe("the pill's keyboard and touch behaviour", () => {
476476
477477
478478 test("on a preview with a repo the pull line links to the pull; otherwise it is plain text", () => {
479 const a = tree({ app: "notes", repo: "alice/notes", pull: "12" }).lines.find((l) => l.textContent === "Preview of pull #12")!;
479 const a = tree({ app: "notes", repo: "alice/notes", pull: "12" }).lines.find((l) => l.textContent === "Pull #12")!;
480480 expect(a.tag).toBe("a");
481481 expect(a.href).toBe("https://forge.test/alice/notes/pulls/12");
482482 expect(a.style.cssText).toContain("min-height:44px");
483483 const prod = tree({ app: "notes", repo: "alice/notes", env: "production", pull: "12" });
484 expect(prod.lines.some((l) => l.textContent.startsWith("Preview of pull #"))).toBe(false);
484 expect(prod.lines.some((l) => l.textContent.startsWith("Pull #"))).toBe(false);
485485 expect(prod.lines.some((l) => l.textContent === "production")).toBe(true);
486486 // An unknown environment with no pull draws no environment line at all.
487487 const unknown = tree({ app: "notes", repo: "alice/notes", env: "staging" });
488488 expect(unknown.lines.some((l) => l.textContent === "production" || l.textContent.startsWith("preview"))).toBe(false);
489489 for (const bad of [{ pull: "12x" }, { pull: "../1" }, { pull: "1234567890" }, { repo: "" }]) {
490490 const t = tree({ app: "notes", repo: "alice/notes", pull: "12", ...bad });
491 const l = t.lines.find((x) => x.textContent.startsWith("Preview of pull #"))!;
491 const l = t.lines.find((x) => x.textContent.startsWith("Pull #"))!;
492492 expect(l.tag === "a").toBe(false);
493493 }
494494 });
test/lost-journey.test.ts +2 −2
@@ -231,7 +231,7 @@ describe("lost journey: where you are and three exits", () => {
231231 expect(focusable(home)).toBe(true);
232232 expect(home.href).toBe(`${origin}/`);
233233
234 const pullLink = run.built.find((e) => e.tag === "a" && String(e.textContent).startsWith(`Preview of pull #${pull}`))!;
234 const pullLink = run.built.find((e) => e.tag === "a" && String(e.textContent).startsWith(`Pull #${pull}`))!;
235235 expect(focusable(pullLink)).toBe(true);
236236 expect(pullLink.href).toBe(`${origin}/alice/public/pulls/${pull}`);
237237
@@ -274,7 +274,7 @@ describe("lost journey: where you are and three exits", () => {
274274 expect(tag[2]).toContain(` data-env="pull-${pull}"`);
275275 expect(tag[2]).toContain(` data-pull="${pull}"`);
276276 const run = await boot(html, await crewOf(host), `http://${host}/`);
277 expect(run.built.find((e) => e.tag === "a" && String(e.textContent).startsWith(`Preview of pull #${pull}`))!.href).toBe(`${new URL(servers.url).origin}/alice/public/pulls/${pull}`);
277 expect(run.built.find((e) => e.tag === "a" && String(e.textContent).startsWith(`Pull #${pull}`))!.href).toBe(`${new URL(servers.url).origin}/alice/public/pulls/${pull}`);
278278 expect(run.named("Home")).toBeDefined();
279279 expect(run.named("Tell the crew")).toBeUndefined();
280280 // Comment goes to the forge's own page, which asks the stranger to sign in there.
test/toolbar-injection.test.ts +1 −1
@@ -86,6 +86,6 @@ test("the pill overlays the page: fixed, out of flow, in a shadow root", () => {
8686 });
8787
8888 test("on a preview the pill links to the pull's forge page in plain words", () => {
89 expect(toolbarJs).toContain('"Preview of pull #"');
89 expect(toolbarJs).toContain('"Pull #"');
9090 expect(toolbarJs).toContain('"/pulls/"');
9191 });
test/toolbar-pull-state.test.ts added +68
@@ -0,0 +1,68 @@
1 /**
2 * The toolbar's pull line says "Pull #N: checking | green | red", links to the pull, reads state at
3 * load only (#14051).
4 */
5 import { expect, test } from "bun:test";
6 import { toolbarJs, withToolbar } from "../src/apps/toolbar.ts";
7
8 const page = new TextEncoder().encode("<html><body><p>hi</p></body></html>");
9 const tag = (check: string, pull = 12) =>
10 new TextDecoder().decode(
11 withToolbar(page, "https://forge.test", { app: "notes", repo: "alice/notes", env: `pull-${pull}`, pull, check: check as any }),
12 );
13
14 const calls = { fetch: [] as string[], setInterval: 0 };
15
16 function line(markup: string): { textContent: string; href?: string } | undefined {
17 const data: Record<string, string> = {};
18 for (const m of /<script ([^>]*)>/.exec(markup)![1]!.matchAll(/data-([a-z]+)="([^"]*)"/g)) data[m[1]!] = m[2]!;
19 calls.fetch = []; calls.setInterval = 0;
20 const made: any[] = [];
21 const el = (t: string): any => ({
22 tag: t, style: {}, dataset: {}, children: [], textContent: "",
23 appendChild(c: any) { return c; }, setAttribute() {}, addEventListener() {}, classList: { add() {}, remove() {} },
24 attachShadow() { return el("shadow"); },
25 });
26 const doc: any = {
27 referrer: "", currentScript: { src: "/__forge/t.js", dataset: data },
28 createElement: (t: string) => { const e = el(t); made.push(e); return e; },
29 addEventListener() {}, body: el("body"), documentElement: el("html"),
30 };
31 const win: any = { location: { origin: "https://app.test", pathname: "/" }, addEventListener() {}, matchMedia: () => ({ matches: false }) };
32 new Function("window", "document", "location", "localStorage", "fetch", "URL", "setTimeout", "setInterval", "requestAnimationFrame", toolbarJs)(
33 win, doc, win.location, { getItem: () => null, setItem() {} }, (u: string) => { calls.fetch.push(String(u)); return new Promise(() => {}); }, URL, () => 0, () => { calls.setInterval++; return 0; }, () => 0);
34 return made.find((e) => /^Pull #\d+/.test(e.textContent));
35 }
36
37 for (const [check, word] of [["running", "checking"], ["passed", "green"], ["failed", "red"]] as const) {
38 test(`${check} reads "Pull #12: ${word}" and links to the pull`, () => {
39 const l = line(tag(check));
40 expect(l!.textContent).toBe(`Pull #12: ${word}`);
41 expect(l!.href).toBe("https://forge.test/alice/notes/pulls/12");
42 });
43 }
44
45 test("production has no pull line", () => {
46 const out = new TextDecoder().decode(withToolbar(page, "https://forge.test", { app: "notes", repo: "alice/notes", env: "production" }));
47 expect(line(out)).toBeUndefined();
48 });
outdated

This does not prove 'no polling'. Spy on setInterval and fetch in the harness and assert neither is called while the pull line is drawn, and assert a hostile data-check draws no line.

49
50 test("drawing the line neither polls nor fetches the pull's state", () => {
51 expect(line(tag("running"))).toBeDefined();
52 // The pill's one crew lookup at load is not the pull's state; nothing asks for the pull or its
53 // check.
54 expect(calls.fetch.filter((u) => /pull|check/i.test(u))).toEqual([]);
55 expect(calls.setInterval).toBe(0);
56 });
57
58 test("a hostile state is escaped in the tag and draws no state word", () => {
59 const out = tag(`"><img src=x>`);
60 expect(out).not.toContain(`"><img`);
61 expect(line(out)!.textContent).toBe("Pull #12");
62 });
63
64 test("one link names the pull, and no separate checks row is drawn", () => {
65 const rows = (() => { const out = tag("passed"); return out; })();
66 expect(line(rows)!.textContent).toBe("Pull #12: green");
67 expect(toolbarJs).not.toContain("Checks passed");
68 });
test/toolbar-pull.test.ts +2 −2
@@ -26,7 +26,7 @@ function lines(markup: string): { tag: string; textContent: string; href?: strin
2626 const win: any = { location: { origin: "https://app.test", pathname: "/" }, addEventListener() {}, matchMedia: () => ({ matches: false }) };
2727 new Function("window", "document", "location", "localStorage", "fetch", "URL", "setTimeout", "setInterval", "requestAnimationFrame", toolbarJs)(
2828 win, doc, win.location, { getItem: () => null, setItem() {} }, () => new Promise(() => {}), URL, () => 0, () => 0, () => 0);
29 return made.filter((e) => e.textContent.startsWith("Preview of pull #"));
29 return made.filter((e) => e.textContent.startsWith("Pull #"));
3030 }
3131
3232 test("a preview response carries the pull number and a link to the pull", () => {
@@ -34,7 +34,7 @@ test("a preview response carries the pull number and a link to the pull", () =>
3434 expect(out).toContain('data-pull="12"');
3535 const [link] = lines(out);
3636 expect(link!.tag).toBe("a");
37 expect(link!.textContent).toBe("Preview of pull #12: Add lists");
37 expect(link!.textContent).toBe("Pull #12");
3838 expect(link!.href).toBe("https://forge.test/alice/notes/pulls/12");
3939 });
4040
test/toolbar-where.test.ts +1 −1
@@ -157,7 +157,7 @@ const form = (made: any[]) => made.find((e) => e.tag === "form" && e.listeners.s
157157
158158 test("the preview's panel names the pull with its title, linked, and has one comment form once opened", () => {
159159 const { made, open } = panel(preview);
160 const link = made.find((e) => e.tag === "a" && e.textContent === "Preview of pull #1: Add lists");
160 const link = made.find((e) => e.tag === "a" && e.textContent === "Pull #1");
161161 expect(link.href).toBe("https://forge.test/alice/notes/pulls/1");
162162 // The form is not in the pill: a closed panel has fetched nothing for it.
163163 expect(made.some((e) => e.tag === "textarea" && e.rows === 2)).toBe(false);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs