@shipvo/cli 0.1.4 → 0.1.5

package/dist/publish.js

@@ -74,7 +74,7 @@ function localKv(dir) {
         },
     };
 }
-const PUBLISH_FLAGS = ["bands", "platform", "release", "min-shell", "hermes-bytecode-version", "max-bases", "skip-export", "skip-web", "dry-run", "out"];
+const PUBLISH_FLAGS = ["bands", "platform", "release", "min-shell", "hermes-bytecode-version", "max-bases", "skip-export", "skip-web", "dry-run", "dry-run-policy", "out"];
 export const PUBLISH_HELP = `Usage: shipvo publish [flags]
 
 Build, sign and publish an over-the-air release.
@@ -89,6 +89,7 @@ Flags (write a value after a space, not =; on/off flags can be bare, or true/fal
   --skip-export               Reuse the last build in dist-ota/
   --skip-web                  Do not publish the web copy for the simulator
   --dry-run                    Build and sign, write files locally, send nothing
+  --dry-run-policy             Check the policy in shipvo.json for these --bands, print the result, publish nothing
   --out <dir>                  Where --dry-run writes files (default .shipvo/dry-run)
   --help                       Show this help
 `;
@@ -99,6 +100,16 @@ export async function publish(argv) {
     }
     checkFlags(argv, PUBLISH_FLAGS);
     const a = parse(argv), cfg = loadConfig(), SEED = seed();
+    if (switchFlag(a, "dry-run-policy")) {
+        const verdict = checkPublishPolicy(cfg.policy, (a.bands || "b0,b1,b2").split(","));
+        if (verdict.ok)
+            console.log(cfg.policy === undefined ? "No policy in shipvo.json: nothing to check." : "Policy allows this publish.");
+        else {
+            console.error(`Refused by policy rule ${verdict.rule}: ${verdict.reason}`);
+            process.exitCode = 1;
+        }
+        return;
+    }
     const dry = switchFlag(a, "dry-run"), skipExport = switchFlag(a, "skip-export"), skipWeb = switchFlag(a, "skip-web");
     if (a.out !== undefined && !dry)
         throw new Error("--out only works with --dry-run");

package/dist/report-md.d.ts

@@ -0,0 +1,26 @@
+type Step = {
+    kind?: string;
+    target?: string;
+    text?: string;
+    enter?: boolean;
+    line?: number;
+};
+type Flow = {
+    name?: string;
+    status?: string;
+    steps?: Step[];
+    failedStep?: Step | null;
+    message?: string | null;
+    screenshots?: string[];
+    screenshot?: string | null;
+};
+export type TestReport = {
+    app?: string | null;
+    commit?: string | null;
+    release?: string | null;
+    time?: string | null;
+    parityLimits?: string[];
+    flows?: Flow[];
+};
+export declare function renderReportMarkdown(report: TestReport): string;
+export {};

package/dist/report-md.js

