@autifyhq/aximo-cli 0.13.0 → 0.14.0

package/dist/commands/plan/restore.js

@@ -0,0 +1,42 @@
+import { defineCommand } from "citty";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { dryRunEnvelope } from "../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { requireId } from "../../validate.js";
+export async function runPlanRestore(options, deps) {
+    let planId;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}/restore`;
+    if (options.dryRun) {
+        return dryRunEnvelope("POST", path);
+    }
+    try {
+        const res = await request(path, { method: "POST" }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "restore",
+        description: "Restore an archived test plan (returns it to lists; its schedule resumes as configured)",
+    },
+    args: {
+        planId: { type: "positional", description: "Plan ID", required: true },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runPlanRestore({
+            planId: args.planId,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/upload/upload.test.js

@@ -131,8 +131,11 @@ describe("runUploadPut", () => {
             presignedUrl: "https://bucket.s3.test/uploads/u2",
         });
         expect(result.ok).toBe(false);
-        if (!result.ok)
-            expect(result.error.code).toBe("unauthorized");
+        if (!result.ok) {
+            expect(result.error.code).toBe("forbidden");
+            // A signature failure is not a role problem, so no admin hint.
+            expect(result.error.hint).toBeUndefined();
+        }
     });
     it("PUTs via the authenticated API when --url is relative", async () => {
         let seenApiKey = null;

package/dist/errors.d.ts

@@ -1,2 +1,7 @@
 import type { ErrorEnvelope } from "./types.js";
+export declare function describeDetails(details: unknown): string | undefined;
+export declare function withDetails(message: string, details: unknown): string;
+export declare function featureHint(message: string, details: unknown): string | undefined;
+export declare const ARCHIVE_FIRST_HINT = "Archive the resource first, then retry: `aximo case archive <caseId>` / `aximo plan archive <planId>` (MCP: aximo_archive_case / aximo_archive_plan).";
+export declare function isArchiveFirstConflict(message: string): boolean;
 export declare function handleApiError(error: unknown): ErrorEnvelope;

package/dist/errors.js

@@ -5,8 +5,106 @@ function isHttpError(error) {
     const e = error;
     return typeof e["status"] === "number" && typeof e["message"] === "string";
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const MAX_ISSUE_LINES = 5;
+// Walks zod treeifyError / flattenError output into "path: message" lines.
+function collectIssues(node, path, out) {
+    if (out.length >= MAX_ISSUE_LINES)
+        return;
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => collectIssues(item, `${path}[${i}]`, out));
+        return;
+    }
+    if (!isRecord(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (out.length >= MAX_ISSUE_LINES)
+            return;
+        if (key === "errors" || key === "_errors" || key === "formErrors") {
+            if (!Array.isArray(value))
+                continue;
+            for (const msg of value) {
+                if (out.length >= MAX_ISSUE_LINES)
+                    return;
+                if (typeof msg === "string")
+                    out.push(path ? `${path}: ${msg}` : msg);
+            }
+        }
+        else if (key === "properties" || key === "fieldErrors" || key === "items") {
+            collectIssues(value, path, out);
+        }
+        else {
+            const childPath = path ? `${path}.${key}` : key;
+            if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+                for (const msg of value) {
+                    if (out.length >= MAX_ISSUE_LINES)
+                        return;
+                    out.push(`${childPath}: ${msg}`);
+                }
+            }
+            else {
+                collectIssues(value, childPath, out);
+            }
+        }
+    }
+}
+export function describeDetails(details) {
+    if (!isRecord(details))
+        return undefined;
+    const parts = [];
+    if (typeof details["path"] === "string")
+        parts.push(`at ${details["path"]}`);
+    if (typeof details["feature"] === "string") {
+        parts.push(`requires feature ${details["feature"]}`);
+    }
+    if (Array.isArray(details["ids"]))
+        parts.push(`ids: ${details["ids"].map(String).join(", ")}`);
+    if (Array.isArray(details["unknownFields"])) {
+        parts.push(`unknown fields: ${details["unknownFields"].map(String).join(", ")}`);
+    }
+    if (typeof details["hint"] === "string")
+        parts.push(details["hint"]);
+    if (parts.length === 0)
+        collectIssues(details, "", parts);
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
+export function withDetails(message, details) {
+    const extra = describeDetails(details);
+    return extra ? `${message} (${extra})` : message;
+}
+const FEATURE_DISABLED_RE = /not enabled for this organization/i;
+export function featureHint(message, details) {
+    const feature = isRecord(details) ? details["feature"] : undefined;
+    if (typeof feature === "string") {
+        return `Ask an Aximo organization admin to enable ${feature}.`;
+    }
+    if (FEATURE_DISABLED_RE.test(message)) {
+        return "Ask an Aximo organization admin to enable this feature.";
+    }
+    return undefined;
+}
 const NOT_FOUND_HINT = "Check the ID exists and you have access. List resources: aximo project list / aximo device list / aximo upload list";
 const AUTH_HINT = "Run `aximo configure` to save credentials, or set AXIMO_API_KEY via `export AXIMO_API_KEY=your-key` or `node --env-file=.env`.";
+// 403 is a permission outcome, not a credentials problem, so it no longer routes
+// to AUTH_HINT: telling someone to `aximo configure` would have them replace a key
+// that works. The admin wording is attached only when the server says the role is
+// what is missing, following ARCHIVE_FIRST_HINT below; a presigned-upload 403
+// (SignatureDoesNotMatch) is also a 403 and has nothing to do with roles.
+const ADMIN_ROLE_HINT = "This action requires an organization admin or owner API key. Ask an admin to run it, or use a key belonging to an admin or owner.";
+// The archived-first delete gate answers with 409 and a message naming the REST archive
+// endpoint; this hint is what translates it into CLI and MCP terms. Only add it when the
+// server says archiving is what is missing: other 409s (e.g. "Case already in plan") are
+// not fixed by archiving anything.
+// Exported so the MCP error mapper in commands/mcp/tools.ts uses the same string.
+// The hint names both surfaces, so both surfaces have to be able to emit it.
+export const ARCHIVE_FIRST_HINT = "Archive the resource first, then retry: `aximo case archive <caseId>` / `aximo plan archive <planId>` (MCP: aximo_archive_case / aximo_archive_plan).";
+// The server wording is load-bearing for this test: it is the only signal either
+// mapper has for telling an archive-first 409 apart from any other 409.
+export function isArchiveFirstConflict(message) {
+    return /archiv/i.test(message);
+}
 // Node's net layer surfaces transient transport failures via these system error codes.
 const RETRYABLE_NET_CODES = new Set([
     "ECONNRESET",
@@ -34,12 +132,18 @@ function isTransientNetworkError(error) {
 }
 export function handleApiError(error) {
     if (isHttpError(error)) {
-        const { status, message, retryAfter } = error;
+        const { status, retryAfter, details } = error;
+        const message = withDetails(error.message, details);
         if (status === 401) {
             return formatError("unauthorized", message, false, AUTH_HINT);
         }
         if (status === 403) {
-            return formatError("unauthorized", message, false, AUTH_HINT);
+            // A feature gate names its own remedy; otherwise fall back to the role hint
+            // when the server says which role is missing. Never the credentials hint: a
+            // 403 means the key is valid.
+            const hint = featureHint(error.message, details) ??
+                (/admin|owner/i.test(message) ? ADMIN_ROLE_HINT : undefined);
+            return formatError("forbidden", message, false, hint);
         }
         if (status === 404) {
             return formatError("not_found", message, false, NOT_FOUND_HINT);
@@ -52,6 +156,10 @@ export function handleApiError(error) {
         if (status >= 500) {
             return formatError("api_error", message, true);
         }
+        if (status === 409) {
+            const hint = isArchiveFirstConflict(message) ? ARCHIVE_FIRST_HINT : undefined;
+            return formatError("conflict", message, false, hint);
+        }
         if (status >= 400) {
             return formatError("validation_error", message, false);
         }

package/dist/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { handleApiError } from "./errors.js";
+import { describeDetails, featureHint, handleApiError, withDetails } from "./errors.js";
 function httpErr(status, message = `status ${status}`, retryAfter) {
     const err = Object.assign(new Error(message), { status });
     if (retryAfter !== undefined)
@@ -15,8 +15,17 @@ describe("handleApiError", () => {
         expect(r.error.hint).toContain("AXIMO_API_KEY");
         expect(r.error.hint).toContain("--env-file");
     });
-    it("maps 403 to unauthorized", () => {
-        expect(handleApiError(httpErr(403)).error.code).toBe("unauthorized");
+    // 403 is its own code as of GEN-2793: it means the key is valid but the role is
+    // not sufficient, which is a different remedy from a missing or bad key.
+    it("maps 403 to forbidden, with no credentials hint", () => {
+        const r = handleApiError(httpErr(403));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toBeUndefined();
+    });
+    it("adds the admin-role hint only when the server names the role", () => {
+        const r = handleApiError(httpErr(403, "Only admins and owners can perform this action"));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toContain("admin or owner");
     });
     it("maps 404 to not_found with list hint", () => {
         const r = handleApiError(httpErr(404));
@@ -86,3 +95,97 @@ describe("handleApiError", () => {
         expect(handleApiError("weird").error.message).toBe("weird");
     });
 });
+function httpErrWithDetails(status, message, details) {
+    return Object.assign(new Error(message), { status, details });
+}
+describe("describeDetails", () => {
+    it("renders path, feature, ids, unknownFields and hint", () => {
+        expect(describeDetails({ path: "apiWebConfig.hostnameOverrideIds", ids: ["a", "b"] })).toBe("at apiWebConfig.hostnameOverrideIds; ids: a, b");
+        expect(describeDetails({ feature: "multiDeviceEnabled" })).toBe("requires feature multiDeviceEnabled");
+        expect(describeDetails({ unknownFields: ["userDeviceId"], hint: "Put it inside apiDesktopConfig." })).toBe("unknown fields: userDeviceId; Put it inside apiDesktopConfig.");
+    });
+    it("walks a zod treeifyError tree into path: message lines", () => {
+        const tree = {
+            errors: ["Unrecognized key"],
+            properties: {
+                apiMobileConfig: {
+                    errors: [],
+                    properties: {
+                        deviceArn: { errors: ["Required"] },
+                        apps: {
+                            errors: [],
+                            items: [null, { errors: [], properties: { uploadArn: { errors: ["Required"] } } }],
+                        },
+                    },
+                },
+            },
+        };
+        expect(describeDetails(tree)).toBe("Unrecognized key; apiMobileConfig.deviceArn: Required; apiMobileConfig.apps[1].uploadArn: Required");
+    });
+    it("walks a zod flattenError fieldErrors map", () => {
+        expect(describeDetails({
+            formErrors: [],
+            fieldErrors: { platform: ["Invalid enum value"], limit: ["Too big"] },
+        })).toBe("platform: Invalid enum value; limit: Too big");
+    });
+    it("caps zod issues at five lines", () => {
+        const fieldErrors = {};
+        for (let i = 0; i < 8; i++)
+            fieldErrors[`f${i}`] = ["bad"];
+        expect(describeDetails({ fieldErrors })?.split("; ")).toHaveLength(5);
+    });
+    it("returns undefined for non-object or empty details", () => {
+        expect(describeDetails(undefined)).toBeUndefined();
+        expect(describeDetails("x")).toBeUndefined();
+        expect(describeDetails(["x"])).toBeUndefined();
+        expect(describeDetails({})).toBeUndefined();
+        expect(describeDetails({ errors: [], properties: { a: { errors: 5 } } })).toBeUndefined();
+    });
+});
+describe("withDetails / featureHint", () => {
+    it("appends rendered details in parentheses", () => {
+        expect(withDetails("Upload not found", { path: "apiMobileConfig.apps[0].uploadArn" })).toBe("Upload not found (at apiMobileConfig.apps[0].uploadArn)");
+        expect(withDetails("Upload not found", undefined)).toBe("Upload not found");
+    });
+    it("names the feature from details, or recognises the not-enabled message", () => {
+        expect(featureHint("Forbidden", { feature: "byodEnabled" })).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+        expect(featureHint("Multi-device cases are not enabled for this organization", undefined)).toBe("Ask an Aximo organization admin to enable this feature.");
+        expect(featureHint("Forbidden", { feature: 3 })).toBeUndefined();
+    });
+});
+describe("handleApiError with details", () => {
+    it("names the failing path on a 404", () => {
+        const r = handleApiError(httpErrWithDetails(404, "Upload not found", {
+            path: "apiMultiDeviceConfig[1].apps[0].uploadArn",
+        }));
+        expect(r.error.code).toBe("not_found");
+        expect(r.error.message).toBe("Upload not found (at apiMultiDeviceConfig[1].apps[0].uploadArn)");
+    });
+    it("swaps the credentials hint for an admin hint on a feature-gated 403", () => {
+        const r = handleApiError(httpErrWithDetails(403, "Desktop cases are not enabled for this organization", {
+            feature: "byodEnabled",
+        }));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.message).toContain("requires feature byodEnabled");
+        expect(r.error.hint).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+    });
+    it("renders zod issues on a 400", () => {
+        const r = handleApiError(httpErrWithDetails(400, "Invalid request body", {
+            errors: [],
+            properties: { apiWebConfig: { errors: ["Expected object, received string"] } },
+        }));
+        expect(r.error.code).toBe("validation_error");
+        expect(r.error.message).toBe("Invalid request body (apiWebConfig: Expected object, received string)");
+    });
+});
+describe("collectIssues cap", () => {
+    it("caps issue lines even within a single errors array", () => {
+        const details = {
+            properties: {
+                scenario: { errors: Array.from({ length: 12 }, (_, i) => `msg ${i}`) },
+            },
+        };
+        const text = describeDetails(details);
+        expect(text?.split("; ")).toHaveLength(5);
+    });
+});

package/dist/types.d.ts

@@ -6,7 +6,7 @@ export interface SuccessEnvelope<T> {
     data: T;
     meta?: SuccessMeta | undefined;
 }
-export type ErrorCode = "unauthorized" | "rate_limited" | "not_found" | "validation_error" | "api_error";
+export type ErrorCode = "unauthorized" | "forbidden" | "rate_limited" | "not_found" | "validation_error" | "conflict" | "api_error";
 export interface ErrorEnvelope {
     ok: false;
     error: {
@@ -186,6 +186,17 @@ export interface Device {
     arn?: string | undefined;
     name?: string | undefined;
     platform?: Platform | undefined;
+    os?: string | undefined;
+    [key: string]: unknown;
+}
+export interface UserDevice {
+    id: string;
+    name: string;
+    platform: string;
+    os?: string | null;
+    status: string;
+    lastSeenAt?: string | null;
+    createdAt: string;
     [key: string]: unknown;
 }
 export interface CreateUploadInput {
@@ -202,6 +213,10 @@ export interface Upload {
     id?: string | undefined;
     fileName?: string | undefined;
     fileType?: FileType | undefined;
+    uploadArn?: string | undefined;
+    status?: string | undefined;
+    appName?: string | null | undefined;
+    identifier?: string | null | undefined;
     [key: string]: unknown;
 }
 export interface UploadPutResult {
@@ -232,11 +247,15 @@ export interface CreateCaseResult {
 }
 export interface UpdateCaseInput {
     title?: string | undefined;
-    description?: string | undefined;
+    description?: string | null | undefined;
     scenario?: string | undefined;
     type?: CaseType | undefined;
     format?: CaseFormat | undefined;
-    startUrl?: string | undefined;
+    startUrl?: string | null | undefined;
+    apiMobileConfig?: CaseMobileConfig | null | undefined;
+    apiDesktopConfig?: Pick<CaseDesktopConfig, "userDeviceId"> | null | undefined;
+    apiMultiDeviceConfig?: CaseMultiDeviceDevice[] | null | undefined;
+    apiWebConfig?: CaseWebConfig | null | undefined;
 }
 export interface UpdateCaseResult {
     success: boolean;
@@ -250,11 +269,30 @@ export interface UpdateCaseResult {
         format: CaseFormat;
         startUrl: string | null;
         updatedAt: string;
+        apiMobileConfig: CaseMobileConfig | null;
+        apiWebConfig: CaseWebConfig | null;
+        apiDesktopConfig: CaseDesktopConfig | null;
+        apiMultiDeviceConfig: CaseMultiDeviceDevice[] | null;
     };
 }
 export interface DeleteCaseResult {
     success: boolean;
 }
+export interface ArchiveCaseResult {
+    archived: boolean;
+}
+export interface ArchivePlanResult {
+    archived: boolean;
+}
+export interface RestoreCaseResult {
+    restored: boolean;
+}
+export interface RestorePlanResult {
+    restored: boolean;
+}
+export interface DeletePlanResult {
+    success: boolean;
+}
 export interface CreatePlanInput {
     projectId: string;
     title: string;

package/dist/validate.d.ts

@@ -17,3 +17,4 @@ export declare class JsonBodyError extends Error {
 }
 export declare function parseJsonBody(value: unknown): Record<string, unknown>;
 export declare function parseJsonObject(name: string, value: unknown): Record<string, unknown> | undefined;
+export declare function parseJsonArray(name: string, value: unknown): unknown[] | undefined;

package/dist/validate.js

@@ -130,20 +130,32 @@ export function parseJsonBody(value) {
     }
     return parsed;
 }
-export function parseJsonObject(name, value) {
+function parseJsonFlag(name, value) {
     if (value === undefined || value === "")
         return undefined;
     if (typeof value !== "string")
         throw new Error(`${name} must be a JSON string`);
-    let parsed;
     try {
-        parsed = JSON.parse(value);
+        return JSON.parse(value);
     }
     catch (err) {
         throw new Error(`${name} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
