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

package/packages/core/providers/github/pipeline-version-readback.js

@@ -0,0 +1,117 @@
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineCaller } from "./pipeline-run-entry.js";
+
+export const pipelineVersionArtifactName = (context, platform) =>
+  `buildchain-version-${context.preparation.root.slice(7)}-${context.runId}-${context.runAttempt}-${platform}`;
+
+export const pipelineVersionJobName = (preparation, platform) =>
+  `Prepare version (${preparation.purpose}, ${platform})`;
+
+export async function readPipelineVersionBuild(context, host) {
+  const { preparation, runId, runAttempt, definitionSha } = context;
+  const { repository, request, runs } = host;
+  if (preparation.source.repository !== repository)
+    throw new Error("Version preparation crossed its repository boundary");
+  const { run, jobs } = await runs.read(runId, runAttempt);
+  await readPipelineCaller(
+    run,
+    preparation.source.configPath,
+    request,
+    repository,
+  );
+  const definitions = (run.referenced_workflows || []).filter((entry) =>
+    entry.path?.startsWith(
+      "kungfu-systems/buildchain/.github/workflows/.release-pipeline-products.yml@",
+    ),
+  );
+  const versionDefinitions = (run.referenced_workflows || []).filter((entry) =>
+    entry.path?.startsWith(
+      "kungfu-systems/buildchain/.github/workflows/.release-pipeline-version.yml@",
+    ),
+  );
+  if (
+    definitions.length !== 1 ||
+    definitions[0].sha !== definitionSha ||
+    versionDefinitions.length !== 1 ||
+    versionDefinitions[0].sha !== definitionSha ||
+    !/^[0-9a-f]{40}$/u.test(definitionSha || "")
+  )
+    throw new Error("Version preparation changed its exact hosted definition");
+  const selected = preparation.platforms.map((platform) => {
+    const name = pipelineVersionJobName(preparation, platform);
+    const matches = jobs.filter(
+      (job) => job.name === name || job.name.endsWith(` / ${name}`),
+    );
+    if (
+      matches.length !== 1 ||
+      matches[0].run_id !== runId ||
+      matches[0].run_attempt !== runAttempt ||
+      matches[0].status !== "completed" ||
+      matches[0].conclusion !== "success"
+    )
+      throw new Error(
+        "Version preparation requires every exact successful product job",
+      );
+    return matches[0];
+  });
+  if (
+    !selected.length ||
+    new Set(preparation.platforms).size !== selected.length
+  )
+    throw new Error(
+      "Version preparation platform inventory is empty or duplicated",
+    );
+  const inventory = await request(
+    `/repos/${repository}/actions/runs/${runId}/artifacts?per_page=100`,
+  );
+  if (
+    !Array.isArray(inventory.artifacts) ||
+    inventory.total_count !== inventory.artifacts.length ||
+    inventory.total_count > 100
+  )
+    throw new Error("Version preparation artifact inventory is incomplete");
+  const assets = preparation.platforms.map((platform) => {
+    const matches = inventory.artifacts.filter(
+      (asset) => asset.name === pipelineVersionArtifactName(context, platform),
+    );
+    if (
+      matches.length !== 1 ||
+      !Number.isSafeInteger(matches[0].id) ||
+      matches[0].id < 1 ||
+      matches[0].expired ||
+      matches[0].workflow_run?.id !== runId ||
+      matches[0].workflow_run?.head_sha !== run.head_sha ||
+      !/^sha256:[0-9a-f]{64}$/u.test(matches[0].digest || "")
+    )
+      throw new Error(
+        "Version preparation has no unique immutable platform artifact",
+      );
+    return matches[0];
+  });
+  const again = await runs.read(runId, runAttempt);
+  if (
+    again.run.head_sha !== run.head_sha ||
+    recordDigest(again.run.referenced_workflows) !==
+      recordDigest(run.referenced_workflows) ||
+    selected.some(
+      (job) =>
+        !again.jobs.some((value) => recordDigest(value) === recordDigest(job)),
+    )
+  )
+    throw new Error(
+      "Version preparation producer changed during independent readback",
+    );
+  const body = {
+    schema: "buildchain.pipeline-version-build-readback/v1",
+    preparationRoot: preparation.root,
+    source: preparation.source,
+    runtime: preparation.runtime,
+    runId,
+    runAttempt,
+    definitionSha,
+    providerSource: run.head_sha,
+    jobs: selected,
+    artifacts: assets.map(({ id, digest }) => ({ id, digest })),
+  };
+  return { build: { ...body, root: recordDigest(body) }, assets };
+}

