@autifyhq/aximo-cli 0.4.0 → 0.6.0

package/README.md

@@ -64,40 +64,47 @@ Credentials and device registrations are **per-environment** — to switch betwe
 
 Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` returns machine-readable argument introspection (e.g. `aximo schema session.create`).
 
-| Command                      | Description                                          |
-| ---------------------------- | ---------------------------------------------------- |
-| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`        |
-| `aximo health check`         | Check API reachability                               |
-| `aximo project list`         | List organization projects                           |
-| `aximo session create`       | Create and queue a test session                      |
-| `aximo session get`          | Get session status                                   |
-| `aximo session save-as-case` | Save a finished session as a reusable test case      |
-| `aximo case create`          | Create a test case                                   |
-| `aximo case delete`          | Delete a test case                                   |
-| `aximo plan create`          | Create a test plan                                   |
-| `aximo plan add-case`        | Add a case to a plan                                 |
-| `aximo plan remove-case`     | Remove a case from a plan                            |
-| `aximo trigger case run`     | Trigger a dashboard-created test case                |
-| `aximo trigger case get`     | Get triggered case status                            |
-| `aximo trigger plan run`     | Trigger a test plan                                  |
-| `aximo trigger plan get`     | Get plan run status                                  |
-| `aximo upload create`        | Create an upload slot for an APK/IPA                 |
-| `aximo upload list`          | List previously uploaded apps                        |
-| `aximo upload get`           | Poll upload processing status                        |
-| `aximo upload put`           | Upload binary file to the slot                       |
-| `aximo upload submit`        | Finalize upload and trigger processing               |
-| `aximo device list`          | List mobile devices from Device Farm                 |
-| `aximo device setup`         | First-time BYOD onboarding (API + Python + register) |
-| `aximo device register`      | Register this machine as a BYOD device               |
-| `aximo device connect`       | Start the BYOD agent and connect to the relay        |
-| `aximo device status`        | List your organization's BYOD devices                |
-| `aximo device ping`          | Check your BYOD device's server-side status          |
-| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)     |
-| `aximo device logs`          | Show the BYOD agent log                              |
-| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds |
-| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)  |
-| `aximo schema`               | Show CLI surface as JSON                             |
-| `aximo mcp`                  | Run a stdio MCP server for agents (see below)        |
+| Command                      | Description                                             |
+| ---------------------------- | ------------------------------------------------------- |
+| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`           |
+| `aximo health check`         | Check API reachability                                  |
+| `aximo project list`         | List organization projects                              |
+| `aximo session create`       | Create and queue a test session                         |
+| `aximo session get`          | Get session status                                      |
+| `aximo session save-as-case` | Save a finished session as a reusable test case         |
+| `aximo case create`          | Create a test case                                      |
+| `aximo case delete`          | Delete a test case                                      |
+| `aximo plan create`          | Create a test plan                                      |
+| `aximo plan add-case`        | Add a case to a plan                                    |
+| `aximo plan remove-case`     | Remove a case from a plan                               |
+| `aximo trigger case run`     | Trigger a dashboard-created test case                   |
+| `aximo trigger case get`     | Get triggered case status                               |
+| `aximo trigger plan run`     | Trigger a test plan                                     |
+| `aximo trigger plan get`     | Get plan run status                                     |
+| `aximo upload create`        | Create an upload slot for an APK/IPA                    |
+| `aximo upload list`          | List previously uploaded apps                           |
+| `aximo upload get`           | Poll upload processing status                           |
+| `aximo upload put`           | Upload binary file to the slot                          |
+| `aximo upload submit`        | Finalize upload and trigger processing                  |
+| `aximo device list`          | List mobile devices from Device Farm                    |
+| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)    |
+| `aximo device register`      | Register this machine as a BYOD device                  |
+| `aximo device connect`       | Start the BYOD agent and connect to the relay           |
+| `aximo device status`        | List your organization's BYOD devices                   |
+| `aximo device ping`          | Check your BYOD device's server-side status             |
+| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)        |
+| `aximo device logs`          | Show the BYOD agent log                                 |
+| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds    |
+| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)     |
+| `aximo mobile list`          | List physically-connected phones (Android adb, iOS idb) |
+| `aximo mobile setup`         | Install the Appium drivers used to drive phones         |
+| `aximo mobile doctor`        | Diagnose prerequisites (adb/idb, SDK/Xcode, driver)     |
+| `aximo mobile register`      | Register a connected Android phone or iPhone            |
+| `aximo mobile install`       | Install an app (.apk via adb, .ipa via idb)             |
+| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone    |
+| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds  |
+| `aximo schema`               | Show CLI surface as JSON                                |
+| `aximo mcp`                  | Run a stdio MCP server for agents (see below)           |
 
 Mutating commands support `--json '<raw body>'` for direct OpenAPI payloads and `--dry-run` to preview requests without executing.
 
@@ -349,16 +356,22 @@ Normal for brief network blips — the agent retries with exponential backoff (1
 - Confirm outbound WebSocket on 443 isn't blocked: `aximo device doctor` runs a handshake probe.
 
 **Python download or pip install fails (corporate proxy).**
-The embedded Python is fetched from `github.com/astral-sh/python-build-standalone/releases`; packages come from PyPI. Behind a proxy:
+The embedded Python is fetched from `github.com/astral-sh/python-build-standalone/releases` and packages come from PyPI, so `aximo device setup` needs outbound access to both. On a network that only reaches the internet through a proxy, set the standard proxy variables — the CLI, pip, and the desktop agent all honor them:
 
 ```bash
 # macOS / Linux
-~/.aximo/python/bin/python3 -m pip config set global.proxy http://your-proxy:port
+export HTTPS_PROXY=http://your-proxy:port
+export HTTP_PROXY=http://your-proxy:port
 
-# Windows
-%USERPROFILE%\.aximo\python\python.exe -m pip config set global.proxy http://your-proxy:port
+# Windows (PowerShell)
+$env:HTTPS_PROXY = "http://your-proxy:port"
+$env:HTTP_PROXY  = "http://your-proxy:port"
 ```
 
+Loopback and a private-range `AXIMO_BASE_URL` (e.g. an on-prem `172.30.x.x` server) are always reached directly, so you don't have to list them in `NO_PROXY`. If your proxy performs TLS interception, also point `NODE_EXTRA_CA_CERTS` at the proxy's CA so the download's certificate verifies.
+
+If the proxy cannot reach GitHub at all, ask your network team to allow-list both `github.com` and its release-asset CDN `release-assets.githubusercontent.com` — the download redirects from the former to the latter, so allow-listing only `github.com` is not enough.
+
 To retry from a clean slate: `aximo device reset --python && aximo device setup`.
 
 **Device shows online, but tests fail on screenshot / click.**
@@ -388,6 +401,174 @@ Default `$AXIMO_HOME` is `~/.aximo` on macOS/Linux, `%USERPROFILE%\.aximo` on Wi
 
 > Devices are registered per-environment (see [Configuration](#configuration)) — a device registered against sandbox can't connect to production and vice versa.
 
+## Mobile (local Android phone or iPhone)
+
+The `mobile` commands let you register a **physically-connected Android phone or iPhone** as an Aximo device and drive it locally, over the same gateway tunnel as desktop BYOD. Aximo's agent controls the phone through a CLI-managed [Appium](https://appium.io) server — UiAutomator2 for Android, XCUITest for iOS — useful for running mobile tests against your own handset instead of a Device Farm device.
+
+> **iOS is macOS-only and needs Xcode + an Apple Developer account.** Driving a physical iPhone goes through Appium's XCUITest driver, which builds and code-signs a WebDriverAgent (WDA) runner onto the device. That requires macOS, Xcode, an Apple Developer **Team ID**, and a WDA bundle id backed by a valid provisioning profile — set via the `AXIMO_IOS_*` env vars below. Android has no such requirement, so iOS setup is heavier; everything after setup (`register` → `connect` → run) works the same on both platforms.
+
+Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machine; **`aximo device list`** (under [Device / BYOD](#device-byod--bring-your-own-device)) returns mobile devices from AWS Device Farm. Don't confuse the two.
+
+### Prerequisites
+
+- **Node.js 20+**, plus `aximo-cli` installed globally (see [Install](#install)).
+- **An Aximo API key**, configured via `aximo configure` or env vars.
+- **A USB-connected phone**:
+  - **Android** — **USB debugging** enabled and authorized — see [Enable USB debugging on the phone](#enable-usb-debugging-on-the-phone).
+  - **iOS** — **Developer Mode** enabled (Settings → Privacy & Security) and the computer trusted.
+- **On the machine that runs `aximo mobile connect`**:
+  - **Android** — `adb` and the Android SDK, with `ANDROID_HOME` set — see [Set up your computer (Android)](#set-up-your-computer-android).
+  - **iOS** — macOS with **Xcode** + command line tools, **`idb`**, and the `AXIMO_IOS_*` signing env vars — see [Set up your computer (iOS)](#set-up-your-computer-ios).
+
+> The Appium server is bundled with the CLI; `aximo mobile setup` installs the UiAutomator2 (Android) and/or XCUITest (iOS) driver — you don't install or manage Appium yourself.
+
+### Set up your computer (Android)
+
+You only need **`adb`** and the **Android SDK** on the machine running `aximo mobile connect`. Appium delegates to `adb`, and its UiAutomator2 driver needs the SDK (even though `adb` is already on `PATH`).
+
+**macOS**
+
+```bash
+# Option A — standalone platform-tools (just adb):
+brew install --cask android-platform-tools
+# Option B — full Android Studio (also installs the SDK):
+brew install --cask android-studio
+
+# Point ANDROID_HOME at the SDK (Android Studio's default location shown):
+echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
+echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"'  >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Linux**
+
+```bash
+# Debian/Ubuntu — adb from the distro (or download platform-tools from Google):
+sudo apt-get install -y android-tools-adb
+# Install the SDK via Android Studio or sdkmanager, then export its path:
+echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
+echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Windows**
+
+- Install **Android Studio** (bundles the SDK + platform-tools), or download the standalone **SDK Platform-Tools** zip from Google.
+- Set `ANDROID_HOME` to the SDK path (e.g. `%LOCALAPPDATA%\Android\Sdk`) and add `%ANDROID_HOME%\platform-tools` to `PATH` via _System Properties → Environment Variables_.
+
+> `aximo mobile doctor` auto-detects the SDK at the standard locations above, so `ANDROID_HOME` is optional when you use the defaults — but setting it explicitly is the most reliable. Confirm `adb` works with `adb version`.
+
+### Set up your computer (iOS)
+
+iOS local devices are **macOS-only** (Appium's XCUITest driver delegates to Xcode). You need Xcode, `idb`, and the signing env vars.
+
+```bash
+# 1. Xcode + command line tools (XCUITest builds WebDriverAgent with them):
+xcode-select --install          # or install Xcode from the App Store, then: sudo xcodebuild -license accept
+
+# 2. idb — discovers connected iPhones and installs .ipa builds:
+brew tap facebook/fb && brew install idb-companion
+pipx install fb-idb             # or: pip install fb-idb
+
+# 3. Signing config for WebDriverAgent (required for a physical iPhone):
+export AXIMO_IOS_TEAM_ID="ABCDE12345"     # your Apple Developer Team ID (developer.apple.com/account → Membership)
+# Optional overrides (sensible defaults shown):
+export AXIMO_IOS_SIGNING_ID="Apple Development"
+export AXIMO_IOS_WDA_BUNDLE_ID="com.facebook.WebDriverAgentRunner"
+# Optional: reuse a prebuilt WDA to skip per-session rebuilds:
+# export AXIMO_IOS_DERIVED_DATA_PATH="$HOME/Library/Developer/Xcode/DerivedData/WebDriverAgent-xxxx"
+```
+
+`AXIMO_IOS_TEAM_ID` is the load-bearing setting: the XCUITest driver uses it (with the signing id and WDA bundle id) to build and sign WebDriverAgent so it can run on the device. The WDA bundle id must be associated with a valid provisioning profile under that team. Run `aximo mobile doctor --platform ios` to confirm Xcode, `idb`, and the signing config are all present.
+
+> Already set up Autify's MobileLink? The CLI also reads MobileLink's names as fallbacks — `XCODE_TEAM_ID`, `XCODE_SIGN_ID`, `WDA_BUNDLE_ID` — so an existing host needs no reconfiguration. `AXIMO_IOS_*` takes precedence when both are set.
+
+> First connect to a physical iPhone is slow: Xcode builds and installs WebDriverAgent (a minute or two). If the build fails on signing, open `WebDriverAgent.xcodeproj` in Xcode once, pick your team, and let it auto-manage signing — or set `AXIMO_IOS_DERIVED_DATA_PATH` to a prebuilt WDA.
+
+### Enable USB debugging on the phone
+
+Exact labels vary by manufacturer and Android version, but the flow is:
+
+1. **Unlock Developer options** — open **Settings → About phone** and tap **Build number** seven times until you see "You are now a developer".
+2. **Turn on USB debugging** — open **Settings → System → Developer options** and enable **USB debugging**.
+3. **Connect and authorize** — plug the phone into your computer with a **data-capable** USB cable, then tap **Allow** on the "Allow USB debugging?" prompt on the phone (tick "Always allow from this computer" to skip it next time).
+4. **Verify the computer sees it**:
+   ```bash
+   adb devices        # or: aximo mobile list
+   ```
+   The phone should appear in state **`device`**. **`unauthorized`** → re-accept the prompt on the phone; **`offline`** → re-plug the cable and unlock the screen. Emulators are not supported — connect a physical phone.
+
+> Keep the phone **unlocked** the first time you run a session: the initial command installs Appium's UiAutomator2 helper and creates the automation session on the device.
+
+### First-time setup
+
+```bash
+aximo mobile setup                          # installs the Appium driver(s) for your platform(s)
+aximo mobile doctor                         # checks tooling / drivers / bundled server
+# Limit to one platform if you only test on one:
+aximo mobile setup  --platform ios          # installs only the XCUITest driver
+aximo mobile doctor --platform ios          # checks Xcode / idb / signing config
+```
+
+`setup` installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off: for Android it reports `adb` and the Android SDK; for iOS it reports `xcrun`/Xcode, `idb`, and your `AXIMO_IOS_TEAM_ID` signing config — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.
+
+### Registering and connecting
+
+```bash
+aximo mobile list                                            # see connected phones (adb serials / iOS udids)
+
+# Android:
+aximo mobile register --name "My Pixel" --platform android   # --platform defaults to android
+# iOS:
+aximo mobile register --name "My iPhone" --platform ios      # targets the single connected iPhone
+
+aximo mobile connect                                         # starts managed Appium + opens the tunnel
+# Ctrl+C to disconnect
+```
+
+`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` (Android) or `--udid` (iOS) to pick a specific one when several are attached. `connect` re-checks prerequisites, starts the managed Appium server, and opens the tunnel; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
+
+Once connected, create a **mobile session in Aximo targeting this local device** — the agent routes its actions through the tunnel to the phone over Appium.
+
+### Testing your own app
+
+Unlike Device Farm, a local phone runs the apps already installed on it. To test your own build, install it first:
+
+```bash
+aximo mobile install --app ./app-debug.apk    # Android: adb install -r
+aximo mobile install --app ./MyApp.ipa         # iOS: idb install (the .ipa must be signed for the device)
+```
+
+Then create the session with the app's bundle id / package name as `--bundle-id` — the agent launches it on startup before the test begins:
+
+```bash
+# Android:
+aximo session create --platform ANDROID --user-device-id DEVICE_ID --bundle-id com.example.app \
+  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"
+# iOS:
+aximo session create --platform IOS --user-device-id DEVICE_ID --bundle-id com.example.MyApp \
+  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"
+```
+
+### Managing devices
+
+```bash
+aximo mobile unregister                       # remove the locally registered device (server-side + local creds)
+aximo mobile unregister --device-id DEVICE_ID # target a specific device when several are registered
+```
+
+### Flags reference
+
+| Command                   | Flags                                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `aximo mobile list`       | _(none)_                                                                                             |
+| `aximo mobile setup`      | `--platform android \| ios` (optional; installs both drivers by default)                             |
+| `aximo mobile doctor`     | `--platform android \| ios` (optional; checks both by default)                                       |
+| `aximo mobile register`   | `--name <name>` (required), `--platform android \| ios` (default android), `--serial`/`--udid`       |
+| `aximo mobile install`    | `--app <path-to-.apk\|.ipa>` (required), `--platform android \| ios` (inferred), `--serial`/`--udid` |
+| `aximo mobile connect`    | `--device-id <id>` (required only if multiple devices are registered)                                |
+| `aximo mobile unregister` | `--device-id <id>` (defaults to the locally registered device)                                       |
+
 ## MCP server
 
 `aximo mcp` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing your recorded sessions, screenshots, and test cases to MCP-capable agents (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, …). The motivating use: let an agent read a finished session and generate a Playwright spec without you piping JSON between commands.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
 import pkg from "../package.json" with { type: "json" };
+import { installProxySupport } from "./proxy.js";
 // citty's --help prints to stdout; route to stderr for `mcp` since its stdout
 // is JSON-RPC.
 const args = process.argv.slice(2);
@@ -27,10 +28,14 @@ const main = defineCommand({
         plan: () => import("./commands/plan/index.js").then((m) => m.default),
         trigger: () => import("./commands/trigger/index.js").then((m) => m.default),
         device: () => import("./commands/device/index.js").then((m) => m.default),
+        mobile: () => import("./commands/mobile/index.js").then((m) => m.default),
         upload: () => import("./commands/upload/index.js").then((m) => m.default),
         project: () => import("./commands/project/index.js").then((m) => m.default),
         schema: () => import("./commands/schema.js").then((m) => m.default),
         mcp: () => import("./commands/mcp/index.js").then((m) => m.default),
     },
 });
+// Honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY for every fetch the CLI makes (the
+// embedded-Python download, API calls). No-op unless a proxy is configured.
+await installProxySupport();
 runMain(main);

package/dist/client.d.ts

@@ -16,3 +16,5 @@ export interface ClientDeps {
 }
 export declare function request<T>(path: string, options?: RequestOptions, deps?: ClientDeps): Promise<T>;
 export declare function requestBuffer(path: string, deps?: ClientDeps): Promise<Buffer>;
+/** Authenticated GET that streams the response body to a file (no full-buffering). */
+export declare function requestToFile(path: string, destPath: string, deps?: ClientDeps): Promise<void>;

package/dist/client.js

@@ -88,3 +88,21 @@ export async function requestBuffer(path, deps = {}) {
     }
     return Buffer.from(await res.arrayBuffer());
 }
+/** Authenticated GET that streams the response body to a file (no full-buffering). */
+export async function requestToFile(path, destPath, deps = {}) {
+    const apiKey = deps.apiKey ?? getApiKey();
+    const baseUrl = deps.baseUrl ?? getBaseUrl();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = buildUrl(baseUrl, path);
+    const res = await fetchImpl(url, { method: "GET", headers: { "x-api-key": apiKey } });
+    if (!res.ok) {
+        const retryAfter = res.headers.get("retry-after") ?? undefined;
+        throw httpError(res.status, await errorMessage(res), retryAfter);
+    }
+    if (!res.body)
+        throw new Error(`Empty response body from ${path}`);
+    const { Readable } = await import("node:stream");
+    const { pipeline } = await import("node:stream/promises");
+    const { createWriteStream } = await import("node:fs");
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}

package/dist/commands/device/device-config.d.ts

@@ -0,0 +1,14 @@
+export interface DeviceConfig {
+    deviceId: string;
+    deviceToken: string;
+    name: string;
+    registeredAt: string;
+    baseUrl?: string;
+}
+/**
+ * Read and validate the local device registration (~/.aximo/device.json).
+ * Returns null when the file is missing, unreadable, or malformed.
+ */
+export declare function readDeviceConfig(): DeviceConfig | null;
+/** Persist the local device registration with owner-only permissions. */
+export declare function writeDeviceConfig(config: DeviceConfig): void;

package/dist/commands/device/device-config.js

@@ -0,0 +1,46 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { getAximoDir, getDeviceConfigPath } from "./paths.js";
+/**
+ * Read and validate the local device registration (~/.aximo/device.json).
+ * Returns null when the file is missing, unreadable, or malformed.
+ */
+export function readDeviceConfig() {
+    const path = getDeviceConfigPath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const raw = parsed;
+        if (typeof raw.deviceId !== "string" ||
+            typeof raw.deviceToken !== "string" ||
+            typeof raw.name !== "string") {
+            return null;
+        }
+        return {
+            deviceId: raw.deviceId,
+            deviceToken: raw.deviceToken,
+            name: raw.name,
+            registeredAt: typeof raw.registeredAt === "string" ? raw.registeredAt : "",
+            ...(typeof raw.baseUrl === "string" ? { baseUrl: raw.baseUrl } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the local device registration with owner-only permissions. */
+export function writeDeviceConfig(config) {
+    const dir = getAximoDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = getDeviceConfigPath();
+    writeFileSync(path, JSON.stringify(config, null, 2), { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // chmod may fail on Windows; file-level ACLs apply instead.
+    }
+}

package/dist/commands/device/device-config.test.d.ts

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

package/dist/commands/device/device-config.test.js

@@ -0,0 +1,56 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readDeviceConfig, writeDeviceConfig } from "./device-config.js";
+let tempHome;
+beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "aximo-device-config-"));
+    process.env["AXIMO_HOME"] = tempHome;
+});
+afterEach(() => {
+    delete process.env["AXIMO_HOME"];
+    rmSync(tempHome, { recursive: true, force: true });
+});
+function devicePath() {
+    return join(tempHome, "device.json");
+}
+describe("device-config", () => {
+    it("returns null when the file is missing", () => {
+        expect(readDeviceConfig()).toBeNull();
+    });
+    it("round-trips a config including baseUrl", () => {
+        writeDeviceConfig({
+            deviceId: "d1",
+            deviceToken: "tok",
+            name: "mac",
+            registeredAt: "2026-06-29T00:00:00.000Z",
+            baseUrl: "https://srv:8443",
+        });
+        expect(readDeviceConfig()).toEqual({
+            deviceId: "d1",
+            deviceToken: "tok",
+            name: "mac",
+            registeredAt: "2026-06-29T00:00:00.000Z",
+            baseUrl: "https://srv:8443",
+        });
+    });
+    it("reads a pre-AT-577 file with no baseUrl (backward compatible)", () => {
+        writeFileSync(devicePath(), JSON.stringify({ deviceId: "d1", deviceToken: "tok", name: "mac", registeredAt: "t" }));
+        const cfg = readDeviceConfig();
+        expect(cfg).not.toBeNull();
+        expect(cfg?.deviceId).toBe("d1");
+        expect(cfg?.baseUrl).toBeUndefined();
+    });
+    it("returns null for malformed json or a missing deviceId", () => {
+        writeFileSync(devicePath(), "{ not json");
+        expect(readDeviceConfig()).toBeNull();
+        writeFileSync(devicePath(), JSON.stringify({ deviceToken: "tok", name: "mac" }));
+        expect(readDeviceConfig()).toBeNull();
+    });
+    it("writes the file with owner-only permissions", () => {
+        writeDeviceConfig({ deviceId: "d1", deviceToken: "tok", name: "mac", registeredAt: "t" });
+        // Sanity: file is valid JSON and readable back.
+        expect(JSON.parse(readFileSync(devicePath(), "utf-8"))).toMatchObject({ deviceId: "d1" });
+    });
+});

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

@@ -17,6 +17,19 @@ export interface DoctorReport {
     };
 }
 export declare function relayProbeUrl(): string;
+export type TlsProbeResult = {
+    ok: true;
+} | {
+    ok: false;
+    kind: "cert" | "conn";
+    reason: string;
+};
+export interface AgentTlsDeps {
+    env?: NodeJS.ProcessEnv;
+    baseUrl?: string;
+    probe?: (host: string, port: number, ca: Buffer) => Promise<TlsProbeResult>;
+}
+export declare function checkAgentTlsTrust(deps?: AgentTlsDeps): Promise<Check>;
 export interface RunDoctorOptions {
     skipRelay?: boolean;
     skipApi?: boolean;