@wtf/release-docs 9.0.1 → 9.1.0

package/api/@wtf/release-oci/publish/README.md

@@ -0,0 +1,52 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-oci/publish
+
+# @wtf/release-oci/publish
+
+The images of a release published, of no rebuild, by crane: [smokeImages](functions/smokeImages.md) finds the tested
+image of each, its source, by its digest, and the platforms it is of; [publishImages](functions/publishImages.md) copies
+that digest to each tag of the release, `crane copy <source>@<digest> <image>:<tag>`, which mounts
+each blob of the source's repository rather than moving it. The tag of the version is copied once:
+a registry that has it at the same digest is skipped, so a release that stopped part way is
+finished by running it again, and at another digest is refused (`EOCIRETAG`), as a released
+version never moves. The moving tags, as `1.4` and `1`, are copied every time.
+
+crane runs by the `System` it is given, of the environment it is given: it reads the credentials
+of the registry of its own config, as `crane auth login` writes it, or of the docker config.
+
+```ts
+import { publishImages } from '@wtf/release-oci/publish'
+import type { System } from '@wtf/release-system'
+
+export async function release(system: System): Promise<void> {
+  await publishImages({
+    context: { system },
+    images: [
+      {
+        repository: 'registry.gitlab.com/acme/images/base',
+        source: { repository: 'registry.gitlab.com/acme/images/base/snapshot', tag: 'base-v1-4-2' }
+      }
+    ],
+    version: '1.4.2'
+  })
+}
+```
+
+## Interfaces
+
+- [CraneContext](interfaces/CraneContext.md)
+- [ImagesRelease](interfaces/ImagesRelease.md)
+- [ImageToPublish](interfaces/ImageToPublish.md)
+- [OciSource](interfaces/OciSource.md)
+- [PublishedImage](interfaces/PublishedImage.md)
+- [SmokedImage](interfaces/SmokedImage.md)
+
+## Functions
+
+- [digestOf](functions/digestOf.md)
+- [platformsOf](functions/platformsOf.md)
+- [publishImages](functions/publishImages.md)
+- [smokeImages](functions/smokeImages.md)

package/api/@wtf/release-oci/publish/functions/digestOf.md

@@ -0,0 +1,38 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / digestOf
+
+# Function: digestOf()
+
+> **digestOf**(`ref`, `context`): `Promise`\<`string` \| `undefined`\>
+
+Defined in: [packages/release-oci/src/publish.ts:114](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L114)
+
+The digest of the image `ref`, as `crane digest` gives it: none of a repository or a tag the
+registry has not.
+
+## Parameters
+
+### ref
+
+`string`
+
+The reference of the image, as `registry.example/a:1.4.2`.
+
+### context
+
+[`CraneContext`](../interfaces/CraneContext.md)
+
+Where crane runs, and its command.
+
+## Returns
+
+`Promise`\<`string` \| `undefined`\>
+
+The digest, as `sha256:…`; none of an image the registry has not.
+
+## Throws
+
+`EOCISMOKE` of a registry crane cannot ask, as of no credentials.

package/api/@wtf/release-oci/publish/functions/platformsOf.md

@@ -0,0 +1,44 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / platformsOf
+
+# Function: platformsOf()
+
+> **platformsOf**(`ref`, `digest`, `context`): `Promise`\<`string`[]\>
+
+Defined in: [packages/release-oci/src/publish.ts:135](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L135)
+
+The platforms of the image `ref` at `digest`: of an index, each manifest's `os/architecture` and
+variant, of `crane manifest`; of a manifest of no index, none.
+
+## Parameters
+
+### ref
+
+`string`
+
+The repository of the image, as `registry.example/a`.
+
+### digest
+
+`string`
+
+Its digest, as `sha256:…`.
+
+### context
+
+[`CraneContext`](../interfaces/CraneContext.md)
+
+Where crane runs, and its command.
+
+## Returns
+
+`Promise`\<`string`[]\>
+
+The platforms, as `['linux/amd64', 'linux/arm64']`.
+
+## Throws
+
+`EOCISMOKE` of a manifest crane cannot give, or that is no JSON.

package/api/@wtf/release-oci/publish/functions/publishImages.md

@@ -0,0 +1,30 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / publishImages
+
+# Function: publishImages()
+
+> **publishImages**(`release`): `Promise`\<[`PublishedImage`](../interfaces/PublishedImage.md)[]\>
+
+Defined in: [packages/release-oci/src/publish.ts:236](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L236)
+
+The images of a release published: each source smoked ([smokeImages](smokeImages.md)), then copied by its
+digest to the tag of the version, of an image the registry has not at it, and to each moving tag.
+Throws, together, `EOCIRETAG` of each image whose version the registry has at another digest,
+before anything is copied; and `EOCITAG` of a copy crane cannot make.
+
+## Parameters
+
+### release
+
+[`ImagesRelease`](../interfaces/ImagesRelease.md)
+
+The images, the version and where crane runs.
+
+## Returns
+
+`Promise`\<[`PublishedImage`](../interfaces/PublishedImage.md)[]\>
+
+Each image, of the tags copied and skipped.

package/api/@wtf/release-oci/publish/functions/smokeImages.md

@@ -0,0 +1,41 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / smokeImages
+
+# Function: smokeImages()
+
+> **smokeImages**(`images`, `context`, `platforms?`): `Promise`\<[`SmokedImage`](../interfaces/SmokedImage.md)[]\>
+
+Defined in: [packages/release-oci/src/publish.ts:170](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L170)
+
+The tested image of each image of a release, as the registry has it: its digest and its
+platforms. Throws, together, `EOCISMOKE` of each source the registry has not, or of fewer
+platforms than `platforms` names.
+
+## Parameters
+
+### images
+
+readonly [`ImageToPublish`](../interfaces/ImageToPublish.md)[]
+
+The images of the release, each of its source.
+
+### context
+
+[`CraneContext`](../interfaces/CraneContext.md)
+
+Where crane runs, and its command.
+
+### platforms?
+
+readonly `string`[] = `[]`
+
+The platforms each source must be of, as `['linux/amd64']`: any by default.
+
+## Returns
+
+`Promise`\<[`SmokedImage`](../interfaces/SmokedImage.md)[]\>
+
+Each image, of the digest and the platforms of its source.

package/api/@wtf/release-oci/publish/interfaces/CraneContext.md

@@ -0,0 +1,67 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / CraneContext
+
+# Interface: CraneContext
+
+Defined in: [packages/release-oci/src/publish.ts:57](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L57)
+
+Where crane runs: the folder, the environment and the system, and the command of crane.
+
+## Extends
+
+- [`GitContext`](../../../release-system/git/interfaces/GitContext.md)
+
+## Properties
+
+### crane?
+
+> `readonly` `optional` **crane?**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:59](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L59)
+
+The command of crane, by its name on the path or its path: `crane` by default.
+
+***
+
+### cwd?
+
+> `readonly` `optional` **cwd?**: `string`
+
+Defined in: [packages/release-system/src/git.ts:26](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/git.ts#L26)
+
+The folder of the repo: the system's working folder by default.
+
+#### Inherited from
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md).[`cwd`](../../../release-system/git/interfaces/GitContext.md#cwd)
+
+***
+
+### env?
+
+> `readonly` `optional` **env?**: `Readonly`\<`Record`\<`string`, `string` \| `undefined`\>\>
+
+Defined in: [packages/release-system/src/git.ts:28](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/git.ts#L28)
+
+The environment of git: the system's by default.
+
+#### Inherited from
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md).[`env`](../../../release-system/git/interfaces/GitContext.md#env)
+
+***
+
+### system
+
+> `readonly` **system**: [`System`](../../../release-system/system/interfaces/System.md)
+
+Defined in: [packages/release-system/src/git.ts:30](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-system/src/git.ts#L30)
+
+The system git runs by, which it requires.
+
+#### Inherited from
+
+[`GitContext`](../../../release-system/git/interfaces/GitContext.md).[`system`](../../../release-system/git/interfaces/GitContext.md#system)

package/api/@wtf/release-oci/publish/interfaces/ImageToPublish.md

@@ -0,0 +1,35 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / ImageToPublish
+
+# Interface: ImageToPublish
+
+Defined in: [packages/release-oci/src/publish.ts:49](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L49)
+
+An image of a release: its repository, and the tested image a release copies to its tags.
+
+## Extended by
+
+- [`SmokedImage`](SmokedImage.md)
+
+## Properties
+
+### repository
+
+> `readonly` **repository**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:51](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L51)
+
+The repository of the image, as `registry.gitlab.com/acme/images/base`.
+
+***
+
+### source
+
+> `readonly` **source**: [`OciSource`](OciSource.md)
+
+Defined in: [packages/release-oci/src/publish.ts:53](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L53)
+
+The tested image, which the release copies.

package/api/@wtf/release-oci/publish/interfaces/ImagesRelease.md

@@ -0,0 +1,83 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / ImagesRelease
+
+# Interface: ImagesRelease
+
+Defined in: [packages/release-oci/src/publish.ts:208](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L208)
+
+What [publishImages](../functions/publishImages.md) publishes.
+
+## Properties
+
+### context
+
+> `readonly` **context**: [`CraneContext`](CraneContext.md)
+
+Defined in: [packages/release-oci/src/publish.ts:210](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L210)
+
+Where crane runs, and its command.
+
+***
+
+### images
+
+> `readonly` **images**: readonly [`ImageToPublish`](ImageToPublish.md)[]
+
+Defined in: [packages/release-oci/src/publish.ts:212](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L212)
+
+The images of the release, each of its source.
+
+***
+
+### log?
+
+> `readonly` `optional` **log?**: (`line`) => `void`
+
+Defined in: [packages/release-oci/src/publish.ts:224](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L224)
+
+Where the steps are said, a line each.
+
+#### Parameters
+
+##### line
+
+`string`
+
+The line.
+
+#### Returns
+
+`void`
+
+***
+
+### moving?
+
+> `readonly` `optional` **moving?**: `boolean`
+
+Defined in: [packages/release-oci/src/publish.ts:216](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L216)
+
+Whether a release moves its minor and its major: `true` by default.
+
+***
+
+### platforms?
+
+> `readonly` `optional` **platforms?**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/publish.ts:218](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L218)
+
+The platforms each source must be of: any by default.
+
+***
+
+### version
+
+> `readonly` **version**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:214](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L214)
+
+The version of the release, as `1.4.2`.

package/api/@wtf/release-oci/publish/interfaces/OciSource.md

@@ -0,0 +1,31 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / OciSource
+
+# Interface: OciSource
+
+Defined in: [packages/release-oci/src/publish.ts:41](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L41)
+
+The tested image of a release: its repository and its tag, as the pipeline that tested it wrote it.
+
+## Properties
+
+### repository
+
+> `readonly` **repository**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:43](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L43)
+
+Its repository, as `registry.gitlab.com/acme/images/base/snapshot`.
+
+***
+
+### tag
+
+> `readonly` **tag**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:45](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L45)
+
+Its tag, as `base-v1-4-2`.

package/api/@wtf/release-oci/publish/interfaces/PublishedImage.md

@@ -0,0 +1,101 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / PublishedImage
+
+# Interface: PublishedImage
+
+Defined in: [packages/release-oci/src/publish.ts:71](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L71)
+
+An image of a release published: each tag copied, and each the registry had already.
+
+## Extends
+
+- [`SmokedImage`](SmokedImage.md)
+
+## Properties
+
+### digest
+
+> `readonly` **digest**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:65](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L65)
+
+The digest of the source, as `sha256:…`.
+
+#### Inherited from
+
+[`SmokedImage`](SmokedImage.md).[`digest`](SmokedImage.md#digest)
+
+***
+
+### platforms
+
+> `readonly` **platforms**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/publish.ts:67](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L67)
+
+The platforms it is of, as `linux/amd64`: none of an image of one manifest of no index.
+
+#### Inherited from
+
+[`SmokedImage`](SmokedImage.md).[`platforms`](SmokedImage.md#platforms)
+
+***
+
+### repository
+
+> `readonly` **repository**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:51](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L51)
+
+The repository of the image, as `registry.gitlab.com/acme/images/base`.
+
+#### Inherited from
+
+[`SmokedImage`](SmokedImage.md).[`repository`](SmokedImage.md#repository)
+
+***
+
+### skipped
+
+> `readonly` **skipped**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/publish.ts:77](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L77)
+
+Each tag the registry had already at the digest of the source, and the release skipped.
+
+***
+
+### source
+
+> `readonly` **source**: [`OciSource`](OciSource.md)
+
+Defined in: [packages/release-oci/src/publish.ts:53](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L53)
+
+The tested image, which the release copies.
+
+#### Inherited from
+
+[`SmokedImage`](SmokedImage.md).[`source`](SmokedImage.md#source)
+
+***
+
+### tags
+
+> `readonly` **tags**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/publish.ts:75](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L75)
+
+Each tag the release copied the source to, the version's first.
+
+***
+
+### version
+
+> `readonly` **version**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:73](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L73)
+
+The version of the release, as `1.4.2`.

