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

package/packages/core/publication/candidate/sealing.js

@@ -0,0 +1,184 @@
+import { resolveOciCandidate } from "./kind.js";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+  publicationArtifactCandidateDigest,
+} from "../publication-artifact-candidate.js";
+import { createPublicationSealedBundle } from "../publication-sealed-bundle.js";
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function normalizeSha256(value, label) {
+  const digest = requiredString(value, label)
+    .replace(/^sha256:/, "")
+    .toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(digest))
+    throw new Error(`${label} must be a sha256 digest`);
+  return digest;
+}
+
+function assertGitSha(value, label) {
+  const sha = requiredString(value, label);
+  if (!/^[0-9a-f]{40}$/i.test(sha))
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  return sha.toLowerCase();
+}
+
+function collectCandidateFiles(root) {
+  const resolvedRoot = path.resolve(requiredString(root, "bundleRoot"));
+  const files = [];
+  const stack = fs.existsSync(resolvedRoot) ? [resolvedRoot] : [];
+  while (stack.length) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const absolutePath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(absolutePath);
+      } else if (entry.isFile()) {
+        files.push({
+          path: path
+            .relative(resolvedRoot, absolutePath)
+            .split(path.sep)
+            .join("/"),
+          absolutePath,
+          size: fs.statSync(absolutePath).size,
+          sha256: crypto
+            .createHash("sha256")
+            .update(fs.readFileSync(absolutePath))
+            .digest("hex"),
+        });
+      }
+    }
+  }
+  return {
+    resolvedRoot,
+    files: files.sort((left, right) => left.path.localeCompare(right.path)),
+  };
+}
+
+export function createResolvedPublicationSealedBundle({
+  bundleRoot,
+  repository,
+  sourceSha,
+  sourceTreeSha,
+  runtimeSha,
+  releaseCandidateRoot,
+  npmArtifacts = [],
+  releaseAssetPaths = [],
+} = {}) {
+  if (npmArtifacts.length === 0) return undefined;
+  const { resolvedRoot, files } = collectCandidateFiles(bundleRoot);
+  const byAbsolutePath = new Map(
+    files.map((file) => [path.resolve(file.absolutePath), file]),
+  );
+  const resolvedNpmArtifacts = npmArtifacts.map((artifact, index) => {
+    const file = byAbsolutePath.get(
+      path.resolve(
+        requiredString(artifact.path, `npmArtifacts[${index}].path`),
+      ),
+    );
+    if (!file)
+      throw new Error(
+        `npmArtifacts[${index}].path is outside the sealed payload root`,
+      );
+    return { file, metadata: artifact };
+  });
+  const main =
+    resolvedNpmArtifacts.find((entry) => entry.metadata.role === "main") ||
+    (resolvedNpmArtifacts.length === 1 ? resolvedNpmArtifacts[0] : undefined);
+  if (
+    !main ||
+    resolvedNpmArtifacts.filter((entry) => entry.metadata.role === "main")
+      .length > 1
+  )
+    throw new Error(
+      "candidate npm payload set has no unique main package tarball",
+    );
+  const selectedReleaseAssets = (
+    releaseAssetPaths.length > 0
+      ? releaseAssetPaths
+      : resolvedNpmArtifacts.map((entry) => entry.file.absolutePath)
+  ).map((assetPath, index) => {
+    const file = byAbsolutePath.get(path.resolve(assetPath));
+    if (!file)
+      throw new Error(
+        `releaseAssetPaths[${index}] is outside the sealed payload root`,
+      );
+    return file;
+  });
+  const candidatePayload = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+    repository: requiredString(repository, "repository"),
+    sourceSha: assertGitSha(sourceSha, "sourceSha"),
+    sourceTreeSha: assertGitSha(sourceTreeSha, "sourceTreeSha"),
+    runtimeSha: assertGitSha(runtimeSha, "runtimeSha"),
+    releaseCandidateRoot: `sha256:${normalizeSha256(releaseCandidateRoot, "releaseCandidateRoot")}`,
+    files: files.map(({ path: filePath, size, sha256 }) => ({
+      path: filePath,
+      size,
+      sha256,
+    })),
+  };
+  if (resolvedNpmArtifacts.length > 1) {
+    candidatePayload.npmPackages = resolvedNpmArtifacts.map(
+      ({ file, metadata }) => ({
+        name: metadata.name,
+        version: metadata.ref,
+        role: metadata.role,
+        path: file.path,
+        size: file.size,
+        sha256: file.sha256,
+        integrity: metadata.integrity,
+      }),
+    );
+  }
+  const candidate = {
+    ...candidatePayload,
+    candidateDigest: publicationArtifactCandidateDigest(candidatePayload),
+  };
+  const manifest = createPublicationSealedBundle({
+    candidate,
+    packageName: main.metadata.name,
+    packageVersion: main.metadata.ref,
+    npmTarballPath: main.file.path,
+    npmIntegrity: main.metadata.integrity,
+    releaseAssetPaths: selectedReleaseAssets.map((file) => file.path),
+  });
+  return {
+    root: resolvedRoot,
+    manifest,
+    npmArtifacts: resolvedNpmArtifacts,
+    files,
+  };
+}
+
+export function resolveCandidatePublicationBundle({
+  kind,
+  payloadDir,
+  passport,
+  runtimeSha,
+  npmArtifacts,
+  releaseAssetPaths,
+}) {
+  if (kind === "oci")
+    return resolveOciCandidate({ payloadRoot: payloadDir, passport });
+  if (kind !== "npm") return undefined;
+  return createResolvedPublicationSealedBundle({
+    bundleRoot: payloadDir,
+    repository: passport.repository,
+    sourceSha: passport.source?.headSha,
+    sourceTreeSha: passport.source?.treeHash,
+    runtimeSha,
+    releaseCandidateRoot: passport.candidateHash,
+    npmArtifacts,
+    releaseAssetPaths,
+  });
+}

