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

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/providers/github/release-evidence-assets.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+const LIMIT = 8 * 1024 * 1024;
+
+async function inventory(request, prefix) {
+  const assets = [],
+    ids = new Set(),
+    names = new Set();
+  for (let page = 1; page <= 20; page++) {
+    const values = await request(`${prefix}/assets?per_page=100&page=${page}`);
+    if (!Array.isArray(values) || values.length > 100)
+      throw new Error("Published evidence asset inventory is incomplete");
+    for (const value of values) {
+      if (
+        !Number.isSafeInteger(value.id) ||
+        value.id < 1 ||
+        typeof value.name !== "string" ||
+        !value.name ||
+        ids.has(value.id) ||
+        names.has(value.name)
+      )
+        throw new Error("Published evidence asset inventory is ambiguous");
+      ids.add(value.id);
+      names.add(value.name);
+      assets.push(value);
+    }
+    if (values.length < 100) return assets;
+  }
+  throw new Error(
+    "Published evidence inventory exceeds its complete-read bound",
+  );
+}
+
+function selectedAssets(assets, names) {
+  return names.map((name) => {
+    const asset = assets.find((value) => value.name === name);
+    if (!asset) return { name, missing: true };
+    if (
+      asset.state !== "uploaded" ||
+      !Number.isSafeInteger(asset.size) ||
+      asset.size < 1 ||
+      asset.size > LIMIT ||
+      !/^sha256:[0-9a-f]{64}$/u.test(asset.digest || "")
+    )
+      throw new Error("Published evidence asset lacks bounded immutable bytes");
+    return { id: asset.id, name, size: asset.size, digest: asset.digest };
+  });
+}
+
+// Download only fixed evidence names from the exact already-observed release.
+// There is no caller-supplied URL, artifact selector or provider write here.
+export async function readReleaseEvidenceAssets(host, candidate, names) {
+  const repository = host.repository;
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(repository || "") ||
+    !Number.isSafeInteger(candidate.id) ||
+    candidate.id < 1
+  )
+    throw new Error("Published evidence requires exact release coordinates");
+  const prefix = `/repos/${repository}/releases/${candidate.id}`;
+  const selected = selectedAssets(await inventory(host.request, prefix), names);
+  const missing = selected
+    .filter((value) => value.missing)
+    .map(({ name }) => name);
+  if (missing.length) return { status: "missing", missing };
+  const [owner, repo] = repository.split("/");
+  const values = {};
+  for (const asset of selected) {
+    const result = await host.github.rest.repos.getReleaseAsset({
+      owner,
+      repo,
+      asset_id: asset.id,
+      headers: { accept: "application/octet-stream" },
+    });
+    const bytes = Buffer.from(result.data);
+    if (
+      bytes.length !== asset.size ||
+      bytes.length > LIMIT ||
+      `sha256:${createHash("sha256").update(bytes).digest("hex")}` !==
+        asset.digest
+    )
+      throw new Error(
+        "Published evidence download differs from provider bytes",
+      );
+    values[asset.name] = bytes;
+  }
+  if (
+    recordDigest(
+      selectedAssets(await inventory(host.request, prefix), names),
+    ) !== recordDigest(selected)
+  )
+    throw new Error(
+      "Published evidence assets changed during provider readback",
+    );
+  return { status: "present", values, assets: selected };
+}

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,36 @@
+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();
+  }
+  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 };
+    },
+  };
+}

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

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { publishedDigest, runNpm } from "./registry.js";
+import { createNativeChildEnvironment } from "../../dev-delivery/native/execution.js";
+import {
+  publicationFile,
+  publicationPath,
+  writeImmutablePublicationFile,
+} from "../pipeline/files.js";
+
+function publicationFailureCode(result) {
+  const code = stripVTControlCharacters(String(result.stderr ?? "")).match(
+    /^npm (?:error|ERR!) code ([A-Z0-9_]+)\r?$/m,
+  )?.[1];
+  return [
+    "ENEEDAUTH",
+    "EOTP",
+    "E401",
+    "E403",
+    "E404",
+    "EPUBLISHCONFLICT",
+    "EPRIVATE",
+    "EINTEGRITY",
+    "EUSAGE",
+    "EINVALIDPACKAGENAME",
+    "ETARGET",
+    "ENOENT",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "EAI_AGAIN",
+    "ENETUNREACH",
+    "ENOTFOUND",
+  ].includes(code)
+    ? code
+    : "unclassified";
+}
+
+export function pipelineNpmEnvironment(directory, environment = process.env) {
+  const cwd = path.resolve(directory);
+  const config = path.join(cwd, ".buildchain-publisher.npmrc");
+  fs.mkdirSync(cwd, { recursive: true });
+  writeImmutablePublicationFile(
+    config,
+    environment.NODE_AUTH_TOKEN
+      ? "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n"
+      : "",
+  );
+  const env = {
+    ...createNativeChildEnvironment(environment),
+    NPM_CONFIG_USERCONFIG: config,
+    NPM_CONFIG_REGISTRY: "https://registry.npmjs.org/",
+    NPM_CONFIG_IGNORE_SCRIPTS: "true",
+  };
+  for (const key of [
+    "ACTIONS_ID_TOKEN_REQUEST_URL",
+    "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    "NODE_AUTH_TOKEN",
+    "GITHUB_ACTIONS",
+  ])
+    if (environment[key]) env[key] = environment[key];
+  return env;
+}
+
+export function pipelineNpmProvider({
+  directory,
+  artifacts,
+  environment = process.env,
+  run = runNpm,
+  lookup = publishedDigest,
+}) {
+  const cwd = path.resolve(directory);
+  const env = pipelineNpmEnvironment(directory, environment);
+  const registry = "https://registry.npmjs.org/";
+  const args = { cwd, env, registry };
+  function artifactFor(effect) {
+    const found = artifacts.filter(
+      (artifact) => artifact.id === effect.product,
+    );
+    if (
+      found.length !== 1 ||
+      found[0].package?.name !== effect.name ||
+      found[0].package?.version !== effect.version ||
+      found[0].package?.integrity !== effect.integrity
+    )
+      throw new Error("npm publication changed qualified package identity");
+    const artifact = found[0];
+    const file = publicationPath(cwd, artifact.file);
+    const bytes = publicationFile(file);
+    if (
+      bytes.integrity !== effect.integrity ||
+      bytes.digest !== artifact.digest
+    )
+      throw new Error("npm publication bytes changed after qualification");
+    return file;
+  }
+  return {
+    async observe(effect) {
+      artifactFor(effect);
+      if (effect.access === "restricted" && !env.NODE_AUTH_TOKEN)
+        throw new Error(
+          "Restricted npm readback requires a configured package read credential",
+        );
+      const integrity = lookup({
+        ...args,
+        name: effect.name,
+        version: effect.version,
+      });
+      return integrity ? { state: "present", integrity } : { state: "absent" };
+    },
+    matches: (effect, observed) =>
+      observed.state === "present" && observed.integrity === effect.integrity,
+    async apply(effect) {
+      const file = artifactFor(effect);
+      const result = run({
+        cwd,
+        env,
+        args: [
+          "publish",
+          file,
+          "--ignore-scripts",
+          "--provenance=false",
+          "--access",
+          effect.access,
+          "--tag",
+          effect.tag,
+          `--registry=${registry}`,
+        ],
+        allowFailure: true,
+      });
+      if (result.status !== 0)
+        throw new Error(
+          `Sealed npm publication failed with exit ${result.status} (npm code ${publicationFailureCode(result)})`,
+        );
+    },
+  };
+}