@git.zone/cli 8.4.0 → 8.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/readme.md CHANGED
@@ -757,18 +757,115 @@ 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
- Assets are uploaded in manifest order. Put corresponding source and relinking
761
- materials before native executables, since public Gitea attachments also
762
- 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 one at a time in manifest order by default: each uploads,
769
+ then is downloaded and hashed, then the next starts. Two transfers in the same
770
+ direction share the link, so each takes longer than it would alone; a large
771
+ upload that runs long enough outlasts the reverse proxy in front of Gitea, which
772
+ then answers HTTP 504 although the bytes kept moving (Spark 35.0.1: two
773
+ concurrent 385 MB uploads took over 11 minutes each, against about 3 minutes
774
+ each one after another, and one ended in a 504). Every upload must therefore
775
+ finish, including the time Gitea needs to store it, within that proxy's timeout,
776
+ and gitzone never runs two uploads, or two verification downloads, at the same
777
+ time. `concurrency: 2` pipelines the attachments instead: the next one uploads
778
+ while the previous one is downloaded and hashed, largest first so the last
779
+ verification is a short one. That is the only overlap that does not share a
780
+ direction; on a link where the two directions are not independent, keep the
781
+ default.
782
+
783
+ Once an attachment publication fails, no further attachment starts; the one
784
+ already running finishes, because cutting a running transfer off would leave its
785
+ result inconclusive, and every failure is reported. The journal keeps each
786
+ attachment's own attempt, so `gitzone release resume` continues with exactly the
787
+ unfinished ones. A crash while pipelining can leave two attachments in
788
+ `publishing`; each needs its own `--recover-attempt`, one resume at a time.
789
+
790
+ An upload that ends in HTTP 504 (or any other unknown outcome) is inspected right
791
+ away: an attachment Gitea stored anyway is downloaded and hashed and then counts
792
+ as published, a missing one is recorded as failed and uploaded again on resume.
793
+ If the proxy let Gitea finish the abandoned request after the resume uploaded the
794
+ attachment again, the release lists the name twice; that is a destination
795
+ conflict that stops the release, never a silent replacement.
796
+
797
+ The lifecycle of the Gitea release:
798
+
799
+ 1. After the Git push, wait until Gitea has processed the pushed tag, then
800
+ create the release with `draft: true` (or adopt the draft or published
801
+ release that already carries the tag) and read it back. Gitea processes a
802
+ tag push in its push queue after the push returned, sometimes minutes later,
803
+ and publishes (`draft: false`) any release it then finds for the tag, so a
804
+ draft created earlier would turn public on its own with the attachments it
805
+ has by then (Spark 35.0.1 with gitzone 8.5.0: the draft turned public while
806
+ its two largest binaries were uploading). Processing the tag writes a
807
+ tag-only release row, which the API hides and the public release page
808
+ (`/<owner>/<repo>/releases/tag/<tag>`) shows; once that page answers 200,
809
+ creating the release converts that row into the draft in place and Gitea
810
+ never touches it again. The wait polls every 5 seconds for at most 15
811
+ minutes; when it runs out, nothing was created and `gitzone release resume`
812
+ waits again. A release that this run created must read back as a draft,
813
+ otherwise the release stops before any upload.
814
+ 2. Upload every attachment into it and download and hash each one. While the
815
+ release is a draft, listing and downloads carry the token (sent only to the
816
+ configured Gitea origin, never along a redirect to another host); a draft's
817
+ attachment cannot be downloaded anonymously. The bytes hashed are the stored
818
+ object the public URL serves later, so integrity is proven the same way.
819
+ 3. Verify the complete set: nothing missing, nothing extra, every frozen
820
+ identity unchanged.
821
+ 4. Before publishing, every listed attachment must be exactly the one this run
822
+ downloaded and hashed — same attachment id and UUID — so an attachment
823
+ replaced after the final check, even by one of identical size, is never
824
+ published: that is a destination conflict and the release stays a draft. A
825
+ server that reports no UUIDs is held to the attachment id alone; there the
826
+ final check downloads every attachment again, and Gitea never replaces an
827
+ attachment's bytes under its id.
828
+ 5. Publish the release (`PATCH … {"draft": false}`), then prove the public
829
+ view: the release is anonymously visible with the same id, the anonymous
830
+ attachment list carries exactly the verified attachment ids and UUIDs, and
831
+ every attachment's public URL answers `200` with its frozen
832
+ `Content-Length` and no content encoding; no name or id may appear twice.
833
+ These public checks read headers only; the bytes are not downloaded again.
834
+ 6. Record the journal's completion, then publish npm.
835
+
836
+ Setting `draft: false` changes nothing but the flag, is idempotent, and its
837
+ result is observable, so it has no journal attempt of its own: a resume after a
838
+ crash before or after it finds the draft or the published release, verifies it
839
+ and continues. A release that an older gitzone already published keeps the
840
+ previous semantics: its attachments are listed and downloaded anonymously, and
841
+ publishing only verifies it. Because every attachment of such a release is
842
+ public the moment it lands, its missing attachments upload one at a time in
843
+ manifest order, whatever `concurrency` says, so sources and notices still come
844
+ before the binaries that follow them in the manifest. The upload order and
845
+ concurrency follow the state Gitea reports, never the state gitzone intended,
846
+ and every upload first reads the release again: a draft that turned public
847
+ meanwhile stops the release before the next byte is sent
848
+ (`GiteaReleaseStateChangedError`), and so does a draft that turned public
849
+ before publication; resume then continues it as a published release.
850
+
851
+ Tag-triggered CI that reads the Gitea release sees the same thing anonymous
852
+ users see. The Git target pushes the tag before the Gitea target creates the
853
+ draft, so such a job starts while the release is still a draft or absent and
854
+ gets 404 for it until the release is published complete. A job that polls
855
+ until the release is complete (Spark's `verify-node-release.ts` treats a missing
856
+ release as pending and waits up to 40 minutes) keeps working, and it never sees
857
+ a partially uploaded release; a job that reads the release once, immediately,
858
+ fails, as it did before this change.
763
859
 
