@git.zone/cli 6.14.0 → 6.15.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/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@git.zone/cli",
3
3
  "private": false,
4
- "version": "6.14.0",
4
+ "version": "6.15.0",
5
5
  "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.",
6
6
  "main": "dist_ts/index.js",
7
7
  "typings": "dist_ts/index.d.ts",
@@ -43,15 +43,15 @@
43
43
  "@git.zone/tsbuild": "^4.4.3",
44
44
  "@git.zone/tspack": "1.3.0",
45
45
  "@git.zone/tsrun": "^2.0.6",
46
- "@git.zone/tstest": "6.1.0",
47
- "@types/node": "26.5.0"
46
+ "@git.zone/tstest": "6.1.1",
47
+ "@types/node": "26.5.1"
48
48
  },
49
49
  "dependencies": {
50
50
  "@aws-sdk/client-s3": "3.1095.0",
51
51
  "@git.zone/tsdoc": "^2.1.1",
52
52
  "@git.zone/tsdocker": "3.5.8",
53
53
  "@git.zone/tspublish": "^1.14.0",
54
- "@push.rocks/commitinfo": "^1.0.13",
54
+ "@push.rocks/commitinfo": "^1.1.0",
55
55
  "@push.rocks/early": "^4.0.4",
56
56
  "@push.rocks/projectinfo": "^5.1.0",
57
57
  "@push.rocks/smartbucket": "4.13.0",
package/readme.md CHANGED
@@ -187,7 +187,7 @@ Before interactive confirmation or source mutation, a Docker release verifies th
187
187
  The release core is not configurable plumbing. It always follows the same professional release transaction:
188
188
 
189
189
  1. Verify the release branch, clean state, and `main` worktree ownership.
190
- 2. Read `changelog.md` `## Pending` entries and infer or accept a semver bump.
190
+ 2. Read `changelog.md` `## Pending` entries and infer or accept a semver bump, raised to `release.versionFloor` when that is higher.
191
191
  3. Run configured tests.
192
192
  4. With `--merge`, fast-forward and lease-push `main` before release metadata is created.
193
193
  5. Update version files and baked commit info.
@@ -242,12 +242,64 @@ Release flags:
242
242
  | `--no-publish` | Remove Gitea assets, npm and Docker from the resolved target set without implicitly enabling Git |
243
243
  | `--no-build` | Disable the separate post-metadata project build; Docker qualification still performs its required image build |
244
244
  | `--merge` | Fast-forward and lease-push a cleanly rebased feature branch into `main`, then release from `main`; incompatible with Docker or Gitea assets |
245
- | `--major`, `--minor`, `--patch` | Override inferred semver level |
245
+ | `--major`, `--minor`, `--patch` | Override inferred semver level; `release.versionFloor` still applies |
246
246
  | `--plan` | Show the resolved workflow without fetching or mutating refs, files, the index, or worktrees |
247
247
  | `inspect [version]` | Read one or all durable release journals; add `--json` for machine-readable output |
248
248
  | `resume <version>` | Resume journaled Git, npm, qualification, promotion, or cleanup work; fresh-release overrides are rejected, and `--json` remains inspect-only |
249
249
  | `--recover-attempt <id>` | Recover the exact 32-character lowercase hexadecimal `attempt.id` shown by `inspect --json`, after independently proving its publisher stopped |
250
250
 
251
+ ### Version floor
252
+
253
+ `release.versionFloor` sets a minimum for the next release version. Use it when a repository must join a common version line, for example when every serve.zone package moves to major 32:
254
+
255
+ ```json
256
+ {
257
+ "@git.zone/cli": {
258
+ "release": {
259
+ "versionFloor": "32.0.0"
260
+ }
261
+ }
262
+ }
263
+ ```
264
+
265
+ GitZone first infers the version as usual. It starts from the current `package.json` or `deno.json` version and applies the level from the Pending changelog or from `--major`, `--minor` or `--patch`. The release version is then the higher of that inferred version and the floor. The floor is committed configuration, so the plain `gitzone release -y` honours it without a flag, and nobody has to hand-edit `package.json` to a version that was never published.
266
+
267
+ `gitzone release --plan` states the outcome:
268
+
269
+ | Plan line | Meaning |
270
+ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
271
+ | `version floor: 32.0.0 applied (inferred 3.6.0 -> release 32.0.0)` | The floor is higher than the inferred version and becomes the release version |
272
+ | `version floor: 3.5.4 satisfied by inferred 3.6.0` | The inferred version already meets the floor; nothing changes |
273
+ | `version floor: 32.0.0 inert (current 32.0.0 already meets it); remove release.versionFloor` | The project has reached the floor; delete the setting |
274
+ | `version notice: the floor raises the major version above inferred 3.6.0, and Pending ...` | The floor raised the major version above the inferred version and Pending has no `### Breaking Changes` section; the line is informational and stays until such a section exists |
275
+
276
+ A floor does not require a `### Breaking Changes` Pending section. `--major` never required one, and the floor is the same kind of explicit maintainer decision, reviewed in a commit. Aligning a version line is often not an API break, so requiring the section would force a false changelog entry. A major release is also the safe direction for consumers, because `^3` ranges never resolve to `32.0.0`. The plan notice only makes that jump visible and never blocks the release. It appears only when the floor itself raises the major version; a major that `--major` produces prints no notice.
277
+
278
+ When the floor decides the version, the release journal records that decision with the release identity:
279
+
280
+ ```json
281
+ "release": {
282
+ "version": "32.0.0",
283
+ "tag": "v32.0.0",
284
+ "mainOid": "...",
285
+ "tagOid": "...",
286
+ "versionFloor": { "floor": "32.0.0", "inferredVersion": "3.6.0" }
287
+ }
288
+ ```
289
+
290
+ `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.
291
+
292
+ 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:
293
+
294
+ | Code | Cause |
295
+ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
296
+ | `malformed-version-floor` | Anything else, such as `"32"`, `"v32.0.0"`, `null`, a number, or a component above `9007199254740991` |
297
+ | `unsupported-prerelease-floor` | A prerelease or build suffix such as `"32.0.0-rc.1"`; GitZone releases only canonical versions |
298
+ | `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 |
299
+ | `current-version-changed` | The release checkout's `package.json` or `deno.json` version differs from the version the release was resolved from |
300
+
301
+ `gitzone config show` lists the configured floor.
302
+
251
303
  ### Exact artifacts and release journals
252
304
 
253
305
  Journal schema 1 supports Git and public npm publication. Schema 2 adds Docker qualification, promotion, and cleanup evidence without changing the storage path or schema-1 parsing and resume behavior. Fresh and resumed npm publication dynamically qualifies the active stable `pnpm` version; there is no version allowlist. GitZone reads `minimum-release-age` and `minimum-release-age-exclude` through that exact pnpm invocation in the release directory, so project configuration and global policy retain pnpm's normal precedence. It verifies the selected version's publication time through the configured registry unless the effective policy disables the age delay or excludes that version. Missing timestamps follow `minimum-release-age-ignore-missing-time`, including pnpm's default of `true`; malformed policy, metadata failures, immature versions, and prerelease versions stop qualification. GitZone also verifies the required pack/publish command contract and keeps every subsequent command bound to the qualified exact version. A new pnpm version with the same capabilities needs no GitZone update once it satisfies the policy. Registries must be unique canonical credential-free HTTP(S) URLs, and `release.targets.npm.accessLevel` must be `public` so verification does not depend on publisher credentials.
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '6.14.0',
6
+ version: '6.15.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
  }
