forgedock 1.27.0 → 1.29.0

package/bin/lean/toolchain.mjs

@@ -0,0 +1,228 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Toolchain pins for a lane (#4163). Reads the target repo's own pins (package.json `packageManager` / `engines.node`,
+ * `.nvmrc`, `.node-version`, `.tool-versions`) and writes a per-run shim dir for the pinned package manager, prepended
+ * to the runner's PATH so the builder, its validate commands and git hooks all resolve the pinned version. Zero LLM.
+ * A repo without pins gets nothing: no shim dir, no env, no warning.
+ */
+import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+import { accessSync, constants } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, delimiter, resolve } from "node:path";
+
+const PMS = ["pnpm", "yarn", "npm"];
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+/** "pnpm@10.4.1+sha512.ab" -> {name, version}; null for anything not a known manager at an exact version. */
+export function parsePackageManager(s) {
+  const m = /^(pnpm|yarn|npm)@([^+\s]+)(?:\+\S*)?$/.exec(String(s ?? "").trim());
+  return m && VERSION_RE.test(m[2]) ? { name: m[1], version: m[2] } : null;
+}
+
+/** `.tool-versions` lines -> {tool: firstVersion}. */
+function parseToolVersions(text) {
+  const out = {};
+  for (const l of String(text ?? "").split("\n")) {
+    const [tool, ver] = l.replace(/#.*/, "").trim().split(/\s+/);
+    if (tool && ver && !(tool in out)) out[tool] = ver;
+  }
+  return out;
+}
+
+/**
+ * The repo's pins. `override` is forge.yaml `env.toolchain`: "<pm>@<version>" replaces the package-manager pin, "off"
+ * disables detection. Returns {pm:{name,version,source}|null, node:{spec,source}|null, notes:[]}.
+ */
+export async function detectPins(dir, { override = null, read = (p) => readFile(p, "utf8") } = {}) {
+  const res = { pm: null, node: null, notes: [] };
+  const ov = typeof override === "string" ? override.trim() : "";
+  if (ov.toLowerCase() === "off") return res;
+  const tryRead = async (f) => { try { return String(await read(join(dir, f))); } catch { return null; } };
+  let pkg = null;
+  const pkgText = await tryRead("package.json");
+  if (pkgText !== null) { try { pkg = JSON.parse(pkgText); } catch { res.notes.push("package.json is not valid JSON; its pins are ignored"); } }
+  const tv = parseToolVersions(await tryRead(".tool-versions"));
+  if (ov) {
+    const pm = parsePackageManager(ov);
+    if (pm) res.pm = { ...pm, source: "forge.yaml env.toolchain" };
+    else res.notes.push(`forge.yaml env.toolchain "${ov.slice(0, 60)}" is not <pnpm|yarn|npm>@<x.y.z> or "off"; ignored`);
+  }
+  if (!res.pm && typeof pkg?.packageManager === "string") {
+    const pm = parsePackageManager(pkg.packageManager);
+    if (pm) res.pm = { ...pm, source: "package.json packageManager" };
+    else res.notes.push(`package.json packageManager "${pkg.packageManager.slice(0, 60)}" is not <pnpm|yarn|npm>@<x.y.z>; not pinned`);
+  }
+  if (!res.pm) {
+    const name = PMS.find((n) => VERSION_RE.test(tv[n] ?? ""));
+    if (name) res.pm = { name, version: tv[name], source: ".tool-versions" };
+  }
+  for (const [f, get] of [[".nvmrc", (t) => t], [".node-version", (t) => t]]) {
+    if (res.node) break;
+    const t = await tryRead(f);
+    const spec = t === null ? "" : get(t).split("\n")[0].trim();
+    if (spec) res.node = { spec, source: f };
+  }
+  if (!res.node && (tv.nodejs || tv.node)) res.node = { spec: tv.nodejs || tv.node, source: ".tool-versions" };
+  if (!res.node && typeof pkg?.engines?.node === "string" && pkg.engines.node.trim()) res.node = { spec: pkg.engines.node.trim(), source: "package.json engines.node" };
+  return res;
+}
+
+// ---- minimal semver satisfaction for node pins ----
+const parseV = (s) => {
+  const m = /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/i.exec(String(s).trim());
+  if (!m) return null;
+  const n = (x) => (x === undefined || /^[x*]$/i.test(x) ? null : Number(x));
+  return [Number(m[1]), n(m[2]), n(m[3])];
+};
+const cmp = (a, b) => { for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1; } return 0; };
+const fill = (p, v = 0) => p.map((x) => (x === null ? v : x));
+/** host [M,m,p] within partial p (20 -> 20.x.x, 20.11 -> 20.11.x)? */
+const within = (h, p) => p.every((x, i) => x === null || x === h[i]);
+const upper = (p) => (p[1] === null ? [p[0] + 1, 0, 0] : p[2] === null ? [p[0], p[1] + 1, 0] : null);
+
+/** true/false, or null when the comparator can't be evaluated. */
+function satisfiesOne(h, c) {
+  const m = /^(\^|~|>=|<=|>|<|=)?\s*(\S+)$/.exec(c.trim());
+  if (!m) return null;
+  const p = parseV(m[2]);
+  if (!p) return null;
+  const lo = fill(p);
+  switch (m[1] ?? "") {
+    case "": case "=": return within(h, p);
+    case ">=": return cmp(h, lo) >= 0;
+    case ">": return p[1] === null || p[2] === null ? cmp(h, upper(p)) >= 0 : cmp(h, lo) > 0;
+    case "<": return cmp(h, lo) < 0;
+    case "<=": return p[1] === null || p[2] === null ? cmp(h, upper(p)) < 0 : cmp(h, lo) <= 0;
+    case "~": return cmp(h, lo) >= 0 && cmp(h, p[1] === null ? [p[0] + 1, 0, 0] : [p[0], p[1] + 1, 0]) < 0;
+    case "^": return cmp(h, lo) >= 0 && cmp(h, lo[0] > 0 ? [lo[0] + 1, 0, 0] : lo[1] > 0 ? [0, lo[1] + 1, 0] : [0, 0, lo[2] + 1]) < 0;
+  }
+  return null;
+}
+
+/** Does host version `v` satisfy node spec? true/false, or null when the spec can't be evaluated (aliases, unknown syntax). */
+export function nodeSatisfies(spec, v) {
+  const h = parseV(v);
+  if (!h || h.includes(null)) return null;
+  const alts = String(spec).split("||").map((s) => s.trim()).filter(Boolean);
+  if (!alts.length) return null;
+  let unknown = false;
+  for (const alt of alts) {
+    const hy = /^(\S+)\s+-\s+(\S+)$/.exec(alt); // hyphen range "18 - 20" = ">=18 <=20"
+    const parts = hy ? [`>=${hy[1]}`, `<=${hy[2]}`] : alt.replace(/(\^|~|>=|<=|>|<|=)\s+/g, "$1").split(/\s+/);
+    let ok = true;
+    for (const c of parts) {
+      const r = satisfiesOne(h, c);
+      if (r === null) { unknown = true; ok = false; break; }
+      if (!r) { ok = false; break; }
+    }
+    if (ok) return true;
+  }
+  return unknown ? null : false;
+}
+
+/** One-line trajectory warning when the host node does not satisfy the pin; null when it does or nothing is pinned. */
+export function nodeWarning(pin, hostVersion = process.version) {
+  if (!pin?.spec) return null;
+  if (/^(lts\/|node$|stable$|latest$|current$|system$)/i.test(pin.spec)) return null;
+  const ok = nodeSatisfies(pin.spec, hostVersion);
+  if (ok === true) return null;
+  if (ok === null) return `Toolchain: cannot evaluate node pin "${pin.spec}" (${pin.source}) against host node ${hostVersion}; check it manually`;
+  return `host node ${hostVersion} does not satisfy the ${pin.source} pin "${pin.spec}"; installs, builds and tests may behave differently from the repo's CI`;
+}
+
+/** First executable `name` on `pathStr`, skipping `exclude` dirs (the shim dir itself, so a shim never calls itself). */
+export function which(name, pathStr = process.env.PATH ?? "", exclude = []) {
+  const skip = new Set(exclude.map((d) => resolve(d)));
+  for (const d of String(pathStr).split(delimiter)) {
+    if (!d || skip.has(resolve(d))) continue;
+    const p = join(d, name);
+    try { accessSync(p, constants.X_OK); return p; } catch { /* next */ }
+  }
+  return null;
+}
+
+const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const HEADER = "#!/bin/sh\n# forgedock lane toolchain shim (#4163): pinned by the target repo; do not edit.\nexport COREPACK_ENABLE_DOWNLOAD_PROMPT=0 COREPACK_ENABLE_STRICT=0\n";
+
+/**
+ * Shim scripts {name: content} for the pinned manager: `corepack <pm>@<ver>` when corepack is on the host PATH, else
+ * `npx -y`. Absolute paths are resolved here, so a shim never re-enters the shim dir. Returns {} when neither exists.
+ */
+export function shimScripts(pm, { corepack = null, npx = null } = {}) {
+  if (!pm || !PMS.includes(pm.name) || !VERSION_RE.test(pm.version)) return {};
+  const at = `${pm.name}@${pm.version}`;
+  const out = {};
+  if (pm.name === "npm") {
+    if (npx) { out.npm = `${HEADER}exec ${q(npx)} -y ${q(at)} "$@"\n`; out.npx = `${HEADER}exec ${q(npx)} -y -p ${q(at)} npx "$@"\n`; }
+    return out;
+  }
+  if (corepack) {
+    out[pm.name] = `${HEADER}exec ${q(corepack)} ${q(at)} "$@"\n`;
+    if (pm.name === "pnpm") out.pnpx = `${HEADER}exec ${q(corepack)} ${q(at)} dlx "$@"\n`;
+    return out;
+  }
+  if (!npx) return out;
+  // yarn >= 2 is published as @yarnpkg/cli-dist; the npm "yarn" package is 1.x only.
+  const pkg = pm.name === "yarn" && Number(pm.version.split(".")[0]) >= 2 ? `@yarnpkg/cli-dist@${pm.version}` : at;
+  out[pm.name] = `${HEADER}exec ${q(npx)} -y -p ${q(pkg)} ${pm.name} "$@"\n`;
+  if (pm.name === "pnpm") out.pnpx = `${HEADER}exec ${q(npx)} -y -p ${q(pkg)} pnpm dlx "$@"\n`;
+  return out;
+}
+
+/** Runner env for a shim dir: PATH with the shim dir first, corepack prompts off. */
+export function toolchainEnv(binDir, basePath = process.env.PATH ?? "") {
+  return { PATH: basePath ? `${binDir}${delimiter}${basePath}` : binDir, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", COREPACK_ENABLE_STRICT: "0" };
+}
+
+/** Version of the host `node` the builder's shells resolve (PATH), falling back to this process. */
+export function hostNodeVersion(pathStr = process.env.PATH ?? "") {
+  const n = which("node", pathStr);
+  if (n) { try { return String(execFileSync(n, ["--version"], { timeout: 10000 })).trim(); } catch { /* fall through */ } }
+  return process.version;
+}
+
+async function writeShimFile(p, content) { await writeFile(p, content); await chmod(p, 0o755); }
+
+/**
+ * Write executable (0755) shims for the pinned manager into `binDir`; launchers are resolved from `path` with `binDir`
+ * excluded. Returns the shim names written ([] when neither corepack nor npx is on `path`).
+ */
+export async function writeShims(binDir, pm, { path = process.env.PATH ?? "", find = which, writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }) } = {}) {
+  const scripts = shimScripts(pm, { corepack: find("corepack", path, [binDir]), npx: find("npx", path, [binDir]) });
+  if (!Object.keys(scripts).length) return [];
+  await mkdirp(binDir);
+  for (const [name, content] of Object.entries(scripts)) await writeShim(join(binDir, name), content);
+  return Object.keys(scripts);
+}
+
+/** Short pin text for prompts and decisions, e.g. "pnpm@10.4.1 (package.json packageManager), node 20 (.nvmrc)"; null when nothing is pinned. */
+export function summary(pins) {
+  const parts = [...(pins?.pm ? [`${pins.pm.name}@${pins.pm.version} (${pins.pm.source})`] : []), ...(pins?.node ? [`node ${pins.node.spec} (${pins.node.source})`] : [])];
+  return parts.length ? parts.join(", ") : null;
+}
+
+/**
+ * Detect pins in `dir` and, for a pinned package manager, write shims to `binDir`.
+ * @returns {Promise<{pins, env:?object, shims:string[], summary:?string, warning:?string, notes:string[]}>}
+ *   env is null and shims empty without a usable pm pin; summary is null when nothing is pinned: the caller changes nothing.
+ */
+export async function prepareToolchain({ dir, binDir, override = null, read, basePath = process.env.PATH ?? "",
+  writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }), find = which, hostNode = () => hostNodeVersion(basePath) } = {}) {
+  const pins = await detectPins(dir, { override, ...(read ? { read } : {}) });
+  const out = { pins, env: null, shims: [], summary: null, warning: null, notes: [...pins.notes] };
+  if (pins.node) {
+    let v = null;
+    try { v = hostNode(); } catch { v = null; }
+    out.warning = v ? nodeWarning(pins.node, v) : null;
+  }
+  const pm = pins.pm;
+  let effective = pins;
+  if (pm && binDir) {
+    out.shims = await writeShims(binDir, pm, { path: basePath, find, writeShim, mkdirp });
+    if (out.shims.length) out.env = toolchainEnv(binDir, basePath);
+    else { out.notes.push(`Toolchain: ${pm.name}@${pm.version} is pinned but neither corepack nor npx is on PATH; the host ${pm.name} is used`); effective = { ...pins, pm: null }; }
+  }
+  out.summary = summary(effective);
+  return out;
+}

