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

package/packages/core/providers/github/discussions/materials.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+
+export function materialDigest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+// Draft release assets retain immutable recovery bytes outside the source Git
+// object database. Only the Discussion record selects a committed manifest.
+export function discussionMaterials({ octokit, repository, intentId }) {
+  const [owner, repo] = repository.split("/");
+  const tag = `buildchain-records/${intentId.replace("sha256:", "")}`;
+  const repos = octokit.rest.repos;
+  let retainedArchive;
+  async function findArchive() {
+    let pages = 0;
+    const releases = await octokit.paginate(
+      repos.listReleases,
+      { owner, repo, per_page: 100 },
+      (response) => {
+        if (++pages > 100)
+          throw new Error("Material archive pagination exceeded its bound");
+        return response.data.filter((release) => release.tag_name === tag);
+      },
+    );
+    const matches = releases.filter((release) => release.tag_name === tag);
+    if (matches.length > 1)
+      throw new Error("Ambiguous transaction material archive");
+    return matches[0];
+  }
+  async function archive() {
+    if (retainedArchive) return retainedArchive;
+    let release = await findArchive();
+    if (!release) {
+      try {
+        release = (
+          await repos.createRelease({
+            owner,
+            repo,
+            tag_name: tag,
+            // Storage archives use the repository default; candidate identity is
+            // retained in the material manifest, never in a storage Git ref.
+            name: `Buildchain transaction materials ${intentId}`,
+            body: "Immutable recovery material. The associated Discussion owns transaction state.",
+            draft: true,
+            prerelease: true,
+          })
+        ).data;
+      } catch (error) {
+        release = await findArchive();
+        if (!release)
+          throw new Error("Material archive creation outcome is unknown", {
+            cause: error,
+          });
+      }
+    }
+    if (!release.draft || release.tag_name !== tag)
+      throw new Error("Transaction material archive identity mismatch");
+    retainedArchive = release;
+    return release;
+  }
+  async function read(handle) {
+    const response = await repos.getReleaseAsset({
+      owner,
+      repo,
+      asset_id: handle.id,
+      headers: { accept: "application/octet-stream" },
+    });
+    const bytes = Buffer.from(response.data);
+    if (bytes.length !== handle.size || materialDigest(bytes) !== handle.digest)
+      throw new Error(
+        "Retained transaction material failed integrity verification",
+      );
+    return bytes;
+  }
+  async function put(bytes) {
+    if (bytes.length > 256 * 1024 * 1024)
+      throw new Error("Transaction material exceeds the supported file bound");
+    const digest = materialDigest(bytes),
+      name = digest.replace(":", "-");
+    const release = await archive();
+    const find = async () => {
+      const assets = await octokit.paginate(repos.listReleaseAssets, {
+        owner,
+        repo,
+        release_id: release.id,
+        per_page: 100,
+      });
+      const matches = assets.filter((asset) => asset.name === name);
+      if (matches.length > 1)
+        throw new Error("Ambiguous immutable transaction material");
+      return matches[0];
+    };
+    let asset = await find();
+    if (!asset) {
+      try {
+        asset = (
+          await repos.uploadReleaseAsset({
+            owner,
+            repo,
+            release_id: release.id,
+            name,
+            data: bytes,
+            headers: {
+              "content-type": "application/octet-stream",
+            },
+          })
+        ).data;
+      } catch (error) {
+        asset = await find();
+        if (!asset)
+          throw new Error("Transaction material upload outcome is unknown", {
+            cause: error,
+          });
+      }
+    }
+    const handle = { id: asset.id, digest, size: bytes.length };
+    await read(handle);
+    return handle;
+  }
+  async function diagnose(operation, effect) {
+    try {
+      return await effect();
+    } catch (error) {
+      let cause = error;
+      for (let depth = 0; depth < 4 && cause.cause; depth++)
+        cause = cause.cause;
+      const details = [
+        operation,
+        cause.name,
+        cause.status,
+        cause.request?.method,
+        cause.response?.data?.errors?.[0]?.code,
+        cause.code,
+      ].filter(Boolean);
+      error.code = `discussion-material-${details
+        .join("-")
+        .replace(/[^a-zA-Z0-9-]/gu, "-")
+        .slice(0, 140)}`;
+      throw error;
+    }
+  }
+  return {
+    put: (bytes) => diagnose("put", () => put(bytes)),
+    read: (handle) => diagnose("read", () => read(handle)),
+  };
+}

