@git.zone/cli 6.9.0 → 6.11.0

package/ts/mod_release/helpers.npmartifact.ts

@@ -4,16 +4,15 @@ import {
   type IReleaseArtifact,
 } from "./classes.releasejournal.js";
 import { assertCredentialFreeGitPushDestination } from "./helpers.releasebranch.js";
-
-const supportedPnpmVersions = [
-  "11.25.0",
-  "12.1.0",
-  "12.2.1",
-  "12.3.0",
-  "12.3.4",
-] as const;
-const pnpmHelpRequirements = {
-  "11.25.0": {
+import {
+  getDefaultMinimumReleaseAgeMinutes,
+  packageSelectorMatches,
+} from "../mod_tools/classes.packagemanager.js";
+
+const stablePnpmVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+// Qualify the command contract, independently of the executable's version.
+const pnpmHelpRequirements = [
+  {
     pack: ["--out <path>", "--json"],
     publish: [
       "publish [<tarball>|<dir>]",
@@ -24,33 +23,7 @@ const pnpmHelpRequirements = {
       "--access <public|restricted>",
     ],
   },
-  "12.1.0": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-  "12.2.1": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-  "12.3.0": {
+  {
     pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
     publish: [
       "Usage: pnpm publish [OPTIONS] [PACKAGE]",
@@ -63,20 +36,7 @@ const pnpmHelpRequirements = {
       "[possible values: public, restricted]",
     ],
   },
-  "12.3.4": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-} as const;
+] as const;
 const maximumMetadataResponseBytes = 8 * 1024 * 1024;
 const capabilityCommandTimeoutMs = 30_000;
 const packCommandTimeoutMs = 10 * 60_000;
@@ -91,17 +51,14 @@ export function assertNpmPackageName(value: unknown): asserts value is string {
 }
 
 export interface IPnpmReleaseCapability {
-  readonly version: (typeof supportedPnpmVersions)[number];
+  readonly version: string;
 }
 
 export const buildQualifiedPnpmArgs = (
   capabilityArg: IPnpmReleaseCapability | undefined,
   argsArg: readonly string[],
 ): string[] => {
-  if (
-    !capabilityArg ||
-    !supportedPnpmVersions.includes(capabilityArg.version)
-  ) {
+  if (!capabilityArg || !stablePnpmVersion.test(capabilityArg.version)) {
     throw new Error(
       "npm release commands require a qualified pnpm invocation.",
     );
@@ -165,15 +122,140 @@ const readPackageIdentity = async (
 
 const requireHelpFragments = (
   outputArg: string,
-  fragmentsArg: readonly string[],
-  commandArg: string,
+  commandArg: "pack" | "publish",
 ): void => {
-  const missing = fragmentsArg.filter(
-    (fragmentArg) => !outputArg.includes(fragmentArg),
+  const missing = pnpmHelpRequirements.map((requirements) =>
+    requirements[commandArg].filter(
+      (fragment) => !outputArg.includes(fragment),
+    ),
+  );
+  if (missing.every((fragments) => fragments.length > 0)) {
+    throw new Error(
+      `pnpm ${commandArg} is missing required exact-release capabilities: ${missing.map((fragments) => fragments.join(", ")).join("; or ")}.`,
+    );
+  }
+};
+
+const readPnpmJson = async (
+  shellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  capabilityArg: IPnpmReleaseCapability,
+  argsArg: string[],
+  labelArg: string,
+): Promise<unknown> => {
+  const result = await shellArg.execSpawn(
+    "pnpm",
+    buildQualifiedPnpmArgs(capabilityArg, [...argsArg, "--json"]),
+    {
+      cwd: cwdArg,
+      silent: true,
+      timeout: capabilityCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+      maxBuffer: maximumMetadataResponseBytes,
+    },
+  );
+  if (result.exitCode !== 0 || result.timedOut) {
+    throw new Error(`Unable to inspect pnpm ${labelArg}.`);
+  }
+  if (result.stdout.trim() === "undefined") return undefined;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid pnpm ${labelArg} response.`);
+  }
+};
+
+const assertPnpmReleaseAge = async (
+  shellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  capabilityArg: IPnpmReleaseCapability,
+): Promise<void> => {
+  const configuredAge = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["config", "get", "minimum-release-age"],
+    "minimum release age",
+  );
+  const age =
+    configuredAge === undefined || configuredAge === null
+      ? getDefaultMinimumReleaseAgeMinutes(capabilityArg.version)
+      : configuredAge;
+  if (
+    typeof age !== "number" ||
+    !Number.isSafeInteger(age) ||
+    age < 0 ||
+    age > Number.MAX_SAFE_INTEGER / 60_000
+  ) {
+    throw new Error(
+      "pnpm minimum-release-age must be a nonnegative integer number of minutes.",
+    );
+  }
+  if (age === 0) return;
+  const configuredExclusions = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["config", "get", "minimum-release-age-exclude"],
+    "release-age exclusions",
   );
-  if (missing.length > 0) {
+  const exclusions =
+    configuredExclusions === undefined || configuredExclusions === null
+      ? []
+      : configuredExclusions;
+  if (
+    !Array.isArray(exclusions) ||
+    exclusions.some((value) => typeof value !== "string" || !value.trim())
+  ) {
     throw new Error(
-      `pnpm ${commandArg} is missing required exact-release capabilities: ${missing.join(", ")}.`,
+      "pnpm minimum-release-age-exclude must be an array of package selectors.",
+    );
+  }
+  if (
+    exclusions.some((selector) =>
+      packageSelectorMatches("pnpm", capabilityArg.version, selector),
+    )
+  )
+    return;
+
+  const times = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["view", `pnpm@${capabilityArg.version}`, "time"],
+    "publication times",
+  );
+  if (!times || typeof times !== "object" || Array.isArray(times)) {
+    throw new Error("pnpm publication times must be an object.");
+  }
+  const publishedAt = Object.hasOwn(times, capabilityArg.version)
+    ? (times as Record<string, unknown>)[capabilityArg.version]
+    : undefined;
+  if (publishedAt === undefined) {
+    const ignoreMissingTime = await readPnpmJson(
+      shellArg,
+      cwdArg,
+      capabilityArg,
+      ["config", "get", "minimum-release-age-ignore-missing-time"],
+      "missing publication time policy",
+    );
+    if (
+      ignoreMissingTime === true ||
+      ignoreMissingTime === undefined ||
+      ignoreMissingTime === null
+    )
+      return;
+    throw new Error(
+      `The registry has no publication time for pnpm ${capabilityArg.version}; its minimum release age cannot be verified.`,
+    );
+  }
+  const timestamp =
+    typeof publishedAt === "string" ? Date.parse(publishedAt) : NaN;
+  if (!Number.isFinite(timestamp))
+    throw new Error("Invalid pnpm publication timestamp.");
+  if (timestamp > Date.now() - age * 60_000) {
+    throw new Error(
+      `pnpm ${capabilityArg.version} does not yet satisfy minimum-release-age (${age} minutes).`,
     );
   }
 };
@@ -189,16 +271,17 @@ export const assertPnpmReleaseCapability = async (
     timeoutKillGraceMs: 5_000,
   });
   const version = versionResult.stdout.trim();
-  const supportedVersion = supportedPnpmVersions.find(
-    (candidateArg) => candidateArg === version,
-  );
-  if (versionResult.exitCode !== 0 || !supportedVersion) {
+  if (
+    versionResult.exitCode !== 0 ||
+    versionResult.timedOut ||
+    !stablePnpmVersion.test(version)
+  ) {
     throw new Error(
-      `Exact release packaging requires a verified pnpm version (${supportedPnpmVersions.join(", ")}); resolved ${version || "unknown"}.`,
+      "Exact release packaging requires a canonical stable pnpm version.",
     );
   }
-  const requirements = pnpmHelpRequirements[supportedVersion];
-  const capability = Object.freeze({ version: supportedVersion });
+  const capability = Object.freeze({ version });
+  await assertPnpmReleaseAge(smartshellArg, cwdArg, capability);
 
   const packHelp = await smartshellArg.execSpawn(
     "pnpm",
@@ -210,12 +293,12 @@ export const assertPnpmReleaseCapability = async (
       timeoutKillGraceMs: 5_000,
     },
   );
-  if (packHelp.exitCode !== 0) {
+  if (packHelp.exitCode !== 0 || packHelp.timedOut) {
     throw new Error(
       "Unable to inspect the selected pnpm pack capabilities. Exact release commands require standalone pnpm with support; Corepack launchers are unsupported.",
     );
   }
-  requireHelpFragments(packHelp.combinedOutput, requirements.pack, "pack");
+  requireHelpFragments(packHelp.combinedOutput, "pack");
 
   const publishHelp = await smartshellArg.execSpawn(
     "pnpm",
@@ -227,14 +310,10 @@ export const assertPnpmReleaseCapability = async (
       timeoutKillGraceMs: 5_000,
     },
   );
-  if (publishHelp.exitCode !== 0) {
+  if (publishHelp.exitCode !== 0 || publishHelp.timedOut) {
     throw new Error("Unable to inspect pnpm publish capabilities.");
   }
-  requireHelpFragments(
-    publishHelp.combinedOutput,
-    requirements.publish,
-    "publish",
-  );
+  requireHelpFragments(publishHelp.combinedOutput, "publish");
   return capability;
 };
 

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" ||