@kungfu-tech/buildchain 0.0.0-bootstrap.0 → 2.0.13-alpha.11

package/scripts/release-line-policy.mjs

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const MAJOR_GATE_REF = "publish-gate/major";
+export const LEGACY_MAJOR_GATE_REF = "major-gate";
+export const MAJOR_GATE_CHANNEL = "major";
+
+export function normalizeRef(ref) {
+  return String(ref || "").replace(/^refs\/heads\//, "");
+}
+
+export function isMajorGateRef(ref) {
+  const normalizedRef = normalizeRef(ref);
+  return normalizedRef === MAJOR_GATE_REF || normalizedRef === LEGACY_MAJOR_GATE_REF;
+}
+
+export function parseVersionStateRef(ref) {
+  const normalizedRef = normalizeRef(ref);
+  if (/^buildchain\/version-state\/publish-gate-major\/[0-9a-f]{12,40}$/.test(normalizedRef)) {
+    return {
+      channel: MAJOR_GATE_CHANNEL,
+      normalizedRef: MAJOR_GATE_REF,
+      lineSuffix: "",
+    };
+  }
+
+  if (/^buildchain\/version-state\/major-gate\/[0-9a-f]{12,40}$/.test(normalizedRef)) {
+    return {
+      channel: MAJOR_GATE_CHANNEL,
+      normalizedRef: LEGACY_MAJOR_GATE_REF,
+      lineSuffix: "",
+    };
+  }
+
+  const match = normalizedRef.match(
+    /^buildchain\/version-state\/(alpha|release)-v(\d+)-v(\d+\.\d+)\/[0-9a-f]{12,40}$/,
+  );
+  if (!match) return undefined;
+  return {
+    channel: match[1],
+    major: Number(match[2]),
+    loose: Number(match[3]),
+    normalizedRef: `${match[1]}/v${match[2]}/v${match[3]}`,
+    lineSuffix: `/v${match[2]}/v${match[3]}`,
+  };
+}
+
+export function getChannel(ref) {
+  const versionStateTarget = parseVersionStateRef(ref);
+  if (versionStateTarget) return versionStateTarget.channel;
+  const normalizedRef = normalizeRef(ref);
+  if (isMajorGateRef(normalizedRef)) return MAJOR_GATE_CHANNEL;
+  return normalizedRef.split("/")[0];
+}
+
+export function getLineSuffix(ref, channel) {
+  const versionStateTarget = parseVersionStateRef(ref);
+  if (versionStateTarget) return versionStateTarget.lineSuffix;
+  if (isMajorGateRef(ref)) return "";
+  return normalizeRef(ref).replace(channel, "");
+}
+
+export function readCurrentVersion(cwd = process.cwd()) {
+  const packagePath = path.join(cwd, fs.existsSync(path.join(cwd, "lerna.json")) ? "lerna.json" : "package.json");
+  const config = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return parseVersion(config.version);
+}
+
+export function parseVersion(value) {
+  const match = String(value || "").match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) {
+    throw new Error(`Invalid version: ${value}`);
+  }
+  return {
+    version: match[0],
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+export function getBumpKeyword({ cwd = process.cwd(), headRef, baseRef, loose = false } = {}) {
+  const version = readCurrentVersion(cwd);
+  const looseVersionNumber = Number(`${version.major}.${version.minor}`);
+  const lastLooseVersionNumber = Number((looseVersionNumber - 0.1).toFixed(1));
+  const versionStateTarget = parseVersionStateRef(headRef);
+  const headChannel = getChannel(headRef);
+  const baseChannel = getChannel(baseRef);
+  const key = `${headChannel}->${baseChannel}`;
+  const keywords = {
+    "dev->alpha": "prerelease",
+    "alpha->release": "patch",
+    "release->major": "premajor",
+    "release->release": "preminor",
+  };
+
+  const lts = baseChannel === "release" && normalizeRef(baseRef).split("/").pop() === "lts";
+  const preminor = headChannel === "release" && lts;
+  const majorGate = headChannel === "release" && baseChannel === MAJOR_GATE_CHANNEL;
+
+  if (getLineSuffix(headRef, headChannel) !== getLineSuffix(baseRef, baseChannel) && !preminor && !majorGate) {
+    throw new Error(`Versions not match for head/base refs: ${headRef} -> ${baseRef}`);
+  }
+
+  if (versionStateTarget) {
+    if (versionStateTarget.channel !== baseChannel) {
+      throw new Error(`Versions not match for head/base refs: ${headRef} -> ${baseRef}`);
+    }
+    return baseChannel === "release" || baseChannel === MAJOR_GATE_CHANNEL ? "patch" : "prerelease";
+  }
+
+  const normalizedHeadRef = normalizeRef(headRef);
+  const headMatch = normalizedHeadRef.match(/(\w+)\/v(\d+)\/v(\d+\.\d)/);
+  const mismatchMsg = `The version of head ref ${headRef} does not match current ${version.version}`;
+
+  if (!headMatch) {
+    throw new Error(mismatchMsg);
+  }
+
+  const headMajor = Number(headMatch[2]);
+  const headLoose = Number(headMatch[3]);
+
+  if (headMajor !== version.major || headLoose > looseVersionNumber) {
+    throw new Error(mismatchMsg);
+  }
+
+  if (headLoose < lastLooseVersionNumber) {
+    throw new Error(mismatchMsg);
+  }
+
+  if (headLoose === lastLooseVersionNumber && !loose) {
+    throw new Error(mismatchMsg);
+  }
+
+  const keyword = keywords[key];
+  if (!keyword) {
+    throw new Error(`No rule to bump for head/base refs: ${headRef} -> ${baseRef}`);
+  }
+  return keyword;
+}

package/scripts/release-transaction.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  createReleaseTransaction,
+  defaultPublishEvidencePath,
+  defaultReleaseStatePath,
+  planTransactionRecovery,
+  readPublishEvidence,
+  readReleaseTransaction,
+  transitionReleaseTransaction,
+  validatePublishEvidence,
+  writeReleaseTransaction,
+} from "../packages/core/publish-transaction.js";
+
+function usage() {
+  return `Usage:
+  buildchain release inspect --version <tag> [--state-path <path>] [--evidence-path <path>]
+  buildchain release recover --version <tag> [--state-path <path>] [--evidence-path <path>] [--override]
+  buildchain release finalize --version <tag> [--state-path <path>] [--evidence-path <path>]
+  buildchain release abort --version <tag> --superseded-by <tag> [--state-path <path>]
+
+Required creation flags when no state file exists:
+  --repository <owner/repo> --source-sha <sha> --release-sha <sha> --target-ref <ref> --channel <channel>
+
+Optional validation flags:
+  --release-material-sha <sha> --publish-tooling-sha <sha> --required-artifacts-json <json>
+`;
+}
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === "-h" || command === "--help") {
+    return { command: "help" };
+  }
+  const options = { _: [] };
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+    if (!value.startsWith("--")) {
+      options._.push(value);
+      continue;
+    }
+    const key = value.slice(2);
+    if (key === "override") {
+      options.override = true;
+      continue;
+    }
+    const next = rest[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      throw new Error(`missing value for --${key}`);
+    }
+    options[key.replaceAll("-", "_")] = next;
+    index += 1;
+  }
+  return { command, options };
+}
+
+function requireOption(options, key) {
+  if (!options[key]) {
+    throw new Error(`--${key.replaceAll("_", "-")} is required`);
+  }
+  return options[key];
+}
+
+function statePath(options) {
+  return path.resolve(options.state_path || defaultReleaseStatePath(requireOption(options, "version")));
+}
+
+function evidencePath(options) {
+  return path.resolve(options.evidence_path || defaultPublishEvidencePath(requireOption(options, "version")));
+}
+
+function loadOrCreate(options) {
+  const filePath = statePath(options);
+  const existing = readReleaseTransaction(filePath);
+  if (existing) {
+    return { record: existing, filePath, created: false };
+  }
+  const record = createReleaseTransaction({
+    repository: requireOption(options, "repository"),
+    version: requireOption(options, "version"),
+    exactTag: options.exact_tag || options.version,
+    channel: requireOption(options, "channel"),
+    line: options.line || "",
+    sourceSha: requireOption(options, "source_sha"),
+    targetRef: requireOption(options, "target_ref"),
+    releaseSha: requireOption(options, "release_sha"),
+    releaseMaterialSha: options.release_material_sha || options.release_sha,
+    publishToolingSha: options.publish_tooling_sha || options.release_sha,
+    statePath: filePath,
+    evidencePath: evidencePath(options),
+    actor: process.env.GITHUB_ACTOR || process.env.USER || "",
+    runId: process.env.GITHUB_RUN_ID || "",
+  });
+  writeReleaseTransaction(filePath, record);
+  return { record, filePath, created: true };
+}
+
+function validateIfPossible(record, options) {
+  const evidence = readPublishEvidence(evidencePath(options));
+  if (!evidence) {
+    return { evidence: undefined, validation: undefined };
+  }
+  const requiredArtifacts = options.required_artifacts_json
+    ? JSON.parse(options.required_artifacts_json)
+    : [];
+  const validation = validatePublishEvidence({
+    evidence,
+    version: record.version,
+    channel: record.channel,
+    sourceSha: record.source_sha,
+    releaseSha: record.release_sha,
+    targetRef: record.target_ref,
+    releaseMaterialSha: record.release_material_sha,
+    publishToolingSha: options.publish_tooling_sha || record.publish_tooling_sha || "",
+    requiredArtifacts,
+  });
+  return { evidence, validation };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function main() {
+  const { command, options = {} } = parseArgs(process.argv.slice(2));
+  if (command === "help") {
+    process.stdout.write(usage());
+    return;
+  }
+  if (!["inspect", "recover", "finalize", "abort"].includes(command)) {
+    throw new Error(`unsupported release transaction command: ${command}`);
+  }
+  requireOption(options, "version");
+  const { record, filePath, created } = loadOrCreate(options);
+  const { evidence, validation } = validateIfPossible(record, options);
+
+  if (command === "inspect") {
+    printJson({
+      command,
+      statePath: filePath,
+      durableStateRef: record.state_ref || "",
+      durableBoundary: "remote durable refs and public Git ref finalization are owned by actions/promote-buildchain-ref",
+      created,
+      transaction: record,
+      evidence,
+      validation,
+    });
+    return;
+  }
+
+  if (command === "recover") {
+    const recovery = planTransactionRecovery({
+      transaction: record,
+      evidence,
+      validation,
+      explicitOverride: Boolean(options.override),
+    });
+    printJson({
+      command,
+      statePath: filePath,
+      durableStateRef: record.state_ref || "",
+      durableBoundary: "remote durable refs and public Git ref finalization are owned by actions/promote-buildchain-ref",
+      recovery,
+      transaction: record,
+      validation,
+    });
+    if (recovery.blocked) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === "finalize") {
+    if (!validation?.valid) {
+      throw new Error(`cannot finalize release transaction without valid evidence: ${(validation?.errors || ["missing evidence"]).join("; ")}`);
+    }
+    const next = transitionReleaseTransaction(
+      record.state === "published" ? transitionReleaseTransaction(record, "finalizing") : record,
+      "complete",
+    );
+    writeReleaseTransaction(filePath, next);
+    printJson({
+      command,
+      statePath: filePath,
+      durableStateRef: next.state_ref || "",
+      durableBoundary: "local transaction state finalized; public Git refs are finalized by actions/promote-buildchain-ref",
+      transaction: next,
+      validation,
+    });
+    return;
+  }
+
+  const supersededBy = requireOption(options, "superseded_by");
+  const next = transitionReleaseTransaction(record, "abandoned", {
+    supersededBy,
+    failure: `abandoned in favor of ${supersededBy}`,
+  });
+  writeReleaseTransaction(filePath, next);
+  printJson({
+    command,
+    statePath: filePath,
+    durableStateRef: next.state_ref || "",
+    durableBoundary: "local transaction state abandoned; remote durable state is written by actions/promote-buildchain-ref",
+    transaction: next,
+  });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/resolve-build-contract.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import {
+  resolveArtifactContract,
+  resolveRunnerMatrix,
+  writeGitHubOutputs,
+} from "./build-contract-core.mjs";
+
+function readArg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return process.argv[index + 1] || "";
+}
+
+export function resolveBuildContractCli() {
+  const mode = readArg("mode", process.env.BUILDCHAIN_CONTRACT_MODE || "artifact");
+  if (mode === "runners") {
+    const resolved = resolveRunnerMatrix({
+      runnerPreset: process.env.BUILDCHAIN_RUNNER_PRESET || "github-hosted",
+      platformsJson: process.env.BUILDCHAIN_PLATFORMS_JSON || "",
+    });
+    writeGitHubOutputs({
+      "runner-preset": resolved.runnerPreset,
+      "platforms-json": resolved.platformsJson,
+      "platform-count": String(resolved.platformCount),
+      "platform-source": resolved.source,
+    });
+    return resolved;
+  }
+  if (mode === "artifact") {
+    const resolved = resolveArtifactContract({
+      artifactName: process.env.BUILDCHAIN_ARTIFACT_NAME || "buildchain-artifact",
+      artifactNameTemplate:
+        process.env.BUILDCHAIN_ARTIFACT_NAME_TEMPLATE || "{artifact}-{platform}-{sha}",
+      platformId: process.env.BUILDCHAIN_PLATFORM_ID || "",
+      platformName: process.env.BUILDCHAIN_PLATFORM_NAME || "",
+      sha: process.env.BUILDCHAIN_SOURCE_SHA || process.env.GITHUB_SHA || "",
+      ref: process.env.GITHUB_REF || "",
+      runId: process.env.GITHUB_RUN_ID || "",
+      runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",
+    });
+    writeGitHubOutputs({
+      "artifact-name": resolved.artifactName,
+      "artifact-base-name": resolved.artifactBaseName,
+      "artifact-name-template": resolved.artifactNameTemplate,
+      "platform-id": resolved.platform.id,
+      "platform-name": resolved.platform.name,
+    });
+    return resolved;
+  }
+  throw new Error(`unsupported build contract mode: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    resolveBuildContractCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/resolve-publish-gate.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { resolvePublishGate, writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function readEnv(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+export function resolvePublishGateCli() {
+  const gate = resolvePublishGate({
+    trusted: readEnv("BUILDCHAIN_TRUSTED_EVENT", "true"),
+    publishChannel: readEnv("BUILDCHAIN_PUBLISH_CHANNEL", "none"),
+    eventName: readEnv("GITHUB_EVENT_NAME", ""),
+    ref: readEnv("GITHUB_REF", ""),
+    publishRefsJson: readEnv("BUILDCHAIN_PUBLISH_REFS_JSON", ""),
+  });
+  writeGitHubOutputs({
+    "trusted-event": String(gate.trusted),
+    "publish-channel": gate.publishChannel,
+    "publish-allowed": String(gate.publishAllowed),
+    "publish-reason": gate.publishReason,
+  });
+  return gate;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    resolvePublishGateCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/resolve-publish-source.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createResolvedReleaseManifest,
+  parsePublishSourceRef,
+  resolvePublishSourceLock,
+  writeGitHubOutputs,
+} from "./build-contract-core.mjs";
+import {
+  resolvePublishSourceRefSha,
+  sourceRefFromEnv,
+} from "./publish-source-ref-resolver.mjs";
+
+function readArg(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return args[index + 1] || "";
+}
+
+function readEnv(env, name, fallback = "") {
+  return env[name] || fallback;
+}
+
+export async function resolvePublishSourceCli({
+  args = process.argv.slice(2),
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const mode = readArg(args, "mode", readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_MODE", "lock"));
+  const sourceRef = sourceRefFromEnv(env);
+  const parsed = parsePublishSourceRef(sourceRef);
+  const repository = readEnv(env, "BUILDCHAIN_SOURCE_REPOSITORY", readEnv(env, "GITHUB_REPOSITORY"));
+  const sourceSha = readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_SHA")
+    || (parsed.enabled
+      ? await resolvePublishSourceRefSha({ repository, sourceRef: parsed.sourceRef, env, fetchImpl })
+      : readEnv(env, "GITHUB_SHA"));
+  const lock = resolvePublishSourceLock({
+    publishSourceRef: parsed.sourceRef,
+    publishSourceSha: sourceSha,
+    fallbackRef: readEnv(env, "GITHUB_REF_NAME", readEnv(env, "GITHUB_REF")),
+    fallbackSha: readEnv(env, "GITHUB_SHA"),
+  });
+
+  if (mode === "lock") {
+    writeGitHubOutputs({
+      "publish-source-ref": lock.sourceRef,
+      "publish-source-full-ref": lock.fullRef,
+      "publish-source-sha": lock.sourceSha,
+      "publish-source-locked": String(lock.sourceLocked),
+      "publish-source-channel": lock.channel,
+      "publish-source-line": lock.line,
+      "publish-source-consumer-version": lock.consumerVersion,
+      "publish-source-reason": lock.sourceReason,
+    });
+    return lock;
+  }
+  if (mode === "manifest") {
+    const cwd = path.resolve(readEnv(env, "BUILDCHAIN_SOURCE_CWD", "."));
+    const outputPath = path.resolve(
+      readEnv(env, "BUILDCHAIN_RELEASE_MANIFEST", ".buildchain/artifacts/publish-source-manifest.json"),
+    );
+    const manifest = await createResolvedReleaseManifest({
+      cwd,
+      repository,
+      sourceRef: lock.sourceLocked ? lock.sourceRef : "",
+      sourceSha: lock.sourceSha,
+      anchorRequestJson: readEnv(env, "BUILDCHAIN_PUBLISH_ANCHOR_REQUEST_JSON"),
+      publishRegistry: readEnv(env, "BUILDCHAIN_PUBLISH_REGISTRY", "https://registry.npmjs.org/"),
+      distTag: readEnv(env, "BUILDCHAIN_PUBLISH_DIST_TAG"),
+    });
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    writeGitHubOutputs({
+      "publish-source-ref": lock.sourceRef,
+      "publish-source-sha": lock.sourceSha,
+      "publish-source-locked": String(lock.sourceLocked),
+      "publish-source-channel": lock.channel,
+      "publish-source-line": lock.line,
+      "publish-source-consumer-version": lock.consumerVersion,
+      "release-manifest-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
+      "release-manifest-json": JSON.stringify(manifest),
+    });
+    return manifest;
+  }
+  throw new Error(`unsupported publish source mode: ${mode}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    await resolvePublishSourceCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}