windscout 0.3.1 → 0.4.2

package/README.md

@@ -4,6 +4,8 @@ Find which Windscribe locations and protocols actually work from your network, r
 
 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.
 
+![WindScout picking countries, scanning, and printing the availability grid and ranked results](demo.gif)
+
 > Unofficial tool, not affiliated with Windscribe.
 
 ## Requirements
@@ -27,6 +29,7 @@ Run `windscout` with no arguments to open the interactive picker:
 ```
 ╭─ WindScout ──────────────────────────────────── 2/68 selected ─╮
 │ 1 ● wireguard   2 ● stealth   3 ○ wstunnel   4 ● udp   5 ● tcp │
+│ s ○ speed test  off: connect-only, ranks by latency            │
 ╰────────────────────────────────────────────────────────────────╯
 ╭────────────────────────────────────────────────────────────────╮
 │ 🔍 an▏                                              1–16 of 18 │
@@ -51,7 +54,7 @@ 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. On Windows, use Windows Terminal; if clicks do nothing there, the keyboard does everything.
+**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; the shortcut key is underlined on screen (on the buttons, the protocol numbers and `s`). 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` (`%USERPROFILE%\.config\windscout\config.json` on Windows) and preselected next time.
 
@@ -73,25 +76,26 @@ windscout -t 40 -a                          # longer connect timeout, also list
 | `-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 |
+| `-n, --no-speed` | connect-only mode: skip the download test, rank by latency | picker: saved, or connect-only on first run; with `-c`: speed test on |
 | `-v, --version` | print the installed version, and the update command if a newer one is on npm | |
 
 ## Connect-only mode
 
-Often you only need to know **what connects**, not how fast it is. Turn the speed test off with `s` in the picker or with `--no-speed`. Each working connection is then checked with a quick latency test only. That saves about 15 s per working connection, and results are ranked by latency. The choice is remembered.
+Often you only need to know **what connects**, not how fast it is. Turn the speed test off with `s` in the picker or with `--no-speed`. Each working connection is then checked with a quick latency test only. That saves about 15 s per working connection, and results are ranked by latency. Connect-only is the default on the first run, and the choice is remembered.
 
-Both modes show an **availability grid**: one row per country, and ✓ / ✗ for each protocol (`·` = not tried yet):
+Both modes show an **availability grid**: one row per country, and ✓ / ✗ for each protocol (`·` = not tried yet). Location(s) lists each datacenter that connected, one per line, since protocols can land on different ones:
 
 ```
