@kungfu-tech/buildchain 2.2.1-alpha.0 → 2.2.1

package/docs/site-bundle-contract.md

@@ -0,0 +1,70 @@
+# Site Bundle Contract
+
+`@kungfu-tech/buildchain` publishes `dist/site/` as the package-owned fact
+source for `buildchain.libkungfu.dev` and other documentation surfaces.
+
+The website may design navigation, visual hierarchy, examples, and explanatory
+copy around these facts. It should not hand-write the current Buildchain
+release mechanics, command registry, workflow registry, or artifact schema.
+
+## Files
+
+```text
+dist/site/
+  buildchain-site.json
+  site-manifest.json
+  cli-registry.json
+  workflow-registry.json
+  release-model.json
+  artifact-schemas.json
+  product-mechanism.json
+  release-provenance.json
+  agent-index.json
+```
+
+`buildchain-site.json` is the top-level bundle entrypoint.
+
+## npm Consumption
+
+```bash
+npm install @kungfu-tech/buildchain
+```
+
+Then read files from:
+
+```text
+node_modules/@kungfu-tech/buildchain/dist/site/
+```
+
+Package exports are also provided for direct JSON-aware consumers:
+
+```js
+import siteManifest from "@kungfu-tech/buildchain/site/site-manifest.json" with { type: "json" };
+```
+
+## Generation
+
+```bash
+pnpm run generate:site
+pnpm run check:site
+```
+
+`check:site` fails when generated files are stale. `pnpm run check` includes
+this gate, so release candidates cannot publish an out-of-date site bundle.
+
+## Scope
+
+The P0 bundle includes:
+
+- site manifest;
+- CLI command registry;
+- workflow/action registry;
+- release model facts;
+- artifact and evidence schema index;
+- product mechanism manifest;
+- release provenance;
+- agent read order.
+
+Future minor lines can add examples, recipes, fixture indexes, and richer
+schema metadata without breaking existing consumers.
+

package/docs/toolkit-observability.md

