@git.zone/cli 8.8.2 → 8.9.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.
package/readme.md CHANGED
@@ -234,6 +234,14 @@ Consequences worth knowing before upgrading:
234
234
  dependency specifier, so a lockfile accepted in preflight is still accepted in
235
235
  the release commit. A project with both a `package.json` and a `deno.json` is
236
236
  an npm project here and owes the same proof.
237
+ - Pnpm commands use the scope carried by the release commit. A repository that
238
+ tracks its own root `pnpm-workspace.yaml` retains that workspace's settings
239
+ and member validation. Otherwise, lockfile verification and checkout
240
+ installation use `--ignore-workspace`. Configured test and build commands
241
+ inherit the repository directory as pnpm's workspace discovery boundary,
242
+ including their nested pnpm processes. An independent repository inside a
243
+ separate parent workspace therefore checks its own committed lockfile without
244
+ installing or validating unrelated repositories.
237
245
  - A Deno-only project — a commit with a `deno.json` and no `package.json` —
238
246
  neither needs a pnpm lockfile nor installs anything: its checkout runs the
239
247
  configured build and test commands against the committed tree, and pinning
@@ -369,17 +377,75 @@ When the floor decides the version, the release journal records that decision wi
369
377
 
370
378
  `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
379
 
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:
380
+ 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
381
 
374
382
  | Code | Cause |
375
383
  | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
376
384
  | `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 |
