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

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

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+
+import { validateControllerReceipt } from "../observability/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/packages/core/workflow/admission/actions.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+import { workflowInstallationRoot } from "../installation.js";
+import {
+  inspectUniversalRequest,
+  admitReviewedWorkflow,
+} from "./transactions.js";
+import { readCandidateReview } from "./review.js";
+const request = (core) =>
+  JSON.parse(core.getInput("request-json", { required: true }));
+export function inspectUniversalRequestAction(core) {
+  const outputs = inspectUniversalRequest(
+    request(core),
+    core.getBooleanInput("recovery"),
+  );
+  for (const [key, value] of Object.entries(outputs))
+    core.setOutput(key, value);
+}
+export function reviewUniversalCandidateAction(core, env) {
+  const review = readCandidateReview({
+    request: request(core),
+    workspace: env.GITHUB_WORKSPACE,
+    runtimeRoot: workflowInstallationRoot(import.meta.url),
+    candidateRoot: path.join(env.GITHUB_WORKSPACE, ".buildchain/candidate"),
+    token: core.getInput("token", { required: true }),
+  });
+  const file = path.join(
+    env.GITHUB_WORKSPACE,
+    ".buildchain/review-evidence.json",
+  );
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(review, null, 2) + "\n");
+  core.setOutput("review-json", JSON.stringify(review));
+}
+export function admitUniversalCandidateAction(core, env) {
+  const admitted = admitReviewedWorkflow({
+    request: request(core),
+    reviewEvidence: JSON.parse(
+      core.getInput("review-json", { required: true }),
+    ),
+    workspace: env.GITHUB_WORKSPACE,
+    candidateRoot: path.join(env.GITHUB_WORKSPACE, ".buildchain/candidate"),
+    consumer: {
+      repository: env.GITHUB_REPOSITORY,
+      sha: env.GITHUB_SHA,
+      workflowRef: env.GITHUB_WORKFLOW_REF,
+    },
+  });
+  for (const [key, value] of Object.entries({
+    "runtime-sha": admitted.runtime.sha,
+    "request-root": admitted.requestRoot,
+    "admission-root": admitted.admissionRoot,
+    "admission-json": JSON.stringify(admitted),
+  }))
+    core.setOutput(key, value);
+}

package/packages/core/workflow/admission/recovery.js

