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

/templates shows how many forges each template started and its newest start #14475

Merged opened this

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

Merged

torque/forge:torque/14460-templates-shows-how-many-forges-each-tem → main 4 commits fork 2 threads · 2 unresolved

  • Merged. torque/14460-templates-shows-how-many-forges-each-tem was merged into main as 9382a03.

Review

Sign in to review this change.
6 files changed +145 −4
docs/features/template-use.md added +10
@@ -0,0 +1,10 @@
1 ---
2 topic: Your apps
3 row: See how many forges each template started
4 ---
5 # Template use
6
7 Each card on `/templates` says `N forges started, newest YYYY-MM-DD`, or `not used yet`. The counts come from this forge's spawn records (the ledger, one read of `listChildren`), grouped by template in one pass; a forge made without a template counts for Blank. A record counts once the start has begun (finished or not): "started" means begun, so a start still in progress or one that failed part-way is in the count. Only counts and a date are shown, never a forge's name or owner.
8
9 - **Terminal:** `/templates` shows the same sentence under the selected row (`useWords`), read once when the screen opens. Test: `test/templates-tui.test.ts`.
10 - Code: `src/spawn/template_use.ts`, `src/web/pages/templates.ts`, `src/tui/screens/templates.ts`. Test: `test/template-use.test.ts`.
src/spawn/template_use.ts added +41
@@ -0,0 +1,41 @@
1 /**
2 * How often each template was used: forges started from it and the newest start, counted from the
3 * spawn records (the ledger, `listChildren`). Plain data in, plain data out: counts only, never a
4 * forge's name or owner. A record with no template is a blank forge (`DEFAULT_TEMPLATE`).
5 */
6
7 import { DEFAULT_TEMPLATE } from "./templates.ts";
8
9 export interface TemplateUse {
10 readonly count: number;
11 /** When the newest start began, ISO; null when no record of it says. */
12 readonly newest: string | null;
13 }
14
15 /** The slice of a spawn record this reads. */
16 export interface StartRecord {
17 readonly template?: string;
18 readonly createdAt: string | null;
19 }
20
21 /** One pass over the records: use by template id. A template with no start is absent. */
22 export function templateUse(records: readonly StartRecord[]): Map<string, TemplateUse> {
23 const out = new Map<string, TemplateUse>();
24 for (const r of records) {
25 const id = r.template ?? DEFAULT_TEMPLATE;
26 const was = out.get(id);
27 const at = r.createdAt !== null && !Number.isNaN(Date.parse(r.createdAt)) ? r.createdAt : null;
28 const newest = was?.newest == null || (at !== null && Date.parse(at) > Date.parse(was.newest)) ? (at ?? was?.newest ?? null) : was.newest;
29 out.set(id, { count: (was?.count ?? 0) + 1, newest });
30 }
31 return out;
32 }
33
34 export const NOT_USED_YET = "not used yet";
35
36 /** The card's sentence: `N forges started, newest 2026-11-02`, or `not used yet`. */
37 export function useWords(u: TemplateUse | undefined): string {
38 if (u === undefined || u.count === 0) return NOT_USED_YET;
39 const n = `${u.count} ${u.count === 1 ? "forge" : "forges"} started`;
40 return u.newest === null ? n : `${n}, newest ${new Date(u.newest).toISOString().slice(0, 10)}`;
41 }
src/tui/screens/templates.ts +5 −1
@@ -11,12 +11,16 @@ import { binding } from "../app/keys.ts";
1111 import { style } from "../term/style.ts";
1212 import { truncate, wrap } from "../term/width.ts";
1313 import type { Session } from "../session.ts";
14 import { listChildrenNow } from "../../actions/spawn.ts";
15 import { templateUse, useWords } from "../../spawn/template_use.ts";
1416 import { newForgeScreen } from "./newforge.ts";
1517
1618 export function templatesScreen(session: Session, ctx: Ctx): Screen {
1719 let at = 0;
1820 let q = "";
1921 let typing = false;
22 // Read once when the screen opens: a keypress must not hit the disk.
23 const used = templateUse(listChildrenNow(session.app));
2024 const rows = () => filterTemplates(templateList(session.app.db, session.user), q);
2125 return {
2226 title: "Templates",
@@ -32,7 +36,7 @@ export function templatesScreen(session: Session, ctx: Ctx): Screen {
3236 const on = i === at;
3337 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);
3438 y += 1;
outdated

Untested terminal door, and used() reads the ledger synchronously per render. Hoist it and add a test.

35 if (on) for (const line of [...wrap(r.says, area.w - 6), ...(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);
39 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);
3640 });
3741 if (session.user === undefined && y < area.y + area.h)
3842 s.text(area.x + 1, y + 1, truncate("Sign in to start a forge from one, or use /templates on the web.", area.w - 2), style(c.mutedFg, c.bg), area.x + area.w);
src/web/pages/templates.ts +6 −2
@@ -7,9 +7,11 @@
77
88 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
99 import type { Ctx } from "../../http/context.ts";
10 import { listChildren } from "../../actions/spawn.ts";
1011 import { DEFAULT_TEMPLATE } from "../../spawn/templates.ts";
1112 import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds } from "../../spawn/template_holds.ts";
1213 import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts";
14 import { templateUse, useWords, type TemplateUse } from "../../spawn/template_use.ts";
1315 import { pageHead } from "../chrome.ts";
1416 import { html, type Html } from "../html.ts";
1517 import { page } from "../layout.ts";
@@ -30,7 +32,7 @@ function holdsView(id: string, holds: TemplateHolds | undefined, known: boolean)
3032 }
3133
3234 /** The rows: one sentence and one button each. The unknown-template 404 shows the same list. */
33 export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<string, TemplateHolds | undefined>): Html {
35 export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<string, TemplateHolds | undefined>, used?: ReadonlyMap<string, TemplateUse>): Html {
3436 return html`<ul class="plain" id="templates">
3537 ${rows.map(
3638 (r) => html`<li data-template="${r.id}">
@@ -39,6 +41,7 @@ export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<st
3941 <span><b>${r.title}</b> ${r.says}</span>
4042 ${btn(`Start a forge from ${r.title}`, { variant: "secondary" })}
4143 </form>
44 ${used === undefined ? null : html`<p class="small muted">${useWords(used.get(r.id))}</p>`}
outdated

Principle 3/8: drop the unused uses class; reuse small muted only.

4245 ${held === undefined ? null : holdsView(r.id, held.get(r.id), held.has(r.id))}
4346 </li>`,
4447 )}
@@ -53,6 +56,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> {
5356 const rows = filterTemplates(all, q);
5457 const held = new Map<string, TemplateHolds | undefined>();
5558 await Promise.all(rows.map(async (r) => held.set(r.id, await templateHolds(ctx.app, r.id))));
59 const used = templateUse(await listChildren(ctx.app));
5660 return timePhase(ctx.request, "render", () =>
5761 page({
5862 ctx,
@@ -66,7 +70,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> {
6670 </form>
6771 ${rows.length === 0
6872 ? html`<p class="muted" id="templates-none" role="status">${TEMPLATES_NONE} <a href="/templates">Show all templates</a></p>`
69 : templateRows(rows, held)}
73 : templateRows(rows, held, used)}
7074 </div>`,
7175 }),
7276 );
test/template-use.test.ts added +61
@@ -0,0 +1,61 @@
1 /** /templates says how many forges each template started and the newest start (#14460). */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { serve, type Servers } from "../src/http/server.ts";
8 import { templateUse, useWords } from "../src/spawn/template_use.ts";
9
10 let dir: string;
11 let app: App;
12 let servers: Servers;
13
14 const ledger = (name: string, template: string | undefined, createdAt: string) =>
15 writeFile(join(dir, "spawn", `${name}.json`), JSON.stringify({ name, bodyId: `b${name}`, done: true, createdAt, forWhom: "secret-person", ...(template ? { template } : {}) }));
16
17 beforeAll(async () => {
18 dir = await mkdtemp(join(tmpdir(), "forge-tpluse-"));
19 app = createApp({ dataDir: dir, url: "https://forge.test", port: 0 });
20 servers = await serve(app);
21 await mkdir(join(dir, "spawn"), { recursive: true });
22 await ledger("one", "starter", "2026-11-01T10:00:00.000Z");
23 await ledger("many-a", "blank", "2026-10-01T10:00:00.000Z");
24 await ledger("many-b", undefined, "2026-11-05T10:00:00.000Z");
25 await ledger("many-c", "blank", "2026-10-20T10:00:00.000Z");
26 }, 30_000);
27
28 afterAll(async () => {
29 servers.stop();
30 app.close();
31 await rm(dir, { recursive: true, force: true });
32 });
33
34 test("words for zero, one and many", () => {
35 expect(useWords(undefined)).toBe("not used yet");
36 expect(useWords({ count: 1, newest: "2026-11-01T10:00:00.000Z" })).toBe("1 forge started, newest 2026-11-01");
37 expect(useWords({ count: 3, newest: "2026-11-05T10:00:00.000Z" })).toBe("3 forges started, newest 2026-11-05");
38 });
39
40 test("the reader groups by template and keeps the newest", () => {
41 const m = templateUse([
42 { template: "a/b", createdAt: "2026-01-01T00:00:00Z" },
43 { template: "a/b", createdAt: "2026-03-01T00:00:00Z" },
44 { template: "a/b", createdAt: null },
45 { createdAt: null },
46 ]);
47 expect(m.get("a/b")).toEqual({ count: 3, newest: "2026-03-01T00:00:00Z" });
48 expect(m.get("blank")).toEqual({ count: 1, newest: null });
49 });
50
51 test("the page shows zero, one and many, and no names", async () => {
52 const text = await (await fetch(`${servers.url}/templates`)).text();
53 const card = (id: string) => text.split(`data-template="${id}"`)[1]!.split("</li>")[0]!;
54 expect(card("starter")).toContain("1 forge started, newest 2026-11-01");
55 expect(card("blank")).toContain("3 forges started, newest 2026-11-05");
56 expect(text).not.toContain("secret-person");
57 expect(text).not.toContain("many-a");
58 await rm(join(dir, "spawn", "one.json"));
59 const after = await (await fetch(`${servers.url}/templates`)).text();
60 expect(after.split('data-template="starter"')[1]!.split("</li>")[0]!).toContain("not used yet");
61 });
test/templates-tui.test.ts +22 −1
@@ -3,7 +3,7 @@
33 * New forge with it chosen.
44 */
55 import { afterAll, beforeAll, expect, test } from "bun:test";
6 import { mkdtemp, rm } from "node:fs/promises";
6 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
77 import { tmpdir } from "node:os";
88 import { join } from "node:path";
99 import { createApp, type App } from "../src/app.ts";
@@ -111,3 +111,24 @@ test("the selected row prints its share path, as the page's own URL", async () =
111111 expect(t.tui.screen.toText()).toContain("Share: /templates/starter");
112112 t.tui.stop?.();
113113 });
114
115 test("the selected row says how many forges it started, read once when the screen opens", async () => {
116 await mkdir(join(dir, "spawn"), { recursive: true });
117 const rec = (name: string, template: string, createdAt: string) => writeFile(join(dir, "spawn", `${name}.json`), JSON.stringify({ name, bodyId: `b${name}`, done: true, createdAt, template }));
118 await rec("a", "starter", "2026-11-01T10:00:00.000Z");
119 await rec("b", "starter", "2026-11-05T10:00:00.000Z");
120 const t = open(otto);
121 await settleApp(t.tui);
122 expect(t.tui.screen.toText()).toContain("not used yet"); // Blank is selected
123 t.screen.key(key("j"));
124 t.tui.ctx.invalidate();
125 await settleApp(t.tui);
126 expect(t.tui.screen.toText()).toContain("2 forges started, newest 2026-11-05");
127 await rec("c", "starter", "2026-11-09T10:00:00.000Z"); // after the open: not re-read on a keypress
128 t.screen.key(key("k"));
129 t.screen.key(key("j"));
130 t.tui.ctx.invalidate();
131 await settleApp(t.tui);
132 expect(t.tui.screen.toText()).toContain("2 forges started, newest 2026-11-05");
133 t.tui.stop?.();
134 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs