dataface 0.3.2.dev22__py3-none-any.whl → 0.3.2.dev150__py3-none-any.whl

dataface/cli/commands/render.py

@@ -1,24 +1,22 @@
 """Render command implementation."""
 
+from __future__ import annotations
+
 import json as _json
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import typer
 
-from dataface.agent_api import Diagnostic, InMemoryFace, ProjectSession, RenderFormat
-from dataface.agent_api._paths import (
-    build_face_render_context,
-    build_yaml_render_context,
-    resolve_face_or_error,
-)
-from dataface.agent_api.cache import project_cache_ctx
-from dataface.agent_api.dashboards import RenderedDashboard
-from dataface.agent_api.diagnostics import REGISTRY as _diag_registry
+from dataface.agent_api import Diagnostic, RenderFormat
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 from dataface.cli.filesystem_project import FilesystemProject
 
+if TYPE_CHECKING:
+    from dataface.agent_api.dashboards import RenderedDashboard
+
 # Maps common file extensions to render formats for format inference.
 _EXT_TO_FORMAT: dict[str, RenderFormat] = {
     "svg": "svg",
@@ -64,6 +62,8 @@ def _validate_ignore_codes(ignore_codes: set[str]) -> None:
     at error level (suppressing an error is never valid) versus a code that
     isn't registered at all (a typo or stale suppression stub).
     """
+    from dataface.agent_api.diagnostics import REGISTRY as _diag_registry
+
     warning_codes = _diag_registry.codes(level="warning")
     error_codes = _diag_registry.codes(level="error")
     for code in sorted(ignore_codes):
@@ -172,6 +172,7 @@ def render_command(
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
     print0: bool = False,
+    chart: str | None = None,
     *,
     project: FilesystemProject,
 ) -> str | None:
@@ -204,6 +205,13 @@ def render_command(
     Returns:
         Output file path on success, None for terminal/stdout output
     """
+    from dataface.agent_api import ProjectSession
+    from dataface.agent_api._paths import (
+        build_face_render_context,
+        resolve_face_or_error,
+    )
+    from dataface.agent_api.cache import project_cache_ctx
+
     if ignore_codes:
         _validate_ignore_codes(ignore_codes)
 
@@ -230,6 +238,7 @@ def render_command(
             raise RenderFailed([resolved])
         result = project_session.render_dashboard(
             face=resolved,
+            chart=chart,
             format=format,
             variables=variables,
             use_cache=use_cache,
@@ -266,6 +275,7 @@ def render_command_from_yaml(
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
     print0: bool = False,
+    chart: str | None = None,
     *,
     project: FilesystemProject,
 ) -> str | None:
@@ -296,6 +306,10 @@ def render_command_from_yaml(
         Output file path on success, None for terminal/stdout output. Exits 1
         (typer.Exit) after reporting on a validation/chart failure.
     """
+    from dataface.agent_api import InMemoryFace, ProjectSession
+    from dataface.agent_api._paths import build_yaml_render_context
+    from dataface.agent_api.cache import project_cache_ctx
+
     if ignore_codes:
         _validate_ignore_codes(ignore_codes)
 
@@ -318,6 +332,7 @@ def render_command_from_yaml(
         face = InMemoryFace(yaml_content, path=None)
         result = project_session.render_dashboard(
             face=face,
+            chart=chart,
             format=format,
             variables=variables,
             use_cache=use_cache,
@@ -428,6 +443,7 @@ def render_commands(
     max_workers: int | None = None,
     print0: bool = False,
     fail_fast: bool = False,
+    chart: str | None = None,
 ) -> None:
     """Render one or more dashboards, printing output paths to stdout.
 
@@ -474,6 +490,7 @@ def render_commands(
                 fail_on_chart_errors=fail_on_chart_errors,
                 max_workers=max_workers,
                 print0=print0,
+                chart=chart,
             )
         except RenderFailed as exc:
             print_diagnostics(exc.errors, json_output=json_errors)

dataface/cli/commands/search.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 import typer
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api.search import SearchResult
+from dataface.agent_api import Project
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 
+if TYPE_CHECKING:
+    from dataface.agent_api.search import SearchResult
+
 
 @with_project
 def search_command(
@@ -19,6 +23,8 @@ def search_command(
     limit: int = 10,
 ) -> None:
     """Search dashboards by keyword with ranked results."""
+    from dataface.agent_api import ProjectSession
+
     with ProjectSession.from_project(project) as project_session:
         result = project_session.search_dashboards(query, limit=limit)
 

dataface/cli/commands/serve.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import os
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -10,15 +9,10 @@ from typing import TYPE_CHECKING
 import typer
 import uvicorn
 
+from dataface.agent_api import Diagnostic
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.diagnostics import ERR_STARTUP_FAILED
-
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.diagnostics.base import DatafaceError
-
 if TYPE_CHECKING:
     from dataface.cli.filesystem_project import FilesystemProject
 
@@ -34,7 +28,6 @@ def serve_command(
     max_workers: int | None = None,
     no_cache: bool = False,
     cache_path: Path | None = None,
-    allow_external_access: bool = False,
 ) -> None:
     """Start unified Dataface server.
 
@@ -55,10 +48,6 @@ def serve_command(
         project: The resolved Dataface project (injected by @with_project)
         dialect: SQL dialect (auto-detected from dbt profile, or duckdb)
         target: dbt target name (defaults to DBT_TARGET env var, then profile default)
-        allow_external_access: Allow author SQL to reach the filesystem/network via
-            DuckDB (read_csv, read_json_auto, httpfs). Off by default — serve is
-            strict read-only. Opt in only for local dashboards that must read files
-            directly in SQL (e.g. glob-based analytics that cannot be file sources).
         no_cache: Skip the query-result cache entirely.
         cache_path: Persist the query-result cache to this DuckDB file (created
             if absent). None (the default) opens an in-memory cache — ephemeral,
@@ -68,86 +57,42 @@ def serve_command(
         None (exits with code 0 on success, 1 on errors)
     """
     from dataface.agent_api import set_surface
-
-    # tach-ignore(cli->core debt: route via agent_api; burn-down task)
-    from dataface.core.compile.config import list_built_in_themes, load_config
-
-    # tach-ignore(cli->core debt: route via agent_api; burn-down task)
-    from dataface.core.diagnostics import ERR_INVALID_DEFAULT_THEME
-
-    # tach-ignore(cli->core debt: route via agent_api; burn-down task)
-    from dataface.core.project_roots import infer_dialect_from_dbt
-
-    # tach-ignore(cli->core debt: route via agent_api; burn-down task)
-    from dataface.core.serve.port import resolve_port
-
-    # tach-ignore(cli->core debt: route via agent_api; burn-down task)
-    from dataface.core.serve.server import create_server
+    from dataface.agent_api.serve import format_startup_failure, prepare_serve
 
     # Narrows the root callback's "cli": a served dashboard's queries are a
     # different cost story from a one-shot `dft render`.
     set_surface("serve")
 
-    project_dir = project.root
-
-    # Validate DFT_DEFAULT_THEME at startup — fail fast before serving any request.
-    # The env var is read per-compilation by get_default_theme_name(); validation
-    # here ensures the user sees a clear error at startup rather than on first render.
-    env_theme = os.environ.get(
-        "DFT_DEFAULT_THEME"
-    )  # noqa: TID251 — DFT_DEFAULT_THEME knob
-    # Empty string is treated as unset (matches get_default_theme_name, which
-    # falls back to the shipped default) — only a non-empty unknown name errors.
-    if env_theme:
-        available = list_built_in_themes()
-        if env_theme not in available:
-            err = DatafaceError.from_code(
-                ERR_INVALID_DEFAULT_THEME,
-                source="DFT_DEFAULT_THEME env var",
-                theme=env_theme,
-                available=available,
-            )
-            print_diagnostics([err.to_diagnostic()])
-            raise typer.Exit(1) from None
-
-    # Validate dataface.yml wholesale: stray keys (style:, board:, theme:, etc.) are a
-    # hard error here at startup rather than silently ignored.
+    # Validate DFT_DEFAULT_THEME/dataface.yml, resolve port/dialect, and build the
+    # ASGI app — a dataface.yml validation failure raises pydantic's ValidationError
+    # uncaught (matches pre-existing behavior: a plain echo, not the Diagnostic
+    # envelope used everywhere else in this command).
     from pydantic import ValidationError as _PydanticError
 
     try:
-        load_config(project)
+        setup = prepare_serve(
+            project,
+            port=port,
+            host=host,
+            dialect=dialect,
+            target=target,
+            max_workers=max_workers,
+            no_cache=no_cache,
+            cache_path=cache_path,
+        )
     except _PydanticError as e:
         typer.echo(f"dataface.yml validation error: {e}", err=True)
         raise typer.Exit(1) from None
 
-    # Resolve port: --port > DFT_PORT > dataface.yml server.port > hash(project_dir)
-    port = resolve_port(
-        explicit_port=port,
-        project_dir=project_dir,
-        host=host,
-    )
+    if isinstance(setup, Diagnostic):
+        print_diagnostics([setup])
+        raise typer.Exit(1) from None
 
-    # Resolve dbt target: CLI flag > DBT_TARGET env > profile default
-    effective_target = target or os.environ.get("DBT_TARGET") or None
-
-    # Infer dialect from dbt profile when not explicitly provided
-    effective_dialect = dialect
-    if effective_dialect is None:
-        inferred = infer_dialect_from_dbt(project_dir, effective_target)
-        if inferred:
-            typer.echo(f"  Auto-detected dialect: {inferred} (from dbt profile)")
-        effective_dialect = inferred or "duckdb"
-
-    # Create FastAPI app
-    app = create_server(
-        project,
-        dialect=effective_dialect,
-        target=effective_target,
-        max_workers=max_workers,
-        no_cache=no_cache,
-        cache_path=cache_path,
-        allow_external_access_in_readonly=allow_external_access,
-    )
+    if setup.dialect_inferred:
+        typer.echo(f"  Auto-detected dialect: {setup.dialect} (from dbt profile)")
+
+    port = setup.port
+    app = setup.app
 
     # Start server
     typer.echo("🚀 Starting dashboard server")
@@ -175,6 +120,5 @@ def serve_command(
         typer.echo("\n👋 Server stopped")
         sys.exit(0)
     except Exception as e:  # noqa: BLE001 — uvicorn surface
-        err = DatafaceError.from_code(ERR_STARTUP_FAILED, detail=str(e))
-        print_diagnostics([err.to_diagnostic()])
+        print_diagnostics([format_startup_failure(e)])
         raise typer.Exit(1) from None

dataface/cli/commands/skills_init.py

@@ -7,28 +7,11 @@ from pathlib import Path
 import typer
 
 from dataface.agent_api import skill_install
-
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.project_roots import find_dft_root, find_repo_root
+from dataface.cli._project import resolve_skill_install_root
 
 _VALID_TARGETS = skill_install.SKILL_INSTALL_TARGETS
 
 
-def _resolve_project_dir(start: Path) -> Path:
-    """Return the directory where skills should be installed.
-
-    Skills are agent tooling that belong at the git root, not the operational
-    project root. When a .git directory exists above the dataface.yml, install
-    at the git root so monorepos with nested dataface projects don't accumulate
-    divergent skill copies.
-    """
-    project_root = find_dft_root(start) or start.resolve()
-    git_root = find_repo_root(project_root)
-    if git_root is not None:
-        return git_root
-    return project_root
-
-
 def _resolve_targets(
     target: str | None,
     *,
@@ -110,7 +93,7 @@ def run_init_skills(
         typer.echo("Specify either --all or --dir, not both.", err=True)
         raise typer.Exit(1)
 
-    project_root = _resolve_project_dir(
+    project_root = resolve_skill_install_root(
         project_dir if project_dir is not None else Path.cwd()
     )
     target_dirs = _resolve_targets(

dataface/cli/commands/validate.py

@@ -4,15 +4,18 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import typer
 
-from dataface.agent_api import Project, ProjectSession
-from dataface.agent_api.validate import ValidateResult
+from dataface.agent_api import Project
 from dataface.cli._console import dft_console
 from dataface.cli._error_format import print_diagnostics
 from dataface.cli._project import with_project
 
+if TYPE_CHECKING:
+    from dataface.agent_api.validate import ValidateResult
+
 _console = dft_console()
 
 
@@ -24,6 +27,8 @@ def validate_command(
     json_output: bool = False,
     strict: bool = False,
 ) -> None:
+    from dataface.agent_api import ProjectSession
+
     with ProjectSession.from_project(project) as project_session:
         results = project_session.validate_paths(paths)
     _emit(results, json_output=json_output, strict=strict)

dataface/cli/filesystem_project.py

@@ -30,6 +30,7 @@ from dataface.core.project import (
     assert_relpath,
     glob_literal_prefix,
     glob_to_regex,
+    posix_relpath,
 )
 
 if TYPE_CHECKING:
@@ -143,7 +144,7 @@ class FilesystemProject(Project):
         # First try: fully resolved path. Handles OS-level symlinks (/var on macOS).
         resolved = path.resolve()
         try:
-            return str(resolved.relative_to(self.root))
+            return posix_relpath(resolved, self.root)
         except ValueError:
             pass
 
@@ -151,7 +152,7 @@ class FilesystemProject(Project):
         # paths through project-internal symlinks (e.g. faces/tasks/ -> ../../tasks/).
         normalized = Path(os.path.normpath(path.absolute()))
         try:
-            return str(normalized.relative_to(self.root))
+            return posix_relpath(normalized, self.root)
         except ValueError:
             raise ValueError(
                 f"Path {path!r} is outside project root {self.root!r}"
@@ -218,12 +219,12 @@ class FilesystemProject(Project):
                 dirs[:] = sorted(d for d in dirs if d not in SKIP_SCAN_DIRS)
                 root_path = Path(root_str)
                 for name in files:
-                    candidates.append(str((root_path / name).relative_to(self.root)))
+                    candidates.append(posix_relpath(root_path / name, self.root))
             yield from sorted(candidates)
         else:
             for p in sorted(subtree.iterdir()):
                 if p.is_file():
-                    yield str(p.relative_to(self.root))
+                    yield posix_relpath(p, self.root)
 
     def iter_dir(self, under: str) -> Iterator[ProjectPath | ProjectDirectory]:
         """``os.scandir`` over *under*, filtered/sorted per ``Project.iter_dir``.

dataface/cli/main.py

@@ -16,6 +16,7 @@ from dataface.agent_api import RenderFormat, set_surface
 from dataface.cli._console import is_plain_output
 from dataface.cli._extras import require_extras
 from dataface.cli._parsing import parse_kv_pairs
+from dataface.cli._project import has_faces_marker
 from dataface.cli.commands import (
     board_artifact as board_artifact_cmd,
     describe as describe_cmd,
@@ -35,9 +36,6 @@ from dataface.cli.commands import (
 from dataface.cli.commands.mcp_init import run_init as _mcp_run_init
 from dataface.cli.commands.skills_init import run_init_skills as _skills_run_init
 
-# tach-ignore(cli->core debt: route via agent_api; burn-down task)
-from dataface.core.project_roots import find_dft_root
-
 # Evaluated once at process startup — mid-session env changes won't take effect.
 _RICH_MARKUP_MODE: Literal["rich"] | None = None if is_plain_output() else "rich"
 # Probe for private package once at startup; avoids repeated find_spec calls.
@@ -107,21 +105,6 @@ if not logging.getLogger().handlers:
     )
 
 
-def _has_faces_marker(start: Path) -> bool:
-    """True iff *start* sits inside a Dataface project that has a ``faces/`` directory.
-
-    Anchors on :func:`find_dft_root` so the walk-up stops at the
-    project root (any of ``dataface.yml``/``dataface.yaml``/``dbt_project.yml``)
-    rather than blindly hunting upward for stray ``faces/`` directories
-    elsewhere on the filesystem. A bare-dbt repo with no scaffolded
-    ``faces/`` returns False — that's the case the banner exists for.
-    """
-    if (start / "faces").is_dir():
-        return True
-    project = find_dft_root(start)
-    return project is not None and (project / "faces").is_dir()
-
-
 def _render_init_banner() -> None:
     """Print a nudge to run ``dft init``.
 
@@ -203,7 +186,7 @@ class _RootHelpGroup(TyperGroup):
         )
 
     def format_help(self, ctx: Any, formatter: Any) -> None:
-        if not _has_faces_marker(Path.cwd()):
+        if not has_faces_marker(Path.cwd()):
             _render_init_banner()
         super().format_help(ctx, formatter)
 
@@ -813,6 +796,16 @@ def render(
             ),
         ),
     ] = False,
+    chart: Annotated[
+        str | None,
+        typer.Option(
+            "--chart",
+            help=(
+                "Render only this chart (by chart id). "
+                "Valid only with a single face argument or stdin."
+            ),
+        ),
+    ] = None,
 ) -> None:
     """Render one or more dashboards to SVG, HTML, PNG, PDF, or terminal.
 
@@ -876,6 +869,14 @@ def render(
                 param_hint="--output",
             )
 
+    # --chart is ambiguous with multiple faces: no mapping syntax, no silent fanout.
+    if chart is not None and len(faces) > 1:
+        raise typer.BadParameter(
+            f"--chart is only valid with a single face argument; "
+            f"got {len(faces)} face arguments",
+            param_hint="--chart",
+        )
+
     # Stdin path (single face "-")
     if has_stdin:
         yaml_content = sys.stdin.read()
@@ -896,6 +897,7 @@ def render(
             fail_on_chart_errors=fail_on_chart_errors,
             max_workers=max_workers,
             print0=print0,
+            chart=chart,
         )
         return
 
@@ -914,6 +916,7 @@ def render(
         max_workers=max_workers,
         print0=print0,
         fail_fast=fail_fast,
+        chart=chart,
     )
 
 
@@ -1104,19 +1107,6 @@ def serve(
             ),
         ),
     ] = None,
-    allow_external_access: Annotated[
-        bool,
-        typer.Option(
-            "--allow-external-access",
-            help=(
-                "Allow author SQL to read local files / URLs through DuckDB "
-                "(read_csv, read_json_auto, httpfs). Off by default — serve runs "
-                "strict read-only. Opt in only for local dashboards that must read "
-                "files directly in SQL (e.g. glob analytics not expressible as file "
-                "sources); prefer type: csv/json/parquet sources otherwise."
-            ),
-        ),
-    ] = False,
 ) -> None:
     """Start the dashboard server.
 
@@ -1166,7 +1156,6 @@ def serve(
         max_workers=max_workers,
         no_cache=no_cache,
         cache_path=cache,
-        allow_external_access=allow_external_access,
     )
 
 

dataface/core/__init__.py

@@ -13,8 +13,10 @@ Submodules:
 
 High-Level API:
     >>> from pathlib import Path
-    >>> from dataface.core import compile, Executor, render
+    >>> from dataface.core.compile import compile
+    >>> from dataface.core.execute import Executor
     >>> from dataface.core.execute.adapters import build_adapter_registry
+    >>> from dataface.core.render import render
     >>> result = compile(yaml_content)
     >>> from dataface.cli.filesystem_project import FilesystemProject
     >>> registry = build_adapter_registry(FilesystemProject(Path.cwd()))
@@ -22,37 +24,45 @@ High-Level API:
     >>> html = render(result.face, executor, format="html")
 """
 
-# Re-export main compile functions and types
-# Re-export validate module
-from dataface.core import validate
-from dataface.core.compile import (
-    AnyQuery,
-    AuthoredFace,
-    CompilationError,
-    CompileResult,
-    Face,
-    Layout,
-    LayoutItem,
-    Variable,
-    compile,
-    compile_file,
-)
+from __future__ import annotations
 
-# Re-export execute functions and types
-from dataface.core.execute import (
-    ExecutionError,
-    Executor,
-)
+import importlib
+from typing import TYPE_CHECKING, Any
 
-# Re-export render functions and types
-from dataface.core.render import (
-    RenderError,
-    render,
-)
+if TYPE_CHECKING:
+    # Import-time-only: PEP 562 __getattr__ below resolves these lazily at
+    # runtime, so `import dataface.core.<anything>` (this file runs first,
+    # always) doesn't eagerly pull in the whole compile/execute/render stack
+    # just for this convenience re-export.
+    from dataface.core import validate as validate
+    from dataface.core.compile import (
+        AnyQuery as AnyQuery,
+        AuthoredFace as AuthoredFace,
+        CompilationError as CompilationError,
+        CompileResult as CompileResult,
+        Face as Face,
+        Layout as Layout,
+        LayoutItem as LayoutItem,
+        Variable as Variable,
+        compile_file as compile_file,
+    )
+    from dataface.core.execute import (
+        ExecutionError as ExecutionError,
+        Executor as Executor,
+    )
+    from dataface.core.render import RenderError as RenderError
 
+# `compile` and `render` are deliberately NOT re-exported here: both names
+# collide with a same-named submodule one level down (`dataface.core.compile`,
+# `dataface.core.render`). Importing that submodule for *any* reason binds it
+# onto this package under that exact name as a side effect of Python's own
+# import machinery — a rebind PEP 562 __getattr__ cannot see or prevent — so a
+# lazy alias sharing a submodule's leaf name silently flips from function to
+# module depending on import order. Import the function directly from its
+# submodule instead: `from dataface.core.compile import compile`,
+# `from dataface.core.render import render`.
 __all__ = [
     # Compile
-    "compile",
     "compile_file",
     "CompileResult",
     "Face",
@@ -66,8 +76,43 @@ __all__ = [
     "Executor",
     "ExecutionError",
     # Render
-    "render",
     "RenderError",
     # Validate
     "validate",
 ]
+
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "validate": ("dataface.core", "validate"),
+    "AnyQuery": ("dataface.core.compile", "AnyQuery"),
+    "AuthoredFace": ("dataface.core.compile", "AuthoredFace"),
+    "CompilationError": ("dataface.core.compile", "CompilationError"),
+    "CompileResult": ("dataface.core.compile", "CompileResult"),
+    "Face": ("dataface.core.compile", "Face"),
+    "Layout": ("dataface.core.compile", "Layout"),
+    "LayoutItem": ("dataface.core.compile", "LayoutItem"),
+    "Variable": ("dataface.core.compile", "Variable"),
+    "compile_file": ("dataface.core.compile", "compile_file"),
+    "ExecutionError": ("dataface.core.execute", "ExecutionError"),
+    "Executor": ("dataface.core.execute", "Executor"),
+    "RenderError": ("dataface.core.render", "RenderError"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_path, attr_name = _LAZY_ATTRS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    if module_path == __name__ and attr_name == name:
+        # "validate" is a submodule of this very package, not another
+        # module's attribute — import it directly to avoid recursing back
+        # into this __getattr__.
+        module = importlib.import_module(f"{__name__}.{attr_name}")
+    else:
+        module = getattr(importlib.import_module(module_path), attr_name)
+    globals()[name] = module  # cache: repeated access is O(1) and `is` identity holds
+    return module
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_ATTRS))

dataface/core/aliases.py

@@ -0,0 +1,27 @@
+"""Alias-URL semantics, shared by every host that resolves a face's ``aliases:``.
+
+A leaf module on purpose. An alias is claimed in a face and matched against an
+incoming request path as a *string*, so the two sides must normalize it
+identically or a claim resolves on one host and silently does nothing on the
+other. Hosts that keep their own board index (rather than building an
+``AliasIndex``) need that rule without importing the ``dft serve`` HTTP
+application to get it — ``core/serve/`` sits at the top of the dependency stack.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import unquote
+
+
+def normalize_alias_url(url: str) -> str:
+    """Normalize a URL key: percent-decode, ensure leading /, ensure trailing /."""
+    decoded = unquote(url)
+    if not decoded.startswith("/"):
+        raise ValueError(
+            f"Alias {url!r} is not absolute: aliases must start with a leading /. "
+            "Example: /old-reports/"
+        )
+    # Trailing-slash canonical: add if missing
+    if not decoded.endswith("/"):
+        decoded = decoded + "/"
+    return decoded