package/api/@wtf/release-oci/publish/interfaces/SmokedImage.md

@@ -0,0 +1,67 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/publish](../README.md) / SmokedImage
+
+# Interface: SmokedImage
+
+Defined in: [packages/release-oci/src/publish.ts:63](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L63)
+
+The tested image of an image, as the registry has it.
+
+## Extends
+
+- [`ImageToPublish`](ImageToPublish.md)
+
+## Extended by
+
+- [`PublishedImage`](PublishedImage.md)
+
+## Properties
+
+### digest
+
+> `readonly` **digest**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:65](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L65)
+
+The digest of the source, as `sha256:…`.
+
+***
+
+### platforms
+
+> `readonly` **platforms**: readonly `string`[]
+
+Defined in: [packages/release-oci/src/publish.ts:67](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L67)
+
+The platforms it is of, as `linux/amd64`: none of an image of one manifest of no index.
+
+***
+
+### repository
+
+> `readonly` **repository**: `string`
+
+Defined in: [packages/release-oci/src/publish.ts:51](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L51)
+
+The repository of the image, as `registry.gitlab.com/acme/images/base`.
+
+#### Inherited from
+
+[`ImageToPublish`](ImageToPublish.md).[`repository`](ImageToPublish.md#repository)
+
+***
+
+### source
+
+> `readonly` **source**: [`OciSource`](OciSource.md)
+
+Defined in: [packages/release-oci/src/publish.ts:53](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/publish.ts#L53)
+
+The tested image, which the release copies.
+
+#### Inherited from
+
+[`ImageToPublish`](ImageToPublish.md).[`source`](ImageToPublish.md#source)

package/api/@wtf/release-oci/registry/README.md

@@ -0,0 +1,34 @@
+[**Release trains**](../../../README.md)
+
+***
+
+[Release trains](../../../README.md) / @wtf/release-oci/registry
+
+# @wtf/release-oci/registry
+
+The page of an image in the container registry of GitLab ([registryPageOf](functions/registryPageOf.md)), which the
+GitLab release of a tag links each image by: the Container Registry API of the project lists its
+repositories, `GET /projects/<id>/registry/repositories`, each of its `location`, as
+`registry.gitlab.com/acme/images/base`, and its ID, whose page is
+`<project>/container_registry/<id>`. An image is linked where it lives, never uploaded.
+
+```ts
+import { registryPageOf } from '@wtf/release-oci/registry'
+import { gitlabHeadersOf, gitlabProjectOf } from '@wtf/release-trains/gitlab'
+
+const env = { CI_PROJECT_PATH: 'acme/images', GITLAB_TOKEN: 'token' }
+export const page = await registryPageOf({
+  fetch,
+  project: gitlabProjectOf({}, env, undefined),
+  repository: 'registry.gitlab.com/acme/images/base',
+  headers: gitlabHeadersOf(env)
+})
+```
+
+## Interfaces
+
+- [RegistryQuery](interfaces/RegistryQuery.md)
+
+## Functions
+
+- [registryPageOf](functions/registryPageOf.md)

package/api/@wtf/release-oci/registry/functions/registryPageOf.md

@@ -0,0 +1,30 @@
+[**Release trains**](../../../../README.md)
+
+***
+
+[Release trains](../../../../README.md) / [@wtf/release-oci/registry](../README.md) / registryPageOf
+
+# Function: registryPageOf()
+
+> **registryPageOf**(`query`): `Promise`\<`string`\>
+
+Defined in: [packages/release-oci/src/registry.ts:55](https://gitlab.com/wetryfun/release/release/-/blob/838e75e66ef604439e05c0180870e65b00370ea2/packages/release-oci/src/registry.ts#L55)
+
+The page of the image `repository` in the container registry of `project`: the repository of its
+`location`, of the first page of a hundred, at `<project>/container_registry/<id>`. Throws
+`EOCILINK` of a request GitLab refuses or that cannot be made, and of a registry that lists no
+repository of the location.
+
+## Parameters
+
+### query
+
+[`RegistryQuery`](../interfaces/RegistryQuery.md)
+
+The `fetch`, the project, the repository and the headers.
+
+## Returns
+
+`Promise`\<`string`\>
+
+The URL of the page of the image.