@git.zone/cli 12.1.1 → 12.3.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.
Files changed (62) hide show
  1. package/assets/templates/npm/.package.json +1 -1
  2. package/assets/templates/service/.package.json +1 -1
  3. package/assets/templates/wcc/.package.json +1 -1
  4. package/assets/templates/website/.package.json +1 -1
  5. package/dist_ts/00_commitinfo_data.js +1 -1
  6. package/dist_ts/helpers.tssea.d.ts +2 -7
  7. package/dist_ts/helpers.tssea.js +20 -10
  8. package/dist_ts/helpers.versionsource.d.ts +23 -5
  9. package/dist_ts/helpers.versionsource.js +115 -37
  10. package/dist_ts/helpers.workflow.d.ts +60 -17
  11. package/dist_ts/helpers.workflow.js +156 -51
  12. package/dist_ts/mod_config/index.js +98 -31
  13. package/dist_ts/mod_release/classes.releasejournal.d.ts +63 -8
  14. package/dist_ts/mod_release/classes.releasejournal.js +283 -124
  15. package/dist_ts/mod_release/helpers.cargorelease.d.ts +4 -3
  16. package/dist_ts/mod_release/helpers.cargorelease.js +5 -4
  17. package/dist_ts/mod_release/helpers.fossglobalassets.d.ts +61 -0
  18. package/dist_ts/mod_release/helpers.fossglobalassets.js +580 -0
  19. package/dist_ts/mod_release/helpers.giteaassets.d.ts +15 -51
  20. package/dist_ts/mod_release/helpers.giteaassets.js +40 -507
  21. package/dist_ts/mod_release/helpers.releaseassets.d.ts +40 -0
  22. package/dist_ts/mod_release/helpers.releaseassets.js +349 -0
  23. package/dist_ts/mod_release/helpers.releaseassettransfer.d.ts +67 -0
  24. package/dist_ts/mod_release/helpers.releaseassettransfer.js +239 -0
  25. package/dist_ts/mod_release/helpers.releasecheck.js +3 -2
  26. package/dist_ts/mod_release/helpers.releasepreparation.d.ts +7 -6
  27. package/dist_ts/mod_release/helpers.releasepreparation.js +34 -7
  28. package/dist_ts/mod_release/helpers.releasepublication.d.ts +8 -2
  29. package/dist_ts/mod_release/helpers.releasepublication.js +218 -54
  30. package/dist_ts/mod_release/helpers.releaseversionsource.d.ts +7 -5
  31. package/dist_ts/mod_release/helpers.releaseversionsource.js +9 -7
  32. package/dist_ts/mod_release/index.d.ts +1 -1
  33. package/dist_ts/mod_release/index.js +109 -68
  34. package/dist_ts/mod_release/interfaces.fossglobalassets.d.ts +108 -0
  35. package/dist_ts/mod_release/interfaces.fossglobalassets.js +2 -0
  36. package/dist_ts/mod_release/interfaces.giteaassets.d.ts +9 -43
  37. package/dist_ts/mod_release/interfaces.releaseassets.d.ts +68 -0
  38. package/dist_ts/mod_release/interfaces.releaseassets.js +2 -0
  39. package/dist_ts/plugins.d.ts +1 -0
  40. package/dist_ts/plugins.js +1 -1
  41. package/package.json +3 -2
  42. package/readme.md +339 -41
  43. package/ts/00_commitinfo_data.ts +1 -1
  44. package/ts/helpers.tssea.ts +31 -10
  45. package/ts/helpers.versionsource.ts +176 -45
  46. package/ts/helpers.workflow.ts +288 -78
  47. package/ts/mod_config/index.ts +130 -38
  48. package/ts/mod_release/classes.releasejournal.ts +499 -180
  49. package/ts/mod_release/helpers.cargorelease.ts +8 -3
  50. package/ts/mod_release/helpers.fossglobalassets.ts +886 -0
  51. package/ts/mod_release/helpers.giteaassets.ts +127 -694
  52. package/ts/mod_release/helpers.releaseassets.ts +516 -0
  53. package/ts/mod_release/helpers.releaseassettransfer.ts +339 -0
  54. package/ts/mod_release/helpers.releasecheck.ts +3 -1
  55. package/ts/mod_release/helpers.releasepreparation.ts +55 -12
  56. package/ts/mod_release/helpers.releasepublication.ts +351 -69
  57. package/ts/mod_release/helpers.releaseversionsource.ts +11 -7
  58. package/ts/mod_release/index.ts +151 -90
  59. package/ts/mod_release/interfaces.fossglobalassets.ts +127 -0
  60. package/ts/mod_release/interfaces.giteaassets.ts +14 -47
  61. package/ts/mod_release/interfaces.releaseassets.ts +96 -0
  62. package/ts/plugins.ts +3 -0
@@ -2,17 +2,24 @@ import * as plugins from "./mod.plugins.js";
2
2
  import { formatCommandFailure } from "./helpers.commandfailure.js";
3
3
  import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
4
4
  import {
5
- resolveGiteaAssetsConfiguration,
5
+ assertSingleReleaseAssetTarget,
6
+ releaseAssetTargetNames,
7
+ resolveReleaseAssetsConfiguration,
6
8
  resolveReleaseRecordRetention,
9
+ type IReleaseAssetsTargetConfig,
10
+ type IResolvedReleaseResumeConfiguration,
7
11
  type TReleaseRecordedPlan,
8
12
  type TReleaseTarget,
9
13
  } from "../helpers.workflow.js";
