windscout 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # WindScout
 
-Find which Windscribe locations and protocols actually work from your network, ranked by speed.
+Find which Windscribe locations and protocols actually work from your network, ranked by speed. Runs on Linux, macOS and Windows.
 
 WindScout drives the official `windscribe-cli`: it connects to each country × protocol pair, measures latency and download speed through the tunnel, disconnects, and prints a ranked table.
 
@@ -8,9 +8,9 @@ WindScout drives the official `windscribe-cli`: it connects to each country × p
 
 ## Requirements
 
-- Linux or macOS
+- Linux, macOS or Windows 10/11
 - Node.js 20+
-- The [Windscribe desktop app](https://windscribe.com/download) installed, running and logged in. It includes `windscribe-cli`, which WindScout uses to control the app. Check with `windscribe-cli status`, which should show `Logged in`.
+- The [Windscribe desktop app](https://windscribe.com/download) installed, running and logged in. It includes `windscribe-cli`, which WindScout uses to control the app. Check with `windscribe-cli status`, which should show `Logged in`. On Windows the app doesn't put the CLI on `PATH`, so run `"C:\Program Files\Windscribe\windscribe-cli.exe" status` instead. WindScout finds it there on its own.
 
 ## Install
 
@@ -18,6 +18,8 @@ WindScout drives the official `windscribe-cli`: it connects to each country × p
 npm install -g windscout   # or run once with: npx windscout
 ```
 
+On startup, WindScout checks npm for a newer version. If there is one, it shows the command to update, both in the picker and after the final report.
+
 ## Usage
 
 Run `windscout` with no arguments to open the interactive picker:
@@ -49,9 +51,9 @@ Run `windscout` with no arguments to open the interactive picker:
 | `enter` | start scanning |
 | `q` | quit (during a scan: stop and show partial results; press again to force quit) |
 
-**Mouse:** click a country to select or unselect it, click a protocol or the speed-test line to toggle it, click the search box to start typing (click anywhere else to leave it), and scroll the list with the wheel. The `[ ▶ Start ]  [ All ]  [ None ]  [ Quit ]` buttons under the table do the same as their keys. This needs a terminal with mouse support, which most have.
+**Mouse:** click a country to select or unselect it, click a protocol or the speed-test line to toggle it, click the search box to start typing (click anywhere else to leave it), and scroll the list with the wheel. The `[ ▶ Start ]  [ All ]  [ None ]  [ Quit ]` buttons under the table do the same as their keys. This needs a terminal with mouse support, which most have. On Windows, use Windows Terminal; if clicks do nothing there, the keyboard does everything.
 
-Your selection is saved to `~/.config/windscout/config.json` and preselected next time.
+Your selection is saved to `~/.config/windscout/config.json` (`%USERPROFILE%\.config\windscout\config.json` on Windows) and preselected next time.
 
 While scanning, WindScout shows a progress bar, elapsed time and remaining time. It also shows what it's doing right now (connecting, measuring latency or measuring speed). The table of working locations refreshes after each country. When the scan finishes, the final report is printed to your normal terminal.
 
@@ -68,7 +70,7 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | Option | Meaning | Default |
 |---|---|---|
 | `-c, --countries` | comma-separated ISO country codes, city names or nicknames | open the picker |
-| `-p, --protocols` | comma-separated: `wireguard`, `ikev2` (macOS only), `stealth`, `wstunnel`, `udp`, `tcp`, optionally `:port` | saved, or all |
+| `-p, --protocols` | comma-separated: `wireguard`, `ikev2` (macOS and Windows), `stealth`, `wstunnel`, `udp`, `tcp`, optionally `:port` | saved, or all |
 | `-t, --timeout` | seconds to wait for each connection | 20 |
 | `-a, --all` | include failed attempts in the final table | off |
 | `-n, --no-speed` | connect-only mode: skip the download test, rank by latency | saved, or off |

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "windscout",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Find which Windscribe locations and protocols work from your network, ranked by speed (unofficial)",
   "type": "module",
-  "bin": { "windscout": "windscout.js" },
-  "files": ["windscout.js"],
-  "engines": { "node": ">=20" },
-  "os": ["linux", "darwin"],
-  "keywords": ["windscribe", "vpn", "speedtest", "wireguard", "stealth", "cli"],
+  "bin": {
+    "windscout": "windscout.js"
+  },
+  "files": [
+    "windscout.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "keywords": [
+    "windscribe",
+    "vpn",
+    "speedtest",
+    "wireguard",
+    "stealth",
+    "cli"
+  ],
   "author": "Dier Cohen <i.am.dier.cohen@gmail.com>",
   "license": "MIT"
 }

package/windscout.js

@@ -2,20 +2,25 @@
 // WindScout: find which Windscribe locations and protocols actually work from here.
 // Drives the official windscribe-cli: connects to each country/protocol pair,
 // measures latency and download speed through the tunnel, prints a ranked table.
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import readline from "node:readline";
 import { PassThrough } from "node:stream";
-import { parseArgs, promisify } from "node:util";
+import { parseArgs } from "node:util";
 
 const CLI = "windscribe-cli";
-// 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
-const DESKTOP_CLI = process.platform === "darwin"
-  ? "/Applications/Windscribe.app/Contents/MacOS/windscribe-cli"
-  : "/opt/windscribe/windscribe-cli";
+// 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";
 const DOWNLOAD_URL = "https://windscribe.com/download";
+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
+const repoLink = `\x1b]8;;${REPO_URL}\x1b\\${REPO_URL}\x1b]8;;\x1b\\`;
 let cliBin = CLI;
 // IKEv2 is offered by the macOS/Windows apps only
 const PROTOCOLS = ["wireguard", ...(process.platform === "linux" ? [] : ["ikev2"]), "stealth", "wstunnel", "udp", "tcp"];
@@ -29,30 +34,46 @@ const SPEED_URL = "https://speed.cloudflare.com/__down?bytes=10000000";
 const SPEED_SECONDS = 15;
 const CONFIG = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "windscout", "config.json");
 
-const run = promisify(execFile);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const now = () => performance.now() / 1000;
 const regionName = new Intl.DisplayNames(["en"], { type: "region" });
 const countryName = (code) => {
   try { return regionName.of(code); } catch { return code; } // city names / nicknames aren't region codes
 };
-// two regional-indicator letters render as the country's flag emoji
-const flag = (code) => /^[A-Z]{2}$/.test(code) ? String.fromCodePoint(...[...code].map((c) => 0x1f1a5 + c.charCodeAt(0))) : "  ";
+// two regional-indicator letters render as the country's flag emoji (Windows has no flag glyphs: it would show
+// two boxed letters of unpredictable width and break the table borders, so leave the slot blank there)
+const flag = (code) => process.platform !== "win32" && /^[A-Z]{2}$/.test(code) ? String.fromCodePoint(...[...code].map((c) => 0x1f1a5 + c.charCodeAt(0))) : "  ";
 let stop = 0;
 let speedTest = true; // false = connect-only mode: skip the download test, rank by latency
 
 // ---------- windscribe + measurements ----------
 
+// 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));
+  });
+}
+
 async function cli(...args) {
-  let out = "";
+  let out;
   try {
-    ({ stdout: out } = await run(cliBin, args, { timeout: 90_000 }));
+    out = await run(args);
   } catch (e) {
     if (e.code === "ENOENT") {
       if (cliBin === CLI && existsSync(DESKTOP_CLI)) return (cliBin = DESKTOP_CLI), cli(...args);
       throw new Error(`${CLI} not found. Install the Windscribe desktop app (it includes ${CLI}): ${DOWNLOAD_URL}`);
     }
-    out = e.stdout ?? "";
+    throw e;
   }
   // the CLI mixes JSON log lines into stdout
   return out.split("\n").filter((l) => !l.startsWith('{"tm"')).join("\n");
@@ -130,6 +151,26 @@ async function probe(query, protocol, timeout, onStep = () => {}) {
   }
 }
 
+// ---------- update check ----------
+
+const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
+let update = null; // newer version on npm, once known
+let updateCheck = Promise.resolve();
+// numeric x.y.z compare; parseInt drops a prerelease suffix ("0-beta" → 0)
+const 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;
+};
+// best effort: offline or registry down just means no notice
+const checkUpdate = () =>
+  fetch("https://registry.npmjs.org/windscout/latest", { signal: AbortSignal.timeout(3000) })
+    .then((r) => r.json())
+    .then(({ version }) => { if (version && newer(version, VERSION)) update = version; })
+    .catch(() => {});
+const updateNotice = () => `update available: ${VERSION} → ${update} · run: ${
+  process.env.npm_command === "exec" ? "npx windscout@latest" : "npm install -g windscout@latest"}`;
+
 // ---------- formatting ----------
 
 const color = (code, s) => (process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[${code}m${s}\x1b[0m`);
