Use ## to allow command be pasted as a whole.

fastapi-vue/fastapi_vue/staticfiles.py

@@ -1,8 +1,10 @@
 """FastAPI static file serving with zstd compression and SPA support."""
 
+from __future__ import annotations
+
+import fnmatch
 import logging
 import mimetypes
-import os
 import time
 from base64 import urlsafe_b64encode
 from functools import partial
@@ -17,29 +19,44 @@ from starlette.exceptions import HTTPException
 from starlette.routing import Route
 from zstandard import ZstdCompressor
 
-# Dev mode: index files but don't load content, return error responses
-_DEVMODE = os.getenv("FASTAPI_VUE_FRONTEND_URL")
-
 logger = logging.getLogger("uvicorn.error")  # Use FastAPI logging style
 
+__all__ = ["Frontend"]
+
+
+class Assets:
+    """Default cached value to /assets/"""
+
+    @staticmethod
+    def parse(cached: str | list[str] | Assets) -> list[str]:
+        match cached:
+            case Assets():
+                return ["/assets/"]
+            case str():
+                return [cached]
+            case list():
+                return cached
+            case _:
+                raise ValueError(f"Invalid cached value: {cached!r}")
+
 
 class Frontend:
     """Static file server with automatic zstd compression and caching.
 
     Features:
     - Automatic zstd compression for compressible files
-    - ETag-based caching with configurable cache headers
+    - ETag-based caching of immutable assets
     - SPA (Single Page Application) support
-    - Favicon handling from hashed assets
+    - /favicon.ico with correct MIME type (image/png etc)
     - Dev mode: indexes files but returns error directing to Vite server
 
     Args:
         directory: Path to the directory containing static files
         index: Name of the index file (default: "index.html")
         spa: Enable SPA mode - serve index.html for unknown routes (default: False)
-        cached: Path prefixes that should have immutable cache headers
+        cached: Path prefixes that are immutable (default: "/assets/")
+        favicon: May use wildcards of full path. E.g. /assets/logo*.png matches logo.hash.png created by Vite
         zstdlevel: Zstd compression level (default: 18)
-        favicon: Path to favicon for automatic /favicon.ico handling
     """
 
     def __init__(
@@ -49,24 +66,18 @@ class Frontend:
         index: str = "index.html",
         spa: bool = False,
         catch_all: bool | None = None,
-        cached: str | list[str] | None = None,
-        zstdlevel: int = 18,
+        cached: str | list[str] | Assets = Assets(),
         favicon: str | None = None,
+        zstdlevel: int = 18,
     ) -> None:
         self.www: dict[str, tuple[bytes, bytes | None, dict]] = {}
         self.base: Path = Path(directory)
         self.index = index
         self.spa = spa
         self._catch_all = spa if catch_all is None else catch_all
-        if cached is None:
-            self.cached_paths = []
-        elif isinstance(cached, str):
-            self.cached_paths = [cached]
-        else:
-            self.cached_paths = cached
+        self.cached_paths = Assets.parse(cached)
         self.zstdlevel = zstdlevel
         self.favicon = favicon
-        self.devmode = bool(_DEVMODE)
         self._app: FastAPI | None = None
         self._mount_path: str = ""
         self._ridx: int = 0
@@ -132,15 +143,11 @@ class Frontend:
                     zstd = None
                 www[name] = data, zstd, headers
         if self.favicon:
-            p = PurePosixPath(self.favicon)
-            base = str(p.with_suffix(""))
-            ext = p.suffix
-            hashed_path = next(
-                (path for path in www if path.startswith(base) and path.endswith(ext)),
-                None,
-            )
-            if hashed_path:
-                www["/favicon.ico"] = www[hashed_path]
+            if m := fnmatch.filter(www, self.favicon):
+                data, zstd, headers = www[m[0]]
+                if "immutable" in headers.get("cache-control", ""):
+                    headers = {**headers, "cache-control": "max-age=86400"}
+                www["/favicon.ico"] = data, zstd, headers
         if not www:
             msg = "Frontend files missing, check your installation.\n"
             www["/"] = (
@@ -154,12 +161,15 @@ class Frontend:
             )
         return www
 
-    async def load(self, *, log=True):
+    async def load(self, *, debug: bool | None = None, log: bool = True):
         """Load or reload static files from disk.
 
-        In dev mode (FASTAPI_VUE_FRONTEND_URL set), only indexes paths without loading content.
+        In debug mode, returns 409 instead of files (avoid accidental use of stale builds)
+        If debug is None, uses app.debug (app passed to frontend.route)
         """
-        if self.devmode:
+        if debug is None:
+            debug = getattr(self._app, "debug", False)
+        if debug:
             # Dev mode: just index paths, no content loading
             self._devmode_paths = await run_in_threadpool(self._index_only)
             self._register_routes()
@@ -180,6 +190,8 @@ class Frontend:
                 f"{self.base.name}: {len(self.www)} files in {1000 * duration:.1f} ms | "
                 f"zstd {len(compfiles)} files {1e-6 * raw:.2f}->{1e-6 * comp:.2f} MB ({ratio:.0f} %)"
             )
