Public: anyone can read this; the crew can change it.
A template's one-line description on /templates is its README's first sentence, escaped and cut at 140 characters #14546
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14505-a-template-s-one-line-description-on-tem → main 3 commits fork 2 threads · 2 unresolved
6 files
changed +265
−4
docs/features/template-says.md added +19
| @@ -0,0 +1,19 @@ | ||
| 1 | --- | |
| 2 | topic: What a forge is | |
| 3 | row: A template describes itself: its README's first sentence on /templates | |
| 4 | --- | |
| 5 | # A template's own sentence | |
| 6 | ||
| 7 | On `/templates`, a template repository's one-line description is the first sentence of its `README.md`: headings, | |
| 8 | badges and code fences are skipped, links and emphasis become plain text, tags are dropped, and the sentence is cut at | |
| 9 | 140 characters with an ellipsis. A repository with no README (or nothing sayable in it) keeps the generic words. The | |
| 10 | filter box searches this sentence too. | |
| 11 | ||
| 12 | What was read is kept on the running forge, keyed by the default-branch tip, so a listing costs one ref read until the | |
| 13 | template changes. | |
| 14 | ||
| 15 | Try it: add a README.md to a marked template and open `/templates`. | |
| 16 | ||
| 17 | The terminal (both doors): the **Templates** screen shows the same sentence under the cursor, a moment after it opens. | |
| 18 | ||
| 19 | Pinned by `test/template-says.test.ts`. |
src/spawn/template_says.ts added +123
| @@ -0,0 +1,123 @@ | ||
| 1 | /** | |
| 2 | * A template repository describes itself (#14505): the first sentence of its README.md, cut at 140 | |
| 3 | * characters with an ellipsis. Markup is flattened to plain text here; the page escapes it again | |
| 4 | * on output. What was read is kept on the app, keyed by the branch tip, so a listing costs one ref | |
| 5 | * read until the template changes. No README, or nothing sayable in it, keeps the generic words. | |
| 6 | */ | |
| 7 | ||
| 8 | import type { App } from "../app.ts"; | |
| 9 | import { getRepo } from "../core/repos.ts"; | |
| 10 | import { blobForRender, refTip } from "../git/read.ts"; | |
| 11 | import { repoDir } from "../git/repos.ts"; | |
| 12 | import type { TemplateRow } from "./template_list.ts"; | |
| 13 | import { repoTemplateRef } from "./templates.ts"; | |
| 14 | ||
| 15 | export const SAYS_MAX = 140; | |
| 16 | ||
| 17 | /** | |
| 18 | * Plain text of one markdown line: images and tags dropped, links to their text, emphasis marks | |
| 19 | * gone. | |
| 20 | */ | |
| 21 | function plain(s: string): string { | |
| 22 | return s | |
| 23 | .replace(/!\[[^\]]*\]\([^)]*\)/g, "") | |
| 24 | .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") | |
| 25 | .replace(/<[^>]*>?/g, "") | |
| 26 | .replace(/[`*_~]/g, "") | |
| 27 | // biome-ignore lint: control characters are the point | |
| 28 | .replace(/[\u0000-\u001f\u007f]/g, " ") | |
| 29 | .replace(/\s+/g, " ") | |
| 30 | .trim(); | |
| 31 | } | |
| 32 | ||
| 33 | /** Abbreviations whose full stop does not end a sentence. */ | |
| 34 | const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|vs|etc|cf|approx|incl)\.$/i; | |
| 35 | ||
| 36 | /** Where the first sentence ends: after a stop followed by space or the end, not after "e.g.". */ | |
| 37 | function sentenceEnd(text: string): number { | |
| 38 | const stop = /[.!?](?=\s|$)/g; | |
| 39 | for (let m = stop.exec(text); m !== null; m = stop.exec(text)) { | |
| 40 | if (m[0] === "." && ABBREVIATION.test(text.slice(0, m.index + 1))) continue; | |
| 41 | return m.index + 1; | |
| 42 | } | |
| 43 | return text.length; | |
| 44 | } | |
| 45 | ||
| 46 | /** | |
| 47 | * The first sentence of a README, at most `SAYS_MAX` characters; undefined when there is none. | |
| 48 | * Pure. | |
| 49 | */ | |
| 50 | export function firstSentence(readme: string): string | undefined { | |
| 51 | const paragraph: string[] = []; | |
| 52 | let fenced = false; | |
| 53 | for (const raw of readme.split(/\r?\n/)) { | |
| 54 | const l = raw.trim(); | |
| 55 | if (/^(```|~~~)/.test(l)) { | |
| 56 | fenced = !fenced; | |
| 57 | continue; | |
| 58 | } | |
| 59 | if (fenced) continue; | |
| 60 | const text = /^(#{1,6}\s|[=-]{3,}$|>|\||<!--|---)/.test(l) || /^\[!?\[?[^\]]*\]\([^)]*\)$/.test(l) ? "" : plain(l); | |
| 61 | if (text === "") { | |
| 62 | if (paragraph.length > 0) break; | |
| 63 | continue; | |
| 64 | } | |
| 65 | paragraph.push(text); | |
| 66 | } | |
| 67 | const joined = paragraph.join(" "); | |
| 68 | if (joined === "") return undefined; | |
| 69 | const sentence = joined.slice(0, sentenceEnd(joined)); | |
| 70 | if (sentence.length <= SAYS_MAX) return sentence; | |
| 71 | return `${sentence.slice(0, SAYS_MAX - 1).trimEnd()}…`; | |
| 72 | } | |
| 73 | ||
| 74 | const kept = new WeakMap<App, Map<string, { tip: string; says: string | undefined }>>(); | |
| 75 | ||
| 76 | /** | |
| 77 | * The README sentence of a template repository id (`owner/name`); undefined when it cannot be had. | |
| 78 | */ | |
| 79 | export async function readmeSays(app: App, id: string): Promise<string | undefined> { | |
| 80 | const ref = repoTemplateRef(id); | |
| 81 | if (ref === undefined) return undefined; | |
| 82 | const [owner = "", name = ""] = ref.split("/"); | |
| 83 | const repo = getRepo(app.db, owner, name); | |
| 84 | if (!repo) return undefined; | |
| 85 | const dir = repoDir(app.reposRoot, repo.ownerName, repo.name); | |
| 86 | const tip = await refTip(dir, `refs/heads/${repo.defaultBranch}`).catch(() => undefined); | |
| 87 | if (tip === undefined) return undefined; | |
| 88 | let mine = kept.get(app); | |
| 89 | if (mine === undefined) kept.set(app, (mine = new Map())); | |
| 90 | const hit = mine.get(id); | |
| 91 | if (hit !== undefined && hit.tip === tip) return hit.says; | |
| 92 | const says = await blobForRender(dir, tip, "README.md", 16 * 1024) | |
| 93 | .then((b) => (b.kind === "text" ? firstSentence(new TextDecoder().decode(b.body)) : undefined)) | |
| 94 | .catch(() => undefined); | |
| 95 | mine.set(id, { tip, says }); | |
| 96 | return says; | |
| 97 | } | |
| 98 | ||
| 99 | /** At most this many README reads run at once. */ | |
| 100 | export const SAYS_PARALLEL = 4; | |
| 101 | ||
| 102 | /** | |
| 103 | * The rows with each repository template's own sentence where its README has one. Reads run a few | |
| 104 | * at a time; what is kept for ids no longer listed is dropped. | |
| 105 | */ | |
| 106 | export async function withReadmeSays(app: App, rows: readonly TemplateRow[]): Promise<TemplateRow[]> { | |
| 107 | const mine = kept.get(app); | |
| 108 | if (mine !== undefined) { | |
| 109 | const ids = new Set(rows.map((r) => r.id)); | |
| 110 | for (const id of [...mine.keys()]) if (!ids.has(id)) mine.delete(id); | |
| 111 | } | |
| 112 | const out = [...rows]; | |
| 113 | let next = 0; | |
| 114 | const worker = async () => { | |
| 115 | for (let i = next++; i < rows.length; i = next++) { | |
| 116 | const r = rows[i]!; | |
| 117 | const says = repoTemplateRef(r.id) === undefined ? undefined : await readmeSays(app, r.id); | |
| 118 | if (says !== undefined) out[i] = { ...r, says }; | |
| 119 | } | |
| 120 | }; | |
| 121 | await Promise.all(Array.from({ length: Math.min(SAYS_PARALLEL, rows.length) }, worker)); | |
| 122 | return out; | |
| 123 | } |
src/tui/screens/templates.ts +8 −1
| @@ -12,6 +12,7 @@ import { style } from "../term/style.ts"; | ||
| 12 | 12 | import { truncate, wrap } from "../term/width.ts"; |
| 13 | 13 | import type { Session } from "../session.ts"; |
| 14 | 14 | import { listChildrenNow } from "../../actions/spawn.ts"; |
| 15 | import { withReadmeSays } from "../../spawn/template_says.ts"; | |
| 15 | 16 | import { templateUse, useWords } from "../../spawn/template_use.ts"; |
| 16 | 17 | import { newForgeScreen } from "./newforge.ts"; |
| 17 | 18 | |
| @@ -21,7 +22,13 @@ export function templatesScreen(session: Session, ctx: Ctx): Screen { | ||
| 21 | 22 | let typing = false; |
| 22 | 23 | // Read once when the screen opens: a keypress must not hit the disk. |
| 23 | 24 | const used = templateUse(listChildrenNow(session.app)); |
| 24 | const rows = () => filterTemplates(templateList(session.app.db, session.user), q); | |
| 25 | // Each repository template's README sentence arrives after the first paint, then stays. | |
| 26 | let listed = templateList(session.app.db, session.user); | |
| 27 | void withReadmeSays(session.app, listed).then((r) => { | |
| 28 | listed = r; | |
| 29 | ctx.invalidate(); | |
| 30 | }); | |
| 31 | const rows = () => filterTemplates(listed, q); | |
| 25 | 32 | return { |
| 26 | 33 | title: "Templates", |
| 27 | 34 | keys: [binding(["j", "k"], "move"), ...(session.user === undefined ? [] : [binding(["enter"], "start a forge from it")]), binding(["/"], "filter by name or description"), binding(["esc"], "back")], |
src/web/pages/templates.ts +3 −1
| @@ -11,6 +11,7 @@ import { listChildren } from "../../actions/spawn.ts"; | ||
| 11 | 11 | import { DEFAULT_TEMPLATE } from "../../spawn/templates.ts"; |
| 12 | 12 | import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds } from "../../spawn/template_holds.ts"; |
| 13 | 13 | import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts"; |
| 14 | import { withReadmeSays } from "../../spawn/template_says.ts"; | |
| 14 | 15 | import { templateUse, useWords, type TemplateUse } from "../../spawn/template_use.ts"; |
| 15 | 16 | import { pageHead } from "../chrome.ts"; |
| 16 | 17 | import { html, type Html } from "../html.ts"; |
| @@ -52,7 +53,8 @@ export async function templatesPage(ctx: Ctx): Promise<Response> { | ||
| 52 | 53 | const user = ctx.auth.user; |
| 53 | 54 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 54 | 55 | const q = (ctx.url.searchParams.get("q") ?? "").trim().slice(0, TEMPLATES_QUERY_MAX); |
| 55 | const all = timePhase(ctx.request, "reads", () => templateList(ctx.app.db, user?.kind === "user" ? user : undefined)); | |
| 56 | const listed = timePhase(ctx.request, "reads", () => templateList(ctx.app.db, user?.kind === "user" ? user : undefined)); | |
| 57 | const all = await withReadmeSays(ctx.app, listed); | |
This awaits one ref read per template per request, before the filter runs. Cap the concurrency or reuse a known tip, so the page stays in milliseconds when the cache is cold. |
||
| 56 | 58 | const rows = filterTemplates(all, q); |
| 57 | 59 | const held = new Map<string, TemplateHolds | undefined>(); |
| 58 | 60 | await Promise.all(rows.map(async (r) => held.set(r.id, await templateHolds(ctx.app, r.id)))); |
test/template-says.test.ts added +92
| @@ -0,0 +1,92 @@ | ||
| 1 | /** | |
| 2 | * A template repository's one-line description is its README's first sentence, escaped and cut | |
| 3 | * (#14505). | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { commitToBranch, createRepo, updateRepoSettings } from "../src/actions/repos.ts"; | |
| 10 | import { createApp, type App } from "../src/app.ts"; | |
| 11 | import { getRepo } from "../src/core/repos.ts"; | |
| 12 | import { createUser } from "../src/core/users.ts"; | |
| 13 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 14 | import { firstSentence, SAYS_MAX } from "../src/spawn/template_says.ts"; | |
| 15 | ||
| 16 | test("firstSentence: empty, plain, markup, long", () => { | |
| 17 | expect(firstSentence("")).toBeUndefined(); | |
| 18 | expect(firstSentence("# Title\n\n\n")).toBeUndefined(); | |
| 19 | expect(firstSentence("# T\n\nA tidy kit. It has more.\n")).toBe("A tidy kit."); | |
| 20 | expect(firstSentence("**Bold** [link](http://x) and `code` here\ncontinues. Next.")).toBe("Bold link and code here continues."); | |
| 21 | expect(firstSentence("<script>alert(1)</script> Hello.")).toBe("alert(1) Hello."); | |
| 22 | const long = firstSentence(`${"word ".repeat(100)}end`)!; | |
| 23 | expect(long.length).toBe(SAYS_MAX); | |
| 24 | expect(long.endsWith("…")).toBe(true); | |
| 25 | }); | |
| 26 | ||
| 27 | let dir: string; | |
| 28 | let app: App; | |
| 29 | let servers: Servers; | |
| 30 | ||
| 31 | beforeAll(async () => { | |
| 32 | dir = await mkdtemp(join(tmpdir(), "forge-template-says-")); | |
| 33 | app = createApp({ dataDir: dir, url: "https://forge.test", port: 0, forgeRepo: "alice/forge-code" }); | |
| 34 | servers = await serve(app); | |
| 35 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "giver", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 36 | if (!made.ok) throw new Error(made.error); | |
| 37 | const make = async (name: string, readme: string | undefined) => { | |
| 38 | const repo = await createRepo(app, made.value, { name, visibility: "public", description: "" }); | |
| 39 | if (!repo.ok) throw new Error(repo.error); | |
| 40 | const files = [{ path: "server.ts", content: "x" }, { path: "forge.json", content: '{"app":{"run":"bun main.ts"}}' }, ...(readme === undefined ? [] : [{ path: "README.md", content: readme }])]; | |
| 41 | const done = await commitToBranch(app, made.value, repo.value, { message: "t", files }); | |
| 42 | if (!done.ok) throw new Error(String(done.error)); | |
| 43 | const r = await updateRepoSettings(app, made.value, getRepo(app.db, "giver", name)!, { template: true }); | |
| 44 | if (!r.ok) throw new Error(String(r.error)); | |
| 45 | }; | |
| 46 | await make("plainkit", "# Plainkit\n\nA zesty little starter. More text.\n"); | |
| 47 | await make("hostile", "<img src=x onerror=alert(1)>&<b>\"'<script>alert(2)</script>\n"); | |
| 48 | await make("nothing", undefined); | |
| 49 | await make("longkit", `# L\n\n${"word ".repeat(100)}end\n`); | |
| 50 | await make("abbrev", "Use it e.g. for a blog vs. a wiki. Then more.\n"); | |
| 51 | }, 30_000); | |
| 52 | ||
| 53 | afterAll(async () => { | |
| 54 | servers.stop(); | |
| 55 | app.close(); | |
| 56 | await rm(dir, { recursive: true, force: true }); | |
| 57 | }); | |
| 58 | ||
| 59 | const li = (text: string, id: string) => text.split("<li").find((p) => p.includes(`data-template="${id}"`)) ?? ""; | |
| 60 | ||
| 61 | test("the listing carries the README sentence; no README keeps the generic words; hostile is escaped", async () => { | |
| 62 | const text = await (await fetch(`${servers.url}/templates`)).text(); | |
| 63 | expect(li(text, "giver/plainkit")).toContain("A zesty little starter."); | |
| 64 | expect(li(text, "giver/plainkit")).not.toContain("More text"); | |
| 65 | expect(li(text, "giver/nothing")).toContain("The code and apps of that repository."); | |
| 66 | const hostile = li(text, "giver/hostile"); | |
| 67 | expect(hostile).not.toContain("<script>"); | |
| 68 | expect(hostile).not.toContain("<img"); | |
| 69 | expect(text).not.toContain("onerror=alert(1)>"); | |
| 70 | }); | |
| 71 | ||
| 72 | test("the hostile README shows as exact escaped text", async () => { | |
| 73 | const hostile = li(await (await fetch(`${servers.url}/templates`)).text(), "giver/hostile"); | |
| 74 | expect(hostile).toMatch(/&"'alert\(2\)/); | |
| 75 | }); | |
| 76 | ||
| 77 | test("a long README is cut at 140 characters through /templates", async () => { | |
| 78 | const row = li(await (await fetch(`${servers.url}/templates`)).text(), "giver/longkit"); | |
| 79 | const says = /<\/b> (word [^<]*…)/.exec(row)?.[1]; | |
| 80 | expect(says?.length).toBe(SAYS_MAX); | |
| 81 | }); | |
| 82 | ||
| 83 | test("e.g. and vs. do not end the sentence", () => { | |
| 84 | expect(firstSentence("Use it e.g. for a blog vs. a wiki. Then more.")).toBe("Use it e.g. for a blog vs. a wiki."); | |
| 85 | }); | |
| 86 | ||
| 87 | test("the filter box searches the README sentence", async () => { | |
| 88 | const text = await (await fetch(`${servers.url}/templates?q=zesty`)).text(); | |
| 89 | expect(text).toContain('data-template="giver/plainkit"'); | |
| 90 | expect(text).not.toContain('data-template="giver/nothing"'); | |
| 91 | expect(text).not.toContain('data-template="starter"'); | |
| 92 | }); |
test/templates-tui.test.ts +20 −2
| @@ -7,7 +7,8 @@ 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"; |
| 10 | import { createRepo } from "../src/core/repos.ts"; | |
| 10 | import { commitToBranch, createRepo as createRepoAction } from "../src/actions/repos.ts"; | |
| 11 | import { createRepo, getRepo } from "../src/core/repos.ts"; | |
| 11 | 12 | import { createUser, type User } from "../src/core/users.ts"; |
| 12 | 13 | import { createForgeApp } from "../src/tui/forge.ts"; |
| 13 | 14 | import { templatesScreen } from "../src/tui/screens/templates.ts"; |
| @@ -22,7 +23,7 @@ let otto: User; | ||
| 22 | 23 | beforeAll(async () => { |
| 23 | 24 | dir = await mkdtemp(join(tmpdir(), "forge-templates-tui-")); |
| 24 | 25 | app = createApp({ dataDir: dir, port: 0 }); |
| 25 | const a = await createUser(app.db, { origin: "seed", trusted: true, username: "tess", email: "[email protected]", password: "a-good-passphrase" }); | |
| 26 | const a = await createUser(app.db, { origin: "seed", trusted: true, username: "tess", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 26 | 27 | const b = await createUser(app.db, { origin: "seed", trusted: true, username: "otto", email: "[email protected]", password: "a-good-passphrase" }); |
| 27 | 28 | if (!a.ok || !b.ok) throw new Error("no users"); |
| 28 | 29 | tess = a.value; |
| @@ -132,3 +133,20 @@ test("the selected row says how many forges it started, read once when the scree | ||
| 132 | 133 | expect(t.tui.screen.toText()).toContain("2 forges started, newest 2026-11-05"); |
| 133 | 134 | t.tui.stop?.(); |
| 134 | 135 | }); |
| 136 | ||
| 137 | test("a template's README sentence appears without a keypress and is searchable", async () => { | |
| 138 | const made = await createRepoAction(app, tess, { name: "zesty-kit", visibility: "public", description: "" }); | |
| 139 | if (!made.ok) throw new Error(made.error); | |
| 140 | const done = await commitToBranch(app, tess, made.value, { message: "t", files: [{ path: "README.md", content: "# Z\n\nA zesty little starter. More.\n" }] }); | |
| 141 | if (!done.ok) throw new Error(String(done.error)); | |
| 142 | app.db.query("UPDATE repo SET is_template = 1 WHERE name = 'zesty-kit'").run(); | |
| 143 | expect(getRepo(app.db, "tess", "zesty-kit")).not.toBeNull(); | |
| 144 | const t = open(otto); | |
| 145 | for (const k of ["/", "z", "e", "s", "t", "y"]) t.screen.key(key(k)); // filter by a README word | |
| 146 | t.screen.key(key("enter")); | |
| 147 | await settleApp(t.tui); // no further key: the redraw came from the read resolving | |
| 148 | const text = t.tui.screen.toText(); | |
| 149 | expect(text).toContain("tess/zesty-kit"); | |
| 150 | expect(text).toContain("A zesty little starter."); | |
| 151 | t.tui.stop?.(); | |
| 152 | }); |
new above
offline
The result replaces
listedbut nothing asks for a redraw, so the sentence only shows after a keypress. Redraw when it resolves, and add a TUI test that pins it.