@kungfu-tech/buildchain 4.1.0 → 4.1.1-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.1.0",
+  "version": "4.1.1-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/providers/github/graphql-errors.js

@@ -0,0 +1,34 @@
+export function createGitHubGraphqlError(errors) {
+  const details = errors.map((error) => ({
+    message: typeof error.message === "string" ? error.message : "",
+    ...(error.type ? { type: error.type } : {}),
+    ...(error.extensions?.code
+      ? { extensions: { code: error.extensions.code } }
+      : {}),
+  }));
+  return Object.assign(
+    new Error(
+      details
+        .map((error) => error.message)
+        .filter(Boolean)
+        .join("; ") || "GitHub GraphQL request failed",
+    ),
+    { errors: details },
+  );
+}
+
+export function isTransientGitHubGraphqlError(error) {
+  const errors = error?.errors;
+  return (
+    Array.isArray(errors) &&
+    errors.length > 0 &&
+    errors.every((detail) => {
+      const code = detail.type || detail.extensions?.code;
+      return code
+        ? code === "INTERNAL"
+        : /^Something went wrong while executing your query on /u.test(
+            detail.message || "",
+          );
+    })
+  );
+}

package/packages/core/providers/github/qualification-artifacts.js

@@ -0,0 +1,88 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const LIMIT = 8 * 1024 * 1024;
+
+export function readPublicBuildArchive(archive, digest) {
+  if (
+    archive.length > LIMIT ||
+    `sha256:${createHash("sha256").update(archive).digest("hex")}` !== digest
+  )
+    throw new Error("public build artifact digest or size mismatch");
+  const script = [
+    "import io,sys,zipfile",
+    "z=zipfile.ZipFile(io.BytesIO(sys.stdin.buffer.read()))",
+    "entries=[e for e in z.infolist() if e.filename=='build-summary.json']",
+    "assert len(entries)==1 and entries[0].file_size <= 1048576, 'invalid public build archive'",
+    "sys.stdout.buffer.write(z.read(entries[0]))",
+  ].join("\n");
+  return JSON.parse(
+    execFileSync(
+      process.platform === "win32" ? "python" : "python3",
+      ["-c", script],
+      { input: archive, encoding: "utf8", maxBuffer: 1048576 },
+    ),
+  );
+}
+
+export async function fetchQualificationArchive({
+  apiUrl,
+  token,
+  endpoint,
+  fetchImpl,
+}) {
+  let response = await fetchImpl(`${apiUrl.replace(/\/+$/, "")}${endpoint}`, {
+    redirect: "manual",
+    headers: {
+      accept: "application/vnd.github+json",
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+  });
+  if (response.status === 302) {
+    const location = new URL(response.headers.get("location"));
+    if (location.protocol !== "https:")
+      throw new Error("invalid artifact download redirect");
+    response = await fetchImpl(location.href, { redirect: "error" });
+  }
+  if (!response.ok)
+    throw new Error(
+      `public build artifact download failed: ${response.status}`,
+    );
+  if (Number(response.headers.get("content-length")) > LIMIT)
+    throw new Error("public build archive exceeds size limit");
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > LIMIT)
+      throw new Error("public build archive exceeds size limit");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function readPublicBuildArtifact({
+  api,
+  fetchArchive,
+  repository,
+  run,
+}) {
+  const prefix = `/repos/${repository}/actions`;
+  const assets = await api(`${prefix}/runs/${run.id}/artifacts?per_page=100`);
+  const matches = (assets.artifacts || []).filter(
+    (asset) => asset.name === `buildchain-summary-${run.head_sha}`,
+  );
+  if (
+    matches.length !== 1 ||
+    matches[0].expired ||
+    matches[0].size_in_bytes > LIMIT
+  )
+    throw new Error(
+      "public build summary artifact missing, ambiguous or expired",
+    );
+  const asset = matches[0];
+  return readPublicBuildArchive(
+    await fetchArchive(`${prefix}/artifacts/${asset.id}/zip`),
+    asset.digest,
+  );
+}

package/packages/core/providers/github-cli-api.js

@@ -1,26 +1,60 @@
-import { command } from "../runtime/action-process.mjs";
+import { execFileSync } from "node:child_process";
+import { createGitHubGraphqlError } from "./github/graphql-errors.js";
 
-export function createGitHubCliApi(execute = command, env = process.env) {
+function apiFailure(cause) {
+  let response;
+  try {
+    response = JSON.parse(String(cause.stdout || ""));
+  } catch {
+    // Process diagnostics are not a provider response and may contain secrets.
+  }
+  const messages = Array.isArray(response?.errors)
+    ? response.errors
+        .map((error) => error.message)
+        .filter((message) => typeof message === "string")
+    : [];
+  const message =
+    messages.join("; ") ||
+    (typeof response?.message === "string" ? response.message : "") ||
+    `GitHub API command failed with exit code ${cause.status ?? 1}`;
+  const error = messages.length
+    ? createGitHubGraphqlError(response.errors)
+    : new Error(message);
+  error.exitCode = cause.status ?? 1;
+  const status = Number(response?.status);
+  if (Number.isInteger(status) && status >= 100 && status <= 599)
+    error.status = status;
+  if (cause.code) error.code = cause.code;
+  return error;
+}
+
+export function createGitHubCliApi(execute = execFileSync, env = process.env) {
   function invoke(method, endpoint, body, flags = []) {
-    const output = execute(
-      "gh",
-      [
-        "api",
-        "--method",
-        method,
-        endpoint,
-        "-H",
-        "Accept: application/vnd.github+json",
-        ...flags,
-        ...(body === undefined ? [] : ["--input", "-"]),
-      ],
-      {
-        env,
-        input: body === undefined ? undefined : JSON.stringify(body),
-        maxBuffer: 8 * 1024 * 1024,
-        stdio: ["pipe", "pipe", "pipe"],
-      },
-    );
+    let output;
+    try {
+      output = execute(
+        "gh",
+        [
+          "api",
+          "--method",
+          method,
+          endpoint,
+          "-H",
+          "Accept: application/vnd.github+json",
+          ...flags,
+          ...(body === undefined ? [] : ["--input", "-"]),
+        ],
+        {
+          env,
+          encoding: "utf8",
+          input: body === undefined ? undefined : JSON.stringify(body),
+          maxBuffer: 8 * 1024 * 1024,
+          stdio: ["pipe", "pipe", "pipe"],
+        },
+      );
+    } catch (error) {
+      throw apiFailure(error);
+    }
     return output?.trim() ? JSON.parse(output) : {};
   }
   return {

package/packages/core/release/commands/stable-release-gate.mjs

@@ -2,6 +2,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { fetchQualificationArchive } from "../../providers/github/qualification-artifacts.js";
+import { resolvePublicBuildCanaryEvidence } from "../qualification/canary-evidence.js";
 import {
   assertStableReleaseGate,
   evaluateStableReleaseGate,
@@ -278,12 +280,16 @@ export async function collectStableReleaseGateReport({
   const canaries = await resolveCanaryEvidence({
     api,
     repository,
-    policy,
+    policy: { ...policy, requiredCanaries: policy.requiredCanaries.filter((entry) => entry.source !== "public-build") },
     candidateTag: candidate.tag,
     candidateSha,
     releaseCandidateRunId,
     releaseCandidateRunUrl,
   });
+  canaries.push(...await resolvePublicBuildCanaryEvidence({
+    api, policy, candidateSha, repository: repository.fullName,
+    fetchArchive: (endpoint) => fetchQualificationArchive({ apiUrl, token, endpoint, fetchImpl }),
+  }));
   return assertStableReleaseGate({
     policy,
     channel,

package/packages/core/release/next-development/enqueue.js

@@ -2,6 +2,7 @@ import { requireCurrentIndependentApproval } from "./approval.js";
 import { REVIEWER } from "./review-policy.js";
 import { observe } from "./observation.js";
 import { enqueueNextDevelopmentPullRequest } from "../promote-candidate/next-development-queue.js";
+import { createGitHubGraphqlError } from "../../providers/github/graphql-errors.js";
 export async function enqueueVerifiedDevelopmentReview({
   client,
   repository,
@@ -39,9 +40,7 @@ export async function enqueueVerifiedDevelopmentReview({
       graphql: async (query, variables) => {
         const result = client.post("graphql", { query, variables });
         if (result.errors?.length)
-          throw new Error(
-            result.errors.map((error) => error.message).join("; "),
-          );
+          throw createGitHubGraphqlError(result.errors);
         return result.data;
       },
     },

package/packages/core/release/promote-candidate/next-development-queue-observation.js

@@ -0,0 +1,25 @@
+export async function observeNextDevelopmentQueue({
+  mutationOctokit,
+  pull,
+  headSha,
+}) {
+  const { node } = await mutationOctokit.graphql(
+    `query BuildchainObserveQueuedPullRequest($id: ID!) {
+      node(id: $id) { ... on PullRequest {
+        id headRefOid baseRefName state merged mergeQueueEntry { id }
+      } }
+    }`,
+    { id: pull.node_id },
+  );
+  if (
+    node?.id !== pull.node_id ||
+    node.headRefOid !== headSha ||
+    (pull.base?.ref && node.baseRefName !== pull.base.ref) ||
+    !["OPEN", "MERGED"].includes(node.state) ||
+    node.merged !== (node.state === "MERGED")
+  )
+    throw new Error(
+      "next-development queue readback cannot prove the exact open or merged pull request",
+    );
+  return node.merged || Boolean(node.mergeQueueEntry?.id);
+}

package/packages/core/release/promote-candidate/next-development-queue.js

@@ -4,6 +4,21 @@ const MAX_TRANSPORT_RETRIES = 4;
 export function nextDevelopmentQueueFailure(error) {
   const status = Number(error?.status || error?.response?.status || 0);
   const message = String(error?.message || "");
+  if (
+    [401, 403, 404, 409, 422].includes(status) &&
+    !(status === 403 && /rate limit/iu.test(message))
+  )
+    return "rejected";
+  if (Array.isArray(error?.errors) && error.errors.length) {
+    if (isTransientGitHubGraphqlError(error)) return "transient";
+    const kinds = error.errors.map((detail) => {
+      const code = detail.type || detail.extensions?.code;
+      return code && code !== "UNPROCESSABLE"
+        ? "rejected"
+        : nextDevelopmentQueueFailure({ message: detail.message });
+    });
+    return kinds.every((kind) => kind === kinds[0]) ? kinds[0] : "rejected";
+  }
   if (/already.*queue|queue.*already/iu.test(message)) return "queued";
   if (/already.*merged|merged.*already/iu.test(message)) return "merged";
   if (
@@ -28,6 +43,16 @@ export function assertNextDevelopmentPull(pull, headSha, base) {
     throw new Error("next-development pull request was closed without merge");
 }
 
+async function recoverQueuedMutation(options) {
+  try {
+    return await observeNextDevelopmentQueue(options);
+  } catch (error) {
+    if (nextDevelopmentQueueFailure(error) !== "transient")
+      throw Object.assign(error, { releaseTailClass: "conflict" });
+    return false;
+  }
+}
+
 export async function enqueueNextDevelopmentPullRequest({
   mutationOctokit,
   pull,
@@ -48,6 +73,11 @@ export async function enqueueNextDevelopmentPullRequest({
     } catch (error) {
       const kind = nextDevelopmentQueueFailure(error);
       if (kind === "queued" || kind === "merged") return;
+      if (
+        kind === "transient" &&
+        (await recoverQueuedMutation({ mutationOctokit, pull, headSha }))
+      )
+        return;
       if (
         kind === "rejected" ||
         poll === maxPolls ||
@@ -61,3 +91,5 @@ export async function enqueueNextDevelopmentPullRequest({
     }
   }
 }
+import { isTransientGitHubGraphqlError } from "../../providers/github/graphql-errors.js";
+import { observeNextDevelopmentQueue } from "./next-development-queue-observation.js";

package/packages/core/release/qualification/canary-evidence.js

@@ -0,0 +1,89 @@
+import { readPublicBuildArtifact } from "../../providers/github/qualification-artifacts.js";
+import {
+  resolveStableCandidateQualificationCandidate,
+  validatePublicBuildRun,
+} from "./public-build.js";
+
+async function readCanary({
+  api,
+  fetchArchive,
+  repository,
+  candidateSha,
+  canary,
+  statuses,
+}) {
+  const status = statuses.find((entry) => entry.context === canary.context);
+  const evidence = {
+    id: canary.id,
+    candidateSha,
+    status: "missing",
+    attestor: status?.creator?.login || "",
+  };
+  if (!status || status.state !== "success") return evidence;
+  const target =
+    /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/([1-9][0-9]*)\/?$/u.exec(
+      status.target_url || "",
+    );
+  if (!target || target[1] !== repository || canary.repository !== repository)
+    return { ...evidence, status: "mismatched" };
+  const prefix = `/repos/${repository}/actions`;
+  const run = await api(`${prefix}/runs/${target[2]}`);
+  const workflow = await api(`${prefix}/workflows/${run.workflow_id}`);
+  validatePublicBuildRun(run, workflow, repository);
+  if (
+    ![workflow.name, workflow.path?.split("/").pop()].includes(canary.workflow)
+  )
+    throw new Error("public build canary workflow differs from policy");
+  const summary = await readPublicBuildArtifact({
+    api,
+    fetchArchive,
+    repository,
+    run,
+  });
+  const runtimeSha = resolveStableCandidateQualificationCandidate({
+    repositoryName: repository,
+    sourceRun: run,
+    buildSummary: summary,
+  });
+  if (runtimeSha !== candidateSha)
+    throw new Error("public build canary does not qualify the exact candidate");
+  return {
+    ...evidence,
+    status: "success",
+    completedAt: run.updated_at,
+    evidenceUrl: status.target_url,
+    repository,
+    workflow: workflow.name,
+    workflowId: workflow.id,
+    runtimeRef: runtimeSha,
+    runtimeRefSource: "public-build-summary",
+  };
+}
+
+export async function resolvePublicBuildCanaryEvidence({
+  api,
+  fetchArchive,
+  repository,
+  candidateSha,
+  policy,
+}) {
+  const canaries = policy.requiredCanaries.filter(
+    (entry) => entry.source === "public-build",
+  );
+  if (!canaries.length) return [];
+  const statuses = await api(
+    `/repos/${repository}/commits/${candidateSha}/statuses?per_page=100`,
+  );
+  return Promise.all(
+    canaries.map((canary) =>
+      readCanary({
+        api,
+        fetchArchive,
+        repository,
+        candidateSha,
+        canary,
+        statuses,
+      }),
+    ),
+  );
+}

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

@@ -74,10 +74,10 @@ export function loadStableReleasePolicy({ cwd = process.cwd(), input = "" } = {}
       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 (!new Set(["release-candidate", "commit-status", "public-build"]).has(source)) {
+        throw new Error(`requiredCanaries[${index}].source must be release-candidate, commit-status or public-build`);
       }
-      if (source === "commit-status" && !string(canary.context)) {
+      if (source !== "release-candidate" && !string(canary.context)) {
         throw new Error(`requiredCanaries[${index}].context is required for commit-status canaries`);
       }
       return {

package/scripts/check-inventory.mjs

@@ -281,7 +281,7 @@ for (const [channel, ref] of [["alpha", `v${selfDogfoodMajor}-alpha`], ["stable"
   const workflow = fs.readFileSync(path.join(root, `.github/workflows/self-build-${channel}-dogfood.yml`), "utf8");
   if (!workflow.includes(`/.github/workflows/build.yml@${ref}`) || /steps:|buildchain-channel:|runner-preset:|working-directory:/u.test(workflow)) throw new Error(`${channel} self-dogfood must remain a thin public TOML build caller`);
   if (!workflow.includes(`group: buildchain-${channel}-self-dogfood-`) || !workflow.includes("cancel-in-progress: false")) throw new Error(`${channel} self-dogfood must serialize its own runs`);
-  const expectedInputs = channel === "alpha" ? [] : ["config-path"];
+  const expectedInputs = [];
   const call = parseWorkflowCallJobs(workflow).find((job) => job.id === `${channel}-consumer`);
   if (JSON.stringify(Object.keys(call.with || {})) !== JSON.stringify(expectedInputs)) throw new Error(`${channel} self-dogfood input contract drift`);
 }