@autifyhq/aximo-cli 0.4.0 → 0.5.0

package/dist/commands/mobile/doctor.js

@@ -0,0 +1,143 @@
+import { defineCommand } from "citty";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { formatSuccess, printResult } from "../../output.js";
+import { importAppium } from "../../mobile-control/appium-import.js";
+import { getAppiumHome, resolveAndroidSdk } from "../../mobile-control/appium-server.js";
+function which(cmd) {
+    const probe = platform() === "win32" ? "where" : "which";
+    const result = spawnSync(probe, [cmd], { encoding: "utf-8" });
+    return result.status === 0 ? (result.stdout || "").split("\n")[0]?.trim() || cmd : null;
+}
+function driverInstalled(driver) {
+    return existsSync(join(getAppiumHome(), "node_modules", `appium-${driver}-driver`));
+}
+function adbInstallHint() {
+    switch (platform()) {
+        case "darwin":
+            return "Install Android platform-tools (brew install --cask android-platform-tools).";
+        case "linux":
+            return "Install Android platform-tools (apt install android-tools-adb, or your distro's adb package).";
+        case "win32":
+            return "Install platform-tools via the Android Studio SDK Manager.";
+        default:
+            return "Install Android platform-tools (adb).";
+    }
+}
+async function checkAppium() {
+    try {
+        const mod = await importAppium();
+        if (typeof mod.main === "function") {
+            return { name: "appium", status: "pass", message: "bundled Appium server is importable" };
+        }
+        return {
+            name: "appium",
+            status: "fail",
+            message: "appium is installed but exposes no programmatic `main`",
+        };
+    }
+    catch (err) {
+        return {
+            name: "appium",
+            status: "fail",
+            message: err instanceof Error ? err.message : String(err),
+            hint: "Reinstall the CLI; the bundled Appium dependency appears to be missing.",
+        };
+    }
+}
+function checkAndroid() {
+    const checks = [];
+    checks.push(driverInstalled("uiautomator2")
+        ? { name: "uiautomator2 driver", status: "pass", message: "installed" }
+        : {
+            name: "uiautomator2 driver",
+            status: "warn",
+            message: "Appium UiAutomator2 driver not installed",
+            hint: "Run `aximo mobile setup` to install Appium drivers.",
+        });
+    const adb = which("adb");
+    checks.push(adb
+        ? { name: "adb", status: "pass", message: adb }
+        : {
+            name: "adb",
+            status: "fail",
+            message: "adb not found in PATH",
+            hint: `${adbInstallHint()} Appium delegates to adb.`,
+        });
+    const sdk = resolveAndroidSdk();
+    checks.push(sdk
+        ? { name: "android sdk", status: "pass", message: sdk }
+        : {
+            name: "android sdk",
+            status: "fail",
+            message: "Android SDK not found (ANDROID_HOME/ANDROID_SDK_ROOT unset)",
+            hint: "Set ANDROID_HOME to your Android SDK — Appium's UiAutomator2 driver requires it even though adb is on PATH — or install it via Android Studio.",
+        });
+    return checks;
+}
+function checkIos() {
+    if (platform() !== "darwin") {
+        return [
+            { name: "ios", status: "info", message: "iOS device control is only available on macOS" },
+        ];
+    }
+    const checks = [];
+    checks.push(driverInstalled("xcuitest")
+        ? { name: "xcuitest driver", status: "pass", message: "installed" }
+        : {
+            name: "xcuitest driver",
+            status: "warn",
+            message: "Appium XCUITest driver not installed",
+            hint: "Run `aximo mobile setup` to install Appium drivers.",
+        });
+    const xcrun = which("xcrun");
+    checks.push(xcrun
+        ? { name: "xcrun", status: "pass", message: xcrun }
+        : {
+            name: "xcrun",
+            status: "warn",
+            message: "xcrun not found",
+            hint: "Install Xcode command line tools: xcode-select --install. Appium's XCUITest driver delegates to Xcode.",
+        });
+    checks.push({
+        name: "ios webdriveragent",
+        status: "info",
+        message: "Physical iPhones are driven via Appium's XCUITest driver, which builds and installs a WebDriverAgent runner on the device.",
+        hint: "WDA needs an Apple Developer signing identity; enable Developer Mode (Settings → Privacy & Security) and trust the device.",
+    });
+    return checks;
+}
+export async function runMobileDoctor(options = {}) {
+    const checks = [await checkAppium()];
+    if (options.platform !== "ios") {
+        checks.push(...checkAndroid());
+    }
+    if (options.platform !== "android") {
+        checks.push(...checkIos());
+    }
+    const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+    for (const c of checks)
+        summary[c.status]++;
+    return formatSuccess({ checks, summary });
+}
+export default defineCommand({
+    meta: {
+        name: "doctor",
+        description: "Diagnose Appium prerequisites (bundled server, drivers, adb/Xcode delegates)",
+    },
+    args: {
+        platform: { type: "string", description: "Limit checks to ios | android" },
+    },
+    async run({ args }) {
+        const options = {};
+        if (args.platform === "ios" || args.platform === "android")
+            options.platform = args.platform;
+        const result = await runMobileDoctor(options);
+        printResult(result);
+        if (result.ok && result.data.summary.fail > 0) {
+            process.exitCode = 1;
+        }
+    },
+});

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

