@autifyhq/aximo-cli 0.10.1 → 0.11.1

package/dist/desktop-server/offline.test.js

@@ -0,0 +1,74 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { findOfflinePythonArchive, findOfflineWheelsDir, getOfflineDir } from "./offline.js";
+let tempDir;
+let savedEnv;
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "aximo-offline-"));
+    savedEnv = process.env["AXIMO_OFFLINE_DIR"];
+    delete process.env["AXIMO_OFFLINE_DIR"];
+});
+afterEach(() => {
+    if (savedEnv === undefined)
+        delete process.env["AXIMO_OFFLINE_DIR"];
+    else
+        process.env["AXIMO_OFFLINE_DIR"] = savedEnv;
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe("getOfflineDir", () => {
+    it("returns undefined when unset", () => {
+        expect(getOfflineDir()).toBeUndefined();
+    });
+    it("treats a blank value as unset so it can force the online path", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = "   ";
+        expect(getOfflineDir()).toBeUndefined();
+    });
+    it("returns the configured directory", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = tempDir;
+        expect(getOfflineDir()).toBe(tempDir);
+    });
+    it("throws on a path that is not a directory rather than silently going online", () => {
+        const file = join(tempDir, "not-a-dir");
+        writeFileSync(file, "x");
+        process.env["AXIMO_OFFLINE_DIR"] = file;
+        expect(() => getOfflineDir()).toThrow(/not a directory/);
+    });
+    it("throws when the directory is missing", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = join(tempDir, "nope");
+        expect(() => getOfflineDir()).toThrow(/not a directory/);
+    });
+});
+describe("findOfflinePythonArchive", () => {
+    const archive = "cpython-3.12.13+20260414-x86_64-pc-windows-msvc-install_only.tar.gz";
+    it("returns undefined when no payload directory is configured", () => {
+        expect(findOfflinePythonArchive(archive)).toBeUndefined();
+    });
+    it("returns undefined when the archive for this platform is absent", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = tempDir;
+        writeFileSync(join(tempDir, "cpython-other-target.tar.gz"), "x");
+        expect(findOfflinePythonArchive(archive)).toBeUndefined();
+    });
+    it("returns the archive path when present", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = tempDir;
+        const path = join(tempDir, archive);
+        writeFileSync(path, "x");
+        expect(findOfflinePythonArchive(archive)).toBe(path);
+    });
+});
+describe("findOfflineWheelsDir", () => {
+    it("returns undefined when no payload directory is configured", () => {
+        expect(findOfflineWheelsDir()).toBeUndefined();
+    });
+    it("returns undefined when the payload has no wheels directory", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = tempDir;
+        expect(findOfflineWheelsDir()).toBeUndefined();
+    });
+    it("returns the wheels directory when present", () => {
+        process.env["AXIMO_OFFLINE_DIR"] = tempDir;
+        const wheels = join(tempDir, "wheels");
+        mkdirSync(wheels);
+        expect(findOfflineWheelsDir()).toBe(wheels);
+    });
+});

package/dist/desktop-server/setup-deps.test.d.ts

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

package/dist/desktop-server/setup-deps.test.js

