@kungfu-tech/buildchain 4.1.0-alpha.0 → 4.1.0-alpha.2

package/packages/core/runtime/runtime-selection-action.js

@@ -1,34 +0,0 @@
-import { context, getOctokit } from "@actions/github";
-import { selectRuntime } from "./runtime-selection.js";
-
-export async function runtimeSelectionAction(core) {
-  const request = {
-    purpose: core.getInput("purpose", { required: true }),
-    repository: core.getInput("repository", { required: true }),
-    requestedRef: core.getInput("ref"),
-    workflowSha: core.getInput("workflow-sha", { required: true }),
-    workflowRef: core.getInput("workflow-ref"),
-  };
-  const result = await selectRuntime(request, {
-    context,
-    github: getOctokit(core.getInput("token", { required: true })),
-  });
-  for (const [name, value] of Object.entries(result))
-    core.setOutput(name, value);
-  if (request.purpose === "web")
-    await core.summary
-      .addHeading("Buildchain runtime")
-      .addCodeBlock(
-        JSON.stringify(
-          {
-            workflow: request.workflowRef,
-            definition: request.workflowSha,
-            ...result,
-          },
-          null,
-          2,
-        ),
-        "json",
-      )
-      .write();
-}

package/packages/core/runtime/runtime-selection.js

