@autifyhq/aximo-cli 0.14.0 → 0.16.0

package/dist/commands/mcp/server.test.js

@@ -24,15 +24,19 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 29 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 40 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
             expect(tools.map((t) => t.name).sort()).toEqual([
                 "aximo_get_case",
                 "aximo_get_session",
+                "aximo_wait_for_session",
+                "aximo_cancel_session",
                 "aximo_get_session_capture",
                 "aximo_get_session_snapshot",
+                "aximo_export_session_pdf",
+                "aximo_export_session_screenshots",
                 "aximo_get_session_messages",
                 "aximo_get_session_screenshots",
                 "aximo_get_session_timeline",
@@ -48,6 +52,7 @@ describe("createMcpServer wiring", () => {
                 "aximo_restore_case",
                 "aximo_delete_case",
                 "aximo_run_case",
+                "aximo_create_session",
                 "aximo_create_plan",
                 "aximo_add_case_to_plan",
                 "aximo_remove_case_from_plan",
@@ -61,6 +66,9 @@ describe("createMcpServer wiring", () => {
                 "aximo_list_plan_runs",
                 "aximo_get_plan_run",
                 "aximo_save_session_as_case",
+                "aximo_start_testbox",
+                "aximo_get_testbox",
+                "aximo_stop_testbox",
             ].sort());
             const timeline = tools.find((t) => t.name === "aximo_get_session_timeline");
             expect(timeline?.inputSchema?.required).toContain("sessionId");
@@ -88,6 +96,25 @@ describe("createMcpServer wiring", () => {
             await cleanup();
         }
     });
+    it("serves the full tool list without an API key and answers calls with the configure hint", async () => {
+        const prev = process.env["AXIMO_API_KEY"];
+        delete process.env["AXIMO_API_KEY"];
+        const { client, cleanup } = await connect();
+        try {
+            const { tools } = await client.listTools();
+            expect(tools.length).toBe(40);
+            const result = await client.callTool({ name: "aximo_list_projects", arguments: {} });
+            expect(result.isError).toBe(true);
+            const content = result.content;
+            const payload = JSON.parse(content[0].text);
+            expect(payload.error).toBe("API key not configured");
+            expect(payload.hint).toBe("Run `aximo configure`, then call the tool again.");
+        }
+        finally {
+            process.env["AXIMO_API_KEY"] = prev;
+            await cleanup();
+        }
+    });
     it("returns isError with a validation message when input fails the schema", async () => {
         const { client, cleanup } = await connect();
         try {

package/dist/commands/mcp/testbox-tools.test.d.ts

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

package/dist/commands/mcp/testbox-tools.test.js

@@ -0,0 +1,278 @@
+import { mkdirSync, mkdtempSync, rmSync, 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 "../device/paths.js";
+import { fail, fakeDocker, ok, starts } from "../device/testbox/fake-docker.js";
+import { defineTools } from "./tools.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-mcp-testbox-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_API_KEY"];
+    delete process.env["AXIMO_BASE_URL"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(join(tempHome, "testbox"), { recursive: true, force: true });
+    mkdirSync(join(tempHome, "testbox"), { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+function fakeClock() {
+    const start = 1_700_000_000_000;
+    let t = start;
+    return {
+        now: () => t,
+        sleep: async (ms) => {
+            t += ms;
+        },
+        elapsed: () => t - start,
+    };
+}
+function devices(list) {
+    server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: list })));
+}
+function seedRegistration() {
+    writeFileSync(getTestboxConfigPath("default"), JSON.stringify({
+        deviceId: "dev-1",
+        deviceToken: "tok",
+        name: "mac-testbox-abcd",
+        registeredAt: "2026-01-01T00:00:00.000Z",
+        baseUrl: TEST_BASE_URL,
+    }));
+}
+function seedState(state) {
+    writeFileSync(getTestboxStatePath("default"), JSON.stringify({ startedAt: new Date().toISOString(), pid: process.pid, ...state }));
+}
+const config = {
+    image: "ghcr.io/autifyhq/aximo-testbox:0.1.0",
+    ports: "3000",
+    blockHosts: [],
+    network: "bridge",
+    novncPort: 6080,
+    screen: "1280x720",
+};
+function runningBox(docker) {
+    docker.on(starts("inspect"), ok(`true|${config.image}|${JSON.stringify({ "aximo.testbox": "default", "aximo.testbox.config": JSON.stringify(config) })}\n`));
+}
+function toolsWithDetachedUp(docker = fakeDocker(), detachedUp = {}) {
+    const spawned = [];
+    const clock = fakeClock();
+    const deps = {
+        testbox: {
+            docker: docker.run,
+            clock,
+            spawn: (args) => {
+                spawned.push(args);
+                if (detachedUp.writesPullingState ?? true)
+                    seedState({ phase: "pulling" });
+                detachedUp.onSpawn?.();
+                return 4242;
+            },
+        },
+    };
+    const all = defineTools(deps);
+    const tool = (name) => {
+        const t = all.find((x) => x.name === name);
+        if (!t)
+            throw new Error(`tool ${name} not found`);
+        return t;
+    };
+    const payload = (result) => JSON.parse(result.content[0].text);
+    return { tool, payload, spawned, clock };
+}
+describe("aximo_start_testbox", () => {
+    it("spawns a detached up with the flags and reports the pull in progress", async () => {
+        devices([]);
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({
+            ports: "5173",
+            blockHosts: ["prod.example.com"],
+            startUrl: "http://localhost:5173/",
+            screen: "1920x1080",
+            timeoutSeconds: 5,
+        });
+        expect(spawned).toEqual([
+            [
+                "device",
+                "testbox",
+                "up",
+                "--no-wait",
+                "--name",
+                "default",
+                "--ports",
+                "5173",
+                "--block-hosts",
+                "prod.example.com",
+                "--start-url",
+                "http://localhost:5173/",
+                "--screen",
+                "1920x1080",
+            ],
+        ]);
+        expect(result.isError).toBeFalsy();
+        expect(payload(result)).toMatchObject({
+            ready: false,
+            state: "pulling",
+            hint: expect.stringContaining("aximo_get_testbox"),
+        });
+    });
+    it("does not spawn a second up while one is still running", async () => {
+        devices([]);
+        seedState({ phase: "starting" });
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 });
+        expect(spawned).toEqual([]);
+        expect(payload(result)).toMatchObject({ ready: false, state: "starting" });
+    });
+    it("forgets a previous run's error before spawning, instead of reporting it as this run's", async () => {
+        devices([]);
+        seedState({ phase: "error", pid: 1, lastError: "old failure" });
+        const { tool, payload, spawned } = toolsWithDetachedUp();
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 }));
+        expect(spawned).toHaveLength(1);
+        expect(result["state"]).toBe("pulling");
+        expect(result["lastError"]).toBeUndefined();
+    });
+    it("returns ready with the device id once the box is online", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "online" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker, {
+            writesPullingState: false,
+            onSpawn: () => runningBox(docker),
+        });
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 3 }));
+        expect(spawned).toHaveLength(1);
+        expect(result).toMatchObject({
+            ready: true,
+            state: "online",
+            container: "running",
+            agent: "running",
+            userDeviceId: "dev-1",
+            deviceName: "mac-testbox-abcd",
+            deviceStatus: "online",
+            liveViewUrl: "http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale&password=pw123",
+            ports: [{ port: 3000, reachable: true }],
+            hint: expect.stringContaining("userDeviceId"),
+        });
+    });
+    it("does not touch a box that is already online unless asked to reconfigure it", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "online" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker, { writesPullingState: false });
+        expect(payload(await tool("aximo_start_testbox").handler({}))["ready"]).toBe(true);
+        expect(spawned).toEqual([]);
+        await tool("aximo_start_testbox").handler({ ports: "5173" });
+        expect(spawned).toHaveLength(1);
+    });
+    it("returns within timeoutSeconds even when the detached up never writes state", async () => {
+        devices([]);
+        const { tool, payload, clock } = toolsWithDetachedUp(fakeDocker(), {
+            writesPullingState: false,
+        });
+        const result = payload(await tool("aximo_start_testbox").handler({ timeoutSeconds: 7 }));
+        expect(result["state"]).toBe("down");
+        expect(clock.elapsed()).toBeLessThanOrEqual(7_000 + 3_000);
+    });
+    it("is a tool error with the install link when Docker is missing", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        docker.on(starts("info"), () => {
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        const { tool, payload, spawned } = toolsWithDetachedUp(docker);
+        const result = await tool("aximo_start_testbox").handler({});
+        expect(result.isError).toBe(true);
+        expect(payload(result)["error"]).toContain("https://docs.docker.com/get-docker/");
+        expect(spawned).toEqual([]);
+    });
+    it("rejects a name that is not a valid box name", async () => {
+        devices([]);
+        const { tool } = toolsWithDetachedUp();
+        const result = await tool("aximo_start_testbox").handler({ name: "../x" });
+        expect(result.isError).toBe(true);
+    });
+});
+describe("aximo_get_testbox and aximo_stop_testbox", () => {
+    it("get reports down with the start hint when nothing runs", async () => {
+        devices([]);
+        const { tool, payload } = toolsWithDetachedUp();
+        expect(payload(await tool("aximo_get_testbox").handler({}))).toEqual({
+            ready: false,
+            state: "down",
+            name: "default",
+            container: "absent",
+            hint: "Not running. Call aximo_start_testbox.",
+        });
+    });
+    it("get waits up to timeoutSeconds while the box is still connecting", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "offline" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload, clock } = toolsWithDetachedUp(docker);
+        const result = payload(await tool("aximo_get_testbox").handler({ timeoutSeconds: 7 }));
+        expect(result).toMatchObject({
+            ready: false,
+            state: "connecting",
+            hint: expect.stringContaining("aximo_get_testbox"),
+        });
+        expect(clock.elapsed()).toBe(6_000);
+    });
+    it("get surfaces a failed detached up as an error with its cause", async () => {
+        devices([]);
+        seedState({
+            phase: "error",
+            pid: 1,
+            lastError: "Could not pull ghcr.io/autifyhq/aximo-testbox:0.1.0: denied",
+        });
+        const { tool, payload } = toolsWithDetachedUp();
+        expect(payload(await tool("aximo_get_testbox").handler({}))).toMatchObject({
+            state: "error",
+            lastError: expect.stringContaining("Could not pull"),
+            hint: expect.stringContaining("aximo_start_testbox"),
+        });
+    });
+    it("get passes the agent's last message through", async () => {
+        devices([{ id: "dev-1", name: "mac-testbox-abcd", status: "offline" }]);
+        seedRegistration();
+        const docker = fakeDocker();
+        runningBox(docker);
+        docker.on((args) => args.includes("cat") && args.includes("/run/aximo/agent.status"), ok("Auth failed. Re-register with: aximo device register\n"));
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        expect(payload(await tool("aximo_get_testbox").handler({}))["agentStatus"]).toContain("Auth failed");
+    });
+    it("stop removes the container and nothing else", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        runningBox(docker);
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        expect(payload(await tool("aximo_stop_testbox").handler({}))).toEqual({
+            name: "default",
+            removed: true,
+        });
+        expect(docker.find("rm", "-f", "aximo-testbox")).toHaveLength(1);
+        expect(docker.find("volume")).toHaveLength(0);
+    });
+    it("maps a Docker failure to a tool error", async () => {
+        devices([]);
+        const docker = fakeDocker();
+        runningBox(docker);
+        docker.on(starts("rm"), fail("permission denied"));
+        const { tool, payload } = toolsWithDetachedUp(docker);
+        const result = await tool("aximo_stop_testbox").handler({});
+        expect(result.isError).toBe(true);
+        expect(payload(result)["error"]).toContain("permission denied");
+    });
+});

package/dist/commands/mcp/tools.d.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { type ClientDeps } from "../../client.js";
+import { type TestboxDeps } from "../device/testbox/box.js";
+import { type DetachedSpawner } from "../device/testbox/self-command.js";
 interface ToolResult {
     content: Array<{
         type: "text";
@@ -7,6 +9,11 @@ interface ToolResult {
     }>;
     isError?: boolean;
 }
+export interface ToolDeps extends ClientDeps {
+    testbox?: TestboxDeps & {
+        spawn?: DetachedSpawner;
+    };
+}
 export interface Tool<TInput extends z.ZodRawShape = z.ZodRawShape> {
     name: string;
     title: string;
@@ -14,5 +21,5 @@ export interface Tool<TInput extends z.ZodRawShape = z.ZodRawShape> {
     inputSchema: TInput;
     handler: (input: z.infer<z.ZodObject<TInput>>) => Promise<ToolResult>;
 }
-export declare function defineTools(deps?: ClientDeps): Tool[];
+export declare function defineTools(deps?: ToolDeps): Tool[];
 export {};