+        if self.favicon and "/favicon.ico" not in self.www:
+            logger.warning("Favicon not found: %s", self.favicon)
 
     def route(self, app: FastAPI, mount_path="/"):
         """Register frontend routes with a FastAPI app.
@@ -214,13 +226,14 @@ class Frontend:
         self._routes.clear()
 
         # Get paths and select handler based on mode (checked once, not per request)
-        paths = self._devmode_paths if self.devmode else self.www.keys()
-        handler = _devmode_respond if self.devmode else self._respond
+        debug = getattr(self._app, "debug", False)
+        paths = self._devmode_paths if debug else self.www.keys()
+        handler = _devmode_respond if debug else self._respond
         # Insert at the position where route() was called
         self._app.routes[self._ridx : self._ridx] = self._routes = [
             Route(
                 self._mount_path + p,
-                endpoint=handler if self.devmode else partial(handler, name=p),
+                endpoint=handler if debug else partial(handler, name=p),
                 methods=["GET", "HEAD"],
                 name=f"frontend{p.replace('/', '_')}",
             )
@@ -241,7 +254,8 @@ class Frontend:
     def handle(self, request: Request, path: str):
         """SPA catch-all handler with directory redirects and fallback to index."""
         name = path.removesuffix(self.index)
-        files = self._devmode_paths if self.devmode else self.www
+        debug = getattr(self._app, "debug", False)
+        files = self._devmode_paths if debug else self.www
 
         if name not in files:
             # Friendly redirect for directories missing trailing slash
@@ -254,7 +268,7 @@ class Frontend:
             if name not in files:
                 raise HTTPException(status_code=404)
 
-        return (_devmode_respond if self.devmode else self._respond)(request, name)
+        return (_devmode_respond if debug else self._respond)(request, name)
 
 
 def _devmode_respond(request: Request, name=""):
@@ -262,6 +276,6 @@ def _devmode_respond(request: Request, name=""):
     return JSONResponse(
         status_code=409,
         content={
-            "detail": f"Frontend assets served by Vite in dev mode. Connect via {_DEVMODE} instead."
+            "detail": "Frontend assets served by Vite in debug mode. You are on backend, connect to frontend instead."
         },
     )

fastapi_vue_setup.py

@@ -8,10 +8,12 @@ Usage:
 Options:
     --module-name NAME      Python module name (auto-detected from pyproject.toml)
     --ports DEFAULT,VITE,DEV  Port configuration (default: 3100,3100,3200)
-    --dry-run               Show what would be done without making changes
+    --dry                   Show what would be done without making changes
 """
 
 import argparse
+import ast
+import importlib.metadata
 import os
 import re
 import shutil
@@ -22,9 +24,56 @@ from textwrap import indent
 
 import tomlkit
 
+version = importlib.metadata.version("fastapi-vue-setup")
+
+# Track Python files written/patched for ruff formatting
+_python_files_to_format: list[Path] = []
+
 # Template directory
 TEMPLATE_DIR = Path(__file__).parent / "template"
 
+
+def print_boxed(text: str) -> None:
+    """Print text in a Unicode rounded box."""
+    width = len(text) + 2
+    print(f"╭{'─' * width}╮")
+    print(f"│ {text} │")
+    print(f"╰{'─' * width}╯")
+
+
+def ruff_sort_imports(files: list[Path], dry: bool = False) -> None:
+    """Run ruff to sort imports in the given Python files."""
+    if not files:
+        return
+    py_files = [str(f) for f in files if f.suffix == ".py" and f.exists()]
+    if not py_files:
+        return
+    if dry:
+        print(f"🔧 Would run ruff import sorting on {len(py_files)} files")
+        return
+    print("🔧 Ruff isort on modified files")
+    subprocess.run(
+        [sys.executable, "-m", "ruff", "check", "--select", "I", "--fix", *py_files],
+        stdout=subprocess.DEVNULL,
+    )
+
+
+def uv_add_packages(
+    packages: list[str], *, cwd: Path, group: str | None = None
+) -> None:
+    """Add packages using uv."""
+    cmd = ["uv", "add", "-q", "-U"]
+    if group:
+        cmd.extend(["--group", group])
+    else:
+        cmd.append("--no-sync")
+    cmd.extend(packages)
+    result = subprocess.run(cmd, cwd=cwd, check=False)
+    if result.returncode != 0:
+        label = f" ({group})" if group else ""
+        print(f"⚠️  Failed to add{label} dependencies")
+
+
 # Default ports: (default, vite, dev)
 # If vite == dev, dev is incremented by 100
 DEFAULT_PORTS = (3100, 3100, 3200)
@@ -57,7 +106,16 @@ PYPROJECT_ADDITIONS = {
 # Frontend instantiation block for patching existing apps
 FRONTEND_BLOCK = """
 # Vue Frontend static files
-frontend = Frontend(Path(__file__).with_name("frontend-build"), cached=["/assets/"])
+frontend = Frontend(Path(__file__).with_name("frontend-build"))
+"""
+
+# Lifespan block for patching apps that don't have one
+LIFESPAN_BLOCK = """
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    \"\"\"Manage app startup and shutdown resources.\"\"\"
+    await frontend.load()
+    yield
 """
 
 # TypeScript health check script for Vue components
@@ -68,7 +126,7 @@ const backendStatus = ref<'checking' | 'connected' | 'error'>('checking')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/health')
+    const res = await fetch('/api/health?from=frontend')
     backendStatus.value = res.ok ? 'connected' : 'error'
   } catch {
     backendStatus.value = 'error'
@@ -84,7 +142,7 @@ const backendStatus = ref('checking')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/health')
+    const res = await fetch('/api/health?from=frontend')
     backendStatus.value = res.ok ? 'connected' : 'error'
   } catch {
     backendStatus.value = 'error'
@@ -103,17 +161,16 @@ STATUS_SPAN_TEMPLATE = """\
 """
 
 # Setup complete message template
-SETUP_COMPLETE_MESSAGE = """
-Next steps:
-
-1. Build for production:
-   CD_CMDuv build
-
-2. Start development server:
+SETUP_COMPLETE_MESSAGE = """\
+## Development server: (live reloads, debug)
 CD_CMDuv run scripts/devserver.py
 
-3. Run production server:
-   CD_CMDuv run SCRIPT_NAME
+## Production build:
+CD_CMDuv build && uv run SCRIPT_NAME
+
+## Release Python package, run anywhere:
+CD_CMDuv build && uv publish
+uvx SCRIPT_NAME  # No Node required
 """
 
 
@@ -153,6 +210,24 @@ def parse_ports(ports_str: str | None) -> tuple[int, int, int]:
     return default, vite, dev
 
 
+def find_import_insertion_line(source: str) -> int:
+    """Find line number (1-based) for inserting imports, after shebang/docstring."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 2 if source.startswith("#!") else 1
+    # Find first import, or end of docstring if no imports
+    for node in tree.body:
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            return node.lineno
+        if not (isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant)):
+            break  # Non-import, non-docstring statement
+    # No imports found - insert after docstring or at line 1
+    if tree.body and isinstance(tree.body[0], ast.Expr):
+        return tree.body[0].end_lineno + 1
+    return 2 if source.startswith("#!") else 1
+
+
 def extract_existing_ports(project_dir: Path) -> tuple[int, int, int] | None:
     """Extract existing port configuration from project files.
 
@@ -417,11 +492,11 @@ def render_template(template: str, **kwargs) -> str:
 
 
 def patch_app_file(
-    path: Path, module_name: str, app_var: str, dry_run: bool = False
+    path: Path, module_name: str, app_var: str, dry: bool = False
 ) -> bool:
     """Patch an existing app.py with frontend integration.
 
