@containerbase/base 14.41.1 → 14.43.0

package/README.md

@@ -47,6 +47,16 @@ import { defaultDistro } from '@containerbase/base';
 defaultDistro; // 'noble'
 ```
 
+The format of the published [tool-versions](https://github.com/containerbase/tool-versions/blob/main/docs/format.md) data is exported too, so its readers share one definition.
+The zod schemas (`ToolVersions`, `VersionFiles`, `VersionIntegrity`, `ToolIndex`, `FormatIndex` and their parts) live behind the `zod` entry point, the zod free types behind the main one:
+
+```ts
+import { ToolVersions } from '@containerbase/base/zod';
+import type { ToolVersions as ToolVersionsType } from '@containerbase/base';
+```
+
+The schemas ignore unknown keys and accept any arch name, so additive changes of the format don't break a reader; readers ignore files of an arch they don't know.
+
 ## Contents
 
 Each entry may carry the following metadata:

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { tools } from './data.ts';
 import type { DistroCode } from './types.ts';
 export type { DistroCode, InstallToolType, ToolMetadata, ToolType, } from './types.ts';
+export type { FileIntegrity, FileReference, FormatIndex, ToolFile, ToolIndex, ToolVersion, ToolVersions, VersionFiles, VersionIntegrity, } from './tool-versions-types.ts';
 export { tools };
 /**
  * The Ubuntu release the default containerbase image is built from, the

package/dist/tool-versions-schema.d.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+/** A file of a version: where to download it and how to verify it. */
+export declare const ToolFile: z.ZodObject<{
+    name: z.ZodString;
+    url: z.ZodURL;
+    checksum: z.ZodString;
+    arch: z.ZodExactOptional<z.ZodString>;
+    distro: z.ZodExactOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * An SRI-style sha256 digest of a published file's bytes, like npm's
+ * `integrity`.
+ */
+export declare const FileIntegrity: z.ZodString;
+/**
+ * A version `install-tool` can install, the flags are only set when true and
+ * `files` and `releaseTimestamp` only when known.
+ */
+export declare const ToolVersion: z.ZodObject<{
+    version: z.ZodString;
+    prerelease: z.ZodExactOptional<z.ZodLiteral<true>>;
+    lts: z.ZodExactOptional<z.ZodLiteral<true>>;
+    releaseTimestamp: z.ZodExactOptional<z.ZodISODateTime>;
+    files: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodURL;
+        checksum: z.ZodString;
+        arch: z.ZodExactOptional<z.ZodString>;
+        distro: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    constraints: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+/** The content of a `<tool>.json` file. */
+export declare const ToolVersions: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodURL>;
+    tool: z.ZodString;
+    type: z.ZodExactOptional<z.ZodEnum<{
+        gem: "gem";
+        npm: "npm";
+        pip: "pip";
+        dotnet: "dotnet";
+    }>>;
+    sourceUrl: z.ZodExactOptional<z.ZodURL>;
+    homepage: z.ZodExactOptional<z.ZodURL>;
+    minVersion: z.ZodExactOptional<z.ZodString>;
+    distroMinVersion: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    updatedAt: z.ZodISODateTime;
+    versions: z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        prerelease: z.ZodExactOptional<z.ZodLiteral<true>>;
+        lts: z.ZodExactOptional<z.ZodLiteral<true>>;
+        releaseTimestamp: z.ZodExactOptional<z.ZodISODateTime>;
+        files: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodURL;
+            checksum: z.ZodString;
+            arch: z.ZodExactOptional<z.ZodString>;
+            distro: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        constraints: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The content of a `<tool>/<version>.json` file: the files of one version. */
+export declare const VersionFiles: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodURL>;
+    tool: z.ZodString;
+    version: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodURL;
+        checksum: z.ZodString;
+        arch: z.ZodExactOptional<z.ZodString>;
+        distro: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The content of a `<tool>.integrity.json` file: the integrity of each
+ * `<tool>/<version>.json` file, by version.
+ */
+export declare const VersionIntegrity: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodURL>;
+    tool: z.ZodString;
+    versions: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+/** A published file and the integrity of its bytes. */
+export declare const FileReference: z.ZodObject<{
+    file: z.ZodString;
+    integrity: z.ZodString;
+}, z.core.$strip>;
+/** The content of the `v1/index.json` file. */
+export declare const ToolIndex: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodURL>;
+    updatedAt: z.ZodISODateTime;
+    tools: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        versionCount: z.ZodNumber;
+        slim: z.ZodObject<{
+            file: z.ZodString;
+            integrity: z.ZodString;
+        }, z.core.$strip>;
+        versionFiles: z.ZodExactOptional<z.ZodObject<{
+            file: z.ZodString;
+            integrity: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The content of the root `index.json` file, which lists the published formats.
+ * It is minimal and stable: consumers pin a major version of the format and
+ * only read it to warn when their major is deprecated.
+ */
+export declare const FormatIndex: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodURL>;
+    defaultDistro: z.ZodString;
+    formats: z.ZodArray<z.ZodObject<{
+        version: z.ZodNumber;
+        path: z.ZodString;
+        status: z.ZodEnum<{
+            current: "current";
+            preview: "preview";
+            deprecated: "deprecated";
+        }>;
+        removalDate: z.ZodExactOptional<z.ZodISODate>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/tool-versions-schema.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { ToolType } from "./schema.js";
+// Reader schemas of the published tool-versions format, see
+// https://github.com/containerbase/tool-versions/blob/main/docs/format.md
+//
+// Keep in sync with the interfaces in `tool-versions-types.ts`, which are the
+// zod free version used by the default export. The objects are plain
+// `z.object`s, so unknown keys are dropped and additive changes of the format
+// don't break readers. Optionals are exact, so the inferred types match the
+// interfaces.
+/** A file of a version: where to download it and how to verify it. */
+export const ToolFile = z.object({
+    /** the file name */
+    name: z.string().min(1),
+    /** the https download url */
+    url: z.url({ protocol: /^https$/ }),
+    /** `<algorithm>:<lowercase hex>` */
+    checksum: z
+        .string()
+        .regex(/^(sha1:[0-9a-f]{40}|sha256:[0-9a-f]{64}|sha512:[0-9a-f]{128})$/),
+    /**
+     * the containerbase arch, like `amd64`, omitted for arch-independent files;
+     * readers ignore files of an arch they don't know
+     */
+    arch: z.string().min(1).exactOptional(),
+    /** the distro of a distro specific file, like `jammy` */
+    distro: z.string().min(1).exactOptional(),
+});
+/**
+ * An SRI-style sha256 digest of a published file's bytes, like npm's
+ * `integrity`.
+ */
+export const FileIntegrity = z.string().regex(/^sha256-[0-9A-Za-z+/]{43}=$/);
+/**
+ * A version `install-tool` can install, the flags are only set when true and
+ * `files` and `releaseTimestamp` only when known.
+ */
+export const ToolVersion = z.object({
+    version: z.string().min(1),
+    prerelease: z.literal(true).exactOptional(),
+    lts: z.literal(true).exactOptional(),
+    /** when the version was released, in UTC */
+    releaseTimestamp: z.iso.datetime().exactOptional(),
+    /**
+     * sorted by name, not in the `<tool>.json` files, but in the
+     * `<tool>/<version>.json` ones
+     */
+    files: z.array(ToolFile).min(1).exactOptional(),
+    /**
+     * the runtime constraint of this version per parent tool, like
+     * `{ node: '>=20.17.0' }`, as the raw string in the registry's syntax, only
+     * present when the registry has one
+     */
+    constraints: z.record(z.string().min(1), z.string().min(1)).exactOptional(),
+});
+/**
+ * The url of the json schema of a published file, which identifies its format.
+ * It is the first property, optional so files published before it was added
+ * still parse.
+ */
+const SchemaUrl = z.url({ protocol: /^https$/ }).exactOptional();
+/** The content of a `<tool>.json` file. */
+export const ToolVersions = z.object({
+    $schema: SchemaUrl,
+    tool: z.string(),
+    /** the package manager installing the tool, omitted for other tools */
+    type: ToolType.exactOptional(),
+    /** where the source code of the tool lives, omitted when unset */
+    sourceUrl: z.url({ protocol: /^https$/ }).exactOptional(),
+    /** the homepage of the tool, omitted when unset */
+    homepage: z.url({ protocol: /^https$/ }).exactOptional(),
+    /**
+     * the oldest version containerbase supports, on the `defaultDistro` of the
+     * root index, in the versioning of the tool. Older versions aren't listed.
+     * Omitted for tools without a limit.
+     */
+    minVersion: z.string().min(1).exactOptional(),
+    /**
+     * the oldest version on a distro, by codename, only for the distros whose
+     * floor differs from `minVersion`. Any codename is allowed, so new distros
+     * don't break readers.
+     */
+    distroMinVersion: z
+        .record(z.string().min(1), z.string().min(1))
+        .exactOptional(),
+    updatedAt: z.iso.datetime(),
+    /** newest first */
+    versions: z.array(ToolVersion),
+});
+/** The content of a `<tool>/<version>.json` file: the files of one version. */
+export const VersionFiles = z.object({
+    $schema: SchemaUrl,
+    tool: z.string(),
+    version: z.string().min(1),
+    /** sorted by name */
+    files: z.array(ToolFile).min(1),
+});
+/**
+ * The content of a `<tool>.integrity.json` file: the integrity of each
+ * `<tool>/<version>.json` file, by version.
+ */
+export const VersionIntegrity = z.object({
+    $schema: SchemaUrl,
+    tool: z.string(),
+    versions: z.record(z.string(), FileIntegrity),
+});
+/** A published file and the integrity of its bytes. */
+export const FileReference = z.object({
+    file: z.string(),
+    integrity: FileIntegrity,
+});
+/** The content of the `v1/index.json` file. */
+export const ToolIndex = z.object({
+    $schema: SchemaUrl,
+    updatedAt: z.iso.datetime(),
+    tools: z.array(z.object({
+        tool: z.string(),
+        versionCount: z.number().int().nonnegative(),
+        /** the `<tool>.json` file, the versions without their files */
+        slim: FileReference,
+        /**
+         * the `<tool>.integrity.json` file, with the integrity of each
+         * `<tool>/<version>.json` file, only for tools with files
+         */
+        versionFiles: FileReference.exactOptional(),
+    })),
+});
+/**
+ * The content of the root `index.json` file, which lists the published formats.
+ * It is minimal and stable: consumers pin a major version of the format and
+ * only read it to warn when their major is deprecated.
+ */
+export const FormatIndex = z.object({
+    $schema: SchemaUrl,
+    /**
+     * the codename of the Ubuntu release the default image is built from, which
+     * the `minVersion` of the tools refers to
+     */
+    defaultDistro: z.string().min(1),
+    formats: z.array(z.object({
+        /** the major version of the format */
+        version: z.number().int().positive(),
+        /** the folder of the format, relative to the root */
+        path: z.string().min(1),
+        /** `current` is the format to use, `preview` is not stable yet */
+        status: z.enum(['current', 'preview', 'deprecated']),
+        /** the date a deprecated format is no longer published */
+        removalDate: z.iso.date().exactOptional(),
+    })),
+});

package/dist/tool-versions-types.d.ts

@@ -0,0 +1,186 @@
+import type { ToolType } from './types.ts';
+/**
+ * A file of a version: where to download it and how to verify it.
+ */
+export interface ToolFile {
+    /**
+     * The file name.
+     */
+    name: string;
+    /**
+     * The https download url.
+     */
+    url: string;
+    /**
+     * `<algorithm>:<lowercase hex>`
+     */
+    checksum: string;
+    /**
+     * The containerbase arch, like `amd64`, omitted for arch-independent files;
+     * readers ignore files of an arch they don't know.
+     */
+    arch?: string;
+    /**
+     * The distro of a distro specific file, like `jammy`.
+     */
+    distro?: string;
+}
+/**
+ * An SRI-style sha256 digest of a published file's bytes, like npm's
+ * `integrity`.
+ */
+export type FileIntegrity = string;
+/**
+ * A version `install-tool` can install, the flags are only set when true and
+ * `files` and `releaseTimestamp` only when known.
+ */
+export interface ToolVersion {
+    version: string;
+    prerelease?: true;
+    lts?: true;
+    /**
+     * When the version was released, in UTC.
+     */
+    releaseTimestamp?: string;
+    /**
+     * Sorted by name, not in the `<tool>.json` files, but in the
+     * `<tool>/<version>.json` ones.
+     */
+    files?: ToolFile[];
+    /**
+     * The runtime constraint of this version per parent tool, like
+     * `{ node: '>=20.17.0' }`, as the raw string in the registry's syntax, only
+     * present when the registry has one.
+     */
+    constraints?: Record<string, string>;
+}
+/**
+ * The content of a `<tool>.json` file.
+ */
+export interface ToolVersions {
+    /**
+     * The url of the json schema of the file, which identifies its format.
+     */
+    $schema?: string;
+    tool: string;
+    /**
+     * The package manager installing the tool, omitted for other tools.
+     */
+    type?: ToolType;
+    /**
+     * Where the source code of the tool lives, omitted when unset.
+     */
+    sourceUrl?: string;
+    /**
+     * The homepage of the tool, omitted when unset.
+     */
+    homepage?: string;
+    /**
+     * The oldest version containerbase supports, on the `defaultDistro` of the
+     * root index, in the versioning of the tool. Older versions aren't listed.
+     * Omitted for tools without a limit.
+     */
+    minVersion?: string;
+    /**
+     * The oldest version on a distro, by codename, only for the distros whose
+     * floor differs from `minVersion`. Any codename is allowed, so new distros
+     * don't break readers.
+     */
+    distroMinVersion?: Record<string, string>;
+    updatedAt: string;
+    /**
+     * Newest first.
+     */
+    versions: ToolVersion[];
+}
+/**
+ * The content of a `<tool>/<version>.json` file: the files of one version.
+ */
+export interface VersionFiles {
+    /**
+     * The url of the json schema of the file, which identifies its format.
+     */
+    $schema?: string;
+    tool: string;
+    version: string;
+    /**
+     * Sorted by name.
+     */
+    files: ToolFile[];
+}
+/**
+ * The content of a `<tool>.integrity.json` file: the integrity of each
+ * `<tool>/<version>.json` file, by version.
+ */
+export interface VersionIntegrity {
+    /**
+     * The url of the json schema of the file, which identifies its format.
+     */
+    $schema?: string;
+    tool: string;
+    versions: Record<string, FileIntegrity>;
+}
+/**
+ * A published file and the integrity of its bytes.
+ */
+export interface FileReference {
+    file: string;
+    integrity: FileIntegrity;
+}
+/**
+ * The content of the `v1/index.json` file.
+ */
+export interface ToolIndex {
+    /**
+     * The url of the json schema of the file, which identifies its format.
+     */
+    $schema?: string;
+    updatedAt: string;
+    tools: {
+        tool: string;
+        versionCount: number;
+        /**
+         * The `<tool>.json` file, the versions without their files.
+         */
+        slim: FileReference;
+        /**
+         * The `<tool>.integrity.json` file, with the integrity of each
+         * `<tool>/<version>.json` file, only for tools with files.
+         */
+        versionFiles?: FileReference;
+    }[];
+}
+/**
+ * The content of the root `index.json` file, which lists the published formats.
+ * It is minimal and stable: consumers pin a major version of the format and
+ * only read it to warn when their major is deprecated.
+ */
+export interface FormatIndex {
+    /**
+     * The url of the json schema of the file, which identifies its format.
+     */
+    $schema?: string;
+    /**
+     * The codename of the Ubuntu release the default image is built from, which
+     * the `minVersion` of the tools refers to.
+     */
+    defaultDistro: string;
+    formats: {
+        /**
+         * The major version of the format.
+         */
+        version: number;
+        /**
+         * The folder of the format, relative to the root.
+         */
+        path: string;
+        /**
+         * `current` is the format to use, `preview` is not stable yet.
+         */
+        status: 'current' | 'preview' | 'deprecated';
+        /**
+         * The date a deprecated format is no longer published.
+         */
+        removalDate?: string;
+    }[];
+}

package/dist/tool-versions-types.js

@@ -0,0 +1 @@
+export {};

package/dist/zod.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export * from './schema.ts';
+export * from './tool-versions-schema.ts';
 /**
  * Enum of all tool names supported by the containerbase version this package
  * was released with.

package/dist/zod.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { toolNames } from "./index.js";
 export * from "./schema.js";
+export * from "./tool-versions-schema.js";
 /**
  * Enum of all tool names supported by the containerbase version this package
  * was released with.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@containerbase/base",
-  "version": "14.41.1",
+  "version": "14.43.0",
   "description": "Metadata about the tools supported by containerbase",
   "keywords": [
     "containerbase",