@@ -0,0 +1,47 @@
+import { requireValue } from "../../runtime/action-process.mjs";
+import { completeUniversalWorkflow } from "../universal-workflow-bootstrap.js";
+
+export function recoveryCoordinates(request) {
+  const candidate = request.candidate;
+  requireValue(
+    request.schema === "kungfu-buildchain-v4-universal-workflow-request/v1" &&
+      request.mode === "train",
+    "Recovery requires the current Train request envelope",
+  );
+  requireValue(
+    candidate?.repository === "kungfu-systems/buildchain" &&
+      /^train\/v4\/v4\.\d+\/[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(
+        candidate.discoveryRef || "",
+      ) &&
+      !candidate.discoveryRef.split("/").includes(".."),
+    "Recovery requires a Buildchain capability Train",
+  );
+  requireValue(
+    /^[0-9a-f]{40}$/u.test(candidate.expectedSha || "") &&
+      Number.isSafeInteger(candidate.reviewPullRequest) &&
+      candidate.reviewPullRequest > 0,
+    "Recovery requires an exact candidate SHA and review PR",
+  );
+  return {
+    repository: candidate.repository,
+    ref: candidate.discoveryRef,
+    sha: candidate.expectedSha,
+    pr: candidate.reviewPullRequest,
+  };
+}
+export function recoveryTerminalReceipt(admission, result) {
+  requireValue(
+    result.schema === "kungfu-buildchain-v4-universal-workflow-result/v1" &&
+      ["succeeded", "failed"].includes(result.status) &&
+      result.requestRoot === admission.requestRoot &&
+      result.capabilityRoot === admission.capabilityRoot &&
+      result.runtime?.repository === admission.runtime?.repository &&
+      result.runtime?.sha === admission.runtime?.sha,
+    "candidate result does not match the consumer-owned admission lineage",
+  );
+  return completeUniversalWorkflow({
+    admission,
+    resultRoot: result.resultRoot,
+    status: result.status,
+  });
+}

package/packages/core/workflow/admission/review.js

@@ -0,0 +1,188 @@
+import { workflowInstallationRoot } from "../installation.js";
+import path from "node:path";
+import fs from "node:fs";
+import { command, requireValue } from "../../runtime/action-process.mjs";
+
+function exactTime(value) {
+  const time = new Date(value);
+  requireValue(Number.isFinite(time.getTime()), "Review timestamp is invalid");
+  return time.toISOString();
+}
+export function bootstrapVersionLine(
+  runtimeRoot = workflowInstallationRoot(import.meta.url),
+) {
+  const version = JSON.parse(
+    fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8"),
+  ).version;
+  const match = /^(\d+)\.(\d+)\.\d+(?:-[0-9A-Za-z.-]+)?$/u.exec(version);
+  requireValue(
+    match,
+    "Bootstrap package version must declare its release line",
+  );
+  return {
+    development: `dev/v${match[1]}/v${match[1]}.${match[2]}`,
+    alpha: `alpha/v${match[1]}/v${match[1]}.${match[2]}`,
+  };
+}
+export function reviewedCandidateEvidence({
+  request,
+  pr,
+  reviews,
+  checks,
+  commit,
+  line,
+  observedAt,
+}) {
+  const candidate = request.candidate;
+  const matches =
+    pr.head?.repo?.full_name === candidate.repository &&
+    pr.number === candidate.reviewPullRequest;
+  let kind;
+  if (
+    matches &&
+    pr.head.sha === candidate.expectedSha &&
+    pr.base?.ref === line.development
+  )
+    kind = "reviewed-head";
+  else if (
+    matches &&
+    request.mode === "alpha" &&
+    pr.merged === true &&
+    pr.merge_commit_sha === candidate.expectedSha &&
+    pr.base?.ref === line.alpha
+  )
+    kind = "protected-alpha-merge";
+  requireValue(kind, "review does not bind the exact candidate runtime");
+  const reviewedSha = pr.head.sha.toLowerCase();
+  const latestReviews = new Map();
+  for (const review of [...reviews].sort(
+    (a, b) =>
+      Date.parse(exactTime(a.submitted_at)) -
+      Date.parse(exactTime(b.submitted_at)),
+  )) {
+    if (["APPROVED", "CHANGES_REQUESTED", "DISMISSED"].includes(review.state))
+      latestReviews.set(review.user?.login?.toLowerCase(), review);
+  }
+  const latestChecks = new Map();
+  for (const check of [...checks].sort((a, b) => (a.id || 0) - (b.id || 0))) {
+    if (check.head_sha)
+      requireValue(
+        check.head_sha === candidate.expectedSha,
+        "Check belongs to a different candidate",
+      );
+    latestChecks.set(check.name, check);
+  }
+  reviews = [...latestReviews.values()];
+  checks = [...latestChecks.values()];
+  requireValue(
+    reviews.some(
+      (review) =>
+        review.state === "APPROVED" &&
+        review.commit_id === reviewedSha &&
+        review.user?.login?.toLowerCase() === "kungfu-origin",
+    ),
+    "Exact candidate requires independent kungfu-origin approval",
+  );
+  requireValue(
+    checks.some(
+      (check) =>
+        check.name === "check" &&
+        check.status === "completed" &&
+        check.conclusion === "success",
+    ),
+    "Exact candidate requires successful check",
+  );
+  return {
+    repository: candidate.repository,
+    pullRequest: candidate.reviewPullRequest,
+    headSha: reviewedSha,
+    baseRef: pr.base.ref,
+    approvals: reviews
+      .filter(
+        (review) =>
+          review.state === "APPROVED" && review.commit_id === reviewedSha,
+      )
+      .map((review) => ({
+        reviewer: review.user.login.toLowerCase(),
+        commitSha: review.commit_id,
+        submittedAt: exactTime(review.submitted_at),
+      })),
+    checks: checks
+      .filter((check) => check.status === "completed" && check.conclusion)
+      .map(({ name, status, conclusion }) => ({
+        name,
+        status,
+        conclusion,
+        commitSha: candidate.expectedSha,
+      })),
+    runtimeBinding: {
+      kind,
+      runtimeSha: candidate.expectedSha,
+      parentShas: commit.parents.map(({ sha }) => sha.toLowerCase()),
+      mergedAt:
+        kind === "protected-alpha-merge" ? exactTime(pr.merged_at) : null,
+    },
+    observedAt: exactTime(observedAt),
+  };
+}
+export function readCandidateReview(
+  { request, workspace, runtimeRoot, candidateRoot, token },
+  execute = command,
+) {
+  if (!token)
+    throw new Error("Candidate review requires an explicit read credential");
+  const { repository, expectedSha, reviewPullRequest } = request.candidate;
+  const observed = execute("git", ["-C", candidateRoot, "rev-parse", "HEAD"], {
+    stdio: ["ignore", "pipe", "inherit"],
+  })
+    .trim()
+    .toLowerCase();
+  requireValue(
+    observed === expectedSha,
+    "Candidate checkout does not match its expected SHA",
+  );
+  const api = (endpoint, paginate = false) =>
+    JSON.parse(
+      execute(
+        "gh",
+        [
+          "api",
+          ...(paginate ? ["--paginate", "--slurp"] : []),
+          "-H",
+          "Accept: application/vnd.github+json",
+          `repos/${repository}/${endpoint}`,
+        ],
+        {
+          stdio: ["ignore", "pipe", "inherit"],
+          env: { ...process.env, GH_TOKEN: token },
+        },
+      ),
+    );
+  const pr = api(`pulls/${reviewPullRequest}`);
+  const reviews = api(`pulls/${reviewPullRequest}/reviews`, true).flat();
+  const checks = api(
+    `commits/${expectedSha}/check-runs?per_page=100`,
+    true,
+  ).flatMap((page) => page.check_runs);
+  const commit = api(`git/commits/${expectedSha}`);
+  fs.mkdirSync(path.join(workspace, ".buildchain"), { recursive: true });
+  for (const [name, value] of Object.entries({
+    pr,
+    reviews,
+    checks,
+    "runtime-commit": commit,
+  }))
+    fs.writeFileSync(
+      path.join(workspace, `.buildchain/${name}.json`),
+      JSON.stringify(value) + "\n",
+    );
+  return reviewedCandidateEvidence({
+    request,
+    pr,
+    reviews,
+    checks,
+    commit,
+    line: bootstrapVersionLine(runtimeRoot),
+    observedAt: new Date().toISOString(),
+  });
+}

package/packages/core/workflow/admission/transactions.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { command } from "../../runtime/action-process.mjs";
+import {
+  validateUniversalWorkflowRequest,
+  universalWorkflowRequestRoot,
+  admitUniversalWorkflow,
+} from "../universal-workflow-bootstrap.js";
+import { recoveryCoordinates } from "./recovery.js";
+export function inspectUniversalRequest(request, recovery = false) {
+  if (recovery) recoveryCoordinates(request);
+  const value = validateUniversalWorkflowRequest(request);
+  return {
+    mode: value.mode,
+    repository: value.candidate.repository,
+    "discovery-ref": value.candidate.discoveryRef,
+    "expected-sha": value.candidate.expectedSha,
+    "review-pr": value.candidate.reviewPullRequest,
+    "capability-id": value.capability.id,
+    "request-root": universalWorkflowRequestRoot(value),
+  };
+}
+export function admitReviewedWorkflow({
+  request,
+  reviewEvidence,
+  workspace,
+  candidateRoot,
+  consumer,
+}) {
+  const observedSha = command(
+    "git",
+    ["-C", candidateRoot, "rev-parse", "HEAD"],
+    { stdio: "pipe" },
+  )
+    .trim()
+    .toLowerCase();
+  const policy = JSON.parse(
+    fs.readFileSync(
+      path.join(
+        candidateRoot,
+        "architecture/universal-workflow-train-admission.json",
+      ),
+      "utf8",
+    ),
+  );
+  const admitted = admitUniversalWorkflow({
+    request,
+    policy,
+    observedRefSha: observedSha,
+    observedConsumerRepository: consumer.repository,
+    observedConsumerSha: consumer.sha,
+    observedConsumerWorkflowRef: consumer.workflowRef,
+    reviewEvidence,
+    now: new Date().toISOString(),
+  });
+  const file = path.join(workspace, ".buildchain/admission.json");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(admitted, null, 2) + "\n");
+  return admitted;
+}

