@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/paper/publication/envelope.js

@@ -0,0 +1,118 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { readPublishedPaper } from "./readback.js";
+import { requirePaperReleasePassport } from "../publication-controller.js";
+
+export async function sealReleaseEnvelope(publication) {
+  await readPublishedPaper(publication);
+  requirePaperReleasePassport(
+    JSON.parse(fs.readFileSync(publication.passportPath, "utf8")),
+    {
+      repository: publication.repository,
+      sourceSha: publication.sourceSha,
+      tag: publication.releaseTag,
+    },
+  );
+  const sha256File = (file) =>
+    crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  const canonicalPublicationFile = (name) => {
+    const file = path.join(
+      publication.workspace,
+      ".buildchain/admitted/artifact/.buildchain/publication",
+      name,
+    );
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+      throw new Error(`canonical publication file is missing: ${file}`);
+    }
+    return file;
+  };
+  const packageFact = JSON.parse(
+    fs.readFileSync(
+      path.join(publication.workspace, ".buildchain/published-package.json"),
+      "utf8",
+    ),
+  );
+  if (packageFact.version !== publication.packageVersion)
+    throw new Error("npm version readback mismatch");
+  const packageIntegrity = packageFact.dist?.integrity;
+  if (!packageIntegrity?.startsWith("sha512-"))
+    throw new Error("npm integrity readback is missing");
+  if (packageFact.gitHead !== publication.sourceSha)
+    throw new Error("npm gitHead readback does not match source SHA");
+  if (publication.releaseTag !== `v${publication.packageVersion}`)
+    throw new Error("public release tag does not match package version");
+
+  const manifestPath = canonicalPublicationFile("publication-artifact.json");
+  const passportPath = canonicalPublicationFile(
+    "publication-artifact-passport.json",
+  );
+  const registryPath = canonicalPublicationFile("publication-registry.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const archive = manifest.publication?.archive;
+  if (!archive || archive.version !== publication.packageVersion)
+    throw new Error("publication archive identity mismatch");
+  const primary = (archive.publicArtifacts?.artifacts || []).find(
+    (entry) => entry.role === "primary",
+  );
+  if (!primary) throw new Error("publication archive has no primary artifact");
+  const releasePassportPath = path.resolve(publication.passportPath);
+  const releaseBase = `https://github.com/${publication.repository}/releases/download/${publication.releaseTag}`;
+  const envelope = {
+    repository: publication.repository,
+    channel: publication.channel,
+    tag: publication.releaseTag,
+    tagTargetSha: publication.sourceSha,
+    sourceSha: publication.sourceSha,
+    package: {
+      name: publication.packageName,
+      version: publication.packageVersion,
+      integrity: packageIntegrity,
+      gitHead: packageFact.gitHead,
+    },
+    releasePassport: {
+      url: `${releaseBase}/buildchain.release.json`,
+      sha256: sha256File(releasePassportPath),
+    },
+    publicationArtifact: {
+      id: archive.id,
+      kind: manifest.publication.kind,
+      version: archive.version,
+      canonicalUrl: archive.routes.canonicalUrl,
+      latestUrl: archive.routes.latestUrl,
+      latestEvidenceUrl: archive.routes.latestEvidenceUrl || "",
+      immutableVersionUrl:
+        archive.routes.immutableVersionUrl ||
+        archive.routes.immutableVersionPrefix,
+      immutableVersionPrefix:
+        archive.routes.immutableVersionPrefix ||
+        archive.routes.immutableVersionUrl,
+      registry: {
+        url: `${releaseBase}/${path.basename(registryPath)}`,
+        sha256: sha256File(registryPath),
+      },
+      manifest: {
+        url: `${releaseBase}/${path.basename(manifestPath)}`,
+        sha256: sha256File(manifestPath),
+      },
+      passport: {
+        url: `${releaseBase}/${path.basename(passportPath)}`,
+        sha256: sha256File(passportPath),
+      },
+      primaryArtifact: {
+        path: primary.path,
+        url: primary.url,
+        sha256: primary.sha256,
+        bytes: primary.bytes,
+      },
+      ...(archive.publicArtifacts.sourceBundle
+        ? { sourceBundle: archive.publicArtifacts.sourceBundle }
+        : {}),
+    },
+  };
+  fs.writeFileSync(
+    path.join(publication.workspace, ".buildchain/upstream-release.json"),
+    `${JSON.stringify(envelope, null, 2)}\n`,
+  );
+  return envelope;
+}