@@ -0,0 +1,58 @@
+const one = (s) => s.replace(/\s+/g, " ").trim();
+/** Inline code that survives backticks in the text. */
+function code(s) {
+    const t = one(s);
+    const fence = "`".repeat(Math.max(0, ...[...t.matchAll(/`+/g)].map((m) => m[0].length)) + 1);
+    return `${fence}${t.startsWith("`") || t.endsWith("`") ? ` ${t} ` : t}${fence}`;
+}
+function stepText(s) {
+    const kind = s.kind ?? "step";
+    if (kind === "tap")
+        return `tap "${s.target ?? ""}"`;
+    if (kind === "type")
+        return `type "${s.text ?? ""}" into "${s.target ?? ""}"${s.enter ? " and press enter" : ""}`;
+    const arg = s.text ?? s.target;
+    return arg !== undefined ? `${kind} "${arg}"` : kind;
+}
+function block(s) {
+    const fence = "`".repeat(Math.max(2, ...[...s.matchAll(/`+/g)].map((m) => m[0].length)) + 1);
+    return `${fence}\n${s}\n${fence}`;
+}
+export function renderReportMarkdown(report) {
+    const flows = Array.isArray(report.flows) ? report.flows : [];
+    const failed = flows.filter((f) => f.status === "failed");
+    const out = [`# Shipvo test report: ${failed.length ? "failed" : "all flows passed"}`, ""];
+    const meta = [];
+    if (report.app)
+        meta.push(`- App: ${code(report.app)}`);
+    meta.push(`- Release: ${report.release ? code(report.release) : "not set"}`);
+    meta.push(`- Commit: ${report.commit ? code(report.commit) : "unknown"}`);
+    if (report.time)
+        meta.push(`- Time: ${report.time}`);
+    meta.push(`- Flows: ${flows.length - failed.length} passed, ${failed.length} failed`);
+    out.push(...meta, "");
+    if (!failed.length)
+        out.push(flows.length ? `All ${flows.length} flow${flows.length === 1 ? "" : "s"} passed.` : "No flows were run.", "");
+    for (const f of failed) {
+        out.push(`## Failing flow: ${code(f.name ?? "unnamed flow")}`, "");
+        const bad = f.failedStep;
+        if (bad)
+            out.push(`Failed step${bad.line ? ` (line ${bad.line})` : ""}: ${code(stepText(bad))}`, "");
+        if (f.message)
+            out.push("Error:", "", block(f.message), "");
+        const shots = [...(f.screenshots ?? []), ...(f.screenshot ? [f.screenshot] : [])];
+        if (shots.length)
+            out.push(`Screenshots: ${shots.map(code).join(", ")}`, "");
+        if (f.steps?.length) {
+            out.push("Steps:", "");
+            f.steps.forEach((s, i) => {
+                const mark = bad && s.line !== undefined && s.line === bad.line ? " ← failed" : "";
+                out.push(`${i + 1}. ${code(stepText(s))}${mark}`);
+            });
+            out.push("");
+        }
+    }
+    if (report.parityLimits?.length)
+        out.push("## Parity limits", "", ...report.parityLimits.map((l) => `- ${one(l)}`), "");
+    return out.join("\n");
+}

package/dist/run-bridge.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The shared screen rules (`@shipvo/sim`), as source that the page can run. Same copy the simulator uses.
+ * Only plain `export function` / `export const` lines are supported: `export default` and `export {…}` would not be stripped.
+ */
+export declare function screenRulesSource(): string;
+/** The script text served at `/__shipvo/bridge.js`. It reads the session token from its own `data-token` attribute and then removes the attribute. */
+export declare function bridgeScript(rules?: string): string;

package/dist/run-bridge.js

@@ -0,0 +1,374 @@
+// The page script of `shipvo run`. The frame page serves it at `/__shipvo/bridge.js`. It connects to the agent
+// channel as role `screen` and answers `tree` requests from the same-origin app iframe. No Playwright: the tree is
+// built from the DOM, in the shape of the simulator's `- role "name" [ref=eN]` lines (slice 3b of #448).
+// Differences from the simulator tree are listed in docs/run-bridge.md.
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+/**
+ * The shared screen rules (`@shipvo/sim`), as source that the page can run. Same copy the simulator uses.
+ * Only plain `export function` / `export const` lines are supported: `export default` and `export {…}` would not be stripped.
+ */
+export function screenRulesSource() {
+    const path = createRequire(import.meta.url).resolve("@shipvo/sim/screen-rules.mjs");
+    const src = readFileSync(path, "utf8");
+    if (/^export\s+(default\b|\{|\*)/m.test(src))
+        throw new Error("screen-rules.mjs may only use `export function` or `export const`");
+    return src.replace(/^export /gm, "");
+}
+/** Runs in the page. Everything it needs is nested inside, because it is serialised with `String(fn)`. */
+function bridgeMain(win, token) {
+    const doc = win.document;
+    // A ref names one element with one role and name. If the element's content changes, it gets a new ref and the old one is stale.
+    const refs = new WeakMap();
+    const byRef = new Map();
+    let counter = 0;
+    const refOf = (el, sig) => {
+        let r = refs.get(el);
+        if (!r || r.sig !== sig) {
+            r = { n: ++counter, sig };
+            refs.set(el, r);
+        }
+        byRef.set("e" + r.n, { el, sig });
+        return "e" + r.n;
+    };
+    const INPUT_ROLE = { checkbox: "checkbox", radio: "radio", range: "slider", button: "button", submit: "button", reset: "button", image: "button", search: "searchbox", number: "spinbutton" };
+    const TAG_ROLE = { button: "button", textarea: "textbox", select: "combobox", img: "img", ul: "list", ol: "list", li: "listitem", nav: "navigation", main: "main", dialog: "dialog", form: "form", table: "table", tr: "row", td: "cell", th: "columnheader", p: "paragraph", progress: "progressbar", article: "article", aside: "complementary" };
+    const FROM_CONTENT = new Set(["button", "link", "heading", "tab", "checkbox", "radio", "switch", "menuitem", "option", "cell", "columnheader"]);
+    const norm = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+    const hidden = (el, cs) => el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true" || cs.display === "none" || cs.visibility === "hidden" || cs.visibility === "collapse";
+    function roleOf(el) {
+        const explicit = norm(el.getAttribute("role")).split(" ")[0];
+        if (explicit && explicit !== "presentation" && explicit !== "none")
+            return explicit;
+        const tag = el.tagName.toLowerCase();
+        if (tag === "a")
+            return el.hasAttribute("href") ? "link" : "";
+        if (/^h[1-6]$/.test(tag))
+            return "heading";
+        if (tag === "input") {
+            const t = (el.getAttribute("type") || "text").toLowerCase();
+            return t === "hidden" ? "" : INPUT_ROLE[t] || "textbox";
+        }
+        if (tag === "section")
+            return el.hasAttribute("aria-label") || el.hasAttribute("aria-labelledby") ? "region" : "";
+        if (tag === "img" && el.getAttribute("alt") === "")
+            return "";
+        return TAG_ROLE[tag] || "";
+    }
+    function textOf(node) {
+        if (node.nodeType === 3)
+            return node.nodeValue || "";
+        if (node.nodeType !== 1)
+            return "";
+        const tag = node.tagName.toLowerCase();
+        if (tag === "script" || tag === "style" || tag === "noscript")
+            return "";
+        if (hidden(node, win.getComputedStyle(node)))
+            return "";
+        if (tag === "img")
+            return node.getAttribute("alt") || "";
+        const own = node.getAttribute("aria-label");
+        if (own && roleOf(node))
+            return own;
+        let out = "";
+        for (const c of node.childNodes)
+            out += textOf(c) + (c.nodeType === 1 && win.getComputedStyle(c).display !== "inline" ? " " : "");
+        return out;
+    }
+    /** Accessible name and whether it came from the element's own content. */
+    function nameOf(el, role) {
+        const by = norm(el.getAttribute("aria-labelledby"));
+        if (by) {
+            const t = by.split(" ").map((id) => { const r = doc.getElementById(id); return r ? norm(textOf(r)) : ""; }).filter(Boolean).join(" ");
+            if (t)
+                return { name: t, fromContent: false };
+        }
+        const label = norm(el.getAttribute("aria-label"));
+        if (label)
+            return { name: label, fromContent: false };
+        const tag = el.tagName.toLowerCase();
+        if (tag === "input" || tag === "textarea" || tag === "select") {
+            const ls = el.labels ? [...el.labels] : [];
+            const t = norm(ls.map((l) => textOf(l)).join(" "));
+            if (t)
+                return { name: t, fromContent: false };
+            if (tag === "input" && /^(button|submit|reset)$/.test(el.type) && el.value)
+                return { name: norm(el.value), fromContent: false };
+            const ph = norm(el.getAttribute("placeholder")) || norm(el.getAttribute("title"));
+            return { name: ph, fromContent: false };
+        }
+        if (tag === "img")
+            return { name: norm(el.getAttribute("alt")) || norm(el.getAttribute("title")), fromContent: false };
+        if (FROM_CONTENT.has(role)) {
+            const t = norm(textOf(el));
+            if (t)
+                return { name: t, fromContent: true };
+        }
+        return { name: norm(el.getAttribute("title")), fromContent: false };
+    }
+    function states(el, role) {
+        let s = "";
+        const aria = (n) => el.getAttribute(n);
+        const on = (n) => aria(n) === "true";
+        if (role === "heading") {
+            const l = aria("aria-level") || (/^h([1-6])$/i.exec(el.tagName)?.[1] ?? "2");
+            s += " [level=" + l + "]";
+        }
+        if (/^(checkbox|radio|switch|menuitemcheckbox|menuitemradio)$/.test(role)) {
+            if (el.tagName === "INPUT" ? el.checked : on("aria-checked"))
+                s += " [checked]";
+            else if (aria("aria-checked") === "mixed")
+                s += " [checked=mixed]";
+        }
+        if (el.disabled === true || on("aria-disabled") || (el.closest && el.closest("fieldset[disabled]")))
+            s += " [disabled]";
+        if (on("aria-expanded"))
+            s += " [expanded]";
+        if (/^(tab|option|treeitem|row|gridcell)$/.test(role) && on("aria-selected"))
+            s += " [selected]";
+        if (on("aria-pressed"))
+            s += " [pressed]";
+        return s;
+    }
+    const quote = (s) => JSON.stringify(s);
+    // The simulator's snapshot is YAML-like: a key with ": " inside is wrapped in single quotes, a value with ": " in double quotes.
+    const needs = (t) => /: | #|:$|^[\[\]{}&*!|>'"%@`#?,-]/.test(t);
+    const keyLine = (pad, key, tail) => pad + "- " + (needs(key) ? "'" + key.replace(/'/g, "''") + "'" : key) + tail;
+    const val = (t) => (needs(t) ? JSON.stringify(t) : t);
+    function walk(el, depth, out) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === "script" || tag === "style" || tag === "noscript" || tag === "template")
+            return;
+        if (hidden(el, win.getComputedStyle(el)))
+            return;
+        const role = roleOf(el);
+        const pad = "  ".repeat(depth);
+        if (role) {
+            const { name, fromContent } = nameOf(el, role);
+            const key = role + (name ? " " + quote(name) : "") + states(el, role) + " [ref=" + refOf(el, role + "|" + name) + "]";
+            if (tag === "input" || tag === "textarea") {
+                const v = el.value;
+                out.push(keyLine(pad, key, v && !/^(checkbox|radio|button|submit|reset)$/.test(el.type) ? ": " + val(v) : ""));
+                return;
+            }
+            if (fromContent || tag === "img") {
+                out.push(keyLine(pad, key, ""));
+                return;
+            }
+            const mark = out.length;
+            out.push("");
+            for (const c of el.childNodes)
+                child(c, depth + 1, out);
+            out[mark] = keyLine(pad, key, out.length > mark + 1 ? ":" : "");
+            return;
+        }
+        // No role: keep the text, drop the wrapper. A wrapper with only text becomes one generic line.
+        const hasEl = [...el.children].length > 0;
+        if (!hasEl) {
+            const t = norm(el.textContent);
+            if (t)
+                out.push(pad + "- generic [ref=" + refOf(el, "generic|" + t) + "]: " + val(t));
+            return;
+        }
+        for (const c of el.childNodes)
+            child(c, depth, out);
+    }
+    function child(c, depth, out) {
+        if (c.nodeType === 1)
+            walk(c, depth, out);
+        else if (c.nodeType === 3) {
+            const t = norm(c.nodeValue);
+            if (t)
+                out.push("  ".repeat(depth) + "- text: " + val(t));
+        }
+    }
+    function tree() {
+        const frame = doc.getElementById("app");
+        const d = frame && frame.contentDocument;
+        if (!d || !d.body)
+            throw new Error("the app is not loaded yet");
+        globalThis.__shipvoRules.clearScreenRules(d);
+        globalThis.__shipvoRules.applyScreenRules(d);
+        try {
+            const out = [];
+            for (const c of d.body.childNodes)
+                child(c, 0, out);
+            return globalThis.__shipvoRules.filterTree(out.join("\n"));
+        }
+        finally {
+            globalThis.__shipvoRules.clearScreenRules(d);
+        }
+    }
+    /** Same code and message shape as the simulator's typed errors. */
+    class ActError extends Error {
+        code;
+        constructor(code, msg) { super(msg); this.code = code; }
+    }
+    const sigOf = (el) => { const role = roleOf(el); return role ? role + "|" + nameOf(el, role).name : "generic|" + norm(el.textContent); };
+    const appDoc = () => { const f = doc.getElementById("app"); return f && f.contentDocument; };
+    /** The element for a ref from a snapshot, or `stale_ref` if it is unknown, gone, left the page, or changed role or name. */
+    function resolve(ref) {
+        const stale = () => new ActError("stale_ref", `stale ref ${ref}: the screen changed. Take a new snapshot (action "screen") and use a ref from it.`);
+        const d = appDoc();
+        const rec = byRef.get(String(ref));
+        if (!d || !rec || !rec.el.isConnected || rec.el.ownerDocument !== d)
+            throw stale();
+        if (sigOf(rec.el) !== rec.sig || refs.get(rec.el)?.sig !== rec.sig)
+            throw stale();
+        return rec.el;
+    }
+    /** Say why an element cannot receive a tap. Nothing has reached the app when this throws. */
+    function ready(el, ref) {
+        const fail = (code, why) => new ActError(code, `${ref} ${why}, so nothing was sent to the app.`);
+        if (hidden(el, win.getComputedStyle(el)) || el.getClientRects().length === 0)
+            throw fail("not_visible", "is not visible");
+        if (el.disabled === true || el.getAttribute("aria-disabled") === "true" || (el.closest && el.closest("fieldset[disabled]")))
+            throw fail("disabled", "is disabled");
+        el.scrollIntoView({ block: "center", inline: "center" });
+        const r = el.getBoundingClientRect();
+        const w = el.ownerDocument.defaultView;
+        if (r.right <= 0 || r.bottom <= 0 || r.left >= w.innerWidth || r.top >= w.innerHeight)
+            throw fail("not_visible", "is not visible");
+        const x = r.left + r.width / 2, y = r.top + r.height / 2;
+        const top = el.ownerDocument.elementFromPoint(x, y);
+        if (top && top !== el && !el.contains(top) && !top.contains(el))
+            throw fail("covered", "is covered by another element");
+        return { x, y, target: top && el.contains(top) ? top : el };
+    }
+    function tap(el, ref) {
+        const { x, y, target } = ready(el, ref);
+        const w = el.ownerDocument.defaultView;
+        const init = { bubbles: true, cancelable: true, composed: true, view: w, clientX: x, clientY: y, button: 0, pointerId: 1, pointerType: "mouse", isPrimary: true };
+        const fire = (Ctor, type, buttons) => target.dispatchEvent(new Ctor(type, { ...init, buttons }));
+        fire(w.PointerEvent, "pointerdown", 1);
+        fire(w.MouseEvent, "mousedown", 1);
+        if (typeof el.focus === "function")
+            el.focus({ preventScroll: true });
+        fire(w.PointerEvent, "pointerup", 0);
+        fire(w.MouseEvent, "mouseup", 0);
+        fire(w.MouseEvent, "click", 0);
+    }
+    function type(el, ref, text, enter) {
+        const field = /^(INPUT|TEXTAREA)$/.test(el.tagName) ? el : el.querySelector("input, textarea");
+        if (!field)
+            throw new ActError("not_a_field", `${ref} is not a text field. Type into a "textbox" ref.`);
+        ready(field, ref);
+        const w = field.ownerDocument.defaultView;
+        field.focus();
+        const proto = field.tagName === "TEXTAREA" ? w.HTMLTextAreaElement.prototype : w.HTMLInputElement.prototype;
+        Object.getOwnPropertyDescriptor(proto, "value").set.call(field, text);
+        field.dispatchEvent(new w.InputEvent("input", { bubbles: true, inputType: "insertText", data: text }));
+        field.dispatchEvent(new w.Event("change", { bubbles: true }));
+        if (enter)
+            for (const t of ["keydown", "keypress", "keyup"])
+                field.dispatchEvent(new w.KeyboardEvent(t, { key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true }));
+        return field.value;
+    }
+    function scroll(ref, direction) {
+        const d = appDoc();
+        const w = d.defaultView;
+        const dx = direction === "right" ? 300 : direction === "left" ? -300 : 0;
+        const dy = direction === "down" ? 600 : direction === "up" ? -600 : 0;
+        if (!dx && !dy)
+            throw new ActError("bad_direction", "scroll needs a direction: up, down, left or right.");
+        let el = ref ? resolve(ref) : d.body;
+        // The nearest ancestor that can scroll that way. Fall back to the page.
+        for (; el && el !== d.body && el !== d.documentElement; el = el.parentElement) {
+            const cs = w.getComputedStyle(el);
+            if (dy && /auto|scroll/.test(cs.overflowY) && el.scrollHeight > el.clientHeight)
+                break;
+            if (dx && /auto|scroll/.test(cs.overflowX) && el.scrollWidth > el.clientWidth)
+                break;
+        }
+        if (!el || el === d.body || el === d.documentElement)
+            el = d.scrollingElement || d.documentElement;
+        el.scrollBy({ left: dx, top: dy, behavior: "instant" });
+    }
+    function back() {
+        const d = appDoc();
+        for (const el of d.querySelectorAll("button, [role=button], input[type=button], input[type=submit]")) {
+            const role = roleOf(el);
+            if (role === "button" && !hidden(el, win.getComputedStyle(el)) && nameOf(el, role).name === "Back") {
+                tap(el, "Back");
+                return;
+            }
+        }
+        throw new Error("no Back button on this screen");
+    }
+    const sleep = (ms) => new Promise((r) => win.setTimeout(r, ms));
+    /** Give the app a moment to react, and wait for a page load a tap started. */
+    async function settle() {
+        await sleep(250);
+        for (let i = 0; i < 30; i++) {
+            const d = appDoc();
+            if (d && d.readyState === "complete" && d.body)
+                break;
+            await sleep(100);
+        }
+        await sleep(50);
+    }
+    const screenOrUndefined = () => { try {
+        return tree();
+    }
+    catch {
+        return undefined;
+    } };
+    async function act(m) {
+        switch (m.type) {
+            case "tap":
+                tap(resolve(m.ref), m.ref);
+                break;
+            case "type": {
+                const value = type(resolve(m.ref), m.ref, String(m.text ?? ""), !!m.enter);
+                await settle();
+                return { delivery: "delivered", value, screen: tree() };
+            }
+            case "scroll":
+                scroll(m.ref, m.direction);
+                break;
+            case "back":
+                back();
+                break;
+            default: throw new Error("unknown request: " + m.type);
+        }
+        await settle();
+        return { delivery: "delivered", screen: tree() };
+    }
+    const ws = new win.WebSocket((win.location.protocol === "https:" ? "wss://" : "ws://") + win.location.host + "/__shipvo/agent?role=screen&token=" + encodeURIComponent(token));
+    ws.onmessage = (e) => {
+        let m;
+        try {
+            m = JSON.parse(String(e.data));
+        }
+        catch {
+            return;
+        }
+        if (!m || typeof m.id !== "number")
+            return;
+        try {
+            if (m.type === "tree")
+                ws.send(JSON.stringify({ id: m.id, type: "tree", ok: true, tree: tree() }));
+            else if (/^(tap|type|scroll|back)$/.test(m.type)) {
+                act(m).then((r) => ws.send(JSON.stringify({ id: m.id, type: m.type, ok: true, ...r })), (err) => ws.send(JSON.stringify({ id: m.id, type: m.type, ok: false, ...(err && err.code ? { code: err.code } : {}), error: String(err && err.message || err), screen: screenOrUndefined() })));
+            }
+            else
+                ws.send(JSON.stringify({ id: m.id, type: m.type, ok: false, error: "unknown request: " + m.type }));
+        }
+        catch (err) {
+            ws.send(JSON.stringify({ id: m.id, type: m.type, ok: false, error: String(err && err.message || err) }));
+        }
+    };
+}
+/** The script text served at `/__shipvo/bridge.js`. It reads the session token from its own `data-token` attribute and then removes the attribute. */
+export function bridgeScript(rules = screenRulesSource()) {
+    return `(function(){
+var __rules=(function(){${rules}
+return {clearScreenRules:clearScreenRules,applyScreenRules:applyScreenRules,filterTree:filterTree};})();
+globalThis.__shipvoRules=__rules;
+var tag=document.currentScript;
+var tok=tag?tag.getAttribute("data-token")||"":"";
+if(tag)tag.removeAttribute("data-token");
+(${bridgeMain.toString()})(window, tok);
+})();
+`;
+}

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 };
+}