pipefy-cli 0.3.0a1__py3-none-any.whl

pipefy_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Typer CLI entry surface for Pipefy (pipefy)."""
+
+from __future__ import annotations
+
+__version__ = "0.3.0-alpha.1"
+
+__all__ = ["__version__"]

pipefy_cli/_docs.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+DOCS_CLI_AUTH_REF = "docs/cli/auth.md"

pipefy_cli/auth.py

@@ -0,0 +1,225 @@
+"""Build an authenticated :class:`PipefyClient` from CLI configuration.
+
+The precedence chain lives in :func:`pipefy_auth.resolve_pipefy_auth`; this
+module collapses the CLI's two static-token surfaces (``--token`` flag and
+``PIPEFY_TOKEN`` env var) into a single value before calling the resolver, and
+translates resolver failures into Typer exits. The flag-vs-env distinction
+survives only as a diagnostic label for ``pipefy auth status``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any, Final, Literal, assert_never
+
+import typer
+from pipefy_auth import (
+    OidcClient,
+    RefreshError,
+    ResolvedAuth,
+    ServiceAccount,
+    ServiceAccountAuth,
+    StaticTokenAuth,
+    StoredSessionAuth,
+    build_httpx_auth,
+    detect_pipefy_auth_methods,
+    ensure_fresh_session,
+    missing_auth_message,
+    resolve_pipefy_auth,
+)
+from pipefy_sdk import (
+    PipefyClient,
+    PipefySettings,
+)
+
+from pipefy_cli._docs import DOCS_CLI_AUTH_REF
+
+# Display labels for ``pipefy auth status``. The resolver knows the
+# static-token method; the CLI restores the flag-vs-env distinction here.
+FLAG_TOKEN_SOURCE: Final = "flag-token"
+ENV_TOKEN_SOURCE: Final = "env-token"
+
+# Locked JSON wire schema for ``pipefy auth status``: the auth-method names,
+# with the static-token method split into the CLI's flag-vs-env surfaces, plus
+# an explicit ``"none"`` sentinel for when no method resolved. Produced by
+# :func:`detect_cli_auth_methods` / :func:`to_display_source`; ``commands.auth``
+# renders it.
+DisplaySource = Literal[
+    "flag-token",
+    "env-token",
+    "service-account",
+    "stored-session",
+    "none",
+]
+
+
+@dataclass(frozen=True)
+class BearerToken:
+    """Static bearer token plus the surface that produced it (``--token`` or env)."""
+
+    value: str = field(repr=False)
+    source: Literal["flag", "env"]
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    """Auth inputs for a single CLI invocation.
+
+    Each field maps to one auth method (bearer-token, service-account,
+    stored-session). Built once at startup from the loaded
+    :class:`pipefy_auth.AuthSettings` plus the per-invocation ``--token`` /
+    ``PIPEFY_TOKEN`` resolution.
+
+    ``oidc_client`` is ``None`` only when ``AuthSettings.disable_stored_session``
+    is set (env: PIPEFY_DISABLE_STORED_SESSION); the stored-session method is
+    then skipped end-to-end. Otherwise ``auth_url`` defaults to the prod IdP
+    and the client is always present.
+    """
+
+    bearer_token: BearerToken | None
+    service_account: ServiceAccount | None
+    oidc_client: OidcClient | None
+
+
+_cached_signature: str | None = None
+# One-shot CLIs reuse this; long-lived programmatic use should call
+# ``clear_authenticated_client_cache`` between logical sessions (tests reset via fixture).
+_cached_client: PipefyClient | None = None
+
+
+def clear_authenticated_client_cache() -> None:
+    """Drop the in-process client cache (tests and rare reload scenarios)."""
+    global _cached_signature, _cached_client
+    _cached_signature = None
+    _cached_client = None
+
+
+def _resolver_kwargs(auth: AuthContext) -> dict[str, Any]:
+    """Map an :class:`AuthContext` onto the keyword inputs the resolver takes."""
+    return {
+        "static_token": auth.bearer_token.value if auth.bearer_token else None,
+        "service_account": auth.service_account,
+        "oidc_client": auth.oidc_client,
+    }
+
+
+def _resolve(auth: AuthContext) -> ResolvedAuth | None:
+    return resolve_pipefy_auth(**_resolver_kwargs(auth))
+
+
+def to_display_source(
+    resolved: ResolvedAuth, bearer: BearerToken | None
+) -> DisplaySource:
+    """Map a resolved auth method to its locked ``auth status`` wire value.
+
+    The static-token method splits into the flag-vs-env distinction the CLI
+    surfaces; the other methods map to their resolver wire name unchanged.
+    """
+    match resolved:
+        case StaticTokenAuth():
+            return (
+                FLAG_TOKEN_SOURCE
+                if bearer and bearer.source == "flag"
+                else ENV_TOKEN_SOURCE
+            )
+        case ServiceAccountAuth():
+            return "service-account"
+        case StoredSessionAuth():
+            return "stored-session"
+        case _:
+            assert_never(resolved)
+
+
+def detect_cli_auth_methods(auth: AuthContext) -> list[ResolvedAuth]:
+    """Return the detected auth methods for a CLI invocation, precedence-first.
+
+    The non-short-circuiting view of the chain: every configured method, not
+    just the winner. ``pipefy auth status`` renders each via
+    :func:`to_display_source` and treats the first as the active source.
+    """
+    return detect_pipefy_auth_methods(**_resolver_kwargs(auth))
+
+
+def _cache_key(
+    pipefy_settings: PipefySettings,
+    auth: AuthContext,
+) -> str:
+    """SHA-256 digest of every input that could change the cached client.
+
+    Hashed (not stored as plaintext) so the dump's secrets — the bearer
+    token, the service-account ``client_secret`` — don't linger in module
+    state for the process lifetime. Adding a new field to
+    :class:`PipefySettings` or :class:`AuthContext` automatically participates
+    in the key without touching this function. The resolved method is omitted:
+    it is a pure function of the auth fields above, so it adds no distinction.
+    """
+    payload = json.dumps(
+        {
+            "settings": pipefy_settings.model_dump(mode="json"),
+            "auth": asdict(auth),
+        },
+        sort_keys=True,
+        default=str,
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def get_authenticated_client(
+    pipefy_settings: PipefySettings,
+    auth: AuthContext,
+) -> PipefyClient:
+    """Return a facade client using the highest-precedence available auth source.
+
+    Raises:
+        typer.Exit: Code 2 when no auth source resolves, or when refreshing a
+            stored session fails.
+    """
+    global _cached_signature, _cached_client
+
+    resolved = _resolve(auth)
+    if resolved is None:
+        typer.echo(f"{missing_auth_message()} See {DOCS_CLI_AUTH_REF}.", err=True)
+        raise typer.Exit(2)
+
+    # Stored-session: warm up eagerly so refresh failures surface as a clean
+    # exit(2) with a "run `pipefy auth login` again" hint instead of leaking
+    # out as a transport error on the first GraphQL call.
+    if isinstance(resolved, StoredSessionAuth):
+        try:
+            ensure_fresh_session(
+                issuer=resolved.oidc_client.issuer_url,
+                client_id=resolved.oidc_client.client_id,
+            )
+        except RefreshError as exc:
+            typer.echo(
+                f"Stored Pipefy session could not be refreshed: {exc}. "
+                "Run `pipefy auth login` to sign in again.",
+                err=True,
+            )
+            raise typer.Exit(2) from exc
+
+    key = _cache_key(pipefy_settings, auth)
+    if _cached_client is not None and _cached_signature == key:
+        return _cached_client
+
+    client = PipefyClient(
+        pipefy_settings, auth=build_httpx_auth(resolved), surface="cli"
+    )
+    _cached_signature = key
+    _cached_client = client
+    return client
+
+
+__all__ = [
+    "AuthContext",
+    "BearerToken",
+    "DisplaySource",
+    "ENV_TOKEN_SOURCE",
+    "FLAG_TOKEN_SOURCE",
+    "clear_authenticated_client_cache",
+    "detect_cli_auth_methods",
+    "get_authenticated_client",
+    "to_display_source",
+]

pipefy_cli/commands/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from pipefy_cli.commands.card import card_app
+
+__all__ = ["card_app"]

pipefy_cli/commands/_common.py

@@ -0,0 +1,359 @@
+"""Shared Typer helpers for domain command modules."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import math
+import sys
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+import typer
+from gql.transport.exceptions import TransportError, TransportQueryError
+from pipefy_sdk import PipefyClient, PipefySettings, stream_bytes
+from pipefy_sdk.exceptions import PipefyError
+from pipefy_sdk.label_color import normalize_label_color
+from pipefy_sdk.report_filter_preflight import prepare_report_cards_filter
+
+from pipefy_cli.auth import (
+    AuthContext,
+    BearerToken,
+    get_authenticated_client,
+)
+from pipefy_cli.output import render_json, render_rich
+
+_T = TypeVar("_T")
+_R = TypeVar("_R")
+
+DEFAULT_EXPORT_MAX_BYTES = 50 * 1024 * 1024
+
+# Pipefy occasionally encodes ids with a leading hyphen (e.g. table id "-ZocGcM0").
+# Click parses tokens starting with "-" as short options by default, which breaks
+# every `<sub> get/update/delete <ID>` command. Setting ignore_unknown_options on
+# the command relaxes the parser so the dashed token is consumed as the positional
+# id. Tokens starting with ``--`` must still be rejected (they look like long
+# options); use :func:`validate_positional_id` on those arguments.
+ID_POSITIONAL_CONTEXT_SETTINGS = {"ignore_unknown_options": True}
+
+
+def validate_positional_id(value: str) -> str:
+    """Reject typoed long-option tokens mistakenly captured as a resource id."""
+    if value.startswith("--"):
+        raise typer.BadParameter(
+            f"unknown option-like value {value!r}; if an id starts with '-', pass it after '--'"
+        )
+    return value
+
+
+def resource_id_argument(*, help: str) -> Any:
+    """Typer ``Argument`` for resource ids when ``ignore_unknown_options`` is enabled."""
+    return typer.Argument(..., help=help, callback=validate_positional_id)
+
+
+def validate_optional_resource_id(value: str | None, label: str) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    if not cleaned:
+        raise typer.BadParameter(
+            f"Invalid '{label}': provide a non-empty string or positive integer."
+        )
+    if cleaned.startswith("-") and cleaned[1:].isdigit():
+        raise typer.BadParameter(f"Invalid '{label}': provide a positive integer.")
+    if cleaned.isdigit() and int(cleaned) <= 0:
+        raise typer.BadParameter(f"Invalid '{label}': provide a positive integer.")
+    return cleaned
+
+
+_CARDS_PAGE_SIZE_MIN = 1
+_CARDS_PAGE_SIZE_MAX = 500
+
+
+def validate_cards_page_size(first: int | None) -> int | None:
+    if first is None:
+        return None
+    if first < _CARDS_PAGE_SIZE_MIN or first > _CARDS_PAGE_SIZE_MAX:
+        raise typer.BadParameter(
+            f"--first must be between {_CARDS_PAGE_SIZE_MIN} and "
+            f"{_CARDS_PAGE_SIZE_MAX} (inclusive)."
+        )
+    return first
+
+
+def validate_label_name_cli(name: str) -> str:
+    nm = name.strip()
+    if not nm:
+        raise typer.BadParameter("--name must be non-empty.")
+    return nm
+
+
+def prepare_report_cards_filter_cli(
+    filter_obj: dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    """Normalize and validate ``ReportCardsFilter`` before auth or network I/O."""
+    try:
+        return prepare_report_cards_filter(filter_obj)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def normalize_label_color_cli(color: str) -> str:
+    """Normalize label ``color`` before auth or network I/O."""
+    try:
+        return normalize_label_color(color)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def export_poll_max_rounds(
+    poll_timeout_seconds: float, *, delay_seconds: float = 2.0
+) -> int:
+    """Map a wall-clock export poll budget to loop iterations (``delay_seconds`` per round).
+
+    Args:
+        poll_timeout_seconds: Maximum time to wait for export state ``done``.
+        delay_seconds: Sleep between status polls.
+    """
+    if poll_timeout_seconds <= 0:
+        raise ValueError("poll_timeout_seconds must be positive")
+    return max(1, math.ceil(poll_timeout_seconds / delay_seconds))
+
+
+async def poll_export_until_done(
+    fetch: Callable[[str], Awaitable[dict[str, Any] | None]],
+    export_id: str,
+    unwrap: Callable[[dict[str, Any]], dict[str, Any]],
+    *,
+    max_rounds: int,
+    delay_seconds: float = 2.0,
+) -> str:
+    """Poll an export job until ``state == done`` and return ``fileURL``.
+
+    Args:
+        fetch: Async callable taking export id and returning the raw GraphQL payload dict.
+        export_id: Export job id from the start mutation.
+        unwrap: Extract the export status node dict from ``fetch``'s return value.
+        max_rounds: Maximum poll iterations before timing out.
+        delay_seconds: Delay between polls.
+    """
+    eid = str(export_id)
+    for _ in range(max_rounds):
+        raw = await fetch(eid)
+        node = unwrap(raw or {}) or {}
+        state = str(node.get("state") or "")
+        if state in ("failed", "error"):
+            raise ValueError(f"Export failed (state={state!r}).")
+        if state == "done":
+            url = node.get("fileURL") or node.get("fileUrl")
+            if isinstance(url, str) and url.strip():
+                return url.strip()
+            raise ValueError("Export is done but fileURL is missing.")
+        await asyncio.sleep(delay_seconds)
+    raise ValueError(
+        f"Timed out waiting for export {eid} after {max_rounds * delay_seconds:.0f}s."
+    )
+
+
+async def write_export_csv_to_stdout(
+    *,
+    export_id: str,
+    poll_fetch: Callable[[str], Awaitable[dict[str, Any] | None]],
+    unwrap_status: Callable[[dict[str, Any]], dict[str, Any]],
+    poll_timeout_seconds: float,
+    max_bytes: int = DEFAULT_EXPORT_MAX_BYTES,
+) -> None:
+    """Poll an export job until ``done`` and stream the CSV body to stdout.
+
+    Args:
+        export_id: Export job id (from the start mutation).
+        poll_fetch: Async callable that fetches the export status payload by id.
+        unwrap_status: Extract the export status node dict from the raw payload.
+        poll_timeout_seconds: Wall-clock budget for polling before raising ``ValueError``.
+        max_bytes: Hard cap on the download size enforced by :func:`stream_bytes`.
+    """
+    max_rounds = export_poll_max_rounds(poll_timeout_seconds)
+    url = await poll_export_until_done(
+        poll_fetch,
+        export_id,
+        unwrap_status,
+        max_rounds=max_rounds,
+    )
+    async for chunk in stream_bytes(url, max_bytes=max_bytes):
+        sys.stdout.buffer.write(chunk)
+    sys.stdout.buffer.flush()
+
+
+def run_pipefy_client_coroutine(
+    ctx: typer.Context,
+    coro_factory: Callable[[PipefyClient], Awaitable[_T]],
+    *,
+    value_error_exit_code: int | None = None,
+) -> _T:
+    """Run ``asyncio.run`` on a coroutine built with a configured :class:`PipefyClient`.
+
+    Args:
+        ctx: Typer context (resolves settings/token from the root app).
+        coro_factory: Async callable receiving an authenticated client.
+        value_error_exit_code: When set, map ``ValueError`` from the factory to this exit code (stderr message).
+
+    Returns:
+        The coroutine result.
+
+    Raises:
+        typer.Exit: On :class:`PipefyError` (exit code 1), optional ``ValueError`` mapping, or ``BrokenPipeError`` (exit 0).
+    """
+    pipefy_settings, auth = settings_and_auth_from_ctx(ctx)
+
+    async def _run() -> _T:
+        client = get_authenticated_client(pipefy_settings, auth)
+        return await coro_factory(client)
+
+    try:
+        return asyncio.run(_run())
+    except PipefyError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    except ValueError as exc:
+        if value_error_exit_code is None:
+            raise
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(value_error_exit_code) from exc
+    except BrokenPipeError:
+        raise typer.Exit(0) from None
+    except TransportQueryError as exc:
+        typer.echo(_format_transport_query_error(exc), err=True)
+        raise typer.Exit(1) from exc
+    except TransportError as exc:
+        typer.echo(f"Pipefy transport error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+
+
+def _format_transport_query_error(exc: TransportQueryError) -> str:
+    """Render a GraphQL transport error as a clean single-line message for the CLI.
+
+    Falls back to ``str(exc)`` when the structured ``errors`` payload is missing or empty.
+    """
+    errors = getattr(exc, "errors", None) or []
+    if not errors:
+        return str(exc)
+    first = errors[0] if isinstance(errors[0], dict) else {"message": str(errors[0])}
+    message = first.get("message") or str(exc)
+    code = (first.get("extensions") or {}).get("code")
+    return f"{message} ({code})" if code else message
+
+
+def format_card_get_transport_query_error(exc: TransportQueryError) -> str:
+    """Like :func:`_format_transport_query_error` with a hint for missing/deleted cards."""
+    base = _format_transport_query_error(exc)
+    errors = getattr(exc, "errors", None) or []
+    if errors and isinstance(errors[0], dict):
+        code = (errors[0].get("extensions") or {}).get("code")
+        if code == "PERMISSION_DENIED":
+            return f"{base} The card may have been deleted or is not visible to this token."
+    return base
+
+
+def settings_and_token(
+    ctx: typer.Context,
+) -> tuple[PipefySettings, BearerToken | None]:
+    """Resolve root CLI context object into settings and optional bearer token."""
+    root = ctx.find_root()
+    obj = root.obj
+    return obj["pipefy_settings"], obj.get("token")
+
+
+def settings_and_auth_from_ctx(
+    ctx: typer.Context,
+) -> tuple[PipefySettings, AuthContext]:
+    """Resolve root ``ctx.obj`` into the (settings, auth) pair the client boundary needs."""
+    obj = ctx.find_root().obj
+    auth_settings = obj["auth_settings"]
+    auth = AuthContext(
+        bearer_token=obj.get("token"),
+        service_account=auth_settings.to_service_account(),
+        oidc_client=auth_settings.to_oidc_client(),
+    )
+    return obj["pipefy_settings"], auth
+
+
+def authenticated_client_from_ctx(ctx: typer.Context) -> PipefyClient:
+    """Build a :class:`PipefyClient` using the same auth path as ``run_cli_command``."""
+    pipefy_settings, auth = settings_and_auth_from_ctx(ctx)
+    return get_authenticated_client(pipefy_settings, auth)
+
+
+def parse_json_value(raw: str | None, option_name: str) -> Any:
+    """Parse a JSON value from a CLI string option (empty input returns ``None``)."""
+    if raw is None or raw.strip() == "":
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON for {option_name}: {exc}") from exc
+
+
+def parse_json_object(raw: str | None, option_name: str) -> dict[str, Any] | None:
+    """Parse a JSON object from a CLI string option (empty input returns ``None``)."""
+    if raw is None or raw.strip() == "":
+        return None
+    parsed = parse_json_value(raw, option_name)
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter(f"{option_name} must be a JSON object")
+    return parsed
+
+
+def confirm_destructive(*, yes: bool, description: str, verb: str = "delete") -> None:
+    """Prompt before a destructive action unless ``yes`` is True."""
+    if yes:
+        return
+    if not typer.confirm(f"Permanently {verb} {description}?"):
+        raise typer.Abort()
+
+
+def run_cli_command(
+    ctx: typer.Context,
+    json_out: bool,
+    coro_factory: Callable[[PipefyClient], Awaitable[_R]],
+    *,
+    exit_code_2_on_value_error: bool = True,
+    format_transport_query_error: Callable[[TransportQueryError], str] | None = None,
+) -> None:
+    """Run an async coroutine factory with a configured client and render the result.
+
+    Args:
+        ctx: Typer context (resolves settings/token from the root app).
+        json_out: When True, print JSON; otherwise Rich rendering.
+        coro_factory: Async callable receiving ``PipefyClient`` and returning renderable data.
+        exit_code_2_on_value_error: Map ``ValueError`` to process exit code 2 (stderr).
+        format_transport_query_error: Optional override for GraphQL transport errors
+            (defaults to a single-line formatter).
+    """
+    pipefy_settings, auth = settings_and_auth_from_ctx(ctx)
+    transport_fmt = format_transport_query_error or _format_transport_query_error
+
+    async def _run() -> _R:
+        client = get_authenticated_client(pipefy_settings, auth)
+        return await coro_factory(client)
+
+    try:
+        data = asyncio.run(_run())
+    except PipefyError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    except TransportQueryError as exc:
+        typer.echo(transport_fmt(exc), err=True)
+        raise typer.Exit(1) from exc
+    except TransportError as exc:
+        typer.echo(f"Pipefy transport error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    except ValueError as exc:
+        if exit_code_2_on_value_error:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(2) from exc
+        raise
+
+    if json_out:
+        render_json(data)
+    else:
+        render_rich(data)