@shipvo/cli 0.1.4 → 0.1.6

package/dist/run-net.d.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const NET_PATH = "/__shipvo/net";
+export type NetProfile = {
+    latencyMs: number;
+    downKbps: number;
+    failureRate: number;
+};
+export type NetRecord = {
+    at: number;
+    session: string;
+    method: string;
+    host: string;
+    status: number;
+    ms: number;
+    profile: string;
+    error?: string;
+};
+/** One cookie jar per phone session, like the cookies of one installed app. */
+export declare class CookieJar {
+    private list;
+    set(url: URL, header: string, now?: number): void;
+    header(url: URL, now?: number): string;
+}
+/** The profile table from @shipvo/sim (one source of truth); a built-in copy if that file cannot be loaded. */
+export declare function loadProfiles(): Promise<Record<string, NetProfile>>;
+export type NetProxy = {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    log: NetRecord[];
+};
+/** The request handler for `NET_PATH`. `tokens` are the credentials it accepts; `port()` is the bound port. */
+export declare function createNetProxy(o: {
+    tokens: string[];
+    port: () => number;
+    profiles: Record<string, NetProfile>;
+    onRecord?: (r: NetRecord) => void;
+    fetchImpl?: typeof fetch;
+}): NetProxy;
+/** The script that runs inside the app's page: sends cross-origin fetch and XMLHttpRequest through `NET_PATH`. */
+export declare function netClientSource(): string;

package/dist/run-net.js

@@ -0,0 +1,266 @@
+import { createRequire } from "node:module";
+import { hostAllowed, isLoopback, originAllowed, tokenMatches } from "./run-protocol.js";
+export const NET_PATH = "/__shipvo/net";
+/** One cookie jar per phone session, like the cookies of one installed app. */
+export class CookieJar {
+    list = [];
+    set(url, header, now = Date.now()) {
+        const [pair, ...attrs] = header.split(";").map((x) => x.trim());
+        const eq = pair.indexOf("=");
+        if (eq < 1)
+            return;
+        const c = { name: pair.slice(0, eq), value: pair.slice(eq + 1), domain: url.hostname, hostOnly: true, path: defaultPath(url.pathname), secure: false };
+        for (const a of attrs) {
+            const i = a.indexOf("=");
+            const k = (i < 0 ? a : a.slice(0, i)).toLowerCase();
+            const v = i < 0 ? "" : a.slice(i + 1);
+            if (k === "domain" && v) {
+                c.domain = v.replace(/^\./, "").toLowerCase();
+                c.hostOnly = false;
+            }
+            else if (k === "path" && v.startsWith("/"))
+                c.path = v;
+            else if (k === "secure")
+                c.secure = true;
+            else if (k === "expires" && c.expires === undefined) {
+                const t = Date.parse(v);
+                if (!Number.isNaN(t))
+                    c.expires = t;
+            }
+            else if (k === "max-age" && /^-?\d+$/.test(v))
+                c.expires = now + Number(v) * 1000;
+        }
+        if (!c.hostOnly && !(url.hostname === c.domain || url.hostname.endsWith("." + c.domain)))
+            return;
+        this.list = this.list.filter((o) => !(o.name === c.name && o.domain === c.domain && o.path === c.path));
+        if (c.expires === undefined || c.expires > now)
+            this.list.push(c);
+    }
+    header(url, now = Date.now()) {
+        this.list = this.list.filter((c) => c.expires === undefined || c.expires > now);
+        return this.list
+            .filter((c) => (c.hostOnly ? url.hostname === c.domain : url.hostname === c.domain || url.hostname.endsWith("." + c.domain)) && url.pathname.startsWith(c.path) && (!c.secure || url.protocol === "https:"))
+            .sort((a, b) => b.path.length - a.path.length)
+            .map((c) => `${c.name}=${c.value}`).join("; ");
+    }
+}
+const defaultPath = (p) => { const i = p.lastIndexOf("/"); return i <= 0 ? "/" : p.slice(0, i); };
+const FALLBACK = {
+    online: { latencyMs: 0, downKbps: Infinity, failureRate: 0 }, offline: { latencyMs: 0, downKbps: 0, failureRate: 1 },
+    "2g": { latencyMs: 800, downKbps: 50, failureRate: 0.02 }, "3g": { latencyMs: 300, downKbps: 750, failureRate: 0.01 },
+    "slow-4g": { latencyMs: 150, downKbps: 1600, failureRate: 0 }, spotty: { latencyMs: 400, downKbps: 500, failureRate: 0.3 },
+    "low-end-4g": { latencyMs: 100, downKbps: 6300, failureRate: 0.005 },
+};
+/** The profile table from @shipvo/sim (one source of truth); a built-in copy if that file cannot be loaded. */
+export async function loadProfiles() {
+    try {
+        const file = createRequire(import.meta.url).resolve("@shipvo/sim/network-profiles.mjs");
+        const mod = await import(new URL(`file://${file.startsWith("/") ? "" : "/"}${file.replace(/\\/g, "/")}`).href);
+        return mod.PROFILES;
+    }
+    catch {
+        return FALLBACK;
+    }
+}
+const HOP = new Set(["connection", "keep-alive", "transfer-encoding", "upgrade", "proxy-connection", "te", "trailer", "content-length", "content-encoding", "set-cookie", "host"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const readBody = (req) => new Promise((ok, fail) => { const b = []; req.on("data", (c) => b.push(c)); req.on("end", () => ok(Buffer.concat(b))); req.on("error", fail); });
+const hostOf = (u) => u.host;
+/** The request handler for `NET_PATH`. `tokens` are the credentials it accepts; `port()` is the bound port. */
+export function createNetProxy(o) {
+    const jars = new Map();
+    const log = [];
+    const doFetch = o.fetchImpl ?? fetch;
+    let draw = 1;
+    const random = () => { draw = (Math.imul(draw, 1664525) + 1013904223) >>> 0; return draw / 4294967296; };
+    const refuse = (res, code, msg) => { res.writeHead(code, { "content-type": "text/plain" }); res.end(msg); };
+    async function handle(req, res) {
+        const port = o.port();
+        if (!isLoopback(req.socket.remoteAddress) || !hostAllowed(req.headers.host, port) || req.headers.origin === undefined || !originAllowed(req.headers.origin, port))
+            return refuse(res, 403, "Forbidden");
+        const given = req.headers["x-shipvo-token"];
+        if (typeof given !== "string" || !o.tokens.some((t) => tokenMatches(given, t)))
+            return refuse(res, 401, "Unauthorized");
+        if (req.method !== "POST")
+            return refuse(res, 405, "Use POST");
+        let spec;
+        try {
+            spec = JSON.parse(decodeURIComponent(String(req.headers["x-shipvo-req"])));
+            new URL(spec.url);
+        }
+        catch {
+            return refuse(res, 400, "Bad request description");
+        }
+        const url = new URL(spec.url);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return refuse(res, 400, "Only http and https");
+        const session = String(req.headers["x-shipvo-session"] ?? "default").slice(0, 64);
+        const profileName = String(req.headers["x-shipvo-profile"] ?? "online");
+        const profile = o.profiles[profileName] ?? o.profiles.online;
+        const method = String(spec.method || "GET").toUpperCase();
+        const started = Date.now();
+        const record = (status, error) => { const r = { at: started, session, method, host: hostOf(url), status, ms: Date.now() - started, profile: profileName, ...(error ? { error } : {}) }; log.push(r); o.onRecord?.(r); };
+        const body = await readBody(req);
+        const failed = profile.failureRate >= 1 || random() < profile.failureRate;
+        const bytesMs = (n) => (n && Number.isFinite(profile.downKbps) && profile.downKbps > 0 ? (n * 8) / profile.downKbps : 0);
+        await sleep(profile.latencyMs + bytesMs(body.length));
+        // XMLHttpRequest cannot tell a 599 from a reply, so drop the connection and let the browser raise its own `error` event.
+        const dropForXhr = () => { if (req.headers["x-shipvo-xhr"]) {
+            req.socket.destroy();
+            return true;
+        } return false; };
+        if (failed) {
+            record(599, "network request failed");
+            if (dropForXhr())
+                return;
+            res.writeHead(599, { "x-shipvo-net-error": "1", "content-type": "text/plain" });
+            return void res.end("network request failed");
+        }
+        let jar = jars.get(session);
+        if (!jar)
+            jars.set(session, jar = new CookieJar());
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(spec.headers ?? {}))
+            if (!HOP.has(k.toLowerCase()) && !["cookie", "origin", "referer"].includes(k.toLowerCase()))
+                headers.set(k, v);
+        let up;
+        let cur = url;
+        let curMethod = method;
+        let curBody = method === "GET" || method === "HEAD" || body.length === 0 ? undefined : new Uint8Array(body);
+        try {
+            // Redirects are followed here so each hop's Set-Cookie reaches the jar and its cookies go out on the next hop.
+            for (let hop = 0;; hop++) {
+                const h = new Headers(headers);
+                h.delete("cookie");
+                const c = jar.header(cur);
+                if (c)
+                    h.set("cookie", c);
+                up = await doFetch(cur, { method: curMethod, headers: h, body: curBody, redirect: "manual" });
+                for (const sc of up.headers.getSetCookie())
+                    jar.set(cur, sc);
+                const loc = up.headers.get("location");
+                if (![301, 302, 303, 307, 308].includes(up.status) || !loc)
+                    break;
+                if (hop >= 20)
+                    throw new Error("too many redirects");
+                const next = new URL(loc, cur);
+                if (next.protocol !== "http:" && next.protocol !== "https:")
+                    throw new Error("redirect to an unsupported address");
+                void up.body?.cancel().catch(() => { });
+                if (next.origin !== cur.origin)
+                    headers.delete("authorization");
+                if (up.status === 303 ? curMethod !== "HEAD" : (up.status === 301 || up.status === 302) && curMethod === "POST") {
+                    curMethod = "GET";
+                    curBody = undefined;
+                }
+                cur = next;
+            }
+        }
+        catch (e) {
+            record(599, e.message);
+            if (dropForXhr())
+                return;
+            res.writeHead(599, { "x-shipvo-net-error": "1", "content-type": "text/plain" });
+            return void res.end(`network request failed: ${e.message}`);
+        }
+        const out = { "x-shipvo-final-url": cur.href, "cache-control": "no-store" };
+        up.headers.forEach((v, k) => { if (!HOP.has(k))
+            out[k] = v; });
+        res.writeHead(up.status, out);
+        record(up.status);
+        if (!up.body || method === "HEAD")
+            return void res.end();
+        res.on("close", () => { void up.body?.cancel().catch(() => { }); });
+        const reader = up.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const wait = bytesMs(value.length);
+            if (wait > 0)
+                await sleep(wait);
+            if (!res.write(value))
+                await new Promise((r) => res.once("drain", r));
+        }
+        res.end();
+    }
+    return { handle: (req, res) => handle(req, res).catch(() => { if (!res.headersSent)
+            refuse(res, 500, "Proxy error");
+        else
+            res.destroy(); }), log };
+}
+/** The script that runs inside the app's page: sends cross-origin fetch and XMLHttpRequest through `NET_PATH`. */
+export function netClientSource() { return `(${netClientMain.toString()})`; }
+function netClientMain(win, cfg) {
+    const origin = win.location.origin;
+    const abs = (u) => new win.URL(u, win.location.href);
+    const proxied = (u) => { try {
+        const x = abs(String(u));
+        return (x.protocol === "http:" || x.protocol === "https:") && x.origin !== origin ? x : null;
+    }
+    catch {
+        return null;
+    } };
+    const meta = (url, method, headers) => ({
+        "x-shipvo-token": cfg.token, "x-shipvo-session": cfg.session, "x-shipvo-profile": cfg.profile(),
+        "x-shipvo-req": encodeURIComponent(JSON.stringify({ url: url.href, method, headers })),
+    });
+    const origFetch = win.fetch.bind(win);
+    win.fetch = async function (input, init) {
+        const isReq = input instanceof win.Request;
+        // Decide before building a Request: building one from a Request with a body would use up the original.
+        if (!proxied(isReq ? input.url : input))
+            return origFetch(input, init);
+        const req = new win.Request(input, init);
+        const url = proxied(req.url);
+        if (!url)
+            return origFetch(input, init);
+        const t0 = Date.now();
+        const headers = {};
+        req.headers.forEach((v, k) => { headers[k] = v; });
+        const fail = () => { cfg.log({ method: req.method, host: url.host, status: 0, ms: Date.now() - t0 }); throw new TypeError("Network request failed"); };
+        if (!cfg.online())
+            fail();
+        const body = req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
+        let res;
+        try {
+            res = await origFetch("/__shipvo/net", { method: "POST", headers: meta(url, req.method, headers), body, signal: req.signal, cache: "no-store" });
+        }
+        catch {
+            fail();
+        }
+        if (res.headers.get("x-shipvo-net-error"))
+            fail();
+        cfg.log({ method: req.method, host: url.host, status: res.status, ms: Date.now() - t0 });
+        return res;
+    };
+    const X = win.XMLHttpRequest;
+    if (X) {
+        const open = X.prototype.open, send = X.prototype.send, setH = X.prototype.setRequestHeader;
+        X.prototype.open = function (method, u, ...rest) {
+            const url = proxied(u);
+            this.__net = url ? { url, method: String(method).toUpperCase(), headers: {} } : undefined;
+            return this.__net ? open.call(this, "POST", "/__shipvo/net", ...rest) : open.call(this, method, u, ...rest);
+        };
+        X.prototype.setRequestHeader = function (k, v) { if (this.__net) {
+            this.__net.headers[k] = v;
+            return;
+        } return setH.call(this, k, v); };
+        X.prototype.send = function (body) {
+            const n = this.__net;
+            if (!n)
+                return send.call(this, body);
+            const t0 = Date.now();
+            if (!cfg.online()) {
+                cfg.log({ method: n.method, host: n.url.host, status: 0, ms: 0 });
+                win.setTimeout(() => { this.dispatchEvent(new win.ProgressEvent("error")); }, 0);
+                return;
+            }
+            const m = { ...meta(n.url, n.method, n.headers), "x-shipvo-xhr": "1" };
+            for (const k of Object.keys(m))
+                setH.call(this, k, m[k]);
+            this.addEventListener("loadend", () => cfg.log({ method: n.method, host: n.url.host, status: this.status, ms: Date.now() - t0 }));
+            return send.call(this, n.method === "GET" || n.method === "HEAD" ? null : body);
+        };
+    }
+}