@@ -0,0 +1,2 @@
+declare const _default: import("citty").CommandDef<import("citty").ArgsDef>;
+export default _default;

package/dist/commands/mobile/index.js

@@ -0,0 +1,15 @@
+import { defineCommand } from "citty";
+export default defineCommand({
+    meta: {
+        name: "mobile",
+        description: "Register and connect a phone to Aximo via a CLI-managed Appium server",
+    },
+    subCommands: {
+        list: () => import("./list.js").then((m) => m.default),
+        register: () => import("./register.js").then((m) => m.default),
+        unregister: () => import("./unregister.js").then((m) => m.default),
+        connect: () => import("./connect.js").then((m) => m.default),
+        setup: () => import("./setup.js").then((m) => m.default),
+        doctor: () => import("./doctor.js").then((m) => m.default),
+    },
+});

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

@@ -0,0 +1,10 @@
+import type { Envelope } from "../../types.js";
+import { type AndroidDevice, type IosPhysicalDevice } from "../../mobile-control/devices.js";
+import type { ExecFn } from "../../mobile-control/exec.js";
+export interface MobileListResult {
+    androidDevices: AndroidDevice[];
+    iosDevices: IosPhysicalDevice[];
+}
+export declare function runMobileList(exec?: ExecFn): Promise<Envelope<MobileListResult>>;
+declare const _default: import("citty").CommandDef<{}>;
+export default _default;

package/dist/commands/mobile/list.js