package/packages/core/providers/github/discussions/transport.js

@@ -0,0 +1,115 @@
+const fields =
+  "id number url body author { __typename login ... on Node { id } } lastEditedAt repository { nameWithOwner }";
+const commentFields =
+  "id url body author { __typename login ... on Node { id } } lastEditedAt";
+
+export function discussionTransport(graphql) {
+  async function request(query, variables) {
+    try {
+      return await graphql(query, variables);
+    } catch (error) {
+      const code =
+        error.errors?.[0]?.extensions?.code ||
+        error.errors?.[0]?.type ||
+        error.status ||
+        "unknown";
+      error.code = `discussion-provider-${String(code).replace(/[^a-zA-Z0-9-]/gu, "-")}`;
+      throw error;
+    }
+  }
+  async function repository(repository) {
+    const [owner, name] = repository.split("/");
+    const result = await request(
+      `
+        query ($owner: String!, $name: String!) {
+          viewer {
+            login
+            id
+          }
+          repository(owner: $owner, name: $name) {
+            id
+            hasDiscussionsEnabled
+            discussionCategories(first: 25) {
+              nodes {
+                id
+                name
+                slug
+              }
+            }
+          }
+        }
+      `,
+      { owner, name },
+    );
+    if (!result.repository?.hasDiscussionsEnabled)
+      throw new Error(
+        `Enable Discussions in ${repository} before release execution`,
+      );
+    return { ...result.repository, viewer: result.viewer };
+  }
+  async function list(repository, categoryId, after = null) {
+    const [owner, name] = repository.split("/");
+    const result = await request(
+      `query($owner:String!,$name:String!,$category:ID!,$after:String){repository(owner:$owner,name:$name){discussions(first:100,after:$after,categoryId:$category,orderBy:{field:CREATED_AT,direction:ASC}){nodes{${fields}} pageInfo{hasNextPage endCursor}}}}`,
+      { owner, name, category: categoryId, after },
+    );
+    return result.repository.discussions;
+  }
+  async function get(id) {
+    const result = await request(
+      `query($id:ID!){node(id:$id){... on Discussion{${fields}}}}`,
+      { id },
+    );
+    if (!result.node?.repository)
+      throw new Error("Release Discussion was not found");
+    return result.node;
+  }
+  async function comments(id, after = null) {
+    const result = await request(
+      `query($id:ID!,$after:String){node(id:$id){... on Discussion{comments(first:100,after:$after){nodes{${commentFields}} pageInfo{hasNextPage endCursor}}}}}`,
+      { id, after },
+    );
+    if (!result.node?.comments)
+      throw new Error("Release Discussion comments are unavailable");
+    return result.node.comments;
+  }
+  async function create({ repositoryId, categoryId, title, body }) {
+    const result = await request(
+      `mutation($input:CreateDiscussionInput!){createDiscussion(input:$input){discussion{${fields}}}}`,
+      { input: { repositoryId, categoryId, title, body } },
+    );
+    return result.createDiscussion.discussion;
+  }
+  async function append(id, body) {
+    const result = await request(
+      `mutation($input:AddDiscussionCommentInput!){addDiscussionComment(input:$input){comment{${commentFields}}}}`,
+      { input: { discussionId: id, body } },
+    );
+    return result.addDiscussionComment.comment;
+  }
+  return { repository, list, get, comments, create, append };
+}
+
+export async function collectDiscussionPages(readPage, limit = 100) {
+  let cursor = null;
+  const nodes = [];
+  const cursors = new Set();
+  for (let page = 0; page < limit; page++) {
+    const result = await readPage(cursor);
+    if (!Array.isArray(result?.nodes) || !result.pageInfo)
+      throw new Error("Incomplete Discussion page");
+    nodes.push(...result.nodes);
+    if (Buffer.byteLength(JSON.stringify(nodes)) > 32 * 1024 * 1024)
+      throw new Error(
+        "Discussion read exceeds its byte bound; refusing an incomplete view",
+      );
+    if (!result.pageInfo.hasNextPage) return nodes;
+    cursor = result.pageInfo.endCursor;
+    if (!cursor || cursors.has(cursor))
+      throw new Error("Discussion pagination did not advance");
+    cursors.add(cursor);
+  }
+  throw new Error(
+    "Discussion page limit exceeded; refusing an incomplete transaction view",
+  );
+}

