@git.zone/cli 8.3.2 → 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 +68 -7
  8. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  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 +302 -22
  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,6 +107,8 @@ 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 {
@@ -192,7 +206,7 @@ const readPackageIdentity = async (
192
206
 
193
207
  const requireHelpFragments = (
194
208
  outputArg: string,
195
- commandArg: "pack" | "publish",
209
+ commandArg: "pack" | "publish" | "view",
196
210
  ): void => {
197
211
  const missing = pnpmHelpRequirements.map((requirements) =>
198
212
  requirements[commandArg].filter(
@@ -420,6 +434,42 @@ export const assertPnpmReleaseCapability = async (
420
434
  return capability;
421
435
  };
422
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
+
423
473
  /**
424
474
  * Development documents must never reach a published tarball.
425
475
  *
@@ -794,6 +844,7 @@ const buildPrivateDestinationArgs = (
794
844
  export const buildPnpmPublishArgs = (
795
845
  artifactPathArg: string,
796
846
  registryArg: string,
847
+ distTagArg: string,
797
848
  accessArg: TReleaseNpmAccess = "public",
798
849
  packageNameArg?: string,
799
850
  ): string[] => [
@@ -805,7 +856,7 @@ export const buildPnpmPublishArgs = (
805
856
  ...buildPrivateDestinationArgs(registryArg, packageNameArg),
806
857
  "--access=restricted",
807
858
  ]),
808
- "--tag=latest",
859
+ `--tag=${distTagArg}`,
809
860
  "--no-git-checks",
810
861
  "--ignore-scripts",
811
862
  "--json",
@@ -817,6 +868,7 @@ export const publishNpmArtifact = async (
817
868
  artifactPathArg: string,
818
869
  registryArg: string,
819
870
  capabilityArg: IPnpmReleaseCapability | undefined,
871
+ distTagArg: string,
820
872
  accessArg: TReleaseNpmAccess = "public",
821
873
  packageNameArg?: string,
822
874
  ): Promise<{ exitCode: number; output: string; failure?: string }> => {
@@ -827,6 +879,7 @@ export const publishNpmArtifact = async (
827
879
  buildPnpmPublishArgs(
828
880
  artifactPathArg,
829
881
  registryArg,
882
+ distTagArg,
830
883
  accessArg,
831
884
  packageNameArg,
832
885
  ),
@@ -1123,6 +1176,68 @@ const getMetadataUrl = (
1123
1176
  );
1124
1177
  };
1125
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
+
1126
1241
  /**
1127
1242
  * The tarball bytes prove the release; the dist-tag only proves provenance.
1128
1243
  * A later release moving the tag on is history, exactly as a `main` that moved
@@ -1139,10 +1254,51 @@ const tagSupersedesVersion = (
1139
1254
  isCanonicalReleaseVersion(versionArg) &&
1140
1255
  compareReleaseVersions(taggedVersionArg, versionArg) > 0;
1141
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
+
1142
1298
  export const probeAnonymousNpmArtifact = async (
1143
1299
  registryArg: string,
1144
1300
  artifactArg: IReleaseArtifact,
1145
- tagArg = "latest",
1301
+ tagArg: string,
1146
1302
  optionsArg: INpmArtifactProbeOptions = {},
1147
1303
  ): Promise<INpmArtifactProbeResult> => {
1148
1304
  const registry = normalizeNpmRegistryUrl(registryArg);
@@ -1223,14 +1379,11 @@ export const probeAnonymousNpmArtifact = async (
1223
1379
  )) as {
1224
1380
  ["dist-tags"]?: Record<string, unknown>;
1225
1381
  };
1226
- const taggedVersion = packageMetadata["dist-tags"]?.[tagArg];
1227
- if (taggedVersion === artifactArg.version) {
1228
- return { status: "exact", code: "exact" };
1229
- }
1230
- if (tagSupersedesVersion(taggedVersion, artifactArg.version)) {
1231
- return { status: "exact", code: "superseded-tag" };
1232
- }
1233
- return { status: "inconclusive", code: "tag-conflict" };
1382
+ return assessPublishedDistTags(
1383
+ readDistTagsField(packageMetadata),
1384
+ artifactArg.version,
1385
+ tagArg,
1386
+ );
1234
1387
  } catch {
1235
1388
  return { status: "inconclusive", code: "network-error" };
1236
1389
  }
@@ -1281,7 +1434,7 @@ const waitForNpmProbe = async (
1281
1434
  export const waitForAnonymousNpmArtifact = async (
1282
1435
  registryArg: string,
1283
1436
  artifactArg: IReleaseArtifact,
1284
- tagArg = "latest",
1437
+ tagArg: string,
1285
1438
  optionsArg: INpmArtifactProbeOptions = {},
1286
1439
  ): Promise<INpmArtifactProbeResult> =>
1287
1440
  waitForNpmProbe(
@@ -1459,6 +1612,59 @@ const readAuthenticatedNpmVersion = async (
1459
1612
  : { status: "inconclusive", code: "registry-response" };
1460
1613
  };
1461
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
+
1462
1668
  /**
1463
1669
  * Verifies a private destination through an authenticated metadata read: the
1464
1670
  * version must exist with the packed artifact's integrity and SHA-1, a
@@ -1471,7 +1677,7 @@ export const probeAuthenticatedNpmArtifact = async (
1471
1677
  readerArg: IAuthenticatedNpmRegistryReader,
1472
1678
  registryArg: string,
1473
1679
  artifactArg: IReleaseArtifact,
1474
- tagArg = "latest",
1680
+ tagArg: string,
1475
1681
  ): Promise<INpmArtifactProbeResult> => {
1476
1682
  const registry = normalizeNpmRegistryUrl(registryArg);
1477
1683
  const read = await readAuthenticatedNpmVersion(
@@ -1522,21 +1728,18 @@ export const probeAuthenticatedNpmArtifact = async (
1522
1728
  ) {
1523
1729
  return { status: "conflict", code: "metadata-conflict" };
1524
1730
  }
1525
- const taggedVersion = metadata["dist-tags"]?.[tagArg];
1526
- if (taggedVersion === artifactArg.version) {
1527
- return { status: "exact", code: "exact" };
1528
- }
1529
- if (tagSupersedesVersion(taggedVersion, artifactArg.version)) {
1530
- return { status: "exact", code: "superseded-tag" };
1531
- }
1532
- return { status: "inconclusive", code: "tag-conflict" };
1731
+ return assessPublishedDistTags(
1732
+ readDistTagsField(metadata),
1733
+ artifactArg.version,
1734
+ tagArg,
1735
+ );
1533
1736
  };
1534
1737
 
1535
1738
  export const waitForAuthenticatedNpmArtifact = async (
1536
1739
  readerArg: IAuthenticatedNpmRegistryReader,
1537
1740
  registryArg: string,
1538
1741
  artifactArg: IReleaseArtifact,
1539
- tagArg = "latest",
1742
+ tagArg: string,
1540
1743
  optionsArg: INpmArtifactProbeOptions = {},
1541
1744
  ): Promise<INpmArtifactProbeResult> =>
1542
1745
  waitForNpmProbe(
@@ -1579,3 +1782,80 @@ export const assertAuthenticatedNpmVersionAbsent = async (
1579
1782
  }).`,
1580
1783
  );
1581
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
+ };