@autifyhq/aximo-cli 0.6.0 → 0.8.0

package/dist/mobile-control/mobile-errors.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { mobileErrorHint, withMobileHint } from "./mobile-errors.js";
+describe("mobileErrorHint (iOS)", () => {
+    it("guides trusting the developer cert", () => {
+        expect(mobileErrorHint("...its profile has not been explicitly trusted by the user", "ios")).toContain("VPN & Device Management");
+    });
+    it("guides setting a unique WDA bundle id when the id is taken", () => {
+        expect(mobileErrorHint('The app identifier "com.facebook.WebDriverAgentRunner.xctrunner" cannot be registered to your development team', "ios")).toContain("AXIMO_IOS_WDA_BUNDLE_ID");
+    });
+    it("guides installing the iOS platform components", () => {
+        expect(mobileErrorHint("error: iOS 26.5 is not installed. Please download", "ios")).toContain("downloadPlatform");
+    });
+    it("explains that a sideloaded .ipa must be device-signed", () => {
+        expect(mobileErrorHint("Last event ApplicationVerificationFailed", "ios")).toContain("signed for THIS device");
+    });
+    it("falls back to a general WDA hint for a bare xcodebuild failure", () => {
+        expect(mobileErrorHint("xcodebuild failed with code 65", "ios")).toContain("aximo mobile doctor");
+    });
+    it("matches a refused connection on a dynamic wdaLocalPort", () => {
+        expect(mobileErrorHint("Connection refused to port 51234", "ios")).toContain("device tunnel");
+    });
+    it("matches the driver's RemoteXPC tunnel errors", () => {
+        expect(mobileErrorHint("RemoteXPC tunnel is not available for this session", "ios")).toContain("device tunnel");
+    });
+    it("hints unlocking for a locked device but not for 'unlocked' messages", () => {
+        expect(mobileErrorHint("The device 'iPhone' is locked", "ios")).toContain("Unlock");
+        expect(mobileErrorHint("the device was not, or could not be, unlocked", "ios")).toContain("Unlock");
+        expect(mobileErrorHint("the device screen is unlocked and ready", "ios")).toBeUndefined();
+    });
+    it("returns undefined for an unrecognized message", () => {
+        expect(mobileErrorHint("some unrelated failure", "ios")).toBeUndefined();
+    });
+});
+describe("mobileErrorHint (Android)", () => {
+    it("guides uninstalling on a signature mismatch", () => {
+        expect(mobileErrorHint("Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE]", "android")).toContain("adb uninstall");
+    });
+});
+describe("withMobileHint", () => {
+    it("appends the hint to the message when one matches", () => {
+        const out = withMobileHint("Failure [INSTALL_FAILED_INSUFFICIENT_STORAGE]", "android");
+        expect(out).toContain("Failure [INSTALL_FAILED_INSUFFICIENT_STORAGE] — ");
+        expect(out).toContain("out of storage");
+    });
+    it("returns the message unchanged when nothing matches", () => {
+        expect(withMobileHint("weird error", "ios")).toBe("weird error");
+    });
+});

package/dist/mobile-control/tunnel.js

@@ -49,10 +49,43 @@ function defaultConnect(wsUrl, deviceToken) {
         timeout: 10000,
     });
 }
