@kungfu-tech/buildchain 2.11.13 → 2.11.14-alpha.1

package/packages/core/stable-release-gate.js

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STABLE_RELEASE_POLICY_CONTRACT = "kungfu-buildchain-stable-release-policy";
+export const STABLE_RELEASE_GATE_CONTRACT = "kungfu-buildchain-stable-release-gate";
+
+function string(value = "") {
+  return String(value ?? "").trim();
+}
+
+function positiveInteger(value, label) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return number;
+}
+
+function timestamp(value, label) {
+  const normalized = string(value);
+  const milliseconds = Date.parse(normalized);
+  if (!normalized || !Number.isFinite(milliseconds)) {
+    throw new Error(`${label} must be an ISO-8601 timestamp`);
+  }
+  return { iso: new Date(milliseconds).toISOString(), milliseconds };
+}
+
+function loadJsonInput({ cwd = process.cwd(), input = "", label }) {
+  const normalized = string(input);
+  if (!normalized) {
+    return undefined;
+  }
+  if (normalized.startsWith("{")) {
+    return JSON.parse(normalized);
+  }
+  const resolved = path.isAbsolute(normalized) ? normalized : path.resolve(cwd, normalized);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`${label} path does not exist: ${normalized}`);
+  }
+  return JSON.parse(fs.readFileSync(resolved, "utf8"));
+}
+
+export function loadStableReleasePolicy({ cwd = process.cwd(), input = "" } = {}) {
+  const policy = loadJsonInput({ cwd, input, label: "stable release policy" });
+  if (!policy) {
+    return undefined;
+  }
+  if (policy.contract !== STABLE_RELEASE_POLICY_CONTRACT) {
+    throw new Error(`stable release policy contract must be ${STABLE_RELEASE_POLICY_CONTRACT}`);
+  }
+  if (Number(policy.schemaVersion) !== 1) {
+    throw new Error("stable release policy schemaVersion must be 1");
+  }
+  const minimumStableIntervalSeconds = positiveInteger(
+    policy.minimumStableIntervalSeconds,
+    "minimumStableIntervalSeconds",
+  );
+  const minimumCanarySoakSeconds = positiveInteger(
+    policy.minimumCanarySoakSeconds,
+    "minimumCanarySoakSeconds",
+  );
+  const productPathPrefixes = [...new Set(
+    (Array.isArray(policy.productPathPrefixes) ? policy.productPathPrefixes : [])
+      .map(string)
+      .filter(Boolean),
+  )];
+  if (productPathPrefixes.length === 0) {
+    throw new Error("stable release policy requires productPathPrefixes[]");
+  }
+  const requiredCanaries = (Array.isArray(policy.requiredCanaries) ? policy.requiredCanaries : [])
+    .map((canary, index) => {
+      const id = string(canary?.id);
+      const source = string(canary?.source);
+      if (!id) {
+        throw new Error(`requiredCanaries[${index}].id is required`);
+      }
+      if (!new Set(["release-candidate", "commit-status"]).has(source)) {
+        throw new Error(`requiredCanaries[${index}].source must be release-candidate or commit-status`);
+      }
+      if (source === "commit-status" && !string(canary.context)) {
+        throw new Error(`requiredCanaries[${index}].context is required for commit-status canaries`);
+      }
+      return {
+        id,
+        source,
+        repository: string(canary.repository),
+        workflow: string(canary.workflow),
+        context: string(canary.context),
+        allowedAttestors: [...new Set(
+          (Array.isArray(canary.allowedAttestors) ? canary.allowedAttestors : [])
+            .map(string)
+            .filter(Boolean),
+        )],
+      };
+    });
+  if (requiredCanaries.length === 0) {
+    throw new Error("stable release policy requires requiredCanaries[]");
+  }
+  if (new Set(requiredCanaries.map((canary) => canary.id)).size !== requiredCanaries.length) {
+    throw new Error("stable release policy canary ids must be unique");
+  }
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_POLICY_CONTRACT,
+    enabled: policy.enabled !== false,
+    minimumStableIntervalSeconds,
+    minimumCanarySoakSeconds,
+    productPathPrefixes,
+    requiredCanaries,
+  };
+}
+
+function check(ok, id, message, details = {}) {
+  return { id, status: ok ? "pass" : "fail", message, details };
+}
+
+function matchesProductPath(file, prefixes) {
+  return prefixes.some((prefix) => file === prefix || file.startsWith(prefix));
+}
+
+export function evaluateStableReleaseGate({
+  policy,
+  channel = "",
+  candidate = {},
+  previousStable = undefined,
+  changedPaths = [],
+  impact = {},
+  canaries = [],
+  now = new Date().toISOString(),
+} = {}) {
+  const normalizedChannel = string(channel);
+  if (!policy || policy.enabled === false || normalizedChannel !== "release") {
+    return {
+      schemaVersion: 1,
+      contract: STABLE_RELEASE_GATE_CONTRACT,
+      applies: false,
+      ok: true,
+      channel: normalizedChannel,
+      checks: [],
+      summary: { reason: !policy ? "policy-not-configured" : policy.enabled === false ? "policy-disabled" : "non-stable-channel" },
+    };
+  }
+
+  const nowTime = timestamp(now, "now");
+  const candidatePublished = timestamp(candidate.publishedAt, "candidate.publishedAt");
+  const candidateSha = string(candidate.sha);
+  const candidateTag = string(candidate.tag);
+  const checks = [];
+  checks.push(check(/^[0-9a-f]{40}$/i.test(candidateSha), "candidate.sha", "candidate alpha SHA is exact", { sha: candidateSha }));
+  checks.push(check(/-alpha\.\d+$/.test(candidateTag), "candidate.tag", "candidate is an exact alpha tag", { tag: candidateTag }));
+
+  if (previousStable) {
+    const previousPublished = timestamp(previousStable.publishedAt, "previousStable.publishedAt");
+    const elapsedSeconds = Math.floor((nowTime.milliseconds - previousPublished.milliseconds) / 1000);
+    checks.push(check(
+      elapsedSeconds >= policy.minimumStableIntervalSeconds,
+      "stable.minimum_interval",
+      "minimum interval since the previous stable release is satisfied",
+      {
+        previousTag: string(previousStable.tag),
+        previousPublishedAt: previousPublished.iso,
+        elapsedSeconds,
+        requiredSeconds: policy.minimumStableIntervalSeconds,
+      },
+    ));
+  } else {
+    checks.push(check(true, "stable.minimum_interval", "no previous stable release exists", { firstStable: true }));
+  }
+
+  const normalizedChangedPaths = [...new Set(changedPaths.map(string).filter(Boolean))].sort();
+  const productChangedPaths = normalizedChangedPaths.filter((file) =>
+    matchesProductPath(file, policy.productPathPrefixes));
+  checks.push(check(
+    productChangedPaths.length > 0,
+    "stable.product_diff",
+    "candidate contains a product or contract difference from the current stable release",
+    { changedPaths: productChangedPaths, comparedPathCount: normalizedChangedPaths.length },
+  ));
+
+  const surfaceImpacts = Array.isArray(impact?.surfaceImpacts) ? impact.surfaceImpacts : [];
+  checks.push(check(
+    surfaceImpacts.length > 0 && string(impact?.summary) !== "",
+    "stable.impact",
+    "version-bound impact declares a summary and at least one surface",
+    { summary: string(impact?.summary), surfaceIds: surfaceImpacts.map((entry) => string(entry?.id)).filter(Boolean) },
+  ));
+
+  const canaryById = new Map(canaries.map((canary) => [string(canary?.id), canary]));
+  const canaryCompletionTimes = [];
+  for (const required of policy.requiredCanaries) {
+    const evidence = canaryById.get(required.id);
+    const completedAt = evidence?.completedAt
+      ? timestamp(evidence.completedAt, `canary ${required.id} completedAt`)
+      : undefined;
+    const attestorAllowed = required.allowedAttestors.length === 0 ||
+      required.allowedAttestors.includes(string(evidence?.attestor));
+    const valid = Boolean(
+      evidence &&
+      string(evidence.status) === "success" &&
+      string(evidence.candidateSha) === candidateSha &&
+      completedAt &&
+      completedAt.milliseconds >= candidatePublished.milliseconds &&
+      attestorAllowed,
+    );
+    if (completedAt) {
+      canaryCompletionTimes.push(completedAt.milliseconds);
+    }
+    checks.push(check(
+      valid,
+      `stable.canary.${required.id}`,
+      `required canary ${required.id} passed for the exact alpha candidate`,
+      {
+        source: required.source,
+        context: required.context,
+        repository: string(evidence?.repository || required.repository),
+        workflow: string(evidence?.workflow || required.workflow),
+        runtimeRef: string(evidence?.runtimeRef),
+        candidateSha: string(evidence?.candidateSha),
+        completedAt: completedAt?.iso || "",
+        evidenceUrl: string(evidence?.evidenceUrl),
+        attestor: string(evidence?.attestor),
+        attestorAllowed,
+      },
+    ));
+  }
+
+  const soakStartMilliseconds = Math.max(candidatePublished.milliseconds, ...canaryCompletionTimes);
+  const soakElapsedSeconds = Math.floor((nowTime.milliseconds - soakStartMilliseconds) / 1000);
+  checks.push(check(
+    canaryCompletionTimes.length === policy.requiredCanaries.length &&
+      soakElapsedSeconds >= policy.minimumCanarySoakSeconds,
+    "stable.canary_soak",
+    "minimum soak interval after the final required canary is satisfied",
+    {
+      soakStartedAt: new Date(soakStartMilliseconds).toISOString(),
+      elapsedSeconds: soakElapsedSeconds,
+      requiredSeconds: policy.minimumCanarySoakSeconds,
+    },
+  ));
+
+  const ok = checks.every((entry) => entry.status === "pass");
+  return {
+    schemaVersion: 1,
+    contract: STABLE_RELEASE_GATE_CONTRACT,
+    applies: true,
+    ok,
+    channel: normalizedChannel,
+    evaluatedAt: nowTime.iso,
+    candidate: {
+      tag: candidateTag,
+      sha: candidateSha,
+      publishedAt: candidatePublished.iso,
+    },
+    previousStable: previousStable
+      ? {
+          tag: string(previousStable.tag),
+          sha: string(previousStable.sha),
+          publishedAt: timestamp(previousStable.publishedAt, "previousStable.publishedAt").iso,
+        }
+      : undefined,
+    policy: {
+      minimumStableIntervalSeconds: policy.minimumStableIntervalSeconds,
+      minimumCanarySoakSeconds: policy.minimumCanarySoakSeconds,
+      requiredCanaries: policy.requiredCanaries.map((canary) => canary.id),
+    },
+    checks,
+    summary: {
+      decision: ok ? "allow" : "block",
+      failedChecks: checks.filter((entry) => entry.status === "fail").map((entry) => entry.id),
+      productChangedPaths,
+    },
+  };
+}
+
+export function assertStableReleaseGate(input = {}) {
+  const report = evaluateStableReleaseGate(input);
+  if (!report.ok) {
+    throw Object.assign(
+      new Error(`stable release gate blocked promotion: ${report.summary.failedChecks.join(", ")}`),
+      { report },
+    );
+  }
+  return report;
+}

