devlinker 1.4.0__tar.gz → 1.4.2__tar.gz

{devlinker-1.4.0/devlinker.egg-info → devlinker-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlinker
-Version: 1.4.0
+Version: 1.4.2
 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
@@ -13,24 +13,101 @@ Requires-Dist: httpx
 Requires-Dist: pyngrok
 Requires-Dist: qrcode[pil]
 Requires-Dist: requests
+Requires-Dist: rich
 Requires-Dist: uvicorn
 Requires-Dist: websockets
 Dynamic: license-file
 
 # Dev Linker
 
-Dev Linker runs frontend and backend dev servers, proxies both through a single local port (8000), and creates a single public URL via Cloudflare or ngrok.
+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
 
 - 🚀 **Unified Dev Proxy:** Combines frontend (Vite/React) and backend (FastAPI/Flask/Node/Docker) into a single local and public URL.
 - 🔍 **Auto Detection:** Detects frontend/backend ports, runtime, Docker containers, and Vite servers automatically.
+- 📡 **Debug Request Logger:** Live API traffic lines (method, path, status, latency) only in debug mode.
+- 🧩 **Backend-Only Mode:** If no frontend is detected, DevLinker still runs and forwards all traffic to backend.
+- 🔁 **Auto API URL Sync:** Updates `frontend/.env.local` with `VITE_API_URL=http://localhost:<proxy-port>` using a managed block.
+- 🛡️ **Proxy CORS + Preflight:** Handles common CORS/preflight behavior at the proxy layer, including credential-safe Origin handling.
 - 🧠 **Smart Detection & Doctor:** Real-time request analysis, backend intelligence, log analyzer, and `devlinker doctor` for instant diagnostics.
 - 🛡️ **Auto-Fix Engine:** `devlinker fix` applies safe fixes (like VITE_API_URL) and suggests code changes.
 - 🌍 **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.
@@ -62,8 +139,33 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker --no-lan` — Hide WLAN sharing URL
 - `devlinker --interactive-backend` — Prompt to choose backend if multiple found
 - `devlinker --proxy-port 18000` — Use custom proxy port
+- `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
@@ -88,6 +190,12 @@ For local development:
 pip install .
 ```
 
+For editable local development:
+
+```bash
+pip install -e .
+```
+
 After publishing to PyPI:
 
 ```bash
@@ -100,34 +208,47 @@ pip install devlinker
 devlinker
 ```
 
-Typical startup output:
+Direct module run (without installing entrypoint script):
+
+```bash
+python -m devlinker.main
+```
+
+Typical startup output (TTY with Rich available):
 
 ```text
-Dev Linker v1.2.2
+╭─────────────────────────────╮
+│ ♾️  DevLinker v1.4.1        │
+│ Smart Local Dev Environment │
+╰─────────────────────────────╯
+
+✔ Detecting project...
+⏳ Booting local services...
+
+╭───────── DevLinker Ready ─────────╮
+│ Proxy     http://localhost:8001   │
+│ WLAN      http://192.168.1.3:8001 │
+│ Public    disabled (use --url)    │
+╰───────────────────────────────────╯
+
+✨ Ready in 5.5s
+Powered by DevLinker 🚀
+```
 
-[INFO] Mode: Auto (FastAPI async proxy + Docker detection)
-[INFO] Booting local services...
-[INFO] Detecting frontend/backend ports...
-[OK] Frontend -> 5173
-[OK] Backend  -> 5000
+Enable debug mode with live API request logging:
 
-[OK] Proxy ready at http://localhost:8000
+```bash
+devlinker --debug
+```
 
-[OK] Tunnel provider: Cloudflare
-[OK] Public URL:
-    https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
+Debug mode request logger sample:
 
-[INFO] Share this link with collaborators.
+```text
+🛠 Debug mode enabled: live API request logger is ON
 
-DevLinker Ready (in 2.4s)
-Frontend: http://localhost:5173
-Backend:  http://localhost:5000
-Access Links:
-Local:  http://localhost:8000
-WLAN:   http://192.168.1.5:8000
-Public: https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
+📡 Requests (Live)
+GET    /api/users               200  45ms
+POST   /api/login               401  120ms
 ```
 
 Version check:
@@ -160,15 +281,6 @@ devlinker --docker
 By default, DevLinker starts **fast local proxy only** (no tunnel). To enable a public tunnel, use the `--url` flag:
 
 
-```bash
-devlinker --url
-```
-
-In your terminal output, you'll see:
-
-
-URL, run:
-
 ```bash
 devlinker --url
 ```
@@ -177,11 +289,11 @@ This will start the proxy and open a public tunnel (Cloudflare or ngrok). The ou
 
 ```text
 🌍 Enabling public tunnel...
-[OK] Tunnel provider: Cloudflare
-[OK] Public URL:
+✔ Tunnel provider: Cloudflare
+✔ Public URL:
      https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
-[INFO] Share this link with collaborators.
+ℹ Tip: Ctrl+Click to open link
+ℹ Share this link with collaborators.
 ```
 
 To force tunnel off (even if --url is passed):
@@ -241,13 +353,11 @@ devlinker --frontend 5173 --backend 5000 --proxy-port 18000
 Default behavior also tries fallback ports automatically when 8000 is busy:
 
 ```text
-[WARN] Port 8000 in use
-[INFO] Using proxy port: 8001
+⚠ Port 8000 in use
+ℹ Using proxy port: 8001
 ```
 
-- 8001
-- 8002
-- 18000
+By default it scans the next 10 ports after the requested one, then tries `18000`.
 
 Frontend detection behavior:
 
@@ -266,6 +376,41 @@ fetch("/api/endpoint")
 
 Do not hardcode backend host URLs in frontend code.
 
+DevLinker also writes/updates a managed block in `frontend/.env.local`:
+
+```env
+# devlinker-managed:start
+VITE_API_URL=http://localhost:8001
+# devlinker-managed:end
+```
+
+This keeps frontend API calls consistently routed through the proxy.
+
+Use the proxy URL as your single entry point during development:
+
+```text
+http://localhost:<proxy-port>
+```
+
+Avoid direct backend calls like `http://localhost:5000` from browser-facing code.
+
+## Configuration File
+
+DevLinker loads config from the first file found in this order:
+
+1. `devlinker.yaml`
+2. `devlinker.yml`
+3. `devlinker.json`
+
+Example:
+
+```yaml
+frontend: 5173
+backend: 5000
+proxy_port: 8001
+tunnel: false
+```
+
 ## Backend Auto-Detection
 
 Backend port detection runs in this order:
@@ -321,12 +466,15 @@ For containerized Flask backends, ensure:
 
 - runner.py expects frontend project in frontend and Python app in backend/app.py.
 - If those paths do not exist, Dev Linker skips launch and only tries to detect already-running services.
+- If frontend is missing but backend is available, DevLinker continues in backend-only mode.
 - Tunnel selection order is: cloudflared (TryCloudflare), then ngrok.
 - If cloudflared is unavailable and ngrok is not configured, Dev Linker prints one-time setup guidance.
 - You may need to set ngrok auth once on your machine using ngrok config add-authtoken <token>.
 - Dev Linker prints a public URL with `ngrok-skip-browser-warning=true` only when ngrok is used.
 - Startup output includes selected tunnel provider (`cloudflare` or `ngrok`).
 - Proxy layer now supports WebSocket upgrades, including Vite HMR over shared links.
+- Proxy handles common CORS/preflight behavior and adds camera/mic permissions policy headers.
+- Live API request logging is disabled by default and only enabled with `devlinker --debug`.
 - Proxy listens on `0.0.0.0` and can print a WLAN URL for same-network sharing.
 - If WLAN access fails on Windows, allow the proxy port in firewall and confirm devices are on the same network.
 

{devlinker-1.4.0 → devlinker-1.4.2}/README.md

@@ -1,17 +1,93 @@
 # Dev Linker
 
-Dev Linker runs frontend and backend dev servers, proxies both through a single local port (8000), and creates a single public URL via Cloudflare or ngrok.
+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
 
 - 🚀 **Unified Dev Proxy:** Combines frontend (Vite/React) and backend (FastAPI/Flask/Node/Docker) into a single local and public URL.
 - 🔍 **Auto Detection:** Detects frontend/backend ports, runtime, Docker containers, and Vite servers automatically.
+- 📡 **Debug Request Logger:** Live API traffic lines (method, path, status, latency) only in debug mode.
+- 🧩 **Backend-Only Mode:** If no frontend is detected, DevLinker still runs and forwards all traffic to backend.
+- 🔁 **Auto API URL Sync:** Updates `frontend/.env.local` with `VITE_API_URL=http://localhost:<proxy-port>` using a managed block.
+- 🛡️ **Proxy CORS + Preflight:** Handles common CORS/preflight behavior at the proxy layer, including credential-safe Origin handling.
 - 🧠 **Smart Detection & Doctor:** Real-time request analysis, backend intelligence, log analyzer, and `devlinker doctor` for instant diagnostics.
 - 🛡️ **Auto-Fix Engine:** `devlinker fix` applies safe fixes (like VITE_API_URL) and suggests code changes.
 - 🌍 **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.
@@ -43,8 +119,33 @@ If DevLinker helps you ship faster, consider supporting the project:
 - `devlinker --no-lan` — Hide WLAN sharing URL
 - `devlinker --interactive-backend` — Prompt to choose backend if multiple found
 - `devlinker --proxy-port 18000` — Use custom proxy port
+- `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
@@ -69,6 +170,12 @@ For local development:
 pip install .
 ```
 
+For editable local development:
+
+```bash
+pip install -e .
+```
+
 After publishing to PyPI:
 
 ```bash
@@ -81,34 +188,47 @@ pip install devlinker
 devlinker
 ```
 
-Typical startup output:
+Direct module run (without installing entrypoint script):
+
+```bash
+python -m devlinker.main
+```
+
+Typical startup output (TTY with Rich available):
 
 ```text
-Dev Linker v1.2.2
+╭─────────────────────────────╮
+│ ♾️  DevLinker v1.4.1        │
+│ Smart Local Dev Environment │
+╰─────────────────────────────╯
+
+✔ Detecting project...
+⏳ Booting local services...
+
+╭───────── DevLinker Ready ─────────╮
+│ Proxy     http://localhost:8001   │
+│ WLAN      http://192.168.1.3:8001 │
+│ Public    disabled (use --url)    │
+╰───────────────────────────────────╯
+
+✨ Ready in 5.5s
+Powered by DevLinker 🚀
+```
 
-[INFO] Mode: Auto (FastAPI async proxy + Docker detection)
-[INFO] Booting local services...
-[INFO] Detecting frontend/backend ports...
-[OK] Frontend -> 5173
-[OK] Backend  -> 5000
+Enable debug mode with live API request logging:
 
-[OK] Proxy ready at http://localhost:8000
+```bash
+devlinker --debug
+```
 
-[OK] Tunnel provider: Cloudflare
-[OK] Public URL:
-    https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
+Debug mode request logger sample:
 
-[INFO] Share this link with collaborators.
+```text
+🛠 Debug mode enabled: live API request logger is ON
 
-DevLinker Ready (in 2.4s)
-Frontend: http://localhost:5173
-Backend:  http://localhost:5000
-Access Links:
-Local:  http://localhost:8000
-WLAN:   http://192.168.1.5:8000
-Public: https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
+📡 Requests (Live)
+GET    /api/users               200  45ms
+POST   /api/login               401  120ms
 ```
 
 Version check:
@@ -141,15 +261,6 @@ devlinker --docker
 By default, DevLinker starts **fast local proxy only** (no tunnel). To enable a public tunnel, use the `--url` flag:
 
 
-```bash
-devlinker --url
-```
-
-In your terminal output, you'll see:
-
-
-URL, run:
-
 ```bash
 devlinker --url
 ```
@@ -158,11 +269,11 @@ This will start the proxy and open a public tunnel (Cloudflare or ngrok). The ou
 
 ```text
 🌍 Enabling public tunnel...
-[OK] Tunnel provider: Cloudflare
-[OK] Public URL:
+✔ Tunnel provider: Cloudflare
+✔ Public URL:
      https://xxxx.trycloudflare.com
-Tip: Press Ctrl+Click to open link
-[INFO] Share this link with collaborators.
+ℹ Tip: Ctrl+Click to open link
+ℹ Share this link with collaborators.
 ```
 
 To force tunnel off (even if --url is passed):
@@ -222,13 +333,11 @@ devlinker --frontend 5173 --backend 5000 --proxy-port 18000
 Default behavior also tries fallback ports automatically when 8000 is busy:
 
 ```text
-[WARN] Port 8000 in use
-[INFO] Using proxy port: 8001
+⚠ Port 8000 in use
+ℹ Using proxy port: 8001
 ```
 
-- 8001
-- 8002
-- 18000
+By default it scans the next 10 ports after the requested one, then tries `18000`.
 
 Frontend detection behavior:
 
@@ -247,6 +356,41 @@ fetch("/api/endpoint")
 
 Do not hardcode backend host URLs in frontend code.
 
+DevLinker also writes/updates a managed block in `frontend/.env.local`:
+
+```env
+# devlinker-managed:start
+VITE_API_URL=http://localhost:8001
+# devlinker-managed:end
+```
+
+This keeps frontend API calls consistently routed through the proxy.
+
+Use the proxy URL as your single entry point during development:
+
+```text
+http://localhost:<proxy-port>
+```
+
+Avoid direct backend calls like `http://localhost:5000` from browser-facing code.
+
+## Configuration File
+
+DevLinker loads config from the first file found in this order:
+
+1. `devlinker.yaml`
+2. `devlinker.yml`
+3. `devlinker.json`
+
+Example:
+
+```yaml
+frontend: 5173
+backend: 5000
+proxy_port: 8001
+tunnel: false
+```
+
 ## Backend Auto-Detection
 
 Backend port detection runs in this order:
@@ -302,12 +446,15 @@ For containerized Flask backends, ensure:
 
 - runner.py expects frontend project in frontend and Python app in backend/app.py.
 - If those paths do not exist, Dev Linker skips launch and only tries to detect already-running services.
+- If frontend is missing but backend is available, DevLinker continues in backend-only mode.
 - Tunnel selection order is: cloudflared (TryCloudflare), then ngrok.
 - If cloudflared is unavailable and ngrok is not configured, Dev Linker prints one-time setup guidance.
 - You may need to set ngrok auth once on your machine using ngrok config add-authtoken <token>.
 - Dev Linker prints a public URL with `ngrok-skip-browser-warning=true` only when ngrok is used.
 - Startup output includes selected tunnel provider (`cloudflare` or `ngrok`).
 - Proxy layer now supports WebSocket upgrades, including Vite HMR over shared links.
+- Proxy handles common CORS/preflight behavior and adds camera/mic permissions policy headers.
+- Live API request logging is disabled by default and only enabled with `devlinker --debug`.
 - Proxy listens on `0.0.0.0` and can print a WLAN URL for same-network sharing.
 - If WLAN access fails on Windows, allow the proxy port in firewall and confirm devices are on the same network.
 

devlinker-1.4.2/devlinker/config.py

@@ -0,0 +1,17 @@
+import os
+import json
+
+import yaml
+
+def load_config(config_path: str = "devlinker.yaml") -> dict:
+    candidates = [config_path, "devlinker.yml", "devlinker.json"]
+    selected = next((path for path in candidates if os.path.exists(path)), None)
+    if not selected:
+        return {}
+
+    with open(selected, "r", encoding="utf-8") as handle:
+        if selected.endswith(".json"):
+            data = json.load(handle)
+        else:
+            data = yaml.safe_load(handle)
+    return data or {}

{devlinker-1.4.0 → devlinker-1.4.2}/devlinker/detector_ai.py

@@ -1,16 +1,21 @@
 class DevLinkerAI:
     def analyze_failure(self, error_text):
+        lowered = error_text.lower()
         if "CORS" in error_text:
             return [
                 "Frontend is calling backend directly",
                 "Use /api/* instead of localhost:PORT"
             ]
         if "404" in error_text:
+            if " get / " in lowered or lowered.strip().startswith("get /"):
+                return []
+            if "/api" not in lowered:
+                return ["Route not found"]
             return [
                 "Route not found",
                 "Check if '/api' prefix is required"
             ]
-        if "connection refused" in error_text.lower():
+        if "connection refused" in lowered:
             return [
                 "Backend not reachable",
                 "Ensure backend is running"