@git.zone/cli 8.3.2 → 8.5.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 (39) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +29 -0
  3. package/dist_ts/helpers.workflow.js +37 -2
  4. package/dist_ts/mod_config/index.js +45 -3
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +108 -13
  7. package/dist_ts/mod_release/helpers.giteaassets.d.ts +47 -1
  8. package/dist_ts/mod_release/helpers.giteaassets.js +236 -56
  9. package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
  10. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  11. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  12. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  13. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  14. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  15. package/dist_ts/mod_release/helpers.releasephase.d.ts +9 -0
  16. package/dist_ts/mod_release/helpers.releasephase.js +25 -0
  17. package/dist_ts/mod_release/helpers.releasepreparation.js +6 -3
  18. package/dist_ts/mod_release/helpers.releasepublication.d.ts +12 -1
  19. package/dist_ts/mod_release/helpers.releasepublication.js +235 -52
  20. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  21. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  22. package/dist_ts/mod_release/index.js +149 -44
  23. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +16 -0
  24. package/package.json +5 -5
  25. package/readme.md +224 -17
  26. package/ts/00_commitinfo_data.ts +1 -1
  27. package/ts/helpers.workflow.ts +87 -0
  28. package/ts/mod_config/index.ts +50 -1
  29. package/ts/mod_release/classes.releasejournal.ts +165 -14
  30. package/ts/mod_release/helpers.giteaassets.ts +319 -64
  31. package/ts/mod_release/helpers.npmartifact.ts +302 -22
  32. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  33. package/ts/mod_release/helpers.releaseline.ts +214 -0
  34. package/ts/mod_release/helpers.releasephase.ts +26 -0
  35. package/ts/mod_release/helpers.releasepreparation.ts +12 -3
  36. package/ts/mod_release/helpers.releasepublication.ts +425 -78
  37. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  38. package/ts/mod_release/index.ts +213 -32
  39. package/ts/mod_release/interfaces.giteaassets.ts +19 -0
