@git.zone/cli 5.0.0 → 6.0.1

package/ts/mod_release/helpers.releasepublication.ts

@@ -0,0 +1,641 @@
+import * as plugins from "./mod.plugins.js";
+import {
+  ReleaseJournalStore,
+  createReleaseAttempt,
+  finalizeJournalCompletion,
+  type IReleaseJournal,
+  type IReleaseTargetStatus,
+  type TReleaseErrorCode,
+  type TReleaseTargetState,
+} from "./classes.releasejournal.js";
+import {
+  probeAnonymousNpmArtifact,
+  publishNpmArtifact,
+  verifyStoredNpmArtifact,
+  waitForAnonymousNpmArtifact,
+  type INpmArtifactProbeOptions,
+  type INpmArtifactProbeResult,
+} from "./helpers.npmartifact.js";
+import { releaseGitEnv } from "./helpers.releasebranch.js";
+
+const gitProbeTimeoutMs = 60_000;
+const gitPushTimeoutMs = 5 * 60_000;
+
+export interface IBuildReleaseGitPushArgsOptions {
+  destination: string;
+  newVersion: string;
+  pushBranch: boolean;
+  pushTags: boolean;
+  mainOid: string;
+  tagOid: string;
+  expectedRemoteMainOid?: string;
+}
+
+export function buildReleaseGitPushArgs(
+  optionsArg: IBuildReleaseGitPushArgsOptions,
+): string[] {
+  const refspecs: string[] = [];
+  if (optionsArg.pushBranch) {
+    refspecs.push(`${optionsArg.mainOid}:refs/heads/main`);
+  }
+  if (optionsArg.pushTags) {
+    refspecs.push(
+      `${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`,
+    );
+  }
+  const args = ["push", "--no-follow-tags"];
+  if (refspecs.length > 1) {
+    args.push("--atomic");
+  }
+  if (optionsArg.pushBranch && optionsArg.expectedRemoteMainOid) {
+    args.push(
+      `--force-with-lease=refs/heads/main:${optionsArg.expectedRemoteMainOid}`,
+    );
+  }
+  args.push(optionsArg.destination, ...refspecs);
+  return args;
+}
+
+type TReleaseTargetSelector =
+  | { kind: "git" }
+  | { kind: "npm"; registry: string };
+
+type TGitProbeStatus = "pending" | "exact" | "conflict" | "inconclusive";
+
+interface IGitProbeResult {
+  status: TGitProbeStatus;
+}
+
+export interface IReleasePublicationOptions {
+  smartshell: plugins.smartshell.Smartshell;
+  cwd: string;
+  store: ReleaseJournalStore;
+  journal: IReleaseJournal;
+  pushUrl?: string;
+  recoveryAttemptId?: string;
+  npmProbeOptions?: INpmArtifactProbeOptions;
+  ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
+}
+
+const getTargetStatus = (
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+): IReleaseTargetStatus => {
+  if (selectorArg.kind === "git") {
+    return journalArg.git;
+  }
+  const registry = journalArg.npm.registries.find(
+    (registryArg) => registryArg.registry === selectorArg.registry,
+  );
+  if (!registry) {
+    throw new Error(`Release journal does not contain npm registry ${selectorArg.registry}.`);
+  }
+  return registry;
+};
+
+const updateTarget = async (
+  storeArg: ReleaseJournalStore,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+  expectedStateArg: TReleaseTargetState | TReleaseTargetState[],
+  expectedAttemptIdArg: string | null,
+  updateArg: (statusArg: IReleaseTargetStatus) => void,
+): Promise<IReleaseJournal> => {
+  const expectedStates = Array.isArray(expectedStateArg)
+    ? expectedStateArg
+    : [expectedStateArg];
+  return storeArg.transact(
+    journalArg.release.version,
+    journalArg.revision,
+    (currentArg) => {
+      const status = getTargetStatus(currentArg, selectorArg);
+      if (!expectedStates.includes(status.state)) {
+        throw new Error("Release target state changed concurrently.");
+      }
+      if ((status.attempt?.id || null) !== expectedAttemptIdArg) {
+        throw new Error("Release target attempt ownership changed concurrently.");
+      }
+      updateArg(status);
+      return finalizeJournalCompletion(currentArg);
+    },
+  );
+};
+
+const claimTarget = async (
+  storeArg: ReleaseJournalStore,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+): Promise<IReleaseJournal> =>
+  updateTarget(
+    storeArg,
+    journalArg,
+    selectorArg,
+    ["pending", "failed"],
+    null,
+    (statusArg) => {
+      statusArg.state = "publishing";
+      statusArg.attempts += 1;
+      statusArg.attempt = createReleaseAttempt();
+      statusArg.error = null;
+    },
+  );
+
+const finishPublishingTarget = async (
+  storeArg: ReleaseJournalStore,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+  stateArg: "verified" | "failed" | "conflict",
+  errorArg: TReleaseErrorCode | null,
+): Promise<IReleaseJournal> => {
+  const attemptId = getTargetStatus(journalArg, selectorArg).attempt?.id;
+  if (!attemptId) {
+    throw new Error("Release target has no active publication attempt.");
+  }
+  return updateTarget(
+    storeArg,
+    journalArg,
+    selectorArg,
+    "publishing",
+    attemptId,
+    (statusArg) => {
+      statusArg.state = stateArg;
+      statusArg.attempt = null;
+      statusArg.error = errorArg;
+    },
+  );
+};
+
+const markUnclaimedTarget = async (
+  storeArg: ReleaseJournalStore,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+  expectedStatesArg: TReleaseTargetState[],
+  stateArg: "verified" | "failed" | "conflict",
+  errorArg: TReleaseErrorCode | null,
+): Promise<IReleaseJournal> =>
+  updateTarget(
+    storeArg,
+    journalArg,
+    selectorArg,
+    expectedStatesArg,
+    null,
+    (statusArg) => {
+      statusArg.state = stateArg;
+      statusArg.error = errorArg;
+    },
+  );
+
+const recoverPublishingTarget = async (
+  storeArg: ReleaseJournalStore,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+  recoveryAttemptIdArg: string | undefined,
+): Promise<IReleaseJournal> => {
+  const status = getTargetStatus(journalArg, selectorArg);
+  const attemptId = status.attempt?.id;
+  if (!attemptId || recoveryAttemptIdArg !== attemptId) {
+    throw new Error(
+      `Release target has unresolved publication attempt ${attemptId || "unknown"}. ` +
+        `After proving its publisher stopped, retry with --recover-attempt=${attemptId || "<attempt-id>"}.`,
+    );
+  }
+  return finishPublishingTarget(
+    storeArg,
+    journalArg,
+    selectorArg,
+    "failed",
+    "attempt-recovery-required",
+  );
+};
+
+const inspectRemoteRelease = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  destinationArg: string,
+  journalArg: IReleaseJournal,
+): Promise<IGitProbeResult> => {
+  const tagRef = `refs/tags/${journalArg.release.tag}`;
+  const result = await smartshellArg.execSpawn(
+    "git",
+    [
+      "ls-remote",
+      destinationArg,
+      "refs/heads/main",
+      tagRef,
+      `${tagRef}^{}`,
+    ],
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      silent: true,
+      timeout: gitProbeTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  if (result.exitCode !== 0) {
+    return { status: "inconclusive" };
+  }
+  const refs = new Map<string, string>();
+  for (const line of result.stdout.split("\n")) {
+    const match = line.trim().match(/^([0-9a-f]{40}|[0-9a-f]{64})\s+(.+)$/);
+    if (match) refs.set(match[2], match[1]);
+  }
+  const mainOid = refs.get("refs/heads/main");
+  const tagOid = refs.get(tagRef);
+  const tagCommitOid = refs.get(`${tagRef}^{}`);
+  if (
+    mainOid === journalArg.release.mainOid &&
+    tagOid === journalArg.release.tagOid &&
+    tagCommitOid === journalArg.release.mainOid
+  ) {
+    return { status: "exact" };
+  }
+  if (
+    mainOid === journalArg.git.expectedRemoteMainOid &&
+    tagOid === undefined &&
+    tagCommitOid === undefined
+  ) {
+    return { status: "pending" };
+  }
+  return { status: "conflict" };
+};
+
+const executeGitTarget = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournal,
+): Promise<IReleaseJournal> => {
+  const selector: TReleaseTargetSelector = { kind: "git" };
+  if (journalArg.git.state === "skipped") {
+    return journalArg;
+  }
+  const expectedRemoteMainOid = journalArg.git.expectedRemoteMainOid;
+  if (!optionsArg.pushUrl || !expectedRemoteMainOid) {
+    throw new Error("Active Git release journal lacks a verified destination.");
+  }
+
+  let journal = journalArg;
+  let probe = await inspectRemoteRelease(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    optionsArg.pushUrl,
+    journal,
+  );
+  if (journal.git.state === "verified") {
+    if (probe.status === "exact") {
+      await optionsArg.ensurePublicationState(journal.release.mainOid);
+      return journal;
+    }
+    if (probe.status === "conflict") {
+      await markUnclaimedTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        ["verified"],
+        "conflict",
+        "destination-conflict",
+      );
+      throw new Error("Previously verified Git release refs no longer match.");
+    }
+    throw new Error(
+      "Previously verified Git release refs cannot currently be verified.",
+    );
+  }
+
+  if (journal.git.state === "publishing") {
+    if (probe.status === "exact") {
+      journal = await finishPublishingTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        "verified",
+        null,
+      );
+      await optionsArg.ensurePublicationState(journal.release.mainOid);
+      return journal;
+    }
+    if (probe.status === "conflict") {
+      await finishPublishingTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        "conflict",
+        "destination-conflict",
+      );
+      throw new Error("Remote Git refs conflict with the release journal.");
+    }
+    if (probe.status === "inconclusive") {
+      throw new Error("Remote Git publication state is inconclusive.");
+    }
+    journal = await recoverPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      optionsArg.recoveryAttemptId,
+    );
+  }
+
+  if (journal.git.state === "conflict") {
+    throw new Error("Git release target is in conflict and cannot resume automatically.");
+  }
+  probe = await inspectRemoteRelease(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    optionsArg.pushUrl,
+    journal,
+  );
+  if (probe.status === "exact") {
+    journal = await markUnclaimedTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      ["pending", "failed"],
+      "verified",
+      null,
+    );
+    await optionsArg.ensurePublicationState(journal.release.mainOid);
+    return journal;
+  }
+  if (probe.status === "conflict") {
+    await markUnclaimedTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      ["pending", "failed"],
+      "conflict",
+      "destination-conflict",
+    );
+    throw new Error("Remote Git refs conflict with the release journal.");
+  }
+  if (probe.status === "inconclusive") {
+    await markUnclaimedTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      ["pending", "failed"],
+      "failed",
+      "verification-inconclusive",
+    );
+    throw new Error("Remote Git publication state is inconclusive.");
+  }
+
+  await optionsArg.ensurePublicationState(expectedRemoteMainOid);
+  journal = await claimTarget(optionsArg.store, journal, selector);
+  const pushResult = await optionsArg.smartshell.execSpawn(
+    "git",
+    buildReleaseGitPushArgs({
+      destination: optionsArg.pushUrl,
+      newVersion: journal.release.version,
+      pushBranch: true,
+      pushTags: true,
+      mainOid: journal.release.mainOid,
+      tagOid: journal.release.tagOid,
+      expectedRemoteMainOid,
+    }),
+    {
+      cwd: optionsArg.cwd,
+      env: releaseGitEnv,
+      timeout: gitPushTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  probe = await inspectRemoteRelease(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    optionsArg.pushUrl,
+    journal,
+  );
+  if (probe.status === "exact") {
+    journal = await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      "verified",
+      null,
+    );
+    await optionsArg.ensurePublicationState(journal.release.mainOid);
+    return journal;
+  }
+  if (probe.status === "conflict") {
+    await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      "conflict",
+      "destination-conflict",
+    );
+    throw new Error("Git publication produced conflicting remote refs.");
+  }
+  await finishPublishingTarget(
+    optionsArg.store,
+    journal,
+    selector,
+    "failed",
+    pushResult.exitCode === 0
+      ? "verification-inconclusive"
+      : "command-failed",
+  );
+  throw new Error("Git publication did not produce verifiable remote refs.");
+};
+
+const probeNpm = async (
+  journalArg: IReleaseJournal,
+  registryArg: string,
+  optionsArg: IReleasePublicationOptions,
+  waitArg = false,
+): Promise<INpmArtifactProbeResult> => {
+  if (!journalArg.artifact) {
+    throw new Error("npm release target has no exact artifact.");
+  }
+  return waitArg
+    ? waitForAnonymousNpmArtifact(
+        registryArg,
+        journalArg.artifact,
+        journalArg.npm.tag,
+        optionsArg.npmProbeOptions,
+      )
+    : probeAnonymousNpmArtifact(
+        registryArg,
+        journalArg.artifact,
+        journalArg.npm.tag,
+        optionsArg.npmProbeOptions,
+      );
+};
+
+const markNpmProbeFailure = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournal,
+  selectorArg: TReleaseTargetSelector,
+  expectedStatesArg: TReleaseTargetState[],
+  probeArg: INpmArtifactProbeResult,
+): Promise<IReleaseJournal> => {
+  const conflict = probeArg.status === "conflict";
+  return markUnclaimedTarget(
+    optionsArg.store,
+    journalArg,
+    selectorArg,
+    expectedStatesArg,
+    conflict ? "conflict" : "failed",
+    conflict ? "artifact-conflict" : "verification-inconclusive",
+  );
+};
+
+const executeNpmRegistry = async (
+  optionsArg: IReleasePublicationOptions,
+  journalArg: IReleaseJournal,
+  registryArg: string,
+): Promise<IReleaseJournal> => {
+  const selector: TReleaseTargetSelector = { kind: "npm", registry: registryArg };
+  let journal = journalArg;
+  let status = getTargetStatus(journal, selector);
+  let probe = await probeNpm(journal, registryArg, optionsArg);
+
+  if (status.state === "verified") {
+    if (probe.status === "exact") {
+      return journal;
+    }
+    if (probe.status === "conflict") {
+      await markUnclaimedTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        ["verified"],
+        "conflict",
+        "artifact-conflict",
+      );
+      throw new Error(`Previously verified npm registry drifted: ${registryArg}`);
+    }
+    throw new Error(
+      `Previously verified npm registry cannot currently be verified: ${registryArg}`,
+    );
+  }
+  if (status.state === "publishing") {
+    if (probe.status === "exact") {
+      return finishPublishingTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        "verified",
+        null,
+      );
+    }
+    if (probe.status === "conflict") {
+      await finishPublishingTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        "conflict",
+        "artifact-conflict",
+      );
+      throw new Error(`npm registry contains conflicting bytes: ${registryArg}`);
+    }
+    if (probe.status === "inconclusive") {
+      throw new Error(`npm registry publication is inconclusive: ${registryArg}`);
+    }
+    journal = await recoverPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      optionsArg.recoveryAttemptId,
+    );
+    status = getTargetStatus(journal, selector);
+  }
+  if (status.state === "conflict") {
+    throw new Error(`npm registry target is in conflict: ${registryArg}`);
+  }
+
+  probe = await probeNpm(journal, registryArg, optionsArg);
+  if (probe.status === "exact") {
+    if (status.attempts === 0 && journal.npm.alreadyPublished === "error") {
+      await markUnclaimedTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        ["pending", "failed"],
+        "conflict",
+        "already-published",
+      );
+      throw new Error(`npm version was already published: ${registryArg}`);
+    }
+    return markUnclaimedTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      ["pending", "failed"],
+      "verified",
+      null,
+    );
+  }
+  if (probe.status !== "absent") {
+    await markNpmProbeFailure(
+      optionsArg,
+      journal,
+      selector,
+      ["pending", "failed"],
+      probe,
+    );
+    throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
+  }
+
+  const artifactPath = optionsArg.store.getArtifactPath(journal.release.version);
+  if (!journal.artifact) {
+    throw new Error("npm release journal has no artifact.");
+  }
+  await verifyStoredNpmArtifact(artifactPath, journal.artifact);
+  journal = await claimTarget(optionsArg.store, journal, selector);
+  const publishResult = await publishNpmArtifact(
+    optionsArg.smartshell,
+    optionsArg.cwd,
+    artifactPath,
+    registryArg,
+  );
+  probe = await probeNpm(journal, registryArg, optionsArg, true);
+  if (probe.status === "exact") {
+    return finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      "verified",
+      null,
+    );
+  }
+  if (probe.status === "conflict") {
+    await finishPublishingTarget(
+      optionsArg.store,
+      journal,
+      selector,
+      "conflict",
+      "artifact-conflict",
+    );
+    throw new Error(`npm registry published conflicting bytes: ${registryArg}`);
+  }
+  await finishPublishingTarget(
+    optionsArg.store,
+    journal,
+    selector,
+    "failed",
+    publishResult.exitCode === 0
+      ? "verification-inconclusive"
+      : "command-failed",
+  );
+  throw new Error(`npm publication could not be verified: ${registryArg}`);
+};
+
+export const executeReleasePublication = async (
+  optionsArg: IReleasePublicationOptions,
+): Promise<IReleaseJournal> => {
+  let journal = optionsArg.journal;
+  journal = await executeGitTarget(optionsArg, journal);
+  const expectedRemoteMainOid =
+    journal.git.state === "verified"
+      ? journal.release.mainOid
+      : journal.git.expectedRemoteMainOid || undefined;
+  for (const registry of journal.npm.registries) {
+    await optionsArg.ensurePublicationState(expectedRemoteMainOid);
+    journal = await executeNpmRegistry(
+      optionsArg,
+      journal,
+      registry.registry,
+    );
+  }
+  return journal;
+};