package/packages/core/paper/publication/propagation.js

@@ -0,0 +1,135 @@
+import fs from "node:fs";
+import path from "node:path";
+import { requireValue } from "../../runtime/action-process.mjs";
+import {
+  planReleasePropagation,
+  createReleasePropagationWork,
+  verifyReleasePropagationWork,
+} from "../../release/release-propagation.js";
+
+export function validatePaperPropagationConfig(config) {
+  const fields = [
+    "schemaVersion",
+    "contract",
+    "sourceNode",
+    "graph",
+    "targets",
+  ].sort();
+  requireValue(
+    config &&
+      JSON.stringify(Object.keys(config).sort()) === JSON.stringify(fields) &&
+      config.schemaVersion === 1 &&
+      config.contract === "kungfu-buildchain-paper-release-propagation",
+    "Paper propagation config must use the exact current contract",
+  );
+  requireValue(
+    config.graph &&
+      typeof config.graph === "object" &&
+      !Array.isArray(config.graph),
+    "Paper propagation graph must be an object",
+  );
+  requireValue(
+    typeof config.sourceNode === "string" && Boolean(config.sourceNode),
+    "Paper propagation sourceNode is required",
+  );
+  requireValue(
+    Array.isArray(config.targets) &&
+      config.targets.length > 0 &&
+      config.targets.every(
+        (x) => typeof x === "string" && /^[A-Za-z0-9._-]+$/.test(x),
+      ),
+    "Paper propagation targets must be non-empty canonical node ids",
+  );
+  requireValue(
+    JSON.stringify([...new Set(config.targets)].sort()) ===
+      JSON.stringify(config.targets),
+    "Paper propagation targets must be sorted and unique",
+  );
+  return config;
+}
+export async function capturePaperPropagation({
+  workspace,
+  repository,
+  sourceSha,
+  packageVersion,
+  github,
+}) {
+  const [owner, repo] = repository.split("/");
+  let response;
+  try {
+    response = await github.rest.repos.getContent({
+      owner,
+      repo,
+      path: ".buildchain/release-propagation.json",
+      ref: sourceSha,
+    });
+  } catch (error) {
+    if (error.status === 404) {
+      return { configured: false };
+    }
+    throw error;
+  }
+  requireValue(
+    response.data.type === "file" && response.data.encoding === "base64",
+    "Paper propagation config is not a base64 repository file",
+  );
+  const config = validatePaperPropagationConfig(
+    JSON.parse(Buffer.from(response.data.content, "base64").toString("utf8")),
+  );
+  const upstreamRelease = JSON.parse(
+    fs.readFileSync(
+      path.join(workspace, ".buildchain/upstream-release.json"),
+      "utf8",
+    ),
+  );
+  const plan = planReleasePropagation({
+    graph: config.graph,
+    upstreamRelease,
+    sourceNode: config.sourceNode,
+  });
+  fs.writeFileSync(
+    path.join(workspace, ".buildchain/release-propagation-config.json"),
+    JSON.stringify(config, null, 2) + "\n",
+  );
+  fs.writeFileSync(
+    path.join(workspace, ".buildchain/release-propagation-plan.json"),
+    JSON.stringify(plan, null, 2) + "\n",
+  );
+  for (const target of config.targets) {
+    const rows = plan.targets.filter((entry) => entry.target === target);
+    requireValue(
+      rows.length === 1 && /^[0-9a-f]{64}$/.test(rows[0].propagationKey),
+      "Configured propagation target is absent or ambiguous",
+    );
+    const selected = rows[0];
+    const [targetOwner, targetRepo] = selected.repository.split("/");
+    const commit = await github.rest.repos.getCommit({
+      owner: targetOwner,
+      repo: targetRepo,
+      ref: selected.baseRef,
+    });
+    const work = createReleasePropagationWork({
+      plan,
+      target,
+      expectedDownstreamBaseSha: commit.data.sha,
+    });
+    const directory = path.join(
+      workspace,
+      ".buildchain/release-propagation-work",
+      selected.propagationKey,
+    );
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(
+      path.join(directory, "work.json"),
+      JSON.stringify(work, null, 2) + "\n",
+    );
+    fs.writeFileSync(
+      path.join(directory, "status.json"),
+      JSON.stringify(verifyReleasePropagationWork(work), null, 2) + "\n",
+    );
+  }
+  return {
+    configured: true,
+    "artifact-name": `paper-propagation-work-${packageVersion}-${sourceSha}`,
+  };
+}