@@ -24,6 +24,7 @@ import {
24
24
  import {
25
25
  getDeclaredTsdockerRange,
26
26
  resolveGiteaAssetsConfiguration,
27
+ resolveGiteaAssetConcurrency,
27
28
  resolveGiteaAssetTransferLimits,
28
29
  resolveGitRemoteTimeoutSeconds,
29
30
  resolveNpmVerificationWindowMinutes,
@@ -35,6 +36,7 @@ import {
35
36
  parseReleaseVersionFloor,
36
37
  } from "../mod_release/helpers.releaseversion.js";
37
38
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
39
+ import { parseReleaseLine } from "../mod_release/helpers.releaseline.js";
38
40
 
39
41
  export { ReleaseConfig, CommitConfig };
40
42
 
@@ -305,6 +307,12 @@ async function handleShow(mode: ICliMode): Promise<void> {
305
307
  printConfigSection("Release Workflow", [
306
308
  ["confirmation", formatValue(release.confirmation)],
307
309
  ["version floor", formatValue(release.versionFloor)],
310
+ [
311
+ "release line",
312
+ release.line
313
+ ? `${formatValue(release.line.branch)} -> npm dist-tag ${formatValue(release.line.distTag)}`
314
+ : "main (npm dist-tag latest)",
315
+ ],
308
316
  ["clean tree", "required"],
309
317
  ["run tests", formatValue(release.preflight?.test)],
310
318
  ["run build", formatValue(release.preflight?.build)],
@@ -1913,6 +1921,7 @@ async function validateReleaseConfig(
1913
1921
  }
1914
1922
 
1915
1923
  findings.push(validateReleaseVersionFloor(releaseConfig.versionFloor));
1924
+ findings.push(validateReleaseLine(releaseConfig.line, releaseConfig.targets));
1916
1925
 
1917
1926
  if (
1918
1927
  releaseConfig.registries ||
@@ -1958,9 +1967,10 @@ async function validateReleaseConfig(
1958
1967
  try {
1959
1968
  resolveGiteaAssetsConfiguration(targets.giteaAssets);
1960
1969
  const transfer = resolveGiteaAssetTransferLimits(targets.giteaAssets);
1970
+ const concurrency = resolveGiteaAssetConcurrency(targets.giteaAssets);
1961
1971
  findings.push({
1962
1972
  level: "ok",
1963
- message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s`,
1973
+ message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s each; ${concurrency} run at the same time, so the link must carry ${(concurrency * transfer.minimumBytesPerSecond) / 1024} KiB/s`,
1964
1974
  });
1965
1975
  if (targets.git?.enabled === false || targets.docker?.enabled === true)
1966
1976
  throw new Error(
@@ -2004,6 +2014,45 @@ function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
2004
2014
  }
2005
2015
  }
2006
2016
 
2017
+ function validateReleaseLine(
2018
+ valueArg: unknown,
2019
+ targetsArg: unknown,
2020
+ ): IDoctorFinding {
2021
+ let line: ReturnType<typeof parseReleaseLine>;
2022
+ try {
2023
+ line = parseReleaseLine(valueArg);
2024
+ } catch (error) {
2025
+ return {
2026
+ level: "error",
2027
+ message: error instanceof Error ? error.message : String(error),
2028
+ fix: 'Set release.line to { "branch": "<maintenance branch>", "distTag": "<dist-tag>" } on the maintenance branch, or remove it.',
2029
+ };
2030
+ }
2031
+ if (!line) {
2032
+ return {
2033
+ level: "ok",
2034
+ message: "Release line is not configured; releases run from main under latest",
2035
+ };
2036
+ }
2037
+ const targets = isPlainObject(targetsArg) ? targetsArg : {};
2038
+ const enabled = (["docker", "giteaAssets"] as const).filter(
2039
+ (targetArg) =>
2040
+ isPlainObject(targets[targetArg]) &&
2041
+ (targets[targetArg] as Record<string, unknown>).enabled === true,
2042
+ );
2043
+ if (enabled.length > 0) {
2044
+ return {
2045
+ level: "error",
2046
+ message: `Release line ${line.distTag} publishes only to Git and npm, but ${enabled.join(" and ")} ${enabled.length > 1 ? "are" : "is"} enabled`,
2047
+ fix: `Disable ${enabled.join(" and ")} in release.targets on ${line.branch}.`,
2048
+ };
2049
+ }
2050
+ return {
2051
+ level: "ok",
2052
+ message: `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}`,
2053
+ };
2054
+ }
2055
+
2007
2056
  async function validateAssetsConfig(
2008
2057
  rawAssetsConfig: unknown,
2009
2058
  smartconfigData: Record<string, any>,
@@ -29,8 +29,14 @@ import {
29
29
  import {
30
30
  compareReleaseVersions,
31
31
  isCanonicalReleaseVersion,
32
+ releaseVersionMajor,
32
33
  type IReleaseVersionFloorRecord,
33
34
  } from "./helpers.releaseversion.js";
35
+ import {
36
+ getReleaseDistTag,
37
+ parseReleaseLine,
38
+ type IReleaseLine,
39
+ } from "./helpers.releaseline.js";
34
40
 
35
41
  export const releaseJournalStorageVersion = 1 as const;
36
42
  export const legacyReleaseJournalSchemaVersion = 1 as const;
@@ -66,7 +72,8 @@ export type TReleaseErrorCode =
66
72
  | "artifact-conflict"
67
73
  | "already-published"
68
74
  | "destination-conflict"
69
- | "attempt-recovery-required";
75
+ | "attempt-recovery-required"
76
+ | "dist-tag-conflict";
70
77
 
71
78
  export interface IReleaseAttempt {
72
79
  id: string;
@@ -95,21 +102,34 @@ export interface IReleaseArtifact {
95
102
  export interface IReleaseGitJournal extends IReleaseTargetStatus {
96
103
  remote: string | null;
97
104
  destinationHash: string | null;
105
+ /**
106
+ * The release branch's commit at the destination that the push leases:
107
+ * `main`, or the branch of the journaled release line. The name predates
108
+ * release lines and is kept so that every journal keeps parsing.
109
+ */
98
110
  expectedRemoteMainOid: string | null;
99
111
  }
100
112
 
101
113
  export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
102
114
  registry: string;
103
115
  packageName?: string;
116
+ /**
117
+ * A release line records the `latest` version it found when it claimed the
118
+ * publication, so a line that took `latest` names the exact restore command.
119
+ */
120
+ previousLatest?: string;
104
121
  }
105
122
 
106
123
  export interface IReleaseIdentity {
107
124
  version: string;
108
125
  tag: string;
126
+ /** The release commit, on `main` or on the branch of `line`. */
109
127
  mainOid: string;
110
128
  tagOid: string;
111
129
  /** Present only when release.versionFloor raised the version above the inferred one. */
112
130
  versionFloor?: IReleaseVersionFloorRecord;
131
+ /** Present only for a maintenance line release; absent means `main` and `latest`. */
132
+ line?: IReleaseLine;
113
133
  }
114
134
 
115
135
  export interface IReleaseJournalV1 {
@@ -121,7 +141,8 @@ export interface IReleaseJournalV1 {
121
141
  git: IReleaseGitJournal;
122
142
  npm: {
123
143
  access: TReleaseNpmAccess;
124
- tag: "latest";
144
+ /** `latest`, or the dist-tag of the journaled release line. */
145
+ tag: string;
125
146
  alreadyPublished: "success" | "error";
126
147
  registries: IReleaseNpmRegistryJournal[];
127
148
  };
@@ -163,7 +184,8 @@ export interface IReleaseJournalV2 {
163
184
  git: IReleaseGitJournal;
164
185
  npm: {
165
186
  access: TReleaseNpmAccess;
166
- tag: "latest";
187
+ /** `latest`, or the dist-tag of the journaled release line. */
188
+ tag: string;
167
189
  alreadyPublished: "success" | "error";
168
190
  registries: IReleaseNpmRegistryJournal[];
169
191
  };
@@ -274,6 +296,7 @@ const errorCodes: TReleaseErrorCode[] = [
274
296
  "already-published",
275
297
  "destination-conflict",
276
298
  "attempt-recovery-required",
299
+ "dist-tag-conflict",
277
300
  ];
278
301
 
279
302
  const isPlainObject = (
@@ -606,18 +629,75 @@ const assertVersionFloorRecord = (
606
629
  }
607
630
  };
608
631
 
632
+ const assertReleaseLineRecord = (valueArg: unknown): IReleaseLine => {
633
+ if (!isPlainObject(valueArg)) {
634
+ throw new Error("Release journal release line must be an object.");
635
+ }
636
+ assertExactKeys(
637
+ valueArg,
638
+ ["branch", "distTag"],
639
+ "Release journal release line",
640
+ );
641
+ const line = parseReleaseLine(valueArg, "Release journal release line");
642
+ if (!line) throw new Error("Release journal release line is missing.");
643
+ return line;
644
+ };
645
+
646
+ /**
647
+ * Only a line release claims a publication with the `latest` version it found,
648
+ * and the guard admitted it only with a higher major than the release. The
649
+ * record exists once the publication was claimed.
650
+ */
651
+ const assertPreviousLatest = (
652
+ registryArg: Record<string, unknown>,
653
+ releaseArg: IReleaseIdentity,
654
+ contextArg: string,
655
+ ): void => {
656
+ const previousLatest = registryArg.previousLatest;
657
+ if (
658
+ !releaseArg.line ||
659
+ typeof previousLatest !== "string" ||
660
+ !isCanonicalReleaseVersion(previousLatest) ||
661
+ releaseVersionMajor(previousLatest) <=
662
+ releaseVersionMajor(releaseArg.version) ||
663
+ registryArg.attempts === 0
664
+ ) {
665
+ throw new Error(
666
+ `${contextArg}.previousLatest must record the higher-major latest version a release line found when it claimed the publication.`,
667
+ );
668
+ }
669
+ };
670
+
671
+ /**
672
+ * A release line publishes only to Git and npm: Docker aliases and Gitea's
673
+ * latest release follow their own rules, which a line must not move.
674
+ */
675
+ const assertNoReleaseLine = (
676
+ valueArg: Record<string, unknown>,
677
+ schemaArg: number,
678
+ ): void => {
679
+ if (isPlainObject(valueArg.release) && Object.hasOwn(valueArg.release, "line"))
680
+ throw new Error(
681
+ `Release journal schema ${schemaArg} cannot carry a release line.`,
682
+ );
683
+ };
684
+
609
685
  const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
610
686
  if (!isPlainObject(valueArg)) {
611
687
  throw new Error("Release journal release identity is missing.");
612
688
  }
613
689
  const hasVersionFloor = Object.hasOwn(valueArg, "versionFloor");
690
+ const hasLine = Object.hasOwn(valueArg, "line");
614
691
  assertExactKeys(
615
692
  valueArg,
616
- hasVersionFloor
617
- ? [...releaseIdentityKeys, "versionFloor"]
618
- : releaseIdentityKeys,
693
+ [
694
+ ...releaseIdentityKeys,
695
+ ...(hasVersionFloor ? ["versionFloor"] : []),
696
+ ...(hasLine ? ["line"] : []),
697
+ ],
619
698
  "Release journal release",
620
699
  );
700
+ if (hasLine) assertReleaseLineRecord(valueArg.line);
621
701
  if (
622
702
  typeof valueArg.version !== "string" ||
623
703
  normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
@@ -722,7 +802,7 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
722
802
  );
723
803
  if (
724
804
  (valueArg.npm.access !== "public" && valueArg.npm.access !== "private") ||
725
- valueArg.npm.tag !== "latest" ||
805
+ valueArg.npm.tag !== getReleaseDistTag(release.line) ||
726
806
  (valueArg.npm.alreadyPublished !== "success" &&
727
807
  valueArg.npm.alreadyPublished !== "error") ||
728
808
  !Array.isArray(valueArg.npm.registries)
@@ -738,10 +818,26 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
738
818
  }
739
819
  assertExactKeys(
740
820
  rawRegistry,
741
- ["state", "attempts", "attempt", "error", "registry"],
821
+ [
822
+ "state",
823
+ "attempts",
824
+ "attempt",
825
+ "error",
826
+ "registry",
827
+ ...(Object.hasOwn(rawRegistry, "previousLatest")
828
+ ? ["previousLatest"]
829
+ : []),
830
+ ],
742
831
  `Release journal npm registry ${index}`,
743
832
  );
744
833
  assertTargetStatus(rawRegistry, `Release journal npm registry ${index}`);
834
+ if (Object.hasOwn(rawRegistry, "previousLatest")) {
835
+ assertPreviousLatest(
836
+ rawRegistry,
837
+ release,
838
+ `Release journal npm registry ${index}`,
839
+ );
840
+ }
745
841
  if (
746
842
  typeof rawRegistry.registry !== "string" ||
747
843
  !isCanonicalRegistryUrl(rawRegistry.registry) ||
@@ -1029,6 +1125,7 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1029
1125
  if (!isPlainObject(valueArg)) {
1030
1126
  throw new Error("Release journal root must be a JSON object.");
1031
1127
  }
1128
+ assertNoReleaseLine(valueArg, 2);
1032
1129
  const hasPackages = Object.hasOwn(valueArg, "packages");
1033
1130
  assertExactKeys(
1034
1131
  valueArg,
@@ -1160,7 +1257,17 @@ const assertReleaseJournalV3 = (
1160
1257
  const target = targets[targetOffset++];
1161
1258
  assertExactKeys(
1162
1259
  target,
1163
- ["state", "attempts", "attempt", "error", "registry", "packageName"],
1260
+ [
1261
+ "state",
1262
+ "attempts",
1263
+ "attempt",
1264
+ "error",
1265
+ "registry",
1266
+ "packageName",
1267
+ ...(Object.hasOwn(target, "previousLatest")
1268
+ ? ["previousLatest"]
1269
+ : []),
1270
+ ],
1164
1271
  "Release package target",
1165
1272
  );
1166
1273
  const { packageName, ...registry } = target;
@@ -1249,6 +1356,7 @@ const assertReleaseJournalV3 = (
1249
1356
  const assertReleaseJournalV4 = (
1250
1357
  valueArg: Record<string, unknown>,
1251
1358
  ): IReleaseJournalV4 => {
1359
+ assertNoReleaseLine(valueArg, 4);
1252
1360
  assertExactKeys(
1253
1361
  valueArg,
1254
1362
  [
@@ -1356,12 +1464,23 @@ const assertReleaseJournalV4 = (
1356
1464
  ...journal.giteaAssets.assets,
1357
1465
  ...journal.npm.registries,
1358
1466
  ];
1467
+ // Attachments may publish concurrently, each under its own attempt; any
1468
+ // other target has one owner and never overlaps them.
1469
+ const otherPublishing = [
1470
+ journal.git,
1471
+ journal.giteaAssets.release,
1472
+ ...journal.npm.registries,
1473
+ ].filter((entry) => entry.state === "publishing").length;
1474
+ const assetsPublishing = journal.giteaAssets.assets.filter(
1475
+ (entry) => entry.state === "publishing",
1476
+ ).length;
1359
1477
  if (
1360
1478
  journal.git.state === "skipped" ||
1361
- statuses.filter((entry) => entry.state === "publishing").length > 1
1479
+ otherPublishing > 1 ||
1480
+ (otherPublishing > 0 && assetsPublishing > 0)
1362
1481
  ) {
1363
1482
  throw new Error(
1364
- "Gitea assets require an active Git target and one publication owner.",
1483
+ "Gitea assets require an active Git target and one publication owner outside concurrent attachment uploads.",
1365
1484
  );
1366
1485
  }
1367
1486
  const assetStates = journal.giteaAssets.assets;
@@ -1395,8 +1514,9 @@ const assertReleaseJournalV4 = (
1395
1514
  completed > journal.updatedAt
1396
1515
  )
1397
1516
  throw new Error("Release journal completion state is inconsistent.");
1398
- } else if (isComplete(journal))
1399
- throw new Error("Complete release journal must record completedAt.");
1517
+ }
1518
+ // Every target verified with no completedAt yet: the final verification of
1519
+ // the complete attachment set has not passed, and resume runs it.
1400
1520
  return journal;
1401
1521
  };
1402
1522
 
@@ -1736,6 +1856,28 @@ const assertSchema4AppendOnlyTransition = (
1736
1856
  }
1737
1857
  };
1738
1858
 
1859
+ /**
1860
+ * The `latest` a line found is recorded when it claims a publication and is
1861
+ * never rewritten afterwards, except by the next claim of a failed attempt.
1862
+ */
1863
+ const assertPreviousLatestTransition = (
1864
+ currentArg: TReleaseJournal,
1865
+ nextArg: TReleaseJournal,
1866
+ ): void => {
1867
+ for (const [index, before] of currentArg.npm.registries.entries()) {
1868
+ const after = nextArg.npm.registries[index];
1869
+ if (before.previousLatest === after?.previousLatest) continue;
1870
+ const claims =
1871
+ (before.state === "pending" || before.state === "failed") &&
1872
+ after?.state === "publishing";
1873
+ if (!claims || after.previousLatest === undefined) {
1874
+ throw new Error(
1875
+ "A release line records the latest version it found only when it claims a publication.",
1876
+ );
1877
+ }
1878
+ }
1879
+ };
1880
+
1739
1881
  /** The Git destination state a recorded release leases when it publishes. */
1740
1882
  export interface IReleaseIntentGit {
1741
1883
  remote: string;
@@ -1824,9 +1966,17 @@ export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
1824
1966
  if (valueArg.kind !== releaseIntentKind) {
1825
1967
  throw new Error("Release intent kind is invalid.");
1826
1968
  }
1827
- assertReleaseIdentity(valueArg.release);
1969
+ const release = assertReleaseIdentity(valueArg.release);
1828
1970
  const plan = assertReleaseIntentPlan(valueArg.plan);
1829
1971
  const git = assertReleaseIntentGit(valueArg.git);
1972
+ if (
1973
+ release.line &&
1974
+ (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
1975
+ ) {
1976
+ throw new Error(
1977
+ "A release line publishes only to Git and npm; its intent cannot name Docker or Gitea assets.",
1978
+ );
1979
+ }
1830
1980
  if (plan.targets.includes("git") !== (git !== null)) {
1831
1981
  throw new Error(
1832
1982
  "A release intent records a Git destination exactly when Git is a target.",
@@ -2247,6 +2397,7 @@ export class ReleaseJournalStore {
2247
2397
  }
2248
2398
  if (current.schemaVersion === 4 && next.schemaVersion === 4)
2249
2399
  assertSchema4AppendOnlyTransition(current, next);
2400
+ assertPreviousLatestTransition(current, next);
2250
2401
  await this.writeAtomic(version, next);
2251
2402
  return next;
2252
2403
  });