@git.zone/cli 8.7.1 → 8.8.1

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 (32) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.js +9 -8
  3. package/dist_ts/mod_config/index.js +33 -25
  4. package/dist_ts/mod_release/classes.releasejournal.js +12 -8
  5. package/dist_ts/mod_release/helpers.gitremote.d.ts +76 -15
  6. package/dist_ts/mod_release/helpers.gitremote.js +173 -38
  7. package/dist_ts/mod_release/helpers.releasebranch.d.ts +1 -1
  8. package/dist_ts/mod_release/helpers.releasebranch.js +69 -39
  9. package/dist_ts/mod_release/helpers.releaseline.d.ts +12 -3
  10. package/dist_ts/mod_release/helpers.releaseline.js +4 -1
  11. package/dist_ts/mod_release/helpers.releasepreparation.js +6 -6
  12. package/dist_ts/mod_release/helpers.releasepublication.d.ts +2 -2
  13. package/dist_ts/mod_release/helpers.releasepublication.js +41 -29
  14. package/dist_ts/mod_release/helpers.tsdockerprotocol.d.ts +4 -4
  15. package/dist_ts/mod_release/helpers.tsdockerprotocol.js +15 -5
  16. package/dist_ts/mod_release/index.js +43 -8
  17. package/dist_ts/plugins.d.ts +1 -1
  18. package/dist_ts/plugins.js +1 -1
  19. package/package.json +2 -2
  20. package/readme.md +77 -18
  21. package/ts/00_commitinfo_data.ts +1 -1
  22. package/ts/helpers.workflow.ts +8 -9
  23. package/ts/mod_config/index.ts +51 -25
  24. package/ts/mod_release/classes.releasejournal.ts +15 -8
  25. package/ts/mod_release/helpers.gitremote.ts +271 -58
  26. package/ts/mod_release/helpers.releasebranch.ts +107 -56
  27. package/ts/mod_release/helpers.releaseline.ts +22 -3
  28. package/ts/mod_release/helpers.releasepreparation.ts +4 -6
  29. package/ts/mod_release/helpers.releasepublication.ts +42 -30
  30. package/ts/mod_release/helpers.tsdockerprotocol.ts +31 -5
  31. package/ts/mod_release/index.ts +81 -4
  32. package/ts/plugins.ts +2 -0
@@ -1,115 +1,333 @@
1
1
  import * as plugins from "./mod.plugins.js";
2
+ import { logger } from "../gitzone.logging.js";
2
3
  import { describeCommandFailure } from "./helpers.commandfailure.js";
3
4
 
4
5
  /** Bound of one `git ls-remote` attempt unless `release.targets.git.remoteTimeoutSeconds` sets it. */
5
6
  export const defaultReleaseGitRemoteTimeoutSeconds = 180;
6
7
  export const maximumReleaseGitRemoteTimeoutSeconds = 3600;
7
8
 
9
+ /** Bound of one `git fetch` or `git push` attempt, which transfers objects. */
10
+ export const releaseGitTransferTimeoutMs = 5 * 60_000;
11
+
8
12
  /**
9
13
  * 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.
14
+ * is retried.
11
15
  */
12
16
  export interface IReleaseGitRemotePolicy {
13
- /** Bound of one attempt. */
17
+ /** Bound of one `ls-remote` attempt. */
14
18
  timeoutMs: number;
15
19
  /** Wait before each retry; its length is the number of retries. */
16
20
  retryDelaysMs: readonly number[];
17
21
  }
18
22
 
19
- /** Two retries, 5 s and 20 s apart: three attempts in all. */
20
- const defaultRetryDelaysMs: readonly number[] = [5_000, 20_000];
23
+ /**
24
+ * Eight attempts in all, waiting 2, 4, 8 and 16 s and then 30 s three times:
25
+ * two minutes of waiting at most. On 2026-10-05 code.foss.global dropped about
26
+ * two in three ssh connections, so five attempts would still have failed about
27
+ * one step in eight.
28
+ */
29
+ export const releaseGitRemoteRetryDelaysMs: readonly number[] = [
30
+ 2_000, 4_000, 8_000, 16_000, 30_000, 30_000, 30_000,
31
+ ];
32
+
33
+ /** The most waiting any policy may add between the attempts of one step. */
34
+ export const maximumReleaseGitRemoteRetryWaitMs = 180_000;
21
35
 
