windscout 0.4.6 → 0.5.1

package/dist/tui/progress.js

@@ -0,0 +1,124 @@
+import { sortOk } from "../probe.js";
+import { attemptSeconds } from "../scan.js";
+import { duration, now } from "../time.js";
+import { CLI, restoreFirewall } from "../windscribe.js";
+import { countryName, flag } from "./country.js";
+import { matrix, resultTable } from "./tables.js";
+import { draw, enterScreen, input, leaveScreen, out, repoLink } from "./terminal.js";
+import { bold, cyan, dim, green, red, vw, yellow } from "./text.js";
+import { bar, box, centerIn } from "./widgets.js";
+/** Progress bar, current attempt, results so far. tab switches the table, p pauses, q stops (twice: quits).
+ * blocking: we turned the firewall on for the scan */
+export function showProgress(scan, blocking) {
+    const { protocols, options: { timeout, speedTest } } = scan;
+    let view = speedTest ? "ranking" : "availability"; // tab switches
+    let frame = 0;
+    const render = () => {
+        const rows = out.rows || 24;
+        const { done, total, waiting, paused, stopping, results, finished } = scan;
+        const elapsed = scan.elapsed();
+        // smooth bar: count the running attempt as partially done
+        const partial = waiting ? 0 : Math.min(0.95, (now() - scan.attemptStart) / attemptSeconds(timeout));
+        const fraction = (done + (done < total ? partial : 0)) / total;
+        const eta = (total - done) * (done ? elapsed / done : attemptSeconds(timeout));
+        const spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"[frame++ % 10];
+        const ok = sortOk(results);
+        const failed = finished.filter((c) => !results.some((r) => r.query === c && r.status === "ok"));
+        const current = scan.current ? `${flag(scan.current.country)} ${countryName(scan.current.country)} ${dim("·")} ${scan.current.protocol}` : "";
+        const pct = bold(`${String(Math.floor(fraction * 100)).padStart(3)}%`);
+        const stats = [
+            `${dim("elapsed")} ${duration(elapsed)}`,
+            `${dim("remaining")} ${done < total ? "≈ " + duration(eta) : "-"}`,
+            `${green("✓")} ${ok.length} ${dim("working")}`,
+            `${red("✗")} ${failed.length} ${dim("blocked")}`,
+        ].join(dim("   │   "));
+        const minW = Math.max(64, vw(stats) + 6); // panel and table share one width
+        // results table gets whatever height the status panel and footer leave
+        const room = Math.max(1, rows - 22);
+        const table = view === "availability"
+            ? matrix(results, protocols, { minWidth: minW, limit: room })
+            : ok.length
+                ? resultTable(ok.slice(0, room), speedTest, {
+                    caption: bold("Working so far"),
+                    captionRight: dim(ok.length > room ? `top ${room} of ${ok.length}` : `${ok.length} found`),
+                    minWidth: minW,
+                })
+                : [];
+        const width = Math.max(minW, table.length ? vw(table[0]) : 0);
+        const inner = width - 4;
+        const panel = box([
+            "",
+            ` ${bar(fraction, inner - 8)}  ${pct}`,
+            "",
+            stopping
+                ? yellow(" stopping after the current attempt…")
+                : waiting ? yellow(` paused · VPN disconnected${blocking ? " · firewall blocking internet" : ""} · press p to resume`)
+                    : ` ${cyan(spinner)} ${bold(current)}`,
+            stopping || waiting ? "" : `   ${dim(scan.step)} ${dim("·")} ${duration(now() - scan.attemptStart)}${paused && frame % 8 < 5 ? yellow(" · pausing after this attempt") : ""}`,
+            null,
+            centerIn(stats, inner),
+        ], {
+            title: bold(cyan("WindScout")),
+            right: `${bold(String(done))}${dim(`/${total} attempts`)}`,
+            width: inner,
+        });
+        const lines = [...panel];
+        if (table.length)
+            lines.push(...table);
+        else
+            lines.push("", centerIn(dim(finished.length ? "nothing has connected yet" : "results appear here after each country"), width));
+        if (failed.length) {
+            let txt = `${red("✗")} ${dim("no connection:")} ${failed.map((c) => `${flag(c)} ${c}`).join(" ")}`;
+            while (vw(txt) > width && failed.length)
+                txt = txt.slice(0, -8) + "…"; // ponytail: crude trim, fine for a status line
+            lines.push("", centerIn(txt, width));
+        }
+        lines.push("", centerIn(dim(`tab ${view === "ranking" ? "availability" : "ranking"} view · p ${paused ? "resume" : "pause"} · q stop · q twice force quit`), width), "", centerIn(dim(repoLink), width));
+        draw(lines);
+    };
+    enterScreen();
+    input.on("keypress", async (_str, key = {}) => {
+        if (key.name === "tab") {
+            view = view === "ranking" ? "availability" : "ranking";
+            render();
+        }
+        else if (key.name === "p" || key.name === "space") {
+            scan.togglePause();
+            render();
+        }
+        else if (key.name === "q" || key.name === "escape" || (key.ctrl && key.name === "c")) {
+            if (scan.stopping) { // second press: bail out now
+                leaveScreen();
+                console.error(`stopped. the VPN may still be connecting: run '${CLI} disconnect'`);
+                await restoreFirewall();
+                process.exit(130);
+            }
+            scan.stop();
+            render();
+        }
+    });
+    out.on("resize", render);
+    const timer = setInterval(render, 120);
+    return {
+        close() {
+            clearInterval(timer);
+            out.off("resize", render);
+            leaveScreen();
+        },
+    };
+}
+/** A line per attempt. Ctrl-C stops after the current attempt, a second one quits */
+export function logProgress(scan) {
+    process.on("SIGINT", async () => {
+        if (scan.stopping) {
+            await restoreFirewall();
+            process.exit(130);
+        }
+        scan.stop();
+    });
+    return {
+        attempt: (country, protocol) => process.stdout.write(`[${scan.done + 1}/${scan.total}] ${country} ${protocol} ... `),
+        result: (r) => console.log([r.status, r.location, r.speedMbps ? `${r.speedMbps.toFixed(1)} Mbps` : ""].join(" ").trim()),
+        close() { },
+    };
+}

