@kungfu-tech/buildchain 3.0.5 → 3.0.6-alpha.0

package/scripts/release-propagation.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import {
   claimReleasePropagationWork,
@@ -15,6 +16,15 @@ import {
   resumeReleasePropagationWork,
   verifyReleasePropagationWork,
   writeReleasePropagationLock,
+  createManualUpstreamPickupCapture,
+  createManualUpstreamPickupPlan,
+  createReleasePropagationPushPlan,
+  executeReleasePropagationPush,
+  inspectReleasePropagationPushState,
+  normalizeManualUpstreamPickupConfig,
+  planSiteUpstreamAgentEntry,
+  RELEASE_PROPAGATION_FAILURE_MATRIX,
+  resolveNpmRegistryRelease,
 } from "../packages/core/release-propagation.js";
 
 function usage() {
@@ -61,6 +71,28 @@ function usage() {
                                               --completion-decision <json-or-path>
                                               --expected-work-root <sha256:...>
                                               [--output <file>] [--json]
+  buildchain release-propagation work push-plan --work <json-or-path>
+                                             --expected-work-root <sha256:...>
+                                             [--cwd <dir>] [--remote <name>]
+                                             [--output <file>] [--json]
+  buildchain release-propagation work push-branch --work <json-or-path>
+                                               --expected-work-root <sha256:...>
+                                               [--cwd <dir>] [--remote <name>]
+                                               --execute [--output <file>] [--json]
+  buildchain release-propagation entry plan --source-id <paper|kfd|buildchain|kungfu-core>
+                                            [--channel <alpha|release>]
+                                            [--handoff-work <json-or-path>]
+                                            [--output <file>] [--json]
+  buildchain release-propagation entry fault-matrix [--json]
+  buildchain release-propagation pickup plan --config <json-or-path>
+                                            --source-id <id> --channel <alpha|release>
+                                            --current-version <version>
+                                            [--output <file>] [--json]
+  buildchain release-propagation pickup create --config <json-or-path>
+                                              --source-id <id> --channel <alpha|release>
+                                              --current-version <version>
+                                              --expected-downstream-base-sha <git-sha>
+                                              [--output <file>] [--json]
 `;
 }
 
@@ -168,10 +200,115 @@ function runWorkCli(args) {
     emitWorkResult(workArgs, result, `release propagation work complete: ${result.contentRoot}`);
     return;
   }
+  if (mode === "push-plan" || mode === "push-branch") {
+    const work = readJsonFlag(workArgs, "work");
+    const cwd = readFlag(workArgs, "cwd", process.cwd());
+    const remote = readFlag(workArgs, "remote", "origin");
+    let result;
+    if (mode === "push-plan") {
+      const repositoryState = inspectReleasePropagationPushState({ work, cwd, remote });
+      result = createReleasePropagationPushPlan({
+        work,
+        expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+        repositoryState,
+      });
+    } else {
+      if (!hasFlag(workArgs, "execute")) throw new Error("work push-branch requires --execute");
+      result = executeReleasePropagationPush({
+        work,
+        expectedWorkRoot: readFlag(workArgs, "expected-work-root"),
+        cwd,
+        remote,
+      });
+    }
+    emitWorkResult(workArgs, result, mode === "push-plan"
+      ? `release propagation push plan: ${result.planRoot}`
+      : `release propagation push result: ${result.resultRoot}`);
+    return;
+  }
   throw new Error(`unsupported release-propagation work command: ${mode}`);
 }
 
-export function runReleasePropagationCli(argv = process.argv.slice(2)) {
+function runEntryCli(args) {
+  const [mode = "", ...entryArgs] = args;
+  if (!mode || mode === "--help" || mode === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  let result;
+  if (mode === "fault-matrix") {
+    result = RELEASE_PROPAGATION_FAILURE_MATRIX;
+  } else if (mode === "plan") {
+    result = planSiteUpstreamAgentEntry({
+      sourceId: readFlag(entryArgs, "source-id"),
+      channel: readFlag(entryArgs, "channel"),
+      handoffWork: entryArgs.includes("--handoff-work")
+        ? readJsonFlag(entryArgs, "handoff-work")
+        : null,
+    });
+  } else {
+    throw new Error(`unsupported release-propagation entry command: ${mode}`);
+  }
+  writeOutput(readFlag(entryArgs, "output", ""), result);
+  if (hasFlag(entryArgs, "json")) printJson(result);
+  else process.stdout.write(`${result.contract}\n`);
+}
+
+async function resolvePickupPlan(args) {
+  const config = normalizeManualUpstreamPickupConfig(readJsonFlag(args, "config"));
+  const sourceId = readFlag(args, "source-id");
+  const channel = readFlag(args, "channel");
+  const source = config.sources.find((entry) => entry.id === sourceId);
+  if (!source) throw new Error(`manual pickup source is not configured: ${sourceId}`);
+  const distTag = source.distTags[channel];
+  if (!distTag) throw new Error("manual pickup channel must be alpha or release");
+  const packageMetadata = args.includes("--package-metadata")
+    ? readJsonFlag(args, "package-metadata")
+    : JSON.parse(execFileSync("npm", ["view", `${source.package}@${distTag}`, "--json", "--registry=https://registry.npmjs.org/"], {
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+      }));
+  const attestationUrl = packageMetadata.dist?.attestations?.url;
+  if (!attestationUrl) throw new Error("published npm package does not expose an attestation URL");
+  let attestations;
+  if (args.includes("--attestations")) {
+    attestations = readJsonFlag(args, "attestations");
+  } else {
+    const response = await fetch(attestationUrl, { headers: { accept: "application/json" } });
+    if (!response.ok) throw new Error(`npm attestation lookup failed: HTTP ${response.status}`);
+    attestations = await response.json();
+  }
+  const upstreamRelease = resolveNpmRegistryRelease({ source, channel, packageMetadata, attestations });
+  return createManualUpstreamPickupPlan({
+    config,
+    sourceId,
+    channel,
+    currentVersion: readFlag(args, "current-version"),
+    upstreamRelease,
+  });
+}
+
+async function runPickupCli(args) {
+  const [mode = "", ...pickupArgs] = args;
+  if (!mode || mode === "--help" || mode === "-h") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (mode !== "plan" && mode !== "create") throw new Error(`unsupported release-propagation pickup command: ${mode}`);
+  const plan = await resolvePickupPlan(pickupArgs);
+  const result = mode === "create"
+    ? createManualUpstreamPickupCapture({
+        plan,
+        expectedDownstreamBaseSha: readFlag(pickupArgs, "expected-downstream-base-sha"),
+      })
+    : plan;
+  writeOutput(readFlag(pickupArgs, "output", ""), result);
+  if (hasFlag(pickupArgs, "json")) printJson(result);
+  else if (mode === "plan") process.stdout.write(`manual upstream pickup: ${plan.source.id} ${plan.currentVersion} -> ${plan.resolvedVersion} (${plan.status})\n`);
+  else process.stdout.write(`manual upstream pickup next action: ${result.nextAction}\n`);
+}
+
+export async function runReleasePropagationCli(argv = process.argv.slice(2)) {
   const [mode = "", ...args] = argv;
   if (!mode || mode === "--help" || mode === "-h") {
     process.stdout.write(usage());
@@ -206,6 +343,14 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
     runWorkCli(args);
     return;
   }
+  if (mode === "entry") {
+    runEntryCli(args);
+    return;
+  }
+  if (mode === "pickup") {
+    await runPickupCli(args);
+    return;
+  }
   if (mode === "write-lock") {
     const plan = readReleasePropagationJson(readFlag(args, "plan"), {
       label: "--plan",
@@ -259,5 +404,8 @@ export function runReleasePropagationCli(argv = process.argv.slice(2)) {
 }
 
 if (!process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT && process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  runReleasePropagationCli();
+  runReleasePropagationCli().catch((error) => {
+    console.error(`buildchain release-propagation: ${error.message}`);
+    process.exitCode = 1;
+  });
 }

package/scripts/run-lifecycle-core.mjs

@@ -28,6 +28,7 @@ import {
   parseExpectedArtifactsJson,
   validateExpectedArtifacts,
 } from "./build-contract-core.mjs";
+import { verifyCompilerCacheActivity } from "./compiler-cache-evidence.mjs";
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const buildchainCliCandidates = [
@@ -391,6 +392,22 @@ function writeDiagnosticsSidecarManifest(filePath, {
   return manifest;
 }
 
+export function verifyBuildLifecycleCompilerCacheActivity({
+  stageName = "",
+  executed = false,
+  cwd = process.cwd(),
+  env = process.env,
+  verifier = verifyCompilerCacheActivity,
+  frameworkLog,
+} = {}) {
+  if (stageName !== "build" || !executed) return undefined;
+  const activity = verifier({ cwd, env });
+  if (activity) {
+    frameworkLog?.info("compiler-cache.activity", { attributes: activity });
+  }
+  return activity;
+}
+
 export function runLifecycle({
   cwd = process.cwd(),
   stageName = "",
@@ -646,6 +663,13 @@ export function runLifecycle({
     throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
   }
 
+  const compilerCacheActivity = verifyBuildLifecycleCompilerCacheActivity({
+    stageName,
+    executed,
+    cwd: resolvedCwd,
+    frameworkLog,
+  });
+
   const shouldReadProcessSummary = Boolean(
     resolvedProcessSummaryPath
       && (fs.existsSync(resolvedProcessSummaryPath) || processSummaryRequired),
@@ -739,6 +763,7 @@ export function runLifecycle({
     fileCount: summary.fileCount,
   });
   observability.lifecycle = lifecycleObservability;
+  Object.assign(observability, { compilerCacheActivity });
   observability.diagnostics = {
     contract: BUILDCHAIN_DIAGNOSTICS_CONTRACT,
     path: relativeDiagnosticsPath,

package/scripts/site-capability-metadata.mjs

@@ -120,7 +120,7 @@ export function cliCommandMeta(id) {
     "release-dry-run": { group: "governance-versioning", purpose: "Explain what a channel merge would publish before the PR is merged." },
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
-    "release-propagation": { group: "site-and-propagation", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
+    "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },

package/scripts/stable-candidate-patrol.mjs

@@ -23,6 +23,20 @@ function bool(value, fallback = false) {
   return ["1", "true", "yes", "on"].includes(String(value).trim().toLowerCase());
 }
 
+function autoMergeMethod(value, fallback = "merge") {
+  const normalized = text(value || fallback).toLowerCase();
+  if (!["merge", "squash", "rebase"].includes(normalized)) {
+    throw new Error(
+      `mergeMethod must be merge, squash, or rebase, got ${value || "<empty>"}`,
+    );
+  }
+  return normalized;
+}
+
+function shouldEnableAutoMerge(options, pullRequest) {
+  return options.autoMerge && !pullRequest.auto_merge;
+}
+
 function list(value) {
   return [...new Set(String(value || "").split(/[\n,]+/).map((entry) => entry.trim()).filter(Boolean))];
 }
@@ -67,6 +81,7 @@ export function normalizeStableCandidatePatrolOptions(options = {}) {
     releaseNow: text(options.releaseNow ?? process.env.BUILDCHAIN_STABLE_PATROL_RELEASE_NOW).replace(/^v/, ""),
     autoPromote: bool(options.autoPromote ?? process.env.BUILDCHAIN_STABLE_PATROL_AUTO_PROMOTE, false),
     autoMerge: bool(options.autoMerge ?? process.env.BUILDCHAIN_STABLE_PATROL_AUTO_MERGE, false),
+    mergeMethod: autoMergeMethod(options.mergeMethod ?? process.env.BUILDCHAIN_STABLE_PATROL_MERGE_METHOD),
     dryRun: bool(options.dryRun ?? process.env.BUILDCHAIN_STABLE_PATROL_DRY_RUN, true),
     now: text(options.now ?? process.env.BUILDCHAIN_STABLE_PATROL_NOW) || new Date().toISOString(),
     outputPath: text(options.outputPath ?? process.env.BUILDCHAIN_STABLE_PATROL_OUTPUT_PATH) || ".buildchain/patrol/stable-candidate.json",
@@ -239,7 +254,9 @@ export async function runStableCandidatePatrol(optionsInput = {}, clientInput) {
           "The source-lock branch freezes the exact candidate; newer alpha publications do not alter this PR.",
         ].join("\n"),
       });
-      if (options.autoMerge) await client.enableAutoMerge(pullRequest);
+      if (shouldEnableAutoMerge(options, pullRequest)) {
+        await client.enableAutoMerge(pullRequest, options.mergeMethod);
+      }
       promotion.pullRequest = pullRequest;
       const storedCandidate = ledger.candidates.find((entry) => entry.version === selection.candidate.version);
       storedCandidate.promotionRequest = {
@@ -434,9 +451,18 @@ export function createGitHubStableCandidateClient({ repository: repositoryInput,
       const open = await api(`/repos/${owner}/${repo}/pulls?state=open&head=${encodeURIComponent(`${owner}:${head}`)}&base=${encodeURIComponent(base)}&per_page=20`);
       return open[0] || api(`/repos/${owner}/${repo}/pulls`, { method: "POST", body: { head, base, title, body } });
     },
-    async enableAutoMerge(pullRequest) {
-      const query = `mutation($id:ID!){enablePullRequestAutoMerge(input:{pullRequestId:$id,mergeMethod:MERGE}){pullRequest{url}}}`;
-      return api("/graphql", { method: "POST", body: { query, variables: { id: pullRequest.node_id } } });
+    async enableAutoMerge(pullRequest, mergeMethod) {
+      const query = `mutation($id:ID!,$mergeMethod:PullRequestMergeMethod!){enablePullRequestAutoMerge(input:{pullRequestId:$id,mergeMethod:$mergeMethod}){pullRequest{url}}}`;
+      return api("/graphql", {
+        method: "POST",
+        body: {
+          query,
+          variables: {
+            id: pullRequest.node_id,
+            mergeMethod: autoMergeMethod(mergeMethod).toUpperCase(),
+          },
+        },
+      });
     },
     async setVariable(name, value) {
       const current = await api(`/repos/${owner}/${repo}/actions/variables/${encodeURIComponent(name)}`, { allow404: true });

package/scripts/workflow-call-contract.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { evaluateWorkflowCallContract } from "../packages/core/workflow-call-contract.js";
+
+function usage() {
+  return `usage: node scripts/workflow-call-contract.mjs check \\
+  --caller-workflow <path> --job <id> --caller-repository <owner/repo> \\
+  --callee-root <checkout> --callee-workflow <path> --callee-repository <owner/repo> \\
+  --trusted-event <event[:type]> [--trusted-event ...] \\
+  [--expected-contract-root sha256:...] [--allow-dirty] [--output <path>]`;
+}
+
+function parseArgs(argv) {
+  const options = { trustedEvents: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--allow-dirty") {
+      options.allowDirty = true;
+      continue;
+    }
+    if (!arg.startsWith("--") || !argv[index + 1])
+      throw new Error(`invalid argument: ${arg}`);
+    const value = argv[index + 1];
+    index += 1;
+    if (arg === "--trusted-event") options.trustedEvents.push(value);
+    else
+      options[
+        arg.slice(2).replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+      ] = value;
+  }
+  return options;
+}
+
+function git(root, ...args) {
+  return execFileSync("git", ["-C", root, ...args], {
+    encoding: "utf8",
+  }).trim();
+}
+
+function required(options, names) {
+  const missing = names.filter((name) => !options[name]);
+  if (missing.length)
+    throw new Error(`missing required options: ${missing.join(", ")}`);
+}
+
+export function checkWorkflowCall(options) {
+  const callerRoot = path.resolve(options.callerRoot || process.cwd());
+  const calleeRoot = path.resolve(options.calleeRoot);
+  const callerStatus = git(
+    callerRoot,
+    "status",
+    "--porcelain",
+    "--untracked-files=no",
+  );
+  if (callerStatus && !options.allowDirty) {
+    throw new Error(
+      "caller checkout is dirty; use --allow-dirty only for local diagnostic validation",
+    );
+  }
+  const calleeStatus = git(
+    calleeRoot,
+    "status",
+    "--porcelain",
+    "--untracked-files=no",
+  );
+  if (calleeStatus) {
+    throw new Error("callee checkout is dirty; exact pinned-ref bytes are required");
+  }
+  const callerSha = git(callerRoot, "rev-parse", "HEAD");
+  const callerTree = git(callerRoot, "rev-parse", "HEAD^{tree}");
+  const calleeSha = git(calleeRoot, "rev-parse", "HEAD");
+  const report = evaluateWorkflowCallContract({
+    callerText: fs.readFileSync(
+      path.join(callerRoot, options.callerWorkflow),
+      "utf8",
+    ),
+    calleeText: fs.readFileSync(
+      path.join(calleeRoot, options.calleeWorkflow),
+      "utf8",
+    ),
+    callerRepository: options.callerRepository,
+    callerWorkflowPath: options.callerWorkflow,
+    callerSha,
+    callerTree,
+    callerSourceState: callerStatus ? "diagnostic-dirty" : "clean",
+    calleeRepository: options.calleeRepository,
+    calleeWorkflowPath: options.calleeWorkflow,
+    calleeSha,
+    jobId: options.job,
+    trustedEventClasses: options.trustedEvents,
+    expectedContractRoot: options.expectedContractRoot || "",
+  });
+  if (options.output) {
+    const output = path.resolve(callerRoot, options.output);
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`);
+  }
+  return report;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const command = argv.shift();
+  if (command !== "check") throw new Error(usage());
+  const options = parseArgs(argv);
+  required(options, [
+    "callerWorkflow",
+    "job",
+    "callerRepository",
+    "calleeRoot",
+    "calleeWorkflow",
+    "calleeRepository",
+  ]);
+  if (!options.trustedEvents.length)
+    throw new Error("at least one --trusted-event is required");
+  const report = checkWorkflowCall(options);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`workflow call contract: ${error.message}`);
+    process.exitCode = 1;
+  }
+}