@autifyhq/aximo-cli 0.1.0

package/dist/commands/device/doctor.js

@@ -0,0 +1,421 @@
+import { defineCommand } from "citty";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { platform } from "node:os";
+import { WebSocket } from "ws";
+import { getBaseUrl, request } from "../../client.js";
+import { formatSuccess, printResult } from "../../output.js";
+import { loadConfig } from "../../config.js";
+import { readCachedManifest } from "../../desktop-server/agent-sync.js";
+import { installedPythonTag, PYTHON_RELEASE, PYTHON_VERSION } from "../../desktop-server/setup.js";
+import { getAgentRequirementsPath, getAgentScriptPath, getDepsMarkerPath, getDeviceConfigPath, getEmbeddedPythonBinary, getPythonDir, getPythonMarkerPath, } from "./paths.js";
+function redactKey(value) {
+    if (value.length <= 8)
+        return "***";
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+function checkApiKey() {
+    // Match the runtime precedence in client.ts: config file > env > default.
+    const config = loadConfig();
+    const source = config.apiKey ? "config file" : process.env["AXIMO_API_KEY"] ? "env" : null;
+    const value = config.apiKey ?? process.env["AXIMO_API_KEY"];
+    if (!value || !source) {
+        return {
+            name: "API key",
+            status: "fail",
+            message: "not set",
+            hint: "Run: aximo configure (or export AXIMO_API_KEY=...)",
+        };
+    }
+    return {
+        name: "API key",
+        status: "pass",
+        message: `set via ${source} (${redactKey(value)})`,
+    };
+}
+function checkBaseUrl() {
+    const config = loadConfig();
+    const resolved = getBaseUrl();
+    if (config.baseUrl) {
+        return { name: "base URL", status: "pass", message: `${resolved} (from config file)` };
+    }
+    if (process.env["AXIMO_BASE_URL"]) {
+        return { name: "base URL", status: "pass", message: `${resolved} (from env)` };
+    }
+    return { name: "base URL", status: "info", message: `default: ${resolved}` };
+}
+function checkProxyEnv() {
+    const vars = ["HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy"];
+    const present = vars.filter((v) => process.env[v]);
+    if (present.length === 0) {
+        return { name: "proxy", status: "info", message: "no proxy env vars set" };
+    }
+    return { name: "proxy", status: "info", message: `proxy vars present: ${present.join(", ")}` };
+}
+async function checkApiHealth(deps) {
+    try {
+        await request("/api/health", {}, deps ?? {});
+        return { name: "aximo API health", status: "pass", message: "reachable" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "aximo API health",
+            status: "fail",
+            message,
+            hint: "Check AXIMO_BASE_URL and network connectivity",
+        };
+    }
+}
+function checkDeviceConfig() {
+    const configPath = getDeviceConfigPath();
+    if (!existsSync(configPath)) {
+        return {
+            check: {
+                name: "device registered",
+                status: "warn",
+                message: "no local device config",
+                hint: 'Run: aximo device register --name "My PC"',
+            },
+        };
+    }
+    try {
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!config.deviceId) {
+            return {
+                check: {
+                    name: "device registered",
+                    status: "fail",
+                    message: "device.json missing deviceId",
+                    hint: "Re-register: aximo device register --name ...",
+                },
+            };
+        }
+        return {
+            check: {
+                name: "device registered",
+                status: "pass",
+                message: `${config.name ?? "(unnamed)"} · ${config.deviceId}`,
+            },
+            config,
+        };
+    }
+    catch (err) {
+        return {
+            check: {
+                name: "device registered",
+                status: "fail",
+                message: `device.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
+                hint: "Delete the file and re-register",
+            },
+        };
+    }
+}
+function checkEmbeddedPython() {
+    if (!existsSync(getPythonDir())) {
+        return {
+            name: "embedded Python",
+            status: "fail",
+            message: "not installed",
+            hint: "Run: aximo device setup",
+        };
+    }
+    const binary = getEmbeddedPythonBinary();
+    if (!existsSync(binary)) {
+        return {
+            name: "embedded Python",
+            status: "fail",
+            message: `binary missing at ${binary}`,
+            hint: "Run: aximo device reset --python && aximo device setup",
+        };
+    }
+    const markerPath = getPythonMarkerPath();
+    const installed = existsSync(markerPath) ? readFileSync(markerPath, "utf-8").trim() : "";
+    const expected = installedPythonTag();
+    if (installed !== expected) {
+        return {
+            name: "embedded Python",
+            status: "warn",
+            message: `installed ${installed || "unknown"}, expected ${expected}`,
+            hint: "Run: aximo device setup (to upgrade)",
+        };
+    }
+    const result = spawnSync(binary, ["--version"], { encoding: "utf-8" });
+    if (result.status !== 0) {
+        return {
+            name: "embedded Python",
+            status: "fail",
+            message: `binary does not run: ${(result.stderr || result.stdout || "").trim()}`,
+            hint: "Run: aximo device reset --python && aximo device setup",
+        };
+    }
+    return {
+        name: "embedded Python",
+        status: "pass",
+        message: `${(result.stdout || result.stderr).trim()} (${PYTHON_VERSION}+${PYTHON_RELEASE})`,
+    };
+}
+function checkPythonDeps() {
+    if (!existsSync(getDepsMarkerPath())) {
+        return {
+            name: "python dependencies",
+            status: "warn",
+            message: "not yet installed",
+            hint: "Run: aximo device setup",
+        };
+    }
+    const binary = getEmbeddedPythonBinary();
+    if (!existsSync(binary)) {
+        return { name: "python dependencies", status: "fail", message: "python binary missing" };
+    }
+    const result = spawnSync(binary, ["-c", "import pyautogui, pyperclip, websockets, PIL"], {
+        encoding: "utf-8",
+    });
+    if (result.status !== 0) {
+        return {
+            name: "python dependencies",
+            status: "fail",
+            message: (result.stderr || result.stdout || "").trim() || "import failed",
+            hint: "Run: aximo device reset --deps && aximo device setup",
+        };
+    }
+    return {
+        name: "python dependencies",
+        status: "pass",
+        message: "pyautogui, pyperclip, websockets, PIL importable",
+    };
+}
+function checkAgentFiles() {
+    const scriptPath = getAgentScriptPath();
+    const requirementsPath = getAgentRequirementsPath();
+    if (!existsSync(scriptPath) || !existsSync(requirementsPath)) {
+        return {
+            name: "agent files",
+            status: "warn",
+            message: "agent script not yet synced",
+            hint: "Run: aximo device setup",
+        };
+    }
+    const local = readCachedManifest();
+    if (!local) {
+        return {
+            name: "agent files",
+            status: "warn",
+            message: "agent manifest missing or invalid",
+            hint: "Run: aximo device setup",
+        };
+    }
+    return {
+        name: "agent files",
+        status: "pass",
+        message: `version ${local.version}`,
+    };
+}
+async function checkAgentUpToDate(deps) {
+    const local = readCachedManifest();
+    try {
+        const server = await request("/api/devices/agent/manifest", {}, deps ?? {});
+        if (!local) {
+            return {
+                name: "agent up to date",
+                status: "warn",
+                message: `local cache missing; server has version ${server.version}`,
+                hint: "Run: aximo device setup",
+            };
+        }
+        if (local.version === server.version) {
+            return {
+                name: "agent up to date",
+                status: "pass",
+                message: `version ${server.version}`,
+            };
+        }
+        return {
+            name: "agent up to date",
+            status: "warn",
+            message: `local ${local.version}, server ${server.version}`,
+            hint: "Run: aximo device setup (to fetch latest)",
+        };
+    }
+    catch (err) {
+        return {
+            name: "agent up to date",
+            status: "fail",
+            message: err instanceof Error ? err.message : String(err),
+            hint: "Check AXIMO_BASE_URL and AXIMO_API_KEY",
+        };
+    }
+}
+function relayUrlFromBase() {
+    return `${getBaseUrl().replace(/^http/, "ws")}/devices/tunnel`;
+}
+const RELAY_CHECK_NAME = "relay handshake";
+function checkRelayReachable() {
+    return new Promise((resolve) => {
+        const url = relayUrlFromBase();
+        let settled = false;
+        const ws = new WebSocket(url, { handshakeTimeout: 5_000 });
+        const done = (check) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            resolve(check);
+        };
+        const timer = setTimeout(() => {
+            done({
+                name: RELAY_CHECK_NAME,
+                status: "fail",
+                message: `timed out connecting to ${url}`,
+                hint: "Check firewall / proxy for outbound wss:// on 443",
+            });
+        }, 5_000);
+        ws.on("open", () => {
+            clearTimeout(timer);
+            done({
+                name: RELAY_CHECK_NAME,
+                status: "pass",
+                message: `WebSocket handshake to ${url} succeeded (device auth not verified)`,
+            });
+        });
+        ws.on("error", (err) => {
+            clearTimeout(timer);
+            done({
+                name: RELAY_CHECK_NAME,
+                status: "fail",
+                message: `${url}: ${err instanceof Error ? err.message : String(err)}`,
+                hint: "Check AXIMO_BASE_URL and firewall rules for outbound wss://",
+            });
+        });
+    });
+}
+async function checkCurrentStatus(deviceId, deps) {
+    const name = "device status";
+    try {
+        const res = await request("/api/devices/user", {}, deps ?? {});
+        const device = res.devices?.find((d) => d.id === deviceId);
+        if (!device) {
+            return {
+                name,
+                status: "warn",
+                message: "device not listed for current API key",
+                hint: "Token may be from another account; re-register",
+            };
+        }
+        if (device.status === "online") {
+            return { name, status: "pass", message: `online · last seen ${device.lastSeenAt ?? "now"}` };
+        }
+        return {
+            name,
+            status: "warn",
+            message: `status: ${device.status}`,
+            hint: "Run: aximo device connect",
+        };
+    }
+    catch (err) {
+        return {
+            name,
+            status: "fail",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function checkPlatformExtras() {
+    const p = platform();
+    if (p === "linux") {
+        const needs = ["scrot", "xclip"];
+        const found = needs.filter((cmd) => spawnSync("which", [cmd]).status === 0);
+        if (found.length === needs.length) {
+            return [{ name: "linux tools", status: "pass", message: `${needs.join(", ")} installed` }];
+        }
+        const missing = needs.filter((c) => !found.includes(c));
+        return [
+            {
+                name: "linux tools",
+                status: "warn",
+                message: `missing: ${missing.join(", ")}`,
+                hint: "Install via your package manager (e.g. apt install scrot xclip)",
+            },
+        ];
+    }
+    if (p === "darwin") {
+        return [
+            {
+                name: "macos permissions",
+                status: "info",
+                message: "Accessibility + Screen Recording must be granted manually",
+                hint: "System Settings → Privacy & Security → Accessibility / Screen Recording",
+            },
+        ];
+    }
+    return [];
+}
+function logDirUsage() {
+    const pythonDir = getPythonDir();
+    try {
+        if (existsSync(pythonDir)) {
+            const stat = statSync(pythonDir);
+            if (stat.isDirectory()) {
+                return { name: "install dir", status: "info", message: pythonDir };
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return { name: "install dir", status: "info", message: pythonDir };
+}
+export async function runDeviceDoctor(options = {}, deps) {
+    const checks = [];
+    checks.push(checkApiKey());
+    checks.push(checkBaseUrl());
+    checks.push(checkProxyEnv());
+    if (!options.skipApi && checks[0]?.status !== "fail") {
+        checks.push(await checkApiHealth(deps));
+    }
+    const { check: configCheck, config } = checkDeviceConfig();
+    checks.push(configCheck);
+    checks.push(checkEmbeddedPython());
+    checks.push(checkPythonDeps());
+    checks.push(checkAgentFiles());
+    checks.push(...checkPlatformExtras());
+    checks.push(logDirUsage());
+    if (!options.skipApi && checks[0]?.status !== "fail") {
+        checks.push(await checkAgentUpToDate(deps));
+    }
+    if (!options.skipRelay) {
+        checks.push(await checkRelayReachable());
+    }
+    if (config?.deviceId && !options.skipApi && checks[0]?.status !== "fail") {
+        checks.push(await checkCurrentStatus(config.deviceId, deps));
+    }
+    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 your BYOD setup (env, Python, relay, device status)",
+    },
+    args: {
+        "skip-relay": { type: "boolean", description: "Skip WebSocket reachability check" },
+        "skip-api": { type: "boolean", description: "Skip Aximo API calls (offline check only)" },
+    },
+    async run({ args }) {
+        const result = await runDeviceDoctor({
+            skipRelay: Boolean(args["skip-relay"]),
+            skipApi: Boolean(args["skip-api"]),
+        });
+        printResult(result);
+        if (result.ok && result.data.summary.fail > 0) {
+            process.exitCode = 1;
+        }
+    },
+});

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

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

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

@@ -0,0 +1,89 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } 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 { runDeviceDoctor } from "./doctor.js";
+let tempHome;
+beforeAll(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-doctor-"));
+    process.env["AXIMO_HOME"] = tempHome;
+    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());
+function findCheck(checks, name) {
+    return checks.find((c) => c.name === name);
+}
+describe("runDeviceDoctor", () => {
+    it("fails the API key check when AXIMO_API_KEY is unset", async () => {
+        delete process.env["AXIMO_API_KEY"];
+        const result = await runDeviceDoctor({ skipRelay: true, skipApi: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const apiKey = findCheck(result.data.checks, "API key");
+        expect(apiKey?.status).toBe("fail");
+        expect(result.data.summary.fail).toBeGreaterThanOrEqual(1);
+    });
+    it("passes the API key check when the env is set and warns on missing local device config", async () => {
+        process.env["AXIMO_API_KEY"] = "test-key";
+        const result = await runDeviceDoctor({ skipRelay: true, skipApi: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(findCheck(result.data.checks, "API key")?.status).toBe("pass");
+        expect(findCheck(result.data.checks, "device registered")?.status).toBe("warn");
+    });
+    it("passes the API health check when /api/health responds", async () => {
+        process.env["AXIMO_API_KEY"] = "test-key";
+        server.use(http.get(`${TEST_BASE_URL}/api/health`, () => HttpResponse.json({ status: "ok" })), http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ devices: [] })), http.get(`${TEST_BASE_URL}/api/devices/agent/manifest`, () => HttpResponse.json({
+            manifestVersion: 2,
+            version: "v1",
+            script: { sha256: "s", size: 0 },
+            requirements: { sha256: "r", size: 0 },
+        })));
+        const result = await runDeviceDoctor({ skipRelay: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(findCheck(result.data.checks, "aximo API health")?.status).toBe("pass");
+    });
+    it("reports device status when a local config matches a listed device", async () => {
+        process.env["AXIMO_API_KEY"] = "test-key";
+        const deviceId = "dev-1";
+        writeFileSync(join(tempHome, "device.json"), JSON.stringify({ deviceId, deviceToken: "t", name: "Test PC" }));
+        server.use(http.get(`${TEST_BASE_URL}/api/health`, () => HttpResponse.json({ status: "ok" })), http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({
+            devices: [{ id: deviceId, name: "Test PC", status: "online", lastSeenAt: "now" }],
+        })), http.get(`${TEST_BASE_URL}/api/devices/agent/manifest`, () => HttpResponse.json({
+            manifestVersion: 2,
+            version: "v1",
+            script: { sha256: "s", size: 0 },
+            requirements: { sha256: "r", size: 0 },
+        })));
+        const result = await runDeviceDoctor({ skipRelay: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        const status = findCheck(result.data.checks, "device status");
+        expect(status?.status).toBe("pass");
+        expect(status?.message).toContain("online");
+    });
+    it("flags agent-files as warn when no local cache exists", async () => {
+        process.env["AXIMO_API_KEY"] = "test-key";
+        const result = await runDeviceDoctor({ skipRelay: true, skipApi: true });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            return;
+        expect(findCheck(result.data.checks, "agent files")?.status).toBe("warn");
+    });
+});

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

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

package/dist/commands/device/index.js

@@ -0,0 +1,16 @@
+import { defineCommand } from "citty";
+export default defineCommand({
+    meta: { name: "device", description: "Device commands" },
+    subCommands: {
+        list: () => import("./list.js").then((m) => m.default),
+        register: () => import("./register.js").then((m) => m.default),
+        connect: () => import("./connect.js").then((m) => m.default),
+        status: () => import("./status.js").then((m) => m.default),
+        unregister: () => import("./unregister.js").then((m) => m.default),
+        setup: () => import("./setup.js").then((m) => m.default),
+        doctor: () => import("./doctor.js").then((m) => m.default),
+        logs: () => import("./logs.js").then((m) => m.default),
+        reset: () => import("./reset.js").then((m) => m.default),
+        ping: () => import("./ping.js").then((m) => m.default),
+    },
+});

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

@@ -0,0 +1,20 @@
+import type { Envelope, Device } from "../../types.js";
+import { type ClientDeps } from "../../client.js";
+export interface DeviceListOptions {
+    platform?: string | undefined;
+    availableOnly?: boolean | undefined;
+}
+export declare function runDeviceList(options?: DeviceListOptions, deps?: ClientDeps): Promise<Envelope<{
+    devices: Device[];
+}>>;
+declare const _default: import("citty").CommandDef<{
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "ANDROID | IOS";
+    };
+    readonly "available-only": {
+        readonly type: "boolean";
+        readonly description: "Only available devices";
+    };
+}>;
+export default _default;

package/dist/commands/device/list.js

@@ -0,0 +1,40 @@
+import { defineCommand } from "citty";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { handleApiError } from "../../errors.js";
+import { request } from "../../client.js";
+import { parsePlatform } from "../../validate.js";
+export async function runDeviceList(options = {}, deps) {
+    let platform;
+    try {
+        platform = parsePlatform(options.platform);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    try {
+        const res = await request("/api/devices", {
+            query: {
+                platform,
+                availableOnly: options.availableOnly,
+            },
+        }, deps ?? {});
+        const devices = res.devices ?? [];
+        return formatSuccess({ devices }, { total: devices.length });
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: { name: "list", description: "List Aximo devices" },
+    args: {
+        platform: { type: "string", description: "ANDROID | IOS" },
+        "available-only": { type: "boolean", description: "Only available devices" },
+    },
+    async run({ args }) {
+        printResult(await runDeviceList({
+            platform: args.platform,
+            availableOnly: args["available-only"],
+        }));
+    },
+});

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

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

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

@@ -0,0 +1,38 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
+import { runDeviceList } from "./list.js";
+beforeAll(() => {
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+describe("runDeviceList", () => {
+    it("forwards platform + availableOnly as query", async () => {
+        let seenUrl = "";
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, ({ request: req }) => {
+            seenUrl = req.url;
+            return HttpResponse.json({ devices: [{ name: "d1" }] });
+        }));
+        const result = await runDeviceList({ platform: "IOS", availableOnly: true });
+        expect(result.ok).toBe(true);
+        expect(seenUrl).toContain("platform=IOS");
+        expect(seenUrl).toContain("availableOnly=true");
+    });
+    it("rejects invalid platform with validation_error", async () => {
+        const result = await runDeviceList({ platform: "WINDOWS" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("maps 429 to rate_limited", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, () => HttpResponse.json({ error: "Rate limit exceeded" }, { status: 429 })));
+        const result = await runDeviceList();
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("rate_limited");
+            expect(result.error.retryable).toBe(true);
+        }
+    });
+});

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

@@ -0,0 +1,34 @@
+import type { Envelope } from "../../types.js";
+export interface LogsResult {
+    path: string;
+    lines?: string[];
+    truncated?: boolean;
+    cleared?: boolean;
+}
+export interface RunDeviceLogsOptions {
+    lines?: number;
+    path?: boolean;
+    clear?: boolean;
+}
+export declare function runDeviceLogs(options?: RunDeviceLogsOptions): Envelope<LogsResult>;
+declare const _default: import("citty").CommandDef<{
+    readonly follow: {
+        readonly type: "boolean";
+        readonly alias: "f";
+        readonly description: "Stream new log lines as they are written";
+    };
+    readonly lines: {
+        readonly type: "string";
+        readonly alias: "n";
+        readonly description: "Number of lines to show (default 50)";
+    };
+    readonly path: {
+        readonly type: "boolean";
+        readonly description: "Print log file path and exit";
+    };
+    readonly clear: {
+        readonly type: "boolean";
+        readonly description: "Truncate the log file";
+    };
+}>;
+export default _default;