package/packages/core/publication/candidate/stage-capsules.js

@@ -0,0 +1,205 @@
+import fs from "node:fs";
+import path from "node:path";
+import { domainContentRoot } from "../../contracts/canonical-contracts.js";
+import {
+  STAGE_CAPSULE_CONTRACT,
+  STAGE_CAPSULE_IDENTITY_CONTRACT,
+  stageCapsuleIdentityRoot,
+  stageCapsuleRoot,
+  validateStageCapsule,
+} from "../../build/stage-capsule.js";
+import { runtimeResumeDocumentRoot } from "../../consumer/runtime-ref-resume-authority.js";
+import { createDomainPublicationQualificationReceipt } from "../publication-qualification.js";
+
+const readJsonFile = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+export function createReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  coordinates,
+}) {
+  if (!passport.consumerPolicy?.receiptRoot) return undefined;
+  if (
+    coordinates.repository !== passport.repository ||
+    String(coordinates.runId) !== String(passport.workflow.runId) ||
+    String(coordinates.runAttempt) !== String(passport.workflow.runAttempt) ||
+    coordinates.sourceSha !== passport.source.headSha
+  ) {
+    throw new Error(
+      "Stage Capsule coordinate set does not bind the candidate run",
+    );
+  }
+  const coordinateByPlatform = new Map(
+    coordinates.artifacts.map((entry) => [entry.platformId, entry]),
+  );
+  const qualificationArtifacts = passport.platformMatrix.map((platform) => {
+    const coordinate = coordinateByPlatform.get(platform.platformId);
+    if (!coordinate || coordinate.name !== platform.artifactName)
+      throw new Error(
+        `Stage Capsule coordinate missing for ${platform.platformId}`,
+      );
+    const manifest = readJsonFile(platform.manifestPath);
+    return {
+      role: platform.artifactName,
+      platform: platform.platformId,
+      artifactRoot: coordinate.digest,
+      manifestRoot: domainContentRoot(
+        "stage-capsule-artifact-manifest",
+        manifest,
+      ),
+    };
+  });
+  const qualificationExpiresAt = coordinates.artifacts
+    .map((entry) => entry.expiresAt)
+    .sort((left, right) => Date.parse(left) - Date.parse(right))[0];
+  const qualificationReceipt = createDomainPublicationQualificationReceipt({
+    repository: passport.repository,
+    candidateRoot: `sha256:${passport.candidateHash}`,
+    sourceSha: passport.source.headSha,
+    sourceRoot: domainContentRoot("candidate-identity", passport.source),
+    policyDigest: passport.consumerPolicy.receiptRoot,
+    artifacts: qualificationArtifacts,
+    issuedAt:
+      passport.createdAt ||
+      new Date(Date.parse(qualificationExpiresAt) - 86_400_000).toISOString(),
+    expiresAt: qualificationExpiresAt,
+  });
+  const qualificationRoot = qualificationReceipt.receiptRoot;
+  const entries = passport.platformMatrix
+    .map((platform) => {
+      const coordinate = coordinateByPlatform.get(platform.platformId);
+      if (!coordinate || coordinate.name !== platform.artifactName) {
+        throw new Error(
+          `Stage Capsule coordinate missing for ${platform.platformId}`,
+        );
+      }
+      const manifest = readJsonFile(platform.manifestPath);
+      const identity = {
+        schema: STAGE_CAPSULE_IDENTITY_CONTRACT,
+        sourceRoot: domainContentRoot("candidate-identity", passport.source),
+        platform: platform.platformId,
+        platformRoot: domainContentRoot(
+          "candidate-identity",
+          manifest.platform,
+        ),
+        stage: "verify",
+        toolchainRoots: [],
+        runtimeRoot: domainContentRoot("candidate-identity", {
+          sha: passport.buildchain.sha,
+        }),
+        policyRoot: passport.consumerPolicy.receiptRoot,
+        declaredInputs: [
+          {
+            name: "release-candidate",
+            root: `sha256:${passport.candidateHash}`,
+          },
+        ],
+        transformationRoot: domainContentRoot("candidate-identity", {
+          lifecycle: manifest.lifecycle,
+          summary: platform.summary,
+        }),
+        outputManifestRoot: domainContentRoot(
+          "stage-capsule-artifact-manifest",
+          { artifact: coordinate, manifest },
+        ),
+        qualificationRoot,
+        observationRoots: [
+          {
+            name: "provider-coordinate",
+            root: domainContentRoot("provider-readback-sample", coordinate),
+          },
+        ],
+      };
+      const capsule = {
+        schema: STAGE_CAPSULE_CONTRACT,
+        writerAuthority: "typescript-v3",
+        rustAuthority: "validation-only",
+        identity,
+        identityRoot: stageCapsuleIdentityRoot(identity),
+        retentionPromise: {
+          class: "github-artifact",
+          retainUntil: coordinate.expiresAt,
+        },
+        capsuleRoot: `sha256:${"0".repeat(64)}`,
+      };
+      capsule.capsuleRoot = stageCapsuleRoot(capsule);
+      validateStageCapsule(capsule);
+      return {
+        platform: platform.platformId,
+        artifactName: coordinate.name,
+        artifactDigest: coordinate.digest,
+        publicationArtifact: qualificationArtifacts.find(
+          ({ platform: platformId }) => platformId === platform.platformId,
+        ),
+        artifact: coordinate,
+        capsule,
+      };
+    })
+    .sort((left, right) => left.platform.localeCompare(right.platform));
+  const body = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-release-candidate-stage-capsules/v1",
+    status: "sealed",
+    repository: passport.repository,
+    buildAttempt: {
+      id: `github-run:${passport.workflow.runId}:attempt:${passport.workflow.runAttempt}`,
+      runtimeSha: passport.buildchain.sha,
+    },
+    source: {
+      sha: passport.source.headSha,
+      treeSha: passport.source.treeHash,
+    },
+    consumerPolicyReceiptRoot: passport.consumerPolicy.receiptRoot,
+    publicationQualificationRoot: qualificationRoot,
+    publicationQualificationReceipt: qualificationReceipt,
+    capsules: entries,
+  };
+  return { ...body, root: runtimeResumeDocumentRoot(body) };
+}
+
+export function writeReleaseCandidateStageCapsules({
+  passport,
+  buildSummary,
+  outputPath,
+  coordinatesPath,
+  workspace,
+}) {
+  if (!fs.existsSync(coordinatesPath)) {
+    if (passport.consumerPolicy?.receiptRoot) {
+      throw new Error(
+        "v4 release candidate Stage Capsules require exact artifact coordinates",
+      );
+    }
+    return { path: "", root: "" };
+  }
+  const stageCapsules = createReleaseCandidateStageCapsules({
+    passport,
+    buildSummary,
+    coordinates: readJsonFile(coordinatesPath),
+  });
+  if (!stageCapsules) return { path: "", root: "" };
+  const stageCapsulesPath = path.join(
+    path.dirname(outputPath),
+    "release-candidate-stage-capsules.json",
+  );
+  fs.writeFileSync(
+    stageCapsulesPath,
+    `${JSON.stringify(stageCapsules, null, 2)}\n`,
+  );
+  const qualificationPath = path.join(
+    path.dirname(outputPath),
+    "release-candidate-publication-qualification.json",
+  );
+  fs.writeFileSync(
+    qualificationPath,
+    `${JSON.stringify(stageCapsules.publicationQualificationReceipt, null, 2)}\n`,
+  );
+  return {
+    path: path.relative(workspace, stageCapsulesPath).split(path.sep).join("/"),
+    root: stageCapsules.root,
+    qualificationPath: path
+      .relative(workspace, qualificationPath)
+      .split(path.sep)
+      .join("/"),
+    qualificationRoot: stageCapsules.publicationQualificationRoot,
+  };
+}

