@autifyhq/aximo-cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,49 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { runMobileSetup } from "./setup.js";
+function fakeDoctor(checks) {
+    return async () => ({
+        ok: true,
+        data: { checks, summary: { pass: 0, warn: 0, fail: 0, info: 0 } },
+    });
+}
+describe("runMobileSetup", () => {
+    it("installs both drivers and runs the prerequisite check", async () => {
+        const appiumHome = mkdtempSync(join(tmpdir(), "aximo-setup-"));
+        const installed = [];
+        let doctorCalled = false;
+        const res = await runMobileSetup({
+            appiumHome,
+            install: async (driver) => {
+                installed.push(driver);
+            },
+            doctor: async () => {
+                doctorCalled = true;
+                return fakeDoctor([])();
+            },
+        });
+        expect(installed).toEqual(["uiautomator2", "xcuitest"]);
+        expect(doctorCalled).toBe(true);
+        expect(res.ok).toBe(true);
+        if (res.ok) {
+            expect(res.data.drivers.map((d) => d.driver)).toEqual(["uiautomator2", "xcuitest"]);
+            // checks are surfaced as guidance, not embedded in setup's JSON result
+            expect(res.data).not.toHaveProperty("checks");
+        }
+    });
+    it("limits to one driver with a platform filter", async () => {
+        const appiumHome = mkdtempSync(join(tmpdir(), "aximo-setup-"));
+        const installed = [];
+        await runMobileSetup({
+            appiumHome,
+            platform: "android",
+            install: async (driver) => {
+                installed.push(driver);
+            },
+            doctor: fakeDoctor([]),
+        });
+        expect(installed).toEqual(["uiautomator2"]);
+    });
+});

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

@@ -0,0 +1,14 @@
+import { type ClientDeps } from "../../client.js";
+import type { Envelope } from "../../types.js";
+export declare function runMobileUnregister(options: {
+    deviceId?: string;
+}, deps?: ClientDeps): Promise<Envelope<{
+    success: boolean;
+}>>;
+declare const _default: import("citty").CommandDef<{
+    readonly "device-id": {
+        readonly type: "string";
+        readonly description: "Device ID (defaults to the sole registered local device)";
+    };
+}>;
+export default _default;

package/dist/commands/mobile/unregister.js

@@ -0,0 +1,37 @@
+import { defineCommand } from "citty";
+import { existsSync, unlinkSync } from "node:fs";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { formatSuccess, printResult } from "../../output.js";
+import { resolveDeviceConfig } from "./connect-core.js";
+import { getMobileDeviceConfigPath } from "./paths.js";
+export async function runMobileUnregister(options, deps) {
+    const resolved = resolveDeviceConfig(options.deviceId);
+    if (!resolved.ok)
+        return resolved;
+    const { deviceId } = resolved.config;
+    try {
+        await request(`/api/devices/user/${deviceId}`, { method: "DELETE" }, deps ?? {});
+        const configPath = getMobileDeviceConfigPath(deviceId);
+        if (existsSync(configPath)) {
+            unlinkSync(configPath);
+        }
+        return formatSuccess({ success: true });
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: { name: "unregister", description: "Unregister a local mobile device" },
+    args: {
+        "device-id": {
+            type: "string",
+            description: "Device ID (defaults to the sole registered local device)",
+        },
+    },
+    async run({ args }) {
+        const deviceId = args["device-id"];
+        printResult(await runMobileUnregister(deviceId ? { deviceId } : {}));
+    },
+});

package/dist/commands/schema.js

@@ -36,6 +36,7 @@ export function getSchema() {
                     arg("upload-type", "string", "ANDROID_APP | IOS_APP"),
                     arg("app-name", "string", ""),
                     arg("bundle-id", "string", ""),
+                    arg("user-device-id", "string", "Run on a registered local device"),
                     ...MUTATE_ARGS,
                 ]),
                 cmd("get", "GET /api/sessions/{sessionId}", [
@@ -119,6 +120,27 @@ export function getSchema() {
                     arg("available-only", "boolean", ""),
                 ]),
             ]),
