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

/templates shows each template's most recent landed change and its start count beside the name #14514

Merged opened this

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

Merged

scout/forge:scout/14492-templates-shows-each-template-s-most-rec → main 12 commits fork 3 threads · 3 unresolved

  • Merged. scout/14492-templates-shows-each-template-s-most-rec was merged into main as 926a9e0.

Review

Sign in to review this change.
8 files changed +149 −6
docs/features/template-recency.md added +9
@@ -0,0 +1,9 @@
1 ---
2 topic: Your apps
3 row: See when a template repository last changed
4 ---
5 # Template recency
6
7 A template that is a repository on this forge says `updated 3d ago` on its row at `/templates` and under the selected row of `/templates` in the terminal, from the merge time of its newest landed pull, or `no changes yet` when none has landed. Built-in templates (Blank, Starter) have no repository and show nothing. The time is the shared `<time>` element (`src/web/time_element.ts`): relative words, the exact instant in `datetime` and `title`; the terminal speaks the same `timeAgo` words.
8
9 - Code: `src/spawn/template_recent.ts`, `src/web/pages/templates.ts`, `src/tui/screens/templates.ts`, `src/web/time_element.ts`. Test: `test/templates-alive.test.ts`, `test/templates-tui.test.ts`.
src/spawn/template_recent.ts added +32
@@ -0,0 +1,32 @@
1 /**
2 * How recently each template repository changed: the merge time of its newest landed pull, one
3 * read for all of them. Built-in templates live in the forge's own code, have no repository and so
4 * no entry. Plain data in, plain data out.
5 */
6
7 import type { Database } from "bun:sqlite";
8
9 /** What a repository template with no landed pull says in place of its recency. */
10 export const NO_CHANGES_YET = "no changes yet";
11
12 /**
13 * Newest `merged_at` (ISO) by `owner/name`, for the ids given; a repository with no landed pull is
14 * absent.
15 */
16 export function templateRecency(db: Database, ids: readonly string[]): Map<string, string> {
17 const out = new Map<string, string>();
outdated

One query per template (up to 100) in the page's hot path, contradicting the docstring's 'one read for all of them'. Use one query: SELECT user.username||'/'||repo.name AS id, MAX(pull.merged_at) ... WHERE merged_at IS NOT NULL GROUP BY repo.id, then filter to the ids wanted.

18 const want = new Set(ids.filter((id) => id.includes("/")));
19 if (want.size === 0) return out;
20 const rows = db
21 .query<{ id: string; at: string }, []>(
22 `SELECT user.username || '/' || repo.name AS id, MAX(pull.merged_at) AS at FROM pull
23 JOIN issue ON issue.id = pull.issue_id
24 JOIN repo ON repo.id = issue.repo_id
25 JOIN user ON user.id = repo.owner_id
26 WHERE pull.merged_at IS NOT NULL AND repo.is_template = 1
27 GROUP BY repo.id`,
28 )
29 .all();
30 for (const r of rows) if (want.has(r.id) && !Number.isNaN(Date.parse(r.at))) out.set(r.id, r.at);
31 return out;
outdated

This duplicates the relative-time wording that src/web/time_element.ts already provides (timeAgo, time()). Render the merged time with the shared time() element on the page, and timeAgo in the terminal, and delete recencyWords. The doc's 'plain text' claim then goes too.

32 }
src/tui/screens/templates.ts +7 −1
@@ -14,14 +14,20 @@ import type { Session } from "../session.ts";
1414 import { listChildrenNow } from "../../actions/spawn.ts";
1515 import { withReadmeSays } from "../../spawn/template_says.ts";
1616 import { templateUse, useWords } from "../../spawn/template_use.ts";
17 import { NO_CHANGES_YET, templateRecency } from "../../spawn/template_recent.ts";
18 import { timeAgo } from "../../web/time_element.ts";
1719 import { newForgeScreen } from "./newforge.ts";
1820
21 /** `updated 3d ago`, in the shared clock's words, or that nothing has landed. */
22 const recencyLine = (at: string | undefined): string => (at === undefined ? NO_CHANGES_YET : `updated ${timeAgo(at)}`);
23
1924 export function templatesScreen(session: Session, ctx: Ctx): Screen {
2025 let at = 0;
2126 let q = "";
2227 let typing = false;
2328 // Read once when the screen opens: a keypress must not hit the disk.
2429 const used = templateUse(listChildrenNow(session.app));
30 const recent = templateRecency(session.app.db, templateList(session.app.db, session.user).map((r) => r.id));
2531 // Each repository template's README sentence arrives after the first paint, then stays.
2632 let listed = templateList(session.app.db, session.user);
2733 void withReadmeSays(session.app, listed).then((r) => {
@@ -43,7 +49,7 @@ export function templatesScreen(session: Session, ctx: Ctx): Screen {
4349 const on = i === at;
4450 if (y < area.y + area.h) s.text(area.x + 1, y, truncate(`${on ? "> " : " "}${r.title} (${r.id})`, area.w - 2), style(on ? c.accent : c.fg, c.bg), area.x + area.w);
4551 y += 1;
46 if (on) for (const line of [...wrap(r.says, area.w - 6), useWords(used.get(r.id)), ...(r.id === DEFAULT_TEMPLATE ? [] : [`Share: ${templatePath(r.id)}`])]) if (y < area.y + area.h) s.text(area.x + 5, y++, truncate(line, area.w - 6), style(c.mutedFg, c.bg), area.x + area.w);
52 if (on) for (const line of [...wrap(r.says, area.w - 6), [useWords(used.get(r.id)), ...(r.id.includes("/") ? [recencyLine(recent.get(r.id))] : [])].join(" · "), ...(r.id === DEFAULT_TEMPLATE ? [] : [`Share: ${templatePath(r.id)}`])]) if (y < area.y + area.h) s.text(area.x + 5, y++, truncate(line, area.w - 6), style(c.mutedFg, c.bg), area.x + area.w);
4753 });
4854 if (q === "" && noRepoTemplates(listed) && y + 1 < area.y + area.h) {
4955 s.text(area.x + 1, y + 1, truncate(session.user?.isAdmin === true ? `${TEMPLATES_EMPTY_ADMIN}: repository settings, App card.` : TEMPLATES_EMPTY, area.w - 2), style(c.mutedFg, c.bg), area.x + area.w);
src/web/pages/templates.ts +16 −3
@@ -13,10 +13,12 @@ import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds }
1313 import { filterTemplates, TEMPLATES_EMPTY, noRepoTemplates, TEMPLATES_EMPTY_ADMIN, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts";
1414 import { withReadmeSays } from "../../spawn/template_says.ts";
1515 import { templateUse, useWords, type TemplateUse } from "../../spawn/template_use.ts";
16 import { NO_CHANGES_YET, templateRecency } from "../../spawn/template_recent.ts";
1617 import { json } from "../../http/respond.ts";
1718 import { EDGE_VARY, sharedCache } from "../../http/edge_cache.ts";
1819 import { pageHead } from "../chrome.ts";
1920 import { html, type Html } from "../html.ts";
21 import { time } from "../time_element.ts";
2022 import { page } from "../layout.ts";
2123 import { previewLink } from "../template_card.ts";
2224 import { btn } from "../ui.ts";
@@ -47,8 +49,18 @@ function thumb(r: TemplateRow, src: string | undefined): Html {
4749 return html`<img class="template-thumb" src="${src}" width="64" height="40" alt="Latest look of ${r.title}" loading="lazy" decoding="async">`;
4850 }
4951
52 /**
53 * The muted line under a row: the start count and, for a repository template, its recency; each on
54 * its own.
55 */
56 function sentence(id: string, used: ReadonlyMap<string, TemplateUse> | undefined, recent: ReadonlyMap<string, string> | undefined): Html | null {
57 const at = recent?.get(id);
58 const parts: (string | Html)[] = [...(used === undefined ? [] : [useWords(used.get(id))]), ...(recent === undefined || !id.includes("/") ? [] : [at === undefined ? NO_CHANGES_YET : html`updated ${time(at)}`])];
59 return parts.length === 0 ? null : html`<p class="small muted">${parts.map((p, i) => (i === 0 ? p : html` · ${p}`))}</p>`;
60 }
61
5062 /** The rows: one sentence and one button each. The unknown-template 404 shows the same list. */
51 export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<string, TemplateHolds | undefined>, used?: ReadonlyMap<string, TemplateUse>, pictures?: ReadonlyMap<string, string>): Html {
63 export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<string, TemplateHolds | undefined>, used?: ReadonlyMap<string, TemplateUse>, recent?: ReadonlyMap<string, string>, pictures?: ReadonlyMap<string, string>): Html {
5264 return html`<ul class="plain" id="templates">
5365 ${rows.map(
5466 (r) => html`<li data-template="${r.id}">
@@ -58,7 +70,7 @@ export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<st
5870 <span><b>${r.title}</b> ${r.says}${held === undefined ? null : html` ${previewLink(r.id, r.title, held.get(r.id))}`}</span>
5971 ${btn(`Start a forge from ${r.title}`, { variant: "secondary" })}
6072 </form>
61 ${used === undefined ? null : html`<p class="small muted">${useWords(used.get(r.id))}</p>`}
73 ${sentence(r.id, used, recent)}
6274 ${held === undefined ? null : holdsView(r.id, held.get(r.id), held.has(r.id))}
6375 </li>`,
6476 )}
@@ -74,6 +86,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> {
7486 const rows = filterTemplates(all, q);
7587 const held = new Map<string, TemplateHolds | undefined>();
7688 await Promise.all(rows.map(async (r) => held.set(r.id, await templateHolds(ctx.app, r.id))));
89 const recent = templateRecency(ctx.app.db, rows.map((r) => r.id));
7790 const used = templateUse(await listChildren(ctx.app));
7891 const pictures = timePhase(ctx.request, "pictures", () => templatePictures(ctx, rows.map((r) => r.id)));
7992 return timePhase(ctx.request, "render", () =>
@@ -89,7 +102,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> {
89102 </form>
90103 ${rows.length === 0
91104 ? html`<p class="muted" id="templates-none" role="status">${TEMPLATES_NONE} <a href="/templates">Show all templates</a></p>`
92 : templateRows(rows, held, used, pictures)}
105 : templateRows(rows, held, used, recent, pictures)}
93106 ${q === "" && noRepoTemplates(listed)
94107 ? user?.isAdmin === true
95108 ? html`<p class="muted" id="templates-empty" role="status"><a href="/repos">${TEMPLATES_EMPTY_ADMIN}</a>: repository settings, App card.</p>`
test/engine-split.test.ts +6 −1
@@ -429,9 +429,14 @@ describe("a stream that resumes while the engine writes", () => {
429429 const decoder = new TextDecoder();
430430 let buffer = "";
431431 const stop = Date.now() + 400;
432 // One read in flight at a time: a read the timeout outran still holds the next chunk, and a
433 // fresh read() in its place would drop it.
434 let pending: ReturnType<typeof reader.read> | undefined;
432435 while (Date.now() < stop) {
433 const chunk = await Promise.race([reader.read(), Bun.sleep(100).then(() => undefined)]);
436 pending ??= reader.read();
437 const chunk = await Promise.race([pending, Bun.sleep(100).then(() => undefined)]); // real-timer: read timeout on a live HTTP stream
434438 if (chunk === undefined) continue;
439 pending = undefined;
435440 if (chunk.done) break;
436441 buffer += decoder.decode(chunk.value, { stream: true });
437442 let cut: number;
test/templates-alive.test.ts added +68
@@ -0,0 +1,68 @@
1 /**
2 * /templates says when a template repository last landed a change, or that it has none (#14492).
3 */
4 import { afterAll, beforeAll, expect, test } from "bun:test";
5 import { mkdtemp, rm } from "node:fs/promises";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { createApp, type App } from "../src/app.ts";
9 import { serve, type Servers } from "../src/http/server.ts";
10 import { createRepo } from "../src/core/repos.ts";
11 import { createIssue } from "../src/core/issues.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { NO_CHANGES_YET, templateRecency } from "../src/spawn/template_recent.ts";
14 import type { TemplateRow } from "../src/spawn/template_list.ts";
15 import { templateRows } from "../src/web/pages/templates.ts";
16
17 let dir: string;
18 let app: App;
19 let servers: Servers;
20
21 beforeAll(async () => {
22 dir = await mkdtemp(join(tmpdir(), "forge-tplalive-"));
23 app = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
24 servers = await serve(app);
25 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "tess", email: "[email protected]", password: "a-good-passphrase" });
26 if (!made.ok) throw new Error(made.error);
27 for (const name of ["lively-kit", "quiet-kit"]) {
28 const r = await createRepo(app.db, app.reposRoot, { ownerId: made.value.id, name, visibility: "public", description: name, defaultBranch: "main" });
29 if (!r.ok) throw new Error(r.error);
30 app.db.query("UPDATE repo SET is_template = 1 WHERE name = ?1").run(name);
31 if (name !== "lively-kit") continue;
32 const when = [new Date(Date.now() - 10 * 86400_000), new Date(Date.now() - 3 * 86400_000 - 3600_000)];
33 for (const at of when) {
34 const issue = createIssue(app.db, { repoId: r.value.id, authorId: made.value.id, title: "change", kind: "pull" });
35 if (!issue.ok) throw new Error(issue.error);
36 app.db.query(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, merged_at) VALUES (?1, 'main', 'b', '', '', ?2)`).run(issue.value.id, at.toISOString());
37 }
38 }
39 }, 30_000);
40
41 afterAll(async () => {
42 servers.stop();
43 app.close();
44 await rm(dir, { recursive: true, force: true });
45 });
46
47 test("a template with history says when it last changed; one without says so", async () => {
48 const text = await (await fetch(`${servers.url}/templates`)).text();
49 const row = (id: string) => text.split(`data-template="${id}"`)[1]!.split("</li>")[0]!;
50 expect(row("tess/lively-kit")).toMatch(/updated <time datetime="[^"]+" title="[^"]+ UTC"\s*>3d ago<\/time/);
51 expect(row("tess/quiet-kit")).toContain(NO_CHANGES_YET);
52 expect(row("tess/quiet-kit")).not.toContain("1970");
53 expect(row("starter")).not.toContain("no changes yet");
54 });
55
56 test("recency renders from `recent` alone, and not at all when it is not passed (the 404 listing)", () => {
57 const rows: TemplateRow[] = [{ id: "tess/lively-kit", title: "Lively", says: "x" }, { id: "starter", title: "Starter", says: "y" }];
58 const recent = new Map([["tess/lively-kit", "2026-11-17T00:00:00Z"]]);
59 const withRecent = String(templateRows(rows, undefined, undefined, recent));
60 expect(withRecent).toContain('updated <time datetime="2026-11-17T00:00:00.000Z"');
61 expect(withRecent.match(/no changes yet/g)).toBeNull();
62 expect(String(templateRows(rows))).not.toContain("updated");
63 });
64
65 test("one grouped read answers for many templates", () => {
66 const got = templateRecency(app.db, ["tess/lively-kit", "tess/quiet-kit", "starter", "nobody/none"]);
67 expect([...got.keys()]).toEqual(["tess/lively-kit"]);
68 });
test/templates-picture.test.ts +1 −1
@@ -81,7 +81,7 @@ test("a template with no look, and a built-in, show a box with the initial and n
8181
8282 test("the alt text is escaped", () => {
8383 const rows = [{ id: "x/y", title: '"><script>alert(1)</script>', says: "s" }];
84 const out = String(templateRows(rows, undefined, undefined, new Map([["x/y", "/p.png"]])));
84 const out = String(templateRows(rows, undefined, undefined, undefined, new Map([["x/y", "/p.png"]])));
8585 expect(out).not.toContain("<script>");
8686 expect(out).toContain('alt="Latest look of &quot;&gt;&lt;script&gt;alert(1)&lt;/script&gt;"');
8787 });
test/templates-tui.test.ts +10
@@ -134,6 +134,16 @@ test("the selected row says how many forges it started, read once when the scree
134134 t.tui.stop?.();
135135 });
136136
137 test("the selected repository template says when it last changed; a built-in says nothing of the kind", async () => {
138 const t = open(tess);
139 await settleApp(t.tui);
140 expect(t.tui.screen.toText()).not.toContain("no changes yet"); // selected row is Blank
141 for (const k of ["/", "h", "i", "d", "d", "e", "n", "enter"]) t.screen.key(key(k));
142 await settleApp(t.tui);
143 expect(t.tui.screen.toText()).toContain("no changes yet");
144 t.tui.stop?.();
145 });
146
137147 test("a template's README sentence appears without a keypress and is searchable", async () => {
138148 const made = await createRepoAction(app, tess, { name: "zesty-kit", visibility: "public", description: "" });
139149 if (!made.ok) throw new Error(made.error);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs