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

/templates says what each template holds before you start from it: its top files and what its forge.json runs #13876

Merged opened this

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

Merged

scout/forge:scout/13855-templates-says-what-each-template-holds → main 6 commits fork 3 threads · 3 unresolved

  • Merged. scout/13855-templates-says-what-each-template-holds was merged into main as fdac61b.

Review

Sign in to review this change.
7 files changed +223 −6
docs/features/README.md +1
@@ -20,6 +20,7 @@ Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
2020 - [First week: three steps on a new forge's home](first-week.md)
2121 - [A hosted forge proposes to its parent once the parent has handed it a credential](propose-to-parent.md)
2222 - [How long the last forge from a template took, at /templates/<name>](template-timing.md)
23 - [What a template holds: its files, run and check lines, on /templates](template-holds.md)
2324 - [A look in the feed](feed-look.md)
2425 - [One step deeper from a post](feed-depth.md)
2526 - [A fork's page finds its place in the tree](fork-tree-here.md)
docs/features/template-holds.md added +17
@@ -0,0 +1,17 @@
1 # What a template holds
2
3 Before you start a forge from a template, `/templates` shows what it holds as three rows under its name:
4 **Files** (its top-level files, folders ending in `/`, at most 12, then "and N more"), **Run** (the `run` line of its
5 `forge.json`) and **Check** (its `check` line). A row the `forge.json` does not say is left out. Blank says it holds no
6 files. A template repository that has no commits, or cannot be read, says "Contents not available."
7
8 What was read is kept on the running forge, keyed by the template's default-branch tip: a page costs one ref read until
9 the template changes, then it is read again.
10
11 Try it: open `/templates` and read the rows under Starter app.
12
13 The terminal (both doors): the **App templates** screen (admin). Put the cursor on a marked
14 template and its lines (apps, starter budget, model default) now end with `Files:`, `Run:` and `Check:`, from the same
15 `templateHolds` the page uses.
16
17 Pinned by `test/templates-page.test.ts` and `test/tui-app-templates.test.ts`.
src/spawn/template_holds.ts added +106
@@ -0,0 +1,106 @@
1 /**
2 * What a template holds, to check before starting from it (#13855): its top-level files (at most
3 * 12, then "and N more") and the `run` and `check` lines of its forge.json. The starter's are its
4 * baked files; a template repository is read at its default branch. What was read is kept on the
5 * app, keyed by the branch tip, so a request costs one ref read until the template changes. A
6 * repository that cannot be read says so.
7 */
8
9 import type { App } from "../app.ts";
10 import { bakedFiles } from "../apps/template.ts";
11 import { getRepo } from "../core/repos.ts";
12 import { blobForRender, listTree, refTip } from "../git/read.ts";
13 import { repoDir } from "../git/repos.ts";
14 import { DEFAULT_TEMPLATE, repoTemplateRef } from "./templates.ts";
15
16 export const HOLDS_FILES_MAX = 12;
17 export const HOLDS_BLANK = "Holds no files.";
18 export const HOLDS_NONE = "Contents not available.";
19
20 export interface TemplateHolds {
21 /** Top-level names, a folder ending in `/`; at most `HOLDS_FILES_MAX`. */
22 readonly files: readonly string[];
23 /** How many more there are beyond `files`. */
24 readonly more: number;
25 readonly run: string | undefined;
26 readonly check: string | undefined;
27 }
28
29 const line = (v: unknown): string | undefined =>
30 typeof v === "string" && v.trim() !== "" && v.length <= 200 && !/[\u0000-\u001f\u007f]/.test(v) ? v.trim() : undefined;
31
32 /** The top-level names of a path list, folders first, cut to the limit. Pure. */
33 export function topLevel(paths: readonly string[]): { files: string[]; more: number } {
34 const seen = new Set<string>();
35 for (const p of paths) {
36 const i = p.indexOf("/");
37 seen.add(i === -1 ? p : `${p.slice(0, i)}/`);
38 }
39 const all = [...seen].sort((a, b) => Number(b.endsWith("/")) - Number(a.endsWith("/")) || a.localeCompare(b));
40 return { files: all.slice(0, HOLDS_FILES_MAX), more: Math.max(0, all.length - HOLDS_FILES_MAX) };
41 }
42
43 /** The `run` and `check` lines a forge.json text declares; anything else is unsaid. Pure. */
44 export function runLines(forgeJson: string | undefined): { run: string | undefined; check: string | undefined } {
45 try {
46 const raw: unknown = forgeJson === undefined ? undefined : JSON.parse(forgeJson);
47 const o = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : {};
48 const app = typeof o["app"] === "object" && o["app"] !== null ? (o["app"] as Record<string, unknown>) : {};
49 const check = typeof o["check"] === "object" && o["check"] !== null ? (o["check"] as Record<string, unknown>) : {};
50 return { run: line(app["run"]) ?? line(o["run"]), check: line(check["run"]) ?? line(o["check"]) };
51 } catch {
52 return { run: undefined, check: undefined };
53 }
54 }
55
56 const text = (c: string | Uint8Array | null | undefined): string | undefined =>
57 c === null || c === undefined ? undefined : typeof c === "string" ? c : new TextDecoder().decode(c);
58
59 const starterHolds = (): TemplateHolds => {
60 const files = bakedFiles({ name: "app", description: "" });
61 return { ...topLevel(files.map((f) => f.path)), ...runLines(text(files.find((f) => f.path === "forge.json")?.content)) };
62 };
63
64 async function readTip(dir: string, tip: string): Promise<TemplateHolds | undefined> {
65 try {
66 const tree = await listTree(dir, tip, "");
67 if (!tree.ok) return undefined;
68 const names = tree.value.map((e) => (e.type === "tree" ? `${e.name}/` : e.name));
69 const blob = await blobForRender(dir, tip, "forge.json", 64 * 1024);
70 return { ...topLevel(names), ...runLines(blob.kind === "text" ? new TextDecoder().decode(blob.body) : undefined) };
71 } catch {
72 return undefined;
73 }
74 }
75
76 /** Per forge, per template: the tip that was read and what it held. */
77 const kept = new WeakMap<App, Map<string, { tip: string; holds: TemplateHolds | undefined }>>();
78
79 /** What one template holds; undefined when it cannot be read, and for blank (which holds none). */
80 export async function templateHolds(app: App, id: string): Promise<TemplateHolds | undefined> {
81 if (id === DEFAULT_TEMPLATE) return undefined;
82 if (id === "starter") return starterHolds();
83 const ref = repoTemplateRef(id);
84 if (ref === undefined) return undefined;
85 const [owner = "", name = ""] = ref.split("/");
86 const repo = getRepo(app.db, owner, name);
87 if (!repo) return undefined;
88 const dir = repoDir(app.reposRoot, repo.ownerName, repo.name);
89 const tip = await refTip(dir, `refs/heads/${repo.defaultBranch}`).catch(() => undefined);
90 if (tip === undefined) return undefined;
91 let mine = kept.get(app);
92 if (mine === undefined) kept.set(app, (mine = new Map()));
93 const hit = mine.get(id);
94 if (hit !== undefined && hit.tip === tip) return hit.holds;
95 const holds = await readTip(dir, tip);
96 mine.set(id, { tip, holds });
97 return holds;
98 }
99
100 /** The holds as label and value rows, in the order the page and the terminal show them. */
101 export function holdsRows(h: TemplateHolds): { label: string; value: string; code: boolean }[] {
102 const rows = [{ label: "Files", value: `${h.files.join(", ")}${h.more > 0 ? ` and ${h.more} more` : ""}`, code: false }];
103 if (h.run !== undefined) rows.push({ label: "Run", value: h.run, code: true });
104 if (h.check !== undefined) rows.push({ label: "Check", value: h.check, code: true });
105 return rows;
106 }
src/tui/screens/app_templates.ts +4 −2
@@ -9,6 +9,7 @@
99
1010 import { MARK_TEMPLATE_ERRORS, markTemplate } from "../../actions/app_templates.ts";
1111 import { templateFactsOf } from "../../web/template_card.ts";
12 import { holdsRows, templateHolds } from "../../spawn/template_holds.ts";
1213 import { templateRows, type TemplateFacts } from "../../spawn/template_facts.ts";
1314 import { DEFAULT_TEMPLATE, markedTemplates } from "../../core/app_templates.ts";
1415 import type { Ctx, Screen } from "../app/app.ts";
@@ -33,8 +34,9 @@ export function appTemplatesScreen(f: Session, ctx: Ctx): Screen {
3334 const repo = markedTemplates(f.db).find((r) => `${r.ownerName}/${r.name}` === name);
3435 if (repo === undefined) return;
3536 gets.set(name, []);
36 void templateFactsOf(f.app, repo).then((facts: TemplateFacts) => {
37 gets.set(name, templateRows(facts).map((r) => `${r.label}: ${r.value}`));
37 void Promise.all([templateFactsOf(f.app, repo), templateHolds(f.app, name)]).then(([facts, holds]: [TemplateFacts, Awaited<ReturnType<typeof templateHolds>>]) => {
38 const held = holds === undefined ? ["Contents not available."] : holdsRows(holds).map((r) => `${r.label}: ${r.value}`);

Non-blocking: use HOLDS_NONE from template_holds.ts rather than repeating the sentence.

39 gets.set(name, [...templateRows(facts).map((r) => `${r.label}: ${r.value}`), ...held]);
3840 ctx.invalidate();
3941 }, () => gets.delete(name));
4042 };
src/web/pages/templates.ts +18 −3
@@ -7,6 +7,8 @@
77
88 import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts";
99 import type { Ctx } from "../../http/context.ts";
10 import { DEFAULT_TEMPLATE } from "../../spawn/templates.ts";
11 import { HOLDS_BLANK, HOLDS_NONE, holdsRows, templateHolds, type TemplateHolds } from "../../spawn/template_holds.ts";
1012 import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts";
1113 import { pageHead } from "../chrome.ts";
1214 import { html, type Html } from "../html.ts";
@@ -17,8 +19,18 @@ export const TEMPLATES_WORDS = "Pick where your forge starts. You can change eve
1719
1820 export const TEMPLATES_NONE = "No template matches that name.";
1921
22 /** What one template holds, as `dl` rows; null for an id the list does not know (the 404 page). */
outdated

Doc comment for templateRows now sits on holdsView; restore it and document holdsView separately.

23 function holdsView(id: string, holds: TemplateHolds | undefined, known: boolean): Html | null {
24 if (id === DEFAULT_TEMPLATE) return html`<p class="small muted holds">${HOLDS_BLANK}</p>`;
25 if (!known) return null;
26 if (holds === undefined) return html`<p class="small muted holds">${HOLDS_NONE}</p>`;
27 return html`<dl class="status-rows small muted holds">
28 ${holdsRows(holds).map((r) => html`<div class="status-row"><dt>${r.label}</dt><dd>${r.code ? html`<code>${r.value}</code>` : r.value}</dd></div>`)}
outdated

Principle 7: Files/run/check are facts; render as dl rows rather than paragraphs. Principle 8: 'contents not available' should be a sentence.

29 </dl>`;
30 }
31
2032 /** The rows: one sentence and one button each. The unknown-template 404 shows the same list. */
21 export function templateRows(rows: readonly TemplateRow[]): Html {
33 export function templateRows(rows: readonly TemplateRow[], held?: ReadonlyMap<string, TemplateHolds | undefined>): Html {
2234 return html`<ul class="plain" id="templates">
2335 ${rows.map(
2436 (r) => html`<li data-template="${r.id}">
@@ -27,17 +39,20 @@ export function templateRows(rows: readonly TemplateRow[]): Html {
2739 <span><b>${r.title}</b> ${r.says}</span>
2840 ${btn(`Start a forge from ${r.title}`, { variant: "secondary" })}
2941 </form>
42 ${held === undefined ? null : holdsView(r.id, held.get(r.id), held.has(r.id))}
3043 </li>`,
3144 )}
3245 </ul>`;
3346 }
3447
35 export function templatesPage(ctx: Ctx): Response {
48 export async function templatesPage(ctx: Ctx): Promise<Response> {
3649 const user = ctx.auth.user;
3750 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
3851 const q = (ctx.url.searchParams.get("q") ?? "").trim().slice(0, TEMPLATES_QUERY_MAX);
3952 const all = timePhase(ctx.request, "reads", () => templateList(ctx.app.db, user?.kind === "user" ? user : undefined));
4053 const rows = filterTemplates(all, q);
54 const held = new Map<string, TemplateHolds | undefined>();
55 await Promise.all(rows.map(async (r) => held.set(r.id, await templateHolds(ctx.app, r.id))));
4156 return timePhase(ctx.request, "render", () =>
4257 page({
4358 ctx,
@@ -51,7 +66,7 @@ export function templatesPage(ctx: Ctx): Response {
5166 </form>
5267 ${rows.length === 0
5368 ? html`<p class="muted" id="templates-none" role="status">${TEMPLATES_NONE} <a href="/templates">Show all templates</a></p>`
54 : templateRows(rows)}
69 : templateRows(rows, held)}
5570 </div>`,
5671 }),
5772 );
test/templates-page.test.ts +75 −1
@@ -9,7 +9,7 @@ import { join } from "node:path";
99 import { createApp, type App } from "../src/app.ts";
1010 import { createRepo } from "../src/core/repos.ts";
1111 import { createSession } from "../src/core/sessions.ts";
12 import { createUser } from "../src/core/users.ts";
12 import { createUser, getUserByName } from "../src/core/users.ts";
1313 import { serve, type Servers } from "../src/http/server.ts";
1414 import { templateList } from "../src/spawn/template_list.ts";
1515
@@ -97,3 +97,77 @@ test("a stranger who stumbles on the form keeps the template; the refusal keeps
9797 expect(res.status).toBeGreaterThanOrEqual(400);
9898 expect(await res.text()).toMatch(/<option\s+value="starter"\s+selected/);
9999 });
100
101 test("the starter's files and run lines are dl rows; blank says it holds none", async () => {
102 const text = await (await fetch(`${servers.url}/templates`)).text();
103 const starter = text.slice(text.indexOf('data-template="starter"'));
104 expect(starter).toContain("<dt>Files</dt>");
105 expect(starter).toContain("<dt>Run</dt><dd><code>bun run src/server.ts</code></dd>");
106 expect(starter).toContain("<dt>Check</dt><dd><code>bun scripts/egress-check.ts &amp;&amp; bun test</code></dd>");
107 expect(text.slice(text.indexOf('data-template="blank"'), text.indexOf('data-template="starter"'))).toContain("Holds no files.");
108 });
109
110 const author = { name: "t", email: "[email protected]" };
111
112 async function templateRepo(name: string, files: { path: string; content: string }[] | undefined): Promise<string> {
113 const { commitFiles } = await import("../src/git/write.ts");
114 const { repoDir } = await import("../src/git/repos.ts");
115 const owner = "tomas";
116 if (getUserByName(app.db, owner) === undefined) {
117 const u = await createUser(app.db, { origin: "seed", trusted: true, username: owner, email: "[email protected]", password: "a-good-passphrase" });
118 if (!u.ok) throw new Error("user");
119 }
120 const id = getUserByName(app.db, owner)!.id;
121 const r = await createRepo(app.db, app.reposRoot, { ownerId: id, name, visibility: "public", description: "", defaultBranch: "main" });
122 if (!r.ok) throw new Error("repo");
123 app.db.query("UPDATE repo SET is_template = 1 WHERE name = ?1").run(name);
124 if (files !== undefined) await commitFiles(repoDir(app.reposRoot, owner, name), { branch: "main", message: "files", files, author });
125 return `${owner}/${name}`;
126 }
127
128 const row = async (id: string): Promise<string> => {
129 const text = await (await fetch(`${servers.url}/templates`)).text();
130 return text.slice(text.indexOf(`data-template="${id}"`));
131 };
132
133 test("a template repository lists at most 12 files, then how many more, with its run and check lines", async () => {
134 const { topLevel, runLines } = await import("../src/spawn/template_holds.ts");
135 const many = Array.from({ length: 15 }, (_, i) => `f${String(i).padStart(2, "0")}.txt`);
136 expect(topLevel(many)).toEqual({ files: many.slice(0, 12), more: 3 });
137 expect(topLevel(["a/b/c", "a/d", "z"])).toEqual({ files: ["a/", "z"], more: 0 });
138 expect(runLines('{"run":"bun x.ts","check":"bun test"}')).toEqual({ run: "bun x.ts", check: "bun test" });
139 expect(runLines("nope")).toEqual({ run: undefined, check: undefined });
140
141 const files = Array.from({ length: 14 }, (_, i) => ({ path: `f${String(i).padStart(2, "0")}.txt`, content: "x" }));
142 const id = await templateRepo("full-kit", [...files, { path: "forge.json", content: JSON.stringify({ app: { run: "bun serve.ts" }, check: { run: "bun test <x>" } }) }]);
143 const text = await row(id);
144 expect(text).toContain("and 3 more");
145 expect(text).toContain("<dt>Run</dt><dd><code>bun serve.ts</code></dd>");
146 expect(text).toContain("<dt>Check</dt><dd><code>bun test &lt;x&gt;</code></dd>");
147 });
148
149 test("a template repository with no forge.json lists its files and no run or check row", async () => {
150 const id = await templateRepo("plain-kit", [{ path: "README.md", content: "hi" }]);
151 const text = (await row(id)).split("</li>")[0]!;
152 expect(text).toContain("<dt>Files</dt><dd>README.md</dd>");
153 expect(text).not.toContain("<dt>Run</dt>");
154 expect(text).not.toContain("<dt>Check</dt>");
155 });
156
157 test("a template repository with no commits says its contents are not available", async () => {
158 const id = await templateRepo("empty-kit", undefined);
159 const text = (await row(id)).split("</li>")[0]!;
160 expect(text).toContain("Contents not available.");
161 expect(text).not.toContain("<dt>");
162 });
163
164 test("what was read is kept while the tip stands and read again when it moves", async () => {
165 const { commitFiles } = await import("../src/git/write.ts");
166 const { repoDir } = await import("../src/git/repos.ts");
167 const { templateHolds } = await import("../src/spawn/template_holds.ts");
168 const id = await templateRepo("moving-kit", [{ path: "a.txt", content: "1" }]);
169 const first = await templateHolds(app, id);
170 expect(await templateHolds(app, id)).toBe(first);
171 await commitFiles(repoDir(app.reposRoot, "tomas", "moving-kit"), { branch: "main", message: "more", files: [{ path: "b.txt", content: "2" }], author });
172 expect((await templateHolds(app, id))?.files).toEqual(["a.txt", "b.txt"]);
173 });
test/tui-app-templates.test.ts +2
@@ -193,6 +193,8 @@ describe("what a template gets, under the cursor", () => {
193193 expect(text()).toContain("App: notes: Notes");
194194 expect(text()).toContain("App: board");
195195 expect(text()).toContain("Starter budget: $5");
196 expect(text()).toContain("Files: forge.json, README.md");
197 expect(text()).toContain("Run: x");
196198 });
197199 markTemplate(app, admin, "giver/kit", false);
198200 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs