@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/scripts/publication-reproducibility.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+
+import { verifyPublicationReproducibility } from "../packages/core/publication-reproducibility.js";
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+export function runPublicationReproducibilityCli(args = process.argv.slice(2)) {
+  const result = verifyPublicationReproducibility({
+    cwd: readFlag(args, "cwd", process.cwd()),
+    sourceSha: readFlag(args, "source-sha", ""),
+    output: readFlag(
+      args,
+      "output",
+      ".buildchain/publication/reproducibility-receipt.json",
+    ),
+    promote: hasFlag(args, "promote"),
+    keepWorkspaces: hasFlag(args, "keep-workspaces"),
+    pullToolchain: !hasFlag(args, "no-toolchain-pull"),
+    packageName: readFlag(args, "package-name", ""),
+    allowUnpinnedToolchain: hasFlag(args, "allow-unpinned-toolchain"),
+  });
+  if (hasFlag(args, "json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      [
+        `publication-reproducibility=${result.status}`,
+        `publication-reproducibility-qualifying=${result.qualifying}`,
+        `publication-reproducibility-receipt=${result.outputPath}`,
+        `publication-reproducibility-digest=${result.receiptDigest}`,
+        "",
+      ].join("\n"),
+    );
+  }
+  if (!result.qualifying && !hasFlag(args, "allow-unpinned-toolchain")) {
+    process.exitCode = 1;
+  } else if (result.status !== "passed") {
+    process.exitCode = 1;
+  }
+  return result;
+}
+
+if (
+  !process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    runPublicationReproducibilityCli();
+  } catch (error) {
+    console.error(`publication-reproducibility: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/reconcile-github-governance.mjs

@@ -96,6 +96,11 @@ function writeJson(filePath, value) {
   fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+export function githubApiFailureIsAbsence(method, output) {
+  return String(method || "GET").toUpperCase() === "GET" &&
+    /404|not found/i.test(String(output || ""));
+}
+
 function githubApi(route, { method = "GET", body } = {}) {
   const args = [
     "api",
@@ -115,7 +120,9 @@ function githubApi(route, { method = "GET", body } = {}) {
   });
   const output = `${result.stdout || ""}\n${result.stderr || ""}`;
   if (result.status !== 0) {
-    if (/404|not found/i.test(output)) return { exists: false, data: null };
+    if (githubApiFailureIsAbsence(method, output)) {
+      return { exists: false, data: null };
+    }
     throw new Error(`GitHub API ${method} ${route} failed closed`);
   }
   return {

package/scripts/release-propagation.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  createReleasePropagationReceipt,
   planReleasePropagation,
   readReleasePropagationJson,
   writeReleasePropagationLock,
@@ -16,6 +17,14 @@ function usage() {
   buildchain release-propagation write-lock --plan <json-or-path>
                                             [--target <id-or-repo>] [--cwd <dir>]
                                             [--output <file>] [--json]
+  buildchain release-propagation receipt --plan <json-or-path>
+                                         --lock-result <json-or-path>
+                                         --pr-outcome <json-or-path>
+                                         [--target <id-or-repo>]
+                                         [--staging-state <state>]
+                                         [--production-state <state>]
+                                         [--observed-at <iso-8601>]
+                                         [--output <file>] [--json]
 `;
 }
 
@@ -90,6 +99,36 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
     }
     return;
   }
+  if (mode === "receipt") {
+    const plan = readReleasePropagationJson(readFlag(args, "plan"), {
+      label: "--plan",
+      cwd: process.cwd(),
+    });
+    const lockResult = readReleasePropagationJson(readFlag(args, "lock-result"), {
+      label: "--lock-result",
+      cwd: process.cwd(),
+    });
+    const prOutcome = readReleasePropagationJson(readFlag(args, "pr-outcome"), {
+      label: "--pr-outcome",
+      cwd: process.cwd(),
+    });
+    const receipt = createReleasePropagationReceipt({
+      plan,
+      target: readFlag(args, "target", ""),
+      lockResult,
+      prOutcome,
+      stagingState: readFlag(args, "staging-state", "pending"),
+      productionState: readFlag(args, "production-state", "not-requested"),
+      observedAt: readFlag(args, "observed-at", ""),
+    });
+    writeOutput(readFlag(args, "output", ""), receipt);
+    if (hasFlag(args, "json")) {
+      printJson(receipt);
+    } else {
+      process.stdout.write(`release propagation receipt: ${receipt.receiptSha256}\n`);
+    }
+    return;
+  }
   throw new Error(`unsupported release-propagation command: ${mode}`);
 }
 

