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

package/README.md

@@ -1,16 +1,16 @@
 # Buildchain
 
-[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg?branch=dev%2Fv2%2Fv2.8)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)
-[![Release Gate](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)
-[![npm latest](https://img.shields.io/npm/v/%40kungfu-tech%2Fbuildchain/latest?label=npm%20latest)](https://www.npmjs.com/package/@kungfu-tech/buildchain)
-[![npm alpha](https://img.shields.io/npm/v/%40kungfu-tech%2Fbuildchain/alpha?label=npm%20alpha)](https://www.npmjs.com/package/@kungfu-tech/buildchain?activeTab=versions)
-[![GitHub Release](https://img.shields.io/github/v/release/kungfu-systems/buildchain?label=release)](https://github.com/kungfu-systems/buildchain/releases)
-[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![KFD-1](https://img.shields.io/badge/KFD--1-contract%20world-2ea44f.svg)](docs/release-passport.md#kfd-1-contract-world-release-gate)
-[![KFD-2](https://img.shields.io/badge/KFD--2-trust%20passport-0969da.svg)](docs/release-passport.md#kfd-2-release-trust-passport-audit)
-[![KFD-3](https://img.shields.io/badge/KFD--3-collaboration%20interface-8250df.svg)](docs/release-passport.md#kfd-3-collaboration-interface-release-gate)
-![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen.svg)
-![Platforms: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)
+<!-- buildchain:badges:start -->
+[![KFD-1: passed](https://img.shields.io/badge/KFD--1-contract%20world%20passed-2ea44f.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
+[![KFD-2: passed](https://img.shields.io/badge/KFD--2-trust%20passport%20passed-2ea44f.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
+[![KFD-3: passed](https://img.shields.io/badge/KFD--3-collaboration%20interface%20passed-2ea44f.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
+[![Release Passport: passed](https://img.shields.io/badge/release%20passport-passed-2ea44f.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)
+[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
+[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)
+[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)
+[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)
+<!-- buildchain:badges:end -->
 
 Buildchain Release Passport is a mature product release record for artifacts
 that users or agents depend on.
@@ -97,6 +97,14 @@ const report = verifyBuildchainLogEvents({
 The package also ships `dist/site/` as the Buildchain-owned fact source for
 `buildchain.libkungfu.dev`.
 
+Repositories can also generate README status badges from Buildchain-owned facts
+instead of hand-maintaining badge Markdown:
+
+```bash
+buildchain badges readme --check
+buildchain badges readme --write
+```
+
 ## Project Governance
 
 - [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project

package/bin/buildchain.mjs

@@ -30,6 +30,18 @@ import {
   explainArtifactPassport,
   verifyArtifactPassport,
 } from "../packages/core/artifact-passport.js";
+import {
+  checkReadmeBadgeBlock,
+  collectReadmeBadgeFacts,
+  readReadme,
+  updateReadmeBadgeBlock,
+} from "../packages/core/readme-badges.js";
+import {
+  checkHomebrewTap,
+  collectHomebrewTapFacts,
+  renderHomebrewFormula,
+  updateHomebrewTap,
+} from "../packages/core/homebrew.js";
 import {
   BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
   formatDiagnosticsSummaryTable,
@@ -115,6 +127,9 @@ function usage() {
   buildchain web-surface ...
   buildchain infra-contract ...
   buildchain release-propagation <plan|write-lock> ...
+  buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
+  buildchain homebrew update-formula --package <name> --release-passport <file-or-url> [--write] [--json]
+  buildchain homebrew check [--cwd <dir>] [--package <name>] [--release-passport <file-or-url>] [--json]
   buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
   buildchain build-contract ...
 
@@ -277,6 +292,131 @@ function writeJsonFile(filePath, value) {
   return filePath;
 }
 
+async function runReadmeBadgesCli(args = []) {
+  const [subcommand = "", surface = "", ...badgeArgs] = args;
+  if (subcommand !== "readme" || (surface && surface.startsWith("--") === false)) {
+    throw new Error("usage: buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]");
+  }
+  const effectiveArgs = surface ? [surface, ...badgeArgs] : badgeArgs;
+  const cwd = path.resolve(readFlag(effectiveArgs, "cwd", process.cwd()));
+  const readmePath = readFlag(effectiveArgs, "readme", "README.md");
+  const facts = await collectReadmeBadgeFacts({ cwd });
+  if (readBooleanFlag(effectiveArgs, "json") && !readBooleanFlag(effectiveArgs, "check") && !readBooleanFlag(effectiveArgs, "write")) {
+    printJson(facts);
+    return;
+  }
+  const readmeText = readReadme({ cwd, readmePath });
+  if (!readmeText) {
+    throw new Error(`README not found: ${path.join(cwd, readmePath)}`);
+  }
+  const check = checkReadmeBadgeBlock({ readmeText, facts });
+  if (readBooleanFlag(effectiveArgs, "write")) {
+    const next = updateReadmeBadgeBlock({ readmeText, facts });
+    fs.writeFileSync(path.join(cwd, readmePath), next);
+    const result = {
+      schemaVersion: 1,
+      contract: "kungfu-buildchain-readme-badge-write",
+      ok: true,
+      changed: next !== readmeText,
+      readmePath,
+      facts,
+    };
+    if (readBooleanFlag(effectiveArgs, "json")) {
+      printJson(result);
+    } else {
+      process.stdout.write(`buildchain badges readme: ${result.changed ? "updated" : "current"}\n`);
+    }
+    return;
+  }
+  if (readBooleanFlag(effectiveArgs, "check")) {
+    if (readBooleanFlag(effectiveArgs, "json")) {
+      printJson(check);
+    } else {
+      process.stdout.write(`buildchain badges readme: ${check.ok ? "ok" : "failed"}\n`);
+      if (!check.ok) {
+        process.stdout.write(`${check.message}\n`);
+      }
+    }
+    if (!check.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  printJson(facts);
+}
+
+async function runHomebrewCli(args = []) {
+  const [subcommand = "", ...homebrewArgs] = args;
+  const cwd = path.resolve(readFlag(homebrewArgs, "cwd", process.cwd()));
+  const packageName = readFlag(homebrewArgs, "package", "buildchain");
+  const releasePassport = readFlag(homebrewArgs, "release-passport", "");
+  const manifestPath = readFlag(homebrewArgs, "manifest", "tap-manifest.json");
+  const formulaPath = readFlag(homebrewArgs, "formula", "");
+  const json = readBooleanFlag(homebrewArgs, "json");
+  if (subcommand === "update-formula") {
+    if (!releasePassport) {
+      throw new Error("buildchain homebrew update-formula requires --release-passport <file-or-url>");
+    }
+    if (readBooleanFlag(homebrewArgs, "write")) {
+      const result = await updateHomebrewTap({
+        cwd,
+        packageName,
+        releasePassport,
+        manifestPath,
+        formulaPath,
+        write: true,
+      });
+      if (json) {
+        printJson(result);
+      } else {
+        process.stdout.write(`buildchain homebrew update-formula: wrote ${result.written.join(", ")}\n`);
+      }
+      return;
+    }
+    const facts = await collectHomebrewTapFacts({
+      cwd,
+      packageName,
+      releasePassport,
+      manifestPath,
+      formulaPath,
+    });
+    if (json) {
+      printJson({
+        schemaVersion: 1,
+        contract: "kungfu-buildchain-homebrew-formula-render",
+        facts,
+        formula: renderHomebrewFormula(facts),
+        manifest: facts.manifestProjection,
+      });
+    } else {
+      process.stdout.write(renderHomebrewFormula(facts));
+    }
+    return;
+  }
+  if (subcommand === "check") {
+    const report = await checkHomebrewTap({
+      cwd,
+      packageName,
+      releasePassport,
+      manifestPath,
+      formulaPath,
+    });
+    if (json) {
+      printJson(report);
+    } else {
+      process.stdout.write(`buildchain homebrew check: ${report.ok ? "ok" : "failed"}\n`);
+      for (const check of report.checks) {
+        process.stdout.write(`- ${check.status}: ${check.id}: ${check.message}\n`);
+      }
+    }
+    if (!report.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  throw new Error("usage: buildchain homebrew <update-formula|check> ...");
+}
+
 function appendJsonLine(filePath, value) {
   if (!filePath) {
     return "";
@@ -951,6 +1091,16 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "badges") {
+    await runReadmeBadgesCli(args);
+    return;
+  }
+
+  if (command === "homebrew") {
+    await runHomebrewCli(args);
+    return;
+  }
+
   if (command === "build-contract") {
     runScript("resolve-build-contract.mjs", args);
     return;

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.8.15",
+    "version": "2.8.16-alpha.2",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -134,7 +134,7 @@
         "breaking contract drift fails closed before rendering, deployment, or release publication"
       ],
       "breakingDigest": "sha256:82ee63cb336e40d832dfff4a1c5e6cbfa221a4fc8b2359990033bc931bffc43a",
-      "auditDigest": "sha256:5416c9f4112bf24e7cef556f792034842252f65dcf9e8adf338ddc85a5137ada"
+      "auditDigest": "sha256:8de5899084cd0eebc93f5ac549b73c5ff313ac43067875d08b4ca8607d81fbf8"
     },
     {
       "contractVersion": 1,
@@ -235,7 +235,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
+      "auditDigest": "sha256:e4a79237c0363b60fe084393068f6bc7da526bb9c5912b60d747b75364506b32"
     },
     {
       "contractVersion": 1,
@@ -284,7 +284,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
+      "auditDigest": "sha256:e4a79237c0363b60fe084393068f6bc7da526bb9c5912b60d747b75364506b32"
     },
     {
       "contractVersion": 1,
@@ -331,16 +331,88 @@
       "optionalInputs": [
         "validate",
         "lifecycle",
+        "badges readme",
+        "homebrew update-formula",
+        "homebrew check",
         "collect github-release",
         "verify release-passport",
         "release-propagation",
         "infra-contract"
       ],
       "guarantees": [
-        "CLI commands are stable within the major line unless the contract major changes"
+        "CLI commands are stable within the major line unless the contract major changes",
+        "README badge block checks and writes are generated from machine-readable repository facts"
       ],
-      "breakingDigest": "sha256:097db3e67509bedda8c6548bf1edfbfcf57f7b5510520b6a7b7e078d7ec087c8",
-      "auditDigest": "sha256:1f4b07ac623517209dbdee2992f94d95f7ee96e8f35f13ef620dad8da9d2a6e0"
+      "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
+      "auditDigest": "sha256:b7cd109f1c81166fb912eced4b6d9aaa838ac537242197efd221e209da638d79"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "homebrew-distribution-index",
+      "kind": "node-api",
+      "path": "packages/core/homebrew.js",
+      "requiredInputs": [
+        "upstream release passport"
+      ],
+      "requiredOutputs": [
+        "kungfu-buildchain-homebrew-tap-facts",
+        "kungfu-buildchain-homebrew-tap-manifest",
+        "Formula/*.rb"
+      ],
+      "breakingDefaults": {
+        "projectType": "distribution-index",
+        "tapManifest": "tap-manifest.json",
+        "kfdPassedSource": "verified upstream release passport"
+      },
+      "optionalInputs": [
+        "buildchain.toml [project] type=distribution-index",
+        "Formula path",
+        "manifest path",
+        "release passport URL or local path"
+      ],
+      "guarantees": [
+        "Formula metadata is a deterministic projection of upstream release passport evidence",
+        "tap-manifest.json is checked against upstream version, URLs, SHA-256 digests, and KFD status",
+        "KFD passed claims fail closed unless the upstream release passport verifies the corresponding section",
+        "CLI and JavaScript callers use the same Node API implementation"
+      ],
+      "breakingDigest": "sha256:148c0387ff4cea76433bbde80cd9d77c5aa67e1a29856ced33e4d819366f2213",
+      "auditDigest": "sha256:0e978219bd6fca754d80a616d538d5825b116eec78b65857bbe5063b8c84d933"
+    },
+    {
+      "contractVersion": 1,
+      "stability": "stable",
+      "additiveChanges": "optional inputs, optional outputs, diagnostics, and documentation may be added within the same major line",
+      "id": "readme-badge-facts",
+      "kind": "node-api",
+      "path": "packages/core/readme-badges.js",
+      "requiredInputs": [
+        "repository checkout"
+      ],
+      "requiredOutputs": [
+        "kungfu-buildchain-readme-badge-facts"
+      ],
+      "breakingDefaults": {
+        "markerStart": "<!-- buildchain:badges:start -->",
+        "markerEnd": "<!-- buildchain:badges:end -->",
+        "kfdPassedSource": "verified repository-owned release passport"
+      },
+      "optionalInputs": [
+        "buildchain.toml [badges]",
+        "release passport URL or local path",
+        "workflow file list",
+        "platform declarations"
+      ],
+      "guarantees": [
+        "README badge Markdown is a deterministic projection of badge facts",
+        "KFD passed badges require the repository's own verified release passport section",
+        "unreleased repositories downgrade KFD status to explicit non-passed declarations",
+        "CLI and JavaScript callers use the same Node API implementation"
+      ],
+      "breakingDigest": "sha256:bcd72ad6dfba8013c96f8b2f7b0a307d2e7713972a1219348f0d5ecc493939a0",
+      "auditDigest": "sha256:a3400b0083430782d4fda283b21d308327eaed969053aa5b88a8b946bf83d4b3"
     },
     {
       "contractVersion": 1,
@@ -362,7 +434,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:fd6753b3d3cd7561cd5f137f78fafa70ad7a6cc014b9f5c021c12e835c8a7a60"
+      "auditDigest": "sha256:77b5234de4d1ac60b8291e63b21562cdf88c1ab33a369e1f0cccb1e75a62e492"
     },
     {
       "contractVersion": 1,
@@ -384,9 +456,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:8002cc53fb052c49e519cf2466d41b9f76a6241bcc8354520fad5121a7b78065"
+      "auditDigest": "sha256:587d0f465af8e3f1d871e469601999f57ac4911f3a84973fc6910b2db7555667"
     }
   ],
-  "compatibilityDigest": "sha256:85e27de8d34ceac1652d9374697ea5a1a7a08666d2ba7ae377b9afdd14e2ca1f",
-  "contractDigest": "sha256:3a7e7b0ae8accb3c830791de83b8af310305b198949adcbd1483526b5abb1b17"
+  "compatibilityDigest": "sha256:407d6d5ee6a96a34d2cc30db9ac64cf4b1819ab6d77bd7a57a07a124f22101ca",
+  "contractDigest": "sha256:df8e273c2225f1564d77e4089e5d0128746df3c121c9ccfa85082fff1a616ecb"
 }