+            cmd("mobile", "Register and connect a physically-connected Android phone (via adb)", [], [
+                cmd("list", "List physically-connected phones (adb)"),
+                cmd("register", "Register a physically-connected Android phone as an Aximo device", [
+                    arg("name", "string", "Device name", true),
+                    arg("platform", "string", "Device platform (only `android` is supported today)"),
+                    arg("serial", "string", "Android adb serial (defaults to the connected one)"),
+                    arg("os", "string", "Optional OS version label"),
+                ]),
+                cmd("unregister", "Unregister a local mobile device", [
+                    arg("device-id", "string", "Device ID (defaults to the sole registered local device)"),
+                ]),
+                cmd("connect", "Connect a registered Android phone via a CLI-managed Appium server", [
+                    arg("device-id", "string", "Registered device id (required if multiple)"),
+                ]),
+                cmd("setup", "Install the Appium drivers used to drive registered phones", [
+                    arg("platform", "string", "Limit checks to android"),
+                ]),
+                cmd("doctor", "Diagnose physical-device tooling (adb authorization, Appium setup)", [
+                    arg("platform", "string", "Limit checks to android"),
+                ]),
+            ]),
             cmd("upload", "Upload commands", [], [
                 cmd("create", "POST /api/uploads", [
                     arg("file-name", "string", "File name"),

package/dist/commands/session/create.d.ts

@@ -16,6 +16,7 @@ export interface CreateSessionOptions {
     uploadType?: unknown;
     appName?: unknown;
     bundleId?: unknown;
+    userDeviceId?: unknown;
     json?: unknown;
     dryRun?: unknown;
 }
@@ -66,6 +67,10 @@ declare const _default: import("citty").CommandDef<{
     readonly "bundle-id": {
         readonly type: "string";
     };
+    readonly "user-device-id": {
+        readonly type: "string";
+        readonly description: "Run on a registered local device (BYOD desktop or local mobile)";
+    };
     readonly json: {
         readonly type: "string";
         readonly description: "Raw JSON request body (replaces individual flags)";

package/dist/commands/session/create.js

@@ -29,6 +29,7 @@ export async function runSessionCreate(options, deps) {
                 uploadType: parseFileType(options.uploadType),
                 appName: optionalString("appName", options.appName),
                 bundleId: optionalString("bundleId", options.bundleId),
+                userDeviceId: optionalString("userDeviceId", options.userDeviceId),
             };
         }
         catch (err) {
@@ -63,6 +64,10 @@ export default defineCommand({
         "upload-type": { type: "string", description: "ANDROID_APP | IOS_APP" },
         "app-name": { type: "string" },
         "bundle-id": { type: "string" },
+        "user-device-id": {
+            type: "string",
+            description: "Run on a registered local device (BYOD desktop or local mobile)",
+        },
         json: { type: "string", description: "Raw JSON request body (replaces individual flags)" },
         "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
     },
@@ -82,6 +87,7 @@ export default defineCommand({
             uploadType: args["upload-type"],
             appName: args["app-name"],
             bundleId: args["bundle-id"],
+            userDeviceId: args["user-device-id"],
             json: args.json,
             dryRun: args["dry-run"],
         }));

package/dist/index.d.ts

@@ -3,6 +3,9 @@ export { getApiKey, getBaseUrl, request } from "./client.js";
 export { runCaseCreate } from "./commands/case/create.js";
 export { runDeviceList } from "./commands/device/list.js";
 export { runHealthCheck } from "./commands/health/check.js";
+export { runMobileList } from "./commands/mobile/list.js";
+export { runMobileRegister } from "./commands/mobile/register.js";
+export { runMobileDoctor } from "./commands/mobile/doctor.js";
 export { runPlanAddCase } from "./commands/plan/add-case.js";
 export { runPlanCreate } from "./commands/plan/create.js";
 export { runPlanRemoveCase } from "./commands/plan/remove-case.js";

package/dist/index.js

@@ -2,6 +2,9 @@ export { getApiKey, getBaseUrl, request } from "./client.js";
 export { runCaseCreate } from "./commands/case/create.js";
 export { runDeviceList } from "./commands/device/list.js";
 export { runHealthCheck } from "./commands/health/check.js";
+export { runMobileList } from "./commands/mobile/list.js";
+export { runMobileRegister } from "./commands/mobile/register.js";
+export { runMobileDoctor } from "./commands/mobile/doctor.js";
 export { runPlanAddCase } from "./commands/plan/add-case.js";
 export { runPlanCreate } from "./commands/plan/create.js";
 export { runPlanRemoveCase } from "./commands/plan/remove-case.js";

package/dist/mobile-control/appium-controller.d.ts

@@ -0,0 +1,39 @@
+import type { ActionResult, MobileController } from "./controller.js";
+import { type WebDriverTransport } from "./webdriver.js";
+export interface AppiumControllerOptions {
+    endpoint: string;
+    platform: "ios" | "android";
+    target: string;
+    transport?: WebDriverTransport;
+}
+export declare class AppiumController implements MobileController {
+    private readonly session;
+    private readonly platform;
+    private readonly target;
+    private sessionReady;
+    private scaling;
+    constructor(opts: AppiumControllerOptions);
+    private capabilities;
+    private ensureSession;
+    private scale;
+    private toPoint;
+    private pointerAction;
+    screenshot(): Promise<Buffer>;
+    tap(x: number, y: number): Promise<void>;
+    doubleTap(x: number, y: number): Promise<void>;
+    longPress(x: number, y: number, durationMs: number): Promise<void>;
+    swipe(x1: number, y1: number, x2: number, y2: number, durationMs: number): Promise<void>;
+    private performPointer;
+    typeText(text: string): Promise<ActionResult>;
+    clearText(): Promise<ActionResult>;
+    pressKey(key: string): Promise<ActionResult>;
+    launchApp(app: string): Promise<ActionResult>;
+    findElement(text: string): Promise<ActionResult>;
+    private locate;
+    hideKeyboard(): Promise<ActionResult>;
+    getDeviceTime(): Promise<{
+        datetime: string;
+        timezone: string;
+    } | null>;
+    close(): Promise<void>;
+}

package/dist/mobile-control/appium-controller.js

@@ -0,0 +1,367 @@
+import { fetchTransport, WebDriverSession } from "./webdriver.js";
+const ANDROID_KEY_CODES = {
+    enter: 66,
+    delete: 67,
+    tab: 61,
+    space: 62,
+    escape: 111,
+    back: 4,
+    home: 3,
+};
+const ANDROID_KEYCODE_A = 29;
+const ANDROID_META_CTRL_ON = 4096;
+const IOS_BUTTONS = {
+    home: "home",
+};
+const W3C_KEYS = {
+    enter: "\uE007",
+    delete: "\uE003",
+    tab: "\uE004",
+    escape: "\uE00C",
+    space: " ",
+};
+export class AppiumController {
+    session;
+    platform;
+    target;
+    sessionReady = null;
+    scaling = null;
+    constructor(opts) {
+        this.platform = opts.platform;
+        this.target = opts.target;
+        const transport = opts.transport ?? fetchTransport(opts.endpoint);
+        this.session = new WebDriverSession(transport);
+    }
+    capabilities() {
+        if (this.platform === "android") {
+            return {
+                platformName: "Android",
+                "appium:automationName": "UiAutomator2",
+                "appium:udid": this.target,
+                "appium:noReset": true,
+                "appium:autoLaunch": false,
+                "appium:newCommandTimeout": 0,
+            };
+        }
+        return {
+            platformName: "iOS",
+            "appium:automationName": "XCUITest",
+            "appium:udid": this.target,
+            "appium:newCommandTimeout": 0,
+        };
+    }
+    ensureSession() {
+        if (!this.sessionReady) {
+            this.sessionReady = this.session
+                .createSession(this.capabilities())
+                .then(() => undefined)
+                .catch((err) => {
+                this.sessionReady = null;
+                throw err;
+            });
+        }
+        return this.sessionReady;
+    }
+    // Incoming pixel coords scale to logical points: iOS divides by DPR, Android ~= 1.
+    async scale() {
+        if (this.scaling)
+            return this.scaling.scale;
+        const [rect, shot] = await Promise.all([this.session.windowRect(), this.session.screenshot()]);
+        const pixelWidth = readPngWidth(shot);
+        const scale = rect.width > 0 && pixelWidth > 0 ? pixelWidth / rect.width : 1;
+        this.scaling = { scale: scale > 0 ? scale : 1 };
+        return this.scaling.scale;
+    }
+    async toPoint(x, y) {
+        const s = await this.scale();
+        return [Math.round(x / s), Math.round(y / s)];
+    }
+    pointerAction(actions) {
+        return [
+            {
+                type: "pointer",
+                id: "finger1",
+                parameters: { pointerType: "touch" },
+                actions,
+            },
+        ];
+    }
+    async screenshot() {
+        await this.ensureSession();
+        return this.session.screenshot();
+    }
+    async tap(x, y) {
+        await this.ensureSession();
+        const [px, py] = await this.toPoint(x, y);
+        await this.performPointer([
+            { type: "pointerMove", duration: 0, x: px, y: py },
+            { type: "pointerDown", button: 0 },
+            { type: "pause", duration: 50 },
+            { type: "pointerUp", button: 0 },
+        ]);
+    }
+    async doubleTap(x, y) {
+        await this.ensureSession();
+        const [px, py] = await this.toPoint(x, y);
+        await this.performPointer([
+            { type: "pointerMove", duration: 0, x: px, y: py },
+            { type: "pointerDown", button: 0 },
+            { type: "pause", duration: 50 },
+            { type: "pointerUp", button: 0 },
+            { type: "pause", duration: 50 },
+            { type: "pointerDown", button: 0 },
+            { type: "pause", duration: 50 },
+            { type: "pointerUp", button: 0 },
+        ]);
+    }
+    async longPress(x, y, durationMs) {
+        await this.ensureSession();
+        const [px, py] = await this.toPoint(x, y);
+        await this.performPointer([
+            { type: "pointerMove", duration: 0, x: px, y: py },
+            { type: "pointerDown", button: 0 },
+            { type: "pause", duration: Math.max(0, Math.round(durationMs)) },
+            { type: "pointerUp", button: 0 },
+        ]);
+    }
+    async swipe(x1, y1, x2, y2, durationMs) {
+        await this.ensureSession();
+        const [px1, py1] = await this.toPoint(x1, y1);
+        const [px2, py2] = await this.toPoint(x2, y2);
+        await this.performPointer([
+            { type: "pointerMove", duration: 0, x: px1, y: py1 },
+            { type: "pointerDown", button: 0 },
+            { type: "pointerMove", duration: Math.max(0, Math.round(durationMs)), x: px2, y: py2 },
+            { type: "pointerUp", button: 0 },
+        ]);
+    }
+    async performPointer(actions) {
+        await this.session.performActions(this.pointerAction(actions));
+        await this.session.releaseActions();
+    }
+    async typeText(text) {
+        await this.ensureSession();
+        try {
+            if (this.platform === "android") {
+                await this.session.execute("mobile: type", [{ text }]);
+                return { ok: true };
+            }
+            await this.session.setValueOnActiveElement(text);
+            return { ok: true };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async clearText() {
+        await this.ensureSession();
+        try {
+            const active = await this.session.getActiveElement();
+            if (active) {
+                await this.session.elementClear(active);
+                return { ok: true };
+            }
+        }
+        catch { }
+        if (this.platform === "android") {
+            try {
+                await this.session.execute("mobile: pressKey", [
+                    { keycode: ANDROID_KEYCODE_A, metastate: ANDROID_META_CTRL_ON },
+                ]);
+                await this.session.execute("mobile: pressKey", [{ keycode: ANDROID_KEY_CODES["delete"] }]);
+                return { ok: true };
+            }
+            catch (error) {
+                return fail(error);
+            }
+        }
+        return {
+            ok: false,
+            error: "Could not clear the field: no focused input element was found. " +
+                "Tap the field to focus it before calling clear_text.",
+        };
+    }
+    async pressKey(key) {
+        await this.ensureSession();
+        const normalized = key.toLowerCase().trim();
+        try {
+            if (this.platform === "android") {
+                const code = ANDROID_KEY_CODES[normalized];
+                if (code === undefined)
+                    return { ok: false, error: `Unsupported key: ${key}` };
+                await this.session.execute("mobile: pressKey", [{ keycode: code }]);
+                return { ok: true };
+            }
+            if (normalized === "back") {
+                return {
+                    ok: false,
+                    error: '"back" key is Android-only. On iOS, tap the back button in the UI instead.',
+                };
+            }
+            const button = IOS_BUTTONS[normalized];
+            if (button) {
+                await this.session.execute("mobile: pressButton", [{ name: button }]);
+                return { ok: true };
+            }
+            const w3c = W3C_KEYS[normalized];
+            if (w3c) {
+                await this.session.performActions([
+                    {
+                        type: "key",
+                        id: "keyboard",
+                        actions: [
+                            { type: "keyDown", value: w3c },
+                            { type: "keyUp", value: w3c },
+                        ],
+                    },
+                ]);
+                await this.session.releaseActions();
+                return { ok: true };
+            }
+            return { ok: false, error: `Unsupported key: ${key}` };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async launchApp(app) {
+        if (!app)
+            return { ok: false, error: "launch_app requires an app id" };
+        await this.ensureSession();
+        try {
+            const param = this.platform === "android" ? { appId: app } : { bundleId: app };
+            await this.session.execute("mobile: activateApp", [param]);
+            return { ok: true };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async findElement(text) {
+        if (!text)
+            return { ok: false, error: "find_element requires text" };
+        await this.ensureSession();
+        try {
+            const ref = await this.locate(text);
+            if (!ref)
+                return { ok: false, error: `Element with text "${text}" not found` };
+            await this.session.elementClick(ref);
+            return { ok: true };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    }
+    async locate(text) {
+        const strategies = this.platform === "android" ? androidStrategies(text) : iosStrategies(text);
+        for (const [using, value] of strategies) {
+            try {
+                const ref = await this.session.findElement(using, value);
+                if (ref)
+                    return ref;
+            }
+            catch { }
+        }
+        return null;
+    }
+    async hideKeyboard() {
+        await this.ensureSession();
+        try {
+            await this.session.execute("mobile: hideKeyboard", []);
+            return { ok: true };
+        }
+        catch {
+            return { ok: true };
+        }
+    }
+    async getDeviceTime() {
+        await this.ensureSession();
+        try {
+            const raw = await this.session.execute("mobile: getDeviceTime", []);
+            if (typeof raw !== "string" || raw.trim().length === 0)
+                return null;
+            const parsed = new Date(raw);
+            if (Number.isNaN(parsed.getTime()))
+                return null;
+            return {
+                datetime: humanizeDateTime(parsed),
+                timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async close() {
+        try {
+            await this.session.deleteSession();
+        }
+        catch { }
+    }
+}
+// Builds an XPath string literal that is safe even when `s` contains single quotes.
+function xpathLiteral(s) {
+    if (!s.includes("'"))
+        return `'${s}'`;
+    const parts = s.split("'").map((part) => `'${part}'`);
+    return `concat(${parts.join(`, "'", `)})`;
+}
+// Escapes backslashes and double quotes for a Java UiSelector string argument.
+function uiSelectorLiteral(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+// Escapes single quotes for an iOS NSPredicate string literal.
+function iosPredicateLiteral(s) {
+    return s.replace(/'/g, "\\'");
+}
+function androidStrategies(text) {
+    const lower = text.toLowerCase();
+    return [
+        ["accessibility id", text],
+        ["id", text],
+        ["xpath", `//*[@text=${xpathLiteral(text)}]`],
+        [
+            "xpath",
+            `//*[contains(translate(@text, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz'), ${xpathLiteral(lower)})]`,
+        ],
+        ["xpath", `//*[@content-desc=${xpathLiteral(text)}]`],
+        ["xpath", `//*[contains(@content-desc, ${xpathLiteral(text)})]`],
+        ["-android uiautomator", `new UiSelector().textContains("${uiSelectorLiteral(text)}")`],
+    ];
+}
+function iosStrategies(text) {
+    const v = iosPredicateLiteral(text);
+    return [
+        ["-ios predicate string", `type == 'XCUIElementTypeButton' AND label == '${v}'`],
+        ["-ios predicate string", `type == 'XCUIElementTypeButton' AND name == '${v}'`],
+        ["accessibility id", text],
+        ["name", text],
+        ["-ios predicate string", `label == '${v}'`],
+        ["-ios predicate string", `name == '${v}'`],
+        ["-ios predicate string", `label CONTAINS '${v}'`],
+    ];
+}
+function humanizeDateTime(date) {
+    return date.toLocaleString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+    });
+}
+function fail(error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+}
+function readPngWidth(buffer) {
+    if (buffer.length < 24)
+        return 0;
+    try {
+        return buffer.readUInt32BE(16);
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/mobile-control/appium-controller.test.d.ts

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