mandrel-platform 0.11.7 → 0.12.0

package/README.md

@@ -3,6 +3,10 @@
 Shared CI/deploy workflows, composite toolchain action, npm config package,
 Renovate preset, and operator runbook templates for the Mandrel platform.
 
+**Docs:** [reusable-workflows.md](docs/reusable-workflows.md) (the `workflow_call`
+contract) · [decisions.md](docs/decisions.md) (decision log). Status, the
+consumer convergence matrix, and the forward roadmap are tracked privately.
+
 ---
 
 ## Reusable workflows

package/package.json

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

package/scripts/check-pin-drift.mjs

@@ -8,7 +8,7 @@
  * athportal, swarm-os) went undetected and undocumented: every consumer
  * pinned `pr-quality.yml@<shaA>` and `deploy-cloudflare.yml@<shaB>` — two
  * different release SHAs per repo, neither on the current platform release,
- * with no automated drift detection (roadmap.md §4.2 / §4.3). This script is
+ * with no automated drift detection. This script is
  * the standing check that surfaces it automatically.
  *
  * For each consumer in `scripts/pin-drift-consumers.json` it:
@@ -24,6 +24,15 @@
  *      commit. A consumer is `current` when its single pin equals the latest
  *      release SHA, `lagging` when it pins an older release/SHA, and
  *      `unknown` when the pinned SHA can't be matched to a release.
+ *   5. Reads the consumer's `package.json` and extracts its
+ *      `mandrel-platform` npm dependency version (the platform also ships as
+ *      an npm config package: tsconfig.base.json, biome.base.json, the
+ *      Renovate preset). It compares that version to the latest release's
+ *      version and flags an `npm` verdict (`current` / `lagging` / `ahead` /
+ *      `absent` / `unknown`), plus a **surface skew** when the npm pin and the
+ *      workflow `uses:` pin disagree about being current — the exact
+ *      split-pin class the `uses:`-only check missed (npm lagged at 0.11.3
+ *      while the workflows tracked v0.11.6).
  *
  * Data-driven: a new consumer is one object in pin-drift-consumers.json.
  *
@@ -195,6 +204,135 @@ export function classifyConsumer(pins, latestReleaseSha) {
   };
 }
 
