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

package/scripts/check-inventory.mjs

@@ -861,7 +861,7 @@ for (const forbiddenSnippet of [
 }
 for (const requiredSnippet of [
   "id-token: write",
-  "actions: read",
+  "actions: write",
   "uses: ./.github/workflows/.release-candidate-promote.yml",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",

package/scripts/ensure-github-release.mjs

@@ -1,13 +1,22 @@
 #!/usr/bin/env node
 import { pathToFileURL } from "node:url";
 
-export function classifyReleaseTag(tag) {
+function classifyPublicationChannel(channel = "") {
+  const normalized = String(channel || "").trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (normalized === "alpha") return true;
+  if (["release", "stable", "major"].includes(normalized)) return false;
+  throw new Error(`Unsupported GitHub Release publication channel: ${channel}`);
+}
+
+export function classifyReleaseTag(tag, { channel = "" } = {}) {
   const normalized = String(tag || "").trim();
   const match = normalized.match(/^v\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?$/);
   if (!match) {
     throw new Error(`Unsupported semver release tag: ${tag}`);
   }
-  const prerelease = normalized.includes("-");
+  const channelPrerelease = classifyPublicationChannel(channel);
+  const prerelease = channelPrerelease ?? normalized.includes("-");
   return {
     tag: normalized,
     prerelease,
@@ -23,6 +32,7 @@ function parseArgs(argv) {
     title: "",
     notes: "",
     target: "",
+    channel: "",
   };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -38,6 +48,7 @@ function parseArgs(argv) {
     else if (arg === "--title") args.title = readValue();
     else if (arg === "--notes") args.notes = readValue();
     else if (arg === "--target") args.target = readValue();
+    else if (arg === "--channel") args.channel = readValue();
     else if (arg === "--api-url") args.apiUrl = readValue();
     else if (arg === "--help" || arg === "-h") {
       args.help = true;
@@ -50,11 +61,12 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    "usage: node scripts/ensure-github-release.mjs --repository <owner/repo> --tag <tag>",
+    "usage: node scripts/ensure-github-release.mjs --repository <owner/repo> --tag <tag> [--channel alpha|release]",
     "",
     "Ensures Buildchain GitHub Release metadata is deterministic:",
-    "- vX.Y.Z-alpha.N => prerelease=true, make_latest=false",
-    "- vX.Y.Z => prerelease=false, make_latest=true",
+    "- explicit alpha => prerelease=true, make_latest=false",
+    "- explicit release/stable/major => prerelease=false, make_latest=true",
+    "- without --channel, semver prerelease syntax remains the fallback",
   ].join("\n");
 }
 
@@ -106,9 +118,10 @@ export async function ensureGitHubRelease({
   title = "",
   notes = "",
   target = "",
+  channel = "",
 } = {}) {
   const { owner, repo } = splitRepository(repository);
-  const metadata = classifyReleaseTag(tag);
+  const metadata = classifyReleaseTag(tag, { channel });
   const encodedTag = encodeURIComponent(metadata.tag);
   const releasePath = `/repos/${owner}/${repo}/releases/tags/${encodedTag}`;
   const refPath = `/repos/${owner}/${repo}/git/ref/tags/${encodedTag}`;
@@ -163,6 +176,7 @@ async function main() {
     title: args.title,
     notes: args.notes,
     target: args.target,
+    channel: args.channel,
   });
   console.log(`github-release-${result.action}=${result.metadata.tag}`);
   console.log(`github-release-prerelease=${result.metadata.prerelease}`);

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

@@ -204,7 +204,7 @@ ${secrets.trimEnd()}
 ${publicOutputs(outputs)}
 
 permissions:
-  actions: read
+  actions: write
   checks: write
   contents: write
   id-token: write
@@ -404,7 +404,7 @@ jobs:
     if: \${{ needs.resolve-promotion.outputs.channel == 'alpha' }}
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
     permissions:
-      actions: read
+      actions: write
       checks: write
       contents: write
       id-token: write
@@ -419,7 +419,7 @@ ${alphaForwarded}
     if: \${{ needs.resolve-promotion.outputs.channel == 'stable' }}
     uses: kungfu-systems/buildchain/${stableRoute.workflowPath}@${stableRoute.callRef}
     permissions:
-      actions: read
+      actions: write
       checks: write
       contents: write
       id-token: write

package/scripts/generate-site-bundle.mjs

@@ -28,6 +28,7 @@ import {
   enumerateWorkflowInputs,
 } from "../packages/core/public-surface-audit.js";
 import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
+import { projectHomepageIntro } from "./site-bundle-homepage.mjs";
 
 const SITE_BUNDLE_CONTRACT = "kungfu-buildchain-site-bundle";
 const PUBLICATION_RELEASE_REGISTRY_CONTRACT = "kungfu-buildchain-publication-release-registry";
@@ -702,6 +703,7 @@ function buildSiteBundle() {
   const packageJson = readJson("package.json");
   const inventory = readJson("tests/buildchain-inventory.json");
   const readme = parseReadme(readText(README_PATH));
+  const homepageIntro = projectHomepageIntro(readme.intro);
   const docs = BUILDCHAIN_AGENT_MANUALS.map((manual) => docEntry(manual.id, manual.title, manual.path, manual.plane));
   const pages = buildSitePages();
   const preservedTimestampPolicy = readExistingSiteTimestampPolicy(packageJson.version);
@@ -945,8 +947,10 @@ function buildSiteBundle() {
     },
     githubRelease: {
       exactTagRelease: true,
-      prereleaseTags: "semver prerelease tags set prerelease=true and make_latest=false",
-      stableTags: "stable semver tags set make_latest=true",
+      authoritativeIntent: "Buildchain publication channel controls prerelease/latest metadata when available",
+      alphaChannel: "alpha publication sets prerelease=true and make_latest=false",
+      stableChannels: "release, stable, and major publication set prerelease=false and make_latest=true",
+      tagFallback: "ordinary callers without publication intent use semver prerelease syntax",
       evidenceAssets: [
         "publish evidence JSON",
         "buildchain.release.json",
@@ -1218,8 +1222,8 @@ function buildSiteBundle() {
     },
     homepage: {
       title: readme.title,
-      lead: paragraphBlocks(readme.intro)[0] || "",
-      mechanismSummary: paragraphBlocks(readme.intro).slice(1),
+      lead: homepageIntro.lead,
+      mechanismSummary: homepageIntro.mechanismSummary,
       sections: homepageSections,
       displayPlan: {
         firstScreen: {

package/scripts/runtime-ref-core.mjs

@@ -111,6 +111,8 @@ export function validateRuntimeOverrideTrust({
   requestedRef = "",
   eventName = "",
   actorPermission = "",
+  sameRepositoryPullRequest = false,
+  pullRequestHeadSha = "",
 } = {}) {
   if (!String(requestedRef || "").trim()) {
     return { ok: true, decision: "stable-default" };
@@ -118,6 +120,16 @@ export function validateRuntimeOverrideTrust({
   if (isOfficialBuildchainChannelRef(requestedRef)) {
     return { ok: true, decision: "official-channel" };
   }
+  const normalizedRequested = String(requestedRef || "").trim().toLowerCase();
+  const normalizedHeadSha = String(pullRequestHeadSha || "").trim().toLowerCase();
+  if (
+    eventName === "pull_request" &&
+    sameRepositoryPullRequest === true &&
+    EXACT_SHA_RE.test(normalizedRequested) &&
+    normalizedRequested === normalizedHeadSha
+  ) {
+    return { ok: true, decision: "same-repository-pr-head" };
+  }
   if (eventName !== "workflow_dispatch") {
     return {
       ok: false,

package/scripts/site-bundle-homepage.mjs

@@ -0,0 +1,39 @@
+const BADGE_BLOCK_START = "<!-- buildchain:badges:start -->";
+const BADGE_BLOCK_END = "<!-- buildchain:badges:end -->";
+
+function normalizeMarkdown(value) {
+  return String(value || "").replace(/\r\n/g, "\n").trim();
+}
+
+function paragraphBlocks(markdown) {
+  return normalizeMarkdown(markdown)
+    .split(/\n{2,}/)
+    .map((block) => block.replace(/\n/g, " ").trim())
+    .filter(Boolean);
+}
+
+export function projectHomepageIntro(markdown) {
+  const intro = normalizeMarkdown(markdown);
+  const start = intro.indexOf(BADGE_BLOCK_START);
+  const end = intro.indexOf(BADGE_BLOCK_END);
+  if ((start >= 0) !== (end >= 0) || (start >= 0 && end < start)) {
+    throw new Error("README.md managed badge block is incomplete");
+  }
+  if (start >= 0) {
+    const endOffset = end + BADGE_BLOCK_END.length;
+    const lead = intro.slice(start, endOffset).trim();
+    const remaining = [intro.slice(0, start), intro.slice(endOffset)]
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .join("\n\n");
+    return {
+      lead,
+      mechanismSummary: paragraphBlocks(remaining),
+    };
+  }
+  const blocks = paragraphBlocks(intro);
+  return {
+    lead: blocks[0] || "",
+    mechanismSummary: blocks.slice(1),
+  };
+}

package/scripts/web-surface-cloudfront-rewrite.mjs

@@ -15,6 +15,9 @@ const FUNCTION_CODE = `function handler(event) {
 }
 `;
 
+const DISTRIBUTION_UPDATE_MAX_ATTEMPTS = 3;
+const DISTRIBUTION_UPDATE_RETRY_DELAY_MS = 250;
+
 function readArg(name, fallback = "") {
   const flag = `--${name}`;
   const index = process.argv.indexOf(flag);
@@ -31,7 +34,7 @@ function runAws(args, { allowFailure = false } = {}) {
   });
   if (result.error) {
     if (allowFailure) {
-      return { ok: false, stdout: "", stderr: String(result.error.message || result.error) };
+      return { ok: false, status: null, stdout: "", stderr: String(result.error.message || result.error) };
     }
     throw result.error;
   }
@@ -39,11 +42,11 @@ function runAws(args, { allowFailure = false } = {}) {
   const stderr = String(result.stderr || "");
   if (result.status !== 0) {
     if (allowFailure) {
-      return { ok: false, stdout, stderr };
+      return { ok: false, status: result.status, stdout, stderr };
     }
     throw new Error(`aws ${args.join(" ")} failed with exit code ${result.status}${stderr.trim() ? `: ${stderr.trim()}` : ""}`);
   }
-  return { ok: true, stdout, stderr };
+  return { ok: true, status: result.status, stdout, stderr };
 }
 
 function runAwsJson(args, options = {}) {
@@ -58,6 +61,22 @@ function functionConfig(comment) {
   return `Comment=${comment.replace(/,/g, " ")},Runtime=cloudfront-js-2.0`;
 }
 
+function awsFailureMessage(args, result) {
+  const status = result.status === null || result.status === undefined
+    ? ""
+    : ` with exit code ${result.status}`;
+  const stderr = String(result.stderr || "").trim();
+  return `aws ${args.join(" ")} failed${status}${stderr ? `: ${stderr}` : ""}`;
+}
+
+function isStaleDistributionEtag(result) {
+  return result.ok === false && /\bPreconditionFailed\b/.test(String(result.stderr || ""));
+}
+
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
 function writeFunctionCode(tmpDir) {
   const file = path.join(tmpDir, "directory-index-rewrite.js");
   fs.writeFileSync(file, FUNCTION_CODE);
@@ -130,57 +149,85 @@ function publishFunction({ name, etag }) {
 }
 
 function attachFunction({ distributionId, functionArn }) {
-  const current = runAwsJson(["cloudfront", "get-distribution-config", "--id", distributionId]);
-  const etag = current.data?.ETag || "";
-  const config = current.data?.DistributionConfig;
-  if (!etag || !config) {
-    throw new Error(`cloudfront get-distribution-config did not return ETag and DistributionConfig for ${distributionId}`);
-  }
-  const defaultBehavior = config.DefaultCacheBehavior || {};
-  const existing = defaultBehavior.FunctionAssociations || { Quantity: 0, Items: [] };
-  const items = Array.isArray(existing.Items) ? [...existing.Items] : [];
-  const currentViewer = items.find((item) => item.EventType === "viewer-request");
-  if (currentViewer && currentViewer.FunctionARN && currentViewer.FunctionARN !== functionArn) {
-    throw new Error(
-      `CloudFront distribution ${distributionId} already has a different viewer-request function ${currentViewer.FunctionARN}; ` +
-      "remove or migrate it before Buildchain can manage directory-index rewrites",
-    );
-  }
-  const nextItems = [
-    ...items.filter((item) => item.EventType !== "viewer-request"),
-    {
-      EventType: "viewer-request",
-      FunctionARN: functionArn,
-    },
-  ];
-  config.DefaultCacheBehavior = {
-    ...defaultBehavior,
-    FunctionAssociations: {
-      Quantity: nextItems.length,
-      Items: nextItems,
-    },
-  };
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-cloudfront-distribution-"));
-  try {
-    const configFile = path.join(tmpDir, "distribution-config.json");
-    fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
-    runAws([
-      "cloudfront",
-      "update-distribution",
-      "--id",
-      distributionId,
-      "--if-match",
-      etag,
-      "--distribution-config",
-      `file://${configFile}`,
-    ]);
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+  let previousViewerRequestFunction;
+  for (let attempt = 1; attempt <= DISTRIBUTION_UPDATE_MAX_ATTEMPTS; attempt += 1) {
+    const current = runAwsJson(["cloudfront", "get-distribution-config", "--id", distributionId]);
+    const etag = current.data?.ETag || "";
+    const config = current.data?.DistributionConfig;
+    if (!etag || !config) {
+      throw new Error(`cloudfront get-distribution-config did not return ETag and DistributionConfig for ${distributionId}`);
+    }
+    const defaultBehavior = config.DefaultCacheBehavior || {};
+    const existing = defaultBehavior.FunctionAssociations || { Quantity: 0, Items: [] };
+    const items = Array.isArray(existing.Items) ? [...existing.Items] : [];
+    const currentViewer = items.find((item) => item.EventType === "viewer-request");
+    if (previousViewerRequestFunction === undefined) {
+      previousViewerRequestFunction = currentViewer?.FunctionARN || "";
+    }
+    if (currentViewer && currentViewer.FunctionARN && currentViewer.FunctionARN !== functionArn) {
+      throw new Error(
+        `CloudFront distribution ${distributionId} already has a different viewer-request function ${currentViewer.FunctionARN}; ` +
+        "remove or migrate it before Buildchain can manage directory-index rewrites",
+      );
+    }
+    if (currentViewer?.FunctionARN === functionArn) {
+      return {
+        previousViewerRequestFunction,
+        nextViewerRequestFunction: functionArn,
+      };
+    }
+
+    const nextItems = [
+      ...items.filter((item) => item.EventType !== "viewer-request"),
+      {
+        EventType: "viewer-request",
+        FunctionARN: functionArn,
+      },
+    ];
+    config.DefaultCacheBehavior = {
+      ...defaultBehavior,
+      FunctionAssociations: {
+        Quantity: nextItems.length,
+        Items: nextItems,
+      },
+    };
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-cloudfront-distribution-"));
+    let args;
+    let updated;
+    try {
+      const configFile = path.join(tmpDir, "distribution-config.json");
+      fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+      args = [
+        "cloudfront",
+        "update-distribution",
+        "--id",
+        distributionId,
+        "--if-match",
+        etag,
+        "--distribution-config",
+        `file://${configFile}`,
+      ];
+      updated = runAws(args, { allowFailure: true });
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    if (updated.ok) {
+      return {
+        previousViewerRequestFunction,
+        nextViewerRequestFunction: functionArn,
+      };
+    }
+    if (!isStaleDistributionEtag(updated)) {
+      throw new Error(awsFailureMessage(args, updated));
+    }
+    if (attempt === DISTRIBUTION_UPDATE_MAX_ATTEMPTS) {
+      throw new Error(
+        `CloudFront update-distribution still failed after ${attempt} attempts: ${awsFailureMessage(args, updated)}`,
+      );
+    }
+    sleepSync(DISTRIBUTION_UPDATE_RETRY_DELAY_MS * attempt);
   }
-  return {
-    previousViewerRequestFunction: currentViewer?.FunctionARN || "",
-    nextViewerRequestFunction: functionArn,
-  };
+  throw new Error(`CloudFront update-distribution retry loop ended unexpectedly for ${distributionId}`);
 }
 
 export function ensureCloudFrontDirectoryIndexRewrite({