@autifyhq/aximo-cli 0.4.0 → 0.5.0

package/dist/commands/device/register.js

@@ -1,10 +1,9 @@
-import { defineCommand } from "citty";
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { platform, release } from "node:os";
-import { request } from "../../client.js";
+import { defineCommand } from "citty";
+import { getBaseUrl, request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
 import { formatError, formatSuccess, printResult } from "../../output.js";
-import { getAximoDir, getDeviceConfigPath } from "./paths.js";
+import { readDeviceConfig, writeDeviceConfig } from "./device-config.js";
 function detectPlatform() {
     const p = platform();
     if (p === "win32")
@@ -22,42 +21,59 @@ function detectOs() {
         return `macOS ${r}`;
     return `Linux ${r}`;
 }
+/** Whether deviceId is present among the user's devices on the targeted server. */
+async function deviceExistsOnServer(deviceId, deps) {
+    const res = await request("/api/devices/user", {}, deps);
+    return (res.devices ?? []).some((d) => d.id === deviceId);
+}
 export async function runDeviceRegister(options, deps) {
     try {
-        const configPath = getDeviceConfigPath();
-        if (existsSync(configPath) && !options.force) {
-            return formatError("validation_error", "A device is already registered on this machine. Run 'aximo device unregister' first, or pass --force to overwrite (this orphans the previous server-side device).", false);
+        const clientDeps = deps ?? {};
+        const baseUrl = clientDeps.baseUrl ?? getBaseUrl();
+        let replacedStale = false;
+        let previousBaseUrl;
+        const existing = readDeviceConfig();
+        if (existing && !options.force) {
+            // A local registration exists. It only truly conflicts if that device is
+            // still present on the server we're targeting. If it's gone — deleted, or
+            // registered against a different server (common when rotating ephemeral
+            // on-prem test boxes) — the local file is stale and we re-register instead
+            // of hard-blocking. When the server can't be reached to check, stay safe
+            // and block rather than silently clobber a possibly-valid registration.
+            let liveHere;
+            try {
+                liveHere = await deviceExistsOnServer(existing.deviceId, clientDeps);
+            }
+            catch (err) {
+                return formatError("validation_error", `A device is already registered on this machine and its status on ${baseUrl} ` +
+                    `could not be verified (${err instanceof Error ? err.message : String(err)}). ` +
+                    "Run 'aximo device unregister' first, or pass --force to overwrite.", false);
+            }
+            if (liveHere) {
+                return formatError("validation_error", `A device (${existing.deviceId}) is already registered on this machine and active on ${baseUrl}. ` +
+                    "Run 'aximo device unregister' first, or pass --force to overwrite (this orphans the previous server-side device).", false);
+            }
+            replacedStale = true;
+            previousBaseUrl = existing.baseUrl;
         }
         const res = await request("/api/devices/register", {
             method: "POST",
-            body: {
-                name: options.name,
-                platform: detectPlatform(),
-                os: detectOs(),
-            },
-        }, deps ?? {});
-        const aximoDir = getAximoDir();
-        if (!existsSync(aximoDir)) {
-            mkdirSync(aximoDir, { recursive: true });
-        }
+            body: { name: options.name, platform: detectPlatform(), os: detectOs() },
+        }, clientDeps);
         const registeredAt = new Date().toISOString();
-        const config = {
+        writeDeviceConfig({
             deviceId: res.deviceId,
             deviceToken: res.deviceToken,
             name: options.name,
             registeredAt,
-        };
-        writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
-        try {
-            chmodSync(configPath, 0o600);
-        }
-        catch {
-            // chmod may fail on Windows, file-level ACLs apply instead
-        }
+            baseUrl,
+        });
         return formatSuccess({
             deviceId: res.deviceId,
             name: options.name,
             registeredAt,
+            ...(replacedStale ? { replacedStale: true } : {}),
+            ...(previousBaseUrl ? { previousBaseUrl } : {}),
         });
     }
     catch (err) {
@@ -67,17 +83,19 @@ export async function runDeviceRegister(options, deps) {
 export default defineCommand({
     meta: { name: "register", description: "Register this machine as a BYOD device" },
     args: {
-        name: {
-            type: "string",
-            description: "Device name",
-            required: true,
-        },
+        name: { type: "string", description: "Device name", required: true },
         force: {
             type: "boolean",
             description: "Overwrite an existing local registration (orphans the previous device)",
         },
     },
     async run({ args }) {
-        printResult(await runDeviceRegister({ name: args.name, force: Boolean(args.force) }));
+        const result = await runDeviceRegister({ name: args.name, force: Boolean(args.force) });
+        printResult(result);
+        if (result.ok && result.data.replacedStale) {
+            const prev = result.data.previousBaseUrl;
+            console.error(`\nNote: replaced a stale local registration${prev ? ` (previously registered against ${prev})` : ""}. ` +
+                "If that device still exists on another server it is now orphaned — unregister it there if you no longer need it.");
+        }
     },
 });

package/dist/commands/device/register.test.d.ts

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

package/dist/commands/device/register.test.js

@@ -0,0 +1,95 @@
+import { mkdirSync, mkdtempSync, readFileSync, 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 { runDeviceRegister } from "./register.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-register-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_BASE_URL"];
+    delete process.env["AXIMO_API_KEY"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(tempHome, { recursive: true, force: true });
+    mkdirSync(tempHome, { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+function devicePath() {
+    return join(tempHome, "device.json");
+}
+function seedDevice(cfg) {
+    writeFileSync(devicePath(), JSON.stringify(cfg), { mode: 0o600 });
+}
+function readDevice() {
+    return JSON.parse(readFileSync(devicePath(), "utf-8"));
+}
+describe("runDeviceRegister", () => {
+    it("registers fresh when no local device exists", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "new-1", deviceToken: "tok" })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("new-1");
+            expect(result.data.replacedStale).toBeUndefined();
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "new-1", name: "mac", baseUrl: TEST_BASE_URL });
+    });
+    it("blocks when the local device is still live on the targeted server", async () => {
+        seedDevice({ deviceId: "dev-live", deviceToken: "t", name: "x", baseUrl: TEST_BASE_URL });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: [{ id: "dev-live" }] })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toContain("active on");
+        }
+        // Local file untouched (no POST happened).
+        expect(readDevice()).toMatchObject({ deviceId: "dev-live" });
+    });
+    it("re-registers when the local device is absent on the targeted server (stale)", async () => {
+        seedDevice({ deviceId: "dev-old", deviceToken: "t", name: "x", baseUrl: "https://old.server" });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: [] })), http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "dev-new", deviceToken: "tok2" })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("dev-new");
+            expect(result.data.replacedStale).toBe(true);
+            // The replaced registration's server is surfaced, not silently dropped.
+            expect(result.data.previousBaseUrl).toBe("https://old.server");
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-new", baseUrl: TEST_BASE_URL });
+    });
+    it("blocks conservatively when the server cannot be reached to verify", async () => {
+        seedDevice({ deviceId: "dev-x", deviceToken: "t", name: "x" });
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "boom" }, { status: 500 })));
+        const result = await runDeviceRegister({ name: "mac" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toContain("could not be verified");
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-x" });
+    });
+    it("--force overwrites without checking the server", async () => {
+        seedDevice({ deviceId: "dev-live", deviceToken: "t", name: "x", baseUrl: TEST_BASE_URL });
+        // The device list would 500; if --force consulted it, register would block.
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "boom" }, { status: 500 })), http.post(`${TEST_BASE_URL}/api/devices/register`, () => HttpResponse.json({ deviceId: "dev-forced", deviceToken: "tok" })));
+        const result = await runDeviceRegister({ name: "mac", force: true });
+        expect(result.ok).toBe(true);
+        if (result.ok) {
+            expect(result.data.deviceId).toBe("dev-forced");
+            expect(result.data.replacedStale).toBeUndefined();
+        }
+        expect(readDevice()).toMatchObject({ deviceId: "dev-forced", baseUrl: TEST_BASE_URL });
+    });
+});

