@git.zone/cli 8.8.1 → 8.9.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
@@ -369,17 +369,75 @@ When the floor decides the version, the release journal records that decision wi
369
369
 
370
370
  `gitzone release inspect` and `gitzone release resume` print the same `version floor: ... applied` line. The record is part of the journal's immutable identity. `resume` always publishes the journaled version and never resolves a new one. This matters because after the release commit the floor is inert, and a fresh resolution would infer `32.0.1`. `recover` takes its version from the existing tag and writes no floor record, because the failed run did not record its level override.
371
371
 
372
- The floor must be a canonical `x.y.z` string whose components do not exceed `9007199254740991`. Every rejection throws `ReleaseVersionError`, and its `code` names the rule that failed. `malformed-version-floor` and `unsupported-prerelease-floor` are configuration errors that `--plan` and `gitzone config doctor` report. `--plan` and the release raise `noncanonical-version` when the current `package.json` or `deno.json` version is not canonical. `current-version-changed` is raised only while the release runs:
372
+ The floor must be a canonical `x.y.z` string whose components do not exceed `9007199254740991`, except for a matching [prerelease channel](#prerelease-channels-on-main). Every rejection throws `ReleaseVersionError`, and its `code` names the rule that failed. `malformed-version-floor` and `unsupported-prerelease-floor` are configuration errors that `--plan` and `gitzone config doctor` report. `--plan` and the release raise `noncanonical-version` when the current `package.json` or `deno.json` version is not canonical. `current-version-changed` is raised only while the release runs:
373
373
 
374
374
  | Code | Cause |
375
375
  | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
376
376
  | `malformed-version-floor` | Anything else, such as `"32"`, `"v32.0.0"`, `null`, a number, or a component above `9007199254740991` |
377
- | `unsupported-prerelease-floor` | A prerelease or build suffix such as `"32.0.0-rc.1"`; GitZone releases only canonical versions |
377
+ | `unsupported-prerelease-floor` | A prerelease or build suffix without a matching configured prerelease channel |
378
+ | `invalid-prerelease-config` | A malformed channel, mismatched or missing prerelease floor, forbidden dist-tag or version-level override |
378
379
  | `noncanonical-version` | A floor is configured but the current `package.json` or `deno.json` version is not a canonical `x.y.z` version to compare against |
379
380
  | `current-version-changed` | The release checkout's `package.json` or `deno.json` version differs from the version the release was resolved from |
380
381
 
381
382
  `gitzone config show` lists the configured floor.
382
383
 
384
+ ### Prerelease channels on main
385
+
386
+ A committed prerelease channel publishes a new version, including a newer major,
387
+ from integrated `main` under a non-`latest` npm dist-tag. For example, to release
388
+ version 6 while stable consumers remain on version 5:
389
+
390
+ ```json
391
+ {
392
+ "@git.zone/cli": {
393
+ "release": {
394
+ "versionFloor": "6.0.0-beta.0",
395
+ "prerelease": { "identifier": "beta", "distTag": "beta" }
396
+ }
397
+ }
398
+ }
399
+ ```
400
+
401
+ Use `gitzone release --plan`, then `gitzone release -y`. Starting from `5.1.2`,
402
+ this releases `6.0.0-beta.0`; subsequent releases become `6.0.0-beta.1`,
403
+ `6.0.0-beta.2`, and so on, regardless of the Pending changelog's semver level.
404
+ `--major`, `--minor`, and `--patch` are rejected while the channel is configured.
405
+ Raising the floor selects a higher sequence or a newer version core; a floor
406
+ cannot lower the current core. Components and the sequence must be safe integers.
407
+ The plan and `gitzone config doctor` validate the channel and its floor.
408
+
409
+ Keep both settings throughout the beta. The required matching
410
+ `x.y.z-identifier.N` floor makes earlier GitZone releases, including 8.8.2,
411
+ reject the release before creating metadata instead of ignoring an unknown
412
+ channel and publishing `latest`. Identifiers and dist-tags use lowercase letters
413
+ and digits separated by hyphens and start with a letter. Dist-tags cannot be
414
+ `latest` or a semver range. Prerelease channels and maintenance lines are
415
+ mutually exclusive, and prereleases release `main` in place without `--merge`.
416
+
417
+ Every selected registry must already have a stable `latest` below the prerelease
418
+ core. The channel's tag must be absent or point to an equal or earlier prerelease
419
+ of the same identifier. Publication always passes `--tag=beta` in this example;
420
+ there is no flag that overrides the committed channel. Verification proves the
421
+ exact artifact and the channel tag (or a later sequence of the same core and
422
+ identifier), and rejects a prerelease taking `latest`. The journal records the
423
+ stable `latest` found before publication. A registry conflict stops the release;
424
+ GitZone never repairs dist-tags automatically.
425
+
426
+ The identifier, dist-tag, and configured floor are part of the immutable release
427
+ intent and journal. `resume` refuses changed channel configuration and resumes
428
+ the recorded version. Accepted uploads are verified without publishing again.
429
+ Use `gitzone release resume 6.0.0-beta.0 -y` after an interruption; unjournaled
430
+ prerelease `recover` is rejected because it cannot prove the original channel.
431
+ Git and npm targets are supported. Docker and Gitea asset targets are explicitly
432
+ rejected in `--plan` and before any release side effects; disable those targets
433
+ before configuring a prerelease channel.
434
+
435
+ To promote `6.0.0-beta.N` to `6.0.0`, remove both `release.prerelease` and its
436
+ prerelease `release.versionFloor` in a reviewed commit, add the Pending release
437
+ entry, and run the normal release flow. That explicit removal promotes the exact
438
+ version core, without a semver-level flag. Leaving the channel configured always
439
+ produces another prerelease.
440
+
383
441
  ### Maintenance lines
384
442
 
385
443
  A maintenance line releases an older major from its own branch under its own
@@ -2366,15 +2424,24 @@ a remote that is down fails the release before a long test run; the check
2366
2424
  immediately before the push stays authoritative.
2367
2425
 
2368
2426
  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
2427
+ does not end a release. A timeout, an ssh connection closed by the remote host
2428
+ (`Connection to <host> closed by remote host.`, `Connection closed by <address>
2429
+ port <n>`, `kex_exchange_identification: Connection closed by remote host`) or
2430
+ refused by it (`ssh: connect to host <host> port <n>: Connection refused`), a
2431
+ reset, timed-out or unexpectedly ended connection (`Connection reset by
2432
+ <address> port <n>`, `Connection timed out during banner exchange`,
2433
+ `send-pack: unexpected disconnect while reading sideband packet`), and an HTTP
2434
+ gateway error (502, 503, 504) count as transient; refused authentication,
2435
+ denied permission, a missing repository, a rejected update and Git's own
2436
+ answers are final at once. A refused connection is retried because a
2437
+ restarting or overloaded server refuses too; a wrong port therefore fails only
2438
+ once the attempts run out. Remote reads (`ls-remote`, and `fetch` for
2439
+ inspection or verification) are simply repeated. A push is never repeated
2440
+ blindly: after a transient failure gitzone reads the remote again, and that
2441
+ read is retried like any other. When the pushed refs are already there, the
2442
+ push is done; when the remote is unchanged, it pushes again under the same
2443
+ lease; when the read still fails after all its attempts, or finds other refs,
2444
+ it stops and the usual verification decides. Each push of the Git
2378
2445
  target is journaled as its own attempt. A step makes at most eight attempts,
2379
2446
  waiting 2, 4, 8 and 16 s and then 30 s three times, two minutes in all. Every
2380
2447
  retry is logged as a warning that names the step, the command, the classified
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '8.8.1',
6
+ version: '8.9.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
  }