-╭────────────────────────────────────────────────────────────────────────╮
-│ Availability                                   2/3 countries reachable │
-├─────────────────────────┬──────────────────┬─────────┬───────────┬─────┤
-│ Country                 │ City             │ stealth │ wireguard │ tcp │
-├─────────────────────────┼──────────────────┼─────────┼───────────┼─────┤
-│ 🇩🇪 Germany              │ Frankfurt        │    ✓    │     ✓     │  ✓  │
-│ 🇳🇱 Netherlands          │ Amsterdam        │    ✓    │     ✓     │  ·  │
-│ 🇦🇪 United Arab Emirates │ Dubai            │    ✗    │     ✗     │  ✗  │
-╰─────────────────────────┴──────────────────┴─────────┴───────────┴─────╯
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ Availability                                         2/3 countries reachable │
+├─────────────────────────┬────────────────────────┬─────────┬───────────┬─────┤
+│ Country                 │ Location(s)            │ stealth │ wireguard │ tcp │
+├─────────────────────────┼────────────────────────┼─────────┼───────────┼─────┤
+│ 🇩🇪 Germany              │ Frankfurt - Castle     │    ✓    │     ✓     │  ✓  │
+│                         │ Frankfurt - Wurst      │         │           │     │
+│ 🇳🇱 Netherlands          │ Amsterdam - Tulip      │    ✓    │     ✓     │  ·  │
+│ 🇦🇪 United Arab Emirates │ Dubai                  │    ✗    │     ✗     │  ✗  │
+╰─────────────────────────┴────────────────────────┴─────────┴───────────┴─────╯
 ```
 
 While scanning, press `tab` to switch between the availability grid and the speed or latency ranking. In connect-only mode the scan starts on the availability grid.
@@ -127,9 +131,10 @@ At the end, the results, a per-protocol summary and the best pick are printed to
 
 ## Notes
 
-- **Connecting by country picks a random datacenter.** A single run tests one per country. Pass city names or nicknames with `-c` to test specific datacenters.
+- **Connecting by country picks a random datacenter.** A single run tests one per country and protocol, so different protocols may land on different datacenters. Pass city names or nicknames with `-c` to test specific datacenters.
 - **The country list is built in.** On v2.24, `windscribe-cli locations` returns nothing, so WindScout uses a fixed list of country codes. Codes Windscribe doesn't serve are skipped quickly.
 - **A full scan takes a while.** The worst case is countries × protocols × timeout. Narrow it with `-c` and `-p`.
+- **No flags in macOS Terminal.** Terminal.app draws flag emoji wider than their space, which pushes table borders out of line, so WindScout leaves them out there (as on Windows). iTerm2 and other terminals show them.
 - **Your connection changes during the scan.** WindScout connects and disconnects the VPN repeatedly, so don't run it while you need a stable connection.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windscout",
-  "version": "0.3.1",
+  "version": "0.4.2",
   "description": "Find which Windscribe locations and protocols work from your network, ranked by speed (unofficial)",
   "type": "module",
   "bin": {
@@ -23,8 +23,19 @@
     "speedtest",
     "wireguard",
     "stealth",
-    "cli"
+    "cli",
+    "censorship",
+    "firewall",
+    "unblock",
+    "vpn-speed-test",
+    "server-finder"
   ],
   "author": "Dier Cohen <i.am.dier.cohen@gmail.com>",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Diercohen/windscout.git"
+  },
+  "homepage": "https://github.com/Diercohen/windscout#readme",
+  "bugs": "https://github.com/Diercohen/windscout/issues"
 }

package/windscout.js

@@ -41,8 +41,10 @@ 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 (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))) : "  ";
+// two boxed letters of unpredictable width and break the table borders, so leave the slot blank there).
+// macOS Terminal draws flags ~half a column wider than the 2 it advances, nudging table borders right: blank there too
+const noFlags = process.platform === "win32" || process.env.TERM_PROGRAM === "Apple_Terminal";
+const flag = (code) => !noFlags && /^[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
 
@@ -175,6 +177,8 @@ const updateNotice = () => `update available: ${VERSION} → ${update} · run: $
 
 const color = (code, s) => (process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[${code}m${s}\x1b[0m`);
 const bold = (s) => color(1, s), dim = (s) => color(2, s), green = (s) => color(32, s);
+// underline off (24) instead of a full reset, so it nests inside dim/bold
+const under = (s) => (process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[4m${s}\x1b[24m`);
 const cyan = (s) => color(36, s), yellow = (s) => color(33, s), red = (s) => color(31, s);
 const fmt = (v, digits) => (v === null || v === undefined ? "-" : v.toFixed(digits));
 const list = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
@@ -269,19 +273,25 @@ function matrix(results, protocols, { minWidth = 0, limit = Infinity } = {}) {
   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).map(({ q, rs }) => {
+  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)}`,
-      seen?.location?.split(" - ")[0] || dim("-"),
-      ...protocols.map((p) => {
-        const r = rs.find((x) => x.protocol === p);
-        return !r ? dim("·") : r.status === "ok" ? green("✓") : red("✗");
-      }),
+      [
+        `${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: "City" }, ...protocols.map((p) => ({ title: p, align: "center" }))],
+    [{ title: "Country" }, { title: "Location(s)" }, ...protocols.map((p) => ({ title: p, align: "center" }))],
     rows,
     {
       caption: bold("Availability"),
@@ -409,8 +419,8 @@ function pick(saved, timeout) {
       top = Math.max(0, Math.min(top, list.length - height));
 
       const protoLine = PROTOCOLS.map((p, i) =>
-        `${dim(String(i + 1))} ${protos.has(p) ? green("● " + p) : dim("○ " + p)}`).join("   ");
-      const speedLine = `${dim("s")} ${speedTest ? green("● speed test") : dim("○ speed test")}  ${dim(speedTest
+        `${dim(under(String(i + 1)))} ${protos.has(p) ? green("● " + p) : dim("○ " + p)}`).join("   ");
+      const speedLine = `${dim(under("s"))} ${speedTest ? green("● speed test") : dim("○ speed test")}  ${dim(speedTest
         ? "ranks by download speed · adds ~15s per working connection"
         : "off: connect-only, ranks by latency")}`;
       const search = searching
@@ -425,7 +435,7 @@ function pick(saved, timeout) {
         return [`${here ? cyan("❯") : " "} ${mark}`, here ? bold(code) : dim(code), here ? bold(cyan(name)) : name];
       });
       if (!body.length) body.push(["   ", "", dim("no country matches")]);
-      const buttons = [["start", "▶ Start"], ["all", query ? "All shown" : "All"], ["none", query ? "None shown" : "None"], ["quit", "Quit"]];
+      const buttons = [["start", "▶ Start"], ["all", under("A") + (query ? "ll shown" : "ll")], ["none", under("N") + (query ? "one shown" : "one")], ["quit", under("Q") + "uit"]];
       const buttonLine = buttons.map(([id, label]) => (id === "start" ? bold(cyan(`[ ${label} ]`)) : dim(`[ ${label} ]`))).join("  ");
 
       const table = grid([{ title: "" }, { title: "Code" }, { title: "Country" }], body,
@@ -796,7 +806,7 @@ async function main() {
     if (!tty) throw new Error("no terminal for the picker: pass countries with -c");
     const saved = loadConfig();
     if (protocols && saved) saved.protocols = protocols.filter((p) => PROTOCOLS.includes(p));
-    speedTest = !a["no-speed"] && (saved?.speed ?? true);
+    speedTest = !a["no-speed"] && (saved?.speed ?? false); // first run: connect-only
     const choice = await pick(saved, timeout);
     if (!choice) return;
     countries = choice.countries;