@containerbase/base 14.45.0 → 14.47.0

package/README.md

@@ -33,7 +33,7 @@ The raw data and its json schema are also exported, for consumers which don't us
 import tools from '@containerbase/base/tools.json' with { type: 'json' };
 ```
 
-The zod schemas live behind a separate entry point, so the default export stays dependency free:
+The zod schemas live behind a separate entry point, so the default export only depends on `semver`:
 
 ```ts
 import { SupportedTools, ToolName } from '@containerbase/base/zod';
@@ -74,6 +74,38 @@ isToolVersionsFormat(
 ); // false
 ```
 
+The containerbase image embeds the tool-versions data, a reader running in the image can use it when the site can't be reached:
+
+```ts
+import {
+  isContainerbase,
+  toolVersionsFormatPath,
+  toolVersionsPath,
+} from '@containerbase/base';
+
+if (isContainerbase()) {
+  // eg. '/usr/local/containerbase/tool-versions/v1/node.json'
+  const file = `${toolVersionsPath}/${toolVersionsFormatPath}/node.json`;
+}
+```
+
+`isContainerbase()` checks the `CONTAINERBASE` variable the image sets, pass another environment to check that one instead of `process.env`.
+
+`validateContainerbaseVersion()` reads the version of the image from `/usr/local/containerbase/version` (`containerbaseVersionFile`) and throws when the image doesn't support everything this package describes: it needs the same major version as this package and the same or a newer minor or patch version.
+Development images, whose version is a git sha or `0.0.0-…`, aren't checked; a missing or empty version file throws.
+Call it on startup when `isContainerbase()` is true; `isCompatibleVersion(imageVersion)` does the comparison without reading the file, and `packageVersion` is the version it compares with:
+
+```ts
+import {
+  isContainerbase,
+  validateContainerbaseVersion,
+} from '@containerbase/base';
+
+if (isContainerbase()) {
+  await validateContainerbaseVersion(); // eg. '14.2.0', or throws
+}
+```
+
 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

package/data/tools.json

@@ -1,28 +1,28 @@
 {
   "tools": {
-    "android-sdk-cmdline-tools": { "parent": "java" },
-    "apko": {},
-    "apm": {},
-    "bazelisk": {},
+    "android-sdk-cmdline-tools": { "parent": "java", "minVersion": "1" },
+    "apko": { "minVersion": "0.1.1" },
+    "apm": { "minVersion": "0.4.0" },
+    "bazelisk": { "minVersion": "0.0.1" },
     "bower": { "type": "npm", "parent": "node", "deprecated": true },
-    "buf": {},
-    "buildx": { "parent": "docker" },
+    "buf": { "minVersion": "0.1.0" },
+    "buildx": { "parent": "docker", "minVersion": "0.2.0" },
     "bun": { "minVersion": "0.5.3" },
     "bundler": { "type": "gem", "parent": "ruby" },
     "cabal": { "minVersion": "3.4.1.0" },
     "checkov": { "type": "pip", "parent": "python" },
     "cocoapods": { "type": "gem", "parent": "ruby" },
-    "composer": { "parent": "php" },
+    "composer": { "parent": "php", "minVersion": "1.0.0" },
     "conan": { "type": "pip", "parent": "python" },
     "copier": { "type": "pip", "parent": "python" },
     "corepack": { "type": "npm", "parent": "node" },
     "dart": { "minVersion": "2.0.0" },
     "deno": { "minVersion": "2.0.1" },
-    "devbox": {},
+    "devbox": { "minVersion": "0.0.6" },
     "docker": { "minVersion": "20.10.0" },
     "docker-compose": { "parent": "docker", "minVersion": "2.0.1" },
     "dotnet": { "minVersion": "6.0.100" },
-    "elixir": { "parent": "erlang" },
+    "elixir": { "parent": "erlang", "minVersion": "1.4.3" },
     "erlang": { "minVersion": "24.2.0.0" },
     "flutter": { "minVersion": "1.22.6" },
     "flux": { "minVersion": "0.6.0" },
@@ -31,28 +31,28 @@
     "git": { "root": true, "minVersion": "2.48.0" },
     "git-lfs": { "parent": "git", "minVersion": "2.6.0" },
     "gleam": { "minVersion": "0.23.0" },
-    "golang": {},
-    "gradle": { "parent": "java" },
+    "golang": { "minVersion": "1.9.0" },
+    "gradle": { "parent": "java", "minVersion": "1.0" },
     "hashin": { "type": "pip", "parent": "python" },
     "helm": { "minVersion": "3.1.0" },
-    "helmfile": {},
+    "helmfile": { "minVersion": "0.145.0" },
     "java": { "minVersion": "8.0.302+8" },
     "java-jdk": { "minVersion": "8.0.302+8" },
     "java-jre": { "minVersion": "8.0.302+8" },
-    "jb": {},
+    "jb": { "minVersion": "0.2.0" },
     "jq": { "minVersion": "1.7.1" },
     "kas": { "type": "pip", "parent": "python" },
     "kubectl": { "minVersion": "1.13.11" },
     "kustomize": { "minVersion": "3.3.0" },
     "lerna": { "type": "npm", "parent": "node", "deprecated": true },
-    "maven": { "parent": "java" },
+    "maven": { "parent": "java", "minVersion": "3.0.4" },
     "mise": { "minVersion": "2024.1.0" },
-    "mono": {},
+    "mono": { "minVersion": "6.14.1" },
     "nix": { "minVersion": "2.10.3" },
-    "node": {},
+    "node": { "minVersion": "8.7.0" },
     "npm": { "type": "npm", "parent": "node" },
-    "nub": {},
-    "nuget": { "parent": "mono" },
+    "nub": { "minVersion": "0.0.34" },
+    "nuget": { "parent": "mono", "minVersion": "3.4.4" },
     "paket": { "type": "dotnet", "parent": "dotnet" },
     "pdm": { "type": "pip", "parent": "python" },
     "php": {
@@ -69,21 +69,21 @@
     "python": { "minVersion": "2.7.18" },
     "renovate": { "type": "npm", "parent": "node" },
     "ruby": { "minVersion": "2.7.7" },
-    "rust": {},
+    "rust": { "minVersion": "1.7.0" },
     "sbt": { "parent": "java", "minVersion": "0.13.17" },
-    "scala": { "parent": "java" },
+    "scala": { "parent": "java", "minVersion": "2.11.2" },
     "skopeo": { "minVersion": "1.14.0" },
     "sops": { "minVersion": "3.8.0" },
     "swift": {
       "minVersion": "5.7",
       "distroMinVersion": { "resolute": "6.4.0" }
     },
-    "terraform": {},
+    "terraform": { "minVersion": "0.1.0" },
     "tofu": { "minVersion": "1.6.3" },
     "uv": { "type": "pip", "parent": "python" },
-    "vendir": {},
+    "vendir": { "minVersion": "0.4.0" },
     "vp": { "parent": "node", "minVersion": "0.3.1" },
-    "wally": {},
+    "wally": { "minVersion": "0.3.0" },
     "yarn": { "type": "npm", "parent": "node" },
     "yarn-slim": { "type": "npm", "parent": "node" }
   }

package/dist/containerbase.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the containerbase image embeds the tool-versions data: the extracted
+ * release archive, with the root `index.json` and one folder per format, eg.
+ * `v1/<tool>.json`.
+ */
+export declare const toolVersionsPath = "/usr/local/containerbase/tool-versions";
+/**
+ * The file in which the containerbase image records its version.
+ */
+export declare const containerbaseVersionFile = "/usr/local/containerbase/version";
+/**
+ * The version of this package, which is released with the same version as
+ * containerbase itself.
+ */
+export declare const packageVersion: string;
+/**
+ * Checks if the process runs in a containerbase image, whose environment sets
+ * `CONTAINERBASE`.
+ *
+ * @param env the environment to check, `process.env` by default
+ */
+export declare function isContainerbase(env?: Record<string, string | undefined>): boolean;
+/**
+ * Checks if a containerbase image supports everything this package describes:
+ * the image has the same major version and the same or a newer minor or patch
+ * version.
+ *
+ * @param imageVersion the version of the image, eg. from
+ * `containerbaseVersionFile`
+ * @param version the version to compare with, this package's by default
+ * @returns `false` for another major, an older image or a version which can't
+ * be parsed
+ */
+export declare function isCompatibleVersion(imageVersion: string, version?: string): boolean;
+/**
+ * Reads the version of the containerbase image and throws when it isn't
+ * compatible with this package, see `isCompatibleVersion`. Call it only when
+ * `isContainerbase()` is true.
+ *
+ * Development images, whose version is a git sha or `0.0.0-…`, aren't checked.
+ * A missing or empty version file still throws.
+ *
+ * @param file the version file to read, `containerbaseVersionFile` by default
+ * @returns the version of the image
+ */
+export declare function validateContainerbaseVersion(file?: string): Promise<string>;

package/dist/containerbase.js

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+// semver has no exports map, native ESM needs the file extension
+import semverGte from 'semver/functions/gte.js';
+import semverParse from 'semver/functions/parse.js';
+/**
+ * Where the containerbase image embeds the tool-versions data: the extracted
+ * release archive, with the root `index.json` and one folder per format, eg.
+ * `v1/<tool>.json`.
+ */
+export const toolVersionsPath = '/usr/local/containerbase/tool-versions';
+/**
+ * The file in which the containerbase image records its version.
+ */
+export const containerbaseVersionFile = '/usr/local/containerbase/version';
+/**
+ * The version of this package, which is released with the same version as
+ * containerbase itself.
+ */
+export const packageVersion = createRequire(import.meta.url)('../package.json').version;
+/**
+ * Checks if the process runs in a containerbase image, whose environment sets
+ * `CONTAINERBASE`.
+ *
+ * @param env the environment to check, `process.env` by default
+ */
+export function isContainerbase(env = process.env) {
+    return !!env.CONTAINERBASE;
+}
+/**
+ * Checks if a containerbase image supports everything this package describes:
+ * the image has the same major version and the same or a newer minor or patch
+ * version.
+ *
+ * @param imageVersion the version of the image, eg. from
+ * `containerbaseVersionFile`
+ * @param version the version to compare with, this package's by default
+ * @returns `false` for another major, an older image or a version which can't
+ * be parsed
+ */
+export function isCompatibleVersion(imageVersion, version = packageVersion) {
+    const image = semverParse(imageVersion.trim());
+    const pkg = semverParse(version);
+    return !!image && !!pkg && image.major === pkg.major && semverGte(image, pkg);
+}
+/**
+ * Checks if an image version comes from a release. Development builds write
+ * the git sha or `0.0.0-PLACEHOLDER` instead.
+ */
+function isReleaseVersion(imageVersion) {
+    const image = semverParse(imageVersion);
+    return (!!image && !(image.major === 0 && image.minor === 0 && image.patch === 0));
+}
+/**
+ * Reads the version of the containerbase image and throws when it isn't
+ * compatible with this package, see `isCompatibleVersion`. Call it only when
+ * `isContainerbase()` is true.
+ *
+ * Development images, whose version is a git sha or `0.0.0-…`, aren't checked.
+ * A missing or empty version file still throws.
+ *
+ * @param file the version file to read, `containerbaseVersionFile` by default
+ * @returns the version of the image
+ */
+export async function validateContainerbaseVersion(file = containerbaseVersionFile) {
+    let content;
+    try {
+        content = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        const { code, message } = err;
+        throw new Error(code === 'ENOENT'
+            ? `The containerbase image version file ${file} is missing`
+            : `The containerbase image version file ${file} can't be read: ${message}`, { cause: err });
+    }
+    const imageVersion = content.trim();
+    if (!imageVersion) {
+        throw new Error(`The containerbase image version file ${file} is empty`);
+    }
+    if (isReleaseVersion(imageVersion) && !isCompatibleVersion(imageVersion)) {
+        throw new Error(`The containerbase image version ${imageVersion} is not compatible with @containerbase/base ${packageVersion}, it needs the same major version and the same or a newer minor or patch version`);
+    }
+    return imageVersion;
+}

