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

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,12 @@ import {
   explainArtifactPassport,
   verifyArtifactPassport,
 } from "../packages/core/artifact-passport.js";
+import {
+  checkReadmeBadgeBlock,
+  collectReadmeBadgeFacts,
+  readReadme,
+  updateReadmeBadgeBlock,
+} from "../packages/core/readme-badges.js";
 import {
   BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
   formatDiagnosticsSummaryTable,
@@ -115,6 +121,7 @@ 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 publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
   buildchain build-contract ...
 
@@ -277,6 +284,59 @@ 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);
+}
+
 function appendJsonLine(filePath, value) {
   if (!filePath) {
     return "";
@@ -951,6 +1011,11 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "badges") {
+    await runReadmeBadgesCli(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.1",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -235,7 +235,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
+      "auditDigest": "sha256:4d88ba7178753d2d1488f6393fee7c086dfb660f42e6507db718dccd38bf8a34"
     },
     {
       "contractVersion": 1,
@@ -284,7 +284,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
+      "auditDigest": "sha256:4d88ba7178753d2d1488f6393fee7c086dfb660f42e6507db718dccd38bf8a34"
     },
     {
       "contractVersion": 1,
@@ -331,16 +331,51 @@
       "optionalInputs": [
         "validate",
         "lifecycle",
+        "badges readme",
         "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:af247c9ce9227e64e07344fee30d718646ed66ada69b6e1d6155a7f33ff1005e"
+    },
+    {
+      "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 +397,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:99fd5e862e5a29eb10b0ec5a7a5e06d9ab7a594bd7b345bfcb8d45a0a099b9fc"
     },
     {
       "contractVersion": 1,
@@ -384,9 +419,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:8002cc53fb052c49e519cf2466d41b9f76a6241bcc8354520fad5121a7b78065"
+      "auditDigest": "sha256:e1fae05f9ab0186e9423464b7e4bcb9bfefe4185fe0925a0b95368fb97f1cd41"
     }
   ],
-  "compatibilityDigest": "sha256:85e27de8d34ceac1652d9374697ea5a1a7a08666d2ba7ae377b9afdd14e2ca1f",
-  "contractDigest": "sha256:3a7e7b0ae8accb3c830791de83b8af310305b198949adcbd1483526b5abb1b17"
+  "compatibilityDigest": "sha256:217f7764849bf779cbc70aea9da59429a44c68f5f7131b26593bb18a6e7ffb18",
+  "contractDigest": "sha256:242f4e40e1768fddb28264561efcfaf3a206b3907c35f08143d4b98a4e13b527"
 }