@@ -0,0 +1,112 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getDepsMarkerPath } from "../commands/device/paths.js";
+import { ensureDependencies, pipInstallArgs } from "./setup.js";
+let tempDir;
+let requirements;
+const savedEnv = {};
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "aximo-deps-"));
+    savedEnv["AXIMO_HOME"] = process.env["AXIMO_HOME"];
+    process.env["AXIMO_HOME"] = tempDir;
+    requirements = join(tempDir, "requirements.txt");
+    writeFileSync(requirements, "pyautogui>=0.9.54\n");
+});
+afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe("pipInstallArgs", () => {
+    it("resolves from PyPI when no wheel directory is given", () => {
+        const args = pipInstallArgs("/tmp/requirements.txt");
+        expect(args).toEqual([
+            "-m",
+            "pip",
+            "install",
+            "--disable-pip-version-check",
+            "--no-warn-script-location",
+            "-r",
+            "/tmp/requirements.txt",
+        ]);
+    });
+    it("pins pip to a local wheel directory and blocks the index entirely", () => {
+        const args = pipInstallArgs("/tmp/requirements.txt", "/payload/wheels");
+        expect(args).toContain("--no-index");
+        expect(args.slice(args.indexOf("--find-links"), args.indexOf("--find-links") + 2)).toEqual([
+            "--find-links",
+            "/payload/wheels",
+        ]);
+        // -r must still come last so the requirements file drives resolution.
+        expect(args.slice(-2)).toEqual(["-r", "/tmp/requirements.txt"]);
+    });
+});
+describe("ensureDependencies", () => {
+    it("installs offline and records the requirements hash", () => {
+        const calls = [];
+        ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: (_file, args) => {
+                calls.push(args);
+                return { status: 0 };
+            },
+        });
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toContain("--no-index");
+        expect(existsSync(getDepsMarkerPath())).toBe(true);
+    });
+    it("skips the install when the requirements have not changed", () => {
+        let runs = 0;
+        const exec = () => {
+            runs++;
+            return { status: 0 };
+        };
+        ensureDependencies("/py", requirements, { exec });
+        ensureDependencies("/py", requirements, { exec });
+        expect(runs).toBe(1);
+    });
+    it("reinstalls when the requirements change", () => {
+        let runs = 0;
+        const exec = () => {
+            runs++;
+            return { status: 0 };
+        };
+        ensureDependencies("/py", requirements, { exec });
+        writeFileSync(requirements, "pyautogui>=0.9.54\nmss>=10.0\n");
+        ensureDependencies("/py", requirements, { exec });
+        expect(runs).toBe(2);
+    });
+    it("blames a stale payload when an offline install cannot be satisfied", () => {
+        expect(() => ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: () => ({ status: 1 }),
+        })).toThrow(/older than the requirements/);
+    });
+    it("names the wheel directory in the offline failure so it can be checked", () => {
+        expect(() => ensureDependencies("/py", requirements, {
+            wheelsDir: "/payload/wheels",
+            exec: () => ({ status: 1 }),
+        })).toThrow(/\/payload\/wheels/);
+    });
+    it("keeps the plain failure message for an online install", () => {
+        expect(() => ensureDependencies("/py", requirements, { exec: () => ({ status: 1 }) })).toThrow(/^pip install failed \(exit 1\)$/);
+    });
+    it("does not record the marker when the install fails", () => {
+        expect(() => ensureDependencies("/py", requirements, { exec: () => ({ status: 1 }) })).toThrow();
+        expect(existsSync(getDepsMarkerPath())).toBe(false);
+    });
+    it("rejects a missing requirements file", () => {
+        expect(() => ensureDependencies("/py", join(tempDir, "nope.txt"))).toThrow(/requirements.txt not found/);
+    });
+    it("records the hash of the requirements it actually installed", () => {
+        ensureDependencies("/py", requirements, { exec: () => ({ status: 0 }) });
+        const marker = readFileSync(getDepsMarkerPath(), "utf-8").trim();
+        expect(marker).toMatch(/^[0-9a-f]{64}$/);
+    });
+});

package/dist/desktop-server/setup-python.test.d.ts

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

package/dist/desktop-server/setup-python.test.js

