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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13855-templates-says-what-each-template-holds → main 6 commits fork 3 threads · 3 unresolved
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). | ||
| 20 | 20 | - [](first-week.md) |
| 21 | 21 | - [](propose-to-parent.md) |
| 22 | 22 | - [](template-timing.md) |
| 23 | - [](template-holds.md) | |
| 23 | 24 | - [](feed-look.md) |
| 24 | 25 | - [](feed-depth.md) |
| 25 | 26 | - [](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 @@ | ||
| 9 | 9 | |
| 10 | 10 | import { MARK_TEMPLATE_ERRORS, markTemplate } from "../../actions/app_templates.ts"; |
| 11 | 11 | import { templateFactsOf } from "../../web/template_card.ts"; |
| 12 | import { holdsRows, templateHolds } from "../../spawn/template_holds.ts"; | |
| 12 | 13 | import { templateRows, type TemplateFacts } from "../../spawn/template_facts.ts"; |
| 13 | 14 | import { DEFAULT_TEMPLATE, markedTemplates } from "../../core/app_templates.ts"; |
| 14 | 15 | import type { Ctx, Screen } from "../app/app.ts"; |
| @@ -33,8 +34,9 @@ export function appTemplatesScreen(f: Session, ctx: Ctx): Screen { | ||
| 33 | 34 | const repo = markedTemplates(f.db).find((r) => `${r.ownerName}/${r.name}` === name); |
| 34 | 35 | if (repo === undefined) return; |
| 35 | 36 | 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}`); | |
| 39 | gets.set(name, [...templateRows(facts).map((r) => `${r.label}: ${r.value}`), ...held]); | |
| 38 | 40 | ctx.invalidate(); |
| 39 | 41 | }, () => gets.delete(name)); |
| 40 | 42 | }; |
src/web/pages/templates.ts +18 −3
| @@ -7,6 +7,8 @@ | ||
| 7 | 7 | |
| 8 | 8 | import { notePhase, takeSessionTime, timePhase } from "../../core/route_timing.ts"; |
| 9 | 9 | 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"; | |
| 10 | 12 | import { filterTemplates, TEMPLATES_QUERY_MAX, templateList, type TemplateRow } from "../../spawn/template_list.ts"; |
| 11 | 13 | import { pageHead } from "../chrome.ts"; |
| 12 | 14 | import { html, type Html } from "../html.ts"; |
| @@ -17,8 +19,18 @@ export const TEMPLATES_WORDS = "Pick where your forge starts. You can change eve | ||
| 17 | 19 | |
| 18 | 20 | export const TEMPLATES_NONE = "No template matches that name."; |
| 19 | 21 | |
| 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 | ||
| 20 | 32 | /** 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 { | |
| 22 | 34 | return html`<ul class="plain" id="templates"> |
| 23 | 35 | ${rows.map( |
| 24 | 36 | (r) => html`<li data-template="${r.id}"> |
| @@ -27,17 +39,20 @@ export function templateRows(rows: readonly TemplateRow[]): Html { | ||
| 27 | 39 | <span><b>${r.title}</b> ${r.says}</span> |
| 28 | 40 | ${btn(`Start a forge from ${r.title}`, { variant: "secondary" })} |
| 29 | 41 | </form> |
| 42 | ${held === undefined ? null : holdsView(r.id, held.get(r.id), held.has(r.id))} | |
| 30 | 43 | </li>`, |
| 31 | 44 | )} |
| 32 | 45 | </ul>`; |
| 33 | 46 | } |
| 34 | 47 | |
| 35 | export function templatesPage(ctx: Ctx): Response { | |
| 48 | export async function templatesPage(ctx: Ctx): Promise<Response> { | |
| 36 | 49 | const user = ctx.auth.user; |
| 37 | 50 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 38 | 51 | const q = (ctx.url.searchParams.get("q") ?? "").trim().slice(0, TEMPLATES_QUERY_MAX); |
| 39 | 52 | const all = timePhase(ctx.request, "reads", () => templateList(ctx.app.db, user?.kind === "user" ? user : undefined)); |
| 40 | 53 | 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)))); | |
| 41 | 56 | return timePhase(ctx.request, "render", () => |
| 42 | 57 | page({ |
| 43 | 58 | ctx, |
| @@ -51,7 +66,7 @@ export function templatesPage(ctx: Ctx): Response { | ||
| 51 | 66 | </form> |
| 52 | 67 | ${rows.length === 0 |
| 53 | 68 | ? 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)} | |
| 55 | 70 | </div>`, |
| 56 | 71 | }), |
| 57 | 72 | ); |
test/templates-page.test.ts +75 −1
| @@ -9,7 +9,7 @@ import { join } from "node:path"; | ||
| 9 | 9 | import { createApp, type App } from "../src/app.ts"; |
| 10 | 10 | import { createRepo } from "../src/core/repos.ts"; |
| 11 | 11 | import { createSession } from "../src/core/sessions.ts"; |
| 12 | import { createUser } from "../src/core/users.ts"; | |
| 12 | import { createUser, getUserByName } from "../src/core/users.ts"; | |
| 13 | 13 | import { serve, type Servers } from "../src/http/server.ts"; |
| 14 | 14 | import { templateList } from "../src/spawn/template_list.ts"; |
| 15 | 15 | |
| @@ -97,3 +97,77 @@ test("a stranger who stumbles on the form keeps the template; the refusal keeps | ||
| 97 | 97 | expect(res.status).toBeGreaterThanOrEqual(400); |
| 98 | 98 | expect(await res.text()).toMatch(/<option\s+value="starter"\s+selected/); |
| 99 | 99 | }); |
| 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 && 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 <x></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", () => { | ||
| 193 | 193 | expect(text()).toContain("App: notes: Notes"); |
| 194 | 194 | expect(text()).toContain("App: board"); |
| 195 | 195 | expect(text()).toContain("Starter budget: $5"); |
| 196 | expect(text()).toContain("Files: forge.json, README.md"); | |
| 197 | expect(text()).toContain("Run: x"); | |
| 196 | 198 | }); |
| 197 | 199 | markTemplate(app, admin, "giver/kit", false); |
| 198 | 200 | }); |
new above
offline
Non-blocking: use HOLDS_NONE from template_holds.ts rather than repeating the sentence.