package/dist/run-protocol.d.ts

@@ -0,0 +1,32 @@
+export declare const AGENT_PATH = "/__shipvo/agent";
+export type AgentRole = "screen" | "driver";
+/** Contents of `.shipvo/run.json` while `shipvo run` is up. */
+export type RunInfo = {
+    port: number;
+    platform: "android" | "ios";
+    app: string;
+    token: string;
+    pid: number;
+};
+/** Driver to screen: ask the page to do something. `id` pairs the reply with the request. */
+export type DriverMessage = {
+    id: number;
+    type: string;
+    [key: string]: unknown;
+};
+/** Screen to driver: the reply to `id`, or an event the page pushes on its own (no `id`). */
+export type ScreenMessage = {
+    id?: number;
+    type: string;
+    ok?: boolean;
+    error?: string;
+    [key: string]: unknown;
+};
+export type AgentMessage = DriverMessage | ScreenMessage;
+export declare const isAgentRole: (v: string | null) => v is AgentRole;
+export declare function isLoopback(addr: string | undefined): boolean;
+/** True when the `Host` header names this server on loopback. Blocks DNS rebinding. */
+export declare function hostAllowed(host: string | undefined, port: number): boolean;
+/** True when there is no `Origin` (not a browser) or it is this server's own origin. */
+export declare function originAllowed(origin: string | undefined, port: number): boolean;
+export declare function tokenMatches(given: string | null, token: string): boolean;

