@git.zone/cli 6.9.0 → 6.10.0

package/ts/mod_release/classes.releasejournal.ts

@@ -1,5 +1,12 @@
 import * as plugins from "./mod.plugins.js";
 import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
+import { resolveGiteaAssetsConfiguration } from "../helpers.workflow.js";
+import {
+  assertGiteaFrozenAssets,
+  validateGiteaAssets,
+  type IGiteaAssetDestination,
+  type IGiteaFrozenAsset,
+} from "./helpers.giteaassets.js";
 import {
   assertReleaseCleanupResult,
   assertReleasePromotionEvidence,
@@ -151,8 +158,35 @@ export interface IReleaseJournalV3 extends Omit<
   packages: IReleasePackage[];
 }
 
+export interface IReleaseGiteaAssetJournal extends IReleaseTargetStatus {
+  asset: IGiteaFrozenAsset;
+}
+
+export interface IReleaseGiteaAssetsJournal {
+  destination: IGiteaAssetDestination;
+  tokenEnv: string;
+  manifestPath: string;
+  release: IReleaseTargetStatus & { id: number | null };
+  assets: IReleaseGiteaAssetJournal[];
+}
+
+export interface IReleaseJournalV4 extends Omit<
+  IReleaseJournalV1,
+  "schemaVersion"
+> {
+  schemaVersion: 4;
+  packages: IReleasePackage[];
+  giteaAssets: IReleaseGiteaAssetsJournal;
+}
+
 export type TReleaseJournal =
-  IReleaseJournalV1 | IReleaseJournalV2 | IReleaseJournalV3;
+  IReleaseJournalV1 | IReleaseJournalV2 | IReleaseJournalV3 | IReleaseJournalV4;
+
+export const hasReleasePackages = (
+  journalArg: TReleaseJournal,
+): journalArg is IReleaseJournalV3 | IReleaseJournalV4 =>
+  journalArg.schemaVersion === 3 ||
+  (journalArg.schemaVersion === 4 && journalArg.packages.length > 0);
 
 export const releasePackageArtifactFile = (packageNameArg: string): string =>
   `package.${plugins.crypto.createHash("sha256").update(packageNameArg).digest("hex")}.tgz`;
@@ -160,7 +194,7 @@ export const releasePackageArtifactFile = (packageNameArg: string): string =>
 export const getReleaseArtifacts = (
   journalArg: TReleaseJournal,
 ): IReleaseArtifact[] =>
-  journalArg.schemaVersion === 3
+  hasReleasePackages(journalArg)
     ? journalArg.packages.map((entryArg) => entryArg.artifact)
     : journalArg.artifact
       ? [journalArg.artifact]
@@ -170,12 +204,11 @@ export const getReleaseNpmArtifact = (
   journalArg: TReleaseJournal,
   packageNameArg?: string,
 ): IReleaseArtifact => {
-  const artifact =
-    journalArg.schemaVersion === 3
-      ? journalArg.packages.find(
-          (entryArg) => entryArg.artifact.packageName === packageNameArg,
-        )?.artifact
-      : journalArg.artifact;
+  const artifact = hasReleasePackages(journalArg)
+    ? journalArg.packages.find(
+        (entryArg) => entryArg.artifact.packageName === packageNameArg,
+      )?.artifact
+    : journalArg.artifact;
   if (!artifact) throw new Error("npm release target has no exact artifact.");
   return artifact;
 };
