@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
@@ -12,7 +12,12 @@ import {
12
12
  import {
13
13
  compareReleaseVersions,
14
14
  isCanonicalReleaseVersion,
15
+ releaseVersionMajor,
15
16
  } from "./helpers.releaseversion.js";
17
+ import {
18
+ findDistTagPublicationRefusal,
19
+ latestDistTag,
20
+ } from "./helpers.releaseline.js";
16
21
  import {
17
22
  getDefaultMinimumReleaseAgeMinutes,
18
23
  packageSelectorMatches,
@@ -31,6 +36,7 @@ const pnpmHelpRequirements = [
31
36
  "--tag <tag>",
32
37
  "--access <public|restricted>",
33
38
  ],
39
+ view: ["pnpm view [<package-name>] [<field>[.subfield]...]", "--json"],
34
40
  },
35
41
  {
36
42
  pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
@@ -44,6 +50,11 @@ const pnpmHelpRequirements = [
44
50
  "--access <ACCESS>",
45
51
  "[possible values: public, restricted]",
46
52
  ],
53
+ view: [
54
+ "Usage: pnpm view [OPTIONS] [PARAMS]...",
55
+ "followed by optional fields to print",
56
+ "--json",
57
+ ],
47
58
  },
48
59
  ] as const;
49
60
  const maximumMetadataResponseBytes = 8 * 1024 * 1024;