-    Inserts import and Frontend instantiation after imports, route at bottom,
+    Inserts imports at top (ruff will sort them), route at bottom,
     and tries to patch lifespan with frontend.load().
 
     Returns True if patched, False if already patched or failed.
@@ -431,73 +506,156 @@ def patch_app_file(
         return False
 
     original_content = path.read_text("UTF-8")
-    marker = "from fastapi_vue import Frontend"
+    content = original_content
 
-    if marker in original_content:
+    # Check what's already patched
+    has_frontend = "from fastapi_vue import Frontend" in content
+    has_devmode = f"from {module_name}.__main__ import DEVMODE" in content
+    has_debug_arg = re.search(r"FastAPI\s*\([^)]*debug\s*=", content) is not None
+    has_lifespan = "await frontend.load()" in content
+
+    if has_frontend and has_devmode and has_debug_arg and has_lifespan:
         print(f"✔️  {path} (already patched)")
         return False
 
-    # Find where to insert the import (after other imports)
-    lines = original_content.split("\n")
-    import_line = "from fastapi_vue import Frontend"
-
     route_line = f'frontend.route({app_var}, "/")'
 
-    # Find last import line and check if pathlib is imported
+    # Add missing imports (using AST to find correct insertion point)
+    imports = []
+    if not has_frontend:
+        imports.extend(["from pathlib import Path", "from fastapi_vue import Frontend"])
+    if not has_devmode:
+        imports.append(f"from {module_name}.__main__ import DEVMODE")
+    if imports:
+        insert_line = find_import_insertion_line(content)
+        lines = content.splitlines(keepends=True)
+        # Convert to 0-based index
+        insert_idx = insert_line - 1
+        import_text = "\n".join(imports) + "\n"
+        if insert_idx >= len(lines):
+            # Append at end
+            content = content.rstrip("\n") + "\n" + import_text
+        else:
+            # Insert at the found position
+            content = (
+                "".join(lines[:insert_idx]) + import_text + "".join(lines[insert_idx:])
+            )
+
+    # Insert FRONTEND_BLOCK after last import (only if Frontend wasn't already there)
+    if not has_frontend:
+        lines = content.split("\n")
         last_import_idx = 0
-    has_pathlib = False
         for i, line in enumerate(lines):
             stripped = line.strip()
             if stripped.startswith("import ") or stripped.startswith("from "):
                 last_import_idx = i
-            if "pathlib" in stripped or "from pathlib" in stripped:
-                has_pathlib = True
             elif stripped and not stripped.startswith("#") and last_import_idx > 0:
-            # Stop at first non-import, non-comment, non-empty line after imports
                 break
+        lines.insert(last_import_idx + 1, FRONTEND_BLOCK)
+        content = "\n".join(lines)
 
-    # Check if we found imports to insert after
-    if last_import_idx == 0 and not lines[0].strip().startswith(("import ", "from ")):
-        print(f"⚠️  Skipping {path} (no imports found to patch)")
-        return False
-
-    # Insert imports after last import, then frontend instantiation
-    if not has_pathlib:
-        lines.insert(last_import_idx + 1, "from pathlib import Path")
-        last_import_idx += 1
-    lines.insert(last_import_idx + 1, import_line)
-    lines.insert(last_import_idx + 2, FRONTEND_BLOCK)
-
-    # Append route at end
+    # Append route at end (only if not already present)
+    if route_line not in content:
+        lines = content.split("\n")
         lines.append("")
-    lines.append("# Serve the Vue frontend (needs to be last if SPA catch-all is used)")
+        lines.append(
+            "# Serve the Vue frontend (needs to be last if SPA catch-all is used)"
+        )
         lines.append(route_line)
         content = "\n".join(lines)
 
+    # Try to patch FastAPI() call with debug=DEVMODE if no debug arg exists
+    if not has_debug_arg:
+        fastapi_pattern = r"(\w+\s*=\s*FastAPI\s*\()([^)]*)\)"
+        for match in re.finditer(fastapi_pattern, content, re.DOTALL):
+            args = match.group(2)
+            if "debug" not in args:
+                # Add debug=DEVMODE as last argument
+                if args.strip():
+                    new_args = f"{args}, debug=DEVMODE"
+                else:
+                    new_args = "debug=DEVMODE"
+                content = (
+                    content[: match.start()]
+                    + match.group(1)
+                    + new_args
+                    + ")"
+                    + content[match.end() :]
+                )
+                break  # Only patch first FastAPI() call
+
     # Try to patch lifespan function - insert await frontend.load() before yield
-    lifespan_patched = False
+    lifespan_patched = "await frontend.load()" in content
 
     # Look for yield inside an async def lifespan function
     # Find the yield statement and insert before it
+    if not lifespan_patched:
         yield_pattern = r"^([ \t]+)(yield\b)"
         yield_match = re.search(yield_pattern, content, re.MULTILINE)
         if yield_match:
-        indent = yield_match.group(1)
+            ws = yield_match.group(1)
             insert_pos = yield_match.start()
-        load_code = f"{indent}await frontend.load()\n"
+            load_code = f"{ws}await frontend.load()\n"
             content = content[:insert_pos] + load_code + content[insert_pos:]
             lifespan_patched = True
 
+    # No lifespan at all: create one and wire it into FastAPI()
+    if not lifespan_patched and f"@{app_var}.on_event" not in content:
+        # Add contextlib import
+        if "from contextlib import asynccontextmanager" not in content:
+            insert_line = find_import_insertion_line(content)
+            lines = content.splitlines(keepends=True)
+            insert_idx = insert_line - 1
+            import_text = "from contextlib import asynccontextmanager\n"
+            if insert_idx >= len(lines):
+                content = content.rstrip("\n") + "\n" + import_text
+            else:
+                content = (
+                    "".join(lines[:insert_idx])
+                    + import_text
+                    + "".join(lines[insert_idx:])
+                )
+
+        # Insert lifespan block before the FastAPI() call
+        fastapi_line_pattern = r"^(\w+\s*=\s*FastAPI\s*\()"
+        fastapi_match = re.search(fastapi_line_pattern, content, re.MULTILINE)
+        if fastapi_match:
+            content = (
+                content[: fastapi_match.start()]
+                + LIFESPAN_BLOCK.lstrip("\n")
+                + "\n"
+                + content[fastapi_match.start() :]
+            )
+
+        # Add lifespan=lifespan to FastAPI() call
+        fastapi_pattern = r"(\w+\s*=\s*FastAPI\s*\()([^)]*)\)"
+        fastapi_match = re.search(fastapi_pattern, content, re.DOTALL)
+        if fastapi_match and "lifespan" not in fastapi_match.group(2):
+            args = fastapi_match.group(2)
+            if args.strip():
+                new_args = f"{args}, lifespan=lifespan"
+            else:
+                new_args = "lifespan=lifespan"
+            content = (
+                content[: fastapi_match.start()]
+                + fastapi_match.group(1)
+                + new_args
+                + ")"
+                + content[fastapi_match.end() :]
+            )
+        lifespan_patched = True
+
     # Check if content actually changed
     if content == original_content:
         print(f"⚠️  Skipping {path} (no changes needed)")
         return False
 
-    if dry_run:
-        print(f"[DRY RUN] Would patch {path}")
+    if dry:
+        print(f"✅ Would patch {path}")
         return True
 
     path.write_text(content, "UTF-8", newline="\n")
+    _python_files_to_format.append(path)
     print(f"✅ Patched {path}")
 
     if not lifespan_patched:
@@ -521,7 +679,7 @@ def patch_app_file(
 def patch_vite_config(
     path: Path,
     module_name: str,
-    dry_run: bool = False,
+    dry: bool = False,
 ) -> bool:
     """Patch an existing vite.config.js/ts by adding fastapi-vue plugin.
 
@@ -583,8 +741,8 @@ def patch_vite_config(
         print(f"ℹ️  Skipping {path} (no changes needed)")
         return False
 
-    if dry_run:
-        print(f"[DRY RUN] Would patch {path}")
+    if dry:
+        print(f"✅ Would patch {path}")
         return True
 
     path.write_text(content, "UTF-8", newline="\n")
@@ -592,7 +750,7 @@ def patch_vite_config(
     return True
 
 
-def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bool:
+def patch_frontend_health_check(frontend_dir: Path, dry: bool = False) -> bool:
     """Patch Vue app to include FastAPI backend health check.
 
     Tries HelloWorld.vue first (full demo), then falls back to App.vue (minimal).
@@ -683,8 +841,8 @@ def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bo
         print(f"ℹ️  Skipping {target_file} (no changes needed)")
         return False
 
-    if dry_run:
-        print(f"[DRY RUN] Would patch {target_file}")
+    if dry:
+        print(f"✅ Would patch {target_file}")
         return True
 
     target_file.write_text(content, "UTF-8", newline="\n")
@@ -692,6 +850,40 @@ def patch_frontend_health_check(frontend_dir: Path, dry_run: bool = False) -> bo
     return True
 
 
+# SHA-256 of old vite-plugin-fastapi.js (before auto-upgrade marker was added)
+# with module name replaced by MODULE_NAME in the outDir path
+_OLD_VITE_PLUGIN_SHA256 = (
+    "93713e879c15a25c750a70ce1de684adeaf11b0c723c38da56e5e7ba207f6632"
+)
+
+
+def _upgrade_old_vite_plugin(path: Path, module_name: str, dry: bool = False) -> None:
+    """Remove old vite-plugin-fastapi.js that lacks auto-upgrade marker.
+
+    Old versions didn't have the upgrade marker, so write_file skips them as
+    'customized by user'. We recognize the old version by normalizing the module
+    name in outDir and comparing the SHA-256 hash.
+    """
+    if not path.exists():
+        return
+    content = path.read_text("UTF-8")
+    if UPGRADE_MARKER in content:
+        return  # Already new format, write_file handles it
+    import hashlib
+
+    normalized = content.replace(
+        f"../{module_name}/frontend-build", "../MODULE_NAME/frontend-build"
+    )
+    digest = hashlib.sha256(normalized.encode()).hexdigest()
+    if digest != _OLD_VITE_PLUGIN_SHA256:
+        return  # Modified by user, don't touch
+    if dry:
+        print(f"🔄 Would upgrade old {path}")
+        return
+    path.unlink()
+    print(f"🔄 Removing old {path} (will be replaced)")
+
+
 # Track .new.py files written during setup (for merge notification)
 _new_files_written: list[tuple[Path, Path]] = []
 
@@ -700,7 +892,7 @@ def write_file(
     path: Path,
     content: str,
     overwrite: bool = True,
-    dry_run: bool = False,
+    dry: bool = False,
     executable: bool = False,
     fallback_path: Path | None = None,
     force: bool = False,
@@ -729,20 +921,22 @@ def write_file(
             if fallback_path is not None:
                 # Write to fallback path instead
                 return _write_fallback_file(
-                    path, fallback_path, content, dry_run, executable
+                    path, fallback_path, content, dry, executable
                 )
             print(f"ℹ️  Skipping {path} (customized by user)")
             return False
 
-    if dry_run:
+    if dry:
         action = "overwrite" if exists else "create"
-        print(f"[DRY RUN] Would {action} {path}")
+        print(f"✅ Would {action} {path}")
         return True
 
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(content, "UTF-8", newline="\n")
     if executable and sys.platform != "win32":
         path.chmod(path.stat().st_mode | 0o111)
+    if path.suffix == ".py":
+        _python_files_to_format.append(path)
     action = "Updated" if exists else "Created"
     print(f"✅ {action} {path}")
     return True
@@ -752,7 +946,7 @@ def _write_fallback_file(
     original_path: Path,
     fallback_path: Path,
     content: str,
-    dry_run: bool,
+    dry: bool,
     executable: bool,
 ) -> bool:
     """Write content to a fallback .new.py file when original can't be overwritten."""
@@ -762,8 +956,8 @@ def _write_fallback_file(
             print(f"✔️  {fallback_path} (already up to date)")
             return False
 
-    if dry_run:
-        print(f"[DRY RUN] Would create {fallback_path} (original customized by user)")
+    if dry:
+        print(f"✅ Would create {fallback_path} (original customized by user)")
         _new_files_written.append((fallback_path, original_path))
         return True
 
@@ -771,6 +965,8 @@ def _write_fallback_file(
     fallback_path.write_text(content, "UTF-8", newline="\n")
     if executable and sys.platform != "win32":
         fallback_path.chmod(fallback_path.stat().st_mode | 0o111)
+    if fallback_path.suffix == ".py":
+        _python_files_to_format.append(fallback_path)
     print(f"✅ Created {fallback_path} (original customized by user)")
     _new_files_written.append((fallback_path, original_path))
     return True
@@ -897,14 +1093,14 @@ def find_js_runtime() -> tuple[str, str] | None:
     return None
 
 
-def ensure_python_project(project_dir: Path, dry_run: bool = False) -> bool:
+def ensure_python_project(project_dir: Path, dry: bool = False) -> bool:
     """Ensure pyproject.toml exists, run uv init if needed."""
     pyproject = project_dir / "pyproject.toml"
     if pyproject.exists():
         return True
 
-    if dry_run:
-        print(f"[DRY RUN] Would run: uv init {project_dir}")
+    if dry:
+        print(f"📦 Would run: uv init {project_dir}")
         return True
 
     print("📦 No pyproject.toml found, initializing Python project...")
@@ -923,7 +1119,7 @@ def ensure_python_project(project_dir: Path, dry_run: bool = False) -> bool:
     return True
 
 
-def ensure_frontend(project_dir: Path, dry_run: bool = False) -> bool:
+def ensure_frontend(project_dir: Path, dry: bool = False) -> bool:
     """Ensure frontend directory exists with a Vue project, run create-vue if needed."""
     frontend_dir = project_dir / "frontend"
     package_json = frontend_dir / "package.json"
@@ -947,8 +1143,8 @@ def ensure_frontend(project_dir: Path, dry_run: bool = False) -> bool:
     }
     create_cmd = create_vue_commands[js_name]
 
-    if dry_run:
-        print(f"[DRY RUN] Would run: {' '.join(create_cmd)}")
+    if dry:
+        print(f"🎨 Would run: {' '.join(create_cmd)}")
         return True
 
     print("🎨 No frontend/ found, creating Vue project...")
@@ -987,27 +1183,28 @@ def cmd_setup(args: argparse.Namespace) -> int:
         project_dir = Path.cwd() / project_path
 
     project_dir = project_dir.resolve()
-    dry_run = args.dry_run
+    dry = args.dry
+
+    print_boxed(f"fastapi-vue-setup {version}")
+    if dry:
+        print("🏃 DRY RUN MODE - no changes will be made\n")
 
     # Create project directory if it doesn't exist
     if not project_dir.exists():
-        if dry_run:
-            print(f"[DRY RUN] Would create directory: {project_dir}")
+        if dry:
+            print(f"✅ Would create directory: {project_dir}")
         else:
             project_dir.mkdir(parents=True)
             print(f"✅ Created {project_dir}")
 
     print(f"🔧 Setting up project: {project_dir}")
 
-    if dry_run:
-        print("\n🏃 DRY RUN MODE - no changes will be made\n")
-
     # Step 1: Ensure frontend exists (do this first so cancellation doesn't leave partial setup)
-    if not ensure_frontend(project_dir, dry_run):
+    if not ensure_frontend(project_dir, dry):
         return 1
 
     # Step 2: Ensure Python project exists
-    if not ensure_python_project(project_dir, dry_run):
+    if not ensure_python_project(project_dir, dry):
         return 1
 
     # Detect module name
@@ -1015,11 +1212,8 @@ def cmd_setup(args: argparse.Namespace) -> int:
     if not module_name:
         # Derive from directory name
         module_name = project_dir.name.replace("-", "_")
-        print(f"📦 Using module name from directory: {module_name}")
-
-    # Title for templates
-    project_title = module_name.replace("_", " ").title()
-
+        print(f"📦 Module: {module_name} (from directory name)")
+    else:
         print(f"📦 Module: {module_name}")
 
     # Determine port configuration
@@ -1040,6 +1234,9 @@ def cmd_setup(args: argparse.Namespace) -> int:
         f"📡 Ports: default={default_port}, vite={vite_port}, dev={dev_port} {ports_note}"
     )
 
+    # Title for templates
+    project_title = module_name.replace("_", " ").title()
+
     # Template variables
     tpl_vars = {
         "MODULE_NAME": module_name,
@@ -1047,6 +1244,8 @@ def cmd_setup(args: argparse.Namespace) -> int:
         "TEMPLATE_DEFAULT_PORT": str(default_port),
         "TEMPLATE_VITE_PORT": str(vite_port),
         "TEMPLATE_DEV_PORT": str(dev_port),
+        "ENVPREFIX": module_name.upper(),
+        "PROJECT_CLI": module_name,
     }
 
     module_dir = project_dir / module_name
@@ -1071,7 +1270,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         tpl_vars["APP_MODULE"] = "app"
 
     # Create directories
-    if not dry_run:
+    if not dry:
         if not module_dir.exists():
             module_dir.mkdir(parents=True)
         fastapi_vue_scripts.mkdir(parents=True, exist_ok=True)
@@ -1083,8 +1282,8 @@ def cmd_setup(args: argparse.Namespace) -> int:
     # Remove obsolete util.py if present
     obsolete_util = fastapi_vue_scripts / "util.py"
     if obsolete_util.exists():
-        if dry_run:
-            print(f"[DRY RUN] Would remove obsolete {obsolete_util}")
+        if dry:
+            print(f"🗑️ Would remove obsolete {obsolete_util}")
         else:
             obsolete_util.unlink()
             print(f"🗑️  Removed obsolete {obsolete_util}")
@@ -1100,7 +1299,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
                 dest_path,
                 content,
                 overwrite=True,
-                dry_run=dry_run,
+                dry=dry,
                 force=True,  # Internal files, always overwrite
             )
 
@@ -1113,7 +1312,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
         devserver_path,
         content,
         overwrite=True,
-        dry_run=dry_run,
+        dry=dry,
         executable=True,
         fallback_path=devserver_fallback,
     )
@@ -1121,7 +1320,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
     # === Handle app module ===
     if app_file:
         # Existing app: patch with import, route, and try to patch lifespan
-        patch_app_file(app_file, module_name, app_var, dry_run=dry_run)
+        patch_app_file(app_file, module_name, app_var, dry=dry)
     else:
         # No app: create full app.py
         # Create __init__.py if missing
@@ -1129,13 +1328,13 @@ def cmd_setup(args: argparse.Namespace) -> int:
         if not init_file.exists():
             template = load_template("backend/__init__.py")
             content = render_template(template, **tpl_vars)
-            write_file(init_file, content, overwrite=False, dry_run=dry_run)
+            write_file(init_file, content, overwrite=False, dry=dry)
 
         # Create app.py
         app_file_path = module_dir / "app.py"
         template = load_template("backend/app.py")
         content = render_template(template, **tpl_vars)
-        write_file(app_file_path, content, overwrite=False, dry_run=dry_run)
+        write_file(app_file_path, content, overwrite=False, dry=dry)
 
     # === Handle __main__.py ===
     main_file = module_dir / "__main__.py"
@@ -1152,7 +1351,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
             main_file,
             main_content,
             overwrite=True,
-            dry_run=dry_run,
+            dry=dry,
             fallback_path=main_fallback,
         )
     elif not existing_cli:
@@ -1161,7 +1360,7 @@ def cmd_setup(args: argparse.Namespace) -> int:
             main_file,
             main_content,
             overwrite=False,
-            dry_run=dry_run,
+            dry=dry,
         )
     else:
         # No file but has existing entrypoint - don't create (user has custom CLI setup)