package/dist/data.d.ts

@@ -4,18 +4,28 @@
 export declare const tools: {
     readonly 'android-sdk-cmdline-tools': {
         readonly parent: "java";
+        readonly minVersion: "1";
+    };
+    readonly apko: {
+        readonly minVersion: "0.1.1";
+    };
+    readonly apm: {
+        readonly minVersion: "0.4.0";
+    };
+    readonly bazelisk: {
+        readonly minVersion: "0.0.1";
     };
-    readonly apko: {};
-    readonly apm: {};
-    readonly bazelisk: {};
     readonly bower: {
         readonly type: "npm";
         readonly parent: "node";
         readonly deprecated: true;
     };
-    readonly buf: {};
+    readonly buf: {
+        readonly minVersion: "0.1.0";
+    };
     readonly buildx: {
         readonly parent: "docker";
+        readonly minVersion: "0.2.0";
     };
     readonly bun: {
         readonly minVersion: "0.5.3";
@@ -37,6 +47,7 @@ export declare const tools: {
     };
     readonly composer: {
         readonly parent: "php";
+        readonly minVersion: "1.0.0";
     };
     readonly conan: {
         readonly type: "pip";
@@ -56,7 +67,9 @@ export declare const tools: {
     readonly deno: {
         readonly minVersion: "2.0.1";
     };
-    readonly devbox: {};
+    readonly devbox: {
+        readonly minVersion: "0.0.6";
+    };
     readonly docker: {
         readonly minVersion: "20.10.0";
     };
@@ -69,6 +82,7 @@ export declare const tools: {
     };
     readonly elixir: {
         readonly parent: "erlang";
+        readonly minVersion: "1.4.3";
     };
     readonly erlang: {
         readonly minVersion: "24.2.0.0";
@@ -96,9 +110,12 @@ export declare const tools: {
     readonly gleam: {
         readonly minVersion: "0.23.0";
     };
-    readonly golang: {};
+    readonly golang: {
+        readonly minVersion: "1.9.0";
+    };
     readonly gradle: {
         readonly parent: "java";
+        readonly minVersion: "1.0";
     };
     readonly hashin: {
         readonly type: "pip";
@@ -107,7 +124,9 @@ export declare const tools: {
     readonly helm: {
         readonly minVersion: "3.1.0";
     };
-    readonly helmfile: {};
+    readonly helmfile: {
+        readonly minVersion: "0.145.0";
+    };
     readonly java: {
         readonly minVersion: "8.0.302+8";
     };
@@ -117,7 +136,9 @@ export declare const tools: {
     readonly 'java-jre': {
         readonly minVersion: "8.0.302+8";
     };
-    readonly jb: {};
+    readonly jb: {
+        readonly minVersion: "0.2.0";
+    };
     readonly jq: {
         readonly minVersion: "1.7.1";
     };
@@ -138,22 +159,30 @@ export declare const tools: {
     };
     readonly maven: {
         readonly parent: "java";
+        readonly minVersion: "3.0.4";
     };
     readonly mise: {
         readonly minVersion: "2024.1.0";
     };
-    readonly mono: {};
+    readonly mono: {
+        readonly minVersion: "6.14.1";
+    };
     readonly nix: {
         readonly minVersion: "2.10.3";
     };
-    readonly node: {};
+    readonly node: {
+        readonly minVersion: "8.7.0";
+    };
     readonly npm: {
         readonly type: "npm";
         readonly parent: "node";
     };
-    readonly nub: {};
+    readonly nub: {
+        readonly minVersion: "0.0.34";
+    };
     readonly nuget: {
         readonly parent: "mono";
+        readonly minVersion: "3.4.4";
     };
     readonly paket: {
         readonly type: "dotnet";
@@ -204,13 +233,16 @@ export declare const tools: {
     readonly ruby: {
         readonly minVersion: "2.7.7";
     };
-    readonly rust: {};
+    readonly rust: {
+        readonly minVersion: "1.7.0";
+    };
     readonly sbt: {
         readonly parent: "java";
         readonly minVersion: "0.13.17";
     };
     readonly scala: {
         readonly parent: "java";
+        readonly minVersion: "2.11.2";
     };
     readonly skopeo: {
         readonly minVersion: "1.14.0";
@@ -224,7 +256,9 @@ export declare const tools: {
             readonly resolute: "6.4.0";
         };
     };
-    readonly terraform: {};
+    readonly terraform: {
+        readonly minVersion: "0.1.0";
+    };
     readonly tofu: {
         readonly minVersion: "1.6.3";
     };
@@ -232,12 +266,16 @@ export declare const tools: {
         readonly type: "pip";
         readonly parent: "python";
     };
-    readonly vendir: {};
+    readonly vendir: {
+        readonly minVersion: "0.4.0";
+    };
     readonly vp: {
         readonly parent: "node";
         readonly minVersion: "0.3.1";
     };
-    readonly wally: {};
+    readonly wally: {
+        readonly minVersion: "0.3.0";
+    };
     readonly yarn: {
         readonly type: "npm";
         readonly parent: "node";

package/dist/data.js

@@ -2,29 +2,29 @@
  * All tools `install-tool` supports, sorted by name.
  */
 export const tools = {
-    'android-sdk-cmdline-tools': { parent: 'java' },
-    apko: {},
-    apm: {},
-    bazelisk: {},
+    'android-sdk-cmdline-tools': { parent: 'java', minVersion: '1' },
+    apko: { minVersion: '0.1.1' },
+    apm: { minVersion: '0.4.0' },
+    bazelisk: { minVersion: '0.0.1' },
     bower: { type: 'npm', parent: 'node', deprecated: true },
-    buf: {},
-    buildx: { parent: 'docker' },
+    buf: { minVersion: '0.1.0' },
+    buildx: { parent: 'docker', minVersion: '0.2.0' },
     bun: { minVersion: '0.5.3' },
     bundler: { type: 'gem', parent: 'ruby' },
     cabal: { minVersion: '3.4.1.0' },
     checkov: { type: 'pip', parent: 'python' },
     cocoapods: { type: 'gem', parent: 'ruby' },
-    composer: { parent: 'php' },
+    composer: { parent: 'php', minVersion: '1.0.0' },
     conan: { type: 'pip', parent: 'python' },
     copier: { type: 'pip', parent: 'python' },
     corepack: { type: 'npm', parent: 'node' },
     dart: { minVersion: '2.0.0' },
     deno: { minVersion: '2.0.1' },
-    devbox: {},
+    devbox: { minVersion: '0.0.6' },
     docker: { minVersion: '20.10.0' },
     'docker-compose': { parent: 'docker', minVersion: '2.0.1' },
     dotnet: { minVersion: '6.0.100' },
-    elixir: { parent: 'erlang' },
+    elixir: { parent: 'erlang', minVersion: '1.4.3' },
     erlang: { minVersion: '24.2.0.0' },
     flutter: { minVersion: '1.22.6' },
     flux: { minVersion: '0.6.0' },
@@ -33,28 +33,28 @@ export const tools = {
     git: { root: true, minVersion: '2.48.0' },
     'git-lfs': { parent: 'git', minVersion: '2.6.0' },
     gleam: { minVersion: '0.23.0' },
-    golang: {},
-    gradle: { parent: 'java' },
+    golang: { minVersion: '1.9.0' },
+    gradle: { parent: 'java', minVersion: '1.0' },
     hashin: { type: 'pip', parent: 'python' },
     helm: { minVersion: '3.1.0' },
-    helmfile: {},
+    helmfile: { minVersion: '0.145.0' },
     java: { minVersion: '8.0.302+8' },
     'java-jdk': { minVersion: '8.0.302+8' },
     'java-jre': { minVersion: '8.0.302+8' },
-    jb: {},
+    jb: { minVersion: '0.2.0' },
     jq: { minVersion: '1.7.1' },
     kas: { type: 'pip', parent: 'python' },
     kubectl: { minVersion: '1.13.11' },
     kustomize: { minVersion: '3.3.0' },
     lerna: { type: 'npm', parent: 'node', deprecated: true },
-    maven: { parent: 'java' },
+    maven: { parent: 'java', minVersion: '3.0.4' },
     mise: { minVersion: '2024.1.0' },
-    mono: {},
+    mono: { minVersion: '6.14.1' },
     nix: { minVersion: '2.10.3' },
-    node: {},
+    node: { minVersion: '8.7.0' },
     npm: { type: 'npm', parent: 'node' },
-    nub: {},
-    nuget: { parent: 'mono' },
+    nub: { minVersion: '0.0.34' },
+    nuget: { parent: 'mono', minVersion: '3.4.4' },
     paket: { type: 'dotnet', parent: 'dotnet' },
     pdm: { type: 'pip', parent: 'python' },
     php: { minVersion: '7.4.0', distroMinVersion: { resolute: '8.1.31' } },
@@ -68,18 +68,18 @@ export const tools = {
     python: { minVersion: '2.7.18' },
     renovate: { type: 'npm', parent: 'node' },
     ruby: { minVersion: '2.7.7' },
-    rust: {},
+    rust: { minVersion: '1.7.0' },
     sbt: { parent: 'java', minVersion: '0.13.17' },
-    scala: { parent: 'java' },
+    scala: { parent: 'java', minVersion: '2.11.2' },
     skopeo: { minVersion: '1.14.0' },
     sops: { minVersion: '3.8.0' },
     swift: { minVersion: '5.7', distroMinVersion: { resolute: '6.4.0' } },
-    terraform: {},
+    terraform: { minVersion: '0.1.0' },
     tofu: { minVersion: '1.6.3' },
     uv: { type: 'pip', parent: 'python' },
-    vendir: {},
+    vendir: { minVersion: '0.4.0' },
     vp: { parent: 'node', minVersion: '0.3.1' },
-    wally: {},
+    wally: { minVersion: '0.3.0' },
     yarn: { type: 'npm', parent: 'node' },
     'yarn-slim': { type: 'npm', parent: 'node' },
 };

package/dist/index.d.ts

@@ -2,6 +2,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 { containerbaseVersionFile, isCompatibleVersion, isContainerbase, packageVersion, toolVersionsPath, validateContainerbaseVersion, } from './containerbase.ts';
 export { isToolVersionsFormat, toolVersionsFormat, toolVersionsFormatPath, } from './tool-versions-format.ts';
 export { tools };
 /**

package/dist/index.js

@@ -1,4 +1,5 @@
 import { tools } from "./data.js";
+export { containerbaseVersionFile, isCompatibleVersion, isContainerbase, packageVersion, toolVersionsPath, validateContainerbaseVersion, } from "./containerbase.js";
 export { isToolVersionsFormat, toolVersionsFormat, toolVersionsFormatPath, } from "./tool-versions-format.js";
 export { tools };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@containerbase/base",
-  "version": "14.45.0",
+  "version": "14.47.0",
   "description": "Metadata about the tools supported by containerbase",
   "keywords": [
     "containerbase",
@@ -31,7 +31,11 @@
     "data",
     "dist"
   ],
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
   "devDependencies": {
+    "@types/semver": "7.8.0",
     "zod": "4.6.7"
   },
   "peerDependencies": {