@autifyhq/aximo-cli 0.5.0 → 0.7.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.d.ts

@@ -5,7 +5,11 @@ export interface RunControlTunnelOptions {
     deviceToken: string;
     deviceName: string;
     controller: MobileController;
+    /** Installs the app under test on the device (fetch by upload id -> adb/idb install). */
+    installApp?: (args: {
+        uploadId: string;
+    }) => Promise<void>;
     connect?: (wsUrl: string, deviceToken: string) => Socket;
 }
-export declare function registerHandlers(socket: Socket, controller: MobileController): void;
+export declare function registerHandlers(socket: Socket, controller: MobileController, installApp?: RunControlTunnelOptions["installApp"]): void;
 export declare function runControlTunnel(options: RunControlTunnelOptions): Promise<void>;

package/dist/mobile-control/tunnel.js

@@ -49,7 +49,7 @@ function defaultConnect(wsUrl, deviceToken) {
         timeout: 10000,
     });
 }
-export function registerHandlers(socket, controller) {
+export function registerHandlers(socket, controller, installApp) {
     const on = (event, handler) => {
         socket.on(event, (rawArgs, ack) => {
             const args = (rawArgs ?? {});
@@ -100,6 +100,15 @@ export function registerHandlers(socket, controller) {
     on("input", async (args) => asActionResult(await controller.typeText(String(args["text"] ?? ""))));
     on("key", async (args) => asActionResult(await controller.pressKey(String(args["key"] ?? ""))));
     on("launch_app", async (args) => asActionResult(await controller.launchApp(String(args["app"] ?? ""))));
+    if (installApp) {
+        on("install_app", async (args) => {
+            const uploadId = String(args["uploadId"] ?? "");
+            if (!uploadId)
+                return { ok: false, error: "install_app requires an uploadId" };
+            await installApp({ uploadId });
+            return ok();
+        });
+    }
     on("find_element", async (args) => asActionResult(await controller.findElement(String(args["text"] ?? ""))));
     on("clear_text", async () => asActionResult(await controller.clearText()));
     on("hide_keyboard", async () => asActionResult(await controller.hideKeyboard()));
@@ -107,9 +116,10 @@ export function registerHandlers(socket, controller) {
 export async function runControlTunnel(options) {
     const connect = options.connect ?? defaultConnect;
     const socket = connect(options.wsUrl, options.deviceToken);
-    registerHandlers(socket, options.controller);
+    registerHandlers(socket, options.controller, options.installApp);
     await new Promise((resolve, reject) => {
         let shuttingDown = false;
+        let serverKicks = [];
         const cleanup = () => {
             if (shuttingDown)
                 return;
@@ -117,12 +127,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;
@@ -130,8 +155,34 @@ export async function runControlTunnel(options) {
             console.error(`Connection error: ${err.message}`);
         });
         socket.on("disconnect", (reason) => {
+            // A SIGINT/SIGTERM teardown closes the socket itself; cleanup() already
+            // 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;
@@ -142,7 +193,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

@@ -127,7 +127,7 @@ describe("registerHandlers", () => {
         const result = (await socket.emit("datetime", {}));
         expect(typeof result.datetime).toBe("string");
         expect(result.datetime.length).toBeGreaterThan(0);
-        expect(result.datetime).not.toContain("T"); // humanized, not raw ISO
+        expect(result.datetime).not.toMatch(/\dT\d/); // humanized, not raw ISO (e.g. 2026-06-30T14:41)
         expect(typeof result.timezone).toBe("string");
         expect(result.timezone.length).toBeGreaterThan(0);
     });

package/dist/proxy.d.ts

@@ -0,0 +1,11 @@
+/** True for loopback, RFC1918, link-local, or IPv6 ULA hosts — never proxied. */
+export declare function isPrivateHost(host: string): boolean;
+/** Merge any existing NO_PROXY with the hosts we always force direct. */
+export declare function resolveNoProxy(env: NodeJS.ProcessEnv, host: string | null): string;
+/**
+ * Route the CLI's global fetch() through any configured HTTP(S) proxy. No-op
+ * when no proxy env var is set. Writes the resolved NO_PROXY back onto the
+ * environment so the pip subprocess and the spawned Python agent inherit the
+ * same bypass rules. Returns whether a proxy was installed.
+ */
+export declare function installProxySupport(env?: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/proxy.js

@@ -0,0 +1,85 @@
+import { getBaseUrl } from "./client.js";
+// Make every fetch() the CLI issues honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY,
+// the same way npm, curl and pip do. Node's global fetch (undici) ignores these
+// by default, so the embedded-Python download and the API calls would bypass a
+// corporate proxy and fail on a locked-down on-prem network.
+//
+// Two hosts are always forced direct, even when a proxy is set:
+//   - loopback: the local Appium / WebDriver servers the mobile commands drive.
+//   - a private-range Aximo server: an on-prem box (e.g. 172.30.x.x) is reached
+//     directly, and an internet proxy usually cannot route to an internal IP —
+//     proxying it would break a link that currently works. NO_PROXY can't
+//     express CIDRs reliably, so we match the base-URL host against the private
+//     ranges ourselves and force it direct when it's an internal IP literal.
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "::1"];
+/** True for loopback, RFC1918, link-local, or IPv6 ULA hosts — never proxied. */
+export function isPrivateHost(host) {
+    const h = host.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    if (LOOPBACK_HOSTS.includes(h))
+        return true;
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+    if (v4) {
+        const a = Number(v4[1]);
+        const b = Number(v4[2]);
+        if (a === 10 || a === 127)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        return false;
+    }
+    // IPv6 ULA / link-local — only for IPv6 literals (which contain a colon), so
+    // ordinary DNS names like "fd.example.com" or "fc00.example.com" stay public.
+    if (h.includes(":")) {
+        if (/^fe[89ab]/.test(h))
+            return true; // fe80::/10 link-local
+        if (/^f[cd]/.test(h))
+            return true; // fc00::/7 unique-local
+    }
+    return false;
+}
+function hasProxyEnv(env) {
+    return Boolean(env["HTTP_PROXY"] || env["http_proxy"] || env["HTTPS_PROXY"] || env["https_proxy"]);
+}
+function serverHost() {
+    try {
+        return new URL(getBaseUrl()).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Merge any existing NO_PROXY with the hosts we always force direct. */
+export function resolveNoProxy(env, host) {
+    const parts = (env["NO_PROXY"] ?? env["no_proxy"] ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const direct = [...LOOPBACK_HOSTS];
+    if (host && isPrivateHost(host))
+        direct.push(host);
+    for (const d of direct) {
+        if (!parts.includes(d))
+            parts.push(d);
+    }
+    return parts.join(",");
+}
+/**
+ * Route the CLI's global fetch() through any configured HTTP(S) proxy. No-op
+ * when no proxy env var is set. Writes the resolved NO_PROXY back onto the
+ * environment so the pip subprocess and the spawned Python agent inherit the
+ * same bypass rules. Returns whether a proxy was installed.
+ */
+export async function installProxySupport(env = process.env) {
+    if (!hasProxyEnv(env))
+        return false;
+    const noProxy = resolveNoProxy(env, serverHost());
+    env["NO_PROXY"] = noProxy;
+    env["no_proxy"] = noProxy;
+    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(new EnvHttpProxyAgent({ noProxy }));
+    return true;
+}

package/dist/proxy.test.d.ts

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

package/dist/proxy.test.js

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getGlobalDispatcher, setGlobalDispatcher } from "undici";
+import { isPrivateHost, installProxySupport, resolveNoProxy } from "./proxy.js";
+describe("isPrivateHost", () => {
+    it("treats loopback as private", () => {
+        expect(isPrivateHost("localhost")).toBe(true);
+        expect(isPrivateHost("127.0.0.1")).toBe(true);
+        expect(isPrivateHost("::1")).toBe(true);
+        expect(isPrivateHost("[::1]")).toBe(true);
+    });
+    it("treats RFC1918 / link-local IPv4 as private", () => {
+        expect(isPrivateHost("10.1.2.3")).toBe(true);
+        expect(isPrivateHost("172.30.193.138")).toBe(true); // the on-prem repro
+        expect(isPrivateHost("192.168.0.5")).toBe(true);
+        expect(isPrivateHost("169.254.10.10")).toBe(true);
+    });
+    it("treats 172.x outside 16-31 as public", () => {
+        expect(isPrivateHost("172.15.0.1")).toBe(false);
+        expect(isPrivateHost("172.32.0.1")).toBe(false);
+    });
+    it("treats IPv6 ULA / link-local as private", () => {
+        expect(isPrivateHost("fd00::1")).toBe(true);
+        expect(isPrivateHost("fe80::1")).toBe(true);
+    });
+    it("treats public hosts as not private", () => {
+        expect(isPrivateHost("aximo.autify.com")).toBe(false);
+        expect(isPrivateHost("8.8.8.8")).toBe(false);
+        expect(isPrivateHost("2606:4700::1")).toBe(false);
+    });
+    it("treats DNS names that start like IPv6 ULA/link-local as public", () => {
+        expect(isPrivateHost("fd.example.com")).toBe(false);
+        expect(isPrivateHost("fc00.example.com")).toBe(false);
+        expect(isPrivateHost("fe80.example.com")).toBe(false);
+    });
+});
+describe("resolveNoProxy", () => {
+    it("always forces loopback direct", () => {
+        expect(resolveNoProxy({}, null).split(",")).toEqual(["localhost", "127.0.0.1", "::1"]);
+    });
+    it("adds a private server host so the on-prem link stays direct", () => {
+        const result = resolveNoProxy({}, "172.30.193.138").split(",");
+        expect(result).toContain("172.30.193.138");
+    });
+    it("leaves a public server host to the proxy", () => {
+        expect(resolveNoProxy({}, "aximo.autify.com")).not.toContain("aximo.autify.com");
+    });
+    it("preserves an existing NO_PROXY and dedupes", () => {
+        const result = resolveNoProxy({ NO_PROXY: "example.com, localhost" }, "10.0.0.1");
+        const parts = result.split(",");
+        expect(parts).toContain("example.com");
+        expect(parts).toContain("10.0.0.1");
+        expect(parts.filter((p) => p === "localhost")).toHaveLength(1);
+    });
+});
+describe("installProxySupport", () => {
+    // installProxySupport sets a global undici dispatcher; restore it so the
+    // proxy agent doesn't leak into other tests' fetch() calls.
+    const original = getGlobalDispatcher();
+    afterEach(() => setGlobalDispatcher(original));
+    it("is a no-op when no proxy env is set", async () => {
+        const env = {};
+        expect(await installProxySupport(env)).toBe(false);
+        expect(env["NO_PROXY"]).toBeUndefined();
+    });
+    it("installs a dispatcher and writes NO_PROXY when a proxy is set", async () => {
+        const env = { HTTPS_PROXY: "http://proxy.local:8080" };
+        expect(await installProxySupport(env)).toBe(true);
+        const noProxy = env["NO_PROXY"] ?? "";
+        expect(noProxy.split(",")).toContain("127.0.0.1");
+        expect(env["no_proxy"]).toBe(noProxy);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",
@@ -38,8 +38,10 @@
   "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",
     "ws": "^8.18.0",
     "zod": "^3.25.76"
   },
@@ -61,7 +63,7 @@
     "vitest": "4.1.4"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.18.1"
   },
   "scripts": {
     "build": "tsc",