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

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

@@ -0,0 +1,178 @@
+import { bindConsumerSource } from "../../consumer/contract/identity.js";
+import { normalInputs } from "../../consumer/contract/entries.js";
+import { channelRoute } from "../../workflow/pipeline/events.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import { validateGeneration } from "../../workflow/attempt/identity.js";
+
+function exactSha(value) {
+  if (!/^[0-9a-f]{40}$/u.test(value || ""))
+    throw new Error("Pipeline source requires an exact Git commit");
+  return value;
+}
+
+function pullRequestBinding(pr) {
+  return {
+    number: pr.number,
+    state: pr.state,
+    merged: pr.merged,
+    mergeCommit: pr.merge_commit_sha,
+    head: pr.head,
+    base: pr.base,
+    draft: pr.draft,
+    labels: pr.labels,
+    updatedAt: pr.updated_at,
+  };
+}
+
+export function githubPipelineSource(request, repository) {
+  if (!/^[\w.-]+\/[\w.-]+$/u.test(repository || ""))
+    throw new Error("Invalid pipeline repository");
+  const base = `/repos/${repository}`;
+  async function source(commitInput, configPath) {
+    const commit = exactSha(commitInput);
+    const git = await request(`${base}/git/commits/${commit}`);
+    const config = await request(
+      `${base}/contents/${configPath}?ref=${commit}`,
+    );
+    if (
+      config.type !== "file" ||
+      config.encoding !== "base64" ||
+      !Number.isSafeInteger(config.size) ||
+      config.size < 1 ||
+      config.size > 256_000 ||
+      typeof config.content !== "string" ||
+      config.content.length > 512_000
+    )
+      throw new Error("Pipeline TOML is missing or exceeds its byte bound");
+    const bytes = Buffer.from(config.content, "base64");
+    if (bytes.length !== config.size)
+      throw new Error("Pipeline TOML size drift");
+    return bindConsumerSource(
+      {
+        repository,
+        commit,
+        tree: exactSha(git.tree?.sha),
+        configPath,
+        configBlob: config.sha,
+      },
+      bytes,
+    );
+  }
+  async function branchHead(branch) {
+    if (
+      !/^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u.test(
+        branch || "",
+      ) ||
+      branch.includes("..")
+    )
+      throw new Error("Invalid protected branch");
+    const pointer = await request(`${base}/git/ref/heads/${branch}`);
+    if (pointer.object?.type !== "commit")
+      throw new Error("Protected ref is not a commit");
+    return exactSha(pointer.object.sha);
+  }
+  async function observe(pullRequest, inputs = {}) {
+    if (!Number.isSafeInteger(pullRequest) || pullRequest < 1)
+      throw new Error("Pipeline requires an exact PR number");
+    const { configPath } = normalInputs(inputs);
+    const pr = await request(`${base}/pulls/${pullRequest}`);
+    const repositoryInfo = await request(base);
+    if (pr.number !== pullRequest || !repositoryInfo.node_id)
+      throw new Error("Pipeline PR provider identity drift");
+    // Read delivery policy from the protected base. A PR may change its own
+    // product commands, but cannot lower review or grant itself a channel route.
+    const baseCommit = await branchHead(pr.base?.ref);
+    const protectedSource = await source(baseCommit, configPath);
+    const route = channelRoute(protectedSource.plan, pr, repository);
+    if (!route) {
+      if (baseCommit !== (await branchHead(pr.base.ref)))
+        throw new Error("Protected policy changed during route observation");
+      return { eligible: false, reason: "channel-not-enabled" };
+    }
+    const admitted = await source(pr.head.sha, configPath);
+    const again = await request(`${base}/pulls/${pullRequest}`);
+    if (
+      recordDigest(pullRequestBinding(pr)) !==
+        recordDigest(pullRequestBinding(again)) ||
+      baseCommit !== (await branchHead(pr.base.ref))
+    )
+      throw new Error("Pipeline source changed during observation; reobserve");
+    return {
+      eligible: true,
+      repositoryId: repositoryInfo.node_id,
+      route,
+      plan: admitted.plan,
+      protectedPlan: protectedSource.plan,
+      protectedSource: protectedSource.identity,
+      live: {
+        pullRequest,
+        observedHead: pr.head.sha,
+        targetBranch: pr.base.ref,
+        routeEnabled: true,
+        source: admitted.identity,
+        baseCommit,
+        state: pr.state,
+        merged: pr.merged === true,
+        mergeCommit: pr.merge_commit_sha,
+        draft: pr.draft === true,
+        ready: pr.labels.some((label) => label.name === "ready"),
+      },
+    };
+  }
+  async function observeIntent(intent, generation, inputs = {}) {
+    validateGeneration(generation, intent);
+    if (intent.repository !== repository)
+      throw new Error("Recorded intent repository drift");
+    const number = intent.source.pullRequest;
+    const pr = await request(`${base}/pulls/${number}`);
+    const repositoryInfo = await request(base);
+    if (
+      repositoryInfo.node_id !== intent.source.repositoryId ||
+      pr.number !== number ||
+      pr.base?.repo?.full_name !== repository
+    )
+      throw new Error("Recorded pipeline intent provider identity drift");
+    const sameHead =
+      pr.head?.repo?.full_name === repository &&
+      pr.head.sha === generation.source.commit;
+    const live = {
+      pullRequest: number,
+      observedHead: exactSha(pr.head?.sha),
+      targetBranch: pr.base.ref,
+      state: pr.state,
+      merged: pr.merged === true,
+      mergeCommit: pr.merge_commit_sha,
+      source: sameHead ? generation.source : null,
+      baseCommit: null,
+      ready: pr.labels.some((label) => label.name === "ready"),
+      draft: pr.draft === true,
+    };
+    // Closing, updating or retargeting an admitted PR must remain recoverable
+    // even when its new TOML is invalid, its old route disappeared or it is now a fork.
+    if (
+      pr.state !== "open" ||
+      !sameHead ||
+      pr.base.ref !== intent.source.targetBranch
+    ) {
+      const again = await request(`${base}/pulls/${number}`);
+      if (
+        recordDigest(pullRequestBinding(pr)) !==
+        recordDigest(pullRequestBinding(again))
+      )
+        throw new Error("Recorded intent changed during terminal observation");
+      return { eligible: true, cleanupOnly: true, live };
+    }
+    const observed = await observe(number, inputs);
+    if (observed.eligible) return observed;
+    return {
+      eligible: true,
+      cleanupOnly: true,
+      live: {
+        ...live,
+        baseCommit: await branchHead(intent.source.targetBranch),
+        routeEnabled: false,
+      },
+    };
+  }
+  return { observe, observeIntent, source, branchHead };
+}

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

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { recordDigest } from "../../release/discussion/envelope.js";
+import {
+  materializePipelineVersion,
+  readPipelineVersion,
+} from "../../publication/pipeline/version.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) {
+    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 = materializePipelineVersion(
+      plan.versionPolicy,
+      input.files,
+      plan.version,
+    );
+    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) {
+    const input = await inspect(plan.source, plan.versionPolicy);
+    const material = materializePipelineVersion(
+      plan.versionPolicy,
+      input.files,
+      plan.version,
+    );
+    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),
+        },
+      );
+    },
+  };
+}