mandrel-platform 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/apply-uptime-monitors.mjs

@@ -43,9 +43,12 @@
  *   • --token        Better Stack API token. Defaults to
  *                     $BETTERSTACK_API_TOKEN. Missing token → skip-with-
  *                     notice, exit 0.
- *   • --alert-email  Default alert-contact email applied to any monitor
- *                     entry that does not set its own `alertEmail`. Defaults
- *                     to $UPTIME_ALERT_EMAIL.
+ *   • --alert-email  DEPRECATED and ignored (defaults to $UPTIME_ALERT_EMAIL).
+ *                     Better Stack's monitor `email` field is a boolean
+ *                     ("Send e-mail alerts."), not a recipient — recipients
+ *                     resolve from the team roster and the escalation policy.
+ *                     Accepted only so an existing caller does not break; use
+ *                     a monitor entry's `policyId` to control who is alerted.
  *
  * Exit codes:
  *   0 — plan computed / applied successfully, OR skip-with-notice (no token).
@@ -71,12 +74,24 @@ import { resolve } from "node:path";
  *   {
  *     "url": "https://api.example.com/health",   // required, http(s) URL
  *     "name": "api",                              // optional, defaults to url's host
- *     "alertEmail": "oncall@example.com",         // optional, falls back to --alert-email
+ *     "emailAlerts": true,                        // optional, boolean, default true
+ *     "policyId": "12345",                        // optional, Better Stack escalation policy
  *     "checkFrequency": 30                        // optional, seconds, default 30
  *   }
  *
+ * `emailAlerts` maps to Better Stack's `email` field, which the Monitors API
+ * types as a **boolean** ("Send e-mail alerts.") — it is a switch, not a
+ * recipient. Recipients resolve from the Better Stack team roster and the
+ * escalation policy named by `policyId` (`policy_id`), never from a
+ * per-monitor address. The retired `alertEmail` field is still accepted and
+ * type-checked so an existing config keeps parsing, but it is inert: it is
+ * reported in `deprecations[]` and never reaches the API payload.
+ *
  * @param {unknown} raw  Parsed JSON.
- * @returns {{ monitors: Array<{url:string, name:string, alertEmail:string|null, checkFrequency:number}> }}
+ * @returns {{
+ *   monitors: Array<{url:string, name:string, emailAlerts:boolean, policyId:string|null, checkFrequency:number}>,
+ *   deprecations: string[]
+ * }}
  * @throws {Error} with a message naming the offending index/field on invalid input.
  */
 export function parseMonitorConfig(raw) {
@@ -86,9 +101,18 @@ export function parseMonitorConfig(raw) {
       "monitor config must be a JSON array of monitor entries, or an object with a `monitors` array."
     );
   }
-  return {
-    monitors: list.map((entry, i) => validateMonitorEntry(entry, i)),
-  };
+  const deprecations = [];
+  const monitors = list.map((entry, i) => {
+    if (entry && typeof entry === "object" && entry.alertEmail !== undefined) {
+      deprecations.push(
+        `monitor config entry [${i}] sets "alertEmail" — that field is ignored. ` +
+          `Better Stack types the monitor's \`email\` field as a boolean (an on/off switch), not a recipient. ` +
+          `Use "emailAlerts" to toggle e-mail alerts and "policyId" to choose the escalation policy that decides who is alerted.`
+      );
+    }
+    return validateMonitorEntry(entry, i);
+  });
+  return { monitors, deprecations };
 }
 
 function validateMonitorEntry(entry, index) {
@@ -110,13 +134,20 @@ function validateMonitorEntry(entry, index) {
   if (entry.alertEmail !== undefined && typeof entry.alertEmail !== "string") {
     throw new Error(`monitor config entry [${index}] "alertEmail" must be a string when present.`);
   }
+  if (entry.emailAlerts !== undefined && typeof entry.emailAlerts !== "boolean") {
+    throw new Error(`monitor config entry [${index}] "emailAlerts" must be a boolean when present.`);
+  }
+  if (entry.policyId !== undefined && typeof entry.policyId !== "string") {
+    throw new Error(`monitor config entry [${index}] "policyId" must be a string when present.`);
+  }
   if (entry.checkFrequency !== undefined && !(Number.isInteger(entry.checkFrequency) && entry.checkFrequency > 0)) {
     throw new Error(`monitor config entry [${index}] "checkFrequency" must be a positive integer (seconds) when present.`);
   }
   return {
     url: entry.url,
     name: entry.name ?? host,
-    alertEmail: entry.alertEmail ?? null,
+    emailAlerts: entry.emailAlerts ?? true,
+    policyId: entry.policyId ?? null,
     checkFrequency: entry.checkFrequency ?? DEFAULT_CHECK_FREQUENCY_SECONDS,
   };
 }
@@ -163,7 +194,13 @@ function normalizeUrl(url) {
 function monitorNeedsUpdate(live, desired) {
   if (live.name !== undefined && live.name !== desired.name) return true;
   if (live.checkFrequency !== undefined && live.checkFrequency !== desired.checkFrequency) return true;
-  if (live.alertEmail !== undefined && desired.alertEmail !== null && live.alertEmail !== desired.alertEmail) return true;
+  // Both sides are booleans: the live read-back maps Better Stack's boolean
+  // `email` attribute, and `emailAlerts` normalizes to a boolean at parse.
+  // Comparing a boolean against a configured address (the pre-#403 shape)
+  // read as drift on every beat and issued a redundant PATCH per monitor
+  // per apply.
+  if (live.emailAlerts !== undefined && live.emailAlerts !== desired.emailAlerts) return true;
+  if (live.policyId !== undefined && desired.policyId !== null && live.policyId !== desired.policyId) return true;
   return false;
 }
 
@@ -209,7 +246,8 @@ export function createBetterStackClient({ token, fetchImpl = fetch, apiBase = BE
         url: m.attributes?.url ?? "",
         name: m.attributes?.pronounceable_name,
         checkFrequency: m.attributes?.check_frequency,
-        alertEmail: m.attributes?.email,
+        emailAlerts: m.attributes?.email,
+        policyId: m.attributes?.policy_id,
       }));
     },
     async createMonitor(entry) {
@@ -231,7 +269,11 @@ function toBetterStackPayload(entry) {
     url: entry.url,
     pronounceable_name: entry.name,
     check_frequency: entry.checkFrequency,
-    ...(entry.alertEmail ? { email: entry.alertEmail } : {}),
+    // `email` is a boolean in Better Stack's Monitors API ("Send e-mail
+    // alerts.") — always send the switch, never an address. `policy_id` is
+    // the field that actually determines who is alerted.
+    email: entry.emailAlerts,
+    ...(entry.policyId ? { policy_id: entry.policyId } : {}),
   };
 }
 
