Release this as v0.2.0, and give the Hub overview its own job, token and template

release-tooling/contract-version.test.ts

@@ -9,27 +9,51 @@ test("readHostApiVersion pulls the constant out of the real source, and returns
   assert.equal(readHostApiVersion('export const SOMETHING_ELSE = "1.0.0";'), null);
 });
 
-test("the shipped tag and the shipped contract agree", () => {
-  // Guards the pair the release gate checks, so a bump to one fails here before it fails in CI.
-  assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.1.0");
+test("bumping HOST_API_VERSION is a deliberate act, so pin the shipped value", () => {
+  // Not a substitute for the release gate — this test cannot see a tag. It is the tripwire that
+  // makes an accidental edit fail here rather than at release time.
+  assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.2.0");
+});
+
+test("every author-facing apiVersion sample matches the shipped contract", () => {
+  // A plugin author copies these; a stale one produces a boot-aborting refuse on first run. The
+  // examples deliberately write a literal rather than importing the constant (AGENTS.md), so this
+  // is the only thing keeping the copies honest.
+  const host = readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")) ?? "";
+  const [major, minor] = host.split(".");
+  for (const file of [
+    "README.md",
+    "examples/plugins/admin/plugin.ts",
+    "examples/plugins/scheduling/plugin.ts",
+    "release-tooling/dockerhub-overview.md.tmpl",
+    "views/index.ejs",
+  ]) {
+    const found = [...readFileSync(file, "utf8").matchAll(/apiVersion: "(\d+\.\d+\.\d+)"/g)].map((m) => m[1]);
+    assert.ok(found.length > 0, `${file} should carry at least one apiVersion sample`);
+    for (const sample of found) {
+      const [sMajor, sMinor] = (sample ?? "").split(".");
+      assert.equal(`${sMajor}.${sMinor}`, `${major}.${minor}`, `${file} samples apiVersion ${sample}, host is ${host}`);
+    }
+  }
 });
 
 test("checkTagMatchesContract: major.minor must agree, patch may lag", () => {
-  assert.equal(checkTagMatchesContract("v0.1.0", "0.1.0").ok, true);
-  assert.equal(checkTagMatchesContract("v0.1.7", "0.1.0").ok, true); // auto-release cut patches
-  assert.equal(checkTagMatchesContract("0.1.0", "0.1.0").ok, true); // bare tag, no v
-  assert.equal(checkTagMatchesContract("v0.2.0", "0.1.0").ok, false); // plugin-visible, needs a bump
-  assert.equal(checkTagMatchesContract("v1.0.0", "0.1.0").ok, false);
+  assert.equal(checkTagMatchesContract("v0.2.0", "0.2.0").ok, true);
+  assert.equal(checkTagMatchesContract("v0.2.7", "0.2.0").ok, true); // auto-release cut patches
+  assert.equal(checkTagMatchesContract("0.2.0", "0.2.0").ok, true); // bare tag, no v
+  assert.equal(checkTagMatchesContract("v0.3.0", "0.2.0").ok, false); // plugin-visible, needs a bump
+  assert.equal(checkTagMatchesContract("v0.1.0", "0.2.0").ok, false); // the previously released line
+  assert.equal(checkTagMatchesContract("v1.0.0", "0.2.0").ok, false);
 });
 
 test("checkTagMatchesContract names what to fix rather than just failing", () => {
-  const res = checkTagMatchesContract("v0.2.0", "0.1.0");
+  const res = checkTagMatchesContract("v0.3.0", "0.2.0");
   assert.equal(res.ok, false);
-  assert.match(res.ok === false ? res.error : "", /HOST_API_VERSION to 0\.2\.0/);
+  assert.match(res.ok === false ? res.error : "", /HOST_API_VERSION to 0\.3\.0/);
 });
 
 test("checkTagMatchesContract rejects junk on either side without throwing", () => {
-  assert.equal(checkTagMatchesContract("v0.1.0", null).ok, false); // constant not found
-  assert.equal(checkTagMatchesContract("nope", "0.1.0").ok, false);
-  assert.equal(checkTagMatchesContract("v0.1.0", "1.0").ok, false);
+  assert.equal(checkTagMatchesContract("v0.2.0", null).ok, false); // constant not found
+  assert.equal(checkTagMatchesContract("nope", "0.2.0").ok, false);
+  assert.equal(checkTagMatchesContract("v0.2.0", "1.0").ok, false);
 });