@autifyhq/aximo-cli 0.8.0 → 0.10.0

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 () => {

package/dist/desktop-server/preflight.d.ts

@@ -0,0 +1,43 @@
+import { type SpawnSyncReturns } from "node:child_process";
+import type { Check } from "../commands/device/doctor.js";
+export interface PreflightReport {
+    agent?: {
+        platform?: string;
+    };
+    checks: Check[];
+}
+/**
+ * Either the agent's report, "there is no agent to ask yet", or "the agent is
+ * installed but could not answer". Keeping the last two apart matters: doctor
+ * must not tell a tester their machine is fine, or unconfigured, when the probe
+ * actually crashed.
+ */
+export type LocalPreflight = {
+    kind: "ok";
+    report: PreflightReport;
+} | {
+    kind: "not-installed";
+} | {
+    kind: "error";
+    detail: string;
+};
+export type SpawnSyncFn = (command: string, args: string[], options: {
+    encoding: "utf-8";
+    timeout: number;
+    env: NodeJS.ProcessEnv;
+}) => SpawnSyncReturns<string>;
+export interface LocalPreflightOptions {
+    pythonPath?: string;
+    scriptPath?: string;
+    spawn?: SpawnSyncFn;
+}
+/** Run the desktop agent's own environment checks without connecting to a gateway. */
+export declare function runLocalPreflight(options?: LocalPreflightOptions): LocalPreflight;
+export declare function formatPreflightLines(report: PreflightReport): string[];
+export declare function hasBlockingChecks(report: PreflightReport): boolean;
+export interface ConfirmProceedOptions {
+    interactive?: boolean;
+    ask?: (question: string) => Promise<string>;
+}
+/** Ask whether to continue past a failed check, but only when there is one. */
+export declare function confirmProceed(report: PreflightReport, options?: ConfirmProceedOptions): Promise<boolean>;

package/dist/desktop-server/preflight.js

@@ -0,0 +1,78 @@
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { getAgentScriptPath, getAximoDir, getEmbeddedPythonBinary, } from "../commands/device/paths.js";
+import { confirmYesNo } from "../prompt.js";
+const PREFLIGHT_TIMEOUT_MS = 20_000;
+const STATUSES = ["pass", "warn", "fail", "info"];
+function isCheck(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const check = value;
+    return (typeof check["name"] === "string" &&
+        typeof check["message"] === "string" &&
+        STATUSES.includes(check["status"]));
+}
+function parseReport(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const checks = parsed["checks"];
+    if (!Array.isArray(checks) || !checks.every(isCheck))
+        return null;
+    return parsed;
+}
+function firstLine(text) {
+    return text.trim().split("\n")[0]?.trim() ?? "";
+}
+/** Run the desktop agent's own environment checks without connecting to a gateway. */
+export function runLocalPreflight(options = {}) {
+    const pythonPath = options.pythonPath ?? getEmbeddedPythonBinary();
+    const scriptPath = options.scriptPath ?? getAgentScriptPath();
+    if (!existsSync(pythonPath) || !existsSync(scriptPath))
+        return { kind: "not-installed" };
+    const spawn = options.spawn ?? nodeSpawnSync;
+    const result = spawn(pythonPath, [scriptPath, "--preflight"], {
+        encoding: "utf-8",
+        timeout: PREFLIGHT_TIMEOUT_MS,
+        env: { ...process.env, AXIMO_HOME: getAximoDir() },
+    });
+    if (result.status !== 0) {
+        // An agent script older than --preflight exits on the missing GATEWAY_URL.
+        const stderr = firstLine(result.stderr ?? "");
+        if (stderr.includes("GATEWAY_URL"))
+            return { kind: "not-installed" };
+        return { kind: "error", detail: stderr || `exited with status ${result.status}` };
+    }
+    const report = parseReport(result.stdout ?? "");
+    if (!report)
+        return { kind: "error", detail: "the agent did not return a readable report" };
+    return { kind: "ok", report };
+}
+const STATUS_MARK = {
+    pass: "✔",
+    warn: "!",
+    fail: "✘",
+    info: "·",
+};
+export function formatPreflightLines(report) {
+    const lines = report.checks.map((check) => {
+        const hint = check.hint ? `\n    → ${check.hint}` : "";
+        return `  ${STATUS_MARK[check.status]} ${check.name}: ${check.message}${hint}`;
+    });
+    return ["Desktop environment:", ...lines];
+}
+export function hasBlockingChecks(report) {
+    return report.checks.some((check) => check.status === "warn" || check.status === "fail");
+}
+/** Ask whether to continue past a failed check, but only when there is one. */
+export async function confirmProceed(report, options = {}) {
+    if (!hasBlockingChecks(report))
+        return true;
+    return confirmYesNo("Proceed anyway?", options);
+}

package/dist/desktop-server/preflight.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/desktop-server/preflight.test.js

@@ -0,0 +1,115 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { confirmProceed, formatPreflightLines, hasBlockingChecks, runLocalPreflight, } from "./preflight.js";
+const REPORT = {
+    agent: { platform: "Darwin" },
+    checks: [
+        {
+            name: "capture target",
+            status: "info",
+            message: "capturing the primary monitor (2560x1440)",
+        },
+        {
+            name: "accessibility permission",
+            status: "fail",
+            message: "not granted",
+            hint: "System Settings → Privacy & Security → Accessibility",
+        },
+    ],
+};
+const HEALTHY = {
+    checks: [{ name: "input source", status: "pass", message: "com.apple.keylayout.ABC" }],
+};
+let pythonPath;
+let scriptPath;
+beforeAll(() => {
+    const dir = mkdtempSync(join(tmpdir(), "aximo-preflight-"));
+    pythonPath = join(dir, "python3");
+    scriptPath = join(dir, "remote.py");
+    writeFileSync(pythonPath, "");
+    writeFileSync(scriptPath, "");
+});
+function spawnReturning(overrides) {
+    return vi.fn(() => ({
+        status: 0,
+        signal: null,
+        pid: 1,
+        output: [],
+        stdout: "",
+        stderr: "",
+        ...overrides,
+    }));
+}
+describe("runLocalPreflight", () => {
+    it("returns the report the agent printed", () => {
+        const spawn = spawnReturning({ stdout: JSON.stringify(REPORT) });
+        expect(runLocalPreflight({ pythonPath, scriptPath, spawn })).toEqual({
+            kind: "ok",
+            report: REPORT,
+        });
+        expect(spawn).toHaveBeenCalledWith(pythonPath, [scriptPath, "--preflight"], expect.objectContaining({ encoding: "utf-8" }));
+    });
+    // A server still serving an agent script without --preflight exits on the
+    // missing GATEWAY_URL rather than printing a report.
+    it("reports not-installed when the agent script predates --preflight", () => {
+        const spawn = spawnReturning({ status: 1, stderr: "GATEWAY_URL is required" });
+        expect(runLocalPreflight({ pythonPath, scriptPath, spawn })).toEqual({
+            kind: "not-installed",
+        });
+    });
+    // A crash is not the same as "not set up yet", and doctor must not conflate them.
+    it("reports the failure when the agent runs but cannot answer", () => {
+        expect(runLocalPreflight({
+            pythonPath,
+            scriptPath,
+            spawn: spawnReturning({ status: 1, stderr: "ImportError: no module named mss" }),
+        })).toEqual({ kind: "error", detail: "ImportError: no module named mss" });
+    });
+    it("reports an error when stdout is not a report", () => {
+        for (const stdout of ["boom", "[]", JSON.stringify({ checks: [{ name: "x" }] })]) {
+            expect(runLocalPreflight({ pythonPath, scriptPath, spawn: spawnReturning({ stdout }) })).toEqual({ kind: "error", detail: expect.stringContaining("readable report") });
+        }
+    });
+    it("reports not-installed without spawning when python is missing", () => {
+        const spawn = spawnReturning({ stdout: JSON.stringify(REPORT) });
+        expect(runLocalPreflight({ pythonPath: join(tmpdir(), "no-such-python"), scriptPath, spawn })).toEqual({ kind: "not-installed" });
+        expect(spawn).not.toHaveBeenCalled();
+    });
+});
+describe("formatPreflightLines", () => {
+    it("marks each check and indents its hint", () => {
+        const lines = formatPreflightLines(REPORT);
+        expect(lines[0]).toBe("Desktop environment:");
+        expect(lines[1]).toContain("· capture target: capturing the primary monitor");
+        expect(lines[2]).toContain("✘ accessibility permission: not granted");
+        expect(lines[2]).toContain("→ System Settings");
+    });
+});
+describe("hasBlockingChecks", () => {
+    it("is true only when something warns or fails", () => {
+        expect(hasBlockingChecks(REPORT)).toBe(true);
+        expect(hasBlockingChecks(HEALTHY)).toBe(false);
+    });
+});
+describe("confirmProceed", () => {
+    it("does not ask when every check is fine", async () => {
+        const ask = vi.fn();
+        expect(await confirmProceed(HEALTHY, { interactive: true, ask })).toBe(true);
+        expect(ask).not.toHaveBeenCalled();
+    });
+    it("proceeds on an empty answer", async () => {
+        expect(await confirmProceed(REPORT, { interactive: true, ask: async () => "" })).toBe(true);
+    });
+    it("stops on a declined prompt", async () => {
+        expect(await confirmProceed(REPORT, { interactive: true, ask: async () => "n" })).toBe(false);
+        expect(await confirmProceed(REPORT, { interactive: true, ask: async () => "No" })).toBe(false);
+    });
+    // Headless/CI: nobody can answer, so a prompt would read as a hang.
+    it("never asks without a terminal", async () => {
+        const ask = vi.fn();
+        expect(await confirmProceed(REPORT, { interactive: false, ask })).toBe(true);
+        expect(ask).not.toHaveBeenCalled();
+    });
+});