22
36
  export const createReleaseGitRemotePolicy = (
23
37
  timeoutSecondsArg: number = defaultReleaseGitRemoteTimeoutSeconds,
24
38
  ): IReleaseGitRemotePolicy => ({
25
39
  timeoutMs: timeoutSecondsArg * 1000,
26
- retryDelaysMs: defaultRetryDelaysMs,
40
+ retryDelaysMs: releaseGitRemoteRetryDelaysMs,
27
41
  });
28
42
 
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;
43
+ interface IGitRemoteFailurePattern {
44
+ /** Why the failure is classified as it is; every retry line names it. */
45
+ reason: string;
46
+ pattern: RegExp;
35
47
  }
36
48
 
37
49
  /**
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.
50
+ * Transport failures a later attempt can overcome: the connection dropped,
51
+ * was reset or timed out, or an HTTP gateway gave up on a busy server. Git
52
+ * adds "Could not read from remote repository" to each of them; on its own
53
+ * that line proves nothing and is not listed.
41
54
  */
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;
55
+ const transientGitRemoteFailures: readonly IGitRemoteFailurePattern[] = [
56
+ {
57
+ reason: "ssh connection closed by the remote host",
58
+ pattern: /connection to \S+ closed by remote host|connection closed by/i,
59
+ },
60
+ {
61
+ reason: "connection reset",
62
+ pattern: /connection reset|reset by peer|ECONNRESET/i,
63
+ },
64
+ {
65
+ reason: "connection timed out",
66
+ pattern: /connection timed out|operation timed out|ETIMEDOUT/i,
67
+ },
68
+ { reason: "unexpected disconnect", pattern: /unexpected disconnect/i },
69
+ {
70
+ reason: "remote end hung up",
71
+ pattern: /remote end hung up unexpectedly/i,
72
+ },
73
+ { reason: "early EOF", pattern: /early EOF/i },
74
+ { reason: "broken pipe", pattern: /broken pipe/i },
75
+ {
76
+ reason: "ssh key exchange interrupted",
77
+ pattern: /kex_exchange_identification/i,
78
+ },
79
+ {
80
+ reason: "HTTP transport failure",
81
+ pattern:
82
+ /RPC failed; (?:curl (?:18|52|55|56|92)|HTTP 50[234])\b|returned error: 50[234]\b/i,
83
+ },
84
+ ];
85
+
86
+ /**
87
+ * Failures no retry overcomes. They win over any transport symptom in the
88
+ * same output, so `Authentication failed` followed by `remote end hung up`
89
+ * fails at once.
90
+ */
91
+ const permanentGitRemoteFailures: readonly IGitRemoteFailurePattern[] = [
92
+ {
93
+ reason: "authentication refused",
94
+ pattern:
95
+ /authentication failed|could not read (?:username|password)|terminal prompts disabled|returned error: 401\b/i,
96
+ },
97
+ {
98
+ reason: "permission denied",
99
+ pattern: /permission denied|access denied|returned error: 403\b/i,
100
+ },
101
+ {
102
+ reason: "repository not found",
103
+ pattern:
104
+ /repository not found|does not appear to be a git repository|not found|returned error: 404\b/i,
105
+ },
106
+ {
107
+ reason: "update rejected",
108
+ pattern: /non-fast-forward|\[(?:remote )?rejected\]|stale info|fetch first/i,
109
+ },
110
+ ];
111
+
112
+ export interface IGitRemoteFailureClass {
113
+ /** A later attempt could overcome the failure. */
114
+ transient: boolean;
115
+ reason: string;
116
+ }
117
+
118
+ const formatSeconds = (msArg: number): string =>
119
+ `${Number((msArg / 1000).toFixed(1))} s`;
46
120
 
