Public: anyone can read this; the crew can change it.

The release build takes the app template at a pinned commit #13271

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/13258-the-release-build-takes-the-app-template → main 2 commits fork

  • Merged. mason/13258-the-release-build-takes-the-app-template was merged into main as e4fd3dd.

Review

Sign in to review this change.
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
2626 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.
2727
2828 - **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.
3031 - **`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).
3132 - **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).
3233 - **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 @@
11 /**
2 * `bun scripts/take-template.ts <checkout> [owner/name]`: write
2 * `bun scripts/take-template.ts [--verify] <checkout> [owner/name]`: write
33 * `templates/app-template.json`, the copy of the app template every forge
44 * carries in its image (#10305), from a checkout of the template repository.
55 * 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).
1114 */
1215
1316 import { parseTemplateSpec } from "../src/apps/template.ts";
1417
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");
1621 // FORGE_TEMPLATE_OUT: where to write (tests); default the tree's bundle.
1722 const out = process.env["FORGE_TEMPLATE_OUT"] ?? `${import.meta.dir}/../templates/app-template.json`;
1823 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]");
2025 process.exit(2);
2126 }
2227 const git = (...args: string[]): string => {
@@ -48,6 +53,26 @@ if (files["template.json"] === undefined || parseTemplateSpec(files["template.js
4853 console.error("take-template: the checkout has no readable template.json");
4954 process.exit(1);
5055 }
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 }
5176 await Bun.write(
5277 out,
5378 `${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", () => {
8989 child.close();
9090 }, 60_000);
9191
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
92103 test("without a sentence the app is named app", async () => {
93104 const c = await spawn("noa", { template: "starter" });
94105 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
5454 expect(Object.keys(bundle.files).sort()).toEqual(bakedTemplate().files.map((f) => f.path).sort());
5555 });
5656
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
5785 test("take-template refuses a binary file and a checkout without template.json", async () => {
5886 const bin = await checkout("bin", { "icon.png": new Uint8Array([0x89, 0x50, 0xff, 0xfe, 0x00]) });
5987 const out = join(root, "bin.json");

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs