@autifyhq/aximo-cli 0.8.0 → 0.10.0

package/dist/mobile-control/mjpeg-stream.js

@@ -0,0 +1,160 @@
+import { connect } from "node:net";
+const SOI = Buffer.from([0xff, 0xd8]);
+const EOI = Buffer.from([0xff, 0xd9]);
+// A frame at the pinned capture settings is ~30-80KB; anything near this cap
+// means the parser lost sync or the driver ignored the settings. Dropping the
+// buffer resyncs on the next SOI marker.
+const MAX_PARSER_BUFFER = 8 * 1024 * 1024;
+// No bytes at all for this long means the server is wedged (locked phone with a
+// dead WDA, stale forward) — drop the connection and let the retry loop rebuild.
+const STREAM_IDLE_TIMEOUT_MS = 15_000;
+const MAX_RECONNECT_DELAY_MS = 10_000;
+/**
+ * Incremental JPEG frame extractor for an MJPEG byte stream. Scans raw bytes
+ * for SOI/EOI markers instead of parsing multipart headers — the WDA and
+ * UiAutomator2 servers frame their streams differently, and marker scanning
+ * handles both and resyncs after corruption (HTTP headers and part boundaries
+ * fall out naturally because scanning starts at the first SOI).
+ */
+export class MjpegFrameParser {
+    buffer = Buffer.alloc(0);
+    push(chunk) {
+        this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+        const frames = [];
+        for (;;) {
+            const soi = this.buffer.indexOf(SOI);
+            if (soi === -1) {
+                // Nothing before a frame start is useful; keep one byte in case a
+                // marker straddles the chunk edge.
+                this.buffer = this.buffer.subarray(Math.max(0, this.buffer.length - 1));
+                break;
+            }
+            if (soi > 0)
+                this.buffer = this.buffer.subarray(soi);
+            const eoi = this.buffer.indexOf(EOI, SOI.length);
+            if (eoi === -1)
+                break;
+            frames.push(this.buffer.subarray(0, eoi + EOI.length));
+            this.buffer = this.buffer.subarray(eoi + EOI.length);
+        }
+        if (this.buffer.length > MAX_PARSER_BUFFER)
+            this.buffer = Buffer.alloc(0);
+        return frames;
+    }
+}
+/**
+ * Connects to the driver-forwarded MJPEG port and emits complete JPEG frames.
+ * Reconnects with capped backoff while started — an Appium session rebuild
+ * lands on a fresh port, which `getPort` reflects on the next attempt. All
+ * timers are cancellable so `stop()` never holds the process open.
+ */
+export class MjpegStreamClient {
+    options;
+    active = false;
+    socket = null;
+    attempt = 0;
+    loop = null;
+    wake = null;
+    constructor(options) {
+        this.options = options;
+    }
+    isActive() {
+        return this.active;
+    }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.attempt = 0;
+        this.loop = this.run().catch((err) => {
+            this.options.log?.(`MJPEG capture loop crashed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    async stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.socket?.destroy();
+        this.socket = null;
+        this.wake?.();
+        await this.loop;
+        this.loop = null;
+    }
+    async run() {
+        while (this.active) {
+            try {
+                await this.options.ensureReady();
+                if (!this.active)
+                    break;
+                const port = this.options.getPort();
+                if (!port)
+                    throw new Error("MJPEG server port is not configured");
+                await this.streamOnce(port);
+            }
+            catch (err) {
+                if (this.active) {
+                    this.options.log?.(`MJPEG stream interrupted: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (!this.active)
+                break;
+            const delay = Math.min(1000 * 2 ** this.attempt, MAX_RECONNECT_DELAY_MS);
+            this.attempt += 1;
+            await this.sleep(delay);
+        }
+    }
+    streamOnce(port) {
+        return new Promise((resolve, reject) => {
+            const parser = new MjpegFrameParser();
+            const socket = this.options.createConnection?.(port) ?? connect({ host: "127.0.0.1", port });
+            this.socket = socket;
+            let failed = null;
+            socket.setNoDelay(true);
+            socket.setTimeout(STREAM_IDLE_TIMEOUT_MS, () => {
+                failed = new Error(`no stream data for ${STREAM_IDLE_TIMEOUT_MS}ms`);
+                socket.destroy();
+            });
+            // WDA streams to any TCP client; the UiAutomator2 server wants a request
+            // line first. Sending one is harmless for both.
+            socket.on("connect", () => {
+                socket.write("GET / HTTP/1.0\r\nConnection: keep-alive\r\n\r\n");
+            });
+            socket.on("data", (chunk) => {
+                const frames = parser.push(chunk);
+                if (frames.length === 0)
+                    return;
+                // A delivered frame proves the pipeline works — restart backoff.
+                this.attempt = 0;
+                // Keep-latest: only the newest frame matters for a live view.
+                const latest = frames[frames.length - 1];
+                if (latest)
+                    this.options.onFrame(latest);
+            });
+            socket.on("error", (err) => {
+                failed = failed ?? err;
+            });
+            socket.on("close", () => {
+                if (this.socket === socket)
+                    this.socket = null;
+                if (failed)
+                    reject(failed);
+                else
+                    resolve();
+            });
+        });
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.wake = null;
+                resolve();
+            }, ms);
+            timer.unref?.();
+            this.wake = () => {
+                clearTimeout(timer);
+                this.wake = null;
+                resolve();
+            };
+        });
+    }
+}

package/dist/mobile-control/mjpeg-stream.test.d.ts

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

package/dist/mobile-control/mjpeg-stream.test.js

@@ -0,0 +1,93 @@
+import { createServer } from "node:net";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MjpegFrameParser, MjpegStreamClient } from "./mjpeg-stream.js";
+function jpeg(payload) {
+    return Buffer.from([0xff, 0xd8, ...payload, 0xff, 0xd9]);
+}
+describe("MjpegFrameParser", () => {
+    it("extracts a complete frame from one chunk", () => {
+        const parser = new MjpegFrameParser();
+        const frame = jpeg([1, 2, 3]);
+        expect(parser.push(frame)).toEqual([frame]);
+    });
+    it("reassembles a frame split across chunks", () => {
+        const parser = new MjpegFrameParser();
+        const frame = jpeg([9, 8, 7, 6]);
+        expect(parser.push(frame.subarray(0, 3))).toEqual([]);
+        expect(parser.push(frame.subarray(3))).toEqual([frame]);
+    });
+    it("skips multipart headers and boundary bytes between frames", () => {
+        const parser = new MjpegFrameParser();
+        const a = jpeg([1]);
+        const b = jpeg([2]);
+        const stream = Buffer.concat([
+            Buffer.from("HTTP/1.1 200 OK\r\nContent-Type: multipart/x-mixed-replace\r\n\r\n--BoundaryString\r\n"),
+            a,
+            Buffer.from("\r\n--BoundaryString\r\nContent-Length: 4\r\n\r\n"),
+            b,
+        ]);
+        expect(parser.push(stream)).toEqual([a, b]);
+    });
+    it("keeps a trailing partial marker across pushes", () => {
+        const parser = new MjpegFrameParser();
+        const frame = jpeg([5]);
+        // First push ends exactly on the 0xff of the next frame's SOI.
+        expect(parser.push(Buffer.concat([frame, Buffer.from([0xff])]))).toEqual([frame]);
+        const next = jpeg([6]);
+        expect(parser.push(next.subarray(1))).toEqual([next]);
+    });
+});
+describe("MjpegStreamClient", () => {
+    let server = null;
+    afterEach(() => {
+        server?.close();
+        server = null;
+    });
+    function listen(handler) {
+        return new Promise((resolve) => {
+            const created = createServer((socket) => {
+                socket.on("error", () => { });
+                handler((data) => socket.write(data));
+            });
+            server = created;
+            created.listen(0, "127.0.0.1", () => {
+                resolve(created.address().port);
+            });
+        });
+    }
+    it("delivers frames from the device stream", async () => {
+        const frame = jpeg([1, 2, 3, 4]);
+        const port = await listen((write) => {
+            write(Buffer.from("HTTP/1.1 200 OK\r\n\r\n"));
+            write(frame);
+        });
+        const frames = [];
+        const client = new MjpegStreamClient({
+            ensureReady: async () => { },
+            getPort: () => port,
+            onFrame: (f) => frames.push(f),
+        });
+        client.start();
+        await vi.waitFor(() => expect(frames.length).toBeGreaterThanOrEqual(1));
+        expect(frames[0]?.equals(frame)).toBe(true);
+        await client.stop();
+    });
+    it("stop() resolves promptly and stops reconnect attempts", async () => {
+        let readyCalls = 0;
+        const client = new MjpegStreamClient({
+            ensureReady: async () => {
+                readyCalls += 1;
+                throw new Error("session down");
+            },
+            getPort: () => undefined,
+            onFrame: () => { },
+        });
+        client.start();
+        await vi.waitFor(() => expect(readyCalls).toBeGreaterThanOrEqual(1));
+        await client.stop();
+        const after = readyCalls;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        expect(readyCalls).toBe(after);
+        expect(client.isActive()).toBe(false);
+    });
+});