@@ -0,0 +1,30 @@
+import { defineCommand } from "citty";
+import { formatSuccess, printResult } from "../../output.js";
+import { listAndroidDevices, listIosPhysicalDevices, } from "../../mobile-control/devices.js";
+async function safe(fn, fallback) {
+    try {
+        return await fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function runMobileList(exec) {
+    const [allAndroid, iosDevices] = await Promise.all([
+        safe(() => listAndroidDevices(exec), []),
+        safe(() => listIosPhysicalDevices(exec), []),
+    ]);
+    // Physical phones only: drop emulator serials.
+    const androidDevices = allAndroid.filter((d) => !d.serial.startsWith("emulator-"));
+    return formatSuccess({ androidDevices, iosDevices });
+}
+export default defineCommand({
+    meta: {
+        name: "list",
+        description: "List physically-connected phones (Android via adb, iOS via idb)",
+    },
+    args: {},
+    async run() {
+        printResult(await runMobileList());
+    },
+});

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

@@ -0,0 +1,14 @@
+export type MobilePlatform = "ios" | "android";
+export interface MobileDeviceConfig {
+    deviceId: string;
+    deviceToken: string;
+    name: string;
+    platform: MobilePlatform;
+    /** udid for iOS, adb serial for Android. */
+    target: string;
+}
+export declare function getMobileDevicesDir(): string;
+export declare function getMobileDeviceConfigPath(deviceId: string): string;
+export declare function writeMobileDeviceConfig(config: MobileDeviceConfig): string;
+export declare function readMobileDeviceConfig(deviceId: string): MobileDeviceConfig | null;
+export declare function listMobileDeviceConfigs(): MobileDeviceConfig[];

package/dist/commands/mobile/paths.js

@@ -0,0 +1,71 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { getAximoDir } from "../device/paths.js";
+export function getMobileDevicesDir() {
+    return join(getAximoDir(), "mobile-devices");
+}
+export function getMobileDeviceConfigPath(deviceId) {
+    return join(getMobileDevicesDir(), `${deviceId}.json`);
+}
+export function writeMobileDeviceConfig(config) {
+    const dir = getMobileDevicesDir();
+    mkdirSync(dir, { recursive: true });
+    const path = getMobileDeviceConfigPath(config.deviceId);
+    writeFileSync(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // chmod may fail on Windows; file-level ACLs apply instead.
+    }
+    return path;
+}
+function parseConfig(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const c = raw;
+    if (typeof c.deviceId !== "string" ||
+        typeof c.deviceToken !== "string" ||
+        typeof c.name !== "string" ||
+        (c.platform !== "ios" && c.platform !== "android") ||
+        typeof c.target !== "string") {
+        return null;
+    }
+    return {
+        deviceId: c.deviceId,
+        deviceToken: c.deviceToken,
+        name: c.name,
+        platform: c.platform,
+        target: c.target,
+    };
+}
+export function readMobileDeviceConfig(deviceId) {
+    const path = getMobileDeviceConfigPath(deviceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return parseConfig(JSON.parse(readFileSync(path, "utf-8")));
+    }
+    catch {
+        return null;
+    }
+}
+export function listMobileDeviceConfigs() {
+    const dir = getMobileDevicesDir();
+    if (!existsSync(dir))
+        return [];
+    const result = [];
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const parsed = parseConfig(JSON.parse(readFileSync(join(dir, file), "utf-8")));
+            if (parsed)
+                result.push(parsed);
+        }
+        catch {
+            // skip unreadable entries
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,19 @@
+import { type ClientDeps } from "../../client.js";
+import type { Envelope } from "../../types.js";
+import { type MobilePlatform } from "./paths.js";
+export interface MobileRegisterResult {
+    deviceId: string;
+    name: string;
+    platform: MobilePlatform;
+    target: string;
+    configPath: string;
+}
+export interface MobileRegisterOptions {
+    name: string;
+    platform: MobilePlatform;
+    target: string;
+    os?: string;
+}
+/** Shared registration: POST /api/devices/register and persist the config. */
+export declare function registerMobileDevice(options: MobileRegisterOptions, deps?: ClientDeps): Promise<Envelope<MobileRegisterResult>>;
+export declare function parsePlatformArg(value: string | undefined): MobilePlatform | null;

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

@@ -0,0 +1,46 @@
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { formatError, formatSuccess } from "../../output.js";
+import { writeMobileDeviceConfig } from "./paths.js";
+/** Shared registration: POST /api/devices/register and persist the config. */
+export async function registerMobileDevice(options, deps) {
+    if (!options.name) {
+        return formatError("validation_error", "Device name is required (--name).", false);
+    }
+    if (!options.target) {
+        return formatError("validation_error", options.platform === "ios"
+            ? "Could not resolve a device target (--udid)."
+            : "Could not resolve a device target (--serial).", false);
+    }
+    try {
+        const body = {
+            name: options.name,
+            platform: options.platform,
+        };
+        if (options.os)
+            body["os"] = options.os;
+        const res = await request("/api/devices/register", { method: "POST", body }, deps ?? {});
+        const configPath = writeMobileDeviceConfig({
+            deviceId: res.deviceId,
+            deviceToken: res.deviceToken,
+            name: options.name,
+            platform: options.platform,
+            target: options.target,
+        });
+        return formatSuccess({
+            deviceId: res.deviceId,
+            name: options.name,
+            platform: options.platform,
+            target: options.target,
+            configPath,
+        });
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export function parsePlatformArg(value) {
+    if (value === "ios" || value === "android")
+        return value;
+    return null;
+}

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

@@ -0,0 +1,32 @@
+import { type ClientDeps } from "../../client.js";
+import type { Envelope } from "../../types.js";
+import type { ExecFn } from "../../mobile-control/exec.js";
+import { type MobileRegisterResult } from "./register-core.js";
+export interface MobileRegisterCmdOptions {
+    name: string;
+    platform: string;
+    serial?: string | undefined;
+    os?: string | undefined;
+}
+export declare function runMobileRegister(options: MobileRegisterCmdOptions, deps?: ClientDeps, exec?: ExecFn): Promise<Envelope<MobileRegisterResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly name: {
+        readonly type: "string";
+        readonly description: "Device name";
+        readonly required: true;
+    };
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "Device platform (only `android` is supported today)";
+        readonly default: "android";
+    };
+    readonly serial: {
+        readonly type: "string";
+        readonly description: "Android adb serial (defaults to the connected one)";
+    };
+    readonly os: {
+        readonly type: "string";
+        readonly description: "Optional OS version label";
+    };
+}>;
+export default _default;

package/dist/commands/mobile/register.js

@@ -0,0 +1,51 @@
+import { defineCommand } from "citty";
+import {} from "../../client.js";
+import { formatError, printResult } from "../../output.js";
+import { resolveAndroidSerial } from "../../mobile-control/devices.js";
+import { parsePlatformArg, registerMobileDevice, } from "./register-core.js";
+export async function runMobileRegister(options, deps, exec) {
+    const platform = parsePlatformArg(options.platform);
+    if (platform !== "android") {
+        return formatError("validation_error", "Only --platform android is supported (iOS local devices are coming in a future release).", false);
+    }
+    if (!options.name) {
+        return formatError("validation_error", "Device name is required (--name).", false);
+    }
+    let target;
+    try {
+        target = await resolveAndroidSerial(options.serial, exec);
+    }
+    catch (err) {
+        return formatError("validation_error", err instanceof Error ? err.message : String(err), false);
+    }
+    return registerMobileDevice({
+        name: options.name,
+        platform,
+        target,
+        ...(options.os ? { os: options.os } : {}),
+    }, deps);
+}
+export default defineCommand({
+    meta: {
+        name: "register",
+        description: "Register a physically-connected Android phone as an Aximo device",
+    },
+    args: {
+        name: { type: "string", description: "Device name", required: true },
+        platform: {
+            type: "string",
+            description: "Device platform (only `android` is supported today)",
+            default: "android",
+        },
+        serial: { type: "string", description: "Android adb serial (defaults to the connected one)" },
+        os: { type: "string", description: "Optional OS version label" },
+    },
+    async run({ args }) {
+        printResult(await runMobileRegister({
+            name: args.name,
+            platform: args.platform,
+            serial: args.serial,
+            os: args.os,
+        }));
+    },
+});

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

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

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

@@ -0,0 +1,60 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
+import { runMobileRegister } from "./register.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-mob-reg-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterAll(() => {
+    delete process.env["AXIMO_HOME"];
+    server.close();
+    rmSync(tempHome, { recursive: true, force: true });
+});
+beforeEach(() => {
+    rmSync(tempHome, { recursive: true, force: true });
+    mkdirSync(tempHome, { recursive: true });
+});
+afterEach(() => server.resetHandlers());
+const oneAndroidDevice = async () => ({
+    stdout: Buffer.from("List of devices attached\nR58M12345  device model:Pixel_7\n"),
+    stderr: "",
+});
+describe("runMobileRegister", () => {
+    it("posts the resolved android serial and writes config", async () => {
+        let body;
+        server.use(http.post(`${TEST_BASE_URL}/api/devices/register`, async ({ request }) => {
+            body = (await request.json());
+            return HttpResponse.json({ deviceId: "dev-9", deviceToken: "tok-9" }, { status: 201 });
+        }));
+        const result = await runMobileRegister({ name: "My Pixel", platform: "android" }, undefined, oneAndroidDevice);
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(body).toMatchObject({
+            name: "My Pixel",
+            platform: "android",
+        });
+        expect(body).not.toHaveProperty("category");
+        expect(result.data.target).toBe("R58M12345");
+        const configPath = join(tempHome, "mobile-devices", "dev-9.json");
+        expect(existsSync(configPath)).toBe(true);
+        const saved = JSON.parse(readFileSync(configPath, "utf-8"));
+        expect(saved).toMatchObject({ platform: "android", target: "R58M12345" });
+        expect(saved).not.toHaveProperty("category");
+    });
+    it("rejects iOS registration as unsupported", async () => {
+        const result = await runMobileRegister({ name: "iPhone", platform: "ios" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toContain("Only --platform android is supported");
+        }
+    });
+});

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

@@ -0,0 +1,27 @@
+import type { Envelope } from "../../types.js";
+import { type MobileDoctorReport } from "./doctor.js";
+export interface DriverSetupResult {
+    driver: string;
+    alreadyInstalled: boolean;
+}
+export interface SetupResult {
+    appiumHome: string;
+    drivers: DriverSetupResult[];
+}
+export type DriverInstaller = (driver: string, appiumHome: string) => Promise<void>;
+export interface RunMobileSetupOptions {
+    platform?: "ios" | "android" | undefined;
+    install?: DriverInstaller;
+    appiumHome?: string;
+    doctor?: (options: {
+        platform?: "ios" | "android" | undefined;
+    }) => Promise<Envelope<MobileDoctorReport>>;
+}
+export declare function runMobileSetup(options?: RunMobileSetupOptions): Promise<Envelope<SetupResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "Limit to ios | android driver";
+    };
+}>;
+export default _default;

