mandrel-platform 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.24.0",
+  "version": "0.26.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 });
+  }
+});

package/scripts/check-workflow-gh-flags.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * check-workflow-gh-flags.mjs — static lint for known-invalid `gh` CLI flag
+ * combinations inside GitHub Actions workflows.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A `gh api` invocation is valid shell and passes `actionlint` /
+ * `shellcheck`, yet can still be rejected by the `gh` CLI at RUNTIME because a
+ * flag combination is unsupported. That failure surfaces only when the step
+ * runs — for the release pipeline, that means "at release time", the worst
+ * possible moment. Release 0.25.0 wedged its `await-smoke` gate for exactly
+ * this reason:
+ *
+ *     gh api --paginate --slurp "…/status" --jq '…'
+ *     → the `--slurp` option is not supported with `--jq` or `--template`
+ *
+ * Every poll attempt failed instantly, `|| echo none` swallowed it, and the
+ * gate timed out on EVERY release even though smoke was green. No unit test,
+ * acceptance critic, epic-audit, or code-review caught it because none
+ * exercised the real `gh` CLI. This lint shifts that class of failure LEFT
+ * into `ci-required` so an invalid `gh` invocation fails a PR, not a release.
+ *
+ * RULES (extensible — add more as new `gh` incompatibilities are discovered):
+ *   1. slurp-with-jq — `gh` rejects `--slurp` together with `--jq` or
+ *      `--template`. The supported pattern is `gh api --slurp … | jq …`
+ *      (pipe to a STANDALONE jq), so this lint splits on shell pipes and only
+ *      flags a single `gh` command segment that carries BOTH flags.
+ *
+ * SCOPE: `.github/workflows/*.yml` + `templates/workflows/*.yml`.
+ * Exit 0 when clean, 1 when any violation is found (prints file:line).
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const WORKFLOW_DIRS = ['.github/workflows', 'templates/workflows'];
+
+/**
+ * Blank out full-line comments (YAML `#` lines and shell `#` comment lines
+ * inside `run:` blocks) while preserving line count, so the lint never
+ * analyzes PROSE — a workflow comment that merely *documents* an invalid flag
+ * combo (like this file's own header, or a step comment describing the rule)
+ * is not a `gh` command and must not be flagged. Only whole-line comments are
+ * stripped; an inline `#` inside real shell is left alone (it is rarely a
+ * comment there and never carries the flag pattern this lint targets).
+ */
+export function stripComments(source) {
+  return source
+    .split('\n')
+    .map((line) => (/^\s*#/.test(line) ? '' : line))
+    .join('\n');
+}
+
+/**
+ * Collapse shell line-continuations (`\` + newline) so a multi-line `gh`
+ * invocation becomes one logical line, WITHOUT losing the original line number
+ * of where the command started. Returns an array of
+ * `{ line, text }` logical commands (1-indexed `line`).
+ */
+export function collapseContinuations(source) {
+  const rawLines = source.split('\n');
+  const logical = [];
+  let buf = null;
+  let startLine = 0;
+  for (let i = 0; i < rawLines.length; i++) {
+    const line = rawLines[i];
+    const continues = /\\\s*$/.test(line);
+    const stripped = line.replace(/\\\s*$/, '');
+    if (buf === null) {
+      startLine = i + 1;
+      buf = stripped;
+    } else {
+      buf += ' ' + stripped.trim();
+    }
+    if (!continues) {
+      logical.push({ line: startLine, text: buf });
+      buf = null;
+    }
+  }
+  if (buf !== null) logical.push({ line: startLine, text: buf });
+  return logical;
+}
+
+/**
+ * Split a logical shell line into command segments on the separators that
+ * terminate one simple command and start another: pipe, `;`, `&&`, `||`,
+ * and command-substitution boundaries. A `gh api --slurp … | jq …` therefore
+ * becomes two segments — the `gh` part (no `--jq`) and the `jq` part — so the
+ * SUPPORTED pattern is never flagged.
+ */
+export function splitSegments(text) {
+  // Split on |, ||, ;, &&, and the `$(` / `)` / backtick substitution edges.
+  return text.split(/\|\||&&|[|;`]|\$\(|\)/);
+}
+
+/** Return an array of rule-violation strings for one segment (may be empty). */
+export function lintSegment(segment) {
+  const violations = [];
+  const isGh = /(^|\s)gh(\s|$)/.test(segment);
+  if (!isGh) return violations;
+
+  // Rule 1 — slurp-with-jq/template.
+  const hasSlurp = /(^|\s)--slurp(\s|=|$)/.test(segment);
+  const hasJq = /(^|\s)--jq(\s|=|$)/.test(segment);
+  const hasTemplate = /(^|\s)(--template|-t)(\s|=|$)/.test(segment);
+  if (hasSlurp && (hasJq || hasTemplate)) {
+    violations.push(
+      `slurp-with-jq: \`gh\` rejects --slurp together with ${
+        hasJq ? '--jq' : '--template'
+      }. Pipe --slurp's output to a STANDALONE jq instead: \`gh api --slurp … | jq …\`.`,
+    );
+  }
+  return violations;
+}
+
+/** Lint a single workflow file. Returns an array of finding objects. */
+export function lintFile(path, source) {
+  const findings = [];
+  for (const { line, text } of collapseContinuations(stripComments(source))) {
+    for (const segment of splitSegments(text)) {
+      for (const rule of lintSegment(segment)) {
+        findings.push({ path, line, rule });
+      }
+    }
+  }
+  return findings;
+}
+
+function collectWorkflowFiles() {
+  const files = [];
+  for (const dir of WORKFLOW_DIRS) {
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (name.endsWith('.yml') || name.endsWith('.yaml')) {
+        files.push(join(dir, name));
+      }
+    }
+  }
+  return files.sort();
+}
+
+function main() {
+  const files = collectWorkflowFiles();
+  const findings = [];
+  for (const f of files) {
+    findings.push(...lintFile(f, readFileSync(f, 'utf8')));
+  }
+
+  if (findings.length === 0) {
+    console.log(
+      `[check-workflow-gh-flags] ✓ ${files.length} workflow file(s) — no invalid gh flag combinations.`,
+    );
+    return 0;
+  }
+
+  console.error(
+    `[check-workflow-gh-flags] ✗ ${findings.length} invalid gh flag combination(s):\n`,
+  );
+  for (const { path, line, rule } of findings) {
+    console.error(`  ${path}:${line} — ${rule}`);
+  }
+  console.error(
+    '\nThese pass actionlint/shellcheck but fail the `gh` CLI at RUNTIME. Fix before merge.',
+  );
+  return 1;
+}
+
+// Run only as a CLI, not when imported by the test suite.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main());
+}

