@kungfu-tech/buildchain 4.0.2-alpha.2 → 4.0.2-alpha.21

package/scripts/resume-from-candidate-run.mjs

@@ -785,14 +785,13 @@ async function recoverCandidateEvidence({
   for (const artifact of [selected.passport, selected.summary]) initialDownloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   const passport = readOnlyJson(initialDownloads[0].files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "release-candidate-passport.json");
   const buildSummary = readOnlyJson(initialDownloads[1].files.filter((file) => path.basename(file.path) === "build-summary.json"), "build-summary.json");
-  const sidecarFiles = initialDownloads[0].files.filter(
-    (file) =>
-      path.basename(file.path) === "release-candidate-stage-capsules.json",
-  );
-  const stageCapsuleSidecar =
-    sidecarFiles.length === 1
-      ? readOnlyJson(sidecarFiles, "release-candidate-stage-capsules.json")
-      : undefined;
+  const [stageCapsuleFile, publicationQualificationFile] = [
+    "release-candidate-stage-capsules.json",
+    "release-candidate-publication-qualification.json",
+  ].map((name) => initialDownloads[0].files.find((file) => path.basename(file.path) === name));
+  const stageCapsuleSidecar = stageCapsuleFile
+    ? readOnlyJson([stageCapsuleFile], "release-candidate-stage-capsules.json")
+    : undefined;
   const { names: requiredNames, publicationNames } = candidateArtifactNames({ passport, selected, artifacts, artifactPatterns });
   const chosen = artifacts.filter((artifact) => requiredNames.has(artifact.name));
   if (chosen.length !== requiredNames.size) {
@@ -804,7 +803,7 @@ async function recoverCandidateEvidence({
   for (const artifact of chosen.filter((entry) => ![selected.passport.id, selected.summary.id].includes(entry.id))) downloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   return {
     run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-    passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
+    passport, buildSummary, stageCapsuleSidecar, stageCapsuleFile, publicationQualificationFile, chosen, downloads, publicationNames,
   };
 }
 
@@ -822,7 +821,7 @@ export async function resolveRecoveryTransaction({
   transactionId,
   publicationVersion,
 }) {
-  let transaction = publicationVersion
+  let transaction = transactionId && publicationVersion
     ? await readExistingTransaction({
         repoInfo,
         apiUrl,
@@ -878,7 +877,7 @@ export async function resumeFromCandidateRun({
   try {
     const {
       run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-      passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
+      passport, buildSummary, stageCapsuleSidecar, stageCapsuleFile, publicationQualificationFile, chosen, downloads, publicationNames,
     } = await recoverCandidateEvidence({
       repoInfo, runId, artifactName, artifactPatterns, requiredArtifactCount,
       outputDir, apiUrl, token, fetchImpl, archiveDir,
@@ -1023,9 +1022,9 @@ export async function resumeFromCandidateRun({
         sealedBundleRoot: publication.manifest ? outputPath(bundleRoot) : "",
         sealedBundleManifest: publication.manifest ? outputPath(sealedManifestPath) : "",
         recoveryReceipt: outputPath(recoveryReceiptPath),
-        runtimeResumeEvidence: runtimeResumeEvidencePath
-          ? outputPath(runtimeResumeEvidencePath)
-          : "",
+        stageCapsules: stageCapsuleFile ? outputPath(stageCapsuleFile.absolutePath) : "",
+        publicationQualification: publicationQualificationFile ? outputPath(publicationQualificationFile.absolutePath) : "",
+        runtimeResumeEvidence: runtimeResumeEvidencePath ? outputPath(runtimeResumeEvidencePath) : "",
       },
     };
   } finally {
@@ -1077,10 +1076,10 @@ export async function resumeFromCandidateRunCli() {
       "release-candidate-run-url": result.run.url,
       "release-candidate-recovery-receipt-path": result.paths.recoveryReceipt,
       "release-candidate-recovery-root": result.receipt.root,
+      "release-candidate-stage-capsules-path": result.paths.stageCapsules,
+      "release-candidate-publication-qualification-path": result.paths.publicationQualification,
       "v4-runtime-resume-evidence-path": result.paths.runtimeResumeEvidence,
-      "v4-runtime-resume-finalize-command": result.paths.runtimeResumeEvidence
-        ? "node .buildchain/runtime/promotion-shell/scripts/resume-from-candidate-run.mjs finalize"
-        : "",
+      "v4-runtime-resume-finalize-command": result.paths.runtimeResumeEvidence ? "node .buildchain/runtime/promotion-shell/scripts/resume-from-candidate-run.mjs finalize" : "",
       "release-candidate-root": result.candidateRoot,
       "release-candidate-artifact-root": result.artifactRoot,
       "publish-sealed-bundle-root": result.paths.sealedBundleRoot,

package/scripts/universal-facade-maintainability.mjs

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function loadUniversalFacadeMigration(root) {
+  const contract = JSON.parse(
+    fs.readFileSync(
+      path.join(root, "architecture/v4-universal-workflow-bootstrap.json"),
+      "utf8",
+    ),
+  );
+  const retired = new Set(contract.retiredWorkflowSurfaces || []);
+  const paths = (contract.bootstrapGovernedWorkflows || []).filter(
+    (entry) =>
+      entry !== contract.bootstrap?.publicWorkflow && !retired.has(entry),
+  );
+  const sourceRevision = contract.migration?.facadeSourceRevision || "";
+  if (!/^[0-9a-f]{40}$/u.test(sourceRevision)) {
+    throw new Error(
+      "universal facade migration requires an exact facadeSourceRevision",
+    );
+  }
+  return { paths: new Set(paths), sourceRevision };
+}
+
+function verifyUniversalFacadeMigration(root) {
+  execFileSync(
+    process.execPath,
+    ["scripts/generate-v4-universal-workflow-facades.mjs", "--check"],
+    { cwd: root, stdio: "pipe" },
+  );
+}
+
+function governUniversalFacadeWorkflowMetrics({
+  root,
+  current,
+  workflowMetricsAtRevision,
+}) {
+  const migration = loadUniversalFacadeMigration(root);
+  verifyUniversalFacadeMigration(root);
+  const frozen = workflowMetricsAtRevision(root, migration.sourceRevision);
+  const governed = { ...current, workflows: { ...current.workflows } };
+  for (const file of migration.paths) {
+    if (!frozen[file])
+      throw new Error(`frozen universal facade source is missing ${file}`);
+    governed.workflows[file] = frozen[file];
+  }
+  return { governed, migration };
+}
+
+function isGeneratedFacadePublicTransition({
+  entry,
+  kind,
+  migration,
+  baseContract,
+  currentContract,
+}) {
+  if (kind !== "workflow" || !migration?.paths.has(entry.path) || !baseContract)
+    return false;
+  const { inputs: currentInputs, ...currentRest } = currentContract;
+  const { inputs: previousInputs, ...previousRest } = baseContract;
+  if (JSON.stringify(currentRest) !== JSON.stringify(previousRest))
+    return false;
+  const added = currentInputs.filter(
+    (input) => !previousInputs.includes(input),
+  );
+  const removed = previousInputs.filter(
+    (input) => !currentInputs.includes(input),
+  );
+  return (
+    removed.length === 0 &&
+    added.length === 1 &&
+    added[0] === "universal-request-json"
+  );
+}
+
+export {
+  governUniversalFacadeWorkflowMetrics,
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+  verifyUniversalFacadeMigration,
+};

package/scripts/v4-product-publication-intent.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { spawnSyncCommand } from "../packages/core/spawn-command.js";
+import { selectV4ProductPublicationIntent } from "../packages/core/v4-product-publication.js";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+
+function env(name, required = false) {
+  const value = String(process.env[name] || "").trim();
+  if (required && !value) throw new Error(`${name} is required`);
+  return value;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(path.resolve(file), "utf8"));
+}
+
+function packageName() {
+  const declared = env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN");
+  if (declared) return declared;
+  const manifestPath = env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true);
+  const manifest = readJson(manifestPath);
+  const selected = String(manifest?.npm?.name || "").trim();
+  if (!selected)
+    throw new Error("sealed bundle manifest does not declare npm.name");
+  return selected;
+}
+
+function observedVersions(name) {
+  const result = spawnSyncCommand(
+    "npm",
+    [
+      "view",
+      name,
+      "versions",
+      "--json",
+      "--registry=https://registry.npmjs.org/",
+    ],
+    { encoding: "utf8" },
+  );
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+    if (/\bE404\b|404 Not Found|is not in this registry/iu.test(output))
+      return [];
+    throw new Error(`npm version discovery failed: ${output.trim()}`);
+  }
+  const parsed = JSON.parse(String(result.stdout || "[]"));
+  return Array.isArray(parsed) ? parsed : [parsed].filter(Boolean);
+}
+
+function writeOutput(name, value) {
+  const output = env("GITHUB_OUTPUT");
+  if (!output) return;
+  fs.appendFileSync(output, `${name}=${String(value)}\n`);
+}
+
+export function resolveV4ProductPublicationIntent() {
+  const name = packageName();
+  const sourceSha = env("BUILDCHAIN_SOURCE_SHA", true);
+  const manifest = readJson(env("BUILDCHAIN_SEALED_BUNDLE_MANIFEST", true));
+  const requiredArtifacts = readJson(
+    env("BUILDCHAIN_REQUIRED_ARTIFACTS_PATH", true),
+  );
+  const channel = env("BUILDCHAIN_CHANNEL", true);
+  const intent = selectV4ProductPublicationIntent({
+    channel,
+    targetRef: env("BUILDCHAIN_TARGET_REF", true),
+    sourceSha,
+    sourceTimestamp: env("BUILDCHAIN_SOURCE_TIMESTAMP", true),
+    repository: env("BUILDCHAIN_REPOSITORY", true),
+    packageName: name,
+    distTag:
+      env("BUILDCHAIN_PUBLISH_DIST_TAG") ||
+      (channel === "alpha" ? "alpha" : "latest"),
+    sealedBundleRoot: manifest.root,
+    requiredArtifactsRoot: v4ContentRoot(
+      "v4-product-required-artifacts",
+      requiredArtifacts,
+    ),
+    candidateVersion: env("BUILDCHAIN_CANDIDATE_VERSION", true),
+    recoveredVersion: env("BUILDCHAIN_RECOVERED_PUBLICATION_VERSION"),
+    observedVersions: observedVersions(name),
+  });
+  const outputPath = path.resolve(
+    env("BUILDCHAIN_PRODUCT_PUBLICATION_INTENT_PATH") ||
+      ".buildchain/release-candidate/v4-product-publication-intent.json",
+  );
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(intent, null, 2)}\n`);
+  writeOutput("version", intent.version);
+  writeOutput("exact-tag", intent.exactTag);
+  writeOutput("intent-path", outputPath);
+  writeOutput("intent-root", intent.intentRoot);
+  return { name, intent, outputPath };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const result = resolveV4ProductPublicationIntent();
+    process.stdout.write(
+      `v4 product publication intent: ${result.name}@${result.intent.version} (${result.intent.mode})\n`,
+    );
+  } catch (error) {
+    console.error(`v4-product-publication-intent: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/v4-release-candidate-adapter.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function resolveV4ReleaseCandidateAdapter({
+  resumeCandidateRunId = "",
+} = {}) {
+  const mode = String(resumeCandidateRunId || "").trim() ? "recovery" : "fresh";
+  return Object.freeze({
+    mode,
+    script:
+      mode === "recovery"
+        ? "scripts/resume-from-candidate-run.mjs"
+        : "scripts/release-candidate-resolver.mjs",
+  });
+}
+
+export function runV4ReleaseCandidateAdapter({
+  env = process.env,
+  exec = execFileSync,
+} = {}) {
+  const route = resolveV4ReleaseCandidateAdapter({
+    resumeCandidateRunId: env.BUILDCHAIN_RESUME_CANDIDATE_RUN_ID,
+  });
+  exec(process.execPath, [path.join(root, route.script)], {
+    env,
+    stdio: "inherit",
+  });
+  return route;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  runV4ReleaseCandidateAdapter();
+}

package/scripts/v4-universal-workflow-backflow.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  validateV4UniversalWorkflowRequest,
+  v4UniversalWorkflowRequestRoot,
+} from "../packages/core/v4-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 !== v4UniversalWorkflowRequestRoot(request) ||
+    !SHA.test(value.runtime?.sha || "") ||
+    !ROOT.test(value.receiptRoot || "")
+  )
+    fail(
+      "successful exact-candidate terminal receipt is required for backflow",
+    );
+  return value;
+}
+
+export function createV4UniversalBackflowPlan({
+  request: requestValue,
+  receipt,
+}) {
+  const request = validateV4UniversalWorkflowRequest(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.0",
+    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 upsertV4UniversalBackflow({
+  request,
+  receipt,
+  token,
+  fetchImpl = globalThis.fetch,
+}) {
+  const admitted = validateV4UniversalWorkflowRequest(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 = createV4UniversalBackflowPlan({ 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,
+  };
+}
+
+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 upsertV4UniversalBackflow({
+    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();