package/scripts/check-inventory.mjs

@@ -725,6 +725,8 @@ for (const requiredSnippet of [
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
   "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
+  "Enforce Buildchain stable release canary gate",
+  "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
     throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);

package/scripts/generate-site-bundle.mjs

@@ -406,6 +406,7 @@ function cliCommandMeta(id) {
     "kfd-1-witness": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-1 self contract-world witness." },
     "kfd-2": { group: "kfd-trust", purpose: "Inspect KFD-2 trust taxonomy, public claims, and schema command families." },
     "kfd-2-claims": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-2 public trust claim evidence." },
+    "kfd-2-product-claims": { group: "kfd-trust", purpose: "Validate and render product-owned KFD-2 claims in the canonical .buildchain/kfd layout." },
     "kfd-2-schema": { group: "kfd-trust", purpose: "Print the default KFD-2 schema exposed by the KFD package standards metadata." },
     "kfd-2-taxonomy": { group: "kfd-trust", purpose: "Validate KFD-2 trust taxonomy entries from the KFD package standards metadata." },
     "kfd-2-trust-assessment": { group: "kfd-trust", purpose: "Expose and validate the KFD package foundation KFD-2 trust assessment." },

package/scripts/stable-release-gate.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  assertStableReleaseGate,
+  evaluateStableReleaseGate,
+  loadStableReleasePolicy,
+} from "../packages/core/stable-release-gate.js";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function splitRepository(repository) {
+  const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`repository must be owner/repo, got ${repository || "<empty>"}`);
+  }
+  return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+
+function githubHeaders(token) {
+  return {
+    accept: "application/vnd.github+json",
+    ...(token ? { authorization: `Bearer ${token}` } : {}),
+    "user-agent": "buildchain-stable-release-gate",
+    "x-github-api-version": "2022-11-28",
+  };
+}
+
+async function githubJson({
+  apiUrl = "https://api.github.com",
+  token = "",
+  requestPath,
+  fetchImpl = globalThis.fetch,
+}) {
+  const response = await fetchImpl(`${apiUrl.replace(/\/+$/, "")}${requestPath}`, {
+    headers: githubHeaders(token),
+  });
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : undefined;
+  if (!response.ok) {
+    throw new Error(`GitHub API GET ${requestPath} failed with ${response.status}: ${body?.message || text}`);
+  }
+  return body;
+}
+
+function parseAlphaVersion(version) {
+  const normalized = String(version || "").replace(/^v/, "").trim();
+  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)-alpha\.(\d+)$/);
+  if (!match) {
+    throw new Error(`stable release gate requires an exact alpha version, got ${version || "<empty>"}`);
+  }
+  return {
+    version: normalized,
+    tag: `v${normalized}`,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+}
+
+async function resolveTagCommitSha({ api, repository, tag }) {
+  const ref = await api(`/repos/${repository.owner}/${repository.repo}/git/ref/tags/${encodeURIComponent(tag)}`);
+  let sha = ref.object?.sha || "";
+  if (ref.object?.type === "tag") {
+    const annotated = await api(`/repos/${repository.owner}/${repository.repo}/git/tags/${sha}`);
+    sha = annotated.object?.sha || "";
+  }
+  if (!/^[0-9a-f]{40}$/i.test(sha)) {
+    throw new Error(`tag ${tag} did not resolve to a 40-character commit SHA`);
+  }
+  return sha;
+}
+
+function selectPreviousStable({ releases = [], candidate }) {
+  const prefix = `v${candidate.major}.${candidate.minor}.`;
+  return releases
+    .map((release) => {
+      const match = String(release.tag_name || "").match(
+        new RegExp(`^${prefix.replaceAll(".", "\\.")}(\\d+)$`),
+      );
+      return match ? { release, patch: Number(match[1]) } : undefined;
+    })
+    .filter((entry) => entry && entry.patch < candidate.patch && entry.release.published_at)
+    .sort((left, right) => right.patch - left.patch)[0]?.release;
+}
+
+function loadImpact({ cwd, input }) {
+  const normalized = String(input || "").trim();
+  if (!normalized) {
+    return {};
+  }
+  if (normalized.startsWith("{")) {
+    return JSON.parse(normalized);
+  }
+  const resolved = path.isAbsolute(normalized) ? normalized : path.resolve(cwd, normalized);
+  return JSON.parse(fs.readFileSync(resolved, "utf8"));
+}
+
+function parseRunUrl(url = "") {
+  const match = String(url).match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)\/actions\/runs\/(\d+)/);
+  return match
+    ? { owner: match[1], repo: match[2], repository: `${match[1]}/${match[2]}`, runId: match[3] }
+    : undefined;
+}
+
+async function resolveCanaryEvidence({
+  api,
+  repository,
+  policy,
+  candidateTag,
+  candidateSha,
+  releaseCandidateRunId,
+  releaseCandidateRunUrl,
+}) {
+  let statuses;
+  const evidence = [];
+  for (const canary of policy.requiredCanaries) {
+    if (canary.source === "release-candidate") {
+      if (!releaseCandidateRunId) {
+        evidence.push({ id: canary.id, status: "missing", candidateSha });
+        continue;
+      }
+      const run = await api(
+        `/repos/${repository.owner}/${repository.repo}/actions/runs/${encodeURIComponent(releaseCandidateRunId)}`,
+      );
+      const workflowMatches = !canary.workflow ||
+        canary.workflow === run.name || canary.workflow === run.path?.split("/").pop();
+      evidence.push({
+        id: canary.id,
+        status: run.conclusion === "success" && workflowMatches ? "success" : run.conclusion || "failure",
+        candidateSha,
+        completedAt: run.updated_at || run.run_started_at || "",
+        evidenceUrl: run.html_url || releaseCandidateRunUrl,
+        repository: repository.fullName,
+        workflow: run.name || run.path || "",
+        attestor: run.actor?.login || run.triggering_actor?.login || "",
+      });
+      continue;
+    }
+
+    statuses ||= await api(
+      `/repos/${repository.owner}/${repository.repo}/commits/${candidateSha}/statuses?per_page=100`,
+    );
+    const status = statuses.find((entry) => entry.context === canary.context);
+    const targetRun = parseRunUrl(status?.target_url);
+    let targetRunEvidence;
+    if (targetRun && (!canary.repository || targetRun.repository === canary.repository)) {
+      targetRunEvidence = await api(
+        `/repos/${targetRun.owner}/${targetRun.repo}/actions/runs/${targetRun.runId}`,
+      );
+    }
+    const workflowMatches = !canary.workflow ||
+      canary.workflow === targetRunEvidence?.name ||
+      canary.workflow === targetRunEvidence?.path?.split("/").pop();
+    const repositoryMatches = !canary.repository || targetRun?.repository === canary.repository;
+    const runtimeRef = String(
+      targetRunEvidence?.inputs?.buildchain_ref ||
+      targetRunEvidence?.inputs?.buildchainRef ||
+      "",
+    ).trim();
+    const runtimeRefMatches = runtimeRef === candidateTag;
+    evidence.push({
+      id: canary.id,
+      status:
+        status?.state === "success" &&
+        targetRunEvidence?.conclusion === "success" &&
+        workflowMatches &&
+        repositoryMatches &&
+        runtimeRefMatches
+          ? "success"
+          : status?.state || "missing",
+      candidateSha,
+      completedAt: targetRunEvidence?.updated_at || status?.updated_at || "",
+      evidenceUrl: status?.target_url || "",
+      repository: targetRun?.repository || canary.repository,
+      workflow: targetRunEvidence?.name || targetRunEvidence?.path || "",
+      attestor: status?.creator?.login || "",
+      runtimeRef,
+    });
+  }
+  return evidence;
+}
+
+export async function collectStableReleaseGateReport({
+  cwd = process.cwd(),
+  repository: repositoryInput,
+  channel = "",
+  policyInput = ".buildchain/stable-release-policy.json",
+  impactInput = ".buildchain/release-impact.json",
+  candidateVersion = "",
+  releaseCandidateRunId = "",
+  releaseCandidateRunUrl = "",
+  now = new Date().toISOString(),
+  apiUrl = "https://api.github.com",
+  token = "",
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const policy = loadStableReleasePolicy({ cwd, input: policyInput });
+  if (!policy || policy.enabled === false || channel !== "release") {
+    return evaluateStableReleaseGate({ policy, channel });
+  }
+  const repository = splitRepository(repositoryInput);
+  const candidate = parseAlphaVersion(candidateVersion);
+  const api = (requestPath) => githubJson({ apiUrl, token, requestPath, fetchImpl });
+  const [candidateRelease, releases, candidateSha] = await Promise.all([
+    api(`/repos/${repository.owner}/${repository.repo}/releases/tags/${encodeURIComponent(candidate.tag)}`),
+    api(`/repos/${repository.owner}/${repository.repo}/releases?per_page=100`),
+    resolveTagCommitSha({ api, repository, tag: candidate.tag }),
+  ]);
+  const previousRelease = selectPreviousStable({ releases, candidate });
+  const previousSha = previousRelease
+    ? await resolveTagCommitSha({ api, repository, tag: previousRelease.tag_name })
+    : "";
+  const comparison = previousRelease
+    ? await api(
+        `/repos/${repository.owner}/${repository.repo}/compare/${encodeURIComponent(previousRelease.tag_name)}...${encodeURIComponent(candidate.tag)}`,
+      )
+    : { files: [] };
+  const canaries = await resolveCanaryEvidence({
+    api,
+    repository,
+    policy,
+    candidateTag: candidate.tag,
+    candidateSha,
+    releaseCandidateRunId,
+    releaseCandidateRunUrl,
+  });
+  return assertStableReleaseGate({
+    policy,
+    channel,
+    candidate: {
+      tag: candidate.tag,
+      sha: candidateSha,
+      publishedAt: candidateRelease.published_at,
+    },
+    previousStable: previousRelease
+      ? {
+          tag: previousRelease.tag_name,
+          sha: previousSha,
+          publishedAt: previousRelease.published_at,
+        }
+      : undefined,
+    changedPaths: (comparison.files || []).map((file) => file.filename),
+    impact: loadImpact({ cwd, input: impactInput }),
+    canaries,
+    now,
+  });
+}
+
+export async function stableReleaseGateCli() {
+  const cwd = process.cwd();
+  const policyInput = env("BUILDCHAIN_STABLE_RELEASE_POLICY", ".buildchain/stable-release-policy.json");
+  const outputPath = env(
+    "BUILDCHAIN_STABLE_RELEASE_GATE_OUTPUT",
+    ".buildchain/release-passport/stable-release-gate.json",
+  );
+  const report = await collectStableReleaseGateReport({
+    cwd,
+    repository: env("GITHUB_REPOSITORY"),
+    channel: env("BUILDCHAIN_PROMOTION_CHANNEL"),
+    policyInput,
+    impactInput: env("BUILDCHAIN_RELEASE_IMPACT", ".buildchain/release-impact.json"),
+    candidateVersion: env("BUILDCHAIN_RELEASE_CANDIDATE_VERSION"),
+    releaseCandidateRunId: env("BUILDCHAIN_RELEASE_CANDIDATE_RUN_ID"),
+    releaseCandidateRunUrl: env("BUILDCHAIN_RELEASE_CANDIDATE_RUN_URL"),
+    apiUrl: env("GITHUB_API_URL", "https://api.github.com"),
+    token: env("GITHUB_TOKEN"),
+  });
+  const resolvedOutput = path.isAbsolute(outputPath) ? outputPath : path.resolve(cwd, outputPath);
+  fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+  fs.writeFileSync(resolvedOutput, `${JSON.stringify(report, null, 2)}\n`);
+  console.log(`stable-release-gate=${report.applies ? report.summary.decision : report.summary.reason}`);
+  console.log(`stable-release-gate-report=${path.relative(cwd, resolvedOutput).split(path.sep).join("/")}`);
+  return report;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  stableReleaseGateCli().catch((error) => {
+    const report = error?.report;
+    if (report) {
+      const outputPath = env(
+        "BUILDCHAIN_STABLE_RELEASE_GATE_OUTPUT",
+        ".buildchain/release-passport/stable-release-gate.json",
+      );
+      const resolvedOutput = path.resolve(process.cwd(), outputPath);
+      fs.mkdirSync(path.dirname(resolvedOutput), { recursive: true });
+      fs.writeFileSync(resolvedOutput, `${JSON.stringify(report, null, 2)}\n`);
+    }
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  });
+}