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

package/packages/core/release/discussion/checkpoints.js

@@ -0,0 +1,282 @@
+import {
+  retainAttachment,
+  diagnosticReport,
+  diagnosticLog,
+} from "./evidence.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createProgress, recordDigest } from "./envelope.js";
+import { materialDigest } from "../../providers/github/discussions/materials.js";
+import { discussionMaterials } from "../../providers/github/discussions/materials.js";
+
+export function releaseCheckpoints({ session, store, octokit }) {
+  const materials = discussionMaterials({
+    octokit,
+    repository: session.intent.repository,
+    intentId: session.intent.id,
+  });
+  async function checkpoint(
+    node,
+    value,
+    { attachments = [], label = value.schema || "Recovery checkpoint" } = {},
+  ) {
+    const observed = await store.read(session);
+    const records = observed.records.filter(
+      (record) =>
+        record.kind === "checkpoint" &&
+        record.attempt === session.attempt &&
+        record.node === node,
+    );
+    const root = recordDigest(value);
+    const duplicate = records.find((record) => record.payload.root === root);
+    if (duplicate) return duplicate;
+    const sequence =
+      Math.max(-1, ...records.map((record) => record.sequence)) + 1;
+    const handle = await retainAttachment(materials, {
+      name: `${node}-checkpoint-${sequence}.json`,
+      mediaType: "application/json",
+      bytes: Buffer.from(JSON.stringify(value, null, 2) + "\n"),
+    });
+    const record = createProgress({
+      intent: session.intent,
+      runtime: session.runtime,
+      attempt: session.attempt,
+      writer: session.writer || session.attempt,
+      predecessor: session.predecessor,
+      kind: "checkpoint",
+      node,
+      status: "running",
+      sequence,
+      payload: {
+        schema: "buildchain.release-checkpoint/v1",
+        root,
+        material: handle,
+        label,
+        attachments: [handle, ...attachments],
+      },
+    });
+    await store.append(session, record);
+    return record;
+  }
+  async function readCheckpoint(record) {
+    if (
+      record.kind !== "checkpoint" ||
+      record.payload?.schema !== "buildchain.release-checkpoint/v1"
+    )
+      throw new Error("Unsupported recovery checkpoint");
+    const value = JSON.parse(await materials.read(record.payload.material));
+    if (recordDigest(value) !== record.payload.root)
+      throw new Error("Recovery checkpoint root differs from its record");
+    return value;
+  }
+  async function publicationReader(currentBytes) {
+    const observed = await store.read(session);
+    const first = observed.records
+      .filter(
+        (record) =>
+          record.kind === "checkpoint" && record.node === "qualification",
+      )
+      .sort(
+        (a, b) =>
+          observed.attempts.indexOf(a.attempt) -
+            observed.attempts.indexOf(b.attempt) || a.sequence - b.sequence,
+      )[0];
+    if (!first) return currentBytes;
+    const manifest = await readCheckpoint(first);
+    if (manifest.schema !== "buildchain.release-recovery-material/v1")
+      throw new Error("Unsupported retained publication reader manifest");
+    return materials.read(manifest.reader);
+  }
+  async function diagnostics(node, code) {
+    const report = diagnosticReport(
+      session,
+      await store.read(session),
+      node,
+      code,
+    );
+    const log = await retainAttachment(materials, {
+      name: `${node}-diagnostics.log`,
+      mediaType: "text/plain",
+      bytes: diagnosticLog(report),
+    });
+    return checkpoint(node, report, {
+      attachments: [log],
+      label: `Execution diagnostics: ${report.code}`,
+    });
+  }
+  return {
+    checkpoint,
+    readCheckpoint,
+    materials,
+    publicationReader,
+    diagnostics,
+  };
+}
+
+function assertNoSymlink(file, base) {
+  let current = file;
+  while (current.startsWith(base)) {
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink())
+      throw new Error("Recovery path contains a symbolic link");
+    if (current === base) break;
+    current = path.dirname(current);
+  }
+}
+
+const MATERIAL_INPUTS = [
+  "candidate-passport-path",
+  "candidate-build-summary-path",
+  "stage-capsules-path",
+  "product-publication-intent-path",
+  "publication-qualification-path",
+  "required-artifacts-path",
+  "sealed-bundle-manifest",
+  "recovery-receipt-path",
+];
+
+export async function retainRecoveryMaterials(
+  { request, workspace, readerFile },
+  materials,
+) {
+  const base = path.resolve(workspace);
+  const files = new Set(
+    MATERIAL_INPUTS.map((name) => request[name])
+      .filter(Boolean)
+      .map((file) => path.resolve(base, file)),
+  );
+  for (const file of request["artifact-paths"] || [])
+    files.add(path.resolve(base, file));
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink())
+        throw new Error("Recovery materials must not contain symbolic links");
+      if (entry.isDirectory()) walk(file);
+      else if (entry.isFile()) files.add(file);
+      if (files.size > 512)
+        throw new Error("Recovery material file count exceeded");
+    }
+  };
+  if (request["sealed-bundle-root"]) {
+    const root = path.resolve(base, request["sealed-bundle-root"]);
+    if (!root.startsWith(path.join(base, ".buildchain") + path.sep))
+      throw new Error("Sealed recovery directory is outside consumer evidence");
+    assertNoSymlink(root, base);
+    walk(root);
+  }
+  const handles = [];
+  let totalSize = 0;
+  for (const file of files) {
+    const relative = path.relative(base, file).split(path.sep).join("/");
+    if (
+      !relative.startsWith(".buildchain/") ||
+      relative.startsWith(".buildchain/runtime/") ||
+      relative.includes("../")
+    )
+      throw new Error(
+        "Recovery materials must remain in the declared consumer evidence directory",
+      );
+    assertNoSymlink(file, base);
+    const info = fs.lstatSync(file);
+    if (!info.isFile())
+      throw new Error("Recovery material is not a regular file");
+    totalSize += info.size;
+    if (totalSize > 1024 * 1024 * 1024)
+      throw new Error("Recovery material byte budget exceeded");
+    handles.push({
+      path: relative,
+      ...(await materials.put(fs.readFileSync(file))),
+    });
+  }
+  return {
+    schema: "buildchain.release-recovery-material/v1",
+    source: {
+      repository: request.repository,
+      sourceSha: request["source-sha"],
+      version: request.version,
+      targetRef: request["target-ref"],
+      channel: request.channel,
+    },
+    releaseAssets: (request["artifact-paths"] || []).map((file) =>
+      path.relative(base, path.resolve(base, file)).split(path.sep).join("/"),
+    ),
+    files: handles,
+    inputs: Object.fromEntries(
+      [...MATERIAL_INPUTS, "sealed-bundle-root"].map((key) => [
+        key,
+        request[key]
+          ? path
+              .relative(base, path.resolve(base, request[key]))
+              .split(path.sep)
+              .join("/")
+          : "",
+      ]),
+    ),
+    reader: await materials.put(fs.readFileSync(readerFile)),
+  };
+}
+
+function recoveryInventory(manifest, directory) {
+  if (
+    manifest.schema !== "buildchain.release-recovery-material/v1" ||
+    !Array.isArray(manifest.files) ||
+    manifest.files.length > 512
+  )
+    throw new Error("Unsupported recovery material manifest");
+  const base = path.resolve(directory),
+    paths = new Set();
+  const files = manifest.files.map((handle) => {
+    if (
+      typeof handle.path !== "string" ||
+      !handle.path.startsWith(".buildchain/") ||
+      handle.path.startsWith(".buildchain/runtime/") ||
+      handle.path
+        .split(/[\\/]/u)
+        .some((part) => ["..", ".", ""].includes(part)) ||
+      paths.has(handle.path)
+    )
+      throw new Error("Unsafe recovery material path");
+    paths.add(handle.path);
+    const file = path.resolve(base, handle.path);
+    assertNoSymlink(file, base);
+    if (
+      fs.existsSync(file) &&
+      (!fs.lstatSync(file).isFile() ||
+        materialDigest(fs.readFileSync(file)) !== handle.digest)
+    )
+      throw new Error(
+        "Recovery material destination already exists with different bytes",
+      );
+    return { handle, file };
+  });
+  const inputs = Object.fromEntries(
+    Object.entries(manifest.inputs).map(([key, relative]) => {
+      if (!relative) return [key, ""];
+      const present =
+        key === "sealed-bundle-root"
+          ? [...paths].some((file) => file.startsWith(relative + "/"))
+          : paths.has(relative);
+      if (!present)
+        throw new Error("Recovery input is outside the retained inventory");
+      return [key, path.resolve(base, relative)];
+    }),
+  );
+  if ((manifest.releaseAssets || []).some((file) => !paths.has(file)))
+    throw new Error("Release asset is outside the retained inventory");
+  return { files, inputs };
+}
+
+export async function restoreRecoveryMaterials(manifest, directory, materials) {
+  const { files, inputs } = recoveryInventory(manifest, directory);
+  let total = 0;
+  for (const { handle, file } of files) {
+    total += handle.size || 0;
+    if (total > 1024 * 1024 * 1024)
+      throw new Error("Recovery material byte budget exceeded");
+    const bytes = await materials.read(handle);
+    if (fs.existsSync(file)) continue;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, bytes, { flag: "wx" });
+  }
+  return inputs;
+}