package/scripts/resolve-artifact-signing-upload-route.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+
+function normalize(value, name) {
+  const normalized = String(value ?? "").trim();
+  if (/\r|\n|\0/.test(normalized)) {
+    throw new Error(`${name} must be a single-line NO_PROXY value`);
+  }
+  return normalized;
+}
+
+export function resolveArtifactSigningUploadRoute({
+  requestedNoProxy = "",
+  noProxy = "",
+  lowerNoProxy = "",
+} = {}) {
+  const requested = normalize(requestedNoProxy, "artifact signing request upload NO_PROXY");
+  const currentUpper = normalize(noProxy, "NO_PROXY");
+  const currentLower = normalize(lowerNoProxy, "no_proxy");
+
+  return {
+    noProxy: requested || currentUpper || currentLower,
+    overrideApplied: requested !== "",
+  };
+}
+
+export function writeGitHubOutputs(route, outputPath = process.env.GITHUB_OUTPUT) {
+  if (!outputPath) return;
+  fs.appendFileSync(
+    outputPath,
+    [
+      `no-proxy=${route.noProxy}`,
+      `override-applied=${route.overrideApplied}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const route = resolveArtifactSigningUploadRoute({
+    requestedNoProxy: process.env.BUILDCHAIN_SIGNING_REQUEST_UPLOAD_NO_PROXY,
+    noProxy: process.env.NO_PROXY,
+    lowerNoProxy: process.env.no_proxy,
+  });
+  writeGitHubOutputs(route);
+  process.stdout.write(
+    `Resolved artifact signing request upload route (override=${route.overrideApplied ? "yes" : "no"}).\n`,
+  );
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

package/scripts/resolve-build-contract.mjs

@@ -23,6 +23,12 @@ export function resolveBuildContractCli() {
     const resolved = resolveRunnerMatrix({
       runnerPreset: process.env.BUILDCHAIN_RUNNER_PRESET || "github-hosted",
       platformsJson: process.env.BUILDCHAIN_PLATFORMS_JSON || "",
+      awsCodeBuildProject:
+        process.env.BUILDCHAIN_AWS_CODEBUILD_PROJECT || "",
+      awsEc2WindowsRunnerLabel:
+        process.env.BUILDCHAIN_AWS_EC2_WINDOWS_RUNNER_LABEL || "",
+      awsEc2MacosRunnerLabel:
+        process.env.BUILDCHAIN_AWS_EC2_MACOS_RUNNER_LABEL || "",
       linuxContainerPreset: process.env.BUILDCHAIN_LINUX_CONTAINER_PRESET || "",
       linuxContainerImage: process.env.BUILDCHAIN_LINUX_CONTAINER_IMAGE || "",
     });

package/scripts/route-offline-runners.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import {
+  resolveRunnerMatrix,
+  writeGitHubOutputs,
+} from "./build-contract-core.mjs";
+
+export const HOSTED_RUNNER_FALLBACKS = Object.freeze({
+  "linux-x64": '["ubuntu-24.04"]',
+  "macos-arm64": '["macos-15"]',
+  "windows-x64": '["windows-2022"]',
+});
+
+function runnerLabels(runner) {
+  const labels = JSON.parse(String(runner || "[]"));
+  if (
+    !Array.isArray(labels) ||
+    labels.some((label) => typeof label !== "string")
+  ) {
+    throw new Error("runner must be a JSON array of label strings");
+  }
+  return labels;
+}
+
+function runnerHasLabels(runner, requiredLabels) {
+  const labels = new Set(
+    (runner.labels || []).map((label) => String(label?.name || label)),
+  );
+  return requiredLabels.every((label) => labels.has(label));
+}
+
+export function routeOfflineRunners({
+  platforms,
+  runners,
+  fallbacks = HOSTED_RUNNER_FALLBACKS,
+}) {
+  const routes = [];
+  const routedPlatforms = platforms.map((platform) => {
+    const requiredLabels = runnerLabels(platform.runner);
+    if (!requiredLabels.includes("self-hosted")) {
+      routes.push({
+        id: platform.id,
+        status: "hosted",
+        selected: "declared-runner",
+      });
+      return platform;
+    }
+    const matching = runners.filter((runner) =>
+      runnerHasLabels(runner, requiredLabels),
+    );
+    const online = matching.filter((runner) => runner.status === "online");
+    const busyOnline = online.filter((runner) => runner.busy);
+    const fallbackRunner = fallbacks[platform.id] || "";
+    const offline = online.length === 0;
+    const selected =
+      offline && fallbackRunner
+        ? "github-hosted-offline-fallback"
+        : "self-hosted";
+    routes.push({
+      id: platform.id,
+      status: offline ? "offline" : "online",
+      selected,
+      matchingRunnerCount: matching.length,
+      onlineRunnerCount: online.length,
+      busyOnlineRunnerCount: busyOnline.length,
+      fallbackAvailable: Boolean(fallbackRunner),
+    });
+    if (selected !== "github-hosted-offline-fallback") {
+      return platform;
+    }
+    return {
+      ...platform,
+      runner: fallbackRunner,
+    };
+  });
+  return {
+    platforms: routedPlatforms,
+    platformsJson: JSON.stringify(routedPlatforms),
+    fallbackCount: routes.filter(
+      (route) => route.selected === "github-hosted-offline-fallback",
+    ).length,
+    routing: {
+      schema: "buildchain.runner-offline-routing/v1",
+      status: "observed",
+      routes,
+    },
+  };
+}
+
+async function fetchGitHubJson({ url, token, fetchImpl }) {
+  const response = await fetchImpl(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "x-github-api-version": "2022-11-28",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(
+      `runner inventory request failed with status ${response.status}`,
+    );
+  }
+  return response.json();
+}
+
+export async function listRepositoryRunners({
+  repository,
+  token,
+  apiUrl = "https://api.github.com",
+  fetchImpl = fetch,
+}) {
+  const repositoryPayload = await fetchGitHubJson({
+    url: `${apiUrl}/repos/${repository}`,
+    token,
+    fetchImpl,
+  });
+  const ownerLogin = String(repositoryPayload?.owner?.login || "").trim();
+  const ownerType = String(repositoryPayload?.owner?.type || "").trim();
+  const inventoryPath =
+    ownerType === "Organization" && ownerLogin
+      ? `/orgs/${ownerLogin}/actions/runners`
+      : `/repos/${repository}/actions/runners`;
+  const runners = [];
+  for (let page = 1; ; page += 1) {
+    const payload = await fetchGitHubJson({
+      url: `${apiUrl}${inventoryPath}?per_page=100&page=${page}`,
+      token,
+      fetchImpl,
+    });
+    const pageRunners = Array.isArray(payload.runners) ? payload.runners : [];
+    runners.push(...pageRunners);
+    if (pageRunners.length < 100) {
+      return {
+        runners,
+        inventoryScope:
+          ownerType === "Organization" && ownerLogin
+            ? "organization"
+            : "repository",
+      };
+    }
+  }
+}
+
+export async function resolveOfflineRunnerFallback({
+  runnerPreset,
+  platformsJson = "",
+  repository,
+  token,
+  apiUrl,
+  fetchImpl,
+}) {
+  const base = resolveRunnerMatrix({ runnerPreset, platformsJson });
+  const selfHosted = base.platforms.filter((platform) =>
+    runnerLabels(platform.runner).includes("self-hosted"),
+  );
+  if (selfHosted.length === 0) {
+    return {
+      platformsJson: base.platformsJson,
+      fallbackCount: 0,
+      routing: {
+        schema: "buildchain.runner-offline-routing/v1",
+        status: "not-applicable",
+        routes: [],
+      },
+    };
+  }
+  if (!String(token || "").trim()) {
+    return {
+      platformsJson: base.platformsJson,
+      fallbackCount: 0,
+      routing: {
+        schema: "buildchain.runner-offline-routing/v1",
+        status: "unavailable",
+        reason: "runner-inventory-token-not-projected",
+        routes: [],
+      },
+    };
+  }
+  try {
+    const inventory = await listRepositoryRunners({
+      repository,
+      token,
+      apiUrl,
+      fetchImpl,
+    });
+    const routed = routeOfflineRunners({
+      platforms: base.platforms,
+      runners: inventory.runners,
+    });
+    return {
+      ...routed,
+      routing: {
+        ...routed.routing,
+        inventoryScope: inventory.inventoryScope,
+      },
+    };
+  } catch {
+    return {
+      platformsJson: base.platformsJson,
+      fallbackCount: 0,
+      routing: {
+        schema: "buildchain.runner-offline-routing/v1",
+        status: "unavailable",
+        reason: "runner-inventory-unavailable",
+        routes: [],
+      },
+    };
+  }
+}
+
+async function main() {
+  const resolved = await resolveOfflineRunnerFallback({
+    runnerPreset: process.env.BUILDCHAIN_RUNNER_PRESET || "github-hosted",
+    platformsJson: process.env.BUILDCHAIN_PLATFORMS_JSON || "",
+    repository: process.env.GITHUB_REPOSITORY || "",
+    token: process.env.BUILDCHAIN_RUNNER_INVENTORY_TOKEN || "",
+    apiUrl: process.env.GITHUB_API_URL || "https://api.github.com",
+  });
+  writeGitHubOutputs({
+    "platforms-json": resolved.platformsJson,
+    "fallback-count": String(resolved.fallbackCount),
+    "routing-json": JSON.stringify(resolved.routing),
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(
+      `::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`,
+    );
+    process.exitCode = 1;
+  });
+}

package/scripts/run-candidate-body-prefix-renderer.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
+import childProcess from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+
+const EXACT_SHA = /^[0-9a-f]{40}$/u;
+const MANAGED_MARKER = "<!-- buildchain-dev-alpha-candidate-state";
+const MAX_PREFIX_CHARACTERS = 32768;
+
+function required(value, name) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+export function resolveRendererPath(consumerRootValue, rendererValue) {
+  const consumerRoot = fs.realpathSync(
+    path.resolve(required(consumerRootValue, "consumerRoot")),
+  );
+  const renderer = required(rendererValue, "renderer");
+  if (path.isAbsolute(renderer))
+    throw new Error("renderer must be repository-relative");
+  const candidate = path.resolve(consumerRoot, renderer);
+  const candidateRelative = path.relative(consumerRoot, candidate);
+  if (
+    !candidateRelative ||
+    candidateRelative.startsWith("..") ||
+    path.isAbsolute(candidateRelative)
+  )
+    throw new Error("renderer must resolve inside the consumer checkout");
+  const absolute = fs.realpathSync(candidate);
+  const relative = path.relative(consumerRoot, absolute);
+  if (relative.startsWith("..") || path.isAbsolute(relative))
+    throw new Error("renderer must resolve inside the consumer checkout");
+  const stat = fs.statSync(absolute);
+  if (!stat.isFile())
+    throw new Error("renderer must resolve to a regular file");
+  return { consumerRoot, renderer: absolute };
+}
+
+function safeEnvironment(values, source = process.env) {
+  const retained = [
+    "CI",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "PATH",
+    "RUNNER_ARCH",
+    "RUNNER_OS",
+    "TEMP",
+    "TMP",
+    "TMPDIR",
+    "TZ",
+  ];
+  return {
+    ...Object.fromEntries(
+      retained
+        .filter((key) => source[key] !== undefined)
+        .map((key) => [key, source[key]]),
+    ),
+    BUILDCHAIN_CHANNEL_PATROL_PR_BODY_PREFIX_OUTPUT: values.outputPath,
+    BUILDCHAIN_CHANNEL_PATROL_SELECTED_SHA: values.selectedSha,
+    BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH: values.sourceBranch,
+    BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH: values.targetBranch,
+    GIT_TERMINAL_PROMPT: "0",
+  };
+}
+
+function checkedSpawn(command, args, options, label) {
+  const result = childProcess.spawnSync(command, args, {
+    ...options,
+    encoding: "utf8",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || "").trim();
+    throw new Error(`${label} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return result;
+}
+
+function readPrefix(outputPath) {
+  const bytes = fs.readFileSync(outputPath);
+  let value;
+  try {
+    value = new TextDecoder("utf-8", { fatal: true }).decode(bytes).trim();
+  } catch {
+    throw new Error("renderer output must be valid UTF-8");
+  }
+  if (!value) throw new Error("renderer output must not be empty");
+  if (value.length > MAX_PREFIX_CHARACTERS)
+    throw new Error(
+      `renderer output exceeds ${MAX_PREFIX_CHARACTERS} characters`,
+    );
+  if (value.includes(MANAGED_MARKER))
+    throw new Error(
+      "renderer output must not contain the managed candidate state marker",
+    );
+  return value;
+}
+
+export function appendMultilineOutput(outputFile, name, value) {
+  let delimiter;
+  do {
+    delimiter = `buildchain_${crypto.randomUUID()}`;
+  } while (value.split(/\r?\n/u).includes(delimiter));
+  fs.appendFileSync(
+    outputFile,
+    `${name}<<${delimiter}\n${value}\n${delimiter}\n`,
+  );
+}
+
+export function runCandidateBodyPrefixRenderer(options = {}) {
+  const { consumerRoot, renderer } = resolveRendererPath(
+    options.consumerRoot,
+    options.renderer,
+  );
+  const selectedSha = required(options.selectedSha, "selectedSha");
+  if (!EXACT_SHA.test(selectedSha))
+    throw new Error("selectedSha must be an exact 40-character commit SHA");
+  const sourceBranch = required(options.sourceBranch, "sourceBranch");
+  const targetBranch = required(options.targetBranch, "targetBranch");
+  const outputPath = path.resolve(required(options.outputPath, "outputPath"));
+  const githubOutput = required(options.githubOutput, "githubOutput");
+
+  const head = checkedSpawn(
+    "git",
+    ["rev-parse", "HEAD"],
+    {
+      cwd: consumerRoot,
+      env: safeEnvironment({
+        outputPath,
+        selectedSha,
+        sourceBranch,
+        targetBranch,
+      }),
+    },
+    "consumer HEAD resolution",
+  ).stdout.trim();
+  if (head !== selectedSha)
+    throw new Error(
+      `consumer checkout HEAD ${head} does not match selected SHA ${selectedSha}`,
+    );
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.rmSync(outputPath, { force: true });
+  const env = safeEnvironment({
+    outputPath,
+    selectedSha,
+    sourceBranch,
+    targetBranch,
+  });
+  checkedSpawn(
+    process.execPath,
+    [renderer],
+    { cwd: consumerRoot, env },
+    "PR body prefix renderer",
+  );
+  const value = readPrefix(outputPath);
+  appendMultilineOutput(githubOutput, "pull-request-body-prefix", value);
+  return value;
+}
+
+function main() {
+  runCandidateBodyPrefixRenderer({
+    consumerRoot: process.env.BUILDCHAIN_CHANNEL_PATROL_CONSUMER_ROOT,
+    renderer: process.env.BUILDCHAIN_CHANNEL_PATROL_PR_BODY_PREFIX_RENDERER,
+    outputPath: process.env.BUILDCHAIN_CHANNEL_PATROL_PR_BODY_PREFIX_OUTPUT,
+    selectedSha: process.env.BUILDCHAIN_CHANNEL_PATROL_SELECTED_SHA,
+    sourceBranch: process.env.BUILDCHAIN_CHANNEL_PATROL_SOURCE_BRANCH,
+    targetBranch: process.env.BUILDCHAIN_CHANNEL_PATROL_TARGET_BRANCH,
+    githubOutput: process.env.GITHUB_OUTPUT,
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}