@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.3

package/scripts/check-pipeline-publication-topology.mjs

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { inspectWorkflowJob } from "./workflow-action-graph.mjs";
+
+export function assertPipelinePublicationTopology(
+  ledger,
+  discoverReleaseTopology,
+  root,
+) {
+  const pipeline = ledger.pipelinePublicationScope;
+  assert.deepEqual(pipeline.workflowPaths, [
+    ".github/workflows/.release-pipeline-products.yml",
+    ".github/workflows/public-ops-pipeline.yml",
+    ".github/workflows/public-ops-recover.yml",
+    ".github/workflows/.ops-pipeline-execute.yml",
+    ".github/workflows/.release-pipeline-version.yml",
+  ]);
+  const pipelineTopology = discoverReleaseTopology(
+    pipeline.workflowPaths,
+    pipeline.workflowPaths,
+  );
+  assert.deepEqual(pipeline.observedTopology, pipelineTopology);
+  for (const [name, ceiling] of Object.entries(pipeline.maximumMetrics))
+    assert.ok(
+      pipelineTopology.metrics[name] <= ceiling,
+      `pipeline publication exceeds ${name}`,
+    );
+  for (const [job, module] of [
+    ["qualify", "packages/core/publication/pipeline/qualify.js"],
+    ["apply", "packages/core/publication/pipeline/apply.js"],
+    ["settle", "packages/core/publication/pipeline/settle.js"],
+  ])
+    assert.ok(
+      inspectWorkflowJob(pipeline.workflowPaths[0], job, root).modules.has(
+        module,
+      ),
+    );
+  const version = ".github/workflows/.release-pipeline-version.yml";
+  assert.ok(
+    inspectWorkflowJob(version, "build", root).modules.has(
+      "packages/core/publication/pipeline/version-build.js",
+    ),
+  );
+  assert.ok(
+    inspectWorkflowJob(version, "materialize", root).modules.has(
+      "packages/core/publication/pipeline/version-context.js",
+    ),
+  );
+}

package/scripts/check-release-topology.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import assert from "node:assert/strict";
+import { assertPipelinePublicationTopology } from "./check-pipeline-publication-topology.mjs";
 import { inspectWorkflowJob, readWorkflow } from "./workflow-action-graph.mjs";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -28,6 +29,8 @@ const PRIVILEGED_ENTRYPOINTS = [
   "packages/core/release/next-development/actions.js",
   "packages/core/publication/oci/preview-actions.js",
   "packages/core/publication/settlement/actions.js",
+  "packages/core/publication/pipeline/actions.js",
+  "packages/core/publication/pipeline/version-actions.js",
 ];
 
 export function localModuleSpecifiers(source) {
@@ -150,7 +153,9 @@ export function discoverReleaseAuthorityClosure() {
     [".js", ".mjs", ".cjs"],
     /(?:release-tail-provider-(?:adapters|plane)|create(?:GitHubReleaseAssets|SignedStaticChannel|SiteReleaseActivation|ReleasedEvidence)Adapter)/u,
   );
-  const runtimeSelectors = productionFiles("packages/core/runtime/entry", [".js"]).sort();
+  const runtimeSelectors = productionFiles("packages/core/runtime/entry", [
+    ".js",
+  ]).sort();
   const terminalProjections = matchingProductionFiles(
     [".github/workflows", "actions", "packages/core", "scripts"],
     [".yml", ".yaml", ".js", ".mjs", ".cjs"],
@@ -523,6 +528,7 @@ export function checkReleaseTopology() {
   assert.equal(ledger.contract, "kungfu-buildchain-v4-release-topology/v1");
   assertClosedWorld(ledger.closedWorld.workflowPaths);
   assertAuthorityClosure(ledger);
+  assertPipelinePublicationTopology(ledger, discoverReleaseTopology, root);
   const preview = ledger.postPublicationScope;
   assert.deepEqual(preview.workflowPaths, [
     ".github/workflows/public-release-oci-compose-preview.yml",

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: "contract-defined; execution-entry-not-yet-published",
+      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/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-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

package/templates/minimal-consumer/paper/.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/paper/.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