package/packages/core/paper/publication/readback.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { command, requireValue } from "../../runtime/action-process.mjs";
+
+export function publishedPackageMatches(value, publication) {
+  return (
+    value?.version === publication.packageVersion &&
+    value?.gitHead === publication.sourceSha &&
+    typeof value?.dist?.integrity === "string" &&
+    value.dist.integrity.startsWith("sha512-")
+  );
+}
+export function resolvePublishedTag(raw, tag) {
+  const values = new Map();
+  for (const line of raw.trim().split("\n").filter(Boolean)) {
+    const [sha, ref] = line.split(/\s+/);
+    requireValue(
+      [`refs/tags/${tag}`, `refs/tags/${tag}^{}`].includes(ref) &&
+        /^[0-9a-f]{40}$/.test(sha) &&
+        !values.has(ref),
+      "Published tag lookup returned ambiguous coordinates",
+    );
+    values.set(ref, sha);
+  }
+  return (
+    values.get(`refs/tags/${tag}^{}`) || values.get(`refs/tags/${tag}`) || ""
+  );
+}
+export async function readPublishedPaper(
+  publication,
+  { request = fetch, execute = command, wait = setTimeout } = {},
+) {
+  requireValue(
+    Boolean(publication.passportPath),
+    "Paper publication is awaiting its generated version-state merge; merge the generated PR and rerun the failed jobs",
+  );
+  requireValue(
+    publication.releaseTag === `v${publication.packageVersion}` &&
+      /^[0-9a-f]{40}$/.test(publication.sourceSha),
+    "Paper publication requires exact matching version, tag and source SHA",
+  );
+  let fact;
+  for (let attempt = 0; attempt < 6; attempt++) {
+    try {
+      const response = await request(
+        `https://registry.npmjs.org/${encodeURIComponent(publication.packageName)}/${encodeURIComponent(publication.packageVersion)}`,
+        { headers: { accept: "application/json" } },
+      );
+      if (response.ok) {
+        const value = await response.json();
+        if (publishedPackageMatches(value, publication)) {
+          fact = value;
+          break;
+        }
+      }
+    } catch (error) {
+      if (attempt === 5) throw error;
+    }
+    if (attempt < 5) await wait(5000);
+  }
+  requireValue(
+    Boolean(fact),
+    "npm publication did not become coherently readable within the bounded retry window",
+  );
+  const raw = execute(
+    "git",
+    [
+      "ls-remote",
+      "--tags",
+      "origin",
+      `refs/tags/${publication.releaseTag}`,
+      `refs/tags/${publication.releaseTag}^{}`,
+    ],
+    { cwd: publication.workspace, stdio: "pipe" },
+  );
+  requireValue(
+    resolvePublishedTag(raw, publication.releaseTag) === publication.sourceSha,
+    "Published tag target does not match the exact paper source SHA",
+  );
+  fs.mkdirSync(path.join(publication.workspace, ".buildchain"), {
+    recursive: true,
+  });
+  fs.writeFileSync(
+    path.join(publication.workspace, ".buildchain/published-package.json"),
+    JSON.stringify(fact, null, 2) + "\n",
+  );
+  return fact;
+}

