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

package/packages/core/build/commands/aggregate-build-summary.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { aggregateBuildSummary } from "../summary/artifacts.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+const readEnv = (name, fallback = "") => process.env[name] || fallback;
+export function aggregateBuildSummaryCli() {
+  const inputRoot = path.resolve(readEnv("BUILDCHAIN_SUMMARY_INPUT", ".buildchain/downloaded-manifests"));
+  const outputPath = path.resolve(readEnv("BUILDCHAIN_SUMMARY_OUTPUT", ".buildchain/artifacts/build-summary.json"));
+  const artifactName = readEnv("BUILDCHAIN_ARTIFACT_NAME", "buildchain-artifact");
+  const expectedPlatformCount = Number(readEnv("BUILDCHAIN_PLATFORM_COUNT", "0"));
+  const additionalPlatformCount = Number(readEnv("BUILDCHAIN_ADDITIONAL_PLATFORM_COUNT", "0"));
+  const summary = aggregateBuildSummary({ inputRoot, outputPath, artifactName, expectedPlatformCount, additionalPlatformCount,
+    platforms: JSON.parse(readEnv("BUILDCHAIN_EXPECTED_PLATFORMS_JSON", "[]")), additionalPlatforms: JSON.parse(readEnv("BUILDCHAIN_ADDITIONAL_PLATFORM_IDS_JSON", "[]")),
+    git: {
+      repository: process.env.GITHUB_REPOSITORY || "",
+      sha: process.env.BUILDCHAIN_SOURCE_SHA || process.env.GITHUB_SHA || "",
+      treeSha: process.env.BUILDCHAIN_SOURCE_TREE_SHA || "",
+      ref: process.env.BUILDCHAIN_SOURCE_REF || process.env.GITHUB_REF || "",
+      runId: process.env.GITHUB_RUN_ID || "",
+      runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",
+    },
+    publishGate: {
+      trustedEvent: readEnv("BUILDCHAIN_TRUSTED_EVENT", "true") === "true",
+      channel: readEnv("BUILDCHAIN_PUBLISH_CHANNEL", "none"),
+      allowed: readEnv("BUILDCHAIN_PUBLISH_ALLOWED", "false") === "true",
+      reason: readEnv("BUILDCHAIN_PUBLISH_REASON", ""),
+    },
+    publishSource: {
+      ref: readEnv("BUILDCHAIN_PUBLISH_SOURCE_REF", ""),
+      sha: readEnv("BUILDCHAIN_PUBLISH_SOURCE_SHA", ""),
+      locked: readEnv("BUILDCHAIN_PUBLISH_SOURCE_LOCKED", "false") === "true",
+      channel: readEnv("BUILDCHAIN_PUBLISH_SOURCE_CHANNEL", "none"),
+      line: readEnv("BUILDCHAIN_PUBLISH_SOURCE_LINE", ""),
+      consumerVersion: readEnv("BUILDCHAIN_PUBLISH_SOURCE_CONSUMER_VERSION", ""),
+      releaseManifest: readEnv("BUILDCHAIN_RELEASE_MANIFEST_JSON", ""),
+    },
+    runtime: {
+      workflowShellRef: readEnv("BUILDCHAIN_WORKFLOW_SHELL_REF", ""),
+      requestedRef: readEnv("BUILDCHAIN_RUNTIME_REQUESTED_REF", ""),
+      ref: readEnv("BUILDCHAIN_RUNTIME_REF", ""),
+      sha: readEnv("BUILDCHAIN_RUNTIME_SHA", ""),
+      class: readEnv("BUILDCHAIN_RUNTIME_CLASS", ""),
+      override: readEnv("BUILDCHAIN_RUNTIME_OVERRIDE", "false") === "true",
+      trustDecision: readEnv("BUILDCHAIN_RUNTIME_TRUST_DECISION", ""),
+      rollbackRef: readEnv("BUILDCHAIN_ROLLBACK_REF", ""),
+    },
+  });
+  writeGitHubOutputs({
+    "summary-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
+    "platform-count": String(summary.platformCount),
+    "artifact-file-count": String(summary.fileCount),
+    "artifact-total-bytes": String(summary.totalBytes),
+    "artifact-summary-json": JSON.stringify({
+      contract: summary.contract,
+      artifactName: summary.artifactName,
+      platformCount: summary.platformCount,
+      fileCount: summary.fileCount,
+      totalBytes: summary.totalBytes,
+      publishGate: summary.publishGate,
+      publishSource: summary.publishSource,
+      runtime: summary.runtime,
+    }),
+  });
+  return summary;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    aggregateBuildSummaryCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/anchored-version-material.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { createAnchoredVersionMaterialEvidence } from "../anchored-version-material.js";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function writeOutput(name, value) {
+  if (!process.env.GITHUB_OUTPUT) {
+    return;
+  }
+  fs.appendFileSync(process.env.GITHUB_OUTPUT, `${name}=${String(value)}\n`);
+}
+
+try {
+  const cwd = path.resolve(env("BUILDCHAIN_ANCHORED_SOURCE_CWD", process.cwd()));
+  const outputPath = path.resolve(
+    env(
+      "BUILDCHAIN_ANCHORED_MATERIAL_OUTPUT",
+      ".buildchain/artifacts/anchored-version-material.json",
+    ),
+  );
+  const evidence = createAnchoredVersionMaterialEvidence({
+    cwd,
+    targetChannel: env("BUILDCHAIN_ANCHORED_TARGET_CHANNEL"),
+    targetRef: env("BUILDCHAIN_ANCHORED_TARGET_REF"),
+    alphaRef: env("BUILDCHAIN_ANCHORED_ALPHA_REF"),
+    releaseRef: env("BUILDCHAIN_ANCHORED_RELEASE_REF", "HEAD"),
+    runLifecycle: env("BUILDCHAIN_ANCHORED_RUN_LIFECYCLE", "true") !== "false",
+  });
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(evidence, null, 2)}\n`);
+  writeOutput("anchored-version-material-applicable", evidence.applicable === true);
+  writeOutput("anchored-version-material-digest", evidence.digest || "");
+  writeOutput("anchored-version-material-path", outputPath);
+  process.stdout.write(`${JSON.stringify(evidence)}\n`);
+} catch (error) {
+  console.error(`anchored version material: ${error.message}`);
+  process.exitCode = 1;
+}

package/packages/core/build/commands/artifact-signing-controller.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { sealArtifactSigningControlRequest, readArtifactSigningControlRequest, assertArtifactSigningControlRequestContext, artifactSigningControlRequestOutputs } from "../signing/request.js";
+import { settleArtifactSigningControl, assertArtifactSigningControllerReceipt, readArtifactSigningControllerReceipt } from "../signing/control.js";
+import { readArtifactSigningDelegation, artifactSigningDelegationOutputs } from "../signing/delegation.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+function expectedContext() {
+  return {
+    sourceRepository: process.env.BUILDCHAIN_EXPECTED_SOURCE_REPOSITORY || "",
+    sourceRunId: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ID || "",
+    sourceRunAttempt: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ATTEMPT || "",
+    sourceSha: process.env.BUILDCHAIN_EXPECTED_SOURCE_SHA || "",
+    sourceTreeSha: process.env.BUILDCHAIN_EXPECTED_SOURCE_TREE_SHA || "",
+    runtimeRepository: process.env.BUILDCHAIN_EXPECTED_RUNTIME_REPOSITORY || "",
+    runtimeSha: process.env.BUILDCHAIN_EXPECTED_RUNTIME_SHA || "",
+    platformId: process.env.BUILDCHAIN_EXPECTED_PLATFORM_ID || "",
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const mode = process.argv[2] || "seal";
+    if (mode === "seal") {
+      sealArtifactSigningControlRequest({ outputPath: process.env.BUILDCHAIN_SIGNING_CONTROL_REQUEST_PATH, ...{
+  sourceRepository: process.env.GITHUB_REPOSITORY,
+  sourceRunId: process.env.GITHUB_RUN_ID,
+  sourceRunAttempt: process.env.GITHUB_RUN_ATTEMPT || "1",
+  sourceSha: process.env.BUILDCHAIN_SOURCE_SHA,
+  sourceTreeSha: process.env.BUILDCHAIN_SOURCE_TREE_SHA,
+  runtimeRepository: process.env.BUILDCHAIN_RUNTIME_REPOSITORY,
+  runtimeRef: process.env.BUILDCHAIN_RUNTIME_REF,
+  runtimeSha: process.env.BUILDCHAIN_RUNTIME_SHA,
+  platformId: process.env.BUILDCHAIN_PLATFORM_ID,
+  platformName: process.env.BUILDCHAIN_PLATFORM_NAME,
+  requestCount: process.env.BUILDCHAIN_SIGNING_REQUEST_COUNT || "0",
+  requestArtifact: process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT || "",
+  requestIndexPath: process.env.BUILDCHAIN_SIGNING_REQUEST_INDEX,
+  authorityRepository: process.env.BUILDCHAIN_AUTHORITY_REPOSITORY,
+  resultArtifact: process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT || "",
+  artifactName: process.env.BUILDCHAIN_ARTIFACT_NAME,
+  manifestArtifact: process.env.BUILDCHAIN_MANIFEST_ARTIFACT_NAME,
+  diagnosticsArtifact: process.env.BUILDCHAIN_DIAGNOSTICS_ARTIFACT_NAME,
+  workingDirectory: process.env.BUILDCHAIN_SIGNING_CWD || ".",
+} });
+    } else if (mode === "outputs") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(process.env.BUILDCHAIN_SIGNING_CONTROL_REQUEST_PATH),
+        expectedContext(),
+      );
+      writeGitHubOutputs(artifactSigningControlRequestOutputs(request));
+    } else if (mode === "settle") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(process.env.BUILDCHAIN_SIGNING_CONTROL_REQUEST_PATH),
+        expectedContext(),
+      );
+      const { receipt, delegation } = settleArtifactSigningControl({ request, ...{
+  authorityStatus: process.env.BUILDCHAIN_AUTHORITY_STATUS || "failed",
+  authorityRunId: process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  authorityRunUrl: process.env.BUILDCHAIN_AUTHORITY_RUN_URL || "",
+  authorityResultArtifact: process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT ||
+    "",
+  authorityCorrelationId: process.env.BUILDCHAIN_AUTHORITY_CORRELATION_ID ||
+    "",
+  authorityConclusion: process.env.BUILDCHAIN_AUTHORITY_CONCLUSION || "",
+  controllerRepository: process.env.GITHUB_REPOSITORY,
+  controllerRunId: process.env.GITHUB_RUN_ID,
+  controllerRunAttempt: process.env.GITHUB_RUN_ATTEMPT || "1",
+  controllerJob: process.env.GITHUB_JOB || "artifact-signing-control",
+  controllerRunnerOs: process.env.RUNNER_OS || "Linux",
+  controllerStartedAt: process.env.BUILDCHAIN_CONTROLLER_STARTED_AT ||
+    new Date().toISOString(),
+  controllerCompletedAt: process.env.BUILDCHAIN_CONTROLLER_COMPLETED_AT ||
+    new Date().toISOString(),
+  receiptPath: process.env.BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_PATH,
+  delegationPath: process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH,
+  authorityRuntimeSha: process.env.BUILDCHAIN_AUTHORITY_RUNTIME_SHA || "",
+} });
+      writeGitHubOutputs({
+        "controller-status": receipt.controller.status,
+        "controller-receipt-digest": receipt.digest,
+        "controller-qualifying": String(receipt.qualifying),
+        "delegation-created": String(Boolean(delegation)),
+      });
+    } else if (mode === "verify") {
+      const request = assertArtifactSigningControlRequestContext(
+        readArtifactSigningControlRequest(process.env.BUILDCHAIN_SIGNING_CONTROL_REQUEST_PATH),
+        expectedContext(),
+      );
+      const checked = assertArtifactSigningControllerReceipt({
+        request,
+        receipt: readArtifactSigningControllerReceipt(process.env.BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_PATH),
+        delegation: readArtifactSigningDelegation(process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH),
+      });
+      writeGitHubOutputs({
+        ...artifactSigningDelegationOutputs(checked.delegation),
+        "request-root": checked.receipt.request.root,
+        "controller-receipt-digest": checked.receipt.digest,
+        "controller-status": checked.receipt.controller.status,
+      });
+    } else {
+      throw new Error(`unsupported artifact signing controller mode: ${mode}`);
+    }
+  } catch (error) {
+    console.error(
+      `::error::${String(error?.message || error).replace(/\r?\n/gu, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/artifact-signing-delegation.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { sealArtifactSigningDelegation, readArtifactSigningDelegation, assertArtifactSigningDelegationContext, artifactSigningDelegationOutputs } from "../signing/delegation.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+try {
+  const mode = process.argv[2] || "seal";
+  if (mode === "seal") sealArtifactSigningDelegation({ outputPath: process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH, ...{
+  sourceRepository: process.env.GITHUB_REPOSITORY,
+  sourceRunId: process.env.GITHUB_RUN_ID,
+  sourceRunAttempt: process.env.GITHUB_RUN_ATTEMPT || "1",
+  sourceSha: process.env.BUILDCHAIN_SOURCE_SHA,
+  sourceTreeSha: process.env.BUILDCHAIN_SOURCE_TREE_SHA,
+  runtimeRepository: process.env.BUILDCHAIN_RUNTIME_REPOSITORY,
+  runtimeSha: process.env.BUILDCHAIN_RUNTIME_SHA,
+  platformId: process.env.BUILDCHAIN_PLATFORM_ID,
+  platformName: process.env.BUILDCHAIN_PLATFORM_NAME,
+  requestCount: process.env.BUILDCHAIN_SIGNING_REQUEST_COUNT || "0",
+  requestArtifact: process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT || "",
+  requestRoot: process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT_DIGEST || "",
+  authorityRunId: process.env.BUILDCHAIN_AUTHORITY_RUN_ID || "",
+  authorityRuntimeSha: process.env.BUILDCHAIN_AUTHORITY_RUNTIME_SHA || "",
+  resultArtifact: process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT || "",
+  artifactName: process.env.BUILDCHAIN_ARTIFACT_NAME,
+  manifestArtifact: process.env.BUILDCHAIN_MANIFEST_ARTIFACT_NAME,
+  diagnosticsArtifact: process.env.BUILDCHAIN_DIAGNOSTICS_ARTIFACT_NAME,
+  workingDirectory: process.env.BUILDCHAIN_SIGNING_CWD || ".",
+  controllerMode: process.env.BUILDCHAIN_SIGNING_CONTROLLER_MODE || "",
+  controllerReceiptDigest: process.env
+    .BUILDCHAIN_SIGNING_CONTROLLER_RECEIPT_DIGEST || "",
+} });
+  else if (mode === "outputs") writeGitHubOutputs(artifactSigningDelegationOutputs(assertArtifactSigningDelegationContext(readArtifactSigningDelegation(process.env.BUILDCHAIN_SIGNING_DELEGATION_PATH), {
+    sourceRepository: process.env.BUILDCHAIN_EXPECTED_SOURCE_REPOSITORY, sourceRunId: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ID, sourceRunAttempt: process.env.BUILDCHAIN_EXPECTED_SOURCE_RUN_ATTEMPT, sourceSha: process.env.BUILDCHAIN_EXPECTED_SOURCE_SHA, runtimeRepository: process.env.BUILDCHAIN_EXPECTED_RUNTIME_REPOSITORY, runtimeSha: process.env.BUILDCHAIN_EXPECTED_RUNTIME_SHA, platformId: process.env.BUILDCHAIN_EXPECTED_PLATFORM_ID,
+  })));
+  else throw new Error(`unsupported artifact signing delegation mode: ${mode}`);
+} catch (error) { console.error(`::error::${String(error.message).replaceAll("\n", "%0A")}`); process.exitCode = error.status || 1; }

package/packages/core/build/commands/auditable-demo-platform.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { prepareArtifact, validateScenario } from "../demo/scenario.js";
+import { adaptCapture } from "../demo/capture.js";
+import { materializeDemo } from "../demo/materialization.js";
+import { readJson, stableJson, rootJson, fail, requireValue } from "../demo/values.js";
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    requireValue(key?.startsWith("--") && value !== undefined && !(key in values), `invalid argument near ${key || "<empty>"}`);
+    values[key.slice(2)] = value;
+  }
+  return values;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const [command, ...rest] = argv;
+  const args = parseArgs(rest);
+  if (command === "validate") {
+    const scenario = validateScenario(readJson(path.resolve(args.scenario), "scenario"));
+    process.stdout.write(stableJson({ ok: true, scenarioRoot: rootJson(scenario), demoIds: scenario.demos.map((entry) => entry.id) }));
+    return;
+  }
+  if (command === "list") {
+    const scenario = validateScenario(readJson(path.resolve(args.scenario), "scenario"));
+    process.stdout.write(`${scenario.demos.map((entry) => entry.id).join("\n")}\n`);
+    return;
+  }
+  if (command === "publication") {
+    const scenario = validateScenario(readJson(path.resolve(args.scenario), "scenario"));
+    process.stdout.write(stableJson({
+      ...scenario.publication,
+      ...(scenario.presentation ? { technicalSpecPath: scenario.presentation.materialization.technicalSpecPath } : {}),
+    }));
+    return;
+  }
+  if (command === "prepare-artifact") {
+    const result = prepareArtifact({
+      artifactRoot: path.resolve(args["artifact-root"]),
+      scenarioPath: path.resolve(args.scenario),
+    });
+    process.stdout.write(stableJson({ ok: true, ...result }));
+    return;
+  }
+  if (command === "adapt") {
+    const result = adaptCapture({ artifactRoot: path.resolve(args["artifact-root"]), output: path.resolve(args.output) });
+    process.stdout.write(stableJson({ ok: true, ...result }));
+    return;
+  }
+  if (command === "materialize") {
+    const result = materializeDemo({
+      repositoryRoot: path.resolve(args.repository),
+      scenarioPath: path.resolve(args.scenario),
+      demoId: args["demo-id"],
+      captureRoot: path.resolve(args.capture),
+      gateBundle: path.resolve(args.gate),
+      mediaBundle: path.resolve(args.media),
+      buildchainSha: args["buildchain-sha"],
+      rendererImage: args["renderer-image"],
+    });
+    process.stdout.write(stableJson(result));
+    return;
+  }
+  fail(`unknown command: ${command || "<empty>"}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/auditable-demo-transport-smoke.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { runTransportSmoke } from "../demo/transport-smoke.js";
+function parseArgs(argv) {
+  const values = {};
+  for (let index = 0; index < argv.length; index += 2)
+    values[argv[index].replace(/^--/u, "")] = argv[index + 1];
+  return values;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, ...runTransportSmoke({ artifactRoot: args["artifact-root"], scenarioPath: args.scenario }) }, null, 2)}\n`,
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/auditable-demo.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runAdapter, prepareSmoke } from "../demo/adapter.js";
+import { finalizeGate, verifyGate } from "../demo/gate.js";
+import { finalizeMedia } from "../demo/media-bundle.js";
+import { inspectRendererMedia } from "../demo/media-inspection.js";
+import { qualifyMediaFixture } from "../demo/renderer-evidence.js";
+import { appendOutputs, stableJson, invariant, required } from "../demo/io.js";
+
+function parseArguments(argv) {
+  const command = argv[0];
+  const values = {};
+  for (let index = 1; index < argv.length; index += 2) {
+    const key = argv[index];
+    const value = argv[index + 1];
+    invariant(key?.startsWith("--") && value !== undefined, `invalid argument near ${key || "<empty>"}`);
+    invariant(!(key.slice(2).replace(/-([a-z])/gu, (_match, letter) => letter.toUpperCase()) in values), `duplicate argument: ${key}`);
+    values[key.slice(2).replace(/-([a-z])/gu, (_match, letter) => letter.toUpperCase())] = value;
+  }
+  return { command, values };
+}
+
+function main(argv) {
+  const { command, values } = parseArguments(argv);
+  switch (command) {
+    case "run-adapter":
+      return runAdapter(values);
+    case "prepare-smoke":
+      return prepareSmoke(values);
+    case "finalize-gate":
+      { const result = finalizeGate(values); appendOutputs(values.githubOutput, { "gate-root": result.root, "gate-artifact-name": result.artifactName }); process.stdout.write(stableJson({ status: result.status, root: result.root, artifactName: result.artifactName })); return result; }
+    case "verify-gate":
+      return verifyGate(values);
+    case "finalize-media":
+      { const result = finalizeMedia(values); appendOutputs(values.githubOutput, { "media-root": result.root, "media-artifact-name": result.artifactName, "media-profile": result.mediaProfile, "media-qualification-root": result.mediaQualificationRoot }); process.stdout.write(stableJson({ status: result.status, root: result.root, artifactName: result.artifactName })); return result; }
+    case "inspect-media":
+      return inspectRendererMedia(values);
+    case "qualify-media-fixture":
+      return qualifyMediaFixture({
+        renderOutput: required(values, "renderOutput"),
+        output: required(values, "output"),
+        rendererImage: required(values, "rendererImage"),
+        rendererSourceRepository: required(values, "rendererSourceRepository"),
+        rendererSourceRef: required(values, "rendererSourceRef"),
+        rendererSourceSha: required(values, "rendererSourceSha"),
+        mediaProfile: required(values, "mediaProfile"),
+        mediaInspection: required(values, "mediaInspection"),
+      });
+    default:
+      throw new Error(`unknown command: ${command || "<empty>"}`);
+  }
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`auditable-demo: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/compiler-cache-evidence.mjs

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { prepareCompilerCacheEvidence, verifyCompilerCacheActivity } from "../cache/compiler-evidence.js";
+function main() {
+  const command = process.argv[2] || "";
+  if (!new Set(["prepare", "verify"]).has(command)) {
+    throw new Error("usage: node packages/core/build/commands/compiler-cache-evidence.mjs <prepare|verify>");
+  }
+  if (command === "prepare") {
+    const receipt = prepareCompilerCacheEvidence({ cwd: process.cwd(), env: process.env });
+    if (receipt) {
+      console.log(`compiler_cache_provider=${receipt.provider}`);
+      console.log(`compiler_cache_preparation_root=${receipt.root}`);
+    } else {
+      console.log("compiler_cache_provider=none");
+    }
+  } else {
+    const activity = verifyCompilerCacheActivity({ cwd: process.cwd(), env: process.env });
+    if (activity) {
+      console.log(`compiler_cache_compile_requests=${activity.compileRequests}`);
+      console.log(`compiler_cache_hits=${activity.cacheHits}`);
+      console.log(`compiler_cache_misses=${activity.cacheMisses}`);
+    } else {
+      console.log("compiler_cache_activity=not-applicable");
+    }
+  }
+}
+
+const isMain = process.argv[1] &&
+  path.basename(process.argv[1]) === "compiler-cache-evidence.mjs" &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/dispatch-artifact-signing-authority.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { dispatchArtifactSigningAuthority } from "../signing/dispatch.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+try { const result = await dispatchArtifactSigningAuthority({
+  token: process.env.BUILDCHAIN_AUTHORITY_DISPATCH_TOKEN,
+  authorityRepository: process.env.BUILDCHAIN_AUTHORITY_REPOSITORY ||
+    "kungfu-systems/buildchain",
+  authorityRef: process.env.BUILDCHAIN_AUTHORITY_REF,
+  sourceRepository: process.env.GITHUB_REPOSITORY,
+  sourceRunId: process.env.GITHUB_RUN_ID,
+  sourceRunAttempt: process.env.GITHUB_RUN_ATTEMPT || "1",
+  requestArtifact: process.env.BUILDCHAIN_SIGNING_REQUEST_ARTIFACT,
+  requestRoot: process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT_DIGEST,
+  runtimeSha: process.env.BUILDCHAIN_RUNTIME_SHA,
+  resultArtifact: process.env.BUILDCHAIN_SIGNING_RESULT_ARTIFACT,
+  correlationId: process.env.BUILDCHAIN_AUTHORITY_CORRELATION_ID || "",
+  timeoutSeconds: process.env.BUILDCHAIN_SIGNING_TIMEOUT_SECONDS || "7200",
+}); writeGitHubOutputs(result.outputs); }
+catch (error) { if (error.authorityOutputs) writeGitHubOutputs(error.authorityOutputs); console.error(`::error::${String(error.message).replaceAll("\n", "%0A")}`); process.exitCode = error.status || 1; }

package/packages/core/build/commands/import-artifact-signing-results.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { importArtifactSigningResults } from "../signing/import-results.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+try { writeGitHubOutputs(importArtifactSigningResults({
+  workspace: process.env.GITHUB_WORKSPACE || process.cwd(),
+  cwd: process.env.BUILDCHAIN_SIGNING_CWD || ".",
+  requestRoot: process.env.BUILDCHAIN_SIGNING_REQUEST_ROOT,
+  resultRoot: process.env.BUILDCHAIN_SIGNING_RESULT_ROOT,
+  evidenceRoot: process.env.BUILDCHAIN_SIGNING_IMPORTED_EVIDENCE_ROOT || ".buildchain/artifacts/signing",
+}).outputs); } catch (error) { console.error(`::error::${String(error.message).replaceAll("\n", "%0A")}`); process.exitCode = error.status || 1; }

package/packages/core/build/commands/lifecycle-substage-evidence.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readLifecycleSubstageEvidence } from "../lifecycle/substage-evidence.js";
+function parse(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    if (!flag?.startsWith("--") || index + 1 >= argv.length)
+      throw new Error(`invalid option: ${flag || "missing"}`);
+    options[flag.slice(2)] = argv[index + 1];
+  }
+  return options;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parse(argv);
+  const evidence = readLifecycleSubstageEvidence(options.file, {
+    lifecycleStage: options.stage || "",
+    sourceSha: options["source-sha"] || "",
+    sourceTree: options["source-tree"] || "",
+    platformId: options["platform-id"] || "",
+  });
+  process.stdout.write(
+    `${JSON.stringify({ ok: true, evidenceRoot: evidence.evidenceRoot, conclusion: evidence.conclusion })}\n`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  path.basename(process.argv[1]) === "lifecycle-substage-evidence.mjs" &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(
+      `[lifecycle-substages] ${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exit(1);
+  }
+}

package/packages/core/build/commands/resolve-artifact-coordinates.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
+import { resolveArtifactCoordinates } from "../artifact/coordinates.js";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+function required(value, label) { if (!String(value || "").trim()) throw new Error(`${label} is required`); return String(value).trim(); }
+function parseArray(value, label) { const result = JSON.parse(value); if (!Array.isArray(result) || !result.length) throw new Error(`${label} must be a non-empty JSON array`); return result; }
+export function resolveArtifactCoordinatesCli(env = process.env) {
+  const artifactListPath = required(
+    env.BUILDCHAIN_ARTIFACT_LIST_PATH,
+    "BUILDCHAIN_ARTIFACT_LIST_PATH",
+  );
+  const outputPath = required(
+    env.BUILDCHAIN_ARTIFACT_COORDINATES_PATH,
+    "BUILDCHAIN_ARTIFACT_COORDINATES_PATH",
+  );
+  const artifacts = parseArray(
+    fs.readFileSync(artifactListPath, "utf8"),
+    "artifact list",
+  );
+  const platforms = parseArray(
+    env.BUILDCHAIN_PLATFORMS_JSON || "",
+    "platforms-json",
+  );
+  const result = resolveArtifactCoordinates({
+    artifacts,
+    platforms,
+    artifactName: env.BUILDCHAIN_ARTIFACT_NAME,
+    artifactNameTemplate: env.BUILDCHAIN_ARTIFACT_NAME_TEMPLATE,
+    sourceSha: env.BUILDCHAIN_SOURCE_SHA,
+    sourceRef: env.GITHUB_REF,
+    repository: env.GITHUB_REPOSITORY,
+    runId: env.GITHUB_RUN_ID,
+    runAttempt: env.GITHUB_RUN_ATTEMPT,
+    serverUrl: env.GITHUB_SERVER_URL,
+  });
+  const pretty = `${JSON.stringify(result, null, 2)}\n`;
+  const compact = JSON.stringify(result);
+  fs.writeFileSync(outputPath, pretty);
+  writeGitHubOutputs({
+    "artifact-coordinates-json": compact,
+    "artifact-coordinates-path": outputPath,
+  });
+  process.stdout.write(pretty);
+  return result;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    resolveArtifactCoordinatesCli();
+  } catch (error) {
+    console.error(`resolve-artifact-coordinates: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/build/commands/resolve-artifact-transfer-mode.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { resolveArtifactTransfer } from "../artifact/transfer-policy.js";
+function resolveArtifactTransferMode(env = process.env) {
+  return resolveArtifactTransfer({ mode: env.INPUT_TRANSFER_MODE || "github-artifacts", relayRequired: env.INPUT_RELAY_REQUIRED !== "false",
+    bucket: env.INPUT_S3_BUCKET || env.VAR_S3_BUCKET, region: env.INPUT_S3_REGION || env.VAR_S3_REGION,
+    prefix: env.INPUT_S3_PREFIX || env.VAR_S3_PREFIX,
+    uploadRole: env.INPUT_S3_UPLOAD_ROLE_ARN || env.VAR_S3_UPLOAD_ROLE_ARN || env.SECRET_S3_UPLOAD_ROLE_ARN,
+    downloadRole: env.INPUT_S3_DOWNLOAD_ROLE_ARN || env.VAR_S3_DOWNLOAD_ROLE_ARN || env.SECRET_S3_DOWNLOAD_ROLE_ARN,
+    oidcAudience: env.INPUT_OIDC_AUDIENCE || env.VAR_OIDC_AUDIENCE });
+}
+
+function writeArtifactTransferOutputs(outputPath, resolution) {
+  if (!outputPath) {
+    throw new Error("GITHUB_OUTPUT is required");
+  }
+  fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+  fs.appendFileSync(
+    outputPath,
+    [
+      `mode=${resolution.mode}`,
+      `s3-bucket=${resolution.s3Bucket}`,
+      `s3-region=${resolution.s3Region}`,
+      `s3-prefix=${resolution.s3Prefix}`,
+      `oidc-audience=${resolution.oidcAudience}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const resolution = resolveArtifactTransferMode();
+  writeArtifactTransferOutputs(process.env.GITHUB_OUTPUT, resolution);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(
+      `::error::${error instanceof Error ? error.message : String(error)}`,
+    );
+    process.exitCode = 1;
+  }
+}
+
+export { resolveArtifactTransferMode, writeArtifactTransferOutputs };