@@ -152,7 +193,7 @@ const estimate = (nCountries, nProtocols, timeout) => nCountries * nProtocols *
 
 // visible width: ANSI codes take no space; flags and emoji (🔍) take 2 columns. text symbols like ▶ ★ stay 1
 const vw = (s) =>
-  [...s.replace(/\x1b\[[0-9;]*m/g, "").replace(/[\u{1F1E6}-\u{1F1FF}]{2}|[\u{1F300}-\u{1FAFF}]/gu, "xx")].length;
+  [...s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g, "").replace(/[\u{1F1E6}-\u{1F1FF}]{2}|[\u{1F300}-\u{1FAFF}]/gu, "xx")].length;
 // align: falsy = left, true = right, "center"
 const pad = (s, n, align = false) => {
   const gap = Math.max(0, n - vw(s));
@@ -281,8 +322,13 @@ const input = new PassThrough();
 readline.emitKeypressEvents(input);
 // SGR mouse report: ESC [ < button ; col ; row (M = press, m = release); 64/65 = wheel up/down
 // ponytail: assumes a report never straddles two reads, true for terminals in practice
+let link = null; // where draw() last put the repo link: { y, x }
+const openUrl = (url) =>
+  spawn({ darwin: "open", win32: "explorer" }[process.platform] ?? "xdg-open", [url], { stdio: "ignore", detached: true })
+    .on("error", () => {}).unref();
 const onData = (buf) => {
   const rest = buf.toString().replace(/\x1b\[<(\d+);(\d+);(\d+)([Mm])/g, (_, b, x, y, kind) => {
+    if (link && kind === "M" && b === "0" && y - 1 === link.y && x - 1 >= link.x && x - 1 < link.x + REPO_URL.length) openUrl(REPO_URL);
     input.emit("mouse", { button: Number(b), x: Number(x) - 1, y: Number(y) - 1, press: kind === "M" });
     return "";
   });
@@ -316,6 +362,8 @@ function draw(lines) {
   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;;"))) };
   out.write("\x1b[H" + screen.map((l) => l + "\x1b[K").join("\n") + "\x1b[J");
   return { left: left.length, top };
 }
@@ -354,7 +402,7 @@ function pick(saved, timeout) {
     const render = () => {
       const rows = out.rows || 24;
       const list = visible();
-      const height = Math.max(3, rows - 17);
+      const height = Math.max(3, rows - 19 - (update ? 1 : 0));
       cursor = Math.max(0, Math.min(cursor, list.length - 1));
       if (cursor < top) top = cursor;
       if (cursor >= top + height) top = cursor - height + 1;
@@ -403,6 +451,8 @@ function pick(saved, timeout) {
       ];
       lines.splice(head.length + table.length + 1, 0, centerIn(buttonLine, width), "");
       if (message) lines.push(centerIn(yellow(message), width));
+      lines.push("", centerIn(dim(repoLink), width));
+      if (update) lines.push(centerIn(yellow(updateNotice()), width));
       const at = draw(lines);
 
       // click map, in screen coordinates
@@ -429,7 +479,10 @@ function pick(saved, timeout) {
       };
     };
 
+    let closed = false;
+    updateCheck.then(() => update && !closed && render()); // the check usually lands after the first draw
     const finish = (value) => {
+      closed = true;
       out.off("resize", render);
       input.removeAllListeners("keypress");
       input.removeAllListeners("mouse");
@@ -554,7 +607,7 @@ async function scan(countries, protocols, timeout, tty) {
     ].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 - 20);
+    const room = Math.max(1, rows - 22);
     const tried = results.some((r) => !["no such location", "interrupted"].includes(r.status));
     const table = view === "availability"
       ? (tried ? matrix(results, protocols, { minWidth: minW, limit: room }) : [])
@@ -592,7 +645,7 @@ async function scan(countries, protocols, timeout, tty) {
       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 · q stop · q twice force quit`), width));
+    lines.push("", centerIn(dim(`tab ${view === "ranking" ? "availability" : "ranking"} view · q stop · q twice force quit`), width), "", centerIn(dim(repoLink), width));
     draw(lines);
   };
 
@@ -718,10 +771,14 @@ async function main() {
     },
   });
   if (a.help) return console.log(HELP);
+  updateCheck = checkUpdate(); // runs while the app starts and the user picks, before the VPN starts switching
   const timeout = Number(a.timeout);
   if (!(timeout > 0)) throw new Error("--timeout must be a positive number");
 
-  if (!(await cli("status")).includes("Logged in"))
+  // 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 cli("status");
+  for (let i = 0; i < 15 && !status.includes("Logged in"); i++) await sleep(1000), status = await cli("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}`);
 
@@ -744,6 +801,8 @@ async function main() {
   const results = await scan(countries, protocols, timeout, tty);
   if (stop) console.log(yellow("interrupted, showing partial results"));
   report(results, protocols, a.all);
+  await updateCheck;
+  if (update) console.error("\n" + yellow(updateNotice()));
 }
 
 main().catch((e) => {