@autifyhq/aximo-cli 0.15.0 → 0.17.0

package/dist/commands/device/testbox/container.d.ts

@@ -0,0 +1,58 @@
+import { type DockerRunner } from "./docker.js";
+export declare const DEFAULT_BOX_NAME = "default";
+export declare const TESTBOX_IMAGE = "ghcr.io/autifyhq/aximo-testbox";
+export declare const TESTBOX_IMAGE_TAG = "0.1.1";
+export declare const DEFAULT_NOVNC_PORT = 6080;
+export declare const DEFAULT_SCREEN = "1280x720";
+export declare const RUN_DIR = "/run/aximo";
+export declare const AGENT_LOG = "/var/log/aximo/agent.log";
+export declare const MAX_PORTS = 32;
+export declare const BOX_NAME_RE: RegExp;
+export interface TestboxConfig {
+    image: string;
+    ports: string;
+    blockHosts: string[];
+    startUrl: string | undefined;
+    network: "bridge" | "host";
+    novncPort: number;
+    screen: string;
+}
+export declare function validateBoxName(name: string | undefined): string;
+export declare function containerName(name: string): string;
+export declare function profileVolume(name: string): string;
+export declare function legacyVolumes(name: string): string[];
+/** Flag, then AXIMO_TESTBOX_IMAGE, then the running box, then the published tag. */
+export declare function resolveImage(explicit?: string, previous?: string): string;
+export declare function parsePorts(spec: string): number[];
+/** The live view's own ports cannot also be mirrored into the box. */
+export declare function reservedPorts(cfg: TestboxConfig): number[];
+export declare function validateScreen(spec: string): string;
+export declare function validateNovncPort(port: number, network: TestboxConfig["network"]): void;
+export interface ContainerInfo {
+    running: boolean;
+    image: string;
+    config: TestboxConfig | null;
+}
+export declare function inspectContainer(run: DockerRunner, container: string): Promise<ContainerInfo | null>;
+export declare function nextNovncPort(run: DockerRunner): Promise<number>;
+export declare function runArgs(name: string, cfg: TestboxConfig): string[];
+export declare function ensureImage(run: DockerRunner, image: string): Promise<void>;
+export declare function stopAgent(run: DockerRunner, container: string): Promise<void>;
+export declare function removeContainer(run: DockerRunner, container: string): Promise<void>;
+export declare function containerLog(run: DockerRunner, container: string, lines: number): Promise<string>;
+export declare function relayUrl(baseUrl: string, network: TestboxConfig["network"]): string;
+export declare function readInContainer(run: DockerRunner, container: string, path: string): Promise<string | null>;
+export interface AgentIdentity {
+    deviceToken: string;
+    deviceName: string;
+    baseUrl: string;
+}
+export declare function injectAgent(run: DockerRunner, container: string, identity: AgentIdentity, network: TestboxConfig["network"], agent: {
+    scriptPath: string;
+    requirementsPath: string;
+}): Promise<void>;
+export declare function liveViewUrl(run: DockerRunner, container: string, novncPort: number): Promise<string | undefined>;
+export declare function probePorts(run: DockerRunner, container: string, spec: string): Promise<{
+    port: number;
+    reachable: boolean;
+}[]>;

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