@@ -87,6 +98,7 @@ export interface INpmArtifactProbeResult {
87
98
  | "superseded-tag"
88
99
  | "tarball-conflict"
89
100
  | "tag-conflict"
101
+ | "dist-tag-conflict"
90
102
  | "registry-response"
91
103
  | "network-error"
92
104
  | "authentication-required";
@@ -95,11 +107,25 @@ export interface INpmArtifactProbeResult {
95
107
  * redacted command diagnostic. Only authenticated probes set it.
96
108
  */
97
109
  failure?: string;
110
+ /** The `latest` value a `dist-tag-conflict` observed. */
111
+ observedLatest?: unknown;
98
112
  }
99
113
 
100
114
  export interface INpmArtifactProbeOptions {
101
115
  fetchImplementation?: typeof fetch;
116
+ /**
117
+ * Bound of one metadata request, and of a tarball request until its
118
+ * response headers arrive. A tarball body is bounded by the two limits below.
119
+ */
102
120
  timeoutMs?: number;
121
+ /** Longest pause between two chunks of a tarball download before it counts as stalled. */
122
+ tarballIdleTimeoutMs?: number;
123
+ /**
124
+ * Slowest average throughput a tarball download may sustain. With the
125
+ * artifact's size it caps the whole download, so a trickle cannot hold a
126
+ * probe open indefinitely.
127
+ */
128
+ tarballMinimumBytesPerSecond?: number;
103
129
  /** Maximum probes of one waiting verification. */
104
130
  attempts?: number;
105
131
  /** First delay between probes; later delays double up to maxDelayMs. */
@@ -180,7 +206,7 @@ const readPackageIdentity = async (
180
206
 
181
207
  const requireHelpFragments = (
182
208
  outputArg: string,
183
- commandArg: "pack" | "publish",
209
+ commandArg: "pack" | "publish" | "view",
184
210
  ): void => {
185
211
  const missing = pnpmHelpRequirements.map((requirements) =>
186
212
  requirements[commandArg].filter(
@@ -408,6 +434,42 @@ export const assertPnpmReleaseCapability = async (
408
434
  return capability;
409
435
  };
410
436
 
437
+ /**
438
+ * A private package's dist-tags are read through `pnpm view <name> dist-tags
439
+ * --json` before it is published, so that command form joins the qualified
440
+ * contract wherever such a read happens.
441
+ */
442
+ export const assertPnpmDistTagReadCapability = async (
443
+ smartshellArg: plugins.smartshell.Smartshell,
444
+ cwdArg: string,
445
+ capabilityArg: IPnpmReleaseCapability,
446
+ ): Promise<void> => {
447
+ const viewHelp = await smartshellArg.execSpawn(
448
+ "pnpm",
449
+ buildQualifiedPnpmArgs(capabilityArg, ["view", "--help"]),
450
+ {
451
+ cwd: cwdArg,
452
+ silent: true,
453
+ timeout: capabilityCommandTimeoutMs,
454
+ timeoutKillGraceMs: 5_000,
455
+ },
456
+ );
457
+ if (viewHelp.exitCode !== 0 || viewHelp.timedOut) {
458
+ throw new Error(
459
+ formatCommandFailure(
460
+ "Unable to inspect pnpm view capabilities.",
461
+ viewHelp,
462
+ {
463
+ command: "pnpm view --help",
464
+ timeoutMs: capabilityCommandTimeoutMs,
465
+ output: "combined",
466
+ },
467
+ ),
468
+ );
469
+ }
470
+ requireHelpFragments(viewHelp.combinedOutput, "view");
471
+ };
472
+
411
473
  /**
412
474
  * Development documents must never reach a published tarball.
413
475
  *
@@ -782,6 +844,7 @@ const buildPrivateDestinationArgs = (
782
844
  export const buildPnpmPublishArgs = (
783
845
  artifactPathArg: string,
784
846
  registryArg: string,
847
+ distTagArg: string,
785
848
  accessArg: TReleaseNpmAccess = "public",
786
849
  packageNameArg?: string,
787
850
  ): string[] => [
@@ -793,7 +856,7 @@ export const buildPnpmPublishArgs = (
793
856
  ...buildPrivateDestinationArgs(registryArg, packageNameArg),
794
857
  "--access=restricted",
795
858
  ]),
796
- "--tag=latest",
859
+ `--tag=${distTagArg}`,
797
860
  "--no-git-checks",
798
861
  "--ignore-scripts",
799
862
  "--json",
@@ -805,6 +868,7 @@ export const publishNpmArtifact = async (
805
868
  artifactPathArg: string,
806
869
  registryArg: string,
807
870
  capabilityArg: IPnpmReleaseCapability | undefined,
871
+ distTagArg: string,
808
872
  accessArg: TReleaseNpmAccess = "public",
809
873
  packageNameArg?: string,
810
874
  ): Promise<{ exitCode: number; output: string; failure?: string }> => {
@@ -815,6 +879,7 @@ export const publishNpmArtifact = async (
815
879
  buildPnpmPublishArgs(
816
880
  artifactPathArg,
817
881
  registryArg,
882
+ distTagArg,
818
883
  accessArg,
819
884
  packageNameArg,
820
885
  ),
@@ -871,19 +936,30 @@ export const npmPublishWasAccepted = (resultArg: {
871
936
  const getFetch = (optionsArg: INpmArtifactProbeOptions): typeof fetch =>
872
937
  optionsArg.fetchImplementation || globalThis.fetch;
873
938
 
939
+ /** Metadata responses are small; their whole request shares one bound. */
940
+ const defaultRegistryRequestTimeoutMs = 10_000;
941
+ /** A tarball download that delivers no bytes for this long has stalled. */
942
+ const defaultTarballIdleTimeoutMs = 30_000;
943
+ /**
944
+ * 256 KiB/s caps a 67 MB tarball (native binaries) at under five minutes,
945
+ * while a registry that serves at least that rate always completes.
946
+ */
947
+ const defaultTarballMinimumBytesPerSecond = 256 * 1024;
948
+
874
949
  const fetchWithoutRedirects = async (
875
950
  urlArg: URL,
876
951
  acceptArg: string,
877
952
  optionsArg: INpmArtifactProbeOptions,
878
- ): Promise<Response> => {
879
- const timeoutMs = optionsArg.timeoutMs ?? 10_000;
880
- return getFetch(optionsArg)(urlArg, {
953
+ signalArg: AbortSignal = AbortSignal.timeout(
954
+ optionsArg.timeoutMs ?? defaultRegistryRequestTimeoutMs,
955
+ ),
956
+ ): Promise<Response> =>
957
+ getFetch(optionsArg)(urlArg, {
881
958
  method: "GET",
882
959
  headers: { accept: acceptArg },
883
960
  redirect: "manual",
884
- signal: AbortSignal.timeout(timeoutMs),
961
+ signal: signalArg,
885
962
  });
886
- };
887
963
 
888
964
  const cancelResponseBody = (responseArg: Response): void => {
889
965
  if (responseArg.body && !responseArg.body.locked) {
@@ -915,10 +991,41 @@ export const assertNpmVersionAbsent = async (
915
991
  }
916
992
  };
917
993
 
994
+ /** Rejects with the signal's reason once it aborts, whatever the source promise does. */
995
+ const unlessAborted = <T>(
996
+ promiseArg: Promise<T>,
997
+ signalArg: AbortSignal,
998
+ ): Promise<T> =>
999
+ new Promise<T>((resolve, reject) => {
1000
+ if (signalArg.aborted) {
1001
+ reject(signalArg.reason);
1002
+ return;
1003
+ }
1004
+ const onAbort = () => reject(signalArg.reason);
1005
+ signalArg.addEventListener("abort", onAbort, { once: true });
1006
+ promiseArg.then(
1007
+ (valueArg) => {
1008
+ signalArg.removeEventListener("abort", onAbort);
1009
+ resolve(valueArg);
1010
+ },
1011
+ (errorArg: unknown) => {
1012
+ signalArg.removeEventListener("abort", onAbort);
1013
+ reject(errorArg);
1014
+ },
1015
+ );
1016
+ });
1017
+
1018
+ /** Lets a caller end a body read and observe its progress. */
1019
+ interface IResponseReadWatch {
1020
+ signal: AbortSignal;
1021
+ onProgress: () => void;
1022
+ }
1023
+
918
1024
  const readBoundedResponse = async (
919
1025
  responseArg: Response,
920
1026
  maximumSizeArg: number,
921
1027
  contextArg: string,
1028
+ watchArg?: IResponseReadWatch,
922
1029
  ): Promise<Buffer> => {
923
1030
  const contentLength = responseArg.headers.get("content-length");
924
1031
  if (
@@ -937,11 +1044,14 @@ const readBoundedResponse = async (
937
1044
  let complete = false;
938
1045
  try {
939
1046
  while (true) {
940
- const item = await reader.read();
1047
+ const item = await (watchArg
1048
+ ? unlessAborted(reader.read(), watchArg.signal)
1049
+ : reader.read());
941
1050
  if (item.done) {
942
1051
  complete = true;
943
1052
  break;
944
1053
  }
1054
+ watchArg?.onProgress();
945
1055
  size += item.value.byteLength;
946
1056
  if (size > maximumSizeArg) {
947
1057
  throw new Error(`${contextArg} exceeds its maximum response size.`);
@@ -973,6 +1083,86 @@ const readBoundedJsonResponse = async (
973
1083
  ).toString("utf8"),
974
1084
  );
975
1085
 
1086
+ interface ITarballDownloadLimits {
1087
+ requestTimeoutMs: number;
1088
+ idleTimeoutMs: number;
1089
+ minimumBytesPerSecond: number;
1090
+ }
1091
+
1092
+ const resolveTarballDownloadLimits = (
1093
+ optionsArg: INpmArtifactProbeOptions,
1094
+ ): ITarballDownloadLimits => {
1095
+ const limits = {
1096
+ requestTimeoutMs: optionsArg.timeoutMs ?? defaultRegistryRequestTimeoutMs,
1097
+ idleTimeoutMs:
1098
+ optionsArg.tarballIdleTimeoutMs ?? defaultTarballIdleTimeoutMs,
1099
+ minimumBytesPerSecond:
1100
+ optionsArg.tarballMinimumBytesPerSecond ??
1101
+ defaultTarballMinimumBytesPerSecond,
1102
+ };
1103
+ if (
1104
+ !Object.values(limits).every(
1105
+ (valueArg) => Number.isFinite(valueArg) && valueArg > 0,
1106
+ )
1107
+ ) {
1108
+ throw new Error("npm tarball downloads require positive finite limits.");
1109
+ }
1110
+ return limits;
1111
+ };
1112
+
1113
+ /**
1114
+ * Downloads a registry tarball of the artifact's size. The response headers
1115
+ * share the metadata bound; the body may take as long as it keeps delivering
1116
+ * bytes, up to the time the artifact's size needs at the minimum throughput.
1117
+ * Returns undefined for a response other than 200; a timeout throws.
1118
+ */
1119
+ const downloadRegistryTarball = async (
1120
+ urlArg: URL,
1121
+ sizeArg: number,
1122
+ optionsArg: INpmArtifactProbeOptions,
1123
+ limitsArg: ITarballDownloadLimits,
1124
+ ): Promise<Buffer | undefined> => {
1125
+ const { requestTimeoutMs, idleTimeoutMs, minimumBytesPerSecond } = limitsArg;
1126
+ const controller = new AbortController();
1127
+ const abortAfter = (msArg: number, reasonArg: string) =>
1128
+ setTimeout(() => controller.abort(new Error(reasonArg)), msArg);
1129
+ const deadline = abortAfter(
1130
+ requestTimeoutMs + Math.ceil((sizeArg / minimumBytesPerSecond) * 1_000),
1131
+ "Registry tarball download exceeded its size-derived time limit.",
1132
+ );
1133
+ let idle = abortAfter(
1134
+ requestTimeoutMs,
1135
+ "Registry tarball response headers did not arrive in time.",
1136
+ );
1137
+ const restartIdle = () => {
1138
+ clearTimeout(idle);
1139
+ idle = abortAfter(idleTimeoutMs, "Registry tarball download stalled.");
1140
+ };
1141
+ try {
1142
+ const response = await unlessAborted(
1143
+ fetchWithoutRedirects(
1144
+ urlArg,
1145
+ "application/octet-stream",
1146
+ optionsArg,
1147
+ controller.signal,
1148
+ ),
1149
+ controller.signal,
1150
+ );
1151
+ if (response.status !== 200) {
1152
+ cancelResponseBody(response);
1153
+ return undefined;
1154
+ }
1155
+ restartIdle();
1156
+ return await readBoundedResponse(response, sizeArg, "Registry tarball", {
1157
+ signal: controller.signal,
1158
+ onProgress: restartIdle,
1159
+ });
1160
+ } finally {
1161
+ clearTimeout(deadline);
1162
+ clearTimeout(idle);
1163
+ }
1164
+ };
1165
+
976
1166
  const getMetadataUrl = (
977
1167
  registryArg: string,
978
1168
  packageNameArg: string,
@@ -986,6 +1176,68 @@ const getMetadataUrl = (
986
1176
  );
987
1177
  };
988
1178
 
1179
+ /** The `dist-tags` object of a registry document, when it carries one. */
1180
+ const readDistTagsField = (
1181
+ metadataArg: unknown,
1182
+ ): Record<string, unknown> | undefined => {
1183
+ if (
1184
+ typeof metadataArg !== "object" ||
1185
+ metadataArg === null ||
1186
+ Array.isArray(metadataArg)
1187
+ ) {
1188
+ return undefined;
1189
+ }
1190
+ const distTags = (metadataArg as { ["dist-tags"]?: unknown })["dist-tags"];
1191
+ return typeof distTags === "object" &&
1192
+ distTags !== null &&
1193
+ !Array.isArray(distTags)
1194
+ ? (distTags as Record<string, unknown>)
1195
+ : undefined;
1196
+ };
1197
+
1198
+ /**
1199
+ * A package's dist-tags before a version is published: `absent` when the
1200
+ * registry does not know the package, which is how a first publication looks.
1201
+ */
1202
+ export type TNpmDistTagsRead =
1203
+ | { status: "present"; distTags: Record<string, unknown> }
1204
+ | { status: "absent" }
1205
+ | {
1206
+ status: "inconclusive";
1207
+ code: "registry-response" | "network-error" | "authentication-required";
1208
+ failure?: string;
1209
+ };
1210
+
1211
+ /** Reads a public package's dist-tags anonymously, as its probe does. */
1212
+ export const readAnonymousNpmDistTags = async (
1213
+ registryArg: string,
1214
+ packageNameArg: string,
1215
+ optionsArg: INpmArtifactProbeOptions = {},
1216
+ ): Promise<TNpmDistTagsRead> => {
1217
+ assertNpmPackageName(packageNameArg);
1218
+ try {
1219
+ const response = await fetchWithoutRedirects(
1220
+ getMetadataUrl(registryArg, packageNameArg),
1221
+ "application/json",
1222
+ optionsArg,
1223
+ );
1224
+ if (response.status === 404) {
1225
+ cancelResponseBody(response);
1226
+ return { status: "absent" };
1227
+ }
1228
+ if (response.status !== 200) {
1229
+ cancelResponseBody(response);
1230
+ return { status: "inconclusive", code: "registry-response" };
1231
+ }
1232
+ const distTags = readDistTagsField(await readBoundedJsonResponse(response));
1233
+ return distTags
1234
+ ? { status: "present", distTags }
1235
+ : { status: "inconclusive", code: "registry-response" };
1236
+ } catch {
1237
+ return { status: "inconclusive", code: "network-error" };
1238
+ }
1239
+ };
1240
+
989
1241
  /**
990
1242
  * The tarball bytes prove the release; the dist-tag only proves provenance.
991
1243
  * A later release moving the tag on is history, exactly as a `main` that moved
@@ -1002,13 +1254,55 @@ const tagSupersedesVersion = (
1002
1254
  isCanonicalReleaseVersion(versionArg) &&
1003
1255
  compareReleaseVersions(taggedVersionArg, versionArg) > 0;
1004
1256
 
1257
+ /**
1258
+ * Reads the dist-tags of a published version. `latest` follows the rule
1259
+ * above. A maintenance line's tag is superseded only by a later version of
1260
+ * its own major, and a line release additionally requires `latest` to still
1261
+ * carry a higher major: a line whose version took `latest` is a terminal
1262
+ * conflict, because the registry now serves it as the newest release.
1263
+ */
1264
+ export const assessPublishedDistTags = (
1265
+ distTagsArg: Record<string, unknown> | undefined,
1266
+ versionArg: string,
1267
+ distTagArg: string,
1268
+ ): INpmArtifactProbeResult => {
1269
+ const taggedVersion = distTagsArg?.[distTagArg];
1270
+ if (distTagArg !== latestDistTag) {
1271
+ const latest = distTagsArg?.[latestDistTag];
1272
+ if (
1273
+ typeof latest !== "string" ||
1274
+ !isCanonicalReleaseVersion(latest) ||
1275
+ releaseVersionMajor(latest) <= releaseVersionMajor(versionArg)
1276
+ ) {
1277
+ return {
1278
+ status: "conflict",
1279
+ code: "dist-tag-conflict",
1280
+ observedLatest: latest,
1281
+ };
1282
+ }
1283
+ }
1284
+ if (taggedVersion === versionArg) {
1285
+ return { status: "exact", code: "exact" };
1286
+ }
1287
+ if (
1288
+ tagSupersedesVersion(taggedVersion, versionArg) &&
1289
+ (distTagArg === latestDistTag ||
1290
+ releaseVersionMajor(taggedVersion as string) ===
1291
+ releaseVersionMajor(versionArg))
1292
+ ) {
1293
+ return { status: "exact", code: "superseded-tag" };
1294
+ }
1295
+ return { status: "inconclusive", code: "tag-conflict" };
1296
+ };
1297
+
1005
1298
  export const probeAnonymousNpmArtifact = async (
1006
1299
  registryArg: string,
1007
1300
  artifactArg: IReleaseArtifact,
1008
- tagArg = "latest",
1301
+ tagArg: string,
1009
1302
  optionsArg: INpmArtifactProbeOptions = {},
1010
1303
  ): Promise<INpmArtifactProbeResult> => {
1011
1304
  const registry = normalizeNpmRegistryUrl(registryArg);
1305
+ const tarballLimits = resolveTarballDownloadLimits(optionsArg);
1012
1306
  try {
1013
1307
  const versionResponse = await fetchWithoutRedirects(
1014
1308
  getMetadataUrl(registry, artifactArg.packageName, artifactArg.version),
@@ -1050,20 +1344,15 @@ export const probeAnonymousNpmArtifact = async (
1050
1344
  ) {
1051
1345
  return { status: "conflict", code: "metadata-conflict" };
1052
1346
  }
1053
- const tarballResponse = await fetchWithoutRedirects(
1347
+ const bytes = await downloadRegistryTarball(
1054
1348
  tarballUrl,
1055
- "application/octet-stream",
1349
+ artifactArg.size,
1056
1350
  optionsArg,
1351
+ tarballLimits,
1057
1352
  );
1058
- if (tarballResponse.status !== 200) {
1059
- cancelResponseBody(tarballResponse);
1353
+ if (!bytes) {
1060
1354
  return { status: "inconclusive", code: "registry-response" };
1061
1355
  }
1062
- const bytes = await readBoundedResponse(
1063
- tarballResponse,
1064
- artifactArg.size,
1065
- "Registry tarball",
1066
- );
1067
1356
  if (
1068
1357
  bytes.byteLength !== artifactArg.size ||
1069
1358
  plugins.crypto.createHash("sha1").update(bytes).digest("hex") !==
@@ -1090,14 +1379,11 @@ export const probeAnonymousNpmArtifact = async (
1090
1379
  )) as {
1091
1380
  ["dist-tags"]?: Record<string, unknown>;
1092
1381
  };
1093
- const taggedVersion = packageMetadata["dist-tags"]?.[tagArg];
1094
- if (taggedVersion === artifactArg.version) {
1095
- return { status: "exact", code: "exact" };
1096
- }
1097
- if (tagSupersedesVersion(taggedVersion, artifactArg.version)) {
1098
- return { status: "exact", code: "superseded-tag" };
1099
- }
1100
- return { status: "inconclusive", code: "tag-conflict" };
1382
+ return assessPublishedDistTags(
1383
+ readDistTagsField(packageMetadata),
1384
+ artifactArg.version,
1385
+ tagArg,
1386
+ );
1101
1387
  } catch {
1102
1388
  return { status: "inconclusive", code: "network-error" };
1103
1389
  }
@@ -1148,7 +1434,7 @@ const waitForNpmProbe = async (
1148
1434
  export const waitForAnonymousNpmArtifact = async (
1149
1435
  registryArg: string,
1150
1436
  artifactArg: IReleaseArtifact,
1151
- tagArg = "latest",
1437
+ tagArg: string,
1152
1438
  optionsArg: INpmArtifactProbeOptions = {},
1153
1439
  ): Promise<INpmArtifactProbeResult> =>
1154
1440
  waitForNpmProbe(
@@ -1326,6 +1612,59 @@ const readAuthenticatedNpmVersion = async (
1326
1612
  : { status: "inconclusive", code: "registry-response" };
1327
1613
  };
1328
1614
 
1615
+ /**
1616
+ * Reads a private package's dist-tags with the registry's configured
1617
+ * authentication through `pnpm view <name> dist-tags --json`, which
1618
+ * {@link assertPnpmDistTagReadCapability} qualifies. A not-found answer proves
1619
+ * absence only when the registry also confirms that authentication.
1620
+ */
1621
+ export const readAuthenticatedNpmDistTags = async (
1622
+ readerArg: IAuthenticatedNpmRegistryReader,
1623
+ registryArg: string,
1624
+ packageNameArg: string,
1625
+ ): Promise<TNpmDistTagsRead> => {
1626
+ const destinationArgs = buildNpmDestinationArgs(registryArg, packageNameArg);
1627
+ const result = await runRegistryRead(readerArg, [
1628
+ "view",
1629
+ packageNameArg,
1630
+ "dist-tags",
1631
+ "--json",
1632
+ ...destinationArgs,
1633
+ ]);
1634
+ if (result.timedOut) {
1635
+ return { status: "inconclusive", code: "network-error" };
1636
+ }
1637
+ let report: unknown;
1638
+ try {
1639
+ report = parseTrailingJsonReport(result.stdout);
1640
+ } catch {
1641
+ report = undefined;
1642
+ }
1643
+ if (result.exitCode === 0) {
1644
+ return typeof report === "object" &&
1645
+ report !== null &&
1646
+ !Array.isArray(report)
1647
+ ? { status: "present", distTags: report as Record<string, unknown> }
1648
+ : { status: "inconclusive", code: "registry-response" };
1649
+ }
1650
+ const authentication = await readNpmRegistryAuthentication(
1651
+ readerArg,
1652
+ registryArg,
1653
+ );
1654
+ if (!authentication.authenticated) {
1655
+ return {
1656
+ status: "inconclusive",
1657
+ code: "authentication-required",
1658
+ failure: authentication.failure,
1659
+ };
1660
+ }
1661
+ const errorCode = (report as { error?: { code?: unknown } } | undefined)
1662
+ ?.error?.code;
1663
+ return typeof errorCode === "string" && npmNotFoundErrorCodes.has(errorCode)
1664
+ ? { status: "absent" }
1665
+ : { status: "inconclusive", code: "registry-response" };
1666
+ };
1667
+
1329
1668
  /**
1330
1669
  * Verifies a private destination through an authenticated metadata read: the
1331
1670
  * version must exist with the packed artifact's integrity and SHA-1, a
@@ -1338,7 +1677,7 @@ export const probeAuthenticatedNpmArtifact = async (
1338
1677
  readerArg: IAuthenticatedNpmRegistryReader,
1339
1678
  registryArg: string,
1340
1679
  artifactArg: IReleaseArtifact,
1341
- tagArg = "latest",
1680
+ tagArg: string,
1342
1681
  ): Promise<INpmArtifactProbeResult> => {
1343
1682
  const registry = normalizeNpmRegistryUrl(registryArg);
1344
1683
  const read = await readAuthenticatedNpmVersion(
@@ -1389,21 +1728,18 @@ export const probeAuthenticatedNpmArtifact = async (
1389
1728
  ) {
1390
1729
  return { status: "conflict", code: "metadata-conflict" };
1391
1730
  }
1392
- const taggedVersion = metadata["dist-tags"]?.[tagArg];
1393
- if (taggedVersion === artifactArg.version) {
1394
- return { status: "exact", code: "exact" };
1395
- }
1396
- if (tagSupersedesVersion(taggedVersion, artifactArg.version)) {
1397
- return { status: "exact", code: "superseded-tag" };
1398
- }
1399
- return { status: "inconclusive", code: "tag-conflict" };
1731
+ return assessPublishedDistTags(
1732
+ readDistTagsField(metadata),
1733
+ artifactArg.version,
1734
+ tagArg,
1735
+ );
1400
1736
  };
1401
1737
 
1402
1738
  export const waitForAuthenticatedNpmArtifact = async (
1403
1739
  readerArg: IAuthenticatedNpmRegistryReader,
1404
1740
  registryArg: string,
1405
1741
  artifactArg: IReleaseArtifact,
1406
- tagArg = "latest",
1742
+ tagArg: string,
1407
1743
  optionsArg: INpmArtifactProbeOptions = {},
1408
1744
  ): Promise<INpmArtifactProbeResult> =>
1409
1745
  waitForNpmProbe(
@@ -1446,3 +1782,80 @@ export const assertAuthenticatedNpmVersionAbsent = async (
1446
1782
  }).`,
1447
1783
  );
1448
1784
  };
1785
+
1786
+ /** Reads one package's dist-tags the way its verification reads the package. */
1787
+ export const readNpmDistTags = (
1788
+ accessArg: TReleaseNpmAccess,
1789
+ readerArg: IAuthenticatedNpmRegistryReader,
1790
+ registryArg: string,
1791
+ packageNameArg: string,
1792
+ probeOptionsArg: INpmArtifactProbeOptions = {},
1793
+ ): Promise<TNpmDistTagsRead> =>
1794
+ accessArg === "private"
1795
+ ? readAuthenticatedNpmDistTags(readerArg, registryArg, packageNameArg)
1796
+ : readAnonymousNpmDistTags(registryArg, packageNameArg, probeOptionsArg);
1797
+
1798
+ export interface INpmDistTagPreflightOptions {
1799
+ reader: IAuthenticatedNpmRegistryReader;
1800
+ access: TReleaseNpmAccess;
1801
+ registries: readonly string[];
1802
+ packageNames: readonly string[];
1803
+ version: string;
1804
+ distTag: string;
1805
+ /** What the operator runs once an authentication failure is fixed. */
1806
+ nextStep: string;
1807
+ probeOptions?: INpmArtifactProbeOptions;
1808
+ }
1809
+
1810
+ /**
1811
+ * Before anything is committed or tagged, every package at every registry
1812
+ * must allow `version` under `distTag`: a `main` release never moves `latest`
1813
+ * downwards, and a line never takes `latest` or moves its own tag backwards.
1814
+ * A registry that cannot be read stops the release as well, because nothing
1815
+ * else proves the dist-tags it would change. A private read needs the
1816
+ * capability the release qualified with {@link assertPnpmDistTagReadCapability}.
1817
+ */
1818
+ export const assertNpmDistTagsAllowPublication = async (
1819
+ optionsArg: INpmDistTagPreflightOptions,
1820
+ ): Promise<void> => {
1821
+ const refusals: string[] = [];
1822
+ for (const packageName of optionsArg.packageNames) {
1823
+ for (const registryArg of optionsArg.registries) {
1824
+ const registry = normalizeNpmRegistryUrl(registryArg);
1825
+ const read = await readNpmDistTags(
1826
+ optionsArg.access,
1827
+ optionsArg.reader,
1828
+ registry,
1829
+ packageName,
1830
+ optionsArg.probeOptions,
1831
+ );
1832
+ if (read.status === "inconclusive") {
1833
+ if (read.code === "authentication-required") {
1834
+ throw new NpmRegistryAuthenticationError(
1835
+ registry,
1836
+ optionsArg.nextStep,
1837
+ read.failure,
1838
+ );
1839
+ }
1840
+ throw new Error(
1841
+ `Unable to read the dist-tags of ${packageName} at ${registry} (${read.code}), so the release cannot prove which dist-tags it changes. Retry once the registry answers.`,
1842
+ );
1843
+ }
1844
+ const refusal = findDistTagPublicationRefusal(
1845
+ read.status === "present" ? read.distTags : undefined,
1846
+ {
1847
+ packageName,
1848
+ registry,
1849
+ version: optionsArg.version,
1850
+ distTag: optionsArg.distTag,
1851
+ },
1852
+ );
1853
+ if (refusal) refusals.push(refusal);
1854
+ }
1855
+ }
1856
+ if (refusals.length > 0) {
1857
+ throw new Error(
1858
+ `The npm dist-tags do not allow this release; nothing was created or published.\n${refusals.join("\n")}`,
1859
+ );
1860
+ }
1861
+ };