@kungfu-tech/buildchain 3.0.6-alpha.0 → 3.0.6-alpha.10

package/scripts/dev-pr-delivery-warrant.mjs

@@ -0,0 +1,209 @@
+import fs from "node:fs";
+
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const SHA_PATTERN = /^[0-9a-f]{40}$/;
+const ADMISSION_SCHEMA = "kungfu.buildchain.dev-pr-admission/v1";
+
+function mismatch(code) {
+  const error = new Error(code);
+  error.code = code;
+  throw error;
+}
+
+function requireMatch(condition, code) {
+  if (!condition) mismatch(code);
+}
+
+function readWarrantResult(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (cause) {
+    const error = new Error(`delivery Warrant result is unreadable: ${cause.message}`);
+    error.code = "invalid-delivery-warrant-result";
+    throw error;
+  }
+}
+
+function exactActiveReadback(result) {
+  requireMatch(result.schema === "kungfu.buildchain.dev-delivery-command-result/v1", "unsupported-delivery-warrant-result");
+  requireMatch(result.mode === "execute", "delivery-warrant-not-executed");
+  requireMatch(SHA_PATTERN.test(String(result.after?.commitSha || "")), "delivery-warrant-commit-readback-missing");
+  requireMatch(ROOT_PATTERN.test(String(result.after?.stateRoot || "")), "delivery-warrant-state-readback-missing");
+  requireMatch(result.observation?.schema === "kungfu.buildchain.dev-delivery-queue-observation/v1", "delivery-warrant-observation-missing");
+  requireMatch(result.observation.stateRoot === result.after.stateRoot, "delivery-warrant-observation-root-mismatch");
+  const warrant = result.observation.activeWarrant;
+  const candidate = result.observation.activeCandidate;
+  requireMatch(warrant?.schema === "kungfu.buildchain.dev-delivery-warrant/v1", "delivery-warrant-missing");
+  requireMatch(candidate?.candidateId === warrant.candidateId, "delivery-warrant-candidate-readback-missing");
+  requireMatch(!result.warrant || JSON.stringify(result.warrant) === JSON.stringify(warrant), "delivery-warrant-readback-mismatch");
+  return { warrant, candidate };
+}
+
+function exactWarrantBinding({ result, warrant, candidate, options, pullRequest }) {
+  requireMatch(warrant.repository === options.repository.fullName, "delivery-warrant-repository-mismatch");
+  requireMatch(warrant.protectedBase === options.targetBranch, "delivery-warrant-base-mismatch");
+  requireMatch(Number(warrant.pullRequestNumber) === Number(pullRequest.number), "delivery-warrant-pr-mismatch");
+  requireMatch(String(warrant.sourceHead || "").toLowerCase() === options.expectedHeadSha, "delivery-warrant-head-mismatch");
+  requireMatch(Number(candidate.pullRequestNumber) === Number(pullRequest.number), "delivery-warrant-candidate-pr-mismatch");
+  requireMatch(String(candidate.sourceHead || "").toLowerCase() === options.expectedHeadSha, "delivery-warrant-candidate-head-mismatch");
+  requireMatch(ROOT_PATTERN.test(String(warrant.fencingToken || "")), "delivery-warrant-fencing-missing");
+  requireMatch(Number.isInteger(Number(warrant.generation)) && Number(warrant.generation) >= 1, "delivery-warrant-generation-invalid");
+  requireMatch(Number.isFinite(Date.parse(warrant.expiresAt)) && Date.parse(warrant.expiresAt) > Date.now(), "delivery-warrant-expired");
+  requireMatch(ROOT_PATTERN.test(String(result.receiptRoot || "")), "delivery-warrant-receipt-root-missing");
+}
+
+export function createDevPrAdmissionReceipt({ options, pr = {}, state, reason, readiness, decision = {}, queue = null, warrant = null, labels = [], nextAction }) {
+  const observedHeadSha = String(pr.head?.sha || "").toLowerCase();
+  return {
+    schema: ADMISSION_SCHEMA,
+    repository: options.repository.fullName,
+    targetBranch: options.targetBranch,
+    pullRequestNumber: options.targetPullRequestNumber,
+    pullRequestUrl: pr.html_url || `https://github.com/${options.repository.fullName}/pull/${options.targetPullRequestNumber}`,
+    expectedHeadSha: options.expectedHeadSha,
+    observedHeadSha,
+    observedBaseBranch: pr.base?.ref || "",
+    headRepository: pr.head?.repo?.full_name || "",
+    headRef: pr.head?.ref || "",
+    observedLabels: [...labels].sort(),
+    policy: {
+      readyLabel: options.readyLabel,
+      blockLabels: options.blockLabels,
+      allowedHeadPrefixes: options.allowedHeadPrefixes,
+      requiredChecks: options.requiredChecks,
+      requireApproval: options.requireApproval,
+      sameRepositoryOnly: options.sameRepositoryOnly,
+      landingMode: options.landingMode,
+      queueAdmissionContext: options.queueAdmissionContext,
+      diagnosticContext: options.diagnosticContext,
+    },
+    readiness: {
+      label: options.readyLabel,
+      observed: readiness?.observed === true,
+      established: readiness?.established === true,
+      mutationAuthorized: !options.dryRun,
+    },
+    approval: decision.approval || { required: options.requireApproval, passed: false },
+    checks: decision.checks || { required: options.requiredChecks, entries: [], passed: false },
+    projectCut: decision.projectCut || null,
+    queue,
+    deliveryWarrant: warrant,
+    autoMergeEnabled: Boolean(pr.auto_merge || pr.autoMergeRequest),
+    state,
+    reason,
+    decision: state,
+    qualification: ["ready", "queued"].includes(state),
+    nextAction: nextAction({ options, state, reason, observedHeadSha }),
+  };
+}
+
+export function readDeliveryWarrantResult(options, pullRequest) {
+  if (options.warrantMode === "off") return null;
+  if (!options.warrantResultPath) mismatch("missing-delivery-warrant");
+  const result = readWarrantResult(options.warrantResultPath);
+  const { warrant, candidate } = exactActiveReadback(result);
+  exactWarrantBinding({ result, warrant, candidate, options, pullRequest });
+  return {
+    stateRef: result.stateRef || "",
+    stateCommit: result.after.commitSha,
+    stateRoot: result.after.stateRoot,
+    receiptRoot: result.receiptRoot,
+    candidateId: warrant.candidateId,
+    fencingToken: warrant.fencingToken,
+    generation: warrant.generation,
+    issuedAt: warrant.issuedAt,
+    expiresAt: warrant.expiresAt,
+  };
+}
+
+export async function runSourceQualification({ options, pullRequest, readiness, client, evaluate, admissionState, createReceipt, root, publishDiagnostic, reject }) {
+  const decision = await evaluate(pullRequest, { ...options, landingMode: options.landingMode, dryRun: true }, client);
+  if (decision.observedHeadSha && String(decision.observedHeadSha).toLowerCase() !== options.expectedHeadSha) {
+    return reject("stale", "head-sha-drift-during-source-qualification", readiness);
+  }
+  const state = decision.action === "would-merge" ? "ready" : admissionState(decision);
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state,
+    reason: state === "ready" ? "source-qualified-exact-head" : decision.reason,
+    readiness,
+    decision,
+    queue: null,
+    warrant: null,
+  });
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: state === "ready",
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: state === "ready" ? "source-qualified" : "targeted-admission-failed",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}
+
+export async function admitExistingQueueEntry({ options, pullRequest, readiness, client, entry, warrant, createReceipt, root, publishDiagnostic }) {
+  if (!entry) return null;
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state: "queued",
+    reason: "already-enqueued-exact-head",
+    readiness,
+    queue: { enabled: true, entry },
+    warrant,
+  });
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: true,
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: "admitted",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}
+
+export async function runTargetedQueueAdmission({ options, pullRequest, readiness, client, warrant, runController, admissionState, createReceipt, root, publishDiagnostic }) {
+  const targetedClient = Object.create(client);
+  targetedClient.listPullRequests = async () => [pullRequest];
+  const controller = await runController({ ...options, targetPullRequestNumber: 0 }, targetedClient);
+  controller.runKind = "targeted-admission-evaluation";
+  controller.outcome = controller.actions.length === 0 ? "target-not-admitted" : "target-action-selected";
+  controller.qualification = false;
+  controller.noOp = controller.actions.length === 0;
+  const entry = controller.evaluated.find((value) => value.number === pullRequest.number) || { action: "skip", reason: "target-not-selected" };
+  const state = admissionState(entry);
+  const receipt = createReceipt({
+    options,
+    pr: pullRequest,
+    state,
+    reason: entry.reason,
+    readiness,
+    decision: entry,
+    queue: {
+      enabled: controller.mergeQueue?.enabled === true,
+      predecessor: entry.admissionReceipt?.predecessor || null,
+      entry: entry.queueEntry || null,
+    },
+    warrant,
+  });
+  const admitted = ["ready", "queued"].includes(state);
+  const result = {
+    schema: "kungfu.buildchain.dev-pr-admission-result/v1",
+    ok: admitted,
+    mode: options.dryRun ? "plan" : "execute",
+    outcome: admitted ? "admitted" : "targeted-admission-failed",
+    receipt,
+    receiptRoot: root(receipt),
+    diagnostic: null,
+    controller,
+  };
+  if (!options.dryRun) result.diagnostic = await publishDiagnostic(client, options, receipt, result.receiptRoot);
+  return result;
+}

