@kungfu-tech/buildchain 2.8.15 → 2.8.16-alpha.2

package/packages/core/readme-badges.js

@@ -0,0 +1,450 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import { loadBuildchainConfig } from "./buildchain-config.js";
+import {
+  readJsonFromLocation,
+  verifyReleasePassport,
+} from "./release-passport.js";
+
+export const README_BADGE_FACTS_CONTRACT = "kungfu-buildchain-readme-badge-facts";
+export const README_BADGE_BLOCK_START = "<!-- buildchain:badges:start -->";
+export const README_BADGE_BLOCK_END = "<!-- buildchain:badges:end -->";
+
+const KFD_KEYS = [
+  { key: "kfd-1", id: "kfd1", label: "KFD-1", text: "contract world" },
+  { key: "kfd-2", id: "kfd2", label: "KFD-2", text: "trust passport" },
+  { key: "kfd-3", id: "kfd3", label: "KFD-3", text: "collaboration interface" },
+];
+
+const STATE_COLORS = {
+  passed: "2ea44f",
+  aligned: "0969da",
+  declared: "6e7781",
+  planned: "bf8700",
+  draft: "8250df",
+  downgraded: "bf8700",
+  failed: "cf222e",
+  missing: "6e7781",
+  unknown: "6e7781",
+};
+
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function readTextIfExists(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+}
+
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function posixPath(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function encodeBadge(value) {
+  return encodeURIComponent(String(value || ""))
+    .replace(/-/g, "--")
+    .replace(/_/g, "__");
+}
+
+function badgeUrl({ label, message, color }) {
+  return `https://img.shields.io/badge/${encodeBadge(label)}-${encodeBadge(message)}-${color || "6e7781"}.svg`;
+}
+
+function normalizeState(value, fallback = "planned") {
+  const normalized = String(value || fallback).trim().toLowerCase();
+  if (["passed", "aligned", "declared", "planned", "draft", "downgraded", "failed", "missing"].includes(normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+function normalizeDeclarationState(value, fallback = "planned") {
+  const normalized = normalizeState(value, fallback);
+  return normalized === "passed" ? "declared" : normalized;
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => String(entry || "").trim())
+    .filter(Boolean);
+}
+
+function readRepositoryFromGit(cwd) {
+  const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], {
+    cwd,
+    encoding: "utf8",
+  });
+  const value = remote.status === 0 ? remote.stdout.trim() : "";
+  const match = value.match(/github\.com[:/]([^/\s]+)\/([^/\s.]+)(?:\.git)?$/);
+  if (!match) {
+    return { fullName: "", owner: "", name: "", url: "" };
+  }
+  const fullName = `${match[1]}/${match[2]}`;
+  return {
+    fullName,
+    owner: match[1],
+    name: match[2],
+    url: `https://github.com/${fullName}`,
+  };
+}
+
+function normalizePackageRepository(repository) {
+  const value = typeof repository === "string" ? repository : repository?.url || "";
+  const match = String(value).match(/github\.com[:/]([^/\s]+)\/([^/\s.]+)(?:\.git)?/);
+  if (!match) {
+    return undefined;
+  }
+  const fullName = `${match[1]}/${match[2]}`;
+  return {
+    fullName,
+    owner: match[1],
+    name: match[2],
+    url: `https://github.com/${fullName}`,
+  };
+}
+
+function discoverWorkflowFacts({ cwd, repository, badgeConfig = {} }) {
+  const workflowDir = path.join(cwd, ".github", "workflows");
+  const configured = normalizeStringArray(badgeConfig.workflows);
+  const defaults = ["verify.yml", "build.yml", "buildchain-ref-promotion.yml"];
+  const names = configured.length > 0 ? configured : defaults;
+  if (!fs.existsSync(workflowDir)) {
+    return [];
+  }
+  return names
+    .map((file) => {
+      const workflowPath = path.join(workflowDir, file);
+      if (!fs.existsSync(workflowPath)) {
+        return undefined;
+      }
+      const source = fs.readFileSync(workflowPath, "utf8");
+      const nameMatch = source.match(/^name:\s*["']?(.+?)["']?\s*$/m);
+      const name = String(nameMatch?.[1] || path.basename(file, path.extname(file))).trim();
+      return {
+        file,
+        name,
+        badgeUrl: repository.fullName
+          ? `https://github.com/${repository.fullName}/actions/workflows/${file}/badge.svg`
+          : "",
+        url: repository.fullName
+          ? `https://github.com/${repository.fullName}/actions/workflows/${file}`
+          : "",
+      };
+    })
+    .filter(Boolean);
+}
+
+function defaultReleasePassportLocation({ cwd, repository, badgeConfig = {} }) {
+  const configured = badgeConfig.release_passport_url || badgeConfig.releasePassportUrl || badgeConfig.release_passport || "";
+  if (configured) {
+    return String(configured);
+  }
+  const localCandidates = [
+    "buildchain.release.json",
+    ".buildchain/release-passport/buildchain.release.json",
+  ];
+  for (const candidate of localCandidates) {
+    const filePath = path.join(cwd, candidate);
+    if (fs.existsSync(filePath)) {
+      return candidate;
+    }
+  }
+  return repository.fullName
+    ? `https://github.com/${repository.fullName}/releases/latest/download/buildchain.release.json`
+    : "";
+}
+
+function siblingUrl(location, filename) {
+  if (!/^https?:\/\//.test(location)) {
+    return "";
+  }
+  return `${location.replace(/\/[^/]*$/, "")}/${filename}`;
+}
+
+async function readPassportAndReport({ cwd, location }) {
+  if (!location) {
+    return { passport: undefined, report: undefined, error: "" };
+  }
+  const resolvedLocation = /^https?:\/\//.test(location) ? location : path.resolve(cwd, location);
+  try {
+    const passport = await readJsonFromLocation(resolvedLocation);
+    const report = await verifyReleasePassport({
+      passportLocation: resolvedLocation,
+      artifactEvidenceLocation: siblingUrl(resolvedLocation, "artifact-evidence.json"),
+      impactLocation: siblingUrl(resolvedLocation, "impact.json"),
+      agentIndexLocation: siblingUrl(resolvedLocation, "agent-index.json"),
+      productMechanismLocation: siblingUrl(resolvedLocation, "product-mechanism.json"),
+    });
+    return { passport, report, error: "" };
+  } catch (error) {
+    return { passport: undefined, report: undefined, error: error.message };
+  }
+}
+
+function kfdSectionPassed({ passport, report, key }) {
+  if (!passport || !report?.ok) {
+    return false;
+  }
+  const section = passport[key] || (key === "kfd-1" ? passport.kfd1 : undefined) || (key === "kfd-3" ? passport.kfd3 : undefined);
+  return section?.status === "passed";
+}
+
+function declaredKfdState({ badgeConfig = {}, key, id }) {
+  const kfdConfig = badgeConfig.kfd && typeof badgeConfig.kfd === "object" ? badgeConfig.kfd : {};
+  return normalizeDeclarationState(
+    badgeConfig[key] ||
+      badgeConfig[id] ||
+      badgeConfig[key.replace("-", "_")] ||
+      kfdConfig[key] ||
+      kfdConfig[id] ||
+      kfdConfig[key.replace("kfd-", "")],
+    "planned",
+  );
+}
+
+function releasePassportState({ report, error, badgeConfig = {} }) {
+  if (report?.ok) {
+    return "passed";
+  }
+  if (error) {
+    return normalizeDeclarationState(badgeConfig.release_passport_state || badgeConfig.releasePassportState, "declared");
+  }
+  return normalizeDeclarationState(badgeConfig.release_passport_state || badgeConfig.releasePassportState, "planned");
+}
+
+function licenseFromFiles(cwd, packageJson) {
+  if (packageJson.license) {
+    return String(packageJson.license);
+  }
+  const licenseFile = fs.readdirSync(cwd).find((entry) => /^licen[sc]e($|\.)/i.test(entry));
+  return licenseFile ? licenseFile.replace(/^LICENSE[.-]?/i, "") || "present" : "";
+}
+
+function collectPlatformFacts({ badgeConfig = {}, passport = undefined }) {
+  const configured = normalizeStringArray(badgeConfig.platforms);
+  if (configured.length > 0) {
+    return configured;
+  }
+  const assets = Array.isArray(passport?.artifacts) ? passport.artifacts : [];
+  const platforms = new Set();
+  for (const asset of assets) {
+    const platform = String(asset.platform || "").trim();
+    if (platform) {
+      platforms.add(platform);
+    }
+  }
+  return [...platforms].sort();
+}
+
+function localFactFileSummary(cwd, candidates = []) {
+  for (const relPath of candidates) {
+    const filePath = path.join(cwd, relPath);
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      continue;
+    }
+    try {
+      const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      return {
+        location: relPath,
+        sha256: sha256File(filePath),
+        contract: value.contract || "",
+        claimCount: Array.isArray(value.publicClaims) ? value.publicClaims.length : undefined,
+        category: value.category || "",
+      };
+    } catch (error) {
+      return {
+        location: relPath,
+        error: error.message,
+      };
+    }
+  }
+  return undefined;
+}
+
+function buildBadgeEntries(facts) {
+  const entries = [];
+  for (const kfd of facts.kfd) {
+    entries.push({
+      id: kfd.key,
+      alt: `${kfd.label}: ${kfd.state}`,
+      image: badgeUrl({
+        label: kfd.label,
+        message: `${kfd.text} ${kfd.state}`,
+        color: STATE_COLORS[kfd.state] || STATE_COLORS.unknown,
+      }),
+      link: kfd.url,
+    });
+  }
+  entries.push({
+    id: "release-passport",
+    alt: `Release Passport: ${facts.releasePassport.state}`,
+    image: badgeUrl({
+      label: "release passport",
+      message: facts.releasePassport.state,
+      color: STATE_COLORS[facts.releasePassport.state] || STATE_COLORS.unknown,
+    }),
+    link: facts.releasePassport.url,
+  });
+  if (facts.package.license) {
+    entries.push({
+      id: "license",
+      alt: `License: ${facts.package.license}`,
+      image: badgeUrl({ label: "license", message: facts.package.license, color: "0969da" }),
+      link: facts.repository.url ? `${facts.repository.url}/blob/HEAD/LICENSE` : "",
+    });
+  }
+  if (facts.platforms.length > 0) {
+    entries.push({
+      id: "platform",
+      alt: `Platform: ${facts.platforms.join(" | ")}`,
+      image: badgeUrl({ label: "platform", message: facts.platforms.join(" | "), color: "6e7781" }),
+      link: facts.releasePassport.url,
+    });
+  }
+  for (const workflow of facts.workflows) {
+    entries.push({
+      id: `workflow:${workflow.file}`,
+      alt: workflow.name,
+      image: workflow.badgeUrl,
+      link: workflow.url,
+    });
+  }
+  return entries;
+}
+
+export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const loadedConfig = loadBuildchainConfig(resolvedCwd);
+  const badgeConfig = loadedConfig?.config?.badges && typeof loadedConfig.config.badges === "object"
+    ? loadedConfig.config.badges
+    : {};
+  const packageJson = readJsonIfExists(path.join(resolvedCwd, "package.json")) || {};
+  const packageRepository = normalizePackageRepository(packageJson.repository);
+  const repository = packageRepository || readRepositoryFromGit(resolvedCwd);
+  const releasePassportLocation = defaultReleasePassportLocation({ cwd: resolvedCwd, repository, badgeConfig });
+  const { passport, report, error } = await readPassportAndReport({
+    cwd: resolvedCwd,
+    location: releasePassportLocation,
+  });
+  const releasePassportUrl = /^https?:\/\//.test(releasePassportLocation)
+    ? releasePassportLocation
+    : repository.fullName && releasePassportLocation
+      ? `${repository.url}/blob/HEAD/${posixPath(releasePassportLocation)}`
+      : releasePassportLocation;
+  const releaseState = releasePassportState({ report, error, badgeConfig });
+  const kfd = KFD_KEYS.map((entry) => {
+    const passed = kfdSectionPassed({ passport, report, key: entry.key });
+    const state = passed ? "passed" : declaredKfdState({ badgeConfig, key: entry.key, id: entry.id });
+    return {
+      key: entry.key,
+      label: entry.label,
+      text: entry.text,
+      state,
+      source: passed ? "release-passport" : "declaration",
+      url: releasePassportUrl,
+    };
+  });
+  const facts = {
+    schemaVersion: 1,
+    contract: README_BADGE_FACTS_CONTRACT,
+    cwd: resolvedCwd,
+    repository,
+    package: {
+      name: packageJson.name || "",
+      version: packageJson.version || "",
+      license: licenseFromFiles(resolvedCwd, packageJson),
+    },
+    releasePassport: {
+      location: releasePassportLocation,
+      url: releasePassportUrl,
+      state: releaseState,
+      verified: Boolean(report?.ok),
+      error,
+      reportSummary: report ? {
+        ok: report.ok,
+        trust: report.trust,
+        issueCount: Array.isArray(report.issues) ? report.issues.length : 0,
+      } : undefined,
+    },
+    kfdClaimRegistry: localFactFileSummary(resolvedCwd, [
+      "dist/site/kfd-claims.json",
+      ".buildchain/kfd-claims.json",
+    ]),
+    productMechanism: localFactFileSummary(resolvedCwd, [
+      "dist/site/product-mechanism.json",
+      "product-mechanism.json",
+      ".buildchain/product-mechanism.json",
+    ]),
+    kfd,
+    platforms: collectPlatformFacts({ badgeConfig, passport }),
+    workflows: discoverWorkflowFacts({ cwd: resolvedCwd, repository, badgeConfig }),
+    badges: [],
+  };
+  facts.badges = buildBadgeEntries(facts);
+  return facts;
+}
+
+export function renderReadmeBadgeBlock(facts) {
+  const lines = [
+    README_BADGE_BLOCK_START,
+    ...facts.badges.map((badge) => (
+      badge.link
+        ? `[![${badge.alt}](${badge.image})](${badge.link})`
+        : `![${badge.alt}](${badge.image})`
+    )),
+    README_BADGE_BLOCK_END,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+function badgeBlockRegex() {
+  return new RegExp(`${README_BADGE_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${README_BADGE_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`);
+}
+
+export function checkReadmeBadgeBlock({ readmeText, facts } = {}) {
+  const expected = renderReadmeBadgeBlock(facts);
+  const match = String(readmeText || "").match(badgeBlockRegex());
+  const actual = match ? match[0] : "";
+  const normalizedActual = actual.endsWith("\n") ? actual : `${actual}\n`;
+  const ok = normalizedActual === expected;
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-readme-badge-check",
+    ok,
+    missing: !match,
+    stale: Boolean(match) && !ok,
+    expected,
+    actual,
+    facts,
+    message: ok ? "README badge block is current" : (match ? "README badge block is stale" : "README badge block is missing"),
+  };
+}
+
+export function updateReadmeBadgeBlock({ readmeText, facts } = {}) {
+  const source = String(readmeText || "");
+  const block = renderReadmeBadgeBlock(facts);
+  if (badgeBlockRegex().test(source)) {
+    return source.replace(badgeBlockRegex(), block);
+  }
+  const h1 = source.match(/^# .+\n+/);
+  if (h1) {
+    return `${h1[0]}${block}\n${source.slice(h1[0].length)}`;
+  }
+  return `${block}\n${source}`;
+}
+
+export function readReadme({ cwd = process.cwd(), readmePath = "README.md" } = {}) {
+  return readTextIfExists(path.resolve(cwd, readmePath));
+}

package/packages/core/release-passport.js

@@ -1465,10 +1465,16 @@ function validateKfd2ReleaseTrustPassportAudit(section, issues) {
   }
 }
 
-function resolveSiblingJson(basePath, relativePath) {
-  if (!basePath || !relativePath || /^https?:\/\//.test(relativePath)) {
+async function resolveSiblingJson(basePath, relativePath) {
+  if (!basePath || !relativePath) {
     return undefined;
   }
+  if (/^https?:\/\//.test(relativePath)) {
+    return readJsonFromLocation(relativePath);
+  }
+  if (/^https?:\/\//.test(basePath)) {
+    return readJsonFromLocation(new URL(relativePath, basePath).toString());
+  }
   const candidate = path.resolve(path.dirname(basePath), relativePath);
   if (!fs.existsSync(candidate)) {
     return undefined;
@@ -1789,13 +1795,22 @@ export function createReleaseCheckReport({
   };
 }
 
-export async function readJsonFromLocation(location) {
+export async function readJsonFromLocation(location, redirectCount = 0) {
   const input = nonEmptyString(location, "location");
+  if (redirectCount > 5) {
+    throw new Error(`too many redirects while reading ${input}`);
+  }
   if (/^https?:\/\//.test(input)) {
     const client = input.startsWith("https:") ? https : http;
     return new Promise((resolve, reject) => {
       client
         .get(input, (response) => {
+          if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+            const nextLocation = new URL(response.headers.location, input).toString();
+            response.resume();
+            readJsonFromLocation(nextLocation, redirectCount + 1).then(resolve, reject);
+            return;
+          }
           if (response.statusCode < 200 || response.statusCode >= 300) {
             reject(new Error(`HTTP ${response.statusCode} while reading ${input}`));
             response.resume();
@@ -1829,27 +1844,27 @@ export async function verifyReleasePassport({
   productMechanismLocation = "",
 } = {}) {
   const passport = await readJsonFromLocation(passportLocation);
-  const basePath = /^https?:\/\//.test(passportLocation) ? "" : path.resolve(passportLocation);
+  const basePath = /^https?:\/\//.test(passportLocation) ? passportLocation : path.resolve(passportLocation);
   const artifactEvidence =
     artifactEvidenceLocation
       ? await readJsonFromLocation(artifactEvidenceLocation)
-      : resolveSiblingJson(basePath, passport.evidence?.artifactEvidence) || {};
+      : await resolveSiblingJson(basePath, passport.evidence?.artifactEvidence) || {};
   const publishEvidence =
     publishEvidenceLocation
       ? await readJsonFromLocation(publishEvidenceLocation)
-      : resolveSiblingJson(basePath, passport.evidence?.publishEvidence) || {};
+      : await resolveSiblingJson(basePath, passport.evidence?.publishEvidence) || {};
   const impact =
     impactLocation
       ? await readJsonFromLocation(impactLocation)
-      : resolveSiblingJson(basePath, passport.evidence?.impact) || {};
+      : await resolveSiblingJson(basePath, passport.evidence?.impact) || {};
   const agentIndex =
     agentIndexLocation
       ? await readJsonFromLocation(agentIndexLocation)
-      : resolveSiblingJson(basePath, passport.evidence?.agentIndex) || {};
+      : await resolveSiblingJson(basePath, passport.evidence?.agentIndex) || {};
   const productMechanism =
     productMechanismLocation
       ? await readJsonFromLocation(productMechanismLocation)
-      : resolveSiblingJson(basePath, passport.product?.mechanism) || {};
+      : await resolveSiblingJson(basePath, passport.product?.mechanism) || {};
   return createReleaseCheckReport({
     passport,
     artifactEvidence,

package/scripts/check-inventory.mjs

@@ -14,12 +14,15 @@ const requiredPaths = [
   ".github/ISSUE_TEMPLATE/config.yml",
   ".github/pull_request_template.md",
   "bin/buildchain.mjs",
+  "packages/core/homebrew.js",
   "docs/MAP.md",
   "docs/binary-distribution.md",
   "docs/cli.md",
   "docs/consumer-issue-reporting.md",
+  "docs/homebrew.md",
   "docs/install.md",
   "docs/product-mechanism.md",
+  "docs/readme-badges.md",
   "docs/release-passport.md",
   "docs/release-propagation.md",
   "docs/site-bundle-contract.md",
@@ -105,12 +108,18 @@ if (rootPackage.exports?.["."] !== "./packages/core/index.js") {
 if (rootPackage.exports?.["./diagnostics"] !== "./packages/core/diagnostics.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/diagnostics");
 }
+if (rootPackage.exports?.["./homebrew"] !== "./packages/core/homebrew.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/homebrew");
+}
 if (rootPackage.exports?.["./buildchain-contract"] !== "./packages/core/buildchain-contract.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/buildchain-contract");
 }
 if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
 }
+if (rootPackage.exports?.["./readme-badges"] !== "./packages/core/readme-badges.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/readme-badges");
+}
 if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/logging");
 }
@@ -199,6 +208,26 @@ if (!coreIndexSource.includes("KFD2_TRUST_PROOF_CONTRACT")) {
 if (!coreIndexSource.includes("createSurfaceTimestampPolicy")) {
   throw new Error("packages/core/index.js must export surface manifest timestamp policy APIs");
 }
+for (const requiredSnippet of [
+  "collectReadmeBadgeFacts",
+  "renderReadmeBadgeBlock",
+  "checkReadmeBadgeBlock",
+  "updateReadmeBadgeBlock",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export README badge API: ${requiredSnippet}`);
+  }
+}
+for (const requiredSnippet of [
+  "collectHomebrewTapFacts",
+  "renderHomebrewFormula",
+  "checkHomebrewTap",
+  "updateHomebrewTap",
+]) {
+  if (!coreIndexSource.includes(requiredSnippet)) {
+    throw new Error(`packages/core/index.js must export Homebrew API: ${requiredSnippet}`);
+  }
+}
 if (siteBundle.contract !== "kungfu-buildchain-site-bundle") {
   throw new Error("buildchain-site.json must expose the Buildchain site bundle contract");
 }
@@ -374,13 +403,41 @@ for (const requiredSnippet of [
   "npm publish transactions",
   "GitHub Release",
   "release propagation",
+  "Homebrew tap distribution indexes",
   "manual-registry.json",
   "node-api-registry.json",
+  "README badge",
 ]) {
   if (!docsMap.includes(requiredSnippet)) {
     throw new Error(`documentation map missing capability coverage snippet: ${requiredSnippet}`);
   }
 }
+const readmeBadgesDoc = fs.readFileSync(path.join(root, "docs/readme-badges.md"), "utf8");
+for (const requiredSnippet of [
+  "buildchain badges readme --check",
+  "collectReadmeBadgeFacts",
+  "kungfu-buildchain-readme-badge-facts",
+  "KFD passed",
+  "release passport",
+  "<!-- buildchain:badges:start -->",
+]) {
+  if (!readmeBadgesDoc.includes(requiredSnippet)) {
+    throw new Error(`README badges doc missing required snippet: ${requiredSnippet}`);
+  }
+}
+const homebrewDoc = fs.readFileSync(path.join(root, "docs/homebrew.md"), "utf8");
+for (const requiredSnippet of [
+  "project.type = \"distribution-index\"",
+  "buildchain homebrew update-formula",
+  "buildchain homebrew check",
+  "collectHomebrewTapFacts",
+  "kungfu-buildchain-homebrew-tap-manifest",
+  "KFD passed",
+]) {
+  if (!homebrewDoc.includes(requiredSnippet)) {
+    throw new Error(`Homebrew doc missing required snippet: ${requiredSnippet}`);
+  }
+}
 const reusableBuildSurfaceDoc = fs.readFileSync(path.join(root, "docs/reusable-build-surface.md"), "utf8");
 for (const requiredSnippet of [
   "Floating Ref Contract Lock",
@@ -403,6 +460,18 @@ for (const [docName, docSource] of Object.entries({ "docs/cli.md": cliDoc, "docs
     }
   }
 }
+for (const requiredSnippet of [
+  "buildchain badges readme --check",
+  "buildchain badges readme --write",
+  "@kungfu-tech/buildchain/readme-badges",
+  "buildchain homebrew update-formula",
+  "buildchain homebrew check",
+  "@kungfu-tech/buildchain/homebrew",
+]) {
+  if (!cliDoc.includes(requiredSnippet)) {
+    throw new Error(`CLI doc missing README badge command snippet: ${requiredSnippet}`);
+  }
+}
 const releaseLineDryRunScript = fs.readFileSync(path.join(root, "scripts/release-line-dry-run.mjs"), "utf8");
 const standaloneBinaryScript = fs.readFileSync(path.join(root, "scripts/build-standalone-binary.mjs"), "utf8");
 for (const requiredSnippet of [

package/scripts/generate-site-bundle.mjs

@@ -293,6 +293,7 @@ function buildSiteBundle() {
       { id: "diagnostics-summary", usage: "buildchain diagnostics summary <diagnostics.json>...", purpose: "Summarize small diagnostics artifacts into JSON and a cross-platform lifecycle timing table." },
       { id: "npm-dry-run", usage: "buildchain npm dry-run --json", purpose: "Verify npm publish shape before a release transaction." },
       { id: "infra-contract", usage: "buildchain infra-contract --mode validate|ci|plan|contract|propagation-plan|propagation-apply|apply|evidence-bundle", purpose: "Validate and publish provider-neutral infrastructure contract evidence with a mutation-free CI evidence chain, provider command plans, configured provider command execution, saved-plan apply gates, dry-run-first propagation, and lifecycle evidence bundles." },
+      { id: "homebrew", usage: "buildchain homebrew update-formula|check", purpose: "Generate and verify Homebrew tap Formula metadata as a distribution-index projection of upstream release passport evidence." },
     ],
   };
 
@@ -317,6 +318,7 @@ function buildSiteBundle() {
       "docs/release-governance.md",
       "docs/release-passport.md",
       "docs/publish-transaction.md",
+      "docs/homebrew.md",
       "docs/site-bundle-contract.md",
       "docs/runtime-train-validation.md",
       "docs/consumer-issue-reporting.md",
@@ -356,6 +358,8 @@ function buildSiteBundle() {
       })),
     docs: [
       { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
+      { id: "readme-badges", path: "docs/readme-badges.md", digest: sha256File("docs/readme-badges.md") },
+      { id: "homebrew", path: "docs/homebrew.md", digest: sha256File("docs/homebrew.md") },
       { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },
     ],
     guidance: "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths.",
@@ -417,6 +421,14 @@ function buildSiteBundle() {
       ],
       owner: "promote-buildchain-ref",
     },
+    distributionIndexes: {
+      homebrewTap: {
+        projectType: "distribution-index",
+        manifest: "tap-manifest.json",
+        command: "buildchain homebrew check",
+        sourceOfTruth: "upstream release passport and sibling evidence",
+      },
+    },
   };
 
   const artifactSchemas = {