@git.zone/cli 7.2.6 → 7.2.7

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.
@@ -0,0 +1,147 @@
1
+ import * as plugins from "./mod.plugins.js";
2
+ import { describeCommandFailure } from "./helpers.commandfailure.js";
3
+
4
+ /** Bound of one `git ls-remote` attempt unless `release.targets.git.remoteTimeoutSeconds` sets it. */
5
+ export const defaultReleaseGitRemoteTimeoutSeconds = 180;
6
+ export const maximumReleaseGitRemoteTimeoutSeconds = 3600;
7
+
8
+ /**
9
+ * How long one remote inspection may take and how often a transient failure
10
+ * is retried. Remote inspection only reads refs, so repeating it is safe.
11
+ */
12
+ export interface IReleaseGitRemotePolicy {
13
+ /** Bound of one attempt. */
14
+ timeoutMs: number;
15
+ /** Wait before each retry; its length is the number of retries. */
16
+ retryDelaysMs: readonly number[];
17
+ }
18
+
19
+ /** Two retries, 5 s and 20 s apart: three attempts in all. */
20
+ const defaultRetryDelaysMs: readonly number[] = [5_000, 20_000];
21
+
22
+ export const createReleaseGitRemotePolicy = (
23
+ timeoutSecondsArg: number = defaultReleaseGitRemoteTimeoutSeconds,
24
+ ): IReleaseGitRemotePolicy => ({
25
+ timeoutMs: timeoutSecondsArg * 1000,
26
+ retryDelaysMs: defaultRetryDelaysMs,
27
+ });
28
+
29
+ /** The final attempt of a remote inspection and what it took to get there. */
30
+ export interface IReleaseGitRemoteResult extends plugins.smartshell.IExecResult {
31
+ attempts: number;
32
+ elapsedMs: number;
33
+ /** The final failure is one a later attempt could have overcome. */
34
+ transient: boolean;
35
+ }
36
+
37
+ /**
38
+ * A dropped or refused connection, or a gateway that gave up on a busy
39
+ * server, can succeed on the next attempt. Anything that names credentials,
40
+ * permissions or a missing repository cannot, so it is never retried.
41
+ */
42
+ const transientTransportPattern =
43
+ /connection reset|reset by peer|ECONNRESET|early EOF|unexpected disconnect|remote end hung up unexpectedly|connection timed out|operation timed out|connection closed by|kex_exchange_identification|broken pipe|RPC failed|returned error: 50[234]\b/i;
44
+ const permanentTransportPattern =
45
+ /authentication failed|permission denied|could not read (?:username|password)|terminal prompts disabled|access denied|returned error: 40[134]\b|repository not found|does not appear to be a git repository|not found/i;
46
+
47
+ export const isTransientGitRemoteFailure = (
48
+ resultArg: plugins.smartshell.IExecResult,
49
+ ): boolean => {
50
+ if (resultArg.exitCode === 0) return false;
51
+ if (resultArg.timedOut) return true;
52
+ return (
53
+ transientTransportPattern.test(resultArg.stderr) &&
54
+ !permanentTransportPattern.test(resultArg.stderr)
55
+ );
56
+ };
57
+
58
+ export interface IRunGitRemoteInspectionOptions {
59
+ smartshell: plugins.smartshell.Smartshell;
60
+ cwd: string;
61
+ /** `ls-remote` arguments, starting with `ls-remote`. */
62
+ args: string[];
63
+ env: NodeJS.ProcessEnv;
64
+ policy: IReleaseGitRemotePolicy;
65
+ }
66
+
67
+ /**
68
+ * Runs one read-only remote inspection under the policy's per-attempt bound,
69
+ * repeating it after a transient failure. The caller decides what the final
70
+ * answer means; this only makes a slow or flaky remote answer at all.
71
+ */
72
+ export const runGitRemoteInspection = async (
73
+ optionsArg: IRunGitRemoteInspectionOptions,
74
+ ): Promise<IReleaseGitRemoteResult> => {
75
+ const started = Date.now();
76
+ for (let attempt = 1; ; attempt++) {
77
+ const result = await optionsArg.smartshell.execSpawn(
78
+ "git",
79
+ optionsArg.args,
80
+ {
81
+ cwd: optionsArg.cwd,
82
+ env: optionsArg.env,
83
+ silent: true,
84
+ timeout: optionsArg.policy.timeoutMs,
85
+ timeoutKillGraceMs: 5_000,
86
+ },
87
+ );
88
+ const transient = isTransientGitRemoteFailure(result);
89
+ const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
90
+ if (!transient || retryDelayMs === undefined) {
91
+ return {
92
+ ...result,
93
+ attempts: attempt,
94
+ elapsedMs: Date.now() - started,
95
+ transient,
96
+ };
97
+ }
98
+ await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
99
+ }
100
+ };
101
+
102
+ const formatSeconds = (msArg: number): string =>
103
+ `${Number((msArg / 1000).toFixed(1))} s`;
104
+
105
+ /** How the final attempt failed, and how long the inspection kept trying. */
106
+ export const describeGitRemoteFailure = (
107
+ resultArg: IReleaseGitRemoteResult,
108
+ policyArg: IReleaseGitRemotePolicy,
109
+ ): string => {
110
+ const failure = describeCommandFailure(resultArg, {
111
+ command: "git ls-remote",
112
+ timeoutMs: policyArg.timeoutMs,
113
+ });
114
+ return resultArg.attempts > 1
115
+ ? `${failure}; gave up after ${resultArg.attempts} attempts over ${formatSeconds(resultArg.elapsedMs)}`
116
+ : failure;
117
+ };
118
+
119
+ /**
120
+ * A remote inspection that failed. The message names the release step, the
121
+ * per-attempt bound, the attempts and the time spent; it never carries the
122
+ * destination URL, whose userinfo the command failure redacts.
123
+ */
124
+ export class ReleaseGitRemoteError extends Error {
125
+ public readonly step: string;
126
+ public readonly attempts: number;
127
+ public readonly elapsedMs: number;
128
+ public readonly timeoutMs: number;
129
+ public readonly transient: boolean;
130
+
131
+ constructor(
132
+ messageArg: string,
133
+ stepArg: string,
134
+ resultArg: IReleaseGitRemoteResult,
135
+ policyArg: IReleaseGitRemotePolicy,
136
+ ) {
137
+ super(
138
+ `${messageArg} Step: ${stepArg}. ${describeGitRemoteFailure(resultArg, policyArg)}`,
139
+ );
140
+ this.name = "ReleaseGitRemoteError";
141
+ this.step = stepArg;
142
+ this.attempts = resultArg.attempts;
143
+ this.elapsedMs = resultArg.elapsedMs;
144
+ this.timeoutMs = policyArg.timeoutMs;
145
+ this.transient = resultArg.transient;
146
+ }
147
+ }
@@ -3,6 +3,13 @@ import {
3
3
  formatCommandFailure,
4
4
  type IReleaseCommandFailureContext,
5
5
  } from "./helpers.commandfailure.js";