@@ -245,14 +287,10 @@ function toBetterStackPayload(entry) {
  * @param {{monitors: Array}} opts.config
  * @param {ReturnType<typeof createBetterStackClient>} opts.client
  * @param {boolean} opts.dryRun
- * @param {string|null} [opts.defaultAlertEmail]
  * @returns {Promise<{created: string[], updated: string[], unchanged: string[], dryRun: boolean}>}
  */
-export async function applyMonitorConfig({ config, client, dryRun, defaultAlertEmail = null }) {
-  const desired = config.monitors.map((m) => ({
-    ...m,
-    alertEmail: m.alertEmail ?? defaultAlertEmail,
-  }));
+export async function applyMonitorConfig({ config, client, dryRun }) {
+  const desired = config.monitors;
   const live = await client.listMonitors();
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, live);
 
@@ -322,10 +360,33 @@ async function main() {
     process.exit(1);
   }
 
+  // Announced before the token check on purpose: "secret provisioned, token
+  // absent" is exactly the state that produced a permanently-green apply a
+  // consumer believed was routing alerts, so that run is the one that most
+  // needs to hear the address is inert (refs #403).
+  if (opts.alertEmail) {
+    process.stdout.write(
+      "::warning title=UPTIME_ALERT_EMAIL is ignored::Better Stack resolves alert recipients from the team roster " +
+        "and escalation policy, not from a per-monitor address. Set a monitor's `policyId` instead, and drop this secret from your caller.\n"
+    );
+    process.stderr.write(
+      "[apply-uptime-monitors] DEPRECATED: --alert-email / $UPTIME_ALERT_EMAIL is ignored — Better Stack's monitor " +
+        "`email` field is a boolean switch, not a recipient. Use a monitor entry's `policyId` (escalation policy) to " +
+        "control who is alerted, and `emailAlerts` to toggle e-mail alerts.\n"
+    );
+  }
+
   // Graceful degradation: no token → skip-with-notice, exit 0. Preserves the
   // pre-existing per-consumer behaviour when Better Stack secrets are not
   // yet provisioned (acceptance criterion — see docs/reusable-workflows.md).
   if (!opts.token) {
+    // Annotation-level, not stdout-only: a consumer can otherwise sit on a
+    // permanently-green `uptime-apply` for weeks with zero live monitors and
+    // never notice the apply is inert (refs #403).
+    process.stdout.write(
+      "::warning title=Uptime monitors not applied::BETTERSTACK_API_TOKEN is not provisioned — " +
+        "this uptime-apply run created and updated nothing. Provision the secret to activate uptime monitoring.\n"
+    );
     process.stdout.write(
       "⏭️  apply-uptime-monitors: BETTERSTACK_API_TOKEN not provided — skipping uptime-monitor apply (Better Stack not provisioned for this consumer yet).\n"
     );
@@ -341,6 +402,10 @@ async function main() {
     process.exit(1);
   }
 
+  for (const notice of config.deprecations) {
+    process.stderr.write(`[apply-uptime-monitors] DEPRECATED: ${notice}\n`);
+  }
+
   // Test-only escape hatch: point the CLI at a local/offline server instead
   // of the live Better Stack API. Never set in a production caller — see
   // createBetterStackClient's apiBase docblock.
@@ -355,7 +420,6 @@ async function main() {
       config,
       client,
       dryRun: opts.dryRun,
-      defaultAlertEmail: opts.alertEmail,
     });
     const verb = result.dryRun ? "would create" : "created";
     const verbUpdate = result.dryRun ? "would update" : "updated";

package/scripts/apply-uptime-monitors.test.mjs

@@ -42,16 +42,19 @@ test("parseMonitorConfig accepts a bare array of monitor entries", () => {
   assert.equal(monitors.length, 1);
   assert.equal(monitors[0].url, "https://api.example.com/health");
   assert.equal(monitors[0].name, "api.example.com");
-  assert.equal(monitors[0].alertEmail, null);
+  assert.equal(monitors[0].emailAlerts, true, "e-mail alerts default to on");
+  assert.equal(monitors[0].policyId, null);
   assert.equal(monitors[0].checkFrequency, DEFAULT_CHECK_FREQUENCY_SECONDS);
 });
 
 test("parseMonitorConfig accepts a wrapped { monitors: [...] } object", () => {
   const { monitors } = parseMonitorConfig({
-    monitors: [{ url: "https://x.example.com", name: "x", alertEmail: "a@b.com", checkFrequency: 60 }],
+    monitors: [
+      { url: "https://x.example.com", name: "x", emailAlerts: false, policyId: "pol-1", checkFrequency: 60 },
+    ],
   });
   assert.deepEqual(monitors, [
-    { url: "https://x.example.com", name: "x", alertEmail: "a@b.com", checkFrequency: 60 },
+    { url: "https://x.example.com", name: "x", emailAlerts: false, policyId: "pol-1", checkFrequency: 60 },
   ]);
 });
 
@@ -83,12 +86,42 @@ test("parseMonitorConfig rejects non-string name/alertEmail", () => {
   );
 });
 
+test("parseMonitorConfig rejects a non-boolean emailAlerts, naming the index", () => {
+  assert.throws(
+    () => parseMonitorConfig([{ url: "https://a.example.com" }, { url: "https://x.example.com", emailAlerts: "yes" }]),
+    /entry \[1\] "emailAlerts" must be a boolean/
+  );
+});
+
+test("parseMonitorConfig rejects a non-string policyId, naming the index", () => {
+  assert.throws(
+    () => parseMonitorConfig([{ url: "https://a.example.com" }, { url: "https://x.example.com", policyId: 12345 }]),
+    /entry \[1\] "policyId" must be a string/
+  );
+});
+
+test("parseMonitorConfig reports a retired alertEmail as a deprecation and drops it", () => {
+  const { monitors, deprecations } = parseMonitorConfig([
+    { url: "https://x.example.com", alertEmail: "oncall@example.com" },
+  ]);
+  assert.equal(deprecations.length, 1);
+  assert.match(deprecations[0], /entry \[0\] sets "alertEmail" — that field is ignored/);
+  assert.match(deprecations[0], /policyId/);
+  assert.equal(monitors[0].alertEmail, undefined, "the retired field never reaches the normalized entry");
+  assert.equal(monitors[0].emailAlerts, true);
+});
+
+test("parseMonitorConfig reports no deprecations for a clean config", () => {
+  const { deprecations } = parseMonitorConfig([{ url: "https://x.example.com", emailAlerts: false }]);
+  assert.deepEqual(deprecations, []);
+});
+
 // ---------------------------------------------------------------------------
 // diffMonitors
 // ---------------------------------------------------------------------------
 
 test("diffMonitors classifies a brand-new url as toCreate", () => {
-  const desired = [{ url: "https://new.example.com", name: "new", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://new.example.com", name: "new", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, []);
   assert.equal(toCreate.length, 1);
   assert.equal(toUpdate.length, 0);
@@ -96,7 +129,7 @@ test("diffMonitors classifies a brand-new url as toCreate", () => {
 });
 
 test("diffMonitors classifies a matching, identical url as unchanged", () => {
-  const desired = [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, live);
   assert.equal(toCreate.length, 0);
@@ -105,7 +138,7 @@ test("diffMonitors classifies a matching, identical url as unchanged", () => {
 });
 
 test("diffMonitors classifies a url with a drifted name/frequency as toUpdate", () => {
-  const desired = [{ url: "https://x.example.com", name: "renamed", alertEmail: null, checkFrequency: 60 }];
+  const desired = [{ url: "https://x.example.com", name: "renamed", emailAlerts: true, policyId: null, checkFrequency: 60 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toUpdate } = diffMonitors(desired, live);
   assert.equal(toUpdate.length, 1);
@@ -113,7 +146,7 @@ test("diffMonitors classifies a url with a drifted name/frequency as toUpdate",
 });
 
 test("diffMonitors url matching is trailing-slash and case insensitive", () => {
-  const desired = [{ url: "https://X.example.com/", name: "x", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://X.example.com/", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toCreate, unchanged } = diffMonitors(desired, live);
   assert.equal(toCreate.length, 0);
@@ -121,7 +154,7 @@ test("diffMonitors url matching is trailing-slash and case insensitive", () => {
 });
 
 test("diffMonitors never proposes deleting a live monitor absent from desired (additive apply only)", () => {
-  const desired = [{ url: "https://kept.example.com", name: "kept", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://kept.example.com", name: "kept", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [
     { id: "1", url: "https://kept.example.com", name: "kept", checkFrequency: 30 },
     { id: "2", url: "https://hand-added.example.com", name: "manual" },
@@ -162,7 +195,16 @@ test("createBetterStackClient.listMonitors normalizes the Better Stack payload s
         data: [
           {
             id: "42",
-            attributes: { url: "https://a.example.com", pronounceable_name: "a", check_frequency: 30, email: "a@b.com" },
+            // `email` is a boolean in Better Stack's API — a switch, not a
+            // recipient. Fixturing it as an address is what let the
+            // string-typed payload bug survive a green suite (refs #403).
+            attributes: {
+              url: "https://a.example.com",
+              pronounceable_name: "a",
+              check_frequency: 30,
+              email: true,
+              policy_id: "pol-1",
+            },
           },
         ],
       },
@@ -171,7 +213,7 @@ test("createBetterStackClient.listMonitors normalizes the Better Stack payload s
   const client = createBetterStackClient({ token: "tok", fetchImpl });
   const monitors = await client.listMonitors();
   assert.deepEqual(monitors, [
-    { id: "42", url: "https://a.example.com", name: "a", checkFrequency: 30, alertEmail: "a@b.com" },
+    { id: "42", url: "https://a.example.com", name: "a", checkFrequency: 30, emailAlerts: true, policyId: "pol-1" },
   ]);
   assert.equal(calls[0].url, "https://uptime.betterstack.com/api/v2/monitors");
 });
@@ -209,7 +251,7 @@ function fakeClient({ live = [] } = {}) {
 test("applyMonitorConfig dry-run computes the plan without calling create/update", async () => {
   const client = fakeClient({ live: [] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: true,
   });
@@ -221,7 +263,7 @@ test("applyMonitorConfig dry-run computes the plan without calling create/update
 test("applyMonitorConfig --apply issues create for new monitors", async () => {
   const client = fakeClient({ live: [] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: false,
   });
@@ -229,21 +271,112 @@ test("applyMonitorConfig --apply issues create for new monitors", async () => {
   assert.equal(client.created.length, 1);
 });
 
-test("applyMonitorConfig falls back to defaultAlertEmail when an entry sets none", async () => {
-  const client = fakeClient({ live: [] });
-  await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+test("a created monitor sends Better Stack's `email` as a boolean, never an address", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: true,
+    policyId: null,
+    checkFrequency: 30,
+  });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(typeof body.email, "boolean", "`email` is a boolean switch in Better Stack's API");
+  assert.equal(body.email, true);
+  assert.ok(!("policy_id" in body), "no escalation policy is sent when the entry names none");
+});
+
+test("emailAlerts:false switches e-mail alerts off rather than omitting the field", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: false,
+    policyId: null,
+    checkFrequency: 30,
+  });
+  assert.equal(JSON.parse(calls[0].body).email, false);
+});
+
+test("policyId maps to Better Stack's policy_id — the field that decides who is alerted", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: true,
+    policyId: "pol-7",
+    checkFrequency: 30,
+  });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(body.policy_id, "pol-7");
+  assert.equal(typeof body.email, "boolean");
+});
+
+test("no payload ever carries an address in `email`, even from a legacy alertEmail config", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const config = parseMonitorConfig([{ url: "https://x.example.com", alertEmail: "oncall@example.com" }]);
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await applyMonitorConfig({ config, client: { ...client, listMonitors: async () => [] }, dryRun: false });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(typeof body.email, "boolean");
+  assert.ok(
+    !JSON.stringify(body).includes("oncall@example.com"),
+    "the retired address never reaches the Better Stack payload"
+  );
+});
+
+test("a converged monitor reports unchanged and issues no update (no per-run PATCH churn)", async () => {
+  // Live read-back carries the boolean `email`; desired carries the boolean
+  // `emailAlerts`. Pre-#403 these were a boolean vs an address, so every
+  // monitor read as drifted on every apply.
+  const client = fakeClient({
+    live: [
+      { id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30, emailAlerts: true, policyId: "pol-1" },
+    ],
+  });
+  const result = await applyMonitorConfig({
+    config: {
+      monitors: [
+        { url: "https://x.example.com", name: "x", emailAlerts: true, policyId: "pol-1", checkFrequency: 30 },
+      ],
+    },
+    client,
+    dryRun: false,
+  });
+  assert.deepEqual(result.unchanged, ["https://x.example.com"]);
+  assert.equal(result.updated.length, 0);
+  assert.equal(client.updated.length, 0, "a converged config issues zero update calls");
+});
+
+test("a drifted emailAlerts switch is still detected as an update", async () => {
+  const client = fakeClient({
+    live: [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30, emailAlerts: false }],
+  });
+  const result = await applyMonitorConfig({
+    config: {
+      monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }],
+    },
     client,
     dryRun: false,
-    defaultAlertEmail: "oncall@example.com",
   });
-  assert.equal(client.created[0].alertEmail, "oncall@example.com");
+  assert.deepEqual(result.updated, ["https://x.example.com"]);
 });
 
 test("applyMonitorConfig issues update for a drifted existing monitor", async () => {
   const client = fakeClient({ live: [{ id: "1", url: "https://x.example.com", name: "old", checkFrequency: 30 }] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "new", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "new", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: false,
   });
@@ -269,6 +402,50 @@ test("CLI skip-with-notice: no BETTERSTACK_API_TOKEN exits 0 with a notice, no c
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
+test("CLI skip-with-notice raises a ::warning:: annotation so an inert apply is visible in the checks UI", () => {
+  tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
+  const configPath = join(tmpDir, "monitors.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com" }]));
+  const out = execFileSync("node", [CLI, "--config", configPath], {
+    encoding: "utf8",
+    env: { ...process.env, BETTERSTACK_API_TOKEN: "" },
+  });
+  assert.match(out, /^::warning title=Uptime monitors not applied::/m);
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test("CLI announces UPTIME_ALERT_EMAIL as ignored instead of silently no-oping, and still exits 0", async () => {
+  tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
+  const configPath = join(tmpDir, "monitors.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com" }]));
+  // "Secret provisioned, token absent" is the exact state that produced a
+  // permanently-green apply a consumer believed was routing alerts — so this
+  // run must still say the address is inert, and must still exit 0.
+  const { stdout, stderr } = await execFileAsync(
+    "node",
+    [CLI, "--config", configPath, "--alert-email", "oncall@example.com"],
+    { env: { ...process.env, BETTERSTACK_API_TOKEN: "" } }
+  );
+  assert.match(stderr, /DEPRECATED: --alert-email \/ \$UPTIME_ALERT_EMAIL is ignored/);
+  assert.match(stderr, /policyId/, "the notice names the replacement, not just the removal");
+  assert.match(stdout, /^::warning title=UPTIME_ALERT_EMAIL is ignored::/m);
+  assert.match(stdout, /skipping uptime-monitor apply/);
+});
+
+test("CLI reports a config's retired alertEmail on stderr and never sends it", async () => {
+  const configPath = join(tmpDir, "legacy.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com", alertEmail: "oncall@example.com" }]));
+  const { stdout, stderr } = await execFileAsync(
+    "node",
+    [CLI, "--config", configPath, "--dry-run", "--alert-email", "oncall@example.com"],
+    { env: { ...process.env, BETTERSTACK_API_TOKEN: "tok", BETTERSTACK_API_BASE_OVERRIDE: "http://127.0.0.1:9" } }
+  ).catch((err) => err);
+  assert.match(stderr, /DEPRECATED: monitor config entry \[0\] sets "alertEmail"/);
+  assert.match(stderr, /DEPRECATED: --alert-email \/ \$UPTIME_ALERT_EMAIL is ignored/);
+  assert.match(stdout, /::warning title=UPTIME_ALERT_EMAIL is ignored::/);
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
 test("CLI exits non-zero on an invalid config file even with a token set", () => {
   tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
   const configPath = join(tmpDir, "monitors.json");

package/scripts/check-playwright-browser-install.test.mjs

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+/**
+ * check-playwright-browser-install.test.mjs — regression guard for the e2e
+ * tier's Playwright browser install (Story #396).
+ *
+ * The bug this pins: the install step was gated on
+ * `steps.playwright-cache.outputs.cache-hit != 'true'`. `actions/cache` sets
+ * `cache-hit: true` on an EXACT key match and says nothing about what the
+ * restored tree actually contains, so the gate treats "an entry exists under
+ * this key" as proof the binaries are present. A cache saved partially — or
+ * saved before a Playwright patch added a browser variant under the same
+ * version key — therefore skips the only step that would repair it, and every
+ * scenario dies in milliseconds at `browserType.launch`.
+ *
+ * It could not self-heal in either direction: the hit kept skipping the
+ * repair, and Actions cache entries are IMMUTABLE under a key (`actions/cache`
+ * skips its post-job save on an exact hit), so the bad entry was never
+ * overwritten. Hence the two halves of the fix this file guards:
+ *
+ *   1. The install runs unconditionally, so a bad restore costs a re-download
+ *      rather than the run. This is not a new cost — the pre-fix hit path
+ *      already ran `playwright install-deps`, so the same OS-dependency step
+ *      ran on BOTH branches; collapsing them adds only a browser-manifest
+ *      verify.
+ *   2. A caller-settable salt is folded into the cache key, so an operator can
+ *      stop paying that repair on every run by moving to a fresh key — without
+ *      hand-deleting caches through the GitHub API.
+ *
+ * Asserting the key by string-matching its spelling would pin the text rather
+ * than the contract. The property that actually matters is RELATIONAL: the
+ * default salt must leave the key byte-for-byte identical to the pre-fix one
+ * (or every consumer's warm cache is silently invalidated by the upgrade), and
+ * distinct salts must produce distinct keys (or the escape hatch does not
+ * escape). So this extracts the real key template and resolves it under
+ * several salt values, the same read-then-execute approach as
+ * check-toolchain-cache-default.test.mjs.
+ *
+ * Run: node --test scripts/check-playwright-browser-install.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const QUALITY = ".github/workflows/pr-quality.yml";
+const SALT_INPUT = "playwright-cache-salt";
+
+/**
+ * The fixed literal the resolve step falls back to (Story #400).
+ *
+ * It must stay a CONSTANT. A host- or run-derived fallback (`$GITHUB_SHA`, a
+ * date) satisfies "the step no longer fails" while minting a new cache key on
+ * every run — permanently defeating the ~460 MiB cache the step exists to
+ * label, which is a worse outcome than the abort it replaced.
+ */
+const SENTINEL = "unresolved";
+
+/** The exact key template the tier carried before Story #396. */
+const PRE_FIX_KEY = "playwright-${{ runner.os }}-${{ steps.pw-version.outputs.version }}";
+const PRE_FIX_RESTORE_KEY = "playwright-${{ runner.os }}-";
+
+const text = readFileSync(QUALITY, "utf8");
+
+/**
+ * The workflow with whole-line `#` comments removed.
+ *
+ * The guard is about what the workflow DOES, not what it says: the tier
+ * carries a comment naming the very expression this file forbids, so that a
+ * future reader is told not to reintroduce it. Scanning raw text would let
+ * that warning fail the check it exists to support. Only leading-`#` lines are
+ * dropped — never a mid-line `#`, which could sit inside a quoted value.
+ */
+const code = text
+  .split("\n")
+  .filter((l) => !l.trimStart().startsWith("#"))
+  .join("\n");
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * The `steps:` block of the named job, sliced by indentation.
+ *
+ * Scans lines rather than building a `new RegExp` around the job name: a
+ * dynamically-constructed regex is a SAST finding (ReDoS surface) and buys
+ * nothing here, since the block boundary is just indentation.
+ */
+function jobBlock(name, source = code) {
+  const lines = source.split("\n");
+  const start = lines.indexOf(`  ${name}:`);
+  assert.notEqual(start, -1, `${QUALITY}: job \`${name}\` not found`);
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") {
+      out.push(lines[i]);
+      continue;
+    }
+    // Dedent to the job-name level or beyond → the block ended.
+    if (lines[i].match(/^(\s*)/)[1].length <= 2) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+/**
+ * The `- name: <step>` … block for one step of a job, sliced by indentation.
+ *
+ * `source` defaults to the comment-stripped text — right for asserting what the
+ * workflow DOES. Pass the raw `text` when the block is going to be EXECUTED, so
+ * the guard runs the same script the runner does rather than a stripped
+ * paraphrase of it.
+ */
+function stepBlock(job, stepName, source = code) {
+  const lines = jobBlock(job, source).split("\n");
+  const start = lines.findIndex((l) => l.trim() === `- name: ${stepName}`);
+  assert.notEqual(start, -1, `${QUALITY}: step \`${stepName}\` not found in job \`${job}\``);
+  const indent = lines[start].match(/^(\s*)/)[1].length;
+  const out = [lines[start]];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    const width = lines[i].match(/^(\s*)/)[1].length;
+    // A sibling list item (or a dedent) at the same indent ends this step.
+    if (width <= indent) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+/** The literal `default:` of the named workflow_call input. */
+function inputDefault(name) {
+  const lines = code.split("\n");
+  const start = lines.indexOf(`      ${name}:`);
+  assert.notEqual(start, -1, `${QUALITY}: workflow_call input \`${name}\` not found`);
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    if (lines[i].match(/^(\s*)/)[1].length <= 6) break;
+    const d = lines[i].match(/^\s*default:\s*(.+)$/);
+    if (d) return d[1].trim();
+  }
+  return assert.fail(`${QUALITY}: input \`${name}\` has no default`);
+}
+
+/** The `key:` / `restore-keys:` templates of the cache step. */
+function cacheKeys() {
+  const block = stepBlock("e2e", "Cache Playwright browsers");
+  const key = block.match(/^\s*key:\s*(.+)$/m);
+  assert.ok(key, `${QUALITY}: the cache step has no \`key:\``);
+  const restore = block.match(/^\s*restore-keys:\s*\|\s*\n\s*(.+)$/m);
+  assert.ok(restore, `${QUALITY}: the cache step has no \`restore-keys:\``);
+  return { key: key[1].trim(), restoreKey: restore[1].trim() };
+}
+
+/**
+ * Resolve a key template for one salt value, leaving every other `${{ … }}`
+ * placeholder untouched so the result is directly comparable to the pre-fix
+ * literal. Split/join rather than a constructed regex, for the SAST reason
+ * above.
+ */
+function resolveSalt(template, salt) {
+  return template
+    .split(`\${{ inputs.${SALT_INPUT} }}`)
+    .join(salt)
+    .split(`\${{ inputs['${SALT_INPUT}'] }}`)
+    .join(salt);
+}
+
+/**
+ * The dedented body of a step's `run: |` block, taken from the RAW workflow
+ * text so the guard executes what the runner executes.
+ *
+ * This is only sound while the block holds no `${{ }}` expression — the runner
+ * substitutes those before bash ever sees them, and there is no substituting
+ * them here. A dedicated test below pins that precondition rather than leaving
+ * it as a silent assumption.
+ */
+function runScript(job, stepName) {
+  const lines = stepBlock(job, stepName, text).split("\n");
+  const start = lines.findIndex((l) => l.trim() === "run: |");
+  assert.notEqual(start, -1, `${QUALITY}: step \`${stepName}\` has no \`run: |\` block`);
+  const body = lines.slice(start + 1);
+  assert.ok(body.length > 0, `${QUALITY}: step \`${stepName}\` has an empty \`run:\` block`);
+  const indent = body[0].match(/^(\s*)/)[1].length;
+  return body.map((l) => l.slice(indent)).join("\n");
+}
+
+/**
+ * Run a script under the runner's own shell invocation, in a throwaway cwd.
+ *
+ * GitHub executes `shell: bash` as `bash --noprofile --norc -eo pipefail
+ * {0}` — the `-e` is the whole reason the pre-fix step could kill the tier, so
+ * the guard reproduces the flags exactly. `cwd` is passed to `spawnSync` and
+ * `process.chdir` is never called: this file's later tests read
+ * `docs/reusable-workflows.md` by a RELATIVE path, and a leaked cwd would fail
+ * them for a reason that has nothing to do with the change under test.
+ */
+function runInDir(script, cwd) {
+  const outPath = join(cwd, "github-output");
+  writeFileSync(outPath, "");
+  const scriptPath = join(cwd, "step.sh");
+  writeFileSync(scriptPath, script);
+  const res = spawnSync("bash", ["--noprofile", "--norc", "-eo", "pipefail", scriptPath], {
+    cwd,
+    env: { ...process.env, GITHUB_OUTPUT: outPath },
+    encoding: "utf8",
+  });
+  const outputs = new Map();
+  for (const line of readFileSync(outPath, "utf8").split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0) outputs.set(line.slice(0, eq), line.slice(eq + 1));
+  }
+  return { status: res.status, stderr: res.stderr, outputs };
+}
+
+/** A temp directory, removed however the callback exits. */
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "pw-version-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Plant a resolvable `@playwright/test` under `dir`.
+ *
+ * The `exports` map matters: the real package restricts subpath access and
+ * lists `"./package.json"` explicitly. Without it here, a resolution strategy
+ * that is ILLEGAL against the real package would still pass this guard.
+ */
+function plantPlaywright(dir, version) {
+  const pkgDir = join(dir, "node_modules", "@playwright", "test");
+  mkdirSync(pkgDir, { recursive: true });
+  writeFileSync(
+    join(pkgDir, "package.json"),
+    JSON.stringify({
+      name: "@playwright/test",
+      version,
+      exports: { "./package.json": "./package.json" },
+    }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The contract
+// ---------------------------------------------------------------------------
+
+test("no step gates on the Playwright cache-hit output", () => {
+  // AC-1, the defect itself. `cache-hit` is true whenever an entry EXISTS
+  // under the key — it is not a statement about the entry's contents, so no
+  // step may treat it as one.
+  assert.doesNotMatch(
+    code,
+    /steps\.playwright-cache\.outputs\.cache-hit/,
+    "a cache-hit gate is back: a partial cache would again be fatal rather than repaired",
+  );
+});
+
+test("the browser install runs unconditionally with --with-deps", () => {
+  // AC-1. Unconditional is the whole fix — an `if:` of ANY shape here
+  // reintroduces a path where a bad restore is never repaired.
+  const block = stepBlock("e2e", "Install Playwright browsers");
+  assert.match(block, /run:\s*pnpm exec playwright install --with-deps/);
+  assert.doesNotMatch(
+    block,
+    /^\s*if:/m,
+    "the install step must carry no condition — see this file's header",
+  );
+});
+
+test("the cache-hit-only OS-dependency step is gone", () => {
+  // AC-1. Its only reason to exist was the hit branch; leaving it behind
+  // would run `install-deps` twice on every run.
+  assert.doesNotMatch(
+    jobBlock("e2e"),
+    /- name: Install browser OS dependencies/,
+    "the split OS-dependency step is redundant once the install is unconditional",
+  );
+});
+
+test(`the ${SALT_INPUT} input exists with a literal default`, () => {
+  // AC-2. A `workflow_call` default may not hold an expression: GitHub
+  // resolves defaults during interface validation, before any context exists,
+  // and check-workflow-portability.mjs Rule 2 rejects it outright.
+  const value = inputDefault(SALT_INPUT);
+  assert.doesNotMatch(value, /\$\{\{/, "a workflow_call default may not hold an expression");
+  assert.equal(value, "''");
+});
+
+test("the cache key interpolates the salt input", () => {
+  // AC-2. Declared-but-unread is the failure mode that makes the escape hatch
+  // silently inert.
+  const { key } = cacheKeys();
+  assert.match(key, /inputs\./, "the key does not read any input");
+  assert.notEqual(
+    resolveSalt(key, "probe"),
+    key,
+    `the key does not interpolate \`inputs.${SALT_INPUT}\``,
+  );
+});
+
+test("the default salt leaves the cache key byte-for-byte unchanged", () => {
+  // AC-3 — the compatibility contract. If this drifts, every consumer's warm
+  // ~460 MiB cache is silently orphaned the moment they adopt the release,
+  // which is a worse outage than the bug being fixed.
+  const { key, restoreKey } = cacheKeys();
+  assert.equal(resolveSalt(key, ""), PRE_FIX_KEY);
+  assert.equal(resolveSalt(restoreKey, ""), PRE_FIX_RESTORE_KEY);
+});
+
+test("distinct salts produce distinct cache keys", () => {
+  // AC-4 — the escape hatch actually escapes. A salt that collapses into the
+  // same key (interpolated into a comment, or into a segment the key does not
+  // use) would leave the operator back at deleting caches by hand.
+  const { key } = cacheKeys();
+  const base = resolveSalt(key, "");
+  const bumped = resolveSalt(key, "-v2");
+  const bumpedAgain = resolveSalt(key, "-v3");
+  assert.notEqual(bumped, base, "a non-empty salt must not resolve to the default key");
+  assert.notEqual(bumpedAgain, bumped, "two different salts must not collide");
+});
+
+test("the salt does not disturb the restore-keys prefix", () => {
+  // A deliberate asymmetry, not an oversight: the prefix fallback must keep
+  // matching older entries so a salt bump still gets a WARM start. The
+  // unconditional install then fills whatever the old entry was missing, and
+  // because a prefix (non-exact) restore leaves `cache-hit` false, the
+  // post-job save writes a complete tree under the NEW key. That is what
+  // completes the escape — one run, no manual cache deletion.
+  const { restoreKey } = cacheKeys();
+  assert.equal(
+    resolveSalt(restoreKey, "-v2"),
+    PRE_FIX_RESTORE_KEY,
+    "restore-keys must stay salt-free so a bumped key still warm-starts",
+  );
+});
+
+test("the documented input row states the default and the escape semantics", () => {
+  // AC-6. The row is the consumer-facing contract for a knob whose entire
+  // purpose is manual operator use — undocumented, it may as well not exist.
+  const docs = readFileSync("docs/reusable-workflows.md", "utf8");
+  const rows = docs
+    .split("\n")
+    .filter((l) => l.startsWith(`| \`${SALT_INPUT}\``) && /\|\s*string\s*\|/.test(l));
+  assert.equal(rows.length, 1, "expected exactly one documented input row");
+  assert.match(rows[0], /`''`/, "row does not state the empty-string default");
+  assert.match(rows[0], /cache/i, "row does not explain what the salt affects");
+});
+
+// ---------------------------------------------------------------------------
+// Version resolution (Story #400)
+//
+// The pre-fix step ran `node -e "…require('./node_modules/@playwright/test/…')"`
+// as a bare `VAR=$(…)` assignment. Under `bash -eo pipefail` that propagates
+// the substitution's exit status, so on a consumer whose ROOT node_modules
+// lacks the package — pnpm's isolated layout only symlinks a root DIRECT
+// dependency, so a workspace-owned Playwright has no such path — `set -e`
+// killed the step and took the whole e2e tier with it. A step that exists only
+// to LABEL a cache key must never be able to do that.
+// ---------------------------------------------------------------------------
+
+test("version resolution uses a bare specifier, not a hardcoded root path", () => {
+  const block = stepBlock("e2e", "Resolve Playwright version");
+  assert.doesNotMatch(
+    block,
+    /\.\/node_modules\/@playwright\/test/,
+    "a hardcoded root path is back: a workspace-owned Playwright would not resolve",
+  );
+  assert.match(
+    block,
+    /require\((['"])@playwright\/test\/package\.json\1\)/,
+    "resolution must go through the bare specifier, which walks node_modules",
+  );
+});
+
+test("the resolve step's run block holds no workflow expression", () => {
+  // The precondition for executing this step in the tests below: the runner
+  // substitutes `${{ }}` before bash sees it, and nothing substitutes it here.
+  // Threading an input into the block would leave the guard asserting against
+  // a string that never runs.
+  assert.doesNotMatch(
+    runScript("e2e", "Resolve Playwright version"),
+    /\$\{\{/,
+    "keep the run block expression-free so the guard executes the runner's text",
+  );
+});
+
+test("the sentinel is assigned as a fixed literal", () => {
+  // Invariant 2 (see SENTINEL above). Assert the SHAPE of the assignment, not
+  // merely that the step stopped failing — `PW_VERSION=$(date +%F)` would pass
+  // a stability check across two runs in the same second and still rekey the
+  // cache on every push.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const assignments = script
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => !l.startsWith("#") && l.includes(`=${SENTINEL}`));
+  assert.equal(assignments.length, 1, `expected exactly one \`=${SENTINEL}\` assignment`);
+  const [assignment] = assignments;
+  assert.match(assignment, /^[A-Za-z_][A-Za-z0-9_]*=unresolved$/, "the sentinel must be a literal");
+  assert.ok(!assignment.includes("$("), "the sentinel must not be command-substituted");
+  assert.ok(!assignment.includes("${"), "the sentinel must not be parameter-expanded");
+});
+
+test("an unresolvable @playwright/test yields the sentinel instead of failing the tier", () => {
+  // The defect itself. A temp dir has no `node_modules` anywhere up its tree,
+  // which is exactly the consumer shape that lost the tier.
+  const script = runScript("e2e", "Resolve Playwright version");
+  withTempDir((dir) => {
+    const { status, outputs, stderr } = runInDir(script, dir);
+    assert.equal(status, 0, `the step must not fail the tier; stderr:\n${stderr}`);
+    assert.equal(outputs.get("version"), SENTINEL);
+  });
+});
+
+test("the sentinel is stable across runs, so the cache key does not churn", () => {
+  // Invariant 2 again, from the outside: a value that varies run to run mints a
+  // fresh key every time and permanently defeats the cache.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const read = () => withTempDir((dir) => runInDir(script, dir).outputs.get("version"));
+  const first = read();
+  // Pin the value, not just its stability: two runs that both emit NOTHING are
+  // trivially equal, which would let a step that never writes the output pass.
+  assert.equal(first, SENTINEL);
+  assert.equal(read(), first);
+});
+
+test("a resolvable @playwright/test produces the pre-fix cache key exactly", () => {
+  // The compatibility contract, end to end: what the step actually emits, fed
+  // through the real key template at the default salt, must equal the key
+  // consumers' warm caches already sit under.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const version = "1.61.1";
+  const resolved = withTempDir((dir) => {
+    plantPlaywright(dir, version);
+    const { status, outputs, stderr } = runInDir(script, dir);
+    assert.equal(status, 0, `stderr:\n${stderr}`);
+    return outputs.get("version");
+  });
+  assert.equal(resolved, version, "the step must report the resolved package's version");
+
+  const { key } = cacheKeys();
+  const withVersion = resolveSalt(key, "")
+    .split("${{ steps.pw-version.outputs.version }}")
+    .join(resolved);
+  assert.equal(withVersion, `playwright-\${{ runner.os }}-${version}`);
+});

package/templates/workflows/uptime-apply.yml

@@ -46,9 +46,15 @@ jobs:
       # the checked-in config; a workflow_dispatch preview run can pass
       # apply:'false' instead to dry-run without writing.
       apply: ${{ github.event_name == 'push' && 'true' || 'false' }}
-    # Frozen secret surface: only these two cross into the shared workflow.
-    # Both are optional on the shared side — an absent BETTERSTACK_API_TOKEN
-    # is the documented graceful-degradation (skip-with-notice) path.
+    # Frozen secret surface. BETTERSTACK_API_TOKEN is optional on the shared
+    # side — absent, the apply takes the documented graceful-degradation
+    # (skip-with-notice) path and raises a warning annotation.
+    #
+    # UPTIME_ALERT_EMAIL is deprecated and deliberately not passed here:
+    # Better Stack's monitor `email` field is a boolean switch, not a
+    # recipient, so the address never routed alerts. Set a monitor entry's
+    # `policyId` (escalation policy) to control who is alerted. The shared
+    # workflow still declares the secret, so an existing caller that passes
+    # it keeps compiling.
     secrets:
       BETTERSTACK_API_TOKEN: ${{ secrets.BETTERSTACK_API_TOKEN }}
-      UPTIME_ALERT_EMAIL: ${{ secrets.UPTIME_ALERT_EMAIL }}