Public: anyone can read this; the crew can change it.
New app picks from admin-marked template repositories, and a repository may hold several templates #10491
mason/forge:mason/10437-new-app-picks-from-admin-marked-template → main 3 commits fork
11 files
changed +556
−11
docs/features/app-template.md added +19
| @@ -0,0 +1,19 @@ | ||
| 1 | # App templates | |
| 2 | ||
| 3 | Admins mark repositories as app templates (`/admin/limits` → App templates; `settings/app_templates.ts`; default `trevato/app-template`). New app (`/apps/new`, `POST /api/v1/apps` with `"template"`, `newApp`'s `template`) offers a picker when more than one template is on offer, the default first; with one or none it starts from the built-in starter as before. | |
| 4 | ||
| 5 | **A template** is a folder holding `TEMPLATE.md` and `template.json`. A repository is one template (the files at its root) or several (each top-level folder holding both). A template is named `owner/name` or `owner/name/folder`. | |
| 6 | ||
| 7 | **template.json** | |
| 8 | ||
| 9 | json | |
| 10 | { "title": "Notes", "summary": "One line for the picker", | |
| 11 | "name": { "literal": "app-template", "files": ["package.json", "README.md"] }, | |
| 12 | "description": { "literal": "A starter.", "files": ["README.md"] } } | |
| 13 | ||
| 14 | ||
| 15 | The forge copies the tracked files of the default branch's tip (leaving `TEMPLATE.md` and `template.json` out), replaces each literal with the app's name or description in the files listed, and commits them as the app's first commit. **It never runs anything a template carries** (a `new.mjs` is copied as a file, nothing more). | |
| 16 | ||
| 17 | **Checks.** The template must be marked; the caller must be able to read its repository (otherwise `no_such_template`, the same word for "absent"). Caps: 200 files, 512 KiB a file, 2 MiB together, 8 folders deep; symlinks and submodules are skipped; over a cap is `template_too_big`. | |
| 18 | ||
| 19 | **Not here.** Deleting the strings in `apps/scaffold.ts`, the pinned copy in the release image, and `template_birth.ts` are the rest of #10305. |
src/actions/apps.ts +28 −4
| @@ -23,6 +23,8 @@ import { appsRuntime, envsFor, type EnvStatus } from "../apps/runtime.ts"; | ||
| 23 | 23 | import { grantUrl, originFor, sideForViewer, sideReader } from "../apps/proxy.ts"; |
| 24 | 24 | import { plainLine } from "../apps/side.ts"; |
| 25 | 25 | import { scaffoldFiles } from "../apps/scaffold.ts"; |
| 26 | import { templateFiles, type TemplateError } from "../apps/template_source.ts"; | |
| 27 | import type { FileWrite } from "../git/write.ts"; | |
| 26 | 28 | import { |
| 27 | 29 | envBuild, |
| 28 | 30 | isEnvName, |
| @@ -270,6 +272,11 @@ export interface NewAppInput { | ||
| 270 | 272 | * also given. |
| 271 | 273 | */ |
| 272 | 274 | pickAgent?: boolean; |
| 275 | /** | |
| 276 | * A marked template (`apps/template_source.ts`) to start from, as | |
| 277 | * `owner/name` or `owner/name/folder`. Absent or empty is the built-in starter. | |
| 278 | */ | |
| 279 | template?: string; | |
| 273 | 280 | } |
| 274 | 281 | |
| 275 | 282 | export interface NewAppResult { |
| @@ -285,6 +292,7 @@ export type NewAppError = | ||
| 285 | 292 | | CreateRepoActionError |
| 286 | 293 | | CreateAppError |
| 287 | 294 | | "scaffold_failed" |
| 295 | | TemplateError | |
| 288 | 296 | | "no_such_agent" |
| 289 | 297 | | "not_a_builder" |
| 290 | 298 | | "app_limit"; |
| @@ -320,6 +328,17 @@ export async function newApp( | ||
| 320 | 328 | const room = requireAppRoom(app, user.value, ownerId); |
| 321 | 329 | if (!room.ok) return room; |
| 322 | 330 | |
| 331 | // A template the caller cannot read is refused before anything exists. | |
| 332 | let files: FileWrite[] | undefined; | |
| 333 | if (input.template !== undefined && input.template !== "") { | |
| 334 | const copied = await templateFiles(app, user.value, input.template, { | |
| 335 | name: input.name, | |
| 336 | description: input.description ?? "", | |
| 337 | }); | |
| 338 | if (!copied.ok) return copied; | |
| 339 | files = copied.value; | |
| 340 | } | |
| 341 | ||
| 323 | 342 | // Refuse a taken slug before anything exists to take back. |
| 324 | 343 | // A name the owner already has stays `name_taken`, which createRepo says. |
| 325 | 344 | if ( |
| @@ -344,10 +363,12 @@ export async function newApp( | ||
| 344 | 363 | if (!repo.ok) return repo; |
| 345 | 364 | const committed = await commitToBranch(app, user.value, repo.value, { |
| 346 | 365 | message: `Start ${input.name}`, |
| 347 | files: scaffoldFiles({ | |
| 348 | name: input.name, | |
| 349 | description: input.description ?? "", | |
| 350 | }), | |
| 366 | files: | |
| 367 | files ?? | |
| 368 | scaffoldFiles({ | |
| 369 | name: input.name, | |
| 370 | description: input.description ?? "", | |
| 371 | }), | |
| 351 | 372 | }); |
| 352 | 373 | lap("scaffold"); |
| 353 | 374 | if (!committed.ok) { |
| @@ -462,6 +483,9 @@ export const NEW_APP_ERRORS: Record<string, string> = { | ||
| 462 | 483 | "Another app already answers to that hostname. Pick another name.", |
| 463 | 484 | already_app: "That repository is already an app.", |
| 464 | 485 | scaffold_failed: "The starter app could not be committed.", |
| 486 | no_such_template: "That template is not one you can use.", | |
| 487 | template_too_big: "That template is larger than a new app may start with.", | |
| 488 | template_invalid: "That template's template.json could not be read.", | |
| 465 | 489 | no_such_agent: NO_SUCH_AGENT, |
| 466 | 490 | not_a_builder: "That agent is not a builder, so it cannot be handed a new app. Pick a builder.", |
| 467 | 491 | }; |
src/actions/signup.ts +20
| @@ -12,6 +12,7 @@ import { | ||
| 12 | 12 | type SignupChange, |
| 13 | 13 | type SignupMode, |
| 14 | 14 | } from "../settings/signup.ts"; |
| 15 | import { markedTemplates, parseTemplates, setTemplates } from "../settings/app_templates.ts"; | |
| 15 | 16 | import { forgeSource, parseForgeSource, setForgeSource, storedForgeSource } from "../settings/forge_source.ts"; |
| 16 | 17 | import type { User } from "../core/users.ts"; |
| 17 | 18 | import { err, ok, type Result } from "../kernel/result.ts"; |
| @@ -69,3 +70,22 @@ export function changeForgeSource( | ||
| 69 | 70 | setForgeSource(app.db, name.value, who.value.id); |
| 70 | 71 | return ok(name.value); |
| 71 | 72 | } |
| 73 | ||
| 74 | /** The repositories marked as app templates (`settings/app_templates.ts`), for an admin. */ | |
| 75 | export function readTemplates(app: App, actor: User | undefined): Result<readonly string[], "not_found"> { | |
| 76 | const who = admin(actor); | |
| 77 | return who.ok ? ok(markedTemplates(app.db)) : who; | |
| 78 | } | |
| 79 | ||
| 80 | export function changeTemplates( | |
| 81 | app: App, | |
| 82 | actor: User | undefined, | |
| 83 | raw: unknown, | |
| 84 | ): Result<readonly string[], "not_found" | "invalid_templates"> { | |
| 85 | const who = admin(actor); | |
| 86 | if (!who.ok) return who; | |
| 87 | const names = parseTemplates(raw); | |
| 88 | if (!names.ok) return names; | |
| 89 | setTemplates(app.db, names.value, who.value.id); | |
| 90 | return ok(names.value); | |
| 91 | } |
src/apps/template_source.ts added +230
| @@ -0,0 +1,230 @@ | ||
| 1 | /** | |
| 2 | * App templates that live in repositories. A template is a folder holding | |
| 3 | * `TEMPLATE.md` and `template.json`; a repository is one template (the files | |
| 4 | * at its root) or several (each folder holding both). New app copies the | |
| 5 | * folder's files and fills the literals `template.json` names. It never runs | |
| 6 | * anything the template carries. | |
| 7 | * | |
| 8 | * `template.json`: | |
| 9 | * { "title": "Notes", "summary": "One line", | |
| 10 | * "name": { "literal": "app-template", "files": ["package.json"] }, | |
| 11 | * "description": { "literal": "A starter.", "files": ["README.md"] } } | |
| 12 | * | |
| 13 | * A template is named by a key: `owner/name`, or `owner/name/folder`. | |
| 14 | * Caps: MAX_FILES files, MAX_FILE_BYTES each, MAX_TOTAL_BYTES together, | |
| 15 | * MAX_DEPTH folders deep. Links and submodules are skipped. | |
| 16 | */ | |
| 17 | ||
| 18 | import type { App } from "../app.ts"; | |
| 19 | import { canRead, getRepo, type Repo } from "../core/repos.ts"; | |
| 20 | import type { User } from "../core/users.ts"; | |
| 21 | import { isSafeTreePath } from "../git/guard.ts"; | |
| 22 | import { listTree, readerFor, type TreeEntry } from "../git/read.ts"; | |
| 23 | import { repoDir } from "../git/repos.ts"; | |
| 24 | import type { FileWrite } from "../git/write.ts"; | |
| 25 | import { err, ok, type Result } from "../kernel/result.ts"; | |
| 26 | import { markedTemplates } from "../settings/app_templates.ts"; | |
| 27 | ||
| 28 | export const MAX_FILES = 200; | |
| 29 | export const MAX_FILE_BYTES = 512 * 1024; | |
| 30 | export const MAX_TOTAL_BYTES = 2 * 1024 * 1024; | |
| 31 | export const MAX_DEPTH = 8; | |
| 32 | const MAX_FOLDERS = 50; | |
| 33 | ||
| 34 | /** Files that describe the template; they are not copied into the app. */ | |
| 35 | const MARKERS = ["TEMPLATE.md", "template.json"]; | |
| 36 | ||
| 37 | export interface Fill { | |
| 38 | readonly literal: string; | |
| 39 | readonly files: readonly string[]; | |
| 40 | } | |
| 41 | ||
| 42 | export interface TemplateSpec { | |
| 43 | readonly title: string | undefined; | |
| 44 | readonly summary: string | undefined; | |
| 45 | readonly name: Fill | undefined; | |
| 46 | readonly description: Fill | undefined; | |
| 47 | } | |
| 48 | ||
| 49 | export interface TemplateOffer { | |
| 50 | /** `owner/name` or `owner/name/folder`. */ | |
| 51 | readonly key: string; | |
| 52 | readonly label: string; | |
| 53 | readonly summary: string; | |
| 54 | } | |
| 55 | ||
| 56 | export type TemplateError = "no_such_template" | "template_too_big" | "template_invalid"; | |
| 57 | ||
| 58 | function fill(raw: unknown): Fill | undefined | "bad" { | |
| 59 | if (raw === undefined) return undefined; | |
| 60 | if (typeof raw !== "object" || raw === null) return "bad"; | |
| 61 | const { literal, files } = raw as Record<string, unknown>; | |
| 62 | if (typeof literal !== "string" || literal === "" || literal.length > 500) return "bad"; | |
| 63 | if (!Array.isArray(files) || files.length > MAX_FILES) return "bad"; | |
| 64 | if (!files.every((f) => typeof f === "string" && isSafeTreePath(f))) return "bad"; | |
| 65 | return { literal, files: files as string[] }; | |
| 66 | } | |
| 67 | ||
| 68 | /** `template.json` from untrusted text; nothing it does not name is read. */ | |
| 69 | export function parseSpec(text: string): Result<TemplateSpec, "template_invalid"> { | |
| 70 | let raw: unknown; | |
| 71 | try { | |
| 72 | raw = JSON.parse(text); | |
| 73 | } catch { | |
| 74 | return err("template_invalid"); | |
| 75 | } | |
| 76 | if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return err("template_invalid"); | |
| 77 | const o = raw as Record<string, unknown>; | |
| 78 | const text1 = (v: unknown, max: number): string | undefined | "bad" => | |
| 79 | v === undefined ? undefined : typeof v === "string" && v.length <= max ? v : "bad"; | |
| 80 | const title = text1(o["title"], 80); | |
| 81 | const summary = text1(o["summary"], 300); | |
| 82 | const name = fill(o["name"]); | |
| 83 | const description = fill(o["description"]); | |
| 84 | if (title === "bad" || summary === "bad" || name === "bad" || description === "bad") | |
| 85 | return err("template_invalid"); | |
| 86 | return ok({ title, summary, name, description }); | |
| 87 | } | |
| 88 | ||
| 89 | /** `literal` becomes `value` in `content`, everywhere; a function replacer keeps `$` in `value` literal. */ | |
| 90 | export function fillLiteral(content: string, literal: string, value: string): string { | |
| 91 | return content.split(literal).join(value); | |
| 92 | } | |
| 93 | ||
| 94 | /** Split a key into repository and folder, or refuse a malformed one. */ | |
| 95 | export function parseKey(key: string): { owner: string; name: string; folder: string } | undefined { | |
| 96 | const m = /^([A-Za-z0-9][A-Za-z0-9._-]{0,99})\/([A-Za-z0-9][A-Za-z0-9._-]{0,99})(?:\/([A-Za-z0-9][A-Za-z0-9._-]{0,99}))?$/.exec( | |
| 97 | key, | |
| 98 | ); | |
| 99 | return m === null ? undefined : { owner: m[1]!, name: m[2]!, folder: m[3] ?? "" }; | |
| 100 | } | |
| 101 | ||
| 102 | function readableRepo(app: App, actor: User | undefined, owner: string, name: string): Repo | undefined { | |
| 103 | const repo = getRepo(app.db, owner, name); | |
| 104 | return repo !== undefined && canRead(app.db, repo, actor) ? repo : undefined; | |
| 105 | } | |
| 106 | ||
| 107 | async function blobText(dir: string, rev: string): Promise<string | undefined> { | |
| 108 | const got = await readerFor(dir).object(rev); | |
| 109 | if (!got.ok || got.value.type !== "blob" || got.value.size > MAX_FILE_BYTES) return undefined; | |
| 110 | return new TextDecoder().decode(got.value.body); | |
| 111 | } | |
| 112 | ||
| 113 | async function isTemplateFolder(dir: string, rev: string, folder: string): Promise<boolean> { | |
| 114 | const listed = await listTree(dir, rev, folder); | |
| 115 | if (!listed.ok) return false; | |
| 116 | const names = new Set(listed.value.filter((e) => e.type === "blob").map((e) => e.name)); | |
| 117 | return MARKERS.every((m) => names.has(m)); | |
| 118 | } | |
| 119 | ||
| 120 | /** The folders of a repository that are templates: "" for the root, else each folder's name. */ | |
| 121 | async function folders(dir: string, rev: string): Promise<string[]> { | |
| 122 | if (await isTemplateFolder(dir, rev, "")) return [""]; | |
| 123 | const root = await listTree(dir, rev, ""); | |
| 124 | if (!root.ok) return []; | |
| 125 | const found: string[] = []; | |
| 126 | for (const e of root.value.filter((e) => e.type === "tree").slice(0, MAX_FOLDERS)) { | |
| 127 | if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(e.name) && (await isTemplateFolder(dir, rev, e.name))) | |
| 128 | found.push(e.name); | |
| 129 | } | |
| 130 | return found; | |
| 131 | } | |
| 132 | ||
| 133 | /** Every template the actor may read among the marked repositories, the default first. */ | |
| 134 | export async function offeredTemplates(app: App, actor: User | undefined): Promise<TemplateOffer[]> { | |
| 135 | const offers: TemplateOffer[] = []; | |
| 136 | for (const marked of markedTemplates(app.db)) { | |
| 137 | const [owner, name] = marked.split("/") as [string, string]; | |
| 138 | const repo = readableRepo(app, actor, owner, name); | |
| 139 | if (repo === undefined) continue; | |
| 140 | const dir = repoDir(app.reposRoot, repo.ownerName, repo.name); | |
| 141 | const rev = `refs/heads/${repo.defaultBranch}`; | |
| 142 | for (const folder of await folders(dir, rev)) { | |
| 143 | const base = folder === "" ? "" : `${folder}/`; | |
| 144 | const spec = parseSpec((await blobText(dir, `${rev}:${base}template.json`)) ?? ""); | |
| 145 | offers.push({ | |
| 146 | key: folder === "" ? marked : `${marked}/${folder}`, | |
| 147 | label: (spec.ok ? spec.value.title : undefined) ?? (folder === "" ? name : folder), | |
| 148 | summary: (spec.ok ? spec.value.summary : undefined) ?? "", | |
| 149 | }); | |
| 150 | } | |
| 151 | } | |
| 152 | return offers; | |
| 153 | } | |
| 154 | ||
| 155 | async function walk( | |
| 156 | dir: string, | |
| 157 | rev: string, | |
| 158 | base: string, | |
| 159 | path: string, | |
| 160 | depth: number, | |
| 161 | out: { path: string; entry: TreeEntry }[], | |
| 162 | ): Promise<boolean> { | |
| 163 | if (depth > MAX_DEPTH) return false; | |
| 164 | const listed = await listTree(dir, rev, `${base}${path}`); | |
| 165 | if (!listed.ok) return false; | |
| 166 | for (const e of listed.value) { | |
| 167 | const rel = path === "" ? e.name : `${path}/${e.name}`; | |
| 168 | if (e.type === "tree") { | |
| 169 | if (!(await walk(dir, rev, base, rel, depth + 1, out))) return false; | |
| 170 | } else if (e.type === "blob" && (e.mode === "100644" || e.mode === "100755")) { | |
| 171 | if (!isSafeTreePath(rel) || (path === "" && MARKERS.includes(e.name))) continue; | |
| 172 | out.push({ path: rel, entry: e }); | |
| 173 | if (out.length > MAX_FILES) return false; | |
| 174 | } | |
| 175 | } | |
| 176 | return true; | |
| 177 | } | |
| 178 | ||
| 179 | /** | |
| 180 | * The files a new app starts with, from the template `key` the actor may | |
| 181 | * read, with the name and description filled in. Nothing is executed. | |
| 182 | */ | |
| 183 | export async function templateFiles( | |
| 184 | app: App, | |
| 185 | actor: User | undefined, | |
| 186 | key: string, | |
| 187 | values: { name: string; description: string }, | |
| 188 | ): Promise<Result<FileWrite[], TemplateError>> { | |
| 189 | const parsed = parseKey(key); | |
| 190 | if (parsed === undefined) return err("no_such_template"); | |
| 191 | if (!markedTemplates(app.db).includes(`${parsed.owner}/${parsed.name}`)) return err("no_such_template"); | |
| 192 | const repo = readableRepo(app, actor, parsed.owner, parsed.name); | |
| 193 | if (repo === undefined) return err("no_such_template"); | |
| 194 | const dir = repoDir(app.reposRoot, repo.ownerName, repo.name); | |
| 195 | const rev = `refs/heads/${repo.defaultBranch}`; | |
| 196 | const base = parsed.folder === "" ? "" : `${parsed.folder}/`; | |
| 197 | if (!(await isTemplateFolder(dir, rev, parsed.folder))) return err("no_such_template"); | |
| 198 | const spec = parseSpec((await blobText(dir, `${rev}:${base}template.json`)) ?? ""); | |
| 199 | if (!spec.ok) return spec; | |
| 200 | ||
| 201 | const listing: { path: string; entry: TreeEntry }[] = []; | |
| 202 | const complete = await walk(dir, rev, base, "", 0, listing); | |
| 203 | let total = 0; | |
| 204 | for (const f of listing) total += f.entry.size; | |
| 205 | if (!complete || total > MAX_TOTAL_BYTES || listing.some((f) => f.entry.size > MAX_FILE_BYTES)) | |
| 206 | return err("template_too_big"); | |
| 207 | ||
| 208 | const fills: [Fill, string][] = []; | |
| 209 | if (spec.value.name) fills.push([spec.value.name, values.name]); | |
| 210 | if (spec.value.description) fills.push([spec.value.description, values.description.trim()]); | |
| 211 | const files: FileWrite[] = []; | |
| 212 | for (const { path, entry } of listing) { | |
| 213 | const got = await readerFor(dir).object(entry.oid); | |
| 214 | if (!got.ok || got.value.type !== "blob") return err("no_such_template"); | |
| 215 | const mine = fills.filter(([f]) => f.files.includes(path)); | |
| 216 | const mode = entry.mode === "100755" ? ("100755" as const) : undefined; | |
| 217 | files.push({ | |
| 218 | path, | |
| 219 | content: | |
| 220 | mine.length === 0 | |
| 221 | ? got.value.body | |
| 222 | : mine.reduce( | |
| 223 | (text, [f, value]) => fillLiteral(text, f.literal, value), | |
| 224 | new TextDecoder().decode(got.value.body), | |
| 225 | ), | |
| 226 | ...(mode === undefined ? {} : { mode }), | |
| 227 | }); | |
| 228 | } | |
| 229 | return ok(files); | |
| 230 | } |
src/contract/openapi/routes/postApiV1Apps.ts +1 −1
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | 3 | /** What `POST /api/v1/apps` reads from its body, and the refusals it answers. */ |
| 4 | const APP_BODY = { name: "string", owner: "string", description: "string", sentence: "string", visibility: "string", agent: "string", pick: "boolean" }; | |
| 4 | const APP_BODY = { name: "string", owner: "string", description: "string", sentence: "string", visibility: "string", agent: "string", pick: "boolean", template: "string" }; | |
| 5 | 5 | const APP_REFUSALS = { |
| 6 | 6 | unverified: "the account has not verified its email", |
| 7 | 7 | no_name: "no `name`, and the `sentence` leaves nothing to make one from", |
src/http/api.ts +1
| @@ -3583,6 +3583,7 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 3583 | 3583 | ...(typeof input.agent === "string" ? { agent: input.agent } : {}), |
| 3584 | 3584 | // Only a real boolean asks; like the other fields, anything else is ignored. |
| 3585 | 3585 | ...(input.pick === true ? { pickAgent: true } : {}), |
| 3586 | ...(typeof input.template === "string" ? { template: input.template } : {}), | |
| 3586 | 3587 | }; |
| 3587 | 3588 | const onPhase = (name: string, ms: number) => notePhase(ctx.request, name, ms); |
| 3588 | 3589 | // No `name` but a `sentence`: the name is derived, as the web form and terminal do. |
src/http/server.ts +2 −1
| @@ -31,7 +31,7 @@ import { adminDataPage, appDataPage, dataPage } from "../web/pages/data.ts"; | ||
| 31 | 31 | import { fleetAct, fleetReceipt, fleetUndo } from "../web/pages/fleet-ops.ts"; |
| 32 | 32 | import { maintenancePage, maintenancePrepare, maintenanceResume } from "../web/pages/maintenance.ts"; |
| 33 | 33 | import { nightlyOutputPage, resiliencePage } from "../web/pages/resilience.ts"; |
| 34 | import { limitsPage, limitsSet, quotasSet, signupSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts"; | |
| 34 | import { limitsPage, limitsSet, quotasSet, signupSet, templatesSet, inviteMint, inviteRevoke } from "../web/pages/admin-limits.ts"; | |
| 35 | 35 | import { allFlowsPage } from "../web/pages/flows-all.ts"; |
| 36 | 36 | import { measureSubmit } from "./measure.ts"; |
| 37 | 37 | import { settingsRoutes } from "./settings_routes.ts"; |
| @@ -1010,6 +1010,7 @@ export function buildRouter(): Router<Handler> { | ||
| 1010 | 1010 | router.add("POST", "/admin/limits", limitsSet); |
| 1011 | 1011 | router.add("POST", "/admin/quotas", quotasSet); |
| 1012 | 1012 | router.add("POST", "/admin/signup", signupSet); |
| 1013 | router.add("POST", "/admin/templates", templatesSet); | |
| 1013 | 1014 | router.add("POST", "/admin/invites", inviteMint); |
| 1014 | 1015 | router.add("POST", "/admin/invites/:id/revoke", inviteRevoke); |
| 1015 | 1016 |
src/settings/app_templates.ts added +51
| @@ -0,0 +1,51 @@ | ||
| 1 | /** | |
| 2 | * Which repositories an admin has marked as app templates, as `owner/name`, | |
| 3 | * first one the default. Stored as a JSON list in `forge_setting` under | |
| 4 | * `app_templates`; with no row it is `DEFAULT_TEMPLATES`. Every change is | |
| 5 | * kept in `forge_setting_change` (who, when, from what to what). | |
| 6 | */ | |
| 7 | ||
| 8 | import type { Database } from "bun:sqlite"; | |
| 9 | import { err, ok, type Result } from "../kernel/result.ts"; | |
| 10 | import { writeSetting } from "./limits.ts"; | |
| 11 | ||
| 12 | export const DEFAULT_TEMPLATES: readonly string[] = ["trevato/app-template"]; | |
| 13 | export const MAX_MARKED = 20; | |
| 14 | ||
| 15 | const STORE_KEY = "app_templates"; | |
| 16 | const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/; | |
| 17 | ||
| 18 | /** A list of `owner/name` from untrusted text (commas or lines), deduplicated, in order. */ | |
| 19 | export function parseTemplates(raw: unknown): Result<string[], "invalid_templates"> { | |
| 20 | if (typeof raw !== "string" || raw.length > 4000) return err("invalid_templates"); | |
| 21 | const names: string[] = []; | |
| 22 | for (const part of raw.split(/[\s,]+/)) { | |
| 23 | if (part === "") continue; | |
| 24 | if (!NAME.test(part)) return err("invalid_templates"); | |
| 25 | if (!names.includes(part)) names.push(part); | |
| 26 | } | |
| 27 | return names.length > MAX_MARKED ? err("invalid_templates") : ok(names); | |
| 28 | } | |
| 29 | ||
| 30 | /** The marked repositories, default first. */ | |
| 31 | export function markedTemplates(db: Database): readonly string[] { | |
| 32 | const row = db | |
| 33 | .query<{ value: string }, [string]>("SELECT value FROM forge_setting WHERE key = ?1") | |
| 34 | .get(STORE_KEY); | |
| 35 | if (row === null) return DEFAULT_TEMPLATES; | |
| 36 | try { | |
| 37 | const list: unknown = JSON.parse(row.value); | |
| 38 | if (!Array.isArray(list)) return DEFAULT_TEMPLATES; | |
| 39 | return list.filter((n): n is string => typeof n === "string" && NAME.test(n)).slice(0, MAX_MARKED); | |
| 40 | } catch { | |
| 41 | return DEFAULT_TEMPLATES; | |
| 42 | } | |
| 43 | } | |
| 44 | ||
| 45 | /** Mark exactly these repositories and keep the change; the same list again keeps nothing. */ | |
| 46 | export function setTemplates(db: Database, names: readonly string[], actorId: string): void { | |
| 47 | const from = markedTemplates(db).join(","); | |
| 48 | const to = names.join(","); | |
| 49 | if (from === to) return; | |
| 50 | writeSetting(db, STORE_KEY, JSON.stringify(names), from, to, actorId); | |
| 51 | } |
src/web/pages/admin-limits.ts +31 −2
| @@ -11,7 +11,7 @@ import { changeQuotas, readQuotas } from "../../actions/quotas.ts"; | ||
| 11 | 11 | import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts"; |
| 12 | 12 | import { INVITE_NOT_OPEN } from "../../actions/sever_invite_words.ts"; |
| 13 | 13 | import { DEFAULT_DAYS, MAX_DAYS } from "../../core/invites.ts"; |
| 14 | import { changeSignup, readSignup } from "../../actions/signup.ts"; | |
| 14 | import { changeSignup, changeTemplates, readSignup, readTemplates } from "../../actions/signup.ts"; | |
| 15 | 15 | import { SIGNUP_MODES } from "../../settings/signup.ts"; |
| 16 | 16 | import { QUOTA_KEYS } from "../../settings/quotas.ts"; |
| 17 | 17 | import type { Ctx } from "../../http/context.ts"; |
| @@ -135,6 +135,18 @@ export function limitsPage(ctx: Ctx): Response { | ||
| 135 | 135 | </dd> |
| 136 | 136 | <dd class="status-act"></dd> |
| 137 | 137 | </div>`; |
| 138 | const marked = readTemplates(ctx.app, ctx.auth.user); | |
| 139 | const templateRow = html`<div class="status-row"> | |
| 140 | <dt>App templates</dt> | |
| 141 | <dd> | |
| 142 | <form class="row-fields" method="post" action="/admin/templates"> | |
| 143 | <textarea class="input mono" name="templates" rows="3" aria-label="Repositories marked as app templates">${marked.ok ? marked.value.join("\n") : ""}</textarea> | |
| 144 | ${btn("Save", { size: "sm", variant: "primary", label: "Save app templates" })} | |
| 145 | </form> | |
| 146 | <span class="muted small">One owner/name per line, the default first. New app offers a picker when more than one is marked; a repository whose folders each hold TEMPLATE.md and template.json offers each folder.</span> | |
| 147 | </dd> | |
| 148 | <dd class="status-act"></dd> | |
| 149 | </div>`; | |
| 138 | 150 | const inviteRows = (invites.ok ? invites.value : []).map((i) => |
| 139 | 151 | row({ |
| 140 | 152 | lead: icon("activity"), |
| @@ -177,7 +189,7 @@ export function limitsPage(ctx: Ctx): Response { | ||
| 177 | 189 | const body = html`<p class="small muted mb"> |
| 178 | 190 | Every limit you can hit, and why. A change applies to the next request that meets it; nothing needs a restart. |
| 179 | 191 | </p> |
| 180 | <dl class="status-rows">${signupRow}${inviteRow}${quotaRow}</dl> | |
| 192 | <dl class="status-rows">${signupRow}${templateRow}${inviteRow}${quotaRow}</dl> | |
| 181 | 193 | ${historyBlock("Invite links made", inviteRows)} |
| 182 | 194 | <section class="settings-block mt"> |
| 183 | 195 | <h2>Limits</h2> |
| @@ -284,6 +296,23 @@ export async function signupSet(ctx: Ctx): Promise<Response> { | ||
| 284 | 296 | ); |
| 285 | 297 | } |
| 286 | 298 | |
| 299 | // POST /admin/templates | |
| 300 | export async function templatesSet(ctx: Ctx): Promise<Response> { | |
| 301 | if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent") | |
| 302 | return notFoundPage(ctx); | |
| 303 | const form = await readForm(ctx, "admin"); | |
| 304 | if (form instanceof Response) return form; | |
| 305 | const changed = changeTemplates(ctx.app, ctx.auth.user, field(form, "templates")); | |
| 306 | if (!changed.ok && changed.error === "not_found") return notFoundPage(ctx); | |
| 307 | return flashTo( | |
| 308 | ctx, | |
| 309 | "/admin/limits", | |
| 310 | changed.ok | |
| 311 | ? { message: "App templates saved." } | |
| 312 | : { tone: "danger", message: "App templates are owner/name, one per line, at most 20." }, | |
| 313 | ); | |
| 314 | } | |
| 315 | ||
| 287 | 316 | // POST /admin/invites |
| 288 | 317 | export async function inviteMint(ctx: Ctx): Promise<Response> { |
| 289 | 318 | if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent") |
src/web/pages/apps.ts +25 −3
| @@ -28,6 +28,7 @@ import { | ||
| 28 | 28 | stopEnv, |
| 29 | 29 | terminalFor, |
| 30 | 30 | } from "../../actions/apps.ts"; |
| 31 | import { offeredTemplates, type TemplateOffer } from "../../apps/template_source.ts"; | |
| 31 | 32 | import { listAllAgents } from "../../actions/crew.ts"; |
| 32 | 33 | import { planningAvailable } from "../../crew/plan.ts"; |
| 33 | 34 | import { appNameJs } from "./apps-name.ts"; |
| @@ -283,6 +284,8 @@ interface NewAppValues { | ||
| 283 | 284 | description: string; |
| 284 | 285 | visibility: string; |
| 285 | 286 | agent: string; |
| 287 | /** A template key; empty is the built-in starter. */ | |
| 288 | template?: string; | |
| 286 | 289 | } |
| 287 | 290 | |
| 288 | 291 | /** The agent select's sentinel for "turn the sentence into a plan and pick". */ |
| @@ -300,6 +303,7 @@ function newAppForm( | ||
| 300 | 303 | values: NewAppValues, |
| 301 | 304 | canPlan: boolean, |
| 302 | 305 | error?: string, |
| 306 | offers: readonly TemplateOffer[] = [], | |
| 303 | 307 | ): Html { |
| 304 | 308 | const user = ctx.auth.user!; |
| 305 | 309 | const writeOrgs = timePhase(ctx.request, "orgs", () => |
| @@ -368,6 +372,18 @@ function newAppForm( | ||
| 368 | 372 | : `Left blank, it comes from your sentence. Use letters, digits, dots, dashes and underscores. It runs at <name>${appHostSuffix(domain)}.`, |
| 369 | 373 | ...(error ? { error } : {}), |
| 370 | 374 | })} |
| 375 | ${offers.length > 1 | |
| 376 | ? selectField({ | |
| 377 | label: "Template", | |
| 378 | name: "template", | |
| 379 | hint: "Where the app's files start. The first is the forge's default.", | |
| 380 | options: offers.map((o, i) => ({ | |
| 381 | value: o.key, | |
| 382 | label: o.summary === "" ? o.label : `${o.label} — ${o.summary}`, | |
| 383 | selected: values.template ? o.key === values.template : i === 0, | |
| 384 | })), | |
| 385 | }) | |
| 386 | : html``} | |
| 371 | 387 | ${selectField({ |
| 372 | 388 | label: "Visibility", |
| 373 | 389 | name: "visibility", |
| @@ -435,10 +451,13 @@ function newAppForm( | ||
| 435 | 451 | } |
| 436 | 452 | |
| 437 | 453 | // GET /apps/new |
| 438 | export function newAppPage(ctx: Ctx): Response { | |
| 454 | export async function newAppPage(ctx: Ctx): Promise<Response> { | |
| 439 | 455 | if (!ctx.auth.user) return signInFirst(ctx); |
| 440 | 456 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 441 | 457 | const picks = plannerOffered(ctx); |
| 458 | const reading = performance.now(); | |
| 459 | const offers = await offeredTemplates(ctx.app, ctx.auth.user); | |
| 460 | notePhase(ctx.request, "templates", performance.now() - reading); | |
| 442 | 461 | const rendering = performance.now(); |
| 443 | 462 | const response = page({ |
| 444 | 463 | ctx, |
| @@ -449,7 +468,7 @@ export function newAppPage(ctx: Ctx): Response { | ||
| 449 | 468 | description: starterFromQuery(ctx.url.searchParams.get("description")), |
| 450 | 469 | visibility: "private", |
| 451 | 470 | agent: picks ? PICK_AGENT : "", |
| 452 | }, picks), | |
| 471 | }, picks, undefined, offers), | |
| 453 | 472 | scriptJs: appNameJs, |
| 454 | 473 | }); |
| 455 | 474 | notePhase(ctx.request, "render", performance.now() - rendering); |
| @@ -469,6 +488,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 469 | 488 | description: field(form, "description"), |
| 470 | 489 | visibility: field(form, "visibility") === "public" ? "public" : "private", |
| 471 | 490 | agent: field(form, "agent"), |
| 491 | template: field(form, "template"), | |
| 472 | 492 | }; |
| 473 | 493 | const pickAgent = values.agent === PICK_AGENT; |
| 474 | 494 | // An explicit name is never second-guessed; left blank, the sentence |
| @@ -478,6 +498,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 478 | 498 | const rest = { |
| 479 | 499 | owner: values.owner, |
| 480 | 500 | visibility: values.visibility === "public" ? "public" : "private", |
| 501 | ...(values.template ? { template: values.template } : {}), | |
| 481 | 502 | ...(pickAgent |
| 482 | 503 | ? { pickAgent: true } |
| 483 | 504 | : values.agent === "" |
| @@ -503,7 +524,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 503 | 524 | { |
| 504 | 525 | ctx, |
| 505 | 526 | title: "New app", |
| 506 | body: newAppForm(ctx, values, plannerOffered(ctx), NO_NAME_ERROR), | |
| 527 | body: newAppForm(ctx, values, plannerOffered(ctx), NO_NAME_ERROR, await offeredTemplates(ctx.app, ctx.auth.user)), | |
| 507 | 528 | scriptJs: appNameJs, |
| 508 | 529 | }, |
| 509 | 530 | 422, |
| @@ -531,6 +552,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 531 | 552 | : made.error === "app_limit" && ownerId !== undefined |
| 532 | 553 | ? appLimitWords(ctx.app, ownerId) |
| 533 | 554 | : (NEW_APP_ERRORS[made.error] ?? "That app could not be created."), |
| 555 | await offeredTemplates(ctx.app, ctx.auth.user), | |
| 534 | 556 | ), |
| 535 | 557 | scriptJs: appNameJs, |
| 536 | 558 | }, |
test/app-templates.test.ts added +148
| @@ -0,0 +1,148 @@ | ||
| 1 | /** | |
| 2 | * Admin-marked template repositories (`settings/app_templates.ts`, | |
| 3 | * `apps/template_source.ts`): the picker's offers, a folder's files copied | |
| 4 | * with `template.json`'s literals filled, and the read check and caps. | |
| 5 | */ | |
| 6 | import { afterAll, expect, setDefaultTimeout, test } from "bun:test"; | |
| 7 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { newApp } from "../src/actions/apps.ts"; | |
| 11 | import { changeTemplates, readTemplates } from "../src/actions/signup.ts"; | |
| 12 | import { commitToBranch, createRepo } from "../src/actions/repos.ts"; | |
| 13 | import { setRole } from "../src/actions/roles.ts"; | |
| 14 | import { createApp } from "../src/app.ts"; | |
| 15 | import { MAX_FILE_BYTES, offeredTemplates, templateFiles } from "../src/apps/template_source.ts"; | |
| 16 | import { createUser } from "../src/core/users.ts"; | |
| 17 | import { quietLogs } from "./helpers/globals.ts"; | |
| 18 | ||
| 19 | quietLogs(); | |
| 20 | setDefaultTimeout(30_000); | |
| 21 | ||
| 22 | const dirs: string[] = []; | |
| 23 | afterAll(async () => { | |
| 24 | for (const d of dirs) await rm(d, { recursive: true, force: true }); | |
| 25 | }); | |
| 26 | ||
| 27 | const spec = (title: string) => | |
| 28 | JSON.stringify({ | |
| 29 | title, | |
| 30 | summary: `${title} starter`, | |
| 31 | name: { literal: "tpl-name", files: ["package.json", "README.md"] }, | |
| 32 | description: { literal: "TPL DESCRIPTION", files: ["README.md"] }, | |
| 33 | }); | |
| 34 | ||
| 35 | async function world() { | |
| 36 | const dir = await mkdtemp(join(tmpdir(), "forge-tpl-")); | |
| 37 | dirs.push(dir); | |
| 38 | const app = createApp({ dataDir: dir, port: 0 }); | |
| 39 | const mk = async (username: string, isAdmin = false) => { | |
| 40 | const made = await createUser(app.db, { | |
| 41 | origin: "seed", trusted: true, username, email: `${username}@x.test`, isAdmin, | |
| 42 | }); | |
| 43 | if (!made.ok) throw new Error(made.error); | |
| 44 | return made.value; | |
| 45 | }; | |
| 46 | const admin = await mk("boss", true); | |
| 47 | const user = await mk("maker"); | |
| 48 | const other = await mk("other"); | |
| 49 | for (const who of [user, other]) setRole(app, admin, who.username, "member"); | |
| 50 | const repo = async (name: string, visibility: "public" | "private", files: { path: string; content: string }[]) => { | |
| 51 | const r = await createRepo(app, admin, { name, visibility }); | |
| 52 | if (!r.ok) throw new Error(r.error); | |
| 53 | const c = await commitToBranch(app, admin, r.value, { files }); | |
| 54 | if (!c.ok) throw new Error(JSON.stringify(c.error)); | |
| 55 | return r.value; | |
| 56 | }; | |
| 57 | return { app, admin, user, other, repo }; | |
| 58 | } | |
| 59 | ||
| 60 | test("a repository of folders offers each folder; the default comes first", async () => { | |
| 61 | const { app, admin, user, repo } = await world(); | |
| 62 | await repo("pack", "public", [ | |
| 63 | { path: "alpha/TEMPLATE.md", content: "# a" }, | |
| 64 | { path: "alpha/template.json", content: spec("Alpha") }, | |
| 65 | { path: "beta/TEMPLATE.md", content: "# b" }, | |
| 66 | { path: "beta/template.json", content: spec("Beta") }, | |
| 67 | { path: "notes/readme.txt", content: "not a template" }, | |
| 68 | ]); | |
| 69 | await repo("solo", "public", [ | |
| 70 | { path: "TEMPLATE.md", content: "# s" }, | |
| 71 | { path: "template.json", content: spec("Solo") }, | |
| 72 | ]); | |
| 73 | expect(await offeredTemplates(app, user)).toEqual([]); | |
| 74 | expect(changeTemplates(app, admin, "boss/solo, boss/pack boss/solo").ok).toBe(true); | |
| 75 | const offers = await offeredTemplates(app, user); | |
| 76 | expect(offers.map((o) => o.key)).toEqual(["boss/solo", "boss/pack/alpha", "boss/pack/beta"]); | |
| 77 | expect(offers[1]).toMatchObject({ label: "Alpha", summary: "Alpha starter" }); | |
| 78 | }); | |
| 79 | ||
| 80 | test("a new app copies the folder, fills the literals, and never copies the markers", async () => { | |
| 81 | const { app, admin, user, repo } = await world(); | |
| 82 | await repo("pack", "public", [ | |
| 83 | { path: "alpha/TEMPLATE.md", content: "# a" }, | |
| 84 | { path: "alpha/template.json", content: spec("Alpha") }, | |
| 85 | { path: "alpha/package.json", content: '{"name":"tpl-name"}' }, | |
| 86 | { path: "alpha/README.md", content: "# tpl-name\nTPL DESCRIPTION $& done" }, | |
| 87 | { path: "alpha/src/new.mjs", content: "throw new Error('must never run')" }, | |
| 88 | { path: "beta/TEMPLATE.md", content: "# b" }, | |
| 89 | { path: "beta/template.json", content: spec("Beta") }, | |
| 90 | { path: "beta/other.txt", content: "beta only" }, | |
| 91 | ]); | |
| 92 | changeTemplates(app, admin, "boss/pack"); | |
| 93 | const files = await templateFiles(app, user, "boss/pack/alpha", { name: "fresh", description: " Tides " }); | |
| 94 | expect(files.ok).toBe(true); | |
| 95 | if (!files.ok) return; | |
| 96 | const byPath = Object.fromEntries(files.value.map((f) => [f.path, typeof f.content === "string" ? f.content : new TextDecoder().decode(f.content ?? new Uint8Array())])); | |
| 97 | expect(Object.keys(byPath).sort()).toEqual(["README.md", "package.json", "src/new.mjs"]); | |
| 98 | expect(String(byPath["package.json"])).toBe('{"name":"fresh"}'); | |
| 99 | expect(String(byPath["README.md"])).toBe("# fresh\nTides $& done"); | |
| 100 | ||
| 101 | const made = await newApp(app, user, { name: "tides", description: "Tides", template: "boss/pack/alpha" }); | |
| 102 | expect(made.ok).toBe(true); | |
| 103 | if (made.ok) expect(made.value.repo.name).toBe("tides"); | |
| 104 | }); | |
| 105 | ||
| 106 | test("an unmarked, unreadable or unknown template is refused before anything exists", async () => { | |
| 107 | const { app, admin, user, other, repo } = await world(); | |
| 108 | const files = [ | |
| 109 | { path: "forge.json", content: '{"run":"bun index.ts","port":3000}' }, | |
| 110 | { path: "TEMPLATE.md", content: "#" }, | |
| 111 | { path: "template.json", content: spec("T") }, | |
| 112 | ]; | |
| 113 | await repo("open", "public", files); | |
| 114 | await repo("hidden", "private", files); | |
| 115 | const ask = (who: typeof user, key: string) => | |
| 116 | newApp(app, who, { name: "x1", template: key }); | |
| 117 | expect(await ask(user, "boss/open")).toEqual({ ok: false, error: "no_such_template" }); | |
| 118 | changeTemplates(app, admin, "boss/open boss/hidden"); | |
| 119 | expect(await ask(user, "boss/hidden")).toEqual({ ok: false, error: "no_such_template" }); | |
| 120 | expect((await offeredTemplates(app, other)).map((o) => o.key)).toEqual(["boss/open"]); | |
| 121 | expect(await ask(user, "boss/open/nope")).toEqual({ ok: false, error: "no_such_template" }); | |
| 122 | expect(await ask(user, "../etc/passwd")).toEqual({ ok: false, error: "no_such_template" }); | |
| 123 | expect(await ask(user, "boss/open")).toMatchObject({ ok: true }); | |
| 124 | }); | |
| 125 | ||
| 126 | test("a template over the caps is refused", async () => { | |
| 127 | const { app, admin, user, repo } = await world(); | |
| 128 | await repo("big", "public", [ | |
| 129 | { path: "TEMPLATE.md", content: "#" }, | |
| 130 | { path: "template.json", content: spec("Big") }, | |
| 131 | { path: "huge.txt", content: "x".repeat(MAX_FILE_BYTES + 1) }, | |
| 132 | ]); | |
| 133 | changeTemplates(app, admin, "boss/big"); | |
| 134 | expect(await templateFiles(app, user, "boss/big", { name: "n", description: "" })).toEqual({ | |
| 135 | ok: false, | |
| 136 | error: "template_too_big", | |
| 137 | }); | |
| 138 | }); | |
| 139 | ||
| 140 | test("only a forge admin who is a person marks templates, and only owner/name is taken", async () => { | |
| 141 | const { app, admin, user } = await world(); | |
| 142 | expect(changeTemplates(app, user, "a/b")).toEqual({ ok: false, error: "not_found" }); | |
| 143 | expect(readTemplates(app, user)).toEqual({ ok: false, error: "not_found" }); | |
| 144 | for (const bad of ["a", "a/b/c", "../x/y", "a/b;rm", 5, null]) { | |
| 145 | expect(changeTemplates(app, admin, bad)).toEqual({ ok: false, error: "invalid_templates" }); | |
| 146 | } | |
| 147 | expect(changeTemplates(app, admin, "")).toEqual({ ok: true, value: [] }); | |
| 148 | }); |
new above
offline