@@ -0,0 +1,289 @@
+import { existsSync, readFileSync } from "node:fs";
+import { arch } from "node:os";
+import { join } from "node:path";
+import { getOfflineDir } from "../../../desktop-server/offline.js";
+import { DockerCommandError, docker } from "./docker.js";
+import { TestboxError } from "./errors.js";
+export const DEFAULT_BOX_NAME = "default";
+export const TESTBOX_IMAGE = "ghcr.io/autifyhq/aximo-testbox";
+// Must match testbox/image/TAG; the image is released on its own cadence.
+export const TESTBOX_IMAGE_TAG = "0.1.1";
+export const DEFAULT_NOVNC_PORT = 6080;
+// The agent reads screenshots at 1000 px wide at most, so a bigger screen only
+// shrinks the text it sees; 1280x720 is also what Aximo's cloud desktop runs.
+export const DEFAULT_SCREEN = "1280x720";
+export const RUN_DIR = "/run/aximo";
+export const AGENT_LOG = "/var/log/aximo/agent.log";
+const BASE_DISPLAY = 99;
+const BASE_VNC_PORT = 5900;
+// Each mirrored port is a supervised socat; an open-ended range would be a fork bomb.
+export const MAX_PORTS = 32;
+const PIDS_LIMIT = 2048;
+const LABEL = "aximo.testbox";
+const CONFIG_LABEL = "aximo.testbox.config";
+// The box name becomes a host file name, a container name and a volume name.
+export const BOX_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+export function validateBoxName(name) {
+    const value = name ?? DEFAULT_BOX_NAME;
+    if (!BOX_NAME_RE.test(value)) {
+        throw new TestboxError(`Invalid testbox name "${value}": use letters, digits, '.', '_' or '-' (max 64 chars)`);
+    }
+    return value;
+}
+export function containerName(name) {
+    return name === DEFAULT_BOX_NAME ? "aximo-testbox" : `aximo-testbox-${name}`;
+}
+export function profileVolume(name) {
+    return `${containerName(name)}-profile`;
+}
+// The Power's script kept the API key and an npm cache in these; they go when
+// the box is recreated or pruned.
+export function legacyVolumes(name) {
+    return [`${containerName(name)}-aximo`, `${containerName(name)}-npm`];
+}
+/** Flag, then AXIMO_TESTBOX_IMAGE, then the running box, then the published tag. */
+export function resolveImage(explicit, previous) {
+    return (explicit ??
+        process.env["AXIMO_TESTBOX_IMAGE"] ??
+        previous ??
+        `${TESTBOX_IMAGE}:${TESTBOX_IMAGE_TAG}`);
+}
+export function parsePorts(spec) {
+    const ports = [];
+    for (const item of spec.split(",")) {
+        const part = item.trim();
+        if (!part)
+            continue;
+        const match = /^(\d{1,5})(?:-(\d{1,5}))?$/.exec(part);
+        const lo = match ? Number(match[1]) : 0;
+        const hi = match ? Number(match[2] ?? match[1]) : 0;
+        if (!match || lo < 1 || hi > 65535 || hi < lo) {
+            throw new TestboxError(`Invalid port spec "${spec}": use e.g. 3000 or 3000,5173-5180`);
+        }
+        for (let p = lo; p <= hi; p++)
+            ports.push(p);
+    }
+    if (ports.length === 0)
+        throw new TestboxError("At least one port is required");
+    if (ports.length > MAX_PORTS) {
+        throw new TestboxError(`Too many ports (${ports.length}); the box mirrors at most ${MAX_PORTS}`);
+    }
+    return ports;
+}
+/** The live view's own ports cannot also be mirrored into the box. */
+export function reservedPorts(cfg) {
+    const offset = cfg.novncPort - DEFAULT_NOVNC_PORT;
+    return cfg.network === "host"
+        ? [cfg.novncPort, BASE_VNC_PORT + offset]
+        : [cfg.novncPort, BASE_VNC_PORT];
+}
+export function validateScreen(spec) {
+    const match = /^(\d{3,4})x(\d{3,4})$/.exec(spec.trim());
+    const width = match ? Number(match[1]) : 0;
+    const height = match ? Number(match[2]) : 0;
+    if (!match || width < 800 || width > 3840 || height < 600 || height > 2160) {
+        throw new TestboxError(`Invalid screen "${spec}": use WIDTHxHEIGHT between 800x600 and 3840x2160, e.g. 1280x720 or 1920x1080`);
+    }
+    return `${width}x${height}`;
+}
+export function validateNovncPort(port, network) {
+    // In host mode the X display and VNC port are derived from this number.
+    const min = network === "host" ? DEFAULT_NOVNC_PORT : 1024;
+    if (!Number.isInteger(port) || port < min || port > 65535) {
+        throw new TestboxError(`Invalid noVNC port ${port}: use an integer between ${min} and 65535`);
+    }
+}
+export async function inspectContainer(run, container) {
+    const result = await run([
+        "inspect",
+        "-f",
+        "{{.State.Running}}|{{.Config.Image}}|{{json .Config.Labels}}",
+        container,
+    ]);
+    if (result.code !== 0) {
+        // Only a confirmed missing container is "absent"; a daemon that is down
+        // or refusing the socket must not read as a stopped box.
+        if (/no such (object|container)/i.test(result.stderr))
+            return null;
+        throw new DockerCommandError(["inspect", container], result);
+    }
+    const [running = "", image = "", ...rest] = result.stdout.trim().split("|");
+    let config = null;
+    try {
+        const labels = JSON.parse(rest.join("|") || "{}") ?? {};
+        const raw = labels[CONFIG_LABEL];
+        config = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        config = null;
+    }
+    return { running: running === "true", image, config };
+}
+export async function nextNovncPort(run) {
+    const out = await docker(run, [
+        "ps",
+        "-a",
+        "--filter",
+        `label=${LABEL}`,
+        "--format",
+        `{{.Label "${CONFIG_LABEL}"}}`,
+    ]);
+    const used = new Set();
+    for (const line of out.split("\n")) {
+        try {
+            const cfg = JSON.parse(line);
+            if (typeof cfg.novncPort === "number")
+                used.add(cfg.novncPort);
+        }
+        catch {
+            // not a testbox container
+        }
+    }
+    let port = DEFAULT_NOVNC_PORT;
+    while (used.has(port))
+        port += 1;
+    return port;
+}
+export function runArgs(name, cfg) {
+    const offset = cfg.novncPort - DEFAULT_NOVNC_PORT;
+    const env = {
+        AXIMO_TESTBOX_PORTS: cfg.ports,
+        AXIMO_TESTBOX_NETWORK: cfg.network,
+        AXIMO_TESTBOX_NOVNC_PORT: String(cfg.novncPort),
+        AXIMO_TESTBOX_SCREEN: cfg.screen,
+        AXIMO_TESTBOX_BLOCK_HOSTS: cfg.blockHosts.join(","),
+    };
+    if (cfg.startUrl)
+        env["AXIMO_TESTBOX_START_URL"] = cfg.startUrl;
+    const args = [
+        "run",
+        "-d",
+        "--init",
+        "--name",
+        containerName(name),
+        "--label",
+        `${LABEL}=${name}`,
+        "--label",
+        `${CONFIG_LABEL}=${JSON.stringify(cfg)}`,
+        "--cap-drop",
+        "ALL",
+        ...["CHOWN", "SETUID", "SETGID", "DAC_OVERRIDE", "FOWNER"].flatMap((c) => ["--cap-add", c]),
+        "--security-opt",
+        "no-new-privileges",
+        "--pids-limit",
+        String(PIDS_LIMIT),
+        "--shm-size=2g",
+        "--tmpfs",
+        `${RUN_DIR}:rw,size=64m`,
+        "-v",
+        `${profileVolume(name)}:/profile`,
+    ];
+    if (cfg.network === "host") {
+        // Every box on a host network shares one X socket namespace and one port
+        // space, so each takes its own display and ports.
+        env["AXIMO_TESTBOX_DISPLAY"] = String(BASE_DISPLAY + 1 + offset);
+        env["AXIMO_TESTBOX_VNC_PORT"] = String(BASE_VNC_PORT + offset);
+        args.push("--network", "host");
+    }
+    else {
+        args.push("--add-host=host.docker.internal:host-gateway", "-p", `127.0.0.1:${cfg.novncPort}:${cfg.novncPort}`);
+    }
+    for (const [k, v] of Object.entries(env))
+        args.push("-e", `${k}=${v}`);
+    args.push(cfg.image);
+    return args;
+}
+function offlineImageTarball() {
+    const dir = getOfflineDir();
+    if (!dir)
+        return undefined;
+    const platform = arch() === "arm64" ? "linux-arm64" : "linux-amd64";
+    const path = join(dir, "testbox", `aximo-testbox-${platform}.tar`);
+    return existsSync(path) ? path : undefined;
+}
+export async function ensureImage(run, image) {
+    if ((await run(["image", "inspect", image])).code === 0)
+        return;
+    const tarball = offlineImageTarball();
+    if (tarball) {
+        await docker(run, ["load", "-i", tarball], { timeoutMs: 0 });
+        return;
+    }
+    const result = await run(["pull", image], { timeoutMs: 0 });
+    if (result.code !== 0) {
+        throw new TestboxError(`Could not pull ${image}: ${result.stderr.trim()}. Set AXIMO_TESTBOX_IMAGE to a mirror, or stage a tarball under $AXIMO_OFFLINE_DIR/testbox/.`, true);
+    }
+}
+export async function stopAgent(run, container) {
+    await run(["exec", container, "pkill", "-INT", "-f", "remote.py"]);
+}
+export async function removeContainer(run, container) {
+    await stopAgent(run, container);
+    await docker(run, ["rm", "-f", container]);
+}
+export async function containerLog(run, container, lines) {
+    const result = await run(["logs", "--tail", String(lines), container]);
+    return `${result.stdout}${result.stderr}`.trim();
+}
+export function relayUrl(baseUrl, network) {
+    const url = new URL(baseUrl);
+    // A dev server on the laptop is only reachable from the bridge by this name.
+    if (network === "bridge" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
+        url.hostname = "host.docker.internal";
+    }
+    return `${url.toString().replace(/\/+$/, "").replace(/^http/, "ws")}/devices/tunnel`;
+}
+export async function readInContainer(run, container, path) {
+    const result = await run(["exec", container, "cat", path]);
+    return result.code === 0 ? result.stdout : null;
+}
+async function writeInContainer(run, container, path, content, mode) {
+    await docker(run, ["exec", "-i", container, "sh", "-c", `umask ${mode} && cat > '${path}'`], {
+        input: content,
+    });
+}
+// Everything the agent needs goes in over stdin: nothing lands in the image,
+// `docker inspect`, argv or a volume. `docker cp` cannot write into a tmpfs.
+export async function injectAgent(run, container, identity, network, agent) {
+    await writeInContainer(run, container, `${RUN_DIR}/requirements.txt`, readFileSync(agent.requirementsPath, "utf-8"), "022");
+    await writeInContainer(run, container, `${RUN_DIR}/remote.py`, readFileSync(agent.scriptPath, "utf-8"), "022");
+    const gateway = relayUrl(identity.baseUrl, network);
+    const env = [
+        `GATEWAY_URL=${gateway}`,
+        `RELAY_URL=${gateway}`,
+        `DEVICE_TOKEN=${identity.deviceToken}`,
+        `DEVICE_NAME=${identity.deviceName}`,
+        "",
+    ].join("\n");
+    const current = await readInContainer(run, container, `${RUN_DIR}/agent.env`);
+    if (current === env)
+        return;
+    await writeInContainer(run, container, `${RUN_DIR}/agent.env`, env, "077");
+    // The supervisor relaunches the agent with the new env.
+    if (current !== null)
+        await stopAgent(run, container);
+}
+export async function liveViewUrl(run, container, novncPort) {
+    const password = await readInContainer(run, container, "/profile/.vncpass");
+    if (password === null)
+        return undefined;
+    return `http://127.0.0.1:${novncPort}/vnc.html?autoconnect=1&resize=scale&password=${password.trim()}`;
+}
+export async function probePorts(run, container, spec) {
+    return Promise.all(parsePorts(spec)
+        .slice(0, 10)
+        .map(async (port) => {
+        const result = await run([
+            "exec",
+            container,
+            "curl",
+            "-s",
+            "-o",
+            "/dev/null",
+            "--max-time",
+            "3",
+            `http://127.0.0.1:${port}/`,
+        ], { timeoutMs: 5_000 });
+        return { port, reachable: result.code === 0 };
+    }));
+}