package/packages/core/publication/candidate/toolchain.js

@@ -0,0 +1,80 @@
+import { loadBuildchainConfig } from "../../consumer/buildchain-config.js";
+
+export async function resolvePublicationToolchain({
+  cwd,
+  toolchainType = "config",
+  toolchainImage = "",
+  toolchainDigest = "",
+  toolchainCommand = "",
+  buildCommand = "",
+}) {
+  const defaultLatexDockerCommand =
+    "latexmk -pdf -outdir=_build paper/main.tex";
+
+  const resolved = selectPublicationToolchain({
+    cwd,
+    toolchainType,
+    toolchainImage,
+    toolchainDigest,
+    toolchainCommand,
+  });
+  if (resolved.type === "custom-command" && !resolved.command) {
+    resolved.command = buildCommand || "";
+  }
+  if (!["custom-command", "latex-docker"].includes(resolved.type)) {
+    throw new Error(`unsupported publication toolchain: ${resolved.type}`);
+  }
+  if (resolved.type === "latex-docker") {
+    if (!resolved.command) {
+      resolved.command = defaultLatexDockerCommand;
+    }
+    if (!resolved.image)
+      throw new Error(
+        "latex-docker publication toolchain requires toolchain-image or publication.toolchain.image",
+      );
+    if (!/^sha256:[0-9a-f]{64}$/i.test(resolved.digest || "")) {
+      throw new Error(
+        "latex-docker publication toolchain requires toolchain-digest or publication.toolchain.digest as sha256:<64 hex>",
+      );
+    }
+    if (!resolved.command)
+      throw new Error(
+        "latex-docker publication toolchain requires toolchain-command or publication.toolchain.command",
+      );
+  }
+  return {
+    ...resolved,
+    imageRef:
+      resolved.image && resolved.digest
+        ? `${resolved.image}@${resolved.digest}`
+        : "",
+  };
+}
+
+function selectPublicationToolchain({
+  cwd,
+  toolchainType,
+  toolchainImage,
+  toolchainDigest,
+  toolchainCommand,
+}) {
+  const inputType = (toolchainType || "config").trim();
+  const inputToolchain = {
+    type: inputType,
+    image: toolchainImage || "",
+    digest: toolchainDigest || "",
+    command: toolchainCommand || "",
+  };
+  const configToolchain =
+    loadBuildchainConfig(cwd)?.config?.publication?.toolchain || {};
+  const resolved =
+    inputType && inputType !== "config"
+      ? inputToolchain
+      : {
+          type: configToolchain.type || "custom-command",
+          image: configToolchain.image || "",
+          digest: configToolchain.digest || "",
+          command: configToolchain.command || "",
+        };
+  return resolved;
+}

