qpyserve 0.1.0__tar.gz

qpyserve-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qpyserve contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qpyserve-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: qpyserve
+Version: 0.1.0
+Summary: Run FastAPI with HTML, React, or Vue on one host using one Python command
+Author: qpyserve contributors
+License: MIT
+Project-URL: Repository, https://github.com/austinwin/qpyserve
+Project-URL: Issues, https://github.com/austinwin/qpyserve/issues
+Keywords: fastapi,vite,react,vue,web,asgi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.110
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Requires-Dist: build>=1.2; extra == "test"
+Dynamic: license-file
+
+# qpyserve
+
+**FastAPI + any frontend. One Python command. One browser address.**
+
+QPyServe is a thin bridge, not a new web framework. Write normal FastAPI endpoints and use plain HTML/JS, React, Vue, or another Vite frontend. QPyServe handles local startup, frontend dependencies, API proxying, hot reload, and static production serving.
+
+> **Status:** Early alpha. Not yet load-tested or security-audited. Multiple workers do not guarantee performance for 1,000 concurrent users.
+
+## Installation
+
+```bash
+pip install qpyserve
+```
+
+For a source checkout: `python -m pip install -e .` instead. If not yet released to PyPI, install from GitHub: `pip install git+https://github.com/austinwin/qpyserve.git` (requires repository access).
+
+## Hello world: two files
+
+`main.py`:
+
+```python
+from fastapi import FastAPI
+from qpyserve import run
+
+app = FastAPI()
+
+@app.get('/api/hello')
+def hello():
+    return {'message': 'Hello from Python'}
+
+if __name__ == '__main__':
+    run(app, frontend='frontend', port=1111)
+```
+
+`frontend/index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+  <body>
+    <button id="hello">Call Python</button><pre id="result"></pre>
+    <script>
+      document.querySelector('#hello').onclick = async () => {
+        const response = await fetch('/api/hello');
+        document.querySelector('#result').textContent =
+          JSON.stringify(await response.json());
+      };
+    </script>
+  </body>
+</html>
+```
+
+```bash
+python main.py
+```
+
+Open <http://localhost:1111>. `/api/hello` serves the same origin and `/docs` shows FastAPI documentation. No Node.js, package.json, or additional commands are needed for plain HTML. Edit HTML/JS and the development page automatically refreshes.
+
+## React, Vue, or another Vite frontend
+
+Point `frontend='frontend'` to an ordinary Vite project containing `package.json` with `vite` in its dependencies. **The Python code does not change.** Run `python main.py`.
+
+- QPyServe detects npm, pnpm, Yarn, or Bun from `packageManager` / lockfiles (npm is the fallback).
+- It installs missing frontend dependencies with the selected package manager, then runs the locally installed Vite. No `npm run dev` script is required.
+- Existing `vite.config.js` / `.ts` / `.mjs` and plugins are retained; Vite provides normal HMR.
+- Development browser URL stays `http://localhost:1111`. The API runs on loopback `:1112` and is proxied through `:1111`.
+- Node.js and the chosen package manager must be installed for Vite projects. QPyServe does **not** silently install Node or fetch arbitrary runtime binaries. It reports what is missing.
+
+See the runnable [HTML counter](examples/counter-html) and [React counter](examples/counter-react).
+
+## Production and builds
+
+| Command | Behavior |
+| --- | --- |
+| `python main.py` | Start dev server, HMR/reload; install frontend packages if needed |
+| `python main.py --build` | Install packages if needed, build frontend, and exit |
+| `python main.py --prod` | Serve prebuilt frontend and FastAPI on one port |
+| `python main.py --prod --build` | Build frontend first, then serve it in production mode |
+
+Plain HTML needs no build. For Vite sites, build once in CI/CD using `--build`; production machines only need Python and the built static files. Avoid building on every production restart.
+
+**Production deployment:** Put an HTTPS reverse proxy or managed load balancer in front, use process supervision, secure the API using ordinary FastAPI dependencies/middleware, and add shared storage/caching as needed. QPyServe does not provide authentication, rate limiting, distributed state, or production infrastructure on its own.
+
+## Advanced options (optional)
+
+```python
+run(
+    app,
+    frontend='frontend',
+    port=1111,
+    host='127.0.0.1',
+    workers=1,
+    api_paths=['/ws', '/custom'],  # /api and FastAPI docs are always included
+    dist='dist',
+    app_import='main:app',  # only needed for nonstandard entrypoints
+)
+```
+
+`api_paths` explicitly adds proxy prefixes for custom HTTP routes or WebSockets during Vite development and prevents those prefixes from falling back to the SPA HTML in production. It does not create or authenticate endpoints. Don't use a broad prefix such as `/` because it would consume frontend routes.
+
+Bind `host='0.0.0.0'` only when you intentionally want to expose the service over a network; never expose the Vite development server to the public internet. `workers > 1` requires production mode and a shared state store for data that must persist across processes. The normal FastAPI OpenAPI/docs and external API clients keep working. Custom Vite proxy/SSR settings remain your frontend's responsibility when your app needs unusual behavior.
+
+## Scope and boundaries
+
+- **QPyServe:** startup/orchestration, dependency detection, Vite development proxy, SPA/static file serving, basic dev reload.
+- **FastAPI:** APIs, authentication, security, WebSockets, validation, database code, dependency injection.
+- **Vite:** React/Vue/JS build, HMR, frontend plugins.
+- **Deployment platform:** HTTPS, worker replicas, monitoring, database, caches, queues, backups.
+
+Vite builds are static SPAs; Next.js server-side rendering, distributed WebSocket fan-out, automatic Kubernetes provisioning, and shared-memory magic are not provided. The HTML file server excludes hidden files, package manager manifests, and Python sources; don't put secrets in a public frontend directory.
+
+## Contributing and verification
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+Check [AGENTS.md](AGENTS.md) for AI-assisted contributions and [RELEASING.md](RELEASING.md) for PyPI publishing. MIT License.

qpyserve-0.1.0/README.md

