mandrel-platform 0.29.0 → 0.29.1

package/package.json

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

package/scripts/check-affected-mode.test.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * check-affected-mode.test.mjs — YAML-level regression guard for the
+ * affected-mode wiring in `.github/workflows/pr-quality.yml` (Story #319,
+ * follow-up to #314/#315).
+ *
+ * `scripts/resolve-diff-range.sh` has solid unit coverage
+ * (`resolve-diff-range.test.mjs`), but the affected-mode *wiring* inside the
+ * reusable workflow was only covered indirectly by anchor-expansion checks.
+ * This suite pins the three invariants that keep the affected-mode design
+ * correct, modelled on the sibling `check-ci-required-aggregator.test.mjs`
+ * (read the real workflow, extract blocks by indentation, assert):
+ *
+ *   1. GATING — the coverage-gate steps (`Checkout gate scripts`, `Coverage
+ *      threshold gate`) carry `inputs.coverage-threshold != 0 && !inputs.affected`,
+ *      and the bypass `::notice::` step carries the *complementary*
+ *      `inputs.coverage-threshold != 0 && inputs.affected`. A drift that drops
+ *      `!inputs.affected` (which would false-fail the whole-repo floor on an
+ *      affected subset) fails this suite.
+ *   2. NO EXPORT ON mode=none — executing the resolve-affected `run:` script
+ *      with an unresolved (`mode=none`) range leaves `TURBO_SCM_*` unset, so
+ *      turbo falls back to its own default rather than a bogus range.
+ *   3. INJECTION-SAFE EXPORT (Story #319 hardening) — a newline-bearing
+ *      `affected-base` override is rejected before the `$GITHUB_ENV` write, so
+ *      it can never inject a second env line; a single-line override exports
+ *      exactly `TURBO_SCM_BASE` / `TURBO_SCM_HEAD` and nothing else.
+ *
+ * The `run:` script is executed against real bash with a stubbed
+ * `resolve-diff-range.sh` (the sourced derivation), so no git repo is needed;
+ * skipped when bash is unavailable locally (CI's ubuntu runner always has it).
+ *
+ * Run: node --test scripts/check-affected-mode.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+const content = readFileSync(join(repoRoot, WORKFLOW), "utf8");
+
+// ---------------------------------------------------------------------------
+// Minimal indentation-based extraction (dependency-free, mirrors
+// check-ci-required-aggregator.test.mjs). A step spans from its `- ` bullet to
+// the next sibling bullet at the same indent (or a dedent below it).
+// ---------------------------------------------------------------------------
+
+function stepByName(text, name) {
+  const lines = text.split("\n");
+  const nameIdx = lines.findIndex((l) => /^\s+(- )?name:\s/.test(l) && l.includes(name));
+  assert.notEqual(nameIdx, -1, `step "${name}" not found`);
+  let start = -1;
+  for (let i = nameIdx; i >= 0; i--) {
+    if (/^\s*-\s/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  assert.notEqual(start, -1, `opening bullet for step "${name}" not found`);
+  const bulletIndent = lines[start].match(/^(\s*)/)[1].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent < bulletIndent) {
+      end = i;
+      break;
+    }
+    if (indent === bulletIndent && /^\s*-\s/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The (first) `if:` expression on a step block, trimmed. */
+function ifCondition(stepBlock) {
+  const m = stepBlock.match(/^\s+if:\s*(.+?)\s*$/m);
+  assert.ok(m, "step has no `if:` condition");
+  return m[1].trim();
+}
+
+/** The dedented body of the step's `run: |` block scalar. */
+function runScript(stepBlock) {
+  const lines = stepBlock.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// 1. GATING — coverage-gate steps gated OUT of affected mode; bypass step gated IN
+// ---------------------------------------------------------------------------
+
+test("resolve-affected step runs only in affected mode", () => {
+  const cond = ifCondition(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+  assert.match(cond, /inputs\.affected/, "the resolve step must be gated on `inputs.affected`");
+  assert.doesNotMatch(cond, /!\s*inputs\.affected/, "the resolve step must not be negated");
+});
+
+for (const step of ["Checkout gate scripts (mandrel-platform@resolved-sha)", "Coverage threshold gate"]) {
+  test(`coverage-gate step "${step}" is gated OUT of affected mode`, () => {
+    const cond = ifCondition(stepByName(content, step));
+    assert.match(
+      cond,
+      /inputs\.coverage-threshold != 0/,
+      "must still require a non-zero coverage-threshold"
+    );
+    assert.match(
+      cond,
+      /!\s*inputs\.affected/,
+      "must carry `!inputs.affected` — dropping it false-fails the whole-repo floor on an affected subset"
+    );
+  });
+}
+
+test("bypass `::notice::` step carries the complementary affected-mode gating", () => {
+  const step = stepByName(content, "Coverage floor bypassed (affected mode)");
+  const cond = ifCondition(step);
+  assert.match(cond, /inputs\.coverage-threshold != 0/, "must require a non-zero coverage-threshold");
+  assert.match(cond, /&&\s*inputs\.affected/, "must fire only in affected mode");
+  assert.doesNotMatch(
+    cond,
+    /!\s*inputs\.affected/,
+    "the bypass notice must be the complement of the gate — never negated"
+  );
+  assert.match(step, /::notice title=/, "the bypass must emit a visible ::notice::, never a silent skip");
+});
+
+// ---------------------------------------------------------------------------
+// 2 & 3. Execute the resolve-affected run script against real bash.
+// ---------------------------------------------------------------------------
+
+function bashAvailable() {
+  try {
+    execFileSync("bash", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const RESOLVE_SCRIPT = runScript(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+
+/**
+ * Run the extracted resolve-affected `run:` body with a stubbed
+ * resolve-diff-range.sh that sets RESOLVED_* from STUB_* env, capturing the
+ * lines the step wrote to $GITHUB_ENV.
+ */
+function runResolve({ mode = "", base = "", head = "", override } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "affected-mode-"));
+  try {
+    const workspace = join(dir, "ws");
+    mkdirSync(join(workspace, "_mandrel-platform-range", "scripts"), { recursive: true });
+    // Stub the sourced derivation: RESOLVED_* come from STUB_* env.
+    writeFileSync(
+      join(workspace, "_mandrel-platform-range", "scripts", "resolve-diff-range.sh"),
+      ['RESOLVED_EVENT_MODE="${STUB_MODE-}"', 'RESOLVED_BASE_SHA="${STUB_BASE-}"', 'RESOLVED_HEAD_SHA="${STUB_HEAD-}"', ""].join("\n")
+    );
+    const scriptFile = join(dir, "resolve.sh");
+    writeFileSync(scriptFile, RESOLVE_SCRIPT);
+    const envFile = join(dir, "github_env");
+    writeFileSync(envFile, "");
+
+    const env = {
+      ...process.env,
+      GITHUB_WORKSPACE: workspace,
+      GITHUB_ENV: envFile,
+      STUB_MODE: mode,
+      STUB_BASE: base,
+      STUB_HEAD: head,
+    };
+    if (override !== undefined) env.AFFECTED_BASE_OVERRIDE = override;
+
+    const r = spawnSync("bash", [scriptFile], { encoding: "utf8", env });
+    return { status: r.status, stderr: r.stderr, envLines: readFileSync(envFile, "utf8") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const exec = { skip: bashAvailable() ? false : "bash not available on this host" };
+
+test("mode=none: no ranged base resolvable → TURBO_SCM_* left unset", exec, () => {
+  const r = runResolve({ mode: "", base: "", head: "" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "mode=none must not export a base");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_HEAD/, "mode=none must not export a head");
+});
+
+test("newline-bearing affected-base override is rejected before the export (injection guard)", exec, () => {
+  const r = runResolve({ override: "deadbeef\nMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0, "a multiline override must fail the step, not export");
+  assert.doesNotMatch(r.envLines, /MALICIOUS/, "the injected env line must never reach $GITHUB_ENV");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "no partial export on a rejected override");
+});
+
+test("carriage-return-bearing affected-base override is rejected too", exec, () => {
+  const r = runResolve({ override: "deadbeef\rMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0);
+  assert.doesNotMatch(r.envLines, /MALICIOUS/);
+});
+
+test("single-line affected-base override exports exactly TURBO_SCM_BASE and TURBO_SCM_HEAD", exec, () => {
+  const r = runResolve({ override: "origin/main", head: "cafebabe" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.envLines, /^TURBO_SCM_BASE=origin\/main$/m);
+  assert.match(r.envLines, /^TURBO_SCM_HEAD=cafebabe$/m);
+  const nonEmpty = r.envLines.split("\n").filter((l) => l.trim() !== "");
+  assert.equal(nonEmpty.length, 2, `expected exactly two env lines, got: ${JSON.stringify(nonEmpty)}`);
+});

package/scripts/runner-fleet-consumers.json

@@ -1,5 +1,6 @@
 {
-  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. All nine runners (including Beestera/swarm-os's three) are co-resident on one operator Mac (2026-07-03 runner audit, repo-ops matrix §1a); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it.",
+  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. The co-resident operator Mac now carries 7 domio + 5 athportal monitored runners (plus 17 beestera/swarm-os installs that are deliberately NOT listed — see `$comment_swarm_os`); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it. Keep these counts in lockstep with the live fleets: the maintenance contract lives in templates/runbooks/runner-provisioning.md.",
+  "$comment_expectedCount": "Semantics: warn-below (over-provisioning is fine). The checker computes shortfall = max(0, expectedCount - matchingOnline) and only alarms when fewer online runners match the labels than expected — adding runners above expectedCount never trips the alarm, so a deliberate scale-up needs no immediate roster edit (though you should still bump the count to keep the shortfall floor meaningful). Removing runners on purpose (scale-down) DOES require lowering expectedCount here, otherwise the monitor will correctly flag the missing runners as a shortfall.",
   "$comment_swarm_os": "Beestera/swarm-os is deliberately NOT listed: no dsj1984-owned PAT can read another org's runner API (fine-grained PATs are bound to one resource owner; the Beestera org rejects classic PATs), so its row would permanently false-positive as 0/3 degraded. Host-level coverage is retained regardless — its runners share the Mac with the rows below, so a wedged host still trips domio/athportal. What is NOT covered: swarm-os's individual launchd services dying while the host stays healthy, and its stale-queue check. Re-add the entry if a Beestera-owned credential (fine-grained PAT or GitHub App) plus per-repo token support ever lands.",
   "$comment_staleQueuedMinutes": "A queued/waiting workflow run older than this many minutes with no online runner matching its labels is flagged as a queue-staleness signal (optional per-repo override via `staleQueuedMinutes`).",
   "defaultStaleQueuedMinutes": 20,
@@ -7,13 +8,13 @@
     {
       "name": "domio",
       "repo": "dsj1984/domio",
-      "expectedCount": 3,
+      "expectedCount": 7,
       "labels": ["self-hosted", "macOS", "ARM64", "domio-runner"]
     },
     {
       "name": "athportal",
       "repo": "dsj1984/athportal",
-      "expectedCount": 3,
+      "expectedCount": 5,
       "labels": ["self-hosted", "macOS", "ARM64", "athportal-runner"]
     }
   ]

package/templates/runbooks/runner-provisioning.md

@@ -66,6 +66,28 @@ shasum -a 256 actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 tar xzf actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 ```
 
+## ⚠️ Read second: keep the health-monitor roster in lockstep
+
+Any change to a fleet's size — **adding or removing a runner** — **MUST** be
+accompanied by an update to that repo's `expectedCount` in
+[`scripts/runner-fleet-consumers.json`](../../scripts/runner-fleet-consumers.json).
+That file is the roster the scheduled `runner-fleet-health.yml` monitor
+(`scripts/check-runner-health.mjs`) compares the live fleet against.
+
+- **Scale up (add a runner):** bump `expectedCount` so the shortfall floor
+  keeps pace. Over-provisioning does not trip the alarm on its own (the
+  monitor is **warn-below**: `shortfall = max(0, expectedCount - matchingOnline)`),
+  but leaving the count stale hides a later drop back down to the old value.
+- **Scale down (remove a runner):** lower `expectedCount` in the same change,
+  otherwise the monitor will correctly flag the now-missing runner(s) as a
+  shortfall and page the operator for a deliberate downsizing.
+
+If the roster and the live fleet drift apart, the monitor either false-alarms
+(count too high) or goes silent on real outages above the stale threshold
+(count too low) — the exact mis-calibration this contract exists to prevent.
+See also [`runner-fleet-health.md`](runner-fleet-health.md) for the operator
+response when the monitor does fire.
+
 ## 2. Register with `config.sh` (repo-level)
 
 Registration is **repo-level** (the fleet's standing model), not org-level.
@@ -179,7 +201,10 @@ The runner loads `.env` at service start — after any `.env` change, restart:
   (§5). Mint the removal token via
   `gh api -X POST repos/<OWNER>/<REPO>/actions/runners/remove-token --jq .token`.
 - **Decommission.** Same removal sequence, then delete `<RUNNER_DIR>`.
-  Confirm the runner disappeared from *Settings → Actions → Runners*.
+  Confirm the runner disappeared from *Settings → Actions → Runners*, **and**
+  lower the repo's `expectedCount` in `scripts/runner-fleet-consumers.json`
+  (see the roster-lockstep callout above) so the health monitor does not flag
+  the intentional removal as a shortfall.
 
 ## Project-Specific Notes