pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/_helpers.py

@@ -0,0 +1,178 @@
+"""Shared helpers for command files (parse --data, etc.)."""
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Union
+
+import click
+
+from pm.client.base import PMApiError
+
+YES_HELP = "Skip the confirmation prompt. Required when stdin is not a terminal."
+
+
+def json_option(f):
+    """Per-command ``--json`` so both ``pm --json report list`` and
+    ``pm report list --json`` work. The callback flips the same
+    ``ctx.obj['json']`` flag the root option sets; ``expose_value=False``
+    keeps the command signature unchanged."""
+    def _set(ctx, _param, value):
+        if value:
+            ctx.ensure_object(dict)["json"] = True
+        return value
+    return click.option(
+        "--json", is_flag=True, expose_value=False, callback=_set,
+        help="Output JSON.",
+    )(f)
+
+
+LIMIT_HELP = "Maximum number of rows to return (default: all)."
+NAME_FILTER_HELP = "Filter by name (case-insensitive substring)."
+
+# A row field to match ``--name`` against: an attribute/key name, or a
+# callable for nested values (e.g. a saved block's ``block.name``).
+RowField = Union[str, Callable[[Dict[str, Any]], Any]]
+
+
+def limit_option(f):
+    """The one ``--limit N`` every list command uses. N >= 1; omitted means
+    every row the command fetches, so default output is unchanged."""
+    return click.option(
+        "--limit", type=click.IntRange(min=1), default=None, help=LIMIT_HELP,
+    )(f)
+
+
+def name_filter_option(f=None, *, matches: Optional[str] = None):
+    """The one ``--name TEXT`` list filter (same wording as recipient and
+    integration list). Exposed as ``name_filter`` so it never collides with
+    a command's own ``name`` parameter.
+
+    ``matches`` names the fields the filter actually reads when that is more
+    than the name, e.g. ``"email, first or last name"``, so the help says
+    what the flag does. Use bare (``@name_filter_option``) or called
+    (``@name_filter_option(matches=...)``).
+    """
+    help_text = (
+        f"Filter by {matches} (case-insensitive substring)." if matches else NAME_FILTER_HELP
+    )
+
+    def decorate(func):
+        return click.option("--name", "name_filter", default=None, help=help_text)(func)
+
+    return decorate(f) if f is not None else decorate
+
+
+def _row_dict(row: Any) -> Dict[str, Any]:
+    if isinstance(row, dict):
+        return row
+    dump = getattr(row, "model_dump", None)
+    return dump() if callable(dump) else dict(getattr(row, "__dict__", {}))
+
+
+def select_rows(
+    rows: Iterable[Any],
+    *,
+    name: Optional[str] = None,
+    fields: Sequence[RowField] = ("name",),
+    limit: Optional[int] = None,
+) -> List[Any]:
+    """Apply ``--name`` then ``--limit`` to rows a list command fetched.
+
+    Filtering is client-side over the rows already fetched, so it works the
+    same for every resource whatever filters its endpoint supports. A row
+    matches when any of ``fields`` contains ``name`` case-insensitively.
+    Order is preserved; ``limit`` keeps the first N matches.
+    """
+    out = list(rows)
+    if name:
+        needle = name.casefold()
+
+        def _matches(row: Any) -> bool:
+            data = _row_dict(row)
+            for field in fields:
+                value = field(data) if callable(field) else data.get(field)
+                if value is not None and needle in str(value).casefold():
+                    return True
+            return False
+
+        out = [r for r in out if _matches(r)]
+    if limit is not None:
+        out = out[:limit]
+    return out
+
+
+def yes_option(f):
+    """The one ``-y, --yes`` every destructive command uses."""
+    return click.option("--yes", "-y", is_flag=True, help=YES_HELP)(f)
+
+
+def peek_name(fetch: Callable[[], Any], *fields: str) -> Optional[str]:
+    """Best-effort display name for a confirmation prompt: the first
+    non-empty of ``fields`` on the fetched object, or None if the fetch
+    fails (the prompt then shows the uid alone)."""
+    try:
+        obj = fetch()
+    except PMApiError:
+        return None
+    for field in fields:
+        value = getattr(obj, field, None)
+        if value:
+            return str(value)
+    return None
+
+
+def confirm_delete(noun: str, uid: str, name: Optional[str] = None, *, note: str = "") -> None:
+    """``Delete <noun> 'name' (uid)? [y/N]`` — abort on anything but yes."""
+    label = f"{name!r} ({uid})" if name else uid
+    tail = f" {note}" if note else ""
+    click.confirm(f"Delete {noun} {label}?{tail}", abort=True)
+
+
+def report_deleted(ctx: click.Context, noun: str, uid: str) -> None:
+    """Confirmation after a delete: ``{"deleted": uid}`` in JSON mode,
+    else ``Deleted <noun> <uid>.`` on stderr."""
+    if ctx.obj.get("json"):
+        from pm.output import emit
+        emit({"deleted": uid}, json_output=True)
+        return
+    info(ctx, f"Deleted {noun} {uid}.")
+
+
+def info(ctx: click.Context, msg: str) -> None:
+    """Emit an informational message to stderr unless --quiet is set.
+
+    Use for chatty status output ("Login successful.", "Deleted X.") that
+    a human appreciates but a sandboxed subprocess (agent) should not see.
+    Error messages should keep using ``click.ClickException`` so they
+    always surface.
+    """
+    if ctx.obj and ctx.obj.get("quiet"):
+        return
+    click.echo(msg, err=True)
+
+
+def parse_data(data_str: Optional[str]) -> Dict[str, Any]:
+    """Parse a `--data '<json>'` flag into a dict, or return {} if absent.
+
+    Raises ClickException with a useful message on invalid JSON.
+    """
+    if not data_str:
+        return {}
+    try:
+        parsed = json.loads(data_str)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"Invalid --data JSON: {exc}")
+    if not isinstance(parsed, dict):
+        raise click.ClickException("--data must be a JSON object")
+    return parsed
+
+
+def merge_fields(*sources: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge multiple field dicts, later sources override earlier. Drops keys
+    whose values are None so explicit flags only override when provided."""
+    merged: Dict[str, Any] = {}
+    for src in sources:
+        for k, v in src.items():
+            if v is not None:
+                merged[k] = v
+    return merged

pm/commands/auth.py

@@ -0,0 +1,222 @@
+"""login / logout / whoami commands."""
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+import requests
+
+from pm.auth import device_flow, exchange, store
+from pm.auth import token as token_auth
+from pm.auth.session import PMSession
+from pm.client import PMClient
+from pm.client.base import PMApiError
+from pm.commands._helpers import info, json_option
+from pm.output import emit
+
+
+def _read_token(ctx: click.Context) -> str:
+    """Read a PAT from stdin (when piped) or an interactive hidden prompt.
+
+    Reading from stdin / a hidden prompt keeps the token off the argv, where
+    it would otherwise leak into shell history and the process list.
+    """
+    if not sys.stdin.isatty():
+        return sys.stdin.read().strip()
+    return click.prompt("Personal access token (pmpat_...)", hide_input=True).strip()
+
+
+def tokens_page_url(api_url: str) -> str:
+    """The web app page where personal access tokens are created and revoked
+    (frontend route ``/a/tokens``, menu label "Access Tokens")."""
+    return f"{api_url}/a/tokens"
+
+
+def _token_login_failure(exc: token_auth.TokenExchangeError, api_url: str) -> str:
+    """Word a failed PAT exchange for a person: a rate limit is not a bad
+    token."""
+    if exc.status == 429:
+        return (
+            "Too many login attempts from this network address "
+            "(10 per minute). Wait a minute and run `pm login --token` again."
+        )
+    if exc.status is None:
+        # Raised before any HTTP (malformed token, unreachable host): the
+        # message already names the next action.
+        return str(exc)
+    return f"{exc}\nHint: tokens are created and revoked at {tokens_page_url(api_url)}"
+
+
+def _login_with_token(ctx: click.Context, profile) -> None:
+    """Store a Personal Access Token after verifying it via the exchange
+    endpoint. Bypasses the Auth0 device flow entirely."""
+    raw = _read_token(ctx)
+    if not raw:
+        raise click.ClickException(
+            "No token provided. Paste the pmpat_... value at the prompt, or pipe "
+            "it in from your secrets manager. Create one at "
+            f"{tokens_page_url(profile.api_url)}."
+        )
+
+    # Verify before storing so we never persist a dud token.
+    http_session = requests.Session()
+    try:
+        token_auth.exchange_pat_for_jwt(http_session, profile.api_url, raw)
+    except token_auth.TokenExchangeError as exc:
+        raise click.ClickException(_token_login_failure(exc, profile.api_url))
+
+    token_auth.save_token(profile.name, raw)
+    info(ctx, f"Logged in to {profile.api_url} (profile {profile.name!r}).")
+    info(ctx, "Next: `pm whoami`, then `pm report list`.")
+
+
+@click.command(name="login")
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    help="Don't try to open the verification URL automatically.",
+)
+@click.option(
+    "--token",
+    "use_token",
+    is_flag=True,
+    help=(
+        "Authenticate with a personal access token (recommended). The token "
+        "is read from a hidden prompt, or from stdin when piped from your "
+        "secrets manager."
+    ),
+)
+@click.pass_context
+def login(ctx: click.Context, no_browser: bool, use_token: bool) -> None:
+    """Log in with a personal access token.
+
+    pm login --token stores the token for this profile. Without --token the
+    browser login is used, which needs an Auth0 client id on the profile.
+    """
+    profile = ctx.obj["profile"]
+
+    if use_token:
+        _login_with_token(ctx, profile)
+        return
+
+    if not profile.auth0_client_id:
+        raise click.ClickException(
+            f"Browser login is not set up for profile {profile.name!r}. "
+            f"Use a personal access token instead: create one at "
+            f"{tokens_page_url(profile.api_url)}, then run `pm login --token`."
+        )
+
+    info(ctx, f"Logging in (profile: {profile.name}, api: {profile.api_url})")
+
+    try:
+        device_payload = device_flow.request_device_code(
+            domain=profile.auth0_domain,
+            client_id=profile.auth0_client_id,
+            audience=profile.audience,
+        )
+    except device_flow.DeviceFlowError as exc:
+        raise click.ClickException(str(exc))
+
+    info(ctx, "")
+    info(
+        ctx,
+        f"Open this URL on any device:    {device_payload.verification_uri_complete}",
+    )
+    info(ctx, f"Verify it shows the user code:  {device_payload.user_code}")
+    info(ctx, "Waiting for authorization...")
+
+    try:
+        token = device_flow.poll_for_token(
+            domain=profile.auth0_domain,
+            client_id=profile.auth0_client_id,
+            payload=device_payload,
+            no_browser=no_browser,
+        )
+    except device_flow.DeviceFlowError as exc:
+        raise click.ClickException(str(exc))
+
+    http_session = requests.Session()
+    try:
+        result = exchange.exchange_for_session(
+            http_session, profile.api_url, token.access_token
+        )
+    except exchange.LoginError as exc:
+        raise click.ClickException(str(exc))
+
+    creds = store.StoredCredentials(
+        profile=profile.name,
+        api_url=profile.api_url,
+        auth0_refresh_token=token.refresh_token,
+        pm_access_token=result.pm_access_token,
+        pm_refresh_token=result.pm_refresh_token,
+    )
+    creds.set_cookies(http_session.cookies)
+    store.save(creds)
+
+    info(ctx, "Login successful.")
+
+
+@click.command(name="logout")
+@click.pass_context
+def logout(ctx: click.Context) -> None:
+    """Log out and forget the stored token or session."""
+    profile = ctx.obj["profile"]
+
+    creds = store.load(profile.name)
+    if creds is not None:
+        try:
+            # Force cookie mode for the server-side logout: a stored PAT must
+            # not turn this into a Bearer call (there's no session to clear).
+            session = PMSession(profile, creds)
+            # Server-side logout is GET /logout/ (returns a 302 to Auth0's logout).
+            # We don't want to follow the redirect — Flask-Login has already
+            # cleared the session by the time the redirect is built.
+            session.get("/logout/", allow_redirects=False, timeout=10)
+        except Exception:
+            pass
+
+    store.clear(profile.name)
+    token_auth.clear_token(profile.name)
+    info(ctx, f"Logged out of profile {profile.name!r}.")
+    # Env credentials outlive logout: the next command would still
+    # authenticate with them. Always shown (not --quiet chatter).
+    for var in ("PM_API_TOKEN", "PM_API_JWT"):
+        if (os.environ.get(var) or "").strip():
+            click.echo(
+                f"Warning: {var} is set in this shell, so the next command still "
+                f"authenticates. Run: unset {var}",
+                err=True,
+            )
+
+
+@click.command(name="whoami")
+@json_option
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """Show who you are logged in as, and the workspace."""
+    profile = ctx.obj["profile"]
+    json_output = ctx.obj["json"]
+
+    client = PMClient.from_profile(profile)
+
+    user = client.users.current()
+
+    workspace = None
+    try:
+        workspace = client.workspaces.current()
+    except PMApiError:
+        pass
+
+    client.persist()
+
+    payload = {
+        "email": user.email,
+        "first_name": user.first_name,
+        "last_name": user.last_name,
+        "workspace": workspace.name if workspace else None,
+        "workspace_uid": workspace.uid if workspace else None,
+        "profile": profile.name,
+        "api_url": profile.api_url,
+    }
+    emit(payload, json_output=json_output)

pm/commands/block.py

@@ -0,0 +1,26 @@
+"""`pm block` — generic block CRUD plumbing (any type).
+
+This is the canonical CRUD surface for blocks across every type. Domain
+groups (`pm sql`, `pm email`, ...) cover the "create a typed block and
+execute it" lifecycle; `pm block` is what you reach for to list/get/
+update/delete blocks generically. `--type X` is required on `create`,
+`run`, and `send` because the discriminator can't be inferred from the
+group name.
+
+Per plan §3.0 + §3.8 — and codex R3 #4 + R4 #7: `pm block delete` is
+suppressed from `single_tool` agent help at the registry level (the
+backend FK constraints make delete a non-guaranteed op anyway, but the
+real reason is: agents shouldn't be picking blocks to delete).
+"""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+block = make_block_group(
+    "block",
+    None,
+    help_text="Blocks of any type.\n\nThe typed groups (pm sql, pm email, ...) are easier; use this one to list, update or delete across types.",
+    crud_verbs=("get", "list", "create", "update", "delete"),
+    execute_verb="run",
+)

pm/commands/chart.py

@@ -0,0 +1,20 @@
+"""`pm chart` — create + run Plotly chart blocks.
+
+The backend's plotly executor auto-renders the PNG as a side effect of
+block creation — the documented carve-out from plan §3.0's "create
+doesn't execute" rule. `create_has_side_effect=True` only affects the
+generated help text so the agent isn't surprised.
+"""
+from __future__ import annotations
+
+from pm.commands._block_factory import make_block_group
+
+
+chart = make_block_group(
+    "chart",
+    "plotly",
+    help_text="Charts (Plotly blocks).\n\nBlock type: plotly.",
+    crud_verbs=("create", "list", "get", "update"),
+    execute_verb="run",
+    create_has_side_effect=True,
+)