@git.zone/cli 8.3.1 → 8.4.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.
Files changed (29) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +14 -0
  3. package/dist_ts/helpers.workflow.js +29 -1
  4. package/dist_ts/mod_config/index.js +42 -1
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +95 -9
  7. package/dist_ts/mod_release/helpers.npmartifact.d.ts +80 -7
  8. package/dist_ts/mod_release/helpers.npmartifact.js +276 -41
  9. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  10. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  11. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  12. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  13. package/dist_ts/mod_release/helpers.releasepublication.d.ts +2 -0
  14. package/dist_ts/mod_release/helpers.releasepublication.js +86 -19
  15. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  16. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  17. package/dist_ts/mod_release/index.js +130 -40
  18. package/package.json +3 -3
  19. package/readme.md +123 -7
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/helpers.workflow.ts +54 -0
  22. package/ts/mod_config/index.ts +47 -0
  23. package/ts/mod_release/classes.releasejournal.ts +149 -10
  24. package/ts/mod_release/helpers.npmartifact.ts +450 -37
  25. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  26. package/ts/mod_release/helpers.releaseline.ts +214 -0
  27. package/ts/mod_release/helpers.releasepublication.ts +168 -16
  28. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  29. package/ts/mod_release/index.ts +177 -26
@@ -0,0 +1,214 @@
1
+ import {
2
+ compareReleaseVersions,
3
+ isCanonicalReleaseVersion,
4
+ releaseVersionMajor,
5
+ } from "./helpers.releaseversion.js";
6
+
7
+ /** The branch every release publishes from unless a release line names another. */
8
+ export const mainReleaseBranch = "main";
9
+ /** The npm dist-tag a `main` release carries. */
10
+ export const latestDistTag = "latest";
11
+
12
+ /**
13
+ * A maintenance line: an older major released from its own branch under its
14
+ * own npm dist-tag, so that `latest` never moves. The block is committed on
15
+ * the maintenance branch itself, which makes that branch, and only that
16
+ * branch, a release source.
17
+ */
18
+ export interface IReleaseLine {
19
+ branch: string;
20
+ distTag: string;
21
+ }
22
+
23
+ const isPlainObject = (
24
+ valueArg: unknown,
25
+ ): valueArg is Record<string, unknown> =>
26
+ typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
27
+
28
+ /**
29
+ * A branch name `git check-ref-format --branch` accepts, restricted to a
30
+ * portable character set. `main` and `HEAD` are never maintenance lines.
31
+ */
32
+ export const isReleaseLineBranchName = (valueArg: unknown): boolean =>
33
+ typeof valueArg === "string" &&
34
+ valueArg.length <= 200 &&
35
+ /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(valueArg) &&
36
+ !valueArg.includes("..") &&
37
+ !valueArg.includes("//") &&
38
+ !valueArg.includes("/.") &&
39
+ !valueArg.endsWith("/") &&
40
+ !valueArg.endsWith(".") &&
41
+ !valueArg.endsWith(".lock") &&
42
+ !valueArg.split("/").some((segmentArg) => segmentArg.endsWith(".lock")) &&
43
+ valueArg !== mainReleaseBranch &&
44
+ valueArg !== "HEAD";
45
+
46
+ /**
47
+ * A dist-tag of lowercase letters and digits joined by single hyphens, which
48
+ * starts with a letter. npm refuses a tag that is a valid semver range; within
49
+ * this alphabet only a bare partial version such as `v4` or `x` is one, so
50
+ * those are refused as well. `latest` belongs to `main`.
51
+ */
52
+ export const isReleaseLineDistTag = (valueArg: unknown): boolean =>
53
+ typeof valueArg === "string" &&
54
+ valueArg.length <= 64 &&
55
+ /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(valueArg) &&
56
+ !/^v*(?:\d+|x)$/.test(valueArg) &&
57
+ valueArg !== latestDistTag;
58
+
59
+ /** Validates `release.line`; absent means the release runs from `main`. */
60
+ export const parseReleaseLine = (
61
+ valueArg: unknown,
62
+ contextArg = "release.line",
63
+ ): IReleaseLine | undefined => {
64
+ if (valueArg === undefined) return undefined;
65
+ if (!isPlainObject(valueArg)) {
66
+ throw new Error(
67
+ `${contextArg} must be an object with "branch" and "distTag".`,
68
+ );
69
+ }
70
+ const keys = Object.keys(valueArg);
71
+ if (
72
+ keys.length !== 2 ||
73
+ !keys.includes("branch") ||
74
+ !keys.includes("distTag")
75
+ ) {
76
+ throw new Error(
77
+ `${contextArg} must contain exactly "branch" and "distTag".`,
78
+ );
79
+ }
80
+ if (!isReleaseLineBranchName(valueArg.branch)) {
81
+ throw new Error(
82
+ `${contextArg}.branch must be a canonical Git branch name other than main, found ${JSON.stringify(valueArg.branch)}.`,
83
+ );
84
+ }
85
+ if (!isReleaseLineDistTag(valueArg.distTag)) {
86
+ throw new Error(
87
+ `${contextArg}.distTag must be lowercase letters and digits joined by hyphens, start with a letter, and be neither "latest" nor a semver range such as "v4", found ${JSON.stringify(valueArg.distTag)}.`,
88
+ );
89
+ }
90
+ return {
91
+ branch: valueArg.branch as string,
92
+ distTag: valueArg.distTag as string,
93
+ };
94
+ };
95
+
96
+ export const getReleaseBranch = (lineArg: IReleaseLine | undefined): string =>
97
+ lineArg ? lineArg.branch : mainReleaseBranch;
98
+
99
+ export const getReleaseDistTag = (lineArg: IReleaseLine | undefined): string =>
100
+ lineArg ? lineArg.distTag : latestDistTag;
101
+
102
+ export const isSameReleaseLine = (
103
+ leftArg: IReleaseLine | undefined,
104
+ rightArg: IReleaseLine | undefined,
105
+ ): boolean =>
106
+ leftArg?.branch === rightArg?.branch && leftArg?.distTag === rightArg?.distTag;
107
+
108
+ /**
109
+ * A maintenance line keeps its major: a breaking change belongs to `main`,
110
+ * and a version of another major would leave the line it is tagged with.
111
+ */
112
+ export const assertReleaseLineVersion = (
113
+ lineArg: IReleaseLine | undefined,
114
+ currentVersionArg: string,
115
+ versionArg: string,
116
+ ): void => {
117
+ if (!lineArg) return;
118
+ if (!isCanonicalReleaseVersion(currentVersionArg)) {
119
+ throw new Error(
120
+ `Release line ${lineArg.distTag} needs a canonical x.y.z current version, found ${JSON.stringify(currentVersionArg)}.`,
121
+ );
122
+ }
123
+ if (releaseVersionMajor(versionArg) !== releaseVersionMajor(currentVersionArg)) {
124
+ throw new Error(
125
+ `Release line ${lineArg.distTag} keeps major ${releaseVersionMajor(currentVersionArg)}, but the release resolved ${currentVersionArg} -> ${versionArg}. ` +
126
+ "A maintenance line never changes its major: remove the Breaking Changes section, --major or release.versionFloor that raised it.",
127
+ );
128
+ }
129
+ };
130
+
131
+ /** Where one package's dist-tags were read. */
132
+ export interface IDistTagSubject {
133
+ packageName: string;
134
+ registry: string;
135
+ version: string;
136
+ distTag: string;
137
+ }
138
+
139
+ const describeDistTagValue = (valueArg: unknown): string =>
140
+ valueArg === undefined ? "absent" : JSON.stringify(valueArg);
141
+
142
+ /**
143
+ * Decides whether publishing `version` under `distTag` is allowed by the
144
+ * registry's current dist-tags; `undefined` means the package does not exist
145
+ * there. Returns why not, or `undefined` when publication may proceed.
146
+ *
147
+ * - `main` (`latest`): a canonical `latest` above the version would move
148
+ * `latest` downwards, so it refuses.
149
+ * - A line: `latest` must already carry a higher major, so the line can never
150
+ * take `latest`, and the line's own tag must not be ahead of the version.
151
+ */
152
+ export const findDistTagPublicationRefusal = (
153
+ distTagsArg: Record<string, unknown> | undefined,
154
+ subjectArg: IDistTagSubject,
155
+ ): string | undefined => {
156
+ const { packageName, registry, version, distTag } = subjectArg;
157
+ const latest = distTagsArg?.[latestDistTag];
158
+ if (distTag === latestDistTag) {
159
+ if (
160
+ typeof latest === "string" &&
161
+ isCanonicalReleaseVersion(latest) &&
162
+ compareReleaseVersions(latest, version) > 0
163
+ ) {
164
+ return (
165
+ `${packageName} at ${registry}: the latest dist-tag points at ${latest}, above ${version}. ` +
166
+ `A main release never moves latest downwards. Release an older major from its maintenance branch with release.line (see "Maintenance lines" in the gitzone readme).`
167
+ );
168
+ }
169
+ return undefined;
170
+ }
171
+ if (
172
+ typeof latest !== "string" ||
173
+ !isCanonicalReleaseVersion(latest) ||
174
+ releaseVersionMajor(latest) <= releaseVersionMajor(version)
175
+ ) {
176
+ return (
177
+ `${packageName} at ${registry}: release line ${distTag} requires the latest dist-tag to carry a higher major than ${version}, but latest is ${describeDistTagValue(latest)}. ` +
178
+ `Publishing could make ${version} the latest version.`
179
+ );
180
+ }
181
+ const lineVersion = distTagsArg?.[distTag];
182
+ if (lineVersion === undefined) return undefined;
183
+ if (
184
+ typeof lineVersion === "string" &&
185
+ isCanonicalReleaseVersion(lineVersion) &&
186
+ compareReleaseVersions(lineVersion, version) <= 0
187
+ ) {
188
+ return undefined;
189
+ }
190
+ return (
191
+ `${packageName} at ${registry}: the ${distTag} dist-tag points at ${describeDistTagValue(lineVersion)}, which is not below ${version}. ` +
192
+ "Publishing would move the release line backwards."
193
+ );
194
+ };
195
+
196
+ /**
197
+ * gitzone never writes dist-tags. When a line release finds `latest` on its
198
+ * own version, it names the command that restores the version `latest`
199
+ * carried when the publication was claimed.
200
+ */
201
+ export const describeLatestMovedConflict = (
202
+ subjectArg: IDistTagSubject,
203
+ observedLatestArg: unknown,
204
+ previousLatestArg: string | undefined,
205
+ ): string => {
206
+ const { packageName, registry, version, distTag } = subjectArg;
207
+ const restore = previousLatestArg
208
+ ? `Restore it with \`pnpm dist-tag add ${packageName}@${previousLatestArg} latest --registry=${registry}\`.`
209
+ : `Restore it with \`pnpm dist-tag add ${packageName}@<the version latest carried before> latest --registry=${registry}\`; this release did not claim the publication, so it recorded no earlier value.`;
210
+ return (
211
+ `${packageName} at ${registry}: release line ${distTag} published ${version}, but the latest dist-tag is ${describeDistTagValue(observedLatestArg)}, no longer a higher major. ` +
212
+ `gitzone does not repair dist-tags. ${restore}`
213
+ );
214
+ };
@@ -11,6 +11,7 @@ import {
11
11
  type TReleaseJournal,
12
12
  type IReleaseJournalV2,
13
13
  type IReleaseJournalV4,
14
+ type IReleaseNpmRegistryJournal,
14
15
  type IReleaseTargetStatus,
15
16
  type TReleaseErrorCode,
16
17
  type TReleaseTargetState,
@@ -29,6 +30,7 @@ import {
29
30
  probeAnonymousNpmArtifact,
30
31
  probeAuthenticatedNpmArtifact,
31
32
  publishNpmArtifact,
33
+ readNpmDistTags,
32
34
  verifyStoredNpmArtifact,
33
35
  waitForAnonymousNpmArtifact,
34
36
  waitForAuthenticatedNpmArtifact,
@@ -38,6 +40,12 @@ import {
38
40
  type INpmArtifactProbeOptions,
39
41
  type INpmArtifactProbeResult,
40
42
  } from "./helpers.npmartifact.js";
43
+ import {
44
+ describeLatestMovedConflict,
45
+ findDistTagPublicationRefusal,
46
+ getReleaseBranch,
47
+ latestDistTag,
48
+ } from "./helpers.releaseline.js";
41
49
  import { isAbsentGitOid, releaseGitEnv } from "./helpers.releasebranch.js";
42
50
  import { describeCommandFailure } from "./helpers.commandfailure.js";
43
51
  import {
@@ -63,6 +71,8 @@ const gitPushTimeoutMs = 5 * 60_000;
63
71
 
64
72
  export interface IBuildReleaseGitPushArgsOptions {
65
73
  destination: string;
74
+ /** `main`, or the branch of the journaled release line. */
75
+ releaseBranch: string;
66
76
  newVersion: string;
67
77
  pushBranch: boolean;
68
78
  pushTags: boolean;
@@ -76,7 +86,7 @@ export function buildReleaseGitPushArgs(
76
86
  ): string[] {
77
87
  const refspecs: string[] = [];
78
88
  if (optionsArg.pushBranch) {
79
- refspecs.push(`${optionsArg.mainOid}:refs/heads/main`);
89
+ refspecs.push(`${optionsArg.mainOid}:refs/heads/${optionsArg.releaseBranch}`);
80
90
  }
81
91
  if (optionsArg.pushTags) {
82
92
  refspecs.push(`${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`);
@@ -87,7 +97,7 @@ export function buildReleaseGitPushArgs(
87
97
  }
88
98
  if (optionsArg.pushBranch && optionsArg.expectedRemoteMainOid) {
89
99
  args.push(
90
- `--force-with-lease=refs/heads/main:${optionsArg.expectedRemoteMainOid}`,
100
+ `--force-with-lease=refs/heads/${optionsArg.releaseBranch}:${optionsArg.expectedRemoteMainOid}`,
91
101
  );
92
102
  }
93
103
  args.push(optionsArg.destination, ...refspecs);
@@ -240,6 +250,8 @@ const claimTarget = async (
240
250
  storeArg: ReleaseJournalStore,
241
251
  journalArg: TReleaseJournal,
242
252
  selectorArg: TReleaseTargetSelector,
253
+ /** A release line records the `latest` version it found, see {@link IReleaseNpmRegistryJournal}. */
254
+ previousLatestArg?: string,
243
255
  ): Promise<TReleaseJournal> =>
244
256
  updateTarget(
245
257
  storeArg,
@@ -252,6 +264,10 @@ const claimTarget = async (
252
264
  statusArg.attempts += 1;
253
265
  statusArg.attempt = createReleaseAttempt();
254
266
  statusArg.error = null;
267
+ if (previousLatestArg !== undefined) {
268
+ (statusArg as IReleaseNpmRegistryJournal).previousLatest =
269
+ previousLatestArg;
270
+ }
255
271
  },
256
272
  );
257
273
 
@@ -329,6 +345,7 @@ const inspectRemoteRelease = async (
329
345
  journalArg: TReleaseJournal,
330
346
  ): Promise<IGitProbeResult> => {
331
347
  const tagRef = `refs/tags/${journalArg.release.tag}`;
348
+ const releaseBranchRef = `refs/heads/${getReleaseBranch(journalArg.release.line)}`;
332
349
  const policy = optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy();
333
350
  const result = await runGitRemoteInspection({
334
351
  smartshell: optionsArg.smartshell,
@@ -336,7 +353,7 @@ const inspectRemoteRelease = async (
336
353
  args: [
337
354
  "ls-remote",
338
355
  destinationArg,
339
- "refs/heads/main",
356
+ releaseBranchRef,
340
357
  tagRef,
341
358
  `${tagRef}^{}`,
342
359
  ],
@@ -354,7 +371,7 @@ const inspectRemoteRelease = async (
354
371
  const match = line.trim().match(/^([0-9a-f]{40}|[0-9a-f]{64})\s+(.+)$/);
355
372
  if (match) refs.set(match[2], match[1]);
356
373
  }
357
- const mainOid = refs.get("refs/heads/main");
374
+ const mainOid = refs.get(releaseBranchRef);
358
375
  const tagOid = refs.get(tagRef);
359
376
  const tagCommitOid = refs.get(`${tagRef}^{}`);
360
377
  // A published release is identified by its annotated tag. Main carrying
@@ -508,6 +525,7 @@ const executeGitTarget = async (
508
525
  "git",
509
526
  buildReleaseGitPushArgs({
510
527
  destination: optionsArg.pushUrl,
528
+ releaseBranch: getReleaseBranch(journal.release.line),
511
529
  newVersion: journal.release.version,
512
530
  pushBranch: true,
513
531
  pushTags: true,
@@ -668,6 +686,46 @@ const assertNpmProbeAuthenticated = (
668
686
  }
669
687
  };
670
688
 
689
+ /** A line that found `latest` on its own version is a dist-tag conflict, not a byte conflict. */
690
+ const npmConflictCode = (
691
+ probeArg: INpmArtifactProbeResult,
692
+ ): TReleaseErrorCode =>
693
+ probeArg.code === "dist-tag-conflict"
694
+ ? "dist-tag-conflict"
695
+ : "artifact-conflict";
696
+
697
+ /**
698
+ * The error a conflicting probe ends the run with. A dist-tag conflict names
699
+ * the command that restores `latest`; gitzone never writes dist-tags itself.
700
+ */
701
+ const npmConflictError = (
702
+ journalArg: TReleaseJournal,
703
+ selectorArg: Extract<TReleaseTargetSelector, { kind: "npm" }>,
704
+ probeArg: INpmArtifactProbeResult,
705
+ byteConflictMessageArg: string,
706
+ ): Error => {
707
+ if (probeArg.code !== "dist-tag-conflict") {
708
+ return new Error(byteConflictMessageArg);
709
+ }
710
+ const registry = getTargetStatus(
711
+ journalArg,
712
+ selectorArg,
713
+ ) as IReleaseNpmRegistryJournal;
714
+ return new Error(
715
+ describeLatestMovedConflict(
716
+ {
717
+ packageName: getReleaseNpmArtifact(journalArg, selectorArg.packageName)
718
+ .packageName,
719
+ registry: selectorArg.registry,
720
+ version: journalArg.release.version,
721
+ distTag: journalArg.npm.tag,
722
+ },
723
+ probeArg.observedLatest,
724
+ registry.previousLatest,
725
+ ),
726
+ );
727
+ };
728
+
671
729
  const markNpmProbeFailure = async (
672
730
  optionsArg: IReleasePublicationOptions,
673
731
  journalArg: TReleaseJournal,
@@ -682,8 +740,70 @@ const markNpmProbeFailure = async (
682
740
  selectorArg,
683
741
  expectedStatesArg,
684
742
  conflict ? "conflict" : "failed",
685
- conflict ? "artifact-conflict" : "verification-inconclusive",
743
+ conflict ? npmConflictCode(probeArg) : "verification-inconclusive",
744
+ );
745
+ };
746
+
747
+ /**
748
+ * Right before a version is published, the registry's dist-tags must still
749
+ * allow it: the guard the release ran in preflight, repeated per package and
750
+ * registry, because a registry can change between the two. A refusal is a
751
+ * terminal dist-tag conflict and nothing is published. A line returns the
752
+ * `latest` version it found, which its claim records.
753
+ */
754
+ const assertNpmDistTagsBeforePublication = async (
755
+ optionsArg: IReleasePublicationOptions,
756
+ journalArg: TReleaseJournal,
757
+ selectorArg: Extract<TReleaseTargetSelector, { kind: "npm" }>,
758
+ ): Promise<string | undefined> => {
759
+ const packageName = getReleaseNpmArtifact(
760
+ journalArg,
761
+ selectorArg.packageName,
762
+ ).packageName;
763
+ const read = await readNpmDistTags(
764
+ journalArg.npm.access,
765
+ {
766
+ smartshell: optionsArg.smartshell,
767
+ cwd: optionsArg.cwd,
768
+ capability: optionsArg.pnpmCapability,
769
+ },
770
+ selectorArg.registry,
771
+ packageName,
772
+ optionsArg.npmProbeOptions,
686
773
  );
774
+ if (read.status === "inconclusive") {
775
+ if (read.code === "authentication-required") {
776
+ throw new NpmRegistryAuthenticationError(
777
+ selectorArg.registry,
778
+ `run \`gitzone release resume ${journalArg.release.version} -y\``,
779
+ read.failure,
780
+ );
781
+ }
782
+ throw new Error(
783
+ `Unable to read the dist-tags of ${packageName} at ${selectorArg.registry} (${read.code}); nothing was published. Run \`gitzone release resume ${journalArg.release.version} -y\` once the registry answers.`,
784
+ );
785
+ }
786
+ const distTags = read.status === "present" ? read.distTags : undefined;
787
+ const refusal = findDistTagPublicationRefusal(distTags, {
788
+ packageName,
789
+ registry: selectorArg.registry,
790
+ version: journalArg.release.version,
791
+ distTag: journalArg.npm.tag,
792
+ });
793
+ if (refusal) {
794
+ await markUnclaimedTarget(
795
+ optionsArg.store,
796
+ journalArg,
797
+ selectorArg,
798
+ ["pending", "failed"],
799
+ "conflict",
800
+ "dist-tag-conflict",
801
+ );
802
+ throw new Error(`${refusal} Nothing was published.`);
803
+ }
804
+ if (journalArg.npm.tag === latestDistTag) return undefined;
805
+ const latest = distTags?.[latestDistTag];
806
+ return typeof latest === "string" ? latest : undefined;
687
807
  };
688
808
 
689
809
  const executeNpmRegistry = async (
@@ -693,7 +813,7 @@ const executeNpmRegistry = async (
693
813
  packageNameArg?: string,
694
814
  deferVerificationArg = false,
695
815
  ): Promise<TReleaseJournal> => {
696
- const selector: TReleaseTargetSelector = {
816
+ const selector: Extract<TReleaseTargetSelector, { kind: "npm" }> = {
697
817
  kind: "npm",
698
818
  registry: registryArg,
699
819
  packageName: packageNameArg,
@@ -721,9 +841,12 @@ const executeNpmRegistry = async (
721
841
  selector,
722
842
  ["verified"],
723
843
  "conflict",
724
- "artifact-conflict",
844
+ npmConflictCode(probe),
725
845
  );
726
- throw new Error(
846
+ throw npmConflictError(
847
+ journal,
848
+ selector,
849
+ probe,
727
850
  `Previously verified npm registry drifted: ${registryArg}`,
728
851
  );
729
852
  }
@@ -747,9 +870,12 @@ const executeNpmRegistry = async (
747
870
  journal,
748
871
  selector,
749
872
  "conflict",
750
- "artifact-conflict",
873
+ npmConflictCode(probe),
751
874
  );
752
- throw new Error(
875
+ throw npmConflictError(
876
+ journal,
877
+ selector,
878
+ probe,
753
879
  `npm registry contains conflicting bytes: ${registryArg}`,
754
880
  );
755
881
  }
@@ -794,9 +920,14 @@ const executeNpmRegistry = async (
794
920
  selector,
795
921
  ["accepted"],
796
922
  "conflict",
797
- "artifact-conflict",
923
+ npmConflictCode(probeArg),
924
+ );
925
+ throw npmConflictError(
926
+ journal,
927
+ selector,
928
+ probeArg,
929
+ `npm registry contains conflicting bytes: ${registryArg}`,
798
930
  );
799
- throw new Error(`npm registry contains conflicting bytes: ${registryArg}`);
800
931
  };
801
932
  const alreadyReadable = await settleAccepted(probe);
802
933
  if (alreadyReadable) return alreadyReadable;
@@ -867,7 +998,12 @@ const executeNpmRegistry = async (
867
998
  ["pending", "failed"],
868
999
  probe,
869
1000
  );
870
- throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
1001
+ throw npmConflictError(
1002
+ journal,
1003
+ selector,
1004
+ probe,
1005
+ `npm registry cannot be verified safely: ${registryArg}`,
1006
+ );
871
1007
  }
872
1008
 
873
1009
  const artifact = getReleaseNpmArtifact(journal, packageNameArg);
@@ -878,13 +1014,24 @@ const executeNpmRegistry = async (
878
1014
  await verifyStoredNpmArtifact(artifactPath, artifact);
879
1015
  // Reject a missing invocation before claiming a potentially publishing target.
880
1016
  buildQualifiedPnpmArgs(optionsArg.pnpmCapability, []);
881
- journal = await claimTarget(optionsArg.store, journal, selector);
1017
+ const previousLatest = await assertNpmDistTagsBeforePublication(
1018
+ optionsArg,
1019
+ journal,
1020
+ selector,
1021
+ );
1022
+ journal = await claimTarget(
1023
+ optionsArg.store,
1024
+ journal,
1025
+ selector,
1026
+ previousLatest,
1027
+ );
882
1028
  const publishResult = await publishNpmArtifact(
883
1029
  optionsArg.smartshell,
884
1030
  optionsArg.cwd,
885
1031
  artifactPath,
886
1032
  registryArg,
887
1033
  optionsArg.pnpmCapability,
1034
+ journal.npm.tag,
888
1035
  journal.npm.access,
889
1036
  artifact.packageName,
890
1037
  );
@@ -911,9 +1058,14 @@ const executeNpmRegistry = async (
911
1058
  journal,
912
1059
  selector,
913
1060
  "conflict",
914
- "artifact-conflict",
1061
+ npmConflictCode(probe),
1062
+ );
1063
+ throw npmConflictError(
1064
+ journal,
1065
+ selector,
1066
+ probe,
1067
+ `npm registry published conflicting bytes: ${registryArg}`,
915
1068
  );
916
- throw new Error(`npm registry published conflicting bytes: ${registryArg}`);
917
1069
  }
918
1070
  if (npmPublishWasAccepted(publishResult)) {
919
1071
  journal = await finishPublishingTarget(
@@ -89,7 +89,11 @@ export const compareReleaseVersions = (
89
89
  return 0;
90
90
  };
91
91
 
92
- const majorOf = (versionArg: string): bigint => parseVersionCore(versionArg)[0];
92
+ /** The major component of a canonical x.y.z version. */
93
+ export const releaseVersionMajor = (versionArg: string): bigint =>
94
+ parseVersionCore(versionArg)[0];
95
+
96
+ const majorOf = releaseVersionMajor;
93
97
 
94
98
  // npm and the version bump arithmetic handle only safe integer components.
95
99
  const hasSafeIntegerComponents = (versionArg: string): boolean =>