dataface 0.1.2__py3-none-any.whl

dataface/core/serve/server.py

@@ -0,0 +1,938 @@
+"""Unified Dataface server.
+
+Stage: SERVE
+Purpose: Single HTTP server for all Dataface rendering.
+
+Routes:
+- /health - Health check
+- /templates - List available inspect templates
+- /{path}/?var=value - Any face file (path.yml → /path/)
+
+For /inspect/* paths, the server checks faces/inspect/{template}.yml first,
+then falls back to built-in templates with Jinja2 pre-processing.
+
+Example URLs:
+- /health
+- /inspect/model/?model=fct_orders&theme=dark
+- /inspect/numeric_column/?model=fct_orders&column=revenue
+- /sales/?region=West  (renders faces/sales.yml when faces_at_root=True)
+"""
+
+import importlib.util
+import logging
+import textwrap
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from html import escape as html_escape
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+_SUPER_SCHEMA_AVAILABLE: bool = (
+    importlib.util.find_spec("dataface_super_schema") is not None
+)
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+from jinja2 import Environment, select_autoescape
+
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.dashboard import RenderedDashboard, render_dashboard
+from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.execute.adapters.adapter_registry import (
+    LOCAL_AUTHORING_REGISTRY_KWARGS,
+)
+from dataface.core.execute.duckdb_cache import DuckDBCache, open_cache_from_env
+from dataface.core.fonts import get_inter_font_path
+from dataface.core.inspect import INSPECT_TEMPLATES
+from dataface.core.inspect.renderer import (
+    InspectProfileCompileError,
+    render_inspect_dashboard,
+    validate_inspect_variables,
+)
+from dataface.core.project_roots import (
+    discover_render_context,
+    discovery_boundary_for_face,
+)
+from dataface.core.render.errors import MissingVariable
+
+logger = logging.getLogger(__name__)
+
+# Module-level cache singleton — opened once at first request, closed on shutdown.
+_cache: DuckDBCache | None = None
+_cache_initialised = False
+
+
+def _get_default_cache() -> DuckDBCache | None:
+    """Return the module-level cache, opening it on first call."""
+    global _cache, _cache_initialised
+    if not _cache_initialised:
+        _cache = open_cache_from_env()
+        _cache_initialised = True
+    return _cache
+
+
+def _ensure_within_project(candidate: Path, project_dir: Path) -> Path:
+    """Reject paths that escape the project root."""
+    try:
+        candidate.resolve().relative_to(project_dir.resolve())
+    except ValueError as e:
+        raise HTTPException(
+            status_code=403, detail="Path outside project directory"
+        ) from e
+    return candidate
+
+
+def _build_link_context(
+    file_path: Path,
+    project_dir: Path,
+    faces_at_root: bool,
+    serve_storage_prefix: str | None = None,
+) -> Any:
+    """Build board-link rewrite context for a served face."""
+    from dataface.core.render.board_links import LinkContext
+
+    rel = file_path.relative_to(project_dir)
+    rel_no_ext = rel.with_suffix("")
+    parts = rel_no_ext.parts
+    storage_prefix = parts[0] if len(parts) > 1 else "faces"
+    board_slug = "/".join(parts[1:]) if len(parts) > 1 else str(rel_no_ext)
+    if faces_at_root and parts and parts[0] == "faces":
+        storage_prefix = ""
+        board_slug = "/".join(parts[1:])
+    elif faces_at_root:
+        storage_prefix = ""
+    if serve_storage_prefix is not None:
+        storage_prefix = serve_storage_prefix.strip("/")
+    return LinkContext(
+        runtime="serve",
+        current_board_slug=board_slug,
+        storage_prefix=storage_prefix,
+    )
+
+
+def _apply_server_defaults(
+    variables: dict[str, Any],
+    connection: str | None,
+) -> dict[str, Any]:
+    """Apply connection default to request variables."""
+    resolved = dict(variables)
+    if "connection" not in resolved and connection:
+        resolved["connection"] = connection
+    return resolved
+
+
+def _resolve_root_index_face(project_dir: Path) -> Path | None:
+    """Return the project-level index face for the root URL, if present."""
+    for candidate in (
+        project_dir / "index.yml",
+        project_dir / "index.yaml",
+        project_dir / "index.md",
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _directory_candidates(
+    project_dir: Path,
+    faces_dir: Path,
+    clean_path: str,
+    faces_at_root: bool,
+) -> list[tuple[Path, str]]:
+    """Build candidate directories to render for the request path."""
+    candidates: list[tuple[Path, str]] = []
+    if clean_path:
+        candidates.append((project_dir / clean_path, clean_path))
+        if faces_at_root and not clean_path.startswith("faces/"):
+            candidates.append((faces_dir / clean_path, clean_path))
+        return candidates
+    if faces_at_root and faces_dir.is_dir():
+        candidates.append((faces_dir, ""))
+    candidates.append((project_dir, clean_path))
+    return candidates
+
+
+def _resolve_face_file_path(
+    project_dir: Path,
+    faces_dir: Path,
+    clean_path: str,
+    faces_at_root: bool,
+) -> Path:
+    """Resolve the request path to a face file path, preserving existing fallback order."""
+    file_candidates: list[Path] = [
+        project_dir / f"{clean_path}.yml",
+        project_dir / f"{clean_path}.yaml",
+        project_dir / f"{clean_path}.md",
+        project_dir / clean_path,
+    ]
+    if faces_at_root and not clean_path.startswith("faces/"):
+        file_candidates.extend(
+            [
+                faces_dir / f"{clean_path}.yml",
+                faces_dir / f"{clean_path}.yaml",
+                faces_dir / f"{clean_path}.md",
+                faces_dir / clean_path,
+            ]
+        )
+
+    file_path: Path | None = None
+    first_yml_candidate: Path | None = None
+    for candidate in file_candidates:
+        _ensure_within_project(candidate, project_dir)
+        if candidate.exists():
+            if candidate.suffix in (".yml", ".yaml", ".md"):
+                file_path = candidate
+                break
+        elif candidate.suffix == ".yml" and first_yml_candidate is None:
+            first_yml_candidate = candidate
+
+    if file_path is not None:
+        return file_path
+    return first_yml_candidate or (project_dir / f"{clean_path}.yml")
+
+
+_error_jinja_template: Any = None
+
+
+def _error_template() -> Any:
+    """Load the structured-error Jinja2 template (lazy, cached at module level)."""
+    global _error_jinja_template
+    if _error_jinja_template is None:
+        raw = (
+            files("dataface.core.serve.templates").joinpath("error.html.j2").read_text()
+        )
+        env = Environment(autoescape=select_autoescape(["html", "j2"]))
+        _error_jinja_template = env.from_string(raw)
+    return _error_jinja_template
+
+
+def _render_structured_errors_html(
+    result: RenderedDashboard,
+    request_path: str,
+    status_override: int | None = None,
+) -> HTMLResponse:
+    """Render a RenderedDashboard error result as a structured HTML page."""
+    if status_override is not None:
+        status = status_override
+    elif result.face_error is not None:
+        status = 500 if result.face_error.code.startswith("DF-UNKNOWN-") else 422
+    elif result.validation_errors:
+        status = 422
+    elif result.chart_errors:
+        status = 200
+    else:
+        status = 200
+
+    face_html = ""
+    if result.chart_errors and result.data:
+        data = result.data
+        face_html = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+
+    html = _error_template().render(
+        result=result,
+        request_path=request_path,
+        face_html=face_html,
+    )
+    return HTMLResponse(content=html, status_code=status)
+
+
+def _synthetic_error(message: str) -> RenderedDashboard:
+    """Build a RenderedDashboard with a synthetic DF-UNKNOWN-INTERNAL face_error."""
+    return RenderedDashboard(
+        success=False,
+        face_error=StructuredError(
+            code="DF-UNKNOWN-INTERNAL",
+            message=message,
+            domain="unknown",
+            doc_url=DF_UNKNOWN_INTERNAL.doc_url,
+        ),
+    )
+
+
+def _render_face_file(
+    file_path: Path,
+    variables: dict[str, Any],
+    project_dir: Path,
+    connection: str | None = None,
+    dialect: str = "duckdb",
+    faces_at_root: bool = False,
+    target: str | None = None,
+    serve_storage_prefix: str | None = None,
+    read_only: bool = True,
+    allow_external_access_in_readonly: bool = False,
+    duckdb_config: dict[str, Any] | None = None,
+) -> Response:
+    """Render a face file to HTML."""
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"Face file not found: {file_path}")
+
+    project_root, dbt_project_path = discover_render_context(
+        file_path.parent,
+        discovery_boundary_for_face(file_path.parent, project_dir),
+    )
+    working_dir = dbt_project_path or project_root
+
+    from dataface.core.compile.config import invalidate_project_sources
+    from dataface.core.execute.adapters import build_adapter_registry
+
+    invalidate_project_sources(working_dir)
+
+    adapter_registry = build_adapter_registry(
+        project_root,
+        read_only=read_only,
+        allow_external_access_in_readonly=allow_external_access_in_readonly,
+        duckdb_config=duckdb_config,
+        dbt_project_path=dbt_project_path,
+        connection_string=connection,
+        profile_type=dialect,
+        target=target,
+    )
+
+    link_context = _build_link_context(
+        file_path,
+        project_dir=project_dir,
+        faces_at_root=faces_at_root,
+        serve_storage_prefix=serve_storage_prefix,
+    )
+
+    result = render_dashboard(
+        path=file_path,
+        variables=variables,
+        adapter_registry=adapter_registry,
+        format="html",
+        link_context=link_context,
+        duckdb_cache=_get_default_cache(),
+    )
+
+    if result.success and not result.chart_errors:
+        data = result.data
+        html = data.decode("utf-8") if isinstance(data, bytes) else str(data)
+        return HTMLResponse(content=html)
+
+    # MissingRequiredVariablesError comes through render_dashboard as a face_error
+    # with fields["missing"] populated. Render the HTML prompt card (200) so the
+    # browser shows the blocking form — same UX surface the Cloud face viewer uses.
+    if result.face_error is not None and result.face_error.fields.get("missing"):
+        from dataface.core.render.missing_vars_prompt import (
+            render_missing_variables_prompt,
+        )
+
+        missing = [MissingVariable(**d) for d in result.face_error.fields["missing"]]
+        prompt_card = render_missing_variables_prompt(
+            missing,
+            # Empty action resubmits to the current URL (GET with query params)
+            form_action="",
+            form_method="get",
+        )
+        return HTMLResponse(
+            content=_render_prompt_page(
+                f"Configuration required — {file_path.name}",
+                prompt_card,
+            ),
+            status_code=200,
+        )
+
+    return _render_structured_errors_html(result, request_path=str(file_path.name))
+
+
+def _handle_inspect_route(
+    template_name: str,
+    variables: dict[str, Any],
+    project_dir: Path,
+    connection: str | None = None,
+    target: str | None = None,
+    read_only: bool = False,
+) -> Response:
+    """Handle /inspect/* routes with custom template fallback.
+
+    The inspect HTML server is DuckDB-only. Project templates under
+    ``faces/inspect/`` use the same Jinja-then-compile pipeline as the
+    built-in copies (``dft init`` ejects Jinja-heavy YAML).
+
+    Args:
+        template_name: Name of the inspect template (e.g., "model" or "model.yml")
+        variables: Variables from query params
+        project_dir: Project directory for custom template lookup
+
+    Returns:
+        Rendered HTML response
+    """
+    _ = (
+        target,
+        read_only,
+    )  # Inspect HTML uses render_inspect_dashboard; registry is fixed.
+
+    template_name = template_name.strip().strip("/")
+    if template_name.endswith((".yml", ".yaml")):
+        template_name = template_name[: template_name.rindex(".")]
+
+    custom_path = project_dir / "faces" / "inspect" / f"{template_name}.yml"
+    has_custom = custom_path.is_file()
+
+    if not has_custom and template_name not in INSPECT_TEMPLATES:
+        return _render_structured_errors_html(
+            _synthetic_error(
+                f"Inspect template '{template_name}' not found. "
+                f"Available: {INSPECT_TEMPLATES}"
+            ),
+            request_path=f"/inspect/{template_name}/",
+            status_override=404,
+        )
+
+    try:
+        variables = validate_inspect_variables(variables)
+    except ValueError as e:
+        return _render_structured_errors_html(
+            RenderedDashboard(
+                success=False,
+                validation_errors=[
+                    StructuredError(
+                        code="DF-UNKNOWN-INTERNAL",
+                        message=str(e),
+                        domain="unknown",
+                        doc_url=DF_UNKNOWN_INTERNAL.doc_url,
+                    )
+                ],
+            ),
+            request_path=f"/inspect/{template_name}/",
+        )
+
+    template_file = f"{template_name}.yml"
+    if has_custom:
+        try:
+            template_yaml = custom_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return _render_structured_errors_html(
+                _synthetic_error(f"Inspect template file not found: {template_file}"),
+                request_path=f"/inspect/{template_name}/",
+                status_override=404,
+            )
+    else:
+        template_path = files("dataface.core.inspect.templates").joinpath(template_file)
+        try:
+            template_yaml = template_path.read_text()
+        except FileNotFoundError:
+            return _render_structured_errors_html(
+                _synthetic_error(f"Template file '{template_file}' not found"),
+                request_path=f"/inspect/{template_name}/",
+                status_override=404,
+            )
+
+    try:
+        return HTMLResponse(
+            content=render_inspect_dashboard(
+                template_yaml,
+                variables,
+                project_root=project_dir,
+                connection=connection,
+            )
+        )
+    except InspectProfileCompileError as e:
+        # Stamp file context for custom profile templates so the validate button appears.
+        from dataface.core.dashboard import _stamp_file_commands
+
+        errs = (
+            _stamp_file_commands(e.result.errors, custom_path)
+            if has_custom
+            else list(e.result.errors)
+        )
+        return _render_structured_errors_html(
+            RenderedDashboard(
+                success=False,
+                validation_errors=errs,
+                warnings=list(e.result.warnings),
+                suppressed_warnings=list(e.result.suppressed_warnings),
+            ),
+            request_path=f"/inspect/{template_name}/",
+        )
+    except (DatafaceError, ValueError) as e:
+        error_msg = str(e)
+        # Surface table-not-found errors as 404 for better UX
+        if "does not exist" in error_msg:
+            return _render_structured_errors_html(
+                _synthetic_error(error_msg),
+                request_path=f"/inspect/{template_name}/",
+                status_override=404,
+            )
+        log_label = "custom" if has_custom else "built-in"
+        logger.exception("Error rendering %s inspect template", log_label)
+        err: RenderedDashboard
+        if isinstance(e, DatafaceError):
+            err = RenderedDashboard(success=False, face_error=e.to_structured())
+        else:
+            err = _synthetic_error(error_msg)
+        return _render_structured_errors_html(
+            err, request_path=f"/inspect/{template_name}/"
+        )
+
+
+def _render_prompt_page(title: str, prompt_card_html: str) -> str:
+    """Wrap a prompt card in a standalone styled HTML page for dft serve."""
+    safe_title = html_escape(title, quote=True)
+    return textwrap.dedent(
+        f"""\
+        <!doctype html>
+        <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>{safe_title}</title>
+            <style>
+              :root {{
+                color-scheme: light;
+                --page-bg: #f6f2e7;
+                --panel-bg: #fffdf8;
+                --text: #2f2a22;
+                --muted: #6d6558;
+                --border: #d7c7aa;
+                --accent: #8d4d00;
+              }}
+              body {{
+                margin: 0;
+                padding: 40px 20px;
+                background: var(--page-bg);
+                color: var(--text);
+                font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif;
+              }}
+              .missing-variables-prompt {{
+                max-width: 640px;
+                margin: 0 auto;
+              }}
+              .missing-variables-card {{
+                background: var(--panel-bg);
+                border: 1px solid var(--border);
+                border-radius: 18px;
+                padding: 28px 32px;
+                box-shadow: 0 12px 32px rgba(58, 41, 16, 0.08);
+              }}
+              h2 {{
+                margin: 0 0 8px;
+                color: var(--accent);
+                font-size: 1.5rem;
+              }}
+              p {{
+                margin: 0 0 20px;
+                color: var(--muted);
+                font-family: ui-sans-serif, system-ui, sans-serif;
+              }}
+              .missing-var-field {{
+                margin-bottom: 16px;
+              }}
+              label {{
+                display: block;
+                font-weight: 600;
+                margin-bottom: 4px;
+                font-family: ui-sans-serif, system-ui, sans-serif;
+                font-size: 0.9rem;
+              }}
+              .missing-var-description {{
+                color: var(--muted);
+                font-size: 0.85rem;
+                margin: 0 0 4px;
+              }}
+              .missing-var-input {{
+                width: 100%;
+                padding: 8px 12px;
+                border: 1px solid var(--border);
+                border-radius: 8px;
+                font-size: 1rem;
+                font-family: ui-sans-serif, system-ui, sans-serif;
+                box-sizing: border-box;
+              }}
+              .missing-variables-submit {{
+                margin-top: 8px;
+                padding: 10px 24px;
+                background: var(--accent);
+                color: #fff;
+                border: none;
+                border-radius: 8px;
+                font-size: 1rem;
+                cursor: pointer;
+                font-family: ui-sans-serif, system-ui, sans-serif;
+              }}
+              .missing-variables-submit:hover {{
+                opacity: 0.9;
+              }}
+            </style>
+          </head>
+          <body>
+            {prompt_card_html}
+          </body>
+        </html>
+        """
+    )
+
+
+def _render_directory_listing(dir_path: Path, url_path: str) -> HTMLResponse:
+    """Render a directory listing through a built-in dataface face."""
+    from dataface.core.compile import compile
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.execute import Executor
+    from dataface.core.execute.adapters import build_adapter_registry
+    from dataface.core.render import render
+
+    listing_lines: list[str] = []
+    if url_path:
+        parent_parts = url_path.strip("/").split("/")[:-1]
+        parent_url = "/" + "/".join(parent_parts)
+        listing_lines.append(f"- [../]({parent_url or '/'})")
+
+    for entry in sorted(
+        dir_path.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())
+    ):
+        if entry.name.startswith("."):
+            continue
+        # /inspect/<template> links require ?model=...&column=... query params;
+        # advertising them as bare entries in the root listing 500s on click.
+        if entry.name == "inspect" and not url_path:
+            continue
+        item_url = f"/{url_path}/{entry.name}".replace("//", "/")
+        if entry.is_dir():
+            listing_lines.append(f"- [{entry.name}/]({item_url}/)")
+        elif entry.suffix in (".yml", ".yaml", ".md"):
+            listing_lines.append(
+                f"- [{entry.name}]({item_url.removesuffix(entry.suffix)})"
+            )
+
+    try:
+        template_path = files("dataface.core.serve.templates").joinpath("directory.yml")
+        rendered_yaml = resolve_jinja_template(
+            template_path.read_text(),
+            variables={
+                "directory_title": f"/{url_path}" if url_path else "/",
+                "listing_markdown": "\n".join(listing_lines)
+                or "No faces or directories found.",
+            },
+            strict=False,
+        )
+        result = compile(rendered_yaml)
+        if result.errors or not result.face:
+            raise RuntimeError(
+                f"Directory face failed: {[e.message for e in result.errors]}"
+            )
+
+        # Directory listings are cache-miss-dominant in practice, but consistency
+        # with the face-render path matters more than the micro-optimisation.
+        html = render(
+            result.face,
+            Executor(
+                result.face,
+                adapter_registry=build_adapter_registry(dir_path),
+                duckdb_cache=_get_default_cache(),
+            ),
+            format="html",
+        ).output
+        if isinstance(html, bytes):
+            html = html.decode("utf-8")
+        return HTMLResponse(content=html)
+    except (DatafaceError, ValueError, FileNotFoundError) as e:
+        if logger.isEnabledFor(logging.DEBUG):
+            raise
+        logger.exception("Error rendering directory listing for %s", dir_path)
+        if isinstance(e, DatafaceError):
+            err = RenderedDashboard(success=False, face_error=e.to_structured())
+        else:
+            err = _synthetic_error(str(e))
+        return _render_structured_errors_html(err, request_path=url_path)
+
+
+def create_server(
+    project_dir: Path | None = None,
+    connection: str | None = None,
+    dialect: str = "duckdb",
+    faces_at_root: bool | None = None,
+    target: str | None = None,
+    serve_storage_prefix: str | None = None,
+    read_only: bool = LOCAL_AUTHORING_REGISTRY_KWARGS["read_only"],
+    allow_external_access_in_readonly: bool = LOCAL_AUTHORING_REGISTRY_KWARGS[
+        "allow_external_access_in_readonly"
+    ],
+    duckdb_config: dict[str, Any] | None = None,
+) -> FastAPI:
+    """Create unified Dataface server.
+
+    Args:
+        project_dir: Project directory for resolving face file paths
+        connection: Database connection string
+        dialect: SQL dialect for face rendering (duckdb, postgres, etc.).
+            The /inspect/* HTML path is always DuckDB — dialect is not forwarded there.
+        faces_at_root: Serve faces at / instead of /faces/. Auto-detected
+            from project structure when not specified (True if faces/ exists).
+        target: dbt target name override for DbtAdapter
+        serve_storage_prefix: Override for rendered board-link URLs in serve mode
+        read_only: DuckDB read-only driver flag for face rendering (default True).
+        allow_external_access_in_readonly: When True with read_only, allow SQL
+            read_csv/read_json_auto on local paths (local dev default True).
+        duckdb_config: DuckDB config dict; defaults to enable_external_access when
+            allow_external_access_in_readonly is True.
+
+    Returns:
+        Configured FastAPI application
+    """
+    if duckdb_config is None and allow_external_access_in_readonly:
+        duckdb_config = LOCAL_AUTHORING_REGISTRY_KWARGS["duckdb_config"]
+
+    @asynccontextmanager
+    async def _lifespan(_app: FastAPI) -> AsyncGenerator[None, None]:
+        global _cache, _cache_initialised
+        yield
+        if _cache is not None:
+            _cache.close()
+        _cache = None
+        _cache_initialised = False
+
+    app = FastAPI(
+        title="Dataface Server",
+        description="Unified server for Dataface rendering",
+        version="0.1.0",
+        lifespan=_lifespan,
+    )
+
+    app.state.project_dir = project_dir or Path.cwd()
+    app.state.connection = connection
+    app.state.dialect = dialect
+    if faces_at_root is None:
+        faces_at_root = (app.state.project_dir / "faces").is_dir()
+    app.state.faces_at_root = faces_at_root
+    app.state.target = target
+    app.state.serve_storage_prefix = serve_storage_prefix
+    app.state.read_only = read_only
+    app.state.allow_external_access_in_readonly = allow_external_access_in_readonly
+    app.state.duckdb_config = duckdb_config
+
+    # Mount the bundled webfonts at /static/fonts so the @font-face URLs
+    # injected into rendered HTML/SVG (Inter Variable, DFT Sans Tabular,
+    # Source Serif 4, Noto Emoji) resolve in the browser. Register before the
+    # `/{path:path}` catch-all — Starlette matches routes in insertion order.
+    app.mount(
+        "/static/fonts",
+        StaticFiles(directory=get_inter_font_path().parent),
+        name="fonts_static",
+    )
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        """Health check endpoint."""
+        return {"status": "ok", "service": "dataface-server"}
+
+    @app.get("/templates")
+    async def list_templates() -> dict[str, Any]:
+        """List available inspect templates."""
+        return {"inspect_templates": INSPECT_TEMPLATES}
+
+    @app.post("/inspect/profile/", response_class=HTMLResponse)
+    async def profile_table(request: Request) -> str:
+        """Run table profiling, save results, and render the dashboard.
+
+        Requires ``dataface-super-schema`` to be installed. Without the private
+        package, this endpoint returns 503 with an install hint.
+
+        Uses POST to avoid accidental invocation by prefetchers/crawlers.
+        """
+        if not _SUPER_SCHEMA_AVAILABLE:
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    "Table profiling requires the dataface-super-schema package. "
+                    "Install it from the monorepo or your private registry."
+                ),
+            )
+        from dataface_super_schema.inspect.connection import (  # noqa: PLC0415
+            source_config_from_url,
+        )
+        from dataface_super_schema.inspect.inspector import (  # noqa: PLC0415
+            TableInspector,
+        )
+        from dataface_super_schema.inspect.storage import (  # noqa: PLC0415
+            InspectionStorage,
+        )
+
+        variables = dict(request.query_params)
+        model_name = variables.get("model", "")
+        if not model_name:
+            raise HTTPException(status_code=400, detail="model parameter required")
+
+        # Apply server defaults so browser-initiated profiling uses the
+        # configured connection, not the fallback `:memory:`.
+        if "connection" not in variables and app.state.connection:
+            variables["connection"] = app.state.connection
+
+        try:
+            variables = validate_inspect_variables(variables)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e)) from e
+
+        super_schema_path = app.state.project_dir / InspectionStorage.DEFAULT_PATH
+        storage = InspectionStorage(output_path=super_schema_path)
+
+        # Inspect HTML server is DuckDB-only.
+        profile_connection = variables.get("connection", ":memory:")
+        profile_dialect = "duckdb"
+        try:
+            with TableInspector(
+                source_config_from_url(profile_connection, profile_dialect)
+            ) as inspector:
+                profile = inspector.inspect_table(model_name)
+            storage.save_inspection(profile)
+        except Exception as e:
+            logger.exception("Profile failed for %s", model_name)
+            raise HTTPException(
+                status_code=500,
+                detail="Profiling failed. Check server logs for details.",
+            ) from e
+
+        template_path = files("dataface.core.inspect.templates").joinpath("model.yml")
+        return render_inspect_dashboard(
+            template_path.read_text(),
+            variables,
+            project_root=app.state.project_dir,
+            connection=profile_connection,
+        )
+
+    @app.get("/inspect/exists/")
+    async def table_exists(model: str, connection: str | None = None) -> Response:
+        """Check if a table exists in the warehouse without reading profile data.
+
+        Requires ``dataface-super-schema`` to be installed.
+        Returns 200 {"exists": true} when found, 404 when not found.
+        Returns 500 if the check itself fails (caller falls through to generic error UI).
+        """
+        if not _SUPER_SCHEMA_AVAILABLE:
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    "Table existence check requires the dataface-super-schema package."
+                ),
+            )
+        from dataface_super_schema.inspect.connection import (  # noqa: PLC0415
+            InspectConnection,
+            source_config_from_url,
+        )
+
+        variables: dict[str, str] = {"model": model}
+        if connection:
+            variables["connection"] = connection
+        try:
+            variables = validate_inspect_variables(variables)
+        except ValueError as e:
+            raise HTTPException(status_code=422, detail=str(e)) from e
+
+        conn_str = variables.get("connection") or app.state.connection or ":memory:"
+        try:
+            with InspectConnection(
+                source_config_from_url(conn_str, "duckdb"), read_only=True
+            ) as conn:
+                rows = conn.execute(
+                    "SELECT 1 FROM information_schema.tables WHERE table_name = ? LIMIT 1",
+                    [model],
+                ).fetchall()
+        except (
+            Exception
+        ) as e:  # noqa: BLE001 — HTTP boundary: any DB error must surface as 500, not crash server
+            logger.warning("inspect/exists check failed for %r: %s", model, e)
+            raise HTTPException(
+                status_code=500, detail="Warehouse existence check failed"
+            ) from e
+        if rows:
+            return JSONResponse({"exists": True})
+        raise HTTPException(
+            status_code=404, detail=f"Table '{model}' not found in warehouse"
+        )
+
+    @app.get("/{path:path}", response_class=HTMLResponse)
+    async def get_face(path: str, request: Request) -> Response:
+        """Serve any face file with query params as variables.
+
+        URL path maps to file path:
+            /sales/ → faces/sales.yml (when faces_at_root=True)
+            /dashboards/exec/ → dashboards/exec.yml
+
+        When faces_at_root is active, /faces/* returns 404.
+
+        Directories show a listing of renderable files and subdirectories.
+
+        Special case - /inspect/* paths:
+            1. Check faces/inspect/{template}.yml for custom templates
+            2. Fall back to built-in templates with Jinja2 pre-processing
+
+        Query params become variables:
+            /sales/?region=West → variables["region"] = "West"
+        """
+        clean_path = path.strip("/")
+        faces_dir = app.state.project_dir / "faces"
+
+        if app.state.faces_at_root and (
+            clean_path == "faces" or clean_path.startswith("faces/")
+        ):
+            raise HTTPException(status_code=404, detail="Not found")
+
+        variables = _apply_server_defaults(
+            dict(request.query_params),
+            connection=app.state.connection,
+        )
+
+        # Prefer a project-level index face for the root URL before directory listing.
+        if not clean_path:
+            candidate = _resolve_root_index_face(app.state.project_dir)
+            if candidate is not None:
+                return _render_face_file(
+                    candidate,
+                    variables,
+                    app.state.project_dir,
+                    connection=app.state.connection,
+                    dialect=app.state.dialect,
+                    target=app.state.target,
+                    faces_at_root=app.state.faces_at_root,
+                    serve_storage_prefix=app.state.serve_storage_prefix,
+                    read_only=app.state.read_only,
+                    allow_external_access_in_readonly=app.state.allow_external_access_in_readonly,
+                    duckdb_config=app.state.duckdb_config,
+                )
+
+        # Directory listing for root or any directory
+        for dir_path, listing_path in _directory_candidates(
+            project_dir=app.state.project_dir,
+            faces_dir=faces_dir,
+            clean_path=clean_path,
+            faces_at_root=app.state.faces_at_root,
+        ):
+            _ensure_within_project(dir_path, app.state.project_dir)
+            if dir_path.is_dir():
+                return _render_directory_listing(dir_path, listing_path)
+
+        # Special case: /inspect/* paths use built-in template fallback (DuckDB-only).
+        if clean_path.startswith("inspect/"):
+            template_name = clean_path.removeprefix("inspect/")
+            return _handle_inspect_route(
+                template_name,
+                variables,
+                app.state.project_dir,
+                connection=app.state.connection,
+                target=app.state.target,
+                read_only=app.state.read_only,
+            )
+
+        file_path = _resolve_face_file_path(
+            project_dir=app.state.project_dir,
+            faces_dir=faces_dir,
+            clean_path=clean_path,
+            faces_at_root=app.state.faces_at_root,
+        )
+
+        return _render_face_file(
+            file_path,
+            variables,
+            app.state.project_dir,
+            connection=app.state.connection,
+            dialect=app.state.dialect,
+            faces_at_root=app.state.faces_at_root,
+            target=app.state.target,
+            serve_storage_prefix=app.state.serve_storage_prefix,
+            read_only=app.state.read_only,
+            allow_external_access_in_readonly=app.state.allow_external_access_in_readonly,
+            duckdb_config=app.state.duckdb_config,
+        )
+
+    return app