14
+ import { assertGiteaFrozenAssets } from "./helpers.giteaassets.js";
15
+ import { assertFossglobalReleaseClaim } from "./helpers.fossglobalassets.js";
10
16
  import {
11
- assertGiteaFrozenAssets,
12
- validateGiteaAssets,
13
- type IGiteaAssetDestination,
14
- type IGiteaFrozenAsset,
15
- } from "./helpers.giteaassets.js";
17
+ releaseAssetTargets,
18
+ validateReleaseAssets,
19
+ type IReleaseAssetDestination,
20
+ type IReleaseFrozenAsset,
21
+ type TReleaseAssetTargetName,
22
+ } from "./helpers.releaseassets.js";
16
23
  import {
17
24
  assertReleaseCleanupResult,
18
25
  assertReleasePromotionEvidence,
@@ -287,6 +294,13 @@ export interface IReleaseJournalV2 {
287
294
  alreadyPublished: "success" | "error";
288
295
  registries: IReleaseNpmRegistryJournal[];
289
296
  };
297
+ /**
298
+ * At most one release asset section, the same as schema 4's: present only
299
+ * when the release also publishes release assets. They publish after Git,
300
+ * before npm and before any Docker promotion.
301
+ */
302
+ giteaAssets?: IReleaseGiteaAssetsJournal;
303
+ fossglobalAssets?: IReleaseFossglobalAssetsJournal;
290
304
  docker: IReleaseDockerJournal;
291
305
  createdAt: string;
292
306
  updatedAt: string;
@@ -309,32 +323,126 @@ export interface IReleaseJournalV3 extends Omit<
309
323
  }
310
324
 
311
325
  export interface IReleaseGiteaAssetJournal extends IReleaseTargetStatus {
312
- asset: IGiteaFrozenAsset;
326
+ asset: IReleaseFrozenAsset;
313
327
  }
314
328
 
315
329
  export interface IReleaseGiteaAssetsJournal {
316
- destination: IGiteaAssetDestination;
330
+ destination: IReleaseAssetDestination;
317
331
  tokenEnv: string;
318
332
  manifestPath: string;
319
333
  release: IReleaseTargetStatus & { id: number | null };
320
334
  assets: IReleaseGiteaAssetJournal[];
321
335
  }
322
336
 
323
- export interface IReleaseJournalV4 extends Omit<
337
+ export interface IReleaseFossglobalAssetJournal extends IReleaseTargetStatus {
338
+ asset: IReleaseFrozenAsset;
339
+ /** The code host's id of the asset, recorded once an inspection verified it. */
340
+ assetId: string | null;
341
+ }
342
+
343
+ /** One release of foss.global's code host, addressed by its tag. */
344
+ export interface IReleaseFossglobalAssetsJournal {
345
+ destination: IReleaseAssetDestination;
346
+ tokenEnv: string;
347
+ manifestPath: string;
348
+ /** The code host's id of the release, recorded once an inspection verified it. */
349
+ release: IReleaseTargetStatus & { releaseId: string | null };
350
+ assets: IReleaseFossglobalAssetJournal[];
351
+ }
352
+
353
+ /** What every schema 4 journal carries besides its one release asset section. */
354
+ export interface IReleaseAssetsJournalBase extends Omit<
324
355
  IReleaseJournalV1,
325
356
  "schemaVersion" | "cargo"
326
357
  > {
327
358
  schemaVersion: 4;
328
359
  packages: IReleasePackage[];
360
+ }
361
+
362
+ export interface IReleaseJournalWithGiteaAssets extends IReleaseAssetsJournalBase {
329
363
  giteaAssets: IReleaseGiteaAssetsJournal;
364
+ fossglobalAssets?: never;
365
+ }
366
+
367
+ export interface IReleaseJournalWithFossglobalAssets extends IReleaseAssetsJournalBase {
368
+ fossglobalAssets: IReleaseFossglobalAssetsJournal;
369
+ giteaAssets?: never;
330
370
  }
331
371
 
372
+ /**
373
+ * Schema 4: Git, npm and exactly one release asset section. A gitzone that
374
+ * knows only `giteaAssets` refuses a journal with `fossglobalAssets`.
375
+ */
376
+ export type TReleaseAssetsJournal =
377
+ IReleaseJournalWithGiteaAssets | IReleaseJournalWithFossglobalAssets;
378
+
332
379
  export type TReleaseJournal =
333
- IReleaseJournalV1 | IReleaseJournalV2 | IReleaseJournalV3 | IReleaseJournalV4;
380
+ | IReleaseJournalV1
381
+ | IReleaseJournalV2
382
+ | IReleaseJournalV3
383
+ | TReleaseAssetsJournal;
384
+
385
+ /** A journal's release asset section with the target it publishes to. */
386
+ export type TReleaseAssetsSection =
387
+ | { target: "giteaAssets"; section: IReleaseGiteaAssetsJournal }
388
+ | { target: "fossglobalAssets"; section: IReleaseFossglobalAssetsJournal };
389
+
390
+ /**
391
+ * The release asset section of a journal that publishes one: schema 4 always
392
+ * carries one, schema 2 (Docker) at most one.
393
+ */
394
+ export const getReleaseAssets = (
395
+ journalArg: TReleaseJournal,
396
+ ): TReleaseAssetsSection | undefined => {
397
+ if (journalArg.schemaVersion !== 2 && journalArg.schemaVersion !== 4)
398
+ return undefined;
399
+ if (journalArg.giteaAssets)
400
+ return { target: "giteaAssets", section: journalArg.giteaAssets };
401
+ if (journalArg.fossglobalAssets)
402
+ return { target: "fossglobalAssets", section: journalArg.fossglobalAssets };
403
+ return undefined;
404
+ };
405
+
406
+ /** The release and asset targets of a journal's release asset section, if any. */
407
+ const getReleaseAssetsStatuses = (
408
+ journalArg: TReleaseJournal,
409
+ ): IReleaseTargetStatus[] => {
410
+ const section = getReleaseAssets(journalArg)?.section;
411
+ return section ? [section.release, ...section.assets] : [];
412
+ };
413
+
414
+ /** The frozen assets of a release asset section in manifest order. */
415
+ const getFrozenReleaseAssets = (
416
+ sectionArg: TReleaseAssetsSection["section"],
417
+ ): IReleaseFrozenAsset[] => sectionArg.assets.map((entry) => entry.asset);
418
+
419
+ /**
420
+ * A resume publishes a journal's release assets only with the configuration
421
+ * its section recorded: the destination, the credential's variable and the
422
+ * manifest. Transfer bounds are tuning and may change.
423
+ */
424
+ export const assertReleaseAssetsResumeConfiguration = (
425
+ configurationArg: Pick<
426
+ IResolvedReleaseResumeConfiguration,
427
+ TReleaseAssetTargetName
428
+ >,
429
+ journalArg: TReleaseJournal,
430
+ ): void => {
431
+ const releaseAssets = getReleaseAssets(journalArg);
432
+ if (!releaseAssets) return;
433
+ const { destination, tokenEnv, manifestPath } = releaseAssets.section;
434
+ if (
435
+ JSON.stringify(configurationArg[releaseAssets.target]) !==
436
+ JSON.stringify({ ...destination, tokenEnv, manifestPath })
437
+ )
438
+ throw new Error(
439
+ `Current ${releaseAssetTargets[releaseAssets.target].label} asset configuration does not match the journal.`,
440
+ );
441
+ };
334
442
 