@@ -0,0 +1,120 @@
+# qpyserve
+
+**FastAPI + any frontend. One Python command. One browser address.**
+
+QPyServe is a thin bridge, not a new web framework. Write normal FastAPI endpoints and use plain HTML/JS, React, Vue, or another Vite frontend. QPyServe handles local startup, frontend dependencies, API proxying, hot reload, and static production serving.
+
+> **Status:** Early alpha. Not yet load-tested or security-audited. Multiple workers do not guarantee performance for 1,000 concurrent users.
+
+## Installation
+
+```bash
+pip install qpyserve
+```
+
+For a source checkout: `python -m pip install -e .` instead. If not yet released to PyPI, install from GitHub: `pip install git+https://github.com/austinwin/qpyserve.git` (requires repository access).
+
+## Hello world: two files
+
+`main.py`:
+
+```python
+from fastapi import FastAPI
+from qpyserve import run
+
+app = FastAPI()
+
+@app.get('/api/hello')
+def hello():
+    return {'message': 'Hello from Python'}
+
+if __name__ == '__main__':
+    run(app, frontend='frontend', port=1111)
+```
+
+`frontend/index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+  <body>
+    <button id="hello">Call Python</button><pre id="result"></pre>
+    <script>
+      document.querySelector('#hello').onclick = async () => {
+        const response = await fetch('/api/hello');
+        document.querySelector('#result').textContent =
+          JSON.stringify(await response.json());
+      };
+    </script>
+  </body>
+</html>
+```
+
+```bash
+python main.py
+```
+
+Open <http://localhost:1111>. `/api/hello` serves the same origin and `/docs` shows FastAPI documentation. No Node.js, package.json, or additional commands are needed for plain HTML. Edit HTML/JS and the development page automatically refreshes.
+
+## React, Vue, or another Vite frontend
+
+Point `frontend='frontend'` to an ordinary Vite project containing `package.json` with `vite` in its dependencies. **The Python code does not change.** Run `python main.py`.
+
+- QPyServe detects npm, pnpm, Yarn, or Bun from `packageManager` / lockfiles (npm is the fallback).
+- It installs missing frontend dependencies with the selected package manager, then runs the locally installed Vite. No `npm run dev` script is required.
+- Existing `vite.config.js` / `.ts` / `.mjs` and plugins are retained; Vite provides normal HMR.
+- Development browser URL stays `http://localhost:1111`. The API runs on loopback `:1112` and is proxied through `:1111`.
+- Node.js and the chosen package manager must be installed for Vite projects. QPyServe does **not** silently install Node or fetch arbitrary runtime binaries. It reports what is missing.
+
+See the runnable [HTML counter](examples/counter-html) and [React counter](examples/counter-react).
+
+## Production and builds
+
+| Command | Behavior |
+| --- | --- |
+| `python main.py` | Start dev server, HMR/reload; install frontend packages if needed |
+| `python main.py --build` | Install packages if needed, build frontend, and exit |
+| `python main.py --prod` | Serve prebuilt frontend and FastAPI on one port |
+| `python main.py --prod --build` | Build frontend first, then serve it in production mode |
+
+Plain HTML needs no build. For Vite sites, build once in CI/CD using `--build`; production machines only need Python and the built static files. Avoid building on every production restart.
+
+**Production deployment:** Put an HTTPS reverse proxy or managed load balancer in front, use process supervision, secure the API using ordinary FastAPI dependencies/middleware, and add shared storage/caching as needed. QPyServe does not provide authentication, rate limiting, distributed state, or production infrastructure on its own.
+
+## Advanced options (optional)
+
+```python
+run(
+    app,
+    frontend='frontend',
+    port=1111,
+    host='127.0.0.1',
+    workers=1,
+    api_paths=['/ws', '/custom'],  # /api and FastAPI docs are always included
+    dist='dist',
+    app_import='main:app',  # only needed for nonstandard entrypoints
+)
+```
+
+`api_paths` explicitly adds proxy prefixes for custom HTTP routes or WebSockets during Vite development and prevents those prefixes from falling back to the SPA HTML in production. It does not create or authenticate endpoints. Don't use a broad prefix such as `/` because it would consume frontend routes.
+
+Bind `host='0.0.0.0'` only when you intentionally want to expose the service over a network; never expose the Vite development server to the public internet. `workers > 1` requires production mode and a shared state store for data that must persist across processes. The normal FastAPI OpenAPI/docs and external API clients keep working. Custom Vite proxy/SSR settings remain your frontend's responsibility when your app needs unusual behavior.
+
+## Scope and boundaries
+
+- **QPyServe:** startup/orchestration, dependency detection, Vite development proxy, SPA/static file serving, basic dev reload.
+- **FastAPI:** APIs, authentication, security, WebSockets, validation, database code, dependency injection.
+- **Vite:** React/Vue/JS build, HMR, frontend plugins.
+- **Deployment platform:** HTTPS, worker replicas, monitoring, database, caches, queues, backups.
+
+Vite builds are static SPAs; Next.js server-side rendering, distributed WebSocket fan-out, automatic Kubernetes provisioning, and shared-memory magic are not provided. The HTML file server excludes hidden files, package manager manifests, and Python sources; don't put secrets in a public frontend directory.
+
+## Contributing and verification
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+Check [AGENTS.md](AGENTS.md) for AI-assisted contributions and [RELEASING.md](RELEASING.md) for PyPI publishing. MIT License.