package/packages/core/release/discussion/envelope.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+
+export const ENVELOPE_SCHEMA = "buildchain.discussion-record/v1";
+export const INTENT_SCHEMA = "buildchain.release-discussion/v1";
+export const PAYLOAD_SCHEMA = "buildchain.release-progress/v1";
+const MARKER = "<!-- buildchain-transaction\n";
+export const MAX_RECORD_BYTES = 48_000;
+
+export function canonicalJson(value) {
+  if (typeof value === "number" && !Number.isFinite(value))
+    throw new Error("Transaction numbers must be finite");
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(",")}}`;
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined)
+    throw new Error("Transaction records must contain JSON values");
+  return encoded;
+}
+
+export function recordDigest(value) {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+export function requireString(value, label) {
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`${label} is required`);
+  return value;
+}
+
+export function validateRuntime(runtime) {
+  if (
+    !/^[\w.-]+\/[\w.-]+$/u.test(runtime?.repository || "") ||
+    !/^[a-f0-9]{40}$/u.test(runtime?.sha || "") ||
+    !/^sha256:[a-f0-9]{64}$/u.test(runtime?.readerDigest || "")
+  )
+    throw new Error(
+      "Record requires selected runtime repository, exact revision and reader digest",
+    );
+  return runtime;
+}
+
+export function encodeRecord(
+  record,
+  summary = "Buildchain release transaction record",
+) {
+  const body = `${summary}\n\n${MARKER}${canonicalJson(record)}\n-->`;
+  if (Buffer.byteLength(body) > MAX_RECORD_BYTES)
+    throw new Error(
+      "Transaction record exceeds the bounded body size; retain material as artifacts",
+    );
+  return body;
+}
+
+export function decodeRecord(body) {
+  if (typeof body !== "string" || !body.includes(MARKER)) return undefined;
+  if (Buffer.byteLength(body) > MAX_RECORD_BYTES)
+    throw new Error("Oversized transaction record");
+  const start = body.indexOf(MARKER) + MARKER.length;
+  const end = body.indexOf("\n-->", start);
+  if (end < 0 || body.indexOf(MARKER, start) >= 0)
+    throw new Error("Malformed transaction envelope");
+  const record = JSON.parse(body.slice(start, end));
+  if (![ENVELOPE_SCHEMA, INTENT_SCHEMA].includes(record.schema))
+    throw new Error("Unsupported transaction envelope schema");
+  return record;
+}
+
+export function createIntent({
+  repository,
+  key,
+  expectedNodes,
+  runtime,
+  source,
+}) {
+  requireString(repository, "Consumer repository");
+  requireString(key, "Release intent key");
+  if (key.length > 240 || /[\r\n<>]/u.test(key))
+    throw new Error("Invalid release intent key");
+  if (
+    !Array.isArray(expectedNodes) ||
+    !expectedNodes.length ||
+    new Set(expectedNodes).size !== expectedNodes.length ||
+    expectedNodes.some((node) => !/^[a-z][a-z0-9-]*$/u.test(node))
+  )
+    throw new Error("Release intent requires unique expected semantic nodes");
+  validateRuntime(runtime);
+  const identity = { repository, key };
+  return {
+    schema: INTENT_SCHEMA,
+    id: recordDigest(identity),
+    ...identity,
+    expectedNodes,
+    organization: "attempt-threads/v1",
+    runtime,
+    source,
+  };
+}
+
+export function createProgress({
+  intent,
+  attempt,
+  predecessor = "",
+  runtime,
+  node,
+  status,
+  payload = {},
+  sequence = 0,
+  kind = "progress",
+  writer = attempt,
+}) {
+  validateRuntime(runtime);
+  requireString(writer, "Record writer");
+  requireString(attempt, "Workflow attempt");
+  if (node !== "attempt" && !intent.expectedNodes.includes(node))
+    throw new Error(`Undeclared release node: ${node}`);
+  if (!["running", "success", "failure", "cancelled"].includes(status))
+    throw new Error("Invalid release node status");
+  if (!Number.isSafeInteger(sequence) || sequence < 0)
+    throw new Error("Invalid record sequence");
+  if (predecessor === attempt) throw new Error("Attempt cannot recover itself");
+  if (!["progress", "checkpoint"].includes(kind))
+    throw new Error("Invalid transaction record kind");
+  const event = {
+    kind,
+    writer,
+    schema: ENVELOPE_SCHEMA,
+    intent: intent.id,
+    attempt,
+    predecessor,
+    runtime,
+    payloadSchema: PAYLOAD_SCHEMA,
+    node,
+    status,
+    sequence,
+    payload,
+  };
+  return { ...event, id: recordDigest(event) };
+}

package/packages/core/release/discussion/evidence.js

@@ -0,0 +1,51 @@
+// Evidence is declared transaction data, never an implicit upload of workspace
+// files, environment variables, raw exceptions or authenticated HTTP responses.
+export async function retainAttachment(materials, { name, mediaType, bytes }) {
+  if (
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,159}$/u.test(name) ||
+    !["application/json", "text/plain", "application/octet-stream"].includes(
+      mediaType,
+    )
+  )
+    throw new Error("Invalid transaction attachment descriptor");
+  const handle = await materials.put(bytes, { name, mediaType });
+  if (!handle.downloadUrl)
+    throw new Error("Retained attachment is missing its provider download URL");
+  return { name, mediaType, ...handle };
+}
+
+export function diagnosticReport(session, state, node, code) {
+  return {
+    schema: "buildchain.release-diagnostics/v1",
+    intent: session.intent.id,
+    attempt: session.attempt,
+    node,
+    code: String(code || "execution-failed")
+      .replace(/[^a-zA-Z0-9._-]/gu, "-")
+      .slice(0, 160),
+    events: state.records
+      .filter((record) => record.attempt === session.attempt)
+      .map(({ id, node, kind, status, sequence, writer }) => ({
+        id,
+        node,
+        kind,
+        status,
+        sequence,
+        writer,
+      })),
+  };
+}
+
+export function diagnosticLog(report) {
+  return Buffer.from(
+    [
+      `Release intent ${report.intent}`,
+      `Attempt ${report.attempt}: ${report.node} ${report.code}`,
+      ...report.events.map(
+        (event) =>
+          `${event.node} ${event.kind} ${event.sequence} ${event.status} writer=${event.writer} record=${event.id}`,
+      ),
+      "",
+    ].join("\n"),
+  );
+}

package/packages/core/release/discussion/presentation.js

@@ -0,0 +1,92 @@
+import { isAttemptRoot } from "./threads.js";
+
+const text = (value) =>
+  String(value ?? "")
+    .replace(
+      /[&<>\[\]`*_\\|]/gu,
+      (character) => `&#${character.charCodeAt(0)};`,
+    )
+    .replace(/[\r\n]/gu, " ");
+const code = (value) => `\`${String(value).replace(/[`\r\n]/gu, " ")}\``;
+
+function runLink(repository, writer) {
+  const match = /^(\d+):(\d+)(?::.*)?$/u.exec(writer);
+  return match
+    ? `[${text(writer)}](https://github.com/${repository}/actions/runs/${match[1]}/attempts/${match[2]})`
+    : code(writer);
+}
+
+function runtimeLink(runtime) {
+  return `[${runtime.repository}@${runtime.sha.slice(0, 12)}](https://github.com/${runtime.repository}/commit/${runtime.sha})`;
+}
+
+export function renderIntent(intent) {
+  return [
+    `## ${intent.source?.qualification ? "Qualification" : "Release"}: ${text(intent.key)}`,
+    `Repository: ${code(intent.repository)}`,
+    "Each top-level transaction comment owns one attempt. Its replies contain node results, recovery checkpoints and downloadable evidence. Recovery attempts link to their predecessors.",
+    `Expected nodes: ${intent.expectedNodes.map(code).join(" → ")}`,
+    `Intent: ${code(intent.id)}`,
+  ].join("\n\n");
+}
+
+function attachmentRows(record, repository) {
+  return (record.payload?.attachments || []).map((attachment) => {
+    const url = new URL(attachment.downloadUrl);
+    if (
+      url.protocol !== "https:" ||
+      url.hostname !== "github.com" ||
+      !url.pathname.startsWith(`/${repository}/releases/download/`) ||
+      url.search ||
+      url.hash
+    )
+      throw new Error(
+        "Attachment download must belong to the consumer repository",
+      );
+    return `| [${text(attachment.name)}](${url.href}) | ${text(attachment.mediaType)} | ${attachment.size} | ${code(attachment.digest)} |`;
+  });
+}
+
+export function renderEvent(record, intent, state) {
+  if (isAttemptRoot(record)) {
+    const predecessor = state.roots.get(record.predecessor);
+    return [
+      `## Attempt ${text(record.attempt)}`,
+      `Execution: ${runLink(intent.repository, record.writer)}  \nRuntime: ${runtimeLink(record.runtime)}`,
+      record.predecessor
+        ? `Resumes: ${predecessor?.url ? `[${text(record.predecessor)}](${predecessor.url})` : code(record.predecessor)}`
+        : "Initial execution of this release intent.",
+      `Nodes: ${intent.expectedNodes.map(code).join(" → ")}`,
+      "Results and evidence are appended below. This root preserves the original execution context.",
+    ].join("\n\n");
+  }
+  const label =
+    record.kind === "checkpoint"
+      ? `checkpoint ${record.sequence}`
+      : record.status;
+  const lines = [
+    `### ${text(record.node)} · ${label}`,
+    `Attempt: ${code(record.attempt)} · Writer: ${runLink(intent.repository, record.writer)}`,
+    `Runtime: ${runtimeLink(record.runtime)}`,
+  ];
+  if (record.payload?.label) lines.push(text(record.payload.label));
+  if (record.payload?.code)
+    lines.push(`Failure code: ${code(record.payload.code)}`);
+  const attachments = attachmentRows(record, intent.repository);
+  if (attachments.length)
+    lines.push(
+      "| Attachment | Type | Bytes | SHA-256 |\n| --- | --- | ---: | --- |\n" +
+        attachments.join("\n"),
+      "Retained files use the transaction material archive. Access requires repository permission to read draft release assets.",
+    );
+  const { attachments: _attachments, ...details } = record.payload || {};
+  if (Object.keys(details).length) {
+    const json = JSON.stringify(details, null, 2);
+    // HTML escaping keeps payload strings from closing the presentation container.
+    lines.push(
+      `<details><summary>Record details</summary><pre>${json.slice(0, 6000).replace(/[&<>]/gu, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c])}${json.length > 6000 ? "\n… See the retained JSON attachment for the complete material." : ""}</pre></details>`,
+    );
+  }
+  lines.push(`Record: ${code(record.id)}`);
+  return lines.join("\n\n");
+}

