Public: anyone can read this; the crew can change it.
The release build takes the app template at a pinned commit #13271
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13258-the-release-build-takes-the-app-template → main 2 commits fork
4 files
changed +74
−9
docs/features/app-template.md +2 −1
| @@ -26,7 +26,8 @@ A marked repository whose top-level folders hold both `TEMPLATE.md` and `templat | ||
| 26 | 26 | The app New app starts from when no template is named is `trevato/app-template` (`apps.template` in `forge_setting` names another), copied at its default branch's tip: one commit, no history (#10305). The strings that used to make it (`src/apps/scaffold.ts`) are gone. |
| 27 | 27 | |
| 28 | 28 | - **Name and description.** The template's `template.json` is `{ "name": "app-template", "description": "A new app on the forge.", "files": [...] }`: the literals the forge replaces, and the only files it replaces them in (`.json` files get the JSON-escaped form). Nothing else is touched, so the template runs and passes its own tests as it stands. `template.json` is not copied. An empty description keeps the template's line. (This is the root template's form; a folder of a template repository uses the `{{name}}` form above.) |
| 29 | - **A copy in every forge.** `templates/app-template.json` is the template's files, carried in the image (`Dockerfile` copies `templates/`). A forge without the repository (a child, a pack forge, a fresh install), or whose copy has no readable `template.json`, uses it; so does `src/spawn/template_birth.ts` (`bakedFiles`). Refresh it with `bun scripts/take-template.ts <checkout>`, which reads bytes and refuses any file that is not UTF-8 text (the bundle is JSON), and marks the bundle `pinned: true` with HEAD as `commit`. A test fails when a pinned bundle's `commit` is not a 40-hex id; the file in the tree says `pinned: false` until it is taken. **Not done:** the file in the tree was generated from the removed strings, so its `commit` is the forge commit they were written at, not a commit of trevato/app-template, and the release build does not yet run `take-template.ts` at a pinned commit; until it does the copy and the repository can differ. | |
| 29 | - **A copy in every forge.** `templates/app-template.json` is the template's files, carried in the image (`Dockerfile` copies `templates/`). A forge without the repository (a child, a pack forge, a fresh install), or whose copy has no readable `template.json`, uses it; so does `src/spawn/template_birth.ts` (`bakedFiles`). Refresh it with `bun scripts/take-template.ts <checkout>`, which reads bytes and refuses any file that is not UTF-8 text (the bundle is JSON), and marks the bundle `pinned: true` with HEAD as `commit`. A test fails when a pinned bundle's `commit` is not a 40-hex id; the file in the tree says `pinned: false` until it is taken. **Not done:** the file in the tree was generated from the removed strings, so its `commit` is the forge commit they were written at, not a commit of trevato/app-template, and nothing yet runs the check below in the release build (child issue of #13258). | |
| 30 | - **The release check.** `bun scripts/take-template.ts --verify <checkout>` writes nothing and exits 1, naming the bundle's pinned commit and the differing files, when a checkout of the template (at the pinned commit) is not what the bundle holds. Calling it from the release workflow is the owner's step: this change touches neither the workflow nor the chart. The bundle in the tree is still `pinned: false` until someone runs `take-template.ts` on a real checkout; a spawn test proves a forge without the repository uses the bundle. | |
| 30 | 31 | - **`apps.template` is operator-only on purpose.** It is a `forge_setting` key with no page or terminal control: which repository every new app copies is a forge-wide choice, set by whoever runs the forge, not by an app owner. A user picks another template per app with `template:` (see above). |
| 31 | 32 | - **Two `template.json` forms, pinned by a test.** The root template names its literals (`name`, `description`, `files`); a folder of a repository of templates uses `files` and `literals`. Each parser rejects the other's form. Both read paths with no dot segments, no `.git`, no absolute path, and the tip copy has the same caps as the rest (500 files, 512 KiB each, 4 MiB; over any falls back to the image's copy). |
| 32 | 33 | - **Checked both ways.** In the template's repository a pull runs its own `bun test`, then `bun scripts/birth-check.ts <checkout>` from this repository, which fills the tip as New app does, boots the result on a port the kernel chose (retried if taken) and waits on `/healthz` and `/`. Wiring that into the template repository's `forge.json` is done in that repository, not here. |
scripts/take-template.ts +33 −8
| @@ -1,22 +1,27 @@ | ||
| 1 | 1 | /** |
| 2 | * `bun scripts/take-template.ts <checkout> [owner/name]`: write | |
| 2 | * `bun scripts/take-template.ts [--verify] <checkout> [owner/name]`: write | |
| 3 | 3 | * `templates/app-template.json`, the copy of the app template every forge |
| 4 | 4 | * carries in its image (#10305), from a checkout of the template repository. |
| 5 | 5 | * The tracked files at HEAD are taken as they are and HEAD is recorded as |
| 6 | * `commit` in the bundle. It is meant to run on a checkout of | |
| 7 | * trevato/app-template at the commit a release pins (the release build does | |
| 8 | * not do so yet); a checkout without a readable `template.json`, or with a | |
| 9 | * file that is not UTF-8 text, is refused. `pinned: true` marks a bundle | |
| 10 | * taken this way; the file in the tree says `pinned: false` until one is. | |
| 6 | * `commit` in the bundle; a checkout without a readable `template.json`, or | |
| 7 | * with a file that is not UTF-8 text, is refused. `pinned: true` marks a | |
| 8 | * bundle taken this way; the file in the tree says `pinned: false` until one | |
| 9 | * is. | |
| 10 | * | |
| 11 | * `--verify` writes nothing: run on a checkout of trevato/app-template at the | |
| 12 | * pinned commit, it exits 1 naming that commit when HEAD or any file differs | |
| 13 | * from the bundle in the tree. No release step calls it yet (#13258). | |
| 11 | 14 | */ |
| 12 | 15 | |
| 13 | 16 | import { parseTemplateSpec } from "../src/apps/template.ts"; |
| 14 | 17 | |
| 15 | const [dir, repo = "trevato/app-template"] = process.argv.slice(2); | |
| 18 | const args = process.argv.slice(2); | |
| 19 | const verify = args.includes("--verify"); | |
| 20 | const [dir, repo = "trevato/app-template"] = args.filter((a) => a !== "--verify"); | |
| 16 | 21 | // FORGE_TEMPLATE_OUT: where to write (tests); default the tree's bundle. |
| 17 | 22 | const out = process.env["FORGE_TEMPLATE_OUT"] ?? `${import.meta.dir}/../templates/app-template.json`; |
| 18 | 23 | if (dir === undefined) { |
| 19 | console.error("usage: bun scripts/take-template.ts <checkout> [owner/name]"); | |
| 24 | console.error("usage: bun scripts/take-template.ts [--verify] <checkout> [owner/name]"); | |
| 20 | 25 | process.exit(2); |
| 21 | 26 | } |
| 22 | 27 | const git = (...args: string[]): string => { |
| @@ -48,6 +53,26 @@ if (files["template.json"] === undefined || parseTemplateSpec(files["template.js | ||
| 48 | 53 | console.error("take-template: the checkout has no readable template.json"); |
| 49 | 54 | process.exit(1); |
| 50 | 55 | } |
| 56 | if (verify) { | |
| 57 | let pinned: { commit: string; files: Record<string, string> }; | |
| 58 | try { | |
| 59 | pinned = (await Bun.file(out).json()) as typeof pinned; | |
| 60 | if (typeof pinned.commit !== "string" || typeof pinned.files !== "object" || pinned.files === null) throw new Error("shape"); | |
| 61 | } catch { | |
| 62 | console.error(`take-template: no bundle at ${out}`); | |
| 63 | process.exit(1); | |
| 64 | } | |
| 65 | const differs = Object.keys({ ...pinned.files, ...files }).filter((p) => pinned.files[p] !== files[p]); | |
| 66 | if (commit !== pinned.commit || differs.length > 0) { | |
| 67 | console.error( | |
| 68 | `take-template: the bundle is pinned at ${pinned.commit} but the checkout is at ${commit}` + | |
| 69 | (differs.length > 0 ? `; differing files: ${differs.join(", ")}` : ""), | |
| 70 | ); | |
| 71 | process.exit(1); | |
| 72 | } | |
| 73 | console.log(`bundle matches ${repo} at ${commit}`); | |
| 74 | process.exit(0); | |
| 75 | } | |
| 51 | 76 | await Bun.write( |
| 52 | 77 | out, |
| 53 | 78 | `${JSON.stringify({ repo, commit, pinned: true, files }, null, 1)}\n`, |
test/spawn-template-birth.test.ts +11
| @@ -89,6 +89,17 @@ describe("a forge made from a template", () => { | ||
| 89 | 89 | child.close(); |
| 90 | 90 | }, 60_000); |
| 91 | 91 | |
| 92 | test("a forge without the template repository spawns from the pinned bundle", async () => { | |
| 93 | expect(getRepo(parent.db, "trevato", "app-template")).toBeUndefined(); | |
| 94 | const c = await spawn("noor", { template: "starter", fresh: SENTENCE }); | |
| 95 | const want = scaffoldFiles({ name: "a-booking-page", description: SENTENCE }); | |
| 96 | expect(want.length).toBeGreaterThan(0); | |
| 97 | const listed = git(c, "noor", "a-booking-page", "ls-tree", "-r", "--name-only", "main").trim().split("\n").sort(); | |
| 98 | expect(listed).toEqual(want.map((f) => f.path).sort()); | |
| 99 | for (const f of want) | |
| 100 | expect(git(c, "noor", "a-booking-page", "show", `main:${f.path}`)).toBe(f.content as string); | |
| 101 | }, 60_000); | |
| 102 | ||
| 92 | 103 | test("without a sentence the app is named app", async () => { |
| 93 | 104 | const c = await spawn("noa", { template: "starter" }); |
| 94 | 105 | const want = scaffoldFiles({ name: "app", description: "" }).map((f) => f.path).sort(); |
test/template-scripts.test.ts +28
| @@ -54,6 +54,34 @@ test("take-template records HEAD as a pinned commit and the tracked files", asyn | ||
| 54 | 54 | expect(Object.keys(bundle.files).sort()).toEqual(bakedTemplate().files.map((f) => f.path).sort()); |
| 55 | 55 | }); |
| 56 | 56 | |
| 57 | test("take-template --verify passes on the pinned bundle and names the commit when it differs", async () => { | |
| 58 | const dir = await checkout("verify"); | |
| 59 | const out = join(root, "verify.json"); | |
| 60 | expect(run("take-template.ts", [dir], { FORGE_TEMPLATE_OUT: out }).exitCode).toBe(0); | |
| 61 | const same = run("take-template.ts", ["--verify", dir], { FORGE_TEMPLATE_OUT: out }); | |
| 62 | expect(same.exitCode).toBe(0); | |
| 63 | const pinned = JSON.parse(await Bun.file(out).text()).commit as string; | |
| 64 | await writeFile(join(dir, "README.md"), "changed\n"); | |
| 65 | git(dir, "add", "-A"); | |
| 66 | git(dir, "commit", "-q", "-m", "drift"); | |
| 67 | const drift = run("take-template.ts", ["--verify", dir], { FORGE_TEMPLATE_OUT: out }); | |
| 68 | expect(drift.exitCode).toBe(1); | |
| 69 | expect(drift.stderr.toString()).toContain(pinned); | |
| 70 | expect(drift.stderr.toString()).toContain("README.md"); | |
| 71 | expect(JSON.parse(await Bun.file(out).text()).commit).toBe(pinned); | |
| 72 | }); | |
| 73 | ||
| 74 | test("take-template --verify without a readable bundle says so and exits 1", async () => { | |
| 75 | const dir = await checkout("nobundle"); | |
| 76 | for (const [name, body] of [["missing.json", undefined], ["junk.json", "{nope"]] as const) { | |
| 77 | const out = join(root, name); | |
| 78 | if (body !== undefined) await writeFile(out, body); | |
| 79 | const r = run("take-template.ts", ["--verify", dir], { FORGE_TEMPLATE_OUT: out }); | |
| 80 | expect(r.exitCode).toBe(1); | |
| 81 | expect(r.stderr.toString()).toContain(`take-template: no bundle at ${out}`); | |
| 82 | } | |
| 83 | }); | |
| 84 | ||
| 57 | 85 | test("take-template refuses a binary file and a checkout without template.json", async () => { |
| 58 | 86 | const bin = await checkout("bin", { "icon.png": new Uint8Array([0x89, 0x50, 0xff, 0xfe, 0x00]) }); |
| 59 | 87 | const out = join(root, "bin.json"); |
new above
offline