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

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/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-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-lifecycle-core.mjs

@@ -130,6 +130,16 @@ function collectArtifactFiles(root, patterns) {
   return [...files].sort();
 }
 
+function signingArtifactPathsForPlatform({ loadedConfig, cwd, platformId }) {
+  const declarations = loadedConfig?.config?.signing?.artifacts || [];
+  return declarations
+    .filter(
+      (entry) =>
+        entry.platforms.length === 0 || entry.platforms.includes(platformId),
+    )
+    .map((entry) => path.resolve(cwd, entry.path));
+}
+
 function readProcessSummaryArtifact(filePath) {
   if (!filePath) {
     return undefined;
@@ -435,11 +445,35 @@ export function runLifecycle({
   const resolvedDiagnosticsProcessSamplesPath = path.join(diagnosticsDir, "process-samples.jsonl");
   const resolvedSourceCheckoutPath = path.resolve(resolvedWorkspace, ".buildchain/diagnostics/source-checkout.json");
   const resolvedDiagnosticsSourceCheckoutPath = path.join(diagnosticsDir, "source-checkout.json");
+  const resolvedCompilerCachePreparationPath = path.resolve(
+    resolvedWorkspace,
+    process.env.BUILDCHAIN_COMPILER_CACHE_PREPARATION_PATH ||
+      ".buildchain/diagnostics/compiler-cache-preparation.json",
+  );
+  const compilerCachePreparationRelative = path.relative(
+    resolvedWorkspace,
+    resolvedCompilerCachePreparationPath,
+  );
+  if (
+    compilerCachePreparationRelative.startsWith("..") ||
+    path.isAbsolute(compilerCachePreparationRelative)
+  ) {
+    throw new Error(
+      "BUILDCHAIN_COMPILER_CACHE_PREPARATION_PATH must remain inside the workflow workspace",
+    );
+  }
+  const resolvedDiagnosticsCompilerCachePreparationPath = path.join(
+    diagnosticsDir,
+    "compiler-cache-preparation.json",
+  );
   const resolvedDiagnosticsManifestPath = path.join(diagnosticsDir, "diagnostics-manifest.json");
   const relativeDiagnosticsEventsPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsEventsPath));
   const relativeDiagnosticsProcessSummaryPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsProcessSummaryPath));
   const relativeDiagnosticsProcessSamplesPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsProcessSamplesPath));
   const relativeDiagnosticsSourceCheckoutPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsSourceCheckoutPath));