package/scripts/dispatch-artifact-signing-authority.mjs

@@ -86,10 +86,8 @@ export function validateArtifactSigningAuthorityRun(
   ) {
     throw new Error("Buildchain signing authority repository mismatch");
   }
-  if (
-    run.path &&
-    !String(run.path).startsWith(`.github/workflows/${AUTHORITY_WORKFLOW}@`)
-  ) {
+  const runPath = String(run.path || "").split("@", 1)[0];
+  if (run.path && runPath !== `.github/workflows/${AUTHORITY_WORKFLOW}`) {
     throw new Error("Buildchain signing authority workflow path mismatch");
   }
   return run;

package/scripts/gate-profile-core.mjs

@@ -67,6 +67,25 @@ function uniqueStrings(value, label) {
   return normalized;
 }
 
+export function normalizeGateEnvironment(value = {}, label = "environment") {
+  const environment = assertObject(value, label);
+  return Object.fromEntries(
+    Object.entries(environment)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, entry]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+          throw new Error(`${label} has invalid environment name: ${name}`);
+        }
+        if (!["string", "number", "boolean"].includes(typeof entry)) {
+          throw new Error(
+            `${label}.${name} must be a string, number, or boolean`,
+          );
+        }
+        return [name, String(entry)];
+      }),
+  );
+}
+
 function inferShifuPlatform(platform) {
   const explicit = String(platform.platform || "")
     .trim()
@@ -121,6 +140,10 @@ export function normalizeGatePlatform(platform, index = 0) {
       platform.capabilities || ["node"],
       `platforms[${index}].capabilities`,
     ).sort(),
+    environment: normalizeGateEnvironment(
+      platform.environment || {},
+      `platforms[${index}].environment`,
+    ),
     required: platform.required !== false,
   };
 }
