localghost 4.2.0__tar.gz → 4.3.0__tar.gz

{localghost-4.2.0 → localghost-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localghost
-Version: 4.2.0
+Version: 4.3.0
 Summary: Localghost serves local applications at friendly .localhost URLs
 Keywords: localghost,localhost,docker,compose,traefik,development,proxy
 Author: SmileyChris
@@ -73,9 +73,10 @@ port 80 available. From an application directory, run:
 uvx localghost run
 ```
 
-Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, and Docker
-Compose projects, starts the shared hub when needed, and keeps the local URL
-visible while the application runs. Press Ctrl+C to stop the application.
+Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, static
+HTML, and Docker Compose projects, starts the shared hub when needed, and
+keeps the local URL visible while the application runs. Press Ctrl+C to stop
+the application.
 
 An unconfigured Compose project asks you to save its routing setup first:
 

{localghost-4.2.0 → localghost-4.3.0}/README.md

@@ -44,9 +44,10 @@ port 80 available. From an application directory, run:
 uvx localghost run
 ```
 
-Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, and Docker
-Compose projects, starts the shared hub when needed, and keeps the local URL
-visible while the application runs. Press Ctrl+C to stop the application.
+Localghost detects Django, Vite, Astro, CakePHP, Laravel, plain PHP, static
+HTML, and Docker Compose projects, starts the shared hub when needed, and
+keeps the local URL visible while the application runs. Press Ctrl+C to stop
+the application.
 
 An unconfigured Compose project asks you to save its routing setup first:
 

{localghost-4.2.0 → localghost-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "localghost"
-version = "4.2.0"
+version = "4.3.0"
 description = "Localghost serves local applications at friendly .localhost URLs"
 readme = "README.md"
 requires-python = ">=3.11"

{localghost-4.2.0 → localghost-4.3.0}/src/localghost/cli.py

@@ -31,6 +31,8 @@ from .config import (
     write_run_config,
 )
 from .feedback import (
+    LIME,
+    MINT,
     action,
     choices,
     compose_dry_run,
@@ -41,6 +43,7 @@ from .feedback import (
     routes,
     run_plan,
     sign_off,
+    styled,
     success,
     title,
     warning,
@@ -90,11 +93,14 @@ from .tailscale import (
     API as TailscaleAPI,
 )
 from .tailscale import (
+    DNS_CONSOLE_URL,
+    MACHINES_CONSOLE_URL,
     OAUTH_CONSOLE_URL,
     POLICY_CONSOLE_URL,
     TailnetHub,
     TailscaleError,
     TailscaleState,
+    tag_in_use,
     tailnet_hubs,
 )
 from .tailscale import (
@@ -1252,7 +1258,7 @@ def _refuse_active_mapping(
             f"split DNS for .{suffix} already points at "
             f"{', '.join(active)} — another machine may be hosting this "
             "suffix. Choose a different --suffix, or pass --takeover to "
-            "replace the mapping."
+            f"replace the mapping. Split DNS is listed at {DNS_CONSOLE_URL}."
         )
 
 
@@ -1310,31 +1316,41 @@ def _resolve_tailscale_credential(
             info("Using the OAuth credential stored in the system keyring.")
             return stored.client_id, stored.client_secret
         if tag is not None:
-            details(
-                [
+            client = "Add OAuth credential"
+            if tag_in_use(tag):
+                # A device already carries the tag, so only the client is left.
+                success(f"The {tag} device tag is already allowed on the tailnet.")
+                steps = [(client, OAUTH_CONSOLE_URL)]
+                indent = ""
+            else:
+                steps = [
                     ("1. Allow the device tag", POLICY_CONSOLE_URL),
                     (
                         "   Add to the policy file",
                         f'"tagOwners": {{"{tag}": ["autogroup:admin"]}}',
                     ),
-                    ("2. Create an OAuth client", OAUTH_CONSOLE_URL),
-                    (
-                        "   Scopes",
-                        f"auth_keys (with {tag} allowed) and dns:write",
-                    ),
-                ],
-                title=(
-                    "Tailscale admin-console setup (already done? enter that "
-                    "client's id and secret)"
-                ),
+                    (f"2. {client}", OAUTH_CONSOLE_URL),
+                ]
+                indent = "   "
+            details(steps)
+            styled(
+                [
+                    (f"{indent}with scopes ", "default"),
+                    ("DNS: Write", MINT),
+                    (", ", "default"),
+                    ("Auth Keys: Write", MINT),
+                    (" (", "default"),
+                    (tag, MINT),
+                    (")", "default"),
+                ]
             )
         else:
             details(
-                [("OAuth client with dns:write", OAUTH_CONSOLE_URL)],
+                [("OAuth credential with DNS: Write", OAUTH_CONSOLE_URL)],
                 title="No OAuth credential is stored in the system keyring",
             )
     if not client_id:
-        client_id = click.prompt("Client id")
+        client_id = click.prompt("Client ID")
     if not client_secret:
         client_secret = click.prompt("Client secret", hide_input=True)
     return client_id, client_secret
@@ -1399,14 +1415,18 @@ def tailscale_unshare(
         "`localghost trust remove` on each to revoke."
     )
     info(
-        f"Remove the offline tagged localghost-{state.node_label} device in the "
-        "Tailscale admin console."
+        f"Remove the offline tagged localghost-{state.node_label} device at "
+        f"{MACHINES_CONSOLE_URL}."
     )
 
 
 def _forget_tailscale_credential() -> None:
     if delete_tailscale_credential():
         info("The OAuth credential was removed from the system keyring.")
+        info(
+            "The OAuth credential still exists in Tailscale; revoke it on the Trust "
+            f"credentials page ({OAUTH_CONSOLE_URL}) if no other machine uses it."
+        )
     else:
         info("No OAuth credential was stored in the system keyring.")
 
@@ -1515,14 +1535,17 @@ def _trust_tailnet_hub(target: str | None) -> None:
 def _share_trust(suffix: str, certificate: PublicCertificate) -> None:
     """Show another tailnet machine how to trust this hub's root."""
     action(
-        f"Trust https://*.{suffix} on other machines",
+        f"To trust https://*.{suffix} on other machines",
         f"uvx localghost tailscale trust {suffix}",
     )
     # The fingerprint is for clients that cannot ask Tailscale for the hub;
     # the plain command above is the way forward for everyone else.
     info(
-        "Without the tailscale CLI, add --fingerprint "
-        f"{certificate.fingerprint} to pin the root."
+        [
+            ("Without the tailscale CLI, add ", "default"),
+            (f"--fingerprint {certificate.fingerprint}", LIME),
+            (" to pin the root.", "default"),
+        ]
     )
 
 

{localghost-4.2.0 → localghost-4.3.0}/src/localghost/feedback.py

@@ -106,7 +106,7 @@ def details(
             console.print(Text(title, style="bold"))
         table = Table.grid(padding=(0, 1))
         table.add_column(style="bold")
-        table.add_column(style=MINT)
+        table.add_column(style=MINT, overflow="fold")
         for label, value in entries:
             table.add_row(label, value)
         console.print(table)
@@ -117,6 +117,16 @@ def details(
     console.print("\n".join(lines), soft_wrap=True)
 
 
+def styled(parts: Iterable[tuple[str, str]], *, err: bool = False) -> None:
+    """Show one line of (text, style) parts; plain text off a terminal."""
+    entries = list(parts)
+    console = _console(err)
+    if _rich_terminal(err):
+        console.print(Text.assemble(*entries))
+        return
+    console.print("".join(text for text, _ in entries), soft_wrap=True)
+
+
 def choices(title: str, items: Iterable[tuple[str, str, bool]]) -> None:
     """Show interactive choices with the same terminal hierarchy as other output."""
     entries = list(items)
@@ -141,7 +151,7 @@ def choices(title: str, items: Iterable[tuple[str, str, bool]]) -> None:
     console.print("\n".join(lines), soft_wrap=True)
 
 
-def info(message: str, *, err: bool = False) -> None:
+def info(message: str | list[tuple[str, str]], *, err: bool = False) -> None:
     _message(message, MINT, err=err)
 
 
@@ -171,7 +181,7 @@ def _labeled_block(rows: list[tuple[str, str]], *, heading: str, err: bool) -> N
         console = _console(err)
         console.print(Text.assemble(("▌ ", MINT), (heading, "bold")))
         table = Table.grid(padding=(0, 1))
-        table.add_column(style=MINT)
+        table.add_column(style=MINT, overflow="fold")
         table.add_column(style="bold")
         table.add_column()
         for label, value in rows:
@@ -269,12 +279,17 @@ def interrupt_break() -> None:
         _console(False).print()
 
 
-def _message(message: str, color: str, *, err: bool, symbol: str = "•") -> None:
+def _message(
+    message: str | list[tuple[str, str]], color: str, *, err: bool, symbol: str = "•"
+) -> None:
+    """Show a message; one given as (text, style) parts can highlight a command."""
+    parts = [message] if isinstance(message, str) else message
     console = _console(err)
     if _rich_terminal(err):
-        console.print(Text.assemble((f"{symbol} ", color), message))
+        console.print(Text.assemble((f"{symbol} ", color), *parts))
     else:
-        console.print(message, soft_wrap=True)
+        plain = "".join(part if isinstance(part, str) else part[0] for part in parts)
+        console.print(plain, soft_wrap=True)
 
 
 def _console(err: bool) -> Console:

localghost-4.3.0/src/localghost/html_server.js

@@ -0,0 +1,29 @@
+// Served by html_server.py as /__localghost/reload.js. Each event lists the
+// changed files' URL paths, one per line. Changes this page never loaded are
+// ignored; changed stylesheets it links are swapped in place, keeping scroll,
+// form and script state; anything else reloads the page.
+performance.setResourceTimingBufferSize(1000);
+new EventSource("/__localghost/reload").onmessage = (event) => {
+  const page = location.pathname;
+  const used = new Set(
+    page.endsWith("/") ? [page + "index.html", page + "index.htm"] : [page],
+  );
+  for (const entry of performance.getEntriesByType("resource")) {
+    const url = new URL(entry.name);
+    if (url.origin === location.origin) used.add(url.pathname);
+  }
+  const changed = event.data.split("\n").filter((path) => used.has(path));
+  if (!changed.length) return;
+  const links = [...document.querySelectorAll("link[rel=stylesheet]")].filter(
+    (link) => changed.includes(new URL(link.href).pathname),
+  );
+  const linked = new Set(links.map((link) => new URL(link.href).pathname));
+  if (!changed.every((path) => linked.has(path))) return location.reload();
+  for (const old of links) {
+    // The new sheet loads before the old one goes, so nothing flashes unstyled.
+    const link = old.cloneNode();
+    link.href = new URL(old.href).pathname + "?" + Date.now();
+    link.onload = () => old.remove();
+    old.after(link);
+  }
+};

localghost-4.3.0/src/localghost/html_server.py

@@ -0,0 +1,207 @@
+"""Serve the current directory, updating open pages when a file changes.
+
+Run as `python -I -m localghost.html_server PORT BIND`. HTML pages get a
+script (`/__localghost/reload.js`, from html_server.js) that holds an event
+stream open; while one is open the server checks file modification times and
+sends the paths of any that change, and the page swaps changed stylesheets or
+reloads. With no page open, nothing is checked. Dotfiles and dot-directories
+are never served.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import sys
+import threading
+import time
+import urllib.parse
+from functools import partial
+from http import HTTPStatus
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+RELOAD_PATH = "/__localghost/reload"
+# Served from a path rather than inline, so a `script-src 'self'` policy
+# still lets it run.
+RELOAD_SCRIPT_PATH = "/__localghost/reload.js"
+RELOAD_SCRIPT = Path(__file__).with_name("html_server.js").read_bytes()
+SCRIPT = f'<script src="{RELOAD_SCRIPT_PATH}"></script>'.encode()
+_BODY_END = re.compile(rb"</body\s*>", re.IGNORECASE)
+_INTERVAL = 0.5
+# A comment line this often notices a closed tab, so its check stops.
+_HEARTBEAT = 15.0
+_SKIPPED_DIRECTORY = "node_modules"
+# The stdlib server's own index names; its `index_pages` is 3.12+.
+_INDEX_PAGES = ("index.html", "index.htm")
+# Every open page shares one scan per interval rather than walking alone.
+_scan_lock = threading.Lock()
+_last_scan: tuple[Path, float, dict[str, int]] | None = None
+
+
+def snapshot(root: Path) -> dict[str, int]:
+    """Modification times of every file under root.
+
+    Dot-directories and node_modules are skipped: neither is served content
+    anyone edits by hand, and node_modules can hold a hundred thousand files.
+    """
+    times = {}
+    for directory, subdirectories, files in os.walk(root):
+        subdirectories[:] = [
+            name
+            for name in subdirectories
+            if not name.startswith(".") and name != _SKIPPED_DIRECTORY
+        ]
+        for name in files:
+            path = os.path.join(directory, name)
+            # A file removed between the listing and the stat is just gone.
+            with contextlib.suppress(OSError):
+                times[path] = os.stat(path).st_mtime_ns
+    return times
+
+
+def shared_snapshot(root: Path) -> dict[str, int]:
+    """A snapshot at most one interval old, so open pages share the walk.
+
+    A reused snapshot can only predate a change, which errs toward one extra
+    reload rather than a missed one.
+    """
+    global _last_scan
+    with _scan_lock:
+        now = time.monotonic()
+        stale = _last_scan is None or now - _last_scan[1] >= _INTERVAL
+        if stale or _last_scan[0] != root:
+            _last_scan = (root, now, snapshot(root))
+        return _last_scan[2]
+
+
+def changed_paths(
+    root: Path, before: dict[str, int], after: dict[str, int]
+) -> list[str]:
+    """URL paths of every file added, removed or modified between snapshots."""
+    changed = {
+        path
+        for path in before.keys() | after.keys()
+        if before.get(path) != after.get(path)
+    }
+    return sorted(
+        urllib.parse.quote("/" + Path(path).relative_to(root).as_posix())
+        for path in changed
+    )
+
+
+def inject(page: bytes) -> bytes:
+    """Put the reload script before the last </body>, or at the end without one."""
+    matches = list(_BODY_END.finditer(page))
+    if not matches:
+        return page + SCRIPT
+    at = matches[-1].start()
+    return page[:at] + SCRIPT + page[at:]
+
+
+class Handler(SimpleHTTPRequestHandler):
+    def do_GET(self) -> None:
+        route = self.path.split("?", 1)[0]
+        if route == RELOAD_PATH:
+            self._stream_reloads()
+            return
+        if route == RELOAD_SCRIPT_PATH:
+            self._send(RELOAD_SCRIPT, "text/javascript")
+            return
+        self._serve()
+
+    def do_HEAD(self) -> None:
+        self._serve()
+
+    def _serve(self) -> None:
+        """GET and HEAD alike, so both report the injected page's length."""
+        if self._hidden():
+            self.send_error(HTTPStatus.NOT_FOUND, "File not found")
+            return
+        page = self._html_file()
+        if page is None:
+            if self.command == "HEAD":
+                super().do_HEAD()
+            else:
+                super().do_GET()
+            return
+        try:
+            body = inject(page.read_bytes())
+        except OSError:
+            self.send_error(HTTPStatus.NOT_FOUND, "File not found")
+            return
+        # No charset: the page's own <meta charset> or BOM decides, as it
+        # would from the stdlib server. The tag is ASCII, so it fits any.
+        self._send(body, self.guess_type(str(page)))
+
+    def _send(self, body: bytes, content_type: str) -> None:
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(body)
+
+    def _hidden(self) -> bool:
+        """Does the path name a dotfile or anything inside a dot-directory?"""
+        path = urllib.parse.unquote(self.path.split("?", 1)[0].split("#", 1)[0])
+        return any(part.startswith(".") for part in path.split("/"))
+
+    def _html_file(self) -> Path | None:
+        """The HTML file this request serves, leaving redirects and listings alone."""
+        path = Path(self.translate_path(self.path))
+        if path.is_dir():
+            if not self.path.split("?", 1)[0].endswith("/"):
+                return None
+            path = next(
+                (path / name for name in _INDEX_PAGES if (path / name).is_file()),
+                path / "index.html",
+            )
+        if path.suffix.lower() in (".html", ".htm") and path.is_file():
+            return path
+        return None
+
+    def _stream_reloads(self) -> None:
+        # Before the headers, so a save the page races to see is still a change.
+        root = Path(self.directory)
+        before = shared_snapshot(root)
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        quiet_since = time.monotonic()
+        # The stream stays open: a page that swaps a stylesheet rather than
+        # reloading would otherwise miss edits made while it reconnected.
+        try:
+            while True:
+                time.sleep(_INTERVAL)
+                after = shared_snapshot(root)
+                if after != before:
+                    paths = changed_paths(root, before, after)
+                    event = "".join(f"data: {path}\n" for path in paths) + "\n"
+                    before = after
+                elif time.monotonic() - quiet_since > _HEARTBEAT:
+                    event = ": still here\n\n"
+                else:
+                    continue
+                self.wfile.write(event.encode())
+                self.wfile.flush()
+                quiet_since = time.monotonic()
+        except OSError:  # The tab closed, or the connection otherwise went.
+            return
+
+
+def main() -> None:
+    port, bind = int(sys.argv[1]), sys.argv[2]
+    handler = partial(Handler, directory=os.getcwd())
+    with (
+        ThreadingHTTPServer((bind, port), handler) as server,
+        contextlib.suppress(KeyboardInterrupt),
+    ):
+        server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

{localghost-4.2.0 → localghost-4.3.0}/src/localghost/runner.py

@@ -68,6 +68,7 @@ SUPPORTED_TYPES = (
     "cakephp",
     "laravel",
     "php",
+    "html",
 )
 RUN_TYPES = tuple(item for item in SUPPORTED_TYPES if item != "dockerfile")
 # Types the non-Compose save path can persist. Compose is handled separately
@@ -93,6 +94,7 @@ DEFAULT_PORTS = {
     "cakephp": 8765,
     "laravel": 8000,
     "php": 8080,
+    "html": 8080,
 }
 
 COMPOSE_FILENAMES = (
@@ -299,6 +301,8 @@ def build_plan(
             default_port, selected_command, working_directory = php_command(
                 project_root, port
             )
+        elif selected_type == "html":
+            default_port, selected_command = html_command(port)
         else:  # Click validates the public option; retain this for direct callers.
             raise click.ClickException(type_choices("--type"))
         wanted_port = port or default_port
@@ -383,7 +387,9 @@ def discover_type(
 
     Ambiguity is computed after filtering to `allowed`, so a type another
     command handles never blocks this one. Generic `php` defers to anything
-    stronger found further up; see `_php_project_strength`.
+    stronger found further up; see `_php_project_strength`. `html` defers
+    to any other type at the same directory, and to any but a weak `php`
+    further up: the nearer of two fallbacks wins.
     """
     if requested is not None and requested not in SUPPORTED_TYPES:
         raise click.ClickException(type_choices("--type"))
@@ -400,6 +406,10 @@ def discover_type(
     fallback: tuple[str, Path] | None = None
     for candidate in _search_path(start):
         detected = [item for item in _types_at(candidate) if item in allowed]
+        if requested is None and "html" in detected:
+            detected.remove("html")
+            if not detected and fallback is None:
+                fallback = ("html", candidate)
         if requested is not None:
             if requested in detected:
                 if requested == "php" and _php_project_strength(candidate) != "strong":
@@ -531,6 +541,8 @@ def _types_at(cwd: Path) -> list[str]:
     php = _php_type(cwd, _composer_manifest(cwd))
     if php is not None:
         detected.append(php)
+    if (cwd / "index.html").is_file():
+        detected.append("html")
     return detected
 
 
@@ -642,6 +654,18 @@ def php_command(
     )
 
 
+def html_command(requested_port: int | None) -> tuple[int, tuple[str, ...]]:
+    """Serve the directory, reloading open pages on change; see `html_server`.
+
+    -I keeps a stray module in the served directory from being imported.
+    """
+    bind = "127.0.0.1" if forwarder.available() else "0.0.0.0"
+    return (
+        requested_port or DEFAULT_PORTS["html"],
+        (sys.executable, "-I", "-m", "localghost.html_server", "{port}", bind),
+    )
+
+
 def astro_command(cwd: Path, requested_port: int | None) -> tuple[int, tuple[str, ...]]:
     manifest = _astro_manifest(cwd)
     if manifest is None:

{localghost-4.2.0 → localghost-4.3.0}/src/localghost/tailscale.py

@@ -25,8 +25,10 @@ from .paths import state_directory
 
 API_ROOT = "https://api.tailscale.com/api/v2"
 TOKEN_URL = f"{API_ROOT}/oauth/token"
-OAUTH_CONSOLE_URL = "https://login.tailscale.com/admin/settings/oauth"
-POLICY_CONSOLE_URL = "https://login.tailscale.com/admin/acls/file"
+OAUTH_CONSOLE_URL = "https://console.tailscale.com/admin/settings/trust-credentials"
+POLICY_CONSOLE_URL = "https://console.tailscale.com/admin/acls/file"
+MACHINES_CONSOLE_URL = "https://console.tailscale.com/admin/machines"
+DNS_CONSOLE_URL = "https://console.tailscale.com/admin/dns"
 KEYRING_SERVICE = "localghost-tailscale"
 _SUFFIX = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
 
@@ -328,8 +330,9 @@ class API:
                 ) from exc
             if exc.code == 403:
                 raise TailscaleError(
-                    f"the OAuth client may not create auth keys: it needs the "
-                    f"auth_keys scope with {tag} allowed ({OAUTH_CONSOLE_URL})"
+                    f"the OAuth credential may not create auth keys: it needs the "
+                    f"Auth Keys: Write scope with {tag} selected (Trust "
+                    f"credentials page, {OAUTH_CONSOLE_URL})"
                 ) from exc
             raise
         try:
@@ -341,8 +344,8 @@ class API:
     def _dns_scope_guidance(exc: APIError) -> TailscaleError:
         if exc.code == 403:
             return TailscaleError(
-                "the OAuth client lacks the dns:write scope; recreate it at "
-                f"{OAUTH_CONSOLE_URL}"
+                "the OAuth credential lacks the DNS: Write scope; recreate it on the "
+                f"Trust credentials page ({OAUTH_CONSOLE_URL})"
             )
         return exc
 
@@ -435,13 +438,8 @@ class TailnetHub:
         )  # fmt: skip
 
 
-def tailnet_hubs(tag: str = "tag:localghost") -> list[TailnetHub] | None:
-    """The online localghost gateways in this client's network map.
-
-    The names and addresses come from the coordination server through the
-    local Tailscale client, not from DNS, so split DNS cannot redirect them.
-    None means there is no tailscale CLI to ask.
-    """
+def _network_map_peers() -> dict | None:
+    """The peers in this client's network map; None without a tailscale CLI."""
     try:
         result = subprocess.run(
             ["tailscale", "status", "--json"],
@@ -454,9 +452,32 @@ def tailnet_hubs(tag: str = "tag:localghost") -> list[TailnetHub] | None:
     if result.returncode != 0:
         return None
     try:
-        peers = json.loads(result.stdout).get("Peer") or {}
+        return json.loads(result.stdout).get("Peer") or {}
     except (json.JSONDecodeError, AttributeError):
         return None
+
+
+def tag_in_use(tag: str) -> bool:
+    """Whether a device in this client's network map, online or not, has tag.
+
+    A device can only carry a tag its owner allowed, so this proves the
+    policy file once allowed it. False proves nothing: the policy may hide
+    tagged devices from this client.
+    """
+    peers = _network_map_peers() or {}
+    return any(tag in (peer.get("Tags") or ()) for peer in peers.values())
+
+
+def tailnet_hubs(tag: str = "tag:localghost") -> list[TailnetHub] | None:
+    """The online localghost gateways in this client's network map.
+
+    The names and addresses come from the coordination server through the
+    local Tailscale client, not from DNS, so split DNS cannot redirect them.
+    None means there is no tailscale CLI to ask.
+    """
+    peers = _network_map_peers()
+    if peers is None:
+        return None
     hubs = [
         TailnetHub(
             str(peer["DNSName"]).lower().removesuffix("."),