package/packages/core/paper/publication/target.js

@@ -0,0 +1,54 @@
+import { command, requireValue } from "../../runtime/action-process.mjs";
+export function resolvePaperTarget({ workspace, ref, sha }, execute = command) {
+  requireValue(
+    /^(alpha|release)\/v\d+\/v\d+\.\d+$/.test(ref),
+    "Paper release requires an exact alpha or release channel branch",
+  );
+  requireValue(
+    /^[0-9a-f]{40}$/.test(sha),
+    "Paper publication source SHA must be exact",
+  );
+  requireValue(
+    execute("git", ["rev-parse", "HEAD"], {
+      cwd: workspace,
+      stdio: "pipe",
+    }).trim() === sha,
+    "Paper source checkout differs from the publication target",
+  );
+  return { ref, sha, channel: ref.split("/")[0] };
+}
+export async function lockPaperPublicationTarget({
+  github,
+  repository,
+  target,
+  version,
+}) {
+  const [owner, repo] = repository.split("/");
+  const gateRef = `publish-gate/${target.channel}/${target.ref.replace(/^(alpha|release)\//, "")}/${version}`,
+    ref = `heads/${gateRef}`;
+  try {
+    const current = await github.rest.git.getRef({ owner, repo, ref });
+    requireValue(
+      current.data.object.sha === target.sha,
+      "publication gate already binds a different source commit",
+    );
+  } catch (error) {
+    if (error.status !== 404) throw error;
+    try {
+      await github.rest.git.createRef({
+        owner,
+        repo,
+        ref: `refs/${ref}`,
+        sha: target.sha,
+      });
+    } catch (createError) {
+      if (createError.status !== 422) throw createError;
+    }
+    const readback = await github.rest.git.getRef({ owner, repo, ref });
+    requireValue(
+      readback.data.object.sha === target.sha,
+      "publication gate readback differs from the admitted source commit",
+    );
+  }
+  return { ...target, gateRef, locked: true };
+}

package/packages/core/paper/publication-controller.js