+}
+export function parseJsonObject(name, value) {
+    const parsed = parseJsonFlag(name, value);
+    if (parsed === undefined)
+        return undefined;
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
         throw new Error(`${name} must be a JSON object`);
     }
     return parsed;
 }
+export function parseJsonArray(name, value) {
+    const parsed = parseJsonFlag(name, value);
+    if (parsed === undefined)
+        return undefined;
+    if (!Array.isArray(parsed))
+        throw new Error(`${name} must be a JSON array`);
+    return parsed;
+}

package/dist/validate.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { requireString, requireId, parseCaseFormat, parseCaseType, parsePlatform, parseSaveAsCaseType, parseFileType, parseTags, parseJsonObject, parseJsonBody, JsonBodyError, } from "./validate.js";
+import { requireString, requireId, parseCaseFormat, parseCaseType, parsePlatform, parseSaveAsCaseType, parseFileType, parseTags, parseJsonObject, parseJsonArray, parseJsonBody, JsonBodyError, } from "./validate.js";
 describe("requireId", () => {
     it("accepts plain IDs", () => {
         expect(requireId("sessionId", "abc123_-")).toBe("abc123_-");
@@ -132,3 +132,20 @@ describe("parseCaseFormat", () => {
         expect(() => parseCaseFormat("klingon")).toThrow(/must be gherkin, markdown, or plain_text/);
     });
 });
+describe("parseJsonArray", () => {
+    it("parses a JSON array", () => {
+        expect(parseJsonArray("multiDeviceConfig", '[{"kind":"web"}]')).toEqual([{ kind: "web" }]);
+    });
+    it("rejects objects", () => {
+        expect(() => parseJsonArray("x", "{}")).toThrow("must be a JSON array");
+    });
+    it("rejects invalid JSON and non-strings", () => {
+        expect(() => parseJsonArray("x", "[bad")).toThrow("not valid JSON");
+        expect(() => parseJsonArray("x", 5)).toThrow("must be a JSON string");
+        expect(() => parseJsonObject("x", 5)).toThrow("must be a JSON string");
+    });
+    it("returns undefined for empty input", () => {
+        expect(parseJsonArray("x", "")).toBeUndefined();
+        expect(parseJsonArray("x", undefined)).toBeUndefined();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",