package/dist/run-protocol.js

@@ -0,0 +1,22 @@
+// Messages on the `shipvo run` agent channel (`/__shipvo/agent`). The host only relays them between the
+// `screen` (the browser tab) and the `driver` (the agent). Slices 2 and 3 of #448 build on these types.
+import { timingSafeEqual } from "node:crypto";
+export const AGENT_PATH = "/__shipvo/agent";
+export const isAgentRole = (v) => v === "screen" || v === "driver";
+export function isLoopback(addr) {
+    return addr === "127.0.0.1" || addr === "::1" || (addr?.startsWith("::ffff:127.") ?? false);
+}
+/** True when the `Host` header names this server on loopback. Blocks DNS rebinding. */
+export function hostAllowed(host, port) {
+    return host === `127.0.0.1:${port}` || host === `localhost:${port}`;
+}
+/** True when there is no `Origin` (not a browser) or it is this server's own origin. */
+export function originAllowed(origin, port) {
+    return origin === undefined || origin === `http://127.0.0.1:${port}` || origin === `http://localhost:${port}`;
+}
+export function tokenMatches(given, token) {
+    if (!given)
+        return false;
+    const a = Buffer.from(given), b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/run-ws.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+export type Peer = {
+    send(text: string): void;
+    close(): void;
+};
+/** Completes the handshake and returns a peer. `onText` gets each complete text message; `onClose` fires once. */
+export declare function acceptWebSocket(req: IncomingMessage, socket: Duplex, onText: (t: string) => void, onClose: () => void): Peer | undefined;

package/dist/run-ws.js

@@ -0,0 +1,89 @@
+// A small server-side WebSocket (RFC 6455) on `node:http` upgrade, enough for JSON text messages.
+import { createHash } from "node:crypto";
+const MAX = 1 << 20;
+function frame(op, payload) {
+    const n = payload.length;
+    const head = n < 126 ? Buffer.from([0x80 | op, n]) : n < 65536 ? Buffer.from([0x80 | op, 126, n >> 8, n & 255]) : (() => {
+        const h = Buffer.alloc(10);
+        h[0] = 0x80 | op;
+        h[1] = 127;
+        h.writeBigUInt64BE(BigInt(n), 2);
+        return h;
+    })();
+    return Buffer.concat([head, payload]);
+}
+/** Completes the handshake and returns a peer. `onText` gets each complete text message; `onClose` fires once. */
+export function acceptWebSocket(req, socket, onText, onClose) {
+    const key = req.headers["sec-websocket-key"];
+    if (typeof key !== "string" || req.headers.upgrade?.toLowerCase() !== "websocket") {
+        socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n");
+        return undefined;
+    }
+    const accept = createHash("sha1").update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").digest("base64");
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    let buf = Buffer.alloc(0);
+    let parts = [];
+    let closed = false;
+    const done = () => { if (!closed) {
+        closed = true;
+        onClose();
+    } };
+    const shut = () => { if (!closed)
+        socket.write(frame(8, Buffer.alloc(0))); socket.end(); done(); };
+    socket.on("close", done);
+    socket.on("error", () => { socket.destroy(); done(); });
+    socket.on("data", (chunk) => {
+        buf = Buffer.concat([buf, chunk]);
+        for (;;) {
+            if (buf.length < 2)
+                return;
+            const op = buf[0] & 15, fin = (buf[0] & 128) !== 0, masked = (buf[1] & 128) !== 0;
+            let len = buf[1] & 127, off = 2;
+            if (len === 126) {
+                if (buf.length < 4)
+                    return;
+                len = buf.readUInt16BE(2);
+                off = 4;
+            }
+            else if (len === 127) {
+                if (buf.length < 10)
+                    return;
+                const big = buf.readBigUInt64BE(2);
+                if (big > BigInt(MAX))
+                    return shut();
+                len = Number(big);
+                off = 10;
+            }
+            if (!masked || len > MAX)
+                return shut(); // clients must mask
+            if (buf.length < off + 4 + len)
+                return;
+            const mask = buf.subarray(off, off + 4);
+            const data = Buffer.from(buf.subarray(off + 4, off + 4 + len));
+            for (let i = 0; i < len; i++)
+                data[i] ^= mask[i & 3];
+            buf = buf.subarray(off + 4 + len);
+            if (op === 8)
+                return shut();
+            if (op === 9) {
+                socket.write(frame(10, data));
+                continue;
+            }
+            if (op === 10)
+                continue;
+            if (op === 1 || op === 2 || op === 0) {
+                parts.push(data);
+                if (parts.reduce((s, p) => s + p.length, 0) > MAX)
+                    return shut();
+                if (fin) {
+                    const text = Buffer.concat(parts).toString("utf8");
+                    parts = [];
+                    if (op !== 2)
+                        onText(text);
+                }
+            }
+        }
+    });
+    return { send: (t) => { if (!closed)
+            socket.write(frame(1, Buffer.from(t))); }, close: shut };
+}

package/dist/run.d.ts

@@ -0,0 +1,109 @@
+import { networkInterfaces } from "node:os";
+import { type Server } from "node:http";
+import { type NetRecord } from "./run-net.js";
+export type Platform = "android" | "ios";
+export type RunOptions = {
+    platform: Platform;
+    open: boolean;
+    port?: number;
+    native: boolean;
+    lan: boolean;
+};
+export declare const RUN_USAGE = "Usage: shipvo run android|ios [options]\n\nOptions:\n  --no-open     do not open the browser\n  --port <n>    serve on this port (default: a free port)\n  --native      run on a real emulator or simulator with `npx expo run:<platform>`\n\nExample: shipvo run android";
+/** True when this project has no earlier web build, so Metro starts with an empty cache. */
+export declare const isFirstBuild: (root: string) => boolean;
+/** Parses `run` arguments. Throws a plain message for anything it does not know. */
+export declare function parseRunArgs(argv: string[]): RunOptions;
+/** The command `--native` runs. */
+export declare const nativeCommand: (p: Platform) => {
+    cmd: string;
+    args: string[];
+};
+export declare const FRAMES: {
+    readonly android: {
+        readonly width: 412;
+        readonly height: 915;
+        readonly radius: 36;
+        readonly label: "Android";
+        readonly sheet: {
+            readonly title: "Allow access?";
+            readonly allow: "While using the app";
+            readonly deny: "Don't allow";
+        };
+    };
+    readonly ios: {
+        readonly width: 393;
+        readonly height: 852;
+        readonly radius: 55;
+        readonly label: "iOS";
+        readonly sheet: {
+            readonly title: "Would Like to Access";
+            readonly allow: "Allow While Using App";
+            readonly deny: "Don't Allow";
+        };
+    };
+};
+export type RenderFrame = ((o: {
+    skin: "android" | "ios";
+    dark?: boolean;
+    status?: object;
+    screen?: string;
+    lumi?: boolean;
+    guide?: boolean;
+}) => {
+    width: number;
+    height: number;
+    outerWidth: number;
+    outerHeight: number;
+    html: string;
+    css: string;
+}) & {
+    /** Script that keeps the status bar live from the app's `pn:status` events. Absent in older @shipvo/sim. */
+    statusScript?: (iframeId?: string, skin?: string) => string;
+};
+/** Loads the frame renderer from @shipvo/sim: the app's install first, then the one next to this CLI. */
+export declare function loadFrameRenderer(bases?: string[]): Promise<RenderFrame>;
+/** The page that shows the app in an Android or iOS frame at its real logical size, scaled to fit the window. The phone body comes from @shipvo/sim's renderFrame. */
+export declare function runFramePage(platform: Platform, name: string, render: RenderFrame, dark?: boolean, token?: string): string;
+/** True for a phone or tablet browser, by user agent. */
+export declare const isMobileUserAgent: (ua: string | undefined) => boolean;
+/** The page for a real phone's browser: the app fills the screen, no phone frame. */
+export declare function runBarePage(name: string, dark?: boolean): string;
+/** The first private IPv4 address of this machine (or any non-internal one), or undefined. */
+export declare function lanAddress(ifaces?: ReturnType<typeof networkInterfaces>): string | undefined;
+/** Adds `.shipvo/` to `<dir>/.gitignore` when it is not already ignored. */
+export declare function ensureShipvoIgnored(dir: string): void;
+/**
+ * Serves the frame page at `/` and the web export at `/app/` (and its absolute asset paths at `/`).
+ * Port 0 picks a free port. Resolves once listening.
+ * The agent channel is a WebSocket at `/__shipvo/agent?role=screen|driver&token=...`, loopback only. It relays JSON
+ * messages between the `screen` and the `driver`. With `projectDir`, `.shipvo/run.json` describes the session while it runs.
+ */
+export declare function startRunServer(opts: {
+    dir: string;
+    platform: Platform;
+    name: string;
+    appId?: string;
+    port?: number;
+    projectDir?: string;
+    render?: RenderFrame;
+    lan?: {
+        host: string;
+    };
+    onNet?: (r: NetRecord) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    server: Server;
+    port: number;
+    token: string;
+    lanToken?: string;
+    netLog: NetRecord[];
+    close: () => Promise<void>;
+}>;
+/** Names the module or file a web build failed on, from the build's error output. */
+export declare function describeWebBuildFailure(output: string): string;
+/** Builds the web export with `rebuildInto` from sim.ts (the same build as `shipvo sim`) into `<root>/sim-dist`. */
+export declare function buildWeb(root: string, command?: string): Promise<void>;
+export declare function openBrowser(url: string): void;
+/** Returns the exit code. */
+export declare function run(argv: string[]): Promise<number>;