+/**
+ * Extract a comparable `x.y.z` semver core from a release tag or version spec.
+ * The platform tags releases as `mandrel-platform-v<semver>`; consumer specs
+ * may carry a range prefix (`^0.11.3`, `~0.11.3`). Returns the dotted triple
+ * or null when no numeric semver core is present (`workspace:*`, `latest`, a
+ * git URL).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function parseSemver(value) {
+  if (typeof value !== "string") return null;
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+  return m ? `${m[1]}.${m[2]}.${m[3]}` : null;
+}
+
+/**
+ * Compare two `x.y.z` semver cores. Returns -1 when a < b, 0 when equal, 1
+ * when a > b. Inputs MUST already be normalized dotted triples (see
+ * `parseSemver`).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Extract the consumer's `mandrel-platform` npm dependency spec from a
+ * package.json text blob. Scans `dependencies`, `devDependencies`,
+ * `optionalDependencies`, and `peerDependencies` in that order. Returns the
+ * raw spec string (e.g. `"0.11.3"`, `"^0.11.7"`, `"workspace:*"`) or null when
+ * the package isn't depended on (or the JSON is unreadable).
+ *
+ * @param {string} text       package.json contents.
+ * @param {string} [pkgName]  Dependency name to look for.
+ * @returns {string | null}
+ */
+export function extractNpmPlatformVersion(text, pkgName = "mandrel-platform") {
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!pkg || typeof pkg !== "object") return null;
+  const fields = [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+  ];
+  for (const field of fields) {
+    const deps = pkg[field];
+    if (deps && typeof deps === "object" && typeof deps[pkgName] === "string") {
+      return deps[pkgName];
+    }
+  }
+  return null;
+}
+
+/**
+ * Classify the consumer's npm pin against the latest platform release version.
+ *
+ * @param {string | null} spec           Raw `mandrel-platform` dependency spec, or null if absent.
+ * @param {string | null} latestVersion  Latest release version (`x.y.z`), or null if unknown.
+ * @returns {{
+ *   rawSpec: string | null,
+ *   version: string | null,
+ *   npmState: 'absent' | 'current' | 'lagging' | 'ahead' | 'unknown',
+ * }}
+ */
+export function classifyNpmPin(spec, latestVersion) {
+  if (spec === null || spec === undefined) {
+    return { rawSpec: null, version: null, npmState: "absent" };
+  }
+  const version = parseSemver(spec);
+  if (version === null) {
+    // Non-numeric spec (workspace:*, dist-tag, git URL) — can't compare by SHA.
+    return { rawSpec: spec, version: null, npmState: "unknown" };
+  }
+  const latest = parseSemver(latestVersion);
+  if (latest === null) {
+    return { rawSpec: spec, version, npmState: "unknown" };
+  }
+  const cmp = compareSemver(version, latest);
+  const npmState = cmp === 0 ? "current" : cmp < 0 ? "lagging" : "ahead";
+  return { rawSpec: spec, version, npmState };
+}
+
+/**
+ * Detect a surface skew: the npm pin and the workflow `uses:` pin disagree
+ * about being current. This is the split-pin class the `uses:`-only check
+ * missed — e.g. workflows on the latest release while the npm config package
+ * lags an older one (or vice versa). Only meaningful when BOTH surfaces
+ * resolve to a comparable currency state.
+ *
+ * @param {'current' | 'lagging' | 'unknown' | 'no-pins'} usesLagState
+ * @param {'absent' | 'current' | 'lagging' | 'ahead' | 'unknown'} npmState
+ * @returns {boolean}
+ */
+export function detectSurfaceSkew(usesLagState, npmState) {
+  const usesKnown = usesLagState === "current" || usesLagState === "lagging";
+  const npmKnown = npmState === "current" || npmState === "lagging";
+  if (!usesKnown || !npmKnown) return false;
+  return (usesLagState === "current") !== (npmState === "current");
+}
+
+/**
+ * Combine the workflow-pin verdict, the npm verdict, and the surface-skew flag
+ * into a single per-consumer drift boolean. `npm ahead` and `npm absent` are
+ * informational, not drift; `npm lagging` and any surface skew are.
+ *
+ * @param {{ drift: boolean }} verdict
+ * @param {{ npmState: string }} npm
+ * @param {boolean} surfaceSkew
+ * @returns {boolean}
+ */
+export function combineDrift(verdict, npm, surfaceSkew) {
+  return verdict.drift || npm.npmState === "lagging" || surfaceSkew;
+}
+
 /**
  * Render the human-readable dashboard report.
  *
@@ -208,12 +346,16 @@ export function classifyConsumer(pins, latestReleaseSha) {
  *     error?: string,
  *     pins: Array<{ file: string, line: number, target: string, ref: string | null }>,
  *     verdict: ReturnType<typeof classifyConsumer>,
+ *     npm?: ReturnType<typeof classifyNpmPin>,
+ *     surfaceSkew?: boolean,
+ *     drift?: boolean,
  *   }>,
  * }} report
  * @returns {string}
  */
 export function renderReport(report) {
   const { platformRepo, latestRelease, results } = report;
+  const latestVersion = parseSemver(latestRelease.tag);
   const out = [];
   out.push("## Cross-consumer pin-drift dashboard");
   out.push("");
@@ -224,17 +366,19 @@ export function renderReport(report) {
       : "unknown";
   out.push(`Latest release: ${relLabel}`);
   out.push("");
-  out.push("| Consumer | Pins | Pinned SHA | Lag | Status |");
-  out.push("| -------- | ---- | ---------- | --- | ------ |");
+  out.push("| Consumer | Pins | uses SHA | uses lag | npm pin | npm lag | Status |");
+  out.push("| -------- | ---- | -------- | -------- | ------- | ------- | ------ |");
 
   const driftLines = [];
   for (const r of results) {
     if (r.error) {
-      out.push(`| \`${r.name}\` | — | — | — | ⚠️ error |`);
+      out.push(`| \`${r.name}\` | — | — | — | — | — | ⚠️ error |`);
       driftLines.push(`- \`${r.name}\` (${r.repo}): error — ${r.error}`);
       continue;
     }
     const v = r.verdict;
+    const npm = r.npm ?? { rawSpec: null, version: null, npmState: "absent" };
+    const surfaceSkew = r.surfaceSkew === true;
     const shaLabel = v.pinnedSha
       ? `\`${v.pinnedSha.slice(0, 7)}\``
       : v.splitPinned
@@ -250,14 +394,27 @@ export function renderReport(report) {
           : v.lagState === "no-pins"
             ? "no pins"
             : "unknown";
+    const npmLabel = npm.version
+      ? `\`${npm.version}\``
+      : npm.rawSpec
+        ? `\`${npm.rawSpec}\``
+        : "—";
+    const npmLagLabel = npm.npmState === "absent" ? "—" : npm.npmState;
     let status;
-    if (v.lagState === "no-pins") status = "➖ no platform pins";
+    if (v.lagState === "no-pins" && npm.npmState === "absent")
+      status = "➖ no platform refs";
     else if (v.splitPinned) status = "❌ split pin";
-    else if (v.lagState === "lagging") status = "⚠️ lagging";
-    else if (v.lagState === "current") status = "✅ current";
+    else if (surfaceSkew) status = "❌ npm/uses skew";
+    else if (v.lagState === "lagging" || npm.npmState === "lagging")
+      status = "⚠️ lagging";
+    else if (
+      (v.lagState === "current" || v.lagState === "no-pins") &&
+      (npm.npmState === "current" || npm.npmState === "absent")
+    )
+      status = "✅ current";
     else status = "❔ unknown";
     out.push(
-      `| \`${r.name}\` | ${v.pinCount} | ${shaLabel} | ${lagLabel} | ${status} |`,
+      `| \`${r.name}\` | ${v.pinCount} | ${shaLabel} | ${lagLabel} | ${npmLabel} | ${npmLagLabel} | ${status} |`,
     );
 
     if (v.splitPinned) {
@@ -279,6 +436,16 @@ export function renderReport(report) {
         `- \`${r.name}\` (${r.repo}): LAGGING — pins \`${v.pinnedSha.slice(0, 7)}\`, latest release is \`${(latestRelease.sha || "?").slice(0, 7)}\` (${latestRelease.tag || "?"}).`,
       );
     }
+
+    if (surfaceSkew) {
+      driftLines.push(
+        `- \`${r.name}\` (${r.repo}): SURFACE SKEW — workflow \`uses:\` pins are ${lagLabel} but the npm \`mandrel-platform\` dependency (\`${npm.version ?? npm.rawSpec}\`) is ${npm.npmState}. The npm config package and the workflow pins are on different releases.`,
+      );
+    } else if (npm.npmState === "lagging") {
+      driftLines.push(
+        `- \`${r.name}\` (${r.repo}): NPM LAGGING — depends on \`mandrel-platform@${npm.version}\`, latest release is \`${latestVersion ?? "?"}\` (${latestRelease.tag || "?"}).`,
+      );
+    }
   }
 
   out.push("");
@@ -290,7 +457,7 @@ export function renderReport(report) {
     out.push("### ✅ No drift");
     out.push("");
     out.push(
-      "Every consumer pins a single platform SHA on the latest release.",
+      "Every consumer pins a single platform SHA on the latest release, and its npm `mandrel-platform` dependency is on the matching version.",
     );
   }
   out.push("");
@@ -405,6 +572,34 @@ export function fetchConsumerWorkflows(repo, branch, runGh) {
   return files;
 }
 
+/**
+ * Fetch a consumer's root `package.json` text over the GitHub contents API.
+ * Returns null when the file is absent or unreadable (a consumer that adopts
+ * the platform workflows but not the npm config package legitimately has no
+ * `mandrel-platform` dependency). The existing `Contents: read` token scope
+ * already covers this — no additional permission is required.
+ *
+ * @param {string} repo    "owner/name".
+ * @param {string} branch  Branch / ref to read.
+ * @param {(args: string[]) => string} runGh
+ * @returns {string | null}
+ */
+export function fetchConsumerPackageJson(repo, branch, runGh) {
+  let obj;
+  try {
+    obj = ghApiJson(
+      `repos/${repo}/contents/package.json?ref=${encodeURIComponent(branch)}`,
+      runGh,
+    );
+  } catch {
+    return null;
+  }
+  if (obj && obj.encoding === "base64" && typeof obj.content === "string") {
+    return Buffer.from(obj.content, "base64").toString("utf-8");
+  }
+  return null;
+}
+
 /**
  * Resolve a consumer's effective branch: the entry's `branch` if set, else the
  * repo's default branch.
@@ -436,7 +631,9 @@ export function resolveBranch(consumer, runGh) {
  */
 export function buildReport(config, runGh) {
   const platformRepo = config.platformRepo;
+  const platformPkg = config.platformPackage || "mandrel-platform";
   const latestRelease = resolveLatestRelease(platformRepo, runGh);
+  const latestVersion = parseSemver(latestRelease.tag);
   const results = [];
   for (const consumer of config.consumers) {
     try {
@@ -447,19 +644,38 @@ export function buildReport(config, runGh) {
         pins.push(...extractPlatformPins(f.path, f.text, platformRepo));
       }
       const verdict = classifyConsumer(pins, latestRelease.sha);
-      results.push({ name: consumer.name, repo: consumer.repo, branch, pins, verdict });
+      const pkgText = fetchConsumerPackageJson(consumer.repo, branch, runGh);
+      const npmSpec =
+        pkgText === null ? null : extractNpmPlatformVersion(pkgText, platformPkg);
+      const npm = classifyNpmPin(npmSpec, latestVersion);
+      const surfaceSkew = detectSurfaceSkew(verdict.lagState, npm.npmState);
+      results.push({
+        name: consumer.name,
+        repo: consumer.repo,
+        branch,
+        pins,
+        verdict,
+        npm,
+        surfaceSkew,
+        drift: combineDrift(verdict, npm, surfaceSkew),
+      });
     } catch (err) {
+      const verdict = classifyConsumer([], latestRelease.sha);
+      const npm = classifyNpmPin(null, latestVersion);
       results.push({
         name: consumer.name,
         repo: consumer.repo,
         branch: consumer.branch || "?",
         error: err instanceof Error ? err.message : String(err),
         pins: [],
-        verdict: classifyConsumer([], latestRelease.sha),
+        verdict,
+        npm,
+        surfaceSkew: false,
+        drift: false,
       });
     }
   }
-  return { platformRepo, latestRelease, results };
+  return { platformRepo, latestRelease, latestVersion, results };
 }
 
 /**
@@ -467,7 +683,7 @@ export function buildReport(config, runGh) {
  * @returns {boolean} true when any consumer has drift or an error.
  */
 export function hasDrift(report) {
-  return report.results.some((r) => r.error || r.verdict.drift);
+  return report.results.some((r) => r.error || r.drift);
 }
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+/**
+ * check-pin-drift.test.mjs — node:test suite for the cross-consumer pin-drift
+ * dashboard (Story #67, MP-12) and the npm-dimension extension that closes the
+ * gap where a consumer's `mandrel-platform` npm dependency could lag the
+ * workflow `uses:` pins undetected (npm at 0.11.3 while the workflows tracked
+ * v0.11.6).
+ *
+ * The checker exposes pure helpers plus an injectable `runGh` seam, so the
+ * whole pipeline is exercised offline with canned GitHub responses — no
+ * network, no `gh` auth.
+ *
+ * Run: node scripts/check-pin-drift.test.mjs   (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import {
+  buildReport,
+  classifyNpmPin,
+  combineDrift,
+  compareSemver,
+  detectSurfaceSkew,
+  extractNpmPlatformVersion,
+  fetchConsumerPackageJson,
+  hasDrift,
+  parseSemver,
+  renderReport,
+  runCli,
+} from "./check-pin-drift.mjs";
+
+// ---------------------------------------------------------------------------
+// parseSemver
+// ---------------------------------------------------------------------------
+
+test("parseSemver extracts the dotted triple from a release tag", () => {
+  assert.equal(parseSemver("mandrel-platform-v0.11.7"), "0.11.7");
+  assert.equal(parseSemver("v1.4.0"), "1.4.0");
+});
+
+test("parseSemver strips range prefixes from a dependency spec", () => {
+  assert.equal(parseSemver("^0.11.7"), "0.11.7");
+  assert.equal(parseSemver("~1.2.3"), "1.2.3");
+  assert.equal(parseSemver(">=2.0.0"), "2.0.0");
+  assert.equal(parseSemver("0.11.3"), "0.11.3");
+});
+
+test("parseSemver returns null for non-numeric specs and non-strings", () => {
+  assert.equal(parseSemver("workspace:*"), null);
+  assert.equal(parseSemver("latest"), null);
+  assert.equal(parseSemver("github:owner/repo"), null);
+  assert.equal(parseSemver(null), null);
+  assert.equal(parseSemver(undefined), null);
+});
+
+// ---------------------------------------------------------------------------
+// compareSemver — numeric, not lexical
+// ---------------------------------------------------------------------------
+
+test("compareSemver orders versions numerically", () => {
+  assert.equal(compareSemver("0.11.3", "0.11.7"), -1);
+  assert.equal(compareSemver("1.4.0", "1.4.0"), 0);
+  assert.equal(compareSemver("2.0.0", "1.9.9"), 1);
+});
+
+test("compareSemver compares each segment as a number, not a string", () => {
+  // Lexical comparison would put "0.2.0" after "0.10.0"; numeric must not.
+  assert.equal(compareSemver("0.2.0", "0.10.0"), -1);
+  assert.equal(compareSemver("0.11.10", "0.11.9"), 1);
+});
+
+// ---------------------------------------------------------------------------
+// extractNpmPlatformVersion
+// ---------------------------------------------------------------------------
+
+test("extractNpmPlatformVersion reads the dep from devDependencies", () => {
+  const text = JSON.stringify({ devDependencies: { "mandrel-platform": "0.11.3" } });
+  assert.equal(extractNpmPlatformVersion(text), "0.11.3");
+});
+
+test("extractNpmPlatformVersion prefers dependencies over devDependencies", () => {
+  const text = JSON.stringify({
+    dependencies: { "mandrel-platform": "1.0.0" },
+    devDependencies: { "mandrel-platform": "2.0.0" },
+  });
+  assert.equal(extractNpmPlatformVersion(text), "1.0.0");
+});
+
+test("extractNpmPlatformVersion falls back to optional/peer deps", () => {
+  const peer = JSON.stringify({ peerDependencies: { "mandrel-platform": "3.1.4" } });
+  assert.equal(extractNpmPlatformVersion(peer), "3.1.4");
+  const opt = JSON.stringify({ optionalDependencies: { "mandrel-platform": "5.0.0" } });
+  assert.equal(extractNpmPlatformVersion(opt), "5.0.0");
+});
+
+test("extractNpmPlatformVersion honors a custom package name", () => {
+  const text = JSON.stringify({ devDependencies: { "@scope/other": "9.9.9" } });
+  assert.equal(extractNpmPlatformVersion(text, "@scope/other"), "9.9.9");
+});
+
+test("extractNpmPlatformVersion returns null when absent or malformed", () => {
+  assert.equal(extractNpmPlatformVersion(JSON.stringify({ devDependencies: {} })), null);
+  assert.equal(extractNpmPlatformVersion("{ not json"), null);
+  assert.equal(extractNpmPlatformVersion("null"), null);
+});
+
+// ---------------------------------------------------------------------------
+// classifyNpmPin
+// ---------------------------------------------------------------------------
+
+test("classifyNpmPin classifies current / lagging / ahead", () => {
+  assert.deepEqual(classifyNpmPin("0.11.7", "0.11.7"), {
+    rawSpec: "0.11.7",
+    version: "0.11.7",
+    npmState: "current",
+  });
+  assert.equal(classifyNpmPin("0.11.3", "0.11.7").npmState, "lagging");
+  assert.equal(classifyNpmPin("1.0.0", "0.11.7").npmState, "ahead");
+});
+
+test("classifyNpmPin marks an absent dependency", () => {
+  assert.deepEqual(classifyNpmPin(null, "0.11.7"), {
+    rawSpec: null,
+    version: null,
+    npmState: "absent",
+  });
+});
+
+test("classifyNpmPin is unknown for non-numeric specs or unknown latest", () => {
+  assert.equal(classifyNpmPin("workspace:*", "0.11.7").npmState, "unknown");
+  assert.equal(classifyNpmPin("0.11.7", null).npmState, "unknown");
+});
+
+// ---------------------------------------------------------------------------
+// detectSurfaceSkew — the incident this guard exists for
+// ---------------------------------------------------------------------------
+
+test("detectSurfaceSkew flags uses-current but npm-lagging (and the reverse)", () => {
+  assert.equal(detectSurfaceSkew("current", "lagging"), true);
+  assert.equal(detectSurfaceSkew("lagging", "current"), true);
+});
+
+test("detectSurfaceSkew is false when both surfaces agree", () => {
+  assert.equal(detectSurfaceSkew("current", "current"), false);
+  assert.equal(detectSurfaceSkew("lagging", "lagging"), false);
+});
+
+test("detectSurfaceSkew is false when either surface is not comparable", () => {
+  assert.equal(detectSurfaceSkew("current", "absent"), false);
+  assert.equal(detectSurfaceSkew("current", "unknown"), false);
+  assert.equal(detectSurfaceSkew("unknown", "lagging"), false);
+  assert.equal(detectSurfaceSkew("no-pins", "lagging"), false);
+});
+
+// ---------------------------------------------------------------------------
+// combineDrift
+// ---------------------------------------------------------------------------
+
+test("combineDrift folds uses-drift, npm-lag, and surface-skew", () => {
+  const clean = { drift: false };
+  assert.equal(combineDrift(clean, { npmState: "current" }, false), false);
+  assert.equal(combineDrift(clean, { npmState: "absent" }, false), false);
+  assert.equal(combineDrift(clean, { npmState: "ahead" }, false), false);
+  assert.equal(combineDrift(clean, { npmState: "lagging" }, false), true);
+  assert.equal(combineDrift(clean, { npmState: "current" }, true), true);
+  assert.equal(combineDrift({ drift: true }, { npmState: "current" }, false), true);
+});
+
+// ---------------------------------------------------------------------------
+// Integration: buildReport + renderReport with an injected gh runner
+// ---------------------------------------------------------------------------
+
+const PLATFORM = "dsj1984/mandrel-platform";
+const TAG = "mandrel-platform-v1.4.0";
+const LATEST_SHA = "a".repeat(40);
+const OLD_SHA = "b".repeat(40);
+
+function b64(value) {
+  const s = typeof value === "string" ? value : JSON.stringify(value);
+  return Buffer.from(s, "utf-8").toString("base64");
+}
+
+function usesYaml(sha) {
+  return ["jobs:", "  q:", `    uses: ${PLATFORM}/.github/workflows/pr-quality.yml@${sha}`].join(
+    "\n",
+  );
+}
+
+function pkgJson(version) {
+  const devDependencies = version ? { "mandrel-platform": version } : {};
+  return { name: "consumer", devDependencies };
+}
+
+/**
+ * Build an injectable gh runner from a per-repo fixture map:
+ *   { "owner/repo": { workflowSha, npm: string | null | "throw" } }
+ */
+function makeRunGh(fixtures) {
+  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" } });
+    }
+    for (const [repo, cfg] of Object.entries(fixtures)) {
+      if (path === `repos/${repo}/contents/.github/workflows?ref=main`) {
+        return JSON.stringify([
+          { type: "file", name: "ci.yml", encoding: "base64", content: b64(usesYaml(cfg.workflowSha)) },
+        ]);
+      }
+      if (path === `repos/${repo}/contents/package.json?ref=main`) {
+        if (cfg.npm === "throw") throw new Error("404 Not Found");
+        return JSON.stringify({ encoding: "base64", content: b64(pkgJson(cfg.npm)) });
+      }
+    }
+    throw new Error(`unexpected gh api path: ${path}`);
+  };
+}
+
+const CONFIG = {
+  platformRepo: PLATFORM,
+  consumers: [
+    { name: "aligned", repo: "o/aligned", branch: "main" },
+    { name: "skew", repo: "o/skew", branch: "main" },
+    { name: "both-lag", repo: "o/both-lag", branch: "main" },
+    { name: "no-npm", repo: "o/no-npm", branch: "main" },
+  ],
+};
+
+const FIXTURES = {
+  "o/aligned": { workflowSha: LATEST_SHA, npm: "1.4.0" },
+  "o/skew": { workflowSha: LATEST_SHA, npm: "1.3.0" },
+  "o/both-lag": { workflowSha: OLD_SHA, npm: "1.3.0" },
+  "o/no-npm": { workflowSha: LATEST_SHA, npm: null },
+};
+
+function byName(report, name) {
+  return report.results.find((r) => r.name === name);
+}
+
+test("buildReport: aligned consumer is current with no drift", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  assert.equal(report.latestVersion, "1.4.0");
+  const r = byName(report, "aligned");
+  assert.equal(r.verdict.lagState, "current");
+  assert.equal(r.npm.npmState, "current");
+  assert.equal(r.surfaceSkew, false);
+  assert.equal(r.drift, false);
+});
+
+test("buildReport: npm lagging while workflows current is a surface skew", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  const r = byName(report, "skew");
+  assert.equal(r.verdict.lagState, "current");
+  assert.equal(r.npm.npmState, "lagging");
+  assert.equal(r.surfaceSkew, true);
+  assert.equal(r.drift, true);
+});
+
+test("buildReport: both surfaces lagging is drift but not a skew", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  const r = byName(report, "both-lag");
+  assert.equal(r.verdict.lagState, "lagging");
+  assert.equal(r.npm.npmState, "lagging");
+  assert.equal(r.surfaceSkew, false);
+  assert.equal(r.drift, true);
+});
+
+test("buildReport: a consumer without the npm dep is current, not drift", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  const r = byName(report, "no-npm");
+  assert.equal(r.npm.npmState, "absent");
+  assert.equal(r.surfaceSkew, false);
+  assert.equal(r.drift, false);
+});
+
+test("buildReport: an unreadable package.json is treated as absent, not an error", () => {
+  const report = buildReport(
+    { platformRepo: PLATFORM, consumers: [{ name: "c", repo: "o/c", branch: "main" }] },
+    makeRunGh({ "o/c": { workflowSha: LATEST_SHA, npm: "throw" } }),
+  );
+  const r = byName(report, "c");
+  assert.equal(r.error, undefined);
+  assert.equal(r.npm.npmState, "absent");
+  assert.equal(r.drift, false);
+});
+
+test("hasDrift is true when any consumer drifts", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  assert.equal(hasDrift(report), true);
+});
+
+test("renderReport surfaces the npm columns and drift lines", () => {
+  const report = buildReport(CONFIG, makeRunGh(FIXTURES));
+  const text = renderReport(report);
+  assert.match(text, /npm pin/);
+  assert.match(text, /npm lag/);
+  assert.match(text, /SURFACE SKEW/);
+  assert.match(text, /npm\/uses skew/);
+  // The aligned consumer renders its npm version in the table.
+  assert.match(text, /`1\.4\.0`/);
+});
+
+test("fetchConsumerPackageJson returns null when the file is missing", () => {
+  const runGh = () => {
+    throw new Error("404");
+  };
+  assert.equal(fetchConsumerPackageJson("o/x", "main", runGh), null);
+});
+
+// ---------------------------------------------------------------------------
+// CLI: --json, --strict, exit codes
+// ---------------------------------------------------------------------------
+
+let cfgDir;
+function writeConfig() {
+  cfgDir = mkdtempSync(join(tmpdir(), "pin-drift-test-"));
+  const p = join(cfgDir, "consumers.json");
+  writeFileSync(p, JSON.stringify(CONFIG));
+  return p;
+}
+
+function capture() {
+  const chunks = [];
+  return { write: (s) => chunks.push(s), text: () => chunks.join("") };
+}
+
+test("runCli --json emits a machine-readable envelope and exits 0 without --strict", () => {
+  const configPath = writeConfig();
+  const stdout = capture();
+  const stderr = capture();
+  try {
+    const code = runCli({
+      argv: ["--config", configPath, "--json"],
+      runGh: makeRunGh(FIXTURES),
+      stdout,
+      stderr,
+      summaryPath: undefined,
+    });
+    assert.equal(code, 0);
+    const envelope = JSON.parse(stdout.text());
+    assert.equal(envelope.kind, "pin-drift-report");
+    assert.equal(envelope.drift, true);
+    assert.equal(envelope.results.length, 4);
+  } finally {
+    rmSync(cfgDir, { recursive: true, force: true });
+  }
+});
+
+test("runCli --strict exits 1 when drift is present", () => {
+  const configPath = writeConfig();
+  try {
+    const code = runCli({
+      argv: ["--config", configPath, "--strict"],
+      runGh: makeRunGh(FIXTURES),
+      stdout: capture(),
+      stderr: capture(),
+      summaryPath: undefined,
+    });
+    assert.equal(code, 1);
+  } finally {
+    rmSync(cfgDir, { recursive: true, force: true });
+  }
+});

