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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14101-the-forge-toolbar-in-a-running-app-names → main 4 commits fork 3 threads · 3 unresolved
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. | ||
| 11 | 11 | "Preview of pull #N" to the pull's page on the forge; Home goes to the forge. |
| 12 | 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. |
| 13 | 13 | - **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 | |
| 15 | 15 | id linked to the commit on the forge. The id and the instant come from the |
| 16 | 16 | forge's own record of the running environment (the same source as the note's |
| 17 | 17 | 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"; | ||
| 76 | 76 | import { heldBy, noteRelayWait, stallTiming } from "./relay_wait.ts"; |
| 77 | 77 | import { stepsOf } from "../core/review_steps.ts"; |
| 78 | 78 | import { TOUR_ASSET_PATH, tourResponse } from "./tour.ts"; |
| 79 | import { behindDefault } from "./pill_behind.ts"; | |
| 80 | import { repoDir } from "../git/repos.ts"; | |
| 79 | 81 | import { cspNonce, htmlAnswer, readPage, rewritable, TOOLBAR_ASSET_PATH, TOOLBAR_ASSET_PREFIX, toolbarResponse, withToolbar, type PillWhere } from "./toolbar.ts"; |
| 80 | 82 | import { COMMENT_ASSET_PATH, commentResponse } from "./toolbar_comment.ts"; |
| 81 | 83 | |
| @@ -600,6 +602,11 @@ export function pillWhere( | ||
| 600 | 602 | where.serving = { oid: live.commitOid, at: liveAt }; |
| 601 | 603 | const change = live?.commitOid === undefined ? undefined : landedChange(runtime.app, target.app.id, target.env, live.commitOid); |
| 602 | 604 | 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); | |
| 608 | if (behind !== undefined) where.serving.behind = behind; | |
| 609 | } | |
| 603 | 610 | const number = /^pull-(\d+)$/.exec(target.env)?.[1]; |
| 604 | 611 | if (number === undefined) return where; |
| 605 | 612 | where.pull = Number(number); |
src/apps/toolbar.ts +7 −2
| @@ -98,6 +98,7 @@ const toolbarSource = `(function () { | ||
| 98 | 98 | el.textContent = text; |
| 99 | 99 | el.style.cssText = "overflow-wrap:anywhere;" + (bold ? "font-weight:600" : "opacity:.85"); |
| 100 | 100 | panel.appendChild(el); |
| 101 | return el; | |
| 101 | 102 | } |
| 102 | 103 | if (d.app) line(d.app, true); |
| 103 | 104 | if (d.env === "production") line("production"); |
| @@ -160,7 +161,8 @@ const toolbarSource = `(function () { | ||
| 160 | 161 | } |
| 161 | 162 | if (cl) sv.appendChild(cl); else part(short); |
| 162 | 163 | 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. |
||
| 164 | 166 | } |
| 165 | 167 | var link = document.createElement("a"); |
| 166 | 168 | link.textContent = "Home"; |
| @@ -728,7 +730,7 @@ export type PillWhere = { | ||
| 728 | 730 | * The commit the environment is serving and the instant it went live, from the forge's own |
| 729 | 731 | * record. |
| 730 | 732 | */ |
| 731 | serving?: { oid: string; at: string; change?: string }; | |
| 733 | serving?: { oid: string; at: string; change?: string; behind?: string }; | |
| 732 | 734 | /** The pull carries a review script: its preview adds the guided review (`apps/tour.ts`). */ |
| 733 | 735 | tour?: TourWhere; |
| 734 | 736 | }; |
| @@ -794,6 +796,9 @@ export function toolbarTag( | ||
| 794 | 796 | ["commit", where.serving?.oid], |
| 795 | 797 | ["live", where.serving?.at], |
| 796 | 798 | ["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], | |
| 797 | 802 | ["behind", where.behind === true ? "1" : undefined], |
| 798 | 803 | ["deploying", where.deploying === true ? "1" : undefined], |
| 799 | 804 | ["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", () => { | ||
| 19 | 19 | expect(tag).not.toContain("<b>"); |
| 20 | 20 | }); |
| 21 | 21 | |
| 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", () => { | |
| 23 | 23 | expect(toolbarTag("https://forge.test", where())).not.toContain("data-change"); |
| 24 | 24 | 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"); | |
| 27 | 27 | }); |
| 28 | 28 | |
| 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 | ||
| 29 | 33 | 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); | |
| 32 | 35 | const tag = toolbarTag("https://forge.test", where("x".repeat(CHANGE_MAX)), "p", "n"); |
| 33 | 36 | const bare = toolbarTag("https://forge.test", where(), "p", "n"); |
| 34 | 37 | 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); | |
| 35 | 41 | }); |
| 36 | 42 | |
| 37 | 43 | const forgeApp = {}; |
test/helpers/toolbar-boot.ts +2 −1
| @@ -19,6 +19,7 @@ const make = (tag: string): El => ({ | ||
| 19 | 19 | listeners: {}, |
| 20 | 20 | hidden: false, |
| 21 | 21 | textContent: "", |
| 22 | title: "", | |
| 22 | 23 | attrs: {} as Record<string, string>, |
| 23 | 24 | setAttribute(k: string, v: string) { this.attrs[k] = v; }, |
| 24 | 25 | removeAttribute(k: string) { delete this.attrs[k]; }, |
| @@ -57,5 +58,5 @@ export function boot(store: Record<string, string> | null, width = 400, height = | ||
| 57 | 58 | const box = root.children[0]!; |
| 58 | 59 | const panel = els.find((e) => e.attrs.role === "region")!; |
| 59 | 60 | 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) }; | |
| 61 | 62 | } |
test/toolbar-serving.test.ts +28 −6
| @@ -2,14 +2,16 @@ | ||
| 2 | 2 | * The panel says which commit the page is serving and since when, from the forge's record (#11480). |
| 3 | 3 | */ |
| 4 | 4 | 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"; | |
| 6 | 6 | import { tmpdir } from "node:os"; |
| 7 | 7 | import { join } from "node:path"; |
| 8 | 8 | import { createApp, type App } from "../src/app.ts"; |
| 9 | 9 | import { newApp } from "../src/actions/apps.ts"; |
| 10 | 10 | import { createUser } from "../src/core/users.ts"; |
| 11 | 11 | 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"; | |
| 13 | 15 | import type { AppsRuntime } from "../src/apps/runtime.ts"; |
| 14 | 16 | import { toolbarTag } from "../src/apps/toolbar.ts"; |
| 15 | 17 | 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 | ||
| 29 | 31 | const { texts, anchors } = line({ ...base, commit: OID, live: ago(4 * 60000 + 5000) }); |
| 30 | 32 | expect(texts).toContain("Serving "); |
| 31 | 33 | 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"); | |
| 33 | 35 | expect(anchors.find((a) => a.textContent === "a1b2c3d")?.href).toBe(`https://forge.test/alice/notes/commit/${OID}`); |
| 34 | 36 | }); |
| 35 | 37 | |
| @@ -49,16 +51,36 @@ test("the tag carries the record as escaped attributes, and an app name with mar | ||
| 49 | 51 | expect(line({ ...base, app: evil, commit: OID, live: ago(1000) }).texts).toContain(evil); |
| 50 | 52 | }); |
| 51 | 53 | |
| 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); | |
| 53 | 56 | 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); | |
| 56 | 59 | expect(w(status).serving).toEqual({ oid: OID, at: "2026-01-01T00:00:00.000Z" }); |
| 57 | 60 | expect(w(undefined).serving).toBeUndefined(); |
| 58 | 61 | expect(w({ ...status, state: "deploying" }).serving).toBeUndefined(); |
| 59 | 62 | }); |
| 60 | 63 | |
| 61 | 64 | |
| 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 | ||
| 62 | 84 | const fake = {} as { app: App; target: AppTarget }; |
| 63 | 85 | let dir = ""; |
| 64 | 86 | 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 | }); |
new above
offline
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.