@@ -1172,24 +1371,26 @@ def cmd_setup(args: argparse.Namespace) -> int:
     if frontend_dir.exists():
         # Install the vite plugin file (always update)
         plugin_file = frontend_dir / "vite-plugin-fastapi.js"
+        # Upgrade old plugin versions that lack the auto-upgrade marker
+        _upgrade_old_vite_plugin(plugin_file, module_name, dry)
         template = load_template("frontend/vite-plugin-fastapi.js")
         content = render_template(template, **tpl_vars)
-        write_file(plugin_file, content, overwrite=True, dry_run=dry_run)
+        write_file(plugin_file, content, overwrite=True, dry=dry)
 
         # Find existing vite config (prefer .ts, fall back to .js)
         vite_config_ts = frontend_dir / "vite.config.ts"
         vite_config_js = frontend_dir / "vite.config.js"
 
         if vite_config_ts.exists():
-            patch_vite_config(vite_config_ts, module_name, dry_run)
+            patch_vite_config(vite_config_ts, module_name, dry)
         elif vite_config_js.exists():
-            patch_vite_config(vite_config_js, module_name, dry_run)
+            patch_vite_config(vite_config_js, module_name, dry)
         else:
             print("⚠️  No vite.config.ts or vite.config.js found in frontend/")
             print("   Run create-vue first to generate a Vite config to patch.")
 
         # Patch Vue app with backend health check