package/scripts/pin-drift-consumers.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Data-driven consumer registry for scripts/check-pin-drift.mjs (Story #67, MP-12). Each entry is one downstream repo that pins mandrel-platform reusable workflows / composite actions via `uses: dsj1984/mandrel-platform/...@<sha>`. Adding a new consumer is a single object here — the drift checker enumerates `.github/workflows/*` in each repo over the GitHub API, extracts every mandrel-platform pin, and asserts a single SHA per consumer plus lag vs the latest mandrel-platform release. `branch` is optional (defaults to the repo's default branch).",
+  "$comment": "Data-driven consumer registry for scripts/check-pin-drift.mjs (Story #67, MP-12). Each entry is one downstream repo that pins mandrel-platform reusable workflows / composite actions via `uses: dsj1984/mandrel-platform/...@<sha>`. Adding a new consumer is a single object here — the drift checker enumerates `.github/workflows/*` and reads `package.json` in each repo over the GitHub API, extracts every mandrel-platform `uses:` pin plus the `mandrel-platform` npm dependency version, and asserts a single SHA per consumer plus lag (and surface skew between the workflow and npm surfaces) vs the latest mandrel-platform release. `branch` is optional (defaults to the repo's default branch).",
   "platformRepo": "dsj1984/mandrel-platform",
   "consumers": [
     {