@autifyhq/aximo-cli 0.10.1 → 0.11.1

package/dist/desktop-server/agent-sync.d.ts

@@ -3,17 +3,37 @@ export interface AgentAssetInfo {
     sha256: string;
     size: number;
 }
+export interface BundleFileInfo extends AgentAssetInfo {
+    /** Path under /api/devices/agent/bundle/ that serves this file. */
+    path: string;
+}
+export interface BundlePythonInfo extends BundleFileInfo {
+    /** python-build-standalone archive filename, which encodes version + target. */
+    archive: string;
+}
 export interface AgentManifest {
-    manifestVersion: 2;
+    /**
+     * The offline setup fields below are optional additive fields on v2 — the
+     * server does not bump the version for them, because every published CLI
+     * rejects a version it does not recognise. Never gate the offline path on
+     * this number; gate it on whether those fields are present.
+     */
+    manifestVersion: 2 | 3;
     version: string;
+    minCliVersion?: string;
     script: AgentAssetInfo;
     requirements: AgentAssetInfo;
+    /** Offline setup assets, keyed by `${platform}-${arch}`. Absent = use GitHub/PyPI. */
+    python?: Record<string, BundlePythonInfo>;
+    wheels?: Record<string, BundleFileInfo[]>;
 }
 export interface EnsureAgentResult {
     scriptPath: string;
     requirementsPath: string;
     changed: boolean;
     version: string;
+    /** The server's manifest, so callers can see what it offers. */
+    manifest: AgentManifest;
 }
 export declare function ensureAgent(deps?: ClientDeps): Promise<EnsureAgentResult>;
 export declare function readCachedManifest(): AgentManifest | null;

package/dist/desktop-server/agent-sync.js