-        patch_frontend_health_check(frontend_dir, dry_run)
+        patch_frontend_health_check(frontend_dir, dry)
 
     # === Update pyproject.toml ===
     pyproject_path = project_dir / "pyproject.toml"
@@ -1210,8 +1411,8 @@ def cmd_setup(args: argparse.Namespace) -> int:
 
         if new_content == old_content:
             print(f"✔️  {pyproject_path} (already up to date)")
-        elif dry_run:
-            print(f"[DRY RUN] Would update {pyproject_path}")
+        elif dry:
+            print(f"✅ Would update {pyproject_path}")
         else:
             pyproject_path.write_text(new_content, "UTF-8", newline="\n")
             print(f"✅ Updated {pyproject_path}")
@@ -1223,8 +1424,8 @@ def cmd_setup(args: argparse.Namespace) -> int:
         gitignore_content = gitignore_path.read_bytes()
         if b"frontend-build" in gitignore_content:
             print("✔️  .gitignore (frontend-build already ignored)")
-        elif dry_run:
-            print(f"[DRY RUN] Would add {gitignore_entry} to .gitignore")
+        elif dry:
+            print(f"✅ Would add {gitignore_entry} to .gitignore")
         else:
             nl = b"\r\n" if b"\r\n" in gitignore_content else b"\n"
             suffix = b"" if gitignore_content.endswith(nl) else nl