package/dist/mobile-control/tunnel.d.ts

@@ -9,7 +9,16 @@ export interface RunControlTunnelOptions {
     installApp?: (args: {
         uploadId: string;
     }) => Promise<void>;
+    /**
+     * Live-view MJPEG pipeline hooks. The gateway demand-gates capture:
+     * `stream_start` when a viewer is watching, `stream_stop` when idle. Capture
+     * must also stop on release/disconnect so an unwatched phone never streams.
+     */
+    stream?: {
+        start: () => void;
+        stop: () => void;
+    };
     connect?: (wsUrl: string, deviceToken: string) => Socket;
 }
-export declare function registerHandlers(socket: Socket, controller: MobileController, installApp?: RunControlTunnelOptions["installApp"]): void;
+export declare function registerHandlers(socket: Socket, controller: MobileController, installApp?: RunControlTunnelOptions["installApp"], stream?: RunControlTunnelOptions["stream"]): void;
 export declare function runControlTunnel(options: RunControlTunnelOptions): Promise<void>;

package/dist/mobile-control/tunnel.js

@@ -52,7 +52,7 @@ function defaultConnect(wsUrl, deviceToken) {
 // Mirrors the gateway's lock lease: a session quiet for longer than this has lost
 // its server-side lock, so a new session id is a legitimate takeover, not a stray.
 const SESSION_LEASE_MS = 25 * 60 * 1000;
-export function registerHandlers(socket, controller, installApp) {
+export function registerHandlers(socket, controller, installApp, stream) {
     // Device-side guard against interleaved sessions: the gateway announces owner
     // changes (session_acquired/session_released) and tags each command with its
     // session id, so commands from a session that no longer owns the device are
@@ -70,8 +70,22 @@ export function registerHandlers(socket, controller, installApp) {
         const sessionId = args?.sessionId;
         if (activeSession && activeSession.id === sessionId) {
             activeSession = null;
+            // No owning session -> nobody may watch the phone.
+            stream?.stop();
         }
     });
+    // Demand gating: the gateway asks for frames only while a session owns the
+    // device AND at least one viewer is reading them; it signals idle explicitly
+    // (and the frame acks carry the same signal as a backstop). The device-side
+    // owner check mirrors the command guard: a stray start from a gateway
+    // instance with stale state must not stream an idle phone. A start dropped
+    // here self-heals — the gateway re-signals while viewers keep reading, and
+    // the owner becomes known on session_acquired or the next tagged command.
+    socket.on("stream_start", () => {
+        if (activeSession)
+            stream?.start();
+    });
+    socket.on("stream_stop", () => stream?.stop());
     const on = (event, handler) => {
         socket.on(event, (rawArgs, ack) => {
             // Destructure the routing-only tag off a clone so the caller's payload
@@ -130,6 +144,29 @@ export function registerHandlers(socket, controller, installApp) {
         await controller.swipe(r.coords[0], r.coords[1], r.coords[2], r.coords[3], num(args["duration"], 300));
         return ok();
     });
+    on("pinch_zoom", async (args) => {
+        const r = requireCoords(args, ["x", "y"]);
+        if ("error" in r)
+            return { ok: false, error: `pinch_zoom ${r.error}` };
+        const scale = reqNum(args, "scale");
+        if (scale === null)
+            return { ok: false, error: "pinch_zoom requires a numeric scale" };
+        await controller.pinchZoom(r.coords[0], r.coords[1], scale, num(args["duration"], 600));
+        return ok();
+    });
+    on("rotate_device", async (args) => {
+        const orientation = String(args["orientation"] ?? "").toLowerCase();
+        if (orientation !== "portrait" && orientation !== "landscape") {
+            return { ok: false, error: 'rotate_device requires orientation "portrait" or "landscape"' };
+        }
+        return asActionResult(await controller.rotateDevice(orientation));
+    });
+    on("set_location", async (args) => {
+        const r = requireCoords(args, ["latitude", "longitude"]);
+        if ("error" in r)
+            return { ok: false, error: `set_location ${r.error}` };
+        return asActionResult(await controller.setLocation(r.coords[0], r.coords[1], num(args["altitude"], 0)));
+    });
     on("input", async (args) => asActionResult(await controller.typeText(String(args["text"] ?? ""))));
     on("key", async (args) => asActionResult(await controller.pressKey(String(args["key"] ?? ""))));
     on("launch_app", async (args) => asActionResult(await controller.launchApp(String(args["app"] ?? ""))));
@@ -149,7 +186,7 @@ export function registerHandlers(socket, controller, installApp) {
 export async function runControlTunnel(options) {
     const connect = options.connect ?? defaultConnect;
     const socket = connect(options.wsUrl, options.deviceToken);
-    registerHandlers(socket, options.controller, options.installApp);
+    registerHandlers(socket, options.controller, options.installApp, options.stream);
     await new Promise((resolve, reject) => {
         let shuttingDown = false;
         let serverKicks = [];
@@ -157,6 +194,7 @@ export async function runControlTunnel(options) {
             if (shuttingDown)
                 return;
             shuttingDown = true;
+            options.stream?.stop();
             socket.close();
             resolve();
         };
@@ -188,6 +226,9 @@ export async function runControlTunnel(options) {
             console.error(`Connection error: ${err.message}`);
         });
         socket.on("disconnect", (reason) => {
+            // Whatever the reason, a disconnected tunnel means no viewer can be
+            // watching — stop capture; a reconnect re-arms via stream_start.
+            options.stream?.stop();
             // A SIGINT/SIGTERM teardown closes the socket itself; cleanup() already
             // resolved the promise, so don't report our own close as an error.
             if (shuttingDown)

package/dist/mobile-control/tunnel.test.js

@@ -20,12 +20,15 @@ function stubController(overrides = {}) {
         doubleTap: vi.fn(async () => { }),
         longPress: vi.fn(async () => { }),
         swipe: vi.fn(async () => { }),
+        pinchZoom: vi.fn(async () => { }),
         typeText: vi.fn(async () => ({ ok: true })),
         pressKey: vi.fn(async () => ({ ok: true })),
         launchApp: vi.fn(async () => ({ ok: true })),
         findElement: vi.fn(async () => ({ ok: true })),
         clearText: vi.fn(async () => ({ ok: true })),
         hideKeyboard: vi.fn(async () => ({ ok: true })),
+        rotateDevice: vi.fn(async () => ({ ok: true })),
+        setLocation: vi.fn(async () => ({ ok: true })),
         close: vi.fn(async () => { }),
     };
     return { ...base, ...overrides };
@@ -116,6 +119,78 @@ describe("registerHandlers", () => {
             error: "no focused field",
         });
     });
+    it("pinch_zoom forwards center, scale, and duration", async () => {
+        const pinchZoom = vi.fn(async () => { });
+        const socket = wire(stubController({ pinchZoom }));
+        await expect(socket.emit("pinch_zoom", { x: 100, y: 200, scale: 2, duration: 800 })).resolves.toEqual({
+            ok: true,
+        });
+        expect(pinchZoom).toHaveBeenCalledWith(100, 200, 2, 800);
+    });
+    it("pinch_zoom defaults duration to 600ms", async () => {
+        const pinchZoom = vi.fn(async () => { });
+        const socket = wire(stubController({ pinchZoom }));
+        await socket.emit("pinch_zoom", { x: 1, y: 2, scale: 0.5 });
+        expect(pinchZoom).toHaveBeenCalledWith(1, 2, 0.5, 600);
+    });
+    it("pinch_zoom rejects a missing scale without calling the controller", async () => {
+        const pinchZoom = vi.fn(async () => { });
+        const socket = wire(stubController({ pinchZoom }));
+        await expect(socket.emit("pinch_zoom", { x: 1, y: 2 })).resolves.toEqual({
+            ok: false,
+            error: "pinch_zoom requires a numeric scale",
+        });
+        expect(pinchZoom).not.toHaveBeenCalled();
+    });
+    it("pinch_zoom rejects missing coordinates", async () => {
+        const pinchZoom = vi.fn(async () => { });
+        const socket = wire(stubController({ pinchZoom }));
+        await expect(socket.emit("pinch_zoom", { scale: 2 })).resolves.toEqual({
+            ok: false,
+            error: "pinch_zoom requires numeric coordinates",
+        });
+        expect(pinchZoom).not.toHaveBeenCalled();
+    });
+    it("rotate_device forwards a valid orientation", async () => {
+        const rotateDevice = vi.fn(async () => ({ ok: true }));
+        const socket = wire(stubController({ rotateDevice }));
+        await expect(socket.emit("rotate_device", { orientation: "landscape" })).resolves.toEqual({
+            ok: true,
+        });
+        expect(rotateDevice).toHaveBeenCalledWith("landscape");
+    });
+    it("rotate_device rejects an invalid orientation without calling the controller", async () => {
+        const rotateDevice = vi.fn(async () => ({ ok: true }));
+        const socket = wire(stubController({ rotateDevice }));
+        await expect(socket.emit("rotate_device", { orientation: "sideways" })).resolves.toEqual({
+            ok: false,
+            error: 'rotate_device requires orientation "portrait" or "landscape"',
+        });
+        expect(rotateDevice).not.toHaveBeenCalled();
+    });
+    it("set_location forwards coordinates with altitude defaulting to 0", async () => {
+        const setLocation = vi.fn(async () => ({ ok: true }));
+        const socket = wire(stubController({ setLocation }));
+        await expect(socket.emit("set_location", { latitude: 35.68, longitude: 139.69 })).resolves.toEqual({
+            ok: true,
+        });
+        expect(setLocation).toHaveBeenCalledWith(35.68, 139.69, 0);
+    });
+    it("set_location rejects a non-numeric latitude without calling the controller", async () => {
+        const setLocation = vi.fn(async () => ({ ok: true }));
+        const socket = wire(stubController({ setLocation }));
+        await expect(socket.emit("set_location", { latitude: "35", longitude: 139.69 })).resolves.toEqual({
+            ok: false,
+            error: "set_location requires numeric coordinates",
+        });
+        expect(setLocation).not.toHaveBeenCalled();
+    });
+    it("set_location acks the structured failure from the controller", async () => {
+        const setLocation = vi.fn(async () => ({ ok: false, error: "mock location not allowed" }));
+        const socket = wire(stubController({ setLocation }));
+        await expect(socket.emit("set_location", { latitude: 1, longitude: 2, altitude: 30 })).resolves.toEqual({ ok: false, error: "mock location not allowed" });
+        expect(setLocation).toHaveBeenCalledWith(1, 2, 30);
+    });
     it("hide_keyboard acks ok", async () => {
         const hideKeyboard = vi.fn(async () => ({ ok: true }));
         const socket = wire(stubController({ hideKeyboard }));
@@ -235,3 +310,36 @@ describe("registerHandlers session guard", () => {
         expect(tap).toHaveBeenCalledTimes(2);
     });
 });
+describe("stream lifecycle handlers", () => {
+    function wireWithStream() {
+        const socket = new FakeSocket();
+        const stream = { start: vi.fn(), stop: vi.fn() };
+        registerHandlers(socket, stubController(), undefined, stream);
+        return { socket, stream };
+    }
+    it("starts and stops capture on gateway demand signals while a session owns the device", () => {
+        const { socket, stream } = wireWithStream();
+        socket.handlers.get("session_acquired")?.({ sessionId: "s1" }, undefined);
+        socket.handlers.get("stream_start")?.({}, undefined);
+        expect(stream.start).toHaveBeenCalledTimes(1);
+        socket.handlers.get("stream_stop")?.({}, undefined);
+        expect(stream.stop).toHaveBeenCalledTimes(1);
+    });
+    it("drops stream_start when no session owns the device", () => {
+        const { socket, stream } = wireWithStream();
+        socket.handlers.get("stream_start")?.({}, undefined);
+        expect(stream.start).not.toHaveBeenCalled();
+    });
+    it("stops capture when the owning session releases the device", () => {
+        const { socket, stream } = wireWithStream();
+        socket.handlers.get("session_acquired")?.({ sessionId: "s1" }, undefined);
+        socket.handlers.get("session_released")?.({ sessionId: "s1" }, undefined);
+        expect(stream.stop).toHaveBeenCalledTimes(1);
+    });
+    it("ignores a release from a session that does not own the device", () => {
+        const { socket, stream } = wireWithStream();
+        socket.handlers.get("session_acquired")?.({ sessionId: "s1" }, undefined);
+        socket.handlers.get("session_released")?.({ sessionId: "other" }, undefined);
+        expect(stream.stop).not.toHaveBeenCalled();
+    });
+});

package/dist/mobile-control/webdriver.d.ts

@@ -18,6 +18,12 @@ export declare class WebDriverSession {
     private requireId;
     screenshot(): Promise<Buffer>;
     windowRect(): Promise<WindowRect>;
+    setOrientation(orientation: "PORTRAIT" | "LANDSCAPE"): Promise<void>;
+    setGeoLocation(location: {
+        latitude: number;
+        longitude: number;
+        altitude: number;
+    }): Promise<void>;
     performActions(actions: unknown[]): Promise<void>;
     releaseActions(): Promise<void>;
     getActiveElement(): Promise<string | null>;
@@ -25,7 +31,9 @@ export declare class WebDriverSession {
     elementClick(elementRef: string): Promise<void>;
     elementClear(elementRef: string): Promise<void>;
     elementSendKeys(elementRef: string, text: string): Promise<void>;
+    elementDisplayed(elementRef: string): Promise<boolean>;
     execute(script: string, args?: unknown[]): Promise<unknown>;
-    setValueOnActiveElement(text: string): Promise<void>;
+    /** Appium extension endpoint: update driver settings for the current session. */
+    updateSettings(settings: Record<string, unknown>): Promise<void>;
 }
 export declare const ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";

package/dist/mobile-control/webdriver.js

@@ -84,6 +84,14 @@ export class WebDriverSession {
             y: Number(value?.y ?? 0),
         };
     }
+    async setOrientation(orientation) {
+        await this.transport.request("POST", `/session/${this.requireId()}/orientation`, {
+            orientation,
+        });
+    }
+    async setGeoLocation(location) {
+        await this.transport.request("POST", `/session/${this.requireId()}/location`, { location });
+    }
     async performActions(actions) {
         await this.transport.request("POST", `/session/${this.requireId()}/actions`, { actions });
     }
@@ -110,17 +118,21 @@ export class WebDriverSession {
     async elementSendKeys(elementRef, text) {
         await this.transport.request("POST", `/session/${this.requireId()}/element/${elementRef}/value`, { text, value: [...text] });
     }
+    async elementDisplayed(elementRef) {
+        const value = await this.transport.request("GET", `/session/${this.requireId()}/element/${elementRef}/displayed`);
+        return value === true;
+    }
     async execute(script, args = []) {
         return this.transport.request("POST", `/session/${this.requireId()}/execute/sync`, {
             script,
             args,
         });
     }
-    async setValueOnActiveElement(text) {
-        const active = await this.getActiveElement();
-        if (!active)
-            throw new Error("No active element to receive text");
-        await this.elementSendKeys(active, text);
+    /** Appium extension endpoint: update driver settings for the current session. */
+    async updateSettings(settings) {
+        await this.transport.request("POST", `/session/${this.requireId()}/appium/settings`, {
+            settings,
+        });
     }
 }
 export const ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";

package/dist/mutate.d.ts

@@ -5,7 +5,7 @@ export interface DryRunResult {
     url: string;
     body?: unknown;
 }
-export declare function dryRunEnvelope(method: string, path: string, body?: unknown): SuccessEnvelope<DryRunResult>;
+export declare function dryRunEnvelope(method: string, pathOrUrl: string, body?: unknown): SuccessEnvelope<DryRunResult>;
 export declare function resolveJsonOverride(jsonFlag: unknown): {
     body: Record<string, unknown>;
 } | {

package/dist/mutate.js

@@ -1,8 +1,10 @@
 import { formatError, formatSuccess, validationError } from "./output.js";
 import { parseJsonBody, JsonBodyError, OPENAPI_URL } from "./validate.js";
 import { getBaseUrl } from "./client.js";
-export function dryRunEnvelope(method, path, body) {
-    const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+export function dryRunEnvelope(method, pathOrUrl, body) {
+    const url = /^https?:\/\//.test(pathOrUrl)
+        ? pathOrUrl
+        : `${getBaseUrl()}${pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`}`;
     const data = { dryRun: true, method, url };
     if (body !== undefined)
         data.body = body;

package/dist/prompt.d.ts

@@ -0,0 +1,11 @@
+export interface ConfirmOptions {
+    /** Whether a human can answer; defaults to stdin being a TTY. */
+    interactive?: boolean;
+    ask?: (question: string) => Promise<string>;
+}
+/**
+ * Yes-by-default confirmation. Enter proceeds; only an explicit n/no declines.
+ * Unattended callers (no TTY) proceed without asking, so CI and daemonized
+ * devices keep working instead of hanging on a prompt nobody can see.
+ */
+export declare function confirmYesNo(question: string, options?: ConfirmOptions): Promise<boolean>;

package/dist/prompt.js

@@ -0,0 +1,19 @@
+import { createInterface } from "node:readline/promises";
+function defaultAsk(question) {
+    // stderr, so prompts never contaminate the JSON envelope on stdout.
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return rl.question(question).finally(() => rl.close());
+}
+/**
+ * Yes-by-default confirmation. Enter proceeds; only an explicit n/no declines.
+ * Unattended callers (no TTY) proceed without asking, so CI and daemonized
+ * devices keep working instead of hanging on a prompt nobody can see.
+ */
+export async function confirmYesNo(question, options = {}) {
+    const interactive = options.interactive ?? process.stdin.isTTY === true;
+    if (!interactive)
+        return true;
+    const ask = options.ask ?? defaultAsk;
+    const answer = (await ask(`${question} [Y/n] `)).trim().toLowerCase();
+    return answer !== "n" && answer !== "no";
+}