@git.zone/cli 8.3.2 → 8.5.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.
Files changed (39) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +29 -0
  3. package/dist_ts/helpers.workflow.js +37 -2
  4. package/dist_ts/mod_config/index.js +45 -3
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +108 -13
  7. package/dist_ts/mod_release/helpers.giteaassets.d.ts +47 -1
  8. package/dist_ts/mod_release/helpers.giteaassets.js +236 -56
  9. package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
  10. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  11. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  12. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  13. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  14. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  15. package/dist_ts/mod_release/helpers.releasephase.d.ts +9 -0
  16. package/dist_ts/mod_release/helpers.releasephase.js +25 -0
  17. package/dist_ts/mod_release/helpers.releasepreparation.js +6 -3
  18. package/dist_ts/mod_release/helpers.releasepublication.d.ts +12 -1
  19. package/dist_ts/mod_release/helpers.releasepublication.js +235 -52
  20. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  21. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  22. package/dist_ts/mod_release/index.js +149 -44
  23. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +16 -0
  24. package/package.json +5 -5
  25. package/readme.md +224 -17
  26. package/ts/00_commitinfo_data.ts +1 -1
  27. package/ts/helpers.workflow.ts +87 -0
  28. package/ts/mod_config/index.ts +50 -1
  29. package/ts/mod_release/classes.releasejournal.ts +165 -14
  30. package/ts/mod_release/helpers.giteaassets.ts +319 -64
  31. package/ts/mod_release/helpers.npmartifact.ts +302 -22
  32. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  33. package/ts/mod_release/helpers.releaseline.ts +214 -0
  34. package/ts/mod_release/helpers.releasephase.ts +26 -0
  35. package/ts/mod_release/helpers.releasepreparation.ts +12 -3
  36. package/ts/mod_release/helpers.releasepublication.ts +425 -78
  37. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  38. package/ts/mod_release/index.ts +213 -32
  39. package/ts/mod_release/interfaces.giteaassets.ts +19 -0
@@ -22,6 +22,8 @@ export interface IGiteaRelease {
22
22
  id: number;
23
23
  tag: string;
24
24
  publicUrl: string;
25
+ /** A draft is visible to repository writers only, its attachments too. */
26
+ draft: boolean;
25
27
  }