+// Mirrors the gateway's lock lease: a session quiet for longer than this has lost
+// its server-side lock, so a new session id is a legitimate takeover, not a stray.
+const SESSION_LEASE_MS = 25 * 60 * 1000;
 export function registerHandlers(socket, controller, installApp) {
+    // Device-side guard against interleaved sessions: the gateway announces owner
+    // changes (session_acquired/session_released) and tags each command with its
+    // session id, so commands from a session that no longer owns the device are
+    // dropped even if a gateway instance lost its in-memory lock.
+    let activeSession = null;
+    socket.on("session_acquired", (args) => {
+        const sessionId = args?.sessionId;
+        if (typeof sessionId === "string" && sessionId) {
+            activeSession = { id: sessionId, lastSeenAt: Date.now() };
+        }
+    });
+    socket.on("session_released", (args) => {
+        // Only the owner's release clears the guard; a takeover by a new session is
+        // announced via session_acquired, so an unmatched release is ignored.
+        const sessionId = args?.sessionId;
+        if (activeSession && activeSession.id === sessionId) {
+            activeSession = null;
+        }
+    });
     const on = (event, handler) => {
         socket.on(event, (rawArgs, ack) => {
-            const args = (rawArgs ?? {});
+            // Destructure the routing-only tag off a clone so the caller's payload
+            // object is never mutated.
+            const { __sessionId: sessionId, ...args } = (rawArgs ?? {});
+            if (typeof sessionId === "string" && sessionId) {
+                if (activeSession &&
+                    activeSession.id !== sessionId &&
+                    Date.now() - activeSession.lastSeenAt < SESSION_LEASE_MS) {
+                    ack?.(fail(new Error("Device is busy with another session")));
+                    return;
+                }
+                activeSession = { id: sessionId, lastSeenAt: Date.now() };
+            }
             void handler(args)
                 .then((result) => ack?.(result))
                 .catch((err) => ack?.(fail(err)));
@@ -119,6 +152,7 @@ export async function runControlTunnel(options) {
     registerHandlers(socket, options.controller, options.installApp);
     await new Promise((resolve, reject) => {
         let shuttingDown = false;
+        let serverKicks = [];
         const cleanup = () => {
             if (shuttingDown)
                 return;
@@ -126,12 +160,27 @@ export async function runControlTunnel(options) {
             socket.close();
             resolve();
         };
+        // Handshake rejections that re-trying can never fix (bad/revoked token,
+        // feature disabled). Everything else is treated as transient.
+        const isTerminalAuthError = (message) => /device token|not enabled for this organization/i.test(message);
         socket.on("connect", () => {
             console.log(`Connected to Aximo as "${options.deviceName}" (${options.wsUrl}${SOCKET_PATH})`);
+            // Once a session has been established, outlive server deploys/restarts:
+            // retry forever instead of giving up after the initial-connect budget.
+            socket.io.opts.reconnectionAttempts = Infinity;
         });
         socket.on("connect_error", (err) => {
+            if (isTerminalAuthError(err.message)) {
+                // Mark as shutting down BEFORE close(): close emits a client-initiated
+                // "disconnect" that would otherwise double-handle this terminal error.
+                shuttingDown = true;
+                socket.close();
+                reject(new Error(`Connection rejected: ${err.message}. Re-register the device with \`aximo mobile register\`.`));
+                return;
+            }
             // socket.active is false once reconnection is given up; reject so the CLI exits non-zero.
             if (!socket.active) {
+                shuttingDown = true;
                 socket.close();
                 reject(new Error(`Connection error: ${err.message}`));
                 return;
@@ -143,8 +192,30 @@ export async function runControlTunnel(options) {
             // resolved the promise, so don't report our own close as an error.
             if (shuttingDown)
                 return;
+            // A server-initiated disconnect (gateway deploy/restart kicking the socket)
+            // does NOT auto-reconnect per socket.io semantics — reconnect explicitly so
+            // a routine deploy doesn't strand the device offline. But rapid repeated
+            // kicks mean another `connect` for this device keeps displacing us (the
+            // gateway kicks the old socket on every re-registration): back off and exit
+            // instead of fighting it for the slot.
+            if (reason === "io server disconnect") {
+                const now = Date.now();
+                serverKicks = serverKicks.filter((t) => now - t < 30_000);
+                serverKicks.push(now);
+                if (serverKicks.length >= 3) {
+                    shuttingDown = true;
+                    socket.close();
+                    reject(new Error("Disconnected repeatedly by the server — another `aximo mobile connect` " +
+                        "is likely running for this device. Stop the other instance first."));
+                    return;
+                }
+                console.log("Server closed the connection (restart/deploy); reconnecting...");
+                socket.connect();
+                return;
+            }
             // socket.active is false when the disconnect is terminal (the client won't reconnect).
             if (!socket.active) {
+                shuttingDown = true;
                 socket.close();
                 reject(new Error(`Disconnected: ${reason}`));
                 return;
@@ -155,7 +226,13 @@ export async function runControlTunnel(options) {
             console.log("Server is shutting down; awaiting reconnect...");
         });
         process.on("SIGINT", () => {
-            console.log("\nDisconnecting...");
+            // Second Ctrl+C: teardown is hanging (e.g. Appium closing a session
+            // mid-build) — force-quit instead of becoming un-interruptible.
+            if (shuttingDown) {
+                console.error("Force exit.");
+                process.exit(130);
+            }
+            console.log("\nDisconnecting... (press Ctrl+C again to force quit)");
             cleanup();
         });
         process.on("SIGTERM", () => {

package/dist/mobile-control/tunnel.test.js

@@ -153,3 +153,85 @@ describe("registerHandlers", () => {
         });
     });
 });
+describe("registerHandlers session guard", () => {
+    const BUSY = { ok: false, error: "Device is busy with another session" };
+    function fire(socket, event, args) {
+        socket.handlers.get(event)?.(args);
+    }
+    it("strips __sessionId for the handler without mutating the incoming payload", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        const payload = { x: 5, y: 9, __sessionId: "s1" };
+        await expect(socket.emit("tap", payload)).resolves.toEqual({ ok: true });
+        expect(tap).toHaveBeenCalledWith(5, 9);
+        expect(payload.__sessionId).toBe("s1");
+    });
+    it("rejects a second session's command while the first is active", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s2" })).resolves.toEqual(BUSY);
+        expect(tap).toHaveBeenCalledTimes(1);
+    });
+    it("accepts a new session after session_released for the active one", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        fire(socket, "session_released", { sessionId: "s1" });
+        await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s2" })).resolves.toEqual({
+            ok: true,
+        });
+        expect(tap).toHaveBeenCalledTimes(2);
+    });
+    it("ignores session_released for a session that is not active", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        fire(socket, "session_released", { sessionId: "other" });
+        await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s2" })).resolves.toEqual(BUSY);
+        expect(tap).toHaveBeenCalledTimes(1);
+    });
+    it("ignores session_released without a sessionId (malformed release)", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        fire(socket, "session_released", {});
+        fire(socket, "session_released", { sessionId: null });
+        await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s2" })).resolves.toEqual(BUSY);
+        expect(tap).toHaveBeenCalledTimes(1);
+    });
+    it("switches owner on session_acquired and rejects the superseded session", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        fire(socket, "session_acquired", { sessionId: "s2" });
+        await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s1" })).resolves.toEqual(BUSY);
+        await expect(socket.emit("tap", { x: 5, y: 6, __sessionId: "s2" })).resolves.toEqual({
+            ok: true,
+        });
+        expect(tap).toHaveBeenCalledTimes(2);
+    });
+    it("allows takeover once the active session is idle past the lease", async () => {
+        vi.useFakeTimers();
+        try {
+            const tap = vi.fn(async () => { });
+            const socket = wire(stubController({ tap }));
+            await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+            vi.advanceTimersByTime(26 * 60 * 1000);
+            await expect(socket.emit("tap", { x: 3, y: 4, __sessionId: "s2" })).resolves.toEqual({
+                ok: true,
+            });
+            expect(tap).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("leaves untagged commands ungated (pre-tagging gateways)", async () => {
+        const tap = vi.fn(async () => { });
+        const socket = wire(stubController({ tap }));
+        await socket.emit("tap", { x: 1, y: 2, __sessionId: "s1" });
+        await expect(socket.emit("tap", { x: 3, y: 4 })).resolves.toEqual({ ok: true });
+        expect(tap).toHaveBeenCalledTimes(2);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",
@@ -38,6 +38,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "appium": "^3.5.2",
+    "applesign": "^5.0.1",
     "citty": "0.2.2",
     "socket.io-client": "^4.8.1",
     "undici": "^7.28.0",