@@ -1,136 +0,0 @@
-import { repositoryActorPermission } from "../providers/github-permission.js";
-const exactSha = /^[0-9a-f]{40}$/iu;
-const train = /^train\/v4\/v4\.\d+\/[A-Za-z0-9._/-]+$/u;
-const channel = /^v4(?:-alpha)?$/u;
-
-export function classifyRuntime(ref) {
-  if (/^v4(?:\.\d+\.\d+)?$/u.test(ref)) return "stable";
-  if (/^v4-alpha$|^v4\.\d+\.\d+-alpha\.\d+$/u.test(ref)) return "alpha";
-  if (exactSha.test(ref)) return "exact-sha";
-  if (train.test(ref)) return "train";
-  return "development";
-}
-
-function runtimeAdmission({
-  purpose,
-  repository,
-  requestedRef = "",
-  workflowSha,
-  workflowRef = "",
-}) {
-  if (!["publication", "web", "gate"].includes(purpose))
-    throw new Error("Unknown runtime admission purpose");
-  repository = String(repository || "").trim();
-  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository))
-    throw new Error("Invalid Buildchain repository");
-  const definition = String(workflowSha || "").toLowerCase();
-  if (!exactSha.test(definition))
-    throw new Error("Runtime requires the exact defining workflow SHA");
-  const requested = String(requestedRef)
-    .trim()
-    .replace(/^refs\/heads\//u, "");
-  const sameRepository = workflowRef.startsWith(
-    `${repository}/.github/workflows/`,
-  );
-  if (!requested && purpose !== "gate" && !sameRepository)
-    throw new Error(
-      "Default runtime must belong to the defining workflow repository",
-    );
-  const sameDefinition = requested.toLowerCase() === definition;
-  // These are different existing authority contracts: Web accepts an explicit
-  // same-definition selection only for a closed release PR or trusted dispatch.
-  const implicitDefinition =
-    purpose === "gate"
-      ? sameDefinition
-      : purpose === "publication" && sameRepository && sameDefinition;
-  const override = Boolean(
-    requested && !channel.test(requested) && !implicitDefinition,
-  );
-  const decision =
-    requested && channel.test(requested)
-      ? "official-channel"
-      : "workflow-definition";
-  return {
-    purpose,
-    repository,
-    workflowRef,
-    definition,
-    requested,
-    sameRepository,
-    sameDefinition,
-    override,
-    decision,
-  };
-}
-async function authorizeRuntimeOverride(
-  { purpose, requested, sameRepository, sameDefinition },
-  { github, context },
-) {
-  if (!exactSha.test(requested) && !train.test(requested))
-    throw new Error(
-      "Runtime override must be a current v4 train or exact SHA; current channel selectors are v4 and v4-alpha",
-    );
-  const closedRelease =
-    purpose === "web" &&
-    sameRepository &&
-    sameDefinition &&
-    context.eventName === "pull_request" &&
-    context.payload?.action === "closed";
-  if (!closedRelease) {
-    if (context.eventName !== "workflow_dispatch")
-      throw new Error("Runtime override requires trusted workflow_dispatch");
-    const permission = await repositoryActorPermission(
-      { ...context.repo, actor: context.actor },
-      github,
-    );
-    if (!["admin", "maintain", "write"].includes(permission))
-      throw new Error("Runtime override requires write permission");
-  }
-  return closedRelease
-    ? "closed-release-pr-shell-runtime"
-    : "override-accepted";
-}
-export async function selectRuntime(request, { github, context }) {
-  const admitted = runtimeAdmission(request);
-  const { purpose, repository, workflowRef, definition, requested, override } =
-    admitted;
-  const decision = override
-    ? await authorizeRuntimeOverride(admitted, { github, context })
-    : admitted.decision;
-  const selected = requested || definition;
-  const fullRef =
-    purpose === "web" && train.test(selected)
-      ? `refs/heads/${selected}`
-      : selected;
-  const [owner, repo] = repository.split("/");
-  const sha = exactSha.test(selected)
-    ? selected.toLowerCase()
-    : (await github.rest.repos.getCommit({ owner, repo, ref: fullRef })).data
-        .sha;
-  if (!exactSha.test(sha || ""))
-    throw new Error("Runtime did not resolve to an exact commit");
-  const coordinate = {
-    "runtime-ref": selected,
-    "runtime-sha": sha.toLowerCase(),
-  };
-  if (purpose === "gate") return coordinate;
-  const result = {
-    ...coordinate,
-    "runtime-class": classifyRuntime(
-      requested ||
-        workflowRef
-          .split("@")
-          .at(-1)
-          .replace(/^refs\/(?:heads|tags)\//u, ""),
-    ),
-    "runtime-override": String(override),
-    "runtime-trust-decision": decision,
-  };
-  if (purpose === "web")
-    Object.assign(result, {
-      "runtime-full-ref": fullRef,
-      "workflow-shell-ref": definition,
-      "rollback-ref": definition,
-    });
-  return result;
-}

package/packages/core/runtime/workflow-runtime.js

@@ -1,11 +0,0 @@
-export function exactWorkflowRuntime(value) {
-  if (!/^[0-9a-f]{40}$/iu.test(value || ""))
-    throw new Error("Called workflow requires an exact commit SHA");
-  return value.toLowerCase();
-}
-export function exactWorkflowRuntimeAction(core) {
-  core.setOutput(
-    "sha",
-    exactWorkflowRuntime(core.getInput("workflow-sha", { required: true })),
-  );
-}

package/packages/core/workflow/admission/review.js

@@ -1,188 +0,0 @@
-import { workflowInstallationRoot } from "../installation.js";
-import path from "node:path";
-import fs from "node:fs";
-import { command, requireValue } from "../../runtime/action-process.mjs";
-
-function exactTime(value) {
-  const time = new Date(value);
-  requireValue(Number.isFinite(time.getTime()), "Review timestamp is invalid");
-  return time.toISOString();
-}
-export function bootstrapVersionLine(
-  runtimeRoot = workflowInstallationRoot(import.meta.url),
-) {
-  const version = JSON.parse(
-    fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8"),
-  ).version;
-  const match = /^(\d+)\.(\d+)\.\d+(?:-[0-9A-Za-z.-]+)?$/u.exec(version);
-  requireValue(
-    match,
-    "Bootstrap package version must declare its release line",
-  );
-  return {
-    development: `dev/v${match[1]}/v${match[1]}.${match[2]}`,
-    alpha: `alpha/v${match[1]}/v${match[1]}.${match[2]}`,
-  };
-}
-export function reviewedCandidateEvidence({
-  request,
-  pr,
-  reviews,
-  checks,
-  commit,
-  line,
-  observedAt,
-}) {
-  const candidate = request.candidate;
-  const matches =
-    pr.head?.repo?.full_name === candidate.repository &&
-    pr.number === candidate.reviewPullRequest;
-  let kind;
-  if (
-    matches &&
-    pr.head.sha === candidate.expectedSha &&
-    pr.base?.ref === line.development
-  )
-    kind = "reviewed-head";
-  else if (
-    matches &&
-    request.mode === "alpha" &&
-    pr.merged === true &&
-    pr.merge_commit_sha === candidate.expectedSha &&
-    pr.base?.ref === line.alpha
-  )
-    kind = "protected-alpha-merge";
-  requireValue(kind, "review does not bind the exact candidate runtime");
-  const reviewedSha = pr.head.sha.toLowerCase();
-  const latestReviews = new Map();
-  for (const review of [...reviews].sort(
-    (a, b) =>
-      Date.parse(exactTime(a.submitted_at)) -
-      Date.parse(exactTime(b.submitted_at)),
-  )) {
-    if (["APPROVED", "CHANGES_REQUESTED", "DISMISSED"].includes(review.state))
-      latestReviews.set(review.user?.login?.toLowerCase(), review);
-  }
-  const latestChecks = new Map();
-  for (const check of [...checks].sort((a, b) => (a.id || 0) - (b.id || 0))) {
-    if (check.head_sha)
-      requireValue(
-        check.head_sha === candidate.expectedSha,
-        "Check belongs to a different candidate",
-      );
-    latestChecks.set(check.name, check);
-  }
-  reviews = [...latestReviews.values()];
-  checks = [...latestChecks.values()];
-  requireValue(
-    reviews.some(
-      (review) =>
-        review.state === "APPROVED" &&
-        review.commit_id === reviewedSha &&
-        review.user?.login?.toLowerCase() === "kungfu-origin",
-    ),
-    "Exact candidate requires independent kungfu-origin approval",
-  );
-  requireValue(
-    checks.some(
-      (check) =>
-        check.name === "check" &&
-        check.status === "completed" &&
-        check.conclusion === "success",
-    ),
-    "Exact candidate requires successful check",
-  );
-  return {
-    repository: candidate.repository,
-    pullRequest: candidate.reviewPullRequest,
-    headSha: reviewedSha,
-    baseRef: pr.base.ref,
-    approvals: reviews
-      .filter(
-        (review) =>
-          review.state === "APPROVED" && review.commit_id === reviewedSha,
-      )
-      .map((review) => ({
-        reviewer: review.user.login.toLowerCase(),
-        commitSha: review.commit_id,
-        submittedAt: exactTime(review.submitted_at),
-      })),
-    checks: checks
-      .filter((check) => check.status === "completed" && check.conclusion)
-      .map(({ name, status, conclusion }) => ({
-        name,
-        status,
-        conclusion,
-        commitSha: candidate.expectedSha,
-      })),
-    runtimeBinding: {
-      kind,
-      runtimeSha: candidate.expectedSha,
-      parentShas: commit.parents.map(({ sha }) => sha.toLowerCase()),
-      mergedAt:
-        kind === "protected-alpha-merge" ? exactTime(pr.merged_at) : null,
-    },
-    observedAt: exactTime(observedAt),
-  };
-}
-export function readCandidateReview(
-  { request, workspace, runtimeRoot, candidateRoot, token },
-  execute = command,
-) {
-  if (!token)
-    throw new Error("Candidate review requires an explicit read credential");
-  const { repository, expectedSha, reviewPullRequest } = request.candidate;
-  const observed = execute("git", ["-C", candidateRoot, "rev-parse", "HEAD"], {
-    stdio: ["ignore", "pipe", "inherit"],
-  })
-    .trim()
-    .toLowerCase();
-  requireValue(
-    observed === expectedSha,
-    "Candidate checkout does not match its expected SHA",
-  );
-  const api = (endpoint, paginate = false) =>
-    JSON.parse(
-      execute(
-        "gh",
-        [
-          "api",
-          ...(paginate ? ["--paginate", "--slurp"] : []),
-          "-H",
-          "Accept: application/vnd.github+json",
-          `repos/${repository}/${endpoint}`,
-        ],
-        {
-          stdio: ["ignore", "pipe", "inherit"],
-          env: { ...process.env, GH_TOKEN: token },
-        },
-      ),
-    );
-  const pr = api(`pulls/${reviewPullRequest}`);
-  const reviews = api(`pulls/${reviewPullRequest}/reviews`, true).flat();
-  const checks = api(
-    `commits/${expectedSha}/check-runs?per_page=100`,
-    true,
-  ).flatMap((page) => page.check_runs);
-  const commit = api(`git/commits/${expectedSha}`);
-  fs.mkdirSync(path.join(workspace, ".buildchain"), { recursive: true });
-  for (const [name, value] of Object.entries({
-    pr,
-    reviews,
-    checks,
-    "runtime-commit": commit,
-  }))
-    fs.writeFileSync(
-      path.join(workspace, `.buildchain/${name}.json`),
-      JSON.stringify(value) + "\n",
-    );
-  return reviewedCandidateEvidence({
-    request,
-    pr,
-    reviews,
-    checks,
-    commit,
-    line: bootstrapVersionLine(runtimeRoot),
-    observedAt: new Date().toISOString(),
-  });
-}

package/packages/core/workflow/commands/universal-workflow-backflow.mjs

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { upsertUniversalBackflow } from "../settlement/backflow.js";
-const fail = message => { throw new Error(message); };
-async function main() {
-  const request = JSON.parse(
-    process.env.BUILDCHAIN_UNIVERSAL_REQUEST_JSON ||
-      fail("request is required"),
-  );
-  const receipt = JSON.parse(
-    process.env.BUILDCHAIN_UNIVERSAL_TERMINAL_RECEIPT_JSON ||
-      fail("terminal receipt is required"),
-  );
-  const result = await upsertUniversalBackflow({
-    request,
-    receipt,
-    token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
-  });
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-}
-
-const isMain =
-  process.argv[1] &&
-  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
-if (isMain) await main();

package/packages/core/workflow/installation.js

@@ -1,33 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { installationRoot } from "../runtime/installation-root.js";
-
-// A consumer-owned recovery package carries only trusted admission and settlement
-// actions. Locating it never gives those bytes candidate execution authority.
-export function workflowInstallationRoot(entryUrl) {
-  let directory = path.dirname(fs.realpathSync(fileURLToPath(entryUrl)));
-  for (;;) {
-    const manifestPath = path.join(directory, "package.json");
-    if (fs.existsSync(manifestPath)) {
-      const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-      if (manifest.name === "@kungfu-tech/buildchain")
-        return installationRoot(entryUrl);
-      if (manifest.name === "buildchain-consumer-recovery") {
-        const distribution = JSON.parse(
-          fs.readFileSync(path.join(directory, "manifest.json"), "utf8"),
-        );
-        if (
-          distribution.schema !==
-          "buildchain.bootstrap-recovery-distribution/v1"
-        )
-          throw new Error("Unsupported consumer recovery distribution");
-        return directory;
-      }
-    }
-    const parent = path.dirname(directory);
-    if (parent === directory)
-      throw new Error("Workflow action is outside a declared distribution");
-    directory = parent;
-  }
-}

package/packages/core/workflow/settlement/backflow.js

@@ -1,187 +0,0 @@
-import crypto from "node:crypto";
-import {
-  validateUniversalWorkflowRequest,
-  universalWorkflowRequestRoot,
-} from "../universal-workflow-bootstrap.js";
-const SHA = /^[0-9a-f]{40}$/u;
-const ROOT = /^sha256:[0-9a-f]{64}$/u;
-
-function fail(message) {
-  throw new Error(message);
-}
-
-function canonical(value) {
-  if (Array.isArray(value)) return value.map(canonical);
-  if (value && typeof value === "object")
-    return Object.fromEntries(
-      Object.keys(value)
-        .sort((left, right) => Buffer.from(left).compare(Buffer.from(right)))
-        .map((key) => [key, canonical(value[key])]),
-    );
-  return value;
-}
-
-function contentRoot(domain, value) {
-  const hash = crypto.createHash("sha256");
-  hash.update(domain, "utf8");
-  hash.update(Buffer.from([0]));
-  hash.update(`${JSON.stringify(canonical(value))}\n`, "utf8");
-  return `sha256:${hash.digest("hex")}`;
-}
-
-function validateTerminalReceipt(value, request) {
-  if (
-    value?.schema !==
-      "kungfu-buildchain-v4-universal-workflow-terminal-receipt/v1" ||
-    value.status !== "succeeded" ||
-    value.runtime?.repository !== request.candidate.repository ||
-    value.runtime?.sha !== request.candidate.expectedSha ||
-    value.requestRoot !== universalWorkflowRequestRoot(request) ||
-    !SHA.test(value.runtime?.sha || "") ||
-    !ROOT.test(value.receiptRoot || "")
-  )
-    fail(
-      "successful exact-candidate terminal receipt is required for backflow",
-    );
-  return value;
-}
-
-export function createUniversalBackflowPlan({
-  request: requestValue,
-  receipt,
-}) {
-  const request = validateUniversalWorkflowRequest(requestValue);
-  if (request.mode !== "train") fail("only Train delivery can create backflow");
-  if (request.capability.id !== "release-candidate-promote")
-    fail("only a release-candidate-promote delivery can create backflow");
-  if (request.payload?.inputs?.["dry-run"] !== false)
-    fail("only a non-dry-run release delivery can create backflow");
-  const terminal = validateTerminalReceipt(receipt, request);
-  const marker = `<!-- buildchain-universal-backflow:${request.candidate.expectedSha} -->`;
-  const binding = {
-    schema: "kungfu-buildchain-v4-universal-workflow-backflow/v1",
-    repository: request.candidate.repository,
-    pullRequest: request.candidate.reviewPullRequest,
-    baseRef: "dev/v4/v4.1",
-    trainSha: request.candidate.expectedSha,
-    consumerRepository: request.consumer.repository,
-    consumerSha: request.consumer.sourceSha,
-    requestRoot: terminal.requestRoot,
-    terminalReceiptRoot: terminal.receiptRoot,
-  };
-  const backflowRoot = contentRoot("universal-workflow-backflow", binding);
-  return {
-    ...binding,
-    marker,
-    backflowRoot,
-    body: [
-      marker,
-      "## Universal Train backflow",
-      "",
-      `- Train SHA: \`${binding.trainSha}\``,
-      `- Consumer: \`${binding.consumerRepository}@${binding.consumerSha}\``,
-      `- Request root: \`${binding.requestRoot}\``,
-      `- Terminal receipt root: \`${binding.terminalReceiptRoot}\``,
-      `- Backflow root: \`${backflowRoot}\``,
-      "",
-      "This receipt binds a successful consumer delivery to the protected Train-to-dev backflow PR; it does not designate the Train candidate as a Buildchain release.",
-    ].join("\n"),
-  };
-}
-
-function githubHeaders(token) {
-  return {
-    accept: "application/vnd.github+json",
-    authorization: `Bearer ${token}`,
-    "content-type": "application/json",
-    "user-agent": "buildchain-universal-backflow",
-    "x-github-api-version": "2022-11-28",
-  };
-}
-
-async function githubJson({ path, method = "GET", token, body, fetchImpl }) {
-  const api = String(
-    process.env.GITHUB_API_URL || "https://api.github.com",
-  ).replace(/\/+$/u, "");
-  const response = await fetchImpl(`${api}${path}`, {
-    method,
-    headers: githubHeaders(token),
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const text = await response.text();
-  const value = text ? JSON.parse(text) : {};
-  if (!response.ok)
-    fail(
-      `GitHub API ${method} ${path} failed with ${response.status}: ${value.message || text}`,
-    );
-  return value;
-}
-
-export async function upsertUniversalBackflow({
-  request,
-  receipt,
-  token,
-  fetchImpl = globalThis.fetch,
-}) {
-  const admitted = validateUniversalWorkflowRequest(request);
-  if (
-    admitted.mode !== "train" ||
-    admitted.capability.id !== "release-candidate-promote" ||
-    admitted.payload?.inputs?.["dry-run"] !== false
-  ) {
-    return {
-      schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
-      action: "skipped",
-      reason: "not-a-successful-non-dry-run-release-delivery",
-      backflowRoot: "",
-    };
-  }
-  if (!token) fail("GH_TOKEN is required for protected backflow");
-  if (typeof fetchImpl !== "function") fail("fetch is required for backflow");
-  const plan = createUniversalBackflowPlan({ request: admitted, receipt });
-  const encodedRepository = plan.repository;
-  const pull = await githubJson({
-    path: `/repos/${encodedRepository}/pulls/${plan.pullRequest}`,
-    token,
-    fetchImpl,
-  });
-  if (
-    pull.state !== "open" ||
-    pull.base?.ref !== plan.baseRef ||
-    pull.head?.repo?.full_name !== plan.repository ||
-    pull.head?.sha !== plan.trainSha
-  )
-    fail("backflow PR no longer binds the exact admitted Train candidate");
-  const comments = await githubJson({
-    path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments?per_page=100`,
-    token,
-    fetchImpl,
-  });
-  const existing = comments.find((comment) =>
-    String(comment.body || "").includes(plan.marker),
-  );
-  const comment = existing
-    ? await githubJson({
-        path: `/repos/${encodedRepository}/issues/comments/${existing.id}`,
-        method: "PATCH",
-        token,
-        body: { body: plan.body },
-        fetchImpl,
-      })
-    : await githubJson({
-        path: `/repos/${encodedRepository}/issues/${plan.pullRequest}/comments`,
-        method: "POST",
-        token,
-        body: { body: plan.body },
-        fetchImpl,
-      });
-  return {
-    schema: "kungfu-buildchain-v4-universal-workflow-backflow-result/v1",
-    action: existing ? "updated" : "created",
-    pullRequest: plan.pullRequest,
-    trainSha: plan.trainSha,
-    terminalReceiptRoot: plan.terminalReceiptRoot,
-    backflowRoot: plan.backflowRoot,
-    commentUrl: comment.html_url,
-  };
-}