lekha-poth-cli 2.1.0__py3-none-any.whl

lekha_poth_cli/__init__.py

@@ -0,0 +1,6 @@
+"""Lekha Poth production CLI (Typer + Pydantic)."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+__version__ = "2.1.0"

lekha_poth_cli/__main__.py

@@ -0,0 +1,4 @@
+from lekha_poth_cli.app import main
+
+if __name__ == "__main__":
+    main()

lekha_poth_cli/app.py

@@ -0,0 +1,287 @@
+"""Typer application: `lp`."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from lekha_poth_cli import __version__
+from lekha_poth_cli.client import ApiClient
+from lekha_poth_cli.config import (
+    LpConfig,
+    OutputFormat,
+    apply_overrides,
+    default_config_path,
+    load_config,
+    save_config,
+    stamp_created,
+)
+from lekha_poth_cli.errors import ApiError, ConfigError, LpError, NetworkError
+from lekha_poth_cli.media import upload_file
+from lekha_poth_cli.output import emit_data, emit_response, err_console
+from lekha_poth_cli.register import CTX_CONFIG, CTX_OUTPUT, load_endpoints, register_all
+
+app = typer.Typer(
+    name="lp",
+    help="Lekha Poth production CLI — every public and admin HTTP endpoint.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+)
+
+config_app = typer.Typer(help="Persistent configuration (~/.config/lekha-poth/config.json).")
+app.add_typer(config_app, name="config")
+
+api_app = typer.Typer(help="Raw HTTP escape hatch.")
+app.add_typer(api_app, name="api")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    api_base: Optional[str] = typer.Option(None, "--api-base", envvar="LEKHA_POTH_API_BASE"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="LEKHA_POTH_API_KEY"),
+    timeout: Optional[float] = typer.Option(None, "--timeout"),
+    output: Optional[OutputFormat] = typer.Option(None, "--output", "-o"),
+    version: bool = typer.Option(False, "--version", callback=_version_callback, is_eager=True),
+) -> None:
+    cfg = apply_overrides(load_config(), api_base=api_base, api_key=api_key, timeout=timeout, output=output)
+    ctx.ensure_object(dict)
+    ctx.obj[CTX_CONFIG] = cfg
+    ctx.obj[CTX_OUTPUT] = output or cfg.output
+
+
+@config_app.command("show")
+def config_show(ctx: typer.Context, reveal: bool = typer.Option(False, "--reveal")) -> None:
+    cfg: LpConfig = ctx.obj[CTX_CONFIG]
+    data = cfg.model_dump() if reveal else cfg.masked()
+    data["config_path"] = str(default_config_path())
+    emit_data(data, ctx.obj[CTX_OUTPUT])
+
+
+@config_app.command("path")
+def config_path() -> None:
+    typer.echo(str(default_config_path()))
+
+
+@config_app.command("set")
+def config_set(
+    ctx: typer.Context,
+    api_base: Optional[str] = typer.Option(None, "--api-base"),
+    site_url: Optional[str] = typer.Option(None, "--site-url"),
+    api_key: Optional[str] = typer.Option(None, "--api-key"),
+    key_name: Optional[str] = typer.Option(None, "--key-name"),
+    access_token: Optional[str] = typer.Option(None, "--access-token"),
+    refresh_token: Optional[str] = typer.Option(None, "--refresh-token"),
+    timeout: Optional[float] = typer.Option(None, "--timeout"),
+    user_agent: Optional[str] = typer.Option(None, "--user-agent"),
+) -> None:
+    """Save connection credentials. Does not wipe output defaults."""
+    cfg = load_config()
+    data = cfg.model_dump()
+    mapping = {
+        "api_base": api_base,
+        "site_url": site_url,
+        "api_key": api_key,
+        "key_name": key_name,
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "timeout": timeout,
+        "user_agent": user_agent,
+    }
+    changed = False
+    for key, value in mapping.items():
+        if value is not None:
+            data[key] = value
+            changed = True
+    if not changed:
+        raise ConfigError("Pass at least one flag to `lp config set`.")
+    saved = stamp_created(LpConfig.model_validate(data))
+    path = save_config(saved)
+    emit_data({"ok": True, "path": str(path), **saved.masked()}, ctx.obj[CTX_OUTPUT])
+
+
+@config_app.command("set-defaults")
+def config_set_defaults(
+    ctx: typer.Context,
+    output: Optional[OutputFormat] = typer.Option(None, "--output"),
+    default_size: Optional[int] = typer.Option(None, "--default-size", min=1, max=100),
+    timeout: Optional[float] = typer.Option(None, "--timeout"),
+) -> None:
+    """Save preferences without overwriting API keys."""
+    cfg = load_config()
+    data = cfg.model_dump()
+    if output is not None:
+        data["output"] = output
+    if default_size is not None:
+        data["default_size"] = default_size
+    if timeout is not None:
+        data["timeout"] = timeout
+    saved = LpConfig.model_validate(data)
+    path = save_config(saved)
+    emit_data({"ok": True, "path": str(path), **saved.masked()}, ctx.obj[CTX_OUTPUT])
+
+
+@config_app.command("clear-tokens")
+def config_clear_tokens(ctx: typer.Context) -> None:
+    cfg = load_config()
+    saved = cfg.model_copy(update={"access_token": None, "refresh_token": None})
+    save_config(saved)
+    emit_data({"ok": True}, ctx.obj[CTX_OUTPUT])
+
+
+@app.command("status")
+def status_cmd(ctx: typer.Context) -> None:
+    """GET /health + /ready + optional /me."""
+    cfg: LpConfig = ctx.obj[CTX_CONFIG]
+    out: dict = {}
+    with ApiClient(cfg) as client:
+        try:
+            out["health"] = client.request("GET", "/health", mount="root").json()
+        except (ApiError, NetworkError) as exc:
+            out["health"] = {"error": exc.format()}
+        try:
+            out["ready"] = client.request("GET", "/ready", mount="root").json()
+        except (ApiError, NetworkError) as exc:
+            out["ready"] = {"error": exc.format()}
+        if cfg.api_key or cfg.access_token:
+            try:
+                out["me"] = client.request("GET", "/me", mount="v1", auth_required=True).json()
+            except (ApiError, NetworkError) as exc:
+                out["me"] = {"error": exc.format()}
+        else:
+            out["me"] = None
+    emit_data(out, ctx.obj[CTX_OUTPUT])
+
+
+@app.command("whoami")
+def whoami_cmd(ctx: typer.Context) -> None:
+    cfg: LpConfig = ctx.obj[CTX_CONFIG]
+    with ApiClient(cfg) as client:
+        emit_response(client.request("GET", "/me", mount="v1", auth_required=True), ctx.obj[CTX_OUTPUT])
+
+
+@app.command("endpoints")
+def endpoints_cmd(
+    ctx: typer.Context,
+    deprecated: bool = typer.Option(False, "--deprecated", help="Only deprecated aliases"),
+    admin: bool = typer.Option(False, "--admin"),
+) -> None:
+    """List every bound HTTP route."""
+    rows = []
+    for ep in load_endpoints():
+        if deprecated and not ep.deprecated:
+            continue
+        if admin and not (ep.path.startswith("/admin") or ep.group[:1] == ["admin"]):
+            continue
+        rows.append(
+            {
+                "id": ep.id,
+                "cli": " ".join(["lp", *ep.group, ep.name]),
+                "method": ep.method,
+                "path": ep.path,
+                "deprecated": ep.deprecated,
+                "auth": ep.auth,
+            }
+        )
+    emit_data({"count": len(rows), "endpoints": rows}, ctx.obj[CTX_OUTPUT])
+
+
+@api_app.command("request")
+def api_request(
+    ctx: typer.Context,
+    method: str = typer.Argument(...),
+    path: str = typer.Argument(..., help="Path under /api/v1, or absolute URL. Use --root for /health."),
+    root: bool = typer.Option(False, "--root", help="Call API origin (health/ready), not /api/v1."),
+    param: list[str] = typer.Option([], "--param", help="query key=value (repeatable)"),
+    header: list[str] = typer.Option([], "--header", help="Header Name: value"),
+    json_body: Optional[str] = typer.Option(None, "--json-body"),
+    body_file: Optional[Path] = typer.Option(None, "--body-file"),
+) -> None:
+    """Call any path. Example: lp api request GET /items --param size=5"""
+    cfg: LpConfig = ctx.obj[CTX_CONFIG]
+    params = {}
+    for item in param:
+        if "=" not in item:
+            raise LpError(f"Bad --param {item!r}; expected key=value")
+        k, v = item.split("=", 1)
+        params[k] = v
+    headers = {}
+    for item in header:
+        name, _, value = item.partition(":")
+        headers[name.strip()] = value.strip()
+    body = None
+    try:
+        if json_body:
+            body = json.loads(json_body)
+        elif body_file:
+            body = json.loads(body_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LpError(f"Body is not valid JSON: {exc}") from exc
+    with ApiClient(cfg) as client:
+        emit_response(
+            client.request(
+                method,
+                path,
+                mount="root" if root else "v1",
+                params=params or None,
+                json_body=body,
+                headers=headers or None,
+            ),
+            ctx.obj[CTX_OUTPUT],
+        )
+
+
+media_app = typer.Typer(help="Staff media helpers (initiate + PUT + complete).")
+# Nested under admin after register? We'll attach at admin.media.upload-file via extra typer.
+# Register generated commands first, then add helper onto the same tree.
+
+_ENDPOINTS = register_all(app)
+
+
+@app.command("upload")
+def upload_cmd(
+    ctx: typer.Context,
+    file: Path = typer.Argument(..., exists=True, readable=True, dir_okay=False),
+    mime_type: Optional[str] = typer.Option(None, "--mime-type"),
+    visibility: str = typer.Option("private", "--visibility"),
+    role: str = typer.Option("original", "--role"),
+    item_id: Optional[str] = typer.Option(None, "--item-id"),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Poll until ready/failed."),
+) -> None:
+    """Staff convenience: POST /admin/media/uploads → PUT bytes → complete → optional poll."""
+    cfg: LpConfig = ctx.obj[CTX_CONFIG]
+    result = upload_file(
+        cfg,
+        file,
+        mime_type=mime_type,
+        visibility=visibility,
+        role=role,
+        item_id=item_id,
+        wait=wait,
+    )
+    emit_data(result, ctx.obj[CTX_OUTPUT])
+
+
+def main() -> None:
+    """Console entry point.
+
+    Errors are turned into an exit code here, with ``sys.exit`` rather than
+    ``typer.Exit``: this runs *outside* Typer's dispatch loop, so a raised
+    ``typer.Exit`` is an uncaught exception that prints a traceback and exits 1
+    whatever code it carried. stderr gets exactly one line.
+    """
+    try:
+        app()
+    except LpError as exc:
+        err_console.print(exc.format(), markup=False, highlight=False, soft_wrap=True)
+        sys.exit(exc.exit_code)

lekha_poth_cli/client.py

@@ -0,0 +1,149 @@
+"""HTTP client. Always sends a browser-like User-Agent (Cloudflare 403s default urllib)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from lekha_poth_cli.config import LpConfig
+from lekha_poth_cli.errors import ApiError, ConfigError, NetworkError
+
+
+class ApiClient:
+    def __init__(self, cfg: LpConfig) -> None:
+        self.cfg = cfg
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": cfg.user_agent,
+        }
+        token = cfg.api_key or cfg.access_token
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._client = httpx.Client(
+            timeout=cfg.timeout,
+            headers=headers,
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def url(self, path: str, *, mount: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        if not path.startswith("/"):
+            path = "/" + path
+        if mount == "root":
+            return self.cfg.origin() + path
+        # v1
+        return self.cfg.api_base + path
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        mount: str = "v1",
+        params: dict[str, Any] | None = None,
+        json_body: Any = None,
+        headers: dict[str, str] | None = None,
+        stream: bool = False,
+        auth_required: bool = False,
+    ) -> httpx.Response:
+        if auth_required and not (self.cfg.api_key or self.cfg.access_token):
+            raise ConfigError(
+                "This command needs a Bearer token. Run `lp config set --api-key lpak_…` "
+                "or `lp auth login`."
+            )
+        if mount == "v1" and not self.cfg.api_base:
+            raise ConfigError(
+                "API base is not configured. Set LEKHA_POTH_API_BASE or run "
+                "`lp config set --api-base https://api.example.com/api/v1` "
+                "(must end in /api/v1)."
+            )
+        if mount == "root" and not self.cfg.origin():
+            raise ConfigError(
+                "API base is not configured. Set LEKHA_POTH_API_BASE or run "
+                "`lp config set --api-base https://api.example.com/api/v1`."
+            )
+        url = self.url(path, mount=mount)
+        clean_params = _clean_params(params or {})
+        extra = dict(headers or {})
+        kwargs: dict[str, Any] = {
+            "method": method.upper(),
+            "url": url,
+            "params": clean_params or None,
+            "headers": extra or None,
+        }
+        if json_body is not None:
+            kwargs["json"] = json_body
+            extra.setdefault("Content-Type", "application/json")
+            kwargs["headers"] = extra
+        try:
+            if stream:
+                return self._client.send(self._client.build_request(**kwargs), stream=True)
+            response = self._client.request(**kwargs)
+        except httpx.TransportError as exc:
+            raise NetworkError(f"{type(exc).__name__}: {exc} ({method.upper()} {url})") from exc
+        return self._raise_for_api(response)
+
+    def _raise_for_api(self, response: httpx.Response) -> httpx.Response:
+        if response.status_code < 400:
+            return response
+        body: Any
+        try:
+            body = response.json()
+        except json.JSONDecodeError:
+            body = response.text
+        code = None
+        message = None
+        request_id = None
+        details = None
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, dict):
+                code = err.get("code")
+                message = err.get("message")
+                request_id = err.get("request_id") or err.get("requestId")
+                details = err.get("details")
+            else:
+                message = body.get("message") or body.get("detail")
+            request_id = request_id or response.headers.get("x-request-id")
+        if not message:
+            message = f"HTTP {response.status_code} {response.reason_phrase}"
+        raise ApiError(
+            str(message),
+            status_code=response.status_code,
+            code=str(code) if code else None,
+            request_id=str(request_id) if request_id else None,
+            details=details,
+            body=body,
+        )
+
+
+def encode_path_param(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+def _clean_params(params: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            # FastAPI list query: repeat key
+            out[key] = [str(v) for v in value if v is not None]
+        else:
+            out[key] = value
+    return out

lekha_poth_cli/config.py

@@ -0,0 +1,145 @@
+"""Persistent configuration (Pydantic). Compatible with existing ~/.config/lekha-poth/config.json."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal, Self
+
+from pydantic import BaseModel, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from lekha_poth_cli.errors import ConfigError
+
+# No compiled-in production host. Point the CLI at a deploy with
+# `lp config set --api-base … --site-url …` or LEKHA_POTH_API_BASE / _SITE_URL.
+DEFAULT_SITE_URL = ""
+DEFAULT_API_BASE = ""
+DEFAULT_USER_AGENT = "lekha-poth-cli/2.0"
+CONFIG_DIR = Path.home() / ".config" / "lekha-poth"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+OutputFormat = Literal["pretty", "json", "raw"]
+
+
+def default_config_path() -> Path:
+    override = os.environ.get("LEKHA_POTH_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    return CONFIG_PATH
+
+
+class LpConfig(BaseModel):
+    """On-disk config. Secrets live here (mode 0600); never in skills or memory."""
+
+    api_base: str = DEFAULT_API_BASE
+    site_url: str = DEFAULT_SITE_URL
+    api_key: str | None = None
+    key_name: str | None = None
+    created_at: str | None = None
+    access_token: str | None = None
+    refresh_token: str | None = None
+    timeout: float = 30.0
+    output: OutputFormat = "pretty"
+    user_agent: str = DEFAULT_USER_AGENT
+    default_size: int = Field(default=20, ge=1, le=100)
+
+    @field_validator("api_base", "site_url")
+    @classmethod
+    def _strip_slash(cls, value: str) -> str:
+        return value.rstrip("/")
+
+    def origin(self) -> str:
+        """API host without ``/api/v1`` (health/ready live here)."""
+        base = self.api_base
+        for suffix in ("/api/v1", "/api"):
+            if base.endswith(suffix):
+                return base[: -len(suffix)]
+        return base
+
+    def masked(self) -> dict[str, Any]:
+        data = self.model_dump()
+        for key in ("api_key", "access_token", "refresh_token"):
+            val = data.get(key)
+            if isinstance(val, str) and val:
+                data[key] = val[:4] + "…" + f"({len(val)} chars)"
+            else:
+                data[key] = None
+        return data
+
+
+class RuntimeSettings(BaseSettings):
+    """Env overlay. File values are the base; env wins; CLI flags win last."""
+
+    model_config = SettingsConfigDict(env_prefix="LEKHA_POTH_", extra="ignore")
+
+    api_base: str | None = None
+    site_url: str | None = None
+    api_key: str | None = None
+    timeout: float | None = None
+    output: OutputFormat | None = None
+    user_agent: str | None = None
+
+
+def load_config(path: Path | None = None) -> LpConfig:
+    path = path or default_config_path()
+    if not path.is_file():
+        env = RuntimeSettings()
+        return _merge(LpConfig(), env)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ConfigError(f"{path} must contain a JSON object")
+    cfg = LpConfig.model_validate(raw)
+    return _merge(cfg, RuntimeSettings())
+
+
+def _merge(cfg: LpConfig, env: RuntimeSettings) -> LpConfig:
+    updates: dict[str, Any] = {}
+    for field in ("api_base", "site_url", "api_key", "timeout", "output", "user_agent"):
+        value = getattr(env, field)
+        if value is not None:
+            updates[field] = value
+    return cfg.model_copy(update=updates) if updates else cfg
+
+
+def save_config(cfg: LpConfig, path: Path | None = None) -> Path:
+    path = path or default_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = cfg.model_dump()
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    tmp.replace(path)
+    os.chmod(path, 0o600)
+    return path
+
+
+def apply_overrides(
+    cfg: LpConfig,
+    *,
+    api_base: str | None = None,
+    api_key: str | None = None,
+    timeout: float | None = None,
+    output: OutputFormat | None = None,
+) -> LpConfig:
+    data = cfg.model_dump()
+    if api_base is not None:
+        data["api_base"] = api_base.rstrip("/")
+    if api_key is not None:
+        data["api_key"] = api_key
+    if timeout is not None:
+        data["timeout"] = timeout
+    if output is not None:
+        data["output"] = output
+    return LpConfig.model_validate(data)
+
+
+def stamp_created(cfg: LpConfig) -> LpConfig:
+    if cfg.created_at:
+        return cfg
+    now = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+    return cfg.model_copy(update={"created_at": now})