@git.zone/cli 6.15.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.
@@ -2,6 +2,7 @@ import { getCliConfigValue } from "./helpers.smartconfig.js";
2
2
  import { getProcessUserArgv } from "./helpers.climode.js";
3
3
  import { shouldCleanTestArtifactsOnRelease } from "./helpers.tstest.js";
4
4
  import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
5
+ import { defaultNpmVerificationWindowMinutes } from "./mod_release/helpers.npmartifact.js";
5
6
 
6
7
  export type TConfirmationMode = "prompt" | "auto" | "plan";
7
8
 
@@ -46,6 +47,8 @@ export interface IReleaseNpmTargetConfig {
46
47
  registries?: string[];
47
48
  accessLevel?: "public" | "private";
48
49
  alreadyPublished?: "success" | "error";
50
+ /** Minutes one accepted upload may stay unreadable before resume takes over. */
51
+ verificationWindowMinutes?: number;
49
52
  }
50
53
 
51
54
  export interface IReleaseGiteaAssetsTargetConfig {
@@ -210,6 +213,7 @@ export interface IResolvedReleaseWorkflow {
210
213
  npmPackageSource: "root" | "tspublish";
211
214
  npmAccessLevel: "public" | "private";
212
215
  npmAlreadyPublished: "success" | "error";
216
+ npmVerificationWindowMinutes: number;
213
217
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
214
218
  dockerEnabled: boolean;
215
219
  dockerEngine: "tsdocker";
@@ -229,6 +233,8 @@ export interface IResolvedReleaseResumeConfiguration {
229
233
  npmRegistries: string[];
230
234
  npmAccessLevel: "public" | "private";
231
235
  npmAlreadyPublished: "success" | "error";
236
+ npmVerificationWindowMinutes: number;
237
+ cleanTestArtifacts: boolean;
232
238
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
233
239
  }
234
240
 
@@ -742,6 +748,24 @@ export const resolveCommitWorkflow = async (
742
748
  };
743
749
  };
744
750
 
751
+ /** One accepted upload may wait this long for the registry to serve it. */
752
+ export const resolveNpmVerificationWindowMinutes = (
753
+ valueArg: unknown,
754
+ ): number => {
755
+ if (valueArg === undefined) return defaultNpmVerificationWindowMinutes;
756
+ if (
757
+ typeof valueArg !== "number" ||
758
+ !Number.isSafeInteger(valueArg) ||
759
+ valueArg < 1 ||
760
+ valueArg > 720
761
+ ) {
762
+ throw new Error(
763
+ "release.targets.npm.verificationWindowMinutes must be a whole number of minutes between 1 and 720",
764
+ );
765
+ }
766
+ return valueArg;
767
+ };
768
+
745
769
  const resolveNpmPackageSource = (valueArg: unknown): "root" | "tspublish" => {
746
770
  if (valueArg === undefined || valueArg === "root") return "root";
747
771
  if (valueArg === "tspublish") return valueArg;
@@ -909,6 +933,9 @@ export const resolveReleaseWorkflow = async (
909
933
  : "root",
910
934
  npmAccessLevel: npmConfig.accessLevel || "public",
911
935
  npmAlreadyPublished: npmConfig.alreadyPublished || "success",
936
+ npmVerificationWindowMinutes: resolveNpmVerificationWindowMinutes(
937
+ npmConfig.verificationWindowMinutes,
938
+ ),
912
939
  ...(giteaAssets ? { giteaAssets } : {}),
913
940
  dockerEnabled,
914
941
  dockerEngine: "tsdocker",
@@ -940,6 +967,7 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
940
967
  let npmRegistries: string[] = [];
941
968
  let npmAccessLevel: "public" | "private" = "public";
942
969
  let npmAlreadyPublished: "success" | "error" = "success";
970
+ let npmVerificationWindowMinutes = defaultNpmVerificationWindowMinutes;
943
971
  if (optionsArg.npm) {
944
972
  if (
945
973
  npmConfig.registries !== undefined &&
@@ -978,6 +1006,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
978
1006
  }
979
1007
  npmAccessLevel = npmConfig.accessLevel || "public";
980
1008
  npmAlreadyPublished = npmConfig.alreadyPublished || "success";
1009
+ npmVerificationWindowMinutes = resolveNpmVerificationWindowMinutes(
1010
+ npmConfig.verificationWindowMinutes,
1011
+ );
981
1012
  }
982
1013
 
983
1014
  return {
@@ -988,6 +1019,8 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
988
1019
  : "root",
989
1020
  npmAccessLevel,
990
1021
  npmAlreadyPublished,
1022
+ npmVerificationWindowMinutes,
1023
+ cleanTestArtifacts: await shouldCleanTestArtifactsOnRelease(process.cwd()),
991
1024
  ...(optionsArg.giteaAssets
992
1025
  ? {
993
1026
  giteaAssets: resolveGiteaAssetsConfiguration(
@@ -22,6 +22,7 @@ import {
22
22
  import {
23
23
  getDeclaredTsdockerRange,
24
24
  resolveGiteaAssetsConfiguration,
25
+ resolveNpmVerificationWindowMinutes,
25
26
  } from "../helpers.workflow.js";
26
27
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
27
28
  import { TsdockerReleaseClient } from "../mod_release/helpers.tsdockerprotocol.js";
@@ -2085,6 +2086,24 @@ async function validateNpmTarget(
2085
2086
  fix: "Use root or tspublish.",
2086
2087
  });
2087
2088
  }
2089
+ try {
2090
+ const windowMinutes = resolveNpmVerificationWindowMinutes(
2091
+ npmTarget.verificationWindowMinutes,
2092
+ );
2093
+ findings.push({
2094
+ level: "ok",
2095
+ message: `npm accepted uploads verify for up to ${windowMinutes} minutes`,
2096
+ });
2097
+ } catch (error) {
2098
+ findings.push({
2099
+ level: "error",
2100
+ message:
2101
+ error instanceof Error
2102
+ ? error.message
2103
+ : "Invalid npm verification window",
2104
+ fix: "Set release.targets.npm.verificationWindowMinutes to a whole number of minutes between 1 and 720 or remove it.",
2105
+ });
2106
+ }
2088
2107
 
2089
2108
  const smartNetwork = new plugins.smartnetwork.SmartNetwork();
2090
2109
  await Promise.all(
@@ -33,8 +33,19 @@ export const releaseJournalSchemaVersion = 2 as const;
33
33
  export const releaseArtifactFileName = "package.tgz" as const;
34
34
  export const releaseJournalFileName = "journal.json" as const;
35
35
 
36
+ /**
37
+ * `accepted` records a destination that took the upload without rejecting it
38
+ * while its read-back is still missing. It is neither a success nor a failure:
39
+ * the bytes are never sent again, and only an exact probe promotes it.
40
+ */
36
41
  export type TReleaseTargetState =
37
- "pending" | "publishing" | "verified" | "failed" | "conflict" | "skipped";
42
+ | "pending"
43
+ | "publishing"
44
+ | "accepted"
45
+ | "verified"
46
+ | "failed"
47
+ | "conflict"
48
+ | "skipped";
38
49
 
39
50
  export type TReleaseErrorCode =
40
51
  | "command-failed"
@@ -228,6 +239,7 @@ const gitRemoteNameRegex = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
228
239
  const targetStates: TReleaseTargetState[] = [
229
240
  "pending",
230
241
  "publishing",
242
+ "accepted",
231
243
  "verified",
232
244
  "failed",
233
245
  "conflict",
@@ -371,12 +383,16 @@ const assertTargetStatus = (
371
383
 
372
384
  if (
373
385
  (valueArg.state === "pending" ||
386
+ valueArg.state === "accepted" ||
374
387
  valueArg.state === "verified" ||
375
388
  valueArg.state === "skipped") &&
376
389
  valueArg.error !== null
377
390
  ) {
378
391
  throw new Error(`${contextArg}.error must be null for ${valueArg.state}.`);
379
392
  }
393
+ if (valueArg.state === "accepted" && (valueArg.attempts as number) < 1) {
394
+ throw new Error(`${contextArg} accepted state requires one attempt.`);
395
+ }
380
396
  if (
381
397
  (valueArg.state === "failed" || valueArg.state === "conflict") &&
382
398
  valueArg.error === null
@@ -455,6 +471,39 @@ const isComplete = (journalArg: TReleaseJournal): boolean => {
455
471
  );
456
472
  };
457
473
 
474
+ /**
475
+ * True when every remaining target only needs verification. Such a resume
476
+ * sends no bytes and mutates no destination, so it may run from a main that
477
+ * already carries later commits.
478
+ */
479
+ export const isVerificationOnlyResume = (
480
+ journalArg: TReleaseJournal,
481
+ ): boolean => {
482
+ const targets: IReleaseTargetStatus[] = [
483
+ journalArg.git,
484
+ ...journalArg.npm.registries,
485
+ ...(journalArg.schemaVersion === 4
486
+ ? [
487
+ journalArg.giteaAssets.release,
488
+ ...journalArg.giteaAssets.assets,
489
+ ]
490
+ : []),
491
+ ...(journalArg.schemaVersion === releaseJournalSchemaVersion
492
+ ? [
493
+ journalArg.docker.qualification,
494
+ ...journalArg.docker.promotions,
495
+ journalArg.docker.cleanup,
496
+ ]
497
+ : []),
498
+ ];
499
+ return (
500
+ targets.some((targetArg) => targetArg.state === "accepted") &&
501
+ targets.every((targetArg) =>
502
+ ["accepted", "verified", "skipped"].includes(targetArg.state),
503
+ )
504
+ );
505
+ };
506
+
458
507
  const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
459
508
  JSON.stringify({
460
509
  schemaVersion: journalArg.schemaVersion,
@@ -1686,11 +1735,15 @@ const assertSchema4AppendOnlyTransition = (
1686
1735
  if (
1687
1736
  after.attempts !== before.attempts ||
1688
1737
  (after.state === "pending" && before.state !== "pending") ||
1738
+ (after.state === "accepted" &&
1739
+ !["publishing", "accepted"].includes(before.state)) ||
1689
1740
  (before.state === "conflict" && after.state !== "conflict") ||
1690
1741
  (before.state === "verified" &&
1691
1742
  !["verified", "conflict"].includes(after.state)) ||
1743
+ (before.state === "accepted" &&
1744
+ !["accepted", "verified", "conflict"].includes(after.state)) ||
1692
1745
  (before.state === "publishing" &&
1693
- !["verified", "failed", "conflict"].includes(after.state))
1746
+ !["accepted", "verified", "failed", "conflict"].includes(after.state))
1694
1747
  ) {
1695
1748
  throw new Error(
1696
1749
  "Release publication status cannot regress or rewrite attempt history.",
@@ -84,10 +84,51 @@ export interface INpmArtifactProbeResult {
84
84
  export interface INpmArtifactProbeOptions {
85
85
  fetchImplementation?: typeof fetch;
86
86
  timeoutMs?: number;
87
+ /** Maximum probes of one waiting verification. */
87
88
  attempts?: number;
89
+ /** First delay between probes; later delays double up to maxDelayMs. */
88
90
  delayMs?: number;
91
+ /** Upper bound of the doubling delay. Defaults to delayMs, which disables backoff. */
92
+ maxDelayMs?: number;
89
93
  }
90
94
 
95
+ /** npmjs usually serves a new version within minutes; an hour has happened. */
96
+ export const defaultNpmVerificationWindowMinutes = 15;
97
+
98
+ const probeDelayForAttempt = (
99
+ attemptArg: number,
100
+ delayMsArg: number,
101
+ maxDelayMsArg: number,
102
+ ): number => Math.min(delayMsArg * 2 ** attemptArg, maxDelayMsArg);
103
+
104
+ /**
105
+ * npm accepts an upload before it serves it. Translate an availability window
106
+ * into the exact probe schedule that covers it under doubling backoff.
107
+ */
108
+ export const planNpmAvailabilityProbes = (
109
+ windowMsArg: number,
110
+ delayMsArg: number,
111
+ maxDelayMsArg: number,
112
+ ): Required<Pick<INpmArtifactProbeOptions, "attempts" | "delayMs" | "maxDelayMs">> => {
113
+ if (
114
+ !Number.isSafeInteger(windowMsArg) ||
115
+ windowMsArg < 0 ||
116
+ !Number.isSafeInteger(delayMsArg) ||
117
+ delayMsArg <= 0 ||
118
+ !Number.isSafeInteger(maxDelayMsArg) ||
119
+ maxDelayMsArg < delayMsArg
120
+ ) {
121
+ throw new Error("npm availability probes require a sane waiting window.");
122
+ }
123
+ let elapsed = 0;
124
+ let attempts = 1;
125
+ while (elapsed < windowMsArg) {
126
+ elapsed += probeDelayForAttempt(attempts - 1, delayMsArg, maxDelayMsArg);
127
+ attempts += 1;
128
+ }
129
+ return { attempts, delayMs: delayMsArg, maxDelayMs: maxDelayMsArg };
130
+ };
131
+
91
132
  const readPackageIdentity = async (
92
133
  cwdArg: string,
93
134
  ): Promise<{ packageName: string; version: string }> => {
@@ -608,6 +649,34 @@ export const publishNpmArtifact = async (
608
649
  return { exitCode: result.exitCode, output: result.combinedOutput };
609
650
  };
610
651
 
652
+ /**
653
+ * A registry answers an upload of a version it already holds with a conflict.
654
+ * npm, pnpm and registry implementations print that conflict as an HTTP 409,
655
+ * as the `E409` or `EPUBLISHCONFLICT` error code, or as the bare sentence, and
656
+ * frequently only one of them. Each signal on its own therefore proves the
657
+ * conflict.
658
+ */
659
+ const npmPublishConflictSignals: RegExp[] = [
660
+ /\b409\b/,
661
+ /e409\b/i,
662
+ /epublishconflict\b/i,
663
+ /cannot publish over (?:the )?previously (?:staged|published) versions?/i,
664
+ ];
665
+
666
+ /**
667
+ * A conflict for the journaled version means the registry already holds it,
668
+ * which npm answers both for a staged and for a served version. The upload was
669
+ * therefore accepted, not rejected. Exact bytes still decide verification.
670
+ */
671
+ export const npmPublishWasAccepted = (resultArg: {
672
+ exitCode: number;
673
+ output: string;
674
+ }): boolean =>
675
+ resultArg.exitCode === 0 ||
676
+ npmPublishConflictSignals.some((signalArg) =>
677
+ signalArg.test(resultArg.output),
678
+ );
679
+
611
680
  const getFetch = (optionsArg: INpmArtifactProbeOptions): typeof fetch =>
612
681
  optionsArg.fetchImplementation || globalThis.fetch;
613
682
 
@@ -831,11 +900,15 @@ export const waitForAnonymousNpmArtifact = async (
831
900
  ): Promise<INpmArtifactProbeResult> => {
832
901
  const attempts = optionsArg.attempts ?? 10;
833
902
  const delayMs = optionsArg.delayMs ?? 1_000;
903
+ const maxDelayMs = optionsArg.maxDelayMs ?? delayMs;
834
904
  if (!Number.isSafeInteger(attempts) || attempts < 1) {
835
905
  throw new Error(
836
906
  "npm verification attempts must be a positive safe integer.",
837
907
  );
838
908
  }
909
+ if (maxDelayMs < delayMs) {
910
+ throw new Error("npm verification backoff cannot fall below its delay.");
911
+ }
839
912
  let lastResult: INpmArtifactProbeResult = {
840
913
  status: "inconclusive",
841
914
  code: "network-error",
@@ -851,7 +924,9 @@ export const waitForAnonymousNpmArtifact = async (
851
924
  return lastResult;
852
925
  }
853
926
  if (attempt + 1 < attempts) {
854
- await plugins.smartdelay.delayFor(delayMs);
927
+ await plugins.smartdelay.delayFor(
928
+ probeDelayForAttempt(attempt, delayMs, maxDelayMs),
929
+ );
855
930
  }
856
931
  }
857
932
  return lastResult;
@@ -1005,6 +1005,120 @@ export async function revalidatePreparedReleaseBranch(
1005
1005
  }
1006
1006
  }
1007
1007
 
1008
+ const verifyCommitContained = async (
1009
+ smartshellArg: TSmartshell,
1010
+ cwdArg: string,
1011
+ ancestorOidArg: string,
1012
+ descendantOidArg: string,
1013
+ messageArg: string,
1014
+ ): Promise<void> => {
1015
+ if (ancestorOidArg === descendantOidArg) return;
1016
+ const result = await runGit(
1017
+ smartshellArg,
1018
+ cwdArg,
1019
+ ["merge-base", "--is-ancestor", ancestorOidArg, descendantOidArg],
1020
+ true,
1021
+ );
1022
+ if (result.exitCode !== 0) throw new Error(messageArg);
1023
+ };
1024
+
1025
+ /**
1026
+ * Containment against the remote tip is only provable with that commit in the
1027
+ * local object store, so a tip this clone has never seen is fetched: by branch
1028
+ * ref, which every server serves, and then by object id for a tip that moved
1029
+ * while it was being read. A tip that stays unavailable leaves remote
1030
+ * containment unproven, which refuses verification instead of skipping it.
1031
+ */
1032
+ const ensureRemoteCommitObject = async (
1033
+ smartshellArg: TSmartshell,
1034
+ cwdArg: string,
1035
+ pushUrlArg: string,
1036
+ remoteMainOidArg: string,
1037
+ ): Promise<void> => {
1038
+ if (await hasCommitObject(smartshellArg, cwdArg, remoteMainOidArg, true)) {
1039
+ return;
1040
+ }
1041
+ for (const fetchTargetArg of [mainBranchRef, remoteMainOidArg]) {
1042
+ await runGit(smartshellArg, cwdArg, [
1043
+ "fetch",
1044
+ "--no-tags",
1045
+ "--no-recurse-submodules",
1046
+ "--no-write-fetch-head",
1047
+ pushUrlArg,
1048
+ fetchTargetArg,
1049
+ ]);
1050
+ if (await hasCommitObject(smartshellArg, cwdArg, remoteMainOidArg, true)) {
1051
+ return;
1052
+ }
1053
+ }
1054
+ throw new Error(
1055
+ `Remote main ${remoteMainOidArg} could not be fetched; remote containment unverified.`,
1056
+ );
1057
+ };
1058
+
1059
+ /**
1060
+ * A verification-only resume publishes nothing, so main may already carry
1061
+ * later commits. The journaled release commit only has to remain part of that
1062
+ * history, locally and on the unchanged remote.
1063
+ */
1064
+ export async function verifyReleaseHistoryRetained(
1065
+ smartshellArg: TSmartshell,
1066
+ contextArg: IReleaseBranchContext,
1067
+ releaseCommitOidArg: string,
1068
+ ): Promise<void> {
1069
+ await verifyNoHistoryOverrides(smartshellArg, contextArg.sourceCwd, true);
1070
+ const localMainOid = await resolveCommit(
1071
+ smartshellArg,
1072
+ contextArg.sourceCwd,
1073
+ mainBranchRef,
1074
+ "A local main branch is required to resume a release.",
1075
+ true,
1076
+ );
1077
+ await verifyCommitContained(
1078
+ smartshellArg,
1079
+ contextArg.sourceCwd,
1080
+ releaseCommitOidArg,
1081
+ localMainOid,
1082
+ "Local main no longer contains the journaled release commit. Restore that history before resuming.",
1083
+ );
1084
+ if (!contextArg.pushUrl) return;
1085
+ const currentPushUrl = await resolvePushUrl(
1086
+ smartshellArg,
1087
+ contextArg.sourceCwd,
1088
+ contextArg.gitRemote,
1089
+ true,
1090
+ );
1091
+ if (currentPushUrl !== contextArg.pushUrl) {
1092
+ throw new Error(
1093
+ "The Git push destination changed before release verification. Restart after reviewing the remote configuration.",
1094
+ );
1095
+ }
1096
+ const remoteMainOid = await resolveRemoteMainOid(
1097
+ smartshellArg,
1098
+ contextArg.sourceCwd,
1099
+ contextArg.pushUrl,
1100
+ true,
1101
+ );
1102
+ if (isAbsentGitOid(remoteMainOid)) {
1103
+ throw new Error(
1104
+ "Remote main no longer exists, so the journaled release history cannot be confirmed.",
1105
+ );
1106
+ }
1107
+ await ensureRemoteCommitObject(
1108
+ smartshellArg,
1109
+ contextArg.sourceCwd,
1110
+ contextArg.pushUrl,
1111
+ remoteMainOid,
1112
+ );
1113
+ await verifyCommitContained(
1114
+ smartshellArg,
1115
+ contextArg.sourceCwd,
1116
+ releaseCommitOidArg,
1117
+ remoteMainOid,
1118
+ "Remote main no longer contains the journaled release commit. Inspect the remote before resuming.",
1119
+ );
1120
+ }
1121
+
1008
1122
  export async function revalidateReleasePublicationState(
1009
1123
  smartshellArg: TSmartshell,
1010
1124
  contextArg: IReleaseBranchContext,