@autifyhq/aximo-cli 0.10.1 → 0.11.1

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

@@ -16,22 +16,32 @@ export const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
 /** How to stop the elevated tunnel daemon — surfaced whenever we start or leave it running. */
 export const TUNNEL_STOP_COMMAND = "sudo pkill -f tunnel-creation";
 /**
- * True when the tunnel registry server answers its HTTP API on `port`. A raw
- * TCP connect is not enough — an unrelated listener on the port would be
- * mistaken for the tunnel and surface much later as an opaque XCUITest error.
+ * Fetch the tunnel registry on `port` and return the device udids it has
+ * tunnels for, or null when no valid registry answers. The response must parse
+ * as a registry (`{"tunnels": {...}}`) — a raw TCP connect is not enough, as an
+ * unrelated listener on the port would be mistaken for the tunnel and surface
+ * much later as an opaque XCUITest error.
+ *
+ * The udid list matters because the XCUITest driver (12+) validates the
+ * session's udid against this registry whenever it answers, ignoring what
+ * devicectl/usbmuxd can see — a running registry without the target device
+ * guarantees "Unknown device or simulator UDID".
  */
-export async function isTunnelHealthy(port = DEFAULT_TUNNEL_REGISTRY_PORT, host = "127.0.0.1", timeoutMs = 1500) {
+export async function listTunnelUdids(port = DEFAULT_TUNNEL_REGISTRY_PORT, host = "127.0.0.1", timeoutMs = 1500) {
     try {
         const res = await fetch(`http://${host}:${port}/remotexpc/tunnels`, {
             signal: AbortSignal.timeout(timeoutMs),
         });
         if (!res.ok)
-            return false;
-        await res.json();
-        return true;
+            return null;
+        const body = (await res.json());
+        if (!body || typeof body !== "object" || !body.tunnels || typeof body.tunnels !== "object") {
+            return null;
+        }
+        return Object.keys(body.tunnels);
     }
     catch {
-        return false;
+        return null;
     }
 }
 /** Single-quote a value for safe embedding in a POSIX shell script. */
@@ -65,6 +75,9 @@ export function buildTunnelScript(opts) {
         "#!/bin/sh",
         `export APPIUM_HOME=${shQuote(opts.appiumHome)}`,
         'export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"',
+        // The old daemon must die before the new one binds the registry port. The
+        // pattern can't match this script (its cmdline is `/bin/sh <path>`).
+        ...(opts.restart ? ["pkill -f tunnel-creation 2>/dev/null; sleep 1"] : []),
         `exec perl -e ${shQuote(DAEMONIZE_PERL)} ${shQuote(opts.logFile)} ${shQuote(opts.nodePath)} ${shQuote(opts.appiumBin)} driver run xcuitest tunnel-creation`,
         "",
     ].join("\n");
@@ -91,35 +104,47 @@ const defaultWriteScript = (path, content, dir) => {
     mkdirSync(dir, { recursive: true });
     writeFileSync(path, content, { mode: 0o700 });
 };
-async function pollHealthy(isHealthy, port, timeoutMs, logFile) {
+async function pollReady(listUdids, port, udid, timeoutMs, logFile) {
     const deadline = Date.now() + timeoutMs;
+    let last = null;
     while (Date.now() < deadline) {
-        if (await isHealthy(port))
+        last = await listUdids(port);
+        if (last !== null && (!udid || last.includes(udid)))
             return;
         await new Promise((resolve) => setTimeout(resolve, 500));
     }
+    if (last !== null && udid) {
+        throw new Error(`The iOS device tunnel is running but did not create a tunnel for device ${udid} ` +
+            `within ${timeoutMs}ms. Make sure the phone is connected over USB, unlocked, and ` +
+            `trusts this Mac, then retry. Check ${logFile} for the daemon's output; stop it ` +
+            `with: ${TUNNEL_STOP_COMMAND}`);
+    }
     throw new Error(`iOS device tunnel did not become ready within ${timeoutMs}ms. ` +
         `Check ${logFile} for the daemon's output. A partially-started daemon may still ` +
         `be running; stop it before retrying: ${TUNNEL_STOP_COMMAND}`);
 }
 /**
- * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
- * Reuses an already-running tunnel (no prompt); otherwise elevates once via the
- * macOS auth dialog to start it. No-op when AXIMO_IOS_SKIP_TUNNEL is set.
+ * Ensure the RemoteXPC tunnel is running — with a tunnel for `udid` when given —
+ * so XCUITest can find the device and reach WebDriverAgent. Reuses a running
+ * daemon whose registry serves the device (no prompt); restarts one that
+ * doesn't; otherwise elevates once via the macOS auth dialog to start it.
+ * No-op when AXIMO_IOS_SKIP_TUNNEL is set.
  */
 export async function ensureIosTunnel(options = {}) {
     const env = options.env ?? process.env;
     const port = options.port ?? DEFAULT_TUNNEL_REGISTRY_PORT;
-    const isHealthy = options.isHealthy ?? ((p) => isTunnelHealthy(p));
+    const listUdids = options.listUdids ?? ((p) => listTunnelUdids(p));
     const log = options.log ?? ((m) => console.error(m));
     if (envFlag(env, "AXIMO_IOS_SKIP_TUNNEL")) {
-        return { reused: false, started: false, skipped: true, port };
+        return { reused: false, started: false, restarted: false, skipped: true, port };
     }
-    // A healthy tunnel is reused as-is — this is what makes the prompt appear at
-    // most once per boot rather than once per `connect`.
-    if (await isHealthy(port)) {
-        return { reused: true, started: false, skipped: false, port };
+    // A tunnel serving the device is reused as-is — this is what makes the prompt
+    // appear at most once per boot rather than once per `connect`.
+    const existing = await listUdids(port);
+    if (existing !== null && (!options.udid || existing.includes(options.udid))) {
+        return { reused: true, started: false, restarted: false, skipped: false, port };
     }
+    const restarting = existing !== null;
     const appiumHome = options.appiumHome ?? getAppiumHome();
     const nodePath = options.nodePath ?? process.execPath;
     const appiumBin = options.appiumBin ?? resolveAppiumBin();
@@ -127,8 +152,12 @@ export async function ensureIosTunnel(options = {}) {
     const scriptPath = join(dir, "tunnel.sh");
     const logFile = join(dir, "tunnel.log");
     const writeScript = options.writeScript ?? defaultWriteScript;
-    writeScript(scriptPath, buildTunnelScript({ appiumHome, nodePath, appiumBin, logFile }), dir);
-    log("Starting the iOS device tunnel (needs admin). Approve the macOS password / Touch ID prompt…");
+    writeScript(scriptPath, buildTunnelScript({ appiumHome, nodePath, appiumBin, logFile, restart: restarting }), dir);
+    log(restarting
+        ? `The running iOS device tunnel has no tunnel for this device (${options.udid}) — ` +
+            "sessions would fail with 'Unknown device or simulator UDID'. Restarting it " +
+            "(needs admin). Approve the macOS password / Touch ID prompt…"
+        : "Starting the iOS device tunnel (needs admin). Approve the macOS password / Touch ID prompt…");
     const elevate = options.elevate ?? osascriptElevate;
     try {
         await elevate(scriptPath);
@@ -136,15 +165,22 @@ export async function ensureIosTunnel(options = {}) {
     catch (err) {
         const detail = err instanceof Error ? err.message : String(err);
         const declined = /User canceled|-128/i.test(detail);
+        const verb = restarting ? "restarted" : "started";
         const lead = declined
-            ? "Admin approval was declined, so the iOS device tunnel wasn't started."
-            : `Could not start the iOS device tunnel: ${detail}.`;
+            ? `Admin approval was declined, so the iOS device tunnel wasn't ${verb}.`
+            : `Could not ${restarting ? "restart" : "start"} the iOS device tunnel: ${detail}.`;
+        // In the restart path the stale daemon still holds the registry port, so the
+        // manual command must include the stop step or it fails to bind.
+        const manual = restarting ? `stop the stale daemon first (${TUNNEL_STOP_COMMAND}), then ` : "";
         throw new Error(`${lead} It is required for iOS 17+ to reach WebDriverAgent. Approve the macOS prompt and ` +
-            `retry, or start it yourself: sudo APPIUM_HOME=${shQuote(appiumHome)} ${shQuote(nodePath)} ` +
-            `${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
+            `retry, or ${manual}start it yourself: sudo APPIUM_HOME=${shQuote(appiumHome)} ` +
+            `${shQuote(nodePath)} ${shQuote(appiumBin)} driver run xcuitest tunnel-creation`);
     }
-    await pollHealthy(isHealthy, port, options.readyTimeoutMs ?? 45_000, logFile);
+    // Per-device tunnel creation (lockdown, CoreDeviceProxy, RSD catalog discovery)
+    // takes 30-60s on top of daemon boot, so the device wait gets a longer default.
+    const readyTimeoutMs = options.readyTimeoutMs ?? (options.udid ? 90_000 : 45_000);
+    await pollReady(listUdids, port, options.udid, readyTimeoutMs, logFile);
     log(`iOS device tunnel is up (registry on port ${port}). It keeps running in the background ` +
         `so later connects don't prompt again; stop it anytime with: ${TUNNEL_STOP_COMMAND}`);
-    return { reused: false, started: true, skipped: false, port };
+    return { reused: false, started: true, restarted: restarting, skipped: false, port };
 }

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

@@ -1,5 +1,6 @@
-import { describe, expect, it, vi } from "vitest";
-import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel } from "./ios-tunnel.js";
+import { createServer } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildTunnelScript, DEFAULT_TUNNEL_REGISTRY_PORT, ensureIosTunnel, listTunnelUdids, } from "./ios-tunnel.js";
 describe("buildTunnelScript", () => {
     it("launches tunnel-creation as a setsid-detached daemon with APPIUM_HOME set", () => {
         const script = buildTunnelScript({
@@ -26,6 +27,63 @@ describe("buildTunnelScript", () => {
         });
         expect(script).toContain("export APPIUM_HOME='/home/o'\\''brien/.aximo'");
     });
+    it("kills the old daemon before starting when restart is set", () => {
+        const opts = {
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            logFile: "/l.log",
+        };
+        const restart = buildTunnelScript({ ...opts, restart: true });
+        expect(restart).toContain("pkill -f tunnel-creation");
+        // pkill must come before the daemon launch, not after.
+        expect(restart.indexOf("pkill")).toBeLessThan(restart.indexOf("exec perl"));
+        expect(buildTunnelScript(opts)).not.toContain("pkill");
+    });
+});
+describe("listTunnelUdids", () => {
+    let server;
+    afterEach(async () => {
+        const open = server;
+        server = undefined;
+        if (open)
+            await new Promise((resolve) => open.close(() => resolve()));
+    });
+    const listen = (handler) => new Promise((resolve) => {
+        server = createServer(handler).listen(0, "127.0.0.1", () => {
+            const address = server?.address();
+            resolve(typeof address === "object" && address ? address.port : 0);
+        });
+    });
+    it("returns the udids the registry has tunnels for", async () => {
+        const port = await listen((req, res) => {
+            expect(req.url).toBe("/remotexpc/tunnels");
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ tunnels: { "00008030-AAAA": {}, "00008130-BBBB": {} } }));
+        });
+        await expect(listTunnelUdids(port)).resolves.toEqual(["00008030-AAAA", "00008130-BBBB"]);
+    });
+    it("returns null when nothing listens on the port", async () => {
+        const port = await listen((_req, res) => res.end());
+        const closed = new Promise((resolve) => server?.close(() => resolve()));
+        await closed;
+        server = undefined;
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
+    it("returns null when the listener is not a tunnel registry", async () => {
+        const port = await listen((_req, res) => {
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({ hello: "world" }));
+        });
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
+    it("returns null on a non-JSON or error response", async () => {
+        const port = await listen((_req, res) => {
+            res.statusCode = 500;
+            res.end("boom");
+        });
+        await expect(listTunnelUdids(port)).resolves.toBeNull();
+    });
 });
 describe("ensureIosTunnel", () => {
     const stubs = () => ({
@@ -36,35 +94,73 @@ describe("ensureIosTunnel", () => {
     it("reuses a healthy tunnel without prompting", async () => {
         const s = stubs();
         const result = await ensureIosTunnel({
-            isHealthy: async () => true,
+            listUdids: async () => [],
             ...s,
             env: {},
         });
         expect(result).toEqual({
             reused: true,
             started: false,
+            restarted: false,
             skipped: false,
             port: DEFAULT_TUNNEL_REGISTRY_PORT,
         });
         expect(s.elevate).not.toHaveBeenCalled();
         expect(s.writeScript).not.toHaveBeenCalled();
     });
+    it("reuses a tunnel that serves the requested device", async () => {
+        const s = stubs();
+        const result = await ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => ["00008030-AAAA"],
+            ...s,
+            env: {},
+        });
+        expect(result.reused).toBe(true);
+        expect(s.elevate).not.toHaveBeenCalled();
+    });
+    it("restarts a running tunnel whose registry lacks the device", async () => {
+        const s = stubs();
+        const listUdids = vi
+            .fn()
+            .mockResolvedValueOnce([]) // pre-check: registry up, no tunnel for the phone
+            .mockResolvedValue(["00008030-AAAA"]); // poll after restart
+        const result = await ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 2000,
+            ...s,
+            env: {},
+        });
+        expect(result.restarted).toBe(true);
+        expect(result.started).toBe(true);
+        expect(result.reused).toBe(false);
+        expect(s.elevate).toHaveBeenCalledWith("/tun/tunnel.sh");
+        // The elevated script must replace the old daemon, not race it for the port.
+        const script = s.writeScript.mock.calls[0]?.[1];
+        expect(script).toContain("pkill -f tunnel-creation");
+        expect(s.log).toHaveBeenCalledWith(expect.stringContaining("no tunnel for this device"));
+    });
     it("is a no-op when AXIMO_IOS_SKIP_TUNNEL is set", async () => {
         const s = stubs();
-        const isHealthy = vi.fn(async () => false);
+        const listUdids = vi.fn(async () => null);
         const result = await ensureIosTunnel({
-            isHealthy,
+            listUdids,
             ...s,
             env: { AXIMO_IOS_SKIP_TUNNEL: "1" },
         });
         expect(result.skipped).toBe(true);
-        expect(isHealthy).not.toHaveBeenCalled();
+        expect(listUdids).not.toHaveBeenCalled();
         expect(s.elevate).not.toHaveBeenCalled();
     });
     it('does not skip for AXIMO_IOS_SKIP_TUNNEL="0"', async () => {
         const s = stubs();
         const result = await ensureIosTunnel({
-            isHealthy: async () => true,
+            listUdids: async () => [],
             ...s,
             env: { AXIMO_IOS_SKIP_TUNNEL: "0" },
         });
@@ -74,7 +170,7 @@ describe("ensureIosTunnel", () => {
     it("points at the tunnel log when the daemon never becomes healthy", async () => {
         const s = stubs();
         await expect(ensureIosTunnel({
-            isHealthy: async () => false,
+            listUdids: async () => null,
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
@@ -84,14 +180,40 @@ describe("ensureIosTunnel", () => {
             env: {},
         })).rejects.toThrow(/tunnel\.log.*pkill -f tunnel-creation/s);
     });
+    it("explains when the registry never creates a tunnel for the device", async () => {
+        const s = stubs();
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => null,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 700,
+            ...s,
+            env: {},
+        })).rejects.toThrow(/did not become ready/);
+        const s2 = stubs();
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => ["00008130-OTHER"],
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            readyTimeoutMs: 700,
+            ...s2,
+            env: {},
+        })).rejects.toThrow(/did not create a tunnel for device 00008030-AAAA.*connected over USB/s);
+    });
     it("elevates and starts the tunnel when none is running", async () => {
         const s = stubs();
-        const isHealthy = vi
+        const listUdids = vi
             .fn()
-            .mockResolvedValueOnce(false) // pre-check
-            .mockResolvedValue(true); // poll after elevate
+            .mockResolvedValueOnce(null) // pre-check
+            .mockResolvedValue([]); // poll after elevate
         const result = await ensureIosTunnel({
-            isHealthy,
+            listUdids,
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
@@ -101,20 +223,37 @@ describe("ensureIosTunnel", () => {
             env: {},
         });
         expect(result.started).toBe(true);
+        expect(result.restarted).toBe(false);
         expect(s.writeScript).toHaveBeenCalledOnce();
         expect(s.elevate).toHaveBeenCalledWith("/tun/tunnel.sh");
+        const script = s.writeScript.mock.calls[0]?.[1];
+        expect(script).not.toContain("pkill");
     });
     it("throws actionable guidance when the admin prompt is declined", async () => {
         const s = stubs();
         s.elevate.mockRejectedValueOnce(new Error("User canceled."));
         await expect(ensureIosTunnel({
-            isHealthy: async () => false,
+            listUdids: async () => null,
+            appiumHome: "/ah",
+            nodePath: "/node",
+            appiumBin: "/appium",
+            dir: "/tun",
+            ...s,
+            env: {},
+        })).rejects.toThrow(/Admin approval was declined.*wasn't started.*driver run xcuitest tunnel-creation/s);
+    });
+    it("tells the user to stop the stale daemon when a declined restart leaves it running", async () => {
+        const s = stubs();
+        s.elevate.mockRejectedValueOnce(new Error("User canceled."));
+        await expect(ensureIosTunnel({
+            udid: "00008030-AAAA",
+            listUdids: async () => [],
             appiumHome: "/ah",
             nodePath: "/node",
             appiumBin: "/appium",
             dir: "/tun",
             ...s,
             env: {},
-        })).rejects.toThrow(/Admin approval was declined.*driver run xcuitest tunnel-creation/s);
+        })).rejects.toThrow(/wasn't restarted.*stop the stale daemon first \(sudo pkill -f tunnel-creation\), then start it yourself/s);
     });
 });

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

@@ -41,6 +41,12 @@ const IOS_RULES = [
         test: /Connection refused to port \d+|Tunnel registry port not found|RemoteXPC|tunnel is not available/i,
         hint: "The iOS device tunnel isn't reachable. `aximo mobile connect` starts it (needs admin); confirm with `aximo mobile doctor`. Set AXIMO_IOS_SKIP_TUNNEL only if you manage it yourself.",
     },
+    {
+        // XCUITest 12+ trusts the tunnel registry over usbmuxd/devicectl when it
+        // answers, so a registry without this device fails even a visible phone.
+        test: /Unknown device or simulator UDID/i,
+        hint: "Appium's device list did not include this phone. If it shows in `xcrun devicectl list devices`, the running tunnel daemon has no tunnel for it — re-run `aximo mobile connect` (it restarts the daemon), or stop it first: sudo pkill -f tunnel-creation. Otherwise reconnect USB (data cable, no hub), unlock the phone, and re-trust this Mac.",
+    },
     {
         // "is locked" (not "is unlocked") plus XCUITest's "could not be, unlocked" phrasing.
         test: /(device|screen).{0,30}\bis locked|could not be,? unlocked|passcode/i,

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

@@ -19,6 +19,9 @@ describe("mobileErrorHint (iOS)", () => {
     it("matches a refused connection on a dynamic wdaLocalPort", () => {
         expect(mobileErrorHint("Connection refused to port 51234", "ios")).toContain("device tunnel");
     });
+    it("explains the stale tunnel registry behind 'Unknown device or simulator UDID'", () => {
+        expect(mobileErrorHint("Unknown device or simulator UDID: '00008030-001D78CC2653402E'", "ios")).toContain("tunnel daemon has no tunnel for it");
+    });
     it("matches the driver's RemoteXPC tunnel errors", () => {
         expect(mobileErrorHint("RemoteXPC tunnel is not available for this session", "ios")).toContain("device tunnel");
     });

package/dist/types.d.ts

@@ -109,6 +109,55 @@ export interface PlanRun {
     status?: string | undefined;
     [key: string]: unknown;
 }
+export interface PlanListItem {
+    id: string;
+    projectId: string;
+    title: string;
+    description: string | null;
+    apiEnabled: boolean;
+    caseCount: number;
+    hasMobileCases: boolean;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: {
+        id: string;
+        name: string | null;
+        email: string;
+    } | null;
+}
+export interface PlanDetail {
+    id: string;
+    projectId: string;
+    title: string;
+    description: string | null;
+    apiEnabled: boolean;
+    executionMode: ExecutionMode;
+    stopOnFailure: boolean;
+    variables: {
+        name: string;
+        value: string;
+        isSecret: boolean;
+    }[];
+    caseCount: number;
+    createdAt: string;
+    updatedAt: string;
+    createdBy: {
+        id: string;
+        name: string | null;
+        email: string;
+    } | null;
+    project: {
+        id: string;
+        name: string;
+    } | null;
+    cases: {
+        id: string;
+        order: number;
+        type: string;
+        title: string | null;
+        lastStatus: string | null;
+    }[];
+}
 export interface PlanRunSummary {
     id: string;
     status: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",
@@ -52,11 +52,13 @@
     "@types/node": "^25.6.0",
     "@types/ws": "^8.18.0",
     "@vitest/coverage-v8": "4.1.4",
+    "esbuild": "0.27.7",
     "husky": "9.1.7",
     "msw": "2.13.2",
     "nano-staged": "1.0.2",
     "oxfmt": "0.45.0",
     "oxlint": "1.60.0",
+    "postject": "1.0.0-alpha.6",
     "secretlint": "11.7.1",
     "tsx": "4.21.0",
     "typescript": "6.0.2",
@@ -67,6 +69,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:sea": "node scripts/build-sea.mjs",
     "cli": "tsx src/cli.ts",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",