package/scripts/check-workflow-gh-flags.test.mjs

@@ -0,0 +1,86 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  collapseContinuations,
+  splitSegments,
+  lintSegment,
+  lintFile,
+} from './check-workflow-gh-flags.mjs';
+
+test('collapseContinuations joins backslash-continued lines and keeps start line', () => {
+  const src = ['a=1', 'state="$(gh api --slurp x \\', '  --jq y \\', '  || echo none)"', 'b=2'].join(
+    '\n',
+  );
+  const logical = collapseContinuations(src);
+  const joined = logical.find((l) => l.text.includes('gh api'));
+  assert.equal(joined.line, 2, 'start line is the first line of the command');
+  assert.match(joined.text, /gh api --slurp x\s+--jq y\s+\|\| echo none/);
+});
+
+test('lintSegment flags gh --slurp with --jq (the 0.25.0 regression)', () => {
+  const v = lintSegment('gh api --paginate --slurp "repos/x/commits/y/status" --jq \'.a\'');
+  assert.equal(v.length, 1);
+  assert.match(v[0], /slurp-with-jq/);
+});
+
+test('lintSegment flags gh --slurp with --template / -t', () => {
+  assert.equal(lintSegment('gh api --slurp x --template "{{.a}}"').length, 1);
+  assert.equal(lintSegment('gh api --slurp x -t "{{.a}}"').length, 1);
+});
+
+test('lintSegment does NOT flag the SUPPORTED pattern (slurp piped to standalone jq)', () => {
+  // The pipe splits this into two segments upstream; each segment alone is clean.
+  assert.equal(lintSegment('gh api --paginate --slurp "…/status"').length, 0);
+  assert.equal(lintSegment(" jq -r '[.[].statuses[]] | first.state'").length, 0);
+});
+
+test('lintSegment ignores non-gh commands and plain gh usage', () => {
+  assert.equal(lintSegment('jq --slurp --jq nonsense').length, 0, 'not a gh command');
+  assert.equal(lintSegment('gh api "repos/x" --jq .a').length, 0, 'jq without slurp is fine');
+  assert.equal(lintSegment('gh api --slurp x').length, 0, 'slurp without jq is fine');
+});
+
+test('splitSegments separates a gh|jq pipe so the supported pattern is not flagged end-to-end', () => {
+  const cmd =
+    'state="$(gh api --paginate --slurp "repos/x/commits/y/status" | jq -r \'.a\' || echo none)"';
+  const segs = splitSegments(cmd);
+  const flagged = segs.flatMap((s) => lintSegment(s));
+  assert.equal(flagged.length, 0, 'gh segment has slurp-no-jq; jq segment is not gh');
+});
+
+test('lintFile flags the invalid combo across continuation lines', () => {
+  const src = [
+    'jobs:',
+    '  x:',
+    '    steps:',
+    '      - run: |',
+    '          state="$(gh api --slurp "u" \\',
+    "            --jq '.a' \\",
+    '            || echo none)"',
+  ].join('\n');
+  const findings = lintFile('.github/workflows/fake.yml', src);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].line, 5, 'points at the line the gh command starts on');
+  assert.match(findings[0].rule, /slurp-with-jq/);
+});
+
+test('lintFile ignores COMMENTS that merely document the invalid combo (false-positive guard)', () => {
+  // A step comment describing the rule — must NOT be flagged (regression: this
+  // exact false positive failed CI on the guard's own PR).
+  const src = [
+    '      # Catches gh flag combos like --slurp with --jq that fail at runtime.',
+    '      - name: Lint gh CLI flag combinations',
+    '        run: node scripts/check-workflow-gh-flags.mjs',
+  ].join('\n');
+  assert.deepEqual(lintFile('.github/workflows/ci.yml', src), []);
+});
+
+test('lintFile is clean for the corrected release-please pattern', () => {
+  const src = [
+    '      - run: |',
+    '          state="$(gh api --paginate --slurp "u" 2>/dev/null \\',
+    "            | jq -r '[.[].statuses[]] | first.state' \\",
+    '            || echo none)"',
+  ].join('\n');
+  assert.deepEqual(lintFile('.github/workflows/ok.yml', src), []);
+});