26
28
  export interface IGiteaAssetInspection {
27
29
  present: IGiteaFrozenAsset[];
@@ -61,5 +63,19 @@ export interface IGiteaAssetsClient {
61
63
  /** Downloads and hashes only the present attachments named in `verify`. */
62
64
  inspectAssets(releaseId: number, expected: IGiteaFrozenAsset[], verify?: readonly IGiteaFrozenAsset[]): Promise<IGiteaAssetInspection>;
63
65
  uploadAsset(releaseId: number, asset: IGiteaFrozenAsset, artifactDirectory: string): Promise<void>;
66
+ /**
67
+ * The complete set, nothing extra, every frozen identity unchanged. Downloads
68
+ * and hashes every attachment except one this client itself downloaded and
69
+ * hashed whose attachment id and UUID are unchanged since. A draft's
70
+ * attachments are listed and downloaded with the token.
71
+ */
64
72
  verifyComplete(releaseId: number, expected: IGiteaFrozenAsset[]): Promise<void>;
73
+ /**
74
+ * Publishes a draft release (`draft: false`), then proves the release, its
75
+ * attachment identities and every attachment's anonymous download. Every
76
+ * listed attachment must be the one this client hashed (id and UUID; the id
77
+ * alone on a server without UUIDs), otherwise a destination conflict leaves
78
+ * the release a draft. An already published release is only verified.
79
+ */
80
+ publishRelease(releaseId: number, expected: IGiteaFrozenAsset[]): Promise<void>;
65
81
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@git.zone/cli",
3
3
  "private": false,
4
- "version": "8.3.2",
4
+ "version": "8.5.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",
@@ -40,11 +40,11 @@
40
40
  "homepage": "https://code.foss.global/git.zone/cli#README",
41
41
  "devDependencies": {
42
42
  "@api.global/typedrequest": "^8.2.0",
43
- "@git.zone/tsbuild": "^5.1.1",
44
- "@git.zone/tspack": "^1.4.1",
43
+ "@git.zone/tsbuild": "^5.1.2",
44
+ "@git.zone/tspack": "^1.4.2",
45
45
  "@git.zone/tsrun": "^3.0.2",
46
- "@git.zone/tstest": "^6.3.4",
47
- "@types/node": "^26.6.2"
46
+ "@git.zone/tstest": "^7.1.0",
47
+ "@types/node": "^26.6.3"
48
48
  },
49
49
  "dependencies": {
50
50
  "@aws-sdk/client-s3": "3.1095.0",
package/readme.md CHANGED
@@ -176,7 +176,7 @@ be included by the existing stage-all workflow.
176
176
 
177
177
  ## Release Workflow
178
178
 
179
- `gitzone release` releases from `main`. Running it on another branch fails before release metadata or ref mutation unless the bare `--merge` flag is explicitly supplied.
179
+ `gitzone release` releases from `main`. Running it on another branch fails before release metadata or ref mutation unless the bare `--merge` flag is explicitly supplied, or the branch carries a `release.line` configuration that names it (see [Maintenance lines](#maintenance-lines)).
180
180
 
181
181
  `--merge` is intentionally strict: the source and existing `main` worktree must be clean, the source must be linearly rebased onto current remote `main`, and the Git target must push both the branch and tag. GitZone pins the single configured push URL, compare-and-swap fast-forwards local `main`, updates its verified worktree, and lease-pushes that exact source commit before creating release metadata. It rejects diverged or merged history, local replacement refs or grafts, stale worktrees, incomplete shallow history, changed destinations, and remote races. If the pre-release push fails, GitZone restores local `main` only when doing so cannot overwrite concurrent work. This plumbing-level integration intentionally does not run merge hooks or write `ORIG_HEAD`.
182
182
 
@@ -186,7 +186,7 @@ Before interactive confirmation or source mutation, a Docker release verifies th
186
186
 
187
187
  The release core is not configurable plumbing. It always follows the same professional release transaction:
188
188
 
189
- 1. Verify the release branch, clean state, and `main` worktree ownership. A release that builds or packs a commit with a `package.json` also proves here that the source commit carries a `pnpm-lock.yaml` its checkout can install with `--frozen-lockfile`.
189
+ 1. Verify the release branch, clean state, and worktree ownership of `main` (or of the maintenance branch a release line names). A release that builds or packs a commit with a `package.json` also proves here that the source commit carries a `pnpm-lock.yaml` its checkout can install with `--frozen-lockfile`. An npm release then reads every registry's dist-tags for every package it publishes: `latest` never moves downwards, and a line never takes `latest` (step `preflight.npmDistTags`).
190
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.
@@ -278,7 +278,7 @@ Targets decide what happens after that:
278
278
 
279
279
  | Target | What it does |
280
280
  | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
281
- | `git` | Atomically pushes the exact `main` release commit and new tag, often triggering remote CI release builds |
281
+ | `git` | Atomically pushes the exact release commit to `main` (or to the maintenance branch of a release line) and the new tag, often triggering remote CI release builds |
282
282
  | `npm` | Publishes the same journaled tarball to every configured registry; verifies its bytes anonymously, or its integrity record with the registry's configured authentication for private packages |
283
283
  | `docker` | Qualifies immutable OCI digest graphs with project-local tSDocker, promotes each journaled destination under single-writer alias fencing, verifies exact digests, then cleans the candidate; a terminal qualification conflict permits cleanup only |
284
284
 
@@ -378,6 +378,122 @@ The floor must be a canonical `x.y.z` string whose components do not exceed `900
378
378
 
379
379
  `gitzone config show` lists the configured floor.
380
380
 
381
+ ### Maintenance lines
382
+
383
+ A maintenance line releases an older major from its own branch under its own
384
+ npm dist-tag, so that `latest` never moves. It is opted into per branch: the
385
+ maintenance branch commits a `release.line` block in its `.smartconfig.json`,
386
+ and that block makes that branch, and only that branch, a release source.
387
+ `main` never carries the block.
388
+
389
+ Worked example: `@push.rocks/smartserve` publishes 8.x as `latest`, and its 4.x
390
+ line lives on the branch `v4-maintenance` under the dist-tag `v4-lts`
391
+ (4.4.0). A security fix is released as 4.4.1 like this. On `v4-maintenance`,
392
+ `.smartconfig.json` carries:
393
+
394
+ ```json
395
+ {
396
+ "@git.zone/cli": {
397
+ "release": {
398
+ "line": { "branch": "v4-maintenance", "distTag": "v4-lts" },
399
+ "targets": {
400
+ "git": { "enabled": true, "remote": "origin", "pushBranch": true, "pushTags": true },
401
+ "npm": {
402
+ "enabled": true,
403
+ "registries": ["https://verdaccio.lossless.digital", "https://registry.npmjs.org"],
404
+ "accessLevel": "public"
405
+ }
406
+ }
407
+ }
408
+ }
409
+ }
410
+ ```
411
+
412
+ Commit the fix with `gitzone commit` on `v4-maintenance`; the branch keeps its
413
+ own `changelog.md`, whose `## Pending` section feeds the release exactly as on
414
+ `main`. Then, still on `v4-maintenance`:
415
+
416
+ ```bash
417
+ gitzone release --plan
418
+ # source branch: v4-maintenance
419
+ # release line: v4-maintenance -> npm dist-tag v4-lts (major 4; latest is never moved)
420
+ # npm dist-tag: v4-lts
421
+ # npm dist-tags of @push.rocks/smartserve at https://registry.npmjs.org: v4-lts 4.4.0 -> 4.4.1, latest 8.2.0 unchanged
422
+ gitzone release -y
423
+ ```
424
+
425
+ The release commits `v4.4.1` on `v4-maintenance`, tags it, pushes exactly
426
+ `refs/heads/v4-maintenance` and `refs/tags/v4.4.1` with a lease on
427
+ `v4-maintenance`, and publishes each package with `pnpm publish <tarball>
428
+ --tag=v4-lts`. `main` is neither read nor written.
429
+
430
+ The rules:
431
+
432
+ - `release.line` takes exactly `branch` and `distTag`. The branch is a
433
+ canonical branch name other than `main`. The dist-tag is lowercase letters
434
+ and digits joined by hyphens and starts with a letter; it is never `latest`
435
+ and never a semver range such as `v4` or `x`, which npm refuses as a tag.
436
+ - The release must run on the branch the line names. On any other branch,
437
+ `main` included, the release stops before anything is created. A branch
438
+ without `release.line` still releases only `main`.
439
+ - A line publishes only to Git and npm. Docker targets promote aliases such as
440
+ `latest`, and Gitea marks its newest release as the latest one, so a line
441
+ with an enabled `docker` or `giteaAssets` target is refused, and so are
442
+ `--merge` and `gitzone release recover`. A line release records its intent,
443
+ so `gitzone release resume <version> -y` continues it.
444
+ - A line keeps its major. A Pending `### Breaking Changes` section, `--major`
445
+ or a `release.versionFloor` that changes the major stops the release.
446
+ - Before anything is created, and again right before each upload, every
447
+ package must, at every registry, already have a canonical `latest` with a
448
+ higher major than the release, and the line's own tag must be absent or
449
+ below the release version. Otherwise the release stops; a refusal right
450
+ before an upload is recorded as the terminal `dist-tag-conflict` and nothing
451
+ is published.
452
+ - After the upload the line's tag must name the version, or a later version
453
+ of the same major, and `latest` must still carry a higher major. A line whose
454
+ version took `latest` is a terminal `dist-tag-conflict`. gitzone never
455
+ writes dist-tags: the error names the exact command that restores `latest`,
456
+ `pnpm dist-tag add <package>@<previous latest> latest --registry=<registry>`,
457
+ where the previous `latest` is the version the release recorded when it
458
+ claimed the upload.
459
+ - `release.targets.npm.alreadyPublished` applies unchanged: identical bytes
460
+ already published, with the line's tag on them and `latest` still a higher
461
+ major, verify without an upload under `success` and stop under `error`.
462
+ Identical bytes without the line's tag stay unverified; gitzone does not add
463
+ the tag.
464
+ - Private packages follow the same rules. Their dist-tags are read with the
465
+ registry's authentication through `pnpm view <package> dist-tags --json`,
466
+ which every release path (fresh, `resume` and `recover`) qualifies from
467
+ `pnpm view --help` in both pnpm command dialects before it authenticates,
468
+ reads or publishes anything.
469
+
470
+ #### `latest` only moves upwards
471
+
472
+ The same check guards every `main` release: when a registry's `latest` is a
473
+ canonical version above the release version, the release stops before
474
+ anything is committed, tagged or published, and names `release.line` as the
475
+ way to release an older major. A release that finds `latest` moved above it
476
+ right before an upload records a terminal `dist-tag-conflict` and publishes
477
+ nothing. A prerelease or non-semver `latest` and a package the registry does
478
+ not know yet do not stop a `main` release.
479
+
480
+ A registry whose dist-tags cannot be read (an outage, a timeout, an
481
+ unexpected answer) now stops a `main` release in preflight as well, before
482
+ the release commit. This is intended: an unknown `latest` could be above the
483
+ release, so publishing would risk a downgrade. Release again once the
484
+ registry answers.
485
+
486
+ #### Journal compatibility
487
+
488
+ A line release journals `release.line` (`branch` and `distTag`) in the
489
+ release identity and its intent, and its dist-tag as `npm.tag`. Each npm
490
+ destination it claims records `previousLatest`, the `latest` version found
491
+ when the upload was claimed. `git.expectedRemoteMainOid` keeps its name and
492
+ holds the leased commit of the release branch, `main` or the line's branch.
493
+ Journals of `main` releases are byte-identical to before. GitZone 8.3.x and
494
+ earlier refuse to read a line journal or intent, so they can neither resume a
495
+ line release onto `main` nor publish it under `latest`.
496
+
381
497
  ### Exact artifacts and release journals
382
498
 
383
499
  Journal schema 1 supports Git and public or private 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. `release.targets.npm.accessLevel` is `public` (the default) or `private`; see [Private npm packages](#private-npm-packages).
@@ -415,13 +531,13 @@ Every release that reaches final publication stores `journal.json` under the rep
415
531
 
416
532
  The canonical journal binds the release commit, annotated tag object, hashed Git destination, npm registries, per-target attempt states, and, when npm is selected, the package identity, tarball size, SHA-1, SHA-256, and SHA-512 integrity. Schema 2 also binds the exact tSDocker request, candidate identity, qualification result, ordered destination promotions, probe or promotion evidence, and terminal cleanup result. Journal updates use revision compare-and-swap under an interprocess lock. Release identity and destinations cannot change after journal creation. Qualification and promotion evidence is append-only, destination conflicts are terminal, and completed Docker state cannot regress. Inspect and resume reject malformed, future, noncanonical, duplicate-key, or merely reformatted journal JSON rather than repairing or normalizing it.
417
533
 
418
- Packing must leave the release tree clean. Each registry receives that exact stored tarball through `pnpm publish <tarball> --ignore-scripts`, so publish lifecycle scripts do not run. For a public package, success is recorded only after anonymous no-redirect probes verify version metadata, SHA-1 and integrity fields, the downloaded tarball bytes, and the `latest` dist-tag. Each metadata request is bounded at 10 s; the tarball download, sized by the packed artifact, runs as long as bytes keep arriving, aborting after 30 s without data or once 10 s plus the time its size needs at 256 KiB/s have passed, so large tarballs with native binaries verify while a stalled registry still ends the probe as retryable. The dist-tag is satisfied by the released version itself and by any later release that has since carried the tag on, so superseded releases stay verifiable; an older version, a prerelease, a non-semver value or an absent tag does not. A matching pre-existing version follows `release.targets.npm.alreadyPublished`; conflicting bytes always stop the release, while transient responses and dist-tag propagation remain retryable.
534
+ Packing must leave the release tree clean. Each registry receives that exact stored tarball through `pnpm publish <tarball> --tag=<dist-tag> --ignore-scripts`, so publish lifecycle scripts do not run. For a public package, success is recorded only after anonymous no-redirect probes verify version metadata, SHA-1 and integrity fields, the downloaded tarball bytes, and the release's dist-tag: `latest`, or the tag of a [maintenance line](#maintenance-lines). Each metadata request is bounded at 10 s; the tarball download, sized by the packed artifact, runs as long as bytes keep arriving, aborting after 30 s without data or once 10 s plus the time its size needs at 256 KiB/s have passed, so large tarballs with native binaries verify while a stalled registry still ends the probe as retryable. The dist-tag is satisfied by the released version itself and by any later release that has since carried the tag on (for a line tag, a later version of the same major), so superseded releases stay verifiable; an older version, a prerelease, a non-semver value or an absent tag does not. A matching pre-existing version follows `release.targets.npm.alreadyPublished`; conflicting bytes always stop the release, while transient responses and dist-tag propagation remain retryable.
419
535
 
420
536
  #### Private npm packages
421
537
 
422
538
  With `release.targets.npm.accessLevel: "private"` the journal records
423
539
  `npm.access: "private"`, each registry receives the stored tarball through
424
- `pnpm publish <tarball> --access=restricted --ignore-scripts`, and verification
540
+ `pnpm publish <tarball> --access=restricted --tag=<dist-tag> --ignore-scripts`, and verification
425
541
  runs through the same qualified pnpm with the registry's configured
426
542
  authentication instead of anonymously. GitZone never reads, parses, logs or
427
543
  journals a credential: pnpm reads its own `.npmrc` for the destination, exactly
@@ -436,7 +552,7 @@ as it does when it publishes, so authenticate at user level with `pnpm login
436
552
  - A destination is `verified` when `pnpm view <name>@<version> --json` reports
437
553
  the packed artifact's `dist.integrity` and `dist.shasum`, a `dist.tarball` on
438
554
  the registry's own origin without credentials, query or fragment, and the
439
- same `latest` dist-tag rules as public releases. pnpm has no command that
555
+ same dist-tag rules as public releases. pnpm has no command that
440
556
  downloads a tarball with the registry's authentication, so the bytes are
441
557
  proven by the registry's integrity record rather than downloaded.
442
558
  - A not-found answer counts as absence only when `pnpm whoami` confirms
@@ -576,7 +692,7 @@ npm can hold accepted uploads for publish-time scanning before they become
576
692
  installable. A release with modules submits every package in publication order,
577
693
  then waits for availability across the submitted set so scans can overlap.
578
694
  Command failures and artifact conflicts still stop submission immediately.
579
- Every package, tarball and `latest` tag must verify before the release is
695
+ Every package, tarball and dist-tag must verify before the release is
580
696
  complete, and Docker promotion waits until every package verified.
581
697
 
582
698
  See [npm's publish-time scanning announcement](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/)
@@ -641,18 +757,77 @@ The normal release build generates a strict manifest for the new release version
641
757
  Replace the example sizes and hashes with the actual file identities. Names and
642
758
  paths must be canonical and unique. Regular files and their ancestor directories
643
759
  must not be symlinks; credential/runtime paths, traversal and globs are rejected.
644
- Assets are uploaded in manifest order. Put corresponding source and relinking
645
- materials before native executables, since public Gitea attachments also
646
- distribute those binaries.
760
+ The release is created as a **draft** and published only after every
761
+ attachment verified, so no attachment is ever public without the others —
762
+ native executables never appear without their corresponding source, relinking
763
+ materials and notices, whatever interrupts the release. Gitea shows a draft,
764
+ its attachment list and its attachment downloads only to accounts with write
765
+ access to the repository's releases; everyone else gets 404, also for the
766
+ attachment's UUID URL and for `/releases/download/<tag>/<name>`.
767
+
768
+ Attachments publish `concurrency` at a time (default 2, at most 6), largest
769
+ first, so an upload overlaps the verification download of another attachment.
770
+ Once an attachment publication fails, no further attachment starts; the ones
771
+ already running finish, because cutting a running transfer off would leave its
772
+ result inconclusive, and every failure is reported. The journal keeps each
773
+ attachment's own attempt, so `gitzone release resume` continues with exactly the
774
+ unfinished ones. A crash during concurrent uploads can leave several attachments
775
+ in `publishing`; each needs its own `--recover-attempt`, one resume at a time.
776
+
777
+ The lifecycle of the Gitea release:
778
+
779
+ 1. After the Git push, create the release with `draft: true` (or adopt the
780
+ draft or published release that already carries the tag).
781
+ 2. Upload every attachment into it and download and hash each one. While the
782
+ release is a draft, listing and downloads carry the token (sent only to the
783
+ configured Gitea origin, never along a redirect to another host); a draft's
784
+ attachment cannot be downloaded anonymously. The bytes hashed are the stored
785
+ object the public URL serves later, so integrity is proven the same way.
786
+ 3. Verify the complete set: nothing missing, nothing extra, every frozen
787
+ identity unchanged.
788
+ 4. Before publishing, every listed attachment must be exactly the one this run
789
+ downloaded and hashed — same attachment id and UUID — so an attachment
790
+ replaced after the final check, even by one of identical size, is never
791
+ published: that is a destination conflict and the release stays a draft. A
792
+ server that reports no UUIDs is held to the attachment id alone; there the
793
+ final check downloads every attachment again, and Gitea never replaces an
794
+ attachment's bytes under its id.
795
+ 5. Publish the release (`PATCH … {"draft": false}`), then prove the public
796
+ view: the release is anonymously visible with the same id, the anonymous
797
+ attachment list carries exactly the verified attachment ids and UUIDs, and
798
+ every attachment's public URL answers `200` with its frozen
799
+ `Content-Length` and no content encoding; no name or id may appear twice.
800
+ These public checks read headers only; the bytes are not downloaded again.
801
+ 6. Record the journal's completion, then publish npm.
802
+
803
+ Setting `draft: false` changes nothing but the flag, is idempotent, and its
804
+ result is observable, so it has no journal attempt of its own: a resume after a
805
+ crash before or after it finds the draft or the published release, verifies it
806
+ and continues. A release that an older gitzone already published keeps the
807
+ previous semantics: its attachments are listed and downloaded anonymously, and
808
+ publishing only verifies it. Because every attachment of such a release is
809
+ public the moment it lands, its missing attachments upload one at a time in
810
+ manifest order, whatever `concurrency` says, so sources and notices still come
811
+ before the binaries that follow them in the manifest.
812
+
813
+ Tag-triggered CI that reads the Gitea release sees the same thing anonymous
814
+ users see. The Git target pushes the tag before the Gitea target creates the
815
+ draft, so such a job starts while the release is still a draft or absent and
816
+ gets 404 for it until the release is published complete. A job that polls
817
+ until the release is complete (Spark's `verify-node-release.ts` treats a missing
818
+ release as pending and waits up to 40 minutes) keeps working, and it never sees
819
+ a partially uploaded release; a job that reads the release once, immediately,
820
+ fails, as it did before this change.
647
821
 
648
822
  Publication runs build → freeze every artifact → write schema-4 journal → Git →
649
823
  Gitea assets → npm. Stored assets use `asset.<sha256-of-name>.bin` filenames next
650
824
  to the retained npm archives. The CLI verifies local hashes before Git, then
651
- inspects or creates the exact public, non-draft, non-prerelease tag release.
652
- Every upload has a revisioned journal attempt. Each accepted attachment must
653
- download anonymously with the expected size and SHA256; authenticated redirects
654
- are rejected and anonymous downloads never carry the token. Transfers and
655
- hashing stream with bounded memory.
825
+ inspects or creates the exact non-prerelease tag release, as a draft until every
826
+ attachment verified (see below). Every upload has a revisioned journal attempt.
827
+ Each accepted attachment must download with the expected size and SHA256 —
828
+ with the token while the release is a draft, anonymously once it is published;
829
+ authenticated API redirects are rejected and the token never leaves the
830
+ configured Gitea origin. Transfers and hashing stream with bounded memory.
656
831
 
657
832
  A Gitea request is bounded by its progress, not by a fixed duration, so a large
658
833
  binary on a slow server finishes as long as bytes keep moving:
@@ -662,6 +837,12 @@ binary on a slow server finishes as long as bytes keep moving:
662
837
  | `responseTimeoutSeconds` | 120 | Wait for response headers of a metadata request or download |
663
838
  | `stallTimeoutSeconds` | 60 | Longest gap without a byte sent or received while a transfer runs |
664
839
  | `minimumKiBPerSecond` | 256 | Rate floor; a request may take the two bounds above plus its size at this rate |
840
+ | `concurrency` | 2 | Attachments published at the same time (1 to 6), largest first |
841
+
842
+ The rate floor applies to every request on its own. With `concurrency` N the
843
+ link has to carry N times `minimumKiBPerSecond`; on a link slower than that,
844
+ concurrent transfers fail as too slow where one alone would pass. `gitzone
845
+ config doctor` prints the rate the configuration needs.
665
846
 
666
847
  Gitea stores an upload before it answers, which takes minutes for a large
667
848
  binary. After an upload's last byte the CLI therefore waits for the upload's
@@ -685,12 +866,29 @@ of 461373440 bytes received)`.
685
866
  The complete remote attachment set must equal the manifest. Extra names,
686
867
  duplicates, changed release identity, or conflicting bytes stop publication;
687
868
  the CLI has no deletion or replacement path. It verifies the complete set again
688
- before npm. An inconclusive or rejected upload leaves npm unpublished and retains
869
+ before it publishes the draft and before npm: the set must be complete with no
870
+ extra attachment, and every attachment must still carry its frozen name, size
871
+ and URL. An attachment this
872
+ run uploaded, downloaded and hashed is not downloaded a second time
873
+ when its attachment id and UUID are unchanged since that download. Gitea stores
874
+ an attachment's bytes under its UUID and its API can only rename an attachment,
875
+ so an unchanged id and UUID mean the bytes the run hashed. Every other
876
+ attachment, including one whose id or UUID changed, or every attachment on a
877
+ server that reports no UUIDs, is downloaded and hashed again.
878
+
879
+ A journal records its completion (`completedAt`) only after that final check
880
+ passed. A Gitea-asset release without npm used to be recorded as complete as
881
+ soon as its last attachment verified, before the final check ran; now a journal
882
+ whose targets all verified but whose final check has not passed reads
883
+ `completed: no`, and `gitzone release resume <version> -y` runs the check.
884
+
885
+ An inconclusive or rejected upload leaves npm unpublished and retains
689
886
  the journal for `gitzone release resume <version> -y`. Resume uses the recorded
690
887
  destination and retained bytes without rebuilding or repacking. It checks the
691
888
  metadata of attachments the journal records as verified without downloading
692
889
  them again, downloads and hashes only the unverified ones, and then verifies the
693
- complete public set once more before npm, even for completed journals. An unresolved active attempt requires
890
+ complete public set once more before npm, even for completed journals; a resume
891
+ runs in a new process, so that final check downloads every attachment. An unresolved active attempt requires
694
892
  the exact `--recover-attempt` identifier after its publisher has stopped.
695
893
 
696
894
  Gitea's general attachment-enabled switch is checked. Its issue-attachment size
@@ -865,6 +1063,15 @@ exits 0:
865
1063
  Release running detached: run <id>, process group <pid>, log <path>. Follow it with `tail -f <path>`; `gitzone release inspect` shows its outcome.
866
1064
  ```
867
1065
 
1066
+ Phase lines in the log carry the time they were printed, for example
1067
+ `[2026-10-03T01:48:31.402Z] Running tests` followed by `Running tests passed in
1068
+ 7 min 8 s.`, so the log of a release shows where its time went: tests, the
1069
+ release checkout and its build, the Git target, the Gitea release and every
1070
+ attachment (`uploading <bytes>`, `uploaded, downloaded and hashed in <time>`),
1071
+ the final attachment-set verification, the publication of the draft, each npm registry and its availability
1072
+ wait, and Docker qualification, promotion and cleanup. A foreground release
1073
+ prints the same lines.
1074
+
868
1075
  When the supervisor refuses to start the release, the launcher prints why and
869
1076
  exits 1. When the supervisor does not report within 60 seconds, the launcher
870
1077
  terminates its whole process group (`SIGTERM`, and `SIGKILL` after another 10
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '8.3.2',
6
+ version: '8.5.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
  }
@@ -6,9 +6,16 @@ import {
6
6
  type ProjectType,
7
7
  } from "./mod_commit/mod.helpers.js";
8
8
  import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
9
+ import {
10
+ getReleaseDistTag,
11
+ parseReleaseLine,
12
+ type IReleaseLine,
13
+ } from "./mod_release/helpers.releaseline.js";
9
14
  import { defaultNpmVerificationWindowMinutes } from "./mod_release/helpers.npmartifact.js";
10
15
  import {
16
+ defaultGiteaAssetConcurrency,
11
17
  defaultGiteaAssetTransferLimits,
18
+ maximumGiteaAssetConcurrency,
12
19
  type IGiteaAssetTransferLimits,
13
20
  } from "./mod_release/helpers.giteaassets.js";
14
21
  import {
@@ -81,6 +88,13 @@ export interface IReleaseGiteaAssetsTargetConfig {
81
88
  stallTimeoutSeconds?: number;
82
89
  /** Rate floor that bounds a whole transfer by its size; default 256. */
83
90
  minimumKiBPerSecond?: number;
91
+ /**
92
+ * Attachments published at the same time, largest first; default 2, at most
93
+ * 6. The order is safe because the release stays a draft, invisible to the
94
+ * public, until the complete set verified. Uploads into a release an older
95
+ * gitzone already published run one at a time in manifest order instead.
96
+ */
97
+ concurrency?: number;
84
98
  }
85
99
 
86
100
  export interface IResolvedReleaseGiteaAssetsConfiguration {
@@ -184,6 +198,21 @@ export const resolveGiteaAssetTransferLimits = (
184
198
  ) * 1024,
185
199
  });
186
200
 
201
+ /**
202
+ * How many attachments a release publishes at the same time. Like the
203
+ * transfer bounds this is tuning, not identity: it may change between resumes.
204
+ */
205
+ export const resolveGiteaAssetConcurrency = (
206
+ configArg: IReleaseGiteaAssetsTargetConfig,
207
+ ): number =>
208
+ resolveWholeNumber(
209
+ configArg.concurrency,
210
+ "concurrency",
211
+ defaultGiteaAssetConcurrency,
212
+ maximumGiteaAssetConcurrency,
213
+ "attachments",
214
+ );
215
+
187
216
  /** Match the resolved destination, without guessing SSH aliases or URL rewrites. */
188
217
  export const assertGiteaAssetsGitDestination = (
189
218
  configArg: IResolvedReleaseGiteaAssetsConfiguration,
@@ -235,6 +264,14 @@ export interface IReleaseWorkflowConfig {
235
264
  };
236
265
  /** Canonical x.y.z minimum for the next release version. */
237
266
  versionFloor?: string;
267
+ /**
268
+ * A maintenance line, committed on its branch: that branch becomes the
269
+ * release source, and npm publishes under `distTag` instead of `latest`.
270
+ */
271
+ line?: {
272
+ branch?: string;
273
+ distTag?: string;
274
+ };
238
275
  preflight?: {
239
276
  test?: boolean;
240
277
  build?: boolean;
@@ -279,6 +316,10 @@ export interface IResolvedReleaseWorkflow {
279
316
  changelogPendingSection: "Pending";
280
317
  changelogVersionHeading: "## {{date}} - {{version}}";
281
318
  versionFloor?: string;
319
+ /** The maintenance line this branch releases; absent releases `main`. */
320
+ line?: IReleaseLine;
321
+ /** `latest`, or the dist-tag of the release line. */
322
+ npmDistTag: string;
282
323
  gitEnabled: boolean;
283
324
  gitRemote: string;
284
325
  /** Bound of one attempt of every Git remote inspection. */
@@ -294,6 +335,8 @@ export interface IResolvedReleaseWorkflow {
294
335
  npmVerificationWindowMinutes: number;
295
336
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
296
337
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
338
+ /** Attachments published at the same time. */
339
+ giteaAssetConcurrency?: number;
297
340
  dockerEnabled: boolean;
298
341
  dockerEngine: "tsdocker";
299
342
  dockerRegistry?: string;
@@ -317,6 +360,7 @@ export type TReleaseRecordedPlan = Pick<
317
360
  >;
318
361
 
319
362
  export interface IResolvedReleaseResumeConfiguration {
363
+ line?: IReleaseLine;
320
364
  gitRemote: string;
321
365
  gitRemoteTimeoutSeconds: number;
322
366
  npmRegistries: string[];
@@ -326,6 +370,7 @@ export interface IResolvedReleaseResumeConfiguration {
326
370
  cleanTestArtifacts: boolean;
327
371
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
328
372
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
373
+ giteaAssetConcurrency?: number;
329
374
  }
330
375
 
331
376
  export type TResolvedReleaseDockerConfiguration = Pick<
@@ -752,6 +797,9 @@ const buildReleasePlan = (options: {
752
797
  projectTypeHasPackageJson(options.projectType)
753
798
  )
754
799
  plan.push("preflight.lockfile");
800
+ // Every npm release reads the registries' dist-tags before it creates
801
+ // anything: `latest` never moves downwards, and a line never takes it.
802
+ if (options.targets.includes("npm")) plan.push("preflight.npmDistTags");
755
803
  if (options.runTests) plan.push("preflight.test");
756
804
  if (options.mergeRequested) {
757
805
  plan.push("integration.main", "integration.pushMain");
@@ -919,6 +967,33 @@ const assertNoRemovedNpmTargetSettings = (
919
967
  }
920
968
  };
921
969
 
970
+ /**
971
+ * A maintenance line publishes only to Git and npm. A Docker target promotes
972
+ * aliases such as `latest`, and Gitea marks its newest release as the latest
973
+ * one; neither may follow an older major. A line releases its branch in
974
+ * place, so it never integrates another branch.
975
+ */
976
+ const assertReleaseLineTargets = (
977
+ lineArg: IReleaseLine | undefined,
978
+ targetsArg: TReleaseTarget[],
979
+ mergeRequestedArg: boolean,
980
+ ): void => {
981
+ if (!lineArg) return;
982
+ const refused = targetsArg.filter(
983
+ (targetArg) => targetArg === "docker" || targetArg === "giteaAssets",
984
+ );
985
+ if (refused.length > 0) {
986
+ throw new Error(
987
+ `Release line ${lineArg.distTag} publishes only to Git and npm; disable ${refused.join(" and ")} on ${lineArg.branch}.`,
988
+ );
989
+ }
990
+ if (mergeRequestedArg) {
991
+ throw new Error(
992
+ `\`gitzone release --merge\` cannot release the ${lineArg.distTag} line: a maintenance line releases its branch ${lineArg.branch} in place.`,
993
+ );
994
+ }
995
+ };
996
+
922
997
  /**
923
998
  * Resolves the release from its configuration and command line. A resume of
924
999
  * a recorded release passes `recordedPlanArg`, which replaces every command
@@ -931,6 +1006,7 @@ export const resolveReleaseWorkflow = async (
931
1006
  const cliConfig = await readCliWorkflowConfig();
932
1007
  const releaseConfig = cliConfig.release || {};
933
1008
  const versionFloor = parseReleaseVersionFloor(releaseConfig.versionFloor);
1009
+ const line = parseReleaseLine(releaseConfig.line);
934
1010
  const targetConfig = releaseConfig.targets || {};
935
1011
  const gitConfig = targetConfig.git || {};
936
1012
  const npmConfig = targetConfig.npm || {};
@@ -1020,6 +1096,7 @@ export const resolveReleaseWorkflow = async (
1020
1096
  "Gitea asset releases cannot combine Docker or --merge; integrate main before release.",
1021
1097
  );
1022
1098
  }
1099
+ assertReleaseLineTargets(line, targets, argvArg.merge === true);
1023
1100
  let npmRegistries: string[] = [];
1024
1101
  if (targets.includes("npm")) {
1025
1102
  if (
@@ -1092,6 +1169,8 @@ export const resolveReleaseWorkflow = async (
1092
1169
  changelogPendingSection: "Pending",
1093
1170
  changelogVersionHeading: "## {{date}} - {{version}}",
1094
1171
  ...(versionFloor ? { versionFloor } : {}),
1172
+ ...(line ? { line } : {}),
1173
+ npmDistTag: getReleaseDistTag(line),
1095
1174
  gitEnabled,
1096
1175
  gitRemote: gitConfig.remote || "origin",
1097
1176
  // Dormant settings of an inactive target are not validated.
@@ -1114,6 +1193,9 @@ export const resolveReleaseWorkflow = async (
1114
1193
  giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1115
1194
  targetConfig.giteaAssets || {},
1116
1195
  ),
1196
+ giteaAssetConcurrency: resolveGiteaAssetConcurrency(
1197
+ targetConfig.giteaAssets || {},
1198
+ ),
1117
1199
  }
1118
1200
  : {}),
1119
1201
  dockerEnabled,
@@ -1129,6 +1211,7 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1129
1211
  }): Promise<IResolvedReleaseResumeConfiguration> => {
1130
1212
  const cliConfig = await readCliWorkflowConfig();
1131
1213
  const releaseConfig = cliConfig.release || {};
1214
+ const line = parseReleaseLine(releaseConfig.line);
1132
1215
  const targetConfig = releaseConfig.targets || {};
1133
1216
  const gitConfig = targetConfig.git || {};
1134
1217
  const npmConfig = targetConfig.npm || {};
@@ -1192,6 +1275,7 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1192
1275
  }
1193
1276
 
1194
1277
  return {
1278
+ ...(line ? { line } : {}),
1195
1279
  gitRemote,
1196
1280
  gitRemoteTimeoutSeconds: optionsArg.git
1197
1281
  ? resolveGitRemoteTimeoutSeconds(gitConfig.remoteTimeoutSeconds)
@@ -1209,6 +1293,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1209
1293
  giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1210
1294
  targetConfig.giteaAssets || {},
1211
1295
  ),
1296
+ giteaAssetConcurrency: resolveGiteaAssetConcurrency(
1297
+ targetConfig.giteaAssets || {},
1298
+ ),
1212
1299
  }
1213
1300
  : {}),
1214
1301
  };