@@ -0,0 +1,70 @@
+# Toolkit Observability
+
+Buildchain ships a small logging toolkit for repository workflows and project
+scripts. The goal is to separate time spent in Buildchain's framework from time
+spent in the consumer's own build, test, packaging, and publish steps.
+
+## CLI Logging
+
+```bash
+buildchain mark \
+  --event native.configure \
+  --phase configure \
+  --component cmake \
+  --attribute preset=release
+
+buildchain span \
+  --event native.build \
+  --phase build \
+  --component cmake \
+  -- cmake --build build --config Release
+
+buildchain log summary --json
+buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4
+```
+
+Every event records a timestamp. `span` records duration and preserves the
+wrapped command's exit code.
+
+## Library API
+
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+
+const logger = createBuildchainLogger({
+  source: "consumer",
+  component: "native-build",
+  phase: "compile",
+});
+
+const span = logger.span("native.compile", { attributes: { target: "release" } });
+try {
+  await compile();
+  span.end();
+} catch (error) {
+  span.error(error);
+  throw error;
+}
+```
+
+Use the API when a build script has internal stages that are invisible to the
+outer workflow. Keep secret values out of attributes; known sensitive keys are
+redacted, but callers should still avoid logging private material.
+
+## Release Gate
+
+Buildchain's own binary distribution lane verifies required log events before
+uploading release assets. Consumers can apply the same pattern:
+
+```bash
+buildchain verify observability-log .buildchain/logs/events.jsonl \
+  --require-phase build \
+  --require-phase package \
+  --require-component workflow \
+  --require-event native.build.start \
+  --require-event native.build.end
+```
+
+This makes missing instrumentation a release failure instead of a dashboard
+afterthought.
+

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.2.1-alpha.0",
+  "version": "2.2.1",
   "private": false,
-  "description": "Kungfu Buildchain reusable workflows, release governance, and CLI tooling.",
+  "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
   "author": "Keren Dong",
   "license": "Apache-2.0",
@@ -15,6 +15,15 @@
     "./core": "./packages/core/index.js",
     "./logging": "./packages/core/logging.js",
     "./release-passport": "./packages/core/release-passport.js",
+    "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
+    "./site/site-manifest.json": "./dist/site/site-manifest.json",
+    "./site/cli-registry.json": "./dist/site/cli-registry.json",
+    "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
+    "./site/release-model.json": "./dist/site/release-model.json",
+    "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",
+    "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
+    "./site/release-provenance.json": "./dist/site/release-provenance.json",
+    "./site/agent-index.json": "./dist/site/agent-index.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -24,18 +33,24 @@
     "LICENSE-POLICY.md",
     "scripts/*.mjs",
     "packages/core/",
+    "dist/site/",
     "README.md",
     "SECURITY.md",
     "docs/MAP.md",
+    "docs/binary-distribution.md",
     "docs/cli.md",
+    "docs/install.md",
     "docs/lifecycle-protocol.md",
     "docs/migration-inventory.md",
     "docs/ownership.md",
+    "docs/product-mechanism.md",
     "docs/publish-transaction.md",
     "docs/release-passport.md",
     "docs/release-flow.md",
     "docs/release-governance.md",
     "docs/reusable-build-surface.md",
+    "docs/site-bundle-contract.md",
+    "docs/toolkit-observability.md",
     "docs/versioning.md",
     "docs/web-surface-deployments.md",
     "actions/*/README.md",
@@ -50,8 +65,10 @@
   },
   "packageManager": "pnpm@11.7.0",
   "scripts": {
-    "check": "node scripts/check-inventory.mjs && pnpm run check:workflows && pnpm run test:unit && pnpm -r --filter \"./actions/**\" build",
+    "check": "node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm -r --filter \"./actions/**\" build",
     "check:workflows": "bash scripts/check-workflows.sh",
+    "generate:site": "node scripts/generate-site-bundle.mjs",
+    "check:site": "node scripts/generate-site-bundle.mjs --check",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",
     "package": "npm pack --dry-run --json --registry=https://registry.npmjs.org/",

package/scripts/check-inventory.mjs

@@ -15,11 +15,18 @@ const requiredPaths = [
   ".github/pull_request_template.md",
   "bin/buildchain.mjs",
   "docs/MAP.md",
+  "docs/binary-distribution.md",
   "docs/cli.md",
+  "docs/install.md",
+  "docs/product-mechanism.md",
   "docs/release-passport.md",
+  "docs/site-bundle-contract.md",
+  "docs/toolkit-observability.md",
   "docs/versioning.md",
   "scripts/release-line-dry-run.mjs",
   "scripts/build-standalone-binary.mjs",
+  "scripts/create-release-bundle.mjs",
+  "scripts/generate-site-bundle.mjs",
   "scripts/npm-publish-dry-run.mjs",
   "scripts/npm-publish-transaction.mjs",
   "docs/migration-inventory.md",
@@ -76,6 +83,11 @@ for (const expectedFile of ["bin/", "scripts/*.mjs", "packages/core/", "docs/MAP
     throw new Error(`root package files must include ${expectedFile}`);
   }
 }
+for (const expectedFile of ["dist/site/", "docs/install.md", "docs/binary-distribution.md", "docs/site-bundle-contract.md"]) {
+  if (!rootPackage.files?.includes(expectedFile)) {
+    throw new Error(`root package files must include ${expectedFile}`);
+  }
+}
 const cliSource = fs.readFileSync(path.join(root, "bin/buildchain.mjs"), "utf8");
 const coreIndexSource = fs.readFileSync(path.join(root, "packages/core/index.js"), "utf8");
 const versioningDoc = fs.readFileSync(path.join(root, "docs/versioning.md"), "utf8");
@@ -206,6 +218,8 @@ for (const requiredSnippet of [
   "bin/buildchain.mjs log summary",
   "collect github-release",
   "verify release-passport",
+  "scripts/create-release-bundle.mjs",
+  "buildchain-release-bundle",
   "gh release upload",
 ]) {
   if (!binaryDistributionWorkflow.includes(requiredSnippet)) {
@@ -247,12 +261,27 @@ if (inventory.safety?.releasePassport?.binaryDistribution?.productionRunnerDefau
 if (inventory.safety?.releasePassport?.binaryDistribution?.selfHostedRole !== "compatibility-fixture") {
   throw new Error("self-hosted runners must remain release passport compatibility fixtures");
 }
-for (const artifact of ["buildchain.release.json", "artifact-evidence.json", "impact.json", "agent-index.json", "llms.txt"]) {
+for (const artifact of [
+  "buildchain.release.json",
+  "artifact-evidence.json",
+  "impact.json",
+  "agent-index.json",
+  "check-report.json",
+  "llms.txt",
+  "buildchain-release-bundle.json",
+  "buildchain-release-bundle.tar.gz",
+]) {
   if (!inventory.safety?.releasePassport?.protocolArtifacts?.includes(artifact)) {
     throw new Error(`release passport inventory missing protocol artifact ${artifact}`);
   }
 }
 
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "cli-registry.json", "release-model.json"]) {
+  if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
+    throw new Error(`site bundle missing ${siteFile}`);
+  }
+}
+
 if (!Array.isArray(inventory.workflowSources) || inventory.workflowSources.length < 1) {
   throw new Error("workflowSources must include the migrated workflows repository");
 }

package/scripts/create-release-bundle.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const BUNDLE_CONTRACT = "kungfu-buildchain-release-evidence-bundle";
+const BUNDLE_BASE = "buildchain-release-bundle";
+
+function readArg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return process.argv[index + 1] || "";
+}
+
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function listFiles(dir) {
+  if (!dir || !fs.existsSync(dir)) {
+    return [];
+  }
+  const results = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryPath);
+      } else if (entry.isFile()) {
+        results.push(entryPath);
+      }
+    }
+  };
+  walk(dir);
+  return results.sort((a, b) => a.localeCompare(b));
+}
+
+function copyFile(source, destination) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+function relative(root, target) {
+  return path.relative(root, target).split(path.sep).join("/");
+}
+
+function isBundleOutput(filePath) {
+  const name = path.basename(filePath);
+  return name === `${BUNDLE_BASE}.tar.gz` || name === `${BUNDLE_BASE}.json`;
+}
+
+export function createReleaseEvidenceBundle({
+  cwd = process.cwd(),
+  assetsDir = "dist/binary",
+  passportDir = ".buildchain/release-passport",
+  outputDir = ".buildchain/release-passport",
+  tag = "",
+  sourceSha = "",
+} = {}) {
+  const resolvedAssetsDir = path.resolve(cwd, assetsDir);
+  const resolvedPassportDir = path.resolve(cwd, passportDir);
+  const resolvedOutputDir = path.resolve(cwd, outputDir);
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-release-bundle-"));
+  const bundleRoot = path.join(tempDir, BUNDLE_BASE);
+  const sourceSets = [
+    { id: "release-assets", dir: resolvedAssetsDir, bundlePrefix: "release-assets" },
+    { id: "release-passport", dir: resolvedPassportDir, bundlePrefix: "release-passport" },
+  ];
+  const included = [];
+  for (const sourceSet of sourceSets) {
+    for (const sourcePath of listFiles(sourceSet.dir)) {
+      if (isBundleOutput(sourcePath)) {
+        continue;
+      }
+      const sourceRelative = relative(sourceSet.dir, sourcePath);
+      const bundlePath = path.join(bundleRoot, sourceSet.bundlePrefix, sourceRelative);
+      copyFile(sourcePath, bundlePath);
+      included.push({
+        source: sourceSet.id,
+        sourcePath: relative(cwd, sourcePath),
+        bundlePath: relative(bundleRoot, bundlePath),
+        size: fs.statSync(sourcePath).size,
+        sha256: sha256File(sourcePath),
+      });
+    }
+  }
+  if (included.length === 0) {
+    throw new Error("release evidence bundle requires at least one input file");
+  }
+
+  const index = {
+    schemaVersion: 1,
+    contract: BUNDLE_CONTRACT,
+    release: {
+      tag,
+      sourceSha,
+    },
+    entrypoints: {
+      releasePassport: "release-passport/buildchain.release.json",
+      checksums: "release-assets/checksums.txt",
+      agentIndex: "release-passport/agent-index.json",
+      llms: "release-passport/llms.txt",
+    },
+    files: included,
+  };
+  fs.writeFileSync(path.join(bundleRoot, `${BUNDLE_BASE}.index.json`), `${JSON.stringify(index, null, 2)}\n`);
+
+  fs.mkdirSync(resolvedOutputDir, { recursive: true });
+  const archivePath = path.join(resolvedOutputDir, `${BUNDLE_BASE}.tar.gz`);
+  const tar = spawnSync("tar", ["-czf", archivePath, "-C", tempDir, BUNDLE_BASE], {
+    cwd,
+    stdio: "inherit",
+  });
+  if (tar.error) {
+    throw tar.error;
+  }
+  if (tar.status !== 0) {
+    throw new Error(`tar exited with ${tar.status}`);
+  }
+  const manifest = {
+    ...index,
+    bundle: {
+      name: path.basename(archivePath),
+      path: relative(cwd, archivePath),
+      size: fs.statSync(archivePath).size,
+      sha256: sha256File(archivePath),
+    },
+  };
+  const manifestPath = path.join(resolvedOutputDir, `${BUNDLE_BASE}.json`);
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return {
+    outputDir: resolvedOutputDir,
+    archivePath,
+    manifestPath,
+    manifest,
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = createReleaseEvidenceBundle({
+      cwd: path.resolve(readArg("cwd", process.cwd())),
+      assetsDir: readArg("assets-dir", "dist/binary"),
+      passportDir: readArg("passport-dir", ".buildchain/release-passport"),
+      outputDir: readArg("output-dir", ".buildchain/release-passport"),
+      tag: readArg("tag", process.env.RELEASE_TAG || ""),
+      sourceSha: readArg("source-sha", process.env.GITHUB_SHA || ""),
+    });
+    process.stdout.write(`${JSON.stringify({
+      contract: BUNDLE_CONTRACT,
+      archive: result.manifest.bundle,
+      fileCount: result.manifest.files.length,
+    }, null, 2)}\n`);
+  } catch (error) {
+    console.error(`buildchain release bundle: ${error.message}`);
+    process.exitCode = 1;
+  }
+}