tina4-python 3.11.35__tar.gz → 3.12.0__tar.gz

{tina4_python-3.11.35 → tina4_python-3.12.0}/.gitignore

@@ -74,3 +74,7 @@ example/store/__pycache__/
 example/store/src/**/__pycache__/
 .claude/settings.local.json
 .claude/worktrees/
+/nonexistent_path/
+/data/store.db
+/example/store/
+/example/uv.lock

{tina4_python-3.11.35 → tina4_python-3.12.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.11.35
-Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
+Version: 3.12.0
+Summary: Tina4 for Python — 54 built-in features, zero dependencies
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT
 Requires-Python: >=3.12

{tina4_python-3.11.35 → tina4_python-3.12.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tina4-python"
-version = "3.11.35"
-description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
+dynamic = ["version"]
+description = "Tina4 for Python — 54 built-in features, zero dependencies"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}
 ]
@@ -55,6 +55,9 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "tina4_python/__init__.py"
+
 [tool.hatch.build]
 include = ["tina4_python/**/*"]
 

{tina4_python-3.11.35 → tina4_python-3.12.0}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.11.35"
+__version__ = "3.12.0"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.11.35 → tina4_python-3.12.0}/tina4_python/auth/__init__.py

@@ -60,7 +60,7 @@ class Auth:
             algorithm:  JWT algorithm (default HS256).
             expires_in: Token lifetime in seconds (default 3600).
         """
-        self.secret = secret or os.environ.get("SECRET", "tina4-default-secret")
+        self.secret = secret or os.environ.get("TINA4_SECRET", "tina4-default-secret")
         self.algorithm = algorithm
         self.expires_in = expires_in or int(
             os.environ.get("TINA4_TOKEN_LIMIT", "60")
@@ -161,28 +161,28 @@ class Auth:
     @classmethod
     def get_token_static(cls, payload: dict, expires_in: int = 60) -> str:
         """Create a JWT without instantiating Auth — reads SECRET from env."""
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = cls(secret=secret, expires_in=expires_in)
         return auth.get_token(payload)
 
     @classmethod
     def valid_token_static(cls, token: str) -> bool:
         """Validate a JWT without instantiating Auth — reads SECRET from env."""
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = cls(secret=secret)
         return auth.valid_token(token)
 
     @classmethod
     def get_payload_static(cls, token: str) -> dict | None:
         """Decode payload (no validation) without instantiating Auth."""
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = cls(secret=secret)
         return auth.get_payload(token)
 
     @classmethod
     def refresh_token_static(cls, token: str, expires_in: int = 60) -> str | None:
         """Refresh a JWT without instantiating Auth — reads SECRET from env."""
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = cls(secret=secret, expires_in=expires_in)
         return auth.refresh_token(token)
 
@@ -193,7 +193,7 @@ class Auth:
         Reads SECRET from env. Checks: Bearer JWT, Bearer API key, Basic auth.
         Returns payload dict on success, None on failure.
         """
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = cls(secret=secret)
         return auth.authenticate_request(headers)
 
