devlinker 0.1.0__tar.gz → 0.2.0__tar.gz

{devlinker-0.1.0 → devlinker-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlinker
-Version: 0.1.0
+Version: 0.2.0
 Summary: AI-powered linking and automation tool
 Author-email: Mani <mani1028@users.noreply.github.com>
 Requires-Python: >=3.7
@@ -16,8 +16,13 @@ Dev Linker runs frontend and backend dev servers, proxies both through a single
 
 ## Features
 
-- Launches frontend and backend (when frontend and backend/app.py exist)
+- Launches frontend automatically (when frontend exists)
+- Auto-detects backend runtime (Docker Compose, Dockerfile, Node, or Python)
+- Auto-starts Python/Node backends; Docker is manual by default for reliability
 - Detects common frontend/backend ports
+- Supports Docker backend port auto-detection
+- Works with dynamic container host ports
+- No config needed for standard Flask/Docker flows
 - Serves both through one proxy at http://localhost:8000
 - Creates a public tunnel for sharing (Cloudflare first, ngrok fallback)
 - Terminal-first workflow
@@ -26,8 +31,8 @@ Dev Linker runs frontend and backend dev servers, proxies both through a single
 ## Project Structure
 
 ```text
-onelink/
-├── onelink/
+devlinker/
+├── devlinker/
 │   ├── __init__.py
 │   ├── main.py
 │   ├── runner.py
@@ -50,7 +55,7 @@ pip install .
 After publishing to PyPI:
 
 ```bash
-pip install dev-linker
+pip install devlinker
 ```
 
 ## Run
@@ -62,20 +67,29 @@ devlinker
 Typical startup output:
 
 ```text
-✨ Dev Linker v0.1.0
+Dev Linker v0.2.0
 
-🚀 Starting services...
-🔍 Detecting services...
-	• Frontend -> 5173
-	• Backend  -> 5000
+[INFO] Mode: Auto (Flask + Docker detection)
+[INFO] Booting local services...
+[INFO] Detecting frontend/backend ports...
+[OK] Frontend -> 5173
+[OK] Backend  -> 5000
 
-🌐 Proxy ready at http://localhost:8000
+[OK] Proxy ready at http://localhost:8000
 
-⚡ Tunnel provider: Cloudflare
-🌍 Public URL:
-	https://xxxx.trycloudflare.com
+[OK] Tunnel provider: Cloudflare
+[OK] Public URL:
+    https://xxxx.trycloudflare.com
+Tip: Press Ctrl+Click to open link
 
-👉 Share this link with anyone
+[INFO] Share this link with collaborators.
+
+DevLinker Ready (in 2.4s)
+Frontend: http://localhost:5173
+Backend:  http://localhost:5000
+Proxy:    http://localhost:8000
+PUBLIC URL: https://xxxx.trycloudflare.com
+Tip: Press Ctrl+Click to open link
 ```
 
 Version check:
@@ -90,6 +104,24 @@ Optional overrides:
 devlinker --frontend 5173 --backend 5000
 ```
 
+Backend override alias:
+
+```bash
+devlinker --backend-port 3001
+```
+
+Enable Docker auto-start explicitly:
+
+```bash
+devlinker --docker
+```
+
+Run local-only mode without tunnel:
+
+```bash
+devlinker --no-tunnel
+```
+
 If port 8000 is already in use:
 
 ```bash
@@ -98,6 +130,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
+```
+
 - 8001
 - 8002
 - 18000
@@ -112,6 +149,49 @@ fetch("/api/endpoint")
 
 Do not hardcode backend host URLs in frontend code.
 
+## Backend Auto-Detection
+
+Backend port detection runs in this order:
+
+1. Check localhost port 5000
+2. If not found, check Docker port mappings for `->5000/tcp`
+3. Use the mapped host port automatically
+4. If nothing is found, print next-step guidance and exit
+
+Detection messages include source labels, for example:
+
+```text
+[OK] Backend detected (Local) -> port 5000
+```
+
+Example Docker dynamic-port message:
+
+```text
+[WARN] Backend not found on port 5000
+[INFO] Checking Docker containers...
+[OK] Backend detected (Docker) -> port 32768
+```
+
+Dev Linker checks backend runtime in this order:
+
+1. Docker Compose (`backend/docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, or `compose.yaml`)
+2. Docker (`backend/Dockerfile`)
+3. Node (`backend/package.json`)
+4. Python (`backend/requirements.txt` or `backend/app.py`)
+
+Backend startup commands:
+
+- Docker Compose (default): manual run `docker compose up --build` in `backend/`
+- Dockerfile (default): manual run `docker build -t devlinker-backend .` then `docker run --rm -p 5000:5000 devlinker-backend`
+- Docker Compose/Dockerfile with `--docker`: Dev Linker runs those Docker commands for you
+- Node: `npm run dev` (or `npm start` when `dev` is missing)
+- Python: `python app.py`
+
+For containerized Flask backends, ensure:
+
+- App binds to all interfaces: `app.run(host="0.0.0.0", port=5000)`
+- Port mapping is present: `-p 5000:5000`
+
 ## Notes
 
 - runner.py expects frontend project in frontend and Flask app in backend/app.py.

devlinker-0.2.0/README.md

@@ -0,0 +1,206 @@
+# 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.
+
+## Features
+
+- Launches frontend automatically (when frontend exists)
+- Auto-detects backend runtime (Docker Compose, Dockerfile, Node, or Python)
+- Auto-starts Python/Node backends; Docker is manual by default for reliability
+- Detects common frontend/backend ports
+- Supports Docker backend port auto-detection
+- Works with dynamic container host ports
+- No config needed for standard Flask/Docker flows
+- Serves both through one proxy at http://localhost:8000
+- Creates a public tunnel for sharing (Cloudflare first, ngrok fallback)
+- Terminal-first workflow
+- Supports CLI version output with --version
+
+## Project Structure
+
+```text
+devlinker/
+├── devlinker/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── runner.py
+│   ├── detector.py
+│   ├── proxy.py
+│   └── tunnel.py
+├── setup.py
+├── README.md
+└── requirements.txt
+```
+
+## Install
+
+For local development:
+
+```bash
+pip install .
+```
+
+After publishing to PyPI:
+
+```bash
+pip install devlinker
+```
+
+## Run
+
+```bash
+devlinker
+```
+
+Typical startup output:
+
+```text
+Dev Linker v0.2.0
+
+[INFO] Mode: Auto (Flask + Docker detection)
+[INFO] Booting local services...
+[INFO] Detecting frontend/backend ports...
+[OK] Frontend -> 5173
+[OK] Backend  -> 5000
+
+[OK] Proxy ready at http://localhost:8000
+
+[OK] Tunnel provider: Cloudflare
+[OK] Public URL:
+    https://xxxx.trycloudflare.com
+Tip: Press Ctrl+Click to open link
+
+[INFO] Share this link with collaborators.
+
+DevLinker Ready (in 2.4s)
+Frontend: http://localhost:5173
+Backend:  http://localhost:5000
+Proxy:    http://localhost:8000
+PUBLIC URL: https://xxxx.trycloudflare.com
+Tip: Press Ctrl+Click to open link
+```
+
+Version check:
+
+```bash
+devlinker --version
+```
+
+Optional overrides:
+
+```bash
+devlinker --frontend 5173 --backend 5000
+```
+
+Backend override alias:
+
+```bash
+devlinker --backend-port 3001
+```
+
+Enable Docker auto-start explicitly:
+
+```bash
+devlinker --docker
+```
+
+Run local-only mode without tunnel:
+
+```bash
+devlinker --no-tunnel
+```
+
+If port 8000 is already in use:
+
+```bash
+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
+```
+
+- 8001
+- 8002
+- 18000
+
+## Important Frontend Rule
+
+Frontend requests must use relative API paths:
+
+```js
+fetch("/api/endpoint")
+```
+
+Do not hardcode backend host URLs in frontend code.
+
+## Backend Auto-Detection
+
+Backend port detection runs in this order:
+
+1. Check localhost port 5000
+2. If not found, check Docker port mappings for `->5000/tcp`
+3. Use the mapped host port automatically
+4. If nothing is found, print next-step guidance and exit
+
+Detection messages include source labels, for example:
+
+```text
+[OK] Backend detected (Local) -> port 5000
+```
+
+Example Docker dynamic-port message:
+
+```text
+[WARN] Backend not found on port 5000
+[INFO] Checking Docker containers...
+[OK] Backend detected (Docker) -> port 32768
+```
+
+Dev Linker checks backend runtime in this order:
+
+1. Docker Compose (`backend/docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, or `compose.yaml`)
+2. Docker (`backend/Dockerfile`)
+3. Node (`backend/package.json`)
+4. Python (`backend/requirements.txt` or `backend/app.py`)
+
+Backend startup commands:
+
+- Docker Compose (default): manual run `docker compose up --build` in `backend/`
+- Dockerfile (default): manual run `docker build -t devlinker-backend .` then `docker run --rm -p 5000:5000 devlinker-backend`
+- Docker Compose/Dockerfile with `--docker`: Dev Linker runs those Docker commands for you
+- Node: `npm run dev` (or `npm start` when `dev` is missing)
+- Python: `python app.py`
+
+For containerized Flask backends, ensure:
+
+- App binds to all interfaces: `app.run(host="0.0.0.0", port=5000)`
+- Port mapping is present: `-p 5000:5000`
+
+## Notes
+
+- runner.py expects frontend project in frontend and Flask app in backend/app.py.
+- If those paths do not exist, Dev Linker skips launch and only tries to detect already-running services.
+- 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`).
+- When Dev Linker launches a Vite frontend, it sets `ONELINK=1` to disable Vite HMR WebSockets for stable tunnel behavior.
+
+## Real-Time Development Modes
+
+### Option 1: Dev Linker sharing mode (recommended)
+
+- Run `devlinker` to share one combined frontend/backend URL.
+- Open local Vite URL yourself for instant HMR updates.
+- Share Dev Linker/ngrok URL with others; they can use normal page refresh to see changes.
+
+### Option 2: Full remote HMR mode (bypass Dev Linker)
+
+- Start frontend and backend manually.
+- Configure Vite `server.proxy` for `/api` to backend.
+- Run `ngrok http <vite-port>` directly so Vite handles WebSocket HMR traffic.

{devlinker-0.1.0 → devlinker-0.2.0}/devlinker/__init__.py

@@ -1,6 +1,6 @@
 """Dev Linker package."""
 
-__version__ = "0.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "main",

devlinker-0.2.0/devlinker/main.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import socket
+import time
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+import click
+
+from . import __version__
+from .detector import check_port, detect_ports, is_vite_port
+from .proxy import start_proxy
+from .runner import detect_backend_port, start_servers
+from .tunnel import start_tunnel
+
+
+def _is_port_in_use(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(1)
+        return sock.connect_ex(("127.0.0.1", port)) == 0
+
+
+def _select_proxy_port(requested_port: int) -> int:
+    if not _is_port_in_use(requested_port):
+        return requested_port
+
+    if requested_port != 8000:
+        raise click.ClickException(
+            f"Proxy port {requested_port} is already in use. Choose another with --proxy-port."
+        )
+
+    for candidate in (8001, 8002, 18000):
+        if not _is_port_in_use(candidate):
+            print("[WARN] Port 8000 in use")
+            print(f"[INFO] Using proxy port: {candidate}")
+            return candidate
+
+    raise click.ClickException(
+        "No free proxy port found in fallback list (8000, 8001, 8002, 18000)."
+    )
+
+
+def _with_ngrok_skip_warning(url: str) -> str:
+    parts = urlsplit(url)
+    if "ngrok" not in parts.netloc:
+        return url
+
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    query["ngrok-skip-browser-warning"] = "true"
+    new_query = urlencode(query)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, new_query, parts.fragment))
+
+
+def _print_summary(
+    frontend_port: int,
+    backend_port: int,
+    proxy_port: int,
+    public_url: str | None,
+    startup_seconds: float,
+) -> None:
+    print(f"\nDevLinker Ready (in {startup_seconds:.1f}s)")
+    print(f"Frontend: http://localhost:{frontend_port}")
+    print(f"Backend:  http://localhost:{backend_port}")
+    print(f"Proxy:    http://localhost:{proxy_port}")
+    if public_url:
+        print(f"PUBLIC URL: {public_url}")
+        print("Tip: Press Ctrl+Click to open link")
+    else:
+        print("Public:   unavailable (local proxy still active)")
+
+
+@click.command()
+@click.version_option(version=__version__, prog_name="devlinker")
+@click.option("--frontend", type=int, default=None, help="Override detected frontend port.")
+@click.option(
+    "--backend",
+    "--backend-port",
+    "backend_port_override",
+    type=int,
+    default=None,
+    help="Override detected backend port.",
+)
+@click.option("--proxy-port", type=int, default=8000, show_default=True, help="Proxy listen port.")
+@click.option(
+    "--docker",
+    "auto_start_docker",
+    is_flag=True,
+    help="Auto-start Docker backends (manual Docker is the default).",
+)
+@click.option("--no-tunnel", is_flag=True, help="Skip public tunnel and run local proxy only.")
+@click.option("--debug", is_flag=True, hidden=True, help="Enable debug logging.")
+def cli(
+    frontend: int | None,
+    backend_port_override: int | None,
+    proxy_port: int,
+    auto_start_docker: bool,
+    no_tunnel: bool,
+    debug: bool,
+) -> None:
+    started = time.perf_counter()
+    print(f"\nDev Linker v{__version__}")
+    print("[INFO] Mode: Auto (Flask + Docker detection)")
+    print("[INFO] Booting local services...")
+
+    start_servers(auto_start_docker=auto_start_docker)
+
+    backend_port = detect_backend_port(
+        default_port=5000,
+        override_port=backend_port_override,
+        debug=debug,
+    )
+    if backend_port is None:
+        raise SystemExit(1)
+
+    print("[INFO] Detecting frontend/backend ports...")
+    frontend_port, backend_port = detect_ports(frontend=frontend, backend=backend_port)
+
+    if frontend_port is None:
+        raise click.ClickException(
+            "Frontend not detected on common ports. Start frontend first or set --frontend (example: 5173)."
+        )
+    if backend_port is None:
+        raise click.ClickException(
+            "Backend not detected on common ports. Start backend first or set --backend (example: 5000)."
+        )
+
+    if not is_vite_port(frontend_port):
+        raise click.ClickException(
+            f"Frontend port {frontend_port} is reachable but does not look like a Vite dev server. "
+            "Run frontend with Dev Linker or pass the correct --frontend port."
+        )
+
+    if not check_port(backend_port):
+        raise click.ClickException(
+            f"Backend port {backend_port} is not reachable. Verify backend is running and listening on localhost."
+        )
+
+    proxy_port = _select_proxy_port(proxy_port)
+
+    print(f"[OK] Frontend -> {frontend_port}")
+    print(f"[OK] Backend  -> {backend_port}\n")
+
+    print(f"[INFO] Starting proxy on :{proxy_port}...")
+    start_proxy(frontend_port, backend_port, proxy_port=proxy_port)
+
+    # Allow Flask thread to bind before opening tunnel.
+    time.sleep(1)
+
+    print(f"\n[OK] Proxy ready at http://localhost:{proxy_port}\n")
+    warning_free_url: str | None = None
+    if no_tunnel:
+        print("[INFO] Tunnel disabled by --no-tunnel; local proxy only.")
+    else:
+        try:
+            print("[INFO] Opening public tunnel...")
+            provider, public_url = start_tunnel(proxy_port)
+            warning_free_url = _with_ngrok_skip_warning(public_url)
+            provider_label = "Cloudflare" if provider == "cloudflare" else "ngrok"
+            print(f"[OK] Tunnel provider: {provider_label}")
+            print("[OK] Public URL:")
+            print(f"     {warning_free_url}\n")
+            print("Tip: Press Ctrl+Click to open link")
+            print("[INFO] Share this link with collaborators.")
+        except RuntimeError as exc:
+            print(f"[WARN] Tunnel failed: {exc}")
+            print("[INFO] Next step: install cloudflared or configure ngrok auth.")
+            print("[INFO] Tip: run 'ngrok config add-authtoken <token>' for ngrok fallback.")
+            print(f"[OK] Continuing with local proxy at http://localhost:{proxy_port}")
+
+    _print_summary(
+        frontend_port,
+        backend_port,
+        proxy_port,
+        warning_free_url,
+        startup_seconds=time.perf_counter() - started,
+    )
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\n[INFO] Dev Linker stopped.")
+
+
+if __name__ == "__main__":
+    cli()