@@ -18,7 +18,7 @@ function readLocalManifest() {
         if (!parsed || typeof parsed !== "object")
             return null;
         const manifest = parsed;
-        if (manifest.manifestVersion === 2 &&
+        if ((manifest.manifestVersion === 2 || manifest.manifestVersion === 3) &&
             typeof manifest.version === "string" &&
             manifest.script?.sha256 &&
             manifest.requirements?.sha256) {
@@ -58,7 +58,9 @@ function validateManifest(raw) {
         throw new Error("Invalid agent manifest: response is not an object");
     }
     const m = raw;
-    if (m.manifestVersion !== 2) {
+    // v2 servers predate the offline assets; accept them so a newer CLI still
+    // works against an on-prem server that hasn't been upgraded yet.
+    if (m.manifestVersion !== 2 && m.manifestVersion !== 3) {
         throw new Error(`Unsupported agent manifest version: ${m.manifestVersion}. Update aximo-cli to the latest version.`);
     }
     if (typeof m.version !== "string" ||
@@ -111,6 +113,7 @@ export async function ensureAgent(deps) {
             requirementsPath: getAgentRequirementsPath(),
             changed: false,
             version: server.version,
+            manifest: server,
         };
     }
     const [scriptBuffer, requirementsBuffer] = await Promise.all([
@@ -134,6 +137,7 @@ export async function ensureAgent(deps) {
         requirementsPath: getAgentRequirementsPath(),
         changed: true,
         version: server.version,
+        manifest: server,
     };
 }
 export function readCachedManifest() {

package/dist/desktop-server/bundle-sync.d.ts

@@ -0,0 +1,25 @@
+import { type ClientDeps } from "../client.js";
+import type { AgentManifest, BundlePythonInfo } from "./agent-sync.js";
+/** Key the manifest uses for per-platform assets, e.g. win32-x64. */
+export declare function platformKey(): string;
+/**
+ * The server's Python archive for this platform, when it matches what this CLI
+ * expects.
+ *
+ * An archive name encodes the interpreter version and target, so comparing it to
+ * the name the CLI would have downloaded is the version check: a server offering
+ * a different interpreter than this CLI is pinned to is ignored rather than
+ * installed, because the CLI's compiled-in SHA256 would reject it anyway.
+ */
+export declare function resolveServerPython(manifest: AgentManifest, expectedArchive: string): BundlePythonInfo | undefined;
+/** Download the server's Python archive into the cache and verify it. */
+export declare function downloadServerPython(info: BundlePythonInfo, deps?: ClientDeps): Promise<string>;
+/**
+ * Mirror the server's wheels for this platform into the cache.
+ *
+ * Returns the directory to point pip at, or undefined when the server offers no
+ * wheels for this platform. Files the manifest no longer lists are removed:
+ * a leftover wheel from an older release could otherwise satisfy a requirement
+ * with the wrong version.
+ */
+export declare function ensureServerWheels(manifest: AgentManifest, deps?: ClientDeps): Promise<string | undefined>;

package/dist/desktop-server/bundle-sync.js

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { arch as osArch, platform } from "node:os";
+import { basename, join } from "node:path";
+import { requestBuffer, requestToFile } from "../client.js";
+import { getCacheDir } from "../commands/device/paths.js";
+/**
+ * Fetch the on-prem CLI bundle assets from the Aximo server.
+ *
+ * An air-gapped device cannot reach GitHub or PyPI, but it can always reach the
+ * server — registering and running a test go through it. When the server's
+ * manifest advertises an embedded Python archive and wheels for this platform,
+ * setup takes them from there instead.
+ */
+const BUNDLE_BASE_PATH = "/api/devices/agent/bundle";
+/** Key the manifest uses for per-platform assets, e.g. win32-x64. */
+export function platformKey() {
+    return `${platform()}-${osArch()}`;
+}
+function bundlePath(info) {
+    return `${BUNDLE_BASE_PATH}/${info.path}`;
+}
+function hashFile(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function fileMatches(path, expected) {
+    if (!existsSync(path))
+        return false;
+    return statSync(path).size === expected.size && hashFile(path) === expected.sha256;
+}
+/**
+ * The server's Python archive for this platform, when it matches what this CLI
+ * expects.
+ *
+ * An archive name encodes the interpreter version and target, so comparing it to
+ * the name the CLI would have downloaded is the version check: a server offering
+ * a different interpreter than this CLI is pinned to is ignored rather than
+ * installed, because the CLI's compiled-in SHA256 would reject it anyway.
+ */
+export function resolveServerPython(manifest, expectedArchive) {
+    const info = manifest.python?.[platformKey()];
+    if (!info)
+        return undefined;
+    if (info.archive === expectedArchive)
+        return info;
+    // Say so rather than falling through quietly: air-gapped, the fallback is a
+    // GitHub download that cannot succeed, and the resulting network error would
+    // give no hint that the real problem is a version mismatch.
+    console.error(`[aximo] The Aximo server offers ${info.archive}, but this CLI is pinned to ` +
+        `${expectedArchive}. Ignoring the server's interpreter — install the aximo-cli ` +
+        "that ships with your current Aximo release.");
+    return undefined;
+}
+/** Download the server's Python archive into the cache and verify it. */
+export async function downloadServerPython(info, deps = {}) {
+    const cacheDir = getCacheDir();
+    mkdirSync(cacheDir, { recursive: true });
+    const dest = join(cacheDir, info.archive);
+    if (fileMatches(dest, info))
+        return dest;
+    console.log(`Fetching embedded Python from the Aximo server (${info.archive})...`);
+    await requestToFile(bundlePath(info), dest, deps);
+    // Size first: the download streams straight to its final path, so an interrupted
+    // transfer leaves a short file. Checking length separately keeps that from being
+    // reported as the server serving the wrong bytes.
+    const size = statSync(dest).size;
+    if (size !== info.size) {
+        rmSync(dest, { force: true });
+        throw new Error(`Incomplete download of ${info.path}: expected ${info.size} bytes, got ${size}. ` +
+            "Re-run `aximo device setup` to retry.");
+    }
+    const actual = hashFile(dest);
+    if (actual !== info.sha256) {
+        rmSync(dest, { force: true });
+        throw new Error(`SHA256 mismatch for ${info.path} served by the Aximo server\n` +
+            `  expected ${info.sha256}\n  actual   ${actual}`);
+    }
+    return dest;
+}
+/**
+ * Mirror the server's wheels for this platform into the cache.
+ *
+ * Returns the directory to point pip at, or undefined when the server offers no
+ * wheels for this platform. Files the manifest no longer lists are removed:
+ * a leftover wheel from an older release could otherwise satisfy a requirement
+ * with the wrong version.
+ */
+export async function ensureServerWheels(manifest, deps = {}) {
+    const wheels = manifest.wheels?.[platformKey()];
+    if (!wheels || wheels.length === 0)
+        return undefined;
+    const dir = join(getCacheDir(), "wheels", platformKey());
+    mkdirSync(dir, { recursive: true });
+    // basename from node:path, not a hand-rolled split: on Windows it also strips
+    // backslash segments, so a manifest path cannot walk out of the cache dir.
+    const expected = new Map();
+    for (const wheel of wheels) {
+        const name = basename(wheel.path);
+        if (!name.endsWith(".whl") || name.includes("/") || name.includes("\\")) {
+            throw new Error(`Refusing to write wheel with unexpected filename: ${wheel.path}`);
+        }
+        expected.set(name, wheel);
+    }
+    for (const name of readdirSync(dir)) {
+        if (!expected.has(name))
+            rmSync(join(dir, name), { recursive: true, force: true });
+    }
+    let fetched = 0;
+    for (const [name, wheel] of expected) {
+        const dest = join(dir, name);
+        if (fileMatches(dest, wheel))
+            continue;
+        const buffer = await requestBuffer(bundlePath(wheel), deps);
+        if (buffer.byteLength !== wheel.size) {
+            throw new Error(`Wheel ${wheel.path} size mismatch: expected ${wheel.size} bytes, got ${buffer.byteLength}`);
+        }
+        const actual = createHash("sha256").update(buffer).digest("hex");
+        if (actual !== wheel.sha256) {
+            throw new Error(`Wheel ${wheel.path} sha256 mismatch: expected ${wheel.sha256}, got ${actual}`);
+        }
+        writeFileSync(dest, buffer, { mode: 0o644 });
+        fetched++;
+    }
+    if (fetched > 0) {
+        console.log(`Fetched ${fetched} Python package(s) from the Aximo server.`);
+    }
+    return dir;
+}

package/dist/desktop-server/bundle-sync.test.d.ts

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

package/dist/desktop-server/bundle-sync.test.js

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { getCacheDir } from "../commands/device/paths.js";
+import { http, HttpResponse, server, TEST_BASE_URL } from "../test-utils.js";
+import { downloadServerPython, ensureServerWheels, platformKey, resolveServerPython, } from "./bundle-sync.js";
+let tempHome;
+const ARCHIVE = "cpython-3.12.13+20260414-x86_64-pc-windows-msvc-install_only.tar.gz";
+const ARCHIVE_BODY = "fake-python-archive";
+const WHEEL_BODY = "fake-wheel-bytes";
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/** Manifest advertising a payload for whatever platform the test runs on. */
+function manifestWithPayload(overrides = {}) {
+    const platform = overrides.platform ?? platformKey();
+    const archive = overrides.archive ?? ARCHIVE;
+    const wheelNames = overrides.wheels ?? ["mss-10.0.0-py3-none-any.whl"];
+    return {
+        manifestVersion: 2,
+        version: "abcd1234",
+        script: { sha256: sha256("s"), size: 1 },
+        requirements: { sha256: sha256("r"), size: 1 },
+        python: {
+            [platform]: {
+                archive,
+                path: `python/${platform}/${archive}`,
+                sha256: sha256(ARCHIVE_BODY),
+                size: Buffer.byteLength(ARCHIVE_BODY),
+            },
+        },
+        wheels: {
+            [platform]: wheelNames.map((name) => ({
+                path: `wheels/${platform}/${name}`,
+                sha256: sha256(WHEEL_BODY),
+                size: Buffer.byteLength(WHEEL_BODY),
+            })),
+        },
+    };
+}
+function mockPayloadEndpoints(body = ARCHIVE_BODY, wheelBody = WHEEL_BODY) {
+    server.use(http.get(`${TEST_BASE_URL}/api/devices/agent/bundle/python/*`, () => new HttpResponse(body)), http.get(`${TEST_BASE_URL}/api/devices/agent/bundle/wheels/*`, () => new HttpResponse(wheelBody)));
+}
+beforeAll(() => server.listen());
+afterAll(() => server.close());
+beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-payload-"));
+    process.env["AXIMO_HOME"] = tempHome;
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    server.resetHandlers();
+    delete process.env["AXIMO_HOME"];
+    rmSync(tempHome, { recursive: true, force: true });
+});
+describe("resolveServerPython", () => {
+    it("returns the entry when the served archive is the one this CLI expects", () => {
+        expect(resolveServerPython(manifestWithPayload(), ARCHIVE)?.archive).toBe(ARCHIVE);
+    });
+    it("ignores an archive for a different interpreter version", () => {
+        vi.spyOn(console, "error").mockImplementation(() => { });
+        const manifest = manifestWithPayload({
+            archive: "cpython-3.13.0+20260414-x86_64-pc-windows-msvc-install_only.tar.gz",
+        });
+        expect(resolveServerPython(manifest, ARCHIVE)).toBeUndefined();
+    });
+    it("says why it ignored a mismatched interpreter, since the fallback cannot work offline", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        const manifest = manifestWithPayload({
+            archive: "cpython-3.13.0+20260414-x86_64-pc-windows-msvc-install_only.tar.gz",
+        });
+        resolveServerPython(manifest, ARCHIVE);
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining("pinned to"));
+    });
+    it("stays quiet when the platform simply is not offered", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        resolveServerPython(manifestWithPayload({ platform: "sunos-sparc" }), ARCHIVE);
+        expect(spy).not.toHaveBeenCalled();
+    });
+    it("ignores a payload that has nothing for this platform", () => {
+        const manifest = manifestWithPayload({ platform: "sunos-sparc" });
+        expect(resolveServerPython(manifest, ARCHIVE)).toBeUndefined();
+    });
+    it("reads the payload from a v2 manifest — the shape production actually ships", () => {
+        // The server never bumps the version for additive fields, so v2-with-payload is
+        // the real-world case. Keep one v3 test for forward tolerance.
+        const manifest = manifestWithPayload();
+        expect(manifest.manifestVersion).toBe(2);
+        expect(resolveServerPython(manifest, ARCHIVE)?.archive).toBe(ARCHIVE);
+    });
+    it("still tolerates a v3 manifest, so a later bump needs no lockstep release", () => {
+        const manifest = { ...manifestWithPayload(), manifestVersion: 3 };
+        expect(resolveServerPython(manifest, ARCHIVE)?.archive).toBe(ARCHIVE);
+    });
+    it("treats a manifest with no payload fields as offering nothing", () => {
+        const manifest = {
+            manifestVersion: 2,
+            version: "abcd1234",
+            script: { sha256: sha256("s"), size: 1 },
+            requirements: { sha256: sha256("r"), size: 1 },
+        };
+        expect(resolveServerPython(manifest, ARCHIVE)).toBeUndefined();
+    });
+});
+describe("downloadServerPython", () => {
+    it("streams the archive into the cache", async () => {
+        mockPayloadEndpoints();
+        const info = manifestWithPayload().python?.[platformKey()];
+        const path = await downloadServerPython(info, { baseUrl: TEST_BASE_URL, apiKey: "k" });
+        expect(readFileSync(path, "utf-8")).toBe(ARCHIVE_BODY);
+        expect(path).toBe(join(getCacheDir(), ARCHIVE));
+    });
+    it("reports an interrupted transfer as such, not as the server serving bad bytes", async () => {
+        mockPayloadEndpoints("short");
+        const info = manifestWithPayload().python?.[platformKey()];
+        await expect(downloadServerPython(info, { baseUrl: TEST_BASE_URL, apiKey: "k" })).rejects.toThrow(/Incomplete download/);
+        expect(existsSync(join(getCacheDir(), ARCHIVE))).toBe(false);
+    });
+    it("rejects and deletes an archive whose checksum does not match", async () => {
+        // Same length as ARCHIVE_BODY so the checksum is what rejects it, not the size.
+        const tampered = "fake-python-ARCHIVE";
+        expect(tampered).toHaveLength(ARCHIVE_BODY.length);
+        mockPayloadEndpoints(tampered);
+        const info = manifestWithPayload().python?.[platformKey()];
+        await expect(downloadServerPython(info, { baseUrl: TEST_BASE_URL, apiKey: "k" })).rejects.toThrow(/SHA256 mismatch/);
+        expect(existsSync(join(getCacheDir(), ARCHIVE))).toBe(false);
+    });
+    it("reuses a cached archive instead of downloading again", async () => {
+        let hits = 0;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/agent/bundle/python/*`, () => {
+            hits++;
+            return new HttpResponse(ARCHIVE_BODY);
+        }));
+        const info = manifestWithPayload().python?.[platformKey()];
+        const deps = { baseUrl: TEST_BASE_URL, apiKey: "k" };
+        await downloadServerPython(info, deps);
+        await downloadServerPython(info, deps);
+        expect(hits).toBe(1);
+    });
+});
+describe("ensureServerWheels", () => {
+    it("mirrors the served wheels and returns the directory to point pip at", async () => {
+        mockPayloadEndpoints();
+        const dir = await ensureServerWheels(manifestWithPayload(), {
+            baseUrl: TEST_BASE_URL,
+            apiKey: "k",
+        });
+        expect(dir).toBe(join(getCacheDir(), "wheels", platformKey()));
+        expect(readFileSync(join(dir, "mss-10.0.0-py3-none-any.whl"), "utf-8")).toBe(WHEEL_BODY);
+    });
+    it("is undefined when the server offers no wheels for this platform", async () => {
+        const manifest = manifestWithPayload({ platform: "sunos-sparc" });
+        expect(await ensureServerWheels(manifest, { baseUrl: TEST_BASE_URL, apiKey: "k" })).toBe(undefined);
+    });
+    it("removes a wheel the manifest no longer lists", async () => {
+        mockPayloadEndpoints();
+        const dir = join(getCacheDir(), "wheels", platformKey());
+        mkdirSync(dir, { recursive: true });
+        const stale = join(dir, "Pillow-1.0.0-cp312-cp312-win_amd64.whl");
+        writeFileSync(stale, "old");
+        await ensureServerWheels(manifestWithPayload(), { baseUrl: TEST_BASE_URL, apiKey: "k" });
+        // A leftover wheel could satisfy a requirement with the wrong version.
+        expect(existsSync(stale)).toBe(false);
+    });
+    it("rejects a wheel whose checksum does not match", async () => {
+        // Same length as WHEEL_BODY, so the checksum is what rejects it.
+        const tampered = "fake-wheel-BYTES";
+        expect(tampered).toHaveLength(WHEEL_BODY.length);
+        mockPayloadEndpoints(ARCHIVE_BODY, tampered);
+        await expect(ensureServerWheels(manifestWithPayload(), { baseUrl: TEST_BASE_URL, apiKey: "k" })).rejects.toThrow(/sha256 mismatch/);
+    });
+    it("rejects a wheel whose length does not match", async () => {
+        mockPayloadEndpoints(ARCHIVE_BODY, "short");
+        await expect(ensureServerWheels(manifestWithPayload(), { baseUrl: TEST_BASE_URL, apiKey: "k" })).rejects.toThrow(/size mismatch/);
+    });
+    it("does not re-download wheels already present and matching", async () => {
+        let hits = 0;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/agent/bundle/wheels/*`, () => {
+            hits++;
+            return new HttpResponse(WHEEL_BODY);
+        }));
+        const deps = { baseUrl: TEST_BASE_URL, apiKey: "k" };
+        await ensureServerWheels(manifestWithPayload(), deps);
+        await ensureServerWheels(manifestWithPayload(), deps);
+        expect(hits).toBe(1);
+    });
+});

package/dist/desktop-server/cli-version.d.ts

@@ -0,0 +1,21 @@
+import type { AgentManifest } from "./agent-sync.js";
+/**
+ * Compare two dotted numeric versions.
+ *
+ * Returns a negative number when a < b, zero when equal, positive when a > b.
+ * Prerelease suffixes are ignored: `0.11.0-rc.1` compares as `0.11.0`, which is
+ * deliberate — a release candidate of the required version is close enough that
+ * warning about it would be noise.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** True when this CLI is older than the server's stated minimum. */
+export declare function isCliOutdated(minCliVersion: string | undefined, current?: string): boolean;
+/**
+ * Warn when the server expects a newer CLI than this one.
+ *
+ * A warning rather than a hard failure: an on-prem server can be upgraded before
+ * every device is, and blocking setup would strand machines that were working a
+ * moment earlier. The message matters most air-gapped, where the CLI is carried
+ * in by hand and drifting behind the server is easy to do by accident.
+ */
+export declare function warnIfCliOutdated(manifest: AgentManifest): void;

package/dist/desktop-server/cli-version.js

@@ -0,0 +1,41 @@
+import pkg from "../../package.json" with { type: "json" };
+/**
+ * Compare two dotted numeric versions.
+ *
+ * Returns a negative number when a < b, zero when equal, positive when a > b.
+ * Prerelease suffixes are ignored: `0.11.0-rc.1` compares as `0.11.0`, which is
+ * deliberate — a release candidate of the required version is close enough that
+ * warning about it would be noise.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => (v.split("-")[0] ?? "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/** True when this CLI is older than the server's stated minimum. */
+export function isCliOutdated(minCliVersion, current = pkg.version) {
+    if (!minCliVersion)
+        return false;
+    return compareVersions(current, minCliVersion) < 0;
+}
+/**
+ * Warn when the server expects a newer CLI than this one.
+ *
+ * A warning rather than a hard failure: an on-prem server can be upgraded before
+ * every device is, and blocking setup would strand machines that were working a
+ * moment earlier. The message matters most air-gapped, where the CLI is carried
+ * in by hand and drifting behind the server is easy to do by accident.
+ */
+export function warnIfCliOutdated(manifest) {
+    if (!isCliOutdated(manifest.minCliVersion))
+        return;
+    console.error(`[aximo] This CLI is ${pkg.version}, but the Aximo server expects ` +
+        `${manifest.minCliVersion} or newer. Device setup may fail or behave unexpectedly — ` +
+        "install the aximo-cli that ships with your current Aximo release.");
+}

package/dist/desktop-server/cli-version.test.d.ts

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

package/dist/desktop-server/cli-version.test.js

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { compareVersions, isCliOutdated, warnIfCliOutdated } from "./cli-version.js";
+function manifest(minCliVersion) {
+    return {
+        manifestVersion: 3,
+        version: "abcd1234",
+        ...(minCliVersion ? { minCliVersion } : {}),
+        script: { sha256: "a".repeat(64), size: 1 },
+        requirements: { sha256: "b".repeat(64), size: 1 },
+    };
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("compareVersions", () => {
+    it("orders by each numeric component", () => {
+        expect(compareVersions("0.10.0", "0.11.0")).toBeLessThan(0);
+        expect(compareVersions("0.11.0", "0.10.0")).toBeGreaterThan(0);
+        expect(compareVersions("1.0.0", "0.99.99")).toBeGreaterThan(0);
+        expect(compareVersions("0.11.0", "0.11.0")).toBe(0);
+    });
+    it("compares numerically rather than lexically", () => {
+        expect(compareVersions("0.9.0", "0.10.0")).toBeLessThan(0);
+    });
+    it("treats missing components as zero", () => {
+        expect(compareVersions("1", "1.0.0")).toBe(0);
+        expect(compareVersions("1.2", "1.2.1")).toBeLessThan(0);
+    });
+    it("ignores a prerelease suffix", () => {
+        expect(compareVersions("0.11.0-rc.1", "0.11.0")).toBe(0);
+    });
+});
+describe("isCliOutdated", () => {
+    it("is false when the server states no minimum", () => {
+        expect(isCliOutdated(undefined, "0.1.0")).toBe(false);
+    });
+    it("is true only when this CLI is behind", () => {
+        expect(isCliOutdated("0.11.0", "0.10.0")).toBe(true);
+        expect(isCliOutdated("0.11.0", "0.11.0")).toBe(false);
+        expect(isCliOutdated("0.11.0", "0.12.0")).toBe(false);
+    });
+});
+describe("warnIfCliOutdated", () => {
+    it("stays quiet when the server states no minimum", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        warnIfCliOutdated(manifest());
+        expect(spy).not.toHaveBeenCalled();
+    });
+    it("names the version to install when the CLI is behind", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        warnIfCliOutdated(manifest("999.0.0"));
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining("999.0.0"));
+    });
+    it("warns rather than throwing, so an upgraded server never strands a device", () => {
+        vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(() => warnIfCliOutdated(manifest("999.0.0"))).not.toThrow();
+    });
+});

package/dist/desktop-server/offline.d.ts

@@ -0,0 +1,6 @@
+/** Configured offline asset directory, or undefined when unset/blank. */
+export declare function getOfflineDir(): string | undefined;
+/** Path to the staged Python archive, or undefined when it isn't present. */
+export declare function findOfflinePythonArchive(archiveName: string): string | undefined;
+/** Path to the staged wheel directory, or undefined when it isn't present. */
+export declare function findOfflineWheelsDir(): string | undefined;

package/dist/desktop-server/offline.js

@@ -0,0 +1,44 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Locally staged setup assets.
+ *
+ * On an air-gapped network `aximo device setup` cannot reach GitHub or PyPI, so
+ * the embedded Python archive and the agent's wheels have to come from
+ * somewhere on disk. AXIMO_OFFLINE_DIR points at a directory holding them:
+ *
+ *   <dir>/cpython-<version>+<release>-<target>-install_only.tar.gz
+ *   <dir>/wheels/*.whl
+ *
+ * An on-prem server can serve the same assets (see agent-sync), in which case
+ * the CLI downloads into its own cache and no env var is needed. This module is
+ * only about files a human placed on the machine.
+ */
+const OFFLINE_DIR_ENV = "AXIMO_OFFLINE_DIR";
+/** Configured offline asset directory, or undefined when unset/blank. */
+export function getOfflineDir() {
+    const raw = process.env[OFFLINE_DIR_ENV];
+    if (!raw || raw.trim() === "")
+        return undefined;
+    const dir = raw.trim();
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        throw new Error(`${OFFLINE_DIR_ENV} is set to ${dir}, which is not a directory.`);
+    }
+    return dir;
+}
+/** Path to the staged Python archive, or undefined when it isn't present. */
+export function findOfflinePythonArchive(archiveName) {
+    const dir = getOfflineDir();
+    if (!dir)
+        return undefined;
+    const path = join(dir, archiveName);
+    return existsSync(path) ? path : undefined;
+}
+/** Path to the staged wheel directory, or undefined when it isn't present. */
+export function findOfflineWheelsDir() {
+    const dir = getOfflineDir();
+    if (!dir)
+        return undefined;
+    const wheels = join(dir, "wheels");
+    return existsSync(wheels) && statSync(wheels).isDirectory() ? wheels : undefined;
+}

package/dist/desktop-server/offline.test.d.ts

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