764
860
  Publication runs build → freeze every artifact → write schema-4 journal → Git →
765
861
  Gitea assets → npm. Stored assets use `asset.<sha256-of-name>.bin` filenames next
766
862
  to the retained npm archives. The CLI verifies local hashes before Git, then
767
- inspects or creates the exact public, non-draft, non-prerelease tag release.
768
- Every upload has a revisioned journal attempt. Each accepted attachment must
769
- download anonymously with the expected size and SHA256; authenticated redirects
770
- are rejected and anonymous downloads never carry the token. Transfers and
771
- hashing stream with bounded memory.
863
+ inspects or creates the exact non-prerelease tag release, as a draft until every
864
+ attachment verified (see below). Every upload has a revisioned journal attempt.
865
+ Each accepted attachment must download with the expected size and SHA256 —
866
+ with the token while the release is a draft, anonymously once it is published;
867
+ authenticated API redirects are rejected and the token never leaves the
868
+ configured Gitea origin. Transfers and hashing stream with bounded memory.
772
869
 
773
870
  A Gitea request is bounded by its progress, not by a fixed duration, so a large
774
871
  binary on a slow server finishes as long as bytes keep moving:
@@ -778,6 +875,14 @@ binary on a slow server finishes as long as bytes keep moving:
778
875
  | `responseTimeoutSeconds` | 120 | Wait for response headers of a metadata request or download |
779
876
  | `stallTimeoutSeconds` | 60 | Longest gap without a byte sent or received while a transfer runs |
780
877
  | `minimumKiBPerSecond` | 256 | Rate floor; a request may take the two bounds above plus its size at this rate |
878
+ | `concurrency` | 1 | Attachments of a draft in progress at the same time (1 or 2); 2 uploads one while the previous is verified |
879
+
880
+ The rate floor applies to every request on its own. Since uploads never
881
+ overlap, and neither do downloads, each direction of the link has to carry
882
+ `minimumKiBPerSecond` once, whatever `concurrency` says. `gitzone config
883
+ doctor` prints that rate. These bounds are gitzone's own; a reverse proxy in
884
+ front of Gitea can end a request sooner (HTTP 504), which is why uploads never
885
+ share the link.
781
886
 
782
887
  Gitea stores an upload before it answers, which takes minutes for a large
783
888
  binary. After an upload's last byte the CLI therefore waits for the upload's
@@ -801,12 +906,29 @@ of 461373440 bytes received)`.
801
906
  The complete remote attachment set must equal the manifest. Extra names,
802
907
  duplicates, changed release identity, or conflicting bytes stop publication;
803
908
  the CLI has no deletion or replacement path. It verifies the complete set again
804
- before npm. An inconclusive or rejected upload leaves npm unpublished and retains
909
+ before it publishes the draft and before npm: the set must be complete with no
910
+ extra attachment, and every attachment must still carry its frozen name, size
911
+ and URL. An attachment this
912
+ run uploaded, downloaded and hashed is not downloaded a second time
913
+ when its attachment id and UUID are unchanged since that download. Gitea stores
914
+ an attachment's bytes under its UUID and its API can only rename an attachment,
915
+ so an unchanged id and UUID mean the bytes the run hashed. Every other
916
+ attachment, including one whose id or UUID changed, or every attachment on a
917
+ server that reports no UUIDs, is downloaded and hashed again.
918
+
919
+ A journal records its completion (`completedAt`) only after that final check
920
+ passed. A Gitea-asset release without npm used to be recorded as complete as
921
+ soon as its last attachment verified, before the final check ran; now a journal
922
+ whose targets all verified but whose final check has not passed reads
923
+ `completed: no`, and `gitzone release resume <version> -y` runs the check.
924
+
925
+ An inconclusive or rejected upload leaves npm unpublished and retains
805
926
  the journal for `gitzone release resume <version> -y`. Resume uses the recorded
806
927
  destination and retained bytes without rebuilding or repacking. It checks the
807
928
  metadata of attachments the journal records as verified without downloading
808
929
  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. An unresolved active attempt requires
930
+ complete public set once more before npm, even for completed journals; a resume
931
+ runs in a new process, so that final check downloads every attachment. An unresolved active attempt requires
810
932
  the exact `--recover-attempt` identifier after its publisher has stopped.
811
933
 
812
934
  Gitea's general attachment-enabled switch is checked. Its issue-attachment size
@@ -981,6 +1103,15 @@ exits 0:
981
1103
  Release running detached: run <id>, process group <pid>, log <path>. Follow it with `tail -f <path>`; `gitzone release inspect` shows its outcome.
982
1104
  ```
