Public: anyone can read this; the crew can change it.
/templates shows how many forges each template started and its newest start #14475
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14460-templates-shows-how-many-forges-each-tem → main 4 commits fork 2 threads · 2 unresolved
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"; | ||
| 11 | 11 | import { style } from "../term/style.ts"; |
| 12 | 12 | import { truncate, wrap } from "../term/width.ts"; |
| 13 | 13 | import type { Session } from "../session.ts"; |
| 14 | import { listChildrenNow } from "../../actions/spawn.ts"; | |
| 15 | import { templateUse, useWords } from "../../spawn/template_use.ts"; | |
| 14 | 16 | import { newForgeScreen } from "./newforge.ts"; |
| 15 | 17 | |
| 16 | 18 | export function templatesScreen(session: Session, ctx: Ctx): Screen { |
| 17 | 19 | let at = 0; |
| 18 | 20 | let q = ""; |
| 19 | 21 | let typing = false; |
| 22 | // Read once when the screen opens: a keypress must not hit the disk. | |
| 23 | const used = templateUse(listChildrenNow(session.app)); | |
| 20 | 24 | const rows = () => filterTemplates(templateList(session.app.db, session.user), q); |
| 21 | 25 | return { |
| 22 | 26 | title: "Templates", |
| @@ -32,7 +36,7 @@ export function templatesScreen(session: Session, ctx: Ctx): Screen { | ||
| 32 | 36 | const on = i === at; |
| 33 | 37 | 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); |
| 34 | 38 | y += 1; |
| 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); | |
| 36 | 40 | }); |
| 37 | 41 | if (session.user === undefined && y < area.y + area.h) |
| 38 | 42 | 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 @@ | ||
| 7 | 7 | |
| 8 | 8 | import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts"; |
| 9 | 9 | import type { Ctx } from "../../http/context.ts"; |
| 10 | import { listChildren } from "../../actions/spawn.ts"; | |
| 10 | 11 | import { DEFAULT_TEMPLATE } from "../../spawn/templates.ts"; |
| 11 | 12 | import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds } from "../../spawn/template_holds.ts"; |
| 12 | 13 | import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts"; |
| 14 | import { templateUse, useWords, type TemplateUse } from "../../spawn/template_use.ts"; | |
| 13 | 15 | import { pageHead } from "../chrome.ts"; |
| 14 | 16 | import { html, type Html } from "../html.ts"; |
| 15 | 17 | import { page } from "../layout.ts"; |
| @@ -30,7 +32,7 @@ function holdsView(id: string, holds: TemplateHolds | undefined, known: boolean) | ||
| 30 | 32 | } |
| 31 | 33 | |
| 32 | 34 | /** 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 { | |
| 34 | 36 | return html`<ul class="plain" id="templates"> |
| 35 | 37 | ${rows.map( |
| 36 | 38 | (r) => html`<li data-template="${r.id}"> |
| @@ -39,6 +41,7 @@ export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<st | ||
| 39 | 41 | <span><b>${r.title}</b> ${r.says}</span> |
| 40 | 42 | ${btn(`Start a forge from ${r.title}`, { variant: "secondary" })} |
| 41 | 43 | </form> |
| 44 | ${used === undefined ? null : html`<p class="small muted">${useWords(used.get(r.id))}</p>`} | |
outdated
Principle 3/8: drop the unused |
||
| 42 | 45 | ${held === undefined ? null : holdsView(r.id, held.get(r.id), held.has(r.id))} |
| 43 | 46 | </li>`, |
| 44 | 47 | )} |
| @@ -53,6 +56,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> { | ||
| 53 | 56 | const rows = filterTemplates(all, q); |
| 54 | 57 | const held = new Map<string, TemplateHolds | undefined>(); |
| 55 | 58 | 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)); | |
| 56 | 60 | return timePhase(ctx.request, "render", () => |
| 57 | 61 | page({ |
| 58 | 62 | ctx, |
| @@ -66,7 +70,7 @@ export async function templatesPage(ctx: Ctx): Promise<Response> { | ||
| 66 | 70 | </form> |
| 67 | 71 | ${rows.length === 0 |
| 68 | 72 | ? 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)} | |
| 70 | 74 | </div>`, |
| 71 | 75 | }), |
| 72 | 76 | ); |
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 @@ | ||
| 3 | 3 | * New forge with it chosen. |
| 4 | 4 | */ |
| 5 | 5 | 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"; | |
| 7 | 7 | import { tmpdir } from "node:os"; |
| 8 | 8 | import { join } from "node:path"; |
| 9 | 9 | 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 () = | ||
| 111 | 111 | expect(t.tui.screen.toText()).toContain("Share: /templates/starter"); |
| 112 | 112 | t.tui.stop?.(); |
| 113 | 113 | }); |
| 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 | }); |
new above
offline
Untested terminal door, and used() reads the ledger synchronously per render. Hoist it and add a test.