package/packages/core/publication/cli/dispatch.mjs

@@ -0,0 +1,107 @@
+import { npmPublishDryRun } from "../npm/preview.js";
+import { runPublicationArtifactCli } from "../commands/publication-artifact.mjs";
+import { runPublicationPackageCli } from "../commands/publication-package.mjs";
+import { runPublicationReproducibilityCli } from "../commands/publication-reproducibility.mjs";
+import {
+  BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
+  formatDiagnosticsSummaryTable,
+  startProcessSampler,
+  summarizeDiagnosticsArtifacts,
+  summarizeProcessSamples,
+  validateAnchoredPackageRelease,
+} from "../../observability/diagnostics.js";
+import {
+  printJson,
+  readBooleanFlag,
+  readFlag,
+  readJsonInput,
+  readRepeatedFlag,
+  readRepeatedJsonInputs,
+  writeJsonFile,
+} from "../../contracts/cli/options.mjs";
+import { runScript } from "../../workflow/cli/process.mjs";
+
+export async function handleNpmCommand(args) {
+  const [subcommand = "", ...npmArgs] = args;
+  if (subcommand !== "dry-run") {
+    throw new Error("usage: buildchain npm dry-run");
+  }
+  const result = npmPublishDryRun({
+    cwd: readFlag(npmArgs, "cwd", process.cwd()),
+    expectedTag: readFlag(npmArgs, "expected-tag", ""),
+    registry: readFlag(npmArgs, "registry", "https://registry.npmjs.org/"),
+    distTag: readFlag(npmArgs, "dist-tag", ""),
+    skipNpmPublishDryRun: readBooleanFlag(npmArgs, "skip-npm-publish-dry-run"),
+  });
+  if (readBooleanFlag(npmArgs, "json")) {
+    printJson(result);
+  } else {
+    process.stdout.write(
+      `npm publish dry-run ok: ${result.package.name}@${result.package.version} -> ${result.distTag}\n`,
+    );
+    process.stdout.write(`pack entries: ${result.pack.entryCount}\n`);
+  }
+  return;
+}
+
+export async function handlePublicationArtifactCommand(args) {
+  if (args[0] === "npm-package" || args[0] === "package") {
+    runPublicationPackageCli(args.slice(1));
+    return;
+  }
+  if (args[0] === "reproducibility" || args[0] === "reproducible") {
+    runPublicationReproducibilityCli(args.slice(1));
+    return;
+  }
+  runPublicationArtifactCli(args);
+  return;
+}
+
+export async function handlePublishSourceCommand(args) {
+  const [mode = "lock", ...publishArgs] = args;
+  if (mode === "lock" || mode === "manifest") {
+    runScript("packages/core/release/commands/resolve-publish-source.mjs", [
+      "--mode",
+      mode,
+      ...publishArgs,
+    ]);
+    return;
+  }
+  if (mode === "verify-lock") {
+    runScript(
+      "packages/core/release/commands/verify-publish-source-lock.mjs",
+      publishArgs,
+    );
+    return;
+  }
+  if (mode === "verify-channel-ref") {
+    runScript(
+      "packages/core/release/commands/verify-publish-channel-ref.mjs",
+      publishArgs,
+    );
+    return;
+  }
+  if (mode === "validate-anchored-release") {
+    const report = validateAnchoredPackageRelease({
+      cwd: readFlag(publishArgs, "cwd", process.cwd()),
+      requirePublishGateSourceLock: true,
+    });
+    if (readBooleanFlag(publishArgs, "json")) {
+      printJson(report);
+    } else {
+      process.stdout.write(
+        `anchored release source lock: ${report.ok ? "ok" : "failed"}\n`,
+      );
+      for (const entry of report.checks) {
+        process.stdout.write(
+          `- ${entry.status}: ${entry.id}: ${entry.message}\n`,
+        );
+      }
+    }
+    if (!report.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  throw new Error(`unsupported publish-source command: ${mode}`);
+}

package/packages/core/publication/commands/create-release-bundle.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createReleaseEvidenceBundle, BUNDLE_CONTRACT } from "../../build/release-evidence-bundle.js";
+function readArg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return process.argv[index + 1] || "";
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = createReleaseEvidenceBundle({
+      cwd: path.resolve(readArg("cwd", process.cwd())),
+      assetsDir: readArg("assets-dir", "dist/binary"),
+      passportDir: readArg("passport-dir", ".buildchain/release-passport"),
+      outputDir: readArg("output-dir", ".buildchain/release-passport"),
+      tag: readArg("tag", process.env.RELEASE_TAG || ""),
+      sourceSha: readArg("source-sha", process.env.GITHUB_SHA || ""),
+    });
+    process.stdout.write(`${JSON.stringify({
+      contract: BUNDLE_CONTRACT,
+      archive: result.manifest.bundle,
+      fileCount: result.manifest.files.length,
+    }, null, 2)}\n`);
+  } catch (error) {
+    console.error(`buildchain release bundle: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/publication/commands/generate-release-candidate-passport.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { writeReleaseCandidatePassport } from "../candidate/passport.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+const env = (name, fallback = "") => process.env[name] || fallback;
+const readJsonFile = file => JSON.parse(fs.readFileSync(file, "utf8"));
+export function generateReleaseCandidatePassportCli() {
+  const buildSummaryPath = path.resolve(env("BUILDCHAIN_BUILD_SUMMARY_PATH", ".buildchain/artifacts/build-summary.json"));
+  const outputPath = path.resolve(env("BUILDCHAIN_RC_PASSPORT_PATH", ".buildchain/artifacts/release-candidate-passport.json"));
+  const buildSummary = readJsonFile(buildSummaryPath);
+  const sourceSha = env("BUILDCHAIN_RC_SOURCE_HEAD_SHA", buildSummary.publishSource?.sha || buildSummary.git?.sha || "");
+  const version = env("BUILDCHAIN_RC_VERSION", buildSummary.publishSource?.consumerVersion || "");
+  const gateAggregateJson = env("BUILDCHAIN_GATE_PROFILE_AGGREGATE_JSON");
+  const gateAggregate = gateAggregateJson ? JSON.parse(gateAggregateJson) : undefined;
+  const controllerReceiptJson = env("BUILDCHAIN_CONTROLLER_RECEIPT_JSON");
+  const controllerReceipts = controllerReceiptJson ? [JSON.parse(controllerReceiptJson)] : [];
+  const familyEvidenceJson = env("BUILDCHAIN_RC_FAMILY_EVIDENCE_JSON");
+  const familyEvidence = familyEvidenceJson ? JSON.parse(familyEvidenceJson) : undefined;
+  const consumerPolicyJson = env("BUILDCHAIN_V4_POLICY_RECEIPT_JSON");
+  const consumerPolicyReceipt = consumerPolicyJson ? { receipt: JSON.parse(consumerPolicyJson), receiptRoot: env("BUILDCHAIN_V4_POLICY_RECEIPT_ROOT") } : undefined;
+  const request = {
+    repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
+    pullRequest: {
+      number: env("BUILDCHAIN_PULL_REQUEST_NUMBER"), url: env("BUILDCHAIN_PULL_REQUEST_URL"),
+      headRef: env("BUILDCHAIN_PULL_REQUEST_HEAD_REF"), baseRef: env("BUILDCHAIN_PULL_REQUEST_BASE_REF"),
+    },
+    targetChannel: env("BUILDCHAIN_RC_TARGET_CHANNEL", buildSummary.publishSource?.channel || buildSummary.publishGate?.channel || ""),
+    version,
+    sourceHeadSha: sourceSha,
+    baseSha: env("BUILDCHAIN_RC_BASE_SHA"),
+    mergeRefSha: env("BUILDCHAIN_RC_MERGE_REF_SHA", buildSummary.git?.sha || ""),
+    sourceTreeHash: env("BUILDCHAIN_RC_SOURCE_TREE_HASH"),
+    buildSummary,
+    buildchain: {
+      ref: env("BUILDCHAIN_RUNTIME_REF", buildSummary.runtime?.ref || ""), sha: env("BUILDCHAIN_RUNTIME_SHA", buildSummary.runtime?.sha || ""),
+      version: env("BUILDCHAIN_RUNTIME_VERSION"), workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""),
+    },
+    gateAggregate,
+    familyEvidence,
+    consumerPolicyReceipt,
+    controllerReceipts,
+    workflow: {
+      name: env("GITHUB_WORKFLOW"), runId: env("GITHUB_RUN_ID", buildSummary.git?.runId || ""),
+      runAttempt: env("GITHUB_RUN_ATTEMPT", buildSummary.git?.runAttempt || ""), url: env("BUILDCHAIN_WORKFLOW_RUN_URL"),
+    },
+  };
+  const { passport, stageCapsules } = writeReleaseCandidatePassport({ request, outputPath,
+    coordinatesPath: path.resolve(env("BUILDCHAIN_ARTIFACT_COORDINATES_PATH", ".buildchain/artifacts/artifact-coordinates.json")), workspace: process.cwd() });
+  writeGitHubOutputs({
+    "release-candidate-passport-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
+    "release-candidate-passport-json": JSON.stringify({
+      contract: passport.contract,
+      repository: passport.repository,
+      target: passport.target,
+      source: passport.source,
+      candidateHash: passport.candidateHash,
+      platformCount: passport.platformMatrix.length,
+      gateProfileEvidence: passport.gateProfileEvidence,
+      familyEvidence: passport.familyEvidence,
+      consumerPolicy: passport.consumerPolicy,
+      controllerReceipts: passport.controllerReceipts || [],
+    }),
+    "release-candidate-stage-capsules-path": stageCapsules.path,
+    "release-candidate-stage-capsules-root": stageCapsules.root,
+    "release-candidate-publication-qualification-path": stageCapsules.qualificationPath,
+    "release-candidate-publication-qualification-root": stageCapsules.qualificationRoot,
+  });
+  return passport;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    generateReleaseCandidatePassportCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}