phase 0.2: cloudflared auto-tunnel for hub --public-tunnel flag

zhub-server --public-tunnel spawns ephemeral cloudflared tunnel, prints the
generated trycloudflare.com URL. operator runs hub on laptop / phone, gets
public URL without VPS or cloudflare account.

- zhub/tunnel.py: CloudflareTunnel async wrapper around cloudflared
  subprocess. is_available() probe. start() reads stdout/stderr until
  it matches the trycloudflare.com URL pattern, returns the URL or
  raises after timeout. close() terminates the subprocess.
- zhub/server.py: --public-tunnel CLI flag. graceful fallback when
  cloudflared isn't on PATH. server runs inside an asyncio task so
  the tunnel's process can be torn down cleanly on shutdown.

usage:
    pip install 'zhub[server]'
    zhub-server --public-tunnel
    # =====================================
    #   zhub public URL:  https://random-words.trycloudflare.com
    # =====================================

publishers point to that public URL. friend's curl from anywhere works.
no port forwarding, no VPS, no cloudflare account.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Zawwarsami16

zhub/server.py

@@ -407,12 +407,47 @@ def main() -> None:
     parser.add_argument("--host", default="0.0.0.0")
     parser.add_argument("--port", default=8080, type=int)
     parser.add_argument("--log-level", default="info")
+    parser.add_argument(
+        "--public-tunnel",
+        action="store_true",
+        help="Spawn an ephemeral Cloudflare Tunnel via `cloudflared` and print the public URL.",
+    )
     args = parser.parse_args()
 
     logging.basicConfig(
         level=getattr(logging, args.log_level.upper(), logging.INFO),
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
     )
+
+    if args.public_tunnel:
+        from .tunnel import CloudflareTunnel
+        if not CloudflareTunnel.is_available():
+            print(
+                "warning: --public-tunnel requested but `cloudflared` not found on PATH.\n"
+                "         install: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/\n"
+                "         falling back to localhost-only mode."
+            )
+        else:
+            async def _run_with_tunnel() -> None:
+                tunnel = CloudflareTunnel(local_port=args.port)
+                try:
+                    url = await tunnel.start()
+                    print()
+                    print("=" * 60)
+                    print(f"  zhub public URL:  {url}")
+                    print("=" * 60)
+                    print()
+                    config = uvicorn.Config(
+                        create_app(), host=args.host, port=args.port,
+                        log_level=args.log_level,
+                    )
+                    server = uvicorn.Server(config)
+                    await server.serve()
+                finally:
+                    await tunnel.close()
+            asyncio.run(_run_with_tunnel())
+            return
+
     app = create_app()
     uvicorn.run(app, host=args.host, port=args.port, log_level=args.log_level)
 

zhub/tunnel.py

@@ -0,0 +1,89 @@
+"""
+Cloudflare Tunnel auto-config helper for the hub.
+
+If `cloudflared` is on the PATH and `--public-tunnel` is passed to the hub,
+the hub spawns an ephemeral cloudflared tunnel on startup and prints the
+public URL to stdout. No Cloudflare account required for ephemeral tunnels.
+
+For production deployment with a stable URL, use a named cloudflared tunnel
+(see the cloudflared docs) and front the hub behind it the normal way —
+this helper is for laptop / phone-side dev, not production.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import shutil
+from typing import Optional
+
+log = logging.getLogger("zhub.tunnel")
+
+URL_RE = re.compile(rb"https://[A-Za-z0-9.-]+\.trycloudflare\.com")
+
+
+class CloudflareTunnel:
+    """Wraps a cloudflared subprocess. Starts on entry, terminates on close()."""
+
+    def __init__(self, local_port: int, binary: Optional[str] = None) -> None:
+        self.local_port = local_port
+        self.binary = binary or shutil.which("cloudflared")
+        self.process: Optional[asyncio.subprocess.Process] = None
+        self.public_url: Optional[str] = None
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return shutil.which("cloudflared") is not None
+
+    async def start(self, timeout: float = 30.0) -> str:
+        """Start the tunnel. Returns the public URL when it's ready."""
+        if not self.binary:
+            raise RuntimeError(
+                "cloudflared not found on PATH. install from "
+                "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/"
+            )
+        cmd = [self.binary, "tunnel", "--url", f"http://localhost:{self.local_port}", "--no-autoupdate"]
+        log.info("starting cloudflared: %s", " ".join(cmd))
+        self.process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.STDOUT,
+        )
+        # Read stdout/stderr until we see the URL or timeout
+        url_future: asyncio.Future = asyncio.get_running_loop().create_future()
+
+        async def consume():
+            assert self.process and self.process.stdout
+            while True:
+                line = await self.process.stdout.readline()
+                if not line:
+                    break
+                m = URL_RE.search(line)
+                if m and not url_future.done():
+                    url = m.group(0).decode()
+                    url_future.set_result(url)
+                # Keep draining so the buffer doesn't fill up
+
+        consumer = asyncio.create_task(consume())
+        try:
+            self.public_url = await asyncio.wait_for(url_future, timeout=timeout)
+            log.info("tunnel up at %s", self.public_url)
+            return self.public_url
+        except asyncio.TimeoutError:
+            consumer.cancel()
+            await self.close()
+            raise RuntimeError(
+                f"cloudflared did not produce a public URL within {timeout}s — "
+                "check `cloudflared tunnel --url http://localhost:{self.local_port}` manually"
+            )
+
+    async def close(self) -> None:
+        if self.process and self.process.returncode is None:
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), timeout=5.0)
+            except asyncio.TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        self.process = None