@autifyhq/aximo-cli 0.13.0 → 0.14.0

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

@@ -1,4 +1,6 @@
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { ARCHIVE_FIRST_HINT, handleApiError, isArchiveFirstConflict } from "../../errors.js";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { defineTools } from "./tools.js";
 beforeAll(() => {
@@ -22,6 +24,9 @@ describe("defineTools", () => {
         const names = defineTools().map((t) => t.name);
         expect(names).toEqual([
             "aximo_list_projects",
+            "aximo_list_devices",
+            "aximo_list_user_devices",
+            "aximo_list_uploads",
             "aximo_list_sessions",
             "aximo_get_session",
             "aximo_get_session_messages",
@@ -33,6 +38,8 @@ describe("defineTools", () => {
             "aximo_get_case",
             "aximo_create_case",
             "aximo_update_case",
+            "aximo_archive_case",
+            "aximo_restore_case",
             "aximo_delete_case",
             "aximo_run_case",
             "aximo_create_plan",
@@ -41,6 +48,9 @@ describe("defineTools", () => {
             "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",
@@ -180,6 +190,9 @@ describe("aximo_update_case", () => {
         expect(result.isError).toBeUndefined();
         expect(parsePayload(result)).toEqual(payload);
         expect(body).toEqual({ title: "Renamed", scenario: "Given a renamed page" });
+        // GEN-2844 regression guard: an omitted description must not be sent at
+        // all, or every partial update would clear the field server-side.
+        expect(body).not.toHaveProperty("description");
     });
     it("rejects an update with no fields instead of issuing an empty PATCH", async () => {
         let called = false;
@@ -204,6 +217,35 @@ describe("aximo_update_case", () => {
         expect(result.isError).toBeUndefined();
         expect(body).toEqual({ startUrl: null });
     });
+    it("passes description: null through as an explicit clear (GEN-2844)", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, description: null });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({ description: null });
+    });
+    // The tests above call handler() directly, which bypasses Zod entirely --
+    // the MCP SDK is what parses in production. These assertions are what
+    // actually pin the clearable fields to their schema.
+    it("accepts null for the clearable fields at schema time, and drops omitted keys", () => {
+        const tool = byName(defineTools(), "aximo_update_case");
+        // biome-ignore lint/suspicious/noExplicitAny: zod runtime check
+        const schemas = tool.inputSchema;
+        expect(schemas.description.safeParse(null).success).toBe(true);
+        expect(schemas.description.safeParse("").success).toBe(true);
+        expect(schemas.description.safeParse(5).success).toBe(false);
+        expect(schemas.startUrl.safeParse(null).success).toBe(true);
+        expect(schemas.startUrl.safeParse("not-a-url").success).toBe(false);
+        // The object schema must leave omitted keys absent rather than defaulting
+        // them to null, which would clear on every partial update.
+        const parsed = z.object(schemas).parse({ caseId, title: "Renamed" });
+        expect(parsed).not.toHaveProperty("description");
+        expect(parsed).not.toHaveProperty("startUrl");
+    });
 });
 describe("aximo_run_case", () => {
     const caseId = "77777777-7777-4777-9777-777777777777";
@@ -704,6 +746,32 @@ describe("write tools", () => {
         expect(parsePayload(result)).toEqual({ success: true });
         expect(method).toBe("DELETE");
     });
+    it("aximo_archive_case POSTs the case archive path", async () => {
+        let method = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/cases/c1/archive`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ archived: true });
+        }));
+        const tool = byName(defineTools(), "aximo_archive_case");
+        const result = await tool.handler({ caseId: "c1" });
+        expect(parsePayload(result)).toEqual({ archived: true });
+        expect(method).toBe("POST");
+    });
+    it("aximo_archive_plan POSTs the plan archive path", async () => {
+        let method = null;
+        server.use(http.post(`${TEST_BASE_URL}/api/plans/pl1/archive`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ archived: true });
+        }));
+        const tool = byName(defineTools(), "aximo_archive_plan");
+        const result = await tool.handler({ planId: "pl1" });
+        expect(parsePayload(result)).toEqual({ archived: true });
+        expect(method).toBe("POST");
+    });
+    it("aximo_delete_case describes itself as archive-first and permanent", () => {
+        const tool = byName(defineTools(), "aximo_delete_case");
+        expect(tool.description).toBe("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.");
+    });
     it("aximo_delete_case DELETEs the case path", async () => {
         let method = null;
         server.use(http.delete(`${TEST_BASE_URL}/api/cases/c1`, ({ request: req }) => {
@@ -727,3 +795,245 @@ describe("write tools", () => {
         expect(body).toEqual({ title: "Saved" });
     });
 });
+describe("aximo_update_case per-target config", () => {
+    const caseId = "55555555-5555-4555-9555-555555555555";
+    const userDeviceId = "77777777-7777-4777-9777-777777777777";
+    it("forwards the config objects untouched, including keys the CLI does not know about", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const mobile = {
+            deviceArn: "enc-device",
+            deviceName: "Pixel 8",
+            platform: "ANDROID",
+            apps: [{ uploadArn: "enc-upload", uploadType: "own_app", appName: null, bundleId: "com.x" }],
+            futureField: "kept",
+        };
+        const multi = [
+            { kind: "web", name: "Buyer", startUrl: "https://shop.example" },
+            { kind: "mobile", name: "Seller", mobilePlatform: "ios", userDeviceId },
+        ];
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({
+            caseId,
+            type: "multi_device",
+            apiMobileConfig: mobile,
+            apiDesktopConfig: { userDeviceId },
+            apiMultiDeviceConfig: multi,
+            apiWebConfig: { hostnameOverrideIds: ["h1"] },
+        });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({
+            type: "multi_device",
+            apiMobileConfig: mobile,
+            apiDesktopConfig: { userDeviceId },
+            apiMultiDeviceConfig: multi,
+            apiWebConfig: { hostnameOverrideIds: ["h1"] },
+        });
+    });
+    it("passes null configs (and description) through as explicit clears", async () => {
+        let body = null;
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, async ({ request: req }) => {
+            body = await req.json();
+            return HttpResponse.json({ success: true });
+        }));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({
+            caseId,
+            description: null,
+            apiMobileConfig: null,
+            apiDesktopConfig: null,
+            apiMultiDeviceConfig: null,
+            apiWebConfig: null,
+        });
+        expect(result.isError).toBeUndefined();
+        expect(body).toEqual({
+            description: null,
+            apiMobileConfig: null,
+            apiDesktopConfig: null,
+            apiMultiDeviceConfig: null,
+            apiWebConfig: null,
+        });
+    });
+    it("keeps unknown nested keys at schema time and only pins userDeviceId's shape", () => {
+        const schema = z.object(byName(defineTools(), "aximo_update_case").inputSchema);
+        const parsed = schema.parse({
+            caseId,
+            apiMobileConfig: { deviceArn: "x", newKey: 1 },
+            apiMultiDeviceConfig: [{ kind: "web", extra: true }],
+            apiWebConfig: { hostnameOverrideIds: [], newKey: true },
+        });
+        expect(parsed["apiMobileConfig"]).toEqual({ deviceArn: "x", newKey: 1 });
+        expect(parsed["apiMultiDeviceConfig"]).toEqual([{ kind: "web", extra: true }]);
+        expect(parsed["apiWebConfig"]).toEqual({ hostnameOverrideIds: [], newKey: true });
+        expect(schema.safeParse({ caseId, apiDesktopConfig: { userDeviceId: "nope" } }).success).toBe(false);
+        expect(schema.safeParse({ caseId, apiMultiDeviceConfig: "web" }).success).toBe(false);
+    });
+    it("names the failing path from the API's error details", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Upload not found",
+            details: { path: "apiMultiDeviceConfig[1].apps[0].uploadArn" },
+        }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMultiDeviceConfig: [{}, {}] });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("Upload not found (at apiMultiDeviceConfig[1].apps[0].uploadArn)");
+    });
+    it("renders zod issues from an Invalid request body tree", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Invalid request body",
+            details: {
+                errors: [],
+                properties: {
+                    apiMobileConfig: {
+                        errors: [],
+                        properties: { deviceArn: { errors: ["Invalid input: expected string"] } },
+                    },
+                },
+            },
+        }, { status: 400 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMobileConfig: {} });
+        expect(result.isError).toBe(true);
+        expect(parsePayload(result).error).toBe("HTTP 400: Invalid request body (apiMobileConfig.deviceArn: Invalid input: expected string)");
+    });
+    it("points at an org admin, not the API key, when a feature gate rejects the config", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({
+            error: "Desktop cases are not enabled for this organization",
+            details: { feature: "byodEnabled" },
+        }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiDesktopConfig: { userDeviceId } });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toBe("Desktop cases are not enabled for this organization (requires feature byodEnabled)");
+        expect(payload.hint).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+    });
+    it("recognises the feature-gate message even without details", async () => {
+        server.use(http.patch(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({ error: "Multi-device cases are not enabled for this organization" }, { status: 403 })));
+        const tool = byName(defineTools(), "aximo_update_case");
+        const result = await tool.handler({ caseId, apiMultiDeviceConfig: [{}, {}] });
+        const payload = parsePayload(result);
+        expect(payload.error).toBe("Multi-device cases are not enabled for this organization");
+        expect(payload.hint).toMatch(/organization admin/);
+        expect(payload.hint).not.toMatch(/API key/);
+    });
+});
+describe("device and upload read tools", () => {
+    it("aximo_list_devices GETs /api/devices with platform and availableOnly", async () => {
+        let url = null;
+        const payload = {
+            devices: [{ arn: "enc-device", name: "Pixel 8", platform: "ANDROID", os: "14" }],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_devices");
+        const result = await tool.handler({ platform: "ANDROID", availableOnly: true });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url.searchParams.get("platform")).toBe("ANDROID");
+        expect(url.searchParams.get("availableOnly")).toBe("true");
+    });
+    it("aximo_list_devices sends no filters when none are given", async () => {
+        let url = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json({ devices: [] });
+        }));
+        const tool = byName(defineTools(), "aximo_list_devices");
+        await tool.handler({ availableOnly: false });
+        expect([...url.searchParams.keys()]).toEqual([]);
+    });
+    it("aximo_list_user_devices GETs /api/devices/user", async () => {
+        const payload = {
+            devices: [{ id: "u1", name: "Abdul's Mac", platform: "macos", os: "15.0", status: "online" }],
+        };
+        let called = false;
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => {
+            called = true;
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_user_devices");
+        const result = await tool.handler({});
+        expect(called).toBe(true);
+        expect(parsePayload(result)).toEqual(payload);
+    });
+    it("aximo_list_user_devices explains the bare 404 the route returns when BYOD is disabled", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/devices/user`, () => HttpResponse.json({ error: "Not found" }, { status: 404 })));
+        const tool = byName(defineTools(), "aximo_list_user_devices");
+        const result = await tool.handler({});
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toContain("BYOD is not enabled for this organization");
+        expect(payload.hint).toContain("byodEnabled");
+    });
+    it("aximo_list_uploads GETs /api/uploads with fileType", async () => {
+        let url = null;
+        const payload = {
+            uploads: [
+                {
+                    id: "up1",
+                    uploadArn: "enc-upload",
+                    status: "succeeded",
+                    appName: "Shop",
+                    identifier: "com.example.shop",
+                    fileType: "IOS_APP",
+                },
+            ],
+        };
+        server.use(http.get(`${TEST_BASE_URL}/api/uploads`, ({ request: req }) => {
+            url = new URL(req.url);
+            return HttpResponse.json(payload);
+        }));
+        const tool = byName(defineTools(), "aximo_list_uploads");
+        const result = await tool.handler({ fileType: "IOS_APP" });
+        expect(result.isError).toBeUndefined();
+        expect(parsePayload(result)).toEqual(payload);
+        expect(url.searchParams.get("fileType")).toBe("IOS_APP");
+    });
+});
+describe("409 handling parity between the CLI and MCP error mappers", () => {
+    const caseId = "11111111-1111-4111-8111-111111111111";
+    const ARCHIVE_409 = "Test case must be archived before it can be permanently deleted. Archive it first with POST /api/cases/{caseId}/archive, then retry the delete.";
+    const OTHER_409 = "Case already in plan";
+    function conflictOnDelete(message) {
+        server.use(http.delete(`${TEST_BASE_URL}/api/cases/${caseId}`, () => HttpResponse.json({ error: message }, { status: 409 })));
+    }
+    it("surfaces the archive hint on the MCP surface, not just the CLI", async () => {
+        conflictOnDelete(ARCHIVE_409);
+        const tool = byName(defineTools(), "aximo_delete_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/must be archived/);
+        // The hint names aximo_archive_case, so the MCP caller it names has to receive
+        // it. Before this branch existed the agent got a bare "HTTP 409: ..." pointing
+        // at a REST endpoint it cannot call.
+        expect(payload.hint).toBe(ARCHIVE_FIRST_HINT);
+        expect(payload.hint).toMatch(/aximo_archive_case/);
+    });
+    it("stays silent on a 409 that archiving would not fix", async () => {
+        conflictOnDelete(OTHER_409);
+        const tool = byName(defineTools(), "aximo_delete_case");
+        const result = await tool.handler({ caseId });
+        expect(result.isError).toBe(true);
+        const payload = parsePayload(result);
+        expect(payload.error).toMatch(/already in plan/);
+        expect(payload.hint).toBeUndefined();
+    });
+    it("agrees with handleApiError on which 409s earn the hint", () => {
+        // Both mappers key off the same predicate and the same constant. If one side
+        // grows a rule the other lacks, this fails rather than silently diverging on
+        // the agent-facing surface.
+        for (const message of [ARCHIVE_409, OTHER_409]) {
+            const cliEnvelope = handleApiError(Object.assign(new Error(message), { status: 409 }));
+            const expectedHint = isArchiveFirstConflict(message) ? ARCHIVE_FIRST_HINT : undefined;
+            expect(cliEnvelope.error.code).toBe("conflict");
+            expect(cliEnvelope.error.hint).toBe(expectedHint);
+        }
+    });
+});

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

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { ArchivePlanResult, Envelope } from "../../types.js";
+export interface ArchivePlanOptions {
+    planId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanArchive(options: ArchivePlanOptions, deps?: ClientDeps): Promise<Envelope<ArchivePlanResult | 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/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;