publinker-cli 0.6.2__py3-none-any.whl

publinker_cli/dispatch_cli.py

@@ -0,0 +1,394 @@
+"""Build a Typer command tree from the route manifest.
+
+Given the list of :class:`~publinker_cli.manifest.Route` records, this module
+materializes Typer ``Typer`` apps for each ``cli.group`` prefix and registers
+one command per route. The body of each generated command is a thin wrapper
+that:
+
+  1. Resolves the active site (when the route is site-scoped) via
+     :mod:`publinker_cli.state`.
+  2. Renders the API path with ``Route.render_path``.
+  3. Calls :class:`PublinkerClient` with the right method + query params.
+  4. Pretty-prints the response (or raw JSON if ``--json`` is passed).
+
+Why a single generic command body: every read-only route has the same shape
+(path args + query params + stage + json toggle). One handler keeps the
+generated tree predictable and the failure mode the same everywhere.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json as _json
+import os
+from typing import Any, Callable, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from publinker_cli import state, write_gate
+from publinker_cli.client import APIError, NotAuthenticatedError, PublinkerClient
+from publinker_cli.config import available_stages
+from publinker_cli.manifest import Route
+
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Command body — the generic execution path every route shares
+# ---------------------------------------------------------------------------
+
+
+def _execute_route(route: Route, params: dict[str, Any]) -> None:
+    """Run one manifest-defined route. Called from each generated Typer command."""
+    stage = params.pop("stage", None)
+    json_out = params.pop("json_out", False)
+    explicit_site = params.pop("site", None) if route.is_site_scoped else None
+
+    # Gate mutations before doing any work — the user shouldn't get to "site
+    # missing" before "writes blocked". Reads bypass the gate entirely.
+    if route.is_mutation and not write_gate.is_allowed():
+        gate = write_gate.status()
+        console.print(
+            f"[red]Writes BLOCKED[/red] — {gate.reason}.\n"
+            f"Prefix one reviewed command with "
+            f"[cyan]{write_gate.ENV_VAR}=1[/cyan]; don't export it."
+        )
+        raise typer.Exit(code=2)
+
+    # A prod-only (customer) build has nothing to disambiguate.
+    if route.is_mutation and not stage and len(available_stages()) > 1:
+        console.print("[red]mutations require an explicit --stage[/red]")
+        raise typer.Exit(code=2)
+    stage = stage or "prod"
+
+    if route.is_mutation and route.is_site_scoped and not explicit_site:
+        console.print("[red]site-scoped mutations require an explicit --site[/red]")
+        raise typer.Exit(code=2)
+
+    path_values: dict[str, str] = {}
+    if route.is_site_scoped:
+        try:
+            path_values["site"] = state.resolve_site(explicit_site)
+        except state.NoSiteSelectedError as exc:
+            console.print(f"[red]{exc}[/red]")
+            raise typer.Exit(code=2)
+
+    for arg in route.extra_path_args:
+        value = params.pop(arg.name, None)
+        if value is None:
+            console.print(f"[red]missing argument: {arg.name}[/red]")
+            raise typer.Exit(code=2)
+        path_values[arg.name] = str(value)
+
+    query_params: dict[str, str] = {}
+    for q in route.query_args:
+        value = params.pop(q.name, None)
+        if value is not None:
+            query_params[q.name] = str(value)
+
+    body = _build_body(route, params)
+    extra_headers = _build_extra_headers(route)
+
+    path = route.render_path(path_values)
+
+    try:
+        client = PublinkerClient(stage=stage)
+        request_kwargs: dict[str, Any] = {}
+        if query_params:
+            request_kwargs["params"] = query_params
+        if body is not None:
+            request_kwargs["json"] = body
+        if extra_headers:
+            request_kwargs["headers"] = extra_headers
+        response = client.request(route.method, path, **request_kwargs)
+    except NotAuthenticatedError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+    except (APIError, ValueError) as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+
+    if json_out:
+        typer.echo(_json.dumps(response, separators=(",", ":"), default=str))
+    else:
+        _pretty_print(route, response)
+
+
+def _build_extra_headers(route: Route) -> dict[str, str]:
+    """Resolve route.extra_headers values from the environment.
+
+    Headers are intentionally never sourced from the manifest itself —
+    routes that need a secret (e.g. ``x-manual-deploy-key``) pull from the
+    caller's env so the value stays out of git. Missing-but-required
+    headers fail fast with a clear message before any network call.
+    """
+    if not route.extra_headers:
+        return {}
+
+    resolved: dict[str, str] = {}
+    missing: list[str] = []
+    for h in route.extra_headers:
+        value = os.environ.get(h.env)
+        if value:
+            resolved[h.name] = value
+        elif h.required:
+            missing.append(h.env)
+
+    if missing:
+        flags = ", ".join(missing)
+        console.print(
+            f"[red]missing required env var(s) for request headers: {flags}.[/red]\n"
+            f"Set them in your shell, then retry. See "
+            f"`publinker site wrapper manual-deploy --help` for context."
+        )
+        raise typer.Exit(code=2)
+
+    return resolved
+
+
+def _build_body(route: Route, params: dict[str, Any]) -> Any:
+    """Assemble the JSON body from ``body_args`` values passed on the CLI.
+
+    Returns ``None`` when the route has no body args (or none were provided
+    and none were required), so ``requests`` doesn't send a body at all.
+    Validates required fields and decodes ``json=true`` args.
+
+    Special-case: a single body arg with ``raw=true`` is the *whole* payload
+    rather than a field inside it — used by routes whose server-side handler
+    accepts a freeform shape (e.g. ``put_pricing``: ``--body '[...floors]'``).
+    Manifest validation guarantees ``raw=true`` implies ``json=true`` and
+    that it's the only body arg.
+    """
+    if not route.body_args:
+        return None
+
+    if len(route.body_args) == 1 and route.body_args[0].raw:
+        b = route.body_args[0]
+        value = params.pop(b.name, None)
+        if value is None:
+            if b.required:
+                console.print(
+                    f"[red]missing required body: --{b.name.replace('_', '-')}[/red]"
+                )
+                raise typer.Exit(code=2)
+            return None
+        try:
+            return _json.loads(value)
+        except _json.JSONDecodeError as exc:
+            console.print(
+                f"[red]--{b.name.replace('_', '-')}: not valid JSON: "
+                f"{exc.msg}[/red]"
+            )
+            raise typer.Exit(code=2)
+
+    body: dict[str, Any] = {}
+    missing: list[str] = []
+    for b in route.body_args:
+        value = params.pop(b.name, None)
+        if value is None:
+            if b.required:
+                missing.append(b.name)
+            continue
+        if b.json:
+            try:
+                body[b.name] = _json.loads(value)
+            except _json.JSONDecodeError as exc:
+                console.print(
+                    f"[red]--{b.name.replace('_', '-')}: not valid JSON: "
+                    f"{exc.msg}[/red]"
+                )
+                raise typer.Exit(code=2)
+        else:
+            body[b.name] = value
+
+    if missing:
+        flags = ", ".join(f"--{m.replace('_', '-')}" for m in missing)
+        console.print(f"[red]missing required body args: {flags}[/red]")
+        raise typer.Exit(code=2)
+
+    return body if body else None
+
+
+def _pretty_print(route: Route, response: Any) -> None:
+    """Best-effort tabular rendering with a JSON fallback.
+
+    The publinker API returns wildly varied shapes — lists of strings, dicts
+    keyed by id, deeply nested reports. Rather than maintain a per-route
+    formatter (which is exactly what the manifest is trying to avoid), we
+    pick the obvious shape and fall back to indented JSON for everything else.
+    """
+    title = f"{route.id} — {route.method} {route.path}"
+
+    if isinstance(response, list) and all(isinstance(item, str) for item in response):
+        _print_string_list(title, response)
+        return
+
+    if isinstance(response, dict):
+        for key in ("sites", "companyIds", "items", "data"):
+            inner = response.get(key)
+            if isinstance(inner, list) and all(isinstance(i, str) for i in inner):
+                _print_string_list(f"{title} — {key}", inner)
+                return
+
+    typer.echo(_json.dumps(response, indent=2, default=str))
+
+
+def _print_string_list(title: str, items: list[str]) -> None:
+    table = Table(title=f"{title} ({len(items)})", show_lines=False)
+    table.add_column("#", style="dim", width=4, justify="right")
+    table.add_column("value", style="cyan")
+    for i, item in enumerate(items, start=1):
+        table.add_row(str(i), item)
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# Command factory — builds a Typer-compatible callback per route
+# ---------------------------------------------------------------------------
+
+
+def _make_callback(route: Route) -> Callable[..., None]:
+    """Create a callback with a Typer-discoverable signature for one route.
+
+    Typer reads ``inspect.signature(callback)`` and turns each parameter's
+    default (a ``typer.Argument`` or ``typer.Option`` instance) into a CLI
+    arg/option. We build that signature programmatically from the route.
+    """
+    params: list[inspect.Parameter] = []
+
+    for arg in route.extra_path_args:
+        params.append(
+            inspect.Parameter(
+                arg.name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Argument(..., help=arg.help),
+                annotation=str,
+            )
+        )
+
+    if route.is_site_scoped:
+        params.append(
+            inspect.Parameter(
+                "site",
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Option(
+                    None,
+                    "--site",
+                    help="Override the active site for this call only.",
+                ),
+                annotation=Optional[str],
+            )
+        )
+
+    for q in route.query_args:
+        params.append(
+            inspect.Parameter(
+                q.name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Option(
+                    q.default,
+                    f"--{q.name.replace('_', '-')}",
+                    help=q.help or f"Query parameter '{q.name}'.",
+                ),
+                annotation=Optional[str],
+            )
+        )
+
+    for b in route.body_args:
+        help_text = b.help or f"Body field '{b.name}'."
+        if b.json:
+            help_text = f"{help_text} (JSON-encoded value)"
+        params.append(
+            inspect.Parameter(
+                b.name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Option(
+                    b.default,
+                    f"--{b.name.replace('_', '-')}",
+                    help=help_text,
+                ),
+                annotation=Optional[str],
+            )
+        )
+
+    params.append(
+        inspect.Parameter(
+            "stage",
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=typer.Option(
+                None if route.is_mutation else "prod",
+                "--stage",
+                "-s",
+                help=(
+                    f"API stage: {' | '.join(available_stages())}. "
+                    "Required for mutations when more than one stage exists; "
+                    "reads default to prod."
+                ),
+            ),
+            annotation=Optional[str],
+        )
+    )
+    params.append(
+        inspect.Parameter(
+            "json_out",
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=typer.Option(
+                False, "--json", help="Print raw JSON instead of a table."
+            ),
+            annotation=bool,
+        )
+    )
+
+    def callback(**kwargs: Any) -> None:
+        _execute_route(route, dict(kwargs))
+
+    callback.__signature__ = inspect.Signature(parameters=params)  # type: ignore[attr-defined]
+    callback.__name__ = route.cli.command.replace("-", "_") or route.id
+    callback.__doc__ = (
+        route.mcp.description.strip()
+        or f"{route.method} {route.path} (route id: {route.id})"
+    )
+    return callback
+
+
+# ---------------------------------------------------------------------------
+# Tree assembly
+# ---------------------------------------------------------------------------
+
+
+def register_routes(
+    root: typer.Typer, routes: list[Route]
+) -> dict[tuple[str, ...], typer.Typer]:
+    """Attach every manifest route as a command under ``root``.
+
+    Groups are materialized lazily: the first route with ``cli.group == ("site",
+    "pricing")`` creates ``publinker site pricing`` as a Typer sub-app; later
+    routes in the same group reuse it. Top-level routes (``cli.group == ()``)
+    attach directly to ``root``.
+
+    Returns the group registry so the caller can hang hand-written commands
+    off existing groups (e.g. ``site report list-options``).
+    """
+    group_registry: dict[tuple[str, ...], typer.Typer] = {(): root}
+
+    def _ensure_group(group: tuple[str, ...]) -> typer.Typer:
+        if group in group_registry:
+            return group_registry[group]
+        parent = _ensure_group(group[:-1])
+        sub = typer.Typer(
+            no_args_is_help=True,
+            help=f"`publinker {' '.join(group)}` commands.",
+        )
+        parent.add_typer(sub, name=group[-1])
+        group_registry[group] = sub
+        return sub
+
+    for route in routes:
+        target = _ensure_group(route.cli.group)
+        callback = _make_callback(route)
+        help_text = route.mcp.description or f"{route.method} {route.path}"
+        target.command(route.cli.command, help=help_text)(callback)
+
+    return group_registry

publinker_cli/keyring_store.py

@@ -0,0 +1,109 @@
+"""Cross-platform OS-vault token storage via `keyring`.
+
+macOS  → Keychain
+Linux  → secret-service (GNOME Keyring, KWallet)
+Windows → Credential Manager
+
+No usable vault (slim Linux, Docker, SSH without D-Bus) → a plain JSON file
+next to state.json, mode 0600, the same trade-off as ~/.aws/credentials.
+
+The whole token bundle (access + refresh + id + expires_at) is stored as a single
+JSON blob under one keyring item. One read/write per operation, simpler than
+splitting across three items.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional
+
+import keyring
+
+from publinker_cli import state
+from publinker_cli.config import KEYRING_ACCOUNT, KEYRING_SERVICE
+
+
+@dataclass
+class TokenBundle:
+    access_token: str
+    refresh_token: str
+    id_token: str
+    expires_at: int  # unix epoch seconds
+
+    @classmethod
+    def from_token_response(
+        cls, body: dict, now: Optional[int] = None
+    ) -> "TokenBundle":
+        """Build a bundle from Auth0's `/oauth/token` response."""
+        now = now if now is not None else int(time.time())
+        return cls(
+            access_token=body["access_token"],
+            refresh_token=body.get("refresh_token", ""),
+            id_token=body.get("id_token", ""),
+            expires_at=now + int(body.get("expires_in", 0)),
+        )
+
+    def is_expired(self, now: Optional[int] = None, leeway: int = 60) -> bool:
+        """True if the access token has expired (with `leeway` seconds buffer)."""
+        now = now if now is not None else int(time.time())
+        return now + leeway >= self.expires_at
+
+
+def _token_file() -> Path:
+    return state._state_path().parent / f"{KEYRING_SERVICE}-token.json"
+
+
+def _warn_file_fallback() -> None:
+    print(
+        f"publinker: no OS keyring available; token kept in {_token_file()} (0600)",
+        file=sys.stderr,
+    )
+
+
+def save(bundle: TokenBundle) -> None:
+    raw = json.dumps(asdict(bundle))
+    try:
+        keyring.set_password(KEYRING_SERVICE, KEYRING_ACCOUNT, raw)
+        return
+    except Exception:  # KeyringError, or a backend error such as pywintypes.error
+        _warn_file_fallback()
+    path = _token_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Created 0600 rather than chmod-ed after, so it is never world-readable.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    if hasattr(os, "fchmod"):  # absent on Windows before Python 3.13
+        os.fchmod(fd, 0o600)  # the mode above only applies when the file is new
+    with os.fdopen(fd, "w") as f:
+        f.write(raw)
+
+
+def load() -> Optional[TokenBundle]:
+    try:
+        raw = keyring.get_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+    except Exception:  # see save()
+        raw = None
+    if not raw:
+        try:
+            raw = _token_file().read_text()
+        except OSError:
+            return None
+    try:
+        data = json.loads(raw)
+        return TokenBundle(**data)
+    except (json.JSONDecodeError, TypeError, KeyError):
+        # Corrupted entry — treat as logged out. The next login will overwrite it.
+        return None
+
+
+def clear() -> None:
+    try:
+        keyring.delete_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+    except Exception:
+        # Already absent (PasswordDeleteError) or no vault — the desired state.
+        pass
+    _token_file().unlink(missing_ok=True)