pipefy-cli 0.3.0a1__tar.gz

pipefy_cli-0.3.0a1/.gitignore

@@ -0,0 +1,56 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Ruff stuff:
+.ruff_cache/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.mise.toml
+
+# Ralph Wiggum (local autonomous runs; state must not land in git)
+.ralph/
+RALPH_TASK.md
+
+# IDEs and editors
+.cursor/
+.claude/
+# Cursor MCP workspace config (machine-specific paths or local server entries).
+# Carve-out: repo-root .mcp.json is the Claude Code plugin's MCP server config
+# (auto-discovered at plugin root) and is intentionally tracked.
+.mcp.json
+!/.mcp.json
+
+# Tracked release tooling only (ignore ad-hoc local scripts and smoke artifacts)
+scripts/*
+!scripts/bump_version.py
+
+# macOS
+.DS_Store
+**/.DS_Store

pipefy_cli-0.3.0a1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: pipefy-cli
+Version: 0.3.0a1
+Summary: Typer CLI for Pipefy (pipefy).
+Requires-Python: >=3.11
+Requires-Dist: pipefy
+Requires-Dist: pipefy-auth
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# pipefy-cli
+
+Typer-based CLI for Pipefy. Exposes all MCP tool capabilities as terminal commands and scripts. Depends on [`pipefy`](../sdk/README.md) for GraphQL calls.
+
+## Install (pre-launch, v0.1 → v0.5)
+
+```sh
+uvx \
+  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
+  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
+  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
+  --refresh pipefy-cli
+```
+
+Or persistently:
+
+```sh
+uv tool install \
+  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
+  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
+  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
+```
+
+The `--with` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uv tool install pipefy-cli`.
+
+## Quick start
+
+```bash
+# Show all commands
+pipefy --help
+
+# Card operations
+pipefy card get 12345 --json
+pipefy card list --pipe 67890
+pipefy card create --pipe 67890 --title "New card"
+```
+
+Agent skills are installed separately via [`skills.sh`](https://github.com/vercel-labs/skills); see [`skills/README.md`](../../skills/README.md).
+
+## Configuration
+
+Same `PIPEFY_*` environment variables as `pipefy-mcp-server` (`.env` in CWD is loaded automatically):
+
+```env
+PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=your_client_id
+PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=your_client_secret
+# Non-prod environments only:
+# PIPEFY_BASE_URL=https://<your-api-host>
+# PIPEFY_AUTH_URL=https://<your-signin-host>/realms/<realm>
+```
+
+`PIPEFY_BASE_URL` defaults to `https://app.pipefy.com` (drives the four API endpoints) and `PIPEFY_AUTH_URL` defaults to `https://signin.pipefy.com/realms/pipefy` (the OIDC issuer). Set them only for non-prod environments.
+
+### Authentication paths
+
+Three credential sources, in CLI precedence order:
+
+1. **Interactive (`pipefy auth login`)** — browser OAuth flow, session stored in the OS keychain. Best for human developers. Status and revocation via `pipefy auth status` and `pipefy auth logout`.
+2. **Static bearer (`PIPEFY_TOKEN` or `--token`)** — direct bearer token, no OAuth. Intended for CI and scripted use. Overrides everything else.
+3. **Service-account OAuth (`PIPEFY_SERVICE_ACCOUNT_CLIENT_ID` + `PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET`)** — unattended OAuth client-credentials grant. Used by the MCP server.
+
+Full env-var reference, validation rules, and `config.toml` precedence: [`docs/config.md`](../../docs/config.md). Auth deep-dive (precedence rules, troubleshooting, keychain backends): [`docs/cli/auth.md`](../../docs/cli/auth.md).
+
+## Output modes
+
+Every command defaults to **Rich-formatted** human output. Add `--json` for machine-readable JSON to stdout.
+
+```bash
+pipefy card get 12345 --json | jq '.title'
+```
+
+## Parity with MCP
+
+Every MCP tool has a CLI counterpart (or a tracked deferral). See [`docs/parity.md`](../../docs/parity.md) for the full matrix.
+
+## Shell completion
+
+```bash
+pipefy --install-completion bash    # or zsh, fish, etc.
+```
+
+## Development
+
+From the **repository root**:
+
+```bash
+uv sync
+uv run pytest packages/cli/tests     # CLI tests
+uv run ruff check packages/cli/src   # lint
+```
+
+See [`AGENTS.md`](../../AGENTS.md) and [`CLAUDE.md`](../../CLAUDE.md) for contributor guidance.

pipefy_cli-0.3.0a1/README.md

