@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/observability/cli/events.mjs

@@ -0,0 +1,126 @@
+import { spawn, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import {
+  createBuildchainLogger,
+  defaultBuildchainLogPath,
+  summarizeBuildchainLogEvents,
+} from "../logging.js";
+import {
+  printJson,
+  readBooleanFlag,
+  readFlag,
+  readJsonInput,
+  readRepeatedFlag,
+  readRepeatedJsonInputs,
+  writeJsonFile,
+} from "../../contracts/cli/options.mjs";
+import { cliLogger, defaultCliLogPath, readAttributes } from "./context.mjs";
+
+export async function handleLogCommand(args) {
+  const [levelOrSubcommand = "info", ...logArgs] = args;
+  if (levelOrSubcommand === "summary") {
+    const logPath = defaultCliLogPath(logArgs);
+    const summary = summarizeBuildchainLogEvents({ path: logPath });
+    if (readBooleanFlag(logArgs, "json")) {
+      printJson(summary);
+    } else {
+      process.stdout.write(
+        `buildchain log summary: ${summary.eventCount} events\n`,
+      );
+      process.stdout.write(
+        `sources: ${Object.keys(summary.sources).join(", ") || "none"}\n`,
+      );
+      process.stdout.write(
+        `phases: ${Object.keys(summary.phases).join(", ") || "none"}\n`,
+      );
+      if (summary.controlPlane.eventCount > 0) {
+        process.stdout.write(
+          `control plane: ${summary.controlPlane.eventCount} events, ` +
+            `incident reuse ${summary.controlPlane.workflowFriction.incidentReuseRate ?? "n/a"}, ` +
+            `release-intent suppression ${summary.controlPlane.releaseIntent.suppressionRate ?? "n/a"}\n`,
+        );
+      }
+    }
+    return;
+  }
+  if (!["info", "warn", "error"].includes(levelOrSubcommand)) {
+    throw new Error("usage: buildchain log <info|warn|error> --event <name>");
+  }
+  const eventName = readFlag(logArgs, "event", "");
+  if (!eventName) {
+    throw new Error("buildchain log requires --event <name>");
+  }
+  const logger = cliLogger(logArgs);
+  const event = logger.emit(levelOrSubcommand, eventName, {
+    message: readFlag(logArgs, "message", ""),
+    attributes: readAttributes(logArgs),
+  });
+  if (readBooleanFlag(logArgs, "json")) {
+    printJson(event);
+  }
+  return;
+}
+
+export async function handleMarkCommand(args) {
+  const eventName = readFlag(args, "event", "");
+  if (!eventName) {
+    throw new Error("buildchain mark requires --event <name>");
+  }
+  const logger = cliLogger(args);
+  const event = logger.mark(eventName, {
+    message: readFlag(args, "message", ""),
+    attributes: readAttributes(args),
+  });
+  if (readBooleanFlag(args, "json")) {
+    printJson(event);
+  }
+  return;
+}
+
+export async function handleSpanCommand(args) {
+  const separator = args.indexOf("--");
+  const spanArgs = separator === -1 ? args : args.slice(0, separator);
+  const commandArgs = separator === -1 ? [] : args.slice(separator + 1);
+  const eventName = readFlag(spanArgs, "event", "");
+  if (!eventName || commandArgs.length === 0) {
+    throw new Error(
+      "usage: buildchain span --event <name> -- <command> [args...]",
+    );
+  }
+  const logger = cliLogger(spanArgs);
+  const spanId = crypto.randomUUID();
+  const startedAt = Date.now();
+  logger.info(`${eventName}.start`, {
+    spanId,
+    message: readFlag(spanArgs, "message", ""),
+    attributes: readAttributes(spanArgs),
+  });
+  const result = spawnSync(commandArgs[0], commandArgs.slice(1), {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  const durationMs = Date.now() - startedAt;
+  if (result.error || result.status !== 0) {
+    logger.error(`${eventName}.error`, {
+      spanId,
+      durationMs,
+      message:
+        result.error?.message ||
+        `command exited with ${result.status ?? "signal"}`,
+      attributes: {
+        ...readAttributes(spanArgs),
+        status: result.status ?? "",
+        signal: result.signal || "",
+      },
+    });
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  logger.info(`${eventName}.end`, {
+    spanId,
+    durationMs,
+    attributes: readAttributes(spanArgs),
+  });
+  return;
+}

package/packages/core/observability/cli/process-sample.mjs

@@ -0,0 +1,71 @@
+import { sampleProcessTree } from "../process/sampling.js";
+import { printJson, readBooleanFlag, readFlag } from "../../contracts/cli/options.mjs";
+export function readIntegerFlag(args, name, fallback = 0) {
+  const value = readFlag(args, name, "");
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`--${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+export async function runProcessTreeSample(sampleArgs = []) {
+  const separator = sampleArgs.indexOf("--");
+  const optionArgs =
+    separator === -1 ? sampleArgs : sampleArgs.slice(0, separator);
+  const commandArgs = separator === -1 ? [] : sampleArgs.slice(separator + 1);
+  if (commandArgs.length === 0) {
+    throw new Error(
+      "usage: buildchain sample process-tree -- <command> [args...]",
+    );
+  }
+  const command = commandArgs[0];
+  const args = commandArgs.slice(1);
+  const label = readFlag(optionArgs, "label", "process-tree");
+  const intervalMs = readIntegerFlag(optionArgs, "interval-ms", 15000);
+  const requestedParallelism = readIntegerFlag(
+    optionArgs,
+    "requested-parallelism",
+    0,
+  );
+  const outputPath = readFlag(
+    optionArgs,
+    "output",
+    ".buildchain/diagnostics/process-samples.jsonl",
+  );
+  const summaryOutputPath = readFlag(
+    optionArgs,
+    "summary-output",
+    ".buildchain/diagnostics/process-summary.json",
+  );
+  const report = await sampleProcessTree({ command, args, label, intervalMs, requestedParallelism, outputPath, summaryOutputPath, cwd: process.cwd(), environment: process.env });
+  const { summary } = report;
+  if (readBooleanFlag(optionArgs, "json")) {
+    printJson(report);
+  } else {
+    process.stdout.write(
+      `buildchain process sample: ${summary.sampleCount} samples\n`,
+    );
+    process.stdout.write(
+      `observed concurrency max: ${summary.observedConcurrency.max}\n`,
+    );
+    process.stdout.write(`wrote: ${outputPath}\n`);
+    process.stdout.write(`wrote: ${summaryOutputPath}\n`);
+  }
+  if (report.exit.error || report.exit.signal || report.exit.status !== 0) process.exitCode = report.exit.status || 1;
+  return report;
+}
+
+export async function handleSampleCommand(args) {
+  const [subcommand = "", ...sampleArgs] = args;
+  if (subcommand !== "process-tree") {
+    throw new Error(
+      "usage: buildchain sample process-tree -- <command> [args...]",
+    );
+  }
+  await runProcessTreeSample(sampleArgs);
+  return;
+}

package/packages/core/observability/commands/aggregate-diagnostics-summary.mjs

@@ -0,0 +1,45 @@
+import { aggregateDiagnosticsSummary } from "../diagnostics/aggregate.js";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { findJsonFiles } from "../../build/artifact/files.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+import {
+  formatDiagnosticsSummaryTable,
+  summarizeDiagnosticsArtifacts,
+} from "../diagnostics.js";
+
+function readEnv(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+export function aggregateDiagnosticsSummaryCli() {
+  const inputRoot = path.resolve(readEnv("BUILDCHAIN_DIAGNOSTICS_INPUT", ".buildchain/downloaded-diagnostics"));
+  const outputPath = path.resolve(readEnv("BUILDCHAIN_DIAGNOSTICS_OUTPUT", ".buildchain/artifacts/diagnostics-summary.json"));
+  const expectedPlatformCount = Number(readEnv("BUILDCHAIN_PLATFORM_COUNT", "0"));
+  const summary = aggregateDiagnosticsSummary({ inputRoot, outputPath, expectedPlatformCount });
+  process.stdout.write(`${formatDiagnosticsSummaryTable(summary)}\n`);
+  writeGitHubOutputs({
+    "diagnostics-summary-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
+    "diagnostics-platform-count": String(summary.count),
+    "diagnostics-summary-json": JSON.stringify({
+      contract: summary.contract,
+      count: summary.count,
+      totalWarningCount: summary.totalWarningCount,
+      totalErrorCount: summary.totalErrorCount,
+      diagnosticsManifestWarningCount: summary.diagnosticsManifestWarningCount,
+      diagnosticsContractWarningCount: summary.diagnosticsContractWarningCount,
+      slowestPlatforms: summary.slowestPlatforms,
+    }),
+  });
+  return summary;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    aggregateDiagnosticsSummaryCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/observability/commands/controller-evidence.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { planControllerEvidence, receiptControllerEvidence } from "../controller-evidence-io.js";
+import {
+  validateControllerPlan,
+  validateControllerReceipt,
+} from "../controller-evidence.js";
+
+function argument(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : process.argv[index + 1] || "";
+}
+
+function env(name, fallback = "") {
+  return String(process.env[name] ?? fallback).trim();
+}
+
+function readJson(filePath, label = filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`could not read ${label}: ${error.message}`);
+  }
+}
+
+function parseJson(value, label, fallback = undefined) {
+  if (!String(value || "").trim() && fallback !== undefined) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${label} must be valid JSON: ${error.message}`);
+  }
+}
+
+function writeOutputs(outputs) {
+  const outputPath = env("GITHUB_OUTPUT");
+  if (!outputPath) return;
+  fs.appendFileSync(outputPath, Object.entries(outputs).map(([name, value]) => `${name}=${String(value ?? "")}\n`).join(""));
+}
+
+function planMode() {
+  const registryPath = path.resolve(env("BUILDCHAIN_CONTROLLER_REGISTRY", ".buildchain/runtime/dist/site/controller-registry.json"));
+  const outputPath = path.resolve(env("BUILDCHAIN_CONTROLLER_PLAN_PATH", ".buildchain/controller/plan.json"));
+  const plan = planControllerEvidence({
+    registryPath, outputPath, controllerId: env("BUILDCHAIN_CONTROLLER_ID"),
+    inputs: parseJson(env("BUILDCHAIN_CONTROLLER_INPUTS_JSON", "{}"), "controller inputs JSON", {}),
+    inputBoundary: env("BUILDCHAIN_CONTROLLER_INPUT_BOUNDARY"),
+    source: { repository: env("BUILDCHAIN_CONTROLLER_SOURCE_REPOSITORY"), sha: env("BUILDCHAIN_CONTROLLER_SOURCE_SHA") },
+    runtime: { ref: env("BUILDCHAIN_CONTROLLER_RUNTIME_REF"), sha: env("BUILDCHAIN_CONTROLLER_RUNTIME_SHA"), contractDigest: env("BUILDCHAIN_CONTROLLER_CONTRACT_DIGEST") },
+  });
+  writeOutputs({
+    "controller-plan-path": outputPath,
+    "controller-plan-json": JSON.stringify(plan),
+    "controller-plan-digest": plan.digest,
+  });
+  return plan;
+}
+
+function receiptMode() {
+  const planPath = path.resolve(env("BUILDCHAIN_CONTROLLER_PLAN_PATH", ".buildchain/controller/plan.json"));
+  const stages = parseJson(env("BUILDCHAIN_CONTROLLER_STAGES_JSON", "[]"), "controller stages JSON", []);
+  const outputPath = path.resolve(env("BUILDCHAIN_CONTROLLER_RECEIPT_PATH", ".buildchain/controller/receipt.json"));
+  const receipt = receiptControllerEvidence({ planPath, outputPath, stages,
+    evidence: parseJson(env("BUILDCHAIN_CONTROLLER_EVIDENCE_JSON", "[]"), "controller evidence JSON", []),
+    evidenceFiles: parseJson(env("BUILDCHAIN_CONTROLLER_EVIDENCE_FILES_JSON", "[]"), "controller evidence files JSON", []),
+    reason: env("BUILDCHAIN_CONTROLLER_REASON_CODE") ? {
+      code: env("BUILDCHAIN_CONTROLLER_REASON_CODE"), summary: env("BUILDCHAIN_CONTROLLER_REASON_SUMMARY", "controller did not pass"),
+    } : undefined,
+    artifact: env("BUILDCHAIN_CONTROLLER_RECEIPT_ARTIFACT"),
+  });
+  writeOutputs({
+    "controller-receipt-path": outputPath,
+    "controller-receipt-json": JSON.stringify(receipt),
+    "controller-receipt-digest": receipt.digest,
+    "controller-receipt-status": receipt.status,
+    "controller-receipt-qualifying": String(receipt.qualifying),
+  });
+  return receipt;
+}
+
+function validateMode() {
+  const kind = env("BUILDCHAIN_CONTROLLER_EVIDENCE_KIND", argument("kind", "receipt"));
+  const filePath = path.resolve(env("BUILDCHAIN_CONTROLLER_EVIDENCE_PATH", argument("file")));
+  const value = readJson(filePath, `controller ${kind}`);
+  const validation = kind === "plan" ? validateControllerPlan(value) : validateControllerReceipt(value);
+  if (!validation.ok || (process.argv.includes("--require-qualifying") && !validation.qualifying)) {
+    throw new Error(`controller ${kind} validation failed: ${validation.issues.join("; ") || "not qualifying"}`);
+  }
+  return validation;
+}
+
+export function controllerEvidenceCli() {
+  const mode = argument("mode", env("BUILDCHAIN_CONTROLLER_MODE", "plan"));
+  if (mode === "plan") return planMode();
+  if (mode === "receipt") return receiptMode();
+  if (mode === "validate") return validateMode();
+  throw new Error(`unsupported controller evidence mode: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    controllerEvidenceCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/observability/commands/observed-evidence.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { publishObservedEvidence } from "../evidence/publication.js";
+function arg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : process.argv[index + 1] || fallback;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const output = arg("output");
+    const result = publishObservedEvidence({
+      manifestPath: arg("manifest"),
+      artifactRoot: arg("artifact-root", path.dirname(arg("manifest"))),
+      bucket: arg("bucket"),
+      distributionId: arg("distribution-id"),
+      dryRun: arg("execute", "false") !== "true",
+    });
+    const json = `${JSON.stringify(result, null, 2)}\n`;
+    if (output) { fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true }); fs.writeFileSync(output, json); }
+    else process.stdout.write(json);
+  } catch (error) {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  }
+}

package/packages/core/observability/controller/identity-action.js

@@ -0,0 +1,11 @@
+import { installationRoot } from "../../runtime/installation-root.js";
+import { controllerCheckoutIdentity } from "./identity.js";
+export function identifyControllerCheckoutsAction(core, env) {
+  for (const [key, value] of Object.entries(
+    controllerCheckoutIdentity({
+      workspace: env.GITHUB_WORKSPACE,
+      runtimeRoot: installationRoot(import.meta.url),
+    }),
+  ))
+    core.setOutput(key, value);
+}

package/packages/core/observability/controller/identity.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import path from "node:path";
+import { command } from "../../runtime/action-process.mjs";
+export function controllerCheckoutIdentity(
+  { workspace, runtimeRoot },
+  execute = command,
+) {
+  const sha = (directory) =>
+    execute("git", ["-C", directory, "rev-parse", "HEAD"], {
+      stdio: "pipe",
+    }).trim();
+  const sourceSha = sha(workspace),
+    runtimeSha = sha(runtimeRoot);
+  const contract = JSON.parse(
+    fs.readFileSync(
+      path.join(runtimeRoot, "dist/site/buildchain-contract.json"),
+      "utf8",
+    ),
+  );
+  if (
+    ![sourceSha, runtimeSha].every((value) => /^[0-9a-f]{40}$/.test(value)) ||
+    !/^sha256:[0-9a-f]{64}$/.test(contract.contractDigest)
+  )
+    throw new Error(
+      "Exact source, runtime and contract identities are required",
+    );
+  return {
+    "source-sha": sourceSha,
+    "runtime-sha": runtimeSha,
+    "contract-digest": contract.contractDigest,
+  };
+}

package/packages/core/observability/controller-actions.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import {
+  planControllerEvidence,
+  receiptControllerEvidence,
+} from "./controller-evidence-io.js";
+
+function jsonInput(core, name, fallback) {
+  try {
+    return JSON.parse(core.getInput(name) || JSON.stringify(fallback));
+  } catch {
+    throw new Error(`${name} must be valid JSON`);
+  }
+}
+
+export function controllerPlanAction(core) {
+  const outputPath = path.resolve(core.getInput("plan-path"));
+  const plan = planControllerEvidence({
+    registryPath: core.getInput("registry"),
+    outputPath,
+    controllerId: core.getInput("controller-id", { required: true }),
+    source: {
+      repository: core.getInput("source-repository", { required: true }),
+      sha: core.getInput("source-sha", { required: true }),
+    },
+    runtime: {
+      ref: core.getInput("runtime-ref", { required: true }),
+      sha: core.getInput("runtime-sha", { required: true }),
+      contractDigest: core.getInput("contract-digest", { required: true }),
+    },
+    inputs: jsonInput(core, "inputs-json", {}),
+    inputBoundary: core.getInput("input-boundary"),
+  });
+  for (const [key, value] of Object.entries({
+    "controller-plan-path": outputPath,
+    "controller-plan-json": JSON.stringify(plan),
+    "controller-plan-digest": plan.digest,
+  }))
+    core.setOutput(key, value);
+}
+
+export function controllerReceiptAction(core) {
+  const outputPath = path.resolve(core.getInput("receipt-path"));
+  const code = core.getInput("reason-code");
+  const receipt = receiptControllerEvidence({
+    planPath: core.getInput("plan-path"),
+    outputPath,
+    stages: jsonInput(core, "stages-json", []),
+    evidence: jsonInput(core, "evidence-json", []),
+    evidenceFiles: jsonInput(core, "evidence-files-json", []),
+    artifact: core.getInput("artifact"),
+    reason: code
+      ? { code, summary: core.getInput("reason-summary") }
+      : undefined,
+  });
+  for (const [key, value] of Object.entries({
+    "controller-receipt-path": outputPath,
+    "controller-receipt-json": JSON.stringify(receipt),
+    "controller-receipt-digest": receipt.digest,
+    "controller-receipt-status": receipt.status,
+    "controller-receipt-qualifying": String(receipt.qualifying),
+  }))
+    core.setOutput(key, value);
+}

package/packages/core/observability/controller-evidence-io.js

@@ -0,0 +1,112 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createControllerPlan,
+  createControllerReceipt,
+} from "./controller-evidence.js";
+import {
+  selectWorkflowCallInputs,
+  resolveControllerInputBoundary,
+} from "./controller-input-boundary.js";
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`could not read ${label}: ${error.message}`);
+  }
+}
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n");
+}
+
+export function planControllerEvidence({
+  registryPath,
+  outputPath,
+  controllerId,
+  source,
+  runtime,
+  inputs = {},
+  inputBoundary = "",
+}) {
+  const registry = readJson(registryPath, "controller registry");
+  const descriptor = registry.controllers?.find(
+    (entry) => entry.id === controllerId,
+  );
+  if (!descriptor)
+    throw new Error(`controller registry does not declare ${controllerId}`);
+  const boundary = resolveControllerInputBoundary(descriptor, inputBoundary);
+  const plan = createControllerPlan({
+    descriptor,
+    source,
+    runtime,
+    inputs:
+      boundary === "workflow-call"
+        ? selectWorkflowCallInputs(descriptor, inputs)
+        : inputs,
+  });
+  writeJson(outputPath, plan);
+  return plan;
+}
+
+export function collectControllerEvidence(evidence, files) {
+  if (!Array.isArray(evidence) || !Array.isArray(files))
+    throw new Error("controller evidence inputs must be arrays");
+  return [
+    ...evidence,
+    ...files.map((entry, index) => {
+      if (!entry.kind || !entry.path)
+        throw new Error(
+          `controller evidence file ${index} requires kind and path`,
+        );
+      const filePath = path.resolve(String(entry.path));
+      if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+        throw new Error(`controller evidence file is missing: ${entry.path}`);
+      return {
+        kind: String(entry.kind),
+        digest: `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`,
+        ...(entry.artifact ? { artifact: String(entry.artifact) } : {}),
+      };
+    }),
+  ];
+}
+
+export function receiptControllerEvidence({
+  planPath,
+  outputPath,
+  stages,
+  evidence = [],
+  evidenceFiles = [],
+  reason,
+  artifact,
+}) {
+  if (!Array.isArray(stages))
+    throw new Error("controller stages JSON must be an array");
+  const normalize = (value) => {
+    const status = String(value || "")
+      .trim()
+      .toLowerCase();
+    return (
+      {
+        success: "passed",
+        failure: "failed",
+        cancelled: "cancelled",
+        skipped: "skipped",
+      }[status] || status
+    );
+  };
+  const receipt = createControllerReceipt({
+    plan: readJson(planPath, "controller plan"),
+    stages: stages.map((stage) => ({
+      ...stage,
+      status: normalize(stage.status),
+    })),
+    evidence: collectControllerEvidence(evidence, evidenceFiles),
+    reason,
+    artifact,
+  });
+  writeJson(outputPath, receipt);
+  return receipt;
+}