@@ -5,7 +5,13 @@ import {
5
5
  projectTypeHasPackageJson,
6
6
  type ProjectType,
7
7
  } from "./mod_commit/mod.helpers.js";
8
- import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
8
+ import {
9
+ parseReleaseVersionFloor,
10
+ parseReleasePrerelease,
11
+ toReleasePrereleaseRecord,
12
+ type IReleasePrerelease,
13
+ type IReleasePrereleaseRecord,
14
+ } from "./mod_release/helpers.releaseversion.js";
9
15
  import {
10
16
  getReleaseDistTag,
11
17
  parseReleaseLine,
@@ -269,8 +275,9 @@ export interface IReleaseWorkflowConfig {
269
275
  strategy?: "semver";
270
276
  source?: "pendingChangelog" | "manual";
271
277
  };
272
- /** Canonical x.y.z minimum for the next release version. */
278
+ /** Canonical minimum, or the required matching identifier.N prerelease guard. */
273
279
  versionFloor?: string;
280
+ prerelease?: IReleasePrerelease;
274
281
  /**
275
282
  * A maintenance line, committed on its branch: that branch becomes the
276
283
  * release source, and npm publishes under `distTag` instead of `latest`.
@@ -323,9 +330,10 @@ export interface IResolvedReleaseWorkflow {
323
330
  changelogPendingSection: "Pending";
324
331
  changelogVersionHeading: "## {{date}} - {{version}}";
325
332
  versionFloor?: string;
333
+ prerelease?: IReleasePrerelease;
326
334
  /** The maintenance line this branch releases; absent releases `main`. */
327
335
  line?: IReleaseLine;
328
- /** `latest`, or the dist-tag of the release line. */
336
+ /** `latest`, or the dist-tag of the maintenance line or prerelease channel. */
329
337
  npmDistTag: string;
330
338
  gitEnabled: boolean;
331
339
  gitRemote: string;
@@ -372,6 +380,7 @@ export type TReleaseRecordedPlan = Pick<
372
380
 
373
381
  export interface IResolvedReleaseResumeConfiguration {
374
382
  line?: IReleaseLine;
383
+ prerelease?: IReleasePrereleaseRecord;
375
384
  gitRemote: string;
376
385
  gitRemoteTimeoutSeconds: number;
377
386
  npmRegistries: string[];
@@ -1065,8 +1074,16 @@ export const resolveReleaseWorkflow = async (
1065
1074
  ): Promise<IResolvedReleaseWorkflow> => {
1066
1075
  const cliConfig = await readCliWorkflowConfig();
1067
1076
  const releaseConfig = cliConfig.release || {};
1068
- const versionFloor = parseReleaseVersionFloor(releaseConfig.versionFloor);
1077
+ const prerelease = parseReleasePrerelease(releaseConfig.prerelease);
1078
+ const versionFloor = parseReleaseVersionFloor(
1079
+ releaseConfig.versionFloor,
1080
+ prerelease,
1081
+ );
1069
1082
  const line = parseReleaseLine(releaseConfig.line);
1083
+ if (prerelease && line)
1084
+ throw new Error(
1085
+ "release.prerelease and release.line are mutually exclusive.",
1086
+ );
1070
1087
  const targetConfig = releaseConfig.targets || {};
1071
1088
  const gitConfig = targetConfig.git || {};
1072
1089
  const npmConfig = targetConfig.npm || {};
@@ -1157,6 +1174,17 @@ export const resolveReleaseWorkflow = async (
1157
1174
  );
1158
1175
  }
1159
1176
  assertReleaseLineTargets(line, targets, argvArg.merge === true);
1177
+ if (
1178
+ prerelease &&
1179
+ (targets.includes("docker") || targets.includes("giteaAssets"))
1180
+ )
1181
+ throw new Error(
1182
+ "Prerelease channels support Git and npm targets; Docker and Gitea assets are not supported and must be disabled before releasing.",
1183
+ );
1184
+ if (prerelease && argvArg.merge === true)
1185
+ throw new Error(
1186
+ "Prerelease channels release integrated main in place; --merge is not supported.",
1187
+ );
1160
1188
  let npmRegistries: string[] = [];
1161
1189
  if (targets.includes("npm")) {
1162
1190
  if (
@@ -1236,8 +1264,9 @@ export const resolveReleaseWorkflow = async (
1236
1264
  changelogPendingSection: "Pending",
1237
1265
  changelogVersionHeading: "## {{date}} - {{version}}",
1238
1266
  ...(versionFloor ? { versionFloor } : {}),
1267
+ ...(prerelease ? { prerelease } : {}),
1239
1268
  ...(line ? { line } : {}),
1240
- npmDistTag: getReleaseDistTag(line),
1269
+ npmDistTag: prerelease?.distTag ?? getReleaseDistTag(line),
1241
1270
  gitEnabled,
1242
1271
  gitRemote: gitConfig.remote || "origin",
1243
1272
  // Dormant settings of an inactive target are not validated.
@@ -1281,6 +1310,14 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1281
1310
  const cliConfig = await readCliWorkflowConfig();
1282
1311
  const releaseConfig = cliConfig.release || {};
1283
1312
  const line = parseReleaseLine(releaseConfig.line);
1313
+ const prerelease = toReleasePrereleaseRecord(
1314
+ parseReleasePrerelease(releaseConfig.prerelease),
1315
+ releaseConfig.versionFloor,
1316
+ );
1317
+ if (prerelease && line)
1318
+ throw new Error(
1319
+ "release.prerelease and release.line are mutually exclusive.",
1320
+ );
1284
1321
  const targetConfig = releaseConfig.targets || {};
1285
1322
  const gitConfig = targetConfig.git || {};
1286
1323
  const npmConfig = targetConfig.npm || {};
@@ -1345,6 +1382,7 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1345
1382
 
1346
1383
  return {
1347
1384
  ...(line ? { line } : {}),
1385
+ ...(prerelease ? { prerelease } : {}),
1348
1386
  gitRemote,
1349
1387
  gitRemoteTimeoutSeconds: optionsArg.git
1350
1388
  ? resolveGitRemoteTimeoutSeconds(gitConfig.remoteTimeoutSeconds)
@@ -40,6 +40,8 @@ import {
40
40
  import {
41
41
  ReleaseVersionError,
42
42
  parseReleaseVersionFloor,
43
+ parseReleasePrerelease,
44
+ type IReleasePrerelease,
43
45
  } from "../mod_release/helpers.releaseversion.js";
44
46
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
45
47
  import {
@@ -317,11 +319,17 @@ async function handleShow(mode: ICliMode): Promise<void> {
317
319
  printConfigSection("Release Workflow", [
318
320
  ["confirmation", formatValue(release.confirmation)],
319
321
  ["version floor", formatValue(release.versionFloor)],
322
+ [
323
+ "prerelease channel",
324
+ release.prerelease
325
+ ? `${formatValue(release.prerelease.identifier)} -> npm dist-tag ${formatValue(release.prerelease.distTag)}`
326
+ : "not configured",
327
+ ],
320
328
  [
321
329
  "release line",
322
330
  release.line
323
331
  ? `${formatValue(release.line.branch)} -> npm dist-tag ${formatValue(release.line.distTag)}`
324
- : "main (npm dist-tag latest)",
332
+ : `main (npm dist-tag ${release.prerelease?.distTag || "latest"})`,
325
333
  ],
326
334
  ["clean tree", "required"],
327
335
  ["run tests", formatValue(release.preflight?.test)],
@@ -1980,11 +1988,41 @@ async function validateReleaseConfig(
1980
1988
  });
1981
1989
  }
1982
1990
 
1983
- findings.push(validateReleaseVersionFloor(releaseConfig.versionFloor));
1991
+ let prerelease: IReleasePrerelease | undefined;
1992
+ try {
1993
+ prerelease = parseReleasePrerelease(releaseConfig.prerelease);
1994
+ if (prerelease && releaseConfig.line !== undefined)
1995
+ throw new Error(
1996
+ "release.prerelease and release.line are mutually exclusive.",
1997
+ );
1998
+ if (
1999
+ prerelease &&
2000
+ (releaseConfig.targets?.docker?.enabled === true ||
2001
+ releaseConfig.targets?.giteaAssets?.enabled === true)
2002
+ )
2003
+ throw new Error(
2004
+ "Prerelease channels support Git and npm targets; Docker and Gitea assets must be disabled.",
2005
+ );
2006
+ if (prerelease)
2007
+ findings.push({
2008
+ level: "ok",
2009
+ message: `Prerelease channel ${prerelease.identifier} releases main under npm dist-tag ${prerelease.distTag}; latest is never moved`,
2010
+ });
2011
+ } catch (error) {
2012
+ findings.push({
2013
+ level: "error",
2014
+ message: error instanceof Error ? error.message : String(error),
2015
+ fix: 'Set release.prerelease to { "identifier": "beta", "distTag": "beta" } with a matching prerelease floor, or remove both settings.',
2016
+ });
2017
+ }
2018
+ findings.push(
2019
+ validateReleaseVersionFloor(releaseConfig.versionFloor, prerelease),
2020
+ );
1984
2021
  const line = validateReleaseLine(
1985
2022
  releaseConfig.line,
1986
2023
  releaseConfig.targets,
1987
2024
  findings,
2025
+ prerelease,
1988
2026
  );
1989
2027
 
1990
2028
  if (
@@ -2064,9 +2102,12 @@ async function validateReleaseConfig(
2064
2102
  );
2065
2103
  }
2066
2104
 
2067
- function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
2105
+ function validateReleaseVersionFloor(
2106
+ valueArg: unknown,
2107
+ prereleaseArg?: IReleasePrerelease,
2108
+ ): IDoctorFinding {
2068
2109
  try {
2069
- const versionFloor = parseReleaseVersionFloor(valueArg);
2110
+ const versionFloor = parseReleaseVersionFloor(valueArg, prereleaseArg);
2070
2111
  return {
2071
2112
  level: "ok",
2072
2113
  message: versionFloor
@@ -2088,6 +2129,7 @@ function validateReleaseLine(
2088
2129
  valueArg: unknown,
2089
2130
  targetsArg: unknown,
2090
2131
  findings: IDoctorFinding[],
2132
+ prereleaseArg?: IReleasePrerelease,
2091
2133
  ): IReleaseLine | undefined {
2092
2134
  let line: IReleaseLine | undefined;
2093
2135
  try {
@@ -2103,7 +2145,9 @@ function validateReleaseLine(
2103
2145
  if (!line) {
2104
2146
  findings.push({
2105
2147
  level: "ok",
2106
- message: "Release line is not configured; releases run from main under latest",
2148
+ message: prereleaseArg
2149
+ ? `Release line is not configured; releases run from main under ${prereleaseArg.distTag}`
2150
+ : "Release line is not configured; releases run from main under latest",
2107
2151
  });
2108
2152
  return undefined;
2109
2153
  }
@@ -30,6 +30,12 @@ import {
30
30
  compareReleaseVersions,
31
31
  isCanonicalReleaseVersion,
32
32
  releaseVersionMajor,
33
+ isSupportedReleaseVersion,
34
+ compareSupportedReleaseVersions,
35
+ parsePrereleaseVersion,
36
+ parseReleasePrerelease,
37
+ toReleasePrereleaseRecord,
38
+ type IReleasePrereleaseRecord,
33
39
  type IReleaseVersionFloorRecord,
34
40
  } from "./helpers.releaseversion.js";
35
41
  import {
@@ -115,8 +121,8 @@ export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
115
121
  registry: string;
116
122
  packageName?: string;
117
123
  /**
118
- * A release line records the `latest` version it found when it claimed the
119
- * publication, so a line that took `latest` names the exact restore command.
124
+ * A maintenance or prerelease channel records the stable `latest` it found
125
+ * when it claimed publication, so a conflict names the exact restore command.
120
126
  */
121
127
  previousLatest?: string;
122
128
  }
@@ -131,6 +137,8 @@ export interface IReleaseIdentity {
131
137
  versionFloor?: IReleaseVersionFloorRecord;
132
138
  /** Present only for a maintenance line release; absent means `main` and `latest`. */
133
139
  line?: IReleaseLine;
140
+ /** Committed main prerelease channel and floor, immutable across resume. */
141
+ prerelease?: IReleasePrereleaseRecord;
134
142
  }
135
143
 
136
144
  export interface IReleaseJournalV1 {
@@ -142,7 +150,7 @@ export interface IReleaseJournalV1 {
142
150
  git: IReleaseGitJournal;
143
151
  npm: {
144
152
  access: TReleaseNpmAccess;
145
- /** `latest`, or the dist-tag of the journaled release line. */
153
+ /** `latest`, or the dist-tag of the journaled maintenance or prerelease channel. */
146
154
  tag: string;
147
155
  alreadyPublished: "success" | "error";
148
156
  registries: IReleaseNpmRegistryJournal[];
@@ -185,7 +193,7 @@ export interface IReleaseJournalV2 {
185
193
  git: IReleaseGitJournal;
186
194
  npm: {
187
195
  access: TReleaseNpmAccess;
188
- /** `latest`, or the dist-tag of the journaled release line. */
196
+ /** `latest`, or the dist-tag of the journaled maintenance or prerelease channel. */
189
197
  tag: string;
190
198
  alreadyPublished: "success" | "error";
191
199
  registries: IReleaseNpmRegistryJournal[];
@@ -353,9 +361,9 @@ const assertIsoTimestamp = (valueArg: unknown, contextArg: string): string => {
353
361
 
354
362
  export const normalizeReleaseVersion = (valueArg: string): string => {
355
363
  const version = valueArg.startsWith("v") ? valueArg.slice(1) : valueArg;
356
- if (!isCanonicalReleaseVersion(version)) {
364
+ if (!isSupportedReleaseVersion(version)) {
357
365
  throw new Error(
358
- "Release journal versions must use canonical x.y.z semver.",
366
+ "Release journal versions must use canonical x.y.z or x.y.z-identifier.N semver.",
359
367
  );
360
368
  }
361
369
  return version;
@@ -613,8 +621,8 @@ const assertVersionFloorRecord = (
613
621
  if (
614
622
  typeof valueArg.floor !== "string" ||
615
623
  typeof valueArg.inferredVersion !== "string" ||
616
- !isCanonicalReleaseVersion(valueArg.floor) ||
617
- !isCanonicalReleaseVersion(valueArg.inferredVersion)
624
+ !isSupportedReleaseVersion(valueArg.floor) ||
625
+ !isSupportedReleaseVersion(valueArg.inferredVersion)
618
626
  ) {
619
627
  throw new Error(
620
628
  "Release journal version floor must record canonical x.y.z versions.",
@@ -622,7 +630,8 @@ const assertVersionFloorRecord = (
622
630
  }
623
631
  if (
624
632
  valueArg.floor !== versionArg ||
625
- compareReleaseVersions(valueArg.inferredVersion, valueArg.floor) >= 0
633
+ compareSupportedReleaseVersions(valueArg.inferredVersion, valueArg.floor) >=
634
+ 0
626
635
  ) {
627
636
  throw new Error(
628
637
  "Release journal version floor must equal the release version and exceed the inferred version.",
@@ -655,16 +664,19 @@ const assertPreviousLatest = (
655
664
  contextArg: string,
656
665
  ): void => {
657
666
  const previousLatest = registryArg.previousLatest;
667
+ const prerelease = parsePrereleaseVersion(releaseArg.version);
658
668
  if (
659
- !releaseArg.line ||
669
+ (!releaseArg.line && !releaseArg.prerelease) ||
660
670
  typeof previousLatest !== "string" ||
661
671
  !isCanonicalReleaseVersion(previousLatest) ||
662
- releaseVersionMajor(previousLatest) <=
663
- releaseVersionMajor(releaseArg.version) ||
672
+ (prerelease
673
+ ? compareReleaseVersions(previousLatest, prerelease.core) >= 0
674
+ : releaseVersionMajor(previousLatest) <=
675
+ releaseVersionMajor(releaseArg.version)) ||
664
676
  registryArg.attempts === 0
665
677
  ) {
666
678
  throw new Error(
667
- `${contextArg}.previousLatest must record the higher-major latest version a release line found when it claimed the publication.`,
679
+ `${contextArg}.previousLatest must record the stable latest version admitted by the release channel when it claimed the publication.`,
668
680
  );
669
681
  }
670
682
  };
@@ -681,6 +693,13 @@ const assertNoReleaseLine = (
681
693
  throw new Error(
682
694
  `Release journal schema ${schemaArg} cannot carry a release line.`,
683
695
  );
696
+ if (
697
+ isPlainObject(valueArg.release) &&
698
+ Object.hasOwn(valueArg.release, "prerelease")
699
+ )
700
+ throw new Error(
701
+ `Release journal schema ${schemaArg} cannot carry a prerelease channel.`,
702
+ );
684
703
  };
685
704
 
686
705
  const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
@@ -689,16 +708,60 @@ const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
689
708
  }
690
709
  const hasVersionFloor = Object.hasOwn(valueArg, "versionFloor");
691
710
  const hasLine = Object.hasOwn(valueArg, "line");
711
+ const hasPrerelease = Object.hasOwn(valueArg, "prerelease");
692
712
  assertExactKeys(
693
713
  valueArg,
694
714
  [
695
715
  ...releaseIdentityKeys,
696
716
  ...(hasVersionFloor ? ["versionFloor"] : []),
697
717
  ...(hasLine ? ["line"] : []),
718
+ ...(hasPrerelease ? ["prerelease"] : []),
698
719
  ],
699
720
  "Release journal release",
700
721
  );
701
722
  if (hasLine) assertReleaseLineRecord(valueArg.line);
723
+ if (hasLine && hasPrerelease)
724
+ throw new Error(
725
+ "Release journal cannot combine a maintenance line with a prerelease channel.",
726
+ );
727
+ const parsedVersion =
728
+ typeof valueArg.version === "string"
729
+ ? parsePrereleaseVersion(valueArg.version)
730
+ : undefined;
731
+ if (hasPrerelease !== (parsedVersion !== undefined))
732
+ throw new Error(
733
+ "Release journal prerelease versions require an immutable prerelease channel identity.",
734
+ );
735
+ if (hasPrerelease) {
736
+ if (!isPlainObject(valueArg.prerelease))
737
+ throw new Error("Release journal prerelease identity is missing.");
738
+ assertExactKeys(
739
+ valueArg.prerelease,
740
+ ["identifier", "distTag", "versionFloor"],
741
+ "Release journal prerelease identity",
742
+ );
743
+ const channel = parseReleasePrerelease({
744
+ identifier: valueArg.prerelease.identifier,
745
+ distTag: valueArg.prerelease.distTag,
746
+ });
747
+ const record = toReleasePrereleaseRecord(
748
+ channel,
749
+ typeof valueArg.prerelease.versionFloor === "string"
750
+ ? valueArg.prerelease.versionFloor
751
+ : undefined,
752
+ );
753
+ if (
754
+ !record ||
755
+ record.identifier !== parsedVersion?.identifier ||
756
+ compareSupportedReleaseVersions(
757
+ record.versionFloor,
758
+ valueArg.version as string,
759
+ ) > 0
760
+ )
761
+ throw new Error(
762
+ "Release journal prerelease channel does not match its version or floor.",
763
+ );
764
+ }
702
765
  if (
703
766
  typeof valueArg.version !== "string" ||
704
767
  normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
@@ -803,7 +866,8 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
803
866
  );
804
867
  if (
805
868
  (valueArg.npm.access !== "public" && valueArg.npm.access !== "private") ||
806
- valueArg.npm.tag !== getReleaseDistTag(release.line) ||
869
+ valueArg.npm.tag !==
870
+ (release.prerelease?.distTag ?? getReleaseDistTag(release.line)) ||
807
871
  (valueArg.npm.alreadyPublished !== "success" &&
808
872
  valueArg.npm.alreadyPublished !== "error") ||
809
873
  !Array.isArray(valueArg.npm.registries)
@@ -1182,6 +1246,8 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1182
1246
  assertReleaseJournalV1({ ...commonProjection, schemaVersion: 1 });
1183
1247
  }
1184
1248
  const journal = valueArg as unknown as IReleaseJournalV2;
1249
+ if (journal.release.prerelease)
1250
+ throw new Error("Prerelease channels do not support Docker journals.");
1185
1251
  const docker = assertDockerJournal(rawDocker, journal.release);
1186
1252
  const activePublishers = [
1187
1253
  journal.git,
@@ -1979,6 +2045,11 @@ export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
1979
2045
  const release = assertReleaseIdentity(valueArg.release);
1980
2046
  const plan = assertReleaseIntentPlan(valueArg.plan);
1981
2047
  const git = assertReleaseIntentGit(valueArg.git);
2048
+ if (
2049
+ release.prerelease &&
2050
+ (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
2051
+ )
2052
+ throw new Error("Prerelease intents support Git and npm targets only.");
1982
2053
  if (release.line && plan.targets.includes("giteaAssets")) {
1983
2054
  throw new Error(
1984
2055
  "A release line never publishes Gitea assets; its intent cannot name them.",
@@ -2207,7 +2278,9 @@ export class ReleaseJournalStore {
2207
2278
  const versions = entries
2208
2279
  .filter(
2209
2280
  (entryArg) =>
2210
- entryArg.isDirectory() && /^v\d+\.\d+\.\d+$/.test(entryArg.name),
2281
+ entryArg.isDirectory() &&
2282
+ entryArg.name.startsWith("v") &&
2283
+ isSupportedReleaseVersion(entryArg.name.slice(1)),
2211
2284
  )
2212
2285
  .map((entryArg) => entryArg.name.slice(1));
2213
2286
  const journals: TReleaseJournal[] = [];
@@ -47,23 +47,41 @@ interface IGitRemoteFailurePattern {
47
47
  }
48
48
 
49
49
  /**
50
- * Transport failures a later attempt can overcome: the connection dropped,
51
- * was reset or timed out, or an HTTP gateway gave up on a busy server. Git
52
- * adds "Could not read from remote repository" to each of them; on its own
53
- * that line proves nothing and is not listed.
50
+ * Transport failures a later attempt can overcome: the connection was refused,
51
+ * dropped, reset or timed out, or an HTTP gateway gave up on a busy server.
52
+ * Git adds "Could not read from remote repository" to each of them; on its own
53
+ * that line proves nothing and is not listed. The ssh messages are OpenSSH's:
54
+ * `clientloop.c` prints "Connection to <host> closed by remote host.",
55
+ * `packet.c` "Connection closed by <address> port <n>", "Connection reset by
56
+ * <address> port <n>" and "Connection to <address> port <n> timed out",
57
+ * `kex.c` "kex_exchange_identification: Connection closed by remote host",
58
+ * "kex_exchange_identification: read: Connection reset by peer" and
59
+ * "Connection timed out during banner exchange", and `sshconnect.c`
60
+ * "ssh: connect to host <host> port <n>: Connection refused". Git's
61
+ * `sideband.c` prints "send-pack: unexpected disconnect while reading sideband
62
+ * packet".
54
63
  */
55
64
  const transientGitRemoteFailures: readonly IGitRemoteFailurePattern[] = [
56
65
  {
57
66
  reason: "ssh connection closed by the remote host",
58
67
  pattern: /connection to \S+ closed by remote host|connection closed by/i,
59
68
  },
69
+ {
70
+ // A server that is restarting or shedding load refuses the connection
71
+ // before anything is sent; on 2026-10-05 code.foss.global did so between
72
+ // dropped pushes. A wrong port refuses too and fails once the bounded
73
+ // attempts run out.
74
+ reason: "ssh connection refused",
75
+ pattern: /ssh: connect to host \S+ port \d+: connection refused/i,
76
+ },
60
77
  {
61
78
  reason: "connection reset",
62
79
  pattern: /connection reset|reset by peer|ECONNRESET/i,
63
80
  },
64
81
  {
65
82
  reason: "connection timed out",
66
- pattern: /connection timed out|operation timed out|ETIMEDOUT/i,
83
+ pattern:
84
+ /connection timed out|connection to \S+ port \d+ timed out|operation timed out|ETIMEDOUT/i,
67
85
  },
68
86
  { reason: "unexpected disconnect", pattern: /unexpected disconnect/i },
69
87
  {
@@ -199,7 +217,12 @@ export interface IRunGitRemotePushOptions extends IGitRemoteCommandOptions {
199
217
  args: ["push", ...string[]];
200
218
  /** Runs before every attempt, the first included; a journaled push claims its attempt here. */
201
219
  beforeAttempt?: () => Promise<void>;
202
- /** Re-reads the remote after a transient failure, before any further attempt. */
220
+ /**
221
+ * Re-reads the remote after a transient failure, before any further
222
+ * attempt. Its reads go through {@link runGitRemoteRead}, so a dropped read
223
+ * is retried like any other; it answers `unknown` only when that read still
224
+ * failed or found refs that are neither the pushed nor the previous state.
225
+ */
203
226
  reinspect: () => Promise<TGitRemotePushState>;
204
227
  }
205
228