@autifyhq/aximo-cli 0.7.0 → 0.9.0

package/dist/commands/mobile/signing-consent.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from "vitest";
+import { confirmIosSigning } from "./signing-consent.js";
+const SIGNING = {
+    teamId: "TEAM123456",
+    signingId: "Apple Development",
+    wdaBundleId: "com.aximo.wda.TEAM123456",
+};
+describe("confirmIosSigning", () => {
+    it("prints a notice naming the team and its account-facing effects", async () => {
+        const log = vi.fn();
+        await confirmIosSigning({ signing: SIGNING, assumeYes: true, log });
+        const notice = log.mock.calls.map((c) => c[0]).join("\n");
+        expect(notice).toContain("TEAM123456");
+        expect(notice).toContain("Apple Developer account");
+        expect(notice).toContain("AXIMO_IOS_TEAM_ID");
+    });
+    it("skips the prompt with --yes", async () => {
+        const ask = vi.fn();
+        await expect(confirmIosSigning({
+            signing: SIGNING,
+            assumeYes: true,
+            interactive: true,
+            ask,
+            log: vi.fn(),
+        })).resolves.toBe(true);
+        expect(ask).not.toHaveBeenCalled();
+    });
+    it("proceeds without prompting when not interactive (daemonized connect)", async () => {
+        const ask = vi.fn();
+        await expect(confirmIosSigning({ signing: SIGNING, interactive: false, ask, log: vi.fn() })).resolves.toBe(true);
+        expect(ask).not.toHaveBeenCalled();
+    });
+    it("defaults to yes on Enter", async () => {
+        const ask = vi.fn(async () => "");
+        await expect(confirmIosSigning({ signing: SIGNING, interactive: true, ask, log: vi.fn() })).resolves.toBe(true);
+        expect(ask).toHaveBeenCalledWith("Proceed with this signing identity? [Y/n] ");
+    });
+    it("accepts y/yes and arbitrary input as yes", async () => {
+        for (const answer of ["y", "Y", "yes", " sure "]) {
+            const ask = vi.fn(async () => answer);
+            await expect(confirmIosSigning({ signing: SIGNING, interactive: true, ask, log: vi.fn() })).resolves.toBe(true);
+        }
+    });
+    it("declines only on an explicit n/no", async () => {
+        for (const answer of ["n", "N", "no", " NO "]) {
+            const ask = vi.fn(async () => answer);
+            await expect(confirmIosSigning({ signing: SIGNING, interactive: true, ask, log: vi.fn() })).resolves.toBe(false);
+        }
+    });
+});

package/dist/commands/mobile/unregister.d.ts

@@ -1,10 +1,14 @@
 import { type ClientDeps } from "../../client.js";
 import type { Envelope } from "../../types.js";