+  const relativeDiagnosticsCompilerCachePreparationPath = toPosix(
+    path.relative(resolvedWorkspace, resolvedDiagnosticsCompilerCachePreparationPath),
+  );
   const relativeDiagnosticsManifestPath = toPosix(path.relative(resolvedWorkspace, resolvedDiagnosticsManifestPath));
   const logRunId = crypto.randomUUID();
   const frameworkLog = createBuildchainLogger({
@@ -622,9 +656,22 @@ export function runLifecycle({
   const sourceCheckoutArtifact = fs.existsSync(resolvedSourceCheckoutPath)
     ? JSON.parse(fs.readFileSync(resolvedSourceCheckoutPath, "utf8"))
     : undefined;
+  const compilerCachePreparationArtifact = fs.existsSync(resolvedCompilerCachePreparationPath)
+    ? JSON.parse(fs.readFileSync(resolvedCompilerCachePreparationPath, "utf8"))
+    : undefined;
   fs.mkdirSync(path.dirname(resolvedManifestPath), { recursive: true });
   const scanStartedAt = Date.now();
-  const files = collectArtifactFiles(resolvedWorkspace, artifactPaths);
+  const signingArtifactPaths = stageName === "build"
+    ? signingArtifactPathsForPlatform({
+        loadedConfig,
+        cwd: resolvedCwd,
+        platformId,
+      })
+    : [];
+  const files = collectArtifactFiles(resolvedWorkspace, [
+    ...artifactPaths,
+    ...signingArtifactPaths,
+  ]);
   const manifestFiles = files.map((file) => {
     const stat = fs.statSync(file);
     return {
@@ -743,6 +790,7 @@ export function runLifecycle({
       lifecycleObservability,
       processSummary: processSummaryArtifact?.summary,
       sourceCheckout: sourceCheckoutArtifact,
+      compilerCachePreparation: compilerCachePreparationArtifact,
       links: {
         artifactName,
         platformId,
@@ -757,6 +805,9 @@ export function runLifecycle({
         ...(processSummaryArtifact ? { diagnosticsProcessSummary: relativeDiagnosticsProcessSummaryPath } : {}),
         ...(processSummaryArtifact?.samplesPath ? { diagnosticsProcessSamples: relativeDiagnosticsProcessSamplesPath } : {}),
         ...(sourceCheckoutArtifact ? { sourceCheckout: relativeDiagnosticsSourceCheckoutPath } : {}),
+        ...(compilerCachePreparationArtifact
+          ? { compilerCachePreparation: relativeDiagnosticsCompilerCachePreparationPath }
+          : {}),
       },
     }),
   );
@@ -778,6 +829,12 @@ export function runLifecycle({
   if (sourceCheckoutArtifact) {
     copyIfExists(resolvedSourceCheckoutPath, resolvedDiagnosticsSourceCheckoutPath);
   }
+  if (compilerCachePreparationArtifact) {
+    copyIfExists(
+      resolvedCompilerCachePreparationPath,
+      resolvedDiagnosticsCompilerCachePreparationPath,
+    );
+  }
   writeDiagnosticsSidecarManifest(resolvedDiagnosticsManifestPath, {
     workspace: resolvedWorkspace,
     artifactName,
@@ -789,6 +846,10 @@ export function runLifecycle({
       { kind: "process-summary", filePath: resolvedDiagnosticsProcessSummaryPath },
       { kind: "process-samples", filePath: resolvedDiagnosticsProcessSamplesPath },
       { kind: "source-checkout", filePath: resolvedDiagnosticsSourceCheckoutPath },
+      {
+        kind: "compiler-cache-preparation",
+        filePath: resolvedDiagnosticsCompilerCachePreparationPath,
+      },
     ],
   });
   console.log(`buildchain_manifest=${path.relative(resolvedWorkspace, resolvedManifestPath)}`);

package/scripts/runtime-ref-core.mjs

@@ -98,7 +98,15 @@ export function resolveRuntimeSelection({
     };
   }
   const normalized = normalizeRequestedRuntimeRef(requested);
-  const runtimeOverride = !normalized.officialChannel;
+  const sameRepositoryWorkflow = String(workflowRef || "").startsWith(
+    `${buildchainRepository}/.github/workflows/`,
+  );
+  const pinnedSelfRuntime =
+    sameRepositoryWorkflow &&
+    normalized.exactSha &&
+    EXACT_SHA_RE.test(workflowShellRef) &&
+    normalized.ref.toLowerCase() === workflowShellRef.toLowerCase();
+  const runtimeOverride = !normalized.officialChannel && !pinnedSelfRuntime;
   return {
     requestedRef: requested,
     runtimeRef: normalized.ref,
@@ -107,7 +115,11 @@ export function resolveRuntimeSelection({
     runtimeOverride,
     workflowShellRef: workflowShellRef || defaultStableRef,
     rollbackRef: workflowShellRef || defaultStableRef,
-    trustDecision: normalized.officialChannel ? "official-channel" : "override-requested",
+    trustDecision: normalized.officialChannel
+      ? "official-channel"
+      : pinnedSelfRuntime
+        ? "pinned-self"
+        : "override-requested",
   };
 }
 
@@ -117,6 +129,7 @@ export function validateRuntimeOverrideTrust({
   eventAction = "",
   actorPermission = "",
   sameRepositoryPullRequest = false,
+  sameRepositoryWorkflow = false,
   pullRequestHeadSha = "",
   workflowShellSha = "",
 } = {}) {
@@ -129,6 +142,14 @@ export function validateRuntimeOverrideTrust({
   const normalizedRequested = String(requestedRef || "").trim().toLowerCase();
   const normalizedHeadSha = String(pullRequestHeadSha || "").trim().toLowerCase();
   const normalizedWorkflowShellSha = String(workflowShellSha || "").trim().toLowerCase();
+  if (
+    sameRepositoryWorkflow === true &&
+    EXACT_SHA_RE.test(normalizedRequested) &&
+    EXACT_SHA_RE.test(normalizedWorkflowShellSha) &&
+    normalizedRequested === normalizedWorkflowShellSha
+  ) {
+    return { ok: true, decision: "pinned-self" };
+  }
   if (
     eventName === "pull_request" &&
     eventAction === "closed" &&

package/scripts/seal-artifact-signing-requests.mjs

@@ -233,18 +233,16 @@ function verifyLifecycleBinding({
   );
   const relativeSubject = toPosix(path.relative(workspace, subjectPath));
   const files = descriptor.entries.filter(
-    (entry) => entry.type !== "directory",
+    (entry) => entry.type !== "directory" && entry.type !== "symlink",
   );
+  let matchedFiles = 0;
   for (const entry of files) {
-    if (entry.type === "symlink") continue;
     const manifestPath = fs.statSync(subjectPath).isFile()
       ? relativeSubject
       : `${relativeSubject}/${entry.path}`;
     const observed = byPath.get(manifestPath);
-    if (!observed)
-      throw new Error(
-        `signed artifact file is absent from lifecycle manifest: ${manifestPath}`,
-      );
+    if (!observed) continue;
+    matchedFiles += 1;
     if (
       `sha256:${observed.sha256}` !== entry.digest ||
       Number(observed.size) !== entry.bytes
@@ -254,6 +252,15 @@ function verifyLifecycleBinding({
       );
     }
   }
+  // A signing declaration is an independent artifact inventory and must not
+  // require consumers to repeat its path in workflow artifact-paths. When the
+  // lifecycle manifest does cover the subject, require complete coverage so a
+  // truncated or stale manifest cannot weaken the exact descriptor binding.
+  if (matchedFiles !== 0 && matchedFiles !== files.length) {
+    throw new Error(
+      `signed artifact is only partially represented in lifecycle manifest: ${relativeSubject}`,
+    );
+  }
 }
 
 export function sealArtifactSigningRequests({