385
+ | `unsupported-prerelease-floor` | A prerelease or build suffix without a matching configured prerelease channel |
386
+ | `invalid-prerelease-config` | A malformed channel, mismatched or missing prerelease floor, forbidden dist-tag or version-level override |
378
387
  | `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
388
  | `current-version-changed` | The release checkout's `package.json` or `deno.json` version differs from the version the release was resolved from |
380
389
 
381
390
  `gitzone config show` lists the configured floor.
382
391
 
392
+ ### Prerelease channels on main
393
+
394
+ A committed prerelease channel publishes a new version, including a newer major,
395
+ from integrated `main` under a non-`latest` npm dist-tag. For example, to release
396
+ version 6 while stable consumers remain on version 5:
397
+
398
+ ```json
399
+ {
400
+ "@git.zone/cli": {
401
+ "release": {
402
+ "versionFloor": "6.0.0-beta.0",
403
+ "prerelease": { "identifier": "beta", "distTag": "beta" }
404
+ }
405
+ }
406
+ }
407
+ ```
408
+
409
+ Use `gitzone release --plan`, then `gitzone release -y`. Starting from `5.1.2`,
410
+ this releases `6.0.0-beta.0`; subsequent releases become `6.0.0-beta.1`,
411
+ `6.0.0-beta.2`, and so on, regardless of the Pending changelog's semver level.
412
+ `--major`, `--minor`, and `--patch` are rejected while the channel is configured.
413
+ Raising the floor selects a higher sequence or a newer version core; a floor
414
+ cannot lower the current core. Components and the sequence must be safe integers.
415
+ The plan and `gitzone config doctor` validate the channel and its floor.
416
+
417
+ Keep both settings throughout the beta. The required matching
418
+ `x.y.z-identifier.N` floor makes earlier GitZone releases, including 8.8.2,
419
+ reject the release before creating metadata instead of ignoring an unknown
420
+ channel and publishing `latest`. Identifiers and dist-tags use lowercase letters
421
+ and digits separated by hyphens and start with a letter. Dist-tags cannot be
422
+ `latest` or a semver range. Prerelease channels and maintenance lines are
423
+ mutually exclusive, and prereleases release `main` in place without `--merge`.
424
+
425
+ Every selected registry must already have a stable `latest` below the prerelease
426
+ core. The channel's tag must be absent or point to an equal or earlier prerelease
427
+ of the same identifier. Publication always passes `--tag=beta` in this example;
428
+ there is no flag that overrides the committed channel. Verification proves the
429
+ exact artifact and the channel tag (or a later sequence of the same core and
430
+ identifier), and rejects a prerelease taking `latest`. The journal records the
431
+ stable `latest` found before publication. A registry conflict stops the release;
432
+ GitZone never repairs dist-tags automatically.
433
+
434
+ The identifier, dist-tag, and configured floor are part of the immutable release
435
+ intent and journal. `resume` refuses changed channel configuration and resumes
436
+ the recorded version. Accepted uploads are verified without publishing again.
437
+ Use `gitzone release resume 6.0.0-beta.0 -y` after an interruption; unjournaled
438
+ prerelease `recover` is rejected because it cannot prove the original channel.
439
+ Git and npm targets are supported. Docker and Gitea asset targets are explicitly
440
+ rejected in `--plan` and before any release side effects; disable those targets
441
+ before configuring a prerelease channel.
442
+
443
+ To promote `6.0.0-beta.N` to `6.0.0`, remove both `release.prerelease` and its
444
+ prerelease `release.versionFloor` in a reviewed commit, add the Pending release
445
+ entry, and run the normal release flow. That explicit removal promotes the exact
446
+ version core, without a semver-level flag. Leaving the channel configured always
447
+ produces another prerelease.
448
+
383
449
  ### Maintenance lines
384
450
 
385
451
  A maintenance line releases an older major from its own branch under its own
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '8.8.2',
6
+ version: '8.9.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
  }
@@ -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[] = [];
@@ -13,6 +13,8 @@ import {
13
13
  compareReleaseVersions,
14
14
  isCanonicalReleaseVersion,
15
15
  releaseVersionMajor,
16
+ parsePrereleaseVersion,
17
+ compareSupportedReleaseVersions,
16
18
  } from "./helpers.releaseversion.js";
17
19
  import {
18
20
  findDistTagPublicationRefusal,
@@ -1255,7 +1257,9 @@ const tagSupersedesVersion = (
1255
1257
  compareReleaseVersions(taggedVersionArg, versionArg) > 0;
1256
1258
 
1257
1259
  /**
1258
- * Reads the dist-tags of a published version. `latest` follows the rule
1260
+ * Reads the dist-tags of a published version. A prerelease needs stable latest
1261
+ * below its core and an exact or later sequence of its own channel and core.
1262
+ * `latest` follows the rule
1259
1263
  * above. A maintenance line's tag is superseded only by a later version of
1260
1264
  * its own major, and a line release additionally requires `latest` to still
1261
1265
  * carry a higher major: a line whose version took `latest` is a terminal
@@ -1267,6 +1271,34 @@ export const assessPublishedDistTags = (
1267
1271
  distTagArg: string,
1268
1272
  ): INpmArtifactProbeResult => {
1269
1273
  const taggedVersion = distTagsArg?.[distTagArg];
1274
+ const prerelease = parsePrereleaseVersion(versionArg);
1275
+ if (prerelease) {
1276
+ const latest = distTagsArg?.[latestDistTag];
1277
+ if (
1278
+ distTagArg === latestDistTag ||
1279
+ typeof latest !== "string" ||
1280
+ !isCanonicalReleaseVersion(latest) ||
1281
+ compareReleaseVersions(latest, prerelease.core) >= 0
1282
+ )
1283
+ return {
1284
+ status: "conflict",
1285
+ code: "dist-tag-conflict",
1286
+ observedLatest: latest,
1287
+ };
1288
+ if (taggedVersion === versionArg) return { status: "exact", code: "exact" };
1289
+ const superseding =
1290
+ typeof taggedVersion === "string"
1291
+ ? parsePrereleaseVersion(taggedVersion)
1292
+ : undefined;
1293
+ if (
1294
+ superseding &&
1295
+ superseding.identifier === prerelease.identifier &&
1296
+ superseding.core === prerelease.core &&
1297
+ compareSupportedReleaseVersions(taggedVersion as string, versionArg) > 0
1298
+ )
1299
+ return { status: "exact", code: "superseded-tag" };
1300
+ return { status: "inconclusive", code: "tag-conflict" };
1301
+ }
1270
1302
  if (distTagArg !== latestDistTag) {
1271
1303
  const latest = distTagsArg?.[latestDistTag];
1272
1304
  if (
@@ -2,6 +2,8 @@ import {
2
2
  compareReleaseVersions,
3
3
  isCanonicalReleaseVersion,
4
4
  releaseVersionMajor,
5
+ parsePrereleaseVersion,
6
+ compareSupportedReleaseVersions,
5
7
  } from "./helpers.releaseversion.js";
6
8
  import type { TReleaseAliasPolicy } from "./mod.plugins.js";
7
9
 
@@ -122,7 +124,8 @@ export const isSameReleaseLine = (
122
124
  leftArg: IReleaseLine | undefined,
123
125
  rightArg: IReleaseLine | undefined,
124
126
  ): boolean =>
125
- leftArg?.branch === rightArg?.branch && leftArg?.distTag === rightArg?.distTag;
127
+ leftArg?.branch === rightArg?.branch &&
128
+ leftArg?.distTag === rightArg?.distTag;
126
129
 
127
130
  /**
128
131
  * A maintenance line keeps its major: a breaking change belongs to `main`,
@@ -139,7 +142,9 @@ export const assertReleaseLineVersion = (
139
142
  `Release line ${lineArg.distTag} needs a canonical x.y.z current version, found ${JSON.stringify(currentVersionArg)}.`,
140
143
  );
141
144
  }
142
- if (releaseVersionMajor(versionArg) !== releaseVersionMajor(currentVersionArg)) {
145
+ if (
146
+ releaseVersionMajor(versionArg) !== releaseVersionMajor(currentVersionArg)
147
+ ) {
143
148
  throw new Error(
144
149
  `Release line ${lineArg.distTag} keeps major ${releaseVersionMajor(currentVersionArg)}, but the release resolved ${currentVersionArg} -> ${versionArg}. ` +
145
150
  "A maintenance line never changes its major: remove the Breaking Changes section, --major or release.versionFloor that raised it.",
@@ -174,6 +179,28 @@ export const findDistTagPublicationRefusal = (
174
179
  ): string | undefined => {
175
180
  const { packageName, registry, version, distTag } = subjectArg;
176
181
  const latest = distTagsArg?.[latestDistTag];
182
+ const prerelease = parsePrereleaseVersion(version);
183
+ if (prerelease) {
184
+ if (!isReleaseLineDistTag(distTag))
185
+ return `${packageName} at ${registry}: a prerelease must publish under a non-latest dist-tag.`;
186
+ if (
187
+ typeof latest !== "string" ||
188
+ !isCanonicalReleaseVersion(latest) ||
189
+ compareReleaseVersions(latest, prerelease.core) >= 0
190
+ )
191
+ return `${packageName} at ${registry}: prerelease ${distTag} requires a stable latest below ${prerelease.core}, found ${describeDistTagValue(latest)}; latest is never moved by this channel.`;
192
+ const tagged = distTagsArg?.[distTag];
193
+ if (tagged === undefined) return undefined;
194
+ const previous =
195
+ typeof tagged === "string" ? parsePrereleaseVersion(tagged) : undefined;
196
+ if (
197
+ previous &&
198
+ previous.identifier === prerelease.identifier &&
199
+ compareSupportedReleaseVersions(tagged as string, version) <= 0
200
+ )
201
+ return undefined;
202
+ return `${packageName} at ${registry}: prerelease dist-tag ${distTag} points at ${describeDistTagValue(tagged)}, which is not a prior release of the configured identifier; publishing would overwrite a different channel or move it backwards.`;
203
+ }
177
204
  if (distTag === latestDistTag) {
178
205
  if (
179
206
  typeof latest === "string" &&
@@ -227,7 +254,7 @@ export const describeLatestMovedConflict = (
227
254
  ? `Restore it with \`pnpm dist-tag add ${packageName}@${previousLatestArg} latest --registry=${registry}\`.`
228
255
  : `Restore it with \`pnpm dist-tag add ${packageName}@<the version latest carried before> latest --registry=${registry}\`; this release did not claim the publication, so it recorded no earlier value.`;
229
256
  return (
230
- `${packageName} at ${registry}: release line ${distTag} published ${version}, but the latest dist-tag is ${describeDistTagValue(observedLatestArg)}, no longer a higher major. ` +
257
+ `${packageName} at ${registry}: ${parsePrereleaseVersion(version) ? "prerelease channel" : "release line"} ${distTag} published ${version}, but the latest dist-tag is ${describeDistTagValue(observedLatestArg)}, ${parsePrereleaseVersion(version) ? "no longer a stable version below the prerelease core" : "no longer a higher major"}. ` +
231
258
  `gitzone does not repair dist-tags. ${restore}`
232
259
  );
233
260
  };