package/dist/tui/report.js

@@ -0,0 +1,44 @@
+// The final report, printed to the normal screen so it stays in the scrollback.
+import { sortOk } from "../probe.js";
+import { CLI } from "../windscribe.js";
+import { flag } from "./country.js";
+import { matrix, resultTable } from "./tables.js";
+import { bold, cyan, dim, fmt, green, vw, yellow } from "./text.js";
+import { box, grid } from "./widgets.js";
+export function report(results, protocols, { all, speedTest }) {
+    const ok = sortOk(results);
+    const rows = [...ok, ...(all ? results.filter((r) => r.status !== "ok") : [])];
+    // render once to learn the widest table, then again so every box lines up
+    const build = (minWidth) => ({
+        avail: matrix(results, protocols, { minWidth }),
+        main: rows.length
+            ? resultTable(rows, speedTest, { caption: bold("Results"), captionRight: dim(`${ok.length} working`), minWidth })
+            : [],
+    });
+    const first = build(0);
+    const width = Math.max(64, ...[first.avail[0], first.main[0]].filter(Boolean).map(vw));
+    const { avail, main } = build(width);
+    console.log();
+    if (avail.length)
+        console.log(avail.join("\n"));
+    if (!ok.length) {
+        console.log(box([yellow("Nothing connected."),
+            dim("Try other countries, ports (e.g. -p stealth:443,tcp:443) or a longer --timeout.")], { title: bold(cyan("WindScout")), width: width - 4 }).join("\n"));
+        return;
+    }
+    console.log(main.join("\n"));
+    const stats = protocols.map((p) => {
+        const tried = results.filter((r) => r.protocol === p && r.status !== "no such location");
+        const good = tried.filter((r) => r.status === "ok");
+        return { p, good: good.length, tried: tried.length, best: sortOk(good).at(0) };
+    }).sort((x, y) => y.good - x.good || (y.best?.speedMbps ?? 0) - (x.best?.speedMbps ?? 0) || (x.best?.latencyMs ?? 1e9) - (y.best?.latencyMs ?? 1e9));
+    const bestValue = (r) => (speedTest ? `${fmt(r.speedMbps, 1)} Mbps` : `${fmt(r.latencyMs, 0)} ms`);
+    console.log(grid([{ title: "Protocol" }, { title: "Worked", align: "right" }, { title: speedTest ? "Best speed" : "Best latency", align: "right" }, { title: "Best location" }], stats.map((s) => [s.p, `${s.good}/${s.tried}`, s.best ? bestValue(s.best) : "-", s.best ? `${flag(s.best.query)} ${s.best.location}` : "-"]), { caption: bold("Per protocol"), minWidth: width }).join("\n"));
+    const b = ok[0];
+    const target = b.location.split(" - ").at(-1) || b.query; // nickname pins the exact datacenter
+    const facts = [speedTest && `${fmt(b.speedMbps, 1)} Mbps`, `${fmt(b.latencyMs, 0)} ms`].filter(Boolean).join(" · ");
+    console.log(box([
+        `${flag(b.query)} ${bold(b.location)} over ${bold(b.protocol)} ${dim("· " + facts)}`,
+        cyan(`${CLI} connect "${target}" ${b.protocol}`),
+    ], { title: green(speedTest ? "★ Best" : "★ Best (lowest latency)"), width: width - 4 }).join("\n"));
+}

