@kungfu-tech/buildchain 2.4.4 → 2.4.5-alpha.1

package/README.md

@@ -106,6 +106,23 @@ writeDiagnosticsArtifact(".buildchain/artifacts/diagnostics.json", {
 platform manifest. It includes lifecycle-wide observability, runner/tool/cache
 snapshots, Git state, and links to the larger manifest and artifact outputs.
 
+Consumers can report Buildchain-owned workflow failures directly to the
+Buildchain repository with a scoped issue-write token:
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2
+  if: failure()
+  with:
+    token: ${{ steps.buildchain-issue-token.outputs.token }}
+    summary: "Reusable build failed before artifact finalization"
+    failure-code: reusable-build-failed
+    buildchain-ref: v2
+    diagnostics-path: .buildchain/artifacts/diagnostics.json
+```
+
+The action deduplicates by fingerprint, comments on existing open reports, and
+is fail-soft by default so issue reporting does not hide the original failure.
+
 ## Use Buildchain
 
 Bootstrap a repository:
@@ -125,6 +142,7 @@ Buildchain's active GitHub Action surface is deliberately small:
 - `actions/validate-config`
 - `actions/run-lifecycle`
 - `actions/promote-buildchain-ref`
+- `actions/report-buildchain-issue`
 
 The active reusable workflow surfaces are:
 
@@ -234,5 +252,6 @@ npm pack --dry-run --json --registry=https://registry.npmjs.org/
 - [Site bundle contract](docs/site-bundle-contract.md)
 - [Lifecycle protocol](docs/lifecycle-protocol.md)
 - [Reusable build surface](docs/reusable-build-surface.md)
+- [Consumer issue reporting](docs/consumer-issue-reporting.md)
 - [Publish transaction](docs/publish-transaction.md)
 - [Release governance](docs/release-governance.md)

package/actions/report-buildchain-issue/README.md

@@ -0,0 +1,46 @@
+# report-buildchain-issue
+
+Create or update a Buildchain repository issue from a consumer workflow.
+
+This action is intended for consumer repositories that need to report
+Buildchain-owned failures with enough evidence for maintainers to act. It
+requires a token that can write issues on the target Buildchain repository.
+For cross-repository consumers, generate that token with a GitHub App
+installation token or another scoped credential owned by the consumer
+organization.
+
+```yaml
+- uses: actions/create-github-app-token@v2
+  id: buildchain-issue-token
+  with:
+    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
+    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
+    owner: kungfu-systems
+    repositories: buildchain
+
+- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2
+  if: failure()
+  with:
+    token: ${{ steps.buildchain-issue-token.outputs.token }}
+    summary: "Reusable build failed before artifact finalization"
+    failure-code: reusable-build-failed
+    buildchain-ref: ${{ inputs.buildchain-ref || 'v2' }}
+    diagnostics-path: .buildchain/artifacts/diagnostics.json
+```
+
+The action computes a stable fingerprint from the consumer repository,
+workflow, job, failure code, and Buildchain ref. When an open issue already
+exists for that fingerprint, it comments with the new run instead of opening a
+duplicate issue.
+
+By default issue reporting is fail-soft:
+
+- `fail-on-error: "false"` prevents a reporting outage from hiding the original
+  build failure.
+- transient GitHub API 429/5xx errors and connection failures are retried.
+- if a configured label is missing, issue creation is retried without labels.
+- common token, private-key, password, and authorization values are redacted
+  before submission.
+
+Use `dry-run: "true"` to verify the computed fingerprint and body shape without
+calling GitHub.

package/dist/site/release-provenance.json

@@ -11,6 +11,7 @@
       ".": "./packages/core/index.js",
       "./core": "./packages/core/index.js",
       "./diagnostics": "./packages/core/diagnostics.js",
+      "./issue-reporting": "./packages/core/issue-reporting.js",
       "./logging": "./packages/core/logging.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",

package/docs/MAP.md

@@ -38,7 +38,8 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
-| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md) | use | stable |
+| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
+| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |
 | What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md) | verify | stable |
 | What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |
 | How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |
@@ -64,6 +65,8 @@ running artifact), *use* (consume / extend) - and a **status**:
 - **runtime train validation / temporary `buildchain-ref` override** ->
   [`runtime-train-validation.md`](runtime-train-validation.md) and
   [`reusable-build-surface.md`](reusable-build-surface.md).
+- **consumer workflow feedback / automatic Buildchain GitHub issues** ->
+  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).
 - **infra contract / observed infrastructure outputs / downstream contract propagation** ->
   [`infra-contract.md`](infra-contract.md).
 - **standalone binary install / platform archives / GitHub Release bundle** ->

package/docs/consumer-issue-reporting.md

@@ -0,0 +1,82 @@
+# Consumer Issue Reporting
+
+Buildchain ships a first-class issue reporting surface for consumer workflows.
+It lets a repository open or update a Buildchain-owned GitHub issue when a
+Buildchain reusable workflow, action, or toolkit API produces a failure that
+needs Buildchain maintainers.
+
+## Trust model
+
+The consumer workflow must provide a token with issue-write access to the
+target repository. A repository's default `GITHUB_TOKEN` only writes to its own
+repository, so cross-repository reports should use a GitHub App installation
+token scoped to:
+
+- the `kungfu-systems/buildchain` repository;
+- Issues: read and write;
+- no content write permission unless another workflow step needs it.
+
+The recommended pattern is:
+
+```yaml
+- uses: actions/create-github-app-token@v2
+  id: buildchain-issue-token
+  with:
+    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
+    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
+    owner: kungfu-systems
+    repositories: buildchain
+
+- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2
+  if: failure()
+  with:
+    token: ${{ steps.buildchain-issue-token.outputs.token }}
+    summary: "Buildchain reusable build failed before artifact finalization"
+    failure-code: reusable-build-failed
+    diagnostics-path: .buildchain/artifacts/diagnostics.json
+    buildchain-ref: ${{ inputs.buildchain-ref || 'v2' }}
+```
+
+## Behavior
+
+`report-buildchain-issue` builds an issue body with consumer repository,
+workflow, ref, SHA, Buildchain ref/version, diagnostics links, and optional
+details. It computes a stable fingerprint and embeds a hidden marker:
+
+```text
+buildchain-consumer-issue:fingerprint=<sha256-prefix>
+```
+
+When an open issue with the same marker exists, the action comments on it with
+the new run evidence. Otherwise it creates a new issue. Consumers may pass an
+explicit `fingerprint` when they need a different dedupe boundary.
+
+The action is fail-soft by default. It retries GitHub API 429/5xx responses and
+connection failures, redacts common secret/token/private-key patterns, truncates
+large bodies, and retries issue creation without labels if the target
+repository does not have the configured labels yet.
+
+Set `fail-on-error: "true"` only when the reporting step is part of a release
+gate and missing Buildchain feedback should stop the workflow.
+
+## JavaScript API
+
+Consumer scripts can import the same implementation:
+
+```js
+import {
+  buildConsumerIssueReport,
+  reportBuildchainIssue,
+} from "@kungfu-tech/buildchain/issue-reporting";
+
+const result = await reportBuildchainIssue({
+  token: process.env.BUILDCHAIN_ISSUE_TOKEN,
+  summary: "Native artifact manifest is incomplete",
+  failureCode: "native-manifest-incomplete",
+  buildchainRef: "v2",
+  diagnosticsPath: ".buildchain/artifacts/diagnostics.json",
+});
+```
+
+Use `buildConsumerIssueReport` for dry-run validation, previewing redaction, or
+unit tests without calling GitHub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.4.4",
+  "version": "2.4.5-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -14,6 +14,7 @@
     ".": "./packages/core/index.js",
     "./core": "./packages/core/index.js",
     "./diagnostics": "./packages/core/diagnostics.js",
+    "./issue-reporting": "./packages/core/issue-reporting.js",
     "./logging": "./packages/core/logging.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
@@ -42,6 +43,7 @@
     "docs/cli.md",
     "docs/install.md",
     "docs/infra-contract.md",
+    "docs/consumer-issue-reporting.md",
     "docs/lifecycle-protocol.md",
     "docs/migration-inventory.md",
     "docs/ownership.md",

package/packages/core/index.js

@@ -104,3 +104,19 @@ export {
   validateKnownReleasePassportContracts,
   verifyReleasePassport,
 } from "./release-passport.js";
+
+export {
+  BUILDCHAIN_CONSUMER_ISSUE_CONTRACT,
+  DEFAULT_BUILDCHAIN_ISSUE_REPOSITORY,
+  GitHubIssueRequestError,
+  buildConsumerIssueReport,
+  computeConsumerIssueFingerprint,
+  consumerIssueMarker,
+  createGitHubIssueRequest,
+  normalizeIssueRepository,
+  parseIssueLabels,
+  readOptionalIssueBodyFile,
+  redactIssueText,
+  reportBuildchainIssue,
+  truncateUtf8,
+} from "./issue-reporting.js";

package/packages/core/issue-reporting.js

@@ -0,0 +1,388 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+export const BUILDCHAIN_CONSUMER_ISSUE_CONTRACT = "kungfu-buildchain-consumer-issue";
+export const DEFAULT_BUILDCHAIN_ISSUE_REPOSITORY = "kungfu-systems/buildchain";
+
+const DEFAULT_LABELS = ["buildchain-consumer-feedback"];
+const DEFAULT_MAX_BODY_BYTES = 60_000;
+const DEFAULT_RETRY_DELAYS_MS = [500, 1_500, 3_000];
+
+const SECRET_PATTERNS = [
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bgh[oprsu]_[A-Za-z0-9_]{20,}\b/g,
+  /\b[A-Z0-9]{20}:[A-Za-z0-9_=-]{20,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /(authorization\s*:\s*)(bearer\s+)?[^\s]+/gi,
+  /(token|secret|password|private[_-]?key)(\s*[:=]\s*)[^\s"'`]+/gi,
+  /-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/g,
+];
+
+export class GitHubIssueRequestError extends Error {
+  constructor(message, { status, response, body } = {}) {
+    super(message);
+    this.name = "GitHubIssueRequestError";
+    this.status = status;
+    this.response = response;
+    this.body = body;
+  }
+}
+
+export function normalizeIssueRepository(repository = DEFAULT_BUILDCHAIN_ISSUE_REPOSITORY) {
+  const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`Invalid GitHub repository: ${repository}`);
+  }
+  return { owner: match[1], repo: match[2], fullName: `${match[1]}/${match[2]}` };
+}
+
+export function parseIssueLabels(input = DEFAULT_LABELS) {
+  if (Array.isArray(input)) {
+    return input.map((label) => String(label).trim()).filter(Boolean);
+  }
+  return String(input || "")
+    .split(/[,\n]/)
+    .map((label) => label.trim())
+    .filter(Boolean);
+}
+
+export function redactIssueText(value) {
+  let text = String(value ?? "");
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, (...args) => {
+      if (args.length >= 4 && typeof args[1] === "string" && typeof args[2] === "string") {
+        return `${args[1]}${args[2]}[REDACTED]`;
+      }
+      return "[REDACTED]";
+    });
+  }
+  return text;
+}
+
+export function computeConsumerIssueFingerprint(fields = {}) {
+  const normalized = {};
+  for (const key of Object.keys(fields).sort()) {
+    const value = fields[key];
+    if (value === undefined || value === null || value === "") {
+      continue;
+    }
+    normalized[key] = String(value);
+  }
+  return crypto.createHash("sha256").update(JSON.stringify(normalized)).digest("hex").slice(0, 32);
+}
+
+export function consumerIssueMarker(fingerprint) {
+  return `buildchain-consumer-issue:fingerprint=${fingerprint}`;
+}
+
+export function truncateUtf8(text, maxBytes = DEFAULT_MAX_BODY_BYTES) {
+  const value = String(text ?? "");
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0 || Buffer.byteLength(value, "utf8") <= maxBytes) {
+    return value;
+  }
+  const suffix = "\n\n[buildchain truncated issue body]\n";
+  const budget = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+  let output = "";
+  let used = 0;
+  for (const char of value) {
+    const bytes = Buffer.byteLength(char, "utf8");
+    if (used + bytes > budget) {
+      break;
+    }
+    output += char;
+    used += bytes;
+  }
+  return `${output}${suffix}`;
+}
+
+export function buildConsumerIssueReport(options = {}) {
+  const target = normalizeIssueRepository(options.targetRepository);
+  const env = options.env || process.env;
+  const consumerRepository = options.consumerRepository || env.GITHUB_REPOSITORY || "";
+  const runId = options.runId || env.GITHUB_RUN_ID || "";
+  const runUrl = options.runUrl || githubRunUrl(env, consumerRepository, runId);
+  const workflow = options.workflow || env.GITHUB_WORKFLOW || "";
+  const job = options.job || env.GITHUB_JOB || "";
+  const consumerRef = options.consumerRef || env.GITHUB_REF || "";
+  const consumerSha = options.consumerSha || env.GITHUB_SHA || "";
+  const failureCode = options.failureCode || "consumer-report";
+  const fingerprint =
+    options.fingerprint ||
+    computeConsumerIssueFingerprint({
+      targetRepository: target.fullName,
+      consumerRepository,
+      workflow,
+      job,
+      failureCode,
+      buildchainRef: options.buildchainRef,
+      buildchainVersion: options.buildchainVersion,
+      title: options.title,
+    });
+  const title = redactIssueText(
+    options.title ||
+      `[Buildchain consumer] ${consumerRepository || "unknown repository"}: ${failureCode}`,
+  );
+  const marker = consumerIssueMarker(fingerprint);
+  const body = truncateUtf8(
+    redactIssueText(
+      [
+        `<!-- ${marker} -->`,
+        `# Buildchain consumer report`,
+        ``,
+        options.summary ? `## Summary\n\n${options.summary}` : "",
+        `## Consumer`,
+        ``,
+        `- Repository: ${consumerRepository || "(unknown)"}`,
+        `- Ref: ${consumerRef || "(unknown)"}`,
+        `- SHA: ${consumerSha || "(unknown)"}`,
+        `- Workflow: ${workflow || "(unknown)"}`,
+        `- Job: ${job || "(unknown)"}`,
+        `- Run: ${runUrl || runId || "(unknown)"}`,
+        ``,
+        `## Buildchain`,
+        ``,
+        `- Ref: ${options.buildchainRef || "(unknown)"}`,
+        `- Version: ${options.buildchainVersion || "(unknown)"}`,
+        `- Failure code: ${failureCode}`,
+        `- Fingerprint: ${fingerprint}`,
+        ``,
+        optionalLine("## Release Passport", options.passportUrl || options.passportPath),
+        optionalLine("## Diagnostics", options.diagnosticsUrl || options.diagnosticsPath),
+        optionalLine("## Artifact", options.artifactUrl),
+        options.body ? `## Details\n\n${options.body}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    ),
+    Number(options.maxBodyBytes || DEFAULT_MAX_BODY_BYTES),
+  );
+  const commentBody = truncateUtf8(
+    redactIssueText(
+      [
+        `New matching Buildchain consumer report observed.`,
+        ``,
+        `- Repository: ${consumerRepository || "(unknown)"}`,
+        `- Ref: ${consumerRef || "(unknown)"}`,
+        `- SHA: ${consumerSha || "(unknown)"}`,
+        `- Workflow: ${workflow || "(unknown)"}`,
+        `- Run: ${runUrl || runId || "(unknown)"}`,
+        `- Failure code: ${failureCode}`,
+        `- Fingerprint: ${fingerprint}`,
+        options.summary ? `\n${options.summary}` : "",
+      ].join("\n"),
+    ),
+    Number(options.maxBodyBytes || DEFAULT_MAX_BODY_BYTES),
+  );
+  return {
+    contract: BUILDCHAIN_CONSUMER_ISSUE_CONTRACT,
+    targetRepository: target.fullName,
+    fingerprint,
+    marker,
+    title,
+    body,
+    commentBody,
+    labels: parseIssueLabels(options.labels ?? DEFAULT_LABELS),
+  };
+}
+
+export async function reportBuildchainIssue(options = {}) {
+  const report = buildConsumerIssueReport(options);
+  const target = normalizeIssueRepository(report.targetRepository);
+  const mode = options.mode || "create-or-comment";
+  if (options.dryRun) {
+    return {
+      ok: true,
+      action: "dry-run",
+      created: false,
+      commented: false,
+      issueNumber: "",
+      issueUrl: "",
+      fingerprint: report.fingerprint,
+      report,
+    };
+  }
+  if (!["create", "create-or-comment", "comment"].includes(mode)) {
+    throw new Error(`Unsupported consumer issue mode: ${mode}`);
+  }
+  const request = options.request || createGitHubIssueRequest(options);
+  const existing = mode === "create" ? undefined : await findOpenConsumerIssue({ request, target, report });
+  if (existing) {
+    if (mode !== "create-or-comment" && mode !== "comment") {
+      return {
+        ok: true,
+        action: "found",
+        created: false,
+        commented: false,
+        issueNumber: existing.number,
+        issueUrl: existing.html_url || existing.url || "",
+        fingerprint: report.fingerprint,
+        report,
+      };
+    }
+    await request({
+      method: "POST",
+      path: `/repos/${target.owner}/${target.repo}/issues/${existing.number}/comments`,
+      body: { body: report.commentBody },
+    });
+    return {
+      ok: true,
+      action: "commented",
+      created: false,
+      commented: true,
+      issueNumber: existing.number,
+      issueUrl: existing.html_url || existing.url || "",
+      fingerprint: report.fingerprint,
+      report,
+    };
+  }
+  if (mode === "comment") {
+    throw new Error(`No open Buildchain consumer issue found for fingerprint ${report.fingerprint}`);
+  }
+  const issue = await createIssueWithLabelFallback({ request, target, report });
+  return {
+    ok: true,
+    action: "created",
+    created: true,
+    commented: false,
+    issueNumber: issue.number,
+    issueUrl: issue.html_url || issue.url || "",
+    fingerprint: report.fingerprint,
+    report,
+  };
+}
+
+export function readOptionalIssueBodyFile(filePath) {
+  const resolved = String(filePath || "").trim();
+  if (!resolved) {
+    return "";
+  }
+  return fs.readFileSync(resolved, "utf8");
+}
+
+export function createGitHubIssueRequest({
+  token,
+  apiUrl = process.env.GITHUB_API_URL || "https://api.github.com",
+  fetchImpl = globalThis.fetch,
+  retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
+} = {}) {
+  if (!token) {
+    throw new Error("A GitHub token is required to report a Buildchain issue");
+  }
+  if (typeof fetchImpl !== "function") {
+    throw new Error("A fetch implementation is required to report a Buildchain issue");
+  }
+  const baseUrl = String(apiUrl || "https://api.github.com").replace(/\/+$/, "");
+  return async function githubIssueRequest({ method = "GET", path, body }) {
+    const url = `${baseUrl}${path}`;
+    let attempt = 0;
+    while (true) {
+      try {
+        const response = await fetchImpl(url, {
+          method,
+          headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+            "x-github-api-version": "2022-11-28",
+          },
+          body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        const parsed = text ? parseJsonResponse(text) : {};
+        if (response.ok) {
+          return parsed;
+        }
+        const retryAfterMs = retryAfterHeaderMs(response.headers?.get?.("retry-after"));
+        if (shouldRetryStatus(response.status) && attempt < retryDelaysMs.length) {
+          await sleep(retryAfterMs ?? retryDelaysMs[attempt]);
+          attempt += 1;
+          continue;
+        }
+        throw new GitHubIssueRequestError(
+          `GitHub API ${method} ${path} failed with ${response.status}: ${parsed.message || text}`,
+          { status: response.status, response: parsed, body },
+        );
+      } catch (error) {
+        if (error instanceof GitHubIssueRequestError) {
+          throw error;
+        }
+        if (attempt < retryDelaysMs.length) {
+          await sleep(retryDelaysMs[attempt]);
+          attempt += 1;
+          continue;
+        }
+        throw new GitHubIssueRequestError(`GitHub API ${method} ${path} failed: ${error.message}`, {
+          body,
+        });
+      }
+    }
+  };
+}
+
+async function findOpenConsumerIssue({ request, target, report }) {
+  const query = encodeURIComponent(
+    `repo:${target.fullName} is:issue is:open "${consumerIssueMarker(report.fingerprint)}"`,
+  );
+  const result = await request({ method: "GET", path: `/search/issues?q=${query}&per_page=1` });
+  const items = Array.isArray(result.items) ? result.items : [];
+  return items[0];
+}
+
+async function createIssueWithLabelFallback({ request, target, report }) {
+  const payload = {
+    title: report.title,
+    body: report.body,
+  };
+  if (report.labels.length > 0) {
+    payload.labels = report.labels;
+  }
+  try {
+    return await request({
+      method: "POST",
+      path: `/repos/${target.owner}/${target.repo}/issues`,
+      body: payload,
+    });
+  } catch (error) {
+    if (error?.status === 422 && payload.labels) {
+      return await request({
+        method: "POST",
+        path: `/repos/${target.owner}/${target.repo}/issues`,
+        body: { title: payload.title, body: payload.body },
+      });
+    }
+    throw error;
+  }
+}
+
+function optionalLine(title, value) {
+  return value ? `${title}\n\n${value}` : "";
+}
+
+function githubRunUrl(env, repository, runId) {
+  if (!repository || !runId) {
+    return "";
+  }
+  const server = env.GITHUB_SERVER_URL || "https://github.com";
+  return `${server}/${repository}/actions/runs/${runId}`;
+}
+
+function parseJsonResponse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+function shouldRetryStatus(status) {
+  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+
+function retryAfterHeaderMs(value) {
+  const seconds = Number(value || "");
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined;
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/scripts/check-inventory.mjs

@@ -17,6 +17,7 @@ const requiredPaths = [
   "docs/MAP.md",
   "docs/binary-distribution.md",
   "docs/cli.md",
+  "docs/consumer-issue-reporting.md",
   "docs/install.md",
   "docs/product-mechanism.md",
   "docs/release-passport.md",
@@ -69,6 +70,9 @@ if (rootPackage.exports?.["."] !== "./packages/core/index.js") {
 if (rootPackage.exports?.["./diagnostics"] !== "./packages/core/diagnostics.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/diagnostics");
 }
+if (rootPackage.exports?.["./issue-reporting"] !== "./packages/core/issue-reporting.js") {
+  throw new Error("root package must export @kungfu-tech/buildchain/issue-reporting");
+}
 if (rootPackage.exports?.["./logging"] !== "./packages/core/logging.js") {
   throw new Error("root package must export @kungfu-tech/buildchain/logging");
 }
@@ -108,6 +112,9 @@ if (!coreIndexSource.includes("verifyBuildchainLogEvents")) {
 if (!coreIndexSource.includes("collectBuildchainDiagnostics")) {
   throw new Error("packages/core/index.js must export collectBuildchainDiagnostics");
 }
+if (!coreIndexSource.includes("reportBuildchainIssue")) {
+  throw new Error("packages/core/index.js must export reportBuildchainIssue");
+}
 for (const requiredSnippet of [
   "Release passport and binary distribution are a minor surface.",
   "`v2.2`",