@@ -1232,42 +1433,26 @@ def cmd_setup(args: argparse.Namespace) -> int:
                 gitignore_content + suffix + gitignore_entry.encode() + nl
             )
             print(f"✅ Added {gitignore_entry} to .gitignore")
-    elif dry_run:
-        print(f"[DRY RUN] Would create .gitignore with {gitignore_entry}")
+    elif dry:
+        print(f"✅ Would create .gitignore with {gitignore_entry}")
     else:
         gitignore_path.write_text(f"{gitignore_entry}\n", "UTF-8", newline="\n")
         print("✅ Created .gitignore")
 
     # === Add dependencies using uv ===
-    uv_add_main = [
-        "uv",
-        "add",
-        "-q",
-        "-U",
-        "--no-sync",
-        "fastapi[standard]",
-        "fastapi-vue",
-    ]
-    uv_add_dev = ["uv", "add", "-q", "-U", "--group", "dev", "httpx"]
-    if dry_run:
-        print(f"[DRY RUN] Would run: {' '.join(uv_add_main)}")
-        print(f"[DRY RUN] Would run: {' '.join(uv_add_dev)}")
+    ruff_sort_imports(_python_files_to_format, dry=dry)
+    if dry:
+        print("📦 Would add: fastapi[standard], fastapi-vue, httpx (dev only)")
     else:
-        print("📦 Adding dependencies...")
-        result = subprocess.run(uv_add_main, cwd=project_dir, check=False)
-        if result.returncode != 0:
-            print("⚠️  Failed to add main dependencies")
-        result = subprocess.run(uv_add_dev, cwd=project_dir, check=False)
-        if result.returncode != 0:
-            print("⚠️  Failed to add dev dependencies")
+        print("📦 Dependencies")
+        uv_add_packages(["fastapi[standard]", "fastapi-vue"], cwd=project_dir)
+        uv_add_packages(["httpx"], cwd=project_dir, group="dev")
 
     print()
-    print("=" * 60)
-    print("✅ Setup complete!")
-    print("=" * 60)
+    print_boxed("Setup complete!")
 
     # Show cd command only if project is not in current directory
-    cd_cmd = "" if project_dir == Path.cwd() else f"cd {project_dir}\n   "
+    cd_cmd = "" if project_dir == Path.cwd() else f"cd {project_dir}; "
     script_name = module_name.replace("_", "-")
 
     message = SETUP_COMPLETE_MESSAGE.replace("CD_CMD", cd_cmd).replace(
@@ -1291,11 +1476,6 @@ def cmd_setup(args: argparse.Namespace) -> int:
     return 0
 
 
-# =============================================================================
-# Main entry point
-# =============================================================================
-
-
 def is_uninitialized_folder(path: Path) -> bool:
     """Check if a folder appears to be completely uninitialized."""
     return (
@@ -1318,14 +1498,14 @@ def is_already_patched(path: Path) -> bool:
 
 def main() -> int:
     parser = argparse.ArgumentParser(
-        description="Set up FastAPI+Vue projects with integrated build/dev systems",
+        description=f"fastapi-vue-setup {version} - FastAPI + Vue project setup tool",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
   fastapi-vue-setup my-new-project     Create a new project from scratch
   fastapi-vue-setup .                  Set up integration in current directory
-  fastapi-vue-setup . --dry-run        Preview what would be done
-  fastapi-vue-setup . --ports 8000,5173,8080  Custom ports (default,vite,dev)
+  fastapi-vue-setup . --dry            Preview what would be done
+  fastapi-vue-setup . --ports=8000,5173,8080  Change default ports (backend, vite dev, backend dev)
 """,
     )
     parser.add_argument(
@@ -1334,14 +1514,15 @@ Examples:
         default=None,
         help="Project directory (use . for current directory)",
     )
+    parser.add_argument("--version", action="version", version=version)
     parser.add_argument("--module-name", help="Python module name (auto-detected)")
     parser.add_argument(
         "--ports",
-        metavar="DEFAULT,VITE,DEV",
+        metavar="BACKEND,VITE,DEV",
         help="Port configuration as comma-separated values (default: 3100,3100,3200)",
     )
     parser.add_argument(
-        "--dry-run", action="store_true", help="Show what would be done"
+        "--dry", "--dry-run", action="store_true", help="Show what would be done"
     )
 
     args = parser.parse_args()

pyproject.toml

@@ -9,6 +9,7 @@ description = "Tool to create or patch FastAPI+Vue projects with integrated buil
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
+    "ruff>=0.14.13",
     "tomlkit>=0.12.0",
 ]
 
@@ -26,4 +27,7 @@ source = "vcs"
 include = ["fastapi_vue_setup.py", "template/**/*", "_version.py"]
 
 [dependency-groups]
-dev = ["ruff"]
+dev = ["ruff", "fastapi-vue"]
+
+[tool.uv.sources]
+fastapi-vue = { path = "fastapi-vue", editable = true }

template/backend/__main__.py

@@ -1,9 +1,11 @@
 # auto-upgrade@fastapi-vue-setup - remove this if you modify this file
 import argparse
+import os
 
 from fastapi_vue import server
 
 DEFAULT_PORT = TEMPLATE_DEFAULT_PORT
+DEVMODE = bool(os.getenv("ENVPREFIX_DEV") == "1")
 
 
 def main():
@@ -15,10 +17,12 @@ def main():
         help=(f"Endpoint (default: localhost:{DEFAULT_PORT})."),
     )
     args = parser.parse_args()
+    dev = {"reload": True, "reload_dirs": ["MODULE_NAME"]}
     server.run(
         "MODULE_NAME.APP_MODULE:APP_VAR",
         listen=args.listen,
         default_port=DEFAULT_PORT,
+        **(dev if DEVMODE else {}),
     )
 
 

template/backend/app.py

@@ -3,9 +3,10 @@ from pathlib import Path
 
 from fastapi import FastAPI
 from fastapi_vue import Frontend
+from MODULE_NAME.__main__ import DEVMODE
 
 # Vue Frontend static files
-frontend = Frontend(Path(__file__).with_name("frontend-build"), cached=["/assets/"])
+frontend = Frontend(Path(__file__).with_name("frontend-build"))
 
 
 @asynccontextmanager
@@ -15,7 +16,7 @@ async def lifespan(app: FastAPI):
     yield
 
 
-app = FastAPI(title="PROJECT_TITLE", lifespan=lifespan)
+app = FastAPI(title="PROJECT_TITLE", debug=DEVMODE, lifespan=lifespan)
 
 
 # Add API routes here...

template/frontend/vite-plugin-fastapi.js

@@ -1,17 +1,18 @@
 /**
  * FastAPI-Vue Vite Plugin
+ * auto-upgrade@fastapi-vue-setup -- remove this if you edit the plugin
  *
  * Configures Vite for FastAPI backend integration:
  * - Proxies /api/* requests to the FastAPI backend
  * - Builds to the Python module's frontend-build directory
  *
- * Environment variables (with defaults):
- *   FASTAPI_VUE_BACKEND_URL=http://localhost:5180 - Backend API URL for proxying
+ * Options:
+ *   paths - Array of paths to proxy (default: ["/api"])
  */
 
-const backendUrl = process.env.FASTAPI_VUE_BACKEND_URL || "http://localhost:5180"
-
 export default function fastapiVue({ paths = ["/api"] } = {}) {
+  const backendUrl = process.env.ENVPREFIX_BACKEND_URL || "http://localhost:TEMPLATE_DEFAULT_PORT"
+
   // Build proxy configuration for each path
   const proxy = {}
   for (const path of paths) {
@@ -23,7 +24,7 @@ export default function fastapiVue({ paths = ["/api"] } = {}) {
   }
 
   return {
-    name: "fastapi-vite",
+    name: "vite-plugin-fastapi-MODULE_NAME",
     config: () => ({
       server: { proxy },
       build: {

template/scripts/devserver.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S uv run
 # auto-upgrade@fastapi-vue-setup - remove this if you modify this file
-"""Run Vite development server for frontend and FastAPI backend with auto-reload."""
+"""Run Vite development server for Vue app and FastAPI backend with auto-reload."""
 
 import argparse
 import asyncio
@@ -16,7 +16,7 @@ from devutil import (  # type: ignore
     check_ports_free,
     logger,
     ready,
-    setup_fastapi,
+    setup_cli,
     setup_vite,
 )
 
@@ -24,26 +24,27 @@ DEFAULT_VITE_PORT = TEMPLATE_VITE_PORT
 DEFAULT_DEV_PORT = TEMPLATE_DEV_PORT
 
 
-async def run_devserver(frontend: str, backend: str) -> None:
+async def run_devserver(
+    listen: str, backend: str, extra_args: list[str] | None = None
+) -> None:
     reporoot = Path(__file__).parent.parent
     front = reporoot / "frontend"
     if not (front / "package.json").exists():
         logger.warning("Frontend source not found at %s", front)
         raise SystemExit(1)
 
-    viteurl, npm_install, vite = setup_vite(frontend, DEFAULT_VITE_PORT)
-    backurl, uvicorn = setup_fastapi(
-        backend, "MODULE_NAME.APP_MODULE:APP_VAR", DEFAULT_DEV_PORT
-    )
+    viteurl, npm_install, vite = setup_vite(listen, DEFAULT_VITE_PORT)
+    backurl, MODULE_NAME = setup_cli("PROJECT_CLI", backend, DEFAULT_DEV_PORT)
 
-    # Tell the everyone where the frontend and backend are (vite proxy, etc)
-    os.environ["FASTAPI_VUE_FRONTEND_URL"] = viteurl
-    os.environ["FASTAPI_VUE_BACKEND_URL"] = backurl
+    # Tell the everyone by environment (vite proxy and backend devmode use these)
+    os.environ["ENVPREFIX_VITE_URL"] = viteurl
+    os.environ["ENVPREFIX_BACKEND_URL"] = backurl
+    os.environ["ENVPREFIX_DEV"] = "1"
 
     async with ProcessGroup() as pg:
         npm_i = await pg.spawn(*npm_install, cwd=front)
         await check_ports_free(viteurl, backurl)
-        await pg.spawn(*uvicorn)
+        await pg.spawn(*MODULE_NAME, *(extra_args or []))
         await pg.wait(npm_i, ready(backurl, path="/api/health?from=devserver.py"))
         await pg.spawn(*vite, cwd=front)
 
@@ -55,25 +56,22 @@ def main():
         epilog=HELP_EPILOG,
     )
     parser.add_argument(
-        "frontend",
-        nargs="?",
+        "-l", "--listen",
         metavar="host:port",
-        help=f"Vite frontend endpoint (default: localhost:{DEFAULT_VITE_PORT})",
+        help=f"Vite (default: localhost:{DEFAULT_VITE_PORT})",
     )
     parser.add_argument(
         "--backend",
         metavar="host:port",
-        help=f"FastAPI backend endpoint (default: localhost:{DEFAULT_DEV_PORT})",
+        help=f"FastAPI (default: localhost:{DEFAULT_DEV_PORT})",
     )
-    args = parser.parse_args()
+    args, extra_args = parser.parse_known_args()
     with suppress(KeyboardInterrupt):
-        asyncio.run(run_devserver(args.frontend, args.backend))
+        asyncio.run(run_devserver(args.listen, args.backend, extra_args))
 
 
 HELP_EPILOG = """
-  scripts/devserver.py                       # Default ports on localhost
-  scripts/devserver.py 3000                  # Vite on localhost:3000
-  scripts/devserver.py :3000 --backend 8000  # *:3000, localhost:8000
+  scripts/devserver.py [args to PROJECT_CLI]
 
   JS_RUNTIME environment variable can be used to select the JS runtime:
   npm, deno, bun, or full path to the runtime executable (node maps to npm).

template/scripts/fastapi-vue/devutil.py

@@ -188,3 +188,24 @@ def setup_fastapi(
         "--forwarded-allow-ips=*",
     ]
     return f"http://{host}:{port}", cmd
+
+
+def setup_cli(
+    cli: str, endpoint: str, default_port: int = 8000
+) -> tuple[str, list[str]]:
+    """Parse backend endpoint and build CLI command.
+
+    Returns (url, cli_cmd).
+    Raises SystemExit(1) on invalid config.
+    """
+    endpoints = parse_endpoint(endpoint, default_port)
+
+    if "uds" in endpoints[0]:
+        logger.warning("Unix sockets not supported with vite devserver")
+        raise SystemExit(1)
+
+    host = endpoints[0]["host"]
+    port = endpoints[0]["port"]
+
+    cmd = [cli, f"--listen={host}:{port}"]
+    return f"http://{host}:{port}", cmd