@autifyhq/aximo-cli 0.14.0 → 0.16.0

package/dist/commands/device/testbox/box.test.js

@@ -0,0 +1,815 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { HttpResponse, http, server, TEST_BASE_URL } from "../../../test-utils.js";
+import { getTestboxConfigPath, getTestboxStatePath } from "../paths.js";
+import { agentLog, agentLogFollowArgs, downTestbox, pendingUp, pruneTestbox, resetTestbox, statusTestbox, upTestbox, waitForTestbox, } from "./box.js";
+import { containerName, DEFAULT_NOVNC_PORT, relayUrl, resolveImage, TESTBOX_IMAGE, TESTBOX_IMAGE_TAG, validateBoxName, } from "./container.js";
+import { TestboxError } from "./errors.js";
+import { fail, fakeDocker, has, ok, starts } from "./fake-docker.js";
+let tempHome;
+let agentDir;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-testbox-"));
+    agentDir = join(tempHome, "agent-src");
+    mkdirSync(agentDir);
+    writeFileSync(join(agentDir, "remote.py"), "print('agent')\n");
+    writeFileSync(join(agentDir, "requirements.txt"), "mss\n");
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_BASE_URL"];
+    delete process.env["AXIMO_API_KEY"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(join(tempHome, "testbox"), { recursive: true, force: true });
+    delete process.env["AXIMO_TESTBOX_IMAGE"];
+    delete process.env["AXIMO_OFFLINE_DIR"];
+});
+afterEach(() => server.resetHandlers());
+function fakeClock() {
+    let t = 1_700_000_000_000;
+    const sleeps = [];
+    return {
+        sleeps,
+        now: () => t,
+        sleep: async (ms) => {
+            sleeps.push(ms);
+            t += ms;
+        },
+    };
+}
+function apiWithDevices(own, org = own) {
+    const registered = [];
+    const deleted = [];
+    server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: own })), http.get(`${TEST_BASE_URL}/api/organizations/devices`, () => HttpResponse.json({ devices: org })), http.post(`${TEST_BASE_URL}/api/devices/register`, async ({ request }) => {
+        const body = (await request.json());
+        registered.push(body);
+        const device = { id: `dev-${registered.length}`, name: body.name, status: "online" };
+        own.push(device);
+        return HttpResponse.json({ deviceId: device.id, deviceToken: `tok-${registered.length}` });
+    }), http.delete(`${TEST_BASE_URL}/api/devices/user/:id`, ({ params }) => {
+        deleted.push(String(params["id"]));
+        return HttpResponse.json({ success: true });
+    }));
+    return { registered, deleted, own };
+}
+const fetchAgent = async () => ({
+    scriptPath: join(agentDir, "remote.py"),
+    requirementsPath: join(agentDir, "requirements.txt"),
+});
+function deps(docker = fakeDocker(), clock = fakeClock()) {
+    return { docker: docker.run, clock, fetchAgent, hostName: () => "mac.local" };
+}
+function seedToken(name, overrides = {}) {
+    mkdirSync(join(tempHome, "testbox"), { recursive: true });
+    writeFileSync(getTestboxConfigPath(name), JSON.stringify({
+        deviceId: "dev-old",
+        deviceToken: "tok-old",
+        name: "mac-testbox-abcd",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        baseUrl: TEST_BASE_URL,
+        ...overrides,
+    }));
+}
+const baseConfig = {
+    image: `${TESTBOX_IMAGE}:${TESTBOX_IMAGE_TAG}`,
+    ports: "3000",
+    blockHosts: [],
+    startUrl: undefined,
+    network: "bridge",
+    novncPort: DEFAULT_NOVNC_PORT,
+    screen: "1280x720",
+};
+function runningContainer(docker, cfg = baseConfig, running = true) {
+    docker.on(starts("inspect"), ok(`${running}|${cfg.image}|${JSON.stringify({ "aximo.testbox": "default", "aximo.testbox.config": JSON.stringify(cfg) })}\n`));
+}
+describe("validateBoxName", () => {
+    it("defaults to the single box and rejects names that would escape a path", () => {
+        expect(validateBoxName(undefined)).toBe("default");
+        expect(validateBoxName("qa-2")).toBe("qa-2");
+        expect(() => validateBoxName("../config")).toThrow(TestboxError);
+        expect(() => validateBoxName("")).toThrow(TestboxError);
+        expect(containerName("default")).toBe("aximo-testbox");
+        expect(containerName("qa")).toBe("aximo-testbox-qa");
+    });
+});
+describe("resolveImage", () => {
+    it("pins the published tag unless overridden", () => {
+        expect(resolveImage()).toBe(`ghcr.io/autifyhq/aximo-testbox:${TESTBOX_IMAGE_TAG}`);
+        process.env["AXIMO_TESTBOX_IMAGE"] = "mirror.local/testbox:1";
+        expect(resolveImage()).toBe("mirror.local/testbox:1");
+        expect(resolveImage("local:dev")).toBe("local:dev");
+    });
+    it("matches the tag the image workflow publishes", () => {
+        expect(readFileSync(new URL("../../../../testbox/image/TAG", import.meta.url), "utf-8").trim()).toBe(TESTBOX_IMAGE_TAG);
+    });
+});
+describe("upTestbox", () => {
+    it("pulls, registers, starts and injects the agent on a fresh machine", async () => {
+        const api = apiWithDevices([]);
+        const docker = fakeDocker();
+        const result = await upTestbox({ ports: "3000,5173", blockHosts: ["prod.example.com"], startUrl: "http://localhost:5173/" }, deps(docker));
+        expect(docker.find("pull")[0]?.args).toEqual(["pull", `${TESTBOX_IMAGE}:${TESTBOX_IMAGE_TAG}`]);
+        expect(api.registered).toEqual([
+            {
+                name: expect.stringMatching(/^mac-testbox-[0-9a-f]{4}$/),
+                platform: "linux",
+                os: "Testbox (Docker)",
+            },
+        ]);
+        const run = docker.find("run")[0].args;
+        expect(run.slice(0, 5)).toEqual(["run", "-d", "--init", "--name", "aximo-testbox"]);
+        expect(run).not.toContain("--network");
+        expect(run).toContain("--add-host=host.docker.internal:host-gateway");
+        expect(run).toContain("127.0.0.1:6080:6080");
+        expect(run).toContain("/run/aximo:rw,size=64m");
+        expect(run).toContain("aximo-testbox-profile:/profile");
+        expect(run).toContain("AXIMO_TESTBOX_PORTS=3000,5173");
+        expect(run).toContain("AXIMO_TESTBOX_BLOCK_HOSTS=prod.example.com");
+        expect(run).toContain("AXIMO_TESTBOX_START_URL=http://localhost:5173/");
+        expect(run).toContain("AXIMO_TESTBOX_SCREEN=1280x720");
+        expect(run.join(" ")).not.toMatch(/tok-|test-key/);
+        const writes = docker.calls.filter((c) => c.input !== undefined);
+        expect(writes.map((c) => c.args.at(-1))).toEqual([
+            "umask 022 && cat > '/run/aximo/requirements.txt'",
+            "umask 022 && cat > '/run/aximo/remote.py'",
+            "umask 077 && cat > '/run/aximo/agent.env'",
+        ]);
+        expect(writes[2].input).toBe([
+            "GATEWAY_URL=wss://aximo.test/devices/tunnel",
+            "RELAY_URL=wss://aximo.test/devices/tunnel",
+            "DEVICE_TOKEN=tok-1",
+            `DEVICE_NAME=${api.registered[0].name}`,
+            "",
+        ].join("\n"));
+        expect(docker.find("exec").some((c) => c.args.includes("pkill"))).toBe(false);
+        expect(result).toMatchObject({
+            name: "default",
+            container: "aximo-testbox",
+            userDeviceId: "dev-1",
+            state: "online",
+            liveViewUrl: "http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale&password=pw123",
+            notes: [],
+        });
+        const token = JSON.parse(readFileSync(getTestboxConfigPath("default"), "utf-8"));
+        expect(token).toMatchObject({
+            deviceId: "dev-1",
+            deviceToken: "tok-1",
+            baseUrl: TEST_BASE_URL,
+        });
+        expect(statSync(getTestboxConfigPath("default")).mode & 0o777).toBe(0o600);
+        expect(existsSync(getTestboxStatePath("default"))).toBe(false);
+    });
+    it("stops before pulling when Docker is missing and leaves no state behind", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("info"), () => {
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/Docker is not installed/);
+        expect(docker.find("pull")).toHaveLength(0);
+        expect(existsSync(getTestboxStatePath("default"))).toBe(false);
+    });
+    it("refuses to run while another up is working on the same box", async () => {
+        apiWithDevices([]);
+        mkdirSync(join(tempHome, "testbox"), { recursive: true });
+        writeFileSync(getTestboxStatePath("default"), JSON.stringify({ phase: "pulling", startedAt: new Date().toISOString(), pid: process.ppid }));
+        const docker = fakeDocker();
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/Another 'aximo device testbox up'/);
+        expect(docker.find("pull")).toHaveLength(0);
+    });
+    it("loses the race to an up that claims the box during the Docker preflight", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("info"), () => {
+            mkdirSync(join(tempHome, "testbox"), { recursive: true });
+            writeFileSync(getTestboxStatePath("default"), JSON.stringify({
+                phase: "pulling",
+                startedAt: new Date().toISOString(),
+                pid: process.ppid,
+            }));
+            return ok('Docker Desktop|["name=seccomp"]\n');
+        });
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/Another 'aximo device testbox up'/);
+        expect(docker.find("pull")).toHaveLength(0);
+        expect(JSON.parse(readFileSync(getTestboxStatePath("default"), "utf-8"))).toMatchObject({
+            phase: "pulling",
+            pid: process.ppid,
+        });
+    });
+    it("replaces a state file left by a dead or finished up", async () => {
+        apiWithDevices([]);
+        mkdirSync(join(tempHome, "testbox"), { recursive: true });
+        for (const stale of [
+            { phase: "pulling", startedAt: new Date().toISOString(), pid: 2 ** 22 - 1 },
+            { phase: "error", startedAt: new Date().toISOString(), pid: 1, lastError: "pull failed" },
+        ]) {
+            writeFileSync(getTestboxStatePath("default"), JSON.stringify(stale));
+            const docker = fakeDocker();
+            await expect(upTestbox({}, deps(docker))).resolves.toMatchObject({ state: "online" });
+            expect(docker.find("pull")).toHaveLength(1);
+            expect(existsSync(getTestboxStatePath("default"))).toBe(false);
+        }
+    });
+    it("checks the API key and the BYOD flag before pulling", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => new HttpResponse(null, { status: 404 })));
+        const docker = fakeDocker();
+        await expect(upTestbox({}, deps(docker))).rejects.toMatchObject({ status: 403 });
+        expect(docker.find("pull")).toHaveLength(0);
+        expect(JSON.parse(readFileSync(getTestboxStatePath("default"), "utf-8"))).toMatchObject({
+            phase: "error",
+            lastError: expect.stringContaining("BYOD is not enabled"),
+        });
+    });
+    it("registers before pulling, so a refused registration costs no download", async () => {
+        apiWithDevices([], [{ id: "dev-old", name: "mac-testbox-abcd", status: "offline" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/another API key owner/);
+        expect(docker.find("pull")).toHaveLength(0);
+    });
+    it("records a failed pull in the state file and says how to work around it", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("pull"), fail("denied: requested access to the resource is denied"));
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/AXIMO_TESTBOX_IMAGE/);
+        expect(JSON.parse(readFileSync(getTestboxStatePath("default"), "utf-8"))).toMatchObject({
+            phase: "error",
+            lastError: expect.stringContaining("denied"),
+        });
+    });
+    it("loads a staged tarball instead of pulling when AXIMO_OFFLINE_DIR has one", async () => {
+        apiWithDevices([]);
+        const offline = join(tempHome, "offline");
+        mkdirSync(join(offline, "testbox"), { recursive: true });
+        const arch = process.arch === "arm64" ? "linux-arm64" : "linux-amd64";
+        writeFileSync(join(offline, "testbox", `aximo-testbox-${arch}.tar`), "");
+        process.env["AXIMO_OFFLINE_DIR"] = offline;
+        const docker = fakeDocker();
+        await upTestbox({}, deps(docker));
+        expect(docker.find("load")[0]?.args).toEqual([
+            "load",
+            "-i",
+            join(offline, "testbox", `aximo-testbox-${arch}.tar`),
+        ]);
+        expect(docker.find("pull")).toHaveLength(0);
+    });
+    it("starts a stopped box with the same settings and injects without interrupting anything", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker, baseConfig, false);
+        const result = await upTestbox({}, deps(docker));
+        expect(docker.find("pull")).toHaveLength(0);
+        expect(docker.find("run")).toHaveLength(0);
+        expect(docker.find("start")[0]?.args).toEqual(["start", "aximo-testbox"]);
+        expect(docker.find("exec").some((c) => c.args.includes("pkill"))).toBe(false);
+        expect(result.userDeviceId).toBe("dev-old");
+    });
+    it("rewrites agent.env and restarts the agent when the running box has a different token", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker);
+        docker.on(has("exec", "cat", "/run/aximo/agent.env"), ok("GATEWAY_URL=stale\n"));
+        await upTestbox({}, deps(docker));
+        const writes = docker.calls.filter((c) => c.input !== undefined).map((c) => c.args.at(-1));
+        expect(writes).toContain("umask 077 && cat > '/run/aximo/agent.env'");
+        expect(docker.find("exec").some((c) => c.args.includes("pkill"))).toBe(true);
+    });
+    it("leaves a matching agent.env alone so a running session is not interrupted", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker);
+        const env = [
+            "GATEWAY_URL=wss://aximo.test/devices/tunnel",
+            "RELAY_URL=wss://aximo.test/devices/tunnel",
+            "DEVICE_TOKEN=tok-old",
+            "DEVICE_NAME=mac-testbox-abcd",
+            "",
+        ].join("\n");
+        docker.on(has("exec", "cat", "/run/aximo/agent.env"), ok(env));
+        await upTestbox({}, deps(docker));
+        const writes = docker.calls.filter((c) => c.input !== undefined).map((c) => c.args.at(-1));
+        expect(writes).not.toContain("umask 077 && cat > '/run/aximo/agent.env'");
+        expect(docker.find("exec").some((c) => c.args.includes("pkill"))).toBe(false);
+    });
+    it("recreates the box when the requested settings differ and drops the Power's old volumes", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker, { ...baseConfig, ports: "3000" });
+        await upTestbox({ ports: "5173" }, deps(docker));
+        expect(docker.find("rm", "-f", "aximo-testbox")).toHaveLength(1);
+        expect(docker.find("volume", "rm").map((c) => c.args.at(-1))).toEqual([
+            "aximo-testbox-aximo",
+            "aximo-testbox-npm",
+        ]);
+        expect(docker.find("run")[0]?.args).toContain("AXIMO_TESTBOX_PORTS=5173");
+    });
+    it("lets AXIMO_TESTBOX_IMAGE override the running box's image, as a flag would", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        process.env["AXIMO_TESTBOX_IMAGE"] = "mirror.local/testbox:2";
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker, { ...baseConfig, image: "mirror.local/testbox:1" });
+        const result = await upTestbox({}, deps(docker));
+        expect(result.config.image).toBe("mirror.local/testbox:2");
+        expect(docker.find("run")).toHaveLength(1);
+    });
+    it("keeps the running box's settings when up is called without flags", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker, { ...baseConfig, ports: "8080", blockHosts: ["prod"] });
+        const result = await upTestbox({}, deps(docker));
+        expect(docker.find("run")).toHaveLength(0);
+        expect(result.config.ports).toBe("8080");
+    });
+    it("replaces the Power's unlabelled container and its API-key volume on first use", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), ok("true|aximo-testbox:local|null\n"));
+        await upTestbox({}, deps(docker));
+        expect(docker.find("rm", "-f", "aximo-testbox")).toHaveLength(1);
+        expect(docker.find("volume", "rm").map((c) => c.args.at(-1))).toEqual([
+            "aximo-testbox-aximo",
+            "aximo-testbox-npm",
+        ]);
+        expect(docker.find("run")[0]?.args).toContain(`${TESTBOX_IMAGE}:${TESTBOX_IMAGE_TAG}`);
+    });
+    it("reads a config label whose start URL contains the separator", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker, { ...baseConfig, startUrl: "http://localhost:3000/?a=b|c" });
+        const result = await upTestbox({}, deps(docker));
+        expect(docker.find("run")).toHaveLength(0);
+        expect(result.config.startUrl).toBe("http://localhost:3000/?a=b|c");
+    });
+    it("re-registers when the device row was deleted on the server", async () => {
+        const api = apiWithDevices([]);
+        seedToken("default");
+        const docker = fakeDocker();
+        const result = await upTestbox({}, deps(docker));
+        expect(api.registered[0]?.name).toBe("mac-testbox-abcd");
+        expect(result.userDeviceId).toBe("dev-1");
+    });
+    it("refuses to register a second row when the device belongs to another key owner", async () => {
+        apiWithDevices([], [{ id: "dev-old", name: "mac-testbox-abcd", status: "offline" }]);
+        seedToken("default");
+        await expect(upTestbox({}, deps())).rejects.toThrow(/another API key owner/);
+    });
+    it("refuses when the token was issued by a different server", async () => {
+        apiWithDevices([]);
+        seedToken("default", { baseUrl: "https://other.example" });
+        await expect(upTestbox({}, deps())).rejects.toThrow(/registered against https:\/\/other.example/);
+    });
+    it("uses the host network on native Linux with a display and ports per box", async () => {
+        apiWithDevices([]);
+        const platform = Object.getOwnPropertyDescriptor(process, "platform");
+        Object.defineProperty(process, "platform", { value: "linux" });
+        try {
+            const docker = fakeDocker();
+            docker.on(starts("info"), ok('Ubuntu 24.04|["name=seccomp"]\n'));
+            docker.on(starts("ps"), ok(`${JSON.stringify(baseConfig)}\n`));
+            const result = await upTestbox({ name: "qa" }, deps(docker));
+            const run = docker.find("run")[0].args;
+            expect(run).toContain("--network");
+            expect(run).toContain("host");
+            expect(run).not.toContain("-p");
+            expect(run).toContain("AXIMO_TESTBOX_NOVNC_PORT=6081");
+            expect(run).toContain("AXIMO_TESTBOX_VNC_PORT=5901");
+            expect(run).toContain("AXIMO_TESTBOX_DISPLAY=101");
+            expect(result.container).toBe("aximo-testbox-qa");
+            expect(result.liveViewUrl).toContain(":6081/");
+        }
+        finally {
+            Object.defineProperty(process, "platform", platform);
+        }
+    });
+    it("falls back to the bridge on rootless Docker and says why", async () => {
+        apiWithDevices([]);
+        const platform = Object.getOwnPropertyDescriptor(process, "platform");
+        Object.defineProperty(process, "platform", { value: "linux" });
+        try {
+            const docker = fakeDocker();
+            docker.on(starts("info"), ok('Ubuntu 24.04|["name=rootless","name=seccomp"]\n'));
+            const result = await upTestbox({}, deps(docker));
+            expect(docker.find("run")[0].args).toContain("--add-host=host.docker.internal:host-gateway");
+            expect(result.notes[0]).toMatch(/Rootless Docker/);
+        }
+        finally {
+            Object.defineProperty(process, "platform", platform);
+        }
+    });
+    it("gives the default box the next free live-view port when a named box took 6080", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("ps"), ok(`${JSON.stringify({ ...baseConfig, novncPort: 6080 })}\n`));
+        const result = await upTestbox({}, deps(docker));
+        expect(result.config.novncPort).toBe(6081);
+        expect(docker.find("run")[0].args).toContain("127.0.0.1:6081:6081");
+    });
+    it("rejects a live-view port that cannot be mapped to a display", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        await expect(upTestbox({ novncPort: Number.NaN }, deps(docker))).rejects.toThrow(/noVNC port/);
+        await expect(upTestbox({ novncPort: 80 }, deps(docker))).rejects.toThrow(/noVNC port/);
+        expect(docker.find("pull")).toHaveLength(0);
+    });
+    it("caps the mirrored ports and keeps the live view's own ports out of the mirror", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        await expect(upTestbox({ ports: "1-65535" }, deps(docker))).rejects.toThrow(/Too many ports/);
+        await expect(upTestbox({ ports: "3000,5900" }, deps(docker))).rejects.toThrow(/Port 5900 is used/);
+        await expect(upTestbox({ ports: "6080" }, deps(docker))).rejects.toThrow(/Port 6080 is used/);
+        expect(docker.find("pull")).toHaveLength(0);
+        expect(docker.find("run")).toHaveLength(0);
+    });
+    it("points the agent at host.docker.internal when the server itself is on localhost", () => {
+        expect(relayUrl("http://localhost:3000", "bridge")).toBe("ws://host.docker.internal:3000/devices/tunnel");
+        expect(relayUrl("http://127.0.0.1:3000", "host")).toBe("ws://127.0.0.1:3000/devices/tunnel");
+        expect(relayUrl("http://[::1]:3000", "bridge")).toBe("ws://host.docker.internal:3000/devices/tunnel");
+        expect(relayUrl("https://aximo.example.com/aximo/", "bridge")).toBe("wss://aximo.example.com/aximo/devices/tunnel");
+    });
+    it("sizes the virtual screen from --screen and rejects sizes the box cannot use", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        const result = await upTestbox({ screen: "1920x1080" }, deps(docker));
+        expect(result.config.screen).toBe("1920x1080");
+        expect(docker.find("run")[0]?.args).toContain("AXIMO_TESTBOX_SCREEN=1920x1080");
+        for (const screen of ["100x100", "1280*720", "abc", "4096x2160", "1280x720x24"]) {
+            const bad = fakeDocker();
+            await expect(upTestbox({ screen }, deps(bad))).rejects.toThrow(/Invalid screen/);
+            expect(bad.find("pull")).toHaveLength(0);
+        }
+    });
+    it("rejects a bad port spec before touching Docker state", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        for (const ports of ["80-70", "3000-3001-9999", "0x10", "3000-", "-3000", "3000.0", "65536"]) {
+            await expect(upTestbox({ ports }, deps(docker))).rejects.toThrow(/Invalid port spec/);
+        }
+        expect(docker.find("pull")).toHaveLength(0);
+    });
+    it("removes a box it just created when the agent cannot be injected, quoting the box's own log", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(has("exec", "-i"), fail("container aximo-testbox is not running"));
+        docker.on(starts("logs"), ok("[aximo-testbox] FATAL: port 5900 is already in use\n"));
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/not running[\s\S]*FATAL: port 5900/);
+        expect(docker.find("rm", "-f", "aximo-testbox")).toHaveLength(1);
+    });
+    it("leaves a reused running box alone when injection fails", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("image", "inspect"), ok());
+        runningContainer(docker);
+        docker.on(has("exec", "-i"), fail("exec failed"));
+        await expect(upTestbox({}, deps(docker))).rejects.toThrow(/exec failed/);
+        expect(docker.find("rm")).toHaveLength(0);
+    });
+    it("keeps polling through transient API errors and stops on a BYOD 403", async () => {
+        const api = apiWithDevices([]);
+        let calls = 0;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => {
+            calls += 1;
+            if (calls === 2 || calls === 3)
+                return new HttpResponse(null, { status: 500 });
+            return HttpResponse.json({ devices: api.own });
+        }));
+        const clock = fakeClock();
+        const result = await upTestbox({}, deps(fakeDocker(), clock));
+        expect(result.state).toBe("online");
+        expect(clock.sleeps).toEqual([3000, 3000]);
+        apiWithDevices([]);
+        let gone = 0;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => {
+            gone += 1;
+            return gone === 1
+                ? HttpResponse.json({ devices: [] })
+                : new HttpResponse(null, { status: 404 });
+        }));
+        await expect(upTestbox({ name: "qa" }, deps(fakeDocker(), fakeClock()))).rejects.toMatchObject({
+            status: 403,
+        });
+    });
+    it("polls until the device is online and gives up with a note after the deadline", async () => {
+        const api = apiWithDevices([]);
+        const clock = fakeClock();
+        const docker = fakeDocker();
+        server.use(http.post(`${TEST_BASE_URL}/api/devices/register`, () => {
+            api.own.push({ id: "dev-slow", name: "n", status: "offline" });
+            return HttpResponse.json({ deviceId: "dev-slow", deviceToken: "t" });
+        }));
+        const result = await upTestbox({}, deps(docker, clock));
+        expect(result.state).toBe("connecting");
+        expect(result.notes[0]).toMatch(/not come online yet/);
+        expect(clock.sleeps.length).toBeGreaterThan(30);
+    });
+    it("returns right after injecting with wait=false and clears the state file so status reads Docker", async () => {
+        apiWithDevices([]);
+        const clock = fakeClock();
+        const result = await upTestbox({ wait: false }, deps(fakeDocker(), clock));
+        expect(result.state).toBe("connecting");
+        expect(clock.sleeps).toEqual([]);
+        expect(existsSync(getTestboxStatePath("default"))).toBe(false);
+    });
+});
+describe("statusTestbox and waitForTestbox", () => {
+    it("is down with no container and no registration", async () => {
+        apiWithDevices([]);
+        const status = await statusTestbox(undefined, deps());
+        expect(status).toEqual({ name: "default", state: "down", container: "absent" });
+    });
+    it("reports a Docker daemon failure instead of calling the box down", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), fail("Cannot connect to the Docker daemon at unix:///var/run/docker.sock"));
+        await expect(statusTestbox(undefined, deps(docker))).rejects.toThrow(/docker inspect aximo-testbox failed: Cannot connect/);
+    });
+    it("is down when Docker is not installed at all", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), () => {
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        expect((await statusTestbox(undefined, deps(docker))).state).toBe("down");
+    });
+    it("reports online with probed ports and the live view", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker, { ...baseConfig, ports: "3000,5173" });
+        docker.on(has("exec", "curl"), (args) => (args.at(-1).endsWith(":5173/") ? fail() : ok()));
+        docker.on(has("exec", "cat", "/run/aximo/agent.status"), ok("connected to gateway\n"));
+        const status = await statusTestbox(undefined, deps(docker));
+        expect(status).toMatchObject({
+            state: "online",
+            container: "running",
+            agent: "running",
+            agentStatus: "connected to gateway",
+            ports: [
+                { port: 3000, reachable: true },
+                { port: 5173, reachable: false },
+            ],
+            device: { userDeviceId: "dev-old", name: "mac-testbox-abcd", status: "online" },
+            liveViewUrl: "http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale&password=pw123",
+        });
+    });
+    it("reports a stopped container as down and omits the live view until the password exists", async () => {
+        apiWithDevices([]);
+        const stopped = fakeDocker();
+        runningContainer(stopped, baseConfig, false);
+        expect(await statusTestbox(undefined, deps(stopped))).toMatchObject({
+            state: "down",
+            container: "stopped",
+        });
+        const booting = fakeDocker();
+        runningContainer(booting);
+        booting.on(has("exec", "cat", "/profile/.vncpass"), fail());
+        expect((await statusTestbox(undefined, deps(booting))).liveViewUrl).toBeUndefined();
+    });
+    it("is connecting while the container runs but the device is offline", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "offline" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker);
+        docker.on(has("exec", "pgrep"), fail());
+        const status = await statusTestbox(undefined, deps(docker));
+        expect(status.state).toBe("connecting");
+        expect(status.agent).toBe("stopped");
+    });
+    it("follows a live detached up, ignores a dead one, and surfaces its error", async () => {
+        apiWithDevices([]);
+        const clock = fakeClock();
+        mkdirSync(join(tempHome, "testbox"), { recursive: true });
+        const write = (state) => writeFileSync(getTestboxStatePath("default"), JSON.stringify(state));
+        write({ phase: "pulling", startedAt: new Date(clock.now()).toISOString(), pid: process.pid });
+        expect(pendingUp("default", clock)).toMatchObject({ phase: "pulling" });
+        expect((await statusTestbox(undefined, deps(fakeDocker(), clock))).state).toBe("pulling");
+        write({ phase: "pulling", startedAt: new Date(clock.now()).toISOString(), pid: 2 ** 22 - 1 });
+        expect(pendingUp("default", clock)).toBeNull();
+        expect((await statusTestbox(undefined, deps(fakeDocker(), clock))).state).toBe("down");
+        write({
+            phase: "starting",
+            startedAt: new Date(clock.now() - 3_600_000).toISOString(),
+            pid: process.pid,
+        });
+        expect((await statusTestbox(undefined, deps(fakeDocker(), clock))).state).toBe("down");
+        write({
+            phase: "error",
+            startedAt: new Date(clock.now()).toISOString(),
+            pid: 1,
+            lastError: "pull failed",
+        });
+        expect(await statusTestbox(undefined, deps(fakeDocker(), clock))).toMatchObject({
+            state: "error",
+            lastError: "pull failed",
+        });
+    });
+    it("reports the last failed up even while an older box is still running", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "online" }]);
+        seedToken("default");
+        mkdirSync(join(tempHome, "testbox"), { recursive: true });
+        writeFileSync(getTestboxStatePath("default"), JSON.stringify({
+            phase: "error",
+            startedAt: new Date().toISOString(),
+            pid: 1,
+            lastError: "pull failed",
+        }));
+        const docker = fakeDocker();
+        runningContainer(docker);
+        expect(await statusTestbox(undefined, deps(docker))).toMatchObject({
+            state: "error",
+            container: "running",
+            lastError: "pull failed",
+        });
+    });
+    it("treats a daemon that is down as an error, not as an absent box", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), fail("Cannot connect to the Docker daemon"));
+        await expect(downTestbox(undefined, deps(docker))).rejects.toThrow(/Cannot connect/);
+        await expect(pruneTestbox(undefined, {}, deps(docker))).rejects.toThrow(/Cannot connect/);
+    });
+    it("surfaces an API failure in lastError without hiding the container state", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => new HttpResponse(null, { status: 500 })));
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker);
+        const status = await statusTestbox(undefined, deps(docker));
+        expect(status.container).toBe("running");
+        expect(status.lastError).toBeDefined();
+        expect(status.state).toBe("connecting");
+    });
+    it("waits across polls and returns at the deadline", async () => {
+        apiWithDevices([{ id: "dev-old", name: "mac-testbox-abcd", status: "offline" }]);
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker);
+        const clock = fakeClock();
+        const status = await waitForTestbox(undefined, 10, deps(docker, clock));
+        expect(status.state).toBe("connecting");
+        expect(clock.sleeps).toEqual([3000, 3000, 3000]);
+    });
+});
+describe("down, reset, prune", () => {
+    it("down stops the agent first and keeps profile and registration", async () => {
+        apiWithDevices([]);
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker);
+        expect(await downTestbox(undefined, deps(docker))).toEqual({ name: "default", removed: true });
+        expect(docker.calls.map((c) => c.args.slice(0, 2))).toEqual(expect.arrayContaining([
+            ["exec", "aximo-testbox"],
+            ["rm", "-f"],
+        ]));
+        expect(docker.find("volume")).toHaveLength(0);
+        expect(existsSync(getTestboxConfigPath("default"))).toBe(true);
+    });
+    it("down without Docker installed says how to install it", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), () => {
+            throw Object.assign(new TestboxError("Docker is not installed. Install Docker Desktop"), {
+                code: "ENOENT",
+            });
+        });
+        await expect(downTestbox(undefined, deps(docker))).rejects.toThrow(/Docker is not installed/);
+    });
+    it("down is a no-op on an absent box", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        expect(await downTestbox("qa", deps(docker))).toEqual({ name: "qa", removed: false });
+        expect(docker.find("rm")).toHaveLength(0);
+    });
+    it("reset also drops the browser profile", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        const result = await resetTestbox(undefined, deps(docker));
+        expect(result.profileDropped).toBe(true);
+        expect(docker.find("volume", "rm")[0]?.args).toEqual([
+            "volume",
+            "rm",
+            "-f",
+            "aximo-testbox-profile",
+        ]);
+    });
+    it("prune unregisters on the server even when the box is already down, then removes everything", async () => {
+        const api = apiWithDevices([]);
+        seedToken("default");
+        const docker = fakeDocker();
+        const result = await pruneTestbox(undefined, {}, deps(docker));
+        expect(api.deleted).toEqual(["dev-old"]);
+        expect(result).toMatchObject({ deviceId: "dev-old", serverDeleted: true, removed: false });
+        expect(docker.find("volume", "rm").map((c) => c.args.at(-1))).toEqual([
+            "aximo-testbox-profile",
+            "aximo-testbox-aximo",
+            "aximo-testbox-npm",
+        ]);
+        expect(docker.find("rmi")[0]?.args).toEqual([
+            "rmi",
+            "-f",
+            `${TESTBOX_IMAGE}:${TESTBOX_IMAGE_TAG}`,
+        ]);
+        expect(existsSync(getTestboxConfigPath("default"))).toBe(false);
+    });
+    it("prune tolerates a device already gone server-side and can keep the image", async () => {
+        apiWithDevices([]);
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/:id`, () => new HttpResponse(null, { status: 404 })));
+        seedToken("default");
+        const docker = fakeDocker();
+        runningContainer(docker, { ...baseConfig, image: "mirror/testbox:9" });
+        const result = await pruneTestbox(undefined, { keepImage: true }, deps(docker));
+        expect(result.serverDeleted).toBe(false);
+        expect(docker.find("rmi")).toHaveLength(0);
+    });
+    it("prune removes the image the box actually ran", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        runningContainer(docker, { ...baseConfig, image: "mirror/testbox:9" });
+        await pruneTestbox(undefined, {}, deps(docker));
+        expect(docker.find("rmi")[0]?.args).toEqual(["rmi", "-f", "mirror/testbox:9"]);
+    });
+    it("prune still deletes the server row and the local token when Docker is gone", async () => {
+        const api = apiWithDevices([]);
+        seedToken("default");
+        const docker = fakeDocker();
+        docker.on(starts("inspect"), () => {
+            throw Object.assign(new Error("spawn docker ENOENT"), { code: "ENOENT" });
+        });
+        const result = await pruneTestbox(undefined, {}, deps(docker));
+        expect(api.deleted).toEqual(["dev-old"]);
+        expect(result).toMatchObject({ removed: false, serverDeleted: true });
+        expect(docker.find("volume")).toHaveLength(0);
+        expect(existsSync(getTestboxConfigPath("default"))).toBe(false);
+    });
+    it("prune refuses to unregister against a different server than the one it registered with", async () => {
+        const api = apiWithDevices([]);
+        seedToken("default", { baseUrl: "https://other.example" });
+        await expect(pruneTestbox(undefined, {}, deps())).rejects.toThrow(/registered against https:\/\/other.example/);
+        expect(api.deleted).toEqual([]);
+        expect(existsSync(getTestboxConfigPath("default"))).toBe(true);
+    });
+    it("prune reports a profile volume it could not remove", async () => {
+        apiWithDevices([]);
+        const docker = fakeDocker();
+        runningContainer(docker);
+        docker.on(starts("volume", "rm"), fail("volume is in use"));
+        await expect(pruneTestbox(undefined, {}, deps(docker))).rejects.toThrow(/volume is in use/);
+    });
+    it("prune re-raises server errors other than 404", async () => {
+        apiWithDevices([]);
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/:id`, () => new HttpResponse(null, { status: 500 })));
+        seedToken("default");
+        await expect(pruneTestbox(undefined, {}, deps())).rejects.toMatchObject({ status: 500 });
+    });
+});
+describe("agent log", () => {
+    it("returns the last lines of the agent log as an envelope payload", async () => {
+        const docker = fakeDocker();
+        docker.on(has("exec", "tail"), ok("line one\nline two\n"));
+        expect(await agentLog("qa", 2, deps(docker))).toEqual({
+            name: "qa",
+            lines: ["line one", "line two"],
+        });
+        expect(docker.find("exec")[0]?.args).toEqual([
+            "exec",
+            "aximo-testbox-qa",
+            "tail",
+            "-n",
+            "2",
+            "/var/log/aximo/agent.log",
+        ]);
+    });
+    it("follows the agent log of the named box", () => {
+        expect(agentLogFollowArgs("qa", 20)).toEqual([
+            "exec",
+            "aximo-testbox-qa",
+            "tail",
+            "-n",
+            "20",
+            "-f",
+            "/var/log/aximo/agent.log",
+        ]);
+    });
+});