@autifyhq/aximo-cli 0.15.0 → 0.16.0

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

@@ -0,0 +1,379 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { getBaseUrl } from "../../../client.js";
+import { ensureAgent } from "../../../desktop-server/agent-sync.js";
+import { realClock } from "../../mcp/wait.js";
+import { getTestboxConfigPath, getTestboxDir, getTestboxLogPath, getTestboxStatePath, } from "../paths.js";
+import { listUserDevices } from "../user-devices.js";
+import { AGENT_LOG, containerLog, containerName, DEFAULT_SCREEN, ensureImage, injectAgent, inspectContainer, legacyVolumes, liveViewUrl, nextNovncPort, parsePorts, probePorts, profileVolume, readInContainer, removeContainer, reservedPorts, resolveImage, RUN_DIR, runArgs, validateBoxName, validateNovncPort, validateScreen, } from "./container.js";
+import { docker, isDockerProblem, preflightDocker, runDocker, } from "./docker.js";
+import { TestboxError } from "./errors.js";
+import { ensureRegistration, readRegistration, unregister } from "./registration.js";
+const DEFAULT_PORTS = "3000";
+const ONLINE_TIMEOUT_MS = 120_000;
+const ONLINE_POLL_MS = 3_000;
+// Backstop for a pid recycled after a reboot; a live pid wins until then.
+const STATE_TTL_MS = 60 * 60_000;
+export function readState(name) {
+    const path = getTestboxStatePath(name);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeState(name, state) {
+    mkdirSync(getTestboxDir(), { recursive: true });
+    writeFileSync(getTestboxStatePath(name), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function clearState(name) {
+    rmSync(getTestboxStatePath(name), { force: true });
+}
+// Exclusive create: of two ups racing for the same box, exactly one gets the file.
+function claimState(name, state) {
+    mkdirSync(getTestboxDir(), { recursive: true });
+    try {
+        writeFileSync(getTestboxStatePath(name), JSON.stringify(state, null, 2), {
+            mode: 0o600,
+            flag: "wx",
+        });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// A pid from the state file may have been recycled; only signal a process
+// that is visibly one of ours. Windows has no cheap equivalent, so it skips.
+function isTestboxUp(pid) {
+    if (process.platform === "win32")
+        return false;
+    const ps = spawnSync("ps", ["-o", "args=", "-p", String(pid)], { encoding: "utf-8" });
+    return ps.status === 0 && /testbox/.test(ps.stdout);
+}
+function stateIsLive(state, clock) {
+    if (state.phase === "error")
+        return true;
+    return pidAlive(state.pid) && clock.now() - Date.parse(state.startedAt) < STATE_TTL_MS;
+}
+/** The detached `up` still working on this box, if any. */
+export function pendingUp(name, clock = realClock) {
+    const state = readState(name);
+    return state && state.phase !== "error" && stateIsLive(state, clock) ? state : null;
+}
+function chooseNetwork(info) {
+    if (info.desktop || process.platform !== "linux")
+        return { network: "bridge" };
+    if (info.rootless) {
+        return {
+            network: "bridge",
+            note: "Rootless Docker cannot share the host network; dev servers must listen on 0.0.0.0, not 127.0.0.1.",
+        };
+    }
+    return { network: "host" };
+}
+async function waitOnline(deviceId, deps, clock, timeoutMs) {
+    const deadline = clock.now() + timeoutMs;
+    for (;;) {
+        let device;
+        try {
+            device = (await listUserDevices(deps)).find((d) => d.id === deviceId);
+        }
+        catch (err) {
+            // A 403 means the BYOD flag was switched off under us; anything else is a blip.
+            if (err.status === 403)
+                throw err;
+        }
+        if (device?.status === "online")
+            return device;
+        if (clock.now() + ONLINE_POLL_MS > deadline)
+            return device;
+        await clock.sleep(ONLINE_POLL_MS);
+    }
+}
+export async function upTestbox(options, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const clock = deps.clock ?? realClock;
+    const name = validateBoxName(options.name);
+    const container = containerName(name);
+    const notes = [];
+    // Reported without touching any state, so a machine without Docker is left as found.
+    const info = await preflightDocker(run);
+    if (isDockerProblem(info))
+        throw new TestboxError(info.message, info.kind === "unreachable");
+    const started = new Date().toISOString();
+    const stateFor = (phase, lastError) => ({
+        phase,
+        startedAt: started,
+        pid: process.pid,
+        ...(lastError ? { lastError } : {}),
+    });
+    const state = (phase, lastError) => writeState(name, stateFor(phase, lastError));
+    // Two concurrent ups would each register a device and fight over the container.
+    // A stale file (a finished error, a dead pid) is replaced; a live one wins.
+    for (let attempt = 0; !claimState(name, stateFor("pulling")); attempt++) {
+        const pending = pendingUp(name, clock);
+        if (attempt > 0 || (pending && pending.pid !== process.pid)) {
+            const who = pending ? ` (pid ${pending.pid}, ${pending.phase})` : "";
+            throw new TestboxError(`Another 'aximo device testbox up' is already working on this box${who}; wait for it or run 'aximo device testbox status'.`, true);
+        }
+        clearState(name);
+    }
+    try {
+        // Validates the key, the base URL and the BYOD flag before anything is pulled.
+        const own = await listUserDevices(deps);
+        const existing = await inspectContainer(run, container);
+        const previous = existing?.config ?? null;
+        const { network, note } = chooseNetwork(info);
+        if (note)
+            notes.push(note);
+        const cfg = {
+            image: resolveImage(options.image, previous?.image),
+            ports: options.ports ?? previous?.ports ?? DEFAULT_PORTS,
+            blockHosts: options.blockHosts ?? previous?.blockHosts ?? [],
+            startUrl: options.startUrl ?? previous?.startUrl,
+            network,
+            novncPort: options.novncPort ?? previous?.novncPort ?? (await nextNovncPort(run)),
+            screen: validateScreen(options.screen ?? previous?.screen ?? DEFAULT_SCREEN),
+        };
+        validateNovncPort(cfg.novncPort, cfg.network);
+        const clash = parsePorts(cfg.ports).filter((p) => reservedPorts(cfg).includes(p));
+        if (clash.length > 0) {
+            throw new TestboxError(`Port ${clash.join(", ")} is used by the live view inside the box; choose other ports or another --novnc-port`);
+        }
+        const registration = await ensureRegistration(name, own, deps);
+        const agent = await (deps.fetchAgent ?? ensureAgent)(deps);
+        await ensureImage(run, cfg.image);
+        state("starting");
+        const reuse = previous !== null && JSON.stringify(previous) === JSON.stringify(cfg);
+        if (existing && !reuse) {
+            await removeContainer(run, container);
+            for (const volume of legacyVolumes(name))
+                await run(["volume", "rm", "-f", volume]);
+        }
+        const created = !existing || !reuse;
+        if (created) {
+            await docker(run, runArgs(name, cfg));
+        }
+        else if (!existing.running) {
+            await docker(run, ["start", container]);
+        }
+        try {
+            await injectAgent(run, container, {
+                deviceToken: registration.deviceToken,
+                deviceName: registration.name,
+                baseUrl: registration.baseUrl ?? "",
+            }, cfg.network, agent);
+        }
+        catch (err) {
+            // The entrypoint's own FATAL line is the useful part. A box we did not
+            // create is left alone: it may be mid-session.
+            const log = await containerLog(run, container, 20);
+            if (created)
+                await run(["rm", "-f", container]);
+            const message = err instanceof Error ? err.message : String(err);
+            throw new TestboxError(log ? `${message}\n${log}` : message, true);
+        }
+        state("connecting");
+        let device;
+        if (options.wait !== false) {
+            device = await waitOnline(registration.deviceId, deps, clock, ONLINE_TIMEOUT_MS);
+            if (device?.status !== "online") {
+                notes.push("The device has not come online yet; 'aximo device testbox status' shows the agent's last message.");
+            }
+        }
+        const url = await liveViewUrl(run, container, cfg.novncPort);
+        clearState(name);
+        return {
+            name,
+            container,
+            userDeviceId: registration.deviceId,
+            deviceName: registration.name,
+            state: device?.status === "online" ? "online" : "connecting",
+            config: cfg,
+            ...(url ? { liveViewUrl: url } : {}),
+            notes,
+        };
+    }
+    catch (err) {
+        state("error", err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+}
+export async function statusTestbox(nameInput, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const clock = deps.clock ?? realClock;
+    const name = validateBoxName(nameInput);
+    const container = containerName(name);
+    const status = { name, state: "down", container: "absent" };
+    const pending = readState(name);
+    const live = pending && stateIsLive(pending, clock) ? pending : null;
+    let info = null;
+    try {
+        info = await inspectContainer(run, container);
+    }
+    catch (err) {
+        // Without the docker binary the box cannot be running; anything else is reported.
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (info) {
+        status.container = info.running ? "running" : "stopped";
+        if (info.config)
+            status.config = info.config;
+        if (info.running && info.config) {
+            status.agent =
+                (await run(["exec", container, "pgrep", "-f", "remote.py"])).code === 0
+                    ? "running"
+                    : "stopped";
+            const last = await readInContainer(run, container, `${RUN_DIR}/agent.status`);
+            if (last?.trim())
+                status.agentStatus = last.trim();
+            status.ports = await probePorts(run, container, info.config.ports);
+            const url = await liveViewUrl(run, container, info.config.novncPort);
+            if (url)
+                status.liveViewUrl = url;
+        }
+    }
+    const registration = readRegistration(name);
+    if (registration) {
+        try {
+            const device = (await listUserDevices(deps)).find((d) => d.id === registration.deviceId);
+            if (device) {
+                status.device = { userDeviceId: device.id, name: device.name, status: device.status };
+            }
+        }
+        catch (err) {
+            status.lastError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    // The last up attempt failed: say so even if an older box is still running,
+    // or a reconfigure that never happened would look like success.
+    if (live?.phase === "error") {
+        status.state = "error";
+        if (live.lastError)
+            status.lastError = live.lastError;
+    }
+    else if (live) {
+        status.state = live.phase;
+    }
+    else if (status.container !== "running") {
+        status.state = "down";
+    }
+    else {
+        status.state = status.device?.status === "online" ? "online" : "connecting";
+    }
+    return status;
+}
+/** Status now, or once the box is online or has stopped trying, whichever comes first. */
+export async function waitForTestbox(name, timeoutSeconds, deps = {}) {
+    const clock = deps.clock ?? realClock;
+    const deadline = clock.now() + timeoutSeconds * 1000;
+    for (;;) {
+        const status = await statusTestbox(name, deps);
+        if (status.state === "online" || status.state === "error" || status.state === "down") {
+            return status;
+        }
+        if (clock.now() + ONLINE_POLL_MS > deadline)
+            return status;
+        await clock.sleep(ONLINE_POLL_MS);
+    }
+}
+export async function downTestbox(nameInput, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const name = validateBoxName(nameInput);
+    const pending = pendingUp(name, deps.clock);
+    if (pending && pending.pid !== process.pid && isTestboxUp(pending.pid)) {
+        try {
+            process.kill(pending.pid, "SIGTERM");
+        }
+        catch {
+            // already gone
+        }
+    }
+    const existed = (await inspectContainer(run, containerName(name))) !== null;
+    if (existed)
+        await removeContainer(run, containerName(name));
+    clearState(name);
+    return { name, removed: existed };
+}
+export async function resetTestbox(nameInput, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const down = await downTestbox(nameInput, deps);
+    await docker(run, ["volume", "rm", "-f", profileVolume(down.name)]);
+    return { ...down, profileDropped: true };
+}
+export async function pruneTestbox(nameInput, options = {}, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const name = validateBoxName(nameInput);
+    const registration = readRegistration(name);
+    const baseUrl = deps.baseUrl ?? getBaseUrl();
+    if (registration?.baseUrl !== undefined && registration.baseUrl !== baseUrl) {
+        throw new TestboxError(`This testbox is registered against ${registration.baseUrl}, not ${baseUrl}; point the CLI at that server to prune it.`);
+    }
+    // The server row and the local files go even on a machine that lost Docker;
+    // any other Docker failure is reported, not papered over.
+    let existing;
+    try {
+        existing = await inspectContainer(run, containerName(name));
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        existing = undefined;
+    }
+    const serverDeleted = registration ? await unregister(registration.deviceId, deps) : false;
+    let removed = false;
+    if (existing !== undefined) {
+        const image = existing?.config?.image ?? resolveImage();
+        removed = (await downTestbox(name, deps)).removed;
+        for (const volume of [profileVolume(name), ...legacyVolumes(name)]) {
+            await docker(run, ["volume", "rm", "-f", volume]);
+        }
+        // Best effort: another box may still run this image.
+        if (!options.keepImage)
+            await run(["rmi", "-f", image]);
+    }
+    clearState(name);
+    rmSync(getTestboxConfigPath(name), { force: true });
+    rmSync(getTestboxLogPath(name), { force: true });
+    return { name, removed, deviceId: registration?.deviceId, serverDeleted };
+}
+export async function agentLog(nameInput, lines, deps = {}) {
+    const run = deps.docker ?? runDocker;
+    const name = validateBoxName(nameInput);
+    const out = await docker(run, [
+        "exec",
+        containerName(name),
+        "tail",
+        "-n",
+        String(lines),
+        AGENT_LOG,
+    ]);
+    return { name, lines: out.split("\n").filter(Boolean) };
+}
+export function agentLogFollowArgs(name, lines) {
+    return [
+        "exec",
+        containerName(validateBoxName(name)),
+        "tail",
+        "-n",
+        String(lines),
+        "-f",
+        AGENT_LOG,
+    ];
+}

package/dist/commands/device/testbox/box.test.d.ts

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