6
+ import {
7
+ ReleaseGitRemoteError,
8
+ createReleaseGitRemotePolicy,
9
+ runGitRemoteInspection,
10
+ type IReleaseGitRemotePolicy,
11
+ type IReleaseGitRemoteResult,
12
+ } from "./helpers.gitremote.js";
6
13
 
7
14
  const mainBranch = "main";
8
15
  const mainBranchRef = `refs/heads/${mainBranch}`;
@@ -27,6 +34,8 @@ export interface IReleaseBranchContext {
27
34
  pushUrl?: string;
28
35
  mergeRequested: boolean;
29
36
  planAncestryVerified: boolean;
37
+ /** Bound and retries of every remote inspection this release makes. */
38
+ gitRemotePolicy: IReleaseGitRemotePolicy;
30
39
  }
31
40
 
32
41
  export interface IIntegratedReleaseBranch {
@@ -44,6 +53,8 @@ export interface IInspectReleaseBranchOptions {
44
53
  pushTags?: boolean;
45
54
  mergeRequested: boolean;
46
55
  planMode: boolean;
56
+ /** Defaults to `release.targets.git.remoteTimeoutSeconds`' default. */
57
+ gitRemotePolicy?: IReleaseGitRemotePolicy;
47
58
  }
48
59
 
49
60
  type TSmartshell = plugins.smartshell.Smartshell;
@@ -475,28 +486,49 @@ const resolvePushUrl = async (
475
486
  export const isAbsentGitOid = (valueArg: string): boolean =>
476
487
  /^(?:0{40}|0{64})$/.test(valueArg);
477
488
 
489
+ /**
490
+ * Reads remote main from the push destination. `stepArg` names the release
491
+ * step in the error, so an unreachable remote says where the release stopped.
492
+ */
478
493
  const resolveRemoteMainOid = async (
479
494
  smartshellArg: TSmartshell,
480
- cwdArg: string,
495
+ contextArg: Pick<IReleaseBranchContext, "sourceCwd" | "gitRemotePolicy">,
481
496
  pushUrlArg: string,
497
+ stepArg: string,
482
498
  readOnlyArg = false,
483
499
  ): Promise<string> => {
484
- const result = await runGit(
485
- smartshellArg,
486
- cwdArg,
487
- ["ls-remote", "--exit-code", pushUrlArg, mainBranchRef],
488
- readOnlyArg,
489
- );
500
+ const inspect = (argsArg: string[]) =>
501
+ runGitRemoteInspection({
502
+ smartshell: smartshellArg,
503
+ cwd: contextArg.sourceCwd,
504
+ args: argsArg,
505
+ env: readOnlyArg ? readOnlyGitEnv : releaseGitEnv,
506
+ policy: contextArg.gitRemotePolicy,
507
+ });
508
+ const remoteFailure = (
509
+ resultArg: IReleaseGitRemoteResult,
510
+ messageArg: string,
511
+ ) =>
512
+ new ReleaseGitRemoteError(
513
+ messageArg,
514
+ stepArg,
515
+ resultArg,
516
+ contextArg.gitRemotePolicy,
517
+ );
518
+ const result = await inspect([
519
+ "ls-remote",
520
+ "--exit-code",
521
+ pushUrlArg,
522
+ mainBranchRef,
523
+ ]);
490
524
  if (result.exitCode === 2 && !result.stdout.trim()) {
491
- const allRefs = requireGitSuccess(
492
- await runGit(
493
- smartshellArg,
494
- cwdArg,
495
- ["ls-remote", pushUrlArg],
496
- readOnlyArg,
497
- ),
498
- "Unable to verify the empty Git push destination.",
499
- );
525
+ const allRefs = await inspect(["ls-remote", pushUrlArg]);
526
+ if (allRefs.exitCode !== 0) {
527
+ throw remoteFailure(
528
+ allRefs,
529
+ "Unable to verify the empty Git push destination.",
530
+ );
531
+ }
500
532
  if (allRefs.stdout.trim()) {
501
533
  throw new Error(
502
534
  "First release requires an empty Git remote; main is missing from a nonempty destination.",
@@ -505,7 +537,7 @@ const resolveRemoteMainOid = async (
505
537
  const format = requireGitSuccess(
506
538
  await runGit(
507
539
  smartshellArg,
508
- cwdArg,
540
+ contextArg.sourceCwd,
509
541
  ["rev-parse", "--show-object-format"],
510
542
  readOnlyArg,
511
543
  ),
@@ -516,10 +548,12 @@ const resolveRemoteMainOid = async (
516
548
  }
517
549
  return "0".repeat(format === "sha256" ? 64 : 40);
518
550
  }
519
- requireGitSuccess(
520
- result,
521
- "Unable to inspect main at the configured Git push destination.",
522
- );
551
+ if (result.exitCode !== 0) {
552
+ throw remoteFailure(
553
+ result,
554
+ "Unable to inspect main at the configured Git push destination.",
555
+ );
556
+ }
523
557
  const match = result.stdout
524
558
  .trim()
525
559
  .match(/^([0-9a-f]{40}|[0-9a-f]{64})\s+refs\/heads\/main$/i);
@@ -776,6 +810,8 @@ export async function inspectReleaseBranch(
776
810
  gitRemote: optionsArg.gitRemote,
777
811
  mergeRequested: optionsArg.mergeRequested,
778
812
  planAncestryVerified: false,
813
+ gitRemotePolicy:
814
+ optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy(),
779
815
  };
780
816
 
781
817
  await verifyNoGitOperation(
@@ -859,8 +895,9 @@ export async function inspectReleaseBranch(
859
895
  );
860
896
  context.remoteMainOid = await resolveRemoteMainOid(
861
897
  optionsArg.smartshell,
862
- optionsArg.cwd,
898
+ context,
863
899
  context.pushUrl,
900
+ "release preflight",
864
901
  true,
865
902
  );
866
903
  if (isAbsentGitOid(context.remoteMainOid)) {
@@ -926,8 +963,9 @@ export async function prepareReleaseIntegration(
926
963
  }
927
964
  const remoteMainOid = await resolveRemoteMainOid(
928
965
  smartshellArg,
929
- contextArg.sourceCwd,
966
+ contextArg,
930
967
  contextArg.pushUrl,
968
+ "release preflight",
931
969
  );
932
970
  if (contextArg.remoteMainOid && remoteMainOid !== contextArg.remoteMainOid) {
933
971
  throw new Error(
@@ -965,8 +1003,9 @@ export async function prepareReleaseIntegration(
965
1003
  );
966
1004
  const verifiedRemoteMainOid = await resolveRemoteMainOid(
967
1005
  smartshellArg,
968
- contextArg.sourceCwd,
1006
+ contextArg,
969
1007
  contextArg.pushUrl,
1008
+ "release preflight",
970
1009
  );
971
1010
  if (verifiedRemoteMainOid !== remoteMainOid) {
972
1011
  throw new Error(
@@ -1033,8 +1072,9 @@ export async function revalidatePreparedReleaseBranch(
1033
1072
  }
1034
1073
  const currentRemoteMainOid = await resolveRemoteMainOid(
1035
1074
  smartshellArg,
1036
- contextArg.sourceCwd,
1075
+ contextArg,
1037
1076
  contextArg.pushUrl,
1077
+ "release preflight after tests",
1038
1078
  );
1039
1079
  if (currentRemoteMainOid !== contextArg.remoteMainOid) {
1040
1080
  throw new Error(
@@ -1139,8 +1179,9 @@ export async function verifyReleaseHistoryRetained(
1139
1179
  }
1140
1180
  const remoteMainOid = await resolveRemoteMainOid(
1141
1181
  smartshellArg,
1142
- contextArg.sourceCwd,
1182
+ contextArg,
1143
1183
  contextArg.pushUrl,
1184
+ "release history check",
1144
1185
  true,
1145
1186
  );
1146
1187
  if (isAbsentGitOid(remoteMainOid)) {
@@ -1209,8 +1250,9 @@ export async function revalidateReleasePublicationState(
1209
1250
  }
1210
1251
  const currentRemoteMainOid = await resolveRemoteMainOid(
1211
1252
  smartshellArg,
1212
- contextArg.sourceCwd,
1253
+ contextArg,
1213
1254
  contextArg.pushUrl,
1255
+ "publication state check",
1214
1256
  );
1215
1257
  if (currentRemoteMainOid !== expectedRemoteMainOidArg) {
1216
1258
  throw new Error(
@@ -1377,8 +1419,9 @@ export async function integrateReleaseBranch(
1377
1419
  }
1378
1420
  const currentRemoteMainOid = await resolveRemoteMainOid(
1379
1421
  smartshellArg,
1380
- contextArg.sourceCwd,
1422
+ contextArg,
1381
1423
  contextArg.pushUrl,
1424
+ "main integration",
1382
1425
  );
1383
1426
  if (currentRemoteMainOid !== contextArg.remoteMainOid) {
1384
1427
  throw new Error(
@@ -1506,8 +1549,9 @@ export async function integrateReleaseBranch(
1506
1549
  try {
1507
1550
  remoteAfterPush = await resolveRemoteMainOid(
1508
1551
  smartshellArg,
1509
- contextArg.sourceCwd,
1552
+ contextArg,
1510
1553
  contextArg.pushUrl,
1554
+ "main integration",
1511
1555
  );
1512
1556
  } catch {
1513
1557
  remoteAfterPush = undefined;
@@ -1542,8 +1586,9 @@ export async function integrateReleaseBranch(
1542
1586
  try {
1543
1587
  pushedRemoteMainOid = await resolveRemoteMainOid(
1544
1588
  smartshellArg,
1545
- contextArg.sourceCwd,
1589
+ contextArg,
1546
1590
  contextArg.pushUrl,
1591
+ "main integration",
1547
1592
  );
1548
1593
  } catch {
1549
1594
  const rollbackState = await rollbackLocalMain(
@@ -20,6 +20,10 @@ import {
20
20
  } from "./helpers.npmartifact.js";
21
21
  import { getReleaseNpmPublicationOrder } from "./helpers.npmpackages.js";
22
22
  import { formatCommandFailure } from "./helpers.commandfailure.js";
23
+ import {
24
+ ReleaseGitRemoteError,
25
+ runGitRemoteInspection,
26
+ } from "./helpers.gitremote.js";
23
27
  import {
24
28
  canonicalReleaseJson,
25
29
  type IReleaseQualificationRequest,
@@ -167,13 +171,27 @@ export const assertPackageReleaseRecovery = async (
167
171
  export const assertRecoveryUnpublished = async (
168
172
  options: IReleasePreparationRecovery,
169
173
  ): Promise<void> => {
170
- const output = await git(options, [
171
- "ls-remote",
172
- options.branch.pushUrl!,
173
- `refs/tags/v${options.version}`,
174
- `refs/tags/v${options.version}^{}`,
175
- ]);
176
- if (output)
174
+ const policy = options.branch.gitRemotePolicy;
175
+ const remoteTags = await runGitRemoteInspection({
176
+ smartshell: options.smartshell,
177
+ cwd: options.branch.sourceCwd,
178
+ args: [
179
+ "ls-remote",
180
+ options.branch.pushUrl!,
181
+ `refs/tags/v${options.version}`,
182
+ `refs/tags/v${options.version}^{}`,
183
+ ],
184
+ env: releaseGitEnv,
185
+ policy,
186
+ });
187
+ if (remoteTags.exitCode !== 0)
188
+ throw new ReleaseGitRemoteError(
189
+ "Unable to inspect the release tag at the configured Git push destination.",
190
+ "release recovery",
191
+ remoteTags,
192
+ policy,
193
+ );
194
+ if (remoteTags.stdout.trim())
177
195
  throw new Error(
178
196
  "Recovery cannot adopt an existing remote release tag. Use its original journal.",
179
197
  );
@@ -37,6 +37,12 @@ import {
37
37
  } from "./helpers.npmartifact.js";
38
38
  import { isAbsentGitOid, releaseGitEnv } from "./helpers.releasebranch.js";
39
39
  import { describeCommandFailure } from "./helpers.commandfailure.js";
40
+ import {
41
+ createReleaseGitRemotePolicy,
42
+ describeGitRemoteFailure,
43
+ runGitRemoteInspection,
44
+ type IReleaseGitRemotePolicy,
45
+ } from "./helpers.gitremote.js";
40
46
  import {
41
47
  TsdockerReleaseCommandError,
42
48
  TsdockerReleaseRequestCleanupError,
@@ -50,7 +56,6 @@ import {
50
56
  type TReleasePromotionEvidence,
51
57
  } from "./helpers.tsdockerprotocol.js";
52
58
 
53
- const gitProbeTimeoutMs = 60_000;
54
59
  const gitPushTimeoutMs = 5 * 60_000;
55
60
 
56
61
  export interface IBuildReleaseGitPushArgsOptions {
@@ -124,6 +129,8 @@ export interface IReleasePublicationOptions {
124
129
  tsdocker?: ITsdockerReleaseClient;
125
130
  /** Transfer bounds for the Gitea client built from the journal's destination. */
126
131
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
132
+ /** Bound and retries of the Git target's remote inspection. */
133
+ gitRemotePolicy?: IReleaseGitRemotePolicy;
127
134
  giteaAssets?: Pick<
128
135
  GiteaAssetsClient,
129
136
  | "preflight"
@@ -314,30 +321,29 @@ const recoverPublishingTarget = async (
314
321
  };
315
322
 
316
323
  const inspectRemoteRelease = async (
317
- smartshellArg: plugins.smartshell.Smartshell,
318
- cwdArg: string,
324
+ optionsArg: IReleasePublicationOptions,
319
325
  destinationArg: string,
320
326
  journalArg: TReleaseJournal,
321
327
  ): Promise<IGitProbeResult> => {
322
328
  const tagRef = `refs/tags/${journalArg.release.tag}`;
323
- const result = await smartshellArg.execSpawn(
324
- "git",
325
- ["ls-remote", destinationArg, "refs/heads/main", tagRef, `${tagRef}^{}`],
326
- {
327
- cwd: cwdArg,
328
- env: releaseGitEnv,
329
- silent: true,
330
- timeout: gitProbeTimeoutMs,
331
- timeoutKillGraceMs: 5_000,
332
- },
333
- );
329
+ const policy = optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy();
330
+ const result = await runGitRemoteInspection({
331
+ smartshell: optionsArg.smartshell,
332
+ cwd: optionsArg.cwd,
333
+ args: [
334
+ "ls-remote",
335
+ destinationArg,
336
+ "refs/heads/main",
337
+ tagRef,
338
+ `${tagRef}^{}`,
339
+ ],
340
+ env: releaseGitEnv,
341
+ policy,
342
+ });
334
343
  if (result.exitCode !== 0) {
335
344
  return {
336
345
  status: "inconclusive",
337
- failure: describeCommandFailure(result, {
338
- command: "git ls-remote",
339
- timeoutMs: gitProbeTimeoutMs,
340
- }),
346
+ failure: `Step: target.git. ${describeGitRemoteFailure(result, policy)}`,
341
347
  };
342
348
  }
343
349
  const refs = new Map<string, string>();
@@ -384,12 +390,7 @@ const executeGitTarget = async (
384
390
  }
385
391
 
386
392
  let journal = journalArg;
387
- let probe = await inspectRemoteRelease(
388
- optionsArg.smartshell,
389
- optionsArg.cwd,
390
- optionsArg.pushUrl,
391
- journal,
392
- );
393
+ let probe = await inspectRemoteRelease(optionsArg, optionsArg.pushUrl, journal);
393
394
  if (journal.git.state === "verified") {
394
395
  if (probe.status === "exact") {
395
396
  await optionsArg.ensurePublicationState(journal.release.mainOid);
@@ -457,12 +458,7 @@ const executeGitTarget = async (
457
458
  "Git release target is in conflict and cannot resume automatically.",
458
459
  );
459
460
  }
460
- probe = await inspectRemoteRelease(
461
- optionsArg.smartshell,
462
- optionsArg.cwd,
463
- optionsArg.pushUrl,
464
- journal,
465
- );
461
+ probe = await inspectRemoteRelease(optionsArg, optionsArg.pushUrl, journal);
466
462
  if (probe.status === "exact") {
467
463
  journal = await markUnclaimedTarget(
468
464
  optionsArg.store,
@@ -523,12 +519,7 @@ const executeGitTarget = async (
523
519
  timeoutKillGraceMs: 5_000,
524
520
  },
525
521
  );
526
- probe = await inspectRemoteRelease(
527
- optionsArg.smartshell,
528
- optionsArg.cwd,
529
- optionsArg.pushUrl,
530
- journal,
531
- );
522
+ probe = await inspectRemoteRelease(optionsArg, optionsArg.pushUrl, journal);
532
523
  if (probe.status === "exact") {
533
524
  journal = await finishPublishingTarget(
534
525
  optionsArg.store,