47
- export const isTransientGitRemoteFailure = (
121
+ /**
122
+ * Classifies a failed remote command. A timeout is transient; a refused
123
+ * credential, a missing repository or a rejected update is not; otherwise only
124
+ * a known transport failure is. Anything unrecognised, including Git's own
125
+ * answers such as `ls-remote --exit-code` finding no ref, is final.
126
+ */
127
+ export const classifyGitRemoteFailure = (
48
128
  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)
129
+ timeoutMsArg: number,
130
+ ): IGitRemoteFailureClass => {
131
+ if (resultArg.timedOut) {
132
+ return {
133
+ transient: true,
134
+ reason: `timed out after ${formatSeconds(timeoutMsArg)}`,
135
+ };
136
+ }
137
+ const permanent = permanentGitRemoteFailures.find((failureArg) =>
138
+ failureArg.pattern.test(resultArg.stderr),
55
139
  );
140
+ if (permanent) return { transient: false, reason: permanent.reason };
141
+ const transient = transientGitRemoteFailures.find((failureArg) =>
142
+ failureArg.pattern.test(resultArg.stderr),
143
+ );
144
+ if (transient) return { transient: true, reason: transient.reason };
145
+ return {
146
+ transient: false,
147
+ reason: resultArg.signal
148
+ ? `terminated by ${resultArg.signal}`
149
+ : `exit code ${resultArg.exitCode}`,
150
+ };
56
151
  };
57
152
 
