@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/helpers.workflow.d.ts +29 -0
- package/dist_ts/helpers.workflow.js +37 -2
- package/dist_ts/mod_config/index.js +45 -3
- package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
- package/dist_ts/mod_release/classes.releasejournal.js +108 -13
- package/dist_ts/mod_release/helpers.giteaassets.d.ts +47 -1
- package/dist_ts/mod_release/helpers.giteaassets.js +236 -56
- package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
- package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
- package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
- package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
- package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
- package/dist_ts/mod_release/helpers.releaseline.js +129 -0
- package/dist_ts/mod_release/helpers.releasephase.d.ts +9 -0
- package/dist_ts/mod_release/helpers.releasephase.js +25 -0
- package/dist_ts/mod_release/helpers.releasepreparation.js +6 -3
- package/dist_ts/mod_release/helpers.releasepublication.d.ts +12 -1
- package/dist_ts/mod_release/helpers.releasepublication.js +235 -52
- package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
- package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
- package/dist_ts/mod_release/index.js +149 -44
- package/dist_ts/mod_release/interfaces.giteaassets.d.ts +16 -0
- package/package.json +5 -5
- package/readme.md +224 -17
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/helpers.workflow.ts +87 -0
- package/ts/mod_config/index.ts +50 -1
- package/ts/mod_release/classes.releasejournal.ts +165 -14
- package/ts/mod_release/helpers.giteaassets.ts +319 -64
- package/ts/mod_release/helpers.npmartifact.ts +302 -22
- package/ts/mod_release/helpers.releasebranch.ts +120 -45
- package/ts/mod_release/helpers.releaseline.ts +214 -0
- package/ts/mod_release/helpers.releasephase.ts +26 -0
- package/ts/mod_release/helpers.releasepreparation.ts +12 -3
- package/ts/mod_release/helpers.releasepublication.ts +425 -78
- package/ts/mod_release/helpers.releaseversion.ts +5 -1
- package/ts/mod_release/index.ts +213 -32
- 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.
|
|
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.
|
|
44
|
-
"@git.zone/tspack": "^1.4.
|
|
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": "^
|
|
47
|
-
"@types/node": "^26.6.
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
645
|
-
|
|
646
|
-
|
|
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
|
|
652
|
-
Every upload has a revisioned journal attempt.
|
|
653
|
-
download
|
|
654
|
-
|
|
655
|
-
|
|
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
|
|
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
|
|
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
|
package/ts/00_commitinfo_data.ts
CHANGED
|
@@ -3,6 +3,6 @@
|
|
|
3
3
|
*/
|
|
4
4
|
export const commitinfo = {
|
|
5
5
|
name: '@git.zone/cli',
|
|
6
|
-
version: '8.
|
|
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
|
}
|
package/ts/helpers.workflow.ts
CHANGED
|
@@ -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
|
};
|