package/dist/commands/mobile/setup.js

@@ -0,0 +1,100 @@
+import { defineCommand } from "citty";
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { formatError, formatSuccess, printResult } from "../../output.js";
+import { getAppiumHome } from "../../mobile-control/appium-server.js";
+import { runMobileDoctor } from "./doctor.js";
+const DRIVER_PACKAGE = {
+    uiautomator2: "appium-uiautomator2-driver",
+    xcuitest: "appium-xcuitest-driver",
+};
+function resolveAppiumBin() {
+    const require = createRequire(import.meta.url);
+    return require.resolve("appium");
+}
+const defaultInstaller = (driver, appiumHome) => new Promise((resolve, reject) => {
+    execFile(process.execPath, [resolveAppiumBin(), "driver", "install", driver], { env: { ...process.env, APPIUM_HOME: appiumHome }, maxBuffer: 16 * 1024 * 1024 }, (error, _stdout, stderr) => {
+        if (error) {
+            reject(new Error(stderr?.toString().trim() || error.message));
+            return;
+        }
+        resolve();
+    });
+});
+function isInstalled(driver, appiumHome) {
+    const pkg = DRIVER_PACKAGE[driver];
+    return pkg ? existsSync(join(appiumHome, "node_modules", pkg)) : false;
+}
+// After installing drivers, tell the user what is still required to drive a real
+// device (adb / Xcode / Developer Mode) rather than implying setup is complete.
+function printNextSteps(checks) {
+    const blockers = checks.filter((c) => c.status === "fail" || c.status === "warn");
+    const notes = checks.filter((c) => c.status === "info");
+    if (blockers.length === 0) {
+        console.error("\nAll required prerequisites are satisfied.");
+    }
+    else {
+        console.error("\nDrivers installed, but you still need to set up:");
+        for (const c of blockers) {
+            console.error(`  - ${c.message}`);
+            if (c.hint)
+                console.error(`      ${c.hint}`);
+        }
+    }
+    for (const c of notes) {
+        console.error(`\nNote: ${c.message}`);
+        if (c.hint)
+            console.error(`      ${c.hint}`);
+    }
+    console.error("\nNext: aximo mobile register --platform android  ->  aximo mobile connect  (recheck: aximo mobile doctor)");
+}
+export async function runMobileSetup(options = {}) {
+    const appiumHome = options.appiumHome ?? getAppiumHome();
+    const install = options.install ?? defaultInstaller;
+    mkdirSync(appiumHome, { recursive: true });
+    const drivers = [];
+    if (options.platform !== "ios")
+        drivers.push("uiautomator2");
+    if (options.platform !== "android")
+        drivers.push("xcuitest");
+    const results = [];
+    for (const driver of drivers) {
+        if (isInstalled(driver, appiumHome)) {
+            console.error(`Appium driver "${driver}" already installed.`);
+            results.push({ driver, alreadyInstalled: true });
+            continue;
+        }
+        console.error(`Installing Appium driver "${driver}"...`);
+        try {
+            await install(driver, appiumHome);
+        }
+        catch (err) {
+            return formatError("api_error", `Failed to install Appium driver "${driver}": ${err instanceof Error ? err.message : String(err)}`, true);
+        }
+        console.error(`Installed Appium driver "${driver}".`);
+        results.push({ driver, alreadyInstalled: false });
+    }
+    // Surface remaining prerequisites as concise guidance; `doctor` owns the full report.
+    const runDoctor = options.doctor ?? runMobileDoctor;
+    const report = await runDoctor({ platform: options.platform });
+    printNextSteps(report.ok ? report.data.checks : []);
+    return formatSuccess({ appiumHome, drivers: results });
+}
+export default defineCommand({
+    meta: {
+        name: "setup",
+        description: "Install the Appium drivers used to drive registered phones",
+    },
+    args: {
+        platform: { type: "string", description: "Limit to ios | android driver" },
+    },
+    async run({ args }) {
+        const options = {};
+        if (args.platform === "ios" || args.platform === "android")
+            options.platform = args.platform;
+        const result = await runMobileSetup(options);
+        printResult(result);
+    },
+});

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

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