package/packages/core/release/discussion/publication.js

@@ -0,0 +1,123 @@
+import { decodeRecord } from "./envelope.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import path from "node:path";
+import fs from "node:fs";
+import { openReleaseSession, RELEASE_NODES } from "./session.js";
+import { releaseCheckpoints, retainRecoveryMaterials } from "./checkpoints.js";
+import { promoteReleaseCandidate } from "../promote-candidate/transaction.js";
+
+export async function publicationNodes(request, graphql) {
+  if (!request["resume-discussion-id"])
+    return [
+      ...RELEASE_NODES,
+      ...(request["standalone-binary-distribution"]
+        ? ["binary-distribution"]
+        : []),
+    ];
+  const discussion = await discussionTransport(graphql).get(
+    request["resume-discussion-id"],
+  );
+  const intent = decodeRecord(discussion.body);
+  if (
+    intent?.repository !== request.repository ||
+    intent.key !== request.version
+  )
+    throw new Error("Discussion recovery cannot change the release intent");
+  return intent.expectedNodes;
+}
+
+export async function publishWithDiscussion(
+  request,
+  {
+    octokit,
+    mutationOctokit,
+    actor,
+    runId,
+    attempt,
+    runtime,
+    workspace,
+    runtimeRoot,
+    observe = () => {},
+  },
+) {
+  let retained;
+  const journal = await openReleaseSession({
+    graphql: octokit.graphql,
+    onFailure: (node, error) => retained.diagnostics(node, error.code),
+    repository: request.repository,
+    key: request.version,
+    source: { version: request.version },
+    expectedNodes: await publicationNodes(request, octokit.graphql),
+    runtime,
+    attempt,
+    discussionId: request["resume-discussion-id"],
+    recover: Boolean(
+      request["resume-discussion-id"] ||
+      request["publish-transaction-override"],
+    ),
+  });
+  retained = releaseCheckpoints({
+    session: journal.session,
+    store: journal.store,
+    octokit,
+  });
+  const readerFile = path.join(
+    runtimeRoot,
+    "dist/readers/release-discussion.cjs",
+  );
+  const locator = {
+    "discussion-id": journal.session.discussion.id,
+    "discussion-url": journal.session.discussion.url,
+  };
+  observe(locator);
+  const locatorPath = path.join(
+    workspace,
+    ".buildchain/release-tail/buildchain.release-transaction.json",
+  );
+  fs.mkdirSync(path.dirname(locatorPath), { recursive: true });
+  fs.writeFileSync(
+    locatorPath,
+    JSON.stringify({
+      schema: "buildchain.release-locator/v1",
+      repository: request.repository,
+      version: request.version,
+      intent: journal.session.intent.id,
+      discussionId: journal.session.discussion.id,
+    }),
+  );
+  const publicReaderPath = path.join(
+    path.dirname(locatorPath),
+    "release-discussion.cjs",
+  );
+  fs.writeFileSync(
+    publicReaderPath,
+    await retained.publicationReader(fs.readFileSync(readerFile)),
+  );
+  const execution = {
+    ...request,
+    discussionCheckpoint: retained.checkpoint,
+    discussionReaderPath: publicReaderPath,
+    discussionLocatorPath: locatorPath,
+    retainRecoveryMaterials: async () =>
+      retained.checkpoint(
+        "qualification",
+        await retainRecoveryMaterials(
+          { request, workspace, readerFile },
+          retained.materials,
+        ),
+      ),
+  };
+  const result = await promoteReleaseCandidate(execution, {
+    octokit,
+    mutationOctokit,
+    actor,
+    runId,
+    observeNode: journal.observe,
+    observe: (outputs) => observe({ ...outputs, ...locator }),
+  });
+  return {
+    ...result,
+    discussion: journal.session.discussion,
+    outputs: { ...result.outputs, ...locator },
+  };
+}