@@ -0,0 +1,144 @@
+import {
+  createControllerPlan,
+  createControllerReceipt,
+  validateControllerReceipt,
+} from "../observability/controller-evidence.js";
+import { validateReleasePassportSchema } from "../release/release-passport-contract.js";
+import { requireValue } from "../runtime/action-process.mjs";
+
+function requireCandidate(receipt, source, runtime) {
+  const result = validateControllerReceipt(receipt, {
+    expectedSourceSha: source.sha,
+    expectedRuntimeSha: runtime.sha,
+  });
+  requireValue(
+    result.qualifying &&
+      receipt.controller.id === "publication-artifact" &&
+      receipt.source.repository === source.repository &&
+      receipt.runtime.contractDigest === runtime.contractDigest,
+    "Paper candidate controller must qualify for the exact source and runtime",
+  );
+}
+
+export function createPaperControllerPlan({
+  descriptor,
+  candidateReceipt,
+  source,
+  runtime,
+  inputs,
+}) {
+  requireCandidate(candidateReceipt, source, runtime);
+  return createControllerPlan({
+    descriptor,
+    source,
+    runtime,
+    inputs: {
+      ...inputs,
+      "candidate-receipt-digest": candidateReceipt.digest,
+    },
+  });
+}
+
+export function requirePaperReleasePassport(
+  passport,
+  { repository, sourceSha, tag },
+) {
+  requireValue(
+    validateReleasePassportSchema(passport).ok,
+    "Paper release Passport must satisfy the current schema",
+  );
+  requireValue(
+    passport.product.repository === repository &&
+      passport.release.sourceSha === sourceSha &&
+      passport.release.tag === tag,
+    "Paper release Passport must bind the exact repository, source and tag",
+  );
+}
+
+function outcomeStatus(outcome) {
+  return (
+    {
+      success: "passed",
+      failure: "failed",
+      cancelled: "cancelled",
+      skipped: "skipped",
+    }[outcome] || "missing"
+  );
+}
+
+export function createPaperControllerReceipt({
+  plan,
+  candidateReceipt,
+  publishOutcome,
+  readbackOutcome,
+  aggregateOutcome,
+  passport,
+  tag,
+  evidence = [],
+  artifact = "",
+}) {
+  let candidateValid = false;
+  let passportValid = false;
+  const failures = [];
+  try {
+    requireCandidate(candidateReceipt, plan.source, plan.runtime);
+    requireValue(
+      candidateReceipt.digest === plan.inputs["candidate-receipt-digest"].value,
+      "Paper candidate receipt changed after admission",
+    );
+    candidateValid = true;
+  } catch (error) {
+    failures.push(error.message);
+  }
+  if (publishOutcome === "success" && readbackOutcome === "success") {
+    try {
+      requirePaperReleasePassport(passport, {
+        repository: plan.source.repository,
+        sourceSha: plan.source.sha,
+        tag,
+      });
+      passportValid = true;
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+  const stages = ["resolve-runtime", "build", "verify", "collect"].map(
+    (id) => ({
+      id,
+      status: candidateValid
+        ? candidateReceipt.stages.find((stage) => stage.id === id)?.status ||
+          "missing"
+        : "failed",
+    }),
+  );
+  stages.push(
+    { id: "publication-authority", status: "passed" },
+    { id: "publish", status: outcomeStatus(publishOutcome) },
+    {
+      id: "passport",
+      status: passportValid
+        ? "passed"
+        : readbackOutcome === "success"
+          ? "failed"
+          : outcomeStatus(readbackOutcome),
+    },
+    {
+      id: "aggregate",
+      status: failures.length ? "failed" : outcomeStatus(aggregateOutcome),
+    },
+  );
+  return createControllerReceipt({
+    plan,
+    stages,
+    artifact,
+    evidence: evidence.filter(
+      (item) => item.kind !== "release-passport" || passportValid,
+    ),
+    reason: {
+      code: "paper-publication-incomplete",
+      summary:
+        failures.join("; ") ||
+        "Paper publication did not complete every required stage",
+    },
+  });
+}

package/packages/core/providers/artifact-relay/files.js

@@ -0,0 +1,71 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export function toPosix(value) {
+  return String(value || "").replaceAll(path.sep, "/");
+}
+
+export function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+export function listFiles(root, rel) {
+  const normalized = String(rel || "")
+    .replace(/\\/g, "/")
+    .replace(/\/\*\*\/?\*?$/, "");
+  const target = path.isAbsolute(normalized)
+    ? normalized
+    : path.join(root, normalized);
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const stat = fs.statSync(target);
+  if (stat.isFile()) {
+    return [target];
+  }
+  return fs
+    .readdirSync(target, { withFileTypes: true })
+    .flatMap((entry) => listFiles(root, path.join(target, entry.name)));
+}
+
+export function collectGroupFiles(root, paths) {
+  const files = new Set();
+  for (const entry of paths) {
+    for (const file of listFiles(root, entry)) {
+      files.add(path.resolve(file));
+    }
+  }
+  return [...files].sort();
+}
+
+export function safeSegment(value, fallback = "artifact") {
+  const segment = String(value || fallback)
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return segment || fallback;
+}
+
+export function normalizePrefix(value) {
+  return (
+    String(value || "buildchain-artifacts").replace(/^\/+|\/+$/g, "") ||
+    "buildchain-artifacts"
+  );
+}
+
+export function assertSafeRelativePath(value) {
+  const normalized = path.posix.normalize(
+    String(value || "").replace(/\\/g, "/"),
+  );
+  if (
+    !normalized ||
+    normalized === "." ||
+    normalized.startsWith("../") ||
+    normalized === ".." ||
+    path.isAbsolute(normalized)
+  ) {
+    throw new Error(`unsafe relay object relative path: ${value}`);
+  }
+  return normalized;
+}