@git.zone/cli 8.4.0 → 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 +15 -0
- package/dist_ts/helpers.workflow.js +9 -2
- package/dist_ts/mod_config/index.js +4 -3
- package/dist_ts/mod_release/classes.releasejournal.js +14 -5
- 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.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 +10 -1
- package/dist_ts/mod_release/helpers.releasepublication.js +150 -34
- package/dist_ts/mod_release/index.js +20 -5
- package/dist_ts/mod_release/interfaces.giteaassets.d.ts +16 -0
- package/package.json +4 -4
- package/readme.md +101 -10
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/helpers.workflow.ts +33 -0
- package/ts/mod_config/index.ts +3 -1
- package/ts/mod_release/classes.releasejournal.ts +16 -4
- package/ts/mod_release/helpers.giteaassets.ts +319 -64
- 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 +257 -62
- package/ts/mod_release/index.ts +36 -6
- package/ts/mod_release/interfaces.giteaassets.ts +19 -0
package/readme.md
CHANGED
|
@@ -757,18 +757,77 @@ The normal release build generates a strict manifest for the new release version
|
|
|
757
757
|
Replace the example sizes and hashes with the actual file identities. Names and
|
|
758
758
|
paths must be canonical and unique. Regular files and their ancestor directories
|
|
759
759
|
must not be symlinks; credential/runtime paths, traversal and globs are rejected.
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
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.
|
|
763
821
|
|
|
764
822
|
Publication runs build → freeze every artifact → write schema-4 journal → Git →
|
|
765
823
|
Gitea assets → npm. Stored assets use `asset.<sha256-of-name>.bin` filenames next
|
|
766
824
|
to the retained npm archives. The CLI verifies local hashes before Git, then
|
|
767
|
-
inspects or creates the exact
|
|
768
|
-
Every upload has a revisioned journal attempt.
|
|
769
|
-
download
|
|
770
|
-
|
|
771
|
-
|
|
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.
|
|
772
831
|
|
|
773
832
|
A Gitea request is bounded by its progress, not by a fixed duration, so a large
|
|
774
833
|
binary on a slow server finishes as long as bytes keep moving:
|
|
@@ -778,6 +837,12 @@ binary on a slow server finishes as long as bytes keep moving:
|
|
|
778
837
|
| `responseTimeoutSeconds` | 120 | Wait for response headers of a metadata request or download |
|
|
779
838
|
| `stallTimeoutSeconds` | 60 | Longest gap without a byte sent or received while a transfer runs |
|
|
780
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.
|
|
781
846
|
|
|
782
847
|
Gitea stores an upload before it answers, which takes minutes for a large
|
|
783
848
|
binary. After an upload's last byte the CLI therefore waits for the upload's
|
|
@@ -801,12 +866,29 @@ of 461373440 bytes received)`.
|
|
|
801
866
|
The complete remote attachment set must equal the manifest. Extra names,
|
|
802
867
|
duplicates, changed release identity, or conflicting bytes stop publication;
|
|
803
868
|
the CLI has no deletion or replacement path. It verifies the complete set again
|
|
804
|
-
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
|
|
805
886
|
the journal for `gitzone release resume <version> -y`. Resume uses the recorded
|
|
806
887
|
destination and retained bytes without rebuilding or repacking. It checks the
|
|
807
888
|
metadata of attachments the journal records as verified without downloading
|
|
808
889
|
them again, downloads and hashes only the unverified ones, and then verifies the
|
|
809
|
-
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
|
|
810
892
|
the exact `--recover-attempt` identifier after its publisher has stopped.
|
|
811
893
|
|
|
812
894
|
Gitea's general attachment-enabled switch is checked. Its issue-attachment size
|
|
@@ -981,6 +1063,15 @@ exits 0:
|
|
|
981
1063
|
Release running detached: run <id>, process group <pid>, log <path>. Follow it with `tail -f <path>`; `gitzone release inspect` shows its outcome.
|
|
982
1064
|
```
|
|
983
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
|
+
|
|
984
1075
|
When the supervisor refuses to start the release, the launcher prints why and
|
|
985
1076
|
exits 1. When the supervisor does not report within 60 seconds, the launcher
|
|
986
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
|
@@ -13,7 +13,9 @@ import {
|
|
|
13
13
|
} from "./mod_release/helpers.releaseline.js";
|
|
14
14
|
import { defaultNpmVerificationWindowMinutes } from "./mod_release/helpers.npmartifact.js";
|
|
15
15
|
import {
|
|
16
|
+
defaultGiteaAssetConcurrency,
|
|
16
17
|
defaultGiteaAssetTransferLimits,
|
|
18
|
+
maximumGiteaAssetConcurrency,
|
|
17
19
|
type IGiteaAssetTransferLimits,
|
|
18
20
|
} from "./mod_release/helpers.giteaassets.js";
|
|
19
21
|
import {
|
|
@@ -86,6 +88,13 @@ export interface IReleaseGiteaAssetsTargetConfig {
|
|
|
86
88
|
stallTimeoutSeconds?: number;
|
|
87
89
|
/** Rate floor that bounds a whole transfer by its size; default 256. */
|
|
88
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;
|
|
89
98
|
}
|
|
90
99
|
|
|
91
100
|
export interface IResolvedReleaseGiteaAssetsConfiguration {
|
|
@@ -189,6 +198,21 @@ export const resolveGiteaAssetTransferLimits = (
|
|
|
189
198
|
) * 1024,
|
|
190
199
|
});
|
|
191
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
|
+
|
|
192
216
|
/** Match the resolved destination, without guessing SSH aliases or URL rewrites. */
|
|
193
217
|
export const assertGiteaAssetsGitDestination = (
|
|
194
218
|
configArg: IResolvedReleaseGiteaAssetsConfiguration,
|
|
@@ -311,6 +335,8 @@ export interface IResolvedReleaseWorkflow {
|
|
|
311
335
|
npmVerificationWindowMinutes: number;
|
|
312
336
|
giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
|
|
313
337
|
giteaAssetTransfer?: IGiteaAssetTransferLimits;
|
|
338
|
+
/** Attachments published at the same time. */
|
|
339
|
+
giteaAssetConcurrency?: number;
|
|
314
340
|
dockerEnabled: boolean;
|
|
315
341
|
dockerEngine: "tsdocker";
|
|
316
342
|
dockerRegistry?: string;
|
|
@@ -344,6 +370,7 @@ export interface IResolvedReleaseResumeConfiguration {
|
|
|
344
370
|
cleanTestArtifacts: boolean;
|
|
345
371
|
giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
|
|
346
372
|
giteaAssetTransfer?: IGiteaAssetTransferLimits;
|
|
373
|
+
giteaAssetConcurrency?: number;
|
|
347
374
|
}
|
|
348
375
|
|
|
349
376
|
export type TResolvedReleaseDockerConfiguration = Pick<
|
|
@@ -1166,6 +1193,9 @@ export const resolveReleaseWorkflow = async (
|
|
|
1166
1193
|
giteaAssetTransfer: resolveGiteaAssetTransferLimits(
|
|
1167
1194
|
targetConfig.giteaAssets || {},
|
|
1168
1195
|
),
|
|
1196
|
+
giteaAssetConcurrency: resolveGiteaAssetConcurrency(
|
|
1197
|
+
targetConfig.giteaAssets || {},
|
|
1198
|
+
),
|
|
1169
1199
|
}
|
|
1170
1200
|
: {}),
|
|
1171
1201
|
dockerEnabled,
|
|
@@ -1263,6 +1293,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
|
|
|
1263
1293
|
giteaAssetTransfer: resolveGiteaAssetTransferLimits(
|
|
1264
1294
|
targetConfig.giteaAssets || {},
|
|
1265
1295
|
),
|
|
1296
|
+
giteaAssetConcurrency: resolveGiteaAssetConcurrency(
|
|
1297
|
+
targetConfig.giteaAssets || {},
|
|
1298
|
+
),
|
|
1266
1299
|
}
|
|
1267
1300
|
: {}),
|
|
1268
1301
|
};
|
package/ts/mod_config/index.ts
CHANGED
|
@@ -24,6 +24,7 @@ import {
|
|
|
24
24
|
import {
|
|
25
25
|
getDeclaredTsdockerRange,
|
|
26
26
|
resolveGiteaAssetsConfiguration,
|
|
27
|
+
resolveGiteaAssetConcurrency,
|
|
27
28
|
resolveGiteaAssetTransferLimits,
|
|
28
29
|
resolveGitRemoteTimeoutSeconds,
|
|
29
30
|
resolveNpmVerificationWindowMinutes,
|
|
@@ -1966,9 +1967,10 @@ async function validateReleaseConfig(
|
|
|
1966
1967
|
try {
|
|
1967
1968
|
resolveGiteaAssetsConfiguration(targets.giteaAssets);
|
|
1968
1969
|
const transfer = resolveGiteaAssetTransferLimits(targets.giteaAssets);
|
|
1970
|
+
const concurrency = resolveGiteaAssetConcurrency(targets.giteaAssets);
|
|
1969
1971
|
findings.push({
|
|
1970
1972
|
level: "ok",
|
|
1971
|
-
message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s`,
|
|
1973
|
+
message: `Gitea asset transfers wait ${transfer.responseTimeoutMs / 1000} s for a response, fail after ${transfer.stallTimeoutMs / 1000} s without progress, and must average at least ${transfer.minimumBytesPerSecond / 1024} KiB/s each; ${concurrency} run at the same time, so the link must carry ${(concurrency * transfer.minimumBytesPerSecond) / 1024} KiB/s`,
|
|
1972
1974
|
});
|
|
1973
1975
|
if (targets.git?.enabled === false || targets.docker?.enabled === true)
|
|
1974
1976
|
throw new Error(
|
|
@@ -1464,12 +1464,23 @@ const assertReleaseJournalV4 = (
|
|
|
1464
1464
|
...journal.giteaAssets.assets,
|
|
1465
1465
|
...journal.npm.registries,
|
|
1466
1466
|
];
|
|
1467
|
+
// Attachments may publish concurrently, each under its own attempt; any
|
|
1468
|
+
// other target has one owner and never overlaps them.
|
|
1469
|
+
const otherPublishing = [
|
|
1470
|
+
journal.git,
|
|
1471
|
+
journal.giteaAssets.release,
|
|
1472
|
+
...journal.npm.registries,
|
|
1473
|
+
].filter((entry) => entry.state === "publishing").length;
|
|
1474
|
+
const assetsPublishing = journal.giteaAssets.assets.filter(
|
|
1475
|
+
(entry) => entry.state === "publishing",
|
|
1476
|
+
).length;
|
|
1467
1477
|
if (
|
|
1468
1478
|
journal.git.state === "skipped" ||
|
|
1469
|
-
|
|
1479
|
+
otherPublishing > 1 ||
|
|
1480
|
+
(otherPublishing > 0 && assetsPublishing > 0)
|
|
1470
1481
|
) {
|
|
1471
1482
|
throw new Error(
|
|
1472
|
-
"Gitea assets require an active Git target and one publication owner.",
|
|
1483
|
+
"Gitea assets require an active Git target and one publication owner outside concurrent attachment uploads.",
|
|
1473
1484
|
);
|
|
1474
1485
|
}
|
|
1475
1486
|
const assetStates = journal.giteaAssets.assets;
|
|
@@ -1503,8 +1514,9 @@ const assertReleaseJournalV4 = (
|
|
|
1503
1514
|
completed > journal.updatedAt
|
|
1504
1515
|
)
|
|
1505
1516
|
throw new Error("Release journal completion state is inconsistent.");
|
|
1506
|
-
}
|
|
1507
|
-
|
|
1517
|
+
}
|
|
1518
|
+
// Every target verified with no completedAt yet: the final verification of
|
|
1519
|
+
// the complete attachment set has not passed, and resume runs it.
|
|
1508
1520
|
return journal;
|
|
1509
1521
|
};
|
|
1510
1522
|
|