@kungfu-tech/buildchain 2.14.2 → 2.14.3-alpha.1

package/scripts/generate-channel-promotion-workflow.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourcePath = path.join(root, ".github/workflows/.release-candidate-promote.yml");
+const targetPath = path.join(root, ".github/workflows/release-candidate-promote.yml");
+const internalInputs = new Set([
+  "promotion-router-ref",
+  "promotion-router-sha",
+  "promotion-shell-ref",
+  "promotion-shell-sha",
+  "promotion-runtime-ref",
+  "promotion-runtime-sha",
+  "promotion-contract-lock-path",
+  "promotion-contract-lock-digest",
+  "promotion-publication-channel",
+  "promotion-target-ref",
+  "promotion-override-used",
+]);
+
+function blockBetween(source, start, end) {
+  const startIndex = source.indexOf(start);
+  const endIndex = source.indexOf(end, startIndex + start.length);
+  if (startIndex < 0 || endIndex < 0) throw new Error(`unable to locate workflow block: ${start.trim()}`);
+  return source.slice(startIndex + start.length, endIndex);
+}
+
+function entries(block, indent = 6) {
+  const pattern = new RegExp(`^ {${indent}}([a-z0-9-]+):$`, "gm");
+  const matches = [...block.matchAll(pattern)];
+  return matches.map((match, index) => ({
+    name: match[1],
+    source: block.slice(match.index, matches[index + 1]?.index ?? block.length).trimEnd(),
+  }));
+}
+
+function publicInputs(inputBlock) {
+  const retained = entries(inputBlock)
+    .filter((entry) => !internalInputs.has(entry.name))
+    .map((entry) => entry.name === "buildchain-contract-lock-path"
+      ? entry.source.replace('        default: ".buildchain/contract-lock.json"', '        default: ""')
+      : entry.source);
+  return [
+    "      buildchain-channel:",
+    '        description: "Promotion workflow-shell/runtime channel: auto, alpha, or stable"',
+    '        default: "auto"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-alpha-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for alpha promotion"',
+    '        default: ".buildchain/alpha-contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-stable-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for stable promotion"',
+    '        default: ".buildchain/contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    ...retained,
+  ].join("\n");
+}
+
+function publicOutputs(outputBlock) {
+  const forwarded = entries(outputBlock).map((entry) => entry.source.replace(
+    /^        value:.*$/m,
+    `        value: \${{ jobs.alpha.outputs.${entry.name} || jobs.stable.outputs.${entry.name} }}`,
+  ));
+  const routed = [
+    ["buildchain-channel", "Selected promotion workflow-shell channel", "channel"],
+    ["promotion-router-ref", "Router workflow ref", "router-ref"],
+    ["promotion-router-sha", "Resolved router workflow SHA", "router-sha"],
+    ["promotion-shell-ref", "Selected advanced promotion workflow-shell ref", "shell-ref"],
+    ["promotion-shell-sha", "Resolved advanced promotion workflow-shell SHA", "shell-sha"],
+    ["promotion-runtime-ref", "Selected Buildchain runtime ref", "runtime-ref"],
+    ["promotion-runtime-sha", "Resolved Buildchain runtime SHA", "runtime-sha"],
+    ["promotion-contract-lock-path", "Selected consumer contract-lock path", "contract-lock-path"],
+    ["promotion-contract-lock-digest", "Selected consumer contract-lock sha256 digest", "contract-lock-digest"],
+    ["promotion-publication-channel", "Derived publication channel", "publication-channel"],
+    ["promotion-target-ref", "Derived promotion target ref", "target-ref"],
+    ["promotion-override-used", "Whether a trusted runtime override was used", "override-used"],
+  ].map(([name, description, output]) => [
+    `      ${name}:`,
+    `        description: "${description}"`,
+    `        value: \${{ jobs.resolve-promotion.outputs.${output} }}`,
+  ].join("\n"));
+  return [...routed, ...forwarded].join("\n");
+}
+
+function forwardedInputs(inputNames) {
+  return inputNames.map((name) => {
+    const routed = {
+      "buildchain-ref": "runtime-ref",
+      "buildchain-contract-lock-path": "contract-lock-path",
+      channel: "publication-channel",
+      "target-ref": "target-ref",
+      "promotion-router-ref": "router-ref",
+      "promotion-router-sha": "router-sha",
+      "promotion-shell-ref": "shell-ref",
+      "promotion-shell-sha": "shell-sha",
+      "promotion-runtime-ref": "runtime-ref",
+      "promotion-runtime-sha": "runtime-sha",
+      "promotion-contract-lock-path": "contract-lock-path",
+      "promotion-contract-lock-digest": "contract-lock-digest",
+      "promotion-publication-channel": "publication-channel",
+      "promotion-target-ref": "target-ref",
+      "promotion-override-used": "override-used",
+    }[name];
+    return routed
+      ? `      ${name}: \${{ needs.resolve-promotion.outputs.${routed} }}`
+      : `      ${name}: \${{ inputs.${name} }}`;
+  }).join("\n");
+}
+
+export function generateChannelPromotionWorkflow(source, { major = 2 } = {}) {
+  const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
+  const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
+  const outputs = blockBetween(source, "    outputs:\n", "\nconcurrency:\n");
+  const inputNames = entries(inputs).map((entry) => entry.name);
+  for (const required of ["buildchain-ref", "buildchain-contract-lock-path", "channel", "target-ref", ...internalInputs]) {
+    if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
+  }
+  const forwarded = forwardedInputs(inputNames);
+  return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
+name: Release Candidate Promote
+
+on:
+  workflow_call:
+    inputs:
+${publicInputs(inputs)}
+    secrets:
+${secrets.trimEnd()}
+    outputs:
+${publicOutputs(outputs)}
+
+permissions:
+  actions: read
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  resolve-promotion:
+    name: Resolve promotion workflow shell and runtime
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    outputs:
+      channel: \${{ steps.route.outputs.channel }}
+      publication-channel: \${{ steps.route.outputs.publication-channel }}
+      target-ref: \${{ steps.route.outputs.target-ref }}
+      router-ref: \${{ steps.router.outputs.ref }}
+      router-sha: \${{ steps.identities.outputs.router-sha }}
+      shell-ref: \${{ steps.route.outputs.shell-ref }}
+      shell-sha: \${{ steps.identities.outputs.shell-sha }}
+      runtime-ref: \${{ steps.route.outputs.runtime-ref }}
+      runtime-sha: \${{ steps.identities.outputs.runtime-sha }}
+      contract-lock-path: \${{ steps.lock.outputs.path }}
+      contract-lock-digest: \${{ steps.lock.outputs.digest }}
+      override-used: \${{ steps.route.outputs.override-used }}
+      selection-source: \${{ steps.route.outputs.selection-source }}
+      reason: \${{ steps.route.outputs.reason }}
+    steps:
+      - name: Resolve promotion router source
+        id: router
+        shell: bash
+        env:
+          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}
+        run: |
+          set -euo pipefail
+          workflow_ref="\${BUILDCHAIN_ROUTER_WORKFLOW_REF}"
+          repository="\${workflow_ref%%/.github/workflows/*}"
+          ref="\${workflow_ref##*@}"
+          ref="\${ref#refs/heads/}"
+          ref="\${ref#refs/tags/}"
+          if [[ -z "\${repository}" || "\${repository}" = "\${workflow_ref}" || -z "\${ref}" ]]; then
+            echo "::error::Unable to resolve promotion router source from job.workflow_ref=\${workflow_ref}"
+            exit 1
+          fi
+          echo "repository=\${repository}" >> "\${GITHUB_OUTPUT}"
+          echo "ref=\${ref}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Checkout promotion router
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.router.outputs.ref }}
+          path: .buildchain/router
+          persist-credentials: false
+
+      - name: Resolve promotion channel
+        id: route
+        shell: bash
+        run: >-
+          node .buildchain/router/scripts/promotion-channel-router.mjs
+          --cwd .buildchain/router
+          --channel "\${{ inputs.buildchain-channel }}"
+          --buildchain-ref "\${{ inputs.buildchain-ref }}"
+          --publication-channel "\${{ inputs.channel }}"
+          --target-ref "\${{ inputs.target-ref || github.ref_name }}"
+          --router-ref "\${{ steps.router.outputs.ref }}"
+
+      - name: Authorize trusted runtime override
+        if: \${{ steps.route.outputs.override-used == 'true' }}
+        uses: actions/github-script@v8
+        with:
+          script: |
+            if (context.eventName !== "workflow_dispatch") {
+              throw new Error("promotion runtime override is only allowed for trusted workflow_dispatch runs");
+            }
+            const permission = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.actor,
+            });
+            const level = permission.data.user?.permissions || permission.data.permission || "none";
+            if (!["write", "maintain", "admin"].includes(level)) {
+              throw new Error(\`promotion runtime override requires write, maintain, or admin permission; actor has \${level}\`);
+            }
+
+      - name: Checkout selected promotion workflow shell
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.shell-ref }}
+          path: .buildchain/shell
+          persist-credentials: false
+
+      - name: Checkout selected Buildchain runtime
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.runtime-ref }}
+          path: .buildchain/runtime
+          persist-credentials: false
+
+      - name: Checkout promotion source
+        uses: actions/checkout@v7.0.0
+        with:
+          ref: \${{ inputs.target-sha || github.sha }}
+          path: .buildchain/source
+          persist-credentials: false
+
+      - name: Select and verify consumer contract lock
+        id: lock
+        shell: bash
+        env:
+          EXPLICIT_PATH: \${{ inputs.buildchain-contract-lock-path }}
+          ALPHA_PATH: \${{ inputs.buildchain-alpha-contract-lock-path }}
+          STABLE_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
+          CHANNEL: \${{ steps.route.outputs.channel }}
+        run: |
+          set -euo pipefail
+          path="\${EXPLICIT_PATH}"
+          if [[ -z "\${path}" ]]; then
+            if [[ "\${CHANNEL}" = "alpha" ]]; then path="\${ALPHA_PATH}"; else path="\${STABLE_PATH}"; fi
+          fi
+          if [[ -z "\${path}" || ! -f ".buildchain/source/\${path}" ]]; then
+            echo "::error::Selected promotion contract lock is missing: \${path:-<empty>}"
+            exit 1
+          fi
+          digest="sha256:$(shasum -a 256 ".buildchain/source/\${path}" | awk '{print $1}')"
+          echo "path=\${path}" >> "\${GITHUB_OUTPUT}"
+          echo "digest=\${digest}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Resolve immutable promotion identities
+        id: identities
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f .buildchain/shell/.github/workflows/.release-candidate-promote.yml
+          {
+            echo "router-sha=$(git -C .buildchain/router rev-parse HEAD)"
+            echo "shell-sha=$(git -C .buildchain/shell rev-parse HEAD)"
+            echo "runtime-sha=$(git -C .buildchain/runtime rev-parse HEAD)"
+          } >> "\${GITHUB_OUTPUT}"
+
+  alpha:
+    name: Promote with alpha workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'alpha' }}
+    uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@v${major}-alpha
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${forwarded}
+    secrets: inherit
+
+  stable:
+    name: Promote with stable workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'stable' }}
+    uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@v${major}
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${forwarded}
+    secrets: inherit
+`;
+}
+
+function main() {
+  const source = fs.readFileSync(sourcePath, "utf8");
+  const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  const major = Number(String(version).match(/^(\d+)\./)?.[1]);
+  if (!Number.isInteger(major)) throw new Error("package version must expose a numeric major");
+  const generated = generateChannelPromotionWorkflow(source, { major });
+  if (process.argv.includes("--check")) {
+    const current = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : "";
+    if (current !== generated) {
+      console.error(".github/workflows/release-candidate-promote.yml is stale; run node scripts/generate-channel-promotion-workflow.mjs");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  fs.writeFileSync(targetPath, generated);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();

package/scripts/generate-site-bundle.mjs

@@ -17,6 +17,10 @@ import {
 import {
   createReadmeBadgeEndpointRegistry,
 } from "../packages/core/readme-badges.js";
+import {
+  RELEASE_PASSPORT_SCHEMA,
+  createReleasePassportCheckManifest,
+} from "../packages/core/release-passport-contract.js";
 import {
   collectPublicSurfaceReverseAudit,
   enumerateActionInputs,
@@ -496,6 +500,7 @@ function nodeApiMeta(exportName) {
     "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
     "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
     "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
+    "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
     "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
@@ -915,6 +920,8 @@ function buildSiteBundle() {
       entrypoint: "buildchain.release.json",
       bundle: "buildchain-release-bundle.tar.gz",
       contract: "kungfu-buildchain-release-passport",
+      schema: "schemas/release-passport-v1.schema.json",
+      checkManifest: "release-passport-check-manifest.json",
     },
     releasePropagation: {
       graphContract: "kungfu-buildchain-release-propagation-graph",
@@ -956,6 +963,8 @@ function buildSiteBundle() {
     contract: "kungfu-buildchain-artifact-schema-index",
     releasePassport: [
       "buildchain.release.json",
+      "release-passport-check-manifest.json",
+      "schemas/release-passport-v1.schema.json",
       "artifact-evidence.json",
       "product-mechanism.json",
       "impact.json",
@@ -981,6 +990,8 @@ function buildSiteBundle() {
       "public-surface-audit.json",
       "release-model.json",
       "artifact-schemas.json",
+      "release-passport-check-manifest.json",
+      "schemas/release-passport-v1.schema.json",
       "buildchain-contract.json",
       "kfd-claims.json",
       "product-mechanism.json",
@@ -1090,6 +1101,8 @@ function buildSiteBundle() {
       "publication-authority-registry.json",
       "public-surface-audit.json",
       "artifact-schemas.json",
+      "release-passport-check-manifest.json",
+      "schemas/release-passport-v1.schema.json",
       "buildchain-contract.json",
       "kfd-upstream-aggregate.json",
       "kfd-claims.json",
@@ -1260,6 +1273,8 @@ function buildSiteBundle() {
     "public-surface-audit.json": publicSurfaceAudit,
     "release-model.json": releaseModel,
     "artifact-schemas.json": artifactSchemas,
+    "release-passport-check-manifest.json": createReleasePassportCheckManifest(),
+    "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),

package/scripts/promotion-channel-router.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveBuildchainChannel } from "./buildchain-channel-router.mjs";
+
+const TARGETS = [
+  { pattern: /^alpha\/v(\d+)\/v\d+\.\d+$/, publicationChannel: "alpha", shellChannel: "alpha" },
+  { pattern: /^release\/v(\d+)\/v\d+\.\d+$/, publicationChannel: "release", shellChannel: "stable" },
+  { pattern: /^(?:publish-gate\/major|major-gate)$/, publicationChannel: "major", shellChannel: "stable" },
+];
+
+function normalized(value) {
+  return String(value ?? "").trim();
+}
+
+function targetIntent(targetRef, requestedPublicationChannel = "") {
+  const ref = normalized(targetRef).replace(/^refs\/heads\//, "");
+  const target = TARGETS.find((entry) => entry.pattern.test(ref));
+  if (!target) throw new Error(`unsupported promotion target ref: ${ref || "<empty>"}`);
+  const requested = normalized(requestedPublicationChannel).toLowerCase();
+  if (requested && requested !== target.publicationChannel) {
+    throw new Error(`promotion channel ${requested} does not match target ref ${ref} (${target.publicationChannel})`);
+  }
+  const match = ref.match(target.pattern);
+  return {
+    targetRef: ref,
+    publicationChannel: target.publicationChannel,
+    shellChannel: target.shellChannel,
+    targetMajor: match?.[1] ? Number(match[1]) : undefined,
+  };
+}
+
+export function resolvePromotionChannel({
+  requestedChannel = "auto",
+  requestedRef = "",
+  publicationChannel = "",
+  targetRef = "",
+  routerRef = "",
+  packageVersion = "",
+} = {}) {
+  const intent = targetIntent(targetRef, publicationChannel);
+  const selected = resolveBuildchainChannel({
+    requestedChannel,
+    requestedRef,
+    publishChannel: intent.publicationChannel,
+    eventName: "workflow_call",
+    routerRef,
+    packageVersion,
+  });
+  const overrideUsed = selected.channel === "override";
+  if (!overrideUsed && selected.channel !== intent.shellChannel) {
+    throw new Error(
+      `promotion target ${intent.targetRef} requires ${intent.shellChannel} shell/runtime, got ${selected.channel}`,
+    );
+  }
+  if (Number.isInteger(intent.targetMajor) && selected.major !== intent.targetMajor) {
+    throw new Error(
+      `promotion target ${intent.targetRef} requires Buildchain v${intent.targetMajor}, got v${selected.major}`,
+    );
+  }
+  const shellRef = intent.shellChannel === "alpha" ? `v${selected.major}-alpha` : `v${selected.major}`;
+  return {
+    targetRef: intent.targetRef,
+    publicationChannel: intent.publicationChannel,
+    channel: intent.shellChannel,
+    major: selected.major,
+    shellRef,
+    runtimeRef: selected.buildchainRef,
+    overrideUsed,
+    selectionSource: selected.selectionSource,
+    reason: selected.reason,
+  };
+}
+
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`missing value for ${token}`);
+    values[token.slice(2)] = value;
+    index += 1;
+  }
+  return values;
+}
+
+function readPackageVersion(cwd) {
+  return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).version;
+}
+
+function writeOutputs(file, result) {
+  const outputs = {
+    "target-ref": result.targetRef,
+    "publication-channel": result.publicationChannel,
+    channel: result.channel,
+    major: String(result.major),
+    "shell-ref": result.shellRef,
+    "runtime-ref": result.runtimeRef,
+    "override-used": String(result.overrideUsed),
+    "selection-source": result.selectionSource,
+    reason: result.reason,
+  };
+  fs.appendFileSync(file, Object.entries(outputs).map(([key, value]) => `${key}=${value}\n`).join(""));
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = path.resolve(args.cwd || process.cwd());
+  const result = resolvePromotionChannel({
+    requestedChannel: args.channel,
+    requestedRef: args["buildchain-ref"],
+    publicationChannel: args["publication-channel"],
+    targetRef: args["target-ref"],
+    routerRef: args["router-ref"],
+    packageVersion: readPackageVersion(cwd),
+  });
+  if (process.env.GITHUB_OUTPUT) writeOutputs(process.env.GITHUB_OUTPUT, result);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`promotion-channel-router: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/validate-package-manager-contract.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { validatePackageManagerContract } from "../packages/core/package-manager.js";
+
+const cwd = path.resolve(
+  process.env.BUILDCHAIN_PACKAGE_MANAGER_CWD || process.argv[2] || process.cwd(),
+);
+const expectedManager = process.env.BUILDCHAIN_EXPECTED_PACKAGE_MANAGER || "";
+const contract = validatePackageManagerContract({ cwd, expectedManager });
+
+if (process.env.GITHUB_OUTPUT) {
+  fs.appendFileSync(
+    process.env.GITHUB_OUTPUT,
+    `name=${contract.name}\ndeclared-spec=${contract.declaredSpec}\ndeclared-version=${contract.declaredVersion}\n`,
+  );
+}
+
+console.log(JSON.stringify({
+  schemaVersion: 1,
+  contract: "kungfu-buildchain-consumer-package-manager",
+  ...contract,
+}, null, 2));