package/dist/tui/tables.js

@@ -0,0 +1,62 @@
+import { countryName, flag } from "./country.js";
+import { bold, dim, fmt, green, red } from "./text.js";
+import { grid } from "./widgets.js";
+const RESULT_COLS = [
+    { title: "#", align: "right" }, { title: "Country" }, { title: "Location" }, { title: "Protocol" },
+    { title: "Connect", align: "right" }, { title: "Latency", align: "right" }, { title: "Speed", align: "right" }, { title: "Status" },
+];
+const SPEED_COL = 6;
+const resultRow = (r, i) => [
+    dim(String(i + 1)),
+    `${flag(r.query)} ${countryName(r.query)}`,
+    r.location || "-",
+    r.protocol,
+    r.connectS === null ? "-" : `${fmt(r.connectS, 1)} s`,
+    r.latencyMs === null ? "-" : `${fmt(r.latencyMs, 0)} ms`,
+    r.speedMbps === null ? "-" : bold(`${fmt(r.speedMbps, 1)} Mbps`),
+    r.status === "ok" ? green("✓ ok") : red(r.status),
+];
+/** Numbered attempts, in the given order; the Speed column only when the speed test ran */
+export function resultTable(results, speedTest, options) {
+    const keep = (_, i) => speedTest || i !== SPEED_COL;
+    return grid(RESULT_COLS.filter(keep), results.map((r, i) => resultRow(r, i).filter(keep)), options);
+}
+/** One row per country, ✓/✗ per protocol (· = not tried yet); no lines until something was tried */
+export function matrix(results, protocols, { minWidth = 0, limit = Infinity } = {}) {
+    const byCountry = new Map();
+    for (const r of results) {
+        if (r.status === "no such location" || r.status === "interrupted")
+            continue;
+        if (!byCountry.has(r.query))
+            byCountry.set(r.query, []);
+        byCountry.get(r.query).push(r);
+    }
+    if (!byCountry.size)
+        return [];
+    const ranked = [...byCountry].map(([q, rs]) => ({ q, rs, good: rs.filter((r) => r.status === "ok").length }))
+        .sort((a, b) => b.good - a.good); // stable: ties keep scan order
+    const reachable = ranked.filter((c) => c.good).length;
+    const rows = ranked.slice(0, limit).flatMap(({ q, rs }) => {
+        const seen = rs.find((r) => r.status === "ok") ?? rs.find((r) => r.location);
+        // protocols can land on different datacenters (even cities), so list each one that connected, one per line
+        const places = [...new Set(rs.filter((r) => r.status === "ok").map((r) => r.location).filter(Boolean))];
+        const [first = seen?.location.split(" - ")[0] || dim("-"), ...more] = places;
+        return [
+            [
+                `${flag(q)} ${countryName(q)}`,
+                first,
+                ...protocols.map((p) => {
+                    const r = rs.find((x) => x.protocol === p);
+                    return !r ? dim("·") : r.status === "ok" ? green("✓") : red("✗");
+                }),
+            ],
+            ...more.map((place) => ["", place, ...protocols.map(() => "")]),
+        ];
+    }).slice(0, limit);
+    return grid([{ title: "Country" }, { title: "Location(s)" }, ...protocols.map((p) => ({ title: p, align: "center" }))], rows, {
+        caption: bold("Availability"),
+        captionRight: dim(`${reachable}/${ranked.length} countries reachable${ranked.length > limit ? ` · top ${limit}` : ""}`),
+        minWidth,
+        stretch: 1,
+    });
+}

