@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
@@ -45,7 +45,10 @@ import {
45
45
  type TReleaseJournal,
46
46
  type IReleaseJournalV1,
47
47
  type IReleaseJournalV2,
48
+ releaseIntentKind,
49
+ type IReleaseIntent,
48
50
  } from "./classes.releasejournal.js";
51
+ import { createReleaseGitRemotePolicy } from "./helpers.gitremote.js";
49
52
  import {
50
53
  GiteaAssetsClient,
51
54
  prepareGiteaAssets,
@@ -152,6 +155,9 @@ const runInternal = async (argvArg: any): Promise<void> => {
152
155
  pushTags: workflow.pushTags,
153
156
  mergeRequested,
154
157
  planMode: workflow.confirmation === "plan",
158
+ gitRemotePolicy: createReleaseGitRemotePolicy(
159
+ workflow.gitRemoteTimeoutSeconds,
160
+ ),
155
161
  });
156
162
  if (workflow.giteaAssets)
157
163
  assertGiteaAssetsGitDestination(
@@ -200,6 +206,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
200
206
  `Gitea assets require the configured credential in ${tokenEnv}.`,
201
207
  );
202
208
  await new GiteaAssetsClient({
209
+ ...workflow.giteaAssetTransfer,
203
210
  destination,
204
211
  tag: `v${newVersion}`,
205
212
  commit: branchContext.sourceOid,
@@ -293,24 +300,6 @@ const runInternal = async (argvArg: any): Promise<void> => {
293
300
  releaseCommitOid,
294
301
  );
295
302
 
296
- // The release build belongs to the release commit and runs in its isolated
297
- // checkout. Docker qualification is bound to the project directory by the
298
- // tSDocker protocol, so an active Docker target additionally builds the
299
- // release worktree that qualification reads.
300
- if (workflow.runBuild && workflow.targets.includes("docker")) {
301
- await runCommandStep(
302
- smartshellInstance,
303
- releaseCwd,
304
- "Running release build",
305
- workflow.buildCommand,
306
- );
307
- await verifyCleanTree(
308
- smartshellInstance,
309
- releaseCwd,
310
- "Build produced uncommitted changes. Aborting release.",
311
- );
312
- }
313
-
314
303
  const ensurePublicationState = async (
315
304
  expectedRemoteMainOidArg = expectedRemoteMainOid,
316
305
  ): Promise<void> => {
@@ -328,53 +317,36 @@ const runInternal = async (argvArg: any): Promise<void> => {
328
317
  );
329
318
  };
330
319
 
331
- await ensurePublicationState();
332
- const tsdocker = workflow.targets.includes("docker")
333
- ? new TsdockerReleaseClient(smartshellInstance, releaseCwd)
334
- : undefined;
335
- await tsdocker?.assertCapabilities();
336
- const dockerRequest = tsdocker
337
- ? createDockerQualificationRequest(
338
- workflow,
339
- releaseCwd,
340
- newVersion,
341
- releaseRefs.mainOid,
342
- )
343
- : undefined;
344
- const journalOptions = {
345
- pnpmCapability,
346
- smartshell: smartshellInstance,
320
+ const versionFloor = toReleaseVersionFloorRecord(versionResolution);
321
+ await recordReleaseIntent(smartshellInstance, {
347
322
  workflow,
348
323
  releaseCwd,
349
324
  releasePushUrl,
350
325
  expectedRemoteMainOid,
351
326
  version: newVersion,
352
- versionFloor: toReleaseVersionFloorRecord(versionResolution),
327
+ versionFloor,
353
328
  refs: releaseRefs,
354
- dockerRequest,
355
- tsdocker,
356
- };
357
- const journalContext = releaseNeedsIsolatedCheckout(workflow)
358
- ? await withIsolatedReleaseCheckout(
359
- {
360
- smartshell: smartshellInstance,
361
- repositoryCwd: releaseCwd,
362
- mainOid: releaseRefs.mainOid,
363
- // Preflight already ran the configured tests on this exact source.
364
- ...(workflow.runBuild ? { buildCommand: workflow.buildCommand } : {}),
365
- },
366
- async (checkout) =>
367
- createReleaseJournal({
368
- ...journalOptions,
369
- npmSourceCwd: checkout.path,
370
- npmPreparationDirectory: checkout.preparationPath,
371
- ensurePublicationState: async () => {
372
- await checkout.assertExact();
373
- await ensurePublicationState();
374
- },
375
- }),
376
- )
377
- : await createReleaseJournal({ ...journalOptions, ensurePublicationState });
329
+ });
330
+ let journalContext: IPreparedTaggedRelease;
331
+ try {
332
+ journalContext = await prepareTaggedRelease({
333
+ pnpmCapability,
334
+ smartshell: smartshellInstance,
335
+ workflow,
336
+ releaseCwd,
337
+ releasePushUrl,
338
+ expectedRemoteMainOid,
339
+ version: newVersion,
340
+ versionFloor,
341
+ refs: releaseRefs,
342
+ ensurePublicationState,
343
+ });
344
+ } catch (error) {
345
+ throw new Error(
346
+ `${error instanceof Error ? error.message : String(error)} The release commit and tag v${newVersion} are recorded locally; \`gitzone release resume ${newVersion} -y\` prepares and publishes them.`,
347
+ { cause: error },
348
+ );
349
+ }
378
350
  const finalJournal = await executeReleasePublication({
379
351
  pnpmCapability,
380
352
  smartshell: smartshellInstance,
@@ -383,7 +355,9 @@ const runInternal = async (argvArg: any): Promise<void> => {
383
355
  journal: journalContext.journal,
384
356
  pushUrl: releasePushUrl,
385
357
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
386
- tsdocker,
358
+ giteaAssetTransfer: workflow.giteaAssetTransfer,
359
+ gitRemotePolicy: branchContext.gitRemotePolicy,
360
+ tsdocker: journalContext.tsdocker,
387
361
  ensurePublicationState,
388
362
  });
389
363
  await cleanTestArtifactsForCompletedRelease(
@@ -551,6 +525,234 @@ const createDockerQualificationRequest = (
551
525
  version: versionArg,
552
526
  });
553
527
 
528
+ interface IRecordReleaseIntentOptions {
529
+ workflow: IResolvedReleaseWorkflow;
530
+ releaseCwd: string;
531
+ releasePushUrl?: string;
532
+ expectedRemoteMainOid?: string;
533
+ version: string;
534
+ versionFloor?: IReleaseVersionFloorRecord;
535
+ refs: IReleaseRefs;
536
+ }
537
+
538
+ /** Records the tagged release before anything can fail on its way to a journal. */
539
+ const recordReleaseIntent = async (
540
+ smartshellArg: plugins.smartshell.Smartshell,
541
+ optionsArg: IRecordReleaseIntentOptions,
542
+ ): Promise<void> => {
543
+ const gitEnabled = optionsArg.workflow.targets.includes("git");
544
+ if (
545
+ gitEnabled &&
546
+ (!optionsArg.releasePushUrl || !optionsArg.expectedRemoteMainOid)
547
+ ) {
548
+ throw new Error("Git release destination state is incomplete.");
549
+ }
550
+ const store = new ReleaseJournalStore(
551
+ await resolveGitCommonDirectory(smartshellArg, optionsArg.releaseCwd),
552
+ );
553
+ await store.recordIntent({
554
+ kind: releaseIntentKind,
555
+ release: {
556
+ version: optionsArg.version,
557
+ tag: `v${optionsArg.version}`,
558
+ mainOid: optionsArg.refs.mainOid,
559
+ tagOid: optionsArg.refs.tagOid,
560
+ ...(optionsArg.versionFloor
561
+ ? { versionFloor: optionsArg.versionFloor }
562
+ : {}),
563
+ },
564
+ plan: {
565
+ targets: optionsArg.workflow.targets,
566
+ runBuild: optionsArg.workflow.runBuild,
567
+ },
568
+ git: gitEnabled
569
+ ? {
570
+ remote: optionsArg.workflow.gitRemote,
571
+ destinationHash: hashReleaseDestination(optionsArg.releasePushUrl!),
572
+ expectedRemoteMainOid: optionsArg.expectedRemoteMainOid!,
573
+ }
574
+ : null,
575
+ createdAt: new Date().toISOString(),
576
+ });
577
+ };
578
+
579
+ type TPrepareTaggedReleaseOptions = Omit<
580
+ ICreateReleaseJournalOptions,
581
+ | "npmSourceCwd"
582
+ | "npmPreparationDirectory"
583
+ | "dockerRequest"
584
+ | "tsdocker"
585
+ | "ensurePublicationState"
586
+ > & {
587
+ ensurePublicationState: () => Promise<void>;
588
+ };
589
+
590
+ interface IPreparedTaggedRelease {
591
+ store: ReleaseJournalStore;
592
+ journal: TReleaseJournal;
593
+ tsdocker?: ITsdockerReleaseClient;
594
+ }
595
+
596
+ /**
597
+ * Everything between the release tag and the installed journal: the Docker
598
+ * worktree build, the isolated build and pack, and the journal itself. A fresh
599
+ * release and the resume of its recorded intent run exactly this.
600
+ */
601
+ const prepareTaggedRelease = async (
602
+ optionsArg: TPrepareTaggedReleaseOptions,
603
+ ): Promise<IPreparedTaggedRelease> => {
604
+ const { workflow, smartshell, releaseCwd } = optionsArg;
605
+ // tSDocker keys qualification to the project directory, so an active Docker
606
+ // target additionally builds the release worktree that qualification reads.
607
+ if (workflow.runBuild && workflow.targets.includes("docker")) {
608
+ await runCommandStep(
609
+ smartshell,
610
+ releaseCwd,
611
+ "Running release build",
612
+ workflow.buildCommand,
613
+ );
614
+ await verifyCleanTree(
615
+ smartshell,
616
+ releaseCwd,
617
+ "Build produced uncommitted changes. Aborting release.",
618
+ );
619
+ }
620
+ await optionsArg.ensurePublicationState();
621
+ const tsdocker = workflow.targets.includes("docker")
622
+ ? new TsdockerReleaseClient(smartshell, releaseCwd)
623
+ : undefined;
624
+ await tsdocker?.assertCapabilities();
625
+ const journalOptions: ICreateReleaseJournalOptions = {
626
+ ...optionsArg,
627
+ dockerRequest: tsdocker
628
+ ? createDockerQualificationRequest(
629
+ workflow,
630
+ releaseCwd,
631
+ optionsArg.version,
632
+ optionsArg.refs.mainOid,
633
+ )
634
+ : undefined,
635
+ tsdocker,
636
+ };
637
+ // The release build belongs to the release commit and runs in its isolated
638
+ // checkout.
639
+ const prepared = releaseNeedsIsolatedCheckout(workflow)
640
+ ? await withIsolatedReleaseCheckout(
641
+ {
642
+ smartshell,
643
+ repositoryCwd: releaseCwd,
644
+ mainOid: optionsArg.refs.mainOid,
645
+ // Preflight already ran the configured tests on this exact source.
646
+ ...(workflow.runBuild ? { buildCommand: workflow.buildCommand } : {}),
647
+ },
648
+ async (checkout) =>
649
+ createReleaseJournal({
650
+ ...journalOptions,
651
+ npmSourceCwd: checkout.path,
652
+ npmPreparationDirectory: checkout.preparationPath,
653
+ ensurePublicationState: async () => {
654
+ await checkout.assertExact();
655
+ await optionsArg.ensurePublicationState();
656
+ },
657
+ }),
658
+ )
659
+ : await createReleaseJournal(journalOptions);
660
+ return { ...prepared, tsdocker };
661
+ };
662
+
663
+ /**
664
+ * A release whose journal was never installed resumes from its recorded
665
+ * intent. It re-resolves the release from the configuration its commit
666
+ * carries and the recorded command-line choices, proves the local refs and
667
+ * the Git destination unchanged, and then prepares the journal exactly as the
668
+ * release would have. Publication continues from that journal.
669
+ */
670
+ const prepareRecordedRelease = async (
671
+ smartshellArg: plugins.smartshell.Smartshell,
672
+ intentArg: IReleaseIntent,
673
+ ): Promise<void> => {
674
+ const { version } = intentArg.release;
675
+ const workflow = await resolveReleaseWorkflow({ yes: true }, intentArg.plan);
676
+ assertReleaseConfiguration(workflow, false);
677
+ const gitEnabled = workflow.targets.includes("git");
678
+ if (gitEnabled && intentArg.git?.remote !== workflow.gitRemote) {
679
+ throw new Error(
680
+ "Current Git release remote does not match the recorded release.",
681
+ );
682
+ }
683
+ const branch = await inspectReleaseBranch({
684
+ smartshell: smartshellArg,
685
+ cwd: paths.cwd,
686
+ gitRemote: workflow.gitRemote,
687
+ gitTargetActive: gitEnabled,
688
+ pushBranch: workflow.pushBranch,
689
+ pushTags: workflow.pushTags,
690
+ mergeRequested: false,
691
+ planMode: false,
692
+ gitRemotePolicy: createReleaseGitRemotePolicy(
693
+ workflow.gitRemoteTimeoutSeconds,
694
+ ),
695
+ });
696
+ if (branch.sourceOid !== intentArg.release.mainOid) {
697
+ throw new Error(
698
+ "Resume must run from the recorded release commit on main.",
699
+ );
700
+ }
701
+ const refs = await captureReleaseRefs(
702
+ smartshellArg,
703
+ paths.cwd,
704
+ version,
705
+ intentArg.release.mainOid,
706
+ );
707
+ if (refs.tagOid !== intentArg.release.tagOid) {
708
+ throw new Error(
709
+ "The local release tag no longer matches the recorded release.",
710
+ );
711
+ }
712
+ if (
713
+ intentArg.git &&
714
+ (!branch.pushUrl ||
715
+ hashReleaseDestination(branch.pushUrl) !== intentArg.git.destinationHash)
716
+ ) {
717
+ throw new Error(
718
+ "The Git push destination changed after the release was recorded.",
719
+ );
720
+ }
721
+ const expectedRemoteMainOid = intentArg.git?.expectedRemoteMainOid;
722
+ const pnpmCapability = await assertFreshReleaseCapabilities(
723
+ smartshellArg,
724
+ workflow,
725
+ paths.cwd,
726
+ branch.pushUrl,
727
+ workflow.targets.includes("docker")
728
+ ? new TsdockerReleaseClient(smartshellArg, paths.cwd)
729
+ : undefined,
730
+ );
731
+ console.log(
732
+ `\nPreparing the journal of recorded release v${version} from ${refs.mainOid}`,
733
+ );
734
+ await prepareTaggedRelease({
735
+ pnpmCapability,
736
+ smartshell: smartshellArg,
737
+ workflow,
738
+ releaseCwd: paths.cwd,
739
+ releasePushUrl: branch.pushUrl,
740
+ expectedRemoteMainOid,
741
+ version,
742
+ versionFloor: intentArg.release.versionFloor,
743
+ refs,
744
+ ensurePublicationState: async () => {
745
+ await verifyReleaseRefs(smartshellArg, paths.cwd, version, refs);
746
+ await revalidateReleasePublicationState(
747
+ smartshellArg,
748
+ branch,
749
+ refs.mainOid,
750
+ expectedRemoteMainOid,
751
+ );
752
+ },
753
+ });
754
+ };
755
+
554
756
  /**
555
757
  * tspublish materializes the already built modules outside every repository,
556
758
  * so each package is packed from its own generated manifest and nothing else.
@@ -887,14 +1089,7 @@ const runReleaseRecover = async (
887
1089
  const store = new ReleaseJournalStore(
888
1090
  await resolveGitCommonDirectory(shell, paths.cwd),
889
1091
  );
890
- const existing = await plugins.fs
891
- .lstat(store.getReleaseDirectory(version))
892
- .then(() => true)
893
- .catch((error: NodeJS.ErrnoException) => {
894
- if (error.code === "ENOENT") return false;
895
- throw error;
896
- });
897
- if (existing) {
1092
+ if (await store.hasJournal(version)) {
898
1093
  if (argvArg.plan) {
899
1094
  printReleaseJournalSummary(await store.read(version));
900
1095
  return;
@@ -905,6 +1100,21 @@ const runReleaseRecover = async (
905
1100
  );
906
1101
  return;
907
1102
  }
1103
+ // A release that recorded its intent resumes from it; recovery is for tags
1104
+ // created without one.
1105
+ if (await store.readIntent(version)) {
1106
+ if (argvArg.plan) {
1107
+ console.log(
1108
+ `Release v${version} is recorded locally without a journal. \`gitzone release resume ${version} -y\` prepares and publishes it.`,
1109
+ );
1110
+ return;
1111
+ }
1112
+ await runReleaseResume(
1113
+ { _: ["release", "resume", version], yes: mode.yes },
1114
+ mode,
1115
+ );
1116
+ return;
1117
+ }
908
1118
  const workflow = await resolveReleaseWorkflow({ yes: true });
909
1119
  assertReleaseConfiguration(workflow, false);
910
1120
  let branch = await inspectReleaseBranch({
@@ -916,6 +1126,9 @@ const runReleaseRecover = async (
916
1126
  pushTags: workflow.pushTags,
917
1127
  mergeRequested: false,
918
1128
  planMode: argvArg.plan === true,
1129
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1130
+ workflow.gitRemoteTimeoutSeconds,
1131
+ ),
919
1132
  });
920
1133
  const refs = await captureReleaseRefs(
921
1134
  shell,
@@ -1027,6 +1240,8 @@ const runReleaseRecover = async (
1027
1240
  journal: context.journal,
1028
1241
  pushUrl: branch.pushUrl,
1029
1242
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
1243
+ giteaAssetTransfer: workflow.giteaAssetTransfer,
1244
+ gitRemotePolicy: branch.gitRemotePolicy,
1030
1245
  tsdocker,
1031
1246
  ensurePublicationState: ensureState,
1032
1247
  });
@@ -1098,6 +1313,24 @@ const runReleaseResume = async (
1098
1313
  const store = new ReleaseJournalStore(
1099
1314
  await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
1100
1315
  );
1316
+ // A release that failed between its tag and its journal left only its
1317
+ // intent; preparing the journal from it is part of this resume.
1318
+ const preparesRecordedRelease = !(await store.hasJournal(version));
1319
+ if (preparesRecordedRelease) {
1320
+ const intent = await store.readIntent(version);
1321
+ if (!intent) {
1322
+ throw new Error(`Release journal v${version} does not exist.`);
1323
+ }
1324
+ if (
1325
+ !(await confirmReleaseResume(
1326
+ modeArg,
1327
+ `Prepare and publish recorded release v${version} now?`,
1328
+ ))
1329
+ ) {
1330
+ return;
1331
+ }
1332
+ await prepareRecordedRelease(smartshellInstance, intent);
1333
+ }
1101
1334
  const journal = await store.read(version);
1102
1335
  const gitEnabled = journal.git.state !== "skipped";
1103
1336
  const resumeConfiguration = await resolveReleaseResumeConfiguration({
@@ -1163,6 +1396,9 @@ const runReleaseResume = async (
1163
1396
  pushTags: true,
1164
1397
  mergeRequested: false,
1165
1398
  planMode: false,
1399
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1400
+ resumeConfiguration.gitRemoteTimeoutSeconds,
1401
+ ),
1166
1402
  });
1167
1403
  const { refs, verificationOnly } = await resolveResumeReleaseRefs(
1168
1404
  smartshellInstance,
@@ -1179,19 +1415,11 @@ const runReleaseResume = async (
1179
1415
  throw new Error("The Git push destination changed after journal creation.");
1180
1416
  }
1181
1417
 
1182
- if (!modeArg.yes) {
1183
- if (!modeArg.interactive) {
1184
- throw new Error("Release resume requires an interactive terminal or -y.");
1185
- }
1186
- const confirmed =
1187
- await plugins.smartinteract.SmartInteract.getCliConfirmation(
1188
- `Resume release v${version} now?`,
1189
- true,
1190
- );
1191
- if (!confirmed) {
1192
- logger.log("info", "Release resume cancelled.");
1193
- return;
1194
- }
1418
+ if (
1419
+ !preparesRecordedRelease &&
1420
+ !(await confirmReleaseResume(modeArg, `Resume release v${version} now?`))
1421
+ ) {
1422
+ return;
1195
1423
  }
1196
1424
 
1197
1425
  const ensurePublicationState = async (
@@ -1230,6 +1458,8 @@ const runReleaseResume = async (
1230
1458
  recoveryAttemptId,
1231
1459
  npmVerificationWindowMs:
1232
1460
  resumeConfiguration.npmVerificationWindowMinutes * 60_000,
1461
+ giteaAssetTransfer: resumeConfiguration.giteaAssetTransfer,
1462
+ gitRemotePolicy: branchContext.gitRemotePolicy,
1233
1463
  tsdocker,
1234
1464
  ensurePublicationState,
1235
1465
  });
@@ -1242,6 +1472,24 @@ const runReleaseResume = async (
1242
1472
  printReleaseJournalSummary(finalJournal);
1243
1473
  };
1244
1474
 
1475
+ /** True when the operator runs with -y or confirms interactively. */
1476
+ const confirmReleaseResume = async (
1477
+ modeArg: ICliMode,
1478
+ questionArg: string,
1479
+ ): Promise<boolean> => {
1480
+ if (modeArg.yes) return true;
1481
+ if (!modeArg.interactive) {
1482
+ throw new Error("Release resume requires an interactive terminal or -y.");
1483
+ }
1484
+ const confirmed =
1485
+ await plugins.smartinteract.SmartInteract.getCliConfirmation(
1486
+ questionArg,
1487
+ true,
1488
+ );
1489
+ if (!confirmed) logger.log("info", "Release resume cancelled.");
1490
+ return confirmed;
1491
+ };
1492
+
1245
1493
  const assertResumeConfiguration = async (
1246
1494
  workflowArg: IResolvedReleaseResumeConfiguration,
1247
1495
  journalArg: TReleaseJournal,
@@ -1871,12 +2119,12 @@ export function showHelp(mode?: ICliMode): void {
1871
2119
  {
1872
2120
  flag: "resume <version>",
1873
2121
  description:
1874
- "Resume exact journaled publication without rebuilding or repacking npm artifacts",
2122
+ "Resume exact journaled publication without rebuilding or repacking npm artifacts, or prepare the journal of a recorded release that failed before it",
1875
2123
  },
1876
2124
  {
1877
2125
  flag: "recover <version>",
1878
2126
  description:
1879
- "Recover a local npm and/or Docker release tag after build or pack failure before journal creation",
2127
+ "Recover a local npm and/or Docker release tag created without a recorded intent after build or pack failure before journal creation",
1880
2128
  },
1881
2129
  {
1882
2130
  flag: "--recover-attempt <id>",
@@ -1926,10 +2174,10 @@ export function showHelp(mode?: ICliMode): void {
1926
2174
  " inspect [version] Read one or all durable release journals without mutation",
1927
2175
  );
1928
2176
  console.log(
1929
- " resume <version> Resume exact journaled publication without rebuilding or repacking npm artifacts",
2177
+ " resume <version> Resume exact journaled publication, or prepare the journal of a recorded release that failed before it",
1930
2178
  );
1931
2179
  console.log(
1932
- " recover <version> Recover an unpublished npm and/or Docker release from its existing local tag",
2180
+ " recover <version> Recover an unpublished npm and/or Docker release tag created without a recorded intent",
1933
2181
  );
1934
2182
  console.log(
1935
2183
  " --recover-attempt Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
@@ -32,13 +32,29 @@ export interface IGiteaAssetInspection {
32
32
  missing: IGiteaFrozenAsset[];
33
33
  }
34
34
 
35
- export interface IGiteaAssetsClientOptions {
35
+ /**
36
+ * Bounds for one Gitea request. A transfer that keeps moving bytes is never cut
37
+ * off by a fixed wall clock; only silence or a rate below the floor ends it.
38
+ */
39
+ export interface IGiteaAssetTransferLimits {
40
+ /**
41
+ * Wait for response headers of a metadata request or download. An upload
42
+ * waits after its last byte for this or its size at the rate floor, whichever is longer.
43
+ */
44
+ responseTimeoutMs: number;
45
+ /** Longest gap without a byte sent or received once the transfer runs. */
46
+ stallTimeoutMs: number;
47
+ /** Rate floor for the whole request's ceiling and an upload's acknowledgement wait. */
48
+ minimumBytesPerSecond: number;
49
+ }
50
+
51
+ export interface IGiteaAssetsClientOptions
52
+ extends Partial<IGiteaAssetTransferLimits> {
36
53
  destination: IGiteaAssetDestination;
37
54
  tag: string;
38
55
  commit: string;
39
56
  token: string;
40
57
  fetchImplementation?: typeof fetch;
41
- timeoutMs?: number;
42
58
  }
43
59
 
44
60
  export interface IGiteaAssetPreflight {
@@ -51,9 +67,11 @@ export interface IGiteaAssetsClient {
51
67
  preflight(): Promise<IGiteaAssetPreflight>;
52
68
  inspectRelease(): Promise<IGiteaRelease | null>;
53
69
  createRelease(): Promise<IGiteaRelease>;
70
+ /** Downloads and hashes only the present attachments named in `verify`. */
54
71
  inspectAssets(
55
72
  releaseId: number,
56
73
  expected: IGiteaFrozenAsset[],
74
+ verify?: readonly IGiteaFrozenAsset[],
57
75
  ): Promise<IGiteaAssetInspection>;
58
76
  uploadAsset(
59
77
  releaseId: number,