pipefy-cli 0.3.0a1__py3-none-any.whl

pipefy_cli/commands/field.py

@@ -0,0 +1,113 @@
+"""Phase field subcommands."""
+
+from __future__ import annotations
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    resource_id_argument,
+    run_cli_command,
+)
+
+field_app = typer.Typer(help="Phase field operations.", no_args_is_help=True)
+
+
+@field_app.command("list")
+def field_list(
+    ctx: typer.Context,
+    phase_id: str = typer.Option(..., "--phase", help="Phase id."),
+    required_only: bool = typer.Option(
+        False,
+        "--required-only",
+        help="Return only required fields.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """List fields on a phase (``get_phase_fields``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_phase_fields(phase_id, required_only=required_only)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_app.command("create")
+def field_create(
+    ctx: typer.Context,
+    phase_id: str = typer.Option(..., "--phase", help="Phase id."),
+    label: str = typer.Option(..., "--label", "-l", help="Field label in the UI."),
+    field_type: str = typer.Option(
+        ...,
+        "--type",
+        "-t",
+        help="Pipefy field type (e.g. short_text, number).",
+    ),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object of extra CreatePhaseFieldInput fields.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create a field on a phase."""
+
+    extra = parse_json_object(extra_json, "--extra") or {}
+    lab = label.strip()
+    ft = field_type.strip()
+    if not lab or not ft:
+        typer.echo("--label and --type must be non-empty.", err=True)
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.create_phase_field(phase_id, lab, ft, **extra)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def field_update(
+    ctx: typer.Context,
+    field_id: str = resource_id_argument(help="Phase field id."),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object of UpdatePhaseFieldInput fields (snake_case / API keys).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update a phase field (pass attributes via ``--extra`` JSON)."""
+
+    extra = parse_json_object(extra_json, "--extra")
+    if not extra:
+        raise typer.BadParameter("Provide --extra with a non-empty JSON object.")
+
+    async def factory(client: PipefyClient):
+        return await client.update_phase_field(field_id, **extra)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def field_delete(
+    ctx: typer.Context,
+    field_id: str = resource_id_argument(help="Phase field id."),
+    pipe_uuid: str | None = typer.Option(
+        None,
+        "--pipe-uuid",
+        help="Optional pipe UUID (passed through to the API when required).",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a phase field permanently."""
+
+    confirm_destructive(yes=yes, description=f"phase field {field_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_phase_field(field_id, pipe_uuid=pipe_uuid)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/field_condition.py

@@ -0,0 +1,201 @@
+"""Field condition rules on phases."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    parse_json_value,
+    resource_id_argument,
+    run_cli_command,
+)
+
+field_condition_app = typer.Typer(
+    help="Field conditions (dynamic form rules on phases).",
+    no_args_is_help=True,
+)
+
+
+@field_condition_app.command("list")
+def field_condition_list(
+    ctx: typer.Context,
+    phase_id: str = typer.Option(
+        ..., "--phase", help="Phase id that owns the conditions."
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """List field conditions on a phase (``get_field_conditions``)."""
+
+    async def factory(client: PipefyClient) -> dict[str, Any]:
+        raw = await client.get_field_conditions(phase_id)
+        phase = raw.get("phase")
+        if phase is None:
+            return {"success": False, "error": "Phase not found or access denied."}
+        rows = phase.get("fieldConditions") or []
+        return {
+            "success": True,
+            "message": "Field conditions loaded.",
+            "field_conditions": rows,
+        }
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_condition_app.command("get", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def field_condition_get(
+    ctx: typer.Context,
+    condition_id: str = resource_id_argument(help="Field condition id."),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Load one field condition by id (``get_field_condition``)."""
+
+    async def factory(client: PipefyClient) -> dict[str, Any]:
+        raw = await client.get_field_condition(condition_id)
+        fc = raw.get("fieldCondition")
+        if fc is None:
+            return {
+                "success": False,
+                "error": "Field condition not found or access denied.",
+            }
+        return {
+            "success": True,
+            "message": "Field condition loaded.",
+            "field_condition": fc,
+        }
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_condition_app.command("create")
+def field_condition_create(
+    ctx: typer.Context,
+    phase_id: str = typer.Option(..., "--phase", help="Phase id."),
+    name: str = typer.Option(..., "--name", "-n", help="Rule name (required by API)."),
+    condition: str = typer.Option(
+        ...,
+        "--condition",
+        help=(
+            "JSON object: ConditionInput. Example: "
+            '\'{"expressions":[{"structure_id":0,"field_address":"<internal_id>",'
+            '"operation":"equals","value":"X"}],"expressions_structure":[[0]]}\'. '
+            "structure_id / expressions_structure entries are coerced to int by the SDK."
+        ),
+    ),
+    actions: str = typer.Option(
+        ...,
+        "--actions",
+        help=(
+            "JSON array: action objects. Each item needs phaseFieldId (use the field's "
+            "internal_id from get_phase_fields) + actionId (hide|show). Example: "
+            '\'[{"phaseFieldId":"<internal_id>","actionId":"hide"}]\'.'
+        ),
+    ),
+    extra: str | None = typer.Option(
+        None,
+        "--extra",
+        help="Optional JSON object merged into create input (camelCase keys).",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Create a field condition (``create_field_condition``)."""
+    cond_obj = parse_json_value(condition, "--condition")
+    if not isinstance(cond_obj, dict):
+        raise typer.BadParameter("--condition must be a JSON object")
+    act_parsed = parse_json_value(actions, "--actions")
+    if not isinstance(act_parsed, list):
+        raise typer.BadParameter("--actions must be a JSON array")
+    actions_list: list[dict[str, Any]] = []
+    for i, item in enumerate(act_parsed):
+        if not isinstance(item, dict):
+            raise typer.BadParameter(f"--actions[{i}] must be a JSON object")
+        actions_list.append(item)
+    extra_obj = parse_json_object(extra, "--extra") or {}
+
+    async def factory(client: PipefyClient):
+        return await client.create_field_condition(
+            phase_id,
+            cond_obj,
+            actions_list,
+            name=name,
+            **extra_obj,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_condition_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def field_condition_update(
+    ctx: typer.Context,
+    condition_id: str = resource_id_argument(help="Field condition id."),
+    extra: str = typer.Option(
+        ...,
+        "--extra",
+        help="JSON object: fields to patch (camelCase keys for UpdateFieldConditionInput).",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Update a field condition (``update_field_condition``)."""
+    extra_obj = parse_json_value(extra, "--extra")
+    if not isinstance(extra_obj, dict):
+        raise typer.BadParameter("--extra must be a JSON object")
+
+    async def factory(client: PipefyClient):
+        return await client.update_field_condition(condition_id, **extra_obj)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@field_condition_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def field_condition_delete(
+    ctx: typer.Context,
+    condition_id: str = resource_id_argument(help="Field condition id."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip interactive confirmation.",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Delete a field condition permanently (``delete_field_condition``)."""
+    confirm_destructive(
+        yes=yes,
+        description=f"field condition {condition_id}",
+        verb="delete",
+    )
+
+    async def factory(client: PipefyClient):
+        return await client.delete_field_condition(condition_id)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/graphql.py

@@ -0,0 +1,110 @@
+"""Raw GraphQL execution (escape hatch for agents)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import typer
+from graphql import GraphQLSyntaxError, parse
+from graphql.language.ast import OperationDefinitionNode, OperationType
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import run_pipefy_client_coroutine
+from pipefy_cli.output import render_json, render_rich
+
+graphql_app = typer.Typer(
+    help="Execute arbitrary GraphQL (mutations require --yes). See docs/cli/self-healing.md.",
+    no_args_is_help=True,
+)
+
+
+def _document_contains_mutation(document: str) -> bool:
+    """Return True when the document defines at least one mutation operation."""
+    try:
+        doc = parse(document)
+    except GraphQLSyntaxError:
+        return False
+    for defn in doc.definitions:
+        if (
+            isinstance(defn, OperationDefinitionNode)
+            and defn.operation == OperationType.MUTATION
+        ):
+            return True
+    return False
+
+
+def _parse_vars_json(raw: str | None) -> dict[str, Any]:
+    """Parse --vars JSON; default is empty object. Malformed JSON raises typer.Exit(2)."""
+    if raw is None or raw.strip() == "":
+        return {}
+    try:
+        parsed: Any = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        typer.echo(f"Invalid JSON for --vars: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    if not isinstance(parsed, dict):
+        typer.echo("--vars must be a JSON object.", err=True)
+        raise typer.Exit(2)
+    return parsed
+
+
+def _run_graphql(
+    ctx: typer.Context,
+    factory: Callable[[PipefyClient], Awaitable[Any]],
+) -> Any:
+    """Run an async GraphQL call with shared auth."""
+    return run_pipefy_client_coroutine(ctx, factory)
+
+
+@graphql_app.command("exec")
+def graphql_exec(
+    ctx: typer.Context,
+    query: str = typer.Option(
+        ...,
+        "--query",
+        "-q",
+        help="GraphQL document string (query or mutation).",
+    ),
+    vars_json: str | None = typer.Option(
+        None,
+        "--vars",
+        help='Variables JSON object (default "{}" ).',
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="Acknowledge and run mutations (required when the document includes mutation).",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Emit JSON to stdout (default is Rich for objects).",
+    ),
+) -> None:
+    """Execute GraphQL via the SDK (``execute_graphql``).
+
+    Pass variables as JSON with ``--vars '{"key":"value"}'`` (not ``--variables``).
+
+    Mutations are rejected unless ``--yes`` is set (exit code 2). Pair with
+    ``pipefy introspect`` to discover operation shapes (see docs/cli/self-healing.md).
+    """
+    variables = _parse_vars_json(vars_json)
+    if _document_contains_mutation(query) and not yes:
+        typer.echo(
+            "This document includes a mutation; re-run with --yes to confirm, "
+            "or use read-only operations.",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.execute_graphql(query, variables)
+
+    payload = _run_graphql(ctx, factory)
+    if json_out:
+        render_json(payload)
+    else:
+        render_rich(payload)

pipefy_cli/commands/introspect.py

@@ -0,0 +1,110 @@
+"""GraphQL schema introspection (types, root fields, search)."""
+
+from __future__ import annotations
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import run_pipefy_client_coroutine
+from pipefy_cli.output import render_json, render_rich
+
+introspect_app = typer.Typer(
+    help="Discover GraphQL types and operations (JSON default).",
+    no_args_is_help=True,
+)
+schema_app = typer.Typer(help="Schema-wide search.", no_args_is_help=True)
+
+
+def _emit_introspection(data: object, *, rich: bool) -> None:
+    """Print introspection payload (JSON default, optional Rich)."""
+    if rich:
+        render_rich(data)
+    else:
+        render_json(data)
+
+
+@introspect_app.command("type")
+def introspect_type(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="GraphQL type name (e.g. Card)."),
+    max_depth: int = typer.Option(
+        1, "--max-depth", help="Nested type resolution depth."
+    ),
+    rich: bool = typer.Option(
+        False,
+        "--rich",
+        help="Pretty-print with Rich instead of JSON.",
+    ),
+) -> None:
+    """Introspect a schema type (``introspect_type``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.introspect_type(name, max_depth=max_depth)
+
+    payload = run_pipefy_client_coroutine(ctx, factory)
+    _emit_introspection(payload, rich=rich)
+
+
+@introspect_app.command("query")
+def introspect_query(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Root query field name."),
+    max_depth: int = typer.Option(
+        1, "--max-depth", help="Nested type resolution depth."
+    ),
+    rich: bool = typer.Option(
+        False, "--rich", help="Pretty-print with Rich instead of JSON."
+    ),
+) -> None:
+    """Introspect a root query field (``introspect_query``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.introspect_query(name, max_depth=max_depth)
+
+    payload = run_pipefy_client_coroutine(ctx, factory)
+    _emit_introspection(payload, rich=rich)
+
+
+@introspect_app.command("mutation")
+def introspect_mutation(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Root mutation field name."),
+    max_depth: int = typer.Option(
+        1, "--max-depth", help="Nested type resolution depth."
+    ),
+    rich: bool = typer.Option(
+        False, "--rich", help="Pretty-print with Rich instead of JSON."
+    ),
+) -> None:
+    """Introspect a root mutation field (``introspect_mutation``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.introspect_mutation(name, max_depth=max_depth)
+
+    payload = run_pipefy_client_coroutine(ctx, factory)
+    _emit_introspection(payload, rich=rich)
+
+
+@schema_app.command("search")
+def introspect_schema_search(
+    ctx: typer.Context,
+    keyword: str = typer.Argument(..., help="Case-insensitive substring."),
+    kind: str | None = typer.Option(
+        None,
+        "--kind",
+        help="Optional GraphQL type kind (OBJECT, INPUT_OBJECT, ENUM, ...).",
+    ),
+    rich: bool = typer.Option(
+        False, "--rich", help="Pretty-print with Rich instead of JSON."
+    ),
+) -> None:
+    """Search schema types (``search_schema``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.search_schema(keyword, kind=kind)
+
+    payload = run_pipefy_client_coroutine(ctx, factory)
+    _emit_introspection(payload, rich=rich)
+
+
+introspect_app.add_typer(schema_app, name="schema")

pipefy_cli/commands/label.py

@@ -0,0 +1,109 @@
+"""Pipe label subcommands."""
+
+from __future__ import annotations
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    normalize_label_color_cli,
+    resource_id_argument,
+    run_cli_command,
+    validate_label_name_cli,
+)
+
+label_app = typer.Typer(help="Pipe label operations.", no_args_is_help=True)
+
+
+@label_app.command("list")
+def label_list(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """List labels on a pipe (from ``get_pipe``); JSON shape matches MCP ``get_labels``."""
+
+    async def factory(client: PipefyClient):
+        raw = await client.get_pipe(pipe_id)
+        pipe_node = (raw or {}).get("pipe")
+        if pipe_node is None:
+            return {"success": False, "error": "Pipe not found or access denied."}
+        labels = pipe_node.get("labels")
+        if labels is None:
+            labels = []
+        return {
+            "success": True,
+            "message": "Labels loaded.",
+            "labels": labels,
+        }
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@label_app.command("create")
+def label_create(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    name: str = typer.Option(..., "--name", "-n", help="Label name."),
+    color: str = typer.Option(
+        ...,
+        "--color",
+        "-c",
+        help="Label color as hex #RRGGBB (e.g. #E50000, #FF0000).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create a label on a pipe."""
+
+    nm = validate_label_name_cli(name)
+    clr = normalize_label_color_cli(color)
+
+    async def factory(client: PipefyClient):
+        return await client.create_label(pipe_id, nm, clr)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@label_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def label_update(
+    ctx: typer.Context,
+    label_id: str = resource_id_argument(help="Label id."),
+    name: str = typer.Option(
+        ..., "--name", "-n", help="New label name (required by API)."
+    ),
+    color: str = typer.Option(
+        ...,
+        "--color",
+        "-c",
+        help="New label color as hex #RRGGBB (required by API).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update a label (name and color are both required by Pipefy)."""
+
+    nm = validate_label_name_cli(name)
+    clr = normalize_label_color_cli(color)
+
+    async def factory(client: PipefyClient):
+        return await client.update_label(label_id, name=nm, color=clr)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@label_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def label_delete(
+    ctx: typer.Context,
+    label_id: str = resource_id_argument(help="Label id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a label permanently."""
+
+    confirm_destructive(yes=yes, description=f"label {label_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_label(label_id)
+
+    run_cli_command(ctx, json_out, factory)