@git.zone/cli 4.0.0 → 6.0.0

package/ts/mod_release/classes.releasejournal.ts

@@ -0,0 +1,740 @@
+import * as plugins from "./mod.plugins.js";
+import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
+
+export const releaseJournalSchemaVersion = 1 as const;
+export const releaseArtifactFileName = "package.tgz" as const;
+export const releaseJournalFileName = "journal.json" as const;
+
+export type TReleaseTargetState =
+  | "pending"
+  | "publishing"
+  | "verified"
+  | "failed"
+  | "conflict"
+  | "skipped";
+
+export type TReleaseErrorCode =
+  | "command-failed"
+  | "verification-inconclusive"
+  | "artifact-conflict"
+  | "already-published"
+  | "destination-conflict"
+  | "attempt-recovery-required";
+
+export interface IReleaseAttempt {
+  id: string;
+  pid: number;
+  startedAt: string;
+}
+
+export interface IReleaseTargetStatus {
+  state: TReleaseTargetState;
+  attempts: number;
+  attempt: IReleaseAttempt | null;
+  error: TReleaseErrorCode | null;
+}
+
+export interface IReleaseArtifact {
+  kind: "npm-tarball";
+  file: typeof releaseArtifactFileName;
+  packageName: string;
+  version: string;
+  size: number;
+  sha1: string;
+  sha256: string;
+  integrity: string;
+}
+
+export interface IReleaseGitJournal extends IReleaseTargetStatus {
+  remote: string | null;
+  destinationHash: string | null;
+  expectedRemoteMainOid: string | null;
+}
+
+export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
+  registry: string;
+}
+
+export interface IReleaseJournal {
+  kind: "gitzone-release-journal";
+  schemaVersion: typeof releaseJournalSchemaVersion;
+  revision: number;
+  release: {
+    version: string;
+    tag: string;
+    mainOid: string;
+    tagOid: string;
+  };
+  artifact: IReleaseArtifact | null;
+  git: IReleaseGitJournal;
+  npm: {
+    access: "public";
+    tag: "latest";
+    alreadyPublished: "success" | "error";
+    registries: IReleaseNpmRegistryJournal[];
+  };
+  createdAt: string;
+  updatedAt: string;
+  completedAt: string | null;
+}
+
+const releaseVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const gitOidRegex = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const attemptIdRegex = /^[0-9a-f]{32}$/;
+const sha1Regex = /^[0-9a-f]{40}$/;
+const sha256Regex = /^[0-9a-f]{64}$/;
+const sha512IntegrityRegex = /^sha512-[A-Za-z0-9+/]+={0,2}$/;
+const packageNameRegex = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+const gitRemoteNameRegex = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+const targetStates: TReleaseTargetState[] = [
+  "pending",
+  "publishing",
+  "verified",
+  "failed",
+  "conflict",
+  "skipped",
+];
+const errorCodes: TReleaseErrorCode[] = [
+  "command-failed",
+  "verification-inconclusive",
+  "artifact-conflict",
+  "already-published",
+  "destination-conflict",
+  "attempt-recovery-required",
+];
+
+const isPlainObject = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
+
+const isCanonicalRegistryUrl = (valueArg: string): boolean => {
+  try {
+    const url = new URL(valueArg);
+    if (
+      (url.protocol !== "https:" && url.protocol !== "http:") ||
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash
+    ) {
+      return false;
+    }
+    const pathname = url.pathname.replace(/\/+$/, "");
+    return valueArg === `${url.origin}${pathname}`;
+  } catch {
+    return false;
+  }
+};
+
+const assertExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  contextArg: string,
+): void => {
+  const actualKeys = Object.keys(valueArg);
+  if (
+    actualKeys.length !== keysArg.length ||
+    actualKeys.some((keyArg, indexArg) => keyArg !== keysArg[indexArg])
+  ) {
+    throw new Error(`${contextArg} must use the exact canonical key set and order.`);
+  }
+};
+
+const assertIsoTimestamp = (valueArg: unknown, contextArg: string): string => {
+  if (
+    typeof valueArg !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(valueArg) ||
+    new Date(valueArg).toISOString() !== valueArg
+  ) {
+    throw new Error(`${contextArg} must be a canonical UTC timestamp.`);
+  }
+  return valueArg;
+};
+
+export const normalizeReleaseVersion = (valueArg: string): string => {
+  const version = valueArg.startsWith("v") ? valueArg.slice(1) : valueArg;
+  if (!releaseVersionRegex.test(version)) {
+    throw new Error("Release journal versions must use canonical x.y.z semver.");
+  }
+  return version;
+};
+
+export const normalizeReleaseGitRemoteName = (valueArg: string): string => {
+  if (
+    typeof valueArg !== "string" ||
+    !gitRemoteNameRegex.test(valueArg) ||
+    valueArg.includes("..") ||
+    valueArg.endsWith("/")
+  ) {
+    throw new Error("Release journals require a canonical credential-free Git remote name.");
+  }
+  return valueArg;
+};
+
+const assertTargetStatus = (
+  valueArg: Record<string, unknown>,
+  contextArg: string,
+): IReleaseTargetStatus => {
+  if (!targetStates.includes(valueArg.state as TReleaseTargetState)) {
+    throw new Error(`${contextArg}.state is invalid.`);
+  }
+  if (
+    !Number.isSafeInteger(valueArg.attempts) ||
+    (valueArg.attempts as number) < 0
+  ) {
+    throw new Error(`${contextArg}.attempts must be a non-negative safe integer.`);
+  }
+  if (
+    valueArg.error !== null &&
+    !errorCodes.includes(valueArg.error as TReleaseErrorCode)
+  ) {
+    throw new Error(`${contextArg}.error is invalid.`);
+  }
+
+  if (valueArg.state === "publishing") {
+    if (!isPlainObject(valueArg.attempt)) {
+      throw new Error(`${contextArg}.attempt is required while publishing.`);
+    }
+    assertExactKeys(valueArg.attempt, ["id", "pid", "startedAt"], `${contextArg}.attempt`);
+    if (
+      typeof valueArg.attempt.id !== "string" ||
+      !attemptIdRegex.test(valueArg.attempt.id) ||
+      !Number.isSafeInteger(valueArg.attempt.pid) ||
+      (valueArg.attempt.pid as number) <= 0
+    ) {
+      throw new Error(`${contextArg}.attempt owner is invalid.`);
+    }
+    assertIsoTimestamp(valueArg.attempt.startedAt, `${contextArg}.attempt.startedAt`);
+    if ((valueArg.attempts as number) < 1 || valueArg.error !== null) {
+      throw new Error(`${contextArg} publishing state is inconsistent.`);
+    }
+  } else if (valueArg.attempt !== null) {
+    throw new Error(`${contextArg}.attempt must be null outside publishing state.`);
+  }
+
+  if (
+    (valueArg.state === "pending" ||
+      valueArg.state === "verified" ||
+      valueArg.state === "skipped") &&
+    valueArg.error !== null
+  ) {
+    throw new Error(`${contextArg}.error must be null for ${valueArg.state}.`);
+  }
+  if (
+    (valueArg.state === "failed" || valueArg.state === "conflict") &&
+    valueArg.error === null
+  ) {
+    throw new Error(`${contextArg}.error is required for ${valueArg.state}.`);
+  }
+  return valueArg as unknown as IReleaseTargetStatus;
+};
+
+const assertArtifact = (valueArg: unknown): IReleaseArtifact | null => {
+  if (valueArg === null) {
+    return null;
+  }
+  if (!isPlainObject(valueArg)) {
+    throw new Error("Release journal artifact must be an object or null.");
+  }
+  assertExactKeys(
+    valueArg,
+    ["kind", "file", "packageName", "version", "size", "sha1", "sha256", "integrity"],
+    "Release journal artifact",
+  );
+  if (
+    valueArg.kind !== "npm-tarball" ||
+    valueArg.file !== releaseArtifactFileName ||
+    typeof valueArg.packageName !== "string" ||
+    !packageNameRegex.test(valueArg.packageName) ||
+    typeof valueArg.version !== "string" ||
+    normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
+    !Number.isSafeInteger(valueArg.size) ||
+    (valueArg.size as number) <= 0 ||
+    typeof valueArg.sha1 !== "string" ||
+    !sha1Regex.test(valueArg.sha1) ||
+    typeof valueArg.sha256 !== "string" ||
+    !sha256Regex.test(valueArg.sha256) ||
+    typeof valueArg.integrity !== "string" ||
+    !sha512IntegrityRegex.test(valueArg.integrity)
+  ) {
+    throw new Error("Release journal artifact identity is invalid.");
+  }
+  return valueArg as unknown as IReleaseArtifact;
+};
+
+const isComplete = (journalArg: IReleaseJournal): boolean =>
+  [
+    journalArg.git.state,
+    ...journalArg.npm.registries.map((registryArg) => registryArg.state),
+  ].every((stateArg) => stateArg === "verified" || stateArg === "skipped");
+
+const immutableJournalIdentity = (journalArg: IReleaseJournal): string =>
+  JSON.stringify({
+    release: journalArg.release,
+    artifact: journalArg.artifact,
+    git: {
+      remote: journalArg.git.remote,
+      destinationHash: journalArg.git.destinationHash,
+      expectedRemoteMainOid: journalArg.git.expectedRemoteMainOid,
+    },
+    npm: {
+      access: journalArg.npm.access,
+      tag: journalArg.npm.tag,
+      alreadyPublished: journalArg.npm.alreadyPublished,
+      registries: journalArg.npm.registries.map((registryArg) =>
+        registryArg.registry
+      ),
+    },
+  });
+
+export const assertReleaseJournal = (valueArg: unknown): IReleaseJournal => {
+  if (!isPlainObject(valueArg)) {
+    throw new Error("Release journal root must be a JSON object.");
+  }
+  assertExactKeys(
+    valueArg,
+    [
+      "kind",
+      "schemaVersion",
+      "revision",
+      "release",
+      "artifact",
+      "git",
+      "npm",
+      "createdAt",
+      "updatedAt",
+      "completedAt",
+    ],
+    "Release journal",
+  );
+  if (
+    valueArg.kind !== "gitzone-release-journal" ||
+    valueArg.schemaVersion !== releaseJournalSchemaVersion ||
+    !Number.isSafeInteger(valueArg.revision) ||
+    (valueArg.revision as number) < 1
+  ) {
+    throw new Error("Release journal header is invalid or unsupported.");
+  }
+
+  if (!isPlainObject(valueArg.release)) {
+    throw new Error("Release journal release identity is missing.");
+  }
+  assertExactKeys(
+    valueArg.release,
+    ["version", "tag", "mainOid", "tagOid"],
+    "Release journal release",
+  );
+  if (
+    typeof valueArg.release.version !== "string" ||
+    normalizeReleaseVersion(valueArg.release.version) !== valueArg.release.version ||
+    valueArg.release.tag !== `v${valueArg.release.version}` ||
+    typeof valueArg.release.mainOid !== "string" ||
+    !gitOidRegex.test(valueArg.release.mainOid) ||
+    typeof valueArg.release.tagOid !== "string" ||
+    !gitOidRegex.test(valueArg.release.tagOid)
+  ) {
+    throw new Error("Release journal Git identity is invalid.");
+  }
+
+  const artifact = assertArtifact(valueArg.artifact);
+  if (artifact && artifact.version !== valueArg.release.version) {
+    throw new Error("Release journal artifact version does not match the release.");
+  }
+
+  if (!isPlainObject(valueArg.git)) {
+    throw new Error("Release journal Git target is missing.");
+  }
+  assertExactKeys(
+    valueArg.git,
+    [
+      "state",
+      "attempts",
+      "attempt",
+      "error",
+      "remote",
+      "destinationHash",
+      "expectedRemoteMainOid",
+    ],
+    "Release journal Git target",
+  );
+  assertTargetStatus(valueArg.git, "Release journal Git target");
+  if (valueArg.git.state === "skipped") {
+    if (
+      valueArg.git.remote !== null ||
+      valueArg.git.destinationHash !== null ||
+      valueArg.git.expectedRemoteMainOid !== null
+    ) {
+      throw new Error("Skipped Git journal targets must not retain destination data.");
+    }
+  } else if (
+    typeof valueArg.git.remote !== "string" ||
+    normalizeReleaseGitRemoteName(valueArg.git.remote) !== valueArg.git.remote ||
+    typeof valueArg.git.destinationHash !== "string" ||
+    !sha256Regex.test(valueArg.git.destinationHash) ||
+    typeof valueArg.git.expectedRemoteMainOid !== "string" ||
+    !gitOidRegex.test(valueArg.git.expectedRemoteMainOid)
+  ) {
+    throw new Error("Active Git journal target destination data is invalid.");
+  }
+
+  if (!isPlainObject(valueArg.npm)) {
+    throw new Error("Release journal npm target is missing.");
+  }
+  assertExactKeys(
+    valueArg.npm,
+    ["access", "tag", "alreadyPublished", "registries"],
+    "Release journal npm target",
+  );
+  if (
+    valueArg.npm.access !== "public" ||
+    valueArg.npm.tag !== "latest" ||
+    (valueArg.npm.alreadyPublished !== "success" &&
+      valueArg.npm.alreadyPublished !== "error") ||
+    !Array.isArray(valueArg.npm.registries)
+  ) {
+    throw new Error("Release journal npm settings are invalid.");
+  }
+  const registryUrls: string[] = [];
+  for (const [index, rawRegistry] of valueArg.npm.registries.entries()) {
+    if (!isPlainObject(rawRegistry)) {
+      throw new Error(`Release journal npm registry ${index} must be an object.`);
+    }
+    assertExactKeys(
+      rawRegistry,
+      ["state", "attempts", "attempt", "error", "registry"],
+      `Release journal npm registry ${index}`,
+    );
+    assertTargetStatus(rawRegistry, `Release journal npm registry ${index}`);
+    if (
+      typeof rawRegistry.registry !== "string" ||
+      !isCanonicalRegistryUrl(rawRegistry.registry) ||
+      rawRegistry.state === "skipped"
+    ) {
+      throw new Error(`Release journal npm registry ${index} URL is invalid.`);
+    }
+    registryUrls.push(rawRegistry.registry);
+  }
+  if (new Set(registryUrls).size !== registryUrls.length) {
+    throw new Error("Release journal npm registries must be unique.");
+  }
+  if ((valueArg.npm.registries.length > 0) !== Boolean(artifact)) {
+    throw new Error("Release journal npm targets and artifact must exist together.");
+  }
+
+  const createdAt = assertIsoTimestamp(valueArg.createdAt, "Release journal createdAt");
+  const updatedAt = assertIsoTimestamp(valueArg.updatedAt, "Release journal updatedAt");
+  if (updatedAt < createdAt) {
+    throw new Error("Release journal updatedAt predates createdAt.");
+  }
+  if (valueArg.completedAt !== null) {
+    const completedAt = assertIsoTimestamp(
+      valueArg.completedAt,
+      "Release journal completedAt",
+    );
+    if (completedAt < createdAt || !isComplete(valueArg as unknown as IReleaseJournal)) {
+      throw new Error("Release journal completion state is inconsistent.");
+    }
+    if (completedAt > updatedAt) {
+      throw new Error("Release journal completedAt exceeds updatedAt.");
+    }
+  } else if (isComplete(valueArg as unknown as IReleaseJournal)) {
+    throw new Error("Complete release journal must record completedAt.");
+  }
+
+  return valueArg as unknown as IReleaseJournal;
+};
+
+export const serializeReleaseJournal = (journalArg: IReleaseJournal): string =>
+  `${JSON.stringify(assertReleaseJournal(journalArg), null, 2)}\n`;
+
+export const parseReleaseJournal = (contentArg: string): IReleaseJournal => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contentArg);
+  } catch (error) {
+    throw new Error("Release journal contains invalid JSON.", { cause: error });
+  }
+  const journal = assertReleaseJournal(parsed);
+  if (serializeReleaseJournal(journal) !== contentArg) {
+    throw new Error(
+      "Release journal must use canonical JSON without duplicate keys or formatting drift.",
+    );
+  }
+  return journal;
+};
+
+export const createReleaseAttempt = (): IReleaseAttempt => ({
+  id: plugins.crypto.randomBytes(16).toString("hex"),
+  pid: process.pid,
+  startedAt: new Date().toISOString(),
+});
+
+const syncDirectory = async (directoryPathArg: string): Promise<void> => {
+  const handle = await plugins.fs.open(directoryPathArg, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+
+export const resolveGitCommonDirectory = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+): Promise<string> => {
+  const result = await smartshellArg.execSpawn(
+    "git",
+    ["rev-parse", "--path-format=absolute", "--git-common-dir"],
+    {
+      cwd: cwdArg,
+      silent: true,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  const commonDirectory = result.stdout.trim();
+  if (
+    result.exitCode !== 0 ||
+    !plugins.path.isAbsolute(commonDirectory) ||
+    !commonDirectory
+  ) {
+    throw new Error("Unable to resolve the Git common directory for release state.");
+  }
+  return plugins.path.resolve(commonDirectory);
+};
+
+export class ReleaseJournalStore {
+  public readonly rootPath: string;
+
+  constructor(gitCommonDirectoryArg: string) {
+    if (!plugins.path.isAbsolute(gitCommonDirectoryArg)) {
+      throw new Error("Release journal storage requires an absolute Git common directory.");
+    }
+    this.rootPath = plugins.path.join(
+      plugins.path.resolve(gitCommonDirectoryArg),
+      "gitzone",
+      "releases",
+      `v${releaseJournalSchemaVersion}`,
+    );
+  }
+
+  public getReleaseDirectory(versionArg: string): string {
+    const version = normalizeReleaseVersion(versionArg);
+    return plugins.path.join(this.rootPath, `v${version}`);
+  }
+
+  public getArtifactPath(versionArg: string): string {
+    return plugins.path.join(
+      this.getReleaseDirectory(versionArg),
+      releaseArtifactFileName,
+    );
+  }
+
+  public async createTemporaryDirectory(versionArg: string): Promise<string> {
+    const version = normalizeReleaseVersion(versionArg);
+    await plugins.fs.mkdir(this.rootPath, { recursive: true, mode: 0o700 });
+    return plugins.fs.mkdtemp(plugins.path.join(this.rootPath, `.v${version}.tmp-`));
+  }
+
+  public async read(versionArg: string): Promise<IReleaseJournal> {
+    const version = normalizeReleaseVersion(versionArg);
+    const filePath = plugins.path.join(
+      this.getReleaseDirectory(version),
+      releaseJournalFileName,
+    );
+    let content: string;
+    try {
+      content = await plugins.fs.readFile(filePath, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new Error(`Release journal v${version} does not exist.`);
+      }
+      throw new Error(`Release journal v${version} could not be read.`, {
+        cause: error,
+      });
+    }
+    const journal = parseReleaseJournal(content);
+    if (journal.release.version !== version) {
+      throw new Error("Release journal directory and version do not match.");
+    }
+    return journal;
+  }
+
+  public async list(): Promise<IReleaseJournal[]> {
+    let entries: Array<{ name: string; isDirectory: () => boolean }>;
+    try {
+      entries = await plugins.fs.readdir(this.rootPath, { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return [];
+      }
+      throw new Error("Release journal directory could not be listed.", {
+        cause: error,
+      });
+    }
+    const versions = entries
+      .filter((entryArg) => entryArg.isDirectory() && /^v\d+\.\d+\.\d+$/.test(entryArg.name))
+      .map((entryArg) => entryArg.name.slice(1));
+    const journals: IReleaseJournal[] = [];
+    for (const version of versions) {
+      journals.push(await this.read(version));
+    }
+    return journals.sort((leftArg, rightArg) =>
+      rightArg.createdAt.localeCompare(leftArg.createdAt),
+    );
+  }
+
+  public async installPrepared(
+    temporaryDirectoryArg: string,
+    journalArg: IReleaseJournal,
+  ): Promise<IReleaseJournal> {
+    const journal = assertReleaseJournal(journalArg);
+    if (journal.revision !== 1) {
+      throw new Error("New release journals must start at revision 1.");
+    }
+    const temporaryDirectory = plugins.path.resolve(temporaryDirectoryArg);
+    if (
+      plugins.path.dirname(temporaryDirectory) !== this.rootPath ||
+      !plugins.path.basename(temporaryDirectory).startsWith(`.v${journal.release.version}.tmp-`)
+    ) {
+      throw new Error("Prepared release directory is outside canonical storage.");
+    }
+    if (journal.artifact) {
+      const artifactPath = plugins.path.join(
+        temporaryDirectory,
+        releaseArtifactFileName,
+      );
+      const artifactStat = await plugins.fs.lstat(artifactPath);
+      if (!artifactStat.isFile() || artifactStat.isSymbolicLink()) {
+        throw new Error("Prepared release artifact must be a regular file.");
+      }
+      const artifactBytes = await plugins.fs.readFile(artifactPath);
+      if (
+        artifactBytes.byteLength !== journal.artifact.size ||
+        plugins.crypto.createHash("sha1").update(artifactBytes).digest("hex") !==
+          journal.artifact.sha1 ||
+        plugins.crypto.createHash("sha256").update(artifactBytes).digest("hex") !==
+          journal.artifact.sha256 ||
+        `sha512-${plugins.crypto.createHash("sha512").update(artifactBytes).digest("base64")}` !==
+          journal.artifact.integrity
+      ) {
+        throw new Error("Prepared release artifact does not match its journal identity.");
+      }
+    }
+
+    const releaseDirectory = this.getReleaseDirectory(journal.release.version);
+    const lock = new InterProcessLock({
+      lockPath: `${releaseDirectory}.create.lock`,
+      description: `Release journal v${journal.release.version} creation`,
+    });
+    return lock.runExclusive(async () => {
+      try {
+        await plugins.fs.lstat(releaseDirectory);
+        throw new Error(
+          `Release journal v${journal.release.version} already exists. Inspect or resume it instead of regenerating artifacts.`,
+        );
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw error;
+        }
+      }
+
+      const journalPath = plugins.path.join(
+        temporaryDirectory,
+        releaseJournalFileName,
+      );
+      const handle = await plugins.fs.open(journalPath, "wx", 0o600);
+      try {
+        await handle.writeFile(serializeReleaseJournal(journal), "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await syncDirectory(temporaryDirectory);
+      await plugins.fs.rename(temporaryDirectory, releaseDirectory);
+      await syncDirectory(this.rootPath);
+      return journal;
+    });
+  }
+
+  public async transact(
+    versionArg: string,
+    expectedRevisionArg: number,
+    operationArg: (journalArg: IReleaseJournal) => IReleaseJournal,
+  ): Promise<IReleaseJournal> {
+    const version = normalizeReleaseVersion(versionArg);
+    const releaseDirectory = this.getReleaseDirectory(version);
+    const lock = new InterProcessLock({
+      lockPath: `${releaseDirectory}.lock`,
+      description: `Release journal v${version}`,
+    });
+    return lock.runExclusive(async () => {
+      const current = await this.read(version);
+      if (current.revision !== expectedRevisionArg) {
+        throw new Error(
+          `Release journal v${version} changed concurrently (expected revision ${expectedRevisionArg}, found ${current.revision}).`,
+        );
+      }
+      const proposed = operationArg(structuredClone(current));
+      const now = new Date().toISOString();
+      const next = assertReleaseJournal({
+        ...proposed,
+        revision: current.revision + 1,
+        createdAt: current.createdAt,
+        updatedAt: now,
+      });
+      if (immutableJournalIdentity(next) !== immutableJournalIdentity(current)) {
+        throw new Error("Release journal immutable identity changed during a transaction.");
+      }
+      await this.writeAtomic(version, next);
+      return next;
+    });
+  }
+
+  private async writeAtomic(
+    versionArg: string,
+    journalArg: IReleaseJournal,
+  ): Promise<void> {
+    const releaseDirectory = this.getReleaseDirectory(versionArg);
+    const journalPath = plugins.path.join(releaseDirectory, releaseJournalFileName);
+    const temporaryPath = plugins.path.join(
+      releaseDirectory,
+      `.journal.tmp-${process.pid}-${plugins.crypto.randomBytes(12).toString("hex")}`,
+    );
+    let handle: Awaited<ReturnType<typeof plugins.fs.open>> | undefined;
+    try {
+      handle = await plugins.fs.open(temporaryPath, "wx", 0o600);
+      await handle.writeFile(serializeReleaseJournal(journalArg), "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = undefined;
+      await plugins.fs.rename(temporaryPath, journalPath);
+      await syncDirectory(releaseDirectory);
+    } catch (error) {
+      await handle?.close().catch(() => {});
+      await plugins.fs.rm(temporaryPath, { force: true }).catch(() => {});
+      throw new Error(`Release journal v${versionArg} could not be updated atomically.`, {
+        cause: error,
+      });
+    }
+  }
+}
+
+export const createInitialTargetStatus = (
+  enabledArg: boolean,
+): IReleaseTargetStatus => ({
+  state: enabledArg ? "pending" : "skipped",
+  attempts: 0,
+  attempt: null,
+  error: null,
+});
+
+export const finalizeJournalCompletion = (
+  journalArg: IReleaseJournal,
+  completedAtArg = new Date().toISOString(),
+): IReleaseJournal => {
+  const completed = isComplete(journalArg);
+  return {
+    ...journalArg,
+    completedAt: completed ? journalArg.completedAt || completedAtArg : null,
+  };
+};