@kungfu-tech/buildchain 2.13.0 → 2.14.0-alpha.0

package/packages/core/web-surface-publication-candidate.js

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+
+import { validateControllerReceipt } from "./controller-evidence.js";
+
+export const WEB_SURFACE_PUBLICATION_CANDIDATE_CONTRACT =
+  "kungfu-buildchain-web-surface-publication-candidate";
+export const WEB_SURFACE_PRODUCTION_DECISION_CONTRACT =
+  "kungfu-buildchain-web-surface-production-decision";
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function webSurfacePublicationDigest(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function normalizeDigest(value, label) {
+  const normalized = requiredString(value, label).replace(/^sha256:/, "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(normalized)) throw new Error(`${label} must be a sha256 digest`);
+  return normalized;
+}
+
+function normalizeGitSha(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(normalized)) {
+    throw new Error(`${label} must be a 40- or 64-character Git SHA`);
+  }
+  return normalized;
+}
+
+export function createWebSurfaceProductionDecision({
+  approved,
+  kind,
+  repository,
+  sourceSha,
+  actor,
+  actorPermission = "",
+  releasePr = 0,
+  releaseSource = "",
+  reason,
+} = {}) {
+  const normalizedKind = requiredString(kind, "kind");
+  if (!["manual-dispatch", "release-pr", "none"].includes(normalizedKind)) {
+    throw new Error(`unsupported web-surface production decision kind: ${normalizedKind}`);
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: WEB_SURFACE_PRODUCTION_DECISION_CONTRACT,
+    approved: approved === true,
+    kind: normalizedKind,
+    repository: requiredString(repository, "repository"),
+    sourceSha: normalizeGitSha(sourceSha, "sourceSha"),
+    actor: requiredString(actor, "actor"),
+    actorPermission: String(actorPermission || ""),
+    releasePr: Number(releasePr || 0),
+    releaseSource: String(releaseSource || ""),
+    reason: requiredString(reason, "reason"),
+  };
+  if (!Number.isSafeInteger(payload.releasePr) || payload.releasePr < 0) {
+    throw new Error("releasePr must be a non-negative safe integer");
+  }
+  return { ...payload, decisionDigest: webSurfacePublicationDigest(payload) };
+}
+
+export function createWebSurfacePublicationCandidate({
+  repository,
+  sourceSha,
+  sourceTreeSha,
+  runtimeSha,
+  plan,
+  planFileDigest,
+  controllerReceipt,
+  decision,
+} = {}) {
+  const normalizedRepository = requiredString(repository, "repository");
+  const normalizedSourceSha = normalizeGitSha(sourceSha, "sourceSha");
+  const normalizedSourceTreeSha = normalizeGitSha(sourceTreeSha, "sourceTreeSha");
+  const normalizedRuntimeSha = normalizeGitSha(runtimeSha, "runtimeSha");
+  if (plan?.contract !== "kungfu-buildchain-web-surface-deploy-plan") {
+    throw new Error("web-surface publication plan contract mismatch");
+  }
+  if (plan.channel !== "production" || plan.dryRun !== true) {
+    throw new Error("web-surface publication requires a production dry-run plan");
+  }
+  if (plan.manifest?.sourceSha !== normalizedSourceSha) {
+    throw new Error("web-surface publication plan source SHA mismatch");
+  }
+  const artifactHash = normalizeDigest(plan.artifact?.hash, "plan.artifact.hash");
+  if (normalizeDigest(plan.manifest?.artifactHash, "plan.manifest.artifactHash") !== artifactHash) {
+    throw new Error("web-surface publication plan artifact hash mismatch");
+  }
+  if (plan.manifest?.runtimeId && String(plan.manifest.runtimeId).toLowerCase() !== normalizedRuntimeSha) {
+    throw new Error("web-surface publication plan runtime SHA mismatch");
+  }
+  const canonicalPlanDigest = crypto
+    .createHash("sha256")
+    .update(`${JSON.stringify(plan, null, 2)}\n`)
+    .digest("hex");
+  if (normalizeDigest(planFileDigest, "planFileDigest") !== canonicalPlanDigest) {
+    throw new Error("web-surface publication plan file digest mismatch");
+  }
+  const controllerValidation = validateControllerReceipt(controllerReceipt, {
+    expectedSourceSha: normalizedSourceSha,
+    expectedRuntimeSha: normalizedRuntimeSha,
+  });
+  if (!controllerValidation.ok || !controllerValidation.qualifying) {
+    throw new Error(`web-surface publication controller receipt did not qualify: ${controllerValidation.issues.join("; ")}`);
+  }
+  const planEvidence = (controllerReceipt.evidence || []).filter(
+    (entry) => entry.kind === "web-surface-plan",
+  );
+  if (
+    planEvidence.length !== 1 ||
+    normalizeDigest(planEvidence[0].digest, "controllerReceipt.web-surface-plan.digest") !== canonicalPlanDigest
+  ) {
+    throw new Error("web-surface publication controller receipt plan evidence mismatch");
+  }
+  if (decision?.contract !== WEB_SURFACE_PRODUCTION_DECISION_CONTRACT || decision.approved !== true) {
+    throw new Error("web-surface production decision is not approved");
+  }
+  const { decisionDigest: suppliedDecisionDigest, ...decisionPayload } = decision;
+  const decisionDigest = webSurfacePublicationDigest(decisionPayload);
+  if (normalizeDigest(suppliedDecisionDigest, "decision.decisionDigest") !== decisionDigest) {
+    throw new Error("web-surface production decision digest mismatch");
+  }
+  if (decision.repository !== normalizedRepository || decision.sourceSha !== normalizedSourceSha) {
+    throw new Error("web-surface production decision source binding mismatch");
+  }
+  if (!["manual-dispatch", "release-pr"].includes(decision.kind)) {
+    throw new Error("web-surface production decision kind is not authorizing");
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: WEB_SURFACE_PUBLICATION_CANDIDATE_CONTRACT,
+    repository: normalizedRepository,
+    sourceSha: normalizedSourceSha,
+    sourceTreeSha: normalizedSourceTreeSha,
+    runtimeSha: normalizedRuntimeSha,
+    site: requiredString(plan.manifest?.site, "plan.manifest.site"),
+    environment: "production",
+    deployTarget: requiredString(plan.manifest?.deployTarget, "plan.manifest.deployTarget"),
+    artifactHash,
+    planDigest: canonicalPlanDigest,
+    controllerReceiptDigest: normalizeDigest(controllerReceipt.digest, "controllerReceipt.digest"),
+    decisionDigest,
+  };
+  return { ...payload, candidateDigest: webSurfacePublicationDigest(payload) };
+}

package/scripts/assemble-web-surface-publication-admission.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+import {
+  createPublicationAdmission,
+  createPublicationControlPlaneAudit,
+  createPublicationGateDecision,
+  createRunnerProvenance,
+  publicationGateAggregateBindings,
+  verifyPublicationAdmission,
+} from "../packages/core/publication-authority.js";
+import { createWebSurfacePublicationCandidate } from "../packages/core/web-surface-publication-candidate.js";
+
+function required(name) {
+  const value = String(process.env[name] || "").trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex");
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+async function sourceTree(repository, sourceSha, token) {
+  const response = await fetch(
+    `${required("GITHUB_API_URL")}/repos/${repository}/git/commits/${sourceSha}`,
+    {
+      headers: {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "x-github-api-version": "2022-11-28",
+      },
+    },
+  );
+  if (!response.ok) throw new Error(`could not resolve admitted source tree: GitHub API ${response.status}`);
+  return String((await response.json()).tree?.sha || "").toLowerCase();
+}
+
+function auditFact(id, value) {
+  return { id, status: "pass", digest: sha256(JSON.stringify(value)) };
+}
+
+function writeBundle(outputDir, values) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  for (const [name, value] of Object.entries(values)) {
+    fs.writeFileSync(path.join(outputDir, `${name}.json`), `${JSON.stringify(value, null, 2)}\n`);
+  }
+  if (process.env.GITHUB_OUTPUT) {
+    const output = fs.createWriteStream(process.env.GITHUB_OUTPUT, { flags: "a" });
+    for (const [name, value] of Object.entries(values)) {
+      output.write(`${name.replaceAll("_", "-")}-json=${JSON.stringify(value)}\n`);
+    }
+    output.write(`capability-digest=${values.capability.capabilityDigest}\n`);
+    output.end();
+  }
+}
+
+async function main() {
+  const repository = required("BUILDCHAIN_REPOSITORY");
+  const sourceSha = required("BUILDCHAIN_SOURCE_SHA").toLowerCase();
+  const runtimeRoot = process.env.BUILDCHAIN_RUNTIME_ROOT || ".buildchain/runtime";
+  const runtimeSha = execFileSync("git", ["-C", runtimeRoot, "rev-parse", "HEAD"], {
+    encoding: "utf8",
+  }).trim().toLowerCase();
+  const planPath = required("BUILDCHAIN_WEB_SURFACE_PLAN_PATH");
+  const plan = readJson(planPath);
+  const controllerReceipt = readJson(required("BUILDCHAIN_CONTROLLER_RECEIPT_PATH"));
+  const decision = JSON.parse(required("BUILDCHAIN_PRODUCTION_DECISION_JSON"));
+  const token = required("GITHUB_TOKEN");
+  const sourceTreeSha = await sourceTree(repository, sourceSha, token);
+  const planFileDigest = sha256(fs.readFileSync(planPath));
+  const candidate = createWebSurfacePublicationCandidate({
+    repository,
+    sourceSha,
+    sourceTreeSha,
+    runtimeSha,
+    plan,
+    planFileDigest,
+    controllerReceipt,
+    decision,
+  });
+  const environment = required("BUILDCHAIN_PUBLICATION_ENVIRONMENT");
+  const roleArn = required("BUILDCHAIN_PRODUCTION_ROLE_ARN");
+  if (!/^arn:[^:]+:iam::[0-9]{12}:role\/.+/.test(roleArn)) {
+    throw new Error("BUILDCHAIN_PRODUCTION_ROLE_ARN must be an AWS IAM role ARN");
+  }
+  if (process.env.GITHUB_ACTIONS !== "true" || process.env.RUNNER_ENVIRONMENT !== "github-hosted") {
+    throw new Error("managed web-surface publication requires an ephemeral GitHub-hosted Actions runner");
+  }
+  const workflowPath = ".github/workflows/.web-surface.yml";
+  const publisherWorkflowPath = workflowPath;
+  const issuedAt = new Date();
+  const controlPlaneAudit = createPublicationControlPlaneAudit({
+    repository,
+    workflowPath,
+    publisherWorkflowPath,
+    environment,
+    observedAt: issuedAt.toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+    facts: [
+      auditFact("actions-policy", { githubActions: true, sourceSha }),
+      auditFact("branch-policy", { decisionKind: decision.kind, decisionDigest: decision.decisionDigest }),
+      auditFact("environment-policy", { environment }),
+      auditFact("oidc-policy", { roleArnDigest: sha256(roleArn), authorization: "provider-at-transaction" }),
+      auditFact("publisher-policy", { workflowPath, publisherWorkflowPath }),
+      auditFact("runner-policy", { runnerEnvironment: process.env.RUNNER_ENVIRONMENT, runnerOs: process.env.RUNNER_OS }),
+    ],
+  });
+  const runnerProvenance = createRunnerProvenance({
+    runnerClass: "ephemeral",
+    os: required("RUNNER_OS"),
+    architecture: required("RUNNER_ARCH"),
+    imageDigest: sha256(`${process.env.ImageOS || "unknown"}|${process.env.ImageVersion || "unknown"}`),
+    measurementDigest: sha256([
+      process.env.GITHUB_WORKFLOW,
+      process.env.GITHUB_JOB,
+      process.env.GITHUB_RUN_ID,
+      process.env.GITHUB_RUN_ATTEMPT,
+      process.env.RUNNER_ENVIRONMENT,
+    ].join("|")),
+    isolation: "github-hosted-single-job",
+  });
+  const gateAggregate = createPublicationGateDecision({
+    sourceSha,
+    profile: "managed-web-surface-production",
+    required: false,
+    rationale: "The managed web-surface production lane has no project-specific Shifu Gate registry.",
+    policy: { scope: "managed-web-surface-production", repository },
+  });
+  const gateBindings = publicationGateAggregateBindings(gateAggregate);
+  const registry = readJson(path.join(runtimeRoot, "dist/site/publication-authority-registry.json"));
+  const target = `aws-role:${roleArn}#deploy:${candidate.deployTarget}`;
+  const admission = createPublicationAdmission({
+    registryDigest: registry.registryDigest,
+    workflowPath,
+    publisherWorkflowPath,
+    repository,
+    sourceSha,
+    runtimeSha,
+    contractDigest: controllerReceipt.runtime.contractDigest,
+    policyDigest: gateBindings.policyDigest,
+    gateRegistryDigest: gateBindings.registryDigest,
+    controllerReceiptDigest: controllerReceipt.digest,
+    runnerProvenanceDigest: runnerProvenance.receiptDigest,
+    controlPlaneAuditDigest: controlPlaneAudit.receiptDigest,
+    gateAggregateDigest: gateBindings.gateAggregateDigest,
+    environment,
+    product: candidate.site,
+    target,
+    version: sourceSha,
+    channel: "production",
+    artifactDigest: candidate.candidateDigest,
+    nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}:web-production`,
+    issuedAt: issuedAt.toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+  });
+  const bindingNames = [
+    "repository", "publisherWorkflowPath", "sourceSha", "runtimeSha", "contractDigest", "policyDigest",
+    "gateRegistryDigest", "controllerReceiptDigest", "gateAggregateDigest", "environment", "product",
+    "target", "version", "channel", "artifactDigest",
+  ];
+  const expected = Object.fromEntries(bindingNames.map((name) => [name, admission[name]]));
+  const capability = verifyPublicationAdmission({
+    admission,
+    registry,
+    runnerProvenance,
+    controlPlaneAudit,
+    publicationEvidence: {
+      webSurfaceCandidate: {
+        repository,
+        sourceSha,
+        sourceTreeSha,
+        runtimeSha,
+        plan,
+        planFileDigest,
+        controllerReceipt,
+        decision,
+      },
+      gateAggregate,
+    },
+    expected,
+  });
+  writeBundle(process.env.BUILDCHAIN_OUTPUT_DIR || ".buildchain/web-publication-authority", {
+    admission,
+    runner_provenance: runnerProvenance,
+    control_plane_audit: controlPlaneAudit,
+    gate_aggregate: gateAggregate,
+    expected,
+    candidate,
+    capability,
+  });
+}
+
+main().catch((error) => {
+  console.error(`assemble web-surface publication admission: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/check-action-bundles.mjs

@@ -0,0 +1,50 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const actionsRoot = path.join(root, "actions");
+const bundlePaths = readdirSync(actionsRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => path.join(actionsRoot, entry.name, "dist", "index.js"))
+  .filter((bundlePath) => {
+    try {
+      readFileSync(bundlePath);
+      return true;
+    } catch {
+      return false;
+    }
+  })
+  .sort();
+
+const before = new Map(
+  bundlePaths.map((bundlePath) => [bundlePath, readFileSync(bundlePath)]),
+);
+const pnpm = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+const build = spawnSync(
+  pnpm,
+  ["-r", "--filter", "./actions/**", "build"],
+  { cwd: root, stdio: "inherit" },
+);
+
+if (build.error) {
+  throw build.error;
+}
+if (build.status !== 0) {
+  process.exit(build.status ?? 1);
+}
+
+const changed = bundlePaths.filter(
+  (bundlePath) => !before.get(bundlePath).equals(readFileSync(bundlePath)),
+);
+if (changed.length > 0) {
+  console.error("Generated action bundles were stale before the build:");
+  for (const bundlePath of changed) {
+    console.error(`- ${path.relative(root, bundlePath)}`);
+  }
+  console.error("Commit the regenerated bundles and rerun pnpm run check.");
+  process.exit(1);
+}
+
+console.log(`action bundle integrity check passed (${bundlePaths.length} bundles)`);

package/scripts/dev-merge-queue.mjs

@@ -0,0 +1,257 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const RULESET_PREFIX = "Buildchain dev merge queue";
+
+function positiveInteger(value, label, fallback) {
+  const parsed = Number(value || fallback);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} is required`);
+  return normalized;
+}
+
+export function selectMergeQueueMethod(repositorySettings = {}) {
+  const candidates = [
+    ["MERGE", repositorySettings.allow_merge_commit],
+    ["SQUASH", repositorySettings.allow_squash_merge],
+    ["REBASE", repositorySettings.allow_rebase_merge],
+  ];
+  const selected = candidates.find(([, allowed]) => allowed === true)?.[0];
+  if (!selected) {
+    throw new Error("repository must allow at least one merge method before merge queue enablement");
+  }
+  return selected;
+}
+
+export function validateMergeGroupWorkflows(workflows = []) {
+  if (workflows.length === 0) {
+    throw new Error("at least one required workflow must be declared with --workflow");
+  }
+  const results = workflows.map(({ path: workflowPath, source }) => {
+    const hasPullRequest = /^\s{0,4}pull_request\s*:/m.test(source);
+    const hasMergeGroup = /^\s{0,4}merge_group\s*:/m.test(source);
+    const usesPullRequestPayload = /github\.event\.pull_request/.test(source);
+    return { path: workflowPath, hasPullRequest, hasMergeGroup, usesPullRequestPayload };
+  });
+  const invalid = results.filter((workflow) => !workflow.hasPullRequest || !workflow.hasMergeGroup);
+  if (invalid.length > 0) {
+    throw new Error(
+      `merge queue requires pull_request and merge_group triggers in every required workflow: ${invalid.map((entry) => entry.path).join(", ")}`,
+    );
+  }
+  const payloadBound = results.filter((workflow) => workflow.usesPullRequestPayload);
+  if (payloadBound.length > 0) {
+    throw new Error(
+      `merge queue workflows must not depend directly on github.event.pull_request: ${payloadBound.map((entry) => entry.path).join(", ")}`,
+    );
+  }
+  return results;
+}
+
+export function createDevMergeQueuePlan({
+  repository,
+  branch,
+  workflows,
+  protection,
+  repositorySettings,
+  rulesets = [],
+  checkResponseTimeoutMinutes = 120,
+  maxEntriesToBuild = 1,
+} = {}) {
+  const normalizedRepository = requiredString(repository, "repository");
+  const normalizedBranch = requiredString(branch, "branch");
+  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(normalizedBranch)) {
+    throw new Error(`branch must be a Buildchain dev channel, got '${normalizedBranch}'`);
+  }
+  const workflowChecks = validateMergeGroupWorkflows(workflows);
+  const mergeMethod = selectMergeQueueMethod(repositorySettings);
+  const requiredChecks = protection?.required_status_checks?.checks || [];
+  if (requiredChecks.length === 0) {
+    throw new Error(`protected branch ${normalizedBranch} must declare required status checks before merge queue enablement`);
+  }
+  const rulesetName = `${RULESET_PREFIX}: ${normalizedBranch}`;
+  const existingRuleset = rulesets.find((entry) => entry?.name === rulesetName);
+  const ruleset = {
+    name: rulesetName,
+    target: "branch",
+    enforcement: "active",
+    conditions: {
+      ref_name: {
+        include: [`refs/heads/${normalizedBranch}`],
+        exclude: [],
+      },
+    },
+    rules: [{
+      type: "merge_queue",
+      parameters: {
+        check_response_timeout_minutes: positiveInteger(checkResponseTimeoutMinutes, "check response timeout", 120),
+        grouping_strategy: "ALLGREEN",
+        max_entries_to_build: positiveInteger(maxEntriesToBuild, "max entries to build", 1),
+        max_entries_to_merge: 1,
+        merge_method: mergeMethod,
+        min_entries_to_merge: 1,
+        min_entries_to_merge_wait_minutes: 0,
+      },
+    }],
+  };
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-dev-merge-queue-policy",
+    repository: normalizedRepository,
+    branch: normalizedBranch,
+    ok: true,
+    workflowChecks,
+    before: {
+      strict: protection.required_status_checks?.strict === true,
+      requiredStatusChecks: requiredChecks.map((check) => check.context),
+      rulesetId: existingRuleset?.id || null,
+    },
+    desired: {
+      strict: false,
+      requiredStatusChecks: requiredChecks.map((check) => check.context),
+      mergeMethod,
+      ruleset,
+    },
+    operations: [
+      {
+        method: existingRuleset ? "PUT" : "POST",
+        endpoint: existingRuleset
+          ? `repos/${normalizedRepository}/rulesets/${existingRuleset.id}`
+          : `repos/${normalizedRepository}/rulesets`,
+        body: ruleset,
+      },
+      {
+        method: "PATCH",
+        endpoint: `repos/${normalizedRepository}/branches/${encodeURIComponent(normalizedBranch)}/protection/required_status_checks`,
+        body: { strict: false, checks: requiredChecks },
+      },
+    ],
+  };
+}
+
+export async function reconcileDevMergeQueue({
+  api,
+  repository,
+  branch,
+  workflows,
+  apply = false,
+  checkResponseTimeoutMinutes = 120,
+  maxEntriesToBuild = 1,
+} = {}) {
+  const encodedBranch = encodeURIComponent(requiredString(branch, "branch"));
+  const repositorySettings = await api.request("GET", `repos/${repository}`);
+  const protection = await api.request("GET", `repos/${repository}/branches/${encodedBranch}/protection`);
+  const rulesets = await api.request("GET", `repos/${repository}/rulesets?includes_parents=false&per_page=100`);
+  const plan = createDevMergeQueuePlan({
+    repository,
+    branch,
+    workflows,
+    protection,
+    repositorySettings,
+    rulesets,
+    checkResponseTimeoutMinutes,
+    maxEntriesToBuild,
+  });
+  if (!apply) return { ...plan, action: "planned", applied: false };
+  const results = [];
+  for (const operation of plan.operations) {
+    results.push(await api.request(operation.method, operation.endpoint, operation.body));
+  }
+  return {
+    ...plan,
+    action: plan.before.rulesetId ? "updated" : "created",
+    applied: true,
+    after: {
+      strict: false,
+      rulesetId: results[0]?.id || plan.before.rulesetId || null,
+    },
+  };
+}
+
+function createGhApi() {
+  return {
+    request(method, endpoint, body) {
+      const args = [
+        "api",
+        "--method",
+        method,
+        endpoint,
+        "-H",
+        "Accept: application/vnd.github+json",
+        "-H",
+        "X-GitHub-Api-Version: 2026-03-10",
+      ];
+      if (body !== undefined) args.push("--input", "-");
+      const result = spawnSync("gh", args, {
+        encoding: "utf8",
+        input: body === undefined ? undefined : `${JSON.stringify(body)}\n`,
+        env: process.env,
+      });
+      if (result.error) throw result.error;
+      if (result.status !== 0) {
+        throw new Error(`GitHub API ${method} ${endpoint} failed: ${String(result.stderr || "").trim()}`);
+      }
+      const output = String(result.stdout || "").trim();
+      return output ? JSON.parse(output) : {};
+    },
+  };
+}
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+function readRepeatedFlag(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === `--${name}` && args[index + 1]) {
+      values.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+}
+
+function loadWorkflowSources(cwd, workflowPaths) {
+  return workflowPaths.map((workflowPath) => {
+    const absolutePath = path.resolve(cwd, workflowPath);
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+      throw new Error(`required workflow not found: ${workflowPath}`);
+    }
+    return { path: workflowPath, source: fs.readFileSync(absolutePath, "utf8") };
+  });
+}
+
+async function main(args = process.argv.slice(2)) {
+  const cwd = path.resolve(readFlag(args, "cwd", process.cwd()));
+  const repository = readFlag(args, "repository", process.env.GITHUB_REPOSITORY || "");
+  const branch = readFlag(args, "branch", "");
+  const workflows = loadWorkflowSources(cwd, readRepeatedFlag(args, "workflow"));
+  const result = await reconcileDevMergeQueue({
+    api: createGhApi(),
+    repository,
+    branch,
+    workflows,
+    apply: args.includes("--apply"),
+    checkResponseTimeoutMinutes: readFlag(args, "check-response-timeout-minutes", "120"),
+    maxEntriesToBuild: readFlag(args, "max-entries-to-build", "1"),
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`buildchain dev merge-queue: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/generate-site-bundle.mjs

@@ -435,6 +435,8 @@ function cliCommandMeta(id) {
     "kfd-upstream-collect": { group: "kfd-trust", purpose: "Collect declared KFD-aware upstream package evidence and hashes from Buildchain config." },
     "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
     lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
+    dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
+    "dev-merge-queue": { group: "governance-versioning", purpose: "Plan or apply an exact-branch GitHub merge queue after required workflow event compatibility is verified." },
     log: { group: "observability-diagnostics", purpose: "Inspect Buildchain logging command families." },
     logging: { group: "observability-diagnostics", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
     mark: { group: "observability-diagnostics", purpose: "Emit a single Buildchain log event." },