983
1105
 
1106
+ Phase lines in the log carry the time they were printed, for example
1107
+ `[2026-10-03T01:48:31.402Z] Running tests` followed by `Running tests passed in
1108
+ 7 min 8 s.`, so the log of a release shows where its time went: tests, the
1109
+ release checkout and its build, the Git target, the Gitea release and every
1110
+ attachment (`uploading <bytes>`, `uploaded, downloaded and hashed in <time>`),
1111
+ the final attachment-set verification, the publication of the draft, each npm registry and its availability
1112
+ wait, and Docker qualification, promotion and cleanup. A foreground release
1113
+ prints the same lines.
1114
+
984
1115
  When the supervisor refuses to start the release, the launcher prints why and
985
1116
  exits 1. When the supervisor does not report within 60 seconds, the launcher
986
1117
  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.4.0',
6
+ version: '8.5.1',
7
7
  description: 'A comprehensive CLI tool for enhancing and managing local development workflows with gitzone utilities, focusing on project setup, version control, code formatting, and template management.'
8
8
  }
@@ -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,14 @@ 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 of a draft in progress at the same time, largest first;
93
+ * default 1, at most 2. Uploads never overlap and neither do verification
94
+ * downloads: with 2 the next attachment uploads while the previous one is
95
+ * verified. Uploads into an already published release run one at a time in
96
+ * manifest order.
97
+ */
98
+ concurrency?: number;
89
99
  }
90
100
 
91
101
  export interface IResolvedReleaseGiteaAssetsConfiguration {
@@ -189,6 +199,21 @@ export const resolveGiteaAssetTransferLimits = (
189
199
  ) * 1024,
190
200
  });
191
201
 
202
+ /**
203
+ * How many attachments of a draft are in progress at the same time. Like the
204
+ * transfer bounds this is tuning, not identity: it may change between resumes.
205
+ */
206
+ export const resolveGiteaAssetConcurrency = (
207
+ configArg: IReleaseGiteaAssetsTargetConfig,
208
+ ): number =>
209
+ resolveWholeNumber(
210
+ configArg.concurrency,
211
+ "concurrency",
212
+ defaultGiteaAssetConcurrency,
213
+ maximumGiteaAssetConcurrency,
214
+ "attachments",
215
+ );
216
+
192
217
  /** Match the resolved destination, without guessing SSH aliases or URL rewrites. */
193
218
  export const assertGiteaAssetsGitDestination = (
194
219
  configArg: IResolvedReleaseGiteaAssetsConfiguration,
@@ -311,6 +336,8 @@ export interface IResolvedReleaseWorkflow {
311
336
  npmVerificationWindowMinutes: number;
312
337
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
313
338
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
339
+ /** Attachments of a draft in progress at the same time. */
340
+ giteaAssetConcurrency?: number;
314
341
  dockerEnabled: boolean;
315
342
  dockerEngine: "tsdocker";
316
343
  dockerRegistry?: string;
@@ -344,6 +371,7 @@ export interface IResolvedReleaseResumeConfiguration {
344
371
  cleanTestArtifacts: boolean;
345
372
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
346
373
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
374
+ giteaAssetConcurrency?: number;
347
375
  }
348
376
 
349
377
  export type TResolvedReleaseDockerConfiguration = Pick<
@@ -1166,6 +1194,9 @@ export const resolveReleaseWorkflow = async (
1166
1194
  giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1167
1195
  targetConfig.giteaAssets || {},
1168
1196
  ),
1197
+ giteaAssetConcurrency: resolveGiteaAssetConcurrency(
1198
+ targetConfig.giteaAssets || {},
1199
+ ),
1169
1200
  }
1170
1201
  : {}),
1171
1202
  dockerEnabled,
@@ -1263,6 +1294,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1263
1294
  giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1264
1295
  targetConfig.giteaAssets || {},
1265
1296
  ),
1297
+ giteaAssetConcurrency: resolveGiteaAssetConcurrency(
1298
+ targetConfig.giteaAssets || {},
1299
+ ),
1266
1300
  }
1267
1301
  : {}),
1268
1302
  };
@@ -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 === 1 ? "one attachment at a time" : "an upload overlaps the previous attachment's verification download"}, never two uploads or two downloads, so each direction of the link must carry ${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
- statuses.filter((entry) => entry.state === "publishing").length > 1
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
- } else if (isComplete(journal))
1507
- throw new Error("Complete release journal must record completedAt.");
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