mandrel-platform 0.18.0 → 0.19.1

package/scripts/lib/uses-pins.test.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * uses-pins.test.mjs — node:test suite for the shared `uses:`-line / SHA-pin
+ * primitives (`scripts/lib/uses-pins.mjs`, Story #203).
+ *
+ * Covers value stripping, line parsing, reference classification (incl. the
+ * new `subpath` field), the 40-char-SHA predicate, and the intra-repo
+ * single-pin invariant that `check-action-pins.mjs` now enforces. Pure — no
+ * temp dirs, no git, fully offline.
+ *
+ * Run: node --test scripts/lib/uses-pins.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import {
+  DEFAULT_FIRST_PARTY_OWNER,
+  stripUsesValue,
+  parseUsesLine,
+  classifyUses,
+  isSha40,
+  collectFirstPartyPins,
+  findSinglePinViolations,
+} from "./uses-pins.mjs";
+
+const SHA = "11bd71901bbe5b1630ceea73d27597364c9af683"; // 40 hex
+const SHA2 = "0000000000000000000000000000000000000000"; // 40 hex, distinct
+const SHORT = "11bd719"; // 7 hex
+
+// ---------------------------------------------------------------------------
+// isSha40
+// ---------------------------------------------------------------------------
+
+test("isSha40 accepts exactly 40 hex chars (any case)", () => {
+  assert.equal(isSha40(SHA), true);
+  assert.equal(isSha40(SHA.toUpperCase()), true);
+});
+
+test("isSha40 rejects tags, short SHAs, branches, and off-by-one", () => {
+  assert.equal(isSha40("v4"), false);
+  assert.equal(isSha40(SHORT), false);
+  assert.equal(isSha40("main"), false);
+  assert.equal(isSha40(SHA + "0"), false); // 41 chars
+  assert.equal(isSha40("g".repeat(40)), false); // non-hex
+});
+
+// ---------------------------------------------------------------------------
+// stripUsesValue
+// ---------------------------------------------------------------------------
+
+test("stripUsesValue drops the trailing # tag comment", () => {
+  assert.equal(
+    stripUsesValue(`actions/checkout@${SHA} # v4.2.2`),
+    `actions/checkout@${SHA}`
+  );
+});
+
+test("stripUsesValue unwraps surrounding quotes and no-comment inputs", () => {
+  assert.equal(stripUsesValue(`actions/checkout@${SHA}`), `actions/checkout@${SHA}`);
+  assert.equal(stripUsesValue(`"actions/checkout@${SHA}"`), `actions/checkout@${SHA}`);
+  assert.equal(stripUsesValue(`'actions/checkout@${SHA}'`), `actions/checkout@${SHA}`);
+});
+
+// ---------------------------------------------------------------------------
+// parseUsesLine
+// ---------------------------------------------------------------------------
+
+test("parseUsesLine returns the bare ref for a mapping-key uses line", () => {
+  assert.equal(parseUsesLine(`      - uses: actions/checkout@${SHA} # v4`), `actions/checkout@${SHA}`);
+  assert.equal(parseUsesLine(`  uses: actions/checkout@${SHA}`), `actions/checkout@${SHA}`);
+});
+
+test("parseUsesLine returns null for comments and non-uses lines", () => {
+  assert.equal(parseUsesLine("# uses: actions/checkout@v4"), null);
+  assert.equal(parseUsesLine("    steps:"), null);
+  assert.equal(parseUsesLine("      run: echo uses: not-a-key"), null);
+});
+
+// ---------------------------------------------------------------------------
+// classifyUses (incl. subpath)
+// ---------------------------------------------------------------------------
+
+test("classifyUses flags external owner/repo as third-party with subpath", () => {
+  const c = classifyUses(`github/codeql-action/analyze@${SHA}`);
+  assert.equal(c.kind, "third-party");
+  assert.equal(c.owner, "github/codeql-action");
+  assert.equal(c.subpath, "analyze");
+  assert.equal(c.ref, SHA);
+});
+
+test("classifyUses treats the default first-party owner as exempt and exposes subpath", () => {
+  const c = classifyUses(
+    `dsj1984/mandrel-platform/.github/actions/setup-toolchain@${SHA}`
+  );
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.owner, DEFAULT_FIRST_PARTY_OWNER);
+  assert.equal(c.subpath, ".github/actions/setup-toolchain");
+  assert.equal(c.ref, SHA);
+});
+
+test("classifyUses honours a custom first-party owner", () => {
+  const c = classifyUses(`my-org/my-repo/.github/workflows/x.yml@v1`, "my-org/my-repo");
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.subpath, ".github/workflows/x.yml");
+});
+
+test("classifyUses exempts local and docker refs", () => {
+  assert.equal(classifyUses("./.github/actions/foo").kind, "local");
+  assert.equal(classifyUses("../shared/action").kind, "local");
+  assert.equal(classifyUses("docker://alpine:3.19").kind, "docker");
+});
+
+test("classifyUses reports empty subpath for a bare owner/repo self-ref", () => {
+  const c = classifyUses(`dsj1984/mandrel-platform@${SHA}`);
+  assert.equal(c.kind, "first-party");
+  assert.equal(c.subpath, "");
+});
+
+test("classifyUses returns unparseable for a ref with no @ or too few segments", () => {
+  assert.equal(classifyUses("").kind, "unparseable");
+  assert.equal(classifyUses("actions/checkout").kind, "unparseable");
+  assert.equal(classifyUses(`justowner@${SHA}`).kind, "unparseable");
+});
+
+// ---------------------------------------------------------------------------
+// collectFirstPartyPins
+// ---------------------------------------------------------------------------
+
+test("collectFirstPartyPins keys first-party subpath refs by target", () => {
+  const content = [
+    "    steps:",
+    `      - uses: dsj1984/mandrel-platform/.github/actions/setup-toolchain@${SHA}`,
+    `      - uses: actions/checkout@${SHA}`, // third-party → ignored
+    `      - uses: dsj1984/mandrel-platform@${SHA}`, // bare self-ref, no subpath → ignored
+  ].join("\n");
+  const byTarget = collectFirstPartyPins(content, "wf.yml");
+  assert.equal(byTarget.size, 1);
+  const occs = byTarget.get("dsj1984/mandrel-platform/.github/actions/setup-toolchain");
+  assert.equal(occs.length, 1);
+  assert.equal(occs[0].ref, SHA);
+  assert.equal(occs[0].line, 2);
+  assert.equal(occs[0].file, "wf.yml");
+});
+
+// ---------------------------------------------------------------------------
+// findSinglePinViolations (the single-pin invariant)
+// ---------------------------------------------------------------------------
+
+test("findSinglePinViolations is clean when a target is pinned consistently", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+    {
+      file: "b.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+  ];
+  assert.deepEqual(findSinglePinViolations(files), []);
+});
+
+test("findSinglePinViolations flags a target pinned to two different SHAs", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+    },
+    {
+      file: "b.yml",
+      content: `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA2}`,
+    },
+  ];
+  const v = findSinglePinViolations(files);
+  assert.equal(v.length, 1);
+  assert.equal(v[0].target, "dsj1984/mandrel-platform/.github/actions/foo");
+  assert.equal(v[0].shas.length, 2);
+  assert.ok(v[0].shas.includes(SHA));
+  assert.ok(v[0].shas.includes(SHA2));
+  assert.equal(v[0].occurrences.length, 2);
+  assert.deepEqual(
+    v[0].occurrences.map((o) => o.file).sort(),
+    ["a.yml", "b.yml"]
+  );
+});
+
+test("findSinglePinViolations catches drift within a single file too", () => {
+  const files = [
+    {
+      file: "a.yml",
+      content: [
+        `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA}`,
+        `      - uses: dsj1984/mandrel-platform/.github/actions/foo@${SHA2}`,
+      ].join("\n"),
+    },
+  ];
+  const v = findSinglePinViolations(files);
+  assert.equal(v.length, 1);
+  assert.equal(v[0].shas.length, 2);
+});
+
+test("findSinglePinViolations ignores third-party targets (cross-repo dashboard owns those)", () => {
+  const files = [
+    { file: "a.yml", content: `      - uses: github/codeql-action/analyze@${SHA}` },
+    { file: "b.yml", content: `      - uses: github/codeql-action/analyze@${SHA2}` },
+  ];
+  assert.deepEqual(findSinglePinViolations(files), []);
+});
+
+test("findSinglePinViolations honours a custom first-party owner", () => {
+  const files = [
+    { file: "a.yml", content: `      - uses: my-org/my-repo/actions/x@${SHA}` },
+    { file: "b.yml", content: `      - uses: my-org/my-repo/actions/x@${SHA2}` },
+  ];
+  const v = findSinglePinViolations(files, "my-org/my-repo");
+  assert.equal(v.length, 1);
+  assert.equal(v[0].target, "my-org/my-repo/actions/x");
+});