335
443
  export type TReleaseJournalWithPackages =
336
444
  | IReleaseJournalV3
337
- | IReleaseJournalV4
445
+ | TReleaseAssetsJournal
338
446
  | (IReleaseJournalV2 & { packages: IReleasePackage[] });
339
447
 
340
448
  export const hasReleasePackages = (
@@ -615,12 +723,7 @@ const isComplete = (journalArg: TReleaseJournal): boolean => {
615
723
  ...journalArg.npm.registries.map((registryArg) => registryArg.state),
616
724
  ...(getReleaseCargo(journalArg)?.registries.map((cellArg) => cellArg.state) ??
617
725
  []),
618
- ...(journalArg.schemaVersion === 4
619
- ? [
620
- journalArg.giteaAssets.release.state,
621
- ...journalArg.giteaAssets.assets.map((entry) => entry.state),
622
- ]
623
- : []),
726
+ ...getReleaseAssetsStatuses(journalArg).map((entry) => entry.state),
624
727
  ].every(isTerminalTargetState);
625
728
  if (
626
729
  !commonComplete ||
@@ -650,12 +753,7 @@ export const isVerificationOnlyResume = (
650
753
  journalArg.git,
651
754
  ...journalArg.npm.registries,
652
755
  ...(getReleaseCargo(journalArg)?.registries ?? []),
653
- ...(journalArg.schemaVersion === 4
654
- ? [
655
- journalArg.giteaAssets.release,
656
- ...journalArg.giteaAssets.assets,
657
- ]
658
- : []),
756
+ ...getReleaseAssetsStatuses(journalArg),
659
757
  ...(journalArg.schemaVersion === releaseJournalSchemaVersion
660
758
  ? [
661
759
  journalArg.docker.qualification,
@@ -674,6 +772,7 @@ export const isVerificationOnlyResume = (
674
772
 
675
773
  const immutableJournalIdentity = (journalArg: TReleaseJournal): string => {
676
774
  const cargo = getReleaseCargo(journalArg);
775
+ const releaseAssets = getReleaseAssets(journalArg);
677
776
  return JSON.stringify({
678
777
  schemaVersion: journalArg.schemaVersion,
679
778
  release: journalArg.release,
@@ -707,15 +806,17 @@ const immutableJournalIdentity = (journalArg: TReleaseJournal): string => {
707
806
  ]),
708
807
  }
709
808
  : undefined,
710
- giteaAssets:
711
- journalArg.schemaVersion === 4
712
- ? {
713
- destination: journalArg.giteaAssets.destination,
714
- tokenEnv: journalArg.giteaAssets.tokenEnv,
715
- manifestPath: journalArg.giteaAssets.manifestPath,
716
- assets: journalArg.giteaAssets.assets.map((entry) => entry.asset),
717
- }
718
- : undefined,
809
+ // The recorded release and asset ids are not identity: they are recorded
810
+ // once, after the journal exists, and never replaced.
811
+ releaseAssets: releaseAssets
812
+ ? {
813
+ target: releaseAssets.target,
814
+ destination: releaseAssets.section.destination,
815
+ tokenEnv: releaseAssets.section.tokenEnv,
816
+ manifestPath: releaseAssets.section.manifestPath,
817
+ assets: getFrozenReleaseAssets(releaseAssets.section),
818
+ }
819
+ : undefined,
719
820
  docker:
720
821
  journalArg.schemaVersion === releaseJournalSchemaVersion
721
822
  ? {
@@ -807,8 +908,9 @@ const assertPreviousLatest = (
807
908
  };
808
909
 
809
910
  /**
810
- * A release line never publishes Gitea assets: Gitea marks its newest release
811
- * as the latest one, which a line must not move.
911
+ * A release line never publishes release assets: Gitea marks its newest
912
+ * release as the latest one, foss.global's code host follows the same order,
913
+ * and a line must not move it.
812
914
  */
813
915
  const assertNoReleaseLine = (
814
916
  valueArg: Record<string, unknown>,
@@ -1459,6 +1561,15 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1459
1561
  throw new Error("Release journal root must be a JSON object.");
1460
1562
  }
1461
1563
  const hasPackages = Object.hasOwn(valueArg, "packages");
1564
+ const assetTargets = releaseAssetTargetNames.filter((targetArg) =>
1565
+ Object.hasOwn(valueArg, targetArg),
1566
+ );
1567
+ if (assetTargets.length > 1)
1568
+ throw new Error(
1569
+ `Schema 2 carries at most one release asset section: ${releaseAssetTargetNames.join(" or ")}.`,
1570
+ );
1571
+ const [assetTarget] = assetTargets;
1572
+ if (assetTarget) assertNoReleaseLine(valueArg, 2);
1462
1573
  assertExactKeys(
1463
1574
  valueArg,
1464
1575
  [
@@ -1470,6 +1581,7 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1470
1581
  ...(hasPackages ? ["packages"] : []),
1471
1582
  "git",
1472
1583
  "npm",
1584
+ ...(assetTarget ? [assetTarget] : []),
1473
1585
  "docker",
1474
1586
  "createdAt",
1475
1587
  "updatedAt",
@@ -1486,8 +1598,14 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1486
1598
  throw new Error("Release journal header is invalid or unsupported.");
1487
1599
  }
1488
1600
  // Identity, Git and npm follow the schema 1 rules, or the schema 3 package
1489
- // matrix when modules accompany the Docker images; only Docker is added here.
1490
- const { docker: rawDocker, ...common } = valueArg;
1601
+ // matrix when modules accompany the Docker images; Docker and the optional
1602
+ // release asset section are validated here.
1603
+ const rawDocker = valueArg.docker;
1604
+ const common = Object.fromEntries(
1605
+ Object.entries(valueArg).filter(
1606
+ ([keyArg]) => keyArg !== "docker" && keyArg !== assetTarget,
1607
+ ),
1608
+ );
1491
1609
  const commonComplete =
1492
1610
  isPlainObject(valueArg.npm) &&
1493
1611
  Array.isArray(valueArg.npm.registries) &&
@@ -1519,6 +1637,23 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1519
1637
  "Schema 2 release journals permit at most one active publication owner.",
1520
1638
  );
1521
1639
  }
1640
+ if (assetTarget) {
1641
+ assertReleaseAssetsSection(assetTarget, valueArg[assetTarget], journal.release);
1642
+ // Docker promotions follow the asset set as npm does, so no image is
1643
+ // published before the assets beside it.
1644
+ assertReleaseAssetsPublicationOrder(
1645
+ journal.git,
1646
+ getReleaseAssets(journal)!,
1647
+ [
1648
+ ...journal.npm.registries,
1649
+ docker.qualification,
1650
+ ...docker.promotions,
1651
+ docker.cleanup,
1652
+ ],
1653
+ [...journal.npm.registries, ...docker.promotions],
1654
+ "npm, Docker promotion",
1655
+ );
1656
+ }
1522
1657
  if (journal.completedAt !== null) {
1523
1658
  const completedAt = assertIsoTimestamp(
1524
1659
  journal.completedAt,
@@ -1530,7 +1665,10 @@ const assertReleaseJournalV2 = (valueArg: unknown): IReleaseJournalV2 => {
1530
1665
  if (completedAt > journal.updatedAt) {
1531
1666
  throw new Error("Release journal completedAt exceeds updatedAt.");
1532
1667
  }
1533
- } else if (isComplete(journal)) {
1668
+ } else if (isComplete(journal) && !assetTarget) {
1669
+ // With release assets, every target verified and no completedAt yet means
1670
+ // the final verification of the complete asset set has not passed; resume
1671
+ // runs it and records the completion.
1534
1672
  throw new Error("Complete release journal must record completedAt.");
1535
1673
  }
1536
1674
  return journal;
@@ -1697,10 +1835,220 @@ const assertReleaseJournalV3 = (
1697
1835
  return journal;
1698
1836
  };
1699
1837
 
1838
+ const releaseAssetsSectionKeys = [
1839
+ "destination",
1840
+ "tokenEnv",
1841
+ "manifestPath",
1842
+ "release",
1843
+ "assets",
1844
+ ] as const;
1845
+ const releaseAssetStatusKeys = ["state", "attempts", "attempt", "error"] as const;
1846
+
1847
+ /**
1848
+ * Validates the frame both release asset sections share: the destination,
1849
+ * credential variable and manifest the configuration resolves, and the status
1850
+ * of the release and of every asset, none of them skipped.
1851
+ */
1852
+ const assertReleaseAssetsSectionFrame = (
1853
+ targetArg: TReleaseAssetTargetName,
1854
+ sectionArg: Record<string, unknown>,
1855
+ releaseIdKeyArg: string,
1856
+ assetKeysArg: readonly string[],
1857
+ ): {
1858
+ release: Record<string, unknown>;
1859
+ assets: Record<string, unknown>[];
1860
+ destination: IReleaseAssetDestination;
1861
+ } => {
1862
+ const { label } = releaseAssetTargets[targetArg];
1863
+ assertExactKeys(sectionArg, releaseAssetsSectionKeys, `${label} assets`);
1864
+ if (
1865
+ !isPlainObject(sectionArg.destination) ||
1866
+ !isPlainObject(sectionArg.release) ||
1867
+ !Array.isArray(sectionArg.assets)
1868
+ )
1869
+ throw new Error(`Invalid ${label} asset publication intent.`);
1870
+ assertExactKeys(
1871
+ sectionArg.destination,
1872
+ ["apiOrigin", "owner", "repository"],
1873
+ `${label} destination`,
1874
+ );
1875
+ resolveReleaseAssetsConfiguration(targetArg, {
1876
+ ...sectionArg.destination,
1877
+ tokenEnv: sectionArg.tokenEnv,
1878
+ manifestPath: sectionArg.manifestPath,
1879
+ } as IReleaseAssetsTargetConfig);
1880
+ assertExactKeys(
1881
+ sectionArg.release,
1882
+ [...releaseAssetStatusKeys, releaseIdKeyArg],
1883
+ `${label} release target`,
1884
+ );
1885
+ assertTargetStatus(sectionArg.release, `${label} release target`);
1886
+ const assets: Record<string, unknown>[] = [];
1887
+ for (const entry of sectionArg.assets) {
1888
+ if (!isPlainObject(entry)) throw new Error(`Invalid ${label} asset target.`);
1889
+ assertExactKeys(entry, assetKeysArg, `${label} asset target`);
1890
+ assertTargetStatus(entry, `${label} asset target`);
1891
+ if (entry.state === "skipped")
1892
+ throw new Error(`${label} asset targets cannot be skipped.`);
1893
+ assets.push(entry);
1894
+ }
1895
+ return {
1896
+ release: sectionArg.release,
1897
+ assets,
1898
+ destination: sectionArg.destination as unknown as IReleaseAssetDestination,
1899
+ };
1900
+ };
1901
+
1902
+ /** Gitea numbers its releases; each attachment is known by its frozen name. */
1903
+ const assertGiteaAssetsSection = (
1904
+ sectionArg: Record<string, unknown>,
1905
+ releaseArg: IReleaseIdentity,
1906
+ ): void => {
1907
+ const { release, assets, destination } = assertReleaseAssetsSectionFrame(
1908
+ "giteaAssets",
1909
+ sectionArg,
1910
+ "id",
1911
+ [...releaseAssetStatusKeys, "asset"],
1912
+ );
1913
+ if (
1914
+ release.state === "skipped" ||
1915
+ (release.id !== null &&
1916
+ (!Number.isSafeInteger(release.id) || (release.id as number) <= 0)) ||
1917
+ (release.state === "verified" && release.id === null)
1918
+ ) {
1919
+ throw new Error("Invalid Gitea release identity or status.");
1920
+ }
1921
+ assertGiteaFrozenAssets(
1922
+ assets.map((entry) => entry.asset),
1923
+ destination,
1924
+ releaseArg.tag,
1925
+ );
1926
+ };
1927
+
1928
+ /**
1929
+ * foss.global's code host gives the release and each asset an opaque id. A
1930
+ * verified target has its id recorded, and the section is exactly the claim
1931
+ * the client holds the destination to.
1932
+ */
1933
+ const assertFossglobalAssetsSection = (
1934
+ sectionArg: Record<string, unknown>,
1935
+ releaseArg: IReleaseIdentity,
1936
+ ): void => {
1937
+ const { release, assets, destination } = assertReleaseAssetsSectionFrame(
1938
+ "fossglobalAssets",
1939
+ sectionArg,
1940
+ "releaseId",
1941
+ [...releaseAssetStatusKeys, "asset", "assetId"],
1942
+ );
1943
+ if (
1944
+ release.state === "skipped" ||
1945
+ (release.state === "verified" && release.releaseId === null) ||
1946
+ assets.some(
1947
+ (entry) => entry.state === "verified" && entry.assetId === null,
1948
+ )
1949
+ )
1950
+ throw new Error("Invalid foss.global release identity or status.");
1951
+ assertFossglobalReleaseClaim(
1952
+ {
1953
+ tagObjectId: releaseArg.tagOid,
1954
+ releaseId: release.releaseId,
1955
+ assets: assets.map((entry) => ({
1956
+ asset: entry.asset,
1957
+ assetId: entry.assetId,
1958
+ })),
1959
+ },
1960
+ destination,
1961
+ releaseArg.tag,
1962
+ );
1963
+ };
1964
+
1965
+ /** Validates one release asset section, of schema 4 or of schema 2. */
1966
+ const assertReleaseAssetsSection = (
1967
+ targetArg: TReleaseAssetTargetName,
1968
+ sectionArg: unknown,
1969
+ releaseArg: IReleaseIdentity,
1970
+ ): void => {
1971
+ if (!isPlainObject(sectionArg))
1972
+ throw new Error(
1973
+ `Invalid ${releaseAssetTargets[targetArg].label} asset publication intent.`,
1974
+ );
1975
+ if (targetArg === "giteaAssets") assertGiteaAssetsSection(sectionArg, releaseArg);
1976
+ else assertFossglobalAssetsSection(sectionArg, releaseArg);
1977
+ };
1978
+
1979
+ /**
1980
+ * The rules a release asset section adds to its journal. Git is active. One
1981
+ * owner publishes at a time, except Gitea attachments, which may upload
1982
+ * concurrently while nothing else publishes. The release and its assets
1983
+ * leave pending only after Git verified or is in conflict, the assets only
1984
+ * after the release, and the followers (npm, and in schema 2 every Docker
1985
+ * promotion) only once the release id is recorded and every asset is
1986
+ * verified or in conflict.
1987
+ */
1988
+ const assertReleaseAssetsPublicationOrder = (
1989
+ gitArg: IReleaseTargetStatus,
1990
+ releaseAssetsArg: TReleaseAssetsSection,
1991
+ /** Every other target outside the section, followers included. */
1992
+ othersArg: IReleaseTargetStatus[],
1993
+ followersArg: IReleaseTargetStatus[],
1994
+ followersNameArg: string,
1995
+ ): void => {
1996
+ const { target, section } = releaseAssetsArg;
1997
+ const { label, hostAssetNoun } = releaseAssetTargets[target];
1998
+ const recordedReleaseId =
1999
+ "id" in section.release ? section.release.id : section.release.releaseId;
2000
+ const publishing = (entriesArg: IReleaseTargetStatus[]): number =>
2001
+ entriesArg.filter((entry) => entry.state === "publishing").length;
2002
+ const otherPublishing = publishing([gitArg, section.release, ...othersArg]);
2003
+ const assetsPublishing = publishing(section.assets);
2004
+ // Gitea attachments may publish concurrently, each under its own attempt;
2005
+ // any other target has one owner and never overlaps them. foss.global's
2006
+ // assets upload one at a time, so every one of its targets has one owner.
2007
+ if (
2008
+ target === "giteaAssets"
2009
+ ? gitArg.state === "skipped" ||
2010
+ otherPublishing > 1 ||
2011
+ (otherPublishing > 0 && assetsPublishing > 0)
2012
+ : gitArg.state === "skipped" || otherPublishing + assetsPublishing > 1
2013
+ ) {
2014
+ throw new Error(
2015
+ target === "giteaAssets"
2016
+ ? `${label} assets require an active Git target and one publication owner outside concurrent ${hostAssetNoun} uploads.`
2017
+ : `${label} assets require an active Git target and one publication owner.`,
2018
+ );
2019
+ }
2020
+ const settled = (entryArg: IReleaseTargetStatus): boolean =>
2021
+ entryArg.state === "verified" || entryArg.state === "conflict";
2022
+ const assetStates: IReleaseTargetStatus[] = section.assets;
2023
+ if (
2024
+ (!settled(gitArg) &&
2025
+ [section.release, ...assetStates, ...followersArg].some(
2026
+ (entry) => entry.state !== "pending",
2027
+ )) ||
2028
+ (!settled(section.release) &&
2029
+ assetStates.some((entry) => entry.state !== "pending")) ||
2030
+ (followersArg.some((entry) => entry.state !== "pending") &&
2031
+ (recordedReleaseId === null ||
2032
+ assetStates.some((entry) => !settled(entry))))
2033
+ )
2034
+ throw new Error(
2035
+ `Release targets violate Git, ${label} assets, ${followersNameArg} publication order.`,
2036
+ );
2037
+ };
2038
+
1700
2039
  const assertReleaseJournalV4 = (
1701
2040
  valueArg: Record<string, unknown>,
1702
- ): IReleaseJournalV4 => {
2041
+ ): TReleaseAssetsJournal => {
1703
2042
  assertNoReleaseLine(valueArg, 4);
2043
+ const sections = releaseAssetTargetNames.filter((targetArg) =>
2044
+ Object.hasOwn(valueArg, targetArg),
2045
+ );
2046
+ if (sections.length !== 1)
2047
+ throw new Error(
2048
+ `Schema 4 requires exactly one release asset section: ${releaseAssetTargetNames.join(" or ")}.`,
2049
+ );
2050
+ const [target] = sections;
2051
+ const { label } = releaseAssetTargets[target];
1704
2052
  assertExactKeys(
1705
2053
  valueArg,
1706
2054
  [
@@ -1712,77 +2060,23 @@ const assertReleaseJournalV4 = (
1712
2060
  "packages",
1713
2061
  "git",
1714
2062
  "npm",
1715
- "giteaAssets",
2063
+ target,
1716
2064
  "createdAt",
1717
2065
  "updatedAt",
1718
2066
  "completedAt",
1719
2067
  ],
1720
2068
  "Release journal",
1721
2069
  );
2070
+ const section = valueArg[target];
1722
2071
  if (
1723
2072
  !Array.isArray(valueArg.packages) ||
1724
- !isPlainObject(valueArg.giteaAssets) ||
2073
+ !isPlainObject(section) ||
1725
2074
  !isPlainObject(valueArg.git) ||
1726
2075
  !isPlainObject(valueArg.npm) ||
1727
2076
  !Array.isArray(valueArg.npm.registries)
1728
2077
  ) {
1729
- throw new Error("Schema 4 requires an exact Gitea asset publication set.");
2078
+ throw new Error(`Schema 4 requires an exact ${label} asset publication set.`);
1730
2079
  }
1731
- const assets = valueArg.giteaAssets;
1732
- assertExactKeys(
1733
- assets,
1734
- ["destination", "tokenEnv", "manifestPath", "release", "assets"],
1735
- "Gitea assets",
1736
- );
1737
- if (
1738
- !isPlainObject(assets.destination) ||
1739
- !isPlainObject(assets.release) ||
1740
- !Array.isArray(assets.assets)
1741
- )
1742
- throw new Error("Invalid Gitea asset publication intent.");
1743
- assertExactKeys(
1744
- assets.destination,
1745
- ["apiOrigin", "owner", "repository"],
1746
- "Gitea destination",
1747
- );
1748
- resolveGiteaAssetsConfiguration({
1749
- ...assets.destination,
1750
- tokenEnv: assets.tokenEnv,
1751
- manifestPath: assets.manifestPath,
1752
- } as Parameters<typeof resolveGiteaAssetsConfiguration>[0]);
1753
- assertExactKeys(
1754
- assets.release,
1755
- ["state", "attempts", "attempt", "error", "id"],
1756
- "Gitea release target",
1757
- );
1758
- assertTargetStatus(assets.release, "Gitea release target");
1759
- if (
1760
- assets.release.state === "skipped" ||
1761
- (assets.release.id !== null &&
1762
- (!Number.isSafeInteger(assets.release.id) ||
1763
- (assets.release.id as number) <= 0)) ||
1764
- (assets.release.state === "verified" && assets.release.id === null)
1765
- ) {
1766
- throw new Error("Invalid Gitea release identity or status.");
1767
- }
1768
- const frozen: unknown[] = [];
1769
- for (const entry of assets.assets) {
1770
- if (!isPlainObject(entry)) throw new Error("Invalid Gitea asset target.");
1771
- assertExactKeys(
1772
- entry,
1773
- ["state", "attempts", "attempt", "error", "asset"],
1774
- "Gitea asset target",
1775
- );
1776
- assertTargetStatus(entry, "Gitea asset target");
1777
- if (entry.state === "skipped")
1778
- throw new Error("Gitea asset targets cannot be skipped.");
1779
- frozen.push(entry.asset);
1780
- }
1781
- assertGiteaFrozenAssets(
1782
- frozen,
1783
- assets.destination as unknown as IGiteaAssetDestination,
1784
- (valueArg.release as IReleaseJournalV1["release"])?.tag,
1785
- );
1786
2080
  const commonComplete = [valueArg.git, ...valueArg.npm.registries].every(
1787
2081
  (entry) => isTerminalTargetState(entry?.state),
1788
2082
  );
@@ -1799,54 +2093,18 @@ const assertReleaseJournalV4 = (
1799
2093
  updatedAt: valueArg.updatedAt,
1800
2094
  completedAt: commonComplete ? valueArg.updatedAt : null,
1801
2095
  };
1802
- if (valueArg.packages.length) assertReleaseJournalV3(common);
1803
- else assertReleaseJournalV1(common);
1804
- const journal = valueArg as unknown as IReleaseJournalV4;
1805
- const statuses = [
1806
- journal.git,
1807
- journal.giteaAssets.release,
1808
- ...journal.giteaAssets.assets,
1809
- ...journal.npm.registries,
1810
- ];
1811
- // Attachments may publish concurrently, each under its own attempt; any
1812
- // other target has one owner and never overlaps them.
1813
- const otherPublishing = [
2096
+ const { release } = valueArg.packages.length
2097
+ ? assertReleaseJournalV3(common)
2098
+ : assertReleaseJournalV1(common);
2099
+ assertReleaseAssetsSection(target, section, release);
2100
+ const journal = valueArg as unknown as TReleaseAssetsJournal;
2101
+ assertReleaseAssetsPublicationOrder(
1814
2102
  journal.git,
1815
- journal.giteaAssets.release,
1816
- ...journal.npm.registries,
1817
- ].filter((entry) => entry.state === "publishing").length;
1818
- const assetsPublishing = journal.giteaAssets.assets.filter(
1819
- (entry) => entry.state === "publishing",
1820
- ).length;
1821
- if (
1822
- journal.git.state === "skipped" ||
1823
- otherPublishing > 1 ||
1824
- (otherPublishing > 0 && assetsPublishing > 0)
1825
- ) {
1826
- throw new Error(
1827
- "Gitea assets require an active Git target and one publication owner outside concurrent attachment uploads.",
1828
- );
1829
- }
1830
- const assetStates = journal.giteaAssets.assets;
1831
- const npmStarted = journal.npm.registries.some(
1832
- (entry) => entry.state !== "pending",
2103
+ getReleaseAssets(journal)!,
2104
+ journal.npm.registries,
2105
+ journal.npm.registries,
2106
+ "npm",
1833
2107
  );
1834
- if (
1835
- (journal.git.state !== "verified" &&
1836
- journal.git.state !== "conflict" &&
1837
- statuses.slice(1).some((entry) => entry.state !== "pending")) ||
1838
- (journal.giteaAssets.release.state !== "verified" &&
1839
- journal.giteaAssets.release.state !== "conflict" &&
1840
- assetStates.some((entry) => entry.state !== "pending")) ||
1841
- (npmStarted &&
1842
- (journal.giteaAssets.release.id === null ||
1843
- assetStates.some(
1844
- (entry) => !["verified", "conflict"].includes(entry.state),
1845
- )))
1846
- )
1847
- throw new Error(
1848
- "Release targets violate Git, Gitea assets, npm publication order.",
1849
- );
1850
2108
  if (journal.completedAt !== null) {
1851
2109
  const completed = assertIsoTimestamp(
1852
2110
  journal.completedAt,
@@ -1860,7 +2118,7 @@ const assertReleaseJournalV4 = (
1860
2118
  throw new Error("Release journal completion state is inconsistent.");
1861
2119
  }
1862
2120
  // Every target verified with no completedAt yet: the final verification of
1863
- // the complete attachment set has not passed, and resume runs it.
2121
+ // the complete asset set has not passed, and resume runs it.
1864
2122
  return journal;
1865
2123
  };
1866
2124
 
@@ -2134,29 +2392,73 @@ const assertSchema2AppendOnlyTransition = (
2134
2392
  }
2135
2393
  };
2136
2394
 
2137
- const assertSchema4AppendOnlyTransition = (
2138
- current: IReleaseJournalV4,
2139
- next: IReleaseJournalV4,
2395
+ /**
2396
+ * A code host's id is recorded once, by the transition that verifies its
2397
+ * target, and never replaced.
2398
+ */
2399
+ const assertRecordedIdTransition = (
2400
+ beforeArg: number | string | null,
2401
+ afterArg: IReleaseTargetStatus,
2402
+ afterIdArg: number | string | null,
2403
+ contextArg: string,
2140
2404
  ): void => {
2405
+ if (beforeArg !== null && beforeArg !== afterIdArg)
2406
+ throw new Error(`The recorded ${contextArg} identity cannot be replaced.`);
2407
+ if (beforeArg === null && afterIdArg !== null && afterArg.state !== "verified")
2408
+ throw new Error(
2409
+ `A ${contextArg} identity must be verified before recording it.`,
2410
+ );
2411
+ };
2412
+
2413
+ /**
2414
+ * The transition of a journal with a release asset section, schema 4 or
2415
+ * schema 2 beside Docker: each id is write-once, and Git, the section and npm
2416
+ * are append-only. Schema 2 runs its Docker checks besides.
2417
+ */
2418
+ const assertReleaseAssetsAppendOnlyTransition = (
2419
+ current: TReleaseJournal,
2420
+ next: TReleaseJournal,
2421
+ ): void => {
2422
+ // The immutable identity already holds both to the same section and frozen set.
2423
+ const currentAssets = getReleaseAssets(current);
2424
+ const nextAssets = getReleaseAssets(next);
2425
+ if (!currentAssets && !nextAssets) return;
2141
2426
  if (
2142
- current.giteaAssets.release.id !== null &&
2143
- current.giteaAssets.release.id !== next.giteaAssets.release.id
2427
+ currentAssets?.target === "giteaAssets" &&
2428
+ nextAssets?.target === "giteaAssets"
2144
2429
  ) {
2145
- throw new Error("The recorded Gitea release identity cannot be replaced.");
2146
- }
2147
- if (
2148
- current.giteaAssets.release.id === null &&
2149
- next.giteaAssets.release.id !== null &&
2150
- next.giteaAssets.release.state !== "verified"
2430
+ assertRecordedIdTransition(
2431
+ currentAssets.section.release.id,
2432
+ nextAssets.section.release,
2433
+ nextAssets.section.release.id,
2434
+ "Gitea release",
2435
+ );
2436
+ } else if (
2437
+ currentAssets?.target === "fossglobalAssets" &&
2438
+ nextAssets?.target === "fossglobalAssets"
2151
2439
  ) {
2152
- throw new Error(
2153
- "A Gitea release identity must be verified before recording it.",
2440
+ const { label } = releaseAssetTargets.fossglobalAssets;
2441
+ assertRecordedIdTransition(
2442
+ currentAssets.section.release.releaseId,
2443
+ nextAssets.section.release,
2444
+ nextAssets.section.release.releaseId,
2445
+ `${label} release`,
2154
2446
  );
2447
+ for (const [index, before] of currentAssets.section.assets.entries()) {
2448
+ const after = nextAssets.section.assets[index];
2449
+ assertRecordedIdTransition(
2450
+ before.assetId,
2451
+ after,
2452
+ after.assetId,
2453
+ `${label} asset`,
2454
+ );
2455
+ }
2456
+ } else {
2457
+ throw new Error("A release asset journal cannot change its section.");
2155
2458
  }
2156
- const statuses = (journal: IReleaseJournalV4) => [
2459
+ const statuses = (journal: TReleaseJournal) => [
2157
2460
  journal.git,
2158
- journal.giteaAssets.release,
2159
- ...journal.giteaAssets.assets,
2461
+ ...getReleaseAssetsStatuses(journal),
2160
2462
  ...journal.npm.registries,
2161
2463
  ];
2162
2464
  const nextStatuses = statuses(next);
@@ -2257,6 +2559,7 @@ export interface IReleaseIntent {
2257
2559
  const releaseTargets: readonly TReleaseTarget[] = [
2258
2560
  "git",
2259
2561
  "giteaAssets",
2562
+ "fossglobalAssets",
2260
2563
  "npm",
2261
2564
  "cargo",
2262
2565
  "docker",
@@ -2324,19 +2627,24 @@ export const assertReleaseIntent = (valueArg: unknown): IReleaseIntent => {
2324
2627
  const release = assertReleaseIdentity(valueArg.release);
2325
2628
  const plan = assertReleaseIntentPlan(valueArg.plan);
2326
2629
  const git = assertReleaseIntentGit(valueArg.git);
2630
+ assertSingleReleaseAssetTarget(plan.targets);
2631
+ const assetTarget = releaseAssetTargetNames.find((targetArg) =>
2632
+ plan.targets.includes(targetArg),
2633
+ );
2327
2634
  if (
2328
2635
  release.prerelease &&
2329
- (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
2636
+ (plan.targets.includes("docker") || assetTarget !== undefined)
2330
2637
  )
2331
2638
  throw new Error("Prerelease intents support Git, npm and cargo targets only.");
2332
- if (
2333
- plan.targets.includes("cargo") &&
2334
- (plan.targets.includes("docker") || plan.targets.includes("giteaAssets"))
2335
- )
2639
+ if (plan.targets.includes("cargo") && assetTarget !== undefined)
2640
+ throw new Error(
2641
+ `A cargo release intent cannot name Docker or ${releaseAssetTargets[assetTarget].label} assets.`,
2642
+ );
2643
+ if (plan.targets.includes("cargo") && plan.targets.includes("docker"))
2336
2644
  throw new Error("A cargo release intent cannot name Docker or Gitea assets.");
2337
- if (release.line && plan.targets.includes("giteaAssets")) {
2645
+ if (release.line && assetTarget !== undefined) {
2338
2646
  throw new Error(
2339
- "A release line never publishes Gitea assets; its intent cannot name them.",
2647
+ `A release line never publishes ${releaseAssetTargets[assetTarget].label} assets; its intent cannot name them.`,
2340
2648
  );
2341
2649
  }
2342
2650
  if (plan.targets.includes("git") !== (git !== null)) {
@@ -2681,13 +2989,16 @@ export class ReleaseJournalStore {
2681
2989
  .map((name) => plugins.path.join(this.rootPath, name));
2682
2990
  }
2683
2991
 
2684
- /** True when a journal's npm tarballs or Gitea assets are not stored. */
2992
+ /** True when a journal's npm tarballs, crates or release assets are not stored. */
2685
2993
  public async isPayloadMissing(journalArg: TReleaseJournal): Promise<boolean> {
2994
+ const releaseAssets = getReleaseAssets(journalArg);
2686
2995
  const files = [
2687
2996
  ...getReleaseArtifacts(journalArg).map((artifact) => artifact.file),
2688
2997
  ...(getReleaseCargo(journalArg)?.crates.map((crate) => crate.file) ?? []),
2689
- ...(journalArg.schemaVersion === 4
2690
- ? journalArg.giteaAssets.assets.map((entry) => entry.asset.fileName)
2998
+ ...(releaseAssets
2999
+ ? getFrozenReleaseAssets(releaseAssets.section).map(
3000
+ (asset) => asset.fileName,
3001
+ )
2691
3002
  : []),
2692
3003
  ];
2693
3004
  for (const file of files) {
@@ -2895,9 +3206,7 @@ export class ReleaseJournalStore {
2895
3206
  [
2896
3207
  journal.git,
2897
3208
  ...journal.npm.registries,
2898
- ...(journal.schemaVersion === 4
2899
- ? [journal.giteaAssets.release, ...journal.giteaAssets.assets]
2900
- : []),
3209
+ ...getReleaseAssetsStatuses(journal),
2901
3210
  ].some(
2902
3211
  (target) =>
2903
3212
  !["pending", "skipped"].includes(target.state) ||
@@ -2927,7 +3236,11 @@ export class ReleaseJournalStore {
2927
3236
  );
2928
3237
  }
2929
3238
  if (journal.schemaVersion === releaseJournalSchemaVersion) {
2930
- const commonTargets = [journal.git, ...journal.npm.registries];
3239
+ const commonTargets = [
3240
+ journal.git,
3241
+ ...journal.npm.registries,
3242
+ ...getReleaseAssetsStatuses(journal),
3243
+ ];
2931
3244
  const commonTargetsUnclaimed = commonTargets.every(
2932
3245
  (targetArg) =>
2933
3246
  (targetArg.state === "pending" || targetArg.state === "skipped") &&
@@ -3008,14 +3321,21 @@ export class ReleaseJournalStore {
3008
3321
  );
3009
3322
  }
3010
3323
  }
3011
- if (journal.schemaVersion === 4) {
3012
- if (journal.giteaAssets.release.id !== null)
3324
+ const releaseAssets = getReleaseAssets(journal);
3325
+ if (releaseAssets) {
3326
+ // A release id comes first; the claim refuses an asset id without it.
3327
+ if (
3328
+ ("id" in releaseAssets.section.release
3329
+ ? releaseAssets.section.release.id
3330
+ : releaseAssets.section.release.releaseId) !== null
3331
+ )
3013
3332
  throw new Error(
3014
- "New Gitea asset journals must not preclaim a release identity.",
3333
+ `New ${releaseAssetTargets[releaseAssets.target].label} asset journals must not preclaim a release identity.`,
3015
3334
  );
3016
- await validateGiteaAssets(
3335
+ await validateReleaseAssets(
3336
+ releaseAssets.target,
3017
3337
  temporaryDirectory,
3018
- journal.giteaAssets.assets.map((entry) => entry.asset),
3338
+ getFrozenReleaseAssets(releaseAssets.section),
3019
3339
  );
3020
3340
  }
3021
3341
 
@@ -3097,8 +3417,7 @@ export class ReleaseJournalStore {
3097
3417
  ) {
3098
3418
  assertSchema2AppendOnlyTransition(current, next);
3099
3419
  }
3100
- if (current.schemaVersion === 4 && next.schemaVersion === 4)
3101
- assertSchema4AppendOnlyTransition(current, next);
3420
+ assertReleaseAssetsAppendOnlyTransition(current, next);
3102
3421
  const currentCargo = getReleaseCargo(current);
3103
3422
  const nextCargo = getReleaseCargo(next);
3104
3423
  if (currentCargo && nextCargo) {