@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
@@ -6,9 +6,11 @@ import {
6
6
  import {
7
7
  ReleaseGitRemoteError,
8
8
  createReleaseGitRemotePolicy,
9
- runGitRemoteInspection,
9
+ runGitRemotePush,
10
+ runGitRemoteRead,
10
11
  type IReleaseGitRemotePolicy,
11
12
  type IReleaseGitRemoteResult,
13
+ type TGitRemoteRead,
12
14
  } from "./helpers.gitremote.js";
13
15
  import {
14
16
  getReleaseBranch,
@@ -49,7 +51,7 @@ export interface IReleaseBranchContext {
49
51
  pushUrl?: string;
50
52
  mergeRequested: boolean;
51
53
  planAncestryVerified: boolean;
52
- /** Bound and retries of every remote inspection this release makes. */
54
+ /** Bound and retries of every remote command this release makes. */
53
55
  gitRemotePolicy: IReleaseGitRemotePolicy;
54
56
  }
55
57
 
@@ -201,14 +203,14 @@ interface IReleaseGitResult extends plugins.smartshell.IExecResult {
201
203
  failureContext: IReleaseCommandFailureContext;
202
204
  }
203
205
 
206
+ /** Local Git commands; remote ones run through `helpers.gitremote`. */
204
207
  const runGit = async (
205
208
  smartshellArg: TSmartshell,
206
209
  cwdArg: string,
207
210
  argsArg: string[],
208
211
  readOnlyArg = false,
209
212
  ): Promise<IReleaseGitResult> => {
210
- const timeoutMs =
211
- argsArg[0] === "fetch" || argsArg[0] === "push" ? 5 * 60_000 : 60_000;
213
+ const timeoutMs = 60_000;
212
214
  const result = await smartshellArg.execSpawn("git", argsArg, {
213
215
  cwd: cwdArg,
214
216
  env: readOnlyArg ? readOnlyGitEnv : releaseGitEnv,
@@ -519,24 +521,15 @@ const resolveRemoteMainOid = async (
519
521
  ): Promise<string> => {
520
522
  const releaseBranch = contextArg.releaseBranch;
521
523
  const releaseBranchRef = branchRef(releaseBranch);
522
- const inspect = (argsArg: string[]) =>
523
- runGitRemoteInspection({
524
+ const inspect = (argsArg: [TGitRemoteRead, ...string[]]) =>
525
+ runGitRemoteRead({
524
526
  smartshell: smartshellArg,
525
527
  cwd: contextArg.sourceCwd,
526
528
  args: argsArg,
527
529
  env: readOnlyArg ? readOnlyGitEnv : releaseGitEnv,
528
530
  policy: contextArg.gitRemotePolicy,
531
+ step: stepArg,
529
532
  });
530
- const remoteFailure = (
531
- resultArg: IReleaseGitRemoteResult,
532
- messageArg: string,
533
- ) =>
534
- new ReleaseGitRemoteError(
535
- messageArg,
536
- stepArg,
537
- resultArg,
538
- contextArg.gitRemotePolicy,
539
- );
540
533
  const result = await inspect([
541
534
  "ls-remote",
542
535
  "--exit-code",
@@ -555,9 +548,9 @@ const resolveRemoteMainOid = async (
555
548
  if (result.exitCode === 2 && !result.stdout.trim()) {
556
549
  const allRefs = await inspect(["ls-remote", pushUrlArg]);
557
550
  if (allRefs.exitCode !== 0) {
558
- throw remoteFailure(
559
- allRefs,
551
+ throw new ReleaseGitRemoteError(
560
552
  "Unable to verify the empty Git push destination.",
553
+ allRefs,
561
554
  );
562
555
  }
563
556
  if (allRefs.stdout.trim()) {
@@ -580,9 +573,9 @@ const resolveRemoteMainOid = async (
580
573
  return "0".repeat(format === "sha256" ? 64 : 40);
581
574
  }
582
575
  if (result.exitCode !== 0) {
583
- throw remoteFailure(
584
- result,
576
+ throw new ReleaseGitRemoteError(
585
577
  `Unable to inspect ${releaseBranch} at the configured Git push destination.`,
578
+ result,
586
579
  );
587
580
  }
588
581
  const match = result.stdout.trim().match(/^([0-9a-f]{40}|[0-9a-f]{64})\s+(\S+)$/i);
@@ -594,6 +587,31 @@ const resolveRemoteMainOid = async (
594
587
  return match[1];
595
588
  };
596
589
 
590
+ /** Fetches one ref or object from the push destination for inspection. */
591
+ const fetchFromPushDestination = (
592
+ smartshellArg: TSmartshell,
593
+ cwdArg: string,
594
+ pushUrlArg: string,
595
+ targetArg: string,
596
+ policyArg: IReleaseGitRemotePolicy,
597
+ stepArg: string,
598
+ ) =>
599
+ runGitRemoteRead({
600
+ smartshell: smartshellArg,
601
+ cwd: cwdArg,
602
+ args: [
603
+ "fetch",
604
+ "--no-tags",
605
+ "--no-recurse-submodules",
606
+ "--no-write-fetch-head",
607
+ pushUrlArg,
608
+ targetArg,
609
+ ],
610
+ env: releaseGitEnv,
611
+ policy: policyArg,
612
+ step: stepArg,
613
+ });
614
+
597
615
  const hasCommitObject = async (
598
616
  smartshellArg: TSmartshell,
599
617
  cwdArg: string,
@@ -1050,17 +1068,20 @@ export async function prepareReleaseIntegration(
1050
1068
  );
1051
1069
  return { ...contextArg, planAncestryVerified: true };
1052
1070
  }
1053
- requireGitSuccess(
1054
- await runGit(smartshellArg, contextArg.sourceCwd, [
1055
- "fetch",
1056
- "--no-tags",
1057
- "--no-recurse-submodules",
1058
- "--no-write-fetch-head",
1059
- contextArg.pushUrl,
1060
- branchRef(contextArg.releaseBranch),
1061
- ]),
1062
- `Unable to fetch current ${contextArg.releaseBranch} from the configured Git push destination.`,
1071
+ const fetchResult = await fetchFromPushDestination(
1072
+ smartshellArg,
1073
+ contextArg.sourceCwd,
1074
+ contextArg.pushUrl,
1075
+ branchRef(contextArg.releaseBranch),
1076
+ contextArg.gitRemotePolicy,
1077
+ "release preflight",
1063
1078
  );
1079
+ if (fetchResult.exitCode !== 0) {
1080
+ throw new ReleaseGitRemoteError(
1081
+ `Unable to fetch current ${contextArg.releaseBranch} from the configured Git push destination.`,
1082
+ fetchResult,
1083
+ );
1084
+ }
1064
1085
  const verifiedRemoteMainOid = await resolveRemoteMainOid(
1065
1086
  smartshellArg,
1066
1087
  contextArg,
@@ -1174,32 +1195,39 @@ const verifyCommitContained = async (
1174
1195
  */
1175
1196
  const ensureRemoteCommitObject = async (
1176
1197
  smartshellArg: TSmartshell,
1177
- cwdArg: string,
1198
+ contextArg: Pick<
1199
+ IReleaseBranchContext,
1200
+ "sourceCwd" | "gitRemotePolicy" | "releaseBranch"
1201
+ >,
1178
1202
  pushUrlArg: string,
1179
- releaseBranchArg: string,
1180
1203
  remoteMainOidArg: string,
1204
+ stepArg: string,
1181
1205
  ): Promise<void> => {
1182
- if (await hasCommitObject(smartshellArg, cwdArg, remoteMainOidArg, true)) {
1206
+ const cwd = contextArg.sourceCwd;
1207
+ if (await hasCommitObject(smartshellArg, cwd, remoteMainOidArg, true)) {
1183
1208
  return;
1184
1209
  }
1185
- let lastFetchFailure: IReleaseGitResult | undefined;
1186
- for (const fetchTargetArg of [branchRef(releaseBranchArg), remoteMainOidArg]) {
1187
- const fetchResult = await runGit(smartshellArg, cwdArg, [
1188
- "fetch",
1189
- "--no-tags",
1190
- "--no-recurse-submodules",
1191
- "--no-write-fetch-head",
1210
+ let lastFetchFailure: IReleaseGitRemoteResult | undefined;
1211
+ for (const fetchTargetArg of [
1212
+ branchRef(contextArg.releaseBranch),
1213
+ remoteMainOidArg,
1214
+ ]) {
1215
+ const fetchResult = await fetchFromPushDestination(
1216
+ smartshellArg,
1217
+ cwd,
1192
1218
  pushUrlArg,
1193
1219
  fetchTargetArg,
1194
- ]);
1220
+ contextArg.gitRemotePolicy,
1221
+ stepArg,
1222
+ );
1195
1223
  if (fetchResult.exitCode !== 0) lastFetchFailure = fetchResult;
1196
- if (await hasCommitObject(smartshellArg, cwdArg, remoteMainOidArg, true)) {
1224
+ if (await hasCommitObject(smartshellArg, cwd, remoteMainOidArg, true)) {
1197
1225
  return;
1198
1226
  }
1199
1227
  }
1200
- const message = `Remote ${releaseBranchArg} ${remoteMainOidArg} could not be fetched; remote containment unverified.`;
1228
+ const message = `Remote ${contextArg.releaseBranch} ${remoteMainOidArg} could not be fetched; remote containment unverified.`;
1201
1229
  throw lastFetchFailure
1202
- ? gitFailure(lastFetchFailure, message)
1230
+ ? new ReleaseGitRemoteError(message, lastFetchFailure)
1203
1231
  : new Error(message);
1204
1232
  };
1205
1233
 
@@ -1254,10 +1282,10 @@ export async function verifyReleaseHistoryRetained(
1254
1282
  }
1255
1283
  await ensureRemoteCommitObject(
1256
1284
  smartshellArg,
1257
- contextArg.sourceCwd,
1285
+ contextArg,
1258
1286
  contextArg.pushUrl,
1259
- contextArg.releaseBranch,
1260
1287
  remoteMainOid,
1288
+ "release history check",
1261
1289
  );
1262
1290
  await verifyCommitContained(
1263
1291
  smartshellArg,
@@ -1611,14 +1639,37 @@ export async function integrateReleaseBranch(
1611
1639
  );
1612
1640
  }
1613
1641
 
1614
- const pushResult = await runGit(smartshellArg, releaseCwd, [
1615
- "push",
1616
- "--no-follow-tags",
1617
- `--force-with-lease=${mainBranchRef}:${contextArg.remoteMainOid}`,
1618
- contextArg.pushUrl,
1619
- `${contextArg.sourceOid}:${mainBranchRef}`,
1620
- ]);
1621
- if (pushResult.exitCode !== 0) {
1642
+ const pushUrl = contextArg.pushUrl;
1643
+ const pushResult = await runGitRemotePush({
1644
+ smartshell: smartshellArg,
1645
+ cwd: releaseCwd,
1646
+ args: [
1647
+ "push",
1648
+ "--no-follow-tags",
1649
+ `--force-with-lease=${mainBranchRef}:${contextArg.remoteMainOid}`,
1650
+ pushUrl,
1651
+ `${contextArg.sourceOid}:${mainBranchRef}`,
1652
+ ],
1653
+ env: releaseGitEnv,
1654
+ policy: contextArg.gitRemotePolicy,
1655
+ step: "main integration",
1656
+ reinspect: async () => {
1657
+ let remoteMainOid: string;
1658
+ try {
1659
+ remoteMainOid = await resolveRemoteMainOid(
1660
+ smartshellArg,
1661
+ contextArg,
1662
+ pushUrl,
1663
+ "main integration",
1664
+ );
1665
+ } catch {
1666
+ return "unknown";
1667
+ }
1668
+ if (remoteMainOid === contextArg.sourceOid) return "landed";
1669
+ return remoteMainOid === contextArg.remoteMainOid ? "absent" : "unknown";
1670
+ },
1671
+ });
1672
+ if (pushResult.exitCode !== 0 && !pushResult.landed) {
1622
1673
  let remoteAfterPush: string | undefined;
1623
1674
  try {
1624
1675
  remoteAfterPush = await resolveRemoteMainOid(
@@ -1637,9 +1688,9 @@ export async function integrateReleaseBranch(
1637
1688
  releaseCwd,
1638
1689
  destinationGitDir,
1639
1690
  );
1640
- const failure = gitFailure(
1641
- pushResult,
1691
+ const failure = new ReleaseGitRemoteError(
1642
1692
  "Integrated main could not be confirmed at the remote. No release metadata was created.",
1693
+ pushResult,
1643
1694
  );
1644
1695
  throw new Error(
1645
1696
  `${failure.message}${rollbackState}${
@@ -3,6 +3,7 @@ import {
3
3
  isCanonicalReleaseVersion,
4
4
  releaseVersionMajor,
5
5
  } from "./helpers.releaseversion.js";
6
+ import type { TReleaseAliasPolicy } from "./mod.plugins.js";
6
7
 
7
8
  /** The branch every release publishes from unless a release line names another. */
8
9
  export const mainReleaseBranch = "main";
@@ -11,9 +12,10 @@ export const latestDistTag = "latest";
11
12
 
12
13
  /**
13
14
  * A maintenance line: an older major released from its own branch under its
14
- * own npm dist-tag, so that `latest` never moves. The block is committed on
15
- * the maintenance branch itself, which makes that branch, and only that
16
- * branch, a release source.
15
+ * own npm dist-tag, so that `latest` never moves. Its Docker images carry only
16
+ * tags bound to the release version, so no floating image tag moves either.
17
+ * The block is committed on the maintenance branch itself, which makes that
18
+ * branch, and only that branch, a release source.
17
19
  */
18
20
  export interface IReleaseLine {
19
21
  branch: string;
@@ -99,6 +101,23 @@ export const getReleaseBranch = (lineArg: IReleaseLine | undefined): string =>
99
101
  export const getReleaseDistTag = (lineArg: IReleaseLine | undefined): string =>
100
102
  lineArg ? lineArg.distTag : latestDistTag;
101
103
 
104
+ /**
105
+ * The tSDocker alias policy a release asks for. A line admits only tags bound
106
+ * to its release version, which tSDocker decides from the Dockerfiles and
107
+ * `additionalTags`; `main` keeps every configured tag, `latest` included.
108
+ */
109
+ export function getReleaseDockerAliasPolicy(
110
+ lineArg: IReleaseLine,
111
+ ): TReleaseAliasPolicy;
112
+ export function getReleaseDockerAliasPolicy(
113
+ lineArg: IReleaseLine | undefined,
114
+ ): TReleaseAliasPolicy | undefined;
115
+ export function getReleaseDockerAliasPolicy(
116
+ lineArg: IReleaseLine | undefined,
117
+ ): TReleaseAliasPolicy | undefined {
118
+ return lineArg ? "release-version" : undefined;
119
+ }
120
+
102
121
  export const isSameReleaseLine = (
103
122
  leftArg: IReleaseLine | undefined,
104
123
  rightArg: IReleaseLine | undefined,
@@ -28,7 +28,7 @@ import {
28
28
  } from "./helpers.releasephase.js";
29
29
  import {
30
30
  ReleaseGitRemoteError,
31
- runGitRemoteInspection,
31
+ runGitRemoteRead,
32
32
  } from "./helpers.gitremote.js";
33
33
  import {
34
34
  canonicalReleaseJson,
@@ -182,8 +182,7 @@ export const assertRecoveryUnpublished = async (
182
182
  options: IReleasePreparationRecovery,
183
183
  pnpmCapabilityArg?: IPnpmReleaseCapability,
184
184
  ): Promise<void> => {
185
- const policy = options.branch.gitRemotePolicy;
186
- const remoteTags = await runGitRemoteInspection({
185
+ const remoteTags = await runGitRemoteRead({
187
186
  smartshell: options.smartshell,
188
187
  cwd: options.branch.sourceCwd,
189
188
  args: [
@@ -193,14 +192,13 @@ export const assertRecoveryUnpublished = async (
193
192
  `refs/tags/v${options.version}^{}`,
194
193
  ],
195
194
  env: releaseGitEnv,
196
- policy,
195
+ policy: options.branch.gitRemotePolicy,
196
+ step: "release recovery",
197
197
  });
198
198
  if (remoteTags.exitCode !== 0)
199
199
  throw new ReleaseGitRemoteError(
200
200
  "Unable to inspect the release tag at the configured Git push destination.",
201
- "release recovery",
202
201
  remoteTags,
203
- policy,
204
202
  );
205
203
  if (remoteTags.stdout.trim())
206
204
  throw new Error(
@@ -56,11 +56,11 @@ import {
56
56
  latestDistTag,
57
57
  } from "./helpers.releaseline.js";
58
58
  import { isAbsentGitOid, releaseGitEnv } from "./helpers.releasebranch.js";
59
- import { describeCommandFailure } from "./helpers.commandfailure.js";
60
59
  import {
61
60
  createReleaseGitRemotePolicy,
62
61
  describeGitRemoteFailure,
63
- runGitRemoteInspection,
62
+ runGitRemotePush,
63
+ runGitRemoteRead,
64
64
  type IReleaseGitRemotePolicy,
65
65
  } from "./helpers.gitremote.js";
66
66
  import {
@@ -76,8 +76,6 @@ import {
76
76
  type TReleasePromotionEvidence,
77
77
  } from "./helpers.tsdockerprotocol.js";
78
78
 
79
- const gitPushTimeoutMs = 5 * 60_000;
80
-
81
79
  export interface IBuildReleaseGitPushArgsOptions {
82
80
  destination: string;
83
81
  /** `main`, or the branch of the journaled release line. */
@@ -92,7 +90,7 @@ export interface IBuildReleaseGitPushArgsOptions {
92
90
 
93
91
  export function buildReleaseGitPushArgs(
94
92
  optionsArg: IBuildReleaseGitPushArgsOptions,
95
- ): string[] {
93
+ ): ["push", ...string[]] {
96
94
  const refspecs: string[] = [];
97
95
  if (optionsArg.pushBranch) {
98
96
  refspecs.push(`${optionsArg.mainOid}:refs/heads/${optionsArg.releaseBranch}`);
@@ -100,7 +98,7 @@ export function buildReleaseGitPushArgs(
100
98
  if (optionsArg.pushTags) {
101
99
  refspecs.push(`${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`);
102
100
  }
103
- const args = ["push", "--no-follow-tags"];
101
+ const args: ["push", ...string[]] = ["push", "--no-follow-tags"];
104
102
  if (refspecs.length > 1) {
105
103
  args.push("--atomic");
106
104
  }
@@ -153,7 +151,7 @@ export interface IReleasePublicationOptions {
153
151
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
154
152
  /** Attachments of a draft in progress at the same time (1 or 2); default 1. */
155
153
  giteaAssetConcurrency?: number;
156
- /** Bound and retries of the Git target's remote inspection. */
154
+ /** Bound and retries of the Git target's remote commands. */
157
155
  gitRemotePolicy?: IReleaseGitRemotePolicy;
158
156
  giteaAssets?: Pick<
159
157
  GiteaAssetsClient,
@@ -366,8 +364,7 @@ const inspectRemoteRelease = async (
366
364
  ): Promise<IGitProbeResult> => {
367
365
  const tagRef = `refs/tags/${journalArg.release.tag}`;
368
366
  const releaseBranchRef = `refs/heads/${getReleaseBranch(journalArg.release.line)}`;
369
- const policy = optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy();
370
- const result = await runGitRemoteInspection({
367
+ const result = await runGitRemoteRead({
371
368
  smartshell: optionsArg.smartshell,
372
369
  cwd: optionsArg.cwd,
373
370
  args: [
@@ -378,12 +375,13 @@ const inspectRemoteRelease = async (
378
375
  `${tagRef}^{}`,
379
376
  ],
380
377
  env: releaseGitEnv,
381
- policy,
378
+ policy: optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy(),
379
+ step: "target.git",
382
380
  });
383
381
  if (result.exitCode !== 0) {
384
382
  return {
385
383
  status: "inconclusive",
386
- failure: `Step: target.git. ${describeGitRemoteFailure(result, policy)}`,
384
+ failure: `Step: ${result.step}. ${describeGitRemoteFailure(result)}`,
387
385
  };
388
386
  }
389
387
  const refs = new Map<string, string>();
@@ -539,12 +537,15 @@ const executeGitTarget = async (
539
537
  );
540
538
  }
541
539
 
542
- await optionsArg.ensurePublicationState(expectedRemoteMainOid);
543
- journal = await claimTarget(optionsArg.store, journal, selector);
544
- const pushResult = await optionsArg.smartshell.execSpawn(
545
- "git",
546
- buildReleaseGitPushArgs({
547
- destination: optionsArg.pushUrl,
540
+ // Each push attempt is journaled as its own claim. A transient failure is
541
+ // followed by a probe: exact refs end the push, a pending remote closes the
542
+ // attempt as failed so the next one claims afresh, anything else stops.
543
+ const pushUrl = optionsArg.pushUrl;
544
+ const pushResult = await runGitRemotePush({
545
+ smartshell: optionsArg.smartshell,
546
+ cwd: optionsArg.cwd,
547
+ args: buildReleaseGitPushArgs({
548
+ destination: pushUrl,
548
549
  releaseBranch: getReleaseBranch(journal.release.line),
549
550
  newVersion: journal.release.version,
550
551
  pushBranch: true,
@@ -553,13 +554,27 @@ const executeGitTarget = async (
553
554
  tagOid: journal.release.tagOid,
554
555
  expectedRemoteMainOid,
555
556
  }),
556
- {
557
- cwd: optionsArg.cwd,
558
- env: releaseGitEnv,
559
- timeout: gitPushTimeoutMs,
560
- timeoutKillGraceMs: 5_000,
557
+ env: releaseGitEnv,
558
+ policy: optionsArg.gitRemotePolicy ?? createReleaseGitRemotePolicy(),
559
+ step: "target.git",
560
+ beforeAttempt: async () => {
561
+ await optionsArg.ensurePublicationState(expectedRemoteMainOid);
562
+ journal = await claimTarget(optionsArg.store, journal, selector);
561
563
  },
562
- );
564
+ reinspect: async () => {
565
+ const found = await inspectRemoteRelease(optionsArg, pushUrl, journal);
566
+ if (found.status === "exact") return "landed";
567
+ if (found.status !== "pending") return "unknown";
568
+ journal = await finishPublishingTarget(
569
+ optionsArg.store,
570
+ journal,
571
+ selector,
572
+ "failed",
573
+ "command-failed",
574
+ );
575
+ return "absent";
576
+ },
577
+ });
563
578
  probe = await inspectRemoteRelease(optionsArg, optionsArg.pushUrl, journal);
564
579
  if (probe.status === "exact") {
565
580
  journal = await finishPublishingTarget(
@@ -587,15 +602,12 @@ const executeGitTarget = async (
587
602
  journal,
588
603
  selector,
589
604
  "failed",
590
- pushResult.exitCode === 0 ? "verification-inconclusive" : "command-failed",
605
+ pushResult.exitCode === 0 || pushResult.landed
606
+ ? "verification-inconclusive"
607
+ : "command-failed",
591
608
  );
592
609
  const pushFailure =
593
- pushResult.exitCode === 0
594
- ? ""
595
- : ` ${describeCommandFailure(pushResult, {
596
- command: "git push",
597
- timeoutMs: gitPushTimeoutMs,
598
- })}`;
610
+ pushResult.exitCode === 0 ? "" : ` ${describeGitRemoteFailure(pushResult)}`;
599
611
  throw new Error(
600
612
  withGitProbeFailure(
601
613
  `Git publication did not produce verifiable remote refs.${pushFailure}`,
@@ -12,8 +12,10 @@ import type {
12
12
  IReleaseQualificationRequest,
13
13
  IReleaseQualificationResult,
14
14
  IReleaseValidationResult,
15
+ TReleaseAliasPolicy,
15
16
  TReleasePromotionEvidence,
16
17
  TReleaseProtocolCommand,
18
+ TReleaseProtocolFeature,
17
19
  } from "./mod.plugins.js";
18
20
 
19
21
  export type {
@@ -26,6 +28,7 @@ export type {
26
28
  IReleaseQualificationRequest,
27
29
  IReleaseQualificationResult,
28
30
  IReleaseValidationResult,
31
+ TReleaseAliasPolicy,
29
32
  TReleasePromotionEvidence,
30
33
  TReleaseProtocolCommand,
31
34
  } from "./mod.plugins.js";
@@ -65,6 +68,27 @@ const requestFilePattern =
65
68
  /^\.tsdocker-request\.([a-f0-9]{32})\.(release-(?:validate|qualify|probe|promote|cleanup))\.([a-f0-9]{24})\.json$/;
66
69
  const minimumReleaseVersion = [3, 5, 1] as const;
67
70
 
71
+ /** The capability a tSDocker that enforces each alias policy advertises. */
72
+ const aliasPolicyFeatures: Record<
73
+ TReleaseAliasPolicy,
74
+ TReleaseProtocolFeature
75
+ > = { "release-version": "release-version-alias-policy" };
76
+ const policyFeatures = new Set(Object.values(aliasPolicyFeatures));
77
+
78
+ /**
79
+ * Every current protocol feature except those of alias policies, plus the one
80
+ * of the requested policy: a release without a policy keeps working with a
81
+ * tSDocker that predates them, and one with a policy never runs without it.
82
+ */
83
+ const getRequiredReleaseFeatures = (
84
+ aliasPolicyArg: TReleaseAliasPolicy | undefined,
85
+ ): TReleaseProtocolFeature[] => [
86
+ ...plugins.tsdockerReleaseProtocol.releaseProtocolFeatures.filter(
87
+ (featureArg) => !policyFeatures.has(featureArg),
88
+ ),
89
+ ...(aliasPolicyArg ? [aliasPolicyFeatures[aliasPolicyArg]] : []),
90
+ ];
91
+
68
92
  const commandTimeouts: Record<TReleaseProtocolCommand, number> = {
69
93
  "release-capabilities": 30_000,
70
94
  "release-validate": 2 * 60_000,
@@ -107,7 +131,9 @@ export class TsdockerReleaseRequestCleanupError extends Error {
107
131
  }
108
132
 
109
133
  export interface ITsdockerReleaseClient {
110
- assertCapabilities: () => Promise<IReleaseCapabilitiesResult>;
134
+ assertCapabilities: (
135
+ aliasPolicyArg?: TReleaseAliasPolicy,
136
+ ) => Promise<IReleaseCapabilitiesResult>;
111
137
  validate: (
112
138
  requestArg: IReleaseQualificationRequest,
113
139
  requestDirectoryArg?: string,
@@ -264,7 +290,9 @@ export class TsdockerReleaseClient implements ITsdockerReleaseClient {
264
290
  );
265
291
  }
266
292
 
267
- public async assertCapabilities(): Promise<IReleaseCapabilitiesResult> {
293
+ public async assertCapabilities(
294
+ aliasPolicyArg?: TReleaseAliasPolicy,
295
+ ): Promise<IReleaseCapabilitiesResult> {
268
296
  const installedVersion = await this.readInstalledVersion();
269
297
  await plugins.fs.access(this.binaryPath);
270
298
  const versionResult = await this.smartshell.execSpawn(
@@ -305,9 +333,7 @@ export class TsdockerReleaseClient implements ITsdockerReleaseClient {
305
333
  requiredCommands: [
306
334
  ...plugins.tsdockerReleaseProtocol.releaseProtocolCommands,
307
335
  ],
308
- requiredFeatures: [
309
- ...plugins.tsdockerReleaseProtocol.releaseProtocolFeatures,
310
- ],
336
+ requiredFeatures: getRequiredReleaseFeatures(aliasPolicyArg),
311
337
  },
312
338
  );
313
339
  }