@git.zone/cli 8.7.0 → 8.8.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.
package/readme.md CHANGED
@@ -438,11 +438,12 @@ The rules:
438
438
  - The release must run on the branch the line names. On any other branch,
439
439
  `main` included, the release stops before anything is created. A branch
440
440
  without `release.line` still releases only `main`.
441
- - A line publishes only to Git and npm. Docker targets promote aliases such as
442
- `latest`, and Gitea marks its newest release as the latest one, so a line
443
- with an enabled `docker` or `giteaAssets` target is refused, and so are
444
- `--merge` and `gitzone release recover`. A line release records its intent,
445
- so `gitzone release resume <version> -y` continues it.
441
+ - A line publishes to Git, npm and Docker. Docker images carry only tags bound
442
+ to the release version (see [Docker images on a line](#docker-images-on-a-line)).
443
+ Gitea marks its newest release as the latest one, so a line with an enabled
444
+ `giteaAssets` target is refused, and so are `--merge` and `gitzone release
445
+ recover`. A line release records its intent, so `gitzone release resume
446
+ <version> -y` continues it.
446
447
  - A line keeps its major. A Pending `### Breaking Changes` section, `--major`
447
448
  or a `release.versionFloor` that changes the major stops the release.
448
449
  - Before anything is created, and again right before each upload, every
@@ -469,6 +470,44 @@ The rules:
469
470
  `pnpm view --help` in both pnpm command dialects before it authenticates,
470
471
  reads or publishes anything.
471
472
 
473
+ #### Docker images on a line
474
+
475
+ A line may enable the `docker` target, but its images never move a tag that
476
+ another release owns, such as `latest`, a literal like `stable` or a major tag
477
+ like `4`. gitzone does not decide this itself: it asks the project-local
478
+ tSDocker for its `release-version` alias policy (tSDocker 3.11.0 or later,
479
+ capability `release-version-alias-policy`), which admits a tag only when its
480
+ template contains `##version##`. Name the Dockerfiles `Dockerfile_##version##`
481
+ (or `Dockerfile_##version##-alpine` and the like) and keep every
482
+ `@git.zone/tsdocker.additionalTags` entry bound to `##version##`, such as
483
+ `v##version##`.
484
+
485
+ `gitzone release --plan` asks tSDocker (`release-validate`, which builds
486
+ nothing and contacts no registry) for the exact tags each selected Dockerfile
487
+ will publish:
488
+
489
+ ```bash
490
+ gitzone release --plan
491
+ # release line: maintenance/32.2 -> npm dist-tag corestore32 (major 32; latest is never moved)
492
+ # targets: git, npm, docker
493
+ # docker alias policy: release-version (every tag is bound to 32.2.4; floating tags such as latest are refused)
494
+ # docker image Dockerfile_##version##: 32.2.4
495
+ ```
496
+
497
+ A Dockerfile or additional tag that would publish a floating tag stops the
498
+ plan and the release before anything is committed or tagged, naming the
499
+ Dockerfile or tag and the tag it would publish:
500
+
501
+ ```text
502
+ Release line corestore32 publishes Docker images only under tags bound to 32.2.4, and tSDocker refused the release (INVALID_RELEASE_CONFIG): Alias policy release-version refuses this release: Dockerfile publishes the tag "latest", which is not bound to the release version; name the Dockerfile with ##version##, such as Dockerfile_##version##.
503
+ ```
504
+
505
+ The policy is part of the journaled qualification request, so tSDocker
506
+ enforces it again when it qualifies the built images, and `resume` continues
507
+ under the same policy. A project-local tSDocker without the capability stops
508
+ a line with Docker before anything is created; `main` releases keep every
509
+ configured tag, `latest` included, and do not need the capability.
510
+
472
511
  #### `latest` only moves upwards
473
512
 
474
513
  The same check guards every `main` release: when a registry's `latest` is a
@@ -494,7 +533,11 @@ when the upload was claimed. `git.expectedRemoteMainOid` keeps its name and
494
533
  holds the leased commit of the release branch, `main` or the line's branch.
495
534
  Journals of `main` releases are byte-identical to before. GitZone 8.3.x and
496
535
  earlier refuse to read a line journal or intent, so they can neither resume a
497
- line release onto `main` nor publish it under `latest`.
536
+ line release onto `main` nor publish it under `latest`. A line release with
537
+ Docker writes a schema 2 journal whose Docker request carries
538
+ `options.aliasPolicy: "release-version"`; a schema 2 journal is accepted only
539
+ when that policy is present exactly for a line. GitZone 8.7.x and earlier
540
+ refuse to read such a journal or its intent.
498
541
 
499
542
  ### Exact artifacts and release journals
500
543
 
@@ -1530,7 +1573,10 @@ attachments belong to the tag, and the job token can write them.
1530
1573
  complete set is retained and nothing is built. A draft that is not complete is
1531
1574
  rebuilt. A published release that is not complete stops the job.
1532
1575
  2. **Prepare** runs the component's prepare command, verifies the result with
1533
- TsPack, runs the verify command on it, and writes the release receipt.
1576
+ TsPack, runs the verify command on it, and writes the release receipt. Both
1577
+ commands run with `SOURCE_DATE_EPOCH` set to the tagged commit's time, so
1578
+ tools that record or embed a time build the same bytes on every attempt; a
1579
+ job that sets another value stops.
1534
1580
  3. **Retain** waits until Gitea has processed the pushed tag before it creates a
1535
1581
  draft, because Gitea publishes a release it finds for a tag when it processes
1536
1582
  the push (the same wait `gitzone release` uses; see [Gitea release attachments before npm](#gitea-release-attachments-before-npm)). The
@@ -1548,17 +1594,21 @@ attachments belong to the tag, and the job token can write them.
1548
1594
  again, publishes the draft and confirms the release and its attachment list
1549
1595
  anonymously.
1550
1596
 
1551
- A published attachment is never replaced and a release is never deleted. A draft
1552
- has never been public, so a draft attachment that conflicts with the sealed set
1553
- (an interrupted earlier attempt whose rebuild produced different bytes, or a file
1554
- outside the set) is replaced: right before each deletion the release must still
1555
- read back as a draft with the token and be invisible anonymously, and the job log
1556
- names the attachment and both digests. A draft that turns public meanwhile stops
1557
- the job before the next change.
1597
+ A published attachment is never replaced and a release is never deleted. A
1598
+ release build must be reproducible: a draft whose description names a manifest
1599
+ holds an earlier build of the same commit, and a rebuild that seals a different
1600
+ manifest is refused without changing the draft, naming both digests. Make the
1601
+ build reproducible, or delete the draft to release a new build. Within the same
1602
+ manifest, a draft attachment that conflicts with the sealed set (bytes an
1603
+ interrupted upload left, or a file outside the set) is replaced: right before
1604
+ each deletion the release must still read back as a draft with the token and be
1605
+ invisible anonymously, and the job log names the attachment and both digests. A
1606
+ draft that turns public meanwhile stops the job before the next change.
1558
1607
 
1559
1608
  After an interruption, rerun the job. A rerun after a complete draft or a
1560
1609
  published release resumes from its bytes without building; a rerun after an
1561
- incomplete draft rebuilds and completes it. The remote tag must match the sealed
1610
+ incomplete draft rebuilds, and completes it when the rebuild reproduces the
1611
+ manifest the draft names. The remote tag must match the sealed
1562
1612
  source commit. Unexpected API responses, a publicly visible draft, an incomplete
1563
1613
  published release and changed source identities stop before publication.
1564
1614
 
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '8.7.0',
6
+ version: '8.8.0',
7
7
  description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
8
8
  }
@@ -1029,10 +1029,12 @@ const assertNoRemovedNpmTargetSettings = (
1029
1029
  };
1030
1030
 
1031
1031
  /**
1032
- * A maintenance line publishes only to Git and npm. A Docker target promotes
1033
- * aliases such as `latest`, and Gitea marks its newest release as the latest
1034
- * one; neither may follow an older major. A line releases its branch in
1035
- * place, so it never integrates another branch.
1032
+ * Gitea marks its newest release as the latest one, which must never follow
1033
+ * an older major, so a maintenance line does not publish Gitea assets. Its
1034
+ * Docker images are admitted under tSDocker's `release-version` alias policy
1035
+ * (see `getReleaseDockerAliasPolicy`), which refuses every tag not bound to
1036
+ * the release version. A line releases its branch in place, so it never
1037
+ * integrates another branch.
1036
1038
  */
1037
1039
  const assertReleaseLineTargets = (
1038
1040
  lineArg: IReleaseLine | undefined,
@@ -1040,12 +1042,9 @@ const assertReleaseLineTargets = (
1040
1042
  mergeRequestedArg: boolean,
1041
1043
  ): void => {
1042
1044
  if (!lineArg) return;
1043
- const refused = targetsArg.filter(
1044
- (targetArg) => targetArg === "docker" || targetArg === "giteaAssets",
1045
- );
1046
- if (refused.length > 0) {
1045
+ if (targetsArg.includes("giteaAssets")) {
1047
1046
  throw new Error(
1048
- `Release line ${lineArg.distTag} publishes only to Git and npm; disable ${refused.join(" and ")} on ${lineArg.branch}.`,
1047
+ `Release line ${lineArg.distTag} does not publish Gitea assets, because Gitea would mark the older major as its latest release; disable giteaAssets on ${lineArg.branch}.`,
1049
1048
  );
1050
1049
  }
1051
1050
  if (mergeRequestedArg) {
@@ -33,13 +33,20 @@ import {
33
33
  } from "../helpers.workflow.js";
34
34
  import { resolvePackageFiles } from "../helpers.packagefiles.js";
35
35
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
36
- import { TsdockerReleaseClient } from "../mod_release/helpers.tsdockerprotocol.js";
36
+ import {
37
+ TsdockerReleaseClient,
38
+ type TReleaseAliasPolicy,
39
+ } from "../mod_release/helpers.tsdockerprotocol.js";
37
40
  import {
38
41
  ReleaseVersionError,
39
42
  parseReleaseVersionFloor,
40
43
  } from "../mod_release/helpers.releaseversion.js";
41
44
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
42
- import { parseReleaseLine } from "../mod_release/helpers.releaseline.js";
45
+ import {
46
+ getReleaseDockerAliasPolicy,
47
+ parseReleaseLine,
48
+ type IReleaseLine,
49
+ } from "../mod_release/helpers.releaseline.js";
43
50
 
44
51
  export { ReleaseConfig, CommitConfig };
45
52
 
@@ -1974,7 +1981,11 @@ async function validateReleaseConfig(
1974
1981
  }
1975
1982
 
1976
1983
  findings.push(validateReleaseVersionFloor(releaseConfig.versionFloor));
1977
- findings.push(validateReleaseLine(releaseConfig.line, releaseConfig.targets));
1984
+ const line = validateReleaseLine(
1985
+ releaseConfig.line,
1986
+ releaseConfig.targets,
1987
+ findings,
1988
+ );
1978
1989
 
1979
1990
  if (
1980
1991
  releaseConfig.registries ||
@@ -2045,7 +2056,12 @@ async function validateReleaseConfig(
2045
2056
  }
2046
2057
  }
2047
2058
  await validateNpmTarget(targets.npm || {}, findings);
2048
- await validateDockerTarget(targets.docker || {}, smartconfigData, findings);
2059
+ await validateDockerTarget(
2060
+ targets.docker || {},
2061
+ smartconfigData,
2062
+ findings,
2063
+ getReleaseDockerAliasPolicy(line),
2064
+ );
2049
2065
  }
2050
2066
 
2051
2067
  function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
@@ -2067,43 +2083,48 @@ function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
2067
2083
  }
2068
2084
  }
2069
2085
 
2086
+ /** Reports release.line and returns it when it is valid. */
2070
2087
  function validateReleaseLine(
2071
2088
  valueArg: unknown,
2072
2089
  targetsArg: unknown,
2073
- ): IDoctorFinding {
2074
- let line: ReturnType<typeof parseReleaseLine>;
2090
+ findings: IDoctorFinding[],
2091
+ ): IReleaseLine | undefined {
2092
+ let line: IReleaseLine | undefined;
2075
2093
  try {
2076
2094
  line = parseReleaseLine(valueArg);
2077
2095
  } catch (error) {
2078
- return {
2096
+ findings.push({
2079
2097
  level: "error",
2080
2098
  message: error instanceof Error ? error.message : String(error),
2081
2099
  fix: 'Set release.line to { "branch": "<maintenance branch>", "distTag": "<dist-tag>" } on the maintenance branch, or remove it.',
2082
- };
2100
+ });
2101
+ return undefined;
2083
2102
  }
2084
2103
  if (!line) {
2085
- return {
2104
+ findings.push({
2086
2105
  level: "ok",
2087
2106
  message: "Release line is not configured; releases run from main under latest",
2088
- };
2107
+ });
2108
+ return undefined;
2089
2109
  }
2090
2110
  const targets = isPlainObject(targetsArg) ? targetsArg : {};
2091
- const enabled = (["docker", "giteaAssets"] as const).filter(
2092
- (targetArg) =>
2093
- isPlainObject(targets[targetArg]) &&
2094
- (targets[targetArg] as Record<string, unknown>).enabled === true,
2095
- );
2096
- if (enabled.length > 0) {
2097
- return {
2111
+ const isEnabled = (targetArg: "docker" | "giteaAssets"): boolean =>
2112
+ isPlainObject(targets[targetArg]) && targets[targetArg].enabled === true;
2113
+ if (isEnabled("giteaAssets")) {
2114
+ findings.push({
2098
2115
  level: "error",
2099
- message: `Release line ${line.distTag} publishes only to Git and npm, but ${enabled.join(" and ")} ${enabled.length > 1 ? "are" : "is"} enabled`,
2100
- fix: `Disable ${enabled.join(" and ")} in release.targets on ${line.branch}.`,
2101
- };
2116
+ message: `Release line ${line.distTag} never publishes Gitea assets, but giteaAssets is enabled`,
2117
+ fix: `Disable giteaAssets in release.targets on ${line.branch}.`,
2118
+ });
2119
+ return line;
2102
2120
  }
2103
- return {
2121
+ findings.push({
2104
2122
  level: "ok",
2105
- message: `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}`,
2106
- };
2123
+ message: isEnabled("docker")
2124
+ ? `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}, and Docker images only under tags bound to the release version (tSDocker alias policy ${getReleaseDockerAliasPolicy(line)})`
2125
+ : `Release line ${line.branch} publishes under npm dist-tag ${line.distTag}`,
2126
+ });
2127
+ return line;
2107
2128
  }
2108
2129
 
2109
2130
  async function validateAssetsConfig(
@@ -2490,6 +2511,7 @@ async function validateDockerTarget(
2490
2511
  dockerTarget: Record<string, any>,
2491
2512
  smartconfigData: Record<string, any>,
2492
2513
  findings: IDoctorFinding[],
2514
+ aliasPolicyArg: TReleaseAliasPolicy | undefined,
2493
2515
  ): Promise<void> {
2494
2516
  if (
2495
2517
  dockerTarget.noBuild === true ||
@@ -2605,6 +2627,7 @@ async function validateDockerTarget(
2605
2627
  findings,
2606
2628
  dockerTarget.buildRegistries,
2607
2629
  dockerTarget.test === true,
2630
+ aliasPolicyArg,
2608
2631
  );
2609
2632
 
2610
2633
  findings.push({
@@ -2693,6 +2716,7 @@ async function validateTsdockerCommand(
2693
2716
  findings: IDoctorFinding[],
2694
2717
  _buildRegistriesArg: unknown,
2695
2718
  _imageTestsRequestedArg: boolean,
2719
+ aliasPolicyArg: TReleaseAliasPolicy | undefined,
2696
2720
  ): Promise<void> {
2697
2721
  let packageJson: unknown;
2698
2722
  try {
@@ -2728,10 +2752,12 @@ async function validateTsdockerCommand(
2728
2752
  await new TsdockerReleaseClient(
2729
2753
  smartshellInstance,
2730
2754
  process.cwd(),
2731
- ).assertCapabilities();
2755
+ ).assertCapabilities(aliasPolicyArg);
2732
2756
  findings.push({
2733
2757
  level: "ok",
2734
- message: "Project-local tSDocker release protocol v1 is available",
2758
+ message: aliasPolicyArg
2759
+ ? `Project-local tSDocker release protocol v1 with alias policy ${aliasPolicyArg} is available`
2760
+ : "Project-local tSDocker release protocol v1 is available",
2735
2761
  });
2736
2762
  } catch (error) {
2737
2763
  findings.push({
@@ -34,6 +34,7 @@ import {
34
34
  } from "./helpers.releaseversion.js";
35
35
  import {
36
36
  getReleaseDistTag,
37
+ getReleaseDockerAliasPolicy,
37
38
  parseReleaseLine,
38
39
  type IReleaseLine,
39
40
  } from "./helpers.releaseline.js";
@@ -669,8 +670,8 @@ const assertPreviousLatest = (
669
670
  };
670
671
 
671
672
  /**
672
- * A release line publishes only to Git and npm: Docker aliases and Gitea's
673
- * latest release follow their own rules, which a line must not move.
673
+ * A release line never publishes Gitea assets: Gitea marks its newest release
674
+ * as the latest one, which a line must not move.
674
675
  */
675
676
  const assertNoReleaseLine = (
676
677
  valueArg: Record<string, unknown>,
@@ -970,6 +971,16 @@ const assertDockerJournal = (
970
971
  "Release journal Docker request does not match the release.",
971
972
  );
972
973
  }
974
+ // A line qualified its images under tSDocker's release-version alias policy;
975
+ // a main release keeps every configured tag.
976
+ if (
977
+ request.options.aliasPolicy !==
978
+ getReleaseDockerAliasPolicy(releaseArg.line)
979
+ ) {
980
+ throw new Error(
981
+ "Release journal Docker alias policy does not match the release line.",
982
+ );
983
+ }
973
984
 
974
985
  assertExactKeys(
975
986
  valueArg.qualification,
@@ -1125,7 +1136,6 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1125
1136
  if (!isPlainObject(valueArg)) {
1126
1137
  throw new Error("Release journal root must be a JSON object.");
1127
1138
  }
1128
- assertNoReleaseLine(valueArg, 2);
1129
1139
  const hasPackages = Object.hasOwn(valueArg, "packages");
1130
1140
  assertExactKeys(
1131
1141
  valueArg,
@@ -1969,12 +1979,9 @@ export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
1969
1979
  const release = assertReleaseIdentity(valueArg.release);
1970
1980
  const plan = assertReleaseIntentPlan(valueArg.plan);
1971
1981
  const git = assertReleaseIntentGit(valueArg.git);
1972
- if (
1973
- release.line &&
1974
- (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
1975
- ) {
1982
+ if (release.line && plan.targets.includes("giteaAssets")) {
1976
1983
  throw new Error(
1977
- "A release line publishes only to Git and npm; its intent cannot name Docker or Gitea assets.",
1984
+ "A release line never publishes Gitea assets; its intent cannot name them.",
1978
1985
  );
1979
1986
  }
1980
1987
  if (plan.targets.includes("git") !== (git !== null)) {
@@ -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,
@@ -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
  }
@@ -79,6 +79,7 @@ import {
79
79
  assertReleaseLineVersion,
80
80
  findDistTagPublicationRefusal,
81
81
  getReleaseDistTag,
82
+ getReleaseDockerAliasPolicy,
82
83
  isSameReleaseLine,
83
84
  latestDistTag,
84
85
  type IReleaseLine,
@@ -104,10 +105,12 @@ import {
104
105
  } from "./helpers.releasepreparation.js";
105
106
  import {
106
107
  TsdockerReleaseClient,
108
+ TsdockerReleaseCommandError,
107
109
  canonicalReleaseJson,
108
110
  createReleaseQualificationRequest,
109
111
  type ITsdockerReleaseClient,
110
112
  type IReleaseQualificationRequest,
113
+ type IReleaseValidationResult,
111
114
  } from "./helpers.tsdockerprotocol.js";
112
115
  import {
113
116
  assertResolvedCurrentVersion,
@@ -242,7 +245,12 @@ const runInternal = async (argvArg: any): Promise<void> => {
242
245
  versionResolution.currentVersion,
243
246
  versionResolution.version,
244
247
  );
245
- await printReleasePlan(workflow, branchContext, versionResolution);
248
+ await printReleasePlan(
249
+ smartshellInstance,
250
+ workflow,
251
+ branchContext,
252
+ versionResolution,
253
+ );
246
254
  if (workflow.confirmation === "plan") {
247
255
  return;
248
256
  }
@@ -536,7 +544,9 @@ const assertFreshReleaseCapabilities = async (
536
544
  if (!tsdockerArg) {
537
545
  throw new Error("Docker release target requires project-local tSDocker.");
538
546
  }
539
- await tsdockerArg.assertCapabilities();
547
+ await tsdockerArg.assertCapabilities(
548
+ getReleaseDockerAliasPolicy(workflowArg.line),
549
+ );
540
550
  }
541
551
  if (workflowArg.targets.includes("git") && !pushUrlArg) {
542
552
  throw new Error(
@@ -684,6 +694,7 @@ const createDockerQualificationRequest = (
684
694
  revisionArg: string,
685
695
  ): IReleaseQualificationRequest =>
686
696
  createReleaseQualificationRequest({
697
+ aliasPolicy: getReleaseDockerAliasPolicy(workflowArg.line),
687
698
  buildRegistries: workflowArg.dockerBuildRegistries,
688
699
  cached: workflowArg.dockerCached,
689
700
  context: workflowArg.dockerContext,
@@ -793,7 +804,9 @@ const prepareTaggedRelease = async (
793
804
  const tsdocker = workflow.targets.includes("docker")
794
805
  ? new TsdockerReleaseClient(smartshell, releaseCwd)
795
806
  : undefined;
796
- await tsdocker?.assertCapabilities();
807
+ await tsdocker?.assertCapabilities(
808
+ getReleaseDockerAliasPolicy(workflow.line),
809
+ );
797
810
  const journalOptions: ICreateReleaseJournalOptions = {
798
811
  ...optionsArg,
799
812
  dockerRequest: tsdocker
@@ -1637,6 +1650,7 @@ const runReleaseResume = async (
1637
1650
  );
1638
1651
  }
1639
1652
  const currentRequest = createReleaseQualificationRequest({
1653
+ aliasPolicy: getReleaseDockerAliasPolicy(resumeConfiguration.line),
1640
1654
  buildRegistries: dockerConfiguration.dockerBuildRegistries,
1641
1655
  cached: dockerConfiguration.dockerCached,
1642
1656
  context: dockerConfiguration.dockerContext,
@@ -1657,7 +1671,9 @@ const runReleaseResume = async (
1657
1671
  );
1658
1672
  }
1659
1673
  tsdocker = new TsdockerReleaseClient(smartshellInstance, paths.cwd);
1660
- await tsdocker.assertCapabilities();
1674
+ await tsdocker.assertCapabilities(
1675
+ journal.docker.request.options.aliasPolicy,
1676
+ );
1661
1677
  await tsdocker.validate(journal.docker.request);
1662
1678
  }
1663
1679
  let pnpmCapability: IPnpmReleaseCapability | undefined;
@@ -2382,7 +2398,61 @@ const describeReleaseLineDistTags = async (
2382
2398
  return lines;
2383
2399
  };
2384
2400
 
2401
+ /**
2402
+ * A line's Docker images carry only tags bound to the release version. The
2403
+ * plan asks tSDocker, which owns that rule, for the tags every selected
2404
+ * Dockerfile will publish; tSDocker refuses a tag that floats across versions,
2405
+ * such as `latest`, before anything is created.
2406
+ */
2407
+ const describeReleaseLineDockerImages = async (
2408
+ smartshellArg: plugins.smartshell.Smartshell,
2409
+ workflowArg: IResolvedReleaseWorkflow,
2410
+ branchContextArg: IReleaseBranchContext,
2411
+ versionArg: string,
2412
+ ): Promise<string[]> => {
2413
+ const line = workflowArg.line;
2414
+ if (!line || !workflowArg.targets.includes("docker")) return [];
2415
+ const aliasPolicy = getReleaseDockerAliasPolicy(line);
2416
+ const tsdocker = new TsdockerReleaseClient(
2417
+ smartshellArg,
2418
+ branchContextArg.sourceCwd,
2419
+ );
2420
+ await tsdocker.assertCapabilities(aliasPolicy);
2421
+ let validation: IReleaseValidationResult;
2422
+ try {
2423
+ validation = await tsdocker.validate(
2424
+ createDockerQualificationRequest(
2425
+ workflowArg,
2426
+ branchContextArg.sourceCwd,
2427
+ versionArg,
2428
+ branchContextArg.sourceOid,
2429
+ ),
2430
+ );
2431
+ } catch (error) {
2432
+ if (error instanceof TsdockerReleaseCommandError) {
2433
+ throw new Error(
2434
+ `Release line ${line.distTag} publishes Docker images only under tags bound to ${versionArg}, and tSDocker refused the release (${error.code}): ${error.message}`,
2435
+ { cause: error },
2436
+ );
2437
+ }
2438
+ throw error;
2439
+ }
2440
+ if (!validation.images) {
2441
+ throw new Error(
2442
+ `tSDocker did not plan the image tags of release line ${line.distTag}.`,
2443
+ );
2444
+ }
2445
+ return [
2446
+ `docker alias policy: ${aliasPolicy} (every tag is bound to ${versionArg}; floating tags such as latest are refused)`,
2447
+ ...validation.images.map(
2448
+ (imageArg) =>
2449
+ `docker image ${imageArg.dockerfile}: ${imageArg.aliases.join(", ")}`,
2450
+ ),
2451
+ ];
2452
+ };
2453
+
2385
2454
  async function printReleasePlan(
2455
+ smartshellArg: plugins.smartshell.Smartshell,
2386
2456
  workflow: IResolvedReleaseWorkflow,
2387
2457
  branchContextArg: IReleaseBranchContext,
2388
2458
  versionResolutionArg: IReleaseVersionResolution,
@@ -2459,6 +2529,13 @@ async function printReleasePlan(
2459
2529
  `docker patterns: ${workflow.dockerPatterns.length > 0 ? workflow.dockerPatterns.join(", ") : "all Dockerfiles"}`,
2460
2530
  );
2461
2531
  console.log(`docker options: ${formatDockerOptions(workflow)}`);
2532
+ for (const line of await describeReleaseLineDockerImages(
2533
+ smartshellArg,
2534
+ workflow,
2535
+ branchContextArg,
2536
+ versionResolutionArg.version,
2537
+ ))
2538
+ console.log(line);
2462
2539
  }
2463
2540
  console.log("");
2464
2541
  }
package/ts/plugins.ts CHANGED
@@ -37,8 +37,10 @@ export type {
37
37
  IReleaseQualificationRequest,
38
38
  IReleaseQualificationResult,
39
39
  IReleaseValidationResult,
40
+ TReleaseAliasPolicy,
40
41
  TReleasePromotionEvidence,
41
42
  TReleaseProtocolCommand,
43
+ TReleaseProtocolFeature,
42
44
  } from '@git.zone/tsdocker/dist_ts/interfaces/index.js';
43
45
 
44
46
  // Create smartfs instance for filesystem operations