package/dist/tui/terminal.js

@@ -0,0 +1,67 @@
+// The terminal: full-screen mode, keyboard and mouse input, drawing frames.
+import { spawn } from "node:child_process";
+import { emitKeypressEvents } from "node:readline";
+import { PassThrough } from "node:stream";
+import { vw } from "./text.js";
+const REPO_URL = "https://github.com/Diercohen/windscout";
+// OSC 8 makes the text a link in terminals that support it; clicks we receive ourselves are handled in onData
+export const repoLink = `\x1b]8;;${REPO_URL}\x1b\\${REPO_URL}\x1b]8;;\x1b\\`;
+export const out = process.stdout;
+// stdin minus mouse reports: readline would split those into stray keypresses ("0", ";", "M"…).
+// Emits "keypress" (str, key) like stdin would, and "mouse" (Mouse)
+export const input = new PassThrough();
+emitKeypressEvents(input);
+let fullscreen = false;
+let link = null; // where draw() last put the repo link
+const openUrl = (url) => spawn({ darwin: "open", win32: "explorer" }[process.platform] ?? "xdg-open", [url], { stdio: "ignore", detached: true })
+    .on("error", () => { }).unref();
+// SGR mouse report: ESC [ < button ; col ; row (M = press, m = release)
+// ponytail: assumes a report never straddles two reads, true for terminals in practice
+const onData = (buf) => {
+    const rest = buf.toString().replace(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/g, (_, b, x, y, kind) => {
+        const m = { button: Number(b), x: Number(x) - 1, y: Number(y) - 1, press: kind === "M" };
+        if (link && m.press && m.button === 0 && m.y === link.y && m.x >= link.x && m.x < link.x + REPO_URL.length)
+            openUrl(REPO_URL);
+        input.emit("mouse", m);
+        return "";
+    });
+    if (rest)
+        input.write(rest);
+};
+/** Alternate screen, cursor hidden, mouse reports on, raw keys */
+export function enterScreen() {
+    if (fullscreen)
+        return;
+    fullscreen = true;
+    out.write("\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h"); // alternate screen, hide cursor, mouse on
+    process.stdin.setRawMode(true);
+    process.stdin.on("data", onData);
+    process.stdin.resume();
+}
+/** Back to the normal screen; drops every key and mouse listener */
+export function leaveScreen() {
+    if (!fullscreen)
+        return;
+    fullscreen = false;
+    process.stdin.setRawMode(false);
+    process.stdin.off("data", onData);
+    process.stdin.pause();
+    input.removeAllListeners("keypress");
+    input.removeAllListeners("mouse");
+    out.write("\x1b[?1000l\x1b[?1006l\x1b[?25h\x1b[?1049l");
+}
+process.on("exit", leaveScreen);
+/** Redraws in place, centered: home, each line cleared to its end, then clear below (no flicker). Returns the top-left corner */
+export function draw(lines) {
+    const cols = out.columns || 80, rows = out.rows || 24;
+    const w = Math.max(...lines.map(vw));
+    const left = " ".repeat(Math.max(0, Math.floor((cols - w) / 2)));
+    const top = Math.max(0, Math.floor((rows - lines.length) / 2));
+    const screen = [...Array(top).fill(""), ...lines.map((l) => left + l)].slice(0, rows);
+    const i = screen.findIndex((l) => l.includes(REPO_URL));
+    link = i < 0 ? null : { y: i, x: vw(screen[i].slice(0, screen[i].indexOf("\x1b]8;;"))) };
+    // a timer tick can land after leaveScreen() (force quit, crash): don't paint over the normal screen
+    if (fullscreen)
+        out.write("\x1b[H" + screen.map((l) => l + "\x1b[K").join("\n") + "\x1b[J");
+    return { left: left.length, top };
+}

