@autifyhq/aximo-cli 0.15.0 → 0.16.0

package/README.md

@@ -73,6 +73,7 @@ Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` r
 | `aximo project list`         | List organization projects                                     |
 | `aximo session create`       | Create and queue a test session                                |
 | `aximo session get`          | Get session status                                             |
+| `aximo session cancel`       | Cancel a queued or running session                             |
 | `aximo session export`       | Download a session result as a PDF or a screenshot ZIP         |
 | `aximo session save-as-case` | Save a finished session as a reusable test case                |
 | `aximo case create`          | Create a test case                                             |
@@ -106,6 +107,7 @@ Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` r
 | `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 device testbox`       | Sandboxed Chromium in Docker as a local device (up/down/...)   |
 | `aximo mobile list`          | List physically-connected phones (Android adb, iOS devicectl)  |
 | `aximo mobile setup`         | Install the Appium drivers used to drive phones                |
 | `aximo mobile doctor`        | Diagnose prerequisites (adb/Xcode/devicectl, signing, driver)  |
@@ -147,6 +149,8 @@ aximo session create --title <t> --prompt <p> --project-id <id> \
 
 aximo session get <sessionId>
 
+aximo session cancel <sessionId> [--dry-run]
+
 aximo session export <sessionId> [--format pdf|screenshots] [--output <path>] [--locale en|ja|ko]
 ```
 
@@ -360,6 +364,20 @@ aximo device unregister --device-id DEVICE_ID  # unregister an orphaned device (
 
 `device ping` returns what the server knows, including `lastSeenAgoSeconds` and the HTTP round-trip `latencyMs`. It does **not** round-trip through the relay, so a passing ping tells you "the server thinks this device is online," not "the local agent is responding right now."
 
+### The testbox: a local device that is not your screen
+
+Registering your laptop hands Aximo your mouse and keyboard for the whole run. The testbox is the alternative for apps on `localhost`: one Chromium on a virtual display inside a Docker container, registered as its own local device, with a live view you can watch (and type a password into) from a browser tab. Requires Docker; macOS and Linux (Windows untested).
+
+```bash
+aximo device testbox up --ports 3000            # pull once, register, start, connect; prints the live-view link
+aximo device testbox status                     # container, agent, device online?, which ports answer
+aximo device testbox url                        # the live-view link again (password included)
+aximo device testbox down                       # stop; keeps the browser profile and the registration
+aximo device testbox prune                      # remove everything, including the device on the server
+```
+
+Use the printed `userDeviceId` as the local device for `session create`, cases and plans, and put the `http://localhost:<port>` URL in the prompt. `--block-hosts prod.example.com` makes the browser refuse production; it is a browser rule matched by name, not a network boundary, and the box can reach whatever your machine can. `--name qa` runs a second box as a second device. The API key never enters the container: the host CLI registers the box and injects only the device token over stdin. MCP agents drive the same box through `aximo_start_testbox` / `aximo_get_testbox` / `aximo_stop_testbox`.
+
 ### Re-registering
 
 `aximo device register` refuses to overwrite an existing local registration. To move a registration to a different device name:
@@ -675,7 +693,7 @@ claude mcp add aximo -- aximo mcp
 
 VS Code (Copilot agent mode) uses the same entry under a `servers` key in `.vscode/mcp.json`.
 