package/packages/core/workflow/cli/main.mjs

@@ -0,0 +1,131 @@
+import { initializeCliRuntime } from "../../contracts/cli/context.mjs";
+import { BUILDCHAIN_USAGE } from "../commands/buildchain-cli-help.mjs";
+import { formatCliHelp } from "../../contracts/cli-reference.js";
+import {
+  TRUST_RELEASE_COMMANDS,
+  dispatchTrustReleaseCommand,
+} from "../../release/cli/trust-release.mjs";
+import { dispatchRegisteredCommand } from "../../contracts/command-registry.mjs";
+import { handleAdopterDeliveryCommand } from "../../adoption/cli/dispatch.mjs";
+import { handleKfdCommand } from "../../adoption/cli/kfd.mjs";
+import {
+  handleInitCommand,
+  handleValidateCommand,
+} from "../../adoption/cli/project.mjs";
+import { handlePortableCacheCommand } from "../../build/cli/cache.mjs";
+import { handleFactsCommand } from "../../build/cli/facts.mjs";
+import { handleHomebrewCommand } from "../../build/cli/homebrew.mjs";
+import {
+  handleBuildContractCommand,
+  handleLifecycleCommand,
+} from "../../build/cli/lifecycle.mjs";
+import { handleInfraContractCommand } from "../../consumer/cli/infrastructure.mjs";
+import {
+  handleHelpCommand,
+  handleLayoutCommand,
+  handleVersionCommand,
+} from "../../contracts/cli/introspection.mjs";
+import { handleDevCommand } from "../../dev-delivery/cli/dispatch.mjs";
+import {
+  handleArchitectureCommand,
+  handleGitHubGovernanceCommand,
+  handleReleaseGovernanceCommand,
+} from "../../governance/cli/dispatch.mjs";
+import { handleDoctorCommand } from "../../governance/cli/doctor.mjs";
+import { handleCandidateCommand } from "../../observability/cli/candidate.mjs";
+import { handleDiagnosticsCommand } from "../../observability/cli/diagnostics.mjs";
+import {
+  handleLogCommand,
+  handleMarkCommand,
+  handleSpanCommand,
+} from "../../observability/cli/events.mjs";
+import { handleSampleCommand } from "../../observability/cli/process-sample.mjs";
+import { handlePaperCommand } from "../../paper/cli/dispatch.mjs";
+import {
+  handleNpmCommand,
+  handlePublicationArtifactCommand,
+  handlePublishSourceCommand,
+} from "../../publication/cli/dispatch.mjs";
+import {
+  handleNextDevelopmentCommand,
+  handleReleasePropagationCommand,
+  handleReleaseTailCommand,
+  handleTailResealCommand,
+  handleTrustReleaseCommand,
+} from "../../release/cli/dispatch.mjs";
+import { handleBadgesCommand } from "../../web/cli/badges.mjs";
+import { handleWebSurfaceCommand } from "../../web/cli/surface.mjs";
+
+export async function main(argv = process.argv.slice(2)) {
+  const helpIndex = argv.findIndex(
+    (entry) => entry === "--help" || entry === "-h",
+  );
+  if (helpIndex >= 0) {
+    process.stdout.write(
+      formatCliHelp({
+        usageText: BUILDCHAIN_USAGE,
+        pathParts: argv.slice(0, helpIndex),
+      }),
+    );
+    return;
+  }
+  const [command = "help", ...args] = argv;
+  return dispatchRegisteredCommand({
+    command,
+    args,
+    handlers: BUILDCHAIN_COMMAND_HANDLERS,
+  });
+}
+
+export const BUILDCHAIN_COMMAND_HANDLERS = Object.freeze({
+  help: handleHelpCommand,
+  version: handleVersionCommand,
+  layout: handleLayoutCommand,
+  "portable-cache": handlePortableCacheCommand,
+  candidate: handleCandidateCommand,
+  init: handleInitCommand,
+  validate: handleValidateCommand,
+  doctor: handleDoctorCommand,
+  dev: handleDevCommand,
+  log: handleLogCommand,
+  diagnostics: handleDiagnosticsCommand,
+  facts: handleFactsCommand,
+  kfd: handleKfdCommand,
+  sample: handleSampleCommand,
+  mark: handleMarkCommand,
+  span: handleSpanCommand,
+  lifecycle: handleLifecycleCommand,
+  npm: handleNpmCommand,
+  ...Object.fromEntries(
+    [...TRUST_RELEASE_COMMANDS].map((command) => [
+      command,
+      (args) => handleTrustReleaseCommand(args, { command }),
+    ]),
+  ),
+  "web-surface": handleWebSurfaceCommand,
+  "infra-contract": handleInfraContractCommand,
+  "publication-artifact": handlePublicationArtifactCommand,
+  paper: handlePaperCommand,
+  "release-propagation": handleReleasePropagationCommand,
+  "release-governance": handleReleaseGovernanceCommand,
+  "release-tail": handleReleaseTailCommand,
+  "tail-reseal": handleTailResealCommand,
+  "next-development": handleNextDevelopmentCommand,
+  "github-governance": handleGitHubGovernanceCommand,
+  badges: handleBadgesCommand,
+  homebrew: handleHomebrewCommand,
+  "build-contract": handleBuildContractCommand,
+  "publish-source": handlePublishSourceCommand,
+  architecture: handleArchitectureCommand,
+  "adopter-delivery": handleAdopterDeliveryCommand,
+});
+
+export async function runCli(entryUrl, argv = process.argv.slice(2)) {
+  try {
+    initializeCliRuntime(entryUrl);
+    await main(argv);
+  } catch (error) {
+    console.error(`buildchain: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/workflow/cli/process.mjs

@@ -0,0 +1,16 @@
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { root } from "../../contracts/cli/context.mjs";
+
+export function runScript(scriptName, args, runner = process.execPath) {
+  const scriptPath = path.join(root, scriptName);
+  const result = spawnSync(runner, [scriptPath, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  process.exitCode = result.status ?? 1;
+}