package/packages/core/publication/binary/action.js

@@ -1,3 +1,6 @@
+import { getOctokit } from "@actions/github";
+import { observeBinaryDistribution } from "../../release/discussion/binary.js";
+import { selectedRecordRuntime } from "../../release/discussion/session.js";
 import path from "node:path";
 import { verifyCheckoutIdentity } from "../../runtime/checkout-identity.js";
 import { releaseAssetClient } from "../../providers/github/release-assets.js";
@@ -13,17 +16,28 @@ export async function publishBinaryAssetsAction(core, env) {
   const client = releaseAssetClient(env.GITHUB_REPOSITORY, {
     token: core.getInput("token", { required: true }),
   });
-  const result = await publishBinaryAssets(
+  const result = await observeBinaryDistribution(
     {
-      workspace,
+      client,
+      octokit: getOctokit(core.getInput("token", { required: true })),
       repository: env.GITHUB_REPOSITORY,
-      sourceSha,
       tag: core.getInput("tag", { required: true }),
-      capability: JSON.parse(
-        core.getInput("capability-json", { required: true }),
-      ),
+      runtime: selectedRecordRuntime(env),
+      writer: `${env.GITHUB_RUN_ID}:${env.GITHUB_RUN_ATTEMPT}:${env.GITHUB_JOB}`,
     },
-    client,
+    () =>
+      publishBinaryAssets(
+        {
+          workspace,
+          repository: env.GITHUB_REPOSITORY,
+          sourceSha,
+          tag: core.getInput("tag", { required: true }),
+          capability: JSON.parse(
+            core.getInput("capability-json", { required: true }),
+          ),
+        },
+        client,
+      ),
   );
   core.info(
     `Verified ${result.assets.length} immutable binary assets for ${result.tag}`,

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

@@ -0,0 +1,65 @@
+import { discussionStatus } from "./reader.js";
+import * as github from "@actions/github";
+import { openReleaseSession, selectedRecordRuntime } from "./session.js";
+import { releaseDiscussionStore } from "./store.js";
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import { createProgress } from "./envelope.js";
+
+function actionStore(core) {
+  return releaseDiscussionStore(
+    discussionTransport(
+      github.getOctokit(core.getInput("token", { required: true })).graphql,
+    ),
+  );
+}
+
+export async function openDiscussionAction(core, env) {
+  const result = await openReleaseSession({
+    graphql: github.getOctokit(core.getInput("token", { required: true }))
+      .graphql,
+    repository: env.GITHUB_REPOSITORY,
+    key: core.getInput("intent-key", { required: true }),
+    source: JSON.parse(core.getInput("source-json", { required: true })),
+    expectedNodes: JSON.parse(
+      core.getInput("expected-nodes-json", { required: true }),
+    ),
+    runtime: selectedRecordRuntime(env),
+    attempt: `${env.GITHUB_RUN_ID}:${env.GITHUB_RUN_ATTEMPT}`,
+    discussionId: core.getInput("discussion-id"),
+    predecessor: core.getInput("predecessor"),
+    dryRun: core.getBooleanInput("dry-run"),
+  });
+  core.setOutput("session-json", JSON.stringify(result.session));
+  core.setOutput("discussion-id", result.session.discussion?.id || "");
+  core.setOutput("discussion-url", result.session.discussion?.url || "");
+}
+
+export async function recordDiscussionAction(core, env) {
+  const session = JSON.parse(core.getInput("session-json", { required: true }));
+  if (session.dryRun) return;
+  const record = createProgress({
+    intent: session.intent,
+    runtime: selectedRecordRuntime(env),
+    attempt: session.attempt,
+    writer: `${env.GITHUB_RUN_ID}:${env.GITHUB_RUN_ATTEMPT}:${env.GITHUB_JOB}`,
+    predecessor: session.predecessor,
+    node: core.getInput("node", { required: true }),
+    status: core.getInput("status", { required: true }),
+    sequence: Number(core.getInput("sequence")),
+    payload: JSON.parse(core.getInput("payload-json") || "{}"),
+  });
+  const result = await actionStore(core).append(session, record);
+  core.setOutput("record-id", result.id);
+}
+
+export async function inspectDiscussionAction(core) {
+  const session = JSON.parse(core.getInput("session-json", { required: true }));
+  if (session.dryRun) {
+    core.setOutput("status", "dry-run");
+    return;
+  }
+  const result = await actionStore(core).read(session);
+  core.setOutput("status", result.status);
+  core.setOutput("handoff-json", JSON.stringify(result.handoff || {}));
+  core.setOutput("state-json", JSON.stringify(discussionStatus(result)));
+}

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

@@ -0,0 +1,92 @@
+import { discussionTransport } from "../../providers/github/discussions/transport.js";
+import { releaseDiscussionStore } from "./store.js";
+import { createProgress, decodeRecord } from "./envelope.js";
+
+// An independent distribution workflow joins the existing intent after resolving
+// its public release locator. Capturing the attempt before execution keeps a late
+// result on its original attempt when another workflow starts recovery.
+export async function observeBinaryDistribution(
+  { client, octokit, repository, tag, runtime, writer },
+  effect,
+) {
+  const release = await client.release(tag);
+  const assets = release.assets.filter(
+    ({ name }) => name === "buildchain.release-transaction.json",
+  );
+  if (assets.length !== 1)
+    throw new Error(
+      "Binary distribution requires one release transaction locator",
+    );
+  const locator = JSON.parse(client.assetBytes(assets[0]));
+  if (
+    locator.schema !== "buildchain.release-locator/v1" ||
+    locator.repository !== repository ||
+    `v${locator.version}` !== tag
+  )
+    throw new Error("Binary transaction locator does not match its release");
+  const transport = discussionTransport(octokit.graphql);
+  const discussion = await transport.get(locator.discussionId);
+  const intent = decodeRecord(discussion.body);
+  if (
+    intent?.id !== locator.intent ||
+    intent.repository !== repository ||
+    discussion.author?.__typename !== "Bot" ||
+    discussion.author.login !== "github-actions"
+  )
+    throw new Error(
+      "Binary transaction intent does not match the consumer workflow",
+    );
+  const store = releaseDiscussionStore(transport);
+  const session = { discussion, intent, writerId: discussion.author.id };
+  const state = await store.read(session);
+  if (!state.attempt || !intent.expectedNodes.includes("binary-distribution"))
+    throw new Error(
+      "Binary distribution was not declared by this release intent",
+    );
+  const attemptRecord = state.records.find(
+    (record) => record.attempt === state.attempt,
+  );
+  const sequence =
+    Math.max(
+      -1,
+      ...state.records
+        .filter(
+          (record) =>
+            record.kind === "progress" &&
+            record.attempt === state.attempt &&
+            record.node === "binary-distribution",
+        )
+        .map((record) => record.sequence),
+    ) + 1;
+  const record = (status, offset, payload = {}) =>
+    store.append(
+      session,
+      createProgress({
+        intent,
+        runtime,
+        writer,
+        attempt: state.attempt,
+        predecessor: attemptRecord.predecessor,
+        node: "binary-distribution",
+        status,
+        sequence: sequence + offset,
+        payload,
+      }),
+    );
+  await record("running", 0);
+  let result;
+  try {
+    result = await effect();
+  } catch (error) {
+    try {
+      await record("failure", 1, {
+        code: String(error.code || "execution-failed"),
+      });
+    } catch (recordError) {
+      error.discussionRecordingError = recordError.message;
+    }
+    throw error;
+  }
+  await record("success", 1, { tag, assets: result.assets.length });
+  return result;
+}