@@ -0,0 +1,92 @@
+# pipefy-cli
+
+Typer-based CLI for Pipefy. Exposes all MCP tool capabilities as terminal commands and scripts. Depends on [`pipefy`](../sdk/README.md) for GraphQL calls.
+
+## Install (pre-launch, v0.1 → v0.5)
+
+```sh
+uvx \
+  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
+  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
+  --from "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli" \
+  --refresh pipefy-cli
+```
+
+Or persistently:
+
+```sh
+uv tool install \
+  --with "pipefy @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/sdk" \
+  --with "pipefy-auth @ git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/auth" \
+  "git+https://github.com/pipefy/ai-toolkit@latest#subdirectory=packages/cli"
+```
+
+The `--with` flags are required pre-1.0 because the workspace members are not yet on PyPI. At v1.0 this collapses to `uv tool install pipefy-cli`.
+
+## Quick start
+
+```bash
+# Show all commands
+pipefy --help
+
+# Card operations
+pipefy card get 12345 --json
+pipefy card list --pipe 67890
+pipefy card create --pipe 67890 --title "New card"
+```
+
+Agent skills are installed separately via [`skills.sh`](https://github.com/vercel-labs/skills); see [`skills/README.md`](../../skills/README.md).
+
+## Configuration
+
+Same `PIPEFY_*` environment variables as `pipefy-mcp-server` (`.env` in CWD is loaded automatically):
+
+```env
+PIPEFY_SERVICE_ACCOUNT_CLIENT_ID=your_client_id
+PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET=your_client_secret
+# Non-prod environments only:
+# PIPEFY_BASE_URL=https://<your-api-host>
+# PIPEFY_AUTH_URL=https://<your-signin-host>/realms/<realm>
+```
+
+`PIPEFY_BASE_URL` defaults to `https://app.pipefy.com` (drives the four API endpoints) and `PIPEFY_AUTH_URL` defaults to `https://signin.pipefy.com/realms/pipefy` (the OIDC issuer). Set them only for non-prod environments.
+
+### Authentication paths
+
+Three credential sources, in CLI precedence order:
+
+1. **Interactive (`pipefy auth login`)** — browser OAuth flow, session stored in the OS keychain. Best for human developers. Status and revocation via `pipefy auth status` and `pipefy auth logout`.
+2. **Static bearer (`PIPEFY_TOKEN` or `--token`)** — direct bearer token, no OAuth. Intended for CI and scripted use. Overrides everything else.
+3. **Service-account OAuth (`PIPEFY_SERVICE_ACCOUNT_CLIENT_ID` + `PIPEFY_SERVICE_ACCOUNT_CLIENT_SECRET`)** — unattended OAuth client-credentials grant. Used by the MCP server.
+
+Full env-var reference, validation rules, and `config.toml` precedence: [`docs/config.md`](../../docs/config.md). Auth deep-dive (precedence rules, troubleshooting, keychain backends): [`docs/cli/auth.md`](../../docs/cli/auth.md).
+
+## Output modes
+
+Every command defaults to **Rich-formatted** human output. Add `--json` for machine-readable JSON to stdout.
+
+```bash
+pipefy card get 12345 --json | jq '.title'
+```
+
+## Parity with MCP
+
+Every MCP tool has a CLI counterpart (or a tracked deferral). See [`docs/parity.md`](../../docs/parity.md) for the full matrix.
+
+## Shell completion
+
+```bash
+pipefy --install-completion bash    # or zsh, fish, etc.
+```
+
+## Development
+
+From the **repository root**:
+
+```bash
+uv sync
+uv run pytest packages/cli/tests     # CLI tests
+uv run ruff check packages/cli/src   # lint
+```
+
+See [`AGENTS.md`](../../AGENTS.md) and [`CLAUDE.md`](../../CLAUDE.md) for contributor guidance.

pipefy_cli-0.3.0a1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "pipefy-cli"
+dynamic = ["version"]
+description = "Typer CLI for Pipefy (pipefy)."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pipefy",
+    "pipefy-auth",
+    "typer>=0.12",
+    "rich>=13",
+    "pydantic-settings>=2.8.1",
+]
+
+[project.scripts]
+pipefy = "pipefy_cli.main:app"
+
+[tool.uv.sources]
+pipefy = { workspace = true }
+pipefy-auth = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-asyncio>=0.26.0",
+    "ruff>=0.11.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipefy_cli"]
+
+[tool.hatch.version]
+path = "src/pipefy_cli/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests", "../sdk/tests"]
+markers = [
+    "unit: marks a test as a unit test",
+    "integration: marks tests that call the live Pipefy API",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+lint.extend-select = ["TID251"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"pipefy_mcp".msg = "pipefy_cli must not import the MCP package; use pipefy_sdk instead."
+"pipefy_sdk.services".msg = "Import from pipefy_sdk only; pipefy_sdk.services is private."
+"pipefy_sdk.queries".msg = "Import from pipefy_sdk only; pipefy_sdk.queries is private."

pipefy_cli-0.3.0a1/src/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-0.3.0a1/src/pipefy_cli/_docs.py

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

pipefy_cli-0.3.0a1/src/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-0.3.0a1/src/pipefy_cli/commands/__init__.py

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