@kungfu-tech/buildchain 2.11.14-alpha.7 → 2.12.0-alpha.0

package/scripts/check-inventory.mjs

@@ -4,6 +4,8 @@ import {
   assertPublicSurfaceReverseAudit,
   collectPublicSurfaceReverseAudit,
 } from "../packages/core/public-surface-audit.js";
+import { evaluateBuildchainContractLock } from "../packages/core/buildchain-contract.js";
+import { generateChannelBuildWorkflow } from "./generate-channel-build-workflow.mjs";
 
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
@@ -38,6 +40,8 @@ const requiredPaths = [
   "docs/toolkit-observability.md",
   "docs/versioning.md",
   "scripts/release-line-dry-run.mjs",
+  "scripts/buildchain-channel-router.mjs",
+  "scripts/generate-channel-build-workflow.mjs",
   "scripts/build-standalone-binary.mjs",
   "scripts/create-release-bundle.mjs",
   "scripts/ensure-github-release.mjs",
@@ -58,6 +62,7 @@ const requiredPaths = [
   "tests/buildchain-inventory.json",
   ".buildchain/buildchain.toml",
   ".buildchain/contract-lock.json",
+  ".buildchain/alpha-contract-lock.json",
   ".buildchain/release-impact.json",
   ".github/actionlint.yaml",
   ".github/workflows/self-hosted-runner-smoke.yml",
@@ -79,6 +84,7 @@ const requiredPaths = [
   ".github/workflows/binary-distribution.yml",
   ".github/workflows/verify.yml",
   ".github/workflows/.build.yml",
+  ".github/workflows/build.yml",
   ".github/workflows/build-surface-fixture.yml",
   ".github/workflows/candidate-lab.yml",
   "fixtures/libnode-shaped/buildchain.toml",
@@ -102,14 +108,39 @@ const selfDogfoodWorkflow = fs.readFileSync(
   path.join(root, ".github/workflows/buildchain-alpha-self-dogfood.yml"),
   "utf8",
 );
+const selfDogfoodAlphaLock = JSON.parse(
+  fs.readFileSync(path.join(root, ".buildchain/alpha-contract-lock.json"), "utf8"),
+);
+const currentBuildchainContract = JSON.parse(
+  fs.readFileSync(path.join(root, "dist/site/buildchain-contract.json"), "utf8"),
+);
 const selfDogfoodMajor = String(rootPackage.version || "").match(/^(\d+)\./)?.[1];
 if (!selfDogfoodMajor) {
   throw new Error("root package version must expose a numeric major for self-dogfood");
 }
+if (selfDogfoodAlphaLock.buildchain?.ref !== `v${selfDogfoodMajor}-alpha`) {
+  throw new Error("Buildchain self-dogfood alpha lock must target the current major alpha ref");
+}
+if (!/^[0-9a-f]{40}$/.test(selfDogfoodAlphaLock.buildchain?.resolvedSha || "")) {
+  throw new Error("Buildchain self-dogfood alpha lock must record an exact accepted SHA");
+}
+if (selfDogfoodAlphaLock.buildchain?.compatibilityPolicy !== "major-compatible") {
+  throw new Error("Buildchain self-dogfood alpha lock must enforce major-compatible policy");
+}
+const selfDogfoodAlphaEvaluation = evaluateBuildchainContractLock({
+  lock: selfDogfoodAlphaLock,
+  current: currentBuildchainContract,
+  runtimeRef: `v${selfDogfoodMajor}-alpha`,
+  runtimeSha: "current-development-contract",
+  runtimeClass: "alpha",
+});
+if (!selfDogfoodAlphaEvaluation.compatible) {
+  throw new Error("Buildchain self-dogfood alpha lock requires review after a breaking contract change");
+}
 for (const requiredSnippet of [
-  `/.github/workflows/.build.yml@v${selfDogfoodMajor}-alpha`,
-  `ref: v${selfDogfoodMajor}`,
-  `echo "ref=v${selfDogfoodMajor}"`,
+  `/.github/workflows/build.yml@v${selfDogfoodMajor}-alpha`,
+  "buildchain-channel: auto",
+  "buildchain-channel: stable",
   `const alphaRef = "v${selfDogfoodMajor}-alpha"`,
   `const stableRef = "v${selfDogfoodMajor}"`,
 ]) {
@@ -130,6 +161,23 @@ for (const requiredSnippet of [
     throw new Error(`reusable build workflow missing called-workflow identity: ${requiredSnippet}`);
   }
 }
+const channelBuildWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/build.yml"),
+  "utf8",
+);
+if (channelBuildWorkflow !== generateChannelBuildWorkflow(reusableBuildWorkflow)) {
+  throw new Error("generated channel build workflow is stale");
+}
+for (const requiredSnippet of [
+  "buildchain-channel:",
+  "uses: ./.github/workflows/.build.yml",
+  "needs.resolve-channel.outputs.buildchain-ref",
+  "needs.resolve-channel.outputs.contract-lock-path",
+]) {
+  if (!channelBuildWorkflow.includes(requiredSnippet)) {
+    throw new Error(`channel build workflow missing routing contract: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "group: buildchain-release-promotion-${{ github.repository }}",
   "cancel-in-progress: false",
@@ -143,6 +191,7 @@ const actionlintConfig = fs.readFileSync(
   "utf8",
 );
 for (const requiredSnippet of [
+  ".github/workflows/build.yml:",
   ".github/workflows/.build.yml:",
   'property "workflow_ref" is not defined in object type',
 ]) {

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

@@ -0,0 +1,101 @@
+#!/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/.build.yml");
+const targetPath = path.join(root, ".github/workflows/build.yml");
+
+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 inputNames(inputBlock) {
+  return [...inputBlock.matchAll(/^      ([a-z0-9-]+):$/gm)].map((match) => match[1]);
+}
+
+function routerInputs(inputBlock) {
+  const adjusted = inputBlock.replace(
+    /(      buildchain-contract-lock-path:\n(?:        .*\n)*?        default:) "buildchain\.contract-lock\.json"/,
+    '$1 ""',
+  );
+  return [
+    "      buildchain-channel:",
+    '        description: "Buildchain runtime channel: auto, alpha, or stable"',
+    '        default: "auto"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-alpha-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for the alpha channel"',
+    '        default: ".buildchain/alpha-contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-stable-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for the stable channel"',
+    '        default: ".buildchain/contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    adjusted.trimEnd(),
+  ].join("\n");
+}
+
+function routerOutputs(outputBlock) {
+  const forwarded = outputBlock.replace(/^        value: \$\{\{ jobs\.[^.]+\.outputs\.([^ }]+) \}\}$/gm, "        value: ${{ jobs.build.outputs.$1 }}");
+  return [
+    "      buildchain-channel:",
+    '        description: "Resolved Buildchain channel: alpha, stable, or override"',
+    "        value: ${{ jobs.resolve-channel.outputs.channel }}",
+    "      buildchain-channel-selection-source:",
+    '        description: "Evidence source used to select the Buildchain channel"',
+    "        value: ${{ jobs.resolve-channel.outputs.selection-source }}",
+    "      buildchain-channel-reason:",
+    '        description: "Human-readable Buildchain channel selection reason"',
+    "        value: ${{ jobs.resolve-channel.outputs.reason }}",
+    forwarded.trimEnd(),
+  ].join("\n");
+}
+
+function forwardedInputs(names) {
+  return names
+    .map((name) => {
+      if (name === "buildchain-ref") return `      buildchain-ref: \${{ needs.resolve-channel.outputs.buildchain-ref }}`;
+      if (name === "buildchain-contract-lock-path") {
+        return "      buildchain-contract-lock-path: ${{ needs.resolve-channel.outputs.contract-lock-path }}";
+      }
+      return `      ${name}: \${{ inputs.${name} }}`;
+    })
+    .join("\n");
+}
+
+export function generateChannelBuildWorkflow(source) {
+  const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
+  const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
+  const outputs = blockBetween(source, "    outputs:\n", "\npermissions:\n");
+  const names = inputNames(inputs);
+  if (!names.includes("buildchain-ref") || !names.includes("publish-channel")) {
+    throw new Error("source build workflow is missing channel-router inputs");
+  }
+  return `# Generated by scripts/generate-channel-build-workflow.mjs. Do not edit directly.\nname: Buildchain Channel Build\n\non:\n  workflow_call:\n    inputs:\n${routerInputs(inputs)}\n    secrets:\n${secrets.trimEnd()}\n    outputs:\n${routerOutputs(outputs)}\n\npermissions:\n  contents: read\n  issues: write\n  id-token: write\n\njobs:\n  resolve-channel:\n    name: Resolve Buildchain channel\n    runs-on: ubuntu-24.04\n    outputs:\n      channel: \${{ steps.channel.outputs.channel }}\n      buildchain-ref: \${{ steps.channel.outputs.buildchain-ref }}\n      contract-lock-path: \${{ steps.lock.outputs.path }}\n      selection-source: \${{ steps.channel.outputs.selection-source }}\n      reason: \${{ steps.channel.outputs.reason }}\n    steps:\n      - name: Resolve router source\n        id: router\n        shell: bash\n        env:\n          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}\n        run: |\n          set -euo pipefail\n          workflow_ref=\"\${BUILDCHAIN_ROUTER_WORKFLOW_REF}\"\n          repository=\"\${workflow_ref%%/.github/workflows/*}\"\n          ref=\"\${workflow_ref##*@}\"\n          ref=\"\${ref#refs/heads/}\"\n          ref=\"\${ref#refs/tags/}\"\n          if [[ -z \"\${repository}\" || \"\${repository}\" = \"\${workflow_ref}\" || -z \"\${ref}\" ]]; then\n            echo \"Unable to resolve Buildchain router source from job.workflow_ref=\${workflow_ref}\" >&2\n            exit 1\n          fi\n          {\n            echo \"repository=\${repository}\"\n            echo \"ref=\${ref}\"\n          } >> \"\${GITHUB_OUTPUT}\"\n\n      - name: Checkout Buildchain router\n        uses: actions/checkout@v7.0.0\n        with:\n          repository: \${{ steps.router.outputs.repository }}\n          ref: \${{ steps.router.outputs.ref }}\n          path: .buildchain/router\n          persist-credentials: false\n\n      - name: Resolve channel\n        id: channel\n        shell: bash\n        env:\n          BUILDCHAIN_CHANNEL: \${{ inputs.buildchain-channel }}\n          BUILDCHAIN_REQUESTED_REF: \${{ inputs.buildchain-ref }}\n          BUILDCHAIN_PUBLISH_CHANNEL: \${{ inputs.publish-channel }}\n          BUILDCHAIN_EVENT_NAME: \${{ github.event_name }}\n          BUILDCHAIN_GIT_REF: \${{ github.ref }}\n          BUILDCHAIN_RELEASE_PRERELEASE: \${{ github.event.release.prerelease }}\n          BUILDCHAIN_ROUTER_REF: \${{ steps.router.outputs.ref }}\n        run: |\n          node .buildchain/router/scripts/buildchain-channel-router.mjs \\\n            --cwd .buildchain/router \\\n            --channel \"\${BUILDCHAIN_CHANNEL}\" \\\n            --buildchain-ref \"\${BUILDCHAIN_REQUESTED_REF}\" \\\n            --publish-channel \"\${BUILDCHAIN_PUBLISH_CHANNEL}\" \\\n            --event-name \"\${BUILDCHAIN_EVENT_NAME}\" \\\n            --ref \"\${BUILDCHAIN_GIT_REF}\" \\\n            --release-prerelease \"\${BUILDCHAIN_RELEASE_PRERELEASE}\" \\\n            --router-ref \"\${BUILDCHAIN_ROUTER_REF}\"\n\n      - name: Select consumer contract lock\n        id: lock\n        shell: bash\n        env:\n          EXPLICIT_PATH: \${{ inputs.buildchain-contract-lock-path }}\n          ALPHA_PATH: \${{ inputs.buildchain-alpha-contract-lock-path }}\n          STABLE_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}\n          CHANNEL: \${{ steps.channel.outputs.channel }}\n        run: |\n          set -euo pipefail\n          path=\"\${EXPLICIT_PATH}\"\n          if [[ -z \"\${path}\" ]]; then\n            if [[ \"\${CHANNEL}\" = \"alpha\" ]]; then\n              path=\"\${ALPHA_PATH}\"\n            else\n              path=\"\${STABLE_PATH}\"\n            fi\n          fi\n          echo \"path=\${path}\" >> \"\${GITHUB_OUTPUT}\"\n\n  build:\n    name: Build with resolved channel\n    needs: resolve-channel\n    uses: ./.github/workflows/.build.yml\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n${forwardedInputs(names)}\n    secrets: inherit\n`;
+}
+
+function main() {
+  const source = fs.readFileSync(sourcePath, "utf8");
+  const generated = generateChannelBuildWorkflow(source);
+  if (process.argv.includes("--check")) {
+    const current = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : "";
+    if (current !== generated) {
+      console.error(".github/workflows/build.yml is stale; run node scripts/generate-channel-build-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

@@ -813,7 +813,8 @@ function buildSiteBundle() {
     workflowSource: ".github/workflows reverse input enumeration",
     workflows: enumerateWorkflowInputs({ root }).map((entry) => {
       const surfaceById = new Map([
-        ["build", "reusable-build"],
+        ["build", "channel-build-router"],
+        [".build", "reusable-build"],
         ["web-surface", "site-app-deployment"],
         ["buildchain-ref-promotion", "release-governance"],
         ["release-line-bootstrap", "release-governance"],