@git.zone/cli 6.9.0 → 6.10.0

package/ts/mod_release/helpers.releasepublication.ts

@@ -7,12 +7,20 @@ import {
   getReleaseDockerPromotionContext,
   getReleaseArtifacts,
   getReleaseNpmArtifact,
+  hasReleasePackages,
   type TReleaseJournal,
   type IReleaseJournalV2,
+  type IReleaseJournalV4,
   type IReleaseTargetStatus,
   type TReleaseErrorCode,
   type TReleaseTargetState,
 } from "./classes.releasejournal.js";
+import {
+  GiteaAssetsClient,
+  GiteaAssetConflictError,
+  validateGiteaAssets,
+} from "./helpers.giteaassets.js";
+import { assertGiteaAssetsGitDestination } from "../helpers.workflow.js";
 import {
   probeAnonymousNpmArtifact,
   publishNpmArtifact,
@@ -75,6 +83,8 @@ export function buildReleaseGitPushArgs(
 
 type TReleaseTargetSelector =
   | { kind: "git" }
+  | { kind: "gitea-release" }
+  | { kind: "gitea-asset"; name: string }
   | { kind: "npm"; registry: string; packageName?: string }
   | { kind: "docker-qualification" }
   | { kind: "docker-promotion"; promotionId: string }
@@ -96,6 +106,15 @@ export interface IReleasePublicationOptions {
   recoveryAttemptId?: string;
   npmProbeOptions?: INpmArtifactProbeOptions;
   tsdocker?: ITsdockerReleaseClient;
+  giteaAssets?: Pick<
+    GiteaAssetsClient,
+    | "preflight"
+    | "inspectRelease"
+    | "createRelease"
+    | "inspectAssets"
+    | "uploadAsset"
+    | "verifyComplete"
+  >;
   ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
 }
 
@@ -106,6 +125,20 @@ const getTargetStatus = (
   if (selectorArg.kind === "git") {
     return journalArg.git;
   }
+  if (
+    selectorArg.kind === "gitea-release" ||
+    selectorArg.kind === "gitea-asset"
+  ) {
+    if (journalArg.schemaVersion !== 4)
+      throw new Error("Release journal has no Gitea assets.");
+    if (selectorArg.kind === "gitea-release")
+      return journalArg.giteaAssets.release;
+    const entry = journalArg.giteaAssets.assets.find(
+      (entry) => entry.asset.name === selectorArg.name,
+    );
+    if (!entry) throw new Error("Release journal has no matching Gitea asset.");
+    return entry;
+  }
   if (selectorArg.kind === "docker-qualification") {
     if (journalArg.schemaVersion !== 2) {
       throw new Error("Release journal does not contain Docker qualification.");
@@ -616,7 +649,7 @@ const executeNpmRegistry = async (
   // the accepted artifact on resume. Older root/Docker journal behavior stays
   // unchanged.
   if (
-    journal.schemaVersion === 3 &&
+    hasReleasePackages(journal) &&
     status.state === "failed" &&
     status.attempts > 0 &&
     status.error === "verification-inconclusive" &&
@@ -692,7 +725,7 @@ const executeNpmRegistry = async (
   }
   if (probe.status !== "absent") {
     if (
-      journal.schemaVersion === 3 &&
+      hasReleasePackages(journal) &&
       status.state === "failed" &&
       probe.status === "inconclusive"
     ) {
@@ -1432,6 +1465,165 @@ const executeDockerPromotion = async (
   );
 };
 
+const executeGiteaTarget = async (
+  options: IReleasePublicationOptions,
+  journalArg: TReleaseJournal,
+  selector: TReleaseTargetSelector,
+  inspect: () => Promise<boolean>,
+  publish: () => Promise<void>,
+  onVerified?: (target: IReleaseTargetStatus) => void,
+): Promise<TReleaseJournal> => {
+  let journal = journalArg;
+  let status = getTargetStatus(journal, selector);
+  if (status.state === "conflict")
+    throw new Error("Gitea publication has a recorded destination conflict.");
+  const mark = async (
+    state: "verified" | "failed" | "conflict",
+    error: TReleaseErrorCode | null,
+  ) => {
+    status = getTargetStatus(journal, selector);
+    journal = await updateTarget(
+      options.store,
+      journal,
+      selector,
+      status.state,
+      status.attempt?.id || null,
+      (target) => {
+        target.state = state;
+        target.error = error;
+        target.attempt = null;
+        if (state === "verified") onVerified?.(target);
+      },
+    );
+  };
+  let present: boolean;
+  try {
+    present = await inspect();
+  } catch (error) {
+    if (error instanceof GiteaAssetConflictError)
+      await mark("conflict", "destination-conflict");
+    throw error;
+  }
+  if (present) {
+    if (status.state !== "verified") await mark("verified", null);
+    return journal;
+  }
+  if (status.state === "verified") {
+    await mark("conflict", "destination-conflict");
+    throw new Error(
+      "A previously verified Gitea release or attachment is missing.",
+    );
+  }
+  if (status.state === "publishing") {
+    journal = await recoverPublishingTarget(
+      options.store,
+      journal,
+      selector,
+      options.recoveryAttemptId,
+    );
+  }
+  await options.ensurePublicationState(journal.release.mainOid);
+  journal = await claimTarget(options.store, journal, selector);
+  // One mutation per claimed attempt. Reconcile an accepted request even when
+  // its response was lost; never overwrite an attachment or recreate a tag.
+  let publicationError: unknown;
+  try {
+    await publish();
+  } catch (error) {
+    publicationError = error;
+  }
+  try {
+    present = await inspect();
+  } catch (error) {
+    await mark(
+      error instanceof GiteaAssetConflictError ? "conflict" : "failed",
+      error instanceof GiteaAssetConflictError
+        ? "destination-conflict"
+        : "verification-inconclusive",
+    );
+    throw error;
+  }
+  if (present) {
+    await mark("verified", null);
+    return journal;
+  }
+  await mark(
+    publicationError instanceof GiteaAssetConflictError ? "conflict" : "failed",
+    publicationError instanceof GiteaAssetConflictError
+      ? "destination-conflict"
+      : publicationError
+        ? "command-failed"
+        : "verification-inconclusive",
+  );
+  throw new Error(
+    "Gitea publication could not be verified; npm publication remains blocked. Inspect the retained journal before resuming.",
+  );
+};
+
+const executeGiteaAssets = async (
+  options: IReleasePublicationOptions,
+  journalArg: IReleaseJournalV4,
+  client: NonNullable<IReleasePublicationOptions["giteaAssets"]>,
+): Promise<IReleaseJournalV4> => {
+  let releaseId = journalArg.giteaAssets.release.id;
+  let journal = (await executeGiteaTarget(
+    options,
+    journalArg,
+    { kind: "gitea-release" },
+    async () => {
+      const release = await client.inspectRelease();
+      if (!release) return false;
+      if (releaseId !== null && release.id !== releaseId)
+        throw new GiteaAssetConflictError("Gitea release identity changed.");
+      releaseId = release.id;
+      return true;
+    },
+    async () => {
+      await client.createRelease();
+    },
+    (target) => {
+      (target as IReleaseJournalV4["giteaAssets"]["release"]).id = releaseId;
+    },
+  )) as IReleaseJournalV4;
+  if (releaseId === null)
+    throw new Error("Gitea release has no verified identity.");
+  const expected = journal.giteaAssets.assets.map((entry) => entry.asset);
+  const directory = options.store.getReleaseDirectory(journal.release.version);
+  for (const { asset } of journal.giteaAssets.assets) {
+    journal = (await executeGiteaTarget(
+      options,
+      journal,
+      { kind: "gitea-asset", name: asset.name },
+      async () => {
+        const inspection = await client.inspectAssets(releaseId!, expected);
+        return inspection.present.some((entry) => entry.name === asset.name);
+      },
+      async () => {
+        await validateGiteaAssets(directory, expected);
+        await client.uploadAsset(releaseId!, asset, directory);
+      },
+    )) as IReleaseJournalV4;
+  }
+  // One full anonymous verification immediately before entering the npm phase.
+  // Resume always repeats it, including an otherwise completed journal.
+  try {
+    await client.verifyComplete(releaseId, expected);
+  } catch (error) {
+    if (error instanceof GiteaAssetConflictError) {
+      await markUnclaimedTarget(
+        options.store,
+        journal,
+        { kind: "gitea-release" },
+        ["verified"],
+        "conflict",
+        "destination-conflict",
+      );
+    }
+    throw error;
+  }
+  return journal;
+};
+
 export const executeReleasePublication = async (
   optionsArg: IReleasePublicationOptions,
 ): Promise<TReleaseJournal> => {
@@ -1443,6 +1635,32 @@ export const executeReleasePublication = async (
       artifact,
     );
   }
+  let giteaClient = optionsArg.giteaAssets;
+  if (journal.schemaVersion === 4) {
+    const { destination, tokenEnv, manifestPath, assets } = journal.giteaAssets;
+    assertGiteaAssetsGitDestination(
+      { ...destination, tokenEnv, manifestPath },
+      optionsArg.pushUrl || "",
+    );
+    await validateGiteaAssets(
+      optionsArg.store.getReleaseDirectory(journal.release.version),
+      assets.map((entry) => entry.asset),
+    );
+    if (!giteaClient) {
+      const token = process.env[tokenEnv];
+      if (!token)
+        throw new Error(
+          `Gitea assets require the configured credential in ${tokenEnv}.`,
+        );
+      giteaClient = new GiteaAssetsClient({
+        destination,
+        token,
+        tag: journal.release.tag,
+        commit: journal.release.mainOid,
+      });
+    }
+    await giteaClient.preflight();
+  }
   if (journal.schemaVersion === 2) {
     journal = await executeDockerQualification(optionsArg, journal);
     if (
@@ -1453,6 +1671,8 @@ export const executeReleasePublication = async (
     }
   }
   journal = await executeGitTarget(optionsArg, journal);
+  if (journal.schemaVersion === 4)
+    journal = await executeGiteaAssets(optionsArg, journal, giteaClient!);
   const expectedRemoteMainOid =
     journal.git.state === "verified"
       ? journal.release.mainOid
@@ -1464,12 +1684,12 @@ export const executeReleasePublication = async (
       journal,
       registry.registry,
       registry.packageName,
-      journal.schemaVersion === 3,
+      hasReleasePackages(journal),
     );
   }
   // Submit in dependency order before waiting for npm's publish-time scans.
   // Success still requires every package/registry cell to verify exactly.
-  if (journal.schemaVersion === 3) {
+  if (hasReleasePackages(journal)) {
     for (const registry of journal.npm.registries) {
       if (
         registry.state !== "failed" ||

package/ts/mod_release/index.ts

@@ -12,6 +12,7 @@ import {
   resolveReleaseDockerConfiguration,
   resolveReleaseWorkflow,
   resolveReleaseResumeConfiguration,
+  assertGiteaAssetsGitDestination,
   type IResolvedReleaseResumeConfiguration,
   type IResolvedReleaseWorkflow,
 } from "../helpers.workflow.js";
@@ -35,6 +36,7 @@ import {
   normalizeReleaseVersion,
   resolveGitCommonDirectory,
   getReleaseArtifacts,
+  hasReleasePackages,
   releasePackageArtifactFile,
   type IReleasePackage,
   type IReleaseArtifact,
@@ -42,6 +44,10 @@ import {
   type IReleaseJournalV1,
   type IReleaseJournalV2,
 } from "./classes.releasejournal.js";
+import {
+  GiteaAssetsClient,
+  prepareGiteaAssets,
+} from "./helpers.giteaassets.js";
 import {
   assertNoLegacyNpmPublisher,
   assertPnpmReleaseCapability,
@@ -127,6 +133,11 @@ const runInternal = async (argvArg: any): Promise<void> => {
     mergeRequested,
     planMode: workflow.confirmation === "plan",
   });
+  if (workflow.giteaAssets)
+    assertGiteaAssetsGitDestination(
+      workflow.giteaAssets,
+      branchContext.pushUrl || "",
+    );
   printReleasePlan(workflow, branchContext);
   if (
     workflow.targets.includes("npm") &&
@@ -172,6 +183,20 @@ const runInternal = async (argvArg: any): Promise<void> => {
     currentVersion,
     versionType,
   );
+  if (workflow.giteaAssets) {
+    const { tokenEnv, manifestPath, ...destination } = workflow.giteaAssets;
+    const token = process.env[tokenEnv];
+    if (!token)
+      throw new Error(
+        `Gitea assets require the configured credential in ${tokenEnv}.`,
+      );
+    await new GiteaAssetsClient({
+      destination,
+      tag: `v${plannedVersion}`,
+      commit: branchContext.sourceOid,
+      token,
+    }).preflight();
+  }
   if (preflightTsdocker) {
     await preflightTsdocker.validate(
       createDockerQualificationRequest(
@@ -352,6 +377,18 @@ const assertReleaseConfiguration = (
   workflowArg: IResolvedReleaseWorkflow,
   mergeRequestedArg: boolean,
 ): void => {
+  if (
+    workflowArg.targets.includes("giteaAssets") &&
+    (!workflowArg.giteaAssets ||
+      !workflowArg.targets.includes("git") ||
+      !workflowArg.pushBranch ||
+      !workflowArg.pushTags ||
+      workflowArg.targets.includes("docker") ||
+      mergeRequestedArg)
+  )
+    throw new Error(
+      "Gitea asset releases require integrated main and Git branch/tag publication without Docker.",
+    );
   if (workflowArg.targets.includes("docker")) {
     if (mergeRequestedArg) {
       throw new Error(
@@ -549,10 +586,47 @@ export const createReleaseJournal = async (
     }
     const now = new Date().toISOString();
     const gitStatus = createInitialTargetStatus(gitEnabled);
+    const assetConfiguration = optionsArg.workflow.giteaAssets;
+    let giteaAssets:
+      | import("./classes.releasejournal.js").IReleaseGiteaAssetsJournal
+      | undefined;
+    if (optionsArg.workflow.targets.includes("giteaAssets")) {
+      if (!assetConfiguration || !gitEnabled || optionsArg.dockerRequest)
+        throw new Error("Invalid Gitea asset target combination.");
+      assertGiteaAssetsGitDestination(
+        assetConfiguration,
+        optionsArg.releasePushUrl!,
+      );
+      const { tokenEnv, manifestPath, ...destination } = assetConfiguration;
+      const assets = await prepareGiteaAssets({
+        repositoryRoot: npmSourceCwd,
+        manifestPath,
+        version: optionsArg.version,
+        tag: `v${optionsArg.version}`,
+        artifactDirectory: temporaryDirectory,
+        destination,
+      });
+      giteaAssets = {
+        destination,
+        tokenEnv,
+        manifestPath,
+        release: { ...createInitialTargetStatus(true), id: null },
+        assets: assets.map((asset) => ({
+          ...createInitialTargetStatus(true),
+          asset,
+        })),
+      };
+    }
     const journal = finalizeJournalCompletion(
       {
         kind: "gitzone-release-journal",
-        schemaVersion: packages.length ? 3 : optionsArg.dockerRequest ? 2 : 1,
+        schemaVersion: giteaAssets
+          ? 4
+          : packages.length
+            ? 3
+            : optionsArg.dockerRequest
+              ? 2
+              : 1,
         revision: 1,
         release: {
           version: optionsArg.version,
@@ -561,7 +635,7 @@ export const createReleaseJournal = async (
           tagOid: optionsArg.refs.tagOid,
         },
         artifact,
-        ...(packages.length ? { packages } : {}),
+        ...(packages.length || giteaAssets ? { packages } : {}),
         git: {
           state: gitStatus.state,
           attempts: gitStatus.attempts,
@@ -602,6 +676,7 @@ export const createReleaseJournal = async (
                 })
               : [],
         },
+        ...(giteaAssets ? { giteaAssets } : {}),
         ...(optionsArg.dockerRequest
           ? {
               docker: createInitialReleaseDockerJournal(
@@ -887,6 +962,7 @@ const runReleaseResume = async (
   const resumeConfiguration = await resolveReleaseResumeConfiguration({
     git: gitEnabled,
     npm: journal.npm.registries.length > 0,
+    giteaAssets: journal.schemaVersion === 4,
   });
   await assertResumeConfiguration(resumeConfiguration, journal, paths.cwd);
   let tsdocker: ITsdockerReleaseClient | undefined;
@@ -1033,13 +1109,24 @@ const assertResumeConfiguration = async (
       ]) ||
       workflowArg.npmAccessLevel !== journalArg.npm.access ||
       workflowArg.npmPackageSource !==
-        (journalArg.schemaVersion === 3 ? "tspublish" : "root") ||
+        (hasReleasePackages(journalArg) ? "tspublish" : "root") ||
       workflowArg.npmAlreadyPublished !== journalArg.npm.alreadyPublished)
   ) {
     throw new Error(
       "Current npm release configuration does not match the journal.",
     );
   }
+  if (journalArg.schemaVersion === 4) {
+    const { destination, tokenEnv, manifestPath } = journalArg.giteaAssets;
+    if (
+      JSON.stringify(workflowArg.giteaAssets) !==
+      JSON.stringify({ ...destination, tokenEnv, manifestPath })
+    ) {
+      throw new Error(
+        "Current Gitea asset configuration does not match the journal.",
+      );
+    }
+  }
   if (
     journalArg.git.state !== "skipped" ||
     getReleaseArtifacts(journalArg).length
@@ -1061,12 +1148,19 @@ const printReleaseJournalSummary = (journalArg: TReleaseJournal): void => {
       `npm ${registry.packageName ? `${registry.packageName} ` : ""}${registry.registry}: ${registry.state}`,
     );
   }
-  if (journalArg.schemaVersion === 3) {
+  if (hasReleasePackages(journalArg)) {
     for (const { artifact } of journalArg.packages)
       console.log(
         `artifact ${artifact.packageName}: ${artifact.integrity} (${artifact.sha256})`,
       );
   }
+  if (journalArg.schemaVersion === 4) {
+    console.log(`Gitea release: ${journalArg.giteaAssets.release.state}`);
+    for (const entry of journalArg.giteaAssets.assets)
+      console.log(
+        `asset ${entry.asset.name}: ${entry.state} (${entry.asset.sha256})`,
+      );
+  }
   if (journalArg.schemaVersion === 2) {
     console.log(
       `docker qualification ${journalArg.docker.request.candidateId}: ${journalArg.docker.qualification.state}`,
@@ -1416,6 +1510,14 @@ function printReleasePlan(
       `npm registries: ${workflow.npmRegistries.length > 0 ? workflow.npmRegistries.join(", ") : "none"}`,
     );
   }
+  if (workflow.giteaAssets) {
+    const assets = workflow.giteaAssets;
+    console.log(
+      `Gitea assets: ${assets.apiOrigin}/${assets.owner}/${assets.repository}`,
+    );
+    console.log(`asset manifest: ${assets.manifestPath}`);
+    console.log(`asset credential variable: ${assets.tokenEnv}`);
+  }
   if (workflow.targets.includes("docker")) {
     console.log(`docker engine: ${workflow.dockerEngine}`);
     console.log(
@@ -1479,7 +1581,7 @@ export function showHelp(mode?: ICliMode): void {
         {
           flag: "--target <names>",
           description:
-            "Replace configured targets with a non-empty subset of git,npm,docker",
+            "Replace configured targets with a non-empty subset of git,giteaAssets,npm,docker",
         },
         { flag: "--npm", description: "Explicitly select the npm target" },
         {
@@ -1489,7 +1591,8 @@ export function showHelp(mode?: ICliMode): void {
         },
         {
           flag: "--no-publish",
-          description: "Remove npm and Docker without implicitly enabling Git",
+          description:
+            "Remove Gitea assets, npm and Docker without implicitly enabling Git",
         },
         {
           flag: "--merge",
@@ -1542,14 +1645,14 @@ export function showHelp(mode?: ICliMode): void {
   console.log("  --no-build          Disable the post-metadata release build");
   console.log("  -p, --push          Explicitly select the git target");
   console.log(
-    "  --target <names>    Replace configured targets with a non-empty subset of git,npm,docker",
+    "  --target <names>    Replace configured targets with a non-empty subset of git,giteaAssets,npm,docker",
   );
   console.log("  --npm               Explicitly select the npm target");
   console.log(
     "  --docker            Select digest-qualified Docker publication through project-local tSDocker >= 3.5.1",
   );
   console.log(
-    "  --no-publish        Remove npm and Docker without implicitly enabling Git",
+    "  --no-publish        Remove Gitea assets, npm and Docker without implicitly enabling Git",
   );
   console.log(
     "  --merge             Fast-forward and lease-push a cleanly rebased feature branch before release metadata",

package/ts/mod_release/interfaces.giteaassets.ts

@@ -0,0 +1,67 @@
+export interface IGiteaAssetDestination {
+  apiOrigin: string;
+  owner: string;
+  repository: string;
+}
+
+export interface IGiteaFrozenAsset {
+  name: string;
+  size: number;
+  sha256: string;
+  fileName: string;
+  publicUrl: string;
+}
+
+export interface IPrepareGiteaAssetsOptions {
+  repositoryRoot: string;
+  manifestPath: string;
+  version: string;
+  tag: string;
+  artifactDirectory: string;
+  destination: IGiteaAssetDestination;
+}
+
+export interface IGiteaRelease {
+  id: number;
+  tag: string;
+  publicUrl: string;
+}
+
+export interface IGiteaAssetInspection {
+  present: IGiteaFrozenAsset[];
+  missing: IGiteaFrozenAsset[];
+}
+
+export interface IGiteaAssetsClientOptions {
+  destination: IGiteaAssetDestination;
+  tag: string;
+  commit: string;
+  token: string;
+  fetchImplementation?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface IGiteaAssetPreflight {
+  repositoryId: number;
+  /** Issue-attachment setting; Gitea's release FILE_MAX_SIZE is separate. */
+  generalAttachmentMaximumBytes: number;
+}
+
+export interface IGiteaAssetsClient {
+  preflight(): Promise<IGiteaAssetPreflight>;
+  inspectRelease(): Promise<IGiteaRelease | null>;
+  createRelease(): Promise<IGiteaRelease>;
+  inspectAssets(
+    releaseId: number,
+    expected: IGiteaFrozenAsset[],
+  ): Promise<IGiteaAssetInspection>;
+  uploadAsset(
+    releaseId: number,
+    asset: IGiteaFrozenAsset,
+    artifactDirectory: string,
+  ): Promise<void>;
+  verifyComplete(
+    releaseId: number,
+    expected: IGiteaFrozenAsset[],
+  ): Promise<void>;
+}