@@ -1,6 +1,7 @@
1
1
  import { getCliConfigValue } from "./helpers.smartconfig.js";
2
2
  import { getProcessUserArgv } from "./helpers.climode.js";
3
3
  import { shouldCleanTestArtifactsOnRelease } from "./helpers.tstest.js";
4
+ import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
4
5
 
5
6
  export type TConfirmationMode = "prompt" | "auto" | "plan";
6
7
 
@@ -156,6 +157,8 @@ export interface IReleaseWorkflowConfig {
156
157
  strategy?: "semver";
157
158
  source?: "pendingChangelog" | "manual";
158
159
  };
160
+ /** Canonical x.y.z minimum for the next release version. */
161
+ versionFloor?: string;
159
162
  preflight?: {
160
163
  test?: boolean;
161
164
  build?: boolean;
@@ -197,6 +200,7 @@ export interface IResolvedReleaseWorkflow {
197
200
  changelogFile: "changelog.md";
198
201
  changelogPendingSection: "Pending";
199
202
  changelogVersionHeading: "## {{date}} - {{version}}";
203
+ versionFloor?: string;
200
204
  gitEnabled: boolean;
201
205
  gitRemote: string;
202
206
  pushBranch: boolean;
@@ -751,6 +755,7 @@ export const resolveReleaseWorkflow = async (
751
755
  ): Promise<IResolvedReleaseWorkflow> => {
752
756
  const cliConfig = await readCliWorkflowConfig();
753
757
  const releaseConfig = cliConfig.release || {};
758
+ const versionFloor = parseReleaseVersionFloor(releaseConfig.versionFloor);
754
759
  const targetConfig = releaseConfig.targets || {};
755
760
  const gitConfig = targetConfig.git || {};
756
761
  const npmConfig = targetConfig.npm || {};
@@ -892,6 +897,7 @@ export const resolveReleaseWorkflow = async (
892
897
  changelogFile: "changelog.md",
893
898
  changelogPendingSection: "Pending",
894
899
  changelogVersionHeading: "## {{date}} - {{version}}",
900
+ ...(versionFloor ? { versionFloor } : {}),
895
901
  gitEnabled,
896
902
  gitRemote: gitConfig.remote || "origin",
897
903
  pushBranch,
@@ -25,6 +25,10 @@ import {
25
25
  } from "../helpers.workflow.js";
26
26
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
27
27
  import { TsdockerReleaseClient } from "../mod_release/helpers.tsdockerprotocol.js";
28
+ import {
29
+ ReleaseVersionError,
30
+ parseReleaseVersionFloor,
31
+ } from "../mod_release/helpers.releaseversion.js";
28
32
  import { getSealedReleaseConfigError } from "../helpers.sealedrelease.js";
29
33
 
30
34
  export { ReleaseConfig, CommitConfig };
@@ -298,6 +302,7 @@ async function handleShow(mode: ICliMode): Promise<void> {
298
302
  const targets = release.targets || {};
299
303
  printConfigSection("Release Workflow", [
300
304
  ["confirmation", formatValue(release.confirmation)],
305
+ ["version floor", formatValue(release.versionFloor)],
301
306
  ["clean tree", "required"],
302
307
  ["run tests", formatValue(release.preflight?.test)],
303
308
  ["run build", formatValue(release.preflight?.build)],
@@ -1776,6 +1781,8 @@ async function validateReleaseConfig(
1776
1781
  });
1777
1782
  }
1778
1783
 
1784
+ findings.push(validateReleaseVersionFloor(releaseConfig.versionFloor));
1785
+
1779
1786
  if (
1780
1787
  releaseConfig.registries ||
1781
1788
  releaseConfig.accessLevel ||
@@ -1842,6 +1849,25 @@ async function validateReleaseConfig(
1842
1849
  await validateDockerTarget(targets.docker || {}, smartconfigData, findings);
1843
1850
  }
1844
1851
 
1852
+ function validateReleaseVersionFloor(valueArg: unknown): IDoctorFinding {
1853
+ try {
1854
+ const versionFloor = parseReleaseVersionFloor(valueArg);
1855
+ return {
1856
+ level: "ok",
1857
+ message: versionFloor
1858
+ ? `Release version floor ${versionFloor} is a canonical version`
1859
+ : "Release version floor is not configured",
1860
+ };
1861
+ } catch (error) {
1862
+ if (!(error instanceof ReleaseVersionError)) throw error;
1863
+ return {
1864
+ level: "error",
1865
+ message: error.message,
1866
+ fix: "Set release.versionFloor to a canonical x.y.z version or remove it.",
1867
+ };
1868
+ }
1869
+ }
1870
+
1845
1871
  async function validateAssetsConfig(
1846
1872
  rawAssetsConfig: unknown,
1847
1873
  smartconfigData: Record<string, any>,
@@ -21,6 +21,11 @@ import {
21
21
  type IReleaseQualificationResult,
22
22
  type TReleasePromotionEvidence,
23
23
  } from "./helpers.tsdockerprotocol.js";
24
+ import {
25
+ compareReleaseVersions,
26
+ isCanonicalReleaseVersion,
27
+ type IReleaseVersionFloorRecord,
28
+ } from "./helpers.releaseversion.js";
24
29
 
25
30
  export const releaseJournalStorageVersion = 1 as const;
26
31
  export const legacyReleaseJournalSchemaVersion = 1 as const;
@@ -74,16 +79,20 @@ export interface IReleaseNpmRegistryJournal extends IReleaseTargetStatus {
74
79
  packageName?: string;
75
80
  }
76
81
 
82
+ export interface IReleaseIdentity {
83
+ version: string;
84
+ tag: string;
85
+ mainOid: string;
86
+ tagOid: string;
87
+ /** Present only when release.versionFloor raised the version above the inferred one. */
88
+ versionFloor?: IReleaseVersionFloorRecord;
89
+ }
90
+
77
91
  export interface IReleaseJournalV1 {
78
92
  kind: "gitzone-release-journal";
79
93
  schemaVersion: typeof legacyReleaseJournalSchemaVersion;
80
94
  revision: number;
81
- release: {
82
- version: string;
83
- tag: string;
84
- mainOid: string;
85
- tagOid: string;
86
- };
95
+ release: IReleaseIdentity;
87
96
  artifact: IReleaseArtifact | null;
88
97
  git: IReleaseGitJournal;
89
98
  npm: {
@@ -123,12 +132,7 @@ export interface IReleaseJournalV2 {
123
132
  kind: "gitzone-release-journal";
124
133
  schemaVersion: typeof releaseJournalSchemaVersion;
125
134
  revision: number;
126
- release: {
127
- version: string;
128
- tag: string;
129
- mainOid: string;
130
- tagOid: string;
131
- };
135
+ release: IReleaseIdentity;
132
136
  artifact: IReleaseArtifact | null;
133
137
  git: IReleaseGitJournal;
134
138
  npm: {
@@ -213,7 +217,6 @@ export const getReleaseNpmArtifact = (
213
217
  return artifact;
214
218
  };
215
219
 
216
- const releaseVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
217
220
  const gitOidRegex = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
218
221
  const attemptIdRegex = /^[0-9a-f]{32}$/;
219
222
  const sha1Regex = /^[0-9a-f]{40}$/;
@@ -292,7 +295,7 @@ const assertIsoTimestamp = (valueArg: unknown, contextArg: string): string => {
292
295
 
293
296
  export const normalizeReleaseVersion = (valueArg: string): string => {
294
297
  const version = valueArg.startsWith("v") ? valueArg.slice(1) : valueArg;
295
- if (!releaseVersionRegex.test(version)) {
298
+ if (!isCanonicalReleaseVersion(version)) {
296
299
  throw new Error(
297
300
  "Release journal versions must use canonical x.y.z semver.",
298
301
  );
@@ -494,6 +497,69 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string =>
494
497
  : undefined,
495
498
  });
496
499
 
500
+ const releaseIdentityKeys = ["version", "tag", "mainOid", "tagOid"] as const;
501
+
502
+ const assertVersionFloorRecord = (
503
+ valueArg: unknown,
504
+ versionArg: string,
505
+ ): void => {
506
+ if (!isPlainObject(valueArg)) {
507
+ throw new Error("Release journal version floor must be an object.");
508
+ }
509
+ assertExactKeys(
510
+ valueArg,
511
+ ["floor", "inferredVersion"],
512
+ "Release journal version floor",
513
+ );
514
+ if (
515
+ typeof valueArg.floor !== "string" ||
516
+ typeof valueArg.inferredVersion !== "string" ||
517
+ !isCanonicalReleaseVersion(valueArg.floor) ||
518
+ !isCanonicalReleaseVersion(valueArg.inferredVersion)
519
+ ) {
520
+ throw new Error(
521
+ "Release journal version floor must record canonical x.y.z versions.",
522
+ );
523
+ }
524
+ if (
525
+ valueArg.floor !== versionArg ||
526
+ compareReleaseVersions(valueArg.inferredVersion, valueArg.floor) >= 0
527
+ ) {
528
+ throw new Error(
529
+ "Release journal version floor must equal the release version and exceed the inferred version.",
530
+ );
531
+ }
532
+ };
533
+
534
+ const assertReleaseIdentity = (valueArg: unknown): IReleaseIdentity => {
535
+ if (!isPlainObject(valueArg)) {
536
+ throw new Error("Release journal release identity is missing.");
537
+ }
538
+ const hasVersionFloor = Object.hasOwn(valueArg, "versionFloor");
539
+ assertExactKeys(
540
+ valueArg,
541
+ hasVersionFloor
542
+ ? [...releaseIdentityKeys, "versionFloor"]
543
+ : releaseIdentityKeys,
544
+ "Release journal release",
545
+ );
546
+ if (
547
+ typeof valueArg.version !== "string" ||
548
+ normalizeReleaseVersion(valueArg.version) !== valueArg.version ||
549
+ valueArg.tag !== `v${valueArg.version}` ||
550
+ typeof valueArg.mainOid !== "string" ||
551
+ !gitOidRegex.test(valueArg.mainOid) ||
552
+ typeof valueArg.tagOid !== "string" ||
553
+ !gitOidRegex.test(valueArg.tagOid)
554
+ ) {
555
+ throw new Error("Release journal Git identity is invalid.");
556
+ }
557
+ if (hasVersionFloor) {
558
+ assertVersionFloorRecord(valueArg.versionFloor, valueArg.version);
559
+ }
560
+ return valueArg as unknown as IReleaseIdentity;
561
+ };
562
+
497
563
  const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
498
564
  if (!isPlainObject(valueArg)) {
499
565
  throw new Error("Release journal root must be a JSON object.");
@@ -523,29 +589,10 @@ const assertReleaseJournalV1 = (valueArg: unknown): IReleaseJournalV1 => {
523
589
  throw new Error("Release journal header is invalid or unsupported.");
524
590
  }
525
591
 
526
- if (!isPlainObject(valueArg.release)) {
527
- throw new Error("Release journal release identity is missing.");
528
- }
529
- assertExactKeys(
530
- valueArg.release,
531
- ["version", "tag", "mainOid", "tagOid"],
532
- "Release journal release",
533
- );
534
- if (
535
- typeof valueArg.release.version !== "string" ||
536
- normalizeReleaseVersion(valueArg.release.version) !==
537
- valueArg.release.version ||
538
- valueArg.release.tag !== `v${valueArg.release.version}` ||
539
- typeof valueArg.release.mainOid !== "string" ||
540
- !gitOidRegex.test(valueArg.release.mainOid) ||
541
- typeof valueArg.release.tagOid !== "string" ||
542
- !gitOidRegex.test(valueArg.release.tagOid)
543
- ) {
544
- throw new Error("Release journal Git identity is invalid.");
545
- }
592
+ const release = assertReleaseIdentity(valueArg.release);
546
593
 
547
594
  const artifact = assertArtifact(valueArg.artifact);
548
- if (artifact && artifact.version !== valueArg.release.version) {
595
+ if (artifact && artifact.version !== release.version) {
549
596
  throw new Error(
550
597
  "Release journal artifact version does not match the release.",
551
598
  );
@@ -717,7 +764,7 @@ export const getReleaseDockerPromotionContext = (
717
764
 
718
765
  const assertDockerJournal = (
719
766
  valueArg: unknown,
720
- releaseArg: IReleaseJournalV2["release"],
767
+ releaseArg: IReleaseIdentity,
721
768
  ): IReleaseDockerJournal => {
722
769
  if (!isPlainObject(valueArg)) {
723
770
  throw new Error("Release journal Docker target is missing.");
@@ -932,28 +979,9 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
932
979
  ) {
933
980
  throw new Error("Release journal header is invalid or unsupported.");
934
981
  }
935
- if (!isPlainObject(valueArg.release)) {
936
- throw new Error("Release journal release identity is missing.");
937
- }
938
- assertExactKeys(
939
- valueArg.release,
940
- ["version", "tag", "mainOid", "tagOid"],
941
- "Release journal release",
942
- );
943
- if (
944
- typeof valueArg.release.version !== "string" ||
945
- normalizeReleaseVersion(valueArg.release.version) !==
946
- valueArg.release.version ||
947
- valueArg.release.tag !== `v${valueArg.release.version}` ||
948
- typeof valueArg.release.mainOid !== "string" ||
949
- !gitOidRegex.test(valueArg.release.mainOid) ||
950
- typeof valueArg.release.tagOid !== "string" ||
951
- !gitOidRegex.test(valueArg.release.tagOid)
952
- ) {
953
- throw new Error("Release journal Git identity is invalid.");
954
- }
982
+ const release = assertReleaseIdentity(valueArg.release);
955
983
  const artifact = assertArtifact(valueArg.artifact);
956
- if (artifact && artifact.version !== valueArg.release.version) {
984
+ if (artifact && artifact.version !== release.version) {
957
985
  throw new Error(
958
986
  "Release journal artifact version does not match the release.",
959
987
  );
@@ -1043,10 +1071,7 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1043
1071
  "Release journal npm targets and artifact must exist together.",
1044
1072
  );
1045
1073
  }
1046
- const docker = assertDockerJournal(
1047
- valueArg.docker,
1048
- valueArg.release as unknown as IReleaseJournalV2["release"],
1049
- );
1074
+ const docker = assertDockerJournal(valueArg.docker, release);
1050
1075
  const activePublishers = [
1051
1076
  valueArg.git as unknown as IReleaseTargetStatus,
1052
1077
  ...(valueArg.npm.registries as unknown as IReleaseTargetStatus[]),