package/packages/core/providers/github/pipeline-version.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { readPipelineVersion } from "../../publication/pipeline/version.js";
+import { preparedPipelineVersionMaterial } from "../../publication/pipeline/version-material.js";
+import { verifyPipelinePublicationPlan } from "../../publication/pipeline/plan.js";
+
+function blobBytes(value, sha) {
+  if (
+    value.encoding !== "base64" ||
+    value.size > 4 * 1024 * 1024 ||
+    typeof value.content !== "string"
+  )
+    throw new Error("Version material requires a bounded Git blob");
+  const bytes = Buffer.from(value.content, "base64");
+  const digest = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (bytes.length !== value.size || digest !== sha || value.sha !== sha)
+    throw new Error("Version material blob identity drift");
+  return bytes.toString("utf8");
+}
+
+export function githubPipelineVersion(request, repository) {
+  const base = `/repos/${repository}`;
+  const post = (url, body) => request(url, { method: "POST", body });
+  async function inspect(source, policy) {
+    if (source.repository !== repository)
+      throw new Error("Version material repository mismatch");
+    const commit = await request(`${base}/git/commits/${source.commit}`);
+    if (commit.sha !== source.commit || commit.tree?.sha !== source.tree)
+      throw new Error("Version material source tree drift");
+    const tree = await request(`${base}/git/trees/${source.tree}?recursive=1`);
+    if (tree.truncated || tree.sha !== source.tree || !Array.isArray(tree.tree))
+      throw new Error("Version material requires a complete source tree");
+    const files = {},
+      entries = {};
+    for (const file of [
+      ...policy.files,
+      ...(policy.derived_files || []).map((path) => ({ path })),
+    ]) {
+      if (Object.hasOwn(files, file.path)) continue;
+      const found = tree.tree.filter((entry) => entry.path === file.path);
+      if (
+        found.length !== 1 ||
+        found[0].type !== "blob" ||
+        !["100644", "100755"].includes(found[0].mode)
+      )
+        throw new Error("Version material must be a tracked regular file");
+      const entry = found[0];
+      entries[file.path] = entry;
+      files[file.path] = blobBytes(
+        await request(`${base}/git/blobs/${entry.sha}`),
+        entry.sha,
+      );
+    }
+    return {
+      commit,
+      files,
+      entries,
+      version: readPipelineVersion(policy, files),
+      sourceTimestamp: commit.committer.date,
+    };
+  }
+  async function materialize(plan, regeneration) {
+    verifyPipelinePublicationPlan(plan);
+    const input = await inspect(plan.source, plan.versionPolicy);
+    if (input.version !== plan.candidateVersion)
+      throw new Error("Version material changed after planning");
+    const material = preparedPipelineVersionMaterial(
+      plan,
+      input.files,
+      regeneration,
+    );
+    let source = plan.source;
+    if (material.changes.length)
+      source = await createMaterializedSource(plan, input, material);
+    const body = {
+      schema: "buildchain.pipeline-version-materialization/v1",
+      planRoot: plan.root,
+      protectedSource: plan.source,
+      source,
+      material,
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  async function materializeDevelopment(plan, regeneration) {
+    const input = await inspect(plan.source, plan.versionPolicy);
+    const material = preparedPipelineVersionMaterial(
+      plan,
+      input.files,
+      regeneration,
+    );
+    const branch = `feature/buildchain-next/${plan.root.slice(7)}`;
+    const source = material.changes.length
+      ? await createMaterializedSource(plan, input, material, `heads/${branch}`)
+      : plan.source;
+    const body = {
+      schema: "buildchain.pipeline-development-materialization/v1",
+      transitionRoot: plan.root,
+      protectedSource: plan.source,
+      source,
+      branch,
+      material,
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  async function createMaterializedSource(plan, input, material, targetRef) {
+    const changes = material.changes.map(({ path, content }) => ({
+      path,
+      content,
+      mode: input.entries[path].mode,
+      type: "blob",
+    }));
+    const tree = await post(`${base}/git/trees`, {
+      base_tree: plan.source.tree,
+      tree: changes,
+    });
+    const identity = {
+      name: "Buildchain automation",
+      email: "noreply@github.com",
+      date: plan.sourceTimestamp,
+    };
+    const parents = [plan.source.commit];
+    // Preserve the prior published version overlay as real Git ancestry. The
+    // resulting tree still changes only the current protected version fields;
+    // no provider force-update is needed for the next stable floating channel.
+    if (
+      plan.previousChannelCommit &&
+      plan.previousChannelCommit !== plan.source.commit
+    ) {
+      if (!/^[0-9a-f]{40}$/u.test(plan.previousChannelCommit))
+        throw new Error(
+          "Version overlay parent must be an exact prior channel commit",
+        );
+      const previous = await request(
+        `${base}/git/commits/${plan.previousChannelCommit}`,
+      );
+      if (previous.sha !== plan.previousChannelCommit)
+        throw new Error("Prior version overlay commit changed");
+      parents.push(previous.sha);
+    }
+    const created = await post(`${base}/git/commits`, {
+      message: `chore(release): materialize ${plan.version}\n\nBuildchain-Plan: ${plan.root}\nSigned-off-by: Buildchain automation <noreply@github.com>`,
+      tree: tree.sha,
+      parents,
+      author: identity,
+      committer: identity,
+    });
+    const commit = await request(`${base}/git/commits/${created.sha}`);
+    if (
+      commit.tree?.sha !== tree.sha ||
+      recordDigest(commit.parents?.map(({ sha }) => sha)) !==
+        recordDigest(parents)
+    )
+      throw new Error("Materialized version commit readback mismatch");
+    const source = { ...plan.source, commit: commit.sha, tree: tree.sha };
+    const verified = await inspect(source, plan.versionPolicy);
+    if (verified.version !== plan.version)
+      throw new Error("Version material did not retain the planned version");
+    const expectedFiles = {
+      ...input.files,
+      ...Object.fromEntries(
+        material.changes.map(({ path, content }) => [path, content]),
+      ),
+    };
+    if (recordDigest(verified.files) !== recordDigest(expectedFiles))
+      throw new Error(
+        "Version material changed document bytes beyond the planned fields",
+      );
+    const comparison = await request(
+      `${base}/compare/${plan.source.commit}...${commit.sha}`,
+    );
+    const paths = comparison.files?.map((file) => file.filename).sort();
+    if (
+      comparison.status !== "ahead" ||
+      (parents.length === 1 && comparison.total_commits !== 1) ||
+      recordDigest(paths) !==
+        recordDigest(material.changes.map(({ path }) => path).sort()) ||
+      comparison.files.some((file) => file.status !== "modified")
+    )
+      throw new Error(
+        "Version material changed paths outside the declared version fields",
+      );
+    const ref =
+      targetRef || `heads/buildchain/publication-source/${plan.root.slice(7)}`;
+    try {
+      await post(`${base}/git/refs`, { ref: `refs/${ref}`, sha: commit.sha });
+    } catch (error) {
+      const observed = await request(`${base}/git/ref/${ref}`);
+      if (observed.object?.sha !== commit.sha) throw error;
+    }
+    const observed = await request(`${base}/git/ref/${ref}`);
+    if (observed.object?.sha !== commit.sha)
+      throw new Error("Version material ref readback mismatch");
+    return source;
+  }
+  return { inspect, materialize, materializeDevelopment };
+}

package/packages/core/providers/github/pipeline-worker.js

@@ -0,0 +1,108 @@
+import { object } from "../../consumer/contract/shape.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export const PIPELINE_WORKER = "buildchain.pipeline-worker/v1";
+
+export function validatePipelineWorker(binding, current, warrant) {
+  object(binding, [
+    "schema",
+    "repository",
+    "attempt",
+    "generation",
+    "sourceHead",
+    "candidateId",
+    "fencingToken",
+    "leaseGeneration",
+    "runId",
+    "runAttempt",
+    "nativeJobId",
+    "sealJobId",
+  ]);
+  if (
+    binding.schema !== PIPELINE_WORKER ||
+    binding.repository !== current.intent.repository ||
+    binding.attempt !== current.identity.id ||
+    binding.generation !== current.generation.id ||
+    binding.sourceHead !== current.generation.source.commit ||
+    binding.candidateId !== warrant.candidateId ||
+    binding.fencingToken !== warrant.fencingToken ||
+    binding.leaseGeneration !== warrant.generation
+  )
+    throw new Error("Native worker does not bind the active pipeline Warrant");
+  for (const key of [
+    "runId",
+    "runAttempt",
+    "nativeJobId",
+    "sealJobId",
+    "leaseGeneration",
+  ])
+    if (!Number.isSafeInteger(binding[key]) || binding[key] < 1)
+      throw new Error("Native worker provider identity is invalid");
+  if (binding.nativeJobId === binding.sealJobId)
+    throw new Error("Native execution and evidence seal must be separate jobs");
+  return binding;
+}
+
+export function githubPipelineWorker(request) {
+  async function jobs(base, binding) {
+    const result = [];
+    for (let page = 1; page <= 100; page++) {
+      const response = await request(
+        `${base}/actions/runs/${binding.runId}/attempts/${binding.runAttempt}/jobs?per_page=100&page=${page}`,
+      );
+      if (!Array.isArray(response.jobs))
+        throw new Error("Missing provider jobs readback");
+      result.push(...response.jobs);
+      if (response.jobs.length < 100) return result;
+    }
+    throw new Error("Pipeline worker jobs exceed the readback bound");
+  }
+  async function observe(binding, current, warrant) {
+    validatePipelineWorker(binding, current, warrant);
+    const base = `/repos/${binding.repository}`;
+    const run = await request(`${base}/actions/runs/${binding.runId}`);
+    if (
+      run.id !== binding.runId ||
+      run.run_attempt !== binding.runAttempt ||
+      run.repository?.full_name !== binding.repository
+    )
+      throw new Error(
+        "Native worker provider run changed; terminality is unproved",
+      );
+    const entries = await jobs(base, binding);
+    const selected = [binding.nativeJobId, binding.sealJobId].map((id) => {
+      const matches = entries.filter((job) => job.id === id);
+      if (
+        matches.length !== 1 ||
+        matches[0].run_id !== binding.runId ||
+        matches[0].run_attempt !== binding.runAttempt
+      )
+        throw new Error("Native worker exact job identity drift");
+      return matches[0];
+    });
+    const again = await request(`${base}/actions/runs/${binding.runId}`);
+    if (
+      again.id !== run.id ||
+      again.run_attempt !== run.run_attempt ||
+      again.status !== run.status ||
+      again.conclusion !== run.conclusion
+    )
+      throw new Error("Native worker changed during terminal readback");
+    const terminal =
+      run.status === "completed" &&
+      Boolean(run.conclusion) &&
+      selected.every(
+        (job) =>
+          job.status === "completed" && job.conclusion && job.completed_at,
+      );
+    const body = {
+      schema: "buildchain.pipeline-worker-readback/v1",
+      binding,
+      status: terminal ? "completed" : "in_progress",
+      run,
+      jobs: selected,
+    };
+    return { ...body, root: recordDigest(body) };
+  }
+  return { observe };
+}

package/packages/core/publication/candidate/registry-hydration.js

@@ -1,3 +1,4 @@
+import { readNpmPackResult } from "../npm/pack-result.js";
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -117,7 +118,7 @@ export function hydratePublishedPublicationRegistry({
   for (const version of publishedVersions) {
     const packageDir = path.join(resolvedOutputDir, `.package-${version}`);
     fs.mkdirSync(packageDir, { recursive: true });
-    const packed = JSON.parse(
+    const pack = readNpmPackResult(
       commandRunner(
         "npm",
         [
@@ -132,7 +133,6 @@ export function hydratePublishedPublicationRegistry({
         { cwd: resolvedCwd },
       ),
     );
-    const pack = Array.isArray(packed) ? packed[0] : packed;
     if (!pack?.filename || !pack?.integrity) {
       throw new Error(
         `npm pack did not report filename and integrity for ${packageName}@${version}`,

package/packages/core/publication/npm/pack-preview.js

@@ -1,6 +1,6 @@
+import { readNpmPackResult } from "./pack-result.js";
 export function summarizePackPreview(stdout) {
-  const parsed = JSON.parse(stdout);
-  const pack = Array.isArray(parsed) ? parsed[0] : parsed;
+  const pack = readNpmPackResult(stdout);
   const files = Array.isArray(pack?.files) ? pack.files : [];
   const bin = files.find((file) => file.path === "bin/buildchain.mjs");
   const fileEntries = files.map((file) => ({

package/packages/core/publication/npm/pack-result.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+
+export function readNpmPackResult(stdout) {
+  const parsed = JSON.parse(stdout);
+  const entries = Array.isArray(parsed)
+    ? parsed
+    : typeof parsed?.name === "string"
+      ? [parsed]
+      : parsed && typeof parsed === "object"
+        ? Object.values(parsed)
+        : [];
+  if (entries.length !== 1)
+    throw new Error("npm pack must return exactly one package");
+  const pack = entries[0];
+  if (
+    typeof pack?.name !== "string" ||
+    !pack.name ||
+    typeof pack?.version !== "string" ||
+    !pack.version
+  ) {
+    throw new Error("npm pack did not return package name and version");
+  }
+  if (
+    typeof pack.filename !== "string" ||
+    !pack.filename.endsWith(".tgz") ||
+    /[/\\]/u.test(pack.filename) ||
+    path.basename(pack.filename) !== pack.filename
+  )
+    throw new Error("npm pack must return a local tarball filename");
+  return pack;
+}

package/packages/core/publication/npm/package.js

@@ -1,3 +1,4 @@
+import { readNpmPackResult } from "./pack-result.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
@@ -11,12 +12,8 @@ export function readPackageJson(cwd) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
-function parsePackResult(stdout) {
-  const parsed = JSON.parse(stdout);
-  const pack = Array.isArray(parsed) ? parsed[0] : parsed;
-  if (!pack?.name || !pack?.version) {
-    throw new Error("npm pack did not return package name and version");
-  }
+export function parsePackResult(stdout) {
+  const pack = readNpmPackResult(stdout);
   return {
     name: pack.name,
     version: pack.version,

package/packages/core/publication/npm/pipeline-channel.js

@@ -0,0 +1,87 @@
+const REGISTRY = "https://registry.npmjs.org";
+
+export function pipelineNpmChannel({
+  environment = process.env,
+  fetchImpl = globalThis.fetch,
+}) {
+  async function json(url, options = {}) {
+    const response = await fetchImpl(url, { ...options, redirect: "error" });
+    if (!response.ok)
+      throw new Error(
+        `npm channel provider rejected the operation with HTTP ${response.status}`,
+      );
+    return response.json();
+  }
+  async function credential(name) {
+    if (environment.NODE_AUTH_TOKEN) return environment.NODE_AUTH_TOKEN;
+    if (
+      !environment.ACTIONS_ID_TOKEN_REQUEST_URL ||
+      !environment.ACTIONS_ID_TOKEN_REQUEST_TOKEN
+    )
+      throw new Error(
+        "npm channel publication requires its hosted package-scoped OIDC or configured publisher credential",
+      );
+    const url = new URL(environment.ACTIONS_ID_TOKEN_REQUEST_URL);
+    if (url.protocol !== "https:")
+      throw new Error("OIDC request requires the provider HTTPS endpoint");
+    url.searchParams.set("audience", "npm:registry.npmjs.org");
+    const identity = await json(url.href, {
+      headers: {
+        authorization: `Bearer ${environment.ACTIONS_ID_TOKEN_REQUEST_TOKEN}`,
+        accept: "application/json",
+      },
+    });
+    if (typeof identity.value !== "string" || !identity.value)
+      throw new Error("Hosted OIDC provider omitted its identity token");
+    const exchange = await json(
+      `${REGISTRY}/-/npm/v1/oidc/token/exchange/package/${encodeURIComponent(name)}`,
+      {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${identity.value}`,
+          accept: "application/json",
+        },
+      },
+    );
+    if (typeof exchange.token !== "string" || !exchange.token)
+      throw new Error(
+        "npm OIDC exchange omitted its package-scoped credential",
+      );
+    return exchange.token;
+  }
+  return {
+    async observe(effect) {
+      if (effect.access === "restricted" && !environment.NODE_AUTH_TOKEN)
+        throw new Error(
+          "Restricted npm readback requires a configured package read credential",
+        );
+      const headers = environment.NODE_AUTH_TOKEN
+        ? { authorization: `Bearer ${environment.NODE_AUTH_TOKEN}` }
+        : {};
+      const tags = await json(
+        `${REGISTRY}/-/package/${encodeURIComponent(effect.name)}/dist-tags`,
+        { headers },
+      );
+      const version = tags[effect.tag] || null;
+      if (version !== null && typeof version !== "string")
+        throw new Error("npm channel has no exact version");
+      return version
+        ? { state: "present", version }
+        : { state: "absent", version: null };
+    },
+    async apply(effect) {
+      const token = await credential(effect.name);
+      await json(
+        `${REGISTRY}/-/package/${encodeURIComponent(effect.name)}/dist-tags/${encodeURIComponent(effect.tag)}`,
+        {
+          method: "PUT",
+          headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(effect.version),
+        },
+      );
+    },
+  };
+}