-The server exposes 34 tools: 17 read-only ones for inspecting sessions, cases, plans, plan runs, devices, and uploads (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_list_plans` and `aximo_get_plan` cover plan discovery; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling; `aximo_list_devices`, `aximo_list_user_devices`, and `aximo_list_uploads` supply the device and upload tokens that case configs and run overrides take), 2 that export a session result to a local file (`aximo_export_session_pdf` for the test result report, `aximo_export_session_screenshots` for a ZIP of the step screenshots), 13 that author content (create, update, archive, restore, and delete cases — including a case's per-target device configuration — create, update, archive, restore, and delete plans, add or remove a plan's cases, save a session as a case), and 2 that trigger runs (`aximo_run_case` starts a case run and returns the `sessionId`; `aximo_run_plan` starts a plan run and returns the `planRunId` — both spend organization credits and require the case or plan to be `apiEnabled`). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
+The server exposes 40 tools: 18 read-only ones for inspecting sessions, cases, plans, plan runs, devices, and uploads (`aximo_get_session_timeline` is the load-bearing one for Playwright export; `aximo_wait_for_session` polls a run; `aximo_list_plans` and `aximo_get_plan` cover plan discovery; `aximo_list_plan_runs` and `aximo_get_plan_run` cover run-status polling; `aximo_list_devices`, `aximo_list_user_devices`, and `aximo_list_uploads` supply the device and upload tokens that case configs and run overrides take), 2 that export a session result to a local file (`aximo_export_session_pdf` for the test result report, `aximo_export_session_screenshots` for a ZIP of the step screenshots), 13 that author content (create, update, archive, restore, and delete cases — including a case's per-target device configuration — create, update, archive, restore, and delete plans, add or remove a plan's cases, save a session as a case), 3 that start runs (`aximo_run_case` starts a case run and returns the `sessionId`; `aximo_create_session` starts a session from a prompt with no saved case; `aximo_run_plan` starts a plan run and returns the `planRunId` — all spend organization credits, and the case and plan runs require `apiEnabled`), 1 that stops one (`aximo_cancel_session` cancels a queued or running session), and 3 that manage the local testbox (`aximo_start_testbox`, `aximo_get_testbox`, `aximo_stop_testbox`: a sandboxed Chromium in Docker, registered as a local device, so an agent can test an app on localhost without taking over your screen; see `aximo device testbox`). See the [MCP reference](./skills/aximo-cli/references/mcp.md) for per-client config paths, the full tool table, the Playwright export prompt, and a no-client smoke test.
 
 ## Agent Skills
 

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

@@ -9,6 +9,6 @@ export interface DeviceConfig {
  * 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;
+export declare function readDeviceConfig(path?: string): DeviceConfig | null;
 /** Persist the local device registration with owner-only permissions. */
-export declare function writeDeviceConfig(config: DeviceConfig): void;
+export declare function writeDeviceConfig(config: DeviceConfig, path?: string): void;

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

@@ -1,11 +1,11 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { getAximoDir, getDeviceConfigPath } from "./paths.js";
+import { dirname } from "node:path";
+import { 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();
+export function readDeviceConfig(path = getDeviceConfigPath()) {
     if (!existsSync(path))
         return null;
     try {
@@ -31,11 +31,8 @@ export function readDeviceConfig() {
     }
 }
 /** 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();
+export function writeDeviceConfig(config, path = getDeviceConfigPath()) {
+    mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, JSON.stringify(config, null, 2), { mode: 0o600 });
     try {
         chmodSync(path, 0o600);

package/dist/commands/device/index.js

@@ -2,7 +2,7 @@ import { defineCommand } from "citty";
 export default defineCommand({
     meta: {
         name: "device",
-        description: "BYOD device commands (register/connect/status/...); 'device list' lists Device Farm mobile devices",
+        description: "BYOD device commands (register/connect/status/...); 'device testbox' runs a sandboxed browser in Docker; 'device list' lists Device Farm mobile devices",
     },
     subCommands: {
         list: () => import("./list.js").then((m) => m.default),
@@ -15,5 +15,6 @@ export default defineCommand({
         logs: () => import("./logs.js").then((m) => m.default),
         reset: () => import("./reset.js").then((m) => m.default),
         ping: () => import("./ping.js").then((m) => m.default),
+        testbox: () => import("./testbox/index.js").then((m) => m.default),
     },
 });

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

@@ -10,4 +10,8 @@ export declare function getAgentDir(): string;
 export declare function getAgentScriptPath(): string;
 export declare function getAgentRequirementsPath(): string;
 export declare function getAgentManifestPath(): string;
+export declare function getTestboxDir(): string;
+export declare function getTestboxConfigPath(name: string): string;
+export declare function getTestboxStatePath(name: string): string;
+export declare function getTestboxLogPath(name: string): string;
 export declare function getEmbeddedPythonBinary(): string;

package/dist/commands/device/paths.js

@@ -36,6 +36,18 @@ export function getAgentRequirementsPath() {
 export function getAgentManifestPath() {
     return join(getAgentDir(), "manifest.json");
 }
+export function getTestboxDir() {
+    return join(getAximoDir(), "testbox");
+}
+export function getTestboxConfigPath(name) {
+    return join(getTestboxDir(), `${name}.json`);
+}
+export function getTestboxStatePath(name) {
+    return join(getTestboxDir(), `${name}.state.json`);
+}
+export function getTestboxLogPath(name) {
+    return join(getTestboxDir(), `${name}.log`);
+}
 export function getEmbeddedPythonBinary() {
     return platform() === "win32"
         ? join(getPythonDir(), "python.exe")

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

@@ -1,6 +1,7 @@
 import type { Envelope } from "../../types.js";
 export interface ResetResult {
     removed: string[];
+    orphanedTestboxes?: string[];
 }
 export interface RunDeviceResetOptions {
     python?: boolean;

package/dist/commands/device/reset.js

@@ -1,13 +1,21 @@
 import { defineCommand } from "citty";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, rmSync } from "node:fs";
 import { formatError, formatSuccess, printResult } from "../../output.js";
-import { getAximoDir, getCacheDir, getDepsMarkerPath, getDeviceConfigPath, getPythonDir, getPythonMarkerPath, getRemoteLogPath, } from "./paths.js";
+import { getAximoDir, getCacheDir, getDepsMarkerPath, getDeviceConfigPath, getPythonDir, getPythonMarkerPath, getRemoteLogPath, getTestboxDir, } from "./paths.js";
 function removeIfExists(path, removed, opts = {}) {
     if (!existsSync(path))
         return;
     rmSync(path, { recursive: opts.recursive ?? false, force: true });
     removed.push(path);
 }
+function listTestboxes() {
+    const dir = getTestboxDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".json") && !f.endsWith(".state.json"))
+        .map((f) => f.slice(0, -".json".length));
+}
 export function runDeviceReset(options = {}) {
     const { python, deps, device, all } = options;
     if (!python && !deps && !device && !all) {
@@ -16,8 +24,12 @@ export function runDeviceReset(options = {}) {
     const removed = [];
     try {
         if (all) {
+            const orphanedTestboxes = listTestboxes();
             removeIfExists(getAximoDir(), removed, { recursive: true });
-            return formatSuccess({ removed });
+            return formatSuccess({
+                removed,
+                ...(orphanedTestboxes.length > 0 ? { orphanedTestboxes } : {}),
+            });
         }
         if (python) {
             removeIfExists(getPythonDir(), removed, { recursive: true });
@@ -60,6 +72,9 @@ export default defineCommand({
             all: Boolean(args.all),
         });
         printResult(result);
+        if (result.ok && result.data.orphanedTestboxes) {
+            console.error(`\nNote: testbox registrations for ${result.data.orphanedTestboxes.join(", ")} were removed locally only; their device rows remain on the server. Delete them in Settings > Devices, or run \`aximo device testbox prune\` before \`reset --all\` next time.`);
+        }
         if (result.ok && args.device) {
             console.error("\nNote: this only removed local credentials. The device row on the Aximo server still exists —\nrun `aximo device unregister` first if you want to delete it server-side.");
         }

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

@@ -65,5 +65,18 @@ describe("runDeviceReset", () => {
         const result = runDeviceReset({ all: true });
         expect(result.ok).toBe(true);
         expect(existsSync(tempHome)).toBe(false);
+        if (result.ok)
+            expect(result.data.orphanedTestboxes).toBeUndefined();
+    });
+    it("--all names the testbox registrations it leaves orphaned on the server", () => {
+        seedAll();
+        mkdirSync(join(tempHome, "testbox"), { recursive: true });
+        writeFileSync(join(tempHome, "testbox", "default.json"), "{}");
+        writeFileSync(join(tempHome, "testbox", "qa.json"), "{}");
+        writeFileSync(join(tempHome, "testbox", "qa.state.json"), "{}");
+        const result = runDeviceReset({ all: true });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.orphanedTestboxes).toEqual(["default", "qa"]);
     });
 });

package/dist/commands/device/testbox/box.d.ts

@@ -0,0 +1,90 @@
+import { type ClientDeps } from "../../../client.js";
+import { type WaitClock } from "../../mcp/wait.js";
+import { type TestboxConfig } from "./container.js";
+import { type DockerRunner } from "./docker.js";
+export interface TestboxDeps extends ClientDeps {
+    docker?: DockerRunner;
+    clock?: WaitClock;
+    fetchAgent?: (deps: ClientDeps) => Promise<{
+        scriptPath: string;
+        requirementsPath: string;
+    }>;
+    hostName?: () => string;
+}
+export interface UpOptions {
+    name?: string;
+    ports?: string;
+    blockHosts?: string[];
+    startUrl?: string;
+    novncPort?: number;
+    screen?: string;
+    image?: string;
+    wait?: boolean;
+}
+export type TestboxState = "down" | "pulling" | "starting" | "connecting" | "online" | "error";
+export interface TestboxStatus {
+    name: string;
+    state: TestboxState;
+    container: "running" | "stopped" | "absent";
+    config?: TestboxConfig;
+    device?: {
+        userDeviceId: string;
+        name: string;
+        status: string;
+    };
+    agent?: "running" | "stopped";
+    agentStatus?: string;
+    ports?: {
+        port: number;
+        reachable: boolean;
+    }[];
+    liveViewUrl?: string;
+    lastError?: string;
+}
+interface StateFile {
+    phase: "pulling" | "starting" | "connecting" | "error";
+    startedAt: string;
+    pid: number;
+    lastError?: string;
+}
+export declare function readState(name: string): StateFile | null;
+export declare function clearState(name: string): void;
+/** The detached `up` still working on this box, if any. */
+export declare function pendingUp(name: string, clock?: WaitClock): StateFile | null;
+export interface UpResult {
+    name: string;
+    container: string;
+    userDeviceId: string;
+    deviceName: string;
+    state: TestboxState;
+    config: TestboxConfig;
+    liveViewUrl?: string;
+    notes: string[];
+}
+export declare function upTestbox(options: UpOptions, deps?: TestboxDeps): Promise<UpResult>;
+export declare function statusTestbox(nameInput: string | undefined, deps?: TestboxDeps): Promise<TestboxStatus>;
+/** Status now, or once the box is online or has stopped trying, whichever comes first. */
+export declare function waitForTestbox(name: string | undefined, timeoutSeconds: number, deps?: TestboxDeps): Promise<TestboxStatus>;
+export declare function downTestbox(nameInput: string | undefined, deps?: TestboxDeps): Promise<{
+    name: string;
+    removed: boolean;
+}>;
+export declare function resetTestbox(nameInput: string | undefined, deps?: TestboxDeps): Promise<{
+    profileDropped: boolean;
+    name: string;
+    removed: boolean;
+}>;
+export declare function pruneTestbox(nameInput: string | undefined, options?: {
+    keepImage?: boolean;
+}, deps?: TestboxDeps): Promise<{
+    name: string;
+    removed: boolean;
+    deviceId: string | undefined;
+    serverDeleted: boolean;
+}>;
+export declare function agentLog(nameInput: string | undefined, lines: number, deps?: TestboxDeps): Promise<{
+    name: string;
+    lines: string[];
+}>;
+export declare function agentLogFollowArgs(name: string | undefined, lines: number): string[];
+export {};