@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/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
- 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 `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 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.
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 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
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. 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
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
@@ -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.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
  }
@@ -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
  };
@@ -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
- 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