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

The forge toolbar in a running app names the release it serves and when it shipped #14115

Merged opened this

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

Merged

mason/forge:mason/14101-the-forge-toolbar-in-a-running-app-names → main 4 commits fork 3 threads · 3 unresolved

  • Merged. mason/14101-the-forge-toolbar-in-a-running-app-names was merged into main as 833230e.

Review

Sign in to review this change.
8 files changed +122 −15
docs/features/forge-toolbar.md +1 −1
@@ -11,7 +11,7 @@ preview), so you always know where you are and can get back to the forge.
1111 "Preview of pull #N" to the pull's page on the forge; Home goes to the forge.
1212 - **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.
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`.
14 - **Which commit:** one more line, `Serving a1b2c3d, live 4 min ago`, the short
14 - **Which commit:** one more line, `Serving a1b2c3d`, then `Live since 4 min ago` (its title is the exact UTC time; ` · behind main` follows on production when its default branch has moved on, from `data-lagging`), the short
1515 id linked to the commit on the forge. The id and the instant come from the
1616 forge's own record of the running environment (the same source as the note's
1717 build), never the client's; they travel as escaped `data-commit` and
src/apps/pill_behind.ts added +14
@@ -0,0 +1,14 @@
1 /**
2 * Whether production serves a commit older than its default branch's tip: one loose-ref read
3 * (or the cached packed-refs), never a git process, so the toolbar's request path stays cheap.
4 */
5 import { readTipSync } from "../git/tip.ts";
6
7 /**
8 * The default branch's name when the commit served is not its tip; undefined when current or
9 * unknown.
10 */
11 export function behindDefault(repoDir: string, defaultBranch: string, servedOid: string): string | undefined {
12 const tip = readTipSync(repoDir, `refs/heads/${defaultBranch}`);
13 return tip !== undefined && tip !== servedOid ? defaultBranch : undefined;
14 }
src/apps/proxy.ts +7
@@ -76,6 +76,8 @@ import { liveOf } from "../perf/live.ts";
7676 import { heldBy, noteRelayWait, stallTiming } from "./relay_wait.ts";
7777 import { stepsOf } from "../core/review_steps.ts";
7878 import { TOUR_ASSET_PATH, tourResponse } from "./tour.ts";
79 import { behindDefault } from "./pill_behind.ts";
80 import { repoDir } from "../git/repos.ts";
7981 import { cspNonce, htmlAnswer, readPage, rewritable, TOOLBAR_ASSET_PATH, TOOLBAR_ASSET_PREFIX, toolbarResponse, withToolbar, type PillWhere } from "./toolbar.ts";
8082 import { COMMENT_ASSET_PATH, commentResponse } from "./toolbar_comment.ts";
8183
@@ -600,6 +602,11 @@ export function pillWhere(
600602 where.serving = { oid: live.commitOid, at: liveAt };
601603 const change = live?.commitOid === undefined ? undefined : landedChange(runtime.app, target.app.id, target.env, live.commitOid);
602604 if (where.serving !== undefined && change !== undefined) where.serving.change = change;
605 // Production behind its default branch: one loose-ref read, never git.
606 if (where.serving !== undefined && target.env === "production") {
607 const behind = behindDefault(repoDir(runtime.app.reposRoot, repo.ownerName, repo.name), repo.defaultBranch, where.serving.oid);

Untested branch: add a pillWhere test for production (behind set / unset) and a preview (never set). The loosened toMatchObject in toolbar-serving.test.ts hides this.

608 if (behind !== undefined) where.serving.behind = behind;
609 }
603610 const number = /^pull-(\d+)$/.exec(target.env)?.[1];
604611 if (number === undefined) return where;
605612 where.pull = Number(number);
src/apps/toolbar.ts +7 −2
@@ -98,6 +98,7 @@ const toolbarSource = `(function () {
9898 el.textContent = text;
9999 el.style.cssText = "overflow-wrap:anywhere;" + (bold ? "font-weight:600" : "opacity:.85");
100100 panel.appendChild(el);
101 return el;
101102 }
102103 if (d.app) line(d.app, true);
103104 if (d.env === "production") line("production");
@@ -160,7 +161,8 @@ const toolbarSource = `(function () {
160161 }
161162 if (cl) sv.appendChild(cl); else part(short);
162163 panel.appendChild(sv);
163 line("live \\u00b7 " + (d.change || "no change yet") + " \\u00b7 " + liveAgo);
164 var lv = line("Live since " + liveAgo + (d.change ? " \\u00b7 " + d.change : "") + (d.lagging ? " \\u00b7 behind " + d.lagging : ""));
165 lv.title = new Date(d.live).toUTCString();

Title is set but nothing asserts it; make the test helper element expose title and assert the UTC string. Also guard a missing or invalid d.live so this line does not throw RangeError.

164166 }
165167 var link = document.createElement("a");
166168 link.textContent = "Home";
@@ -728,7 +730,7 @@ export type PillWhere = {
728730 * The commit the environment is serving and the instant it went live, from the forge's own
729731 * record.
730732 */
731 serving?: { oid: string; at: string; change?: string };
733 serving?: { oid: string; at: string; change?: string; behind?: string };
732734 /** The pull carries a review script: its preview adds the guided review (`apps/tour.ts`). */
733735 tour?: TourWhere;
734736 };
@@ -794,6 +796,9 @@ export function toolbarTag(
794796 ["commit", where.serving?.oid],
795797 ["live", where.serving?.at],
796798 ["change", where.serving?.change],
799 // data-lagging: production serves a commit older than its default branch; data-behind
800 // (below) is the preview behind its pull.
801 ["lagging", where.serving?.behind],
797802 ["behind", where.behind === true ? "1" : undefined],
798803 ["deploying", where.deploying === true ? "1" : undefined],
799804 ["waits", where.waits === true ? PREVIEW_WAITS : undefined],
test/apps-toolbar-state.test.ts +11 −5
@@ -19,19 +19,25 @@ test("the change rides in the tag, escaped", () => {
1919 expect(tag).not.toContain("<b>");
2020 });
2121
22 test("no landed change leaves the attribute out and the pill says there is none yet", () => {
22 test("no landed change leaves the attribute out and the pill says only since when", () => {
2323 expect(toolbarTag("https://forge.test", where())).not.toContain("data-change");
2424 const set = { app: "notes", env: "production", repo: "alice/notes", forge: "https://forge.test", commit: oid, live: new Date(Date.now() - 4 * 60000 - 5000).toISOString() };
25 expect(boot(null, 400, 800, set).texts()).toContain("live \u00b7 no change yet \u00b7 4 min ago");
26 expect(boot(null, 400, 800, { ...set, change: "Fix <b>the</b> thing" }).texts()).toContain("live \u00b7 Fix <b>the</b> thing \u00b7 4 min ago");
25 expect(boot(null, 400, 800, set).texts()).toContain("Live since 4 min ago");
26 expect(boot(null, 400, 800, { ...set, change: "Fix <b>the</b> thing" }).texts()).toContain("Live since 4 min ago \u00b7 Fix <b>the</b> thing");
2727 });
2828
29 // The script's size at the commit this change branched from (bfb7e8dc2), pinned so the delta is
30 // real.
31 const BASE_SCRIPT_BYTES = 22623;
32
2933 test("the addition stays under 300 bytes", () => {
30 const line = toolbarJs.slice(toolbarJs.indexOf('line("live'), toolbarJs.indexOf('line("live') + 200).split("\n")[0]!;
31 expect(Buffer.byteLength(line)).toBeLessThan(300);
34 expect(Buffer.byteLength(toolbarJs) - BASE_SCRIPT_BYTES).toBeLessThan(300);
3235 const tag = toolbarTag("https://forge.test", where("x".repeat(CHANGE_MAX)), "p", "n");
3336 const bare = toolbarTag("https://forge.test", where(), "p", "n");
3437 expect(Buffer.byteLength(tag) - Buffer.byteLength(bare)).toBeLessThan(300);
38 const lagging = toolbarTag("https://forge.test", { ...where(), serving: { oid, at: "2026-01-01T00:00:00.000Z", behind: "main" } }, "p", "n");
39 const current = toolbarTag("https://forge.test", { ...where(), serving: { oid, at: "2026-01-01T00:00:00.000Z" } }, "p", "n");
40 expect(Buffer.byteLength(lagging) - Buffer.byteLength(current)).toBeLessThan(300);
3541 });
3642
3743 const forgeApp = {};
test/helpers/toolbar-boot.ts +2 −1
@@ -19,6 +19,7 @@ const make = (tag: string): El => ({
1919 listeners: {},
2020 hidden: false,
2121 textContent: "",
22 title: "",
2223 attrs: {} as Record<string, string>,
2324 setAttribute(k: string, v: string) { this.attrs[k] = v; },
2425 removeAttribute(k: string) { delete this.attrs[k]; },
@@ -57,5 +58,5 @@ export function boot(store: Record<string, string> | null, width = 400, height =
5758 const box = root.children[0]!;
5859 const panel = els.find((e) => e.attrs.role === "region")!;
5960 const fire = (el: El, t: string, e: object = {}) => el.listeners[t]!.forEach((f) => f({ preventDefault() {}, type: t, ...e }));
60 return { host: host.el!, pill, box, panel, fire, texts: () => all(panel).map((e) => e.textContent).filter(Boolean) };
61 return { host: host.el!, pill, box, panel, fire, els: () => all(panel), texts: () => all(panel).map((e) => e.textContent).filter(Boolean) };
6162 }
test/toolbar-serving.test.ts +28 −6
@@ -2,14 +2,16 @@
22 * The panel says which commit the page is serving and since when, from the forge's record (#11480).
33 */
44 import { afterAll, beforeAll, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
5 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
66 import { tmpdir } from "node:os";
77 import { join } from "node:path";
88 import { createApp, type App } from "../src/app.ts";
99 import { newApp } from "../src/actions/apps.ts";
1010 import { createUser } from "../src/core/users.ts";
1111 import { getAppByRepo } from "../src/core/apps.ts";
12 import { pillWhere, type AppTarget } from "../src/apps/proxy.ts";
12 import { getRepoById } from "../src/core/repos.ts";
13 import { repoDir } from "../src/git/repos.ts";
14 import { pillWhere, type AppTarget, type GrantWho } from "../src/apps/proxy.ts";
1315 import type { AppsRuntime } from "../src/apps/runtime.ts";
1416 import { toolbarTag } from "../src/apps/toolbar.ts";
1517 import { boot } from "./helpers/toolbar-boot.ts";
@@ -29,7 +31,7 @@ test("with a record the panel says the short id, linked to the commit, and how l
2931 const { texts, anchors } = line({ ...base, commit: OID, live: ago(4 * 60000 + 5000) });
3032 expect(texts).toContain("Serving ");
3133 expect(texts).toContain("a1b2c3d");
32 expect(texts).toContain("live \u00b7 no change yet \u00b7 4 min ago");
34 expect(texts).toContain("Live since 4 min ago");
3335 expect(anchors.find((a) => a.textContent === "a1b2c3d")?.href).toBe(`https://forge.test/alice/notes/commit/${OID}`);
3436 });
3537
@@ -49,16 +51,36 @@ test("the tag carries the record as escaped attributes, and an app name with mar
4951 expect(line({ ...base, app: evil, commit: OID, live: ago(1000) }).texts).toContain(evil);
5052 });
5153
52 test("pillWhere takes the commit and time from the runtime's record, for a reader only", () => {
54 test("pillWhere takes the commit and time from the runtime's record, for a reader only", async () => {
55 await setTip(OID);
5356 const status = { state: "running", commitOid: OID, servingAt: "2026-01-01T00:00:00.000Z" };
54 const w = (st: unknown, who?: unknown) =>
55 pillWhere({ app: fake.app, envStatus: () => st } as unknown as AppsRuntime, fake.target, who as never);
57 const w = (st: unknown, who?: GrantWho) =>
58 pillWhere({ app: fake.app, envStatus: () => st } as unknown as AppsRuntime, fake.target, who);
5659 expect(w(status).serving).toEqual({ oid: OID, at: "2026-01-01T00:00:00.000Z" });
5760 expect(w(undefined).serving).toBeUndefined();
5861 expect(w({ ...status, state: "deploying" }).serving).toBeUndefined();
5962 });
6063
6164
65 /** Points the production repository's default branch at one commit, as a push would. */
66 async function setTip(oid: string): Promise<string> {
67 const repo = getRepoById(fake.app.db, fake.target.app.repoId)!;
68 const gitDir = repoDir(fake.app.reposRoot, repo.ownerName, repo.name);
69 await mkdir(join(gitDir, "refs/heads"), { recursive: true });
70 await writeFile(join(gitDir, "refs/heads", repo.defaultBranch), oid + "\n");
71 return repo.defaultBranch;
72 }
73
74 test("pillWhere marks production behind its default branch only when the tip differs, never a preview", async () => {
75 const status = { state: "running", commitOid: OID, servingAt: "2026-01-01T00:00:00.000Z" };
76 const w = (env: string) => pillWhere({ app: fake.app, envStatus: () => status } as unknown as AppsRuntime, { ...fake.target, env } as AppTarget, undefined);
77 const branch = await setTip("b".repeat(40));
78 expect(w("production").serving?.behind).toBe(branch);
79 expect(w("pull-7").serving?.behind).toBeUndefined();
80 await setTip(OID);
81 expect(w("production").serving?.behind).toBeUndefined();
82 });
83
6284 const fake = {} as { app: App; target: AppTarget };
6385 let dir = "";
6486 beforeAll(async () => {
test/toolbar-since.test.ts added +52
@@ -0,0 +1,52 @@
1 /**
2 * The production pill says when the release went live, and says so when it is behind its default
3 * branch (#14101).
4 */
5 import { expect, test } from "bun:test";
6 import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { behindDefault } from "../src/apps/pill_behind.ts";
10 import { toolbarTag } from "../src/apps/toolbar.ts";
11 import { boot } from "./helpers/toolbar-boot.ts";
12
13 const old = "a".repeat(40);
14 const tip = "b".repeat(40);
15 const dir = mkdtempSync(join(tmpdir(), "forge-behind-"));
16 mkdirSync(join(dir, "refs/heads"), { recursive: true });
17 writeFileSync(join(dir, "refs/heads/main"), tip + "\n");
18
19 test("a current app is not behind; an older one names the branch", () => {
20 expect(behindDefault(dir, "main", tip)).toBeUndefined();
21 expect(behindDefault(dir, "main", old)).toBe("main");
22 expect(behindDefault(dir, "nope", old)).toBeUndefined();
23 });
24
25 test("the tag carries the clause only when behind", () => {
26 const at = "2026-11-15T10:00:00Z";
27 expect(toolbarTag("https://forge.test", { app: "n", env: "production", serving: { oid: old, at } })).not.toContain("data-lagging");
28 expect(toolbarTag("https://forge.test", { app: "n", env: "production", serving: { oid: old, at, behind: "main" } })).toContain('data-lagging="main"');
29 });
30
31 test("the pill reads 'Live since', the exact time in the title, and one clause when behind", () => {
32 const live = new Date(Date.now() - 3 * 3600_000).toISOString();
33 const set = { app: "n", env: "production", repo: "a/n", forge: "https://forge.test", commit: old, live };
34 expect(boot(null, 400, 800, set).texts()).toContain("Live since 3 h ago");
35 expect(boot(null, 400, 800, { ...set, lagging: "main" }).texts()).toContain("Live since 3 h ago · behind main");
outdated

Assert the title here, and a case with no change plus behind, for box 2 wording.

36 });
37
38 test("the line's title is the exact UTC time; with no change and behind, only 'behind' follows", () => {
39 const live = "2026-11-15T10:00:00.000Z";
40 const set = { app: "n", env: "production", repo: "a/n", forge: "https://forge.test", commit: old, live, lagging: "main" };
41 const el = boot(null, 400, 800, set).els().find((e) => e.textContent.startsWith("Live since"))!;
42 expect(el.title).toBe(new Date(live).toUTCString());
43 expect(el.title).toBe("Sun, 15 Nov 2026 10:00:00 GMT");
44 expect(el.textContent.endsWith(" · behind main")).toBe(true);
45 expect(el.textContent).not.toContain("no change");
46 });
47
48 test("an invalid time leaves the serving line out instead of throwing", () => {
49 const set = { app: "n", env: "production", repo: "a/n", forge: "https://forge.test", commit: old, live: "not a date" };
50 expect(() => boot(null, 400, 800, set)).not.toThrow();
51 expect(boot(null, 400, 800, set).texts().some((t) => t.startsWith("Live since"))).toBe(false);
52 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs