@git.zone/cli 7.2.6 → 7.3.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 (43) hide show
  1. package/assets/templates/npm/.package.json +1 -1
  2. package/assets/templates/service/.package.json +1 -1
  3. package/assets/templates/wcc/.package.json +1 -1
  4. package/assets/templates/website/.package.json +1 -1
  5. package/dist_ts/00_commitinfo_data.js +1 -1
  6. package/dist_ts/helpers.climode.js +2 -1
  7. package/dist_ts/helpers.workflow.d.ts +19 -1
  8. package/dist_ts/helpers.workflow.js +31 -2
  9. package/dist_ts/mod_config/index.js +18 -2
  10. package/dist_ts/mod_release/classes.detachedrelease.d.ts +85 -0
  11. package/dist_ts/mod_release/classes.detachedrelease.js +506 -0
  12. package/dist_ts/mod_release/classes.releasejournal.d.ts +34 -0
  13. package/dist_ts/mod_release/classes.releasejournal.js +134 -2
  14. package/dist_ts/mod_release/helpers.giteaassets.d.ts +19 -0
  15. package/dist_ts/mod_release/helpers.giteaassets.js +53 -4
  16. package/dist_ts/mod_release/helpers.gitremote.d.ts +52 -0
  17. package/dist_ts/mod_release/helpers.gitremote.js +87 -0
  18. package/dist_ts/mod_release/helpers.releasebranch.d.ts +5 -0
  19. package/dist_ts/mod_release/helpers.releasebranch.js +39 -15
  20. package/dist_ts/mod_release/helpers.releasepreparation.js +18 -8
  21. package/dist_ts/mod_release/helpers.releasepublication.d.ts +3 -0
  22. package/dist_ts/mod_release/helpers.releasepublication.js +19 -15
  23. package/dist_ts/mod_release/index.js +303 -66
  24. package/dist_ts/mod_services/classes.interprocesslock.d.ts +12 -0
  25. package/dist_ts/mod_services/classes.interprocesslock.js +35 -12
  26. package/dist_ts/paths.d.ts +6 -0
  27. package/dist_ts/paths.js +7 -1
  28. package/package.json +4 -4
  29. package/readme.md +158 -21
  30. package/ts/00_commitinfo_data.ts +1 -1
  31. package/ts/helpers.climode.ts +1 -0
  32. package/ts/helpers.workflow.ts +50 -0
  33. package/ts/mod_config/index.ts +19 -0
  34. package/ts/mod_release/classes.detachedrelease.ts +655 -0
  35. package/ts/mod_release/classes.releasejournal.ts +181 -1
  36. package/ts/mod_release/helpers.giteaassets.ts +67 -5
  37. package/ts/mod_release/helpers.gitremote.ts +147 -0
  38. package/ts/mod_release/helpers.releasebranch.ts +75 -30
  39. package/ts/mod_release/helpers.releasepreparation.ts +25 -7
  40. package/ts/mod_release/helpers.releasepublication.ts +27 -36
  41. package/ts/mod_release/index.ts +443 -87
  42. package/ts/mod_services/classes.interprocesslock.ts +44 -15
  43. package/ts/paths.ts +10 -0
@@ -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,