Homebrew Distribution Indexes

Buildchain treats a Homebrew tap as a distribution-index project: the tap contains Formula or Cask files, but those files are projections of upstream release passports. Version, download URLs, SHA-256 digests, KFD status, and evidence links come from the upstream product release, not from hand-maintained tap prose.

Configuration

Use project.type = "distribution-index" for tap repositories:

schema = 1

[project]
type = "distribution-index"
name = "homebrew-tap"

[lifecycle.verify]
command = "buildchain homebrew check"

Buildchain v3.0.0 currently publishes evidence assets but no standalone platform archives, so the Buildchain formula continues to index the latest verified legacy binary line, v2.14.16. This does not change the tap repository’s v3 management workflow.

The tap manifest is the repository-owned declaration of which upstream releases are indexed. Buildchain writes tap-manifest.json as a machine-readable projection:

{
  "schema": 1,
  "contract": "kungfu-buildchain-homebrew-tap-manifest",
  "kind": "homebrew-tap",
  "entries": [
    {
      "type": "formula",
      "name": "buildchain",
      "path": "Formula/buildchain.rb",
      "upstream": {
        "repository": "kungfu-systems/buildchain",
        "tag": "v2.14.16",
        "releasePassportUrl": "https://github.com/kungfu-systems/buildchain/releases/download/v2.14.16/buildchain.release.json"
      },
      "version": "2.14.16",
      "kfd": {
        "kfd-1": "passed",
        "kfd-2": "passed",
        "kfd-3": "passed"
      },
      "artifacts": [
        {
          "platform": "darwin-arm64",
          "url": "https://github.com/kungfu-systems/buildchain/releases/download/v2.14.16/buildchain-aarch64-apple-darwin.tar.gz",
          "sha256": "..."
        }
      ]
    }
  ]
}

CLI

Update a formula and manifest from an upstream passport:

buildchain homebrew update-formula \
  --package buildchain \
  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.14.16/buildchain.release.json \
  --write

Check that the tap still matches upstream evidence:

buildchain homebrew check --json

check fails closed when:

the upstream release passport or its sibling evidence does not verify;
Formula/buildchain.rb drifts from the projected version, URLs, or SHA-256 digests;
tap-manifest.json drifts from the projected upstream evidence;
the tap claims KFD-1, KFD-2, or KFD-3 passed without a verified upstream passport section.

Node API

Use the public @kungfu-tech/buildchain/homebrew export:

import {
  collectHomebrewTapFacts,
  renderHomebrewFormula,
  checkHomebrewTap,
  updateHomebrewTap,
} from "@kungfu-tech/buildchain/homebrew";

The API is the single implementation source. The CLI is a thin wrapper over these functions, so CI and local update commands evaluate the same facts.

Trust Model

Formula metadata is not source of truth. A tap entry may claim kfd-1, kfd-2, or kfd-3 passed only when the upstream release passport verifies and the corresponding passport section is status = "passed". If verification fails, Buildchain downgrades the projected KFD status to unverified and buildchain homebrew check fails.

In short: KFD passed in a tap means the upstream release passport passed, not that the tap author typed a passing status.

This makes Homebrew taps suitable for automated distribution-index CI: the tap can move quickly while still proving that every download URL and digest is bound to release passport evidence.

Homebrew Distribution Indexes