@kungfu-tech/buildchain 4.1.3-alpha.0 → 4.1.3-alpha.10

package/scripts/generate-minimal-consumer-contract.mjs

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { parse as yaml } from "yaml";
+import { format } from "prettier";
+import { standardConsumerExample } from "../packages/core/consumer/contract/examples.js";
+import { inspectConsumerContract } from "../packages/core/consumer/contract/inspection.js";
+import { workflowPath } from "../packages/core/workflow/workflow-taxonomy.mjs";
+
+const root = process.cwd(),
+  check = process.argv.includes("--check");
+const tracked = execFileSync("git", ["ls-files", "-z"], { encoding: "utf8" })
+  .split("\0")
+  .filter(Boolean);
+
+function output(file, value) {
+  const target = path.join(root, file);
+  if (check) {
+    if (!fs.existsSync(target) || fs.readFileSync(target, "utf8") !== value)
+      throw new Error(`${file}: generated contract drift`);
+  } else {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, value);
+  }
+}
+
+function destination(name) {
+  if (name === "config-path") return "normal-entry.config-path";
+  if (name === "runtime-ref") return "recovery-entry.runtime-ref";
+  if (/token|secret|private-key|app-id/u.test(name))
+    return "setup.provider-authority";
+  if (/run|resume|recover|transaction|discussion|attempt/u.test(name))
+    return "attempt.material-index";
+  if (/root|proof|nonce|warrant|fence|generation|candidate/u.test(name))
+    return "attempt.internal-authority";
+  return "internal.plan-derived-input";
+}
+
+function workflowInventory() {
+  const taxonomy = JSON.parse(
+    fs.readFileSync("architecture/workflow-taxonomy.json", "utf8"),
+  );
+  return taxonomy.entries
+    .filter((entry) => ["public", "self"].includes(entry.role))
+    .map((entry) => {
+      const file = workflowPath(entry),
+        document = yaml(fs.readFileSync(file, "utf8"));
+      return {
+        path: file,
+        role: entry.role,
+        events: Object.keys(document.on || {}).sort(),
+        secrets: Object.keys(document.on?.workflow_call?.secrets || {}).sort(),
+        outputs: Object.keys(document.on?.workflow_call?.outputs || {}).sort(),
+        destination:
+          entry.role === "self"
+            ? "self-dogfood.two-callers-or-internal-component"
+            : "internal-component.behind-pipeline-or-recovery",
+        interfaces: ["workflow_call", "workflow_dispatch"].flatMap((trigger) =>
+          Object.entries(document.on?.[trigger]?.inputs || {}).map(
+            ([name, definition]) => ({
+              trigger,
+              name,
+              definition,
+              destination: destination(name),
+            }),
+          ),
+        ),
+        calls: Object.entries(document.jobs || {})
+          .filter(([, job]) => job.uses)
+          .map(([id, job]) => ({
+            id,
+            uses: job.uses,
+            inputs: Object.keys(job.with || {}).sort(),
+            destination: "internal.workflow-composition",
+          })),
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function consumerSourceInventory() {
+  return tracked
+    .filter(
+      (file) =>
+        (/^(?:templates|fixtures|\.buildchain)\//u.test(file) ||
+          file === "package.json") &&
+        /\.(?:ya?ml|toml|json|[cm]?js|sh|py|ps1)$/u.test(file) &&
+        !file.startsWith("templates/minimal-consumer/"),
+    )
+    .map((file) => {
+      const bytes = fs.readFileSync(file, "utf8");
+      const kind = /\.ya?ml$/u.test(file)
+        ? "caller"
+        : /\.toml$/u.test(file)
+          ? "config"
+          : "consumer-source";
+      return {
+        path: file,
+        kind,
+        destination:
+          kind === "caller"
+            ? "replace-with-shared-pair"
+            : kind === "config"
+              ? "closed-toml-plan"
+              : "retain-product-source; move-orchestration-into-runtime",
+        commandReferences: [
+          ...new Set(
+            bytes.match(
+              /(?:packages\/core|scripts)\/[A-Za-z0-9_./-]+\.(?:[cm]?js|sh|py|ps1)/gu,
+            ) || [],
+          ),
+        ].sort(),
+      };
+    });
+}
+
+for (const type of ["npm", "binary", "paper"]) {
+  const files = standardConsumerExample(type);
+  if (check) {
+    const directory = `templates/minimal-consumer/${type}`;
+    for (const entry of fs.readdirSync(directory, {
+      recursive: true,
+      withFileTypes: true,
+    })) {
+      if (entry.isDirectory()) continue;
+      const file = path
+        .relative(directory, path.join(entry.parentPath, entry.name))
+        .split(path.sep)
+        .join("/");
+      if (!entry.isFile() || !Object.hasOwn(files, file))
+        throw new Error(
+          `${directory}/${file}: undeclared generated consumer file`,
+        );
+    }
+  }
+  const inspection = inspectConsumerContract(files);
+  if (!inspection.ok) throw new Error(inspection.issues.join("\n"));
+  for (const [file, bytes] of Object.entries(files))
+    output(`templates/minimal-consumer/${type}/${file}`, bytes);
+}
+output(
+  "architecture/minimal-consumer-migration.json",
+  await format(
+    JSON.stringify({
+      schema: "buildchain.consumer-migration/v1",
+      stage: "self-cutover-in-progress; final-release-qualification-pending",
+      workflows: workflowInventory(),
+      consumerSources: consumerSourceInventory(),
+    }),
+    { parser: "json" },
+  ),
+);
+console.log(
+  "Minimal consumer contract: three shared-caller examples and complete migration inventory verified.",
+);

package/scripts/generate-site-bundle.mjs

@@ -1343,7 +1343,7 @@ function buildSiteBundle() {
     "badge-endpoint-registry.json": badgeEndpointRegistry,
     "publication-registry.json": publicationRegistry,
     "buildchain-contract.json": createBuildchainContractWorld({ root, controllerRegistry }),
-    "kfd-upstream-aggregate.json": collectKfdUpstreamFacts({ cwd: root, includeOwn: false }),
+    "kfd-upstream-aggregate.json": collectKfdUpstreamFacts({ cwd: root, components: readJson("architecture/product-upstreams.json"), includeOwn: false }),
     "kfd-claims.json": createBuildchainKfdClaimRegistry({ root }),
     "product-mechanism.json": productMechanism,
     "release-provenance.json": releaseProvenance,

package/scripts/inventory/binary.mjs

@@ -1,26 +1,16 @@
 import assert from "node:assert/strict";
+import { checkSelfConsumerContract } from "../check-self-consumer-contract.mjs";
 import { inspectWorkflowJob, readWorkflow } from "../workflow-action-graph.mjs";
 
 export function assertBinaryInventory(root) {
-  const file = ".github/workflows/self-build-binary-distribution.yml";
-  const workflow = readWorkflow(file, root);
-  assert.equal(workflow.name, "Binary Distribution");
-  assert.deepEqual(Object.keys(workflow.jobs).filter(id => id !== "execution-runtime"), ["preflight", "binary", "passport", "dispatch-publication"]);
-  const graphs = Object.keys(workflow.jobs).filter(id => id !== "execution-runtime").map(id => inspectWorkflowJob(file, id, root));
-  for (const graph of graphs) {
-    assert.equal(graph.job.permissions.contents, "read");
-    assert.notEqual(graph.job.permissions["id-token"], "write");
-    assert.ok(!JSON.stringify(graph.job["runs-on"]).includes("self-hosted"));
-    for (const step of graph.steps) assert.ok(!/gh release (?:upload|create)/u.test(step.run || ""));
-    assert.ok(graph.actions.has(`actions/build/binary/${["preflight", "build", "passport", "dispatch-publication"][graphs.indexOf(graph)]}`));
-  }
-  const binary = graphs[1];
-  assert.deepEqual(binary.job.strategy.matrix.include.map(entry => entry.os).sort(), ["macos-latest", "ubuntu-24.04", "windows-2022"]);
-  const passport = graphs[2];
-  const executable = passport.modules.get("packages/core/build/binary/distribution.js");
-  for (const command of ["verifyBuildchainLogEvents", "verifyReleasePassport", "verifyArtifactPassport", "createReleaseEvidenceBundle", "buildchain-log-events", "buildchain-log-summary"])
-    assert.ok(executable.includes(command), `Binary evidence is missing ${command}`);
-  assert.ok(passport.actions.has("actions/build/binary/qualify"));
+  const { plan } = checkSelfConsumerContract(root);
+  assert.deepEqual(plan.products.filter(product => product.type === "binary")
+    .flatMap(product => product.platforms).sort(), ["linux-x64", "macos-arm64", "windows-x64"]);
+  const build = inspectWorkflowJob(".github/workflows/.release-pipeline-products.yml", "build", root);
+  assert.equal(build.job.permissions.contents, "read");
+  assert.notEqual(build.job.permissions["id-token"], "write");
+  assert.ok(!JSON.stringify(build.job["runs-on"]).includes("self-hosted"));
+  for (const step of build.steps) assert.ok(!/gh release (?:upload|create)/u.test(step.run || ""));
   const publish = inspectWorkflowJob(".github/workflows/.release-binary-assets.yml", "publish", root);
   assert.equal(publish.workflow.jobs["publication-authority"].uses, "./.github/workflows/.release-authority.yml");
   assert.ok(publish.job.needs.includes("publication-authority"));

package/scripts/inventory/promotion.mjs

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { checkSelfConsumerContract } from "../check-self-consumer-contract.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
@@ -35,19 +36,7 @@ export function assertPromotionInventory(root) {
     "publish-command",
   ])
     assert.ok(!request.properties[key]);
-  for (const file of [
-    "self-release-promote",
-    "self-release-tail-dogfood",
-    "self-ops-promotion-recovery",
-  ]) {
-    const caller = YAML.parse(read(`.github/workflows/${file}.yml`));
-    const calls = Object.values(caller.jobs).filter(
-      (job) => job.uses === `kungfu-systems/buildchain/${publicPath}@v4`,
-    );
-    assert.equal(calls.length, 1, file);
-    assert.ok(calls[0].with["request-json"]);
-    assert.ok(Object.keys(calls[0].with).every(key => ["request-json", "runtime-ref", "contract-lock", "runtime-selection"].includes(key)));
-  }
+  checkSelfConsumerContract(root);
   const component = ".github/workflows/.release-promote.yml";
   const expected = {
     qualify: "promotion/qualify",

package/scripts/prepare-product-toolchain.mjs

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Product prerequisites cross command phases through the runner file protocol.
+// An explicit cache works with the credential-isolated Windows environment too.
+fs.appendFileSync(
+  process.env.GITHUB_ENV,
+  `GOTOOLCHAIN=go1.25.14+auto\nGOCACHE=${path.join(os.tmpdir(), "buildchain-go-cache")}\nGOPATH=${path.join(os.tmpdir(), "buildchain-go")}\n`,
+);

package/scripts/verify-golden-path.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import { readNpmPackResult } from "../packages/core/publication/npm/pack-result.js";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -44,7 +45,10 @@ export function verifyGoldenPath() {
       ["pack", "--json", "--pack-destination", packDir],
       { cwd: root, json: true },
     );
-    const tarball = path.join(packDir, packed[0].filename);
+    const tarball = path.join(
+      packDir,
+      readNpmPackResult(JSON.stringify(packed)).filename,
+    );
     fs.writeFileSync(
       path.join(consumer, "package.json"),
       `${JSON.stringify(

package/scripts/verify-product-platform.mjs

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { verifyStageCapsuleCheckpoints } from "../packages/core/build/stage-capsule/rehearsal/verify.js";
+
+const platform = {
+  linux: "linux-x64",
+  darwin: "macos-arm64",
+  win32: "windows-x64",
+}[process.platform];
+if (!platform)
+  throw new Error(
+    `Unsupported product verification platform: ${process.platform}`,
+  );
+const goVersion = execFileSync("go", ["version"], { encoding: "utf8" }).trim();
+const goMatch = /^go version go1\.(\d+)\./u.exec(goVersion);
+if (!goMatch || Number(goMatch[1]) < 25)
+  throw new Error(
+    `Product verification requires Go 1.25 or newer in major 1: ${goVersion}`,
+  );
+const workspace = process.cwd();
+const result = verifyStageCapsuleCheckpoints({
+  runtimeRoot: workspace,
+  workspace,
+  platform,
+  environment: process.env,
+});
+if (platform === "linux-x64") {
+  // Same immutable image and backbone tests as the retired container CI lane.
+  // Supply the selected Node as the hosted container runner did; no credentials.
+  const image =
+    "ghcr.io/kungfu-systems/build-images/kungfu-verify@sha256:11f0ba64267ce88174a4f73a9bf833ff4e9c59cd16ec3d08a6432a06c2be6fb1";
+  execFileSync(
+    "docker",
+    [
+      "run",
+      "--rm",
+      "--network=none",
+      "--cap-drop=ALL",
+      "--security-opt=no-new-privileges",
+      "--mount",
+      `type=bind,source=${path.resolve(workspace)},target=/source,readonly`,
+      "--mount",
+      `type=bind,source=${process.execPath},target=/toolchain/node,readonly`,
+      "--env",
+      "PATH=/toolchain:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+      "--workdir",
+      "/source",
+      image,
+      "node",
+      "--test",
+      "tests/build-orchestration.test.mjs",
+      "tests/build-artifact-pipeline.test.mjs",
+      "tests/dev-delivery-minimal-request.test.mjs",
+    ],
+    { stdio: "inherit" },
+  );
+}
+console.log(
+  JSON.stringify({
+    platform,
+    checkpoint: result.checkpoint,
+    resume: result.resume,
+    tail: result.tail,
+  }),
+);

package/scripts/verify-standalone-product.mjs

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  platformTriple,
+  packageVersion,
+  sourceSha,
+} from "../packages/core/build/standalone/identity.js";
+
+const cwd = process.cwd();
+const manifest = JSON.parse(
+  fs.readFileSync(
+    path.join(cwd, "dist/binary", `buildchain-${platformTriple()}.json`),
+    "utf8",
+  ),
+);
+const version = packageVersion(cwd);
+assert.equal(manifest.version, version);
+assert.equal(manifest.sourceSha, sourceSha(cwd));
+assert.equal(manifest.platform, platformTriple());
+const binary = path.join(
+  cwd,
+  "dist/binary",
+  process.platform === "win32" ? "buildchain.exe" : "buildchain",
+);
+assert.equal(
+  createHash("sha256").update(fs.readFileSync(binary)).digest("hex"),
+  manifest.sha256,
+);
+assert.equal(
+  execFileSync(binary, ["--version"], { encoding: "utf8" }).trim(),
+  version,
+);
+assert.match(
+  execFileSync(binary, ["help"], { encoding: "utf8" }),
+  /^Usage:\s+buildchain --help/mu,
+);
+process.stdout.write(
+  `Verified standalone product ${platformTriple()} at ${version}\n`,
+);

package/templates/minimal-consumer/binary/.buildchain/buildchain.toml

@@ -0,0 +1,45 @@
+schema = 2
+
+[[products]]
+id = "main"
+type = "binary"
+platforms = ["linux-x64"]
+build = ["node src/build.mjs"]
+verify = ["node src/verify.mjs"]
+
+[[products.artifacts]]
+id = "main"
+path = "dist/hello.tar.gz"
+kind = "archive"
+
+[[products.targets]]
+provider = "github-release"
+artifacts = ["main"]
+
+[version]
+strategy = "semver"
+
+[[version.files]]
+path = "package.json"
+format = "json"
+key = "version"
+
+[[channels]]
+from = "feature/*"
+to = "dev/v1/v1.0"
+operation = "develop"
+
+[[channels]]
+from = "dev/v1/v1.0"
+to = "alpha/v1/v1.0"
+operation = "alpha"
+
+[[channels]]
+from = "alpha/v1/v1.0"
+to = "release/v1/v1.0"
+operation = "stable"
+
+[review]
+minimum_approvals = 1
+code_owners = true
+merge_queue = true

package/templates/minimal-consumer/binary/.github/workflows/buildchain-recover.yml

@@ -0,0 +1,30 @@
+name: Buildchain recovery
+on:
+  workflow_dispatch:
+    inputs:
+      attempt:
+        description: Exact Buildchain attempt to recover
+        required: true
+        type: string
+      runtime-ref:
+        description: Optional repaired runtime
+        required: false
+        type: string
+permissions:
+  contents: read
+jobs:
+  buildchain:
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-recover.yml@v4
+    with:
+      attempt: ${{ inputs.attempt }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+    secrets: inherit
+    permissions:
+      actions: write
+      attestations: write
+      checks: write
+      contents: write
+      discussions: write
+      id-token: write
+      pull-requests: write
+      statuses: write

package/templates/minimal-consumer/binary/.github/workflows/buildchain.yml

@@ -0,0 +1,28 @@
+name: Buildchain pipeline
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review, converted_to_draft, closed, labeled, unlabeled, edited, enqueued, dequeued]
+  pull_request_review:
+    types: [submitted, dismissed]
+  pull_request_target:
+    types: [closed]
+  merge_group:
+    types: [checks_requested]
+  push:
+  repository_dispatch:
+    types: [buildchain-attempt-wake]
+permissions:
+  contents: read
+jobs:
+  buildchain:
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-pipeline.yml@v4
+    secrets: inherit
+    permissions:
+      actions: write
+      attestations: write
+      checks: write
+      contents: write
+      discussions: write
+      id-token: write
+      pull-requests: write
+      statuses: write

package/templates/minimal-consumer/binary/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "minimal-binary",
+  "private": true,
+  "version": "1.0.0-alpha.1",
+  "type": "module"
+}

package/templates/minimal-consumer/binary/src/build.mjs

@@ -0,0 +1,5 @@
+import fs from "node:fs";
+fs.mkdirSync("dist", { recursive: true });
+import { execFileSync } from "node:child_process";
+execFileSync("cc", ["src/hello.c", "-o", "dist/hello"], { stdio: "inherit" });
+execFileSync("tar", ["-czf", "dist/hello.tar.gz", "-C", "dist", "hello"], { stdio: "inherit" });

package/templates/minimal-consumer/binary/src/hello.c

@@ -0,0 +1,2 @@
+#include <stdio.h>
+int main(void) { puts("hello"); return 0; }

package/templates/minimal-consumer/binary/src/verify.mjs

@@ -0,0 +1,3 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+assert.ok(fs.statSync("dist/hello.tar.gz").size > 0);

package/templates/minimal-consumer/npm/.buildchain/buildchain.toml

@@ -0,0 +1,46 @@
+schema = 2
+
+[[products]]
+id = "main"
+type = "npm"
+platforms = ["linux-x64"]
+build = ["node src/build.mjs"]
+verify = ["node src/verify.mjs"]
+
+[[products.artifacts]]
+id = "main"
+path = "dist/package"
+kind = "npm-package"
+
+[[products.targets]]
+provider = "npm"
+artifacts = ["main"]
+access = "public"
+
+[version]
+strategy = "semver"
+
+[[version.files]]
+path = "package.json"
+format = "json"
+key = "version"
+
+[[channels]]
+from = "feature/*"
+to = "dev/v1/v1.0"
+operation = "develop"
+
+[[channels]]
+from = "dev/v1/v1.0"
+to = "alpha/v1/v1.0"
+operation = "alpha"
+
+[[channels]]
+from = "alpha/v1/v1.0"
+to = "release/v1/v1.0"
+operation = "stable"
+
+[review]
+minimum_approvals = 1
+code_owners = true
+merge_queue = true

package/templates/minimal-consumer/npm/.github/workflows/buildchain-recover.yml

@@ -0,0 +1,30 @@
+name: Buildchain recovery
+on:
+  workflow_dispatch:
+    inputs:
+      attempt:
+        description: Exact Buildchain attempt to recover
+        required: true
+        type: string
+      runtime-ref:
+        description: Optional repaired runtime
+        required: false
+        type: string
+permissions:
+  contents: read
+jobs:
+  buildchain:
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-recover.yml@v4
+    with:
+      attempt: ${{ inputs.attempt }}
+      runtime-ref: ${{ inputs.runtime-ref }}
+    secrets: inherit
+    permissions:
+      actions: write
+      attestations: write
+      checks: write
+      contents: write
+      discussions: write
+      id-token: write
+      pull-requests: write
+      statuses: write

package/templates/minimal-consumer/npm/.github/workflows/buildchain.yml

@@ -0,0 +1,28 @@
+name: Buildchain pipeline
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review, converted_to_draft, closed, labeled, unlabeled, edited, enqueued, dequeued]
+  pull_request_review:
+    types: [submitted, dismissed]
+  pull_request_target:
+    types: [closed]
+  merge_group:
+    types: [checks_requested]
+  push:
+  repository_dispatch:
+    types: [buildchain-attempt-wake]
+permissions:
+  contents: read
+jobs:
+  buildchain:
+    uses: kungfu-systems/buildchain/.github/workflows/public-ops-pipeline.yml@v4
+    secrets: inherit
+    permissions:
+      actions: write
+      attestations: write
+      checks: write
+      contents: write
+      discussions: write
+      id-token: write
+      pull-requests: write
+      statuses: write

package/templates/minimal-consumer/npm/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "minimal-npm",
+  "private": true,
+  "version": "1.0.0-alpha.1",
+  "type": "module"
+}

package/templates/minimal-consumer/npm/src/build.mjs

@@ -0,0 +1,5 @@
+import fs from "node:fs";
+fs.mkdirSync("dist", { recursive: true });
+fs.mkdirSync("dist/package", { recursive: true });
+fs.writeFileSync("dist/package/index.js", 'export const hello = "hello";\n');
+fs.writeFileSync("dist/package/package.json", JSON.stringify({ name: "@example/minimal", version: JSON.parse(fs.readFileSync("package.json")).version, type: "module", exports: "./index.js" }));

package/templates/minimal-consumer/npm/src/verify.mjs

@@ -0,0 +1,3 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+assert.ok(fs.statSync("dist/package").isDirectory());

package/templates/minimal-consumer/paper/.buildchain/buildchain.toml

@@ -0,0 +1,45 @@
+schema = 2
+
+[[products]]
+id = "main"
+type = "paper"
+platforms = ["linux-x64"]
+build = ["node src/build.mjs"]
+verify = ["node src/verify.mjs"]
+
+[[products.artifacts]]
+id = "main"
+path = "dist/paper.pdf"
+kind = "pdf"
+
+[[products.targets]]
+provider = "github-release"
+artifacts = ["main"]
+
+[version]
+strategy = "semver"
+
+[[version.files]]
+path = "package.json"
+format = "json"
+key = "version"
+
+[[channels]]
+from = "feature/*"
+to = "dev/v1/v1.0"
+operation = "develop"
+
+[[channels]]
+from = "dev/v1/v1.0"
+to = "alpha/v1/v1.0"
+operation = "alpha"
+
+[[channels]]
+from = "alpha/v1/v1.0"
+to = "release/v1/v1.0"
+operation = "stable"
+
+[review]
+minimum_approvals = 1
+code_owners = true
+merge_queue = true