@@ -0,0 +1,272 @@
+import { execFileSync } from "node:child_process";
+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 { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getPythonDir, getPythonMarkerPath } from "../commands/device/paths.js";
+import { installedPythonTag, installPythonArchive, pythonArchiveName } from "./setup.js";
+let tempDir;
+const savedEnv = {};
+/** Build a tar.gz shaped like python-build-standalone's install_only archive. */
+function writeFakeArchive(dest, layoutDir = "python") {
+    const src = mkdtempSync(join(tmpdir(), "aximo-fake-py-"));
+    try {
+        const root = join(src, layoutDir);
+        mkdirSync(join(root, "bin"), { recursive: true });
+        writeFileSync(join(root, "bin", "python3"), "#!/bin/sh\n");
+        writeFileSync(join(root, "python.exe"), "MZ");
+        execFileSync("tar", ["-czf", dest, "-C", src, layoutDir]);
+    }
+    finally {
+        rmSync(src, { recursive: true, force: true });
+    }
+}
+beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "aximo-setup-py-"));
+    for (const key of ["AXIMO_HOME", "AXIMO_OFFLINE_DIR"]) {
+        savedEnv[key] = process.env[key];
+        delete process.env[key];
+    }
+    process.env["AXIMO_HOME"] = tempDir;
+});
+afterEach(() => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+});
+describe("pythonArchiveName", () => {
+    it("matches the filename python-build-standalone publishes", () => {
+        const name = pythonArchiveName({
+            target: "x86_64-pc-windows-msvc",
+            sha256: "irrelevant",
+        });
+        expect(name).toBe("cpython-3.12.13+20260414-x86_64-pc-windows-msvc-install_only.tar.gz");
+    });
+});
+describe("installPythonArchive", () => {
+    it("installs from a local archive and stamps the version marker", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(join(getPythonDir(), "bin", "python3"))).toBe(true);
+        expect(readFileSync(getPythonMarkerPath(), "utf-8")).toBe(installedPythonTag());
+    });
+    it("keeps a staged archive in place so a shared payload survives setup", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(archive)).toBe(true);
+    });
+    it("removes an archive it downloaded itself", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: false });
+        expect(existsSync(archive)).toBe(false);
+    });
+    it("replaces an existing interpreter rather than merging into it", () => {
+        const stalePath = join(getPythonDir(), "stale-file");
+        mkdirSync(getPythonDir(), { recursive: true });
+        writeFileSync(stalePath, "old");
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive);
+        installPythonArchive(archive, { keepArchive: true });
+        expect(existsSync(stalePath)).toBe(false);
+        expect(existsSync(join(getPythonDir(), "bin", "python3"))).toBe(true);
+    });
+    it("rejects an archive whose layout is not a python/ root", () => {
+        const archive = join(tempDir, "python.tar.gz");
+        writeFakeArchive(archive, "cpython-3.12.13");
+        expect(() => installPythonArchive(archive, { keepArchive: true })).toThrow(/Unexpected archive layout/);
+    });
+});
+describe("acquirePythonTarball fallback diagnostics", () => {
+    // Found by local air-gap testing: when the server offers no interpreter the CLI
+    // falls back to GitHub, and on an air-gapped network that produced a bare
+    // "fetch failed" with no hint that the missing server payload was the cause.
+    it("explains a failed GitHub fallback instead of surfacing a bare network error", async () => {
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const manifest = {
+            manifestVersion: 3,
+            version: "abcd1234",
+            script: { sha256: sha(script), size: Buffer.byteLength(script) },
+            requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+            // Deliberately no python/wheels: this is a server without the CLI bundle.
+        };
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        // The GitHub download uses global fetch; make the air gap real.
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("fetch failed")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(/offered no embedded Python/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+    // The same GitHub path is the normal one for cloud, where a transient failure
+    // has nothing to do with on-prem bundles. Telling a cloud user their server
+    // needs a CLI bundle would be actively misleading.
+    it("stays quiet about on-prem bundles when pointed at cloud", async () => {
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const manifest = {
+            manifestVersion: 2,
+            version: "abcd1234",
+            script: { sha256: sha(script), size: Buffer.byteLength(script) },
+            requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+        };
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("fetch failed")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            const { DEFAULT_BASE_URL } = await import("../client.js");
+            await expect(ensurePythonReady({ baseUrl: DEFAULT_BASE_URL, apiKey: "k", fetchImpl })).rejects.toThrow(/^fetch failed$/);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});
+describe("interpreter source precedence", () => {
+    // README and ADR-003 both promise staged -> server -> GitHub. Each source was
+    // tested alone; the ordering between them was not.
+    const ARCHIVE = pythonArchiveName();
+    const BODY = "staged-archive-bytes";
+    function manifestOffering(archive) {
+        const sha = (v) => createHash("sha256").update(v).digest("hex");
+        const script = 'print("x")\n';
+        const requirements = "mss>=10.0\n";
+        return {
+            manifest: {
+                manifestVersion: 2,
+                version: "abcd1234",
+                script: { sha256: sha(script), size: Buffer.byteLength(script) },
+                requirements: { sha256: sha(requirements), size: Buffer.byteLength(requirements) },
+                python: {
+                    [`${process.platform}-${process.arch}`]: {
+                        archive,
+                        path: `python/x/${archive}`,
+                        sha256: sha("server-bytes"),
+                        size: Buffer.byteLength("server-bytes"),
+                    },
+                },
+            },
+            script,
+            requirements,
+        };
+    }
+    it("prefers a staged archive over the server's", async () => {
+        const staged = join(tempDir, "staged");
+        mkdirSync(staged, { recursive: true });
+        writeFileSync(join(staged, ARCHIVE), BODY);
+        process.env["AXIMO_OFFLINE_DIR"] = staged;
+        const { manifest, script, requirements } = manifestOffering(ARCHIVE);
+        let serverAssetRequested = false;
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            if (url.includes("/bundle/python/"))
+                serverAssetRequested = true;
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => Promise.reject(new Error("github must not be reached")));
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            // Fails on the staged archive's checksum, which proves it got that far with
+            // the staged file — and never asked the server or GitHub for one.
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(new RegExp(staged.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+            expect(serverAssetRequested).toBe(false);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+            delete process.env["AXIMO_OFFLINE_DIR"];
+        }
+    });
+    it("prefers the server over GitHub when it offers a matching archive", async () => {
+        const { manifest, script, requirements } = manifestOffering(ARCHIVE);
+        let serverAssetRequested = false;
+        const fetchImpl = ((input) => {
+            const url = String(input);
+            if (url.endsWith("/manifest")) {
+                return Promise.resolve(new Response(JSON.stringify(manifest), {
+                    status: 200,
+                    headers: { "Content-Type": "application/json" },
+                }));
+            }
+            if (url.endsWith("remote.py"))
+                return Promise.resolve(new Response(script, { status: 200 }));
+            if (url.endsWith("requirements.txt")) {
+                return Promise.resolve(new Response(requirements, { status: 200 }));
+            }
+            if (url.includes("/bundle/python/")) {
+                serverAssetRequested = true;
+                return Promise.resolve(new Response("server-bytes", { status: 200 }));
+            }
+            return Promise.reject(new Error("unexpected request"));
+        });
+        const originalFetch = globalThis.fetch;
+        let githubReached = false;
+        globalThis.fetch = (() => {
+            githubReached = true;
+            return Promise.reject(new Error("fetch failed"));
+        });
+        try {
+            const { ensurePythonReady } = await import("./setup.js");
+            await expect(ensurePythonReady({ baseUrl: "https://aximo.test", apiKey: "k", fetchImpl })).rejects.toThrow(/SHA256 mismatch/);
+            expect(serverAssetRequested).toBe(true);
+            expect(githubReached).toBe(false);
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});

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

@@ -1,8 +1,33 @@
 import { type ChildProcess } from "node:child_process";
-import type { ClientDeps } from "../client.js";
+import { type ClientDeps } from "../client.js";
 export declare const PYTHON_RELEASE = "20260414";
 export declare const PYTHON_VERSION = "3.12.13";
+interface PythonBuild {
+    target: string;
+    sha256: string;
+}
+/** Filename python-build-standalone publishes for this build, also used on disk. */
+export declare function pythonArchiveName(build?: PythonBuild): string;
 export declare function installedPythonTag(): string;
+/**
+ * Extract an already-verified Python archive into place and stamp the markers.
+ *
+ * Callers are responsible for integrity: by the time an archive reaches here it
+ * must have been checked against the expected SHA256.
+ */
+export declare function installPythonArchive(tarball: string, { keepArchive }: {
+    keepArchive: boolean;
+}): void;
+/** pip argv for the agent's requirements, resolving from wheelsDir when given. */
+export declare function pipInstallArgs(requirementsPath: string, wheelsDir?: string): string[];
+export interface DependencyOptions {
+    /** Local wheel directory to resolve from instead of PyPI; undefined means online. */
+    wheelsDir?: string | undefined;
+    exec?: (file: string, args: string[]) => {
+        status: number | null;
+    };
+}
+export declare function ensureDependencies(python: string, requirementsPath: string, options?: DependencyOptions): void;
 export interface PythonReadyResult {
     pythonPath: string;
     scriptPath: string;