qpyserve-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qpyserve"
+version = "0.1.0"
+description = "Run FastAPI with HTML, React, or Vue on one host using one Python command"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "qpyserve contributors" }]
+keywords = ["fastapi", "vite", "react", "vue", "web", "asgi"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = ["fastapi>=0.110,<1", "uvicorn[standard]>=0.30,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "httpx>=0.27", "build>=1.2"]
+
+[project.urls]
+Repository = "https://github.com/austinwin/qpyserve"
+Issues = "https://github.com/austinwin/qpyserve/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qpyserve-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qpyserve-0.1.0/src/qpyserve/__init__.py

@@ -0,0 +1,6 @@
+"""qpyserve: a tiny bridge between FastAPI and frontend applications."""
+
+from ._runtime import run
+
+__all__ = ["run"]
+__version__ = "0.1.0"

qpyserve-0.1.0/src/qpyserve/_entry.py

@@ -0,0 +1,35 @@
+"""Importable Uvicorn factory so reload and multi-worker modes work."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+
+from fastapi import FastAPI
+
+from ._frontend import attach_frontend
+
+
+def create_app() -> FastAPI:
+    raw = os.environ.get("QPYSERVE_RUNTIME_CONFIG")
+    if not raw:
+        raise RuntimeError("qpyserve must be started through run(app, frontend=...).")
+    config = json.loads(raw)
+    module_name, separator, attribute = config["app_import"].partition(":")
+    if not separator:
+        raise ValueError("app_import must be in 'module:variable' format")
+    module = importlib.import_module(module_name)
+    app = module
+    for part in attribute.split("."):
+        app = getattr(app, part)
+    if not isinstance(app, FastAPI):
+        raise TypeError(f"{config['app_import']} does not resolve to a FastAPI app")
+    if config["serve_frontend"]:
+        attach_frontend(app, config["static_directory"], live_reload=config["live_reload"],
+                        api_paths=config.get("api_paths"))
+    else:
+        @app.get("/__qpyserve/health", include_in_schema=False)
+        def qpyserve_health() -> dict[str, str]:
+            return {"status": "ok"}
+    return app

qpyserve-0.1.0/src/qpyserve/_frontend.py

@@ -0,0 +1,124 @@
+"""Serve an HTML/JS site or a built SPA through an existing FastAPI app."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import time
+from threading import Lock
+from typing import Iterable
+
+from ._tooling import normalize_api_paths
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import FileResponse, HTMLResponse
+
+_RELOAD_SCRIPT = """<script>
+(() => {
+  let known;
+  async function check() {
+    try {
+      const response = await fetch('/__qpyserve/version', {cache: 'no-store'});
+      if (!response.ok) return;
+      const current = (await response.json()).version;
+      if (known !== undefined && known !== current) location.reload();
+      known = current;
+    } catch (_) { /* Server may be restarting. */ }
+  }
+  check();
+  setInterval(check, 1200);
+})();
+</script>"""
+
+
+def _version(folder: Path) -> int:
+    """Latest edit time; used only for small local static sites in dev."""
+    latest = 0
+    for file in folder.rglob("*"):
+        if any(part in {"node_modules", ".git", "dist", "__pycache__"} for part in file.parts):
+            continue
+        if file.is_file():
+            try:
+                latest = max(latest, file.stat().st_mtime_ns)
+            except OSError:
+                pass
+    return latest
+
+
+def attach_frontend(app: FastAPI, directory: str | Path, *, live_reload: bool = False,
+                    api_paths: Iterable[str] | None = None) -> FastAPI:
+    """Attach last, after the caller has registered all API routes.
+
+    Unknown /api paths never return the SPA index. Non-existent assets return 404.
+    """
+    reserved_paths = normalize_api_paths(api_paths)
+    root = Path(directory).resolve()
+    if not (root / "index.html").is_file():
+        raise FileNotFoundError(f"No index.html found in {root}")
+
+    @app.get("/__qpyserve/health", include_in_schema=False)
+    def qpyserve_health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    last_scan = [0.0, 0]
+    scan_lock = Lock()
+
+    if live_reload:
+        @app.get("/__qpyserve/version", include_in_schema=False)
+        def qpyserve_version() -> dict[str, int]:
+            # Multiple open tabs share one scan per second, not one scan per request.
+            with scan_lock:
+                now = time.monotonic()
+                if now - last_scan[0] >= 0.75:
+                    last_scan[:] = [now, _version(root)]
+                return {"version": last_scan[1]}
+
+    # Keep missing API paths distinct from static frontend routes, for all methods.
+    @app.api_route(
+        "/api/{unmatched_path:path}",
+        methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
+        include_in_schema=False,
+    )
+    async def unknown_api(unmatched_path: str):
+        raise HTTPException(404, "API endpoint not found")
+
+    @app.get("/{asset_path:path}", include_in_schema=False)
+    async def frontend_asset(asset_path: str, request: Request):
+        requested = "/" + asset_path
+        if any(requested == prefix or requested.startswith(prefix + "/")
+               for prefix in reserved_paths):
+            raise HTTPException(404, "Not found")
+
+        parts = Path(asset_path).parts
+        # A plain HTML frontend is a directory, not an invitation to publish its
+        # .env, package manager files, Python sources, or development config.
+        if any(part.startswith(".") for part in parts) or any(
+            part in {"node_modules", "__pycache__", "package.json", "package-lock.json",
+                     "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"}
+            or part.startswith("vite.config.") or part.endswith((".py", ".pyc"))
+            for part in parts
+        ):
+            raise HTTPException(404, "Not found")
+
+        candidate = (root / asset_path).resolve()
+        if not candidate.is_relative_to(root):
+            raise HTTPException(404, "Not found")
+        if candidate.is_dir():
+            candidate = candidate / "index.html"
+        if not candidate.is_file():
+            # Single-page app history fallback, but not for missing JS/CSS/images.
+            if "." not in Path(asset_path).name and "text/html" in request.headers.get("accept", ""):
+                candidate = root / "index.html"
+            else:
+                raise HTTPException(404, "Not found")
+
+        # A stale SPA entrypoint often causes the "hard refresh required" symptom.
+        headers = ({"Cache-Control": "no-store"} if live_reload else
+                   {"Cache-Control": "no-cache"} if candidate.suffix.lower() == ".html" else {})
+        if live_reload and candidate.suffix.lower() == ".html":
+            html = candidate.read_text(encoding="utf-8")
+            script = _RELOAD_SCRIPT
+            html = html.replace("</body>", f"{script}</body>") if "</body>" in html else html + script
+            return HTMLResponse(html, headers=headers)
+        return FileResponse(candidate, headers=headers)
+
+    return app

qpyserve-0.1.0/src/qpyserve/_runtime.py

@@ -0,0 +1,160 @@
+"""Run a real FastAPI application with any HTML or Vite-based frontend."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+from typing import Iterable, Literal
+
+from fastapi import FastAPI
+import uvicorn
+
+from ._tooling import (
+    build_frontend, ensure_dependencies, has_vite, normalize_api_paths,
+    package_manager, vite_command, vite_config,
+)
+
+Mode = Literal["development", "production"]
+
+# Retain private aliases for older users/tests; these are not public API.
+_has_vite = has_vite
+_vite_config = vite_config
+
+
+def _stop_process(process: subprocess.Popen) -> None:
+    if process.poll() is not None:
+        return
+    if os.name == "nt":
+        # npm/pnpm/yarn/bun may create child processes on Windows.
+        subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=False)
+    else:
+        import contextlib
+        with contextlib.suppress(ProcessLookupError):
+            os.killpg(process.pid, signal.SIGTERM)
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+
+
+def run(
+    app: FastAPI,
+    frontend: str | Path = "frontend",
+    port: int = 1111,
+    *,
+    host: str = "127.0.0.1",
+    mode: Mode | None = None,
+    app_import: str | None = None,
+    dist: str = "dist",
+    workers: int = 1,
+    api_paths: Iterable[str] | None = None,
+    build: bool | None = None,
+) -> None:
+    """One-command runner. `--build` builds and exits; `--prod --build` builds then serves.
+
+    Plain HTML requires Python only. React/Vue require a Vite project and its selected
+    JS package manager, installed automatically when frontend packages are missing.
+    """
+    if not isinstance(app, FastAPI):
+        raise TypeError("run() requires a FastAPI application")
+    if not 1 <= port <= 65535:
+        raise ValueError("port must be 1..65535")
+    if workers < 1:
+        raise ValueError("workers must be >= 1")
+    if mode is None:
+        mode = "production" if "--prod" in sys.argv[1:] else os.environ.get("QPYSERVE_MODE", "development")
+    if mode not in ("development", "production"):
+        raise ValueError("mode must be 'development' or 'production'")
+    if mode == "development" and workers > 1:
+        raise ValueError("Multiple workers are supported only in production")
+    if build is None:
+        build = "--build" in sys.argv[1:]
+    paths = normalize_api_paths(api_paths)
+
+    script = Path(sys.argv[0]).resolve()
+    project_dir = script.parent
+    root = Path(frontend)
+    if not root.is_absolute():
+        root = project_dir / root
+    root = root.resolve()
+    if not root.is_dir():
+        raise FileNotFoundError(f"Frontend directory not found: {root}")
+    if not dist or Path(dist).is_absolute() or ".." in Path(dist).parts:
+        raise ValueError("dist must be a relative frontend build directory")
+
+    vite = has_vite(root)
+    static_directory = root / dist if vite else root
+    if build:
+        if vite:
+            build_frontend(root)
+        else:
+            print("[qpyserve] Plain HTML requires no build", flush=True)
+        if mode != "production":
+            return
+    if mode == "production" and not (static_directory / "index.html").is_file():
+        raise FileNotFoundError(
+            f"Built frontend missing: {static_directory / 'index.html'}. "
+            "Use 'python main.py --prod --build' to build and launch, "
+            "or build once in CI and run 'python main.py --prod'."
+        )
+    if not vite and not (root / "index.html").is_file():
+        raise FileNotFoundError(f"Plain HTML frontend must contain {root / 'index.html'}")
+    if vite and mode == "development" and port == 65535:
+        raise ValueError("Vite dev requires port and port+1; choose port <= 65534")
+
+    if app_import is None:
+        main_globals = vars(sys.modules["__main__"])
+        app_var = next((k for k, v in main_globals.items() if v is app and k.isidentifier()), None)
+        if not app_var or not script.stem.isidentifier():
+            raise ValueError("Cannot locate FastAPI app. Pass app_import='main:app' explicitly.")
+        app_import = f"{script.stem}:{app_var}"
+
+    config = {
+        "app_import": app_import,
+        "serve_frontend": not (vite and mode == "development"),
+        "static_directory": str(static_directory),
+        "live_reload": not vite and mode == "development",
+        "api_paths": paths,
+    }
+    previous = os.environ.get("QPYSERVE_RUNTIME_CONFIG")
+    os.environ["QPYSERVE_RUNTIME_CONFIG"] = json.dumps(config)
+    vite_process: subprocess.Popen | None = None
+    generated_config: Path | None = None
+    try:
+        if vite and mode == "development":
+            manager = package_manager(root)
+            command = ensure_dependencies(root, manager)
+            generated_config = vite_config(root, host=host, port=port,
+                                           backend_port=port + 1, api_paths=paths)
+            cmd = vite_command(command, manager, "--config", generated_config.name)
+            kwargs = ({"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+                      if os.name == "nt" else {"start_new_session": True})
+            vite_process = subprocess.Popen(cmd, cwd=root, **kwargs)
+            print(f"[qpyserve] http://localhost:{port} (Vite) /api -> localhost:{port + 1}", flush=True)
+            uvicorn.run("qpyserve._entry:create_app", factory=True, host="127.0.0.1",
+                        port=port + 1, reload=True, reload_dirs=[str(project_dir)],
+                        reload_includes=["*.py"],
+                        reload_excludes=["node_modules", "dist", ".qpyserve.vite.config.mjs"])
+        else:
+            print(f"[qpyserve] http://localhost:{port} ({mode})", flush=True)
+            uvicorn.run("qpyserve._entry:create_app", factory=True, host=host,
+                        port=port, reload=(mode == "development"),
+                        workers=workers if mode == "production" else None,
+                        reload_dirs=[str(project_dir)] if mode == "development" else None,
+                        reload_includes=["*.py"] if mode == "development" else None,
+                        reload_excludes=["node_modules", "dist"] if mode == "development" else None)
+    finally:
+        if vite_process is not None:
+            _stop_process(vite_process)
+        if generated_config is not None:
+            generated_config.unlink(missing_ok=True)
+        if previous is None:
+            os.environ.pop("QPYSERVE_RUNTIME_CONFIG", None)
+        else:
+            os.environ["QPYSERVE_RUNTIME_CONFIG"] = previous

qpyserve-0.1.0/src/qpyserve/_tooling.py

@@ -0,0 +1,144 @@
+"""Optional Vite tooling; no JavaScript dependency is needed for plain HTML sites."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import re
+import shutil
+import subprocess
+from typing import Iterable
+
+
+DEFAULT_API_PATHS = ("/api", "/docs", "/redoc", "/openapi.json", "/__qpyserve")
+
+
+def normalize_api_paths(paths: Iterable[str] | None = None) -> tuple[str, ...]:
+    """Explicit API prefixes routed to Python in Vite dev and excluded from SPA fallback."""
+    if isinstance(paths, str):
+        paths = (paths,)
+    ordered = dict.fromkeys(DEFAULT_API_PATHS)
+    for path in paths or ():
+        if not isinstance(path, str) or not path.startswith("/") or path.startswith("//"):
+            raise ValueError(f"API path must start with one '/': {path!r}")
+        if path == "/" or any(ch in path for ch in ("?", "#", "\\", "*", "\n", "\r")):
+            raise ValueError(f"Invalid API proxy prefix: {path!r}")
+        path = path.rstrip("/")
+        if not path or "//" in path or "/./" in path or "/../" in path or path.endswith(("/.", "/..")):
+            raise ValueError(f"Invalid API proxy prefix: {path!r}")
+        ordered[path] = None
+    return tuple(ordered)
+
+
+def has_vite(folder: Path) -> bool:
+    manifest = folder / "package.json"
+    if not manifest.is_file():
+        return False
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid frontend/package.json: {exc}") from exc
+    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+    return "vite" in deps
+
+
+def package_manager(folder: Path) -> str:
+    package_json = json.loads((folder / "package.json").read_text(encoding="utf-8"))
+    specified = package_json.get("packageManager", "").split("@", 1)[0]
+    if specified:
+        if specified not in ("npm", "pnpm", "yarn", "bun"):
+            raise ValueError(f"Unsupported package manager: {specified}")
+        return specified
+    for filename, manager in (
+        ("pnpm-lock.yaml", "pnpm"), ("yarn.lock", "yarn"),
+        ("bun.lock", "bun"), ("bun.lockb", "bun"),
+        ("package-lock.json", "npm"), ("npm-shrinkwrap.json", "npm"),
+    ):
+        if (folder / filename).is_file():
+            return manager
+    return "npm"
+
+
+def _manager_command(manager: str) -> list[str]:
+    executable = shutil.which(manager)
+    if executable:
+        return [executable]
+    if manager in ("pnpm", "yarn"):
+        corepack = shutil.which("corepack")
+        if corepack:
+            return [corepack, manager]
+    raise RuntimeError(
+        f"Frontend requires {manager!r}, but it is not installed. "
+        "Install Node.js and the selected package manager (or Corepack). "
+        "Plain HTML frontends need no JavaScript tooling."
+    )
+
+
+def ensure_dependencies(folder: Path, manager: str) -> list[str]:
+    command = _manager_command(manager)
+    vite_bin = folder / "node_modules" / "vite"
+    pnp = folder / ".pnp.cjs"
+    if vite_bin.exists() or (manager == "yarn" and pnp.is_file()):
+        return command
+    install_args = {"npm": ["install"], "pnpm": ["install"],
+                    "yarn": ["install"], "bun": ["install"]}[manager]
+    if manager == "npm" and any((folder / n).is_file() for n in ("package-lock.json", "npm-shrinkwrap.json")):
+        install_args = ["ci"]
+    if manager == "pnpm" and (folder / "pnpm-lock.yaml").is_file():
+        install_args = ["install", "--frozen-lockfile"]
+    print(f"[qpyserve] Installing frontend dependencies ({manager})", flush=True)
+    subprocess.run([*command, *install_args], cwd=folder, check=True)
+    return command
+
+
+def vite_command(manager_cmd: list[str], manager: str, *args: str) -> list[str]:
+    # Invoke local Vite directly: package.json does not need a `dev` or `build` script.
+    if manager == "npm":
+        return [*manager_cmd, "exec", "--no", "--", "vite", *args]
+    if manager == "pnpm":
+        return [*manager_cmd, "exec", "vite", *args]
+    if manager == "yarn":
+        return [*manager_cmd, "vite", *args]
+    return [*manager_cmd, "x", "--no-install", "vite", *args]
+
+
+def build_frontend(folder: Path) -> None:
+    manager = package_manager(folder)
+    command = ensure_dependencies(folder, manager)
+    manifest = json.loads((folder / "package.json").read_text(encoding="utf-8"))
+    if "build" in manifest.get("scripts", {}):
+        args = ["run", "build"] if manager in ("npm", "pnpm", "bun") else ["build"]
+        cmd = [*command, *args]
+    else:
+        cmd = vite_command(command, manager, "build")
+    print("[qpyserve] Building frontend", flush=True)
+    subprocess.run(cmd, cwd=folder, check=True)
+
+
+def vite_config(folder: Path, *, host: str, port: int, backend_port: int,
+                api_paths: Iterable[str] = DEFAULT_API_PATHS) -> Path:
+    config = folder / ".qpyserve.vite.config.mjs"
+    existing = next((p for p in (
+        "vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs",
+        "vite.config.cts", "vite.config.cjs"
+    ) if (folder / p).is_file()), None)
+    original = f"import userConfig from './{existing}';\n" if existing else "const userConfig = {};\n"
+    proxies = {
+        f"^{re.escape(path)}(?:/|$)": {
+            "target": f"http://127.0.0.1:{backend_port}",
+            "changeOrigin": True,
+            "ws": True,
+        }
+        for path in api_paths
+    }
+    server = {"host": host, "port": port, "strictPort": True, "proxy": proxies}
+    config.write_text(
+        "import { defineConfig, mergeConfig } from 'vite';\n"
+        + original
+        + "export default defineConfig(async (env) => {\n"
+        + "  const base = typeof userConfig === 'function' ? await userConfig(env) : userConfig;\n"
+        + f"  return mergeConfig(base || {{}}, {{ server: {json.dumps(server)} }});\n"
+        + "});\n",
+        encoding="utf-8",
+    )
+    return config

qpyserve-0.1.0/src/qpyserve.egg-info/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: qpyserve
+Version: 0.1.0
+Summary: Run FastAPI with HTML, React, or Vue on one host using one Python command
+Author: qpyserve contributors
+License: MIT
+Project-URL: Repository, https://github.com/austinwin/qpyserve
+Project-URL: Issues, https://github.com/austinwin/qpyserve/issues
+Keywords: fastapi,vite,react,vue,web,asgi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.110
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Requires-Dist: build>=1.2; extra == "test"
+Dynamic: license-file
+
+# qpyserve
+
+**FastAPI + any frontend. One Python command. One browser address.**
+
+QPyServe is a thin bridge, not a new web framework. Write normal FastAPI endpoints and use plain HTML/JS, React, Vue, or another Vite frontend. QPyServe handles local startup, frontend dependencies, API proxying, hot reload, and static production serving.
+
+> **Status:** Early alpha. Not yet load-tested or security-audited. Multiple workers do not guarantee performance for 1,000 concurrent users.
+
+## Installation
+
+```bash
+pip install qpyserve
+```
+
+For a source checkout: `python -m pip install -e .` instead. If not yet released to PyPI, install from GitHub: `pip install git+https://github.com/austinwin/qpyserve.git` (requires repository access).
+
+## Hello world: two files
+
+`main.py`:
+
+```python
+from fastapi import FastAPI
+from qpyserve import run
+
+app = FastAPI()
+
+@app.get('/api/hello')
+def hello():
+    return {'message': 'Hello from Python'}
+
+if __name__ == '__main__':
+    run(app, frontend='frontend', port=1111)
+```
+
+`frontend/index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+  <body>
+    <button id="hello">Call Python</button><pre id="result"></pre>
+    <script>
+      document.querySelector('#hello').onclick = async () => {
+        const response = await fetch('/api/hello');
+        document.querySelector('#result').textContent =
+          JSON.stringify(await response.json());
+      };
+    </script>
+  </body>
+</html>
+```
+
+```bash
+python main.py
+```
+
+Open <http://localhost:1111>. `/api/hello` serves the same origin and `/docs` shows FastAPI documentation. No Node.js, package.json, or additional commands are needed for plain HTML. Edit HTML/JS and the development page automatically refreshes.
+
+## React, Vue, or another Vite frontend
+
+Point `frontend='frontend'` to an ordinary Vite project containing `package.json` with `vite` in its dependencies. **The Python code does not change.** Run `python main.py`.
+
+- QPyServe detects npm, pnpm, Yarn, or Bun from `packageManager` / lockfiles (npm is the fallback).
+- It installs missing frontend dependencies with the selected package manager, then runs the locally installed Vite. No `npm run dev` script is required.
+- Existing `vite.config.js` / `.ts` / `.mjs` and plugins are retained; Vite provides normal HMR.
+- Development browser URL stays `http://localhost:1111`. The API runs on loopback `:1112` and is proxied through `:1111`.
+- Node.js and the chosen package manager must be installed for Vite projects. QPyServe does **not** silently install Node or fetch arbitrary runtime binaries. It reports what is missing.
+
+See the runnable [HTML counter](examples/counter-html) and [React counter](examples/counter-react).
+
+## Production and builds
+
+| Command | Behavior |
+| --- | --- |
+| `python main.py` | Start dev server, HMR/reload; install frontend packages if needed |
+| `python main.py --build` | Install packages if needed, build frontend, and exit |
+| `python main.py --prod` | Serve prebuilt frontend and FastAPI on one port |
+| `python main.py --prod --build` | Build frontend first, then serve it in production mode |
+
+Plain HTML needs no build. For Vite sites, build once in CI/CD using `--build`; production machines only need Python and the built static files. Avoid building on every production restart.
+
+**Production deployment:** Put an HTTPS reverse proxy or managed load balancer in front, use process supervision, secure the API using ordinary FastAPI dependencies/middleware, and add shared storage/caching as needed. QPyServe does not provide authentication, rate limiting, distributed state, or production infrastructure on its own.
+
+## Advanced options (optional)
+
+```python
+run(
+    app,
+    frontend='frontend',
+    port=1111,
+    host='127.0.0.1',
+    workers=1,
+    api_paths=['/ws', '/custom'],  # /api and FastAPI docs are always included
+    dist='dist',
+    app_import='main:app',  # only needed for nonstandard entrypoints
+)
+```
+
+`api_paths` explicitly adds proxy prefixes for custom HTTP routes or WebSockets during Vite development and prevents those prefixes from falling back to the SPA HTML in production. It does not create or authenticate endpoints. Don't use a broad prefix such as `/` because it would consume frontend routes.
+
+Bind `host='0.0.0.0'` only when you intentionally want to expose the service over a network; never expose the Vite development server to the public internet. `workers > 1` requires production mode and a shared state store for data that must persist across processes. The normal FastAPI OpenAPI/docs and external API clients keep working. Custom Vite proxy/SSR settings remain your frontend's responsibility when your app needs unusual behavior.
+
+## Scope and boundaries
+
+- **QPyServe:** startup/orchestration, dependency detection, Vite development proxy, SPA/static file serving, basic dev reload.
+- **FastAPI:** APIs, authentication, security, WebSockets, validation, database code, dependency injection.
+- **Vite:** React/Vue/JS build, HMR, frontend plugins.
+- **Deployment platform:** HTTPS, worker replicas, monitoring, database, caches, queues, backups.
+
+Vite builds are static SPAs; Next.js server-side rendering, distributed WebSocket fan-out, automatic Kubernetes provisioning, and shared-memory magic are not provided. The HTML file server excludes hidden files, package manager manifests, and Python sources; don't put secrets in a public frontend directory.
+
+## Contributing and verification
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+python -m build
+```
+
+Check [AGENTS.md](AGENTS.md) for AI-assisted contributions and [RELEASING.md](RELEASING.md) for PyPI publishing. MIT License.

qpyserve-0.1.0/src/qpyserve.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/qpyserve/__init__.py
+src/qpyserve/_entry.py
+src/qpyserve/_frontend.py
+src/qpyserve/_runtime.py
+src/qpyserve/_tooling.py
+src/qpyserve/py.typed
+src/qpyserve.egg-info/PKG-INFO
+src/qpyserve.egg-info/SOURCES.txt
+src/qpyserve.egg-info/dependency_links.txt
+src/qpyserve.egg-info/requires.txt
+src/qpyserve.egg-info/top_level.txt
+tests/test_frontend.py
+tests/test_runtime.py
+tests/test_tooling.py

qpyserve-0.1.0/src/qpyserve.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qpyserve-0.1.0/src/qpyserve.egg-info/requires.txt

@@ -0,0 +1,7 @@
+fastapi<1,>=0.110
+uvicorn[standard]<1,>=0.30
+
+[test]
+pytest>=8
+httpx>=0.27
+build>=1.2

qpyserve-0.1.0/src/qpyserve.egg-info/top_level.txt

@@ -0,0 +1 @@
+qpyserve

qpyserve-0.1.0/tests/test_frontend.py

@@ -0,0 +1,104 @@
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+from qpyserve._frontend import attach_frontend
+from qpyserve._runtime import _has_vite, _vite_config
+
+
+def client_with_site(tmp_path: Path, live_reload=False):
+    (tmp_path / "index.html").write_text("<html><body>Hello</body></html>")
+    (tmp_path / "app.js").write_text("console.log('ok')")
+    app = FastAPI()
+
+    @app.get("/api/ping")
+    def ping():
+        return {"ok": True}
+
+    attach_frontend(app, tmp_path, live_reload=live_reload)
+    return TestClient(app)
+
+
+def test_api_and_html_share_origin(tmp_path):
+    client = client_with_site(tmp_path)
+    assert client.get("/api/ping").json() == {"ok": True}
+    assert "Hello" in client.get("/").text
+    assert "console.log" in client.get("/app.js").text
+    assert client.get("/__qpyserve/health").json() == {"status": "ok"}
+
+
+def test_spa_history_fallback_and_missing_assets(tmp_path):
+    client = client_with_site(tmp_path)
+    assert "Hello" in client.get("/facilities/123", headers={"accept": "text/html"}).text
+    assert client.get("/missing.js").status_code == 404
+    assert client.get("/api/missing", headers={"accept": "text/html"}).status_code == 404
+    assert client.post("/api/missing").status_code == 404
+    assert client.get("/apiary", headers={"accept": "application/json"}).status_code == 404
+    assert client.get("/../other.txt").status_code == 404
+
+
+def test_html_live_reload_is_dev_only(tmp_path):
+    dev = client_with_site(tmp_path, live_reload=True)
+    assert "__qpyserve/version" in dev.get("/").text
+    version = dev.get("/__qpyserve/version")
+    assert version.status_code == 200 and version.json()["version"] > 0
+    prod = client_with_site(tmp_path)
+    assert "__qpyserve/version" not in prod.get("/").text
+    assert prod.get("/__qpyserve/version").status_code == 404
+
+
+def test_vite_detection_and_config(tmp_path):
+    (tmp_path / "package.json").write_text('{"devDependencies":{"vite":"^6.0.0"}}')
+    (tmp_path / "vite.config.ts").write_text("export default {}")
+    assert _has_vite(tmp_path)
+    generated = _vite_config(tmp_path, host="127.0.0.1", port=1111, backend_port=1112)
+    text = generated.read_text()
+    assert "vite.config.ts" in text
+    assert "1112" in text
+    assert "strictPort" in text
+
+
+def test_missing_index(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        attach_frontend(FastAPI(), tmp_path)
+
+
+def test_custom_api_path_never_falls_back_to_html(tmp_path):
+    (tmp_path / "index.html").write_text("<html>App</html>")
+    app = FastAPI()
+
+    @app.get("/ws/status")
+    def status():
+        return {"status": "ready"}
+
+    attach_frontend(app, tmp_path, api_paths=["/ws", "/reports"])
+    client = TestClient(app)
+    assert client.get("/ws/status").json() == {"status": "ready"}
+    assert client.get("/ws/missing", headers={"accept": "text/html"}).status_code == 404
+    assert client.get("/reports/missing", headers={"accept": "text/html"}).status_code == 404
+    assert "App" in client.get("/my-page", headers={"accept": "text/html"}).text
+
+
+def test_version_scan_is_cached_for_multiple_clients(tmp_path, monkeypatch):
+    (tmp_path / "index.html").write_text("<html>Test</html>")
+    app = FastAPI()
+    from qpyserve import _frontend
+    scans = []
+    monkeypatch.setattr(_frontend, "_version", lambda _: scans.append(1) or 42)
+    attach_frontend(app, tmp_path, live_reload=True)
+    client = TestClient(app)
+    assert client.get("/__qpyserve/version").json()["version"] == 42
+    assert client.get("/__qpyserve/version").json()["version"] == 42
+    assert scans == [1]
+
+
+def test_hidden_and_project_source_files_not_public(tmp_path):
+    client = client_with_site(tmp_path)
+    for name in (".env", "package.json", "vite.config.js", "app.py", "node_modules/secret.js"):
+        candidate = tmp_path / name
+        candidate.parent.mkdir(parents=True, exist_ok=True)
+        candidate.write_text("SECRET")
+        assert client.get("/" + name).status_code == 404
+    assert client.get("/").headers["cache-control"] == "no-cache"

qpyserve-0.1.0/tests/test_runtime.py

@@ -0,0 +1,49 @@
+import sys
+
+from fastapi import FastAPI
+import pytest
+
+from qpyserve import run
+
+
+def test_run_validates_app(tmp_path):
+    with pytest.raises(TypeError):
+        run(object(), frontend=tmp_path)
+
+
+def test_run_rejects_bad_port(tmp_path):
+    with pytest.raises(ValueError, match="port"):
+        run(FastAPI(), frontend=tmp_path, port=0)
+
+
+def test_run_rejects_multiple_dev_workers(tmp_path):
+    with pytest.raises(ValueError, match="workers"):
+        run(FastAPI(), frontend=tmp_path, workers=2, mode="development")
+
+
+def test_run_rejects_missing_frontend(tmp_path):
+    with pytest.raises(FileNotFoundError, match="Frontend directory"):
+        run(FastAPI(), frontend=tmp_path / "missing", mode="production")
+
+
+def test_build_only_does_not_start_server(tmp_path, monkeypatch):
+    import qpyserve._runtime as rt
+
+    frontend = tmp_path / "frontend"
+    frontend.mkdir()
+    (frontend / "package.json").write_text('{"devDependencies":{"vite":"^6"}}')
+    monkeypatch.setattr(sys, "argv", [str(tmp_path / "main.py"), "--build"])
+    calls = []
+    monkeypatch.setattr(rt, "build_frontend", lambda _: calls.append("build"))
+    monkeypatch.setattr(rt.uvicorn, "run", lambda *_a, **_kw: calls.append("serve"))
+    run(FastAPI(), frontend=frontend)
+    assert calls == ["build"]
+
+
+def test_production_missing_build_explains_one_command_option(tmp_path, monkeypatch):
+    frontend = tmp_path / "frontend"
+    frontend.mkdir()
+    (frontend / "package.json").write_text('{"devDependencies":{"vite":"^6"}}')
+    monkeypatch.setattr(sys, "argv", [str(tmp_path / "main.py")])
+    with pytest.raises(FileNotFoundError, match="--prod --build"):
+        run(FastAPI(), frontend=frontend, mode="production")

qpyserve-0.1.0/tests/test_tooling.py

@@ -0,0 +1,107 @@
+"""No network/npm installation required: subprocess calls are stubbed."""
+
+import json
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+from qpyserve._tooling import (
+    build_frontend, ensure_dependencies, has_vite, normalize_api_paths,
+    package_manager, vite_command, vite_config,
+)
+
+
+def make_vite(tmp_path: Path, *, scripts=None, manager=None):
+    package = {"devDependencies": {"vite": "^6"}, "scripts": scripts or {}}
+    if manager:
+        package["packageManager"] = manager
+    (tmp_path / "package.json").write_text(json.dumps(package))
+    return tmp_path
+
+
+def test_detect_vite_without_dev_script(tmp_path):
+    make_vite(tmp_path)
+    assert has_vite(tmp_path)
+    assert package_manager(tmp_path) == "npm"
+
+
+@pytest.mark.parametrize("lock,expected", [
+    ("package-lock.json", "npm"), ("pnpm-lock.yaml", "pnpm"),
+    ("yarn.lock", "yarn"), ("bun.lock", "bun"),
+])
+def test_choose_lockfile_package_manager(tmp_path, lock, expected):
+    make_vite(tmp_path)
+    (tmp_path / lock).write_text("{}")
+    assert package_manager(tmp_path) == expected
+
+
+def test_package_manager_field_precedes_lockfile(tmp_path):
+    make_vite(tmp_path, manager="pnpm@9.0.0")
+    (tmp_path / "package-lock.json").write_text("{}")
+    assert package_manager(tmp_path) == "pnpm"
+
+
+@pytest.mark.parametrize("invalid", ["/", "api", "//ws", "/a/../b", "/api?x", "/a/*"])
+def test_invalid_api_prefixes(invalid):
+    with pytest.raises(ValueError):
+        normalize_api_paths([invalid])
+
+
+def test_api_paths_deduplicated_and_custom_websocket_proxy(tmp_path):
+    make_vite(tmp_path)
+    paths = normalize_api_paths(["/api", "/ws/", "/reports"])
+    assert paths.count("/api") == 1
+    config = vite_config(tmp_path, host="127.0.0.1", port=1111,
+                         backend_port=1112, api_paths=paths).read_text()
+    assert "^/ws(?:/|$)" in config
+    assert "^/reports(?:/|$)" in config
+    assert '"ws": true' in config
+    assert "1112" in config
+
+
+def test_package_install_is_automatic_and_uses_lockfile(tmp_path, monkeypatch):
+    make_vite(tmp_path)
+    (tmp_path / "package-lock.json").write_text("{}")
+    monkeypatch.setattr("qpyserve._tooling.shutil.which", lambda _: "/usr/bin/npm")
+    call = Mock()
+    monkeypatch.setattr("qpyserve._tooling.subprocess.run", call)
+    assert ensure_dependencies(tmp_path, "npm") == ["/usr/bin/npm"]
+    call.assert_called_once_with(["/usr/bin/npm", "ci"], cwd=tmp_path, check=True)
+
+
+def test_vite_does_not_require_dev_script():
+    assert vite_command(["npm"], "npm", "--config", "generated.mjs") == [
+        "npm", "exec", "--no", "--", "vite", "--config", "generated.mjs"
+    ]
+
+
+def test_build_falls_back_to_vite_without_build_script(tmp_path, monkeypatch):
+    make_vite(tmp_path)
+    monkeypatch.setattr("qpyserve._tooling.ensure_dependencies", lambda *_: ["npm"])
+    call = Mock()
+    monkeypatch.setattr("qpyserve._tooling.subprocess.run", call)
+    build_frontend(tmp_path)
+    call.assert_called_once_with(
+        ["npm", "exec", "--no", "--", "vite", "build"],
+        cwd=tmp_path, check=True,
+    )
+
+
+def test_build_uses_custom_build_script(tmp_path, monkeypatch):
+    make_vite(tmp_path, scripts={"build": "my-custom-build"})
+    monkeypatch.setattr("qpyserve._tooling.ensure_dependencies", lambda *_: ["npm"])
+    call = Mock()
+    monkeypatch.setattr("qpyserve._tooling.subprocess.run", call)
+    build_frontend(tmp_path)
+    call.assert_called_once_with(["npm", "run", "build"], cwd=tmp_path, check=True)
+
+
+def test_yarn_pnp_does_not_require_node_modules(tmp_path, monkeypatch):
+    make_vite(tmp_path)
+    (tmp_path / ".pnp.cjs").touch()
+    monkeypatch.setattr("qpyserve._tooling.shutil.which", lambda _: "/usr/bin/yarn")
+    call = Mock()
+    monkeypatch.setattr("qpyserve._tooling.subprocess.run", call)
+    assert ensure_dependencies(tmp_path, "yarn") == ["/usr/bin/yarn"]
+    call.assert_not_called()