@@ -259,6 +282,7 @@ export function createGateExecutionMatrix({
       platform: platform.platform,
       runner: platform.runner,
       capabilities: platform.capabilities,
+      environment: platform.environment,
       required: platform.required,
       profile,
       includeAdvisory: Boolean(includeAdvisory),

package/scripts/generate-channel-promotion-workflow.mjs

@@ -130,8 +130,8 @@ function validateWorkflowRoute(name, route, expectedLogicalRef) {
   if (!/^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/.test(route.workflowPath || "")) {
     throw new Error(`promotion shell ${name} workflowPath must name a reusable workflow`);
   }
-  if (!/^(?:v[0-9]+(?:-alpha)?|[0-9a-f]{40})$/.test(route.callRef || "")) {
-    throw new Error(`promotion shell ${name} callRef must be an official channel ref or exact SHA`);
+  if (!/^(?:v[0-9]+(?:-alpha)?|train\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
+    throw new Error(`promotion shell ${name} callRef must be an official channel ref, trusted train, or exact SHA`);
   }
   if (typeof route.forwardInternalInputs !== "boolean") {
     throw new Error(`promotion shell ${name} forwardInternalInputs must be boolean`);
@@ -240,29 +240,45 @@ jobs:
         id: router
         shell: bash
         env:
-          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}
-          BUILDCHAIN_ROUTER_WORKFLOW_REPOSITORY: \${{ job.workflow_repository }}
-          BUILDCHAIN_ROUTER_WORKFLOW_SHA: \${{ job.workflow_sha }}
+          BUILDCHAIN_ROUTER_REPOSITORY: \${{ inputs.buildchain-repository }}
+          BUILDCHAIN_ROUTER_REF: \${{ inputs.buildchain-ref }}
+          BUILDCHAIN_RESUME_RUN_ID: \${{ inputs.resume-candidate-run-id }}
+          BUILDCHAIN_RESUME_RUNTIME_SHA: \${{ inputs.resume-buildchain-runtime-sha }}
         run: |
           set -euo pipefail
-          workflow_ref="\${BUILDCHAIN_ROUTER_WORKFLOW_REF}"
-          repository="\${BUILDCHAIN_ROUTER_WORKFLOW_REPOSITORY}"
-          ref="\${workflow_ref##*@}"
+          repository="\${BUILDCHAIN_ROUTER_REPOSITORY}"
+          ref="\${BUILDCHAIN_ROUTER_REF}"
           ref="\${ref#refs/heads/}"
           ref="\${ref#refs/tags/}"
-          parsed_repository="\${workflow_ref%%/.github/workflows/*}"
-          if [[ -z "\${repository}" || "\${repository}" != "\${parsed_repository}" || -z "\${ref}" ]]; then
-            echo "::error::Unable to resolve promotion router source from job.workflow_ref=\${workflow_ref}"
+          if [[ ! "\${repository}" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ || -z "\${ref}" || "\${ref}" = /* || "\${ref}" = *..* ]]; then
+            echo "::error::Unable to resolve promotion router source from repository/ref inputs"
             exit 1
           fi
-          if [[ ! "\${BUILDCHAIN_ROUTER_WORKFLOW_SHA}" =~ ^[0-9a-fA-F]{40}$ ]]; then
-            echo "::error::job.workflow_sha is not an exact commit SHA"
+
+          remote_url="https://github.com/\${repository}.git"
+          refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
+          head_sha="$(printf '%s\\n' "\${refs}" | awk -v name="refs/heads/\${ref}" '$2 == name { print tolower($1) }')"
+          tag_sha="$(printf '%s\\n' "\${refs}" | awk -v peeled="refs/tags/\${ref}^{}" -v name="refs/tags/\${ref}" '$2 == peeled { print tolower($1); found=1 } $2 == name && !found { fallback=tolower($1) } END { if (!found && fallback != "") print fallback }')"
+          if [[ -n "\${head_sha}" && -n "\${tag_sha}" && "\${head_sha}" != "\${tag_sha}" ]]; then
+            echo "::error::Promotion router ref is ambiguous between branch and tag"
+            exit 1
+          fi
+          sha="\${head_sha:-\${tag_sha}}"
+          if [[ ! "\${sha}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::Promotion router ref did not resolve to one exact commit SHA"
             exit 1
           fi
+          if [[ -n "\${BUILDCHAIN_RESUME_RUN_ID}" ]]; then
+            expected_sha="\${BUILDCHAIN_RESUME_RUNTIME_SHA,,}"
+            if [[ ! "\${expected_sha}" =~ ^[0-9a-f]{40}$ || "\${sha}" != "\${expected_sha}" ]]; then
+              echo "::error::Recovery router ref does not match resume-buildchain-runtime-sha"
+              exit 1
+            fi
+          fi
           {
             echo "repository=\${repository}"
             echo "ref=\${ref}"
-            echo "sha=\${BUILDCHAIN_ROUTER_WORKFLOW_SHA,,}"
+            echo "sha=\${sha}"
           } >> "\${GITHUB_OUTPUT}"
 
       - name: Checkout promotion router

package/scripts/generate-site-bundle.mjs

@@ -56,7 +56,6 @@ const requireFromHere = createRequire(import.meta.url);
 function readText(rel) {
   return fs.readFileSync(path.join(root, rel), "utf8");
 }
-
 function readJson(rel) {
   return JSON.parse(readText(rel));
 }
@@ -518,7 +517,7 @@ function workflowCapabilityGroup(entry) {
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
-  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge")) return capabilityGroup("governance-versioning");
+  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
   if (entry.status === "repository-internal" || entry.status === "compatibility-fixture") return capabilityGroup("api-cli-reference");
   return capabilityGroup("api-cli-reference");
 }
@@ -778,6 +777,7 @@ function buildSiteBundle() {
         ["paper-release", "reusable-build"],
         ["release-propagation", "release-propagation"],
         ["dev-pr-auto-merge", "dev-governance"],
+        ["buildchain-dev-delivery", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
         ["binary-distribution", "release-passport"],
         ["github-artifact-attestation", "release-passport"],

package/scripts/git-fetch-process-tree.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const INTERNAL_COMMAND = "--buildchain-internal-git-fetch";
+const TIMEOUT_EXIT_CODE = 124;
+const scriptPath = fileURLToPath(import.meta.url);
+
+async function terminateProcessTree(child, graceMs) {
+  if (!child?.pid) return;
+  if (process.platform === "win32") {
+    await new Promise((resolve) => {
+      const killer = spawn(
+        "taskkill",
+        ["/pid", String(child.pid), "/t", "/f"],
+        {
+          stdio: "ignore",
+          windowsHide: true,
+        },
+      );
+      const fallback = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // The process tree may already be gone.
+        }
+        resolve();
+      }, graceMs);
+      killer.once("error", () => {
+        clearTimeout(fallback);
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // The process tree may already be gone.
+        }
+        resolve();
+      });
+      killer.once("close", () => {
+        clearTimeout(fallback);
+        resolve();
+      });
+    });
+    return;
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    return;
+  }
+  await new Promise((resolve) => setTimeout(resolve, graceMs));
+  try {
+    process.kill(-child.pid, "SIGKILL");
+  } catch {
+    // The process group exited during the grace period.
+  }
+}
+
+async function runInternalGitFetch() {
+  const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+  const timeoutMs = Math.max(1, Number(payload.timeoutMs || 60000));
+  const graceMs = Math.max(
+    50,
+    Number(process.env.BUILDCHAIN_GIT_TIMEOUT_GRACE_MS || 2000),
+  );
+  const child = spawn("git", payload.args, {
+    cwd: payload.cwd,
+    env: process.env,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout.on("data", (chunk) => stdout.push(chunk));
+  child.stderr.on("data", (chunk) => stderr.push(chunk));
+  let timedOut = false;
+  let spawnError;
+  const closed = new Promise((resolve) => {
+    child.once("error", (error) => {
+      spawnError = error;
+      resolve({ code: 1, signal: "" });
+    });
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    void terminateProcessTree(child, graceMs);
+  }, timeoutMs);
+  const result = await closed;
+  clearTimeout(timer);
+  if (stdout.length) process.stdout.write(Buffer.concat(stdout));
+  if (stderr.length) process.stderr.write(Buffer.concat(stderr));
+  if (spawnError)
+    console.error(
+      `buildchain: failed to start git fetch: ${spawnError.message}`,
+    );
+  if (timedOut)
+    console.error(
+      `buildchain: git fetch timed out after ${timeoutMs}ms; process tree terminated`,
+    );
+  if (result.signal && !timedOut)
+    console.error(`buildchain: git fetch terminated by ${result.signal}`);
+  process.exitCode = timedOut
+    ? TIMEOUT_EXIT_CODE
+    : spawnError || result.signal
+      ? 1
+      : (result.code ?? 1);
+}
+
+export function runGitFetchSync({ args, cwd, env, timeoutMs, stdio }) {
+  const commandStdio = Array.isArray(stdio)
+    ? ["pipe", stdio[1] || "pipe", stdio[2] || "pipe"]
+    : ["pipe", stdio, stdio];
+  try {
+    const output = execFileSync(
+      process.execPath,
+      [scriptPath, INTERNAL_COMMAND],
+      {
+        cwd,
+        env,
+        encoding: "utf8",
+        stdio: commandStdio,
+        input: JSON.stringify({ args, cwd, timeoutMs }),
+        windowsHide: true,
+      },
+    );
+    return output ? String(output).trim() : "";
+  } catch (error) {
+    if (error?.status === TIMEOUT_EXIT_CODE) error.code = "ETIMEDOUT";
+    throw error;
+  }
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  if (process.argv[2] !== INTERNAL_COMMAND)
+    throw new Error("internal git fetch command required");
+  await runInternalGitFetch();
+}