Manage the published quick start's pins, and fail closed on every release-tooling edge

release-tooling/contract-version.ts

@@ -1,14 +1,13 @@
-// The plugin contract version and the release version are one number (README → Contract
-// versioning). This is the gate that keeps them one: a tag whose major.minor disagrees with
-// HOST_API_VERSION would ship a host that misreports itself to every plugin's compatibility check.
-// Pure and unit tested; the git/tag side lives in the workflows that call the CLI below.
+// The gate that keeps the contract version and the release version one number (README → Contract
+// versioning): a tag whose major.minor disagrees with HOST_API_VERSION would ship a host that
+// misreports itself to every plugin's compatibility check.
 
 export type ContractCheck = { ok: true } | { ok: false; error: string };
 
-const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)$/;
+const SEMVER = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 
 export function readHostApiVersion(source: string): string | null {
-  return /HOST_API_VERSION\s*=\s*"([^"]+)"/.exec(source)?.[1] ?? null;
+  return /^export const HOST_API_VERSION = "([^"]+)";/m.exec(source)?.[1] ?? null;
 }
 
 // Patch is deliberately not compared: checkApiVersion ignores it, and auto-release cuts patch
@@ -37,7 +36,13 @@ export function checkTagMatchesContract(tag: string, hostApiVersion: string | nu
 if (process.argv[1]?.endsWith("/contract-version.ts")) {
   const [, , tag, pluginPath = "src/plugin-host/plugin.ts"] = process.argv;
   const { readFileSync } = await import("node:fs");
-  const source = readFileSync(pluginPath === "-" ? 0 : pluginPath, "utf8");
+  let source = "";
+  try {
+    source = readFileSync(pluginPath === "-" ? 0 : pluginPath, "utf8");
+  } catch (err) {
+    process.stderr.write(`${pluginPath}: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  }
   const result = checkTagMatchesContract(tag ?? "", readHostApiVersion(source));
   if (!result.ok) {
     process.stderr.write(`${pluginPath}: ${result.error}\n`);

release-tooling/dockerhub-overview.md.tmpl

@@ -54,7 +54,7 @@ services:
     restart: "on-failure:5"
 
   postgres:
-    image: postgres:18.4-alpine3.23
+    image: postgres:18.6-alpine3.23
     environment:
       POSTGRES_DB: ory
       POSTGRES_PASSWORD: ory
@@ -131,7 +131,7 @@ services:
 
   # Catches Kratos' recovery/verification emails — UI on http://localhost:8025
   mailpit:
-    image: axllent/mailpit:v1.30.1
+    image: axllent/mailpit:v1.30.7
     ports:
       - "8025:8025"
     restart: unless-stopped

release-tooling/dockerhub-overview.test.ts

@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { test } from "node:test";
-import { leftoverPlaceholders, renderOverview } from "./dockerhub-overview.ts";
+import { jwtFrom, leftoverPlaceholders, renderOverview } from "./dockerhub-overview.ts";
+
+const TEMPLATE = "release-tooling/dockerhub-overview.md.tmpl";
+const template = () => readFileSync(TEMPLATE, "utf8");
 
 test("renderOverview substitutes every occurrence, not just the first", () => {
   const out = renderOverview("pull a:{{VERSION}} then b:{{VERSION}}", "1.2.3");
@@ -13,10 +16,33 @@ test("leftoverPlaceholders catches a typo'd placeholder, deduped, and passes cle
   assert.deepEqual(leftoverPlaceholders(renderOverview("x {{VERSION}}", "0.1.0")), []);
 });
 
-test("the real template renders clean and pins no literal image tag", () => {
-  const rendered = renderOverview(readFileSync("release-tooling/dockerhub-overview.md.tmpl", "utf8"), "9.9.9");
+test("the real template renders clean, and the release owns its own image tag", () => {
+  const rendered = renderOverview(template(), "9.9.9");
   assert.deepEqual(leftoverPlaceholders(rendered), []);
   assert.match(rendered, /larvit\/plainpages:9\.9\.9/); // the placeholder actually reaches the examples
-  // The release owns every image tag on the page, so a literal one must not survive rendering.
   assert.doesNotMatch(rendered, /larvit\/plainpages:\d+\.\d+\.\d+(?<!9\.9\.9)/);
 });
+
+test("the quick start's sidecars are pinned to the same versions this repo runs", () => {
+  // The page is published automatically, so a drifted pin here ships a topology CI never tested.
+  const pins = (source: string) =>
+    new Map([...source.matchAll(/image: ([^:\s]+):(v?\d\S*)/g)].map((m) => [m[1] ?? "", m[2] ?? ""]));
+  const ours = new Map([
+    ...pins(readFileSync("compose.yml", "utf8")),
+    ...pins(readFileSync("compose.override.yml", "utf8")),
+  ]);
+  const published = pins(template());
+  assert.ok(published.size > 0, "the template should pin sidecars");
+  for (const [image, tag] of published) {
+    assert.equal(tag, ours.get(image), `${TEMPLATE} pins ${image}:${tag}, this repo runs ${ours.get(image)}`);
+  }
+});
+
+test("jwtFrom accepts only a non-empty string token, never throwing on a hostile body", () => {
+  assert.equal(jwtFrom({ token: "abc" }), "abc");
+  assert.equal(jwtFrom(null), null); // valid JSON, and the shape a proxy can return
+  assert.equal(jwtFrom("<html>rate limited</html>"), null);
+  assert.equal(jwtFrom({}), null);
+  assert.equal(jwtFrom({ token: "" }), null);
+  assert.equal(jwtFrom({ token: 42 }), null);
+});

release-tooling/dockerhub-overview.ts

@@ -1,8 +1,12 @@
-// Publishes the Docker Hub repository overview from dockerhub-overview.md.tmpl. The page is the
-// first thing an adopter copies, so `{{VERSION}}` is rendered from the release being published
-// rather than written by hand.
+// Publishes the Docker Hub repository overview from dockerhub-overview.md.tmpl, rendering
+// `{{VERSION}}` to the release being published.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
 const HUB = "https://hub.docker.com/v2";
+const TIMEOUT_MS = 30_000;
+const VERSION = /^\d+\.\d+\.\d+$/;
 
 export function renderOverview(source: string, version: string): string {
   return source.replaceAll("{{VERSION}}", version);
@@ -13,56 +17,77 @@ export function leftoverPlaceholders(rendered: string): string[] {
   return [...new Set(rendered.match(/\{\{[^}]*\}\}/g) ?? [])];
 }
 
+export function jwtFrom(body: unknown): string | null {
+  if (typeof body !== "object" || body === null || !("token" in body)) return null;
+  return typeof body.token === "string" && body.token !== "" ? body.token : null;
+}
+
+type Fetched = { error: string } | { json: unknown; ok: boolean; status: number; text: string };
+
+// fetch and its body readers throw; this is the one edge that converts that into a value.
+async function post(url: string, init: RequestInit): Promise<Fetched> {
+  try {
+    const res = await fetch(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) });
+    const text = await res.text();
+    let json: unknown = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = null;
+    }
+    return { json, ok: res.ok, status: res.status, text };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 async function main(): Promise<number> {
+  const fail = (message: string): number => {
+    process.stderr.write(`${message}\n`);
+    return 1;
+  };
   const [, , version] = process.argv;
-  const { readFileSync } = await import("node:fs");
   const repo = process.env["DOCKERHUB_REPO"];
   const user = process.env["DOCKERHUB_USER"];
   const token = process.env["DOCKERHUB_OVERVIEW_TOKEN"];
   if (!version || !repo || !user || !token) {
-    process.stderr.write(
-      "usage: dockerhub-overview.ts <version>; needs DOCKERHUB_REPO, DOCKERHUB_USER, DOCKERHUB_OVERVIEW_TOKEN\n",
+    return fail(
+      "usage: dockerhub-overview.ts <X.Y.Z>; needs DOCKERHUB_REPO, DOCKERHUB_USER and " +
+        "DOCKERHUB_OVERVIEW_TOKEN (README -> CI/CD)",
     );
-    return 1;
   }
+  // The page is public, so never render a version that resolves to no image.
+  if (!VERSION.test(version)) return fail(`version must be X.Y.Z, got ${JSON.stringify(version)}`);
 
-  const body = renderOverview(readFileSync("release-tooling/dockerhub-overview.md.tmpl", "utf8"), version);
+  const templatePath = join(import.meta.dirname, "dockerhub-overview.md.tmpl");
+  const body = renderOverview(readFileSync(templatePath, "utf8"), version);
   const leftover = leftoverPlaceholders(body);
-  if (leftover.length > 0) {
-    process.stderr.write(`release-tooling/dockerhub-overview.md.tmpl has unrendered placeholders: ${leftover.join(", ")}\n`);
-    return 1;
-  }
+  if (leftover.length > 0) return fail(`${templatePath} has unrendered placeholders: ${leftover.join(", ")}`);
 
-  const login = await fetch(`${HUB}/users/login`, {
+  const login = await post(`${HUB}/users/login`, {
     body: JSON.stringify({ password: token, username: user }),
     headers: { "content-type": "application/json" },
     method: "POST",
   });
-  if (!login.ok) {
-    process.stderr.write(`Docker Hub login failed: ${login.status} ${await login.text()}\n`);
-    return 1;
-  }
-  const { token: jwt } = (await login.json()) as { token?: string };
-  if (!jwt) {
-    process.stderr.write("Docker Hub login returned no token\n");
-    return 1;
-  }
+  if ("error" in login) return fail(`Docker Hub login unreachable: ${login.error}`);
+  if (!login.ok) return fail(`Docker Hub login failed: ${login.status} ${login.text}`);
+  const jwt = jwtFrom(login.json);
+  if (!jwt) return fail("Docker Hub login returned no token");
 
-  const res = await fetch(`${HUB}/repositories/${repo}/`, {
+  const res = await post(`${HUB}/repositories/${repo}/`, {
     body: JSON.stringify({ full_description: body }),
     headers: { authorization: `Bearer ${jwt}`, "content-type": "application/json" },
     method: "PATCH",
   });
+  if ("error" in res) return fail(`Docker Hub unreachable: ${res.error}`);
   if (!res.ok) {
-    const detail = await res.text();
-    process.stderr.write(
-      `Docker Hub overview PATCH failed: ${res.status} ${detail}\n` +
+    return fail(
+      `Docker Hub overview PATCH failed: ${res.status} ${res.text}` +
         (res.status === 403
-          ? "403 means DOCKERHUB_OVERVIEW_TOKEN cannot edit repository metadata — that is a separate " +
-            "permission from pushing images, which is why it is its own secret (README -> CI/CD).\n"
+          ? "\n403 means DOCKERHUB_OVERVIEW_TOKEN cannot edit repository metadata — a separate " +
+            "permission from pushing images, which is why it is its own secret (README -> CI/CD)."
           : ""),
     );
-    return 1;
   }
   process.stdout.write(`Docker Hub overview updated for ${repo} at ${version}\n`);
   return 0;