@git.zone/cli 6.14.0 → 6.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22,6 +22,9 @@ import {
22
22
  } from "./helpers.giteaassets.js";
23
23
  import { assertGiteaAssetsGitDestination } from "../helpers.workflow.js";
24
24
  import {
25
+ defaultNpmVerificationWindowMinutes,
26
+ npmPublishWasAccepted,
27
+ planNpmAvailabilityProbes,
25
28
  probeAnonymousNpmArtifact,
26
29
  publishNpmArtifact,
27
30
  verifyStoredNpmArtifact,
@@ -105,6 +108,8 @@ export interface IReleasePublicationOptions {
105
108
  pushUrl?: string;
106
109
  recoveryAttemptId?: string;
107
110
  npmProbeOptions?: INpmArtifactProbeOptions;
111
+ /** Waiting budget for one accepted npm target before resume takes over. */
112
+ npmVerificationWindowMs?: number;
108
113
  tsdocker?: ITsdockerReleaseClient;
109
114
  giteaAssets?: Pick<
110
115
  GiteaAssetsClient,
@@ -231,7 +236,7 @@ const finishPublishingTarget = async (
231
236
  storeArg: ReleaseJournalStore,
232
237
  journalArg: TReleaseJournal,
233
238
  selectorArg: TReleaseTargetSelector,
234
- stateArg: "verified" | "failed" | "conflict",
239
+ stateArg: "accepted" | "verified" | "failed" | "conflict",
235
240
  errorArg: TReleaseErrorCode | null,
236
241
  ): Promise<TReleaseJournal> => {
237
242
  const attemptId = getTargetStatus(journalArg, selectorArg).attempt?.id;
@@ -324,8 +329,10 @@ const inspectRemoteRelease = async (
324
329
  const mainOid = refs.get("refs/heads/main");
325
330
  const tagOid = refs.get(tagRef);
326
331
  const tagCommitOid = refs.get(`${tagRef}^{}`);
332
+ // A published release is identified by its annotated tag. Main carrying
333
+ // later commits is normal history, so only the tag decides exactness; the
334
+ // branch itself is leased during publication.
327
335
  if (
328
- mainOid === journalArg.release.mainOid &&
329
336
  tagOid === journalArg.release.tagOid &&
330
337
  tagCommitOid === journalArg.release.mainOid
331
338
  ) {
@@ -524,7 +531,7 @@ const executeGitTarget = async (
524
531
  const probeNpm = async (
525
532
  journalArg: TReleaseJournal,
526
533
  registryArg: string,
527
- optionsArg: IReleasePublicationOptions,
534
+ probeOptionsArg: INpmArtifactProbeOptions | undefined,
528
535
  waitArg = false,
529
536
  packageNameArg?: string,
530
537
  ): Promise<INpmArtifactProbeResult> => {
@@ -534,16 +541,50 @@ const probeNpm = async (
534
541
  registryArg,
535
542
  artifact,
536
543
  journalArg.npm.tag,
537
- optionsArg.npmProbeOptions,
544
+ probeOptionsArg,
538
545
  )
539
546
  : probeAnonymousNpmArtifact(
540
547
  registryArg,
541
548
  artifact,
542
549
  journalArg.npm.tag,
543
- optionsArg.npmProbeOptions,
550
+ probeOptionsArg,
544
551
  );
545
552
  };
546
553
 
554
+ /** Waiting probes start fast and back off, because npm serves most versions within minutes. */
555
+ const npmAvailabilityDelayMs = 2_000;
556
+ const npmAvailabilityMaxDelayMs = 20_000;
557
+ const defaultNpmVerificationWindowMs =
558
+ defaultNpmVerificationWindowMinutes * 60_000;
559
+
560
+ const availabilityProbeOptions = (
561
+ optionsArg: IReleasePublicationOptions,
562
+ ): INpmArtifactProbeOptions => ({
563
+ ...planNpmAvailabilityProbes(
564
+ optionsArg.npmVerificationWindowMs ?? defaultNpmVerificationWindowMs,
565
+ npmAvailabilityDelayMs,
566
+ npmAvailabilityMaxDelayMs,
567
+ ),
568
+ ...optionsArg.npmProbeOptions,
569
+ });
570
+
571
+ const describeNpmTarget = (
572
+ registryArg: string,
573
+ packageNameArg?: string,
574
+ ): string =>
575
+ packageNameArg ? `${packageNameArg} on ${registryArg}` : registryArg;
576
+
577
+ const reportAcceptedNpmTarget = (
578
+ journalArg: TReleaseJournal,
579
+ registryArg: string,
580
+ packageNameArg?: string,
581
+ ): void => {
582
+ console.log(
583
+ `npm accepted ${describeNpmTarget(registryArg, packageNameArg)} but does not serve it yet. ` +
584
+ `Nothing is republished: run \`gitzone release resume ${journalArg.release.version} -y\` later to verify it.`,
585
+ );
586
+ };
587
+
547
588
  const markNpmProbeFailure = async (
548
589
  optionsArg: IReleasePublicationOptions,
549
590
  journalArg: TReleaseJournal,
@@ -579,7 +620,7 @@ const executeNpmRegistry = async (
579
620
  let probe = await probeNpm(
580
621
  journal,
581
622
  registryArg,
582
- optionsArg,
623
+ optionsArg.npmProbeOptions,
583
624
  false,
584
625
  packageNameArg,
585
626
  );
@@ -644,33 +685,44 @@ const executeNpmRegistry = async (
644
685
  throw new Error(`npm registry target is in conflict: ${registryArg}`);
645
686
  }
646
687
 
647
- // A component submission can succeed before npm makes it installable. Keep
648
- // that uncertainty durable without retaining a live publisher or resending
649
- // the accepted artifact on resume. Older root/Docker journal behavior stays
650
- // unchanged.
651
- if (
652
- hasReleasePackages(journal) &&
653
- status.state === "failed" &&
654
- status.attempts > 0 &&
655
- status.error === "verification-inconclusive" &&
656
- probe.status !== "exact" &&
657
- probe.status !== "conflict"
658
- ) {
688
+ // The registry took the upload before serving it. That uncertainty is
689
+ // durable: the accepted bytes are never sent again, and only an exact probe
690
+ // promotes the target.
691
+ if (status.state === "accepted") {
692
+ const settleAccepted = async (
693
+ probeArg: INpmArtifactProbeResult,
694
+ ): Promise<TReleaseJournal | undefined> => {
695
+ if (probeArg.status === "exact") {
696
+ return markUnclaimedTarget(
697
+ optionsArg.store,
698
+ journal,
699
+ selector,
700
+ ["accepted"],
701
+ "verified",
702
+ null,
703
+ );
704
+ }
705
+ if (probeArg.status !== "conflict") return undefined;
706
+ await markUnclaimedTarget(
707
+ optionsArg.store,
708
+ journal,
709
+ selector,
710
+ ["accepted"],
711
+ "conflict",
712
+ "artifact-conflict",
713
+ );
714
+ throw new Error(`npm registry contains conflicting bytes: ${registryArg}`);
715
+ };
716
+ const alreadyReadable = await settleAccepted(probe);
717
+ if (alreadyReadable) return alreadyReadable;
659
718
  if (deferVerificationArg) return journal;
660
719
  console.log(
661
- `Waiting for npm availability: ${packageNameArg} on ${registryArg}`,
720
+ `Waiting for npm availability: ${describeNpmTarget(registryArg, packageNameArg)}`,
662
721
  );
663
722
  probe = await probeNpm(
664
723
  journal,
665
724
  registryArg,
666
- {
667
- ...optionsArg,
668
- npmProbeOptions: {
669
- attempts: 91,
670
- delayMs: 10_000,
671
- ...optionsArg.npmProbeOptions,
672
- },
673
- },
725
+ availabilityProbeOptions(optionsArg),
674
726
  true,
675
727
  packageNameArg,
676
728
  );
@@ -679,26 +731,16 @@ const executeNpmRegistry = async (
679
731
  ? journal.release.mainOid
680
732
  : journal.git.expectedRemoteMainOid || undefined,
681
733
  );
682
- if (probe.status === "exact") {
683
- return markUnclaimedTarget(
684
- optionsArg.store,
685
- journal,
686
- selector,
687
- ["failed"],
688
- "verified",
689
- null,
690
- );
691
- }
692
- await markNpmProbeFailure(optionsArg, journal, selector, ["failed"], probe);
693
- throw new Error(
694
- `npm availability could not be verified: ${packageNameArg} on ${registryArg}`,
695
- );
734
+ const becameReadable = await settleAccepted(probe);
735
+ if (becameReadable) return becameReadable;
736
+ reportAcceptedNpmTarget(journal, registryArg, packageNameArg);
737
+ return journal;
696
738
  }
697
739
 
698
740
  probe = await probeNpm(
699
741
  journal,
700
742
  registryArg,
701
- optionsArg,
743
+ optionsArg.npmProbeOptions,
702
744
  false,
703
745
  packageNameArg,
704
746
  );
@@ -724,13 +766,9 @@ const executeNpmRegistry = async (
724
766
  );
725
767
  }
726
768
  if (probe.status !== "absent") {
727
- if (
728
- hasReleasePackages(journal) &&
729
- status.state === "failed" &&
730
- probe.status === "inconclusive"
731
- ) {
732
- // Preserve a prior command failure: a later network failure must not
733
- // turn it into evidence that the registry accepted the submission.
769
+ if (status.state === "failed" && probe.status === "inconclusive") {
770
+ // Preserve the recorded failure cause: a later network failure must not
771
+ // overwrite why the registry rejected the submission.
734
772
  throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
735
773
  }
736
774
  await markNpmProbeFailure(
@@ -762,7 +800,7 @@ const executeNpmRegistry = async (
762
800
  probe = await probeNpm(
763
801
  journal,
764
802
  registryArg,
765
- optionsArg,
803
+ availabilityProbeOptions(optionsArg),
766
804
  !deferVerificationArg,
767
805
  packageNameArg,
768
806
  );
@@ -785,17 +823,26 @@ const executeNpmRegistry = async (
785
823
  );
786
824
  throw new Error(`npm registry published conflicting bytes: ${registryArg}`);
787
825
  }
788
- journal = await finishPublishingTarget(
826
+ if (npmPublishWasAccepted(publishResult)) {
827
+ journal = await finishPublishingTarget(
828
+ optionsArg.store,
829
+ journal,
830
+ selector,
831
+ "accepted",
832
+ null,
833
+ );
834
+ if (!deferVerificationArg)
835
+ reportAcceptedNpmTarget(journal, registryArg, packageNameArg);
836
+ return journal;
837
+ }
838
+ await finishPublishingTarget(
789
839
  optionsArg.store,
790
840
  journal,
791
841
  selector,
792
842
  "failed",
793
- publishResult.exitCode === 0
794
- ? "verification-inconclusive"
795
- : "command-failed",
843
+ "command-failed",
796
844
  );
797
- if (deferVerificationArg && publishResult.exitCode === 0) return journal;
798
- throw new Error(`npm publication could not be verified: ${registryArg}`);
845
+ throw new Error(`npm publication was rejected: ${registryArg}`);
799
846
  };
800
847
 
801
848
  const requireTsdocker = (
@@ -1691,11 +1738,7 @@ export const executeReleasePublication = async (
1691
1738
  // Success still requires every package/registry cell to verify exactly.
1692
1739
  if (hasReleasePackages(journal)) {
1693
1740
  for (const registry of journal.npm.registries) {
1694
- if (
1695
- registry.state !== "failed" ||
1696
- registry.error !== "verification-inconclusive"
1697
- )
1698
- continue;
1741
+ if (registry.state !== "accepted") continue;
1699
1742
  await optionsArg.ensurePublicationState(expectedRemoteMainOid);
1700
1743
  journal = await executeNpmRegistry(
1701
1744
  optionsArg,
@@ -1705,6 +1748,21 @@ export const executeReleasePublication = async (
1705
1748
  );
1706
1749
  }
1707
1750
  }
1751
+ const npmAwaitingAvailability = journal.npm.registries.some(
1752
+ (registryArg) => registryArg.state === "accepted",
1753
+ );
1754
+ if (
1755
+ journal.schemaVersion === 2 &&
1756
+ journal.docker.cleanup.state !== "verified" &&
1757
+ npmAwaitingAvailability
1758
+ ) {
1759
+ // Docker destinations follow verified npm publication, and an accepted
1760
+ // target is neither verified nor failed. Resume continues from here.
1761
+ console.log(
1762
+ "Docker promotion waits for the accepted npm target to become readable.",
1763
+ );
1764
+ return journal;
1765
+ }
1708
1766
  if (
1709
1767
  journal.schemaVersion === 2 &&
1710
1768
  journal.docker.cleanup.state !== "verified"
@@ -0,0 +1,261 @@
1
+ import { inferVersionTypeFromPending } from "../helpers.changelog.js";
2
+ import {
3
+ calculateNewVersion,
4
+ type VersionType,
5
+ } from "../mod_commit/mod.helpers.js";
6
+
7
+ export type TReleaseVersionErrorCode =
8
+ | "malformed-version-floor"
9
+ | "unsupported-prerelease-floor"
10
+ | "noncanonical-version"
11
+ | "current-version-changed";
12
+
13
+ export class ReleaseVersionError extends Error {
14
+ constructor(
15
+ public readonly code: TReleaseVersionErrorCode,
16
+ messageArg: string,
17
+ ) {
18
+ super(messageArg);
19
+ this.name = "ReleaseVersionError";
20
+ }
21
+ }
22
+
23
+ /**
24
+ * `inert`: the current version already meets the floor, so it can be removed.
25
+ * `satisfied`: the inferred version already meets the floor.
26
+ * `applied`: the floor is higher than the inferred version and becomes the release version.
27
+ */
28
+ export type TReleaseVersionFloorOutcome = "inert" | "satisfied" | "applied";
29
+
30
+ export type TReleaseVersionLevelSource = "pending-changelog" | "flag";
31
+
32
+ export interface IReleaseVersionRequest {
33
+ currentVersion: string;
34
+ pendingChangelog: string;
35
+ /** A `--major`, `--minor` or `--patch` flag; the Pending changelog decides otherwise. */
36
+ levelOverride?: VersionType;
37
+ /** The raw `release.versionFloor` configuration value. */
38
+ versionFloor?: unknown;
39
+ }
40
+
41
+ export interface IReleaseVersionResolution {
42
+ currentVersion: string;
43
+ level: VersionType;
44
+ levelSource: TReleaseVersionLevelSource;
45
+ inferredVersion: string;
46
+ version: string;
47
+ versionFloor: { floor: string; outcome: TReleaseVersionFloorOutcome } | null;
48
+ /** The floor raised the major version above the inferred version, and Pending has no Breaking Changes section. */
49
+ floorRaisesMajorWithoutBreakingChanges: boolean;
50
+ }
51
+
52
+ /** Journaled only when the floor, not the changelog, decided the release version. */
53
+ export interface IReleaseVersionFloorRecord {
54
+ floor: string;
55
+ inferredVersion: string;
56
+ }
57
+
58
+ const canonicalVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
59
+ // The semver.org 2.0.0 grammar. It is consulted only after the canonical form
60
+ // failed, so a match here means prerelease or build metadata.
61
+ const decoratedSemverPattern =
62
+ /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
63
+
64
+ export const isCanonicalReleaseVersion = (valueArg: string): boolean =>
65
+ canonicalVersionPattern.test(valueArg);
66
+
67
+ const parseVersionCore = (valueArg: string): [bigint, bigint, bigint] => {
68
+ const match = canonicalVersionPattern.exec(valueArg);
69
+ if (!match) {
70
+ throw new ReleaseVersionError(
71
+ "noncanonical-version",
72
+ `Release versions must be canonical x.y.z semver, found ${JSON.stringify(valueArg)}.`,
73
+ );
74
+ }
75
+ return [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])];
76
+ };
77
+
78
+ /** Orders two canonical x.y.z versions: negative, zero or positive. */
79
+ export const compareReleaseVersions = (
80
+ leftArg: string,
81
+ rightArg: string,
82
+ ): number => {
83
+ const left = parseVersionCore(leftArg);
84
+ const right = parseVersionCore(rightArg);
85
+ for (let index = 0; index < left.length; index++) {
86
+ if (left[index] !== right[index])
87
+ return left[index] < right[index] ? -1 : 1;
88
+ }
89
+ return 0;
90
+ };
91
+
92
+ const majorOf = (versionArg: string): bigint => parseVersionCore(versionArg)[0];
93
+
94
+ // npm and the version bump arithmetic handle only safe integer components.
95
+ const hasSafeIntegerComponents = (versionArg: string): boolean =>
96
+ versionArg
97
+ .split(".")
98
+ .every((componentArg) => Number.isSafeInteger(Number(componentArg)));
99
+
100
+ /** Validates `release.versionFloor`; absent means no floor. */
101
+ export const parseReleaseVersionFloor = (
102
+ valueArg: unknown,
103
+ ): string | undefined => {
104
+ if (valueArg === undefined) return undefined;
105
+ if (typeof valueArg === "string" && isCanonicalReleaseVersion(valueArg)) {
106
+ if (hasSafeIntegerComponents(valueArg)) return valueArg;
107
+ throw new ReleaseVersionError(
108
+ "malformed-version-floor",
109
+ `release.versionFloor components must not exceed ${Number.MAX_SAFE_INTEGER}, found ${JSON.stringify(valueArg)}.`,
110
+ );
111
+ }
112
+ if (typeof valueArg === "string" && decoratedSemverPattern.test(valueArg)) {
113
+ throw new ReleaseVersionError(
114
+ "unsupported-prerelease-floor",
115
+ `release.versionFloor ${JSON.stringify(valueArg)} carries prerelease or build metadata; GitZone releases only canonical x.y.z versions.`,
116
+ );
117
+ }
118
+ throw new ReleaseVersionError(
119
+ "malformed-version-floor",
120
+ `release.versionFloor must be a canonical x.y.z semver string, found ${JSON.stringify(valueArg)}.`,
121
+ );
122
+ };
123
+
124
+ const decideFloorOutcome = (
125
+ currentVersionArg: string,
126
+ inferredVersionArg: string,
127
+ floorArg: string,
128
+ ): TReleaseVersionFloorOutcome => {
129
+ if (compareReleaseVersions(floorArg, currentVersionArg) <= 0) return "inert";
130
+ if (compareReleaseVersions(floorArg, inferredVersionArg) <= 0) {
131
+ return "satisfied";
132
+ }
133
+ return "applied";
134
+ };
135
+
136
+ /**
137
+ * The only place that decides the next release version: the level-inferred
138
+ * version, raised to `release.versionFloor` when the floor is higher.
139
+ */
140
+ export const resolveReleaseVersion = (
141
+ requestArg: IReleaseVersionRequest,
142
+ ): IReleaseVersionResolution => {
143
+ const pendingLevel = inferVersionTypeFromPending(requestArg.pendingChangelog);
144
+ const level = requestArg.levelOverride ?? pendingLevel;
145
+ const inferredVersion = calculateNewVersion(requestArg.currentVersion, level);
146
+ const levelSource: TReleaseVersionLevelSource = requestArg.levelOverride
147
+ ? "flag"
148
+ : "pending-changelog";
149
+ const unfloored = {
150
+ currentVersion: requestArg.currentVersion,
151
+ level,
152
+ levelSource,
153
+ inferredVersion,
154
+ };
155
+ const floor = parseReleaseVersionFloor(requestArg.versionFloor);
156
+ if (floor === undefined) {
157
+ return {
158
+ ...unfloored,
159
+ version: inferredVersion,
160
+ versionFloor: null,
161
+ floorRaisesMajorWithoutBreakingChanges: false,
162
+ };
163
+ }
164
+ if (!isCanonicalReleaseVersion(requestArg.currentVersion)) {
165
+ throw new ReleaseVersionError(
166
+ "noncanonical-version",
167
+ `release.versionFloor needs a canonical x.y.z current version to compare against, found ${JSON.stringify(requestArg.currentVersion)}.`,
168
+ );
169
+ }
170
+ const outcome = decideFloorOutcome(
171
+ requestArg.currentVersion,
172
+ inferredVersion,
173
+ floor,
174
+ );
175
+ const version = outcome === "applied" ? floor : inferredVersion;
176
+ return {
177
+ ...unfloored,
178
+ version,
179
+ versionFloor: { floor, outcome },
180
+ floorRaisesMajorWithoutBreakingChanges:
181
+ outcome === "applied" &&
182
+ majorOf(version) > majorOf(inferredVersion) &&
183
+ pendingLevel !== "major",
184
+ };
185
+ };
186
+
187
+ /**
188
+ * The version files must still hold the version the release was resolved
189
+ * from; otherwise the resolved version no longer follows from the checkout.
190
+ */
191
+ export const assertResolvedCurrentVersion = (
192
+ resolutionArg: IReleaseVersionResolution,
193
+ checkoutVersionArg: string,
194
+ ): void => {
195
+ if (checkoutVersionArg !== resolutionArg.currentVersion) {
196
+ throw new ReleaseVersionError(
197
+ "current-version-changed",
198
+ `The release checkout carries version ${checkoutVersionArg}, but v${resolutionArg.version} was resolved from ${resolutionArg.currentVersion}.`,
199
+ );
200
+ }
201
+ };
202
+
203
+ const createVersionFloorRecord = (
204
+ resolutionArg: IReleaseVersionResolution,
205
+ floorArg: string,
206
+ ): IReleaseVersionFloorRecord => ({
207
+ floor: floorArg,
208
+ inferredVersion: resolutionArg.inferredVersion,
209
+ });
210
+
211
+ export const toReleaseVersionFloorRecord = (
212
+ resolutionArg: IReleaseVersionResolution,
213
+ ): IReleaseVersionFloorRecord | undefined =>
214
+ resolutionArg.versionFloor?.outcome === "applied"
215
+ ? createVersionFloorRecord(resolutionArg, resolutionArg.versionFloor.floor)
216
+ : undefined;
217
+
218
+ /** Shared wording for the plan and the journal summary. */
219
+ export const describeAppliedVersionFloor = (
220
+ recordArg: IReleaseVersionFloorRecord,
221
+ versionArg: string,
222
+ ): string =>
223
+ `version floor: ${recordArg.floor} applied (inferred ${recordArg.inferredVersion} -> release ${versionArg})`;
224
+
225
+ const describeVersionFloor = (
226
+ resolutionArg: IReleaseVersionResolution,
227
+ ): string[] => {
228
+ const decision = resolutionArg.versionFloor;
229
+ if (!decision) return [];
230
+ switch (decision.outcome) {
231
+ case "inert":
232
+ return [
233
+ `version floor: ${decision.floor} inert (current ${resolutionArg.currentVersion} already meets it); remove release.versionFloor`,
234
+ ];
235
+ case "satisfied":
236
+ return [
237
+ `version floor: ${decision.floor} satisfied by inferred ${resolutionArg.inferredVersion}`,
238
+ ];
239
+ case "applied":
240
+ return [
241
+ describeAppliedVersionFloor(
242
+ createVersionFloorRecord(resolutionArg, decision.floor),
243
+ resolutionArg.version,
244
+ ),
245
+ ...(resolutionArg.floorRaisesMajorWithoutBreakingChanges
246
+ ? [
247
+ `version notice: the floor raises the major version above inferred ${resolutionArg.inferredVersion}, and Pending has no "### Breaking Changes" section`,
248
+ ]
249
+ : []),
250
+ ];
251
+ }
252
+ };
253
+
254
+ /** Plan lines that explain where the release version comes from. */
255
+ export const describeReleaseVersion = (
256
+ resolutionArg: IReleaseVersionResolution,
257
+ ): string[] => [
258
+ `version: ${resolutionArg.currentVersion} -> ${resolutionArg.version}`,
259
+ `version level: ${resolutionArg.level} (${resolutionArg.levelSource === "flag" ? `--${resolutionArg.level}` : "Pending changelog"})`,
260
+ ...describeVersionFloor(resolutionArg),
261
+ ];