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

Merged opened this

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

Merged

scout/forge:scout/14505-a-template-s-one-line-description-on-tem → main 3 commits fork 2 threads · 2 unresolved

  • Merged. scout/14505-a-template-s-one-line-description-on-tem was merged into main as 6521495.

Review

Sign in to review this change.
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";
1212 import { truncate, wrap } from "../term/width.ts";
1313 import type { Session } from "../session.ts";
1414 import { listChildrenNow } from "../../actions/spawn.ts";
15 import { withReadmeSays } from "../../spawn/template_says.ts";
1516 import { templateUse, useWords } from "../../spawn/template_use.ts";
1617 import { newForgeScreen } from "./newforge.ts";
1718
@@ -21,7 +22,13 @@ export function templatesScreen(session: Session, ctx: Ctx): Screen {
2122 let typing = false;
2223 // Read once when the screen opens: a keypress must not hit the disk.
2324 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) => {

The result replaces listed but 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.

28 listed = r;
29 ctx.invalidate();
30 });
31 const rows = () => filterTemplates(listed, q);
2532 return {
2633 title: "Templates",
2734 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";
1111 import { DEFAULT_TEMPLATE } from "../../spawn/templates.ts";
1212 import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds } from "../../spawn/template_holds.ts";
1313 import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts";
14 import { withReadmeSays } from "../../spawn/template_says.ts";
1415 import { templateUse, useWords, type TemplateUse } from "../../spawn/template_use.ts";
1516 import { pageHead } from "../chrome.ts";
1617 import { html, type Html } from "../html.ts";
@@ -52,7 +53,8 @@ export async function templatesPage(ctx: Ctx): Promise<Response> {
5253 const user = ctx.auth.user;
5354 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
5455 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.

5658 const rows = filterTemplates(all, q);
5759 const held = new Map<string, TemplateHolds | undefined>();
5860 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![badge](x.png)\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(/&amp;&quot;&#39;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";
77 import { tmpdir } from "node:os";
88 import { join } from "node:path";
99 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";
1112 import { createUser, type User } from "../src/core/users.ts";
1213 import { createForgeApp } from "../src/tui/forge.ts";
1314 import { templatesScreen } from "../src/tui/screens/templates.ts";
@@ -22,7 +23,7 @@ let otto: User;
2223 beforeAll(async () => {
2324 dir = await mkdtemp(join(tmpdir(), "forge-templates-tui-"));
2425 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 });
2627 const b = await createUser(app.db, { origin: "seed", trusted: true, username: "otto", email: "[email protected]", password: "a-good-passphrase" });
2728 if (!a.ok || !b.ok) throw new Error("no users");
2829 tess = a.value;
@@ -132,3 +133,20 @@ test("the selected row says how many forges it started, read once when the scree
132133 expect(t.tui.screen.toText()).toContain("2 forges started, newest 2026-11-05");
133134 t.tui.stop?.();
134135 });
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs