@autifyhq/aximo-cli 0.12.0 → 0.14.0

package/dist/commands/case/update.js

@@ -3,7 +3,7 @@ import { request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
 import { dryRunEnvelope, resolveJsonOverride } from "../../mutate.js";
 import { formatSuccess, printResult, validationError } from "../../output.js";
-import { optionalString, parseCaseFormat, parseCaseType, requireId } from "../../validate.js";
+import { optionalString, parseCaseFormat, parseCaseType, parseJsonArray, parseJsonObject, requireId, } from "../../validate.js";
 export async function runCaseUpdate(options, deps) {
     let caseId;
     let body;
@@ -21,6 +21,7 @@ export async function runCaseUpdate(options, deps) {
     }
     else {
         try {
+            const desktopDevice = optionalString("desktopDevice", options.desktopDevice);
             body = {
                 title: optionalString("title", options.title),
                 description: optionalString("description", options.description),
@@ -28,6 +29,10 @@ export async function runCaseUpdate(options, deps) {
                 type: parseCaseType(options.type),
                 format: parseCaseFormat(options.format),
                 startUrl: optionalString("startUrl", options.startUrl),
+                apiMobileConfig: parseJsonObject("mobileConfig", options.mobileConfig),
+                apiDesktopConfig: desktopDevice === undefined ? undefined : { userDeviceId: desktopDevice },
+                apiMultiDeviceConfig: parseJsonArray("multiDeviceConfig", options.multiDeviceConfig),
+                apiWebConfig: parseJsonObject("webConfig", options.webConfig),
             };
         }
         catch (err) {
@@ -54,11 +59,33 @@ export default defineCommand({
     args: {
         caseId: { type: "positional", required: true },
         title: { type: "string" },
-        description: { type: "string" },
+        description: {
+            type: "string",
+            description: "Cannot clear; use --json '{\"description\": null}' for that",
+        },
         scenario: { type: "string" },
         type: { type: "string", description: "web | mobile | desktop | multi_device" },
         format: { type: "string", description: "gherkin | markdown | plain_text" },
-        "start-url": { type: "string" },
+        "start-url": {
+            type: "string",
+            description: "Cannot clear; use --json '{\"startUrl\": null}' for that",
+        },
+        "mobile-config": {
+            type: "string",
+            description: "JSON object for apiMobileConfig ({deviceArn, deviceName, platform?, uploadArn?, uploadType?, appName?, bundleId?, apps?}); replaces the whole config. Clear with --json '{\"apiMobileConfig\":null}'",
+        },
+        "desktop-device": {
+            type: "string",
+            description: "Registered BYOD desktop device id (aximo device status) for apiDesktopConfig. Clear with --json '{\"apiDesktopConfig\":null}'",
+        },
+        "multi-device-config": {
+            type: "string",
+            description: "JSON array of 2-3 device entries ({kind: web|mobile, name, ...}) for apiMultiDeviceConfig; replaces the whole config. Clear with --json '{\"apiMultiDeviceConfig\":null}'",
+        },
+        "web-config": {
+            type: "string",
+            description: "JSON object for apiWebConfig ({hostnameOverrideIds: [...]}); replaces the whole config. Clear with --json '{\"apiWebConfig\":null}'",
+        },
         json: { type: "string", description: "Raw JSON request body (replaces individual flags)" },
         "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
     },
@@ -71,6 +98,10 @@ export default defineCommand({
             type: args.type,
             format: args.format,
             startUrl: args["start-url"],
+            mobileConfig: args["mobile-config"],
+            desktopDevice: args["desktop-device"],
+            multiDeviceConfig: args["multi-device-config"],
+            webConfig: args["web-config"],
             json: args.json,
             dryRun: args["dry-run"],
         }));

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

@@ -1,14 +1,5 @@
 import { type ClientDeps } from "../../client.js";
-import type { Envelope } from "../../types.js";
-interface UserDevice {
-    id: string;
-    name: string;
-    platform: string;
-    os?: string;
-    status: string;
-    lastSeenAt?: string;
-    createdAt: string;
-}
+import type { Envelope, UserDevice } from "../../types.js";
 export declare function runDeviceStatus(deps?: ClientDeps): Promise<Envelope<{
     devices: UserDevice[];
 }>>;

package/dist/commands/mcp/server.test.js

@@ -24,7 +24,7 @@ async function connect() {
     };
 }
 describe("createMcpServer wiring", () => {
-    it("exposes all 22 tools through tools/list with valid JSON Schema", async () => {
+    it("exposes all 29 tools through tools/list with valid JSON Schema", async () => {
         const { client, cleanup } = await connect();
         try {
             const { tools } = await client.listTools();
@@ -37,17 +37,27 @@ describe("createMcpServer wiring", () => {
                 "aximo_get_session_screenshots",
                 "aximo_get_session_timeline",
                 "aximo_list_cases",
+                "aximo_list_devices",
                 "aximo_list_projects",
                 "aximo_list_sessions",
+                "aximo_list_uploads",
+                "aximo_list_user_devices",
                 "aximo_create_case",
                 "aximo_update_case",
+                "aximo_archive_case",
+                "aximo_restore_case",
                 "aximo_delete_case",
+                "aximo_run_case",
                 "aximo_create_plan",
                 "aximo_add_case_to_plan",
                 "aximo_remove_case_from_plan",
                 "aximo_list_plans",
                 "aximo_get_plan",
                 "aximo_update_plan",
+                "aximo_archive_plan",
+                "aximo_restore_plan",
+                "aximo_delete_plan",
+                "aximo_run_plan",
                 "aximo_list_plan_runs",
                 "aximo_get_plan_run",
                 "aximo_save_session_as_case",

package/dist/commands/mcp/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { request } from "../../client.js";
+import { ARCHIVE_FIRST_HINT, featureHint, isArchiveFirstConflict, withDetails, } from "../../errors.js";
 function ok(payload) {
     return {
         content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
@@ -23,18 +24,31 @@ async function call(fn) {
     catch (e) {
         if (!(e instanceof Error))
             return err(String(e));
-        const status = e.status;
+        const { status, details } = e;
+        const message = withDetails(e.message, details);
         if (status === 401)
             return err("Unauthorized: check AXIMO_API_KEY", "Run `aximo configure`.");
         if (status === 403) {
-            return err(e.message || "Forbidden", "API key may not have access to this resource.");
+            return err(message || "Forbidden", featureHint(e.message, details) ?? "API key may not have access to this resource.");
         }
         if (status === 404)
-            return err(e.message || "Not found");
-        if (status === 429)
-            return err("Rate limited", "Aximo enforces a daily session limit.");
+            return err(message || "Not found");
+        if (status === 429) {
+            const retryAfter = e.retryAfter;
+            return err("Rate limited", retryAfter
+                ? `Back off and retry after ${retryAfter} seconds.`
+                : "Back off before retrying; Aximo rate-limits requests per organization.");
+        }
+        // Mirrors the 409 branch in handleApiError. Without this, an archive-first
+        // 409 falls through to the bare `HTTP 409: ...` case below and the agent is
+        // told to call a REST endpoint it has no way to reach, while the tool that
+        // would work goes unmentioned. Keyed on the details-enriched message, the
+        // same input handleApiError feeds the predicate, so the two cannot disagree.
+        if (status === 409) {
+            return err(message || "Conflict", isArchiveFirstConflict(message) ? ARCHIVE_FIRST_HINT : undefined);
+        }
         if (typeof status === "number")
-            return err(`HTTP ${status}: ${e.message}`);
+            return err(`HTTP ${status}: ${message}`);
         if (e.message.startsWith("No API key configured")) {
             return err("API key not configured", "Run `aximo configure` and restart the MCP server.");
         }
@@ -54,6 +68,18 @@ function buildQuery(params) {
     }
     return out;
 }
+// Mobile app selection accepted by the run triggers (multi-app, max 3).
+// ARN fields are the encrypted tokens Aximo returns, never raw AWS ARNs.
+const runAppsSchema = z
+    .array(z.object({
+    uploadArn: z
+        .string()
+        .describe("Encrypted upload token (from aximo_get_case config or `aximo upload`)."),
+    uploadType: z.enum(["own_app", "existing", "sample"]),
+    appName: z.string().nullable(),
+    bundleId: z.string().optional(),
+}))
+    .max(3);
 export function defineTools(deps = {}) {
     return [
         {
@@ -66,6 +92,53 @@ export function defineTools(deps = {}) {
                 return res;
             }),
         },
+        {
+            name: "aximo_list_devices",
+            title: "List Device Farm devices",
+            description: "List the cloud (AWS Device Farm) mobile devices available to your organization — not BYOD devices (see aximo_list_user_devices). Each device's arn is the encrypted token to pass as deviceArn, and its name as deviceName, in a case's apiMobileConfig or multi-device mobile entries (aximo_update_case) and in per-run overrides (aximo_run_case, aximo_run_plan). Filter by platform (ANDROID | IOS) or availableOnly.",
+            inputSchema: {
+                platform: z.enum(["ANDROID", "IOS"]).optional(),
+                availableOnly: z
+                    .boolean()
+                    .optional()
+                    .describe("Only devices that are currently free to run on."),
+            },
+            handler: async ({ platform, availableOnly }) => call(async () => {
+                return await request("/api/devices", { query: { platform, availableOnly: availableOnly || undefined } }, deps);
+            }),
+        },
+        {
+            name: "aximo_list_user_devices",
+            title: "List registered BYOD devices",
+            description: "List the BYOD (bring-your-own) desktop and mobile devices registered with `aximo device register` by the owner of this API key — other members' devices are not included. Each device's id is the userDeviceId to pass in a case's apiDesktopConfig or multi-device local entries (aximo_update_case) and in per-run overrides. status shows whether the device is online. Returns 404 when BYOD is not enabled for the organization.",
+            inputSchema: {},
+            handler: async () => call(async () => {
+                try {
+                    return await request("/api/devices/user", {}, deps);
+                }
+                catch (e) {
+                    // The route answers a bare 404 when the org has no BYOD feature.
+                    if (e.status === 404) {
+                        throw Object.assign(new Error("BYOD is not enabled for this organization"), {
+                            status: 403,
+                            details: { feature: "byodEnabled" },
+                        });
+                    }
+                    throw e;
+                }
+            }),
+        },
+        {
+            name: "aximo_list_uploads",
+            title: "List app uploads",
+            description: "List the mobile app binaries (APK / IPA) uploaded to your organization. Each upload's uploadArn is the encrypted token to pass as uploadArn in a case's apiMobileConfig or multi-device mobile entries (aximo_update_case) and in per-run overrides; only uploads with status succeeded can be installed. identifier is the app's bundleId. Filter by fileType (ANDROID_APP | IOS_APP).",
+            inputSchema: {
+                fileType: z.enum(["ANDROID_APP", "IOS_APP"]).optional(),
+            },
+            handler: async ({ fileType }) => call(async () => {
+                return await request("/api/uploads", { query: { fileType } }, deps);
+            }),
+        },
         {
             name: "aximo_list_sessions",
             title: "List sessions",
@@ -215,15 +288,36 @@ export function defineTools(deps = {}) {
         {
             name: "aximo_update_case",
             title: "Update test case",
-            description: "Update a test case's title, description, scenario, type, format, or startUrl (pass null to clear startUrl). Omitted fields are left unchanged; at least one field is required. Per-target device configuration cannot be changed over the API, and changing type does not create or clear it (e.g. switching to mobile leaves apiMobileConfig null until set in the dashboard).",
+            description: "Update a test case's title, description, scenario, type, format, or startUrl (pass null to clear description or startUrl; an empty description string is stored as-is, not a clear). Omitted fields are left unchanged; at least one field is required. Pass apiMobileConfig / apiDesktopConfig / apiMultiDeviceConfig / apiWebConfig to set the case's default targets — the same shapes aximo_get_case returns; null clears one, omit leaves it unchanged. Each config value is replaced whole — send the complete config object you want stored (never a partial), and omit a config key entirely to leave that target unchanged. deviceArn = aximo_list_devices devices[].arn and deviceName = devices[].name; uploadArn = aximo_list_uploads uploads[].uploadArn (status succeeded), bundleId = uploads[].identifier, uploadType is usually \"own_app\"; userDeviceId = aximo_list_user_devices devices[].id. apiMobileConfig.platform is ANDROID|IOS; multi-device mobilePlatform is android|ios. There is no top-level userDeviceId/deviceArn here — they live inside the config objects. Desktop and multi-device require the organization's BYOD / multi-device feature. You can set type in the same call.",
             inputSchema: {
                 caseId: z.string().uuid(),
                 title: z.string().min(1).max(500).optional(),
-                description: z.string().optional(),
+                description: z.string().nullable().optional(),
                 scenario: z.string().min(1).optional(),
                 type: z.enum(["web", "mobile", "desktop", "multi_device"]).optional(),
                 format: z.enum(["gherkin", "markdown", "plain_text"]).optional(),
                 startUrl: z.string().url().nullable().optional(),
+                apiMobileConfig: z
+                    .record(z.unknown())
+                    .nullable()
+                    .optional()
+                    .describe("{ deviceArn, deviceName, platform?: ANDROID|IOS, uploadArn?, uploadType?: own_app|existing|sample, appName?, bundleId?, apps?: [{ uploadArn, uploadType, appName, bundleId? }] (max 3) }. null clears."),
+                apiDesktopConfig: z
+                    .object({ userDeviceId: z.string().uuid() })
+                    .passthrough()
+                    .nullable()
+                    .optional()
+                    .describe("{ userDeviceId } of a registered BYOD desktop device (aximo_list_user_devices); name/platform/os are resolved server-side. null clears."),
+                apiMultiDeviceConfig: z
+                    .array(z.record(z.unknown()))
+                    .nullable()
+                    .optional()
+                    .describe('2-3 entries, each { kind: "web", name, startUrl?, userDeviceId? } or { kind: "mobile", name, mobilePlatform: android|ios, deviceArn?, deviceName?, userDeviceId?, uploadArn?, uploadType?, appName?, bundleId?, apps? }. null clears.'),
+                apiWebConfig: z
+                    .record(z.unknown())
+                    .nullable()
+                    .optional()
+                    .describe("{ hostnameOverrideIds?: string[] }. null clears."),
             },
             handler: async ({ caseId, ...body }) => call(async () => {
                 if (Object.keys(body).length === 0) {
@@ -232,10 +326,32 @@ export function defineTools(deps = {}) {
                 return await request(`/api/cases/${encodeURIComponent(caseId)}`, { method: "PATCH", body }, deps);
             }),
         },
+        {
+            name: "aximo_archive_case",
+            title: "Archive test case",
+            description: "Archive a test case: hidden from lists, plans, and new runs; run history kept. Idempotent. Required before aximo_delete_case can permanently delete it.",
+            inputSchema: {
+                caseId: z.string().uuid(),
+            },
+            handler: async ({ caseId }) => call(async () => {
+                return await request(`/api/cases/${encodeURIComponent(caseId)}/archive`, { method: "POST" }, deps);
+            }),
+        },
+        {
+            name: "aximo_restore_case",
+            title: "Restore test case",
+            description: "Restore an archived test case: it returns to lists, directory counts, and plan membership. Idempotent. A case whose directory was deleted while archived returns to the project root.",
+            inputSchema: {
+                caseId: z.string().uuid(),
+            },
+            handler: async ({ caseId }) => call(async () => {
+                return await request(`/api/cases/${encodeURIComponent(caseId)}/restore`, { method: "POST" }, deps);
+            }),
+        },
         {
             name: "aximo_delete_case",
             title: "Delete test case",
-            description: "Permanently delete a test case. It is removed from any plans it belongs to; past run sessions are kept but detached. This cannot be undone.",
+            description: "Permanently delete an already-archived test case. Archive it first with aximo_archive_case. Requires an organization admin or owner API key. It is removed from any plans it belongs to, and its rows in past plan runs go with it, so those runs list fewer cases than their stored totals; the agent sessions themselves are kept but detached. This cannot be undone.",
             inputSchema: {
                 caseId: z.string().uuid(),
             },
@@ -243,6 +359,45 @@ export function defineTools(deps = {}) {
                 return await request(`/api/cases/${encodeURIComponent(caseId)}`, { method: "DELETE" }, deps);
             }),
         },
+        {
+            name: "aximo_run_case",
+            title: "Run test case",
+            description: "Start a run of a saved test case and return the new sessionId. The case must be apiEnabled (aximo_get_case shows this). All fields except caseId are per-run overrides of the case's stored per-target configuration: omit them to run with the saved defaults. Poll aximo_get_session with the returned sessionId to follow the run; wait at least 5 seconds between polls.",
+            inputSchema: {
+                caseId: z.string().uuid(),
+                model: z
+                    .string()
+                    .optional()
+                    .describe("Agent model override (e.g. 'sonnet', 'haiku', 'auto'). Server-validated."),
+                hostnameOverrideIds: z
+                    .array(z.string().uuid())
+                    .optional()
+                    .describe("Web cases: hostname override ids to apply for this run."),
+                userDeviceId: z
+                    .string()
+                    .uuid()
+                    .optional()
+                    .describe("A user-owned (BYOD) device id; overrides the device bound on the case."),
+                deviceArn: z
+                    .string()
+                    .optional()
+                    .describe("Mobile cases: encrypted device token; overrides the saved device."),
+                deviceName: z.string().optional(),
+                platform: z.enum(["ANDROID", "IOS"]).optional(),
+                uploadArn: z
+                    .string()
+                    .optional()
+                    .describe("Mobile cases: encrypted app upload token; overrides the saved app."),
+                uploadType: z.enum(["own_app", "existing", "sample"]).optional(),
+                appName: z.string().optional(),
+                apps: runAppsSchema
+                    .optional()
+                    .describe("Mobile multi-app runs: up to 3 apps to install; overrides the saved apps and takes precedence over the single-app uploadArn/uploadType/appName fields."),
+            },
+            handler: async ({ caseId, ...body }) => call(async () => {
+                return await request(`/api/triggers/cases/${encodeURIComponent(caseId)}/run`, { method: "POST", body }, deps);
+            }),
+        },
         {
             name: "aximo_create_plan",
             title: "Create test plan",
@@ -323,6 +478,87 @@ export function defineTools(deps = {}) {
                 return await request(`/api/plans/${encodeURIComponent(planId)}`, { method: "PATCH", body }, deps);
             }),
         },
+        {
+            name: "aximo_archive_plan",
+            title: "Archive test plan",
+            description: "Archive a test plan: hidden from lists and blocked from new runs; its cases, run history, and schedule are all kept. The scheduler skips archived plans, so restoring one resumes its normal cadence. Idempotent. Required before aximo_delete_plan can permanently delete it.",
+            inputSchema: {
+                planId: z.string().uuid(),
+            },
+            handler: async ({ planId }) => call(async () => {
+                return await request(`/api/plans/${encodeURIComponent(planId)}/archive`, { method: "POST" }, deps);
+            }),
+        },
+        {
+            name: "aximo_restore_plan",
+            title: "Restore test plan",
+            description: "Restore an archived test plan: it returns to lists and can be run again, and its schedule resumes exactly as configured. Idempotent.",
+            inputSchema: {
+                planId: z.string().uuid(),
+            },
+            handler: async ({ planId }) => call(async () => {
+                return await request(`/api/plans/${encodeURIComponent(planId)}/restore`, { method: "POST" }, deps);
+            }),
+        },
+        {
+            name: "aximo_delete_plan",
+            title: "Delete test plan",
+            description: "Permanently delete an already-archived test plan. Archive it first with aximo_archive_plan. Requires an organization admin or owner API key. Its member cases are kept, and so is its run history: those runs are detached from the plan and remain readable as standalone results. This cannot be undone.",
+            inputSchema: {
+                planId: z.string().uuid(),
+            },
+            handler: async ({ planId }) => call(async () => {
+                return await request(`/api/plans/${encodeURIComponent(planId)}`, { method: "DELETE" }, deps);
+            }),
+        },
+        {
+            name: "aximo_run_plan",
+            title: "Run test plan",
+            description: "Start a run of a test plan (all its cases) and return the new planRunId, totalCases, and the effective executionMode. The plan must be apiEnabled (aximo_get_plan shows this). All fields except planId are per-run overrides of the plan's stored settings: omit them to run with the saved defaults. Poll aximo_get_plan_run with the returned planRunId to follow the run; wait at least 5 seconds between polls.",
+            inputSchema: {
+                planId: z.string().uuid(),
+                model: z
+                    .string()
+                    .optional()
+                    .describe("Agent model override (e.g. 'sonnet', 'haiku', 'auto'). Server-validated."),
+                executionMode: z
+                    .enum(["parallel", "sequential"])
+                    .optional()
+                    .describe("Override the plan's stored Execution setting for this run only."),
+                mobileConfig: z
+                    .object({
+                    deviceArn: z.string().describe("Encrypted device token."),
+                    deviceName: z.string(),
+                    platform: z.enum(["ANDROID", "IOS"]).optional(),
+                    uploadArn: z.string().optional().describe("Encrypted app upload token."),
+                    uploadType: z.enum(["own_app", "existing", "sample"]).optional(),
+                    appName: z.string().optional(),
+                    apps: runAppsSchema
+                        .optional()
+                        .describe("Takes precedence over the single-app uploadArn/uploadType/appName fields."),
+                })
+                    .optional()
+                    .describe("Device + app for the plan's mobile cases; overrides the plan's stored config."),
+                desktopConfig: z
+                    .object({
+                    devices: z.array(z.object({ userDeviceId: z.string().uuid() })).min(1),
+                })
+                    .optional()
+                    .describe("User-owned (BYOD) desktop devices to run desktop cases on; overrides the plan's stored desktop config."),
+                variables: z
+                    .array(z.object({
+                    name: z
+                        .string()
+                        .describe("Uppercase letters, digits, underscores; must start with a letter."),
+                    value: z.string(),
+                }))
+                    .optional()
+                    .describe("Per-run variable values merged over the plan's stored variables by name; never persisted on the plan."),
+            },
+            handler: async ({ planId, ...body }) => call(async () => {
+                return await request(`/api/triggers/plans/${encodeURIComponent(planId)}/run`, { method: "POST", body }, deps);
+            }),
+        },
         {
             name: "aximo_list_plan_runs",
             title: "List plan runs",