package/dist/commands/device/unregister.d.ts

@@ -1,10 +1,12 @@
 import { type ClientDeps } from "../../client.js";
 import type { Envelope } from "../../types.js";
+export interface UnregisterResult {
+    success: boolean;
+    serverDeleted: boolean;
+}
 export declare function runDeviceUnregister(options: {
     deviceId?: string;
-}, deps?: ClientDeps): Promise<Envelope<{
-    success: boolean;
-}>>;
+}, deps?: ClientDeps): Promise<Envelope<UnregisterResult>>;
 declare const _default: import("citty").CommandDef<{
     readonly "device-id": {
         readonly type: "string";

package/dist/commands/device/unregister.js

@@ -1,49 +1,44 @@
+import { existsSync, unlinkSync } from "node:fs";
 import { defineCommand } from "citty";
-import { existsSync, unlinkSync, readFileSync } from "node:fs";
 import { request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
-import { formatSuccess, formatError, printResult } from "../../output.js";
+import { formatError, formatSuccess, printResult } from "../../output.js";
+import { readDeviceConfig } from "./device-config.js";
 import { getDeviceConfigPath } from "./paths.js";
+function isNotFound(err) {
+    return typeof err === "object" && err !== null && err.status === 404;
+}
 export async function runDeviceUnregister(options, deps) {
-    let deviceId = options.deviceId;
-    if (!deviceId && existsSync(getDeviceConfigPath())) {
-        try {
-            const config = JSON.parse(readFileSync(getDeviceConfigPath(), "utf-8"));
-            if (config &&
-                typeof config === "object" &&
-                typeof config.deviceId === "string") {
-                deviceId = config.deviceId;
-            }
-            else {
-                return formatError("validation_error", "Device config is malformed: missing deviceId", false);
-            }
-        }
-        catch {
-            return formatError("validation_error", "Failed to read device config", false);
-        }
-    }
+    const local = readDeviceConfig();
+    const deviceId = options.deviceId ?? local?.deviceId;
     if (!deviceId) {
+        if (existsSync(getDeviceConfigPath())) {
+            return formatError("validation_error", "Local device config is unreadable. Pass a device ID, or clear it with: aximo device reset --device", false);
+        }
         return formatError("validation_error", "No device ID provided and no local device config found. " +
             "Pass a device ID or register first with: aximo device register", false);
     }
+    let serverDeleted = true;
     try {
         await request(`/api/devices/user/${deviceId}`, { method: "DELETE" }, deps ?? {});
-        if (existsSync(getDeviceConfigPath())) {
-            try {
-                const config = JSON.parse(readFileSync(getDeviceConfigPath(), "utf-8"));
-                if (config.deviceId === deviceId) {
-                    unlinkSync(getDeviceConfigPath());
-                }
-            }
-            catch {
-                // non-fatal
-            }
-        }
-        return formatSuccess({ success: true });
     }
     catch (err) {
-        return handleApiError(err);
+        // Already gone server-side — local cleanup is still the goal, so clear the
+        // file and report success. Re-surface any other error.
+        if (!isNotFound(err))
+            return handleApiError(err);
+        serverDeleted = false;
+    }
+    // Remove the local registration when it matches the device we just unregistered.
+    if (local && local.deviceId === deviceId && existsSync(getDeviceConfigPath())) {
+        try {
+            unlinkSync(getDeviceConfigPath());
+        }
+        catch {
+            // non-fatal
+        }
     }
+    return formatSuccess({ success: true, serverDeleted });
 }
 export default defineCommand({
     meta: { name: "unregister", description: "Unregister a device" },
@@ -55,6 +50,10 @@ export default defineCommand({
     },
     async run({ args }) {
         const deviceId = args["device-id"];
-        printResult(await runDeviceUnregister(deviceId ? { deviceId } : {}));
+        const result = await runDeviceUnregister(deviceId ? { deviceId } : {});
+        printResult(result);
+        if (result.ok && !result.data.serverDeleted) {
+            console.error("\nNote: the device was already absent on the server; cleared the local registration.");
+        }
     },
 });

package/dist/commands/device/unregister.test.d.ts

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

package/dist/commands/device/unregister.test.js

@@ -0,0 +1,73 @@
+import { existsSync, 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 { runDeviceUnregister } from "./unregister.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-unregister-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    delete process.env["AXIMO_BASE_URL"];
+    delete process.env["AXIMO_API_KEY"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(tempHome, { recursive: true, force: true });
+    mkdirSync(tempHome, { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+function devicePath() {
+    return join(tempHome, "device.json");
+}
+function seedDevice(cfg) {
+    writeFileSync(devicePath(), JSON.stringify(cfg), { mode: 0o600 });
+}
+describe("runDeviceUnregister", () => {
+    it("deletes the server device and removes the local file", async () => {
+        seedDevice({ deviceId: "dev-1", deviceToken: "t", name: "x" });
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/dev-1`, () => HttpResponse.json({ success: true })));
+        const result = await runDeviceUnregister({});
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.serverDeleted).toBe(true);
+        expect(existsSync(devicePath())).toBe(false);
+    });
+    it("clears the local file even when the server returns 404", async () => {
+        seedDevice({ deviceId: "dev-gone", deviceToken: "t", name: "x" });
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/dev-gone`, () => HttpResponse.json({ error: "not found" }, { status: 404 })));
+        const result = await runDeviceUnregister({});
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.serverDeleted).toBe(false);
+        expect(existsSync(devicePath())).toBe(false);
+    });
+    it("keeps the local file and errors on a non-404 server error", async () => {
+        seedDevice({ deviceId: "dev-1", deviceToken: "t", name: "x" });
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/dev-1`, () => HttpResponse.json({ error: "boom" }, { status: 500 })));
+        const result = await runDeviceUnregister({});
+        expect(result.ok).toBe(false);
+        expect(existsSync(devicePath())).toBe(true);
+    });
+    it("errors when no device id is given and no local config exists", async () => {
+        const result = await runDeviceUnregister({});
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("uses an explicit device id without removing a differing local file", async () => {
+        seedDevice({ deviceId: "local-1", deviceToken: "t", name: "x" });
+        server.use(http.delete(`${TEST_BASE_URL}/api/devices/user/other-2`, () => HttpResponse.json({ success: true })));
+        const result = await runDeviceUnregister({ deviceId: "other-2" });
+        expect(result.ok).toBe(true);
+        // The local registration is for a different device, so it stays.
+        expect(existsSync(devicePath())).toBe(true);
+    });
+});

package/dist/commands/mobile/connect-core.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorEnvelope } from "../../types.js";
+import type { MobileController } from "../../mobile-control/controller.js";
+import { type MobileDeviceConfig } from "./paths.js";
+export declare function getTunnelOrigin(): string;
+interface ConfigOk {
+    ok: true;
+    config: MobileDeviceConfig;
+}
+export declare function resolveDeviceConfig(deviceId: string | undefined): ConfigOk | ErrorEnvelope;
+export declare function buildController(config: MobileDeviceConfig, endpoint: string): MobileController;
+export declare function connectWithConfig(config: MobileDeviceConfig): Promise<void>;
+export {};

package/dist/commands/mobile/connect-core.js

@@ -0,0 +1,74 @@
+import { getBaseUrl } from "../../client.js";
+import { formatError } from "../../output.js";
+import { AppiumController } from "../../mobile-control/appium-controller.js";
+import { startAppiumServer } from "../../mobile-control/appium-server.js";
+import { runControlTunnel } from "../../mobile-control/tunnel.js";
+import { runMobileDoctor } from "./doctor.js";
+import { listMobileDeviceConfigs, readMobileDeviceConfig, } from "./paths.js";
+export function getTunnelOrigin() {
+    return getBaseUrl().replace(/^http/, "ws");
+}
+export function resolveDeviceConfig(deviceId) {
+    if (deviceId) {
+        const config = readMobileDeviceConfig(deviceId);
+        if (!config) {
+            return formatError("not_found", `No registered device with id '${deviceId}'.`, false);
+        }
+        return { ok: true, config };
+    }
+    const all = listMobileDeviceConfigs();
+    if (all.length === 0) {
+        return formatError("validation_error", 'No registered devices. Register one first: aximo mobile register --name "My Pixel" --platform android', false);
+    }
+    if (all.length > 1) {
+        return formatError("validation_error", `Multiple devices registered; pass --device-id. Registered: ${all
+            .map((c) => `${c.name} (${c.deviceId})`)
+            .join(", ")}`, false);
+    }
+    const only = all[0];
+    if (!only) {
+        return formatError("validation_error", "No registered devices.", false);
+    }
+    return { ok: true, config: only };
+}
+export function buildController(config, endpoint) {
+    return new AppiumController({ endpoint, platform: config.platform, target: config.target });
+}
+// A blocking check is any hard failure, plus a missing UiAutomator2 driver
+// (only a warning for `doctor`, but a hard prerequisite for connecting).
+function isBlockingCheck(check) {
+    if (check.status === "fail")
+        return true;
+    return check.name === "uiautomator2 driver" && check.status === "warn";
+}
+async function assertAndroidPrerequisites() {
+    const report = await runMobileDoctor({ platform: "android" });
+    const checks = report.ok ? report.data.checks : [];
+    const blockers = checks.filter(isBlockingCheck);
+    if (blockers.length === 0)
+        return;
+    const lines = blockers.map((c) => `  - ${c.message}${c.hint ? `\n      ${c.hint}` : ""}`);
+    throw new Error(`Missing Appium prerequisites:\n${lines.join("\n")}\n` +
+        "Run `aximo mobile setup` and/or fix the above, then re-run. " +
+        "(`aximo mobile doctor` for details.)");
+}
+export async function connectWithConfig(config) {
+    if (config.platform === "android") {
+        await assertAndroidPrerequisites();
+    }
+    const useDrivers = config.platform === "ios" ? ["xcuitest"] : ["uiautomator2"];
+    const server = await startAppiumServer({ useDrivers });
+    const controller = buildController(config, server.endpoint);
+    try {
+        await runControlTunnel({
+            wsUrl: getTunnelOrigin(),
+            deviceToken: config.deviceToken,
+            deviceName: config.name,
+            controller,
+        });
+    }
+    finally {
+        await controller.close();
+        await server.stop();
+    }
+}

package/dist/commands/mobile/connect.d.ts

@@ -0,0 +1,9 @@
+import type { MobileDeviceConfig } from "./paths.js";
+export declare function iosPhysicalWarning(config: MobileDeviceConfig): string | null;
+declare const _default: import("citty").CommandDef<{
+    readonly "device-id": {
+        readonly type: "string";
+        readonly description: "Registered device id (required if multiple)";
+    };
+}>;
+export default _default;

package/dist/commands/mobile/connect.js

@@ -0,0 +1,35 @@
+import { defineCommand } from "citty";
+import { formatError, printResult } from "../../output.js";
+import { connectWithConfig, resolveDeviceConfig } from "./connect-core.js";
+const IOS_PHYSICAL_WARNING = "Driving a physical iPhone goes through Appium's XCUITest driver, which builds and " +
+    "installs a WebDriverAgent runner on the device. The device must have Developer Mode " +
+    "enabled (Settings → Privacy & Security) and be trusted, and WDA needs an Apple Developer " +
+    "signing identity; if control fails, run `aximo mobile doctor` for guidance.";
+export function iosPhysicalWarning(config) {
+    return config.platform === "ios" ? IOS_PHYSICAL_WARNING : null;
+}
+export default defineCommand({
+    meta: {
+        name: "connect",
+        description: "Connect a registered phone to Aximo via a CLI-managed Appium server",
+    },
+    args: {
+        "device-id": { type: "string", description: "Registered device id (required if multiple)" },
+    },
+    async run({ args }) {
+        const resolved = resolveDeviceConfig(args["device-id"]);
+        if (!resolved.ok) {
+            printResult(resolved);
+            return;
+        }
+        const warning = iosPhysicalWarning(resolved.config);
+        if (warning)
+            console.error(warning);
+        try {
+            await connectWithConfig(resolved.config);
+        }
+        catch (error) {
+            printResult(formatError("api_error", error instanceof Error ? error.message : String(error), true));
+        }
+    },
+});

package/dist/commands/mobile/connect.test.d.ts

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

package/dist/commands/mobile/connect.test.js

@@ -0,0 +1,87 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveDeviceConfig } from "./connect-core.js";
+import { iosPhysicalWarning } from "./connect.js";
+import { writeMobileDeviceConfig } from "./paths.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-mob-connect-"));
+    process.env["AXIMO_HOME"] = tempHome;
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(tempHome, { recursive: true, force: true });
+    mkdirSync(tempHome, { recursive: true });
+});
+describe("iosPhysicalWarning", () => {
+    it("returns an Appium/WDA guidance warning for iOS configs", () => {
+        const warning = iosPhysicalWarning({
+            deviceId: "d1",
+            deviceToken: "t",
+            name: "iPhone",
+            platform: "ios",
+            target: "udid",
+        });
+        expect(warning).toContain("WebDriverAgent");
+        expect(warning).toContain("Developer Mode");
+    });
+    it("returns null for android configs (no warning)", () => {
+        const warning = iosPhysicalWarning({
+            deviceId: "d2",
+            deviceToken: "t",
+            name: "Pixel",
+            platform: "android",
+            target: "serial",
+        });
+        expect(warning).toBeNull();
+    });
+});
+describe("resolveDeviceConfig", () => {
+    it("returns validation_error when none are registered", () => {
+        const result = resolveDeviceConfig(undefined);
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("auto-selects the only registered device", () => {
+        writeMobileDeviceConfig({
+            deviceId: "only-1",
+            deviceToken: "t",
+            name: "Solo",
+            platform: "android",
+            target: "serial-1",
+        });
+        const result = resolveDeviceConfig(undefined);
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.config.deviceId).toBe("only-1");
+    });
+    it("requires --device-id when multiple are registered", () => {
+        for (const id of ["a", "b"]) {
+            writeMobileDeviceConfig({
+                deviceId: id,
+                deviceToken: "t",
+                name: id,
+                platform: "android",
+                target: `serial-${id}`,
+            });
+        }
+        const ambiguous = resolveDeviceConfig(undefined);
+        expect(ambiguous.ok).toBe(false);
+        const picked = resolveDeviceConfig("b");
+        expect(picked.ok).toBe(true);
+        if (picked.ok)
+            expect(picked.config.deviceId).toBe("b");
+    });
+    it("returns not_found for an unknown device id", () => {
+        const result = resolveDeviceConfig("ghost");
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("not_found");
+    });
+});

package/dist/commands/mobile/doctor.d.ts

@@ -0,0 +1,28 @@
+import type { Envelope } from "../../types.js";
+export type CheckStatus = "pass" | "warn" | "fail" | "info";
+export interface Check {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    hint?: string;
+}
+export interface MobileDoctorReport {
+    checks: Check[];
+    summary: {
+        pass: number;
+        warn: number;
+        fail: number;
+        info: number;
+    };
+}
+export interface RunMobileDoctorOptions {
+    platform?: "ios" | "android" | undefined;
+}
+export declare function runMobileDoctor(options?: RunMobileDoctorOptions): Promise<Envelope<MobileDoctorReport>>;
+declare const _default: import("citty").CommandDef<{
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "Limit checks to ios | android";
+    };
+}>;
+export default _default;