@@ -246,7 +246,7 @@ class Auth:
         Returns: True if the provided key matches.
         """
         if expected is None:
-            expected = os.environ.get("TINA4_API_KEY", os.environ.get("API_KEY", ""))
+            expected = os.environ.get("TINA4_API_KEY", "")
         if not expected:
             return False
         return hmac.compare_digest(provided, expected)

{tina4_python-3.11.35 → tina4_python-3.12.0}/tina4_python/cli/__init__.py

@@ -137,6 +137,7 @@ def main():
         "migrate:create": _migrate_create,
         "migrate:rollback": _migrate_rollback,
         "migrate:status": _migrate_status,
+        "env-migrate": _env_migrate,
         "seed": _seed,
         "routes": _routes,
         "test": _test,
@@ -155,6 +156,52 @@ def main():
         _help([])
 
 
+def _env_migrate(args):
+    """Rewrite a .env file in place, renaming pre-3.12 names to TINA4_ form.
+
+    Usage: tina4python env-migrate [path]   (default path: .env)
+
+    Backs the original up to <path>.bak before rewriting. Prints a diff of
+    each rename. Idempotent — running twice is a no-op on the second run.
+    """
+    from tina4_python.core.server import _LEGACY_ENV_VARS
+    target = Path(args[0]) if args else Path(".env")
+    if not target.is_file():
+        print(f"  no .env at {target}")
+        return
+    text = target.read_text(encoding="utf-8")
+    backup = target.with_suffix(target.suffix + ".bak")
+    backup.write_text(text, encoding="utf-8")
+    print(f"  backup written: {backup}")
+
+    renamed = 0
+    new_lines = []
+    for line in text.splitlines(keepends=True):
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith("#"):
+            new_lines.append(line); continue
+        if "=" not in stripped:
+            new_lines.append(line); continue
+        key = stripped.split("=", 1)[0].strip()
+        if key in _LEGACY_ENV_VARS:
+            new_key = _LEGACY_ENV_VARS[key]
+            new_line = line.replace(key, new_key, 1)
+            print(f"  {key:<28}  →  {new_key}")
+            new_lines.append(new_line)
+            renamed += 1
+        else:
+            new_lines.append(line)
+
+    if renamed == 0:
+        print("  nothing to rename — your .env is already on the new convention")
+        backup.unlink()  # don't leave a noise backup
+        return
+
+    target.write_text("".join(new_lines), encoding="utf-8")
+    print(f"\n  done: {renamed} rename(s) applied to {target}")
+    print(f"  original kept at {backup} (delete once you've verified)")
+
+
 def _help(args=None):
     print("""
 Tina4 Python — CLI
@@ -168,6 +215,7 @@ Commands:
   migrate:create <desc>         Create a new migration file
   migrate:rollback              Rollback last migration batch
   migrate:status                Show migration status
+  env-migrate [path]            Rewrite .env to TINA4_-prefixed names (v3.12 migration)
   seed                          Run database seeders
   routes                        List all registered routes
   test                          Run test suite
@@ -212,7 +260,7 @@ def _console(args=None):
 
     # Try to connect database from DATABASE_URL
     db = None
-    db_url = os.environ.get("DATABASE_URL")
+    db_url = os.environ.get("TINA4_DATABASE_URL")
     if db_url:
         try:
             db = Database(db_url)
@@ -404,7 +452,7 @@ def _migrate(args):
     from tina4_python.database import Database
     from tina4_python.migration import Migration
 
-    db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
+    db_url = os.environ.get("TINA4_DATABASE_URL", "sqlite:///data/app.db")
     db = Database(db_url)
     mig_dir = args[0] if args else "migrations"
     ran = Migration(db, mig_dir).migrate()
@@ -434,7 +482,7 @@ def _migrate_rollback(args):
     from tina4_python.database import Database
     from tina4_python.migration import Migration
 
-    db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
+    db_url = os.environ.get("TINA4_DATABASE_URL", "sqlite:///data/app.db")
     db = Database(db_url)
     mig_dir = args[0] if args else "migrations"
     rolled = Migration(db, mig_dir).rollback()
@@ -453,7 +501,7 @@ def _migrate_status(args):
     from tina4_python.database import Database
     from tina4_python.migration import Migration
 
-    db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
+    db_url = os.environ.get("TINA4_DATABASE_URL", "sqlite:///data/app.db")
     db = Database(db_url)
     result = Migration(db, args[0] if args else "migrations").status()
     completed, pending = result["completed"], result["pending"]
@@ -489,7 +537,7 @@ def _seed(args):
     import importlib.util
     from tina4_python.database import Database
 
-    db_url = os.environ.get("DATABASE_URL", "sqlite:///data/app.db")
+    db_url = os.environ.get("TINA4_DATABASE_URL", "sqlite:///data/app.db")
     db = Database(db_url)
     sys.path.insert(0, str(Path.cwd()))
 

