@git.zone/cli 7.2.5 → 7.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +30 -1
  3. package/dist_ts/helpers.workflow.js +55 -3
  4. package/dist_ts/mod_config/index.js +23 -2
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +34 -0
  6. package/dist_ts/mod_release/classes.releasejournal.js +134 -2
  7. package/dist_ts/mod_release/helpers.giteaassets.d.ts +75 -3
  8. package/dist_ts/mod_release/helpers.giteaassets.js +303 -53
  9. package/dist_ts/mod_release/helpers.gitremote.d.ts +52 -0
  10. package/dist_ts/mod_release/helpers.gitremote.js +87 -0
  11. package/dist_ts/mod_release/helpers.releasebranch.d.ts +5 -0
  12. package/dist_ts/mod_release/helpers.releasebranch.js +39 -15
  13. package/dist_ts/mod_release/helpers.releasepreparation.js +18 -8
  14. package/dist_ts/mod_release/helpers.releasepublication.d.ts +6 -1
  15. package/dist_ts/mod_release/helpers.releasepublication.js +31 -21
  16. package/dist_ts/mod_release/index.js +216 -64
  17. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +18 -3
  18. package/package.json +3 -3
  19. package/readme.md +106 -24
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/helpers.workflow.ts +123 -1
  22. package/ts/mod_config/index.ts +25 -0
  23. package/ts/mod_release/classes.releasejournal.ts +181 -1
  24. package/ts/mod_release/helpers.giteaassets.ts +438 -75
  25. package/ts/mod_release/helpers.gitremote.ts +147 -0
  26. package/ts/mod_release/helpers.releasebranch.ts +75 -30
  27. package/ts/mod_release/helpers.releasepreparation.ts +25 -7
  28. package/ts/mod_release/helpers.releasepublication.ts +45 -42
  29. package/ts/mod_release/index.ts +333 -85
  30. package/ts/mod_release/interfaces.giteaassets.ts +20 -2
@@ -27,13 +27,27 @@ export interface IGiteaAssetInspection {
27
27
  present: IGiteaFrozenAsset[];
28
28
  missing: IGiteaFrozenAsset[];
29
29
  }