package/dist/tui/text.js

@@ -0,0 +1,22 @@
+// String helpers for the terminal: ANSI colors, visible width, padding.
+const plain = () => process.env.NO_COLOR || !process.stdout.isTTY;
+export const color = (code, s) => (plain() ? s : `\x1b[${code}m${s}\x1b[0m`);
+export const bold = (s) => color(1, s);
+export const dim = (s) => color(2, s);
+export const red = (s) => color(31, s);
+export const green = (s) => color(32, s);
+export const yellow = (s) => color(33, s);
+export const cyan = (s) => color(36, s);
+// underline off (24) instead of a full reset, so it nests inside dim/bold
+export const under = (s) => (plain() ? s : `\x1b[4m${s}\x1b[24m`);
+/** A number with fixed decimals, "-" when missing */
+export const fmt = (v, digits) => (v === null ? "-" : v.toFixed(digits));
+// visible width: ANSI codes take no space; flags and emoji (🔍) take 2 columns. text symbols like ▶ ★ stay 1
+export const vw = (s) => [...s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g, "").replace(/[\u{1F1E6}-\u{1F1FF}]{2}|[\u{1F300}-\u{1FAFF}]/gu, "xx")].length;
+/** Pads s with spaces to n visible columns */
+export function pad(s, n, align = "left") {
+    const gap = Math.max(0, n - vw(s));
+    if (align === "center")
+        return " ".repeat(Math.floor(gap / 2)) + s + " ".repeat(Math.ceil(gap / 2));
+    return align === "right" ? " ".repeat(gap) + s : s + " ".repeat(gap);
+}

package/dist/tui/widgets.js

@@ -0,0 +1,53 @@
+// Drawing blocks, with rounded box-drawing borders: box, grid (table), progress bar.
+import { bold, color, dim, pad, vw } from "./text.js";
+const border = dim;
+/** Box around lines; a null line draws a ├──┤ divider. title and right sit in the top border */
+export function box(lines, { title = "", right = "", width = 0 } = {}) {
+    const inner = Math.max(width, ...lines.map((l) => (l === null ? 0 : vw(l))), vw(title) + vw(right) + 6);
+    const left = title ? border("─ ") + title + " " : "";
+    const tail = right ? " " + right + border(" ─") : "";
+    const fill = inner + 2 - vw(left) - vw(tail);
+    return [
+        border("╭") + left + border("─".repeat(fill)) + tail + border("╮"),
+        ...lines.map((l) => (l === null ? border("├" + "─".repeat(inner + 2) + "┤") : border("│") + " " + pad(l, inner) + " " + border("│"))),
+        border("╰" + "─".repeat(inner + 2) + "╯"),
+    ];
+}
+/** Bordered table */
+export function grid(cols, rows, { caption, captionRight = "", minWidth = 0, stretch = cols.length - 1 } = {}) {
+    const w = cols.map((c, i) => Math.max(vw(c.title), ...rows.map((r) => vw(r[i]))));
+    const total = () => w.reduce((a, n) => a + n + 3, 1);
+    if (caption !== undefined)
+        w[stretch] += Math.max(0, vw(caption) + vw(captionRight) + 5 - total());
+    w[stretch] += Math.max(0, minWidth - total());
+    const rule = (l, m, r) => border(l + w.map((n) => "─".repeat(n + 2)).join(m) + r);
+    const row = (cells) => border("│") + cells.map((c, i) => " " + pad(c, w[i], cols[i].align) + " ").join(border("│")) + border("│");
+    const out = [];
+    if (caption !== undefined) {
+        const inner = total() - 4;
+        out.push(border("╭" + "─".repeat(total() - 2) + "╮"), border("│") + " " + pad(caption, inner - vw(captionRight)) + captionRight + " " + border("│"), rule("├", "┬", "┤"));
+    }
+    else
+        out.push(rule("╭", "┬", "╮"));
+    out.push(row(cols.map((c) => bold(c.title))), rule("├", "┼", "┤"), ...rows.map(row), rule("╰", "┴", "╯"));
+    return out;
+}
+/** s, indented to sit centered in width columns */
+export const centerIn = (s, width) => " ".repeat(Math.max(0, Math.floor((width - vw(s)) / 2))) + s;
+/** Gradient bar (cyan → green) with eighth-block precision on the leading edge */
+export function bar(fraction, width) {
+    const parts = " ▏▎▍▌▋▊▉";
+    const cells = Math.max(0, Math.min(1, fraction)) * width;
+    const full = Math.floor(cells);
+    const palette = [45, 44, 43, 42, 41, 47, 48, 49, 83, 82];
+    const shade = (i) => palette[Math.floor((i / width) * palette.length)];
+    let s = "";
+    for (let i = 0; i < full; i++)
+        s += color(`38;5;${shade(i)}`, "█");
+    if (full < width) {
+        const p = parts[Math.floor((cells - full) * 8)];
+        s += p === " " ? dim("░") : color(`38;5;${shade(full)}`, p);
+        s += dim("░".repeat(width - full - 1));
+    }
+    return s;
+}

