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

Parked opened this
Closed without merging

mason/forge:mason/10437-new-app-picks-from-admin-marked-template → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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";
2323 import { grantUrl, originFor, sideForViewer, sideReader } from "../apps/proxy.ts";
2424 import { plainLine } from "../apps/side.ts";
2525 import { scaffoldFiles } from "../apps/scaffold.ts";
26 import { templateFiles, type TemplateError } from "../apps/template_source.ts";
27 import type { FileWrite } from "../git/write.ts";
2628 import {
2729 envBuild,
2830 isEnvName,
@@ -270,6 +272,11 @@ export interface NewAppInput {
270272 * also given.
271273 */
272274 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;
273280 }
274281
275282 export interface NewAppResult {
@@ -285,6 +292,7 @@ export type NewAppError =
285292 | CreateRepoActionError
286293 | CreateAppError
287294 | "scaffold_failed"
295 | TemplateError
288296 | "no_such_agent"
289297 | "not_a_builder"
290298 | "app_limit";
@@ -320,6 +328,17 @@ export async function newApp(
320328 const room = requireAppRoom(app, user.value, ownerId);
321329 if (!room.ok) return room;
322330
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
323342 // Refuse a taken slug before anything exists to take back.
324343 // A name the owner already has stays `name_taken`, which createRepo says.
325344 if (
@@ -344,10 +363,12 @@ export async function newApp(
344363 if (!repo.ok) return repo;
345364 const committed = await commitToBranch(app, user.value, repo.value, {
346365 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 }),
351372 });
352373 lap("scaffold");
353374 if (!committed.ok) {
@@ -462,6 +483,9 @@ export const NEW_APP_ERRORS: Record<string, string> = {
462483 "Another app already answers to that hostname. Pick another name.",
463484 already_app: "That repository is already an app.",
464485 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.",
465489 no_such_agent: NO_SUCH_AGENT,
466490 not_a_builder: "That agent is not a builder, so it cannot be handed a new app. Pick a builder.",
467491 };
src/actions/signup.ts +20
@@ -12,6 +12,7 @@ import {
1212 type SignupChange,
1313 type SignupMode,
1414 } from "../settings/signup.ts";
15 import { markedTemplates, parseTemplates, setTemplates } from "../settings/app_templates.ts";
1516 import { forgeSource, parseForgeSource, setForgeSource, storedForgeSource } from "../settings/forge_source.ts";
1617 import type { User } from "../core/users.ts";
1718 import { err, ok, type Result } from "../kernel/result.ts";
@@ -69,3 +70,22 @@ export function changeForgeSource(
6970 setForgeSource(app.db, name.value, who.value.id);
7071 return ok(name.value);
7172 }
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 @@
11 import type { Route } from "../shared.ts";
22
33 /** 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" };
55 const APP_REFUSALS = {
66 unverified: "the account has not verified its email",
77 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 {
35833583 ...(typeof input.agent === "string" ? { agent: input.agent } : {}),
35843584 // Only a real boolean asks; like the other fields, anything else is ignored.
35853585 ...(input.pick === true ? { pickAgent: true } : {}),
3586 ...(typeof input.template === "string" ? { template: input.template } : {}),
35863587 };
35873588 const onPhase = (name: string, ms: number) => notePhase(ctx.request, name, ms);
35883589 // 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";
3131 import { fleetAct, fleetReceipt, fleetUndo } from "../web/pages/fleet-ops.ts";
3232 import { maintenancePage, maintenancePrepare, maintenanceResume } from "../web/pages/maintenance.ts";
3333 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";
3535 import { allFlowsPage } from "../web/pages/flows-all.ts";
3636 import { measureSubmit } from "./measure.ts";
3737 import { settingsRoutes } from "./settings_routes.ts";
@@ -1010,6 +1010,7 @@ export function buildRouter(): Router<Handler> {
10101010 router.add("POST", "/admin/limits", limitsSet);
10111011 router.add("POST", "/admin/quotas", quotasSet);
10121012 router.add("POST", "/admin/signup", signupSet);
1013 router.add("POST", "/admin/templates", templatesSet);
10131014 router.add("POST", "/admin/invites", inviteMint);
10141015 router.add("POST", "/admin/invites/:id/revoke", inviteRevoke);
10151016
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";
1111 import { inviteLink, list as listInviteLinks, mint as mintInviteLink, revoke as revokeInviteLink } from "../../actions/invites.ts";
1212 import { INVITE_NOT_OPEN } from "../../actions/sever_invite_words.ts";
1313 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";
1515 import { SIGNUP_MODES } from "../../settings/signup.ts";
1616 import { QUOTA_KEYS } from "../../settings/quotas.ts";
1717 import type { Ctx } from "../../http/context.ts";
@@ -135,6 +135,18 @@ export function limitsPage(ctx: Ctx): Response {
135135 </dd>
136136 <dd class="status-act"></dd>
137137 </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>`;
138150 const inviteRows = (invites.ok ? invites.value : []).map((i) =>
139151 row({
140152 lead: icon("activity"),
@@ -177,7 +189,7 @@ export function limitsPage(ctx: Ctx): Response {
177189 const body = html`<p class="small muted mb">
178190 Every limit you can hit, and why. A change applies to the next request that meets it; nothing needs a restart.
179191 </p>
180 <dl class="status-rows">${signupRow}${inviteRow}${quotaRow}</dl>
192 <dl class="status-rows">${signupRow}${templateRow}${inviteRow}${quotaRow}</dl>
181193 ${historyBlock("Invite links made", inviteRows)}
182194 <section class="settings-block mt">
183195 <h2>Limits</h2>
@@ -284,6 +296,23 @@ export async function signupSet(ctx: Ctx): Promise<Response> {
284296 );
285297 }
286298
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
287316 // POST /admin/invites
288317 export async function inviteMint(ctx: Ctx): Promise<Response> {
289318 if (ctx.auth.user?.isAdmin !== true || ctx.auth.user.kind === "agent")
src/web/pages/apps.ts +25 −3
@@ -28,6 +28,7 @@ import {
2828 stopEnv,
2929 terminalFor,
3030 } from "../../actions/apps.ts";
31 import { offeredTemplates, type TemplateOffer } from "../../apps/template_source.ts";
3132 import { listAllAgents } from "../../actions/crew.ts";
3233 import { planningAvailable } from "../../crew/plan.ts";
3334 import { appNameJs } from "./apps-name.ts";
@@ -283,6 +284,8 @@ interface NewAppValues {
283284 description: string;
284285 visibility: string;
285286 agent: string;
287 /** A template key; empty is the built-in starter. */
288 template?: string;
286289 }
287290
288291 /** The agent select's sentinel for "turn the sentence into a plan and pick". */
@@ -300,6 +303,7 @@ function newAppForm(
300303 values: NewAppValues,
301304 canPlan: boolean,
302305 error?: string,
306 offers: readonly TemplateOffer[] = [],
303307 ): Html {
304308 const user = ctx.auth.user!;
305309 const writeOrgs = timePhase(ctx.request, "orgs", () =>
@@ -368,6 +372,18 @@ function newAppForm(
368372 : `Left blank, it comes from your sentence. Use letters, digits, dots, dashes and underscores. It runs at <name>${appHostSuffix(domain)}.`,
369373 ...(error ? { error } : {}),
370374 })}
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``}
371387 ${selectField({
372388 label: "Visibility",
373389 name: "visibility",
@@ -435,10 +451,13 @@ function newAppForm(
435451 }
436452
437453 // GET /apps/new
438 export function newAppPage(ctx: Ctx): Response {
454 export async function newAppPage(ctx: Ctx): Promise<Response> {
439455 if (!ctx.auth.user) return signInFirst(ctx);
440456 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
441457 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);
442461 const rendering = performance.now();
443462 const response = page({
444463 ctx,
@@ -449,7 +468,7 @@ export function newAppPage(ctx: Ctx): Response {
449468 description: starterFromQuery(ctx.url.searchParams.get("description")),
450469 visibility: "private",
451470 agent: picks ? PICK_AGENT : "",
452 }, picks),
471 }, picks, undefined, offers),
453472 scriptJs: appNameJs,
454473 });
455474 notePhase(ctx.request, "render", performance.now() - rendering);
@@ -469,6 +488,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> {
469488 description: field(form, "description"),
470489 visibility: field(form, "visibility") === "public" ? "public" : "private",
471490 agent: field(form, "agent"),
491 template: field(form, "template"),
472492 };
473493 const pickAgent = values.agent === PICK_AGENT;
474494 // An explicit name is never second-guessed; left blank, the sentence
@@ -478,6 +498,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> {
478498 const rest = {
479499 owner: values.owner,
480500 visibility: values.visibility === "public" ? "public" : "private",
501 ...(values.template ? { template: values.template } : {}),
481502 ...(pickAgent
482503 ? { pickAgent: true }
483504 : values.agent === ""
@@ -503,7 +524,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> {
503524 {
504525 ctx,
505526 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)),
507528 scriptJs: appNameJs,
508529 },
509530 422,
@@ -531,6 +552,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> {
531552 : made.error === "app_limit" && ownerId !== undefined
532553 ? appLimitWords(ctx.app, ownerId)
533554 : (NEW_APP_ERRORS[made.error] ?? "That app could not be created."),
555 await offeredTemplates(ctx.app, ctx.auth.user),
534556 ),
535557 scriptJs: appNameJs,
536558 },
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs