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 #10458
scout/forge:scout/10437-new-app-picks-from-admin-marked-template → main 5 commits fork
11 files
changed +462
−10
docs/features/app-template.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # App templates | |
| 2 | ||
| 3 | An admin marks repositories as app templates; **New app** starts from one. | |
| 4 | ||
| 5 | - **Marking.** Admins (a person, not an agent) edit "Template repositories" at the foot of `/apps/new`: one `owner/repo` per line. Unset, the list is `trevato/app-template`. The change is a `forge_setting_change` row and an `app_templates.changed` event. | |
| 6 | - **What a template is.** A marked repository whose root holds `TEMPLATE.md` and `template.json` is one template. Otherwise each top-level folder holding both is one (id `owner/repo/folder`). | |
| 7 | - **Picker.** `/apps/new` shows "Start from" when more than one is offered to you, and a line when exactly one is; none means the forge's starter app. `POST /api/v1/apps` and the `new_app` MCP tool take `template`. | |
| 8 | - **template.json.** `{ "title", "description", "literals": { "<text>": "name" | "description" } }`. Each literal in a copied text file becomes the app's name or description. Nothing else is interpreted, and **no script of the template (e.g. `new.mjs`) is ever run**: it is copied like any file. | |
| 9 | - **Read check.** A template is offered, and copied, only if the caller can read its repository (`canRead`); anything else answers `no_such_template`. | |
| 10 | - **Caps** (`TEMPLATE_CAPS`): 20 marked repositories, 30 folders per repository, 200 files, 256 KB per file, 2 MB in all, 8 levels deep. Over a cap the app is refused (`template_too_large`) before a repository exists. Symlinks, submodules, `.git`, `TEMPLATE.md` and `template.json` are not copied. |
scripts/unreached-allow.json −1
| @@ -15,7 +15,6 @@ | ||
| 15 | 15 | "src/flow/review_rounds.ts", |
| 16 | 16 | "src/flow/shared_red.ts", |
| 17 | 17 | "src/flow/stale_fold.ts", |
| 18 | "src/kernel/why_now.ts", | |
| 19 | 18 | "src/spawn/pod.ts", |
| 20 | 19 | "src/tui/gallery.ts", |
| 21 | 20 | "src/tui/ui/qr.ts", |
src/actions/apps.ts +25 −4
| @@ -15,6 +15,7 @@ import { NO_SUCH_AGENT } from "./crew_limit_words.ts"; | ||
| 15 | 15 | import { requireVerified } from "./verify.ts"; |
| 16 | 16 | import { requireAppRoom } from "./app_limit.ts"; |
| 17 | 17 | import type { App } from "../app.ts"; |
| 18 | import type { FileWrite } from "../git/write.ts"; | |
| 18 | 19 | import { checkWord, type CheckWord } from "../apps/check_word.ts"; |
| 19 | 20 | import { openPulls } from "../apps/door_pulls.ts"; |
| 20 | 21 | import { goldenPath, goldenPathLine } from "../apps/golden_path.ts"; |
| @@ -23,6 +24,7 @@ import { appsRuntime, envsFor, type EnvStatus } from "../apps/runtime.ts"; | ||
| 23 | 24 | import { grantUrl, originFor, sideForViewer, sideReader } from "../apps/proxy.ts"; |
| 24 | 25 | import { plainLine } from "../apps/side.ts"; |
| 25 | 26 | import { scaffoldFiles } from "../apps/scaffold.ts"; |
| 27 | import { templateFilesFor } from "../apps/templates.ts"; | |
| 26 | 28 | import { |
| 27 | 29 | envBuild, |
| 28 | 30 | isEnvName, |
| @@ -270,6 +272,8 @@ export interface NewAppInput { | ||
| 270 | 272 | * also given. |
| 271 | 273 | */ |
| 272 | 274 | pickAgent?: boolean; |
| 275 | /** A marked template (`owner/repo` or `owner/repo/folder`) to start from, instead of the starter app. */ | |
| 276 | template?: string; | |
| 273 | 277 | } |
| 274 | 278 | |
| 275 | 279 | export interface NewAppResult { |
| @@ -285,6 +289,8 @@ export type NewAppError = | ||
| 285 | 289 | | CreateRepoActionError |
| 286 | 290 | | CreateAppError |
| 287 | 291 | | "scaffold_failed" |
| 292 | | "no_such_template" | |
| 293 | | "template_too_large" | |
| 288 | 294 | | "no_such_agent" |
| 289 | 295 | | "not_a_builder" |
| 290 | 296 | | "app_limit"; |
| @@ -328,6 +334,17 @@ export async function newApp( | ||
| 328 | 334 | ) |
| 329 | 335 | return err("slug_taken"); |
| 330 | 336 | |
| 337 | // A template is read, checked and filled before a repository exists to take back. | |
| 338 | let files: FileWrite[] | undefined; | |
| 339 | if (input.template !== undefined && input.template !== "") { | |
| 340 | const copied = await templateFilesFor(app, user.value, input.template, { | |
| 341 | name: input.name, | |
| 342 | description: input.description ?? "", | |
| 343 | }); | |
| 344 | if (!copied.ok) return copied; | |
| 345 | files = copied.value; | |
| 346 | } | |
| 347 | ||
| 331 | 348 | let mark = performance.now(); |
| 332 | 349 | const lap = (name: string): void => { |
| 333 | 350 | const now = performance.now(); |
| @@ -344,10 +361,12 @@ export async function newApp( | ||
| 344 | 361 | if (!repo.ok) return repo; |
| 345 | 362 | const committed = await commitToBranch(app, user.value, repo.value, { |
| 346 | 363 | message: `Start ${input.name}`, |
| 347 | files: scaffoldFiles({ | |
| 348 | name: input.name, | |
| 349 | description: input.description ?? "", | |
| 350 | }), | |
| 364 | files: | |
| 365 | files ?? | |
| 366 | scaffoldFiles({ | |
| 367 | name: input.name, | |
| 368 | description: input.description ?? "", | |
| 369 | }), | |
| 351 | 370 | }); |
| 352 | 371 | lap("scaffold"); |
| 353 | 372 | if (!committed.ok) { |
| @@ -462,6 +481,8 @@ export const NEW_APP_ERRORS: Record<string, string> = { | ||
| 462 | 481 | "Another app already answers to that hostname. Pick another name.", |
| 463 | 482 | already_app: "That repository is already an app.", |
| 464 | 483 | scaffold_failed: "The starter app could not be committed.", |
| 484 | no_such_template: "That template is not on offer to you.", | |
| 485 | template_too_large: "That template is larger than a new app may copy.", | |
| 465 | 486 | no_such_agent: NO_SUCH_AGENT, |
| 466 | 487 | not_a_builder: "That agent is not a builder, so it cannot be handed a new app. Pick a builder.", |
| 467 | 488 | }; |
src/apps/templates.ts added +232
| @@ -0,0 +1,232 @@ | ||
| 1 | /** | |
| 2 | * App templates (#10437): repositories an admin marked as the places a new | |
| 3 | * app can start from. A marked repository is one template when its root | |
| 4 | * holds `TEMPLATE.md` and `template.json`, or one template per folder that | |
| 5 | * holds both. The forge copies files and fills `template.json`'s literals; | |
| 6 | * it never runs anything the template carries (a `new.mjs` is just a file). | |
| 7 | * | |
| 8 | * template.json: { "title"?: string, "description"?: string, | |
| 9 | * "literals"?: { "<text in files>": "name" | "description" } } | |
| 10 | * Every occurrence of a literal in a copied text file becomes the app's name | |
| 11 | * or description. Nothing else is interpreted. | |
| 12 | * | |
| 13 | * A template id is `owner/repo` or `owner/repo/folder`. The marked list is a | |
| 14 | * JSON array under `forge_setting` key `app_templates`; unset, it is | |
| 15 | * `DEFAULT_TEMPLATES`. Reads are checked with `canRead` on the caller. | |
| 16 | */ | |
| 17 | ||
| 18 | import type { Database } from "bun:sqlite"; | |
| 19 | import type { App } from "../app.ts"; | |
| 20 | import { canRead, getRepo, type Repo } from "../core/repos.ts"; | |
| 21 | import type { User } from "../core/users.ts"; | |
| 22 | import { blobForRender, listTree } 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 | ||
| 27 | export const DEFAULT_TEMPLATES: readonly string[] = ["trevato/app-template"]; | |
| 28 | const KEY = "app_templates"; | |
| 29 | ||
| 30 | /** What a copy may hold. */ | |
| 31 | export const TEMPLATE_CAPS = { | |
| 32 | repos: 20, | |
| 33 | folders: 30, | |
| 34 | files: 200, | |
| 35 | fileBytes: 256 * 1024, | |
| 36 | totalBytes: 2 * 1024 * 1024, | |
| 37 | depth: 8, | |
| 38 | manifestBytes: 16 * 1024, | |
| 39 | literals: 20, | |
| 40 | literalLength: 64, | |
| 41 | } as const; | |
| 42 | ||
| 43 | export interface TemplateOffer { | |
| 44 | /** `owner/repo` or `owner/repo/folder`. */ | |
| 45 | readonly id: string; | |
| 46 | readonly title: string; | |
| 47 | readonly description: string; | |
| 48 | } | |
| 49 | ||
| 50 | const REPO_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/; | |
| 51 | const FOLDER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/; | |
| 52 | ||
| 53 | /** The marked repositories, `owner/repo` each. */ | |
| 54 | export function markedTemplates(db: Database): string[] { | |
| 55 | const row = db | |
| 56 | .query<{ value: string }, [string]>("SELECT value FROM forge_setting WHERE key = ?1") | |
| 57 | .get(KEY); | |
| 58 | if (row === null) return [...DEFAULT_TEMPLATES]; | |
| 59 | try { | |
| 60 | const data: unknown = JSON.parse(row.value); | |
| 61 | if (Array.isArray(data)) | |
| 62 | return data.filter((s): s is string => typeof s === "string" && REPO_ID.test(s)).slice(0, TEMPLATE_CAPS.repos); | |
| 63 | } catch { | |
| 64 | // A malformed value is the default, never a failed page. | |
| 65 | } | |
| 66 | return [...DEFAULT_TEMPLATES]; | |
| 67 | } | |
| 68 | ||
| 69 | /** An admin who is a person replaces the marked list; anyone else is told `not_found`. */ | |
| 70 | export function markTemplates(app: App, actor: User | undefined, input: readonly string[]): Result<string[], "not_found" | "invalid"> { | |
| 71 | if (actor?.isAdmin !== true || actor.kind === "agent") return err("not_found"); | |
| 72 | const seen: string[] = []; | |
| 73 | for (const raw of input) { | |
| 74 | const id = raw.trim(); | |
| 75 | if (id === "") continue; | |
| 76 | if (!REPO_ID.test(id)) return err("invalid"); | |
| 77 | if (!seen.includes(id)) seen.push(id); | |
| 78 | } | |
| 79 | if (seen.length > TEMPLATE_CAPS.repos) return err("invalid"); | |
| 80 | const at = new Date().toISOString(); | |
| 81 | const from = JSON.stringify(markedTemplates(app.db)); | |
| 82 | const to = JSON.stringify(seen); | |
| 83 | app.db.transaction(() => { | |
| 84 | app.db | |
| 85 | .query( | |
| 86 | `INSERT INTO forge_setting (key, value, updated_by, updated_at) VALUES (?1, ?2, ?3, ?4) | |
| 87 | ON CONFLICT (key) DO UPDATE SET value = excluded.value, | |
| 88 | updated_by = excluded.updated_by, updated_at = excluded.updated_at`, | |
| 89 | ) | |
| 90 | .run(KEY, to, actor.id, at); | |
| 91 | app.db | |
| 92 | .query("INSERT INTO forge_setting_change (key, from_value, to_value, actor_id, at) VALUES (?1, ?2, ?3, ?4, ?5)") | |
| 93 | .run(KEY, from, to, actor.id, at); | |
| 94 | })(); | |
| 95 | app.bus.append({ kind: "app_templates.changed", actorId: actor.id, payload: { templates: seen } }); | |
| 96 | return ok(seen); | |
| 97 | } | |
| 98 | ||
| 99 | interface Manifest { | |
| 100 | readonly title: string; | |
| 101 | readonly description: string; | |
| 102 | readonly literals: ReadonlyMap<string, "name" | "description">; | |
| 103 | } | |
| 104 | ||
| 105 | /** Parse template.json; anything off is `undefined`, so the folder is not offered. */ | |
| 106 | export function parseManifest(raw: string, fallbackTitle: string): Manifest | undefined { | |
| 107 | let data: unknown; | |
| 108 | try { | |
| 109 | data = JSON.parse(raw); | |
| 110 | } catch { | |
| 111 | return undefined; | |
| 112 | } | |
| 113 | if (typeof data !== "object" || data === null || Array.isArray(data)) return undefined; | |
| 114 | const o = data as Record<string, unknown>; | |
| 115 | const text = (v: unknown, max: number): string => (typeof v === "string" ? v.trim().slice(0, max) : ""); | |
| 116 | const literals = new Map<string, "name" | "description">(); | |
| 117 | const given = o["literals"]; | |
| 118 | if (given !== undefined) { | |
| 119 | if (typeof given !== "object" || given === null || Array.isArray(given)) return undefined; | |
| 120 | for (const [k, v] of Object.entries(given)) { | |
| 121 | if (k === "" || k.length > TEMPLATE_CAPS.literalLength) return undefined; | |
| 122 | if (v !== "name" && v !== "description") return undefined; | |
| 123 | literals.set(k, v); | |
| 124 | } | |
| 125 | if (literals.size > TEMPLATE_CAPS.literals) return undefined; | |
| 126 | } | |
| 127 | return { title: text(o["title"], 80) || fallbackTitle, description: text(o["description"], 300), literals }; | |
| 128 | } | |
| 129 | ||
| 130 | async function readText(dir: string, rev: string, path: string, max: number): Promise<string | undefined> { | |
| 131 | const blob = await blobForRender(dir, rev, path, max); | |
| 132 | return blob.kind === "text" ? new TextDecoder().decode(blob.body) : undefined; | |
| 133 | } | |
| 134 | ||
| 135 | async function readableRepo(app: App, viewer: User | undefined, id: string): Promise<Repo | undefined> { | |
| 136 | const [owner, name] = id.split("/"); | |
| 137 | if (owner === undefined || name === undefined) return undefined; | |
| 138 | const repo = getRepo(app.db, owner, name); | |
| 139 | return repo !== undefined && canRead(app.db, repo, viewer) ? repo : undefined; | |
| 140 | } | |
| 141 | ||
| 142 | /** The templates the viewer is offered: marked repositories they can read, each root or folder holding both files. */ | |
| 143 | export async function offeredTemplates(app: App, viewer: User | undefined): Promise<TemplateOffer[]> { | |
| 144 | const out: TemplateOffer[] = []; | |
| 145 | for (const id of markedTemplates(app.db)) { | |
| 146 | const repo = await readableRepo(app, viewer, id); | |
| 147 | if (repo === undefined) continue; | |
| 148 | const dir = repoDir(app.reposRoot, repo.ownerName, repo.name); | |
| 149 | const rev = repo.defaultBranch; | |
| 150 | const root = await listTree(dir, rev, ""); | |
| 151 | if (!root.ok) continue; | |
| 152 | const has = (entries: readonly { name: string; type: string }[]): boolean => | |
| 153 | entries.some((e) => e.type === "blob" && e.name === "TEMPLATE.md") && | |
| 154 | entries.some((e) => e.type === "blob" && e.name === "template.json"); | |
| 155 | const offerOf = async (path: string, offerId: string, fallback: string): Promise<void> => { | |
| 156 | const raw = await readText(dir, rev, path === "" ? "template.json" : `${path}/template.json`, TEMPLATE_CAPS.manifestBytes); | |
| 157 | const manifest = raw === undefined ? undefined : parseManifest(raw, fallback); | |
| 158 | if (manifest) out.push({ id: offerId, title: manifest.title, description: manifest.description }); | |
| 159 | }; | |
| 160 | if (has(root.value)) { | |
| 161 | await offerOf("", id, repo.name); | |
| 162 | continue; | |
| 163 | } | |
| 164 | for (const folder of root.value.filter((e) => e.type === "tree" && FOLDER.test(e.name)).slice(0, TEMPLATE_CAPS.folders)) { | |
| 165 | const inner = await listTree(dir, rev, folder.name); | |
| 166 | if (inner.ok && has(inner.value)) await offerOf(folder.name, `${id}/${folder.name}`, folder.name); | |
| 167 | } | |
| 168 | } | |
| 169 | return out; | |
| 170 | } | |
| 171 | ||
| 172 | export type TemplateError = "no_such_template" | "template_too_large"; | |
| 173 | ||
| 174 | /** | |
| 175 | * The files a new app starts with from template `id`, literals filled. The | |
| 176 | * id must be one the viewer is offered. TEMPLATE.md and template.json stay | |
| 177 | * behind; symlinks and submodules are not copied; caps refuse, not truncate. | |
| 178 | */ | |
| 179 | export async function templateFilesFor( | |
| 180 | app: App, | |
| 181 | viewer: User | undefined, | |
| 182 | id: string, | |
| 183 | fill: { readonly name: string; readonly description: string }, | |
| 184 | ): Promise<Result<FileWrite[], TemplateError>> { | |
| 185 | const offers = await offeredTemplates(app, viewer); | |
| 186 | if (!offers.some((o) => o.id === id)) return err("no_such_template"); | |
| 187 | const parts = id.split("/"); | |
| 188 | const repo = (await readableRepo(app, viewer, `${parts[0]}/${parts[1]}`))!; | |
| 189 | const base = parts[2] ?? ""; | |
| 190 | const dir = repoDir(app.reposRoot, repo.ownerName, repo.name); | |
| 191 | const rev = repo.defaultBranch; | |
| 192 | const raw = await readText(dir, rev, base === "" ? "template.json" : `${base}/template.json`, TEMPLATE_CAPS.manifestBytes); | |
| 193 | const manifest = raw === undefined ? undefined : parseManifest(raw, repo.name); | |
| 194 | if (manifest === undefined) return err("no_such_template"); | |
| 195 | ||
| 196 | const files: FileWrite[] = []; | |
| 197 | let total = 0; | |
| 198 | const walk = async (rel: string, depth: number): Promise<boolean> => { | |
| 199 | if (depth > TEMPLATE_CAPS.depth) return false; | |
| 200 | const tree = await listTree(dir, rev, base === "" ? rel : rel === "" ? base : `${base}/${rel}`); | |
| 201 | if (!tree.ok) return false; | |
| 202 | for (const e of tree.value) { | |
| 203 | if (e.name === ".git" || e.name.includes("\0")) continue; | |
| 204 | const path = rel === "" ? e.name : `${rel}/${e.name}`; | |
| 205 | if (e.type === "tree") { | |
| 206 | if (!(await walk(path, depth + 1))) return false; | |
| 207 | continue; | |
| 208 | } | |
| 209 | // Symlinks (120000) and submodules (commit) are never copied. | |
| 210 | if (e.type !== "blob" || e.mode === "120000") continue; | |
| 211 | if (rel === "" && (e.name === "TEMPLATE.md" || e.name === "template.json")) continue; | |
| 212 | if (files.length >= TEMPLATE_CAPS.files) return false; | |
| 213 | if (e.size > TEMPLATE_CAPS.fileBytes) return false; | |
| 214 | const full = base === "" ? path : `${base}/${path}`; | |
| 215 | const blob = await blobForRender(dir, rev, full, TEMPLATE_CAPS.fileBytes); | |
| 216 | if (blob.kind !== "text" && blob.kind !== "binary") return false; | |
| 217 | total += blob.body.byteLength; | |
| 218 | if (total > TEMPLATE_CAPS.totalBytes) return false; | |
| 219 | const mode = e.mode === "100755" ? "100755" : "100644"; | |
| 220 | if (blob.kind === "binary") { | |
| 221 | files.push({ path, content: blob.body, mode }); | |
| 222 | continue; | |
| 223 | } | |
| 224 | let text = new TextDecoder().decode(blob.body); | |
| 225 | for (const [literal, key] of manifest.literals) text = text.split(literal).join(fill[key]); | |
| 226 | files.push({ path, content: text, mode }); | |
| 227 | } | |
| 228 | return true; | |
| 229 | }; | |
| 230 | if (!(await walk("", 0))) return err("template_too_large"); | |
| 231 | return ok(files); | |
| 232 | } |
src/contract/openapi/routes/postApiV1Apps.ts +3 −1
| @@ -1,13 +1,15 @@ | ||
| 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", |
| 8 | 8 | app_limit: "the owner is at the app limit", |
| 9 | 9 | no_such_agent: "`agent` names no one on the crew", |
| 10 | 10 | slug_taken: "another app already has this name's slug", |
| 11 | no_such_template: "`template` is not one the caller is offered (a marked repository they can read)", | |
| 12 | template_too_large: "the template holds more than a new app may copy", | |
| 11 | 13 | name_taken: "the owner already has a repository of this name", |
| 12 | 14 | }; |
| 13 | 15 |
src/core/event_audience.ts +1
| @@ -172,6 +172,7 @@ const READER_KINDS: ReadonlySet<string> = new Set([ | ||
| 172 | 172 | "issue.confirmed", |
| 173 | 173 | "capacity.changed", |
| 174 | 174 | "shield.changed", |
| 175 | "app_templates.changed", | |
| 175 | 176 | "traffic.capture_started", |
| 176 | 177 | "traffic.networks_imported", |
| 177 | 178 | "crew.governed", |
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" && input.template !== "" ? { 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/mcp/tools/new_app.ts +3 −1
| @@ -19,7 +19,7 @@ async function fromSentence(app: App, user: User, sentence: string, input: Omit< | ||
| 19 | 19 | |
| 20 | 20 | export const tool: Tool = { |
| 21 | 21 | name: "new_app", |
| 22 | doc: "`{ name?, sentence?, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence: with `sentence` and no `name` the name is derived from it (`-2`, `-3` when taken), as the web and terminal do; `name` and `sentence` together keep the name; the first issue is `description`, else `sentence`; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken)", | |
| 22 | doc: "`{ name?, sentence?, description?, owner?, visibility?, agent?, pick?, template? }`: make an app from a sentence: with `sentence` and no `name` the name is derived from it (`-2`, `-3` when taken), as the web and terminal do; `name` and `sentence` together keep the name; the first issue is `description`, else `sentence`; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken)", | |
| 23 | 23 | description: |
| 24 | 24 | "Make an app from a sentence: a repo, production, and with `description` a first issue.", |
| 25 | 25 | inputSchema: { |
| @@ -32,6 +32,7 @@ export const tool: Tool = { | ||
| 32 | 32 | visibility: { type: "string", enum: ["public", "private"] }, |
| 33 | 33 | agent: { type: "string", maxLength: 39 }, |
| 34 | 34 | pick: { type: "boolean" }, |
| 35 | template: { type: "string", maxLength: 200, description: "A marked template, owner/repo or owner/repo/folder." }, | |
| 35 | 36 | }, |
| 36 | 37 | }, |
| 37 | 38 | writes: true, |
| @@ -47,6 +48,7 @@ export const tool: Tool = { | ||
| 47 | 48 | ...(visibility === "public" || visibility === "private" ? { visibility } : {}), |
| 48 | 49 | ...(agent === undefined ? {} : { agent }), |
| 49 | 50 | ...(args["pick"] === true ? { pickAgent: true } : {}), |
| 51 | ...(text("template") ? { template: text("template") as string } : {}), | |
| 50 | 52 | }; |
| 51 | 53 | const given = str(args["name"]).trim(); |
| 52 | 54 | const first = description ?? sentence; |
src/http/server.ts +2
| @@ -321,6 +321,7 @@ import { | ||
| 321 | 321 | appStop, |
| 322 | 322 | newAppPage, |
| 323 | 323 | newAppSubmit, |
| 324 | appTemplatesSubmit, | |
| 324 | 325 | } from "../web/pages/apps.ts"; |
| 325 | 326 | import { |
| 326 | 327 | migratePage, |
| @@ -908,6 +909,7 @@ export function buildRouter(): Router<Handler> { | ||
| 908 | 909 | router.add("GET", "/apps", appsList); |
| 909 | 910 | router.add("GET", "/apps/new", newAppPage); |
| 910 | 911 | router.add("POST", "/apps/new", newAppSubmit); |
| 912 | router.add("POST", "/apps/templates", appTemplatesSubmit); | |
| 911 | 913 | // Migrate: a repository brought here for good, and the page that watches |
| 912 | 914 | // the clone. Literal routes, above /:owner for the same reason. |
| 913 | 915 | router.add("GET", "/migrate", migratePage); |
src/web/pages/apps.ts +57 −3
| @@ -30,6 +30,7 @@ import { | ||
| 30 | 30 | } from "../../actions/apps.ts"; |
| 31 | 31 | import { listAllAgents } from "../../actions/crew.ts"; |
| 32 | 32 | import { planningAvailable } from "../../crew/plan.ts"; |
| 33 | import { markedTemplates, markTemplates, offeredTemplates, type TemplateOffer } from "../../apps/templates.ts"; | |
| 33 | 34 | import { appNameJs } from "./apps-name.ts"; |
| 34 | 35 | import { STARTERS, starterFromQuery, starterHref } from "./apps-starters.ts"; |
| 35 | 36 | import { previewEnv, type EnvName } from "../../apps/data.ts"; |
| @@ -283,6 +284,8 @@ interface NewAppValues { | ||
| 283 | 284 | description: string; |
| 284 | 285 | visibility: string; |
| 285 | 286 | agent: string; |
| 287 | /** A template id, or "" for the starter app. */ | |
| 288 | template?: string; | |
| 286 | 289 | } |
| 287 | 290 | |
| 288 | 291 | /** The agent select's sentinel for "turn the sentence into a plan and pick". */ |
| @@ -299,6 +302,7 @@ function newAppForm( | ||
| 299 | 302 | ctx: Ctx, |
| 300 | 303 | values: NewAppValues, |
| 301 | 304 | canPlan: boolean, |
| 305 | offers: readonly TemplateOffer[], | |
| 302 | 306 | error?: string, |
| 303 | 307 | ): Html { |
| 304 | 308 | const user = ctx.auth.user!; |
| @@ -348,6 +352,24 @@ function newAppForm( | ||
| 348 | 352 | }), |
| 349 | 353 | )} |
| 350 | 354 | </div> |
| 355 | ${offers.length > 1 | |
| 356 | ? selectField({ | |
| 357 | label: "Start from", | |
| 358 | name: "template", | |
| 359 | hint: "The files are copied; nothing in a template is run.", | |
| 360 | options: [ | |
| 361 | { value: "", label: "The forge's starter app", selected: !values.template }, | |
| 362 | ...offers.map((o) => ({ | |
| 363 | value: o.id, | |
| 364 | label: o.description === "" ? o.title : `${o.title} — ${o.description}`, | |
| 365 | selected: values.template === o.id, | |
| 366 | })), | |
| 367 | ], | |
| 368 | }) | |
| 369 | : offers.length === 1 | |
| 370 | ? html`<input type="hidden" name="template" value="${offers[0]!.id}" /> | |
| 371 | <p class="muted small mb">Starts from ${offers[0]!.title}${offers[0]!.description === "" ? "" : ` — ${offers[0]!.description}`}.</p>` | |
| 372 | : ""} | |
| 351 | 373 | ${selectField({ |
| 352 | 374 | label: "Owner", |
| 353 | 375 | name: "owner", |
| @@ -430,15 +452,29 @@ function newAppForm( | ||
| 430 | 452 | ${btn("Cancel", { href: "/apps", variant: "ghost" })} |
| 431 | 453 | </div> |
| 432 | 454 | </form>`} |
| 455 | ${user.isAdmin && user.kind !== "agent" | |
| 456 | ? html`<form method="post" action="/apps/templates" class="mb"> | |
| 457 | ${formField({ | |
| 458 | label: "Template repositories", | |
| 459 | name: "repos", | |
| 460 | type: "textarea", | |
| 461 | rows: 3, | |
| 462 | value: markedTemplates(ctx.app.db).join("\n"), | |
| 463 | hint: "Admins: one owner/repo per line. A repository is a template when its root, or each of its folders, holds TEMPLATE.md and template.json.", | |
| 464 | })} | |
| 465 | <div class="form-actions">${btn("Save templates", { variant: "outline" })}</div> | |
| 466 | </form>` | |
| 467 | : ""} | |
| 433 | 468 | <p class="muted">Already have an app on another forge? <a href="/bring">Bring it here whole</a>.</p> |
| 434 | 469 | </div>`; |
| 435 | 470 | } |
| 436 | 471 | |
| 437 | 472 | // GET /apps/new |
| 438 | export function newAppPage(ctx: Ctx): Response { | |
| 473 | export async function newAppPage(ctx: Ctx): Promise<Response> { | |
| 439 | 474 | if (!ctx.auth.user) return signInFirst(ctx); |
| 440 | 475 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 441 | 476 | const picks = plannerOffered(ctx); |
| 477 | const offers = await offeredTemplates(ctx.app, ctx.auth.user); | |
| 442 | 478 | const rendering = performance.now(); |
| 443 | 479 | const response = page({ |
| 444 | 480 | ctx, |
| @@ -449,7 +485,8 @@ export function newAppPage(ctx: Ctx): Response { | ||
| 449 | 485 | description: starterFromQuery(ctx.url.searchParams.get("description")), |
| 450 | 486 | visibility: "private", |
| 451 | 487 | agent: picks ? PICK_AGENT : "", |
| 452 | }, picks), | |
| 488 | template: ctx.url.searchParams.get("template") ?? "", | |
| 489 | }, picks, offers), | |
| 453 | 490 | scriptJs: appNameJs, |
| 454 | 491 | }); |
| 455 | 492 | notePhase(ctx.request, "render", performance.now() - rendering); |
| @@ -469,7 +506,9 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 469 | 506 | description: field(form, "description"), |
| 470 | 507 | visibility: field(form, "visibility") === "public" ? "public" : "private", |
| 471 | 508 | agent: field(form, "agent"), |
| 509 | template: field(form, "template"), | |
| 472 | 510 | }; |
| 511 | const offers = await offeredTemplates(ctx.app, ctx.auth.user); | |
| 473 | 512 | const pickAgent = values.agent === PICK_AGENT; |
| 474 | 513 | // An explicit name is never second-guessed; left blank, the sentence |
| 475 | 514 | // names the app — and the server derives that name itself (never trusting |
| @@ -478,6 +517,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 478 | 517 | const rest = { |
| 479 | 518 | owner: values.owner, |
| 480 | 519 | visibility: values.visibility === "public" ? "public" : "private", |
| 520 | ...(values.template ? { template: values.template } : {}), | |
| 481 | 521 | ...(pickAgent |
| 482 | 522 | ? { pickAgent: true } |
| 483 | 523 | : values.agent === "" |
| @@ -503,7 +543,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 503 | 543 | { |
| 504 | 544 | ctx, |
| 505 | 545 | title: "New app", |
| 506 | body: newAppForm(ctx, values, plannerOffered(ctx), NO_NAME_ERROR), | |
| 546 | body: newAppForm(ctx, values, plannerOffered(ctx), offers, NO_NAME_ERROR), | |
| 507 | 547 | scriptJs: appNameJs, |
| 508 | 548 | }, |
| 509 | 549 | 422, |
| @@ -524,6 +564,7 @@ export async function newAppSubmit(ctx: Ctx): Promise<Response> { | ||
| 524 | 564 | ctx, |
| 525 | 565 | values, |
| 526 | 566 | plannerOffered(ctx), |
| 567 | offers, | |
| 527 | 568 | made.error === "repository_limit" |
| 528 | 569 | ? `Not made: ${repositoryLimitMessage(ctx.app, ctx.auth.user!)}.` |
| 529 | 570 | : made.error === "storage_limit" |
| @@ -883,3 +924,16 @@ export async function appStop(ctx: Ctx): Promise<Response> { | ||
| 883 | 924 | message: stoppedText(env as EnvName), |
| 884 | 925 | }); |
| 885 | 926 | } |
| 927 | ||
| 928 | // POST /apps/templates — an admin sets which repositories are app templates. | |
| 929 | export async function appTemplatesSubmit(ctx: Ctx): Promise<Response> { | |
| 930 | if (!ctx.auth.user) return signInFirst(ctx); | |
| 931 | const form = await readForm(ctx, "rw"); | |
| 932 | if (form instanceof Response) return form; | |
| 933 | const marked = markTemplates(ctx.app, ctx.auth.user, field(form, "repos").split(/\r?\n/)); | |
| 934 | if (!marked.ok) | |
| 935 | return marked.error === "not_found" | |
| 936 | ? forbiddenPage(ctx, NOT_YOURS_TO_DO) | |
| 937 | : page({ ctx, title: "New app", body: html`<div class="narrow-wide"><p>Each line must be owner/repo.</p><p><a href="/apps/new">Back</a></p></div>` }, 422); | |
| 938 | return flashTo(ctx, "/apps/new", { message: "Template repositories saved." }); | |
| 939 | } |
test/app-templates.test.ts added +128
| @@ -0,0 +1,128 @@ | ||
| 1 | /** | |
| 2 | * App templates (#10437): marked repositories, one template per repository | |
| 3 | * or per folder, files copied with literals filled and nothing run; the | |
| 4 | * caller's read right and the caps hold. | |
| 5 | */ | |
| 6 | ||
| 7 | import { afterAll, beforeAll, describe, expect, setDefaultTimeout, test } from "bun:test"; | |
| 8 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 9 | import { tmpdir } from "node:os"; | |
| 10 | import { join } from "node:path"; | |
| 11 | import { createApp, type App } from "../src/app.ts"; | |
| 12 | import { newApp } from "../src/actions/apps.ts"; | |
| 13 | import { commitToBranch, createRepo } from "../src/actions/repos.ts"; | |
| 14 | import { markTemplates, markedTemplates, offeredTemplates, parseManifest, TEMPLATE_CAPS } from "../src/apps/templates.ts"; | |
| 15 | import { getRepo } from "../src/core/repos.ts"; | |
| 16 | import { createUser, type User } from "../src/core/users.ts"; | |
| 17 | import { listPaths, blobForRender } from "../src/git/read.ts"; | |
| 18 | import { repoDir } from "../src/git/repos.ts"; | |
| 19 | ||
| 20 | setDefaultTimeout(30_000); | |
| 21 | ||
| 22 | describe("app templates", () => { | |
| 23 | let dataDir: string; | |
| 24 | let app: App; | |
| 25 | let admin: User; | |
| 26 | let bob: User; | |
| 27 | ||
| 28 | const user = async (username: string, adminIfFirst: boolean): Promise<User> => { | |
| 29 | const r = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst }); | |
| 30 | if (!r.ok) throw new Error(r.error); | |
| 31 | return r.value; | |
| 32 | }; | |
| 33 | const repoWith = async (name: string, visibility: "public" | "private", files: { path: string; content: string }[]) => { | |
| 34 | const r = await createRepo(app, admin, { name, visibility }); | |
| 35 | if (!r.ok) throw new Error(String(r.error)); | |
| 36 | const c = await commitToBranch(app, admin, r.value, { message: "Start", files }); | |
| 37 | if (!c.ok) throw new Error(JSON.stringify(c.error)); | |
| 38 | }; | |
| 39 | const manifest = JSON.stringify({ title: "Shop", description: "A shop", literals: { __NAME__: "name", __ABOUT__: "description" } }); | |
| 40 | ||
| 41 | beforeAll(async () => { | |
| 42 | dataDir = await mkdtemp(join(tmpdir(), "forge-templates-")); | |
| 43 | app = createApp({ dataDir, port: 0 }); | |
| 44 | admin = await user("alice", true); | |
| 45 | bob = await user("bob", false); | |
| 46 | await repoWith("single", "public", [ | |
| 47 | { path: "TEMPLATE.md", content: "# how\n" }, | |
| 48 | { path: "template.json", content: manifest }, | |
| 49 | { path: "README.md", content: "# __NAME__\n__ABOUT__\n" }, | |
| 50 | { path: "new.mjs", content: "throw new Error('must never run')\n" }, | |
| 51 | { path: "src/a.txt", content: "hello __NAME__" }, | |
| 52 | ]); | |
| 53 | await repoWith("many", "public", [ | |
| 54 | { path: "one/TEMPLATE.md", content: "x" }, | |
| 55 | { path: "one/template.json", content: JSON.stringify({ title: "One" }) }, | |
| 56 | { path: "one/f.txt", content: "one" }, | |
| 57 | { path: "two/TEMPLATE.md", content: "x" }, | |
| 58 | { path: "two/template.json", content: JSON.stringify({ title: "Two" }) }, | |
| 59 | { path: "two/f.txt", content: "two" }, | |
| 60 | { path: "three/template.json", content: "{}" }, | |
| 61 | ]); | |
| 62 | await repoWith("secret", "private", [ | |
| 63 | { path: "TEMPLATE.md", content: "x" }, | |
| 64 | { path: "template.json", content: "{}" }, | |
| 65 | ]); | |
| 66 | await repoWith("big", "public", [ | |
| 67 | { path: "TEMPLATE.md", content: "x" }, | |
| 68 | { path: "template.json", content: "{}" }, | |
| 69 | { path: "huge.txt", content: "x".repeat(TEMPLATE_CAPS.fileBytes + 1) }, | |
| 70 | ]); | |
| 71 | }); | |
| 72 | afterAll(async () => { | |
| 73 | app.db.close(); | |
| 74 | await rm(dataDir, { recursive: true, force: true }); | |
| 75 | }); | |
| 76 | ||
| 77 | test("the default is trevato/app-template until an admin marks others; only an admin person may", () => { | |
| 78 | expect(markedTemplates(app.db)).toEqual(["trevato/app-template"]); | |
| 79 | expect(markTemplates(app, bob, ["alice/single"])).toEqual({ ok: false, error: "not_found" }); | |
| 80 | expect(markTemplates(app, admin, ["not a repo"])).toEqual({ ok: false, error: "invalid" }); | |
| 81 | expect(markTemplates(app, admin, ["alice/single", "alice/many", "alice/secret", "alice/big", "alice/single"]).ok).toBe(true); | |
| 82 | expect(markedTemplates(app.db)).toEqual(["alice/single", "alice/many", "alice/secret", "alice/big"]); | |
| 83 | }); | |
| 84 | ||
| 85 | test("a repository with folders offers each folder holding both files; a private one only to those who read it", async () => { | |
| 86 | const ids = (await offeredTemplates(app, bob)).map((o) => o.id); | |
| 87 | expect(ids).toEqual(["alice/single", "alice/many/one", "alice/many/two", "alice/big"]); | |
| 88 | const mine = (await offeredTemplates(app, admin)).map((o) => o.id); | |
| 89 | expect(mine).toContain("alice/secret"); | |
| 90 | }); | |
| 91 | ||
| 92 | test("a new app copies the files, fills literals, and leaves the template's own files behind", async () => { | |
| 93 | const made = await newApp(app, admin, { name: "mine", description: "sells socks", template: "alice/single" }); | |
| 94 | if (!made.ok) throw new Error(made.error); | |
| 95 | const dir = repoDir(app.reposRoot, "alice", "mine"); | |
| 96 | const paths = await listPaths(dir, "main"); | |
| 97 | const list = paths.ok ? paths.value.paths : []; | |
| 98 | expect(list).toContain("new.mjs"); | |
| 99 | expect(list).toContain("src/a.txt"); | |
| 100 | expect(list).not.toContain("TEMPLATE.md"); | |
| 101 | expect(list).not.toContain("template.json"); | |
| 102 | const readme = await blobForRender(dir, "main", "README.md", 10_000); | |
| 103 | expect(readme.kind === "text" && new TextDecoder().decode(readme.body)).toBe("# mine\nsells socks\n"); | |
| 104 | }); | |
| 105 | ||
| 106 | test("a folder template copies only its folder", async () => { | |
| 107 | const made = await newApp(app, admin, { name: "second", template: "alice/many/two" }); | |
| 108 | if (!made.ok) throw new Error(made.error); | |
| 109 | const paths = await listPaths(repoDir(app.reposRoot, "alice", "second"), "main"); | |
| 110 | expect(paths.ok && paths.value.paths).toEqual(["f.txt"]); | |
| 111 | }); | |
| 112 | ||
| 113 | test("refused before any repository exists: unmarked, unreadable, or over the caps", async () => { | |
| 114 | const before = (n: string) => getRepo(app.db, "bob", n); | |
| 115 | expect(await newApp(app, bob, { name: "x1", template: "alice/secret" })).toEqual({ ok: false, error: "no_such_template" }); | |
| 116 | expect(await newApp(app, bob, { name: "x2", template: "alice/many/three" })).toEqual({ ok: false, error: "no_such_template" }); | |
| 117 | expect(await newApp(app, bob, { name: "x3", template: "../../etc" })).toEqual({ ok: false, error: "no_such_template" }); | |
| 118 | expect(await newApp(app, admin, { name: "x4", template: "alice/big" })).toEqual({ ok: false, error: "template_too_large" }); | |
| 119 | expect(before("x1")).toBeUndefined(); | |
| 120 | expect(getRepo(app.db, "alice", "x4")).toBeUndefined(); | |
| 121 | }); | |
| 122 | ||
| 123 | test("template.json is checked: bad literals are no template", () => { | |
| 124 | expect(parseManifest("nope", "t")).toBeUndefined(); | |
| 125 | expect(parseManifest(JSON.stringify({ literals: { a: "secret" } }), "t")).toBeUndefined(); | |
| 126 | expect(parseManifest("{}", "fallback")?.title).toBe("fallback"); | |
| 127 | }); | |
| 128 | }); |
new above
offline