@@ -396,6 +429,12 @@ const isComplete = (journalArg: TReleaseJournal): boolean => {
   const commonComplete = [
     journalArg.git.state,
     ...journalArg.npm.registries.map((registryArg) => registryArg.state),
+    ...(journalArg.schemaVersion === 4
+      ? [
+          journalArg.giteaAssets.release.state,
+          ...journalArg.giteaAssets.assets.map((entry) => entry.state),
+        ]
+      : []),
   ].every((stateArg) => stateArg === "verified" || stateArg === "skipped");
   if (
     !commonComplete ||
@@ -418,7 +457,7 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
     schemaVersion: journalArg.schemaVersion,
     release: journalArg.release,
     artifact: journalArg.artifact,
-    ...(journalArg.schemaVersion === 3
+    ...(hasReleasePackages(journalArg)
       ? { packages: journalArg.packages }
       : {}),
     git: {
@@ -431,11 +470,20 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
       tag: journalArg.npm.tag,
       alreadyPublished: journalArg.npm.alreadyPublished,
       registries: journalArg.npm.registries.map((registryArg) =>
-        journalArg.schemaVersion === 3
+        hasReleasePackages(journalArg)
           ? [registryArg.packageName, registryArg.registry]
           : registryArg.registry,
       ),
     },
+    giteaAssets:
+      journalArg.schemaVersion === 4
+        ? {
+            destination: journalArg.giteaAssets.destination,
+            tokenEnv: journalArg.giteaAssets.tokenEnv,
+            manifestPath: journalArg.giteaAssets.manifestPath,
+            assets: journalArg.giteaAssets.assets.map((entry) => entry.asset),
+          }
+        : undefined,
     docker:
       journalArg.schemaVersion === releaseJournalSchemaVersion
         ? {
@@ -1174,6 +1222,160 @@ const assertReleaseJournalV3 = (
   return journal;
 };
 
+const assertReleaseJournalV4 = (
+  valueArg: Record<string, unknown>,
+): IReleaseJournalV4 => {
+  assertExactKeys(
+    valueArg,
+    [
+      "kind",
+      "schemaVersion",
+      "revision",
+      "release",
+      "artifact",
+      "packages",
+      "git",
+      "npm",
+      "giteaAssets",
+      "createdAt",
+      "updatedAt",
+      "completedAt",
+    ],
+    "Release journal",
+  );
+  if (
+    !Array.isArray(valueArg.packages) ||
+    !isPlainObject(valueArg.giteaAssets) ||
+    !isPlainObject(valueArg.git) ||
+    !isPlainObject(valueArg.npm) ||
+    !Array.isArray(valueArg.npm.registries)
+  ) {
+    throw new Error("Schema 4 requires an exact Gitea asset publication set.");
+  }
+  const assets = valueArg.giteaAssets;
+  assertExactKeys(
+    assets,
+    ["destination", "tokenEnv", "manifestPath", "release", "assets"],
+    "Gitea assets",
+  );
+  if (
+    !isPlainObject(assets.destination) ||
+    !isPlainObject(assets.release) ||
+    !Array.isArray(assets.assets)
+  )
+    throw new Error("Invalid Gitea asset publication intent.");
+  assertExactKeys(
+    assets.destination,
+    ["apiOrigin", "owner", "repository"],
+    "Gitea destination",
+  );
+  resolveGiteaAssetsConfiguration({
+    ...assets.destination,
+    tokenEnv: assets.tokenEnv,
+    manifestPath: assets.manifestPath,
+  } as Parameters<typeof resolveGiteaAssetsConfiguration>[0]);
+  assertExactKeys(
+    assets.release,
+    ["state", "attempts", "attempt", "error", "id"],
+    "Gitea release target",
+  );
+  assertTargetStatus(assets.release, "Gitea release target");
+  if (
+    assets.release.state === "skipped" ||
+    (assets.release.id !== null &&
+      (!Number.isSafeInteger(assets.release.id) ||
+        (assets.release.id as number) <= 0)) ||
+    (assets.release.state === "verified" && assets.release.id === null)
+  ) {
+    throw new Error("Invalid Gitea release identity or status.");
+  }
+  const frozen: unknown[] = [];
+  for (const entry of assets.assets) {
+    if (!isPlainObject(entry)) throw new Error("Invalid Gitea asset target.");
+    assertExactKeys(
+      entry,
+      ["state", "attempts", "attempt", "error", "asset"],
+      "Gitea asset target",
+    );
+    assertTargetStatus(entry, "Gitea asset target");
+    if (entry.state === "skipped")
+      throw new Error("Gitea asset targets cannot be skipped.");
+    frozen.push(entry.asset);
+  }
+  assertGiteaFrozenAssets(
+    frozen,
+    assets.destination as unknown as IGiteaAssetDestination,
+    (valueArg.release as IReleaseJournalV1["release"])?.tag,
+  );
+  const commonComplete = [valueArg.git, ...valueArg.npm.registries].every(
+    (entry) => entry?.state === "verified" || entry?.state === "skipped",
+  );
+  const common = {
+    kind: valueArg.kind,
+    schemaVersion: valueArg.packages.length ? 3 : 1,
+    revision: valueArg.revision,
+    release: valueArg.release,
+    artifact: valueArg.artifact,
+    ...(valueArg.packages.length ? { packages: valueArg.packages } : {}),
+    git: valueArg.git,
+    npm: valueArg.npm,
+    createdAt: valueArg.createdAt,
+    updatedAt: valueArg.updatedAt,
+    completedAt: commonComplete ? valueArg.updatedAt : null,
+  };
+  if (valueArg.packages.length) assertReleaseJournalV3(common);
+  else assertReleaseJournalV1(common);
+  const journal = valueArg as unknown as IReleaseJournalV4;
+  const statuses = [
+    journal.git,
+    journal.giteaAssets.release,
+    ...journal.giteaAssets.assets,
+    ...journal.npm.registries,
+  ];
+  if (
+    journal.git.state === "skipped" ||
+    statuses.filter((entry) => entry.state === "publishing").length > 1
+  ) {
+    throw new Error(
+      "Gitea assets require an active Git target and one publication owner.",
+    );
+  }
+  const assetStates = journal.giteaAssets.assets;
+  const npmStarted = journal.npm.registries.some(
+    (entry) => entry.state !== "pending",
+  );
+  if (
+    (journal.git.state !== "verified" &&
+      journal.git.state !== "conflict" &&
+      statuses.slice(1).some((entry) => entry.state !== "pending")) ||
+    (journal.giteaAssets.release.state !== "verified" &&
+      journal.giteaAssets.release.state !== "conflict" &&
+      assetStates.some((entry) => entry.state !== "pending")) ||
+    (npmStarted &&
+      (journal.giteaAssets.release.id === null ||
+        assetStates.some(
+          (entry) => !["verified", "conflict"].includes(entry.state),
+        )))
+  )
+    throw new Error(
+      "Release targets violate Git, Gitea assets, npm publication order.",
+    );
+  if (journal.completedAt !== null) {
+    const completed = assertIsoTimestamp(
+      journal.completedAt,
+      "Release journal completedAt",
+    );
+    if (
+      !isComplete(journal) ||
+      completed < journal.createdAt ||
+      completed > journal.updatedAt
+    )
+      throw new Error("Release journal completion state is inconsistent.");
+  } else if (isComplete(journal))
+    throw new Error("Complete release journal must record completedAt.");
+  return journal;
+};
+
 export const assertReleaseJournal = (valueArg: unknown): TReleaseJournal => {
   if (!isPlainObject(valueArg)) {
     throw new Error("Release journal root must be a JSON object.");
@@ -1185,6 +1387,7 @@ export const assertReleaseJournal = (valueArg: unknown): TReleaseJournal => {
     return assertReleaseJournalV2(valueArg);
   }
   if (valueArg.schemaVersion === 3) return assertReleaseJournalV3(valueArg);
+  if (valueArg.schemaVersion === 4) return assertReleaseJournalV4(valueArg);
   throw new Error("Release journal header is invalid or unsupported.");
 };
 
@@ -1409,6 +1612,68 @@ const assertSchema2AppendOnlyTransition = (
   }
 };
 
+const assertSchema4AppendOnlyTransition = (
+  current: IReleaseJournalV4,
+  next: IReleaseJournalV4,
+): void => {
+  if (
+    current.giteaAssets.release.id !== null &&
+    current.giteaAssets.release.id !== next.giteaAssets.release.id
+  ) {
+    throw new Error("The recorded Gitea release identity cannot be replaced.");
+  }
+  if (
+    current.giteaAssets.release.id === null &&
+    next.giteaAssets.release.id !== null &&
+    next.giteaAssets.release.state !== "verified"
+  ) {
+    throw new Error(
+      "A Gitea release identity must be verified before recording it.",
+    );
+  }
+  const statuses = (journal: IReleaseJournalV4) => [
+    journal.git,
+    journal.giteaAssets.release,
+    ...journal.giteaAssets.assets,
+    ...journal.npm.registries,
+  ];
+  const nextStatuses = statuses(next);
+  for (const [index, before] of statuses(current).entries()) {
+    const after = nextStatuses[index];
+    if (before.state === "publishing" && after.state === "publishing") {
+      if (
+        JSON.stringify(before.attempt) !== JSON.stringify(after.attempt) ||
+        before.attempts !== after.attempts
+      )
+        throw new Error("Publication attempt ownership cannot change.");
+      continue;
+    }
+    if (
+      (before.state === "pending" || before.state === "failed") &&
+      after.state === "publishing"
+    ) {
+      if (after.attempts !== before.attempts + 1)
+        throw new Error(
+          "Publication claims must increment the attempt counter once.",
+        );
+      continue;
+    }
+    if (
+      after.attempts !== before.attempts ||
+      (after.state === "pending" && before.state !== "pending") ||
+      (before.state === "conflict" && after.state !== "conflict") ||
+      (before.state === "verified" &&
+        !["verified", "conflict"].includes(after.state)) ||
+      (before.state === "publishing" &&
+        !["verified", "failed", "conflict"].includes(after.state))
+    ) {
+      throw new Error(
+        "Release publication status cannot regress or rewrite attempt history.",
+      );
+    }
+  }
+};
+
 export const createReleaseAttempt = (): IReleaseAttempt => ({
   id: plugins.crypto.randomBytes(16).toString("hex"),
   pid: process.pid,
@@ -1479,7 +1744,8 @@ export class ReleaseJournalStore {
   ): string {
     if (
       fileArg !== releaseArtifactFileName &&
-      !/^package\.[0-9a-f]{64}\.tgz$/.test(fileArg)
+      !/^package\.[0-9a-f]{64}\.tgz$/.test(fileArg) &&
+      !/^asset\.[0-9a-f]{64}\.bin$/.test(fileArg)
     ) {
       throw new Error("Invalid release artifact filename.");
     }
@@ -1567,9 +1833,15 @@ export class ReleaseJournalStore {
       throw new Error("New release journals must start at revision 1.");
     }
     if (
-      journal.schemaVersion === 3 &&
+      (journal.schemaVersion === 3 || journal.schemaVersion === 4) &&
       (journal.completedAt !== null ||
-        [journal.git, ...journal.npm.registries].some(
+        [
+          journal.git,
+          ...journal.npm.registries,
+          ...(journal.schemaVersion === 4
+            ? [journal.giteaAssets.release, ...journal.giteaAssets.assets]
+            : []),
+        ].some(
           (target) =>
             !["pending", "skipped"].includes(target.state) ||
             target.attempts !== 0 ||
@@ -1578,7 +1850,7 @@ export class ReleaseJournalStore {
         ))
     ) {
       throw new Error(
-        "New schema 3 journals require unclaimed publication targets.",
+        "New package and asset journals require unclaimed publication targets.",
       );
     }
     if (journal.schemaVersion === releaseJournalSchemaVersion) {
@@ -1646,6 +1918,16 @@ export class ReleaseJournalStore {
         );
       }
     }
+    if (journal.schemaVersion === 4) {
+      if (journal.giteaAssets.release.id !== null)
+        throw new Error(
+          "New Gitea asset journals must not preclaim a release identity.",
+        );
+      await validateGiteaAssets(
+        temporaryDirectory,
+        journal.giteaAssets.assets.map((entry) => entry.asset),
+      );
+    }
 
     const releaseDirectory = this.getReleaseDirectory(journal.release.version);
     const lock = new InterProcessLock({
@@ -1721,6 +2003,8 @@ export class ReleaseJournalStore {
       ) {
         assertSchema2AppendOnlyTransition(current, next);
       }
+      if (current.schemaVersion === 4 && next.schemaVersion === 4)
+        assertSchema4AppendOnlyTransition(current, next);
       await this.writeAtomic(version, next);
       return next;
     });