package/dist/commands/device/testbox/docker.d.ts

@@ -0,0 +1,31 @@
+export interface DockerResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface DockerRunOptions {
+    /** Piped to the child's stdin and closed; how secrets reach the container. */
+    input?: string;
+    /** 0 disables the limit (pulls); everything else must not hang an MCP call. */
+    timeoutMs?: number;
+}
+export declare const DEFAULT_DOCKER_TIMEOUT_MS = 60000;
+export type DockerRunner = (args: string[], opts?: DockerRunOptions) => Promise<DockerResult>;
+export declare const createDockerRunner: (binary: string) => DockerRunner;
+export declare const runDocker: DockerRunner;
+export declare class DockerCommandError extends Error {
+    constructor(args: string[], result: DockerResult);
+}
+export declare function docker(run: DockerRunner, args: string[], opts?: DockerRunOptions): Promise<string>;
+export declare const DOCKER_INSTALL_URL = "https://docs.docker.com/get-docker/";
+export interface DockerInfo {
+    desktop: boolean;
+    rootless: boolean;
+}
+export interface DockerProblem {
+    kind: "missing" | "unreachable" | "denied";
+    message: string;
+}
+export declare function isDockerProblem(value: DockerInfo | DockerProblem): value is DockerProblem;
+export declare function preflightDocker(run: DockerRunner): Promise<DockerInfo | DockerProblem>;

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