30
- export interface IGiteaAssetsClientOptions {
30
+ /**
31
+ * Bounds for one Gitea request. A transfer that keeps moving bytes is never cut
32
+ * off by a fixed wall clock; only silence or a rate below the floor ends it.
33
+ */
34
+ export interface IGiteaAssetTransferLimits {
35
+ /**
36
+ * Wait for response headers of a metadata request or download. An upload
37
+ * waits after its last byte for this or its size at the rate floor, whichever is longer.
38
+ */
39
+ responseTimeoutMs: number;
40
+ /** Longest gap without a byte sent or received once the transfer runs. */
41
+ stallTimeoutMs: number;
42
+ /** Rate floor for the whole request's ceiling and an upload's acknowledgement wait. */
43
+ minimumBytesPerSecond: number;
44
+ }
45
+ export interface IGiteaAssetsClientOptions extends Partial<IGiteaAssetTransferLimits> {
31
46
  destination: IGiteaAssetDestination;
32
47
  tag: string;
33
48
  commit: string;
34
49
  token: string;
35
50
  fetchImplementation?: typeof fetch;
36
- timeoutMs?: number;
37
51
  }
38
52
  export interface IGiteaAssetPreflight {
39
53
  repositoryId: number;
@@ -44,7 +58,8 @@ export interface IGiteaAssetsClient {
44
58
  preflight(): Promise<IGiteaAssetPreflight>;
45
59
  inspectRelease(): Promise<IGiteaRelease | null>;
46
60
  createRelease(): Promise<IGiteaRelease>;
47
- inspectAssets(releaseId: number, expected: IGiteaFrozenAsset[]): Promise<IGiteaAssetInspection>;
61
+ /** Downloads and hashes only the present attachments named in `verify`. */
62
+ inspectAssets(releaseId: number, expected: IGiteaFrozenAsset[], verify?: readonly IGiteaFrozenAsset[]): Promise<IGiteaAssetInspection>;
48
63
  uploadAsset(releaseId: number, asset: IGiteaFrozenAsset, artifactDirectory: string): Promise<void>;
49
64
  verifyComplete(releaseId: number, expected: IGiteaFrozenAsset[]): Promise<void>;
50
65
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@git.zone/cli",
3
3
  "private": false,
4
- "version": "7.2.5",
4
+ "version": "7.2.7",
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",
@@ -43,8 +43,8 @@
43
43
  "@git.zone/tsbuild": "^5.0.0",
44
44
  "@git.zone/tspack": "^1.4.1",
45
45
  "@git.zone/tsrun": "^3.0.0",
46
- "@git.zone/tstest": "^6.2.1",
47
- "@types/node": "^26.6.1"
46
+ "@git.zone/tstest": "^6.3.1",
47
+ "@types/node": "^26.6.2"
48
48
  },
49
49
  "dependencies": {
50
50
  "@aws-sdk/client-s3": "3.1095.0",
package/readme.md CHANGED
@@ -192,7 +192,7 @@ The release core is not configurable plumbing. It always follows the same profes
192
192
  4. With `--merge`, fast-forward and lease-push `main` before release metadata is created.
193
193
  5. Update version files and baked commit info.
194
194
  6. Move pending changelog entries into the new version section.
195
- 7. Create the local release commit and tag on `main`.
195
+ 7. Create the local release commit and tag on `main`, and record the release intent, so any later failure is resumable (see [Resuming a release that failed before its journal](#resuming-a-release-that-failed-before-its-journal)).
196
196
  8. Create a disposable detached checkout of that release commit, install its locked dependencies when the commit carries a `package.json`, and run the configured release build there. An active Docker target additionally builds the release worktree its qualification reads.
197
197
  9. When npm is selected, prepare every named tspublish module outside the repository, then pack each module and the public root package once into an exact tarball from that checkout.
198
198
  10. Atomically install a durable journal before final publication. A release that publishes only the root package to npm uses journal schema 1, one that also or only publishes tspublish modules uses schema 3, a Docker release uses schema 2 with or without modules, and a Gitea asset release uses schema 4, all in the same storage tree.
@@ -252,16 +252,16 @@ Consequences worth knowing before upgrading:
252
252
  - An install that fails in the checkout for an environmental reason — an
253
253
  unreachable registry, a missing credential, an unusable store — stops the
254
254
  release with the local release commit and tag created, nothing pushed, and no
255
- release journal written. Fix the environment, then: a release with a Git
256
- target plus an npm and/or Docker target continues with `gitzone release
257
- recover <version>`, which prepares and publishes that exact tagged commit
258
- without moving any ref. Other configurations — Gitea-asset releases and
259
- single-target releases — have no recovery path,
260
- because nothing was published: delete the tag and drop the release commit
261
- (`git tag -d v<version>` and `git reset --hard HEAD^` on `main`), then release
262
- again. Confirm first that `HEAD` is the release commit — `git log -1
263
- --format=%s` prints `v<version>` — so that a commit made on top of it is never
264
- dropped.
255
+ release journal written. The release recorded its intent, so fix the
256
+ environment and run `gitzone release resume <version> -y`: it prepares and
257
+ publishes that exact tagged commit without moving any ref. A tag created by
258
+ GitZone 7.2.6 or earlier has no recorded intent; a release with a Git target
259
+ plus an npm and/or Docker target continues with `gitzone release recover
260
+ <version>`, and other configurations of that age delete the tag and drop the
261
+ release commit (`git tag -d v<version>` and `git reset --hard HEAD^` on
262
+ `main`) and release again. Confirm first that `HEAD` is the release commit —
263
+ `git log -1 --format=%s` prints `v<version>` — so that a commit made on top
264
+ of it is never dropped.
265
265
  - The `--plan` step list names the isolated work: `preflight.lockfile` for a
266
266
  project with a `package.json`, then `core.releaseCheckout`,
267
267
  `core.releaseCheckout.build`, then `core.packNpmArtifact`.
@@ -606,15 +606,45 @@ inspects or creates the exact public, non-draft, non-prerelease tag release.
606
606
  Every upload has a revisioned journal attempt. Each accepted attachment must
607
607
  download anonymously with the expected size and SHA256; authenticated redirects
608
608
  are rejected and anonymous downloads never carry the token. Transfers and
609
- hashing stream with bounded memory and timeouts.
609
+ hashing stream with bounded memory.
610
+
611
+ A Gitea request is bounded by its progress, not by a fixed duration, so a large
612
+ binary on a slow server finishes as long as bytes keep moving:
613
+
614
+ | Setting (`release.targets.giteaAssets`) | Default | Bound |
615
+ | --- | --- | --- |
616
+ | `responseTimeoutSeconds` | 120 | Wait for response headers of a metadata request or download |
617
+ | `stallTimeoutSeconds` | 60 | Longest gap without a byte sent or received while a transfer runs |
618
+ | `minimumKiBPerSecond` | 256 | Rate floor; a request may take the two bounds above plus its size at this rate |
619
+
620
+ Gitea stores an upload before it answers, which takes minutes for a large
621
+ binary. After an upload's last byte the CLI therefore waits for the upload's
622
+ size at `minimumKiBPerSecond` (about 28 minutes for 440 MB at 256 KiB/s), or
623
+ `responseTimeoutSeconds` when that is longer, and adds that wait to the
624
+ upload's total bound.
625
+
626
+ Each bound fails with its own message: no response, upload not acknowledged
627
+ (every byte sent, no answer within its size allowance), stalled (no bytes for
628
+ the stall bound), or still progressing but below the rate floor. All of them
629
+ leave the target inconclusive for `gitzone release resume`. The settings tune transfers
630
+ only and may change between runs and resumes.
631
+
632
+ Any other request failure is inconclusive too, and says why without a URL,
633
+ header or token: the HTTP status it reached, each error of the cause chain by
634
+ name and code, a message only when it is plain words, and how far the transfer
635
+ got, for example `Gitea public asset verification is inconclusive (HTTP 200;
636
+ TypeError: terminated; SocketError [UND_ERR_SOCKET]: other side closed; 1048576
637
+ of 461373440 bytes received)`.
610
638
 
611
639
  The complete remote attachment set must equal the manifest. Extra names,
612
640
  duplicates, changed release identity, or conflicting bytes stop publication;
613
641
  the CLI has no deletion or replacement path. It verifies the complete set again
614
642
  before npm. An inconclusive or rejected upload leaves npm unpublished and retains
615
643
  the journal for `gitzone release resume <version> -y`. Resume uses the recorded
616
- destination and retained bytes without rebuilding or repacking, and re-verifies
617
- public assets even for completed journals. An unresolved active attempt requires
644
+ destination and retained bytes without rebuilding or repacking. It checks the
645
+ metadata of attachments the journal records as verified without downloading
646
+ them again, downloads and hashes only the unverified ones, and then verifies the
647
+ complete public set once more before npm, even for completed journals. An unresolved active attempt requires
618
648
  the exact `--recover-attempt` identifier after its publisher has stopped.
619
649
 
620
650
  Gitea's general attachment-enabled switch is checked. Its issue-attachment size
@@ -652,9 +682,49 @@ Resume probes remotely observable targets before acting. A published Git release
652
682
 
653
683
  Schema 1 resumes final Git release-ref and npm publication after the journal is atomically installed. Schema 2 additionally resumes Docker qualification, ordered promotion, and cleanup. Schema 3 resumes the complete npm package set. `--merge` remains available only for non-Docker releases because its pre-release Git push would violate qualification-before-publication ordering.
654
684
 
685
+ ### Resuming a release that failed before its journal
686
+
687
+ Once the local release commit and annotated tag exist, a release records its
688
+ intent before it builds, packs or checks the remote again:
689
+
690
+ ```text
691
+ <git-common-dir>/gitzone/releases/v1/v<version>.intent.json
692
+ ```
693
+
694
+ The intent binds the release commit and tag object, the version floor record,
695
+ the targets and release-build choice the command line selected, and, for a Git
696
+ target, the remote name, the hashed push destination and the remote `main` the
697
+ push will lease. Any failure between the tag and the installed journal — the
698
+ release build, packing, freezing Gitea assets, Docker validation, or a remote
699
+ that cannot be inspected — is then resumable:
700
+
701
+ ```bash
702
+ gitzone release resume 6.0.0 -y
703
+ ```
704
+
705
+ Without a journal, resume reads the intent, resolves the release from the
706
+ `.smartconfig.json` the release commit carries with the recorded targets and
707
+ build choice, and requires clean `main` at the release commit, the recorded tag
708
+ object, the recorded push destination and a remote `main` that still equals the
709
+ leased value. It then prepares the journal exactly as the release would have —
710
+ the Docker worktree build, the disposable checkout with its build, packing and
711
+ frozen assets — and continues as a normal resume from that journal. Tests are
712
+ not run again: preflight ran them on the source the release commit only adds
713
+ version metadata to. Installing the journal removes the intent, and from then on
714
+ the journal alone decides what resume does. A failed resume leaves the intent in
715
+ place for the next one. `recover` on a version with a recorded intent runs this
716
+ resume.
717
+
718
+ To abandon such a release instead of resuming it (nothing reached a remote, and
719
+ you delete the local tag and reset `main` to the commit before the release
720
+ commit), delete its intent file as well; otherwise a later tag of the same version
721
+ is handed to a resume that refuses it.
722
+
723
+ ### Recovering a tag without a recorded intent
724
+
655
725
  For a Git release with npm and/or Docker targets whose local release commit
656
- and annotated tag already exist, but whose build or pack failed before journal
657
- installation, use:
726
+ and annotated tag were created by GitZone 7.2.6 or earlier, which recorded no
727
+ intent, and whose build or pack failed before journal installation, use:
658
728
 
659
729
  ```bash
660
730
  gitzone release recover 6.0.0 --plan
@@ -757,7 +827,8 @@ CLI workflow config lives under `@git.zone/cli` in `.smartconfig.json`. Docker r
757
827
  "enabled": true,
758
828
  "remote": "origin",
759
829
  "pushBranch": true,
760
- "pushTags": true
830
+ "pushTags": true,
831
+ "remoteTimeoutSeconds": 180
761
832
  },
762
833
  "npm": {
763
834
  "enabled": true,
@@ -1535,10 +1606,11 @@ package's `files` list; `.npmignore` does not prevent that traversal when
1535
1606
  `files` is present. Keep service data and its permissions intact.
1536
1607
 
1537
1608
  Inspect the release journal before retrying. An installed journal must be
1538
- resumed with its original artifacts. A failure before journal installation has
1539
- not started final publication and cannot use `release resume`; reconcile the
1540
- local release commit and tag explicitly, preserving their identities. A later
1541
- source correction can be released as a new version from the clean checkout.
1609
+ resumed with its original artifacts. A failure after the release tag but before
1610
+ journal installation has not started final publication; `gitzone release resume
1611
+ <version> -y` prepares the journal from the recorded intent and publishes. A
1612
+ later source correction can be released as a new version from the clean
1613
+ checkout.
1542
1614
 
1543
1615
  A release step fails on a Git, pnpm or tSDocker command:
1544
1616
 
@@ -1546,11 +1618,21 @@ The error names the step, then the command and how it ended, then the end of
1546
1618
  its error output on one line:
1547
1619
 
1548
1620
  ```text
1549
- Unable to inspect main at the configured Git push destination. `git ls-remote` timed out after 60 s and was terminated by SIGTERM
1621
+ Unable to inspect main at the configured Git push destination. Step: publication state check. `git ls-remote` timed out after 180 s and was terminated by SIGTERM; gave up after 3 attempts over 565.2 s
1550
1622
  ```
1551
1623
 
1552
- A timeout means the remote did not answer in time: Git inspections allow 60
1553
- seconds, `git fetch` and `git push` five minutes. Check the remote with the
1624
+ Every `git ls-remote` of a release — the preflight before the tests, the check
1625
+ after them, the check before each publication step and the Git target's own
1626
+ probe — runs under `release.targets.git.remoteTimeoutSeconds` (default 180, at
1627
+ most 3600) per attempt. A timeout, a reset or dropped connection, and a transport failure Git reports
1628
+ as "RPC failed" (other than HTTP 401, 403 or 404) are retried twice, after 5 and 20 seconds;
1629
+ authentication failures, a missing repository and Git's own answers are final
1630
+ at once. The error names the release step, the per-attempt bound, and the
1631
+ attempts and time spent. The preflight reads the remote before the configured
1632
+ tests run, so a remote that is down fails the release before a long test run;
1633
+ the check immediately before the push stays authoritative. A failure after the
1634
+ release tag is resumable with `gitzone release resume <version> -y`. `git
1635
+ fetch` and `git push` keep their five-minute bound. Check the remote with the
1554
1636
  same command, for example `git ls-remote <push-url> refs/heads/main`, and
1555
1637
  retry once it answers promptly. An exit code comes with Git's own message,
1556
1638
  such as `does not appear to be a git repository` for a wrong push URL. The
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@git.zone/cli',
6
- version: '7.2.5',
6
+ version: '7.2.7',
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
  }
@@ -7,10 +7,18 @@ import {
7
7
  } from "./mod_commit/mod.helpers.js";
8
8
  import { parseReleaseVersionFloor } from "./mod_release/helpers.releaseversion.js";
9
9
  import { defaultNpmVerificationWindowMinutes } from "./mod_release/helpers.npmartifact.js";
10
+ import {
11
+ defaultGiteaAssetTransferLimits,
12
+ type IGiteaAssetTransferLimits,
13
+ } from "./mod_release/helpers.giteaassets.js";
10
14
  import {
11
15
  planReleaseNpmPackages,
12
16
  type IReleaseNpmPackageSet,
13
17
  } from "./mod_release/helpers.npmpackages.js";
18
+ import {
19
+ defaultReleaseGitRemoteTimeoutSeconds,
20
+ maximumReleaseGitRemoteTimeoutSeconds,
21
+ } from "./mod_release/helpers.gitremote.js";
14
22
 
15
23
  export type TConfirmationMode = "prompt" | "auto" | "plan";
16
24
 
@@ -47,6 +55,8 @@ export interface IReleaseGitTargetConfig {
47
55
  remote?: string;
48
56
  pushBranch?: boolean;
49
57
  pushTags?: boolean;
58
+ /** Seconds one `git ls-remote` attempt may take; default 180. */
59
+ remoteTimeoutSeconds?: number;
50
60
  }
51
61
 
52
62
  export interface IReleaseNpmTargetConfig {
@@ -65,6 +75,12 @@ export interface IReleaseGiteaAssetsTargetConfig {
65
75
  repository?: string;
66
76
  tokenEnv?: string;
67
77
  manifestPath?: string;
78
+ /** Seconds a metadata request or download waits for response headers; default 120. */
79
+ responseTimeoutSeconds?: number;
80
+ /** Seconds a running transfer may move no byte; default 60. */
81
+ stallTimeoutSeconds?: number;
82
+ /** Rate floor that bounds a whole transfer by its size; default 256. */
83
+ minimumKiBPerSecond?: number;
68
84
  }
69
85
 
70
86
  export interface IResolvedReleaseGiteaAssetsConfiguration {
@@ -118,6 +134,56 @@ export const resolveGiteaAssetsConfiguration = (
118
134
  return { apiOrigin, owner, repository, tokenEnv, manifestPath };
119
135
  };
120
136
 
137
+ const resolveWholeNumber = (
138
+ valueArg: unknown,
139
+ keyArg: string,
140
+ defaultArg: number,
141
+ maximumArg: number,
142
+ unitArg: string,
143
+ ): number => {
144
+ if (valueArg === undefined) return defaultArg;
145
+ if (
146
+ typeof valueArg !== "number" ||
147
+ !Number.isSafeInteger(valueArg) ||
148
+ valueArg < 1 ||
149
+ valueArg > maximumArg
150
+ )
151
+ throw new Error(
152
+ `release.targets.giteaAssets.${keyArg} must be a whole number of ${unitArg} between 1 and ${maximumArg}`,
153
+ );
154
+ return valueArg;
155
+ };
156
+
157
+ /** Transfer bounds are tuning, not identity: they may change between resumes. */
158
+ export const resolveGiteaAssetTransferLimits = (
159
+ configArg: IReleaseGiteaAssetsTargetConfig,
160
+ ): IGiteaAssetTransferLimits => ({
161
+ responseTimeoutMs:
162
+ resolveWholeNumber(
163
+ configArg.responseTimeoutSeconds,
164
+ "responseTimeoutSeconds",
165
+ defaultGiteaAssetTransferLimits.responseTimeoutMs / 1000,
166
+ 3600,
167
+ "seconds",
168
+ ) * 1000,
169
+ stallTimeoutMs:
170
+ resolveWholeNumber(
171
+ configArg.stallTimeoutSeconds,
172
+ "stallTimeoutSeconds",
173
+ defaultGiteaAssetTransferLimits.stallTimeoutMs / 1000,
174
+ 3600,
175
+ "seconds",
176
+ ) * 1000,
177
+ minimumBytesPerSecond:
178
+ resolveWholeNumber(
179
+ configArg.minimumKiBPerSecond,
180
+ "minimumKiBPerSecond",
181
+ defaultGiteaAssetTransferLimits.minimumBytesPerSecond / 1024,
182
+ 1024 * 1024,
183
+ "KiB per second",
184
+ ) * 1024,
185
+ });
186
+
121
187
  /** Match the resolved destination, without guessing SSH aliases or URL rewrites. */
122
188
  export const assertGiteaAssetsGitDestination = (
123
189
  configArg: IResolvedReleaseGiteaAssetsConfiguration,
@@ -215,6 +281,8 @@ export interface IResolvedReleaseWorkflow {
215
281
  versionFloor?: string;
216
282
  gitEnabled: boolean;
217
283
  gitRemote: string;
284
+ /** Bound of one attempt of every Git remote inspection. */
285
+ gitRemoteTimeoutSeconds: number;
218
286
  pushBranch: boolean;
219
287
  pushTags: boolean;
220
288
  npmEnabled: boolean;
@@ -225,6 +293,7 @@ export interface IResolvedReleaseWorkflow {
225
293
  npmAlreadyPublished: "success" | "error";
226
294
  npmVerificationWindowMinutes: number;
227
295
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
296
+ giteaAssetTransfer?: IGiteaAssetTransferLimits;
228
297
  dockerEnabled: boolean;
229
298
  dockerEngine: "tsdocker";
230
299
  dockerRegistry?: string;
@@ -237,14 +306,26 @@ export interface IResolvedReleaseWorkflow {
237
306
  dockerNoBuild: boolean;
238
307
  }
239
308
 
309
+ /**
310
+ * The release choices a command line can override. A release records them
311
+ * with its local commit and tag, so a resume re-resolves exactly that release
312
+ * from the configuration its commit carries.
313
+ */
314
+ export type TReleaseRecordedPlan = Pick<
315
+ IResolvedReleaseWorkflow,
316
+ "targets" | "runBuild"
317
+ >;
318
+
240
319
  export interface IResolvedReleaseResumeConfiguration {
241
320
  gitRemote: string;
321
+ gitRemoteTimeoutSeconds: number;
242
322
  npmRegistries: string[];
243
323
  npmAccessLevel: "public" | "private";
244
324
  npmAlreadyPublished: "success" | "error";
245
325
  npmVerificationWindowMinutes: number;
246
326
  cleanTestArtifacts: boolean;
247
327
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
328
+ giteaAssetTransfer?: IGiteaAssetTransferLimits;
248
329
  }
249
330
 
250
331
  export type TResolvedReleaseDockerConfiguration = Pick<
@@ -788,6 +869,22 @@ export const resolveCommitWorkflow = async (
788
869
  };
789
870
  };
790
871
 
872
+ /** Remote inspection is tuning, not identity: it may change between resumes. */
873
+ export const resolveGitRemoteTimeoutSeconds = (valueArg: unknown): number => {
874
+ if (valueArg === undefined) return defaultReleaseGitRemoteTimeoutSeconds;
875
+ if (
876
+ typeof valueArg !== "number" ||
877
+ !Number.isSafeInteger(valueArg) ||
878
+ valueArg < 1 ||
879
+ valueArg > maximumReleaseGitRemoteTimeoutSeconds
880
+ ) {
881
+ throw new Error(
882
+ `release.targets.git.remoteTimeoutSeconds must be a whole number of seconds between 1 and ${maximumReleaseGitRemoteTimeoutSeconds}`,
883
+ );
884
+ }
885
+ return valueArg;
886
+ };
887
+
791
888
  /** One accepted upload may wait this long for the registry to serve it. */
792
889
  export const resolveNpmVerificationWindowMinutes = (
793
890
  valueArg: unknown,
@@ -822,8 +919,14 @@ const assertNoRemovedNpmTargetSettings = (
822
919
  }
823
920
  };
824
921
 
922
+ /**
923
+ * Resolves the release from its configuration and command line. A resume of
924
+ * a recorded release passes `recordedPlanArg`, which replaces every command
925
+ * line override with the choices that release was created with.
926
+ */
825
927
  export const resolveReleaseWorkflow = async (
826
928
  argvArg: any,
929
+ recordedPlanArg?: TReleaseRecordedPlan,
827
930
  ): Promise<IResolvedReleaseWorkflow> => {
828
931
  const cliConfig = await readCliWorkflowConfig();
829
932
  const releaseConfig = cliConfig.release || {};
@@ -875,6 +978,7 @@ export const resolveReleaseWorkflow = async (
875
978
  if (argvArg.b || argvArg.build) runBuild = true;
876
979
  if (isDisabled(argvArg, "test")) runTests = false;
877
980
  if (isDisabled(argvArg, "build")) runBuild = false;
981
+ if (recordedPlanArg) runBuild = recordedPlanArg.runBuild;
878
982
 
879
983
  const configuredTargets: TReleaseTarget[] = [];
880
984
  if (gitEnabled) configuredTargets.push("git");
@@ -889,6 +993,7 @@ export const resolveReleaseWorkflow = async (
889
993
  if (isDisabled(argvArg, "publish")) {
890
994
  targets = targets.filter((target) => target === "git");
891
995
  }
996
+ if (recordedPlanArg) targets = recordedPlanArg.targets;
892
997
  const selectedTargets = unique(targets);
893
998
  targets = releaseTargetOrder.filter((target) =>
894
999
  selectedTargets.includes(target),
@@ -989,6 +1094,10 @@ export const resolveReleaseWorkflow = async (
989
1094
  ...(versionFloor ? { versionFloor } : {}),
990
1095
  gitEnabled,
991
1096
  gitRemote: gitConfig.remote || "origin",
1097
+ // Dormant settings of an inactive target are not validated.
1098
+ gitRemoteTimeoutSeconds: targets.includes("git")
1099
+ ? resolveGitRemoteTimeoutSeconds(gitConfig.remoteTimeoutSeconds)
1100
+ : defaultReleaseGitRemoteTimeoutSeconds,
992
1101
  pushBranch,
993
1102
  pushTags,
994
1103
  npmEnabled,
@@ -999,7 +1108,14 @@ export const resolveReleaseWorkflow = async (
999
1108
  npmVerificationWindowMinutes: resolveNpmVerificationWindowMinutes(
1000
1109
  npmConfig.verificationWindowMinutes,
1001
1110
  ),
1002
- ...(giteaAssets ? { giteaAssets } : {}),
1111
+ ...(giteaAssets
1112
+ ? {
1113
+ giteaAssets,
1114
+ giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1115
+ targetConfig.giteaAssets || {},
1116
+ ),
1117
+ }
1118
+ : {}),
1003
1119
  dockerEnabled,
1004
1120
  dockerEngine: "tsdocker",
1005
1121
  ...dockerConfiguration,
@@ -1077,6 +1193,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1077
1193
 
1078
1194
  return {
1079
1195
  gitRemote,
1196
+ gitRemoteTimeoutSeconds: optionsArg.git
1197
+ ? resolveGitRemoteTimeoutSeconds(gitConfig.remoteTimeoutSeconds)
1198
+ : defaultReleaseGitRemoteTimeoutSeconds,
1080
1199
  npmRegistries,
1081
1200
  npmAccessLevel,
1082
1201
  npmAlreadyPublished,
@@ -1087,6 +1206,9 @@ export const resolveReleaseResumeConfiguration = async (optionsArg: {
1087
1206
  giteaAssets: resolveGiteaAssetsConfiguration(
1088
1207
  targetConfig.giteaAssets || {},
1089
1208
  ),
1209
+ giteaAssetTransfer: resolveGiteaAssetTransferLimits(
1210
+ targetConfig.giteaAssets || {},
1211
+ ),
1090
1212
  }
1091
1213
  : {}),
1092
1214
  };
@@ -23,6 +23,8 @@ import {
23
23
  import {
24
24
  getDeclaredTsdockerRange,
25
25
  resolveGiteaAssetsConfiguration,
26
+ resolveGiteaAssetTransferLimits,
27
+ resolveGitRemoteTimeoutSeconds,
26
28
  resolveNpmVerificationWindowMinutes,
27
29
  } from "../helpers.workflow.js";
28
30
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
@@ -1974,6 +1976,11 @@ async function validateReleaseConfig(
1974
1976
  if (targets.giteaAssets?.enabled === true) {
1975
1977
  try {
1976
1978
  resolveGiteaAssetsConfiguration(targets.giteaAssets);
1979
+ const transfer = resolveGiteaAssetTransferLimits(targets.giteaAssets);
1980
+ findings.push({
1981
+ level: "ok",
1982
+ 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`,
1983
+ });
1977
1984
  if (targets.git?.enabled === false || targets.docker?.enabled === true)
1978
1985
  throw new Error(
1979
1986
  "Gitea assets require Git publication and cannot combine Docker.",
@@ -2175,6 +2182,24 @@ async function validateGitTarget(
2175
2182
  fix: "Set release.targets.git.pushTags to true or disable the Git target.",
2176
2183
  });
2177
2184
  }
2185
+ try {
2186
+ const timeoutSeconds = resolveGitRemoteTimeoutSeconds(
2187
+ gitTarget.remoteTimeoutSeconds,
2188
+ );
2189
+ findings.push({
2190
+ level: "ok",
2191
+ message: `Git remote inspection waits up to ${timeoutSeconds} s per attempt`,
2192
+ });
2193
+ } catch (error) {
2194
+ findings.push({
2195
+ level: "error",
2196
+ message:
2197
+ error instanceof Error
2198
+ ? error.message
2199
+ : "Invalid Git remote inspection timeout",
2200
+ fix: "Set release.targets.git.remoteTimeoutSeconds to a whole number of seconds between 1 and 3600 or remove it.",
2201
+ });
2202
+ }
2178
2203
  findings.push({
2179
2204
  level: "ok",
2180
2205
  message: `Git release target is enabled (${gitTarget.remote || "origin"})`,