@kungfu-tech/buildchain 4.0.1-alpha.2 → 4.0.1-alpha.3

package/scripts/dev-delivery-warrant-options.mjs

@@ -0,0 +1,266 @@
+export function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : args[index + 1] || "";
+}
+
+export function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+export function devDeliveryCliOptions(args = [], environment = process.env) {
+  const [command = "", ...rest] = args;
+  return {
+    command,
+    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
+    branch: flag(
+      rest,
+      "branch",
+      environment.BUILDCHAIN_DEV_DELIVERY_BRANCH || environment.GITHUB_BASE_REF,
+    ),
+    stateRef: flag(
+      rest,
+      "state-ref",
+      environment.BUILDCHAIN_DEV_DELIVERY_STATE_REF,
+    ),
+    expectedOldStateRoot: flag(
+      rest,
+      "expected-old",
+      environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_OLD,
+    ),
+    pullRequestNumber: flag(
+      rest,
+      "pull-request",
+      environment.BUILDCHAIN_DEV_DELIVERY_PR_NUMBER,
+    ),
+    candidateId: flag(
+      rest,
+      "candidate-id",
+      environment.BUILDCHAIN_DEV_DELIVERY_CANDIDATE_ID,
+    ),
+    sourceHead: flag(
+      rest,
+      "source-head",
+      environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_HEAD,
+    ),
+    expectedSourceHead: flag(
+      rest,
+      "expected-source-head",
+      environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_SOURCE_HEAD,
+    ),
+    observedSourceHead: flag(
+      rest,
+      "observed-source-head",
+      environment.BUILDCHAIN_DEV_DELIVERY_OBSERVED_SOURCE_HEAD,
+    ),
+    assignmentRoot: flag(
+      rest,
+      "assignment-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_ASSIGNMENT_ROOT,
+    ),
+    initiativeRoot: flag(
+      rest,
+      "initiative-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_INITIATIVE_ROOT,
+    ),
+    sourceIdentityRoot: flag(
+      rest,
+      "source-identity-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_IDENTITY_ROOT,
+    ),
+    sourcePatchRoot: flag(
+      rest,
+      "source-patch-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PATCH_ROOT,
+    ),
+    sourceProofRoot: flag(
+      rest,
+      "source-proof-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_PROOF_ROOT,
+    ),
+    sourceWorkflowRunId: flag(
+      rest,
+      "source-workflow-run-id",
+      environment.BUILDCHAIN_DEV_DELIVERY_SOURCE_WORKFLOW_RUN_ID,
+    ),
+    affectedPaths: flag(
+      rest,
+      "affected-paths-json",
+      environment.BUILDCHAIN_DEV_DELIVERY_AFFECTED_PATHS || "[]",
+    ),
+    shardEvidenceRoots: flag(
+      rest,
+      "shard-evidence-roots-json",
+      environment.BUILDCHAIN_DEV_DELIVERY_SHARD_EVIDENCE_ROOTS || "[]",
+    ),
+    nativeCommand: flag(
+      rest,
+      "native-command",
+      environment.BUILDCHAIN_DEV_DELIVERY_NATIVE_COMMAND,
+    ),
+    nativeCommandRoot: flag(
+      rest,
+      "native-command-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_NATIVE_COMMAND_ROOT,
+    ),
+    releaseBlockerPriority: flag(
+      rest,
+      "release-blocker-priority-json",
+      environment.BUILDCHAIN_DEV_DELIVERY_RELEASE_BLOCKER_PRIORITY,
+    ),
+    nativeProofPath: flag(
+      rest,
+      "native-proof",
+      environment.BUILDCHAIN_DEV_DELIVERY_NATIVE_PROOF,
+    ),
+    nativeReuseDecisionPath: flag(
+      rest,
+      "native-reuse-decision",
+      environment.BUILDCHAIN_DEV_DELIVERY_NATIVE_REUSE_DECISION,
+    ),
+    currentBase: flag(
+      rest,
+      "current-base",
+      environment.BUILDCHAIN_DEV_DELIVERY_CURRENT_BASE,
+    ),
+    changedPaths: flag(
+      rest,
+      "changed-paths-json",
+      environment.BUILDCHAIN_DEV_DELIVERY_CHANGED_PATHS || "[]",
+    ),
+    graphKnown: ["1", "true", "yes", "on"].includes(
+      flag(rest, "graph-known", environment.BUILDCHAIN_DEV_DELIVERY_GRAPH_KNOWN)
+        .trim()
+        .toLowerCase(),
+    ),
+    attributionComplete: ["1", "true", "yes", "on"].includes(
+      flag(
+        rest,
+        "attribution-complete",
+        environment.BUILDCHAIN_DEV_DELIVERY_ATTRIBUTION_COMPLETE,
+      )
+        .trim()
+        .toLowerCase(),
+    ),
+    renames: flag(
+      rest,
+      "renames-json",
+      environment.BUILDCHAIN_DEV_DELIVERY_RENAMES || "[]",
+    ),
+    planRoot: flag(
+      rest,
+      "plan-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_PLAN_ROOT,
+    ),
+    closureRoot: flag(
+      rest,
+      "closure-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_CLOSURE_ROOT,
+    ),
+    dependencyRoot: flag(
+      rest,
+      "dependency-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_DEPENDENCY_ROOT,
+    ),
+    toolchainRoot: flag(
+      rest,
+      "toolchain-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_TOOLCHAIN_ROOT,
+    ),
+    environmentRoot: flag(
+      rest,
+      "environment-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_ENVIRONMENT_ROOT,
+    ),
+    deliveryClass: flag(
+      rest,
+      "delivery-class",
+      environment.BUILDCHAIN_DEV_DELIVERY_CLASS,
+    ),
+    priority: flag(
+      rest,
+      "priority",
+      environment.BUILDCHAIN_DEV_DELIVERY_PRIORITY || "ordinary",
+    ),
+    fencingToken: flag(
+      rest,
+      "fencing-token",
+      environment.BUILDCHAIN_DEV_DELIVERY_FENCING_TOKEN,
+    ),
+    leaseGeneration: flag(
+      rest,
+      "lease-generation",
+      environment.BUILDCHAIN_DEV_DELIVERY_LEASE_GENERATION,
+    ),
+    leaseSeconds: flag(
+      rest,
+      "lease-seconds",
+      environment.BUILDCHAIN_DEV_DELIVERY_LEASE_SECONDS,
+    ),
+    outcome: flag(rest, "outcome", environment.BUILDCHAIN_DEV_DELIVERY_OUTCOME),
+    eventAction: flag(
+      rest,
+      "event-action",
+      environment.BUILDCHAIN_DEV_DELIVERY_EVENT_ACTION,
+    ),
+    evidenceRoot: flag(
+      rest,
+      "evidence-root",
+      environment.BUILDCHAIN_DEV_DELIVERY_EVIDENCE_ROOT,
+    ),
+    transferRoot: flag(rest, "transfer-root"),
+    finalizerBoundaryRoot: flag(rest, "finalizer-boundary-root"),
+    nativeJobId: flag(rest, "native-job-id"),
+    sealJobId: flag(rest, "seal-job-id"),
+    reason: flag(rest, "reason", environment.BUILDCHAIN_DEV_DELIVERY_REASON),
+    readMode: flag(
+      rest,
+      "read-mode",
+      environment.BUILDCHAIN_V4_WARRANT_READ_MODE || "v3",
+    ),
+    readQualificationPath: flag(
+      rest,
+      "read-qualification",
+      environment.BUILDCHAIN_V4_WARRANT_READ_QUALIFICATION,
+    ),
+    readQualificationRoot: flag(
+      rest,
+      "read-qualification-root",
+      environment.BUILDCHAIN_V4_WARRANT_READ_QUALIFICATION_ROOT,
+    ),
+    readTypescriptRevision: flag(
+      rest,
+      "read-typescript-revision",
+      environment.BUILDCHAIN_V4_WARRANT_TYPESCRIPT_REVISION,
+    ),
+    readRustRevision: flag(
+      rest,
+      "read-rust-revision",
+      environment.BUILDCHAIN_V4_WARRANT_RUST_REVISION,
+    ),
+    readValidatorVersion: flag(
+      rest,
+      "read-validator-version",
+      environment.BUILDCHAIN_V4_WARRANT_VALIDATOR_VERSION,
+    ),
+    readTimeoutMs: flag(
+      rest,
+      "read-timeout-ms",
+      environment.BUILDCHAIN_V4_WARRANT_READ_TIMEOUT_MS || "5000",
+    ),
+    readEvidenceOutput: flag(
+      rest,
+      "read-evidence-output",
+      environment.BUILDCHAIN_V4_WARRANT_READ_EVIDENCE ||
+        ".buildchain/dev-delivery/v4-read-evidence.json",
+    ),
+    now: flag(rest, "now", environment.BUILDCHAIN_DEV_DELIVERY_NOW),
+    outputPath: flag(
+      rest,
+      "output",
+      environment.BUILDCHAIN_DEV_DELIVERY_OUTPUT ||
+        ".buildchain/dev-delivery/result.json",
+    ),
+    execute: hasFlag(rest, "execute"),
+    json: hasFlag(rest, "json"),
+  };
+}

