@containerbase/base 14.45.0 → 14.46.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/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,74 @@
+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) {
+    const imageVersion = (await readFile(file, 'utf8')).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/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.46.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": {