package/bin/lean/toolchain.test.mjs

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync, statSync } from "node:fs";
+import { join, delimiter } from "node:path";
+import { execFileSync } from "node:child_process";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { detectPins, parsePackageManager, nodeSatisfies, nodeWarning, shimScripts, prepareToolchain, toolchainEnv, writeShims, summary } from "./toolchain.mjs";
+
+const tmp = (p) => tmpDir(p);
+const repo = (files) => {
+  const d = tmp("tc-repo-");
+  for (const [f, t] of Object.entries(files)) writeFileSync(join(d, f), typeof t === "string" ? t : JSON.stringify(t));
+  return d;
+};
+const exe = (dir, name, body) => { mkdirSync(dir, { recursive: true }); const p = join(dir, name); writeFileSync(p, `#!/bin/sh\n${body}\n`); chmodSync(p, 0o755); return p; };
+/**
+ * A host whose PATH has pnpm 11.0.0 and a fake corepack/npx that print the requested version for `--version`
+ * (`corepack pnpm@X --version`, `npx -y -p pnpm@X pnpm --version`) without any network.
+ */
+const fakeHost = ({ corepack = true } = {}) => {
+  const d = tmp("tc-host-");
+  exe(d, "pnpm", 'echo 11.0.0');
+  const pick = 'for a in "$@"; do case "$a" in pnpm@*) v="${a#pnpm@}";; esac; done; for a in "$@"; do [ "$a" = "--version" ] && { echo "$v"; exit 0; }; done; exit 0';
+  if (corepack) exe(d, "corepack", pick);
+  exe(d, "npx", pick);
+  return d;
+};
+const sysPath = process.env.PATH ?? "";
+
+describe("toolchain pins (#4163)", () => {
+  it("parsePackageManager accepts pm@x.y.z (with a +sha suffix) and nothing else", () => {
+    assert.deepEqual(parsePackageManager("pnpm@10.4.1+sha512.abc"), { name: "pnpm", version: "10.4.1" });
+    assert.deepEqual(parsePackageManager("yarn@4.1.0"), { name: "yarn", version: "4.1.0" });
+    for (const bad of ["pnpm@10", "bun@1.0.0", "pnpm@latest", "pnpm@1.0.0;rm -rf /", "", null]) assert.equal(parsePackageManager(bad), null, String(bad));
+  });
+
+  it("detects packageManager and node pins in priority order", async () => {
+    const d = repo({ "package.json": { packageManager: "pnpm@10.4.1", engines: { node: ">=18" } }, ".nvmrc": "20.11.0\n", ".node-version": "22\n" });
+    const p = await detectPins(d);
+    assert.deepEqual(p.pm, { name: "pnpm", version: "10.4.1", source: "package.json packageManager" });
+    assert.deepEqual(p.node, { spec: "20.11.0", source: ".nvmrc" });
+    const e = await detectPins(repo({ "package.json": { engines: { node: "^20" } } }));
+    assert.deepEqual(e.node, { spec: "^20", source: "package.json engines.node" });
+    assert.equal(e.pm, null);
+    const tv = await detectPins(repo({ ".tool-versions": "# pins\nnodejs 20.1.0\npnpm 9.1.0\n" }));
+    assert.deepEqual(tv.pm, { name: "pnpm", version: "9.1.0", source: ".tool-versions" });
+    assert.deepEqual(tv.node, { spec: "20.1.0", source: ".tool-versions" });
+  });
+
+  it("forge.yaml env.toolchain overrides the pm pin; off disables detection; junk is a note", async () => {
+    const d = repo({ "package.json": { packageManager: "pnpm@10.4.1" }, ".nvmrc": "20" });
+    assert.deepEqual((await detectPins(d, { override: "pnpm@9.0.0" })).pm, { name: "pnpm", version: "9.0.0", source: "forge.yaml env.toolchain" });
+    const off = await detectPins(d, { override: "off" });
+    assert.equal(off.pm, null); assert.equal(off.node, null);
+    const junk = await detectPins(d, { override: "pnpm" });
+    assert.equal(junk.pm.version, "10.4.1");
+    assert.match(junk.notes[0], /env\.toolchain "pnpm" is not/);
+  });
+
+  it("nodeSatisfies covers exact, partial, x, caret, tilde, comparators and ||", () => {
+    const t = [["20", "v20.11.0", true], ["20", "v22.1.0", false], ["20.11", "v20.11.4", true], ["20.x", "v20.0.0", true], ["^20.5", "v20.4.0", false],
+      ["^20.5", "v20.9.0", true], ["~20.5.1", "v20.6.0", false], [">=18", "v26.7.0", true], [">=18 <21", "v22.0.0", false], ["18 || 20", "v20.1.0", true],
+      ["< 20", "v20.0.0", false], ["<=20", "v20.9.9", true], [">20", "v20.9.9", false], [">20", "v21.0.0", true], ["v20.11.0", "v20.11.0", true]];
+    for (const [spec, v, want] of t) assert.equal(nodeSatisfies(spec, v), want, `${spec} vs ${v}`);
+    assert.equal(nodeSatisfies("18 - 20", "v19.0.0"), true);
+    assert.equal(nodeSatisfies("18 - 20", "v21.0.0"), false);
+    assert.equal(nodeSatisfies("hydrogen", "v19.0.0"), null);
+  });
+
+  it("an unsatisfied node pin yields a clear warning; a satisfied or alias pin yields none", () => {
+    assert.match(nodeWarning({ spec: "18.19.0", source: ".nvmrc" }, "v26.7.0"), /host node v26\.7\.0 does not satisfy the \.nvmrc pin "18\.19\.0"/);
+    assert.equal(nodeWarning({ spec: ">=18", source: "package.json engines.node" }, "v26.7.0"), null);
+    assert.equal(nodeWarning({ spec: "lts/iron", source: ".nvmrc" }, "v26.7.0"), null);
+    assert.match(nodeWarning({ spec: "iron-ish", source: ".nvmrc" }, "v26.7.0"), /cannot evaluate/);
+  });
+
+  it("shims: corepack first, npx fallback, yarn berry via @yarnpkg/cli-dist, values quoted", () => {
+    const pm = { name: "pnpm", version: "10.4.1" };
+    assert.match(shimScripts(pm, { corepack: "/h/corepack", npx: "/h/npx" }).pnpm, /exec '\/h\/corepack' 'pnpm@10\.4\.1' "\$@"/);
+    assert.match(shimScripts(pm, { corepack: "/h/corepack" }).pnpx, /'pnpm@10\.4\.1' dlx "\$@"/);
+    assert.match(shimScripts(pm, { npx: "/h/npx" }).pnpm, /exec '\/h\/npx' -y -p 'pnpm@10\.4\.1' pnpm "\$@"/);
+    assert.match(shimScripts({ name: "yarn", version: "4.1.0" }, { npx: "/h/npx" }).yarn, /-p '@yarnpkg\/cli-dist@4\.1\.0' yarn/);
+    assert.match(shimScripts({ name: "yarn", version: "1.22.19" }, { npx: "/h/npx" }).yarn, /-p 'yarn@1\.22\.19' yarn/);
+    const npm = shimScripts({ name: "npm", version: "10.2.0" }, { corepack: "/h/c", npx: "/h/npx" });
+    assert.deepEqual(Object.keys(npm), ["npm", "npx"]);
+    assert.match(npm.npx, /exec '\/h\/npx' -y -p 'npm@10\.2\.0' npx "\$@"/);
+    assert.deepEqual(shimScripts(pm, {}), {});
+  });
+
+  for (const corepack of [true, false]) {
+    it(`R1: with packageManager pnpm@10.4.1 and pnpm 11 on PATH, runner/validate/hook shells resolve pnpm --version to 10.4.1 (${corepack ? "corepack" : "npx"})`, async () => {
+      const host = fakeHost({ corepack });
+      const basePath = `${host}${delimiter}${sysPath}`;
+      assert.equal(execFileSync("sh", ["-c", "pnpm --version"], { env: { ...process.env, PATH: basePath } }).toString().trim(), "11.0.0", "the host pnpm is the wrong one");
+      const d = repo({ "package.json": { name: "x", packageManager: "pnpm@10.4.1+sha512.ff" } });
+      const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+      const tc = await prepareToolchain({ dir: d, binDir, basePath, hostNode: () => "v20.0.0" });
+      assert.ok(tc.env && tc.env.PATH.startsWith(binDir + delimiter), "shim dir first on PATH");
+      assert.equal(tc.summary, "pnpm@10.4.1 (package.json packageManager)");
+      const env = { ...process.env, ...tc.env };
+      // runner: the claude CLI child gets this env (bin/runner.mjs applies `env` last); its Bash tool shells inherit it.
+      assert.equal(execFileSync("bash", ["-lc", "pnpm --version"], { env, cwd: d }).toString().trim(), "10.4.1", "runner shell");
+      // validate: a validate command is a shell command in the worktree.
+      assert.equal(execFileSync("sh", ["-c", "cd . && pnpm --version"], { env, cwd: d }).toString().trim(), "10.4.1", "validate command");
+      // hooks: git runs pre-commit / commit-msg hooks with the committing shell's PATH.
+      const git = (a) => execFileSync("git", a, { env: { ...env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" }, cwd: d }).toString();
+      git(["init", "-q"]);
+      exe(join(d, ".git", "hooks"), "pre-commit", `pnpm --version > "${join(d, "pre.out")}"`);
+      exe(join(d, ".git", "hooks"), "commit-msg", `pnpm --version > "${join(d, "msg.out")}"`);
+      git(["add", "package.json"]);
+      git(["commit", "-q", "-m", "x"]);
+      assert.equal(readFileSync(join(d, "pre.out"), "utf8").trim(), "10.4.1", "pre-commit hook");
+      assert.equal(readFileSync(join(d, "msg.out"), "utf8").trim(), "10.4.1", "commit-msg hook");
+    });
+  }
+
+  it("R2: a node pin the host does not satisfy produces a warning (and no shim without a pm pin)", async () => {
+    const binDir = join(tmp("tc-run-"), "bin");
+    const tc = await prepareToolchain({ dir: repo({ ".nvmrc": "18.19.0" }), binDir, hostNode: () => "v26.7.0" });
+    assert.match(tc.warning, /^host node v26\.7\.0 does not satisfy the \.nvmrc pin "18\.19\.0"/);
+    assert.equal(tc.summary, "node 18.19.0 (.nvmrc)");
+    assert.equal(tc.env, null); assert.equal(existsSync(binDir), false);
+  });
+
+  it("R4: a repo without pins gets nothing: no env, no shim dir, no warning, no notes", async () => {
+    const binDir = join(tmp("tc-run-"), "bin");
+    for (const files of [{}, { "package.json": { name: "x", scripts: { test: "node --test" } } }]) {
+      const tc = await prepareToolchain({ dir: repo(files), binDir, hostNode: () => { throw new Error("must not probe node"); } });
+      assert.equal(tc.env, null); assert.equal(tc.summary, null); assert.equal(tc.warning, null);
+      assert.deepEqual(tc.shims, []); assert.deepEqual(tc.notes, []);
+      assert.equal(existsSync(binDir), false);
+    }
+  });
+
+  it("toolchainEnv prepends the shim dir", () => {
+    assert.deepEqual(toolchainEnv("/s", "/a:/b"), { PATH: `/s${delimiter}/a:/b`, COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", COREPACK_ENABLE_STRICT: "0" });
+  });
+
+  it("writeShims writes 0755 shims that never resolve the launcher from the shim dir; summary names the pins", async () => {
+    const host = fakeHost();
+    const binDir = join(tmp("tc-ws-"), "bin");
+    exe(binDir, "corepack", "echo self");
+    const names = await writeShims(binDir, { name: "pnpm", version: "10.4.1" }, { path: `${binDir}${delimiter}${host}` });
+    assert.deepEqual(names, ["pnpm", "pnpx"]);
+    for (const n of names) assert.equal(statSync(join(binDir, n)).mode & 0o777, 0o755);
+    assert.match(readFileSync(join(binDir, "pnpm"), "utf8"), new RegExp(`exec '${join(host, "corepack")}' 'pnpm@10\\.4\\.1'`));
+    assert.deepEqual(await writeShims(join(tmp("tc-ws-"), "bin"), { name: "yarn", version: "4.1.0" }, { path: "/nonexistent" }), []);
+    assert.equal(summary({ pm: { name: "pnpm", version: "10.4.1", source: "package.json packageManager" }, node: { spec: "20", source: ".nvmrc" } }), "pnpm@10.4.1 (package.json packageManager), node 20 (.nvmrc)");
+    assert.equal(summary({ pm: null, node: null }), null);
+    assert.equal(nodeWarning({ spec: "1", source: ".nvmrc" }) !== null, true, "defaults to process.version");
+  });
+});

package/bin/lean/verify.mjs

@@ -11,16 +11,23 @@ export const VERIFY_MODES = Object.freeze(["local", "ci", "hybrid"]);
 /** Changed files that never need the CI matrix (docs-only lanes skip CI verification). */
 export const DEFAULT_SKIP_PATHS = Object.freeze(["*.md", "*.mdx", "*.rst", "*.txt", "docs/**", "devdocs/**"]);
 export const DEFAULT_MAX_ROUNDS = 2;
+/** Per-command timeout of the pre-PR declared check commands (#4240, `verify.precheck_timeout_seconds`). */
+export const DEFAULT_PRECHECK_TIMEOUT_SECONDS = 300;
 /** Total characters of failed-job log handed to the builder. */
 export const LOG_CAP = 12000;
 /** No run or check for the head after this long means CI is unavailable (local fallback). */
 export const DEFAULT_GRACE_MS = 5 * 60000;
 const LEAN_PREFIX = ".forge-lean/";
+/** The lane's own report-only check run (#4270, `verify.check_run`): never part of ForgeDock's own CI waits. */
+export const VERIFY_CHECK_NAME = "forgedock/verify";
+/** Checks API output.text limit is 65535 characters; stay well under it. */
+export const VERIFY_TEXT_CAP = 60000;
 const OK = ["success", "neutral", "skipped"];
 
 /**
  * forge.yaml `verify:` section (block style; parseForgeYaml gives strings) → {mode, workflow, pathsInput, skipPaths,
- * maxRounds}. Invalid values fall back to the defaults; mode defaults to local (today's behaviour).
+ * maxRounds, precheckTimeoutSeconds, checkRun}. Invalid values fall back to the defaults; mode defaults to local (today's
+ * behaviour); checkRun (`check_run`, #4270) is true only for the literal `true`.
  */
 export function parseVerify(sec = {}) {
   const s = sec && typeof sec === "object" ? sec : {};
@@ -32,7 +39,10 @@ export function parseVerify(sec = {}) {
   const skipPaths = rawSkip ? rawSkip.map((x) => String(x).trim()).filter(Boolean) : [...DEFAULT_SKIP_PATHS];
   const n = Number(str(s.max_rounds));
   const maxRounds = str(s.max_rounds) !== "" && Number.isInteger(n) && n >= 0 && n <= 10 ? n : DEFAULT_MAX_ROUNDS;
-  return { mode, workflow, pathsInput, skipPaths, maxRounds };
+  const t = Number(str(s.precheck_timeout_seconds));
+  const precheckTimeoutSeconds = str(s.precheck_timeout_seconds) !== "" && Number.isInteger(t) && t >= 1 && t <= 3600 ? t : DEFAULT_PRECHECK_TIMEOUT_SECONDS;
+  const checkRun = str(s.check_run).toLowerCase() === "true";
+  return { mode, workflow, pathsInput, skipPaths, maxRounds, precheckTimeoutSeconds, checkRun };
 }
 
 const globRe = (g) => new RegExp(`^${g.split("**").map((p) => p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")).join(".*")}$`);
@@ -55,6 +65,19 @@ export function capLogs(failures, cap = LOG_CAP) {
   return failures.map((f) => { const l = String(f.log ?? ""); return { ...f, log: l.length > per ? `…${l.slice(-per)}` : l }; });
 }
 const runIdOf = (url) => /\/actions\/runs\/(\d+)/.exec(String(url ?? ""))?.[1] ?? null;
+/**
+ * Failed checks [{name, url}] → capped [{job, url, log}]: one `failedLogs` fetch per Actions run id, the log attached to
+ * the first check of that run only (#4240: shared by runCiVerify and the merge-time fix rounds).
+ */
+export async function collectFailedLogs(io, failedChecks) {
+  const logs = {}, out = [];
+  for (const c of failedChecks ?? []) {
+    const id = runIdOf(c.url);
+    if (id && !(id in logs)) { try { logs[id] = String((await io.failedLogs?.(id)) ?? ""); } catch { logs[id] = ""; } }
+    out.push({ job: c.name, url: c.url ?? null, log: id && !out.some((x) => runIdOf(x.url) === id) ? logs[id] : "" });
+  }
+  return capLogs(out);
+}
 const sameSha = (a, b) => Boolean(a && b) && (String(a).startsWith(b) || String(b).startsWith(a));
 
 /**
@@ -92,18 +115,12 @@ export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMa
       if (!run && now() - startedAt >= graceMs) return unavailable(`no ${v.workflow} run for ${String(head).slice(0, 12)} appeared within ${Math.round(graceMs / 60000)} min`);
     } else {
       let checks = [];
-      try { checks = (await io.commitChecks(head)) ?? []; } catch { checks = []; }
+      try { checks = ((await io.commitChecks(head)) ?? []).filter((c) => c?.name !== VERIFY_CHECK_NAME); } catch { checks = []; }
       if (!checks.length && now() - startedAt >= graceMs) return unavailable(`no checks reported for ${String(head).slice(0, 12)} within ${Math.round(graceMs / 60000)} min`);
       if (checks.length && checks.every((c) => c.state !== "pending")) {
         const failed = checks.filter((c) => c.state === "failure");
         if (!failed.length) return { result: "pass", failures: [], runUrl: null, detail: `${checks.length} check(s) green` };
-        const logs = {}, out = [];
-        for (const c of failed) {
-          const id = runIdOf(c.url);
-          if (id && !(id in logs)) { try { logs[id] = String((await io.failedLogs?.(id)) ?? ""); } catch { logs[id] = ""; } }
-          out.push({ job: c.name, url: c.url ?? null, log: id && !out.some((x) => runIdOf(x.url) === id) ? logs[id] : "" });
-        }
-        return { result: "fail", failures: capLogs(out), runUrl: failed[0].url ?? null, detail: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}` };
+        return { result: "fail", failures: await collectFailedLogs(io, failed), runUrl: failed[0].url ?? null, detail: `${failed.length} check(s) failed: ${failed.map((c) => c.name).join(", ")}` };
       }
     }
     if (now() - startedAt >= ciMaxMinutes * 60000) return { result: "timeout", failures: [], runUrl: null, detail: `CI still pending after ${ciMaxMinutes} min` };
@@ -111,3 +128,42 @@ export async function runCiVerify({ io, branch, head, changedFiles, verify, ciMa
     await sleep(ciPollDelayMs(i, random));
   }
 }
+
+const VALIDATE_KINDS = ["validate_missing", "validate_failed"], REQUIREMENT_KINDS = ["requirement_unimplemented", "untracked_deferral"];
+/**
+ * #4270: the `forgedock/verify` check-run payload from the results the lane already computed (no gate logic of its own).
+ * commands: [{command, rc}] of the last declared-check round, or null (none configured); structure: the structure delta or
+ * null; undeclaredEdges: package edges the contract does not name; docs: io.docsFreshness result or null; precheck: the
+ * conformance precheck failures of the last gate() run (null = never ran); amendments: its amendment problems; hotspots:
+ * whether hotspot facts were available. Returns {conclusion, gates: [{id, ok, ran, evidence}], title, summary, text}. A gate
+ * counts only when it ran (#4297): failure if a gate that ran failed, neutral ("no gates ran") when none ran, else success.
+ */
+export function verifyReport({ head = null, commands = null, structure = null, undeclaredEdges = [], docs = null, precheck = null, amendments = [], hotspots = false, contract = null, result = null } = {}) {
+  const NOT_RUN = "not run";
+  const pre = Array.isArray(precheck) ? precheck : [];
+  const details = (kinds) => pre.filter((f) => kinds.includes(f?.kind)).map((f) => String(f.detail ?? f.code ?? ""));
+  const runs = Array.isArray(result?.validation) ? result.validation : [];
+  const reqs = Array.isArray(result?.requirements) ? result.requirements : [];
+  const edges = (xs) => (xs ?? []).map((e) => `${e?.from}→${e?.to}${e?.manifest ? ` (${e.manifest})` : ""}`);
+  const gate = (id, ran, failures, okEvidence) => ({ id, ok: !failures.length, ran: Boolean(ran), evidence: !ran ? NOT_RUN : failures.length ? failures : okEvidence });
+  const gates = [
+    gate("precheck.commands", Array.isArray(commands), (commands ?? []).filter((c) => c.rc !== 0).map((c) => `${c.command} (exit ${c.rc})`),
+      (commands ?? []).map((c) => ({ command: c.command, rc: c.rc }))),
+    gate("structure.edges", Boolean(structure), edges(undeclaredEdges).map((e) => `undeclared ${e}`), { added: edges(structure?.package_edges_added) }),
+    gate("docs.freshness", Boolean(docs), docs && !docs.ok ? [String(docs.output ?? "stale docs").slice(0, 2000)] : [], "ok"),
+    gate("conformance.scope", precheck !== null, details(["scope_creep"]), "every changed file is inside the contract's deliverables"),
+    gate("conformance.validate", precheck !== null, details(VALIDATE_KINDS),
+      (contract?.validate ?? []).map((v) => { const r = runs.find((x) => x?.id === v.id); return { id: v.id, command: v.command, ...(r?.exit !== undefined ? { exit: r.exit } : r?.ci ? { ci: true } : {}) }; })),
+    gate("conformance.requirements", precheck !== null, details(REQUIREMENT_KINDS), reqs.map((r) => ({ id: r?.id, status: r?.status }))),
+    gate("maintenance.hotspot_growth", precheck !== null && Boolean(hotspots), details(["hotspot_growth"]), "no over-threshold file grew past the limit"),
+    gate("conformance.amendments", precheck !== null, (amendments ?? []).map((a) => String(a?.detail ?? a)), "ok"),
+  ];
+  const ran = gates.filter((g) => g.ran), failed = ran.filter((g) => !g.ok);
+  const conclusion = failed.length ? "failure" : ran.length ? "success" : "neutral";
+  const title = failed.length ? `${failed.length} of ${ran.length} deterministic gate(s) failed` : ran.length ? `${ran.length} deterministic gate(s) passed` : "no gates ran";
+  const summary = [`ForgeDock deterministic gates${head ? ` at \`${String(head).slice(0, 12)}\`` : ""}: report only (requiring it is the repository's branch-protection choice).`, "",
+    ...(ran.length ? gates.map((g) => `- ${!g.ran ? "⏭️" : g.ok ? "✅" : "❌"} \`${g.id}\`${g.ran ? "" : " (not run)"}`) : ["no gates ran"])].join("\n");
+  let json = JSON.stringify({ head, conclusion, gates }, null, 2);
+  if (json.length > VERIFY_TEXT_CAP) json = JSON.stringify({ head, conclusion, truncated: true, gates: gates.map((g) => ({ id: g.id, ok: g.ok, ran: g.ran, evidence: JSON.stringify(g.evidence).slice(0, Math.floor(VERIFY_TEXT_CAP / (gates.length + 1))) })) }, null, 2);
+  return { conclusion, gates, title, summary, text: "```json\n" + json + "\n```" };
+}

package/bin/lean/verify.test.mjs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, DEFAULT_SKIP_PATHS, LOG_CAP } from "./verify.mjs";
+import { parseVerify, matchesGlob, skipsCi, capLogs, runCiVerify, collectFailedLogs, verifyReport, DEFAULT_SKIP_PATHS, LOG_CAP, VERIFY_CHECK_NAME, VERIFY_TEXT_CAP } from "./verify.mjs";
 import { precheck } from "./conformance.mjs";
 
 const HEAD = "abc123abc123abc123";
@@ -22,9 +22,9 @@ function fake(o = {}) {
 
 describe("verify-by-CI config (#4167)", () => {
   it("parseVerify defaults to local and rejects invalid values", () => {
-    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2 });
+    assert.deepEqual(parseVerify({}), { mode: "local", workflow: null, pathsInput: null, skipPaths: [...DEFAULT_SKIP_PATHS], maxRounds: 2, precheckTimeoutSeconds: 300, checkRun: false });
     const v = parseVerify({ mode: "ci", workflow: ".github/workflows/verify.yml", paths_input: "changed_paths", skip_paths: "*.md, docs/** ,", max_rounds: "3" });
-    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3 });
+    assert.deepEqual(v, { mode: "ci", workflow: ".github/workflows/verify.yml", pathsInput: "changed_paths", skipPaths: ["*.md", "docs/**"], maxRounds: 3, precheckTimeoutSeconds: 300, checkRun: false });
     assert.equal(parseVerify({ mode: "remote" }).mode, "local");
     assert.equal(parseVerify({ workflow: "x; rm -rf /" }).workflow, null);
     assert.equal(parseVerify({ max_rounds: "-1" }).maxRounds, 2);
@@ -93,3 +93,104 @@ describe("runCiVerify (#4167)", () => {
     assert.equal((await runCiVerify(g.args({ verify: parseVerify({ mode: "ci" }) }))).result, "unavailable");
   });
 });
+
+describe("merge-time fix rounds and declared check commands (#4240)", () => {
+  it("collectFailedLogs fetches one log per Actions run and caps the total", async () => {
+    const fetched = [];
+    const io = { failedLogs: async (id) => { fetched.push(id); return "x".repeat(LOG_CAP * 2); } };
+    const out = await collectFailedLogs(io, [
+      { name: "Unit tests", url: "https://github.com/o/r/actions/runs/9/job/1" },
+      { name: "Shell tests", url: "https://github.com/o/r/actions/runs/9/job/2" },
+      { name: "status", url: null },
+    ]);
+    assert.deepEqual(fetched, ["9"]);
+    assert.deepEqual(out.map((f) => f.job), ["Unit tests", "Shell tests", "status"]);
+    assert.ok(out[0].log.length > 0 && out[1].log === "" && out[2].log === "");
+    assert.ok(out.reduce((n, f) => n + f.log.length, 0) <= LOG_CAP + 3);
+    assert.deepEqual(await collectFailedLogs({ failedLogs: async () => { throw new Error("gone"); } }, [{ name: "a", url: "https://x/actions/runs/1" }]), [{ job: "a", url: "https://x/actions/runs/1", log: "" }]);
+  });
+
+  it("parseVerify precheck_timeout_seconds: default 300, integer 1-3600 accepted, others fall back", () => {
+    assert.equal(parseVerify({}).precheckTimeoutSeconds, 300);
+    assert.equal(parseVerify({ precheck_timeout_seconds: "60" }).precheckTimeoutSeconds, 60);
+    for (const bad of ["0", "-5", "1.5", "abc", "3601"]) assert.equal(parseVerify({ precheck_timeout_seconds: bad }).precheckTimeoutSeconds, 300, bad);
+  });
+});
+
+describe("forgedock/verify check run (#4270)", () => {
+  const contract = { requirements: [{ id: "R1", disposition: "deliver" }], deliverables: [{ id: "D1", path: "src/a.ts", change: "x", requirements: ["R1"] }], validate: [{ id: "V1", command: "node --test t.mjs" }, { id: "V2", command: "tsc" }] };
+  const result = { validation: [{ id: "V1", exit: 0 }, { id: "V2", ci: true }], requirements: [{ id: "R1", status: "implemented" }] };
+  const out = (r) => JSON.parse(/```json\n([\s\S]*)\n```/.exec(r.text)[1]);
+
+  it("parseVerify: check_run is true only for the literal true; default false", () => {
+    assert.equal(parseVerify({}).checkRun, false);
+    assert.equal(parseVerify({ check_run: "true" }).checkRun, true);
+    assert.equal(parseVerify({ check_run: true }).checkRun, true);
+    for (const v of ["false", "yes", "1", ""]) assert.equal(parseVerify({ check_run: v }).checkRun, false, v);
+    assert.equal(VERIFY_CHECK_NAME, "forgedock/verify");
+  });
+
+  it("success iff every gate passed; per-gate typed evidence from the computed results", () => {
+    const r = verifyReport({ head: "abc", commands: [{ command: "npm run lint", rc: 0 }], structure: { package_edges_added: [{ from: "@s/a", to: "@s/b", manifest: "packages/a/package.json" }] },
+      docs: { ok: true }, precheck: [], amendments: [], hotspots: true, contract, result });
+    assert.equal(r.conclusion, "success");
+    const g = Object.fromEntries(out(r).gates.map((x) => [x.id, x]));
+    assert.deepEqual(g["precheck.commands"].evidence, [{ command: "npm run lint", rc: 0 }]);
+    assert.deepEqual(g["structure.edges"].evidence, { added: ["@s/a→@s/b (packages/a/package.json)"] });
+    assert.deepEqual(g["conformance.validate"].evidence, [{ id: "V1", command: "node --test t.mjs", exit: 0 }, { id: "V2", command: "tsc", ci: true }]);
+    assert.deepEqual(g["conformance.requirements"].evidence, [{ id: "R1", status: "implemented" }]);
+    assert.ok(Object.values(g).every((x) => x.ok));
+  });
+
+  it("each failing gate is failure with its evidence; gates without input are ok and marked not run", () => {
+    const pre = [
+      { kind: "scope_creep", detail: "changed outside the contract's deliverables: src/x.ts" },
+      { kind: "validate_failed", detail: "validate V1 failed (exit 1)" },
+      { kind: "requirement_unimplemented", detail: "R1 reported \"partial\"" },
+      { kind: "hotspot_growth", detail: "src/big.ts grew by 300 lines" },
+    ];
+    const r = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 2 }], structure: { package_edges_added: [] }, undeclaredEdges: [{ from: "@s/a", to: "@s/b" }],
+      docs: { ok: false, output: "stale devdocs/x.md" }, precheck: pre, amendments: [{ detail: "add-deliverable without why" }], hotspots: true, contract, result });
+    assert.equal(r.conclusion, "failure");
+    const g = Object.fromEntries(r.gates.map((x) => [x.id, x]));
+    assert.ok(r.gates.every((x) => !x.ok), "every gate failed");
+    assert.deepEqual(g["precheck.commands"].evidence, ["lint (exit 2)"]);
+    assert.deepEqual(g["structure.edges"].evidence, ["undeclared @s/a→@s/b"]);
+    assert.match(g["conformance.scope"].evidence[0], /src\/x\.ts/);
+    assert.match(g["maintenance.hotspot_growth"].evidence[0], /src\/big\.ts/);
+    assert.match(r.title, /8 of 8/);
+
+    const none = verifyReport({});
+    assert.ok(none.gates.every((x) => x.ok && !x.ran && x.evidence === "not run"));
+  });
+
+  it("verifyReport with no gate results is neutral with \"no gates ran\" (#4297)", () => {
+    for (const r of [verifyReport({}), verifyReport({ head: "abc" })]) {
+      assert.equal(r.conclusion, "neutral");
+      assert.equal(r.title, "no gates ran");
+      assert.match(r.summary, /no gates ran/);
+      assert.doesNotMatch(`${r.title}\n${r.summary}`, /passed|✅/);
+    }
+    // Only gates that ran are counted: one command round, nothing else.
+    const one = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 0 }] });
+    assert.equal(one.conclusion, "success");
+    assert.equal(one.title, "1 deterministic gate(s) passed");
+    assert.match(one.summary, /`structure\.edges` \(not run\)/);
+    const bad = verifyReport({ head: "abc", commands: [{ command: "lint", rc: 1 }] });
+    assert.equal(bad.conclusion, "failure"); assert.equal(bad.title, "1 of 1 deterministic gate(s) failed");
+  });
+
+  it("the output text stays under the Checks API limit", () => {
+    const r = verifyReport({ precheck: Array.from({ length: 2000 }, (_, i) => ({ kind: "scope_creep", detail: `changed outside: src/${"x".repeat(80)}${i}.ts` })), contract, result });
+    assert.ok(r.text.length < 65535); assert.ok(r.text.length <= VERIFY_TEXT_CAP + 100);
+    assert.equal(r.conclusion, "failure"); assert.equal(out(r).truncated, true);
+  });
+
+  it("runCiVerify never waits on the lane's own forgedock/verify check run", async () => {
+    const f = fake({ checks: [[{ name: "ci", state: "success" }, { name: VERIFY_CHECK_NAME, state: "failure" }]] });
+    const r = await runCiVerify(f.args({ verify: parseVerify({ mode: "ci" }) }));
+    assert.equal(r.result, "pass");
+    const g = fake({ checks: [[{ name: VERIFY_CHECK_NAME, state: "success" }], [{ name: "ci", state: "success" }]] });
+    assert.equal((await runCiVerify(g.args({ verify: parseVerify({ mode: "ci" }) }))).detail, "1 check(s) green", "its own check alone is not CI");
+  });
+});