package/scripts/dev-delivery-warrant-store.mjs

@@ -0,0 +1,227 @@
+import { isDeepStrictEqual } from "node:util";
+import {
+  createDevDeliveryQueue,
+  devDeliveryContentRoot,
+  normalizeDevDeliveryQueue,
+} from "../packages/core/dev-delivery-warrant.js";
+import { normalizeDevDeliveryAuthorityState } from "../packages/core/dev-delivery-authority-state.js";
+
+const STATE_PATH = "queue.json";
+
+function text(value = "") {
+  return String(value ?? "").trim();
+}
+
+function exactSha(value, label) {
+  const normalized = text(value).toLowerCase();
+  if (!/^[0-9a-f]{40}$/.test(normalized)) {
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  }
+  return normalized;
+}
+
+function normalizeRepository(value) {
+  const normalized = text(value);
+  const match = normalized.match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(
+      `repository must be owner/repo, got ${normalized || "<empty>"}`,
+    );
+  }
+  return { owner: match[1], repo: match[2], fullName: normalized };
+}
+
+function encodeRef(ref) {
+  return ref.split("/").map(encodeURIComponent).join("/");
+}
+
+function decodeBlob(blob) {
+  if (blob.encoding !== "base64")
+    throw new Error(
+      `unsupported Git blob encoding ${blob.encoding || "<empty>"}`,
+    );
+  return Buffer.from(
+    String(blob.content || "").replace(/\s+/g, ""),
+    "base64",
+  ).toString("utf8");
+}
+
+function validateStoredState(queue) {
+  const body = structuredClone(queue || {});
+  const embeddedStateRoot = body.stateRoot;
+  delete body.stateRoot;
+  if (embeddedStateRoot !== devDeliveryContentRoot(body)) {
+    throw new Error("dev delivery persisted stateRoot drift");
+  }
+  if (
+    queue?.contract === "kungfu-buildchain-dev-delivery-authority" &&
+    Number(queue?.schemaVersion) === 2
+  ) {
+    normalizeDevDeliveryAuthorityState(queue);
+  } else {
+    normalizeDevDeliveryQueue(queue);
+  }
+  return queue;
+}
+
+export class GitHubDevDeliveryStore {
+  constructor({
+    repository,
+    token,
+    apiUrl = "https://api.github.com",
+    fetchImpl = globalThis.fetch,
+    createInitialState = createDevDeliveryQueue,
+  } = {}) {
+    this.repository = normalizeRepository(repository);
+    if (!fetchImpl) throw new Error("fetch is required");
+    if (!token)
+      throw new Error(
+        "GITHUB_TOKEN is required for the GitHub dev delivery store",
+      );
+    this.token = token;
+    this.apiUrl = apiUrl.replace(/\/+$/, "");
+    this.fetch = fetchImpl;
+    this.createInitialState = createInitialState;
+  }
+
+  async request(method, requestPath, body) {
+    const response = await this.fetch(`${this.apiUrl}${requestPath}`, {
+      method,
+      headers: {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${this.token}`,
+        "content-type": "application/json",
+        "x-github-api-version": "2022-11-28",
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const raw = await response.text();
+    const data = raw ? JSON.parse(raw) : null;
+    if (!response.ok) {
+      const error = new Error(
+        data?.message || raw || `${method} ${requestPath} failed`,
+      );
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+    return data;
+  }
+
+  async read({ stateRef, protectedBase, now }) {
+    let ref;
+    try {
+      ref = await this.request(
+        "GET",
+        `/repos/${this.repository.fullName}/git/ref/heads/${encodeRef(stateRef)}`,
+      );
+    } catch (error) {
+      if (error.status !== 404) throw error;
+      return {
+        exists: false,
+        commitSha: "",
+        queue: this.createInitialState({
+          repository: this.repository.fullName,
+          protectedBase,
+          now,
+        }),
+      };
+    }
+    const commitSha = exactSha(ref?.object?.sha, "state ref commit");
+    const readback = await this.readCommit(commitSha);
+    return { exists: true, ...readback };
+  }
+
+  async readCommit(commitShaInput) {
+    const commitSha = exactSha(commitShaInput, "state commit");
+    const commit = await this.request(
+      "GET",
+      `/repos/${this.repository.fullName}/git/commits/${commitSha}`,
+    );
+    const tree = await this.request(
+      "GET",
+      `/repos/${this.repository.fullName}/git/trees/${commit.tree?.sha}`,
+    );
+    const entry = (tree.tree || []).find(
+      (item) => item.path === STATE_PATH && item.type === "blob",
+    );
+    if (!entry?.sha)
+      throw new Error(`${commitSha} does not contain ${STATE_PATH}`);
+    const blob = await this.request(
+      "GET",
+      `/repos/${this.repository.fullName}/git/blobs/${entry.sha}`,
+    );
+    const bytes = decodeBlob(blob);
+    const queue = validateStoredState(JSON.parse(bytes));
+    return { commitSha, queue, bytes };
+  }
+
+  async write({
+    stateRef,
+    queue,
+    expectedCommitSha,
+    expectedStateRoot,
+    receiptRoot,
+  }) {
+    if (queue.stateRoot === expectedStateRoot)
+      throw new Error("state transition did not advance the queue root");
+    const parent = expectedCommitSha
+      ? exactSha(expectedCommitSha, "expected state commit")
+      : "";
+    validateStoredState(queue);
+    const expectedBytes = `${JSON.stringify(queue, null, 2)}\n`;
+    const blob = await this.request(
+      "POST",
+      `/repos/${this.repository.fullName}/git/blobs`,
+      {
+        content: expectedBytes,
+        encoding: "utf-8",
+      },
+    );
+    const tree = await this.request(
+      "POST",
+      `/repos/${this.repository.fullName}/git/trees`,
+      {
+        tree: [
+          { path: STATE_PATH, mode: "100644", type: "blob", sha: blob.sha },
+        ],
+      },
+    );
+    const commit = await this.request(
+      "POST",
+      `/repos/${this.repository.fullName}/git/commits`,
+      {
+        message: `chore(dev-delivery): advance Warrant queue ${receiptRoot.slice(0, 20)}`,
+        tree: tree.sha,
+        parents: parent ? [parent] : [],
+      },
+    );
+    if (expectedCommitSha) {
+      await this.request(
+        "PATCH",
+        `/repos/${this.repository.fullName}/git/refs/heads/${encodeRef(stateRef)}`,
+        { sha: commit.sha, force: false },
+      );
+    } else {
+      await this.request(
+        "POST",
+        `/repos/${this.repository.fullName}/git/refs`,
+        {
+          ref: `refs/heads/${stateRef}`,
+          sha: commit.sha,
+        },
+      );
+    }
+    const readback = await this.readCommit(commit.sha);
+    if (
+      readback.commitSha !== commit.sha ||
+      readback.bytes !== expectedBytes ||
+      !isDeepStrictEqual(readback.queue, queue)
+    ) {
+      throw new Error(
+        "dev delivery state commit readback mismatch after expected-old update",
+      );
+    }
+    return { commitSha: commit.sha, stateRoot: readback.queue.stateRoot };
+  }
+}