devlinker 1.4.1__tar.gz → 1.4.3__tar.gz

{devlinker-1.4.1 → devlinker-1.4.3}/MANIFEST.in

@@ -1,3 +1,2 @@
 include devlinker/devlinker_loader_instant.html
-include devlinker/devlinker_loader_minimal.html
 include devlinker/devlinker_loader_snippet.html

{devlinker-1.4.1/devlinker.egg-info → devlinker-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlinker
-Version: 1.4.1
+Version: 1.4.3
 Summary: A lightweight proxy that combines your frontend and backend into one link for easy development and sharing.
 Author-email: Mani <mani1028@users.noreply.github.com>
 Requires-Python: >=3.7
@@ -22,6 +22,76 @@ Dynamic: license-file
 
 Dev Linker starts your local development stack and routes frontend and backend traffic through one proxy URL, with optional LAN and public sharing.
 
+## ⚡ Quick Start (2 Minutes)
+
+Install:
+
+```bash
+pip install devlinker
+```
+
+Run your apps:
+
+```bash
+# Backend (example)
+uvicorn main:app --reload
+
+# Frontend (example)
+npm run dev
+```
+
+Run DevLinker:
+
+```bash
+devlinker
+```
+
+Open:
+
+```text
+http://localhost:8001
+```
+
+Done ✅
+
+## 🧠 How DevLinker Works
+
+Request flow:
+
+```text
+Browser -> DevLinker Proxy -> Frontend or Backend
+```
+
+Routing rules:
+
+- / routes to frontend (React/Vite)
+- /api/* routes to backend (FastAPI/Flask/Node)
+
+DevLinker acts as a smart proxy and optional tunnel layer for local, LAN, and public development links.
+
+Architecture diagram:
+
+```mermaid
+flowchart LR
+     B[Browser / Mobile] --> P[DevLinker Proxy]
+     P --> F[Frontend Dev Server\nVite/React]
+     P --> A[Backend API\nFastAPI/Flask/Node]
+     P --> T[Optional Tunnel\nCloudflare/ngrok]
+```
+
+## 🎯 Use Cases
+
+- Test APIs and UI flows on mobile devices over WLAN
+- Share local work instantly with teammates using one public URL
+- Debug frontend-backend integration from a single entrypoint
+- Reduce CORS/preflight issues during development
+
+## 🖼️ Demo & Screenshots
+
+- Terminal startup output: add screenshot at docs/images/terminal-startup.png
+- Browser app via proxy: add screenshot at docs/images/browser-proxy.png
+- Public URL share demo: add screenshot at docs/images/public-url.png
+
 
 ## Features
 
@@ -36,6 +106,8 @@ Dev Linker starts your local development stack and routes frontend and backend t
 - 🌍 **Public Sharing:** Share your local dev environment instantly with `--url` (startup) or `devlinker share` (runtime, no restart).
 - 🔄 **Dynamic Tunnel Control:** `devlinker unshare` disables public tunnel at runtime.
 - 📡 **WLAN Sharing:** Prints LAN URL for same-network device access.
+- 🔒 **Secure Token Linking:** Optional token gate for LAN/public access with `DEVLINKER_LINK_TOKEN`.
+- 📊 **Browser API Logs Dashboard:** Open `/__devlinker/dashboard` for lightweight live API visibility.
 - 🧑‍💻 **Interactive CLI:** Modern, colorized, emoji-rich terminal UX for all commands.
 - 🧩 **Zero Config:** Works out-of-the-box for most FastAPI, Flask, Vite, and Docker projects.
 - 🧪 **Runtime Smoke Test:** Built-in test for end-to-end proxy validation.
@@ -58,6 +130,7 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker support` — Show UPI support QR code in terminal
 - `devlinker --url` — Start with public tunnel (Cloudflare/ngrok)
 - `devlinker share` — Enable public tunnel at runtime (no restart)
+- `devlinker share --proxy-port 18000` — Enable public tunnel for a custom proxy port
 - `devlinker unshare` — Disable public tunnel at runtime
 - `devlinker doctor` — Diagnose issues, see categorized problems and fixes
 - `devlinker fix` — Auto-fix common issues (env, API paths, config)
@@ -70,6 +143,30 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker --debug` — Enable debug mode (turns on live API request logger)
 - `devlinker --version` — Show version
 
+Security token (optional):
+
+```bash
+set DEVLINKER_LINK_TOKEN=your-secret-token
+devlinker --url
+```
+
+When enabled, LAN/public requests must include one of:
+- query param `dl_token=...`
+- header `X-DevLinker-Token: ...`
+- header `Authorization: Bearer ...`
+
+Built-in API logs dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/dashboard
+```
+
+JSON stream endpoint used by the dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/logs
+```
+
 ## Project Structure
 
 ```text
@@ -182,14 +279,16 @@ devlinker --docker
 
 ## Tunnel and Sharing Modes
 
-By default, DevLinker starts **fast local proxy only** (no tunnel). To enable a public tunnel, use the `--url` flag:
+By default, DevLinker starts **fast local proxy only** (no tunnel). It prints a LAN URL when it can detect a local network interface, and you can share that link with devices on the same Wi-Fi/LAN.
+
+For access from another network, start with a public tunnel using the `--url` flag:
 
 
 ```bash
 devlinker --url
 ```
 
-This will start the proxy and open a public tunnel (Cloudflare or ngrok). The output will show:
+This starts the proxy and opens a public tunnel (Cloudflare or ngrok). The output will show:
 
 ```text
 🌍 Enabling public tunnel...
@@ -200,6 +299,20 @@ This will start the proxy and open a public tunnel (Cloudflare or ngrok). The ou
 ℹ Share this link with collaborators.
 ```
 
+If you already started DevLinker and want to turn on sharing without restarting, use:
+
+```bash
+devlinker share
+```
+
+If you use a custom proxy port, pass it explicitly:
+
+```bash
+devlinker share --proxy-port 18000
+```
+
+If your friend is on the same Wi-Fi/LAN, use the printed LAN URL like `http://192.168.x.x:<proxy-port>`. If they are outside your network, use the public tunnel URL instead.
+
 To force tunnel off (even if --url is passed):
 
 ```bash

{devlinker-1.4.1 → devlinker-1.4.3}/README.md

@@ -2,6 +2,76 @@
 
 Dev Linker starts your local development stack and routes frontend and backend traffic through one proxy URL, with optional LAN and public sharing.
 
+## ⚡ Quick Start (2 Minutes)
+
+Install:
+
+```bash
+pip install devlinker
+```
+
+Run your apps:
+
+```bash
+# Backend (example)
+uvicorn main:app --reload
+
+# Frontend (example)
+npm run dev
+```
+
+Run DevLinker:
+
+```bash
+devlinker
+```
+
+Open:
+
+```text
+http://localhost:8001
+```
+
+Done ✅
+
+## 🧠 How DevLinker Works
+
+Request flow:
+
+```text
+Browser -> DevLinker Proxy -> Frontend or Backend
+```
+
+Routing rules:
+
+- / routes to frontend (React/Vite)
+- /api/* routes to backend (FastAPI/Flask/Node)
+
+DevLinker acts as a smart proxy and optional tunnel layer for local, LAN, and public development links.
+
+Architecture diagram:
+
+```mermaid
+flowchart LR
+     B[Browser / Mobile] --> P[DevLinker Proxy]
+     P --> F[Frontend Dev Server\nVite/React]
+     P --> A[Backend API\nFastAPI/Flask/Node]
+     P --> T[Optional Tunnel\nCloudflare/ngrok]
+```
+
+## 🎯 Use Cases
+
+- Test APIs and UI flows on mobile devices over WLAN
+- Share local work instantly with teammates using one public URL
+- Debug frontend-backend integration from a single entrypoint
+- Reduce CORS/preflight issues during development
+
+## 🖼️ Demo & Screenshots
+
+- Terminal startup output: add screenshot at docs/images/terminal-startup.png
+- Browser app via proxy: add screenshot at docs/images/browser-proxy.png
+- Public URL share demo: add screenshot at docs/images/public-url.png
+
 
 ## Features
 
@@ -16,6 +86,8 @@ Dev Linker starts your local development stack and routes frontend and backend t
 - 🌍 **Public Sharing:** Share your local dev environment instantly with `--url` (startup) or `devlinker share` (runtime, no restart).
 - 🔄 **Dynamic Tunnel Control:** `devlinker unshare` disables public tunnel at runtime.
 - 📡 **WLAN Sharing:** Prints LAN URL for same-network device access.
+- 🔒 **Secure Token Linking:** Optional token gate for LAN/public access with `DEVLINKER_LINK_TOKEN`.
+- 📊 **Browser API Logs Dashboard:** Open `/__devlinker/dashboard` for lightweight live API visibility.
 - 🧑‍💻 **Interactive CLI:** Modern, colorized, emoji-rich terminal UX for all commands.
 - 🧩 **Zero Config:** Works out-of-the-box for most FastAPI, Flask, Vite, and Docker projects.
 - 🧪 **Runtime Smoke Test:** Built-in test for end-to-end proxy validation.
@@ -38,6 +110,7 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker support` — Show UPI support QR code in terminal
 - `devlinker --url` — Start with public tunnel (Cloudflare/ngrok)
 - `devlinker share` — Enable public tunnel at runtime (no restart)
+- `devlinker share --proxy-port 18000` — Enable public tunnel for a custom proxy port
 - `devlinker unshare` — Disable public tunnel at runtime
 - `devlinker doctor` — Diagnose issues, see categorized problems and fixes
 - `devlinker fix` — Auto-fix common issues (env, API paths, config)
@@ -50,6 +123,30 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker --debug` — Enable debug mode (turns on live API request logger)
 - `devlinker --version` — Show version
 
+Security token (optional):
+
+```bash
+set DEVLINKER_LINK_TOKEN=your-secret-token
+devlinker --url
+```
+
+When enabled, LAN/public requests must include one of:
+- query param `dl_token=...`
+- header `X-DevLinker-Token: ...`
+- header `Authorization: Bearer ...`
+
+Built-in API logs dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/dashboard
+```
+
+JSON stream endpoint used by the dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/logs
+```
+
 ## Project Structure
 
 ```text
@@ -162,14 +259,16 @@ devlinker --docker
 
 ## Tunnel and Sharing Modes
 
-By default, DevLinker starts **fast local proxy only** (no tunnel). To enable a public tunnel, use the `--url` flag:
+By default, DevLinker starts **fast local proxy only** (no tunnel). It prints a LAN URL when it can detect a local network interface, and you can share that link with devices on the same Wi-Fi/LAN.
+
+For access from another network, start with a public tunnel using the `--url` flag:
 
 
 ```bash
 devlinker --url
 ```
 
-This will start the proxy and open a public tunnel (Cloudflare or ngrok). The output will show:
+This starts the proxy and opens a public tunnel (Cloudflare or ngrok). The output will show:
 
 ```text
 🌍 Enabling public tunnel...
@@ -180,6 +279,20 @@ This will start the proxy and open a public tunnel (Cloudflare or ngrok). The ou
 ℹ Share this link with collaborators.
 ```
 
+If you already started DevLinker and want to turn on sharing without restarting, use:
+
+```bash
+devlinker share
+```
+
+If you use a custom proxy port, pass it explicitly:
+
+```bash
+devlinker share --proxy-port 18000
+```
+
+If your friend is on the same Wi-Fi/LAN, use the printed LAN URL like `http://192.168.x.x:<proxy-port>`. If they are outside your network, use the public tunnel URL instead.
+
 To force tunnel off (even if --url is passed):
 
 ```bash

{devlinker-1.4.1 → devlinker-1.4.3}/devlinker/main.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import socket
 import sys
 import time
@@ -32,7 +33,7 @@ except ImportError:  # pragma: no cover - fallback when rich is unavailable
 
 from . import __version__
 from .detector import check_port, detect_ports, is_vite_port
-from .proxy import start_proxy
+from .proxy import start_proxy, wait_for_proxy_startup
 from .runner import detect_backend_port, start_servers
 from .tunnel import start_tunnel
 from .doctor import doctor
@@ -42,6 +43,7 @@ from .share import share, unshare
 from .config import load_config
 from .inspect import inspect
 from .monitor import monitor
+from .global_state import STATE
 
 SUPPORT_UPI_ID = "devlinker@upi"
 SUPPORT_UPI_LINK = "upi://pay?pa=devlinker@upi&pn=DevLinker&cu=INR&tn=Support%20DevLinker%20Project%20🚀"
@@ -193,6 +195,18 @@ def _with_ngrok_skip_warning(url: str) -> str:
     return urlunsplit((parts.scheme, parts.netloc, parts.path, new_query, parts.fragment))
 
 
+def _with_link_token(url: str) -> str:
+    token = os.getenv("DEVLINKER_LINK_TOKEN", "").strip()
+    if not token:
+        return url
+
+    parts = urlsplit(url)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    query["dl_token"] = token
+    new_query = urlencode(query)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, new_query, parts.fragment))
+
+
 
 def _print_summary(
     frontend_port: int | None,
@@ -589,6 +603,7 @@ def _run_proxy(
         )
 
     proxy_port = _select_proxy_port(proxy_port)
+    STATE["proxy_port"] = proxy_port
     _write_frontend_api_env(proxy_port)
 
     if not live_status:
@@ -606,8 +621,10 @@ def _run_proxy(
         enable_debug_logs=debug,
     )
 
-    # Allow proxy thread to bind before opening tunnel.
-    time.sleep(1)
+    if not wait_for_proxy_startup(timeout=5.0):
+        raise click.ClickException(
+            f"Proxy failed to start on port {proxy_port}. Check whether the port is already in use."
+        )
 
     if live_status:
         live_status.update("Proxy", f"✔ Active ({proxy_port})", style="green")
@@ -616,12 +633,14 @@ def _run_proxy(
     if lan_enabled:
         local_ips = _get_local_ips()
         if local_ips:
-            wlan_url = f"http://{local_ips[0]}:{proxy_port}"
+            wlan_url = _with_link_token(f"http://{local_ips[0]}:{proxy_port}")
             _ui_status("✔", f"LAN share: {wlan_url}", style="green")
             if len(local_ips) > 1:
-                alternative_urls = ", ".join(f"http://{ip}:{proxy_port}" for ip in local_ips[1:])
+                alternative_urls = ", ".join(_with_link_token(f"http://{ip}:{proxy_port}") for ip in local_ips[1:])
                 _ui_status("ℹ", f"Alternate LAN URLs: {alternative_urls}", style="blue")
             _ui_status("ℹ", "Share with teammates on the same WiFi/LAN.", style="blue")
+            if os.getenv("DEVLINKER_LINK_TOKEN", "").strip():
+                _ui_status("🔒", "Token protection is ON for LAN/public traffic.", style="green")
             _ui_status(
                 "⚠",
                 "Camera/mic may be blocked on HTTP. Use localhost or --url for HTTPS.",
@@ -653,7 +672,7 @@ def _run_proxy(
         try:
             _ui_status("🌍", "Enabling public tunnel...", style="green")
             provider, public_url = start_tunnel(proxy_port)
-            warning_free_url = _with_ngrok_skip_warning(public_url)
+            warning_free_url = _with_link_token(_with_ngrok_skip_warning(public_url))
             provider_label = "Cloudflare" if provider == "cloudflare" else "ngrok"
             _ui_status("✔", f"Tunnel provider: {provider_label}", style="blue")
             _ui_status("✔", f"Public URL: {warning_free_url}", style="cyan")

{devlinker-1.4.1 → devlinker-1.4.3}/devlinker/proxy.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import os
 import time
 from typing import Dict, Optional
 from urllib.parse import urlencode
@@ -9,7 +10,7 @@ import httpx
 import uvicorn
 import websockets
 from fastapi import FastAPI, Request, Response, WebSocket
-from fastapi.responses import PlainTextResponse
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
 from starlette.websockets import WebSocketDisconnect
 from websockets.exceptions import ConnectionClosed
 
@@ -24,6 +25,8 @@ _recent_lock = threading.Lock()
 _printed_fixes = set()
 _printed_live_header = False
 LIVE_REQUEST_LOGGING_ENABLED = False
+MAX_RECENT_REQUESTS = 200
+PROXY_READY_EVENT = threading.Event()
 
 
 def _format_request_context(path: str, method: str | None, status: int, target: str) -> str:
@@ -54,8 +57,34 @@ def _print_live_request_line(method: str, path: str, status: int, elapsed_ms: fl
             _printed_live_header = True
     print(f"{method.upper():<6} {path:<24} {status:<3} {elapsed_ms:.0f}ms")
 
+
+def _configured_link_token() -> str | None:
+    token = os.getenv("DEVLINKER_LINK_TOKEN", "").strip()
+    return token or None
+
+
+def _extract_presented_token(headers: Dict[str, str], query_params) -> str | None:
+    query_token = query_params.get("dl_token")
+    if query_token:
+        return query_token
+    direct_header = headers.get("x-devlinker-token", "").strip()
+    if direct_header:
+        return direct_header
+    auth_header = headers.get("authorization", "").strip()
+    bearer_prefix = "Bearer "
+    if auth_header.startswith(bearer_prefix):
+        return auth_header[len(bearer_prefix):].strip()
+    return None
+
+
+def _is_link_token_valid(expected_token: str | None, headers: Dict[str, str], query_params) -> bool:
+    if not expected_token:
+        return True
+    presented = _extract_presented_token(headers, query_params)
+    return bool(presented) and presented == expected_token
+
 class RequestInspector:
-    def analyze(self, path, status, target, method=None, response_text=None):
+    def analyze(self, path, status, target, method=None, response_text=None, elapsed_ms=None):
         warnings = []
         normalized_method = method.upper() if method else ""
         is_root_document_request = path == "/" and normalized_method in {"GET", "HEAD", "OPTIONS"}
@@ -87,14 +116,24 @@ class RequestInspector:
                 warnings.append(issue)
         # Log request for inspector
         with _recent_lock:
-            _recent_requests.append({"path": path, "status": status, "target": target})
-            if len(_recent_requests) > 50:
+            _recent_requests.append(
+                {
+                    "ts": int(time.time() * 1000),
+                    "method": normalized_method or "GET",
+                    "path": path,
+                    "status": status,
+                    "target": target,
+                    "latency_ms": round(float(elapsed_ms), 1) if elapsed_ms is not None else None,
+                }
+            )
+            if len(_recent_requests) > MAX_RECENT_REQUESTS:
                 _recent_requests.pop(0)
         return warnings
 
 FRONTEND: Optional[int] = None
 BACKEND: Optional[int] = None
 HTTP_CLIENT: Optional[httpx.AsyncClient] = None
+UPSTREAM_HOST_CANDIDATES: tuple[str, ...] = ("127.0.0.1", "localhost", "::1")
 
 HOP_BY_HOP_HEADERS = {
     "connection",
@@ -137,6 +176,7 @@ def _apply_cors_headers(headers: Dict[str, str], request: Request) -> Dict[str,
 async def _on_startup() -> None:
     global HTTP_CLIENT
     HTTP_CLIENT = httpx.AsyncClient(timeout=15.0, follow_redirects=False)
+    PROXY_READY_EVENT.set()
 
 
 @app.on_event("shutdown")
@@ -145,6 +185,7 @@ async def _on_shutdown() -> None:
     if HTTP_CLIENT is not None:
         await HTTP_CLIENT.aclose()
         HTTP_CLIENT = None
+    PROXY_READY_EVENT.clear()
 
 
 def _connection_header_tokens(headers: Dict[str, str]) -> set[str]:
@@ -188,22 +229,38 @@ def _target_port(path: str) -> Optional[int]:
     return FRONTEND
 
 
-def _build_target_http_url(port: int, path: str, query_params: list[tuple[str, str]]) -> str:
+def _format_host_for_url(host: str) -> str:
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def _build_target_http_url(
+    port: int,
+    path: str,
+    query_params: list[tuple[str, str]],
+    host: str = "127.0.0.1",
+) -> str:
     query_string = urlencode(query_params, doseq=True)
-    base_url = f"http://127.0.0.1:{port}{path}"
+    base_url = f"http://{_format_host_for_url(host)}:{port}{path}"
     if not query_string:
         return base_url
     return f"{base_url}?{query_string}"
 
 
-def _build_target_ws_url(port: int, path: str, query: str) -> str:
-    base_url = f"ws://127.0.0.1:{port}{path}"
+def _build_target_ws_url(port: int, path: str, query: str, host: str = "127.0.0.1") -> str:
+    base_url = f"ws://{_format_host_for_url(host)}:{port}{path}"
     if not query:
         return base_url
     return f"{base_url}?{query}"
 
 
 async def _forward_http(request: Request) -> Response:
+    if request.url.path == "/__devlinker/logs":
+        return await logs_dashboard_data()
+    if request.url.path == "/__devlinker/dashboard":
+        return await logs_dashboard_page()
+
     if request.method == "OPTIONS" and request.headers.get("access-control-request-method"):
         return Response(
             status_code=204,
@@ -267,6 +324,13 @@ async def _forward_http(request: Request) -> Response:
     is_lan = mode == "lan"
     is_public = mode == "public"
     is_secure = _is_secure_request(request, host_header)
+    required_link_token = _configured_link_token()
+    if (is_lan or is_public) and not _is_link_token_valid(required_link_token, dict(request.headers), request.query_params):
+        return PlainTextResponse(
+            "Unauthorized link: include dl_token query or X-DevLinker-Token header.",
+            status_code=401,
+            headers=_apply_cors_headers(_apply_security_headers({}), request),
+        )
     is_instant = request.headers.get("x-devlinker-instant") == "1"
     accept_header = request.headers.get("accept", "")
     sec_fetch_dest = request.headers.get("sec-fetch-dest", "")
@@ -338,16 +402,33 @@ async def _forward_http(request: Request) -> Response:
 
     payload = await request.body()
     query_params = list(request.query_params.multi_items())
-    target_url = _build_target_http_url(target_port, request.url.path, query_params)
     started_at = time.perf_counter()
 
     try:
-        upstream = await HTTP_CLIENT.request(
-            method=request.method,
-            url=target_url,
-            content=payload,
-            headers=_filter_request_headers(dict(request.headers)),
-        )
+        upstream = None
+        last_exc: httpx.RequestError | None = None
+        for upstream_host in UPSTREAM_HOST_CANDIDATES:
+            target_url = _build_target_http_url(
+                target_port,
+                request.url.path,
+                query_params,
+                host=upstream_host,
+            )
+            try:
+                upstream = await HTTP_CLIENT.request(
+                    method=request.method,
+                    url=target_url,
+                    content=payload,
+                    headers=_filter_request_headers(dict(request.headers)),
+                )
+                break
+            except httpx.RequestError as exc:
+                last_exc = exc
+
+        if upstream is None and last_exc is not None:
+            raise last_exc
+        if upstream is None:
+            raise RuntimeError("Unexpected empty upstream response")
     except httpx.RequestError as exc:
         status = 502
         elapsed_ms = (time.perf_counter() - started_at) * 1000
@@ -376,7 +457,8 @@ async def _forward_http(request: Request) -> Response:
         upstream.status_code,
         target_name,
         method=request.method,
-        response_text=upstream.text
+        response_text=upstream.text,
+        elapsed_ms=elapsed_ms,
     )
     context = _format_request_context(request.url.path, request.method, upstream.status_code, target_name)
     # Only print routing warnings for error responses or /api paths
@@ -435,6 +517,11 @@ async def _forward_http(request: Request) -> Response:
 
 
 async def _proxy_websocket(websocket: WebSocket) -> None:
+    required_link_token = _configured_link_token()
+    if required_link_token and not _is_link_token_valid(required_link_token, dict(websocket.headers), websocket.query_params):
+        await websocket.close(code=1008)
+        return
+
     target_port = _target_port(websocket.url.path)
     if target_port is None:
         await websocket.close(code=1013)
@@ -529,6 +616,102 @@ async def websocket_proxy(websocket: WebSocket, path: str) -> None:  # noqa: ARG
     await _proxy_websocket(websocket)
 
 
+@app.get("/__devlinker/logs")
+async def logs_dashboard_data() -> JSONResponse:
+        with _recent_lock:
+                records = list(_recent_requests[-100:])
+        return JSONResponse({"count": len(records), "items": records})
+
+
+@app.get("/__devlinker/dashboard")
+async def logs_dashboard_page() -> HTMLResponse:
+        html = """<!doctype html>
+<html>
+<head>
+    <meta charset=\"utf-8\" />
+    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\" />
+    <title>DevLinker API Logs</title>
+    <style>
+        :root { --bg:#f4f7fb; --card:#ffffff; --ink:#0f172a; --muted:#64748b; --ok:#065f46; --warn:#92400e; --err:#991b1b; --line:#dbe3ee; }
+        body { margin:0; font-family:\"Segoe UI\",\"Trebuchet MS\",sans-serif; background: radial-gradient(circle at top left,#e7f1ff,transparent 45%), var(--bg); color:var(--ink); }
+        .wrap { max-width: 1100px; margin: 28px auto; padding: 0 16px; }
+        .card { background: var(--card); border:1px solid var(--line); border-radius:14px; box-shadow: 0 10px 25px rgba(15,23,42,.06); overflow:hidden; }
+        h1 { margin:0; font-size: 1.4rem; }
+        .head { padding: 14px 16px; display:flex; justify-content:space-between; align-items:center; border-bottom:1px solid var(--line); }
+        .meta { color:var(--muted); font-size:.9rem; }
+        table { width:100%; border-collapse: collapse; }
+        th,td { padding:10px 12px; border-bottom:1px solid var(--line); text-align:left; font-size:.9rem; }
+        th { color:var(--muted); font-weight:600; }
+        .s2 { color: var(--ok); font-weight: 700; }
+        .s4 { color: var(--warn); font-weight: 700; }
+        .s5 { color: var(--err); font-weight: 700; }
+        .path { font-family:Consolas, monospace; }
+        .empty { padding: 20px; color: var(--muted); }
+    </style>
+</head>
+<body>
+    <div class=\"wrap\">
+        <div class=\"card\">
+            <div class=\"head\">
+                <h1>API Logs Dashboard</h1>
+                <div class=\"meta\" id=\"meta\">Waiting for traffic...</div>
+            </div>
+            <div id=\"content\" class=\"empty\">No requests yet.</div>
+        </div>
+    </div>
+    <script>
+        function statusClass(code){
+            if(code >= 500) return 's5';
+            if(code >= 400) return 's4';
+            return 's2';
+        }
+        function ago(ms){
+            const d = Date.now() - ms;
+            if (d < 1000) return 'now';
+            if (d < 60000) return Math.floor(d/1000) + 's ago';
+            return Math.floor(d/60000) + 'm ago';
+        }
+        function render(items){
+            const content = document.getElementById('content');
+            const meta = document.getElementById('meta');
+            if(!items.length){
+                content.className = 'empty';
+                content.textContent = 'No requests yet.';
+                meta.textContent = 'Waiting for traffic...';
+                return;
+            }
+            const rows = items.slice().reverse().map(item => {
+                const status = Number(item.status || 0);
+                const lat = item.latency_ms == null ? '-' : item.latency_ms + 'ms';
+                return '<tr>' +
+                    '<td>' + (item.method || '-') + '</td>' +
+                    '<td class="path">' + (item.path || '-') + '</td>' +
+                    '<td><span class="' + statusClass(status) + '">' + status + '</span></td>' +
+                    '<td>' + (item.target || '-') + '</td>' +
+                    '<td>' + lat + '</td>' +
+                    '<td>' + (item.ts ? ago(item.ts) : '-') + '</td>' +
+                    '</tr>';
+            }).join('');
+            content.className = '';
+            content.innerHTML = '<table><thead><tr><th>Method</th><th>Path</th><th>Status</th><th>Target</th><th>Latency</th><th>When</th></tr></thead><tbody>' + rows + '</tbody></table>';
+            meta.textContent = items.length + ' requests captured';
+        }
+        async function tick(){
+            try{
+                const resp = await fetch('/__devlinker/logs', {cache:'no-store'});
+                const data = await resp.json();
+                render(Array.isArray(data.items) ? data.items : []);
+            }catch(_){
+            }
+        }
+        tick();
+        setInterval(tick, 1500);
+    </script>
+</body>
+</html>"""
+        return HTMLResponse(html)
+
+
 def start_proxy(
     frontend_port: Optional[int],
     backend_port: int,
@@ -540,9 +723,14 @@ def start_proxy(
     BACKEND = backend_port
     LIVE_REQUEST_LOGGING_ENABLED = enable_debug_logs
     _printed_live_header = False
+    PROXY_READY_EVENT.clear()
 
     thread = threading.Thread(
         target=lambda: uvicorn.run(app, host="0.0.0.0", port=proxy_port, log_level="warning"),
         daemon=True,
     )
     thread.start()
+
+
+def wait_for_proxy_startup(timeout: float = 5.0) -> bool:
+    return PROXY_READY_EVENT.wait(timeout)

devlinker-1.4.3/devlinker/share.py

@@ -0,0 +1,64 @@
+import click
+import requests
+
+from devlinker.global_state import STATE
+from devlinker.tunnel import start_tunnel
+
+
+_COMMON_PROXY_PORTS = (8000, 8001, 8002, 8003, 8004, 8005, 8006, 8007, 8008, 8009, 8010, 18000)
+
+
+def _is_devlinker_proxy(port: int) -> bool:
+    try:
+        response = requests.get(f"http://127.0.0.1:{port}/__devlinker/dashboard", timeout=0.5)
+    except requests.RequestException:
+        return False
+    return response.status_code == 200 and "API Logs Dashboard" in response.text
+
+
+def _resolve_proxy_port(requested_port: int | None) -> int:
+    if requested_port is not None:
+        if _is_devlinker_proxy(requested_port):
+            return requested_port
+        raise click.ClickException(
+            f"No DevLinker proxy is running on port {requested_port}. Start devlinker first, or pass the correct --proxy-port."
+        )
+
+    for candidate in _COMMON_PROXY_PORTS:
+        if _is_devlinker_proxy(candidate):
+            return candidate
+
+    raise click.ClickException(
+        "No running DevLinker proxy was found. Start devlinker first, or pass --proxy-port <port>."
+    )
+
+@click.command()
+@click.option("--proxy-port", type=int, default=None, help="Proxy port to tunnel. Auto-detect when omitted.")
+def share(proxy_port: int | None):
+    """Enable public tunnel at runtime (no restart)."""
+    if STATE["tunnel"]:
+        click.secho("⚠️ Already shared", fg="yellow")
+        return
+    try:
+        resolved_proxy_port = _resolve_proxy_port(proxy_port)
+        STATE["proxy_port"] = resolved_proxy_port
+        provider, url = start_tunnel(resolved_proxy_port)
+        STATE["tunnel"] = url
+        click.secho("\n🌍 Public Sharing Enabled\n" + ("─" * 24), fg="green", bold=True)
+        click.secho("✔ Tunnel connected", fg="green")
+        click.secho(f"\nPublic URL:\n{url}\n", fg="cyan", bold=True)
+        click.secho("📤 Share this link with your team", fg="magenta")
+    except Exception as exc:
+        click.secho(f"[WARN] Tunnel failed: {exc}", fg="red")
+        click.secho("[INFO] Next step: install cloudflared or configure ngrok auth.", fg="yellow")
+
+@click.command()
+def unshare():
+    """Disable public tunnel at runtime (no restart)."""
+    if not STATE["tunnel"]:
+        click.secho("⚠️ No active tunnel", fg="yellow")
+        return
+    from devlinker.tunnel import stop_tunnel
+    stop_tunnel()
+    STATE["tunnel"] = None
+    click.secho("🛑 Sharing stopped", fg="red", bold=True)

{devlinker-1.4.1 → devlinker-1.4.3/devlinker.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlinker
-Version: 1.4.1
+Version: 1.4.3
 Summary: A lightweight proxy that combines your frontend and backend into one link for easy development and sharing.
 Author-email: Mani <mani1028@users.noreply.github.com>
 Requires-Python: >=3.7
@@ -22,6 +22,76 @@ Dynamic: license-file
 
 Dev Linker starts your local development stack and routes frontend and backend traffic through one proxy URL, with optional LAN and public sharing.
 
+## ⚡ Quick Start (2 Minutes)
+
+Install:
+
+```bash
+pip install devlinker
+```
+
+Run your apps:
+
+```bash
+# Backend (example)
+uvicorn main:app --reload
+
+# Frontend (example)
+npm run dev
+```
+
+Run DevLinker:
+
+```bash
+devlinker
+```
+
+Open:
+
+```text
+http://localhost:8001
+```
+
+Done ✅
+
+## 🧠 How DevLinker Works
+
+Request flow:
+
+```text
+Browser -> DevLinker Proxy -> Frontend or Backend
+```
+
+Routing rules:
+
+- / routes to frontend (React/Vite)
+- /api/* routes to backend (FastAPI/Flask/Node)
+
+DevLinker acts as a smart proxy and optional tunnel layer for local, LAN, and public development links.
+
+Architecture diagram:
+
+```mermaid
+flowchart LR
+     B[Browser / Mobile] --> P[DevLinker Proxy]
+     P --> F[Frontend Dev Server\nVite/React]
+     P --> A[Backend API\nFastAPI/Flask/Node]
+     P --> T[Optional Tunnel\nCloudflare/ngrok]
+```
+
+## 🎯 Use Cases
+
+- Test APIs and UI flows on mobile devices over WLAN
+- Share local work instantly with teammates using one public URL
+- Debug frontend-backend integration from a single entrypoint
+- Reduce CORS/preflight issues during development
+
+## 🖼️ Demo & Screenshots
+
+- Terminal startup output: add screenshot at docs/images/terminal-startup.png
+- Browser app via proxy: add screenshot at docs/images/browser-proxy.png
+- Public URL share demo: add screenshot at docs/images/public-url.png
+
 
 ## Features
 
@@ -36,6 +106,8 @@ Dev Linker starts your local development stack and routes frontend and backend t
 - 🌍 **Public Sharing:** Share your local dev environment instantly with `--url` (startup) or `devlinker share` (runtime, no restart).
 - 🔄 **Dynamic Tunnel Control:** `devlinker unshare` disables public tunnel at runtime.
 - 📡 **WLAN Sharing:** Prints LAN URL for same-network device access.
+- 🔒 **Secure Token Linking:** Optional token gate for LAN/public access with `DEVLINKER_LINK_TOKEN`.
+- 📊 **Browser API Logs Dashboard:** Open `/__devlinker/dashboard` for lightweight live API visibility.
 - 🧑‍💻 **Interactive CLI:** Modern, colorized, emoji-rich terminal UX for all commands.
 - 🧩 **Zero Config:** Works out-of-the-box for most FastAPI, Flask, Vite, and Docker projects.
 - 🧪 **Runtime Smoke Test:** Built-in test for end-to-end proxy validation.
@@ -58,6 +130,7 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker support` — Show UPI support QR code in terminal
 - `devlinker --url` — Start with public tunnel (Cloudflare/ngrok)
 - `devlinker share` — Enable public tunnel at runtime (no restart)
+- `devlinker share --proxy-port 18000` — Enable public tunnel for a custom proxy port
 - `devlinker unshare` — Disable public tunnel at runtime
 - `devlinker doctor` — Diagnose issues, see categorized problems and fixes
 - `devlinker fix` — Auto-fix common issues (env, API paths, config)
@@ -70,6 +143,30 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker --debug` — Enable debug mode (turns on live API request logger)
 - `devlinker --version` — Show version
 
+Security token (optional):
+
+```bash
+set DEVLINKER_LINK_TOKEN=your-secret-token
+devlinker --url
+```
+
+When enabled, LAN/public requests must include one of:
+- query param `dl_token=...`
+- header `X-DevLinker-Token: ...`
+- header `Authorization: Bearer ...`
+
+Built-in API logs dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/dashboard
+```
+
+JSON stream endpoint used by the dashboard:
+
+```text
+http://localhost:<proxy-port>/__devlinker/logs
+```
+
 ## Project Structure
 
 ```text
@@ -182,14 +279,16 @@ devlinker --docker
 
 ## Tunnel and Sharing Modes
 
-By default, DevLinker starts **fast local proxy only** (no tunnel). To enable a public tunnel, use the `--url` flag:
+By default, DevLinker starts **fast local proxy only** (no tunnel). It prints a LAN URL when it can detect a local network interface, and you can share that link with devices on the same Wi-Fi/LAN.
+
+For access from another network, start with a public tunnel using the `--url` flag:
 
 
 ```bash
 devlinker --url
 ```
 
-This will start the proxy and open a public tunnel (Cloudflare or ngrok). The output will show:
+This starts the proxy and opens a public tunnel (Cloudflare or ngrok). The output will show:
 
 ```text
 🌍 Enabling public tunnel...
@@ -200,6 +299,20 @@ This will start the proxy and open a public tunnel (Cloudflare or ngrok). The ou
 ℹ Share this link with collaborators.
 ```
 
+If you already started DevLinker and want to turn on sharing without restarting, use:
+
+```bash
+devlinker share
+```
+
+If you use a custom proxy port, pass it explicitly:
+
+```bash
+devlinker share --proxy-port 18000
+```
+
+If your friend is on the same Wi-Fi/LAN, use the printed LAN URL like `http://192.168.x.x:<proxy-port>`. If they are outside your network, use the public tunnel URL instead.
+
 To force tunnel off (even if --url is passed):
 
 ```bash

{devlinker-1.4.1 → devlinker-1.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devlinker"
-version = "1.4.1"
+version = "1.4.3"
 description = "A lightweight proxy that combines your frontend and backend into one link for easy development and sharing."
 authors = [
     { name = "Mani", email = "mani1028@users.noreply.github.com" }

devlinker-1.4.1/devlinker/share.py

@@ -1,32 +0,0 @@
-
-import click
-from devlinker.global_state import STATE
-from devlinker.tunnel import start_tunnel
-
-@click.command()
-def share():
-    """Enable public tunnel at runtime (no restart)."""
-    if STATE["tunnel"]:
-        click.secho("⚠️ Already shared", fg="yellow")
-        return
-    try:
-        provider, url = start_tunnel(STATE["proxy_port"])
-        STATE["tunnel"] = url
-        click.secho("\n🌍 Public Sharing Enabled\n" + ("─" * 24), fg="green", bold=True)
-        click.secho("✔ Tunnel connected", fg="green")
-        click.secho(f"\nPublic URL:\n{url}\n", fg="cyan", bold=True)
-        click.secho("📤 Share this link with your team", fg="magenta")
-    except Exception as exc:
-        click.secho(f"[WARN] Tunnel failed: {exc}", fg="red")
-        click.secho("[INFO] Next step: install cloudflared or configure ngrok auth.", fg="yellow")
-
-@click.command()
-def unshare():
-    """Disable public tunnel at runtime (no restart)."""
-    if not STATE["tunnel"]:
-        click.secho("⚠️ No active tunnel", fg="yellow")
-        return
-    from devlinker.tunnel import stop_tunnel
-    stop_tunnel()
-    STATE["tunnel"] = None
-    click.secho("🛑 Sharing stopped", fg="red", bold=True)