publinker-cli 0.6.2__py3-none-any.whl

publinker_cli/manifest.py

@@ -0,0 +1,409 @@
+"""Route manifest loader for publinker-cli.
+
+Loads ``routes.yaml`` (next to this module) into a list of typed ``Route``
+records. The CLI dispatch builds a Typer command tree from these.
+
+This module deliberately uses ``dataclasses`` + ``yaml`` rather than Pydantic
+to keep runtime dependencies minimal (the CLI is a developer tool, every
+megabyte of dependency cost is felt at ``pipx install`` time).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from urllib.parse import quote
+
+import yaml
+
+from publinker_cli import audience as audience_mod
+
+DEFAULT_ROUTES_FILE = Path(__file__).parent / "routes.yaml"
+
+# Allowed risk tiers. v0.3 only ships GET routes (risk "read" or "admin");
+# mutating tiers ("write", "deploy-trigger") are reserved for v0.4+.
+RISK_TIERS = {"read", "write", "deploy-trigger", "admin"}
+
+# Allowed HTTP methods.
+METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+
+# Matches `{name}` placeholders in API paths.
+_PATH_PLACEHOLDER = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+class ManifestError(ValueError):
+    """Raised when the manifest is malformed."""
+
+
+@dataclass(frozen=True)
+class CLISpec:
+    group: tuple[str, ...]
+    command: str
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "CLISpec":
+        if not isinstance(raw, dict):
+            raise ManifestError(f"{route_id}: cli must be a dict")
+        try:
+            group = raw["group"]
+            command = raw["command"]
+        except KeyError as exc:
+            raise ManifestError(f"{route_id}: cli missing required key {exc}") from exc
+        if not isinstance(group, list) or not all(isinstance(g, str) for g in group):
+            raise ManifestError(f"{route_id}: cli.group must be a list of strings")
+        if not isinstance(command, str):
+            raise ManifestError(f"{route_id}: cli.command must be a string")
+        return cls(group=tuple(group), command=command)
+
+
+@dataclass(frozen=True)
+class MCPSpec:
+    expose: bool
+    tool_name: Optional[str]
+    description: str
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "MCPSpec":
+        if not isinstance(raw, dict):
+            raise ManifestError(f"{route_id}: mcp must be a dict")
+        expose = bool(raw.get("expose", False))
+        tool_name = raw.get("tool_name")
+        description = raw.get("description", "").strip()
+        if expose:
+            if not tool_name:
+                raise ManifestError(
+                    f"{route_id}: mcp.tool_name required when mcp.expose is true"
+                )
+            if not description:
+                raise ManifestError(
+                    f"{route_id}: mcp.description required when mcp.expose is true"
+                )
+        return cls(expose=expose, tool_name=tool_name, description=description)
+
+
+@dataclass(frozen=True)
+class PathArg:
+    """A positional argument required by the path (e.g., {quiz_id})."""
+
+    name: str
+    help: str
+
+    @classmethod
+    def from_path_placeholder(cls, name: str, helps: dict) -> "PathArg":
+        return cls(name=name, help=helps.get(name, f"The {name} value."))
+
+
+@dataclass(frozen=True)
+class QueryArg:
+    """An optional query-string argument (e.g., --limit)."""
+
+    name: str
+    help: str
+    default: Optional[str]
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "QueryArg":
+        if not isinstance(raw, dict) or "name" not in raw:
+            raise ManifestError(f"{route_id}: query_args entries need a 'name' key")
+        return cls(
+            name=raw["name"],
+            help=raw.get("help", ""),
+            default=raw.get("default"),
+        )
+
+
+@dataclass(frozen=True)
+class HeaderSpec:
+    """A request header sourced from an environment variable.
+
+    Used by routes whose server-side handler gates on a custom header instead
+    of the Auth0 bearer the CLI normally sends (e.g.
+    ``POST /site/{site}/wrapper/manual-deploy`` checks
+    ``x-manual-deploy-key`` against the ``MANUAL_DEPLOY_SECRET`` env on the
+    Lambda). The value never goes in routes.yaml; it's resolved from the
+    operator's environment at call time so secrets stay out of git.
+
+    If ``required`` is true and the env var is unset, the dispatcher fails
+    fast with a clear message before any network call.
+    """
+
+    name: str
+    env: str
+    help: str = ""
+    required: bool = False
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "HeaderSpec":
+        if not isinstance(raw, dict):
+            raise ManifestError(f"{route_id}: extra_headers entries must be dicts")
+        for required_field in ("name", "env"):
+            if required_field not in raw:
+                raise ManifestError(
+                    f"{route_id}: extra_headers entries need a {required_field!r} key"
+                )
+        return cls(
+            name=raw["name"],
+            env=raw["env"],
+            help=raw.get("help", ""),
+            required=bool(raw.get("required", False)),
+        )
+
+
+@dataclass(frozen=True)
+class BodyArg:
+    """A JSON request-body field (for POST/PUT/PATCH).
+
+    Each ``BodyArg`` becomes a CLI option (``--<name>``); the dispatcher
+    assembles all provided options into a single JSON object posted to the
+    server. The ``required`` flag controls whether absence is a typer error
+    or just an omitted JSON key.
+
+    ``json`` opts into "value is a JSON-encoded string" — required for nested
+    objects / arrays in the body (e.g. a pricing payload that's a list of
+    floor records).
+    """
+
+    name: str
+    help: str
+    required: bool = False
+    json: bool = False
+    raw: bool = False
+    default: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "BodyArg":
+        if not isinstance(raw, dict) or "name" not in raw:
+            raise ManifestError(f"{route_id}: body_args entries need a 'name' key")
+        return cls(
+            name=raw["name"],
+            help=raw.get("help", ""),
+            required=bool(raw.get("required", False)),
+            json=bool(raw.get("json", False)),
+            raw=bool(raw.get("raw", False)),
+            default=raw.get("default"),
+        )
+
+
+@dataclass(frozen=True)
+class Route:
+    id: str
+    path: str
+    method: str
+    cli: CLISpec
+    mcp: MCPSpec
+    risk: str
+    # Which build ships this route. Defaults to `internal` so a route added
+    # without the field never leaks into a customer wheel (DEV-1566).
+    audience: str = audience_mod.INTERNAL
+    path_args: tuple[PathArg, ...] = field(default_factory=tuple)
+    query_args: tuple[QueryArg, ...] = field(default_factory=tuple)
+    body_args: tuple[BodyArg, ...] = field(default_factory=tuple)
+    extra_headers: tuple[HeaderSpec, ...] = field(default_factory=tuple)
+
+    @property
+    def is_mutation(self) -> bool:
+        """True for any non-GET method (the methods the write-gate guards)."""
+        return self.method != "GET"
+
+    @property
+    def is_site_scoped(self) -> bool:
+        return "{site}" in self.path
+
+    @property
+    def extra_path_args(self) -> tuple[PathArg, ...]:
+        """Path args excluding ``site`` (which is handled by the resolver)."""
+        return tuple(a for a in self.path_args if a.name != "site")
+
+    def render_path(self, values: dict[str, str]) -> str:
+        """Substitute ``{var}`` placeholders, URL-encoding each value as a path
+        segment. Missing keys raise ManifestError.
+
+        Path segments are encoded with ``safe=""`` so reserved characters like
+        ``|`` in Auth0 user ids (``auth0|abc``) are percent-escaped. ``.`` and
+        ``-`` are unreserved and pass through unchanged, so site domains like
+        ``foo.com`` are not mangled.
+        """
+        try:
+            encoded = {k: quote(str(v), safe="") for k, v in values.items()}
+            return self.path.format(**encoded)
+        except KeyError as exc:
+            raise ManifestError(
+                f"{self.id}: missing value for path arg {exc} when rendering {self.path}"
+            ) from exc
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "Route":
+        if not isinstance(raw, dict):
+            raise ManifestError(f"route entry must be a dict, got {type(raw).__name__}")
+        try:
+            route_id = raw["id"]
+            path = raw["path"]
+            method = raw["method"].upper()
+        except KeyError as exc:
+            raise ManifestError(f"route missing required key {exc}") from exc
+        if method not in METHODS:
+            raise ManifestError(f"{route_id}: unknown HTTP method {method!r}")
+        risk = raw.get("risk", "read")
+        if risk not in RISK_TIERS:
+            raise ManifestError(
+                f"{route_id}: risk must be one of {sorted(RISK_TIERS)}, got {risk!r}"
+            )
+        # Absent means internal: forgetting the field hides the route from
+        # customers rather than exposing it to them.
+        route_audience = raw.get("audience", audience_mod.INTERNAL)
+        if route_audience not in audience_mod.VALID:
+            raise ManifestError(
+                f"{route_id}: audience must be one of "
+                f"{sorted(audience_mod.VALID)}, got {route_audience!r}"
+            )
+
+        # Extract path args from the path itself; per-arg help text overrides
+        # come from the optional `args:` block in the YAML.
+        path_arg_helps: dict[str, str] = {}
+        for entry in raw.get("args", []) or []:
+            if not isinstance(entry, dict) or "name" not in entry:
+                raise ManifestError(f"{route_id}: args entries need a 'name' key")
+            path_arg_helps[entry["name"]] = entry.get("help", "")
+
+        placeholders = _PATH_PLACEHOLDER.findall(path)
+        path_args = tuple(
+            PathArg.from_path_placeholder(name, path_arg_helps) for name in placeholders
+        )
+
+        query_args = tuple(
+            QueryArg.from_dict(route_id, q) for q in (raw.get("query_args") or [])
+        )
+        body_args = tuple(
+            BodyArg.from_dict(route_id, b) for b in (raw.get("body_args") or [])
+        )
+        if body_args and method == "GET":
+            raise ManifestError(f"{route_id}: GET routes cannot have body_args")
+        raw_args = [b for b in body_args if b.raw]
+        if raw_args and len(body_args) > 1:
+            raise ManifestError(
+                f"{route_id}: a body_arg with raw=true must be the only body_arg "
+                f"(found {[b.name for b in body_args]})"
+            )
+        if raw_args and not raw_args[0].json:
+            raise ManifestError(
+                f"{route_id}: body_arg {raw_args[0].name!r} uses raw=true and "
+                f"must also set json=true so the value is decoded as JSON"
+            )
+
+        extra_headers = tuple(
+            HeaderSpec.from_dict(route_id, h) for h in (raw.get("extra_headers") or [])
+        )
+
+        return cls(
+            id=route_id,
+            path=path,
+            method=method,
+            cli=CLISpec.from_dict(route_id, raw["cli"]),
+            mcp=MCPSpec.from_dict(route_id, raw["mcp"]),
+            risk=risk,
+            audience=route_audience,
+            path_args=path_args,
+            query_args=query_args,
+            body_args=body_args,
+            extra_headers=extra_headers,
+        )
+
+
+def load_manifest(
+    path: Path = DEFAULT_ROUTES_FILE, audience: Optional[str] = None
+) -> list[Route]:
+    """Load + validate the manifest, filtered to this build's audience.
+
+    Validation runs over EVERY entry before filtering, so a malformed
+    internal-only route still fails a customer build's tests rather than
+    silently disappearing.
+
+    Pass `audience` explicitly in tests; production callers let it resolve
+    from the environment or the packaged build marker.
+    """
+    raw = yaml.safe_load(path.read_text())
+    if not isinstance(raw, list):
+        raise ManifestError(
+            f"{path}: top-level must be a YAML list, got {type(raw).__name__}"
+        )
+
+    routes = [Route.from_dict(entry) for entry in raw]
+
+    # Cross-route invariants.
+    ids: set[str] = set()
+    mcp_tool_names: set[str] = set()
+    cli_paths: dict[tuple[str, ...], str] = {}
+    cli_groups: dict[tuple[str, ...], str] = {}
+    for route in routes:
+        if route.id in ids:
+            raise ManifestError(f"duplicate route id: {route.id}")
+        ids.add(route.id)
+        if route.mcp.expose and route.mcp.tool_name in mcp_tool_names:
+            raise ManifestError(
+                f"{route.id}: duplicate MCP tool name {route.mcp.tool_name!r}"
+            )
+        if route.mcp.expose and route.mcp.tool_name:
+            mcp_tool_names.add(route.mcp.tool_name)
+        cli_path = (*route.cli.group, route.cli.command)
+        if cli_path in cli_paths:
+            raise ManifestError(f"{route.id}: duplicate CLI path {' '.join(cli_path)}")
+        cli_paths[cli_path] = route.id
+        for depth in range(1, len(route.cli.group) + 1):
+            cli_groups.setdefault(route.cli.group[:depth], route.id)
+
+    collisions = sorted(cli_paths.keys() & cli_groups.keys())
+    if collisions:
+        collision = collisions[0]
+        raise ManifestError(
+            f"{cli_paths[collision]}: CLI command path {' '.join(collision)!r} "
+            f"is also a command group for {cli_groups[collision]}"
+        )
+
+    resolved = audience or audience_mod.current_audience()
+    return [r for r in routes if audience_mod.route_is_visible(r.audience, resolved)]
+
+
+def extract_app_py_paths(app_py: Path) -> set[tuple[str, str]]:
+    """Parse `app.py` and return the set of `(path, method)` tuples it declares.
+
+    Handles both single-line route decorators and the multi-line form Chalice
+    sometimes uses. Used by ``check_manifest_against_app_py`` for drift detection.
+    """
+    text = app_py.read_text()
+    pairs: set[tuple[str, str]] = set()
+
+    # Match @app.route("PATH", methods=[...]) — both single-line and multi-line.
+    pattern = re.compile(
+        r"@app\.route\(\s*\"([^\"]+)\"\s*,\s*methods=\[([^\]]+)\]",
+        re.MULTILINE,
+    )
+    for m in pattern.finditer(text):
+        path = m.group(1)
+        for method in re.findall(r"\"([A-Z]+)\"", m.group(2)):
+            pairs.add((path, method))
+    return pairs
+
+
+def check_manifest_against_app_py(
+    routes: list[Route], app_py: Path
+) -> tuple[list[str], list[str]]:
+    """Return (manifest_only, app_py_only_routes).
+
+    ``manifest_only`` is the list of manifest entries whose (path, method) does
+    not appear in app.py — these are stale or typo'd entries.
+    ``app_py_only_routes`` is the list of (path, method) pairs in app.py that
+    no manifest entry covers. For v0.3 we expect this list to be long (we
+    haven't manifested every route yet); the check is informational only.
+    """
+    app_pairs = extract_app_py_paths(app_py)
+    manifest_pairs = {(r.path, r.method) for r in routes}
+
+    stale = [
+        f"{r.method} {r.path} (manifest id={r.id})"
+        for r in routes
+        if (r.path, r.method) not in app_pairs
+    ]
+    uncovered = [f"{m} {p}" for p, m in sorted(app_pairs - manifest_pairs)]
+    return stale, uncovered