@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
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
 
@@ -2307,23 +2350,39 @@ The error names the step, then the command and how it ended, then the end of
2307
2350
  its error output on one line:
2308
2351
 
2309
2352
  ```text
2310
- Unable to inspect main at the configured Git push destination. Step: publication state check. `git ls-remote` timed out after 180 s and was terminated by SIGTERM; gave up after 3 attempts over 565.2 s
2353
+ Unable to inspect main at the configured Git push destination. Step: publication state check. `git ls-remote` timed out after 180 s and was terminated by SIGTERM; gave up after 8 attempts over 1560.4 s
2311
2354
  ```
2312
2355
 
2356
+ The retries bound each step, not the release: a remote that hangs rather than refusing can hold one
2357
+ `ls-remote` step for about 26 minutes (8 × 180 s plus 120 s of waits) and one fetch or push for about
2358
+ 42 minutes (8 × 300 s plus waits, and a push re-reads the remote between attempts).
2359
+
2313
2360
  Every `git ls-remote` of a release — the preflight before the tests, the check
2314
2361
  after them, the check before each publication step and the Git target's own
2315
2362
  probe — runs under `release.targets.git.remoteTimeoutSeconds` (default 180, at
2316
- most 3600) per attempt. A timeout, a reset or dropped connection, and a transport failure Git reports
2317
- as "RPC failed" (other than HTTP 401, 403 or 404) are retried twice, after 5 and 20 seconds;
2318
- authentication failures, a missing repository and Git's own answers are final
2319
- at once. The error names the release step, the per-attempt bound, and the
2320
- attempts and time spent. The preflight reads the remote before the configured
2321
- tests run, so a remote that is down fails the release before a long test run;
2322
- the check immediately before the push stays authoritative. A failure after the
2323
- release tag is resumable with `gitzone release resume <version> -y`. `git
2324
- fetch` and `git push` keep their five-minute bound. Check the remote with the
2325
- same command, for example `git ls-remote <push-url> refs/heads/main`, and
2326
- retry once it answers promptly. An exit code comes with Git's own message,
2363
+ most 3600) per attempt; `git fetch` and `git push` keep their five-minute bound
2364
+ per attempt. The preflight reads the remote before the configured tests run, so
2365
+ a remote that is down fails the release before a long test run; the check
2366
+ immediately before the push stays authoritative.
2367
+
2368
+ Transient remote failures are retried, so a Git server that drops connections
2369
+ does not end a release. A timeout, an ssh connection closed by the remote host,
2370
+ a reset, timed-out or unexpectedly ended connection, and an HTTP gateway error
2371
+ (502, 503, 504) count as transient; refused authentication, denied permission,
2372
+ a missing repository, a rejected update and Git's own answers are final at
2373
+ once. Remote reads (`ls-remote`, and `fetch` for inspection or verification)
2374
+ are simply repeated. A push is never repeated blindly: after a transient failure
2375
+ gitzone reads the remote again. When the pushed refs are already there, the push
2376
+ is done; when the remote is unchanged, it pushes again under the same lease;
2377
+ otherwise it stops and the usual verification decides. Each push of the Git
2378
+ target is journaled as its own attempt. A step makes at most eight attempts,
2379
+ waiting 2, 4, 8 and 16 s and then 30 s three times, two minutes in all. Every
2380
+ retry is logged as a warning that names the step, the command, the classified
2381
+ reason and the attempt. When the attempts run out, the error names the release
2382
+ step, the per-attempt bound, and the attempts and time spent. A failure after
2383
+ the release tag is resumable with `gitzone release resume <version> -y`. Check
2384
+ the remote with the same command, for example `git ls-remote <push-url>
2385
+ refs/heads/main`, and retry once it answers promptly. An exit code comes with Git's own message,
2327
2386
  such as `does not appear to be a git repository` for a wrong push URL. The
2328
2387
  quoted output is shortened to its last 500 characters, and credentials in URLs
2329
2388
  (`https://user:password@host` becomes `https://***@host`), npm `_authToken`
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '8.7.1',
6
+ version: '8.8.1',
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)) {