@autifyhq/aximo-cli 0.13.0 → 0.15.0

package/dist/commands/plan/archive.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 runPlanArchive(options, deps) {
+    let planId;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}/archive`;
+    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: "archive",
+        description: "Archive a test plan (hides it from lists; cases, run history, and its schedule are kept)",
+    },
+    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 runPlanArchive({
+            planId: args.planId,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/plan/delete.d.ts

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { DeletePlanResult, Envelope } from "../../types.js";
+export interface DeletePlanOptions {
+    planId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanDelete(options: DeletePlanOptions, deps?: ClientDeps): Promise<Envelope<DeletePlanResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly planId: {
+        readonly type: "positional";
+        readonly description: "Plan ID";
+        readonly required: true;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;

package/dist/commands/plan/delete.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 runPlanDelete(options, deps) {
+    let planId;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}`;
+    if (options.dryRun) {
+        return dryRunEnvelope("DELETE", path);
+    }
+    try {
+        const res = await request(path, { method: "DELETE" }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "delete",
+        description: "Permanently delete an archived test plan (archive it first with `aximo plan archive`). Requires an org admin or owner. Member cases and run history are kept; the runs are detached from the plan",
+    },
+    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 runPlanDelete({
+            planId: args.planId,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/plan/index.js

@@ -4,6 +4,9 @@ export default defineCommand({
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
         update: () => import("./update.js").then((m) => m.default),
+        archive: () => import("./archive.js").then((m) => m.default),
+        restore: () => import("./restore.js").then((m) => m.default),
+        delete: () => import("./delete.js").then((m) => m.default),
         "add-case": () => import("./add-case.js").then((m) => m.default),
         "remove-case": () => import("./remove-case.js").then((m) => m.default),
     },

package/dist/commands/plan/plan.test.js

@@ -4,6 +4,9 @@ import { runPlanAddCase } from "./add-case.js";
 import { runPlanCreate } from "./create.js";
 import { runPlanUpdate } from "./update.js";
 import { runPlanRemoveCase } from "./remove-case.js";
+import { runPlanArchive } from "./archive.js";
+import { runPlanDelete } from "./delete.js";
+import { runPlanRestore } from "./restore.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
     process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
@@ -61,12 +64,14 @@ describe("runPlanAddCase", () => {
         if (!result.ok)
             expect(result.error.code).toBe("validation_error");
     });
-    it("maps 409 to validation_error", async () => {
+    it("maps 409 to conflict without an archive hint", async () => {
         server.use(http.post(`${TEST_BASE_URL}/api/plans/pl1/cases`, () => HttpResponse.json({ error: "Case already in plan" }, { status: 409 })));
         const result = await runPlanAddCase({ planId: "pl1", caseId: "c1" });
         expect(result.ok).toBe(false);
-        if (!result.ok)
-            expect(result.error.code).toBe("validation_error");
+        if (!result.ok) {
+            expect(result.error.code).toBe("conflict");
+            expect(result.error.hint).toBeUndefined();
+        }
     });
     it("--dry-run returns request without calling API", async () => {
         const result = await runPlanAddCase({ planId: "pl1", caseId: "c1", dryRun: true });
@@ -103,6 +108,41 @@ describe("runPlanRemoveCase", () => {
         }
     });
 });
+describe("runPlanArchive", () => {
+    it("POSTs the archive path and returns success", async () => {
+        let called = false;
+        server.use(http.post(`${TEST_BASE_URL}/api/plans/pl1/archive`, () => {
+            called = true;
+            return HttpResponse.json({ archived: true });
+        }));
+        const result = await runPlanArchive({ planId: "pl1" });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data))
+            expect(result.data.archived).toBe(true);
+        expect(called).toBe(true);
+    });
+    it("rejects missing planId", async () => {
+        const result = await runPlanArchive({});
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("maps 404 to not_found", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/plans/pl1/archive`, () => HttpResponse.json({ error: "Test plan not found" }, { status: 404 })));
+        const result = await runPlanArchive({ planId: "pl1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("not_found");
+    });
+    it("--dry-run returns a POST request without calling API", async () => {
+        const result = await runPlanArchive({ planId: "pl1", dryRun: true });
+        expect(result.ok).toBe(true);
+        if (result.ok && "dryRun" in result.data) {
+            expect(result.data.method).toBe("POST");
+            expect(result.data.url).toBe(`${TEST_BASE_URL}/api/plans/pl1/archive`);
+        }
+    });
+});
 describe("runPlanUpdate", () => {
     it("PATCHes the provided fields and returns the updated plan", async () => {
         let seen;
@@ -163,3 +203,75 @@ describe("runPlanUpdate", () => {
         }
     });
 });
+describe("runPlanRestore", () => {
+    it("POSTs the restore path and returns success", async () => {
+        let called = false;
+        server.use(http.post(`${TEST_BASE_URL}/api/plans/p1/restore`, () => {
+            called = true;
+            return HttpResponse.json({ restored: true });
+        }));
+        const result = await runPlanRestore({ planId: "p1" });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data))
+            expect(result.data.restored).toBe(true);
+        expect(called).toBe(true);
+    });
+    it("rejects missing planId", async () => {
+        const result = await runPlanRestore({});
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+});
+describe("runPlanDelete", () => {
+    it("DELETEs the plan and returns success", async () => {
+        let called = false;
+        server.use(http.delete(`${TEST_BASE_URL}/api/plans/p1`, () => {
+            called = true;
+            return HttpResponse.json({ success: true });
+        }));
+        const result = await runPlanDelete({ planId: "p1" });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data))
+            expect(result.data.success).toBe(true);
+        expect(called).toBe(true);
+    });
+    // Archive is the mandatory first step, and the hint names the command that does it.
+    it("maps the archived-first 409 to conflict with an actionable hint", async () => {
+        server.use(http.delete(`${TEST_BASE_URL}/api/plans/p1`, () => HttpResponse.json({
+            error: "Test plan must be archived before it can be permanently deleted. Archive it first with POST /api/plans/{planId}/archive, then retry the delete.",
+        }, { status: 409 })));
+        const result = await runPlanDelete({ planId: "p1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("conflict");
+            expect(result.error.message).toContain("must be archived");
+        }
+    });
+    it("maps 403 for a non-admin key", async () => {
+        server.use(http.delete(`${TEST_BASE_URL}/api/plans/p1`, () => HttpResponse.json({ error: "Only admins and owners can perform this action" }, { status: 403 })));
+        const result = await runPlanDelete({ planId: "p1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            // Not "unauthorized": the key is valid, the role is not sufficient, and the
+            // hint must not tell the user to go reconfigure a working key.
+            expect(result.error.code).toBe("forbidden");
+            expect(result.error.hint).toContain("admin or owner");
+            expect(result.error.hint).not.toContain("aximo configure");
+        }
+    });
+    it("--dry-run returns a DELETE request without calling API", async () => {
+        let called = false;
+        server.use(http.delete(`${TEST_BASE_URL}/api/plans/p1`, () => {
+            called = true;
+            return HttpResponse.json({ success: true });
+        }));
+        const result = await runPlanDelete({ planId: "p1", dryRun: true });
+        expect(called).toBe(false);
+        expect(result.ok).toBe(true);
+        if (result.ok && "dryRun" in result.data) {
+            expect(result.data.method).toBe("DELETE");
+            expect(result.data.url).toBe(`${TEST_BASE_URL}/api/plans/p1`);
+        }
+    });
+});

package/dist/commands/plan/restore.d.ts

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { RestorePlanResult, Envelope } from "../../types.js";
+export interface RestorePlanOptions {
+    planId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanRestore(options: RestorePlanOptions, deps?: ClientDeps): Promise<Envelope<RestorePlanResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly planId: {
+        readonly type: "positional";
+        readonly description: "Plan ID";
+        readonly required: true;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;

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/session/export.d.ts

@@ -0,0 +1,30 @@
+import type { ClientDeps } from "../../client.js";
+import { type SessionExportResult } from "../../session-export.js";
+import type { Envelope } from "../../types.js";
+export interface SessionExportOptions {
+    sessionId?: unknown;
+    format?: unknown;
+    output?: unknown;
+    locale?: unknown;
+}
+export declare function runSessionExport(options: SessionExportOptions, deps?: ClientDeps): Promise<Envelope<SessionExportResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly sessionId: {
+        readonly type: "positional";
+        readonly description: "Session ID";
+        readonly required: true;
+    };
+    readonly format: {
+        readonly type: "string";
+        readonly description: "pdf | screenshots (default: pdf)";
+    };
+    readonly output: {
+        readonly type: "string";
+        readonly description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)";
+    };
+    readonly locale: {
+        readonly type: "string";
+        readonly description: "Report language: en | ja | ko (default: en)";
+    };
+}>;
+export default _default;

package/dist/commands/session/export.js

@@ -0,0 +1,58 @@
+import { defineCommand } from "citty";
+import { handleApiError } from "../../errors.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { defaultExportFileName, exportSession, SESSION_EXPORT_FORMATS, SESSION_EXPORT_LOCALES, } from "../../session-export.js";
+import { optionalString, requireId } from "../../validate.js";
+function parseOneOf(name, allowed, value) {
+    const raw = optionalString(name, value);
+    if (raw === undefined)
+        return undefined;
+    if (!allowed.includes(raw)) {
+        throw new Error(`${name} must be one of: ${allowed.join(", ")}`);
+    }
+    return raw;
+}
+export async function runSessionExport(options, deps) {
+    let sessionId;
+    let format;
+    let locale;
+    let output;
+    try {
+        sessionId = requireId("sessionId", options.sessionId);
+        format = parseOneOf("format", SESSION_EXPORT_FORMATS, options.format) ?? "pdf";
+        locale = parseOneOf("locale", SESSION_EXPORT_LOCALES, options.locale);
+        output = optionalString("output", options.output) ?? defaultExportFileName(sessionId, format);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    try {
+        return formatSuccess(await exportSession({ sessionId, format, outputPath: output, locale }, deps));
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "export",
+        description: "Download a session's result as a PDF report or a ZIP of its screenshots",
+    },
+    args: {
+        sessionId: { type: "positional", description: "Session ID", required: true },
+        format: { type: "string", description: "pdf | screenshots (default: pdf)" },
+        output: {
+            type: "string",
+            description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)",
+        },
+        locale: { type: "string", description: "Report language: en | ja | ko (default: en)" },
+    },
+    async run({ args }) {
+        printResult(await runSessionExport({
+            sessionId: args.sessionId,
+            format: args.format,
+            output: args.output,
+            locale: args.locale,
+        }));
+    },
+});

package/dist/commands/session/index.js

@@ -4,6 +4,7 @@ export default defineCommand({
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
         get: () => import("./get.js").then((m) => m.default),
+        export: () => import("./export.js").then((m) => m.default),
         "save-as-case": () => import("./save-as-case.js").then((m) => m.default),
     },
 });

package/dist/commands/session/session.test.js

@@ -1,6 +1,10 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
 import { runSessionCreate } from "./create.js";
+import { runSessionExport } from "./export.js";
 import { runSessionGet } from "./get.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
@@ -126,3 +130,61 @@ describe("runSessionGet", () => {
             expect(result.error.code).toBe("not_found");
     });
 });
+describe("runSessionExport", () => {
+    const sessionId = "44444444-4444-4444-9444-444444444444";
+    const defaultPdf = resolve(`${sessionId}.pdf`);
+    const dir = mkdtempSync(join(tmpdir(), "aximo-session-export-"));
+    afterEach(() => rmSync(defaultPdf, { force: true }));
+    afterAll(() => rmSync(dir, { recursive: true, force: true }));
+    it("defaults to a PDF named after the session in the working directory", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/pdf`, () => new HttpResponse("%PDF-1.3\n%%EOF\n")));
+        const result = await runSessionExport({ sessionId });
+        expect(result).toEqual({
+            ok: true,
+            data: { sessionId, format: "pdf", path: defaultPdf, sizeBytes: 15 },
+        });
+    });
+    it("downloads the screenshots archive in the requested locale to --output", async () => {
+        let locale = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, ({ request }) => {
+            locale = new URL(request.url).searchParams.get("locale");
+            const eocd = Buffer.alloc(22);
+            eocd.writeUInt32LE(0x06054b50, 0);
+            return new HttpResponse(eocd);
+        }));
+        const output = join(dir, "shots.zip");
+        const result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output,
+            locale: "ja",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.path).toBe(output);
+        expect(locale).toBe("ja");
+    });
+    it.each([
+        [{ format: "docx" }, /format must be one of: pdf, screenshots/],
+        [{ locale: "fr" }, /locale must be one of: en, ja, ko/],
+        [{ sessionId: "" }, /sessionId/],
+    ])("rejects %o", async (overrides, message) => {
+        const result = await runSessionExport({ sessionId, ...overrides });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toMatch(message);
+        }
+    });
+    it("maps the API's 409 to a conflict envelope", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, () => HttpResponse.json({ error: "Session has no screenshots to export" }, { status: 409 })));
+        const result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output: join(dir, "x.zip"),
+        });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("conflict");
+    });
+});

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);
         }