@@ -0,0 +1,78 @@
+import { spawn } from "node:child_process";
+import { TestboxError } from "./errors.js";
+export const DEFAULT_DOCKER_TIMEOUT_MS = 60_000;
+// Explicit argv, no shell. Rejects only when the binary cannot be started
+// (ENOENT); a non-zero exit is a result the caller inspects.
+export const createDockerRunner = (binary) => (args, opts = {}) => new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        timeout: opts.timeoutMs ?? DEFAULT_DOCKER_TIMEOUT_MS,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf-8").on("data", (chunk) => (stdout += chunk));
+    child.stderr.setEncoding("utf-8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", (err) => {
+        // Every command, not only the preflighted ones, should say how to install Docker.
+        reject(err.code === "ENOENT"
+            ? Object.assign(new TestboxError(DOCKER_MISSING_MESSAGE), { code: "ENOENT" })
+            : err);
+    });
+    child.on("close", (code, signal) => {
+        resolve({ code, stdout, stderr, timedOut: code === null && signal !== null });
+    });
+    child.stdin.on("error", () => { });
+    child.stdin.end(opts.input ?? "");
+});
+export const runDocker = createDockerRunner("docker");
+export class DockerCommandError extends Error {
+    constructor(args, result) {
+        const detail = result.timedOut
+            ? "timed out"
+            : result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`;
+        super(`docker ${args.slice(0, 2).join(" ")} failed: ${detail}`);
+    }
+}
+export async function docker(run, args, opts) {
+    const result = await run(args, opts);
+    if (result.code !== 0)
+        throw new DockerCommandError(args, result);
+    return result.stdout;
+}
+export const DOCKER_INSTALL_URL = "https://docs.docker.com/get-docker/";
+const DOCKER_MISSING_MESSAGE = `Docker is not installed. Install Docker Desktop (macOS, Windows) or Docker Engine (Linux): ${DOCKER_INSTALL_URL}`;
+const PREFLIGHT_TIMEOUT_MS = 10_000;
+export function isDockerProblem(value) {
+    return "kind" in value;
+}
+// Three different situations hide behind a failing `docker info`, and each has
+// a different fix, so the user gets the one that applies.
+export async function preflightDocker(run) {
+    let result;
+    try {
+        result = await run(["info", "-f", "{{.OperatingSystem}}|{{json .SecurityOptions}}"], {
+            timeoutMs: PREFLIGHT_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { kind: "missing", message: DOCKER_MISSING_MESSAGE };
+        }
+        throw err;
+    }
+    if (result.code === 0) {
+        const [os = "", security = ""] = result.stdout.trim().split("|");
+        return { desktop: /desktop/i.test(os), rootless: security.includes("name=rootless") };
+    }
+    if (/permission denied/i.test(result.stderr)) {
+        return {
+            kind: "denied",
+            message: "Docker refused the connection (permission denied). Add your user to the docker group (sudo usermod -aG docker $USER) and log in again, or use Docker Desktop.",
+        };
+    }
+    return {
+        kind: "unreachable",
+        message: "Docker is installed but the daemon is not reachable. Start Docker Desktop, or on Linux: sudo systemctl start docker",
+    };
+}

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

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

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

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { createDockerRunner, DOCKER_INSTALL_URL, DockerCommandError, docker, isDockerProblem, preflightDocker, } from "./docker.js";
+function runner(result) {
+    return async () => ({ code: 0, stdout: "", stderr: "", timedOut: false, ...result });
+}
+describe("preflightDocker", () => {
+    it("reports a missing binary with the install link", async () => {
+        const missing = async () => {
+            throw Object.assign(new Error("spawn docker ENOENT"), { code: "ENOENT" });
+        };
+        const info = await preflightDocker(missing);
+        expect(isDockerProblem(info) && info.kind).toBe("missing");
+        expect(isDockerProblem(info) && info.message).toContain(DOCKER_INSTALL_URL);
+    });
+    it("rethrows spawn failures that are not ENOENT", async () => {
+        const broken = async () => {
+            throw Object.assign(new Error("EACCES"), { code: "EACCES" });
+        };
+        await expect(preflightDocker(broken)).rejects.toThrow("EACCES");
+    });
+    it("distinguishes a socket permission problem from a stopped daemon", async () => {
+        const denied = await preflightDocker(runner({ code: 1, stderr: "permission denied while trying to connect to the Docker daemon" }));
+        expect(isDockerProblem(denied) && denied.kind).toBe("denied");
+        expect(isDockerProblem(denied) && denied.message).toContain("docker group");
+        const stopped = await preflightDocker(runner({
+            code: 1,
+            stderr: "Cannot connect to the Docker daemon. Is the docker daemon running?",
+        }));
+        expect(isDockerProblem(stopped) && stopped.kind).toBe("unreachable");
+        const hung = await preflightDocker(runner({ code: null, timedOut: true }));
+        expect(isDockerProblem(hung) && hung.kind).toBe("unreachable");
+    });
+    it("detects Docker Desktop and rootless engines", async () => {
+        const desktop = await preflightDocker(runner({ stdout: 'Docker Desktop|["name=seccomp"]\n' }));
+        expect(desktop).toEqual({ desktop: true, rootless: false });
+        const rootless = await preflightDocker(runner({ stdout: 'Ubuntu 24.04|["name=rootless","name=seccomp"]\n' }));
+        expect(rootless).toEqual({ desktop: false, rootless: true });
+    });
+});
+describe("docker", () => {
+    it("returns stdout on success and throws the stderr on failure", async () => {
+        await expect(docker(runner({ stdout: "abc\n" }), ["ps"])).resolves.toBe("abc\n");
+        await expect(docker(runner({ code: 125, stderr: "no such container" }), ["rm", "-f", "x"])).rejects.toThrow(new DockerCommandError(["rm", "-f", "x"], {
+            code: 125,
+            stdout: "",
+            stderr: "no such container",
+            timedOut: false,
+        }));
+        await expect(docker(runner({ code: null, timedOut: true }), ["pull", "img"])).rejects.toThrow("docker pull img failed: timed out");
+    });
+});
+describe("createDockerRunner", () => {
+    const node = createDockerRunner(process.execPath);
+    it("captures exit code, stdout and stderr without a shell", async () => {
+        const result = await node([
+            "-e",
+            "process.stdout.write('out'); process.stderr.write('err'); process.exit(3)",
+        ]);
+        expect(result).toEqual({ code: 3, stdout: "out", stderr: "err", timedOut: false });
+    });
+    it("pipes input to stdin and closes it", async () => {
+        const result = await node(["-e", "process.stdin.pipe(process.stdout)"], { input: "secret\n" });
+        expect(result.stdout).toBe("secret\n");
+    });
+    it("applies a default time limit so a stuck daemon cannot hang a call", async () => {
+        const { DEFAULT_DOCKER_TIMEOUT_MS } = await import("./docker.js");
+        expect(DEFAULT_DOCKER_TIMEOUT_MS).toBe(60_000);
+        const result = await node(["-e", "setTimeout(() => {}, 30000)"], { timeoutMs: 200 });
+        expect(result.timedOut).toBe(true);
+    });
+    it("kills a hung command after timeoutMs and flags it", async () => {
+        const result = await node(["-e", "setTimeout(() => {}, 30000)"], { timeoutMs: 200 });
+        expect(result.timedOut).toBe(true);
+        expect(result.code).toBeNull();
+    });
+    it("rejects a missing binary with the install message, keeping the ENOENT code", async () => {
+        await expect(createDockerRunner("aximo-no-such-binary")(["info"])).rejects.toMatchObject({
+            code: "ENOENT",
+            message: expect.stringContaining(DOCKER_INSTALL_URL),
+        });
+    });
+});

package/dist/commands/device/testbox/down.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("citty").CommandDef<{
+    readonly name: {
+        readonly type: "string";
+        readonly description: "Box name when running more than one (default: the single default box)";
+    };
+}>;
+export default _default;

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

@@ -0,0 +1,14 @@
+import { defineCommand } from "citty";
+import { printResult } from "../../../output.js";
+import { downTestbox } from "./box.js";
+import { nameArg, toEnvelope } from "./result.js";
+export default defineCommand({
+    meta: {
+        name: "down",
+        description: "Stop and remove the container; keeps the browser profile and the device registration",
+    },
+    args: { ...nameArg },
+    async run({ args }) {
+        printResult(await toEnvelope(() => downTestbox(args.name)));
+    },
+});

package/dist/commands/device/testbox/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class TestboxError extends Error {
+    readonly retryable: boolean;
+    constructor(message: string, retryable?: boolean);
+}

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

@@ -0,0 +1,7 @@
+export class TestboxError extends Error {
+    retryable;
+    constructor(message, retryable = false) {
+        super(message);
+        this.retryable = retryable;
+    }
+}

package/dist/commands/device/testbox/fake-docker.d.ts

@@ -0,0 +1,25 @@
+import type { DockerResult, DockerRunOptions, DockerRunner } from "./docker.js";
+type Reply = Partial<DockerResult> | ((args: string[], opts?: DockerRunOptions) => Partial<DockerResult>);
+export interface Rule {
+    match: (args: string[]) => boolean;
+    reply: Reply;
+}
+export interface FakeDocker {
+    run: DockerRunner;
+    calls: {
+        args: string[];
+        input?: string;
+    }[];
+    /** Prepend a rule; the newest rule wins. */
+    on(match: Rule["match"], reply: Reply): void;
+    find(...prefix: string[]): {
+        args: string[];
+        input?: string;
+    }[];
+}
+export declare const starts: (...prefix: string[]) => (args: string[]) => boolean;
+export declare const has: (...tokens: string[]) => (args: string[]) => boolean;
+export declare const ok: (stdout?: string) => Partial<DockerResult>;
+export declare const fail: (stderr?: string) => Partial<DockerResult>;
+export declare function fakeDocker(): FakeDocker;
+export {};

package/dist/commands/device/testbox/fake-docker.js

@@ -0,0 +1,35 @@
+export const starts = (...prefix) => (args) => prefix.every((p, i) => args[i] === p);
+export const has = (...tokens) => (args) => tokens.every((t) => args.includes(t));
+export const ok = (stdout = "") => ({ code: 0, stdout });
+export const fail = (stderr = "error") => ({ code: 1, stderr });
+// A Docker Desktop engine with no testbox yet: the image must be pulled, the
+// container does not exist, and the box's live-view password is "pw123".
+export function fakeDocker() {
+    const rules = [
+        { match: starts("info"), reply: ok('Docker Desktop|["name=seccomp"]\n') },
+        { match: starts("image", "inspect"), reply: fail("No such image") },
+        { match: starts("inspect"), reply: fail("No such object") },
+        { match: starts("ps"), reply: ok("") },
+        { match: has("exec", "cat", "/profile/.vncpass"), reply: ok("pw123\n") },
+        { match: has("exec", "cat", "/run/aximo/agent.env"), reply: fail("No such file") },
+        { match: has("exec", "cat", "/run/aximo/agent.status"), reply: fail("No such file") },
+        { match: has("exec", "pgrep"), reply: ok("42\n") },
+    ];
+    const calls = [];
+    const run = async (args, opts) => {
+        calls.push({ args, ...(opts?.input !== undefined ? { input: opts.input } : {}) });
+        const rule = rules.find((r) => r.match(args));
+        const reply = rule
+            ? typeof rule.reply === "function"
+                ? rule.reply(args, opts)
+                : rule.reply
+            : {};
+        return { code: 0, stdout: "", stderr: "", timedOut: false, ...reply };
+    };
+    return {
+        run,
+        calls,
+        on: (match, reply) => rules.unshift({ match, reply }),
+        find: (...prefix) => calls.filter((c) => starts(...prefix)(c.args)),
+    };
+}

package/dist/commands/device/testbox/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("citty").CommandDef<import("citty").ArgsDef>;
+export default _default;

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

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+export default defineCommand({
+    meta: {
+        name: "testbox",
+        description: "A sandboxed Chromium in Docker, registered as a local device, so tests of an app on localhost never touch your screen. macOS and Linux; Windows untested.",
+    },
+    subCommands: {
+        up: () => import("./up.js").then((m) => m.default),
+        status: () => import("./status.js").then((m) => m.default),
+        url: () => import("./url.js").then((m) => m.default),
+        logs: () => import("./logs.js").then((m) => m.default),
+        down: () => import("./down.js").then((m) => m.default),
+        reset: () => import("./reset.js").then((m) => m.default),
+        prune: () => import("./prune.js").then((m) => m.default),
+    },
+});