mandrel-platform 0.21.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.21.0",
+  "version": "0.25.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^1.81.0"
+    "mandrel": "^1.83.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-pin-drift.mjs

@@ -979,18 +979,61 @@ export function hasDrift(report) {
   return report.results.some((r) => r.error || r.drift);
 }
 
+/**
+ * Is EVERY configured consumer an `error` row (M11)? This is the signature of a
+ * dead cross-repo credential: a PIN_DRIFT_TOKEN that was *provided* but has
+ * expired (fine-grained PATs always expire) can no longer read ANY consumer, so
+ * every `fetchConsumerWorkflows` call fails closed to an `error` row. Contrast
+ * the not-yet-provisioned bootstrap case: there the token is *absent*, the run
+ * legitimately can't read the private consumers, and that benign state must keep
+ * its current exit-0 behavior. The caller distinguishes the two by whether the
+ * token was provided (see `runCli`'s `tokenProvided`); this predicate only
+ * answers "did every row error", which — given a provided token — means the
+ * credential died rather than "no drift".
+ *
+ * Requires at least one consumer (an empty registry is vacuously not a
+ * dead-credential signal).
+ *
+ * @param {{ results: Array<{ error?: string }> }} report
+ * @returns {boolean}
+ */
+export function allConsumersErrored(report) {
+  const results = Array.isArray(report.results) ? report.results : [];
+  return results.length > 0 && results.every((r) => Boolean(r.error));
+}
+
 // ---------------------------------------------------------------------------
 // CLI entry
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether the cross-repo `PIN_DRIFT_TOKEN` was PROVIDED (non-empty) to the run
+ * (M11). The scheduled/dispatch workflow reads consumers over the `gh` CLI with
+ * `GH_TOKEN: ${{ secrets.PIN_DRIFT_TOKEN || github.token }}` — the built-in
+ * `github.token` fallback can only read THIS repo, so cross-repo reads fail
+ * closed to `error` rows both when the token is absent (bootstrap) AND when it
+ * is provided-but-dead (expired PAT). This env var is the only signal that
+ * distinguishes the two: the workflow sets it to the raw secret so an empty
+ * value ⇒ absent (bootstrap, benign) and a non-empty value ⇒ provided (a
+ * total error sweep then means the credential died).
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function pinDriftTokenProvided(env) {
+  return typeof env.PIN_DRIFT_TOKEN === "string" && env.PIN_DRIFT_TOKEN.length > 0;
+}
+
 /**
  * @param {{
  *   argv?: string[],
  *   cwd?: string,
  *   stdout?: { write: (s: string) => void },
  *   stderr?: { write: (s: string) => void },
+ *   env?: Record<string, string | undefined>,
  *   runGh?: (args: string[]) => string,
  *   summaryPath?: string | undefined,
+ *   tokenProvided?: boolean,
  *   nowMs?: number,
  * }} [opts]
  * @returns {number} exit code
@@ -1000,8 +1043,10 @@ export function runCli({
   cwd = process.cwd(),
   stdout = process.stdout,
   stderr = process.stderr,
+  env = process.env,
   runGh = defaultGhRunner,
   summaryPath = process.env.GITHUB_STEP_SUMMARY,
+  tokenProvided = pinDriftTokenProvided(env),
   nowMs = Date.now(),
 } = {}) {
   const { config: configRel, json, strict } = parseArgv(argv);
@@ -1025,9 +1070,19 @@ export function runCli({
 
   const report = buildReport(config, runGh, nowMs);
   const drift = hasDrift(report);
+  // M11: a PROVIDED-but-dead PIN_DRIFT_TOKEN (expired PAT) can no longer read
+  // ANY consumer, so every row fails closed to `error`. That is a credential
+  // failure, NOT the benign not-yet-provisioned bootstrap (token absent) — fail
+  // the run unconditionally (even without --strict, which the scheduled path
+  // can never pass) so the death is loud instead of a green no-op. The absent-
+  // token bootstrap keeps its current behavior: tokenProvided is false, so this
+  // branch never fires and the run exits per the drift/--strict rules below.
+  const deadCredential = tokenProvided && allConsumersErrored(report);
 
   if (json) {
-    stdout.write(`${JSON.stringify({ kind: "pin-drift-report", drift, ...report }, null, 2)}\n`);
+    stdout.write(
+      `${JSON.stringify({ kind: "pin-drift-report", drift, deadCredential, ...report }, null, 2)}\n`,
+    );
   } else {
     const text = renderReport(report);
     stdout.write(`${text}\n`);
@@ -1042,6 +1097,16 @@ export function runCli({
     }
   }
 
+  if (deadCredential) {
+    stderr.write(
+      "::error::[pin-drift] PIN_DRIFT_TOKEN was provided but every cross-repo " +
+        "consumer read errored — the credential is dead (likely an expired " +
+        "fine-grained PAT), not a not-yet-provisioned bootstrap. Rotate the " +
+        "token. See docs/runbooks/pin-drift-dashboard.md.\n",
+    );
+    return 1;
+  }
+
   if (strict && drift) {
     stderr.write(`[pin-drift] ❌ drift detected (--strict)\n`);
     return 1;

package/scripts/check-pin-drift.test.mjs

@@ -20,6 +20,7 @@ import { join } from "node:path";
 import { test } from "node:test";
 
 import {
+  allConsumersErrored,
   buildReport,
   classifyNpmPin,
   classifyStaleLiterals,
@@ -34,6 +35,7 @@ import {
   isWithinReleaseAgeWindow,
   parseDurationMs,
   parseSemver,
+  pinDriftTokenProvided,
   renderReport,
   resolveLatestRelease,
   runCli,
@@ -883,3 +885,126 @@ test("runCli --strict DOES exit 1 once the held release ages out", () => {
     rmSync(cfgDir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// M11 — provided-but-dead PIN_DRIFT_TOKEN (expired PAT) vs. not-yet-provisioned
+// bootstrap. A dead credential can read NO consumer, so every row fails closed
+// to an `error` row; that must hard-fail EVEN without --strict (the scheduled
+// path can never pass --strict). The absent-token bootstrap — identical row
+// shape but token unset — must keep its benign exit-0.
+// (temp/audits/workflow-robustness-review-2026-07-05.md M11)
+// ---------------------------------------------------------------------------
+
+const DEAD_CRED_CONFIG = {
+  platformRepo: PLATFORM,
+  consumers: [
+    { name: "c1", repo: "o/c1", branch: "main" },
+    { name: "c2", repo: "o/c2", branch: "main" },
+  ],
+};
+
+/**
+ * A gh runner where the platform's own release resolution succeeds (that read
+ * uses the built-in token, which CAN read this repo) but EVERY cross-repo
+ * consumer workflow-listing call fails with a non-404 (auth/transport) — the
+ * exact shape of a dead cross-repo PAT. Every consumer therefore becomes an
+ * `error` row.
+ */
+function makeAllConsumersFailRunGh() {
+  return (args) => {
+    const path = args[1];
+    if (path === `repos/${PLATFORM}/releases/latest`) {
+      return JSON.stringify({ tag_name: TAG });
+    }
+    if (path === `repos/${PLATFORM}/git/ref/tags/${TAG}`) {
+      return JSON.stringify({ object: { sha: LATEST_SHA, type: "commit" } });
+    }
+    if (/\/contents\/\.github\/workflows/.test(path)) {
+      // 403/5xx (not 404) → fail-closed to an `error` row, mirroring an expired
+      // PAT that can no longer read the private consumer repo.
+      throw ghHttpError(403, "Forbidden");
+    }
+    throw new Error(`unexpected gh api path: ${path}`);
+  };
+}
+
+test("pinDriftTokenProvided: non-empty ⇒ true, empty/absent ⇒ false", () => {
+  assert.equal(pinDriftTokenProvided({ PIN_DRIFT_TOKEN: "ghp_live" }), true);
+  assert.equal(pinDriftTokenProvided({ PIN_DRIFT_TOKEN: "" }), false);
+  assert.equal(pinDriftTokenProvided({}), false);
+});
+
+test("allConsumersErrored: true only when every row errored and ≥1 consumer", () => {
+  const report = buildReport(DEAD_CRED_CONFIG, makeAllConsumersFailRunGh());
+  assert.equal(allConsumersErrored(report), true);
+  // A single clean row flips it back to false — that is drift/partial, not a
+  // dead credential.
+  assert.equal(
+    allConsumersErrored({ results: [{ error: "x" }, { drift: true }] }),
+    false,
+  );
+  assert.equal(allConsumersErrored({ results: [] }), false);
+});
+
+test("runCli: PROVIDED-but-dead PIN_DRIFT_TOKEN (all rows error) exits 1 with ::error:: even without --strict", () => {
+  cfgDir = mkdtempSync(join(tmpdir(), "pin-drift-dead-"));
+  const p = join(cfgDir, "consumers.json");
+  writeFileSync(p, JSON.stringify(DEAD_CRED_CONFIG));
+  const stderr = capture();
+  try {
+    const code = runCli({
+      argv: ["--config", p], // NOTE: no --strict.
+      env: { PIN_DRIFT_TOKEN: "ghp_expired" },
+      runGh: makeAllConsumersFailRunGh(),
+      stdout: capture(),
+      stderr,
+      summaryPath: undefined,
+    });
+    assert.equal(code, 1);
+    assert.match(stderr.text(), /::error::/);
+    assert.match(stderr.text(), /credential is dead/);
+  } finally {
+    rmSync(cfgDir, { recursive: true, force: true });
+  }
+});
+
+test("runCli: dead-credential also surfaces in the --json envelope (deadCredential:true)", () => {
+  cfgDir = mkdtempSync(join(tmpdir(), "pin-drift-dead-json-"));
+  const p = join(cfgDir, "consumers.json");
+  writeFileSync(p, JSON.stringify(DEAD_CRED_CONFIG));
+  const stdout = capture();
+  try {
+    const code = runCli({
+      argv: ["--config", p, "--json"],
+      env: { PIN_DRIFT_TOKEN: "ghp_expired" },
+      runGh: makeAllConsumersFailRunGh(),
+      stdout,
+      stderr: capture(),
+      summaryPath: undefined,
+    });
+    assert.equal(code, 1);
+    const envelope = JSON.parse(stdout.text());
+    assert.equal(envelope.deadCredential, true);
+  } finally {
+    rmSync(cfgDir, { recursive: true, force: true });
+  }
+});
+
+test("runCli: ABSENT PIN_DRIFT_TOKEN bootstrap (all rows error, token unset) stays exit 0 — benign", () => {
+  cfgDir = mkdtempSync(join(tmpdir(), "pin-drift-bootstrap-"));
+  const p = join(cfgDir, "consumers.json");
+  writeFileSync(p, JSON.stringify(DEAD_CRED_CONFIG));
+  try {
+    const code = runCli({
+      argv: ["--config", p], // no --strict, no token.
+      env: {}, // PIN_DRIFT_TOKEN absent → not-yet-provisioned bootstrap.
+      runGh: makeAllConsumersFailRunGh(),
+      stdout: capture(),
+      stderr: capture(),
+      summaryPath: undefined,
+    });
+    assert.equal(code, 0);
+  } finally {
+    rmSync(cfgDir, { recursive: true, force: true });
+  }
+});