+export interface MobileUnregisterResult {
+    success: boolean;
+    deviceId: string;
+    name: string;
+}
 export declare function runMobileUnregister(options: {
     deviceId?: string;
-}, deps?: ClientDeps): Promise<Envelope<{
-    success: boolean;
-}>>;
+}, deps?: ClientDeps): Promise<Envelope<MobileUnregisterResult>>;
+export declare function renderUnregisterResult(data: MobileUnregisterResult): string;
 declare const _default: import("citty").CommandDef<{
     readonly "device-id": {
         readonly type: "string";

package/dist/commands/mobile/unregister.js

@@ -2,14 +2,15 @@ import { defineCommand } from "citty";
 import { existsSync, unlinkSync } from "node:fs";
 import { request } from "../../client.js";
 import { handleApiError } from "../../errors.js";
-import { formatSuccess, printResult } from "../../output.js";
+import { formatSuccess } from "../../output.js";
 import { resolveDeviceConfig } from "./connect-core.js";
+import { printMobileResult } from "./output.js";
 import { getMobileDeviceConfigPath } from "./paths.js";
 export async function runMobileUnregister(options, deps) {
     const resolved = resolveDeviceConfig(options.deviceId);
     if (!resolved.ok)
         return resolved;
-    const { deviceId } = resolved.config;
+    const { deviceId, name } = resolved.config;
     try {
         await request(`/api/devices/user/${deviceId}`, { method: "DELETE" }, deps ?? {});
     }
@@ -25,7 +26,10 @@ export async function runMobileUnregister(options, deps) {
     if (existsSync(configPath)) {
         unlinkSync(configPath);
     }
-    return formatSuccess({ success: true });
+    return formatSuccess({ success: true, deviceId, name });
+}
+export function renderUnregisterResult(data) {
+    return `Unregistered "${data.name}" (device ${data.deviceId}).`;
 }
 export default defineCommand({
     meta: { name: "unregister", description: "Unregister a local mobile device" },
@@ -37,6 +41,8 @@ export default defineCommand({
     },
     async run({ args }) {
         const deviceId = args["device-id"];
-        printResult(await runMobileUnregister(deviceId ? { deviceId } : {}));
+        printMobileResult(await runMobileUnregister(deviceId ? { deviceId } : {}), {
+            render: renderUnregisterResult,
+        });
     },
 });

package/dist/commands/plan/index.js

@@ -3,6 +3,7 @@ export default defineCommand({
     meta: { name: "plan", description: "Test plan commands" },
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
+        update: () => import("./update.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

@@ -2,6 +2,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { runPlanAddCase } from "./add-case.js";
 import { runPlanCreate } from "./create.js";
+import { runPlanUpdate } from "./update.js";
 import { runPlanRemoveCase } from "./remove-case.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
@@ -102,3 +103,63 @@ describe("runPlanRemoveCase", () => {
         }
     });
 });
+describe("runPlanUpdate", () => {
+    it("PATCHes the provided fields and returns the updated plan", async () => {
+        let seen;
+        server.use(http.patch(`${TEST_BASE_URL}/api/plans/pl1`, async ({ request: req }) => {
+            seen = await req.json();
+            return HttpResponse.json({
+                success: true,
+                plan: {
+                    id: "pl1",
+                    title: "Renamed",
+                    description: null,
+                    executionMode: "sequential",
+                    stopOnFailure: true,
+                    updatedAt: "2026-07-16T00:00:00Z",
+                },
+            });
+        }));
+        const result = await runPlanUpdate({
+            planId: "pl1",
+            title: "Renamed",
+            executionMode: "sequential",
+            stopOnFailure: "true",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data)) {
+            expect(result.data.plan.executionMode).toBe("sequential");
+        }
+        expect(seen).toMatchObject({
+            title: "Renamed",
+            executionMode: "sequential",
+            stopOnFailure: true,
+        });
+    });
+    it("rejects when no fields are provided", async () => {
+        const result = await runPlanUpdate({ planId: "pl1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("rejects an invalid executionMode", async () => {
+        const result = await runPlanUpdate({ planId: "pl1", executionMode: "fastest" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("rejects a non-boolean stop-on-failure", async () => {
+        const result = await runPlanUpdate({ planId: "pl1", stopOnFailure: "yes" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("--dry-run returns the PATCH request without calling the API", async () => {
+        const result = await runPlanUpdate({ planId: "pl1", title: "t", dryRun: true });
+        expect(result.ok).toBe(true);
+        if (result.ok && "dryRun" in result.data) {
+            expect(result.data.method).toBe("PATCH");
+            expect(result.data.url).toBe(`${TEST_BASE_URL}/api/plans/pl1`);
+        }
+    });
+});

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

@@ -0,0 +1,42 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { Envelope, UpdatePlanResult } from "../../types.js";
+export interface UpdatePlanOptions {
+    planId?: unknown;
+    title?: unknown;
+    description?: unknown;
+    executionMode?: unknown;
+    stopOnFailure?: unknown;
+    json?: unknown;
+    dryRun?: unknown;
+}
+export declare function runPlanUpdate(options: UpdatePlanOptions, deps?: ClientDeps): Promise<Envelope<UpdatePlanResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly planId: {
+        readonly type: "positional";
+        readonly required: true;
+    };
+    readonly title: {
+        readonly type: "string";
+    };
+    readonly description: {
+        readonly type: "string";
+    };
+    readonly "execution-mode": {
+        readonly type: "string";
+        readonly description: "parallel or sequential";
+    };
+    readonly "stop-on-failure": {
+        readonly type: "string";
+        readonly description: "true or false; sequential runs only";
+    };
+    readonly json: {
+        readonly type: "string";
+        readonly description: "Raw JSON request body (replaces individual flags)";
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;

package/dist/commands/plan/update.js

@@ -0,0 +1,78 @@
+import { defineCommand } from "citty";
+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, parseExecutionMode, parseOptionalBoolean, requireId, } from "../../validate.js";
+export async function runPlanUpdate(options, deps) {
+    let planId;
+    let body;
+    const override = resolveJsonOverride(options.json);
+    if (override && "error" in override)
+        return override.error;
+    try {
+        planId = requireId("planId", options.planId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    if (override) {
+        body = override.body;
+    }
+    else {
+        try {
+            body = {
+                title: optionalString("title", options.title),
+                description: optionalString("description", options.description),
+                executionMode: parseExecutionMode(options.executionMode),
+                stopOnFailure: parseOptionalBoolean("stopOnFailure", options.stopOnFailure),
+            };
+        }
+        catch (err) {
+            return validationError(err);
+        }
+        if (Object.values(body).every((v) => v === undefined)) {
+            return validationError(new Error("at least one field to update is required"));
+        }
+    }
+    const path = `/api/plans/${encodeURIComponent(planId)}`;
+    if (options.dryRun) {
+        return dryRunEnvelope("PATCH", path, body);
+    }
+    try {
+        const res = await request(path, { method: "PATCH", body }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: { name: "update", description: "Update a test plan" },
+    args: {
+        planId: { type: "positional", required: true },
+        title: { type: "string" },
+        description: { type: "string" },
+        "execution-mode": {
+            type: "string",
+            description: "parallel or sequential",
+        },
+        "stop-on-failure": {
+            type: "string",
+            description: "true or false; sequential runs only",
+        },
+        json: { type: "string", description: "Raw JSON request body (replaces individual flags)" },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runPlanUpdate({
+            planId: args.planId,
+            title: args.title,
+            description: args.description,
+            executionMode: args["execution-mode"],
+            stopOnFailure: args["stop-on-failure"],
+            json: args.json,
+            dryRun: args["dry-run"],
+        }));
+    },
+});

package/dist/commands/schema.js

@@ -19,7 +19,7 @@ export function getSchema() {
         name: "aximo",
         version: pkg.version,
         commands: [
-            cmd("health", "Health commands", [], [cmd("check", "GET /api/health")]),
+            cmd("health", "Health commands", [], [cmd("check", "GET /api/health + authenticated API-key probe")]),
             cmd("session", "Session commands", [], [
                 cmd("create", "POST /api/sessions", [
                     arg("title", "string", "Session title"),

package/dist/commands/session/save-as-case.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, requireId } from "../../validate.js";
+import { optionalString, requireId, parseCaseFormat, parseSaveAsCaseType } from "../../validate.js";
 export async function runSessionSaveAsCase(options, deps) {
     let sessionId;
     let body;
@@ -23,9 +23,9 @@ export async function runSessionSaveAsCase(options, deps) {
         try {
             body = {
                 title: optionalString("title", options.title),
-                type: optionalString("type", options.type),
+                type: parseSaveAsCaseType(options.type),
                 scenario: optionalString("scenario", options.scenario),
-                format: optionalString("format", options.format),
+                format: parseCaseFormat(options.format),
             };
         }
         catch (err) {

package/dist/commands/trigger/plan/run.d.ts

@@ -1,10 +1,11 @@
-import type { Envelope, PlanRunResult } from "../../../types.js";
 import { type ClientDeps } from "../../../client.js";
 import { type DryRunResult } from "../../../mutate.js";
+import type { Envelope, PlanRunResult } from "../../../types.js";
 export interface TriggerPlanRunOptions {
     planId?: unknown;
     model?: unknown;
     mobileConfig?: unknown;
+    executionMode?: unknown;
     json?: unknown;
     dryRun?: unknown;
 }
@@ -21,6 +22,10 @@ declare const _default: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: "JSON object string";
     };
+    readonly "execution-mode": {
+        readonly type: "string";
+        readonly description: "parallel or sequential (defaults to the plan's stored setting)";
+    };
     readonly json: {
         readonly type: "string";
         readonly description: "Raw JSON request body";

package/dist/commands/trigger/plan/run.js

@@ -1,9 +1,9 @@
 import { defineCommand } from "citty";
-import { formatSuccess, printResult, validationError } from "../../../output.js";
-import { handleApiError } from "../../../errors.js";
 import { request } from "../../../client.js";
-import { requireId, optionalString, parseJsonObject } from "../../../validate.js";
+import { handleApiError } from "../../../errors.js";
 import { dryRunEnvelope, resolveJsonOverride } from "../../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../../output.js";
+import { optionalString, parseExecutionMode, parseJsonObject, requireId, } from "../../../validate.js";
 export async function runTriggerPlanRun(options, deps) {
     let planId;
     let body;
@@ -24,6 +24,7 @@ export async function runTriggerPlanRun(options, deps) {
             body = {
                 model: optionalString("model", options.model),
                 mobileConfig: parseJsonObject("mobileConfig", options.mobileConfig),
+                executionMode: parseExecutionMode(options.executionMode),
             };
         }
         catch (err) {
@@ -48,6 +49,10 @@ export default defineCommand({
         planId: { type: "positional", required: true },
         model: { type: "string" },
         "mobile-config": { type: "string", description: "JSON object string" },
+        "execution-mode": {
+            type: "string",
+            description: "parallel or sequential (defaults to the plan's stored setting)",
+        },
         json: { type: "string", description: "Raw JSON request body" },
         "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
     },
@@ -56,6 +61,7 @@ export default defineCommand({
             planId: args.planId,
             model: args.model,
             mobileConfig: args["mobile-config"],
+            executionMode: args["execution-mode"],
             json: args.json,
             dryRun: args["dry-run"],
         }));

package/dist/commands/trigger/trigger.test.js

@@ -1,9 +1,9 @@
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
-import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
-import { runTriggerCaseRun } from "./case/run.js";
+import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
 import { runTriggerCaseGet } from "./case/get.js";
-import { runTriggerPlanRun } from "./plan/run.js";
+import { runTriggerCaseRun } from "./case/run.js";
 import { runTriggerPlanGet } from "./plan/get.js";
+import { runTriggerPlanRun } from "./plan/run.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
     process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
@@ -90,6 +90,25 @@ describe("trigger plan", () => {
         if (!result.ok)
             expect(result.error.code).toBe("validation_error");
     });
+    it("sends executionMode in the body and surfaces the echoed effective mode", async () => {
+        let seen;
+        server.use(http.post(`${TEST_BASE_URL}/api/triggers/plans/p1/run`, async ({ request: req }) => {
+            seen = await req.json();
+            return HttpResponse.json({ success: true, planRunId: "pr1", totalCases: 2, executionMode: "sequential" }, { status: 201 });
+        }));
+        const result = await runTriggerPlanRun({ planId: "p1", executionMode: "sequential" });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data)) {
+            expect(result.data.executionMode).toBe("sequential");
+        }
+        expect(seen).toMatchObject({ executionMode: "sequential" });
+    });
+    it("rejects an invalid executionMode", async () => {
+        const result = await runTriggerPlanRun({ planId: "p1", executionMode: "fastest" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
     it("gets plan run", async () => {
         server.use(http.get(`${TEST_BASE_URL}/api/triggers/plans/p1/runs/pr1`, () => HttpResponse.json({ id: "pr1", status: "running" })));
         const result = await runTriggerPlanGet("p1", "pr1");

package/dist/commands/upload/put.d.ts

@@ -4,6 +4,7 @@ import { type DryRunResult } from "../../mutate.js";
 export interface UploadPutOptions {
     uploadId?: unknown;
     bytes?: Uint8Array | undefined;
+    presignedUrl?: unknown;
     dryRun?: unknown;
 }
 export declare function runUploadPut(options: UploadPutOptions, deps?: ClientDeps): Promise<Envelope<UploadPutResult | DryRunResult>>;
@@ -16,6 +17,10 @@ declare const _default: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: "Local path to the file";
     };
+    readonly url: {
+        readonly type: "string";
+        readonly description: "presignedUrl from `upload create` output (required for S3-backed deployments)";
+    };
     readonly "dry-run": {
         readonly type: "boolean";
         readonly description: "Validate and show request without calling API";

package/dist/commands/upload/put.js

@@ -2,34 +2,63 @@ import { readFile } from "node:fs/promises";
 import { defineCommand } from "citty";
 import { formatSuccess, formatError, printResult, validationError } from "../../output.js";
 import { handleApiError } from "../../errors.js";
-import { request } from "../../client.js";
-import { requireId } from "../../validate.js";
+import { request, putToPresignedUrl } from "../../client.js";
+import { requireId, optionalString } from "../../validate.js";
 import { dryRunEnvelope } from "../../mutate.js";
+const PRESIGNED_URL_HINT = "This deployment stores uploads in S3, so the API does not accept file bytes directly. " +
+    'Re-run with --url "<presignedUrl>" using the presignedUrl returned by `aximo upload create`.';
+function isAbsoluteUrl(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+function isMethodNotAllowed(err) {
+    return typeof err === "object" && err !== null && err.status === 405;
+}
 export async function runUploadPut(options, deps) {
     let uploadId;
+    let urlOption;
     try {
         uploadId = requireId("uploadId", options.uploadId);
-        if (!options.dryRun && !options.bytes)
-            throw new Error("file bytes are required");
+        urlOption = optionalString("url", options.presignedUrl);
     }
     catch (err) {
         return validationError(err);
     }
-    const path = `/api/uploads/${encodeURIComponent(uploadId)}`;
+    // The presignedUrl from `upload create` is either an absolute S3 URL
+    // (cloud deployments) or a relative API path (local storage).
+    const presignedUrl = urlOption;
+    const useDirectPut = presignedUrl !== undefined && isAbsoluteUrl(presignedUrl);
+    const target = presignedUrl ?? `/api/uploads/${encodeURIComponent(uploadId)}`;
     if (options.dryRun) {
-        return dryRunEnvelope("PUT", path);
+        return dryRunEnvelope("PUT", target);
+    }
+    if (!options.bytes) {
+        return validationError(new Error("file bytes are required"));
+    }
+    const body = new Blob([new Uint8Array(options.bytes)]);
+    if (useDirectPut) {
+        try {
+            await putToPresignedUrl(target, body, "application/octet-stream", deps ?? {});
+            return formatSuccess({ success: true });
+        }
+        catch (err) {
+            return handleApiError(err);
+        }
     }
     try {
-        await request(path, {
+        await request(target, {
             method: "PUT",
-            rawBody: options.bytes ? new Blob([new Uint8Array(options.bytes)]) : undefined,
+            rawBody: body,
             contentType: "application/octet-stream",
             expectJson: false,
         }, deps ?? {});
         return formatSuccess({ success: true });
     }
     catch (err) {
-        return handleApiError(err);
+        const envelope = handleApiError(err);
+        if (isMethodNotAllowed(err)) {
+            envelope.error.hint = PRESIGNED_URL_HINT;
+        }
+        return envelope;
     }
 }
 export default defineCommand({
@@ -37,12 +66,16 @@ export default defineCommand({
     args: {
         uploadId: { type: "positional", required: true },
         file: { type: "string", description: "Local path to the file" },
+        url: {
+            type: "string",
+            description: "presignedUrl from `upload create` output (required for S3-backed deployments)",
+        },
         "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
     },
     async run({ args }) {
         const dryRun = args["dry-run"];
         if (dryRun) {
-            printResult(await runUploadPut({ uploadId: args.uploadId, dryRun: true }));
+            printResult(await runUploadPut({ uploadId: args.uploadId, presignedUrl: args.url, dryRun: true }));
             return;
         }
         if (!args.file) {
@@ -57,6 +90,6 @@ export default defineCommand({
             printResult(formatError("validation_error", `Cannot read file: ${args.file}`, false, err instanceof Error ? err.message : undefined));
             return;
         }
-        printResult(await runUploadPut({ uploadId: args.uploadId, bytes }));
+        printResult(await runUploadPut({ uploadId: args.uploadId, presignedUrl: args.url, bytes }));
     },
 });

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

@@ -98,6 +98,75 @@ describe("runUploadPut", () => {
         expect(body).not.toBeNull();
         expect(new Uint8Array(body)).toEqual(new Uint8Array([9, 9]));
     });
+    it("PUTs directly to an absolute presigned URL without auth headers", async () => {
+        let seenCT = "";
+        let seenAuth = "unset";
+        let seenApiKey = "unset";
+        let body = null;
+        server.use(http.put("https://bucket.s3.test/uploads/u1", async ({ request: req }) => {
+            seenCT = req.headers.get("content-type") ?? "";
+            seenAuth = req.headers.get("authorization");
+            seenApiKey = req.headers.get("x-api-key");
+            body = await req.arrayBuffer();
+            return new HttpResponse(null, { status: 200 });
+        }));
+        const result = await runUploadPut({
+            uploadId: "u1",
+            bytes: new Uint8Array([7, 7]),
+            presignedUrl: "https://bucket.s3.test/uploads/u1?X-Amz-Signature=abc",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok && !("dryRun" in result.data))
+            expect(result.data.success).toBe(true);
+        expect(seenCT).toContain("application/octet-stream");
+        expect(seenAuth).toBeNull();
+        expect(seenApiKey).toBeNull();
+        expect(new Uint8Array(body)).toEqual(new Uint8Array([7, 7]));
+    });
+    it("maps a presigned URL failure to an error envelope", async () => {
+        server.use(http.put("https://bucket.s3.test/uploads/u2", () => HttpResponse.text("SignatureDoesNotMatch", { status: 403 })));
+        const result = await runUploadPut({
+            uploadId: "u2",
+            bytes: new Uint8Array([1]),
+            presignedUrl: "https://bucket.s3.test/uploads/u2",
+        });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("unauthorized");
+    });
+    it("PUTs via the authenticated API when --url is relative", async () => {
+        let seenApiKey = null;
+        server.use(http.put(`${TEST_BASE_URL}/api/uploads/u1`, ({ request: req }) => {
+            seenApiKey = req.headers.get("x-api-key");
+            return HttpResponse.json({ success: true });
+        }));
+        const result = await runUploadPut({
+            uploadId: "u1",
+            bytes: new Uint8Array([1]),
+            presignedUrl: "/api/uploads/u1",
+        });
+        expect(result.ok).toBe(true);
+        expect(seenApiKey).toBe("test-key");
+    });
+    it("hints at --url when the API PUT returns 405", async () => {
+        server.use(http.put(`${TEST_BASE_URL}/api/uploads/u1`, () => HttpResponse.json({ error: "Uploads use presigned URLs; PUT the file to the presigned URL instead" }, { status: 405 })));
+        const result = await runUploadPut({ uploadId: "u1", bytes: new Uint8Array([1]) });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.hint).toContain("--url");
+            expect(result.error.hint).toContain("aximo upload create");
+        }
+    });
+    it("rejects a non-string --url", async () => {
+        const result = await runUploadPut({
+            uploadId: "u1",
+            bytes: new Uint8Array([1]),
+            presignedUrl: 42,
+        });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
     it("rejects missing bytes", async () => {
         const result = await runUploadPut({ uploadId: "u1" });
         expect(result.ok).toBe(false);
@@ -107,6 +176,19 @@ describe("runUploadPut", () => {
         expect(result.ok).toBe(true);
         if (result.ok && "dryRun" in result.data) {
             expect(result.data.method).toBe("PUT");
+            expect(result.data.url).toBe(`${TEST_BASE_URL}/api/uploads/u1`);
+        }
+    });
+    it("--dry-run reflects the presigned URL target", async () => {
+        const result = await runUploadPut({
+            uploadId: "u1",
+            presignedUrl: "https://bucket.s3.test/uploads/u1?X-Amz-Signature=abc",
+            dryRun: true,
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok && "dryRun" in result.data) {
+            expect(result.data.method).toBe("PUT");
+            expect(result.data.url).toBe("https://bucket.s3.test/uploads/u1?X-Amz-Signature=abc");
         }
     });
     it("rejects uploadId with forbidden chars", async () => {