{tina4_python-3.11.35 → tina4_python-3.12.0}/tina4_python/core/middleware.py

@@ -287,7 +287,7 @@ class CsrfMiddleware:
             bearer_token = auth_header[7:].strip()
             if bearer_token:
                 from tina4_python.auth import Auth as _CsrfAuth
-                secret = os.environ.get("SECRET", "tina4-default-secret")
+                secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
                 auth = _CsrfAuth(secret=secret)
                 if auth.valid_token(bearer_token):
                     return request, response
@@ -326,7 +326,7 @@ class CsrfMiddleware:
 
         # Validate the token
         from tina4_python.auth import Auth as _CsrfAuth
-        secret = os.environ.get("SECRET", "tina4-default-secret")
+        secret = os.environ.get("TINA4_SECRET", "tina4-default-secret")
         auth = _CsrfAuth(secret=secret)
         if not auth.valid_token(token):
             return request, response.error(

{tina4_python-3.11.35 → tina4_python-3.12.0}/tina4_python/core/server.py

@@ -193,20 +193,93 @@ def _render_error_page(status_code: int, path: str, request_id: str, error_messa
 _template_cache: dict[str, str] | None = None
 
 
+# Auto-routing scans this single subdirectory of src/templates/. Only files
+# in src/templates/pages/ become URLs — everything else (partials, layouts,
+# base.twig, errors, components, macros) is never URL-exposed and remains
+# renderable only via {% include %} / {% extends %} / response.render().
+#
+# Convention adapted from Next.js' pages/ directory and Nuxt's pages/ folder.
+# Explicit, secure by default, no skip lists to maintain.
+_TEMPLATE_PAGES_DIR = "pages"
+
+
+def _is_dev_mode() -> bool:
+    """True when ``TINA4_DEBUG`` is one of the truthy values (true|1|yes).
+
+    Centralised so every dev-mode gate (landing page, dev toolbar, error
+    overlay, dev admin) reads the same flag the same way.
+    """
+    return os.environ.get("TINA4_DEBUG", "false").strip().lower() in ("true", "1", "yes")
+
+
+# RFC 7231 / RFC 9110 status reason phrases. We use this to write a correct
+# HTTP status line in the dev server's HTTP/1.1 → ASGI bridge — previously
+# the bridge wrote "HTTP/1.1 404 OK" regardless of code, which is malformed.
+_HTTP_REASON_PHRASES: dict[int, str] = {
+    100: "Continue", 101: "Switching Protocols",
+    200: "OK", 201: "Created", 202: "Accepted", 204: "No Content",
+    206: "Partial Content",
+    301: "Moved Permanently", 302: "Found", 303: "See Other",
+    304: "Not Modified", 307: "Temporary Redirect", 308: "Permanent Redirect",
+    400: "Bad Request", 401: "Unauthorized", 403: "Forbidden",
+    404: "Not Found", 405: "Method Not Allowed", 406: "Not Acceptable",
+    409: "Conflict", 410: "Gone", 413: "Content Too Large",
+    415: "Unsupported Media Type", 422: "Unprocessable Content",
+    429: "Too Many Requests",
+    500: "Internal Server Error", 501: "Not Implemented",
+    502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
+}
+
+
+def _http_reason(status: int) -> str:
+    """Return the canonical HTTP reason phrase for ``status``.
+
+    Falls back to a sensible label when an exotic status is used. Never
+    returns an empty string — the HTTP/1.1 status line requires a phrase.
+    """
+    return _HTTP_REASON_PHRASES.get(int(status), "OK" if 200 <= status < 300 else "Error")
+
+
+def _template_auto_routing_enabled() -> bool:
+    """Honour TINA4_TEMPLATE_ROUTING=off|false|0|no as an explicit kill switch.
+
+    Default: enabled. Drop a file in src/templates/pages/ and it serves at
+    the matching URL — the zero-config Tina4 convention. Operators who want
+    explicit-only routing can set TINA4_TEMPLATE_ROUTING=off and every URL
+    must be registered via @get / @post (or be a static file).
+    """
+    val = os.environ.get("TINA4_TEMPLATE_ROUTING", "on").strip().lower()
+    return val not in ("off", "false", "0", "no", "disabled")
+
+
 def _resolve_template(path: str) -> str | None:
-    """Resolve a URL path to a template file in src/templates/.
+    """Resolve a URL path to a template file in src/templates/pages/.
+
+    Only files inside ``src/templates/pages/`` auto-route from a URL.
+    Anything in ``src/templates/`` outside ``pages/`` (partials, layouts,
+    base.twig, errors, components) is never served standalone.
+
     Dev mode: checks filesystem every time for live changes.
     Production: uses a cached lookup built once at startup.
+
+    The whole feature can be turned off with ``TINA4_TEMPLATE_ROUTING=off``.
     """
+    if not _template_auto_routing_enabled():
+        return None
+
     clean_path = path.strip("/") or "index"
     is_dev = os.environ.get("TINA4_DEBUG", "false").lower() in ("true", "1", "yes")
 
     if is_dev:
-        template_dir = Path("src/templates")
+        # Skip underscore-prefixed files even within pages/ — they're private
+        # by Hugo/Jekyll convention (helpers, fragments) and shouldn't auto-serve.
+        if any(seg.startswith("_") for seg in clean_path.split("/")):
+            return None
+        pages_dir = Path("src/templates") / _TEMPLATE_PAGES_DIR
         for ext in (".twig", ".html"):
-            candidate = clean_path + ext
-            if (template_dir / candidate).is_file():
-                return candidate
+            candidate_rel = f"{_TEMPLATE_PAGES_DIR}/{clean_path}{ext}"
+            if (pages_dir / (clean_path + ext)).is_file():
+                return candidate_rel
         return None
 
     global _template_cache
@@ -216,17 +289,25 @@ def _resolve_template(path: str) -> str | None:
 
 
 def _build_template_cache() -> None:
-    """Scan src/templates/ once and build url_path -> template_file lookup."""
+    """Scan src/templates/pages/ once and build url_path -> template_file lookup.
+    Only files under ``pages/`` are eligible — partials, layouts, base.twig,
+    errors etc remain renderable via explicit response.render() but never
+    auto-serve from a URL.
+    """
     global _template_cache
     _template_cache = {}
-    template_dir = Path("src/templates")
-    if not template_dir.is_dir():
+    pages_dir = Path("src/templates") / _TEMPLATE_PAGES_DIR
+    if not pages_dir.is_dir():
         return
-    for f in template_dir.rglob("*"):
+    for f in pages_dir.rglob("*"):
         if not f.is_file() or f.suffix not in (".twig", ".html"):
             continue
-        rel = str(f.relative_to(template_dir)).replace("\\", "/")
-        url_path = rel.rsplit(".", 1)[0]
+        # Skip private files even within pages/ (e.g. pages/_helper.twig)
+        rel_inside_pages = f.relative_to(pages_dir)
+        if any(p.startswith("_") for p in rel_inside_pages.parts):
+            continue
+        rel = str(f.relative_to(Path("src/templates"))).replace("\\", "/")
+        url_path = str(rel_inside_pages).replace("\\", "/").rsplit(".", 1)[0]
         if url_path not in _template_cache:
             _template_cache[url_path] = rel
 
@@ -837,7 +918,10 @@ async def _handle_dev_admin(request: Request, response: Response) -> Response:
     """Serve the /__dev dashboard and API routes."""
     from tina4_python.dev_admin import get_api_handlers
     if request.path in ("/__dev/", "/__dev", "/__dev/v2", "/__dev/v2/"):
-        # Unified SPA dev admin
+        # Unified SPA dev admin. The bundle derives its WS URL from
+        # `location.host` directly, so no environment shim is needed —
+        # the framework serves /__dev_reload on its own port and the
+        # SPA reaches it as `ws://<page-host>/__dev_reload`.
         response.html("""<!DOCTYPE html>
 <html lang="en"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1.0"><title>Tina4 Dev Admin</title></head>
 <body><div id="app" data-framework="python" data-color="#3b82f6"></div>
@@ -847,8 +931,19 @@ async def _handle_dev_admin(request: Request, response: Response) -> Response:
         handler_info = handlers.get(request.path)
         if handler_info and request.method == handler_info[0]:
             try:
-                def _resp(data, code=200):
-                    if isinstance(data, str):
+                def _resp(data, code=200, content_type=None):
+                    # content_type overrides the auto-detected MIME —
+                    # lets handlers stream binary with an explicit
+                    # Content-Type (e.g. /__dev/api/file/raw).
+                    if content_type is not None:
+                        response.status(code)
+                        response.content_type = content_type
+                        response.content = data if isinstance(data, (bytes, bytearray)) else str(data).encode("utf-8")
+                    elif isinstance(data, (bytes, bytearray)):
+                        response.status(code)
+                        response.content_type = "application/octet-stream"
+                        response.content = data
+                    elif isinstance(data, str):
                         response.status(code).html(data)
                     else:
                         response.status(code).json(data)
@@ -906,7 +1001,7 @@ def _check_auth(request: Request, response: Response, route: dict) -> bool:
     if not route.get("auth_required"):
         return False
     _auth_header = request.headers.get("authorization", "")
-    _api_key = os.environ.get("TINA4_API_KEY", os.environ.get("API_KEY", ""))
+    _api_key = os.environ.get("TINA4_API_KEY", "")
     _auth_ok = False
     if _auth_header and _auth_header.startswith("Bearer "):
         _token = _auth_header[7:]
@@ -1062,7 +1157,19 @@ def _handle_route_error(
 
 
 def _handle_no_route(request: Request, response: Response, request_id: str) -> Response:
-    """Serve static files, templates, landing page, or 404."""
+    """Serve static files, templates, landing page, or 404.
+
+    Lookup order at any URL with no registered route:
+      1. Static file (public/, src/public/, framework public/, with /
+         resolving to index.html so SPAs Just Work)
+      2. Auto-routed template from src/templates/pages/ (gated by
+         TINA4_TEMPLATE_ROUTING)
+      3. Framework landing page — only at "/", and only in dev
+         (``TINA4_DEBUG=true``). Production never shows it, so the
+         framework version, dev-admin link, and gallery never leak
+         to real users.
+      4. 404
+    """
     static = _try_static(request.path)
     if static:
         return static
@@ -1071,7 +1178,7 @@ def _handle_no_route(request: Request, response: Response, request_id: str) -> R
         from tina4_python.core.response import get_frond
         html = get_frond().render(tpl_file, {})
         response.html(html)
-    elif request.path == "/":
+    elif request.path == "/" and _is_dev_mode():
         response.html(_render_landing_page())
     else:
         html = _render_error_page(404, request.path, request_id)
@@ -1182,8 +1289,14 @@ async def handle(request: Request) -> Response:
     from tina4_python.dotenv import is_truthy
     _is_dev = is_truthy(os.environ.get("TINA4_DEBUG", ""))
 
-    # Dev admin
-    if _is_dev and request.path.startswith("/__dev"):
+    # Dev admin — also catches /ai/api/chat (SPA's ollama proxy) and the
+    # bare /ai /vision /embed /image /rag service-health probes that
+    # drive the "SERVICES ●●●●●" dots in the dev-admin UI.
+    _dev_extra_paths = {"/ai/api/chat", "/ai", "/vision", "/embed", "/image", "/rag"}
+    if _is_dev and (
+        request.path.startswith("/__dev")
+        or request.path in _dev_extra_paths
+    ):
         return await _handle_dev_admin(request, response)
 
     # Swagger
@@ -1304,8 +1417,16 @@ def _try_static(path: str) -> Response | None:
     2. public/           (simple, IDE-friendly)
     3. src/public/       (nested convention)
     4. tina4_python/public/  (framework built-in assets)
+
+    Index resolution: when ``path`` is ``/`` or ends with ``/``, the lookup
+    appends ``index.html`` so a Vite/SPA build with ``src/public/index.html``
+    serves at the matching URL — no custom ``@get("/")`` route needed.
     """
     clean = path.lstrip("/")
+    # Index resolution: '/' or '/foo/' -> append 'index.html' so SPA builds
+    # in src/public/ Just Work without a custom root route.
+    if clean == "" or clean.endswith("/"):
+        clean = clean + "index.html"
     custom = os.environ.get("TINA4_PUBLIC_DIR")
     candidates = []
     if custom:
@@ -1555,6 +1676,69 @@ def _print_banner(host: str, port: int, server_name: str = "asyncio", ai_port: i
     print(banner)
 
 
+# Legacy env var names that v3.12 has retired. If any of these are set in
+# the environment we refuse to boot — silently ignoring them would cause
+# auth/db/mail to fall back to defaults with no warning. Each maps to its
+# new TINA4_-prefixed canonical name (or DROPPED for deleted features).
+_LEGACY_ENV_VARS: dict[str, str] = {
+    "DATABASE_URL":           "TINA4_DATABASE_URL",
+    "DATABASE_USERNAME":      "TINA4_DATABASE_USERNAME",
+    "DATABASE_PASSWORD":      "TINA4_DATABASE_PASSWORD",
+    "DB_URL":                 "TINA4_DATABASE_URL",
+    "SECRET":                 "TINA4_SECRET",
+    "API_KEY":                "TINA4_API_KEY",
+    "JWT_ALGORITHM":          "TINA4_JWT_ALGORITHM",
+    "SMTP_HOST":              "TINA4_MAIL_HOST",
+    "SMTP_PORT":              "TINA4_MAIL_PORT",
+    "SMTP_USERNAME":          "TINA4_MAIL_USERNAME",
+    "SMTP_PASSWORD":          "TINA4_MAIL_PASSWORD",
+    "SMTP_FROM":              "TINA4_MAIL_FROM",
+    "SMTP_FROM_NAME":         "TINA4_MAIL_FROM_NAME",
+    "IMAP_HOST":              "TINA4_MAIL_IMAP_HOST",
+    "IMAP_PORT":              "TINA4_MAIL_IMAP_PORT",
+    "IMAP_USER":              "TINA4_MAIL_IMAP_USERNAME",
+    "IMAP_PASS":              "TINA4_MAIL_IMAP_PASSWORD",
+    "HOST_NAME":              "TINA4_HOST_NAME",
+    "SWAGGER_TITLE":          "TINA4_SWAGGER_TITLE",
+    "SWAGGER_DESCRIPTION":    "TINA4_SWAGGER_DESCRIPTION",
+    "SWAGGER_VERSION":        "TINA4_SWAGGER_VERSION",
+    "ORM_PLURAL_TABLE_NAMES": "TINA4_ORM_PLURAL_TABLE_NAMES",
+}
+
+
+def _check_legacy_env_vars() -> None:
+    """Refuse to boot if pre-3.12 un-prefixed env vars are still set.
+
+    Tina4 v3.12 hard-renamed every framework-specific env var to use the
+    ``TINA4_`` prefix. Booting silently with a legacy ``DATABASE_URL`` or
+    ``SECRET`` would let auth, DB, or mail fall back to insecure defaults
+    while the user thought their config was being read. Better to die
+    loudly with a list of names to fix.
+
+    Bypass with ``TINA4_ALLOW_LEGACY_ENV=true`` in CI / migration scripts
+    that genuinely need both names set during a transition window.
+    """
+    if os.environ.get("TINA4_ALLOW_LEGACY_ENV", "").lower() in ("true", "1", "yes"):
+        return
+    found = sorted(name for name in _LEGACY_ENV_VARS if name in os.environ)
+    if not found:
+        return
+    msg = ["", "─" * 72,
+           "Tina4 v3.12 requires TINA4_ prefix on all framework env vars.",
+           "Your environment still has these legacy names:",
+           ""]
+    for old in found:
+        new = _LEGACY_ENV_VARS[old]
+        msg.append(f"    {old:<28}  →  {new}")
+    msg.extend(["",
+                "Run `tina4 env-migrate` to rewrite your .env automatically,",
+                "or rename manually. See https://tina4.com/release/3.12.0",
+                "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
+                "─" * 72, ""])
+    print("\n".join(msg), file=sys.stderr)
+    sys.exit(2)
+
+
 def run(host: str | None = None, port: int | None = None, no_browser: bool = False, no_reload: bool = False):
     """Start the Tina4 dev server.
 
@@ -1570,6 +1754,9 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
     global _start_time
     _start_time = time.time()
 
+    # Refuse to boot with v3.11 / v2 era un-prefixed env vars set.
+    _check_legacy_env_vars()
+
     # ── Require tina4 CLI ─────────────────────────────────────────
     # The framework must be launched via `tina4 serve`, not `python app.py`.
     # The tina4 CLI passes --managed when spawning the server process.
@@ -1615,6 +1802,38 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
     log_level = os.environ.get("TINA4_LOG_LEVEL", "error" if not is_production else "error")
     Log.configure(level=log_level, production=is_production)
 
+    # Install a top-level exception hook so uncaught exceptions bubbling
+    # out of anything (a route handler, a background task, the event
+    # loop itself on startup) land in logs/error.log. Without this,
+    # an uncaught exception surfaces only via Python's default stderr
+    # writer and never touches Log — the same gap PHP had before its
+    # set_exception_handler fix. Chains to the previous hook so any
+    # debugger / IDE hook already in place still fires.
+    import sys as _sys
+    import traceback as _traceback
+    _prior_excepthook = _sys.excepthook
+
+    def _tina4_excepthook(exc_type, exc_value, exc_tb):
+        # KeyboardInterrupt is a user-initiated Ctrl+C, not an error —
+        # defer to the prior hook (which prints a clean traceback).
+        if issubclass(exc_type, KeyboardInterrupt):
+            _prior_excepthook(exc_type, exc_value, exc_tb)
+            return
+        try:
+            trace_text = "".join(_traceback.format_exception(exc_type, exc_value, exc_tb))
+            Log.error(
+                f"Uncaught {exc_type.__name__}: {exc_value}",
+                trace=trace_text,
+            )
+        except Exception:
+            # If logging itself fails (disk full, permissions, logger
+            # not initialised yet), fall through to the prior hook so
+            # the user still sees something in stderr.
+            pass
+        _prior_excepthook(exc_type, exc_value, exc_tb)
+
+    _sys.excepthook = _tina4_excepthook
+
     # Ensure folders
     _ensure_folders()
 
@@ -1777,7 +1996,7 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
                         # Streaming mode — flush headers on first chunk, then write each chunk immediately
                         if not _headers_sent:
                             _headers_sent = True
-                            writer.write(f"HTTP/1.1 {resp_status} OK\r\n".encode())
+                            writer.write(f"HTTP/1.1 {resp_status} {_http_reason(resp_status)}\r\n".encode())
                             for name, value in resp_headers:
                                 writer.write(name + b": " + value + b"\r\n")
                             writer.write(b"\r\n")
@@ -1797,7 +2016,7 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
 
             # Write HTTP/1.1 response (only if headers weren't already sent by streaming)
             if not _headers_sent:
-                status_line = f"HTTP/1.1 {resp_status} OK\r\n"
+                status_line = f"HTTP/1.1 {resp_status} {_http_reason(resp_status)}\r\n"
                 writer.write(status_line.encode())
                 for name, value in resp_headers:
                     writer.write(name + b": " + value + b"\r\n")