58
- export interface IRunGitRemoteInspectionOptions {
153
+ /** The final attempt of a remote command and what it took to get there. */
154
+ export interface IReleaseGitRemoteResult extends plugins.smartshell.IExecResult {
155
+ /** The release step the command belongs to. */
156
+ step: string;
157
+ /** `git ls-remote`, `git fetch` or `git push`, without arguments. */
158
+ command: string;
159
+ /** Bound of each attempt. */
160
+ timeoutMs: number;
161
+ attempts: number;
162
+ elapsedMs: number;
163
+ /** The final failure is one a later attempt could have overcome. */
164
+ transient: boolean;
165
+ }
166
+
167
+ /** A push whose final attempt failed may still have landed; see {@link runGitRemotePush}. */
168
+ export interface IReleaseGitRemotePushResult extends IReleaseGitRemoteResult {
169
+ /** A re-inspection found the pushed refs at the remote after a failed attempt. */
170
+ landed: boolean;
171
+ }
172
+
173
+ interface IGitRemoteCommandOptions {
59
174
  smartshell: plugins.smartshell.Smartshell;
60
175
  cwd: string;
61
- /** `ls-remote` arguments, starting with `ls-remote`. */
62
- args: string[];
63
176
  env: NodeJS.ProcessEnv;
64
177
  policy: IReleaseGitRemotePolicy;
178
+ /** The release step; every retry line and every failure names it. */
179
+ step: string;
180
+ }
181
+
182
+ /** The remote reads a release repeats freely: they change no remote state. */
183
+ export type TGitRemoteRead = "ls-remote" | "fetch";
184
+
185
+ export interface IRunGitRemoteReadOptions extends IGitRemoteCommandOptions {
186
+ args: [TGitRemoteRead, ...string[]];
65
187
  }
66
188
 
189
+ /** What re-reading the remote after a failed push attempt proved. */
190
+ export type TGitRemotePushState =
191
+ /** The remote holds the pushed refs: the push is done. */
192
+ | "landed"
193
+ /** The remote is as it was before the push: pushing again is safe. */
194
+ | "absent"
195
+ /** Neither is proven: the push is not repeated. */
196
+ | "unknown";
197
+
198
+ export interface IRunGitRemotePushOptions extends IGitRemoteCommandOptions {
199
+ args: ["push", ...string[]];
200
+ /** Runs before every attempt, the first included; a journaled push claims its attempt here. */
201
+ beforeAttempt?: () => Promise<void>;
202
+ /** Re-reads the remote after a transient failure, before any further attempt. */
203
+ reinspect: () => Promise<TGitRemotePushState>;
204
+ }
205
+
206
+ const assertRetryBudget = (policyArg: IReleaseGitRemotePolicy): void => {
207
+ const totalWaitMs = policyArg.retryDelaysMs.reduce(
208
+ (sumArg, delayArg) => sumArg + delayArg,
209
+ 0,
210
+ );
211
+ if (totalWaitMs > maximumReleaseGitRemoteRetryWaitMs) {
212
+ throw new Error(
213
+ `A Git remote retry policy may wait at most ${formatSeconds(maximumReleaseGitRemoteRetryWaitMs)} in total; this one waits ${formatSeconds(totalWaitMs)}.`,
214
+ );
215
+ }
216
+ };
217
+
67
218
  /**
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.
219
+ * The single retry loop of every remote command of a release. A transient
220
+ * failure is logged with the step and the classified reason, then retried
221
+ * after the policy's next delay; a push re-reads the remote first and is only
222
+ * repeated when the remote provably did not take it.
71
223
  */
72
- export const runGitRemoteInspection = async (
73
- optionsArg: IRunGitRemoteInspectionOptions,
74
- ): Promise<IReleaseGitRemoteResult> => {
224
+ const runGitRemoteCommand = async (
225
+ optionsArg: IGitRemoteCommandOptions & {
226
+ args: string[];
227
+ beforeAttempt?: () => Promise<void>;
228
+ reinspect?: () => Promise<TGitRemotePushState>;
229
+ },
230
+ ): Promise<{ result: IReleaseGitRemoteResult; landed: boolean }> => {
231
+ assertRetryBudget(optionsArg.policy);
232
+ const subcommand = optionsArg.args[0];
233
+ const command = `git ${subcommand}`;
234
+ const timeoutMs =
235
+ subcommand === "ls-remote"
236
+ ? optionsArg.policy.timeoutMs
237
+ : releaseGitTransferTimeoutMs;
238
+ const maximumAttempts = optionsArg.policy.retryDelaysMs.length + 1;
75
239
  const started = Date.now();
76
240
  for (let attempt = 1; ; attempt++) {
241
+ await optionsArg.beforeAttempt?.();
77
242
  const result = await optionsArg.smartshell.execSpawn(
78
243
  "git",
79
244
  optionsArg.args,
80
245
  {
81
246
  cwd: optionsArg.cwd,
82
247
  env: optionsArg.env,
83
- silent: true,
84
- timeout: optionsArg.policy.timeoutMs,
248
+ // A push shows its progress and the remote's messages; reads stay quiet.
249
+ silent: subcommand !== "push",
250
+ timeout: timeoutMs,
85
251
  timeoutKillGraceMs: 5_000,
86
252
  },
87
253
  );
88
- const transient = isTransientGitRemoteFailure(result);
89
- const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
90
- if (!transient || retryDelayMs === undefined) {
91
- return {
254
+ const finish = (
255
+ transientArg: boolean,
256
+ landedArg = false,
257
+ ): { result: IReleaseGitRemoteResult; landed: boolean } => ({
258
+ result: {
92
259
  ...result,
260
+ step: optionsArg.step,
261
+ command,
262
+ timeoutMs,
93
263
  attempts: attempt,
94
264
  elapsedMs: Date.now() - started,
95
- transient,
96
- };
265
+ transient: transientArg,
266
+ },
267
+ landed: landedArg,
268
+ });
269
+ if (result.exitCode === 0) return finish(false);
270
+ const failure = classifyGitRemoteFailure(result, timeoutMs);
271
+ const retryDelayMs = optionsArg.policy.retryDelaysMs[attempt - 1];
272
+ if (!failure.transient || retryDelayMs === undefined) {
273
+ return finish(failure.transient);
97
274
  }
275
+ const failed = `${optionsArg.step}: \`${command}\` failed (${failure.reason}) on attempt ${attempt} of ${maximumAttempts}`;
276
+ if (optionsArg.reinspect) {
277
+ const state = await optionsArg.reinspect();
278
+ if (state === "landed") {
279
+ await logger.log(
280
+ "warn",
281
+ `${failed}, but the remote already holds the pushed refs; the push is done.`,
282
+ );
283
+ return finish(true, true);
284
+ }
285
+ if (state === "unknown") {
286
+ await logger.log(
287
+ "warn",
288
+ `${failed}, and the remote state could not be proven; not pushing again.`,
289
+ );
290
+ return finish(true);
291
+ }
292
+ }
293
+ await logger.log(
294
+ "warn",
295
+ `${failed}${optionsArg.reinspect ? " and the remote does not hold the pushed refs" : ""}; retrying in ${formatSeconds(retryDelayMs)}.`,
296
+ );
98
297
  await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
99
298
  }
100
299
  };
101
300
 
102
- const formatSeconds = (msArg: number): string =>
103
- `${Number((msArg / 1000).toFixed(1))} s`;
301
+ /**
302
+ * Runs an idempotent remote read (`ls-remote`, or a `fetch` for inspection or
303
+ * verification), retrying transient failures. The caller decides what the
304
+ * final answer means; this only makes a flaky remote answer at all.
305
+ */
306
+ export const runGitRemoteRead = async (
307
+ optionsArg: IRunGitRemoteReadOptions,
308
+ ): Promise<IReleaseGitRemoteResult> =>
309
+ (await runGitRemoteCommand(optionsArg)).result;
310
+
311
+ /**
312
+ * Runs a `git push`, which is never repeated blindly: after a transient
313
+ * failure `reinspect` reads the remote. Refs already in place end the push as
314
+ * landed; an unchanged remote is pushed again; anything else stops. The caller
315
+ * still verifies the remote afterwards.
316
+ */
317
+ export const runGitRemotePush = async (
318
+ optionsArg: IRunGitRemotePushOptions,
319
+ ): Promise<IReleaseGitRemotePushResult> => {
320
+ const { result, landed } = await runGitRemoteCommand(optionsArg);
321
+ return { ...result, landed };
322
+ };
104
323
 
105
- /** How the final attempt failed, and how long the inspection kept trying. */
324
+ /** How the final attempt failed, and how long the step kept trying. */
106
325
  export const describeGitRemoteFailure = (
107
326
  resultArg: IReleaseGitRemoteResult,
108
- policyArg: IReleaseGitRemotePolicy,
109
327
  ): string => {
110
328
  const failure = describeCommandFailure(resultArg, {
111
- command: "git ls-remote",
112
- timeoutMs: policyArg.timeoutMs,
329
+ command: resultArg.command,
330
+ timeoutMs: resultArg.timeoutMs,
113
331
  });
114
332
  return resultArg.attempts > 1
115
333
  ? `${failure}; gave up after ${resultArg.attempts} attempts over ${formatSeconds(resultArg.elapsedMs)}`
@@ -117,7 +335,7 @@ export const describeGitRemoteFailure = (
117
335
  };
118
336
 
119
337
  /**
120
- * A remote inspection that failed. The message names the release step, the
338
+ * A remote command that failed. The message names the release step, the
121
339
  * per-attempt bound, the attempts and the time spent; it never carries the
122
340
  * destination URL, whose userinfo the command failure redacts.
123
341
  */
@@ -128,20 +346,15 @@ export class ReleaseGitRemoteError extends Error {
128
346
  public readonly timeoutMs: number;
129
347
  public readonly transient: boolean;
130
348
 
131
- constructor(
132
- messageArg: string,
133
- stepArg: string,
134
- resultArg: IReleaseGitRemoteResult,
135
- policyArg: IReleaseGitRemotePolicy,
136
- ) {
349
+ constructor(messageArg: string, resultArg: IReleaseGitRemoteResult) {
137
350
  super(
138
- `${messageArg} Step: ${stepArg}. ${describeGitRemoteFailure(resultArg, policyArg)}`,
351
+ `${messageArg} Step: ${resultArg.step}. ${describeGitRemoteFailure(resultArg)}`,
139
352
  );
140
353
  this.name = "ReleaseGitRemoteError";
141
- this.step = stepArg;
354
+ this.step = resultArg.step;
142
355
  this.attempts = resultArg.attempts;
143
356
  this.elapsedMs = resultArg.elapsedMs;
144
- this.timeoutMs = policyArg.timeoutMs;
357
+ this.timeoutMs = resultArg.timeoutMs;
145
358
  this.transient = resultArg.transient;
146
359
  }
147
360
  }