package/dist/update.js

@@ -0,0 +1,28 @@
+// The installed version, and whether npm has a newer one.
+import { readFileSync } from "node:fs";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+let latest = null; // newer version on npm, once known
+let check;
+// numeric x.y.z compare; parseInt drops a prerelease suffix ("0-beta" → 0)
+export function newer(a, b) {
+    const x = a.split(".").map((n) => parseInt(n)), y = b.split(".").map((n) => parseInt(n));
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+}
+/** Asks npm once; later calls share that request. Best effort: offline or registry down just means no notice */
+export function checkUpdate() {
+    check ??= fetch("https://registry.npmjs.org/windscout/latest", { signal: AbortSignal.timeout(3000) })
+        .then((r) => r.json())
+        .then(({ version }) => { if (version && newer(version, VERSION))
+        latest = version; })
+        .catch(() => { });
+    return check;
+}
+/** "update available: …" with the command to run, once checkUpdate() found a newer version */
+export function updateNotice() {
+    if (!latest)
+        return null;
+    return `update available: ${VERSION} → ${latest} · run: ${process.env.npm_command === "exec" ? "npx windscout@latest" : "npm install -g windscout@latest"}`;
+}

package/dist/windscribe.js

@@ -0,0 +1,85 @@
+// The Windscribe desktop app, driven through the windscribe-cli it ships with.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { sleep } from "./time.js";
+export const CLI = "windscribe-cli";
+export const DOWNLOAD_URL = "https://windscribe.com/download";
+// the desktop app installs the CLI here and links it into /usr/bin (/usr/local/bin on macOS); use it directly if the link is missing.
+// Windows doesn't put it on PATH at all, so there the fallback is the normal case
+const DESKTOP_CLI = {
+    darwin: "/Applications/Windscribe.app/Contents/MacOS/windscribe-cli",
+    win32: join(process.env.ProgramFiles || "C:\\Program Files", "Windscribe", "windscribe-cli.exe"),
+}[process.platform] ?? "/opt/windscribe/windscribe-cli";
+let cliBin = CLI;
+// IKEv2 is offered by the macOS/Windows apps only
+export const PROTOCOLS = ["wireguard", ...(process.platform === "linux" ? [] : ["ikev2"]), "stealth", "wstunnel", "udp", "tcp"];
+// ponytail: hardcoded because `windscribe-cli locations` returns nothing on 2.24; refresh when Windscribe adds countries
+export const COUNTRIES = `US CA MX BR AR CL CO PE GB IE FR DE NL BE LU CH AT IT ES PT DK NO SE FI IS
+PL CZ SK HU RO BG GR CY TR RS HR SI BA MK AL MD UA EE LV LT IL AE AZ GE AM KZ IN JP KR
+HK SG TW ID MY TH VN PH AU NZ ZA NG KE EG`.split(/\s+/);
+// spawn, not execFile: if the app isn't running, the CLI launches it and the app inherits our stdout pipe.
+// The pipe then stays open after the CLI exits, and execFile would wait for its timeout. Settle on exit instead
+function run(args) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(cliBin, args, { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        p.stdout.on("data", (d) => (out += d));
+        const done = () => (clearTimeout(kill), p.stdout.destroy(), resolve(out));
+        const kill = setTimeout(() => p.kill(), 90_000);
+        p.on("error", (e) => (clearTimeout(kill), reject(e)));
+        p.on("close", done);
+        // the CLI's last output may still be in the pipe when it exits; read for a moment, then stop waiting
+        p.on("exit", () => setTimeout(done, 300));
+    });
+}
+/** Run a windscribe-cli command; resolves to its output */
+export async function windscribe(...args) {
+    let out;
+    try {
+        out = await run(args);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+        if (cliBin === CLI && existsSync(DESKTOP_CLI)) {
+            cliBin = DESKTOP_CLI;
+            return windscribe(...args);
+        }
+        throw new Error(`${CLI} not found. Install the Windscribe desktop app (it includes ${CLI}): ${DOWNLOAD_URL}`);
+    }
+    // the CLI mixes JSON log lines into stdout
+    return out.split("\n").filter((l) => !l.startsWith('{"tm"')).join("\n");
+}
+/** "Connected: Miami - Vice", "Connecting: …", "Disconnected", … */
+export async function connectState() {
+    // macOS marks the line with a leading "*" once connected: "*Connect state: Connected: Miami - Vice"
+    return (await windscribe("status")).match(/^\*?Connect state: (.*)$/m)?.[1].trim() ?? "";
+}
+/** Waits for the app to run and be logged in; resolves to its status output */
+export async function waitForLogin() {
+    // the first CLI call launches the app if it isn't running; give it a moment to start and restore the session
+    let status = await windscribe("status");
+    for (let i = 0; i < 15 && !status.includes("Logged in"); i++) {
+        await sleep(1000);
+        status = await windscribe("status");
+    }
+    if (!status.includes("Logged in"))
+        throw new Error("Windscribe is not logged in, or the app is not running. Open the Windscribe app and log in, then try again."
+            + `\nDon't have it? ${DOWNLOAD_URL}`);
+    return status;
+}
+export const isFirewallOn = (status) => /^Firewall state: On/m.test(status);
+let firewallChanged = false; // blockInternet() turned the firewall on, so restoreFirewall() turns it back off
+/** Turns on the app's firewall, so nothing goes online outside the VPN. False if it was on already (it then stays on) */
+export async function blockInternet() {
+    if (!/^Firewall state: Off/m.test(await windscribe("status")))
+        return false;
+    await windscribe("firewall", "on");
+    return (firewallChanged = true);
+}
+/** Puts the firewall back the way the user had it; safe to call any time, also on a crash so the internet isn't left blocked */
+export async function restoreFirewall() {
+    if (firewallChanged)
+        await windscribe("firewall", "off");
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "windscout",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "Find which Windscribe locations and protocols work from your network, ranked by speed (unofficial)",
   "type": "module",
   "bin": {
-    "windscout": "windscout.js"
+    "windscout": "dist/cli.js"
   },
   "files": [
-    "windscout.js"
+    "dist"
   ],
+  "scripts": {
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc && node -e \"fs.chmodSync('dist/cli.js', 0o755)\"",
+    "prepack": "npm run build"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -37,5 +41,9 @@
     "url": "git+https://github.com/Diercohen/windscout.git"
   },
   "homepage": "https://github.com/Diercohen/windscout#readme",
-  "bugs": "https://github.com/Diercohen/windscout/issues"
+  "bugs": "https://github.com/Diercohen/windscout/issues",
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^7.0.2"
+  }
 }