package/scripts/lib/walk.mjs

@@ -0,0 +1,74 @@
+/**
+ * scripts/lib/walk.mjs
+ *
+ * The single directory-discovery seam for the pin-tooling scripts. Both
+ * `check-action-pins.mjs` and `check-workflow-portability.mjs` had grown their
+ * own `listWorkflowFiles` / `listActionFiles` pair — same intent, subtly
+ * different code (one sorted, one didn't; one guarded `statSync`, one didn't).
+ * Story #203 consolidates them here.
+ *
+ * All discovery is best-effort: a missing directory or an unreadable entry
+ * yields `[]` / is skipped rather than throwing, so a repo without a
+ * `.github/actions/` tree lints cleanly. Results are sorted for deterministic
+ * output.
+ */
+
+import { readdirSync, statSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * List `*.yml` / `*.yaml` files directly under a workflows dir
+ * (non-recursive — GitHub only runs top-level workflow files).
+ *
+ * @param {string} dir
+ * @returns {string[]} Sorted absolute/relative paths (as joined from `dir`).
+ */
+export function listWorkflowFiles(dir) {
+  if (!existsSync(dir)) return [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((f) => /\.ya?ml$/.test(f))
+    .map((f) => join(dir, f))
+    .filter((p) => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+}
+
+/**
+ * Recursively list composite `action.yml` / `action.yaml` files under a dir.
+ *
+ * @param {string} dir
+ * @returns {string[]} Sorted paths.
+ */
+export function listActionFiles(dir) {
+  const out = [];
+  if (!existsSync(dir)) return out;
+  const walk = (d) => {
+    let entries;
+    try {
+      entries = readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) {
+        walk(full);
+      } else if (/^action\.ya?ml$/.test(e.name)) {
+        out.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return out.sort();
+}

package/scripts/platform-repair.mjs

@@ -68,7 +68,9 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { buildReport, defaultGhRunner, isFullSha } from "./check-pin-drift.mjs";
+import { buildReport, isFullSha } from "./check-pin-drift.mjs";
+import { defaultGhRunner } from "./lib/gh-json.mjs";
+import { parseSemver } from "./lib/semver-duration.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -188,12 +190,16 @@ export function describeDrift(result) {
     const short = v.pinnedSha ? v.pinnedSha.slice(0, 7) : "?";
     out.push(`**Release lag** — workflow \`uses:\` pins \`${short}\`, behind the latest release.`);
   }
+  // Normalize the npm version through the shared parser (Story #198): the
+  // detector already emits a dotted triple, but re-parsing keeps the repair
+  // PR body robust to a raw spec ever reaching here (`^0.11.7` → `0.11.7`).
+  const npmVersion = parseSemver(result.npm?.version ?? null) ?? result.npm?.version ?? "?";
   if (result.surfaceSkew === true) {
     out.push(
-      `**Surface skew** — the npm \`mandrel-platform\` dependency (\`${result.npm?.version ?? "?"}\`) and the workflow \`uses:\` pins are on different releases.`,
+      `**Surface skew** — the npm \`mandrel-platform\` dependency (\`${npmVersion}\`) and the workflow \`uses:\` pins are on different releases.`,
     );
   } else if (result.npm?.npmState === "lagging") {
-    out.push(`**npm lag** — \`mandrel-platform@${result.npm.version}\` is behind the latest release.`);
+    out.push(`**npm lag** — \`mandrel-platform@${npmVersion}\` is behind the latest release.`);
   }
   return out;
 }

package/scripts/update-semgrep-rules.mjs

@@ -50,16 +50,18 @@
  *   node scripts/update-semgrep-rules.mjs --semgrep-pin semgrep==1.97.0
  *   node scripts/update-semgrep-rules.mjs --out .semgrep/rules.json --dry-run
  *
- * Requires network egress to PyPI (to install the pinned `semgrep` package)
- * and to the Semgrep registry (to resolve `p/default`) — this script is run
- * by a human/agent deliberately bumping the ruleset, NOT by CI on every PR.
+ * Requires network egress to PyPI (to install the pinned `semgrep` package,
+ * whose artifact is verified against the recorded SHA-256 hashes via pip's
+ * `--require-hashes`) and to the Semgrep registry (to resolve `p/default`) —
+ * this script is run by a human/agent deliberately bumping the ruleset, NOT
+ * by CI on every PR.
  *
  * Exit codes:
  *   0 — rules file written (or, with --dry-run, would-write reported).
  *   1 — semgrep install or rule resolution failed.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -75,6 +77,26 @@ const REPO_ROOT = resolve(__dirname, "..");
 // generate the file is a (harmless but inconsistent) version skew.
 const DEFAULT_SEMGREP_PIN = "semgrep==1.97.0";
 
+// SHA-256 hashes for every `DEFAULT_SEMGREP_PIN` distribution published on
+// PyPI (the four platform wheels + the sdist). pip's `--require-hashes` mode
+// verifies the downloaded `semgrep` artifact against this set before it is
+// installed, so a compromised or swapped PyPI artifact for this exact version
+// is rejected at install time — the same "pin the supply-chain input" posture
+// the action-pin ratchet (SHA-pinned Actions) and the OSV advisory pin apply
+// to their inputs. When bumping `DEFAULT_SEMGREP_PIN`, refresh this map from
+// `https://pypi.org/pypi/semgrep/<version>/json` (the `urls[].digests.sha256`
+// values) — a version with no hash entry here fails fast rather than
+// installing unverified.
+const SEMGREP_HASHES = {
+  "1.97.0": [
+    "sha256:0ddaa25ee45e669e1fef87e88dcef73b2aee0874b507e09f618862c42452a205",
+    "sha256:9184500bf8c49ad19d0fb2d84923abb4aa53058b0ece7008b57a3b0b5e6ce3ee",
+    "sha256:f7d21d6499d4e6fafb4c0b04b1750e9f4b704a26bd78f0aff19f1c73d44843b4",
+    "sha256:996fe0b2bfac3a4d4511e470fdf5f3bca96b1f794f398e0336c8388802c218de",
+    "sha256:c585164358e03cd7868e1f0d38fbcb422c88dbe08795b83caeb5e36cf18874aa",
+  ],
+};
+
 const DEFAULT_OUT = join(REPO_ROOT, ".semgrep", "rules.json");
 
 // Languages this platform's reusable workflows + consumer trees actually
@@ -143,19 +165,67 @@ function resolveRegistryRules(semgrepPin) {
   const venvDir = join(mkdtempSync(join(tmpdir(), "semgrep-vendor-")), "venv");
   const targetDir = mkdtempSync(join(tmpdir(), "semgrep-vendor-target-"));
   const semgrepHome = mkdtempSync(join(tmpdir(), "semgrep-vendor-home-"));
+  const reqsFile = join(mkdtempSync(join(tmpdir(), "semgrep-vendor-reqs-")), "semgrep.txt");
 
   try {
     spawnSync("python3", ["-m", "venv", venvDir], { stdio: "inherit" });
     const pip = join(venvDir, "bin", "pip");
     const semgrep = join(venvDir, "bin", "semgrep");
 
+    // Resolve the exact version from the pin (`semgrep==<version>`) so we can
+    // look up its published artifact hashes. Only the `==` form is hashable;
+    // an unpinned or range pin cannot be verified.
+    const versionMatch = /^semgrep==(.+)$/.exec(semgrepPin.trim());
+    if (!versionMatch) {
+      throw new Error(
+        `cannot hash-pin ${semgrepPin}: only an exact 'semgrep==<version>' pin is supported`
+      );
+    }
+    const version = versionMatch[1];
+    const hashes = SEMGREP_HASHES[version];
+    if (!hashes || hashes.length === 0) {
+      throw new Error(
+        `no published artifact hashes recorded for ${semgrepPin} in SEMGREP_HASHES — ` +
+          `refresh from https://pypi.org/pypi/semgrep/${version}/json before pinning`
+      );
+    }
+
+    // Hash-pinned install: write a requirements file that pins `semgrep` to
+    // the exact version with every published artifact hash, then install it
+    // with `--require-hashes --no-deps`. pip verifies the downloaded semgrep
+    // artifact against this set before installing — a swapped/compromised
+    // artifact for this version is rejected. Dependencies are resolved in a
+    // separate, non-hashed step (semgrep is already satisfied), keeping the
+    // supply-chain-critical `semgrep` binary itself hash-verified.
+    const hashFlags = hashes.map((h) => `    --hash=${h}`).join(" \\\n");
+    writeFileSync(reqsFile, `semgrep==${version} \\\n${hashFlags}\n`, "utf8");
+
+    const installSemgrep = spawnSync(
+      pip,
+      [
+        "install",
+        "--quiet",
+        "--disable-pip-version-check",
+        "--require-hashes",
+        "--no-deps",
+        "-r",
+        reqsFile,
+      ],
+      { stdio: "inherit" }
+    );
+    if (installSemgrep.status !== 0) {
+      throw new Error(
+        `hash-pinned pip install ${semgrepPin} failed (exit ${installSemgrep.status})`
+      );
+    }
+
     const install = spawnSync(
       pip,
       ["install", "--quiet", "--disable-pip-version-check", "setuptools", semgrepPin],
       { stdio: "inherit" }
     );
     if (install.status !== 0) {
-      throw new Error(`pip install ${semgrepPin} failed (exit ${install.status})`);
+      throw new Error(`pip install ${semgrepPin} (dependencies) failed (exit ${install.status})`);
     }
 
     // A throwaway target file gives semgrep something to "scan" so it
@@ -196,6 +266,7 @@ function resolveRegistryRules(semgrepPin) {
     rmSync(venvDir, { recursive: true, force: true });
     rmSync(targetDir, { recursive: true, force: true });
     rmSync(semgrepHome, { recursive: true, force: true });
+    rmSync(dirname(reqsFile), { recursive: true, force: true });
   }
 }
 

package/templates/runbooks/README.md

@@ -1,10 +1,14 @@
 # Runbook Templates (copyable thin stubs)
 
-These are **copyable thin-stub templates** — one per canonical mandrel-platform
-runbook in [`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks).
-They implement the MP-9 adoption model (§7.7 / F1): *replace each duplicated
-process runbook with a thin local doc that holds project-specific values plus a
-link to the canonical runbook.*
+These are **copyable thin-stub templates** for the eight most commonly-adopted
+canonical mandrel-platform runbooks in
+[`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks)
+(listed in the table below). It is **not** a stub-per-canonical-runbook set —
+several canonical runbooks (`rollback.md`, `slo.md`, `secret-rotation.md`,
+`pin-drift-dashboard.md`) are platform-process docs a consumer reads directly
+and ships no local stub for. They implement the MP-9 adoption model
+(§7.7 / F1): *replace each duplicated process runbook with a thin local doc
+that holds project-specific values plus a link to the canonical runbook.*
 
 Each stub:
 

package/templates/runbooks/branch-protection-setup.md

@@ -21,9 +21,15 @@
 ## Apply & Verify
 
 ```bash
-# Preview / apply
-node scripts/apply-branch-protection.mjs --dry-run
-node scripts/apply-branch-protection.mjs --apply
+# Apply — PUT the protection with the aggregator as the only required context.
+# (There is no apply-branch-protection script; use gh api directly — see the
+# canonical runbook § 3.)
+gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \
+  --method PUT \
+  --raw-field required_status_checks='{"strict":false,"contexts":["<AGGREGATOR_CHECK>"]}' \
+  --field